Conversation
Document callable agent and program contracts, development CI invocation, outcomes, cancellation, and current headless limits. Generated-By: PostHog Desktop Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
🧙 Wizard CIRun the Wizard CI and test your changes against wizard-workbench example apps by replying with a GitHub comment using one of the following commands: Test all apps:
Test all apps in a directory:
Test an individual app:
Show more apps
Test against a Context Mill branch:
Add Results will be posted here when complete. |
Collaborator
Author
|
B4 docs review: start with Non-interactive developer interfaces, then the program API reference and agent API reference. They cover contracts, inputs/options, outputs, invocation, cancellation, development CI, and current limits without TUI usage instructions. Validation: |
Generated-By: PostHog Desktop Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Generated-By: PostHog Desktop Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
…4-api-reference # Conflicts: # src/agent/README.md
gewenyu99
changed the title
Generated-By: PostHog Desktop Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Merge posthog/functional-b3-parity (1acd24b) into B4. The conflicts are in the agent and runner READMEs. B4's wording and ownership map stay, and statements the A3 fix made untrue are corrected: - Every failure carries a code and a message. - A host cancellation keeps a failure the run already decided. - The orchestrator cancels siblings after the first fatal task. - The scan-report flush no longer rejects the promise. Generated-By: PostHog Desktop Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Two histories merged A3 and the B3 ancestry into B4 independently. This keeps the remote B4 resolution (fa7f08b). The next merge brings the joined B3, with the surface e2e routes. Generated-By: PostHog Desktop Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
B4 is now the joined B3 plus B4's own docs and runner comment changes. The e2e swap is restored after the previous join commit took the remote tree: the jest suite, `run-live.ts` and `bin/test-e2e` are gone, and the three `test:e2e:*` routes and their scripts are back. Generated-By: PostHog Desktop Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
…point to the reference hosts - The developer interfaces said external host callbacks may reject the runProgram promise. Credential, approval and composition callback rejections resolve as `failed`. Only an unexpected invocation error rejects. - The programs reference said workflow requests receive the signal. Only the no-agent `workflow` does. `compositionWorkflow.confirmStep` does not, and its rejection during an abort returns `failed`. - The agent and program sections now name their runnable reference hosts, `pnpm test:e2e:agent` and `pnpm test:e2e:programs`, and the environment they read. - The agent reference lists `OutroKind` among the runtime exports. Generated-By: PostHog Desktop Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
…erence
Brings the final Release A, through B1–B3, into the API reference. The
agent reference keeps B4's fuller text and now states A's contract:
- `ask` and `taskNotice` take `{ signal }`, one signal per request;
- `Aborted` means only a host cancel;
- an agent's own `[ABORT]` returns `Failed`;
- the host sends terminal analytics, with the status its outcome names;
- `AgentErrorType` is listed with the runtime exports.
The runner README's flow and the runner header say the agent sends no
terminal analytics.
Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
…erence Brings B3 at fbddbb2, which carries all of B2's WP3, into the API reference. The conflicts keep B4's fuller text and take these contract facts from B3: - `RunConfig.scanReport`, where `defer` leaves the scan report to the host run; - the snapshot's transcript tail when the run definition sets `collectTranscript`; - the smaller runtime export list: `DEFAULT_AGENT_BINDING`, `resolveHarness`, `harnessRunsTasks`, `AgentSignals`, `WIZARD_TOOL_NAMES`, `OutroKind`, `downloadSkill` and `runMcpPromptViaSdk`; - runProgram resolves credentials through a host provider, awaits the host's gates and loads flags, and the legacy adapter supplies those capabilities from the session; - the switchboard holds the registries and `resolveHarness`, and programs own the sequence precedence in `resolveProgramBinding`; - the scan report flushes once, at the end or earlier on a process drain, and its line arrives as `log` progress; - every host reaches runAgent through runProgram, and a standalone caller builds the config and input itself. The runner README is Prettier-formatted. The rest of the pre-WP3 wording in the developer interfaces and the programs README is left for B4-10. Generated-By: PostHog Desktop Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
…erence Bring B3's programs reference and the deck registry comment into B4. The programs README was added on both sides. The resolution takes B3's Signatures, Intent and Architecture structure, which describes the current contracts, and keeps the B4 detail that is still true: the link from createPosthogInferenceAuthProvider to the inference authentication section, the note that the development --ci runner passes a fixed gateway token, and the closing pointer to the developer interfaces guide. The guide's link to the old "Inputs and capabilities" anchor now points to the new Inputs section. Generated-By: PostHog Desktop Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Bring the developer interfaces guide and the agent and runner READMEs in line
with the code. The callable program section now covers the two ways to supply
credentials, with the provider's resolve(programId, { signal }) called once
per invocation. It says runProgram identifies the user, stamps the AI SDK
evidence and refreshes a token near expiry, resolves the binding from
input.overrides, and copies its input. It lists which capabilities receive
the signal, including the workflow connector's step, and the example narrows
on the ProgramProgress kind. A new Preflight section describes the shared
readiness and settings checks. Both surfaces now say they send no terminal
analytics, and the CI section says detection runs through its own runAgent
call.
The agent README adds the collectTranscript tail and requestRemark options,
spells out scanReport: 'defer', lists the ten @agent runtime names, passes the
per-request signal in the ask example, and names agentic detection as a
direct runAgent caller. The runner README moves credential resolution,
stamping, refresh, overrides and the switchboard decision into runProgram and
starts the flow with preflight.
Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
…erence Kept B4's rewritten agent, runner and programs READMEs, and took the trimmed B2 contracts where they conflict: the programs entry table drops the test-only policy re-exports, ProgramInput loses mcp, and the agent README keeps B3's failed-run skill cleanup bullet and now counts eleven entry names, including TASK_OUTCOMES_KEY. developer-interfaces.md now describes settledRuns and diagnostics instead of final progress, names noAgentWorkflow in place of the MCP port, drops the duplicate-runId and throwing-run-definition rejections, and points both reference hosts at the wizard-workbench harness. The programs README lists the new run order, with flags, run definition and refresh before the file watchers. Generated-By: PostHog Desktop Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Generated-By: PostHog Desktop Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Generated-By: PostHog Desktop Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
…b4-api-reference Generated-By: PostHog Desktop Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Generated-By: PostHog Desktop Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Generated-By: PostHog Desktop Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Generated-By: PostHog Desktop Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Generated-By: PostHog Desktop Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
…nges Generated-By: PostHog Desktop Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
…b4-api-reference Generated-By: PostHog Desktop Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
…b4-api-reference Generated-By: PostHog Desktop Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
…d the TUI line Generated-By: PostHog Desktop Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
gewenyu99
added this pull request to stack #1362
September 25, 2026 15:16
Generated-By: PostHog Desktop Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
gewenyu99
commented
Sep 25, 2026
gewenyu99
left a comment
gewenyu99
left a comment
Collaborator
Author
There was a problem hiding this comment.
🥸 Reviewed by NotVincent, totally not Vincent. The real Vincent will review it separately. Probably slop, please disregard.
gewenyu99
marked this pull request as ready for review
September 25, 2026 15:54
johncwaters
reviewed
Sep 25, 2026
johncwaters
reviewed
Sep 25, 2026
| @@ -0,0 +1,309 @@ | |||
| # Developer interfaces | |||
There was a problem hiding this comment.
personal opinion/experience: having code/interfaces in docs drifts quickly compared to linking to the code itself. As a human my eyes glaze over and as an agent I want them reading the actual code not the potential code in docs.
The actual interface and everything is sick!
Collaborator
Author
There was a problem hiding this comment.
NotVincent here. Agreed. The field tables now link straight to the types, and each field has its comment next to it in the code. Each surface keeps one short example for the call shape.
Collaborator
Author
There was a problem hiding this comment.
Human vincent here. Yeah this is a good point. We can deal with this later. Since we're rippping things apart, this just makes the transition easy. Good catch @johncwaters
…b4-api-reference Generated-By: PostHog Desktop Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
…data - The runAgent example removes Write, Edit and Bash instead of adding Read and Glob, and the field table says allowedTools adds to the base tools and disallowedTools removes them. - The runProgram field table says data and program snapshots hold tokens. - The registry link points at frameworks/registry.ts, and every line anchor points at its declaration again. Generated-By: PostHog Desktop Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
![veria-ai[bot]](https://avatars.githubusercontent.com/in/1723776?s=60&v=4){kind=small}
PR overviewAll previously flagged issues have been addressed. No open security concerns remain on this pull request. Security reviewNo open security issues remain on this pull request. Fixed/addressed: 1 · PR risk: 0/10 |
johncwaters
approved these changes
Sep 25, 2026
This was referenced Sep 25, 2026
Two runnable scripts replace the inline examples. tsconfig includes docs/examples, so typecheck keeps them in step with the code. Generated-By: PostHog Desktop Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Both quack examples log in with a personal API key the way --ci does and read the gateway token from WIZARD_CI_GATEWAY_TOKEN_FILE, so a run needs no browser and spends no mint. Generated-By: PostHog Desktop Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Generated-By: PostHog Desktop Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
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.
Scope: Docs only, plus the two quack examples.
Related: #1320
Do a quack
The code:
run-program-quack.tscallsrunProgramandrun-agent-quack.tscallsrunAgent. Each runs one prompt that repliesquack.Both passed on the local stack, running #1363's head (
486657dc) with this PR's examples.The docs for
runProgramandrunAgent, and short READMEs for programs, the agent and the runner. Code is unchanged: apart from the two quack examples and atsconfig.jsoninclude that typechecks them, every file equals #1357.Stack: #1306 moves → #1307 surface shell → #1308 plumbing → #1357 runner context → #1309 docs → #1363 stream retry.
runProgramandrunAgentwhat each is for, its signature, a field table and a runnable quack example.DEFAULT_BINDINGis Pi + linear, and program callbacks use their runner context.Checks
Checks at
3844eb8e:pnpm typecheckandpnpm lint(0 errors) pass, with the quack examples included. Only Markdown changed since. Atd1ed52c4,pnpm vitest run(3,433 tests, the same as #1357) andpnpm test:arch(11 tests) passed.Created with PostHog Desktop