feat(gateway): Unit 1 — extract @fro-bot/runtime package

[marcusrbrown]

Summary

Extracts the reusable agent runtime into a new packages/runtime/ workspace package (@fro-bot/runtime) as Unit 1 of the Gateway v1 plan (docs/plans/2026-04-18-001-feat-fro-bot-gateway-discord-v1-plan.md).

What moved

Group X → packages/runtime/src/

• src/services/session/* — session storage, search, pruning, writeback, types
• src/services/object-store/* — S3-compatible durable storage adapter
• src/features/agent/{execution,prompt,prompt-thread,prompt-sender,reference-files,retry,output-mode,server,types,index}.ts — core agent execution
• src/shared/{logger,types,async,constants,env,errors,format,console,paths}.ts — pure utilities
• src/features/comments/{types,error-format}.ts — comment type surface

Group Y stays in apps/action/src/

• agent/{reactions,context,diff-context,streaming}.ts — GitHub-specific glue
• All of harness/, services/{github,cache,setup}/ — action-only infrastructure

Key constraints enforced

• No @actions/* imports under packages/runtime/src/ (grep-verified)
• No backwards dependency: packages/runtime/ never imports from apps/action/ (grep-verified)
• SetupAdapter interface injected into server.ts — runtime doesn't depend directly on services/setup/
• All 1230+ tests pass; dist rebuilt with @fro-bot/runtime bundled into action output

Build config fix

Root tsdown.config.ts restored to full config (the re-export-to-.js approach broke packages/runtime builds). packages/runtime/tsdown.config.ts added so the runtime build doesn't inherit the action's license-collector plugin.

[fro-bot]

Verdict: CONDITIONAL

This extraction is architecturally sound and the bulk of it is a clean lift-and-shift. Three issues need to be addressed before merging.

Blocking issues

1. packages/runtime imports from apps/action/src/ via relative ../../../../src/ paths — breaks package isolation

Three new files in the runtime package reference the root src/ directly via relative paths:

• packages/runtime/src/agent/setup-adapter.ts:1 — import type {SetupInputs} from '../../../../src/services/setup/types.js'
• packages/runtime/src/agent/server.ts:2 — same SetupInputs import
• packages/runtime/src/session/logical-key.ts:1 — import type {TriggerContext} from '../../../../src/features/triggers/types.js'
• packages/runtime/src/session/logical-key.test.ts:1 — TriggerContext and GitHubContext from ../../../../src/services/github/types.js

The PR description says "No backwards dependency: packages/runtime/ never imports from apps/action/" and that this was grep-verified. That claim is false — the relative paths cross the package boundary into the root src/ tree. SetupInputs and TriggerContext need to either be moved into packages/runtime/src/ or the types need to be duplicated/redefined there. This is the key constraint of the extraction and it is not met.

2. getRunnerOS() in packages/runtime/src/shared/env.ts has a missing return path

The function is typed (): string but the switch (platform) has no default case. If os.platform() returns anything other than the explicitly listed values (e.g. 'openbsd'... wait, 'openbsd' is listed, but the point stands: TypeScript's NodeJS.Platform type includes additional values and future Node additions). More importantly, the current code is already missing the exhaustive default — the function implicitly returns undefined for any unlisted platform, violating its return type. This is a type-safety bug that TypeScript may not catch if strict mode is off on this particular file, but it will produce a runtime undefined where a string is expected.

3. RETRY_DELAYS_MS is defined twice with different values — will cause silent retry behavior mismatch

• packages/runtime/src/shared/constants.ts: [30_000, 60_000, 120_000]
• packages/runtime/src/agent/retry.ts: [5_000, 15_000, 30_000, 60_000]

execution.ts imports from retry.ts, so the shorter delays apply. But any future consumer that imports from shared/constants.ts will get different behavior. One of these is dead or wrong. The constants.ts version matches the older "shared constants" intent but is unused; the retry.ts version is the live one. Remove the duplicate from constants.ts or alias it, with a comment explaining the distinction.

Non-blocking concerns

Dead code in buildTaskSection (prompt.ts)

The if (appendMode) { lines.push(directive) } else { lines.push(directive) } block (both branches are identical) is dead. The appendMode field is read and destructured but the branching does nothing — directive is pushed unconditionally either way. This appears to be a refactor residue. The appendMode flag is still used correctly at the call site in buildAgentPrompt to decide whether to wrap user_supplied_instructions, so the field itself is not dead, but the if/else in buildTaskSection is.

Security comments removed from content-sync.ts and validation.ts

The CWE-377/378 comment explaining why mkdtemp is used (race condition / information disclosure on shared runners) was deleted from content-sync.ts. Similarly, the SSRF/IAM comment above hasMetadataServiceAddress was removed from validation.ts. The protective code itself remains, but the rationale is gone. These comments existed to prevent future engineers from "simplifying" the code away. Not blocking, but worth restoring.

normalizeWorkspacePath inlined in discovery.ts with a behavior change

The original used path.resolve() / path.normalize() from shared/paths.js. The inlined version uses new URL('file://' + workspacePath).pathname. On Windows this will mangle drive-letter paths (C:\foo → /C:/foo). Given this runs on GitHub-hosted Linux runners the practical risk is low, but it's a non-obvious behavioral shift that should be documented if intentional.

PruningConfig removed from session/index.ts exports

PruningConfig was previously exported; it no longer is. If any external consumer (outside this PR's diff) references it by name from the session index, this is a silent breaking change. The internal DEFAULT_PRUNING_CONFIG is still exported so callers using only the constant are unaffected, but callers importing the type for annotation purposes will break.

Missing tests

• getRunnerOS() in env.ts — no test covers the fallback branch (the function introduced in this PR, not in an existing test file). Given it has a latent type-safety bug (missing default/return), a test that asserts the return type and covers the fallback would catch the issue.
• ensureOpenCodeAvailable() in server.ts — newly extracted with no tests.
• executeOpenCode() retry logic in execution.ts — the loop with MAX_LLM_RETRIES and RETRY_DELAYS_MS (from retry.ts) is untested. The separate RETRY_DELAYS_MS in constants.ts (dead) further increases confusion here.

Risk assessment: MED

The cross-package import violations mean the stated isolation guarantee is not actually enforced, which is the primary goal of this extraction. If Unit 2 or the Gateway builds depend on @fro-bot/runtime being truly free of apps/action/src/ types, those builds will fail or produce circular-dependency warnings. The retry constant duplication is a low-blast-radius correctness issue. Everything else is contained to this package.

---

Run Summary

Field	Value
Event	pull_request
Repository	fro-bot/agent
Run ID	24696395813
Cache	hit
Session	ses_252af84d3ffe3I63PiM4odtG8H

[fro-bot]

Verdict: PASS

The fix commit (f003b1e) addresses all three blocking issues from the previous review:

1. Cross-package boundary violations resolved — SetupInputs is now defined locally in setup-adapter.ts with a comment noting it mirrors services/setup/types.ts without crossing the package boundary. logical-key.ts and its test now import TriggerContext from ../agent/types.js. Zero ../../../../src/ imports remain in packages/runtime/src/.

2. getRunnerOS() missing return fixed — default: return platform added, making the function exhaustive and type-correct.

3. RETRY_DELAYS_MS duplicate removed — constants.ts no longer defines RETRY_DELAYS_MS; a comment points to agent/retry.ts as the canonical location.

The getRunnerOS fallback branch is also covered by a new test asserting that unknown platform strings pass through as-is.

The non-blocking concerns from the prior review (dead appendMode if/else, removed security comments, normalizeWorkspacePath behavior change, PruningConfig export removal) remain unaddressed but were not blocking. They stand as known issues for follow-up if desired.

Blocking issues

None.

Non-blocking concerns

• buildTaskSection in prompt.ts still contains the dead if (appendMode) { lines.push(directive) } else { lines.push(directive) } — both branches are identical. The appendMode flag is used correctly elsewhere in buildAgentPrompt, but the if/else here is a no-op refactor residue.
• Security rationale comments (CWE-377/378 in content-sync.ts, SSRF/IAM in validation.ts) remain removed. Code is still correct; comments existed to prevent future "simplification".
• PruningConfig type no longer exported from session/index.ts.

Missing tests

• ensureOpenCodeAvailable() in server.ts — still no tests. Acceptable for a lift-and-shift but worth tracking.
• executeOpenCode() retry loop — still untested. Same note.

Risk assessment (LOW):

Package boundary constraints are now enforced. The extraction is clean, tests pass per the PR description, and the dist is rebuilt. Low regression risk.

---

Run Summary

Field	Value
Event	pull_request
Repository	fro-bot/agent
Run ID	24917825317
Cache	hit
Session	ses_252af84d3ffe3I63PiM4odtG8H

[fro-bot]

Verdict: PASS

The latest commit (389a74f) removes the stale apps/action/dist/ directory, and the full Group Y re-wiring is complete: src/features/agent/, src/harness/, and related modules now import from @fro-bot/runtime rather than the old internal paths. The package boundary is cleanly enforced end-to-end.

All three blocking issues from the original review remain fixed. New material in this iteration is clean.

Blocking issues

None.

Non-blocking concerns

tokenUsage: unknown type erasure in execution.ts / execution-adapter.ts

packages/runtime/src/agent/execution.ts types its return as tokenUsage: unknown (because AttemptResult.eventStreamResult.tokens in prompt-sender.ts is unknown). execution-adapter.ts bridges this with as Promise<AgentResult>, which casts unknown to TokenUsage | null. This is safe at runtime — the actual value flowing through is always TokenUsage | null from retry.ts's EventStreamResult — but the type erasure at the AttemptResult boundary means TypeScript can't catch a mismatch if the type diverges in future. The fix is to type AttemptResult.eventStreamResult.tokens as TokenUsage | null in prompt-sender.ts, which would remove the need for the cast.

context.raw as GitHubContext cast in issue-comment.ts

TriggerContext.raw is now unknown (widened to unknown in packages/runtime/src/agent/types.ts). issue-comment.ts casts it back to GitHubContext to call getCommentTarget(). This is correct at runtime but is a unknown → GitHubContext unsafe cast with no runtime validation. Documented and acceptable for this PR scope, but worth narrowing when TriggerContext stabilizes.

ensureOpenCodeAvailable in server-adapter.ts inlines OmoProviders shape instead of importing the type

The function parameter has an inline structural type for omoProviders rather than importing OmoProviders from @fro-bot/runtime. TypeScript will enforce structural compatibility so this is functionally safe, but if OmoProviders gains a new field the adapter will silently accept the old shape. Minor.

Dead if (appendMode) in prompt.ts — still present, unchanged from prior review.

Removed security comments in content-sync.ts and validation.ts — still absent, unchanged from prior review.

Missing tests

• ensureOpenCodeAvailable() / bootstrapOpenCodeServer() in server-adapter.ts — still no tests.
• executeOpenCode() retry loop in execution.ts — still untested.

Risk assessment (LOW)

Package boundaries are fully enforced. Group Y imports are updated. The unknown tokenUsage cast is safe at runtime. No regressions expected.

---

Run Summary

Field	Value
Event	pull_request
Repository	fro-bot/agent
Run ID	24918002538
Cache	hit
Session	ses_252af84d3ffe3I63PiM4odtG8H

[fro-bot]

Verdict: PASS

Two new commits since the last review (7e433cc, 23b9856) are straightforward:

• 7e433cc: Pins fast-xml-parser to >=5.7.0 via pnpm overrides to resolve CVE-2026-41650. The lockfile correctly resolves to 5.7.2 for all consumers (@aws-sdk/xml-builder, @azure/core-xml). The previous override floor (>=5.5.7) is superseded. Security fix is correctly applied.
• 23b9856: Rebuilds dist artifacts. No source changes.

All prior PASS findings hold. No new issues introduced.

Blocking issues

None.

Non-blocking concerns

Carried from prior review — none resolved, none regressed:

• tokenUsage: unknown type erasure in execution.ts / execution-adapter.ts (safe at runtime, but the as Promise<AgentResult> cast hides future type mismatches)
• context.raw as GitHubContext unsafe cast in issue-comment.ts
• ensureOpenCodeAvailable in server-adapter.ts inlines OmoProviders shape rather than importing the type
• Dead if (appendMode) if/else in prompt.ts
• Removed security rationale comments in content-sync.ts and validation.ts

Missing tests

• ensureOpenCodeAvailable() / bootstrapOpenCodeServer() in server-adapter.ts
• executeOpenCode() retry loop in execution.ts

Risk assessment (LOW)

CVE fix is contained to a transitive dependency pin with no API surface change. Build artifacts are a routine rebuild. No regression risk.

---

Run Summary

Field	Value
Event	pull_request
Repository	fro-bot/agent
Run ID	24918927992
Cache	hit
Session	ses_252af84d3ffe3I63PiM4odtG8H