-
Notifications
You must be signed in to change notification settings - Fork 0
feat(examples): add review-agent + linear-shipper (Relayfile-VFS clients) #93
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
khaliqgant
merged 6 commits into
feat/integrations-vfs
from
feat/integrations-vfs-examples
May 13, 2026
Merged
Changes from all commits
Commits
Show all changes
6 commits
Select commit
Hold shift + click to select a range
b263f86
feat(examples): add review-agent + linear-shipper examples (VFS clients)
khaliqgant c13e3d4
fix(examples/linear-shipper): read event.payload, not event itself
khaliqgant a218724
fix(examples/linear-shipper): use a valid PERSONA_INTENT
khaliqgant c123f2a
fix(persona-kit): reject removed deploy v1 persona keys
78fca47
(rebase PR #93 — strip traits/sandbox from examples)
9e3b5d3
fix(examples/linear-shipper): honor env-var overrides in inputDefault
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,17 @@ | ||
| # Linear Shipper | ||
|
|
||
| This deployable persona follows the paraglide pattern: a Linear issue triggers a sandboxed implementation run, then the agent links the result back to Linear. | ||
|
|
||
| ## Setup | ||
|
|
||
| Connect Linear and GitHub before deploying. | ||
|
|
||
| ```bash | ||
| workforce deploy ./examples/linear-shipper/persona.json --mode dev | ||
| ``` | ||
|
|
||
| Set the target repository through the persona inputs: `GITHUB_OWNER`, `GITHUB_REPO`, and `REPO_URL`. | ||
|
|
||
| ## Current GitHub Handoff | ||
|
|
||
| The v1 client contract exposes `createIssue`, not `createPr`, so the example creates a draft handoff issue and includes a `TODO(human)` where `createPr` should be used once the runtime exposes it. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,69 @@ | ||
| import { handler } from '@agentworkforce/runtime'; | ||
|
|
||
| type LinearIssueEvent = { | ||
| issue?: { id?: string; identifier?: string; title?: string; url?: string }; | ||
| }; | ||
|
|
||
| function inputDefault(ctx: Parameters<Parameters<typeof handler>[0]>[0], name: string): string { | ||
| // Mirror `resolvePersonaInputs` precedence (packages/persona-kit/src/inputs.ts): | ||
| // explicit env var (spec.env ?? input name) wins over the static JSON default. | ||
| const spec = ctx.persona.inputs?.[name]; | ||
| const envName = spec?.env ?? name; | ||
| const fromEnv = process.env[envName]; | ||
| const value = (fromEnv !== undefined && fromEnv !== '' ? fromEnv : undefined) ?? spec?.default; | ||
| if (!value) throw new Error(`${name} input is required`); | ||
| return value; | ||
| } | ||
|
|
||
| function shellQuote(value: string): string { | ||
| return `'${value.replace(/'/g, `'\\''`)}'`; | ||
| } | ||
|
|
||
| function safeRepoDirName(value: string): string { | ||
| if (!/^[A-Za-z0-9._-]+$/.test(value)) { | ||
| throw new Error('GITHUB_REPO must be a repository name, not a path or shell fragment'); | ||
| } | ||
| return value; | ||
| } | ||
|
|
||
| export default handler(async (ctx, event) => { | ||
| if (event.source !== 'linear' || event.type !== 'issue.created') return; | ||
| if (!ctx.linear) throw new Error('linear-shipper requires the linear integration'); | ||
| if (!ctx.github) throw new Error('linear-shipper requires the github integration'); | ||
|
|
||
| const payload = | ||
| typeof event.payload === 'object' && event.payload !== null | ||
| ? (event.payload as LinearIssueEvent) | ||
| : {}; | ||
| const issueRef = payload.issue; | ||
| const issueId = issueRef?.id ?? issueRef?.identifier; | ||
| if (!issueId) throw new Error('Linear event is missing an issue id'); | ||
|
|
||
| const issue = await ctx.linear.getIssue(issueId); | ||
| const repoUrl = inputDefault(ctx, 'REPO_URL'); | ||
| const owner = inputDefault(ctx, 'GITHUB_OWNER'); | ||
| const repo = safeRepoDirName(inputDefault(ctx, 'GITHUB_REPO')); | ||
| const repoDir = `${ctx.sandbox.cwd}/${repo}`; | ||
|
|
||
| await ctx.sandbox.exec(`git clone ${shellQuote(repoUrl)} ${shellQuote(repoDir)}`); | ||
| const result = await ctx.harness.run({ | ||
| prompt: `Implement this Linear issue. Create the smallest reviewable change and include verification notes.\n\nTitle: ${issue.title}\n\n${issue.description ?? ''}`, | ||
| cwd: repoDir | ||
| }); | ||
|
|
||
| // TODO(human): createPr is not in the published GithubClient contract yet. | ||
| const created = await ctx.github.createIssue({ | ||
| owner, | ||
| repo, | ||
| title: `Draft PR needed: ${issue.title}`, | ||
| body: [ | ||
| `Linear issue: ${issue.url ?? issueId}`, | ||
| '', | ||
| 'The harness produced an implementation attempt, but GithubClient.createPr is not exposed yet.', | ||
| '', | ||
| result.output | ||
| ].join('\n') | ||
| }); | ||
|
|
||
| await ctx.linear.comment(issueId, `Implementation attempt captured in GitHub issue: ${created.url}`); | ||
| }); | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,41 @@ | ||
| { | ||
| "id": "linear-shipper", | ||
| "intent": "implement-frontend", | ||
| "tags": ["implementation"], | ||
| "description": "Turns a new Linear issue into an implementation attempt and links the resulting GitHub work back to Linear.", | ||
| "cloud": true, | ||
| "integrations": { | ||
| "linear": { | ||
| "triggers": [{ "on": "issue.created" }] | ||
| }, | ||
| "github": { | ||
| "scope": { | ||
| "repo": "AgentWorkforce/workforce" | ||
| } | ||
| } | ||
| }, | ||
| "inputs": { | ||
| "GITHUB_OWNER": { | ||
| "description": "GitHub owner containing the target repository.", | ||
| "default": "AgentWorkforce" | ||
| }, | ||
| "GITHUB_REPO": { | ||
| "description": "Target repository name.", | ||
| "default": "workforce" | ||
| }, | ||
| "REPO_URL": { | ||
| "description": "Clone URL for the target repository.", | ||
| "default": "https://github.com/AgentWorkforce/workforce.git" | ||
| } | ||
| }, | ||
| "onEvent": "./agent.ts", | ||
| "harness": "codex", | ||
| "model": "gpt-5.4", | ||
| "systemPrompt": "Implement Linear issues with small, reviewable changes and clear handoff notes.", | ||
| "harnessSettings": { | ||
| "reasoning": "medium", | ||
| "timeoutSeconds": 1200, | ||
| "sandboxMode": "workspace-write", | ||
| "workspaceWriteNetworkAccess": true | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,23 @@ | ||
| # Review Agent | ||
|
|
||
| This deployable persona listens for GitHub pull request events and Slack mentions, delegates code reasoning to the configured harness, and posts the result back through the connected integration. | ||
|
|
||
| ## Setup | ||
|
|
||
| Connect GitHub and Slack before deploying. Because `useSubscription` is enabled, deployment also connects the model provider derived from the persona's `model` field. | ||
|
|
||
| ⚠️ **Memory is not wired.** `ctx.memory` is a stub in v1; see `docs/plans/deploy-v1-schema-cascade-spec.md` § Loud hole. Memory wiring lands in a follow-up workflow (not yet specced). | ||
|
|
||
| ```bash | ||
| workforce deploy ./examples/review-agent/persona.json --mode dev | ||
| ``` | ||
|
|
||
| ## Events | ||
|
|
||
| The persona handles opened pull requests, issue comment mentions, pull request review comments, failed check runs, and Slack app mentions. | ||
|
|
||
| ## Run | ||
|
|
||
| ```bash | ||
| workforce deploy ./examples/review-agent/persona.json --mode sandbox | ||
| ``` |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🔴
inputDefaultreads static persona spec defaults, ignoring env-var overridesThe
inputDefaulthelper atexamples/linear-shipper/agent.ts:8readsctx.persona.inputs?.[name]?.default, which returns the literaldefaultstring from the persona JSON definition. This completely bypasses the persona-kit input resolution chain (resolvePersonaInputsatpackages/persona-kit/src/inputs.ts:28-54) that checks explicit values → environment variables → defaults. When a user setsREPO_URL,GITHUB_OWNER, orGITHUB_REPOvia environment variables (as the README atexamples/linear-shipper/README.md:12instructs), those overrides are silently ignored and the handler always uses the hardcoded JSON defaults (AgentWorkforce,workforce, etc.).How the input resolution chain is supposed to work
The
PersonaInputSpectype declares anenvfield that names the env var to read. Whenenvis unset, the key name itself is the env var (e.g.REPO_URLmaps toprocess.env.REPO_URL).resolvePersonaInputsimplements this precedence. ButinputDefaultskips all of that and goes straight to.default.Prompt for agents
Was this helpful? React with 👍 or 👎 to provide feedback.