feat(sdk): bundle @agent-relay/github-primitive at /github subpath

[khaliqgant]

Summary

Bundles @agent-relay/github-primitive into the SDK so workflow authors get it with npm install @agent-relay/sdk — no separate install. Import via the new @agent-relay/sdk/github subpath.

Required breaking an existing circular dep between @agent-relay/sdk and @agent-relay/github-primitive (github-primitive imports WorkflowStep + RunnerStepExecutor from SDK; SDK would now depend on github-primitive → cycle). Fixed by extracting the shared type surface to a new leaf package @agent-relay/workflow-types.

Companion to docs relay#778 which already documents the bundled shape — that doc becomes accurate on this merge.

What's in this PR

New leaf package: @agent-relay/workflow-types

Holds the public type surface both SDK and github-primitive need:

• WorkflowStep, WorkflowStepType, VerificationCheck
• AgentDefinition + transitive (AgentCli, AgentPreset, AgentConstraints, AgentPermissions, AgentCredentialConfig, AccessPreset, FilePermissions, NetworkPermissions, NetworkPermission, PermissionProfileDefinition)
• RunnerStepExecutor
• SwarmPattern
• Type guards (isDeterministicStep, isWorktreeStep, isIntegrationStep, isCustomStep, isAgentStep)
• Legacy aliases (AgentWorkflowStep, DeterministicWorkflowStep)

@agent-relay/sdk

• packages/sdk/src/workflows/types.ts trimmed ~350 lines → now export * from '@agent-relay/workflow-types' for the moved names. Every existing public export on the SDK is preserved — zero API change for SDK consumers.
• packages/sdk/src/workflows/runner.ts — RunnerStepExecutor definition removed, imported from workflow-types.
• packages/sdk/src/github.ts — new barrel: export * from '@agent-relay/github-primitive' + export * from '@agent-relay/github-primitive/workflow-step'.
• packages/sdk/package.json:
  • dependencies gains @agent-relay/github-primitive: 5.0.0 and @agent-relay/workflow-types: 5.0.0.
  • exports gains ./github → ./dist/github.js.

@agent-relay/github-primitive

• Dep swap: drop @agent-relay/sdk, add @agent-relay/workflow-types. Breaks the cycle.
• One-line import change in src/workflow-step.ts: '@agent-relay/sdk/workflows' → '@agent-relay/workflow-types'.

Verification

Authored by a Codex agent under the running-headless-orchestrator pattern; verified by re-running the builds post-commit:

cd packages/workflow-types && npm run build    # clean
cd packages/github-primitive && npm run build  # clean (no SDK dep resolved)
cd packages/sdk && npm run check               # clean (tsc --noEmit)
cd packages/sdk && npm run build               # clean

No behavior change. No public API change for SDK consumers. The only user-visible addition is the new @agent-relay/sdk/github subpath.

Why a leaf package, not inlined types

Considered inlining the two types into github-primitive as local duck-types (smaller scope, no new package). Rejected because the types would drift silently from SDK's definitions over time — they ARE the public contract between SDK and the integration step. The leaf package makes the contract explicit; any future @agent-relay/* primitive package can consume it the same way.

After merge

• relay#778 docs become accurate (import { createGitHubStep } from '@agent-relay/sdk/github' works)
• Users can drop npm install @agent-relay/github-primitive — same symbols via the SDK
• Pattern available for future workflow-specific primitives (Linear, Slack, etc.) to ship similarly

Test plan

• npm run build clean in workflow-types, github-primitive, sdk
• npm run check clean in sdk
• npm test per package (if the workspace has integration tests that exercise these types)
• Verify import { createGitHubStep } from '@agent-relay/sdk/github' works in a consumer project post-install

🤖 Generated by a Codex agent orchestrated via running-headless-orchestrator

---

[barryollama]

Code Review: Bundle @agent-relay/github-primitive at /github subpath

Verdict: Approve ✅

Summary

This is a clean architectural refactoring that breaks the circular dependency between and by introducing a new leaf package . The changes are minimal, focused, and maintain full backward compatibility.

Key Changes Reviewed

1. New package — Pure types package (no runtime deps) containing:

   • , ,
   • • transitive types
   • interface (the key circular dep breaker)
   • and type guards
   • Legacy aliases for backward compatibility

2. Circular dependency resolution — Clean approach:

   • now depends on instead of
   • depends on both and
   • Cycle broken ✅

3. SDK changes — Zero API impact:

   • trimmed from ~350 lines to
   • All existing public exports preserved
   • New subpath export added via field

4. New barrel file — cleanly re-exports the full github-primitive surface

Checks Passed

• ✅ No security concerns
• ✅ Backward compatible (existing SDK consumers unaffected)
• ✅ Clean dependency graph (no cycles)
• ✅ TypeScript configuration proper for new package
• ✅ Documentation in companion PR #778

Minor Note

The shows some → changes that appear to be incidental (likely from npm version differences), not related to this PR's core changes.

---

Reviewed by Hermes Agent

[barryollama]

Code Review: Bundle @agent-relay/github-primitive at /github subpath

Verdict: Approve ✅

Summary

This is a clean architectural refactoring that breaks the circular dependency between @agent-relay/sdk and @agent-relay/github-primitive by introducing a new leaf package @agent-relay/workflow-types. The changes are minimal, focused, and maintain full backward compatibility.

Key Changes Reviewed

1. New @agent-relay/workflow-types package — Pure types package (no runtime deps) containing:

   • WorkflowStep, WorkflowStepType, VerificationCheck
   • AgentDefinition + transitive types
   • RunnerStepExecutor interface (the key circular dep breaker)
   • SwarmPattern and type guards
   • Legacy aliases for backward compatibility

2. Circular dependency resolution — Clean approach:

   • github-primitive now depends on workflow-types instead of sdk
   • sdk depends on both github-primitive and workflow-types
   • Cycle broken ✅

3. SDK changes — Zero API impact:

   • packages/sdk/src/workflows/types.ts trimmed from ~350 lines to export * from workflow-types
   • All existing public exports preserved
   • New ./github subpath export added via exports field

4. New barrel file — packages/sdk/src/github.ts cleanly re-exports the full github-primitive surface

Checks Passed

• ✅ No security concerns
• ✅ Backward compatible (existing SDK consumers unaffected)
• ✅ Clean dependency graph (no cycles)
• ✅ TypeScript configuration proper for new package
• ✅ Documentation in companion PR #778

Minor Note

The package-lock.json shows some devOptional: true → dev: true changes that appear to be incidental (likely from npm version differences), not related to this PR's core changes.

---

Reviewed by Hermes Agent

[devin-ai-integration]

Devin Review found 1 potential issue.

View 4 additional findings in Devin Review.

[devin-ai-integration]

🔴 Ambiguous star exports silently drop all workflow-step symbols from @agent-relay/sdk/github

Both export * statements in sdk/src/github.ts re-export the same symbols from workflow-step.ts. The main entry @agent-relay/github-primitive already re-exports everything from workflow-step.ts via packages/github-primitive/src/index.ts:7. Per the ECMAScript spec, when two export * sources provide the same binding name, that name is silently excluded from the re-exporting module's namespace. This means all runtime values from workflow-step.ts — including createGitHubStep, GitHubStepExecutor, and githubStepConfigFromWorkflowStep — are ambiguous and will not be importable from @agent-relay/sdk/github. The doc comment on line 8 explicitly advertises import { createGitHubStep, GitHubClient } from '@agent-relay/sdk/github', but createGitHubStep would be silently undefined at import time.

Suggested change

	export * from '@agent-relay/github-primitive';
	export * from '@agent-relay/github-primitive/workflow-step';
	export * from '@agent-relay/github-primitive';

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[xkonjin]

Code Review:

This is a clean migration from Next.js transparent rewrites to permanent redirects for legacy URL paths. SEO and analytics will improve now that crawlers see 301s instead of 200s.

Potential Issue — Path Parameter Loss:
The previous rewrite for /relayfile/:path* mapped transparently to /file/:path*, preserving the sub-path. The new redirect maps all /relayfile/* hits to /primitives#file.

If any external bookmarks or integrations hit specific sub-paths like /relayfile/upload, those paths are silently dropped by the redirect destination. If the app still expects specific path routing after the redirect, you may want to either:

1. Preserve the path in the destination (e.g. /primitives/file/:path*), or
2. Add a separate route in the app that reads the original URL from the browser history after the hash redirect.

Coverage Gap:
There doesn't appear to be a test validating that these redirects resolve correctly. A small integration test or a manual check in the Vercel preview deploy against /relayfile/some-path would confirm the intended behavior.

Otherwise, the change is straightforward and safe.