Publish agent.run() as a Pi extension

Research date: 2026-09-20. Status: proposed implementation, not a shipped extension. The current @agentrun/pi package is an unpublished SDK adapter, CLI, and authoring skill. This plan adds a native Pi surface while keeping the DSL portable.

Recommendation

Extend @agentrun/pi with a Pi package manifest and native entry point. Preserve its SDK exports and CLI. Install one package, then use AgentRun from the Pi session already open:

pi install npm:@agentrun/pi@beta
/agentrun demo

These are target post-publication commands. The npm package is not available yet.

The promise: Pi can build, test, and run understandable workflows made from ordinary agent steps, Jev system one decisions, and code. A workflow can be a tool used by the main Pi agent; its agent nodes run in bounded, separate conversations. The extension does not translate an arbitrary running agent loop automatically.

The first demo should work without a key: offer the four executable workflow samples (research, KYB, adverse-news identity review, and SOP-driven merchant classification) with scripted adapters, expose map/route/loop internals and actual evidence, and let the user inspect a judgment in isolation. Label scripted answers clearly. Then offer configured Jev system one decisions and real agent steps as separate, explicit next steps.

What already exists in the ecosystem

Versions below were checked against published npm metadata on the research date. Capabilities summarize each project's own documentation; this is not a comparative performance or security audit.

Package	Published version	Relevance
pi-typesafe	0.6.0	Jev evaluation tool, typed library, credential helpers, terminal playground, and calibration. Best candidate for optional credential interoperability.
pi-jev-auto-mode	0.4.1	Uses Jev system one decisions in tool-approval policy. A useful reference for host policy boundaries.
pi-warden	0.28.4	Supervises tool actions, rules, repeated failures, and completion claims; uses pi-typesafe.
pi-extensible-workflows	5.15.0	JavaScript workflows, agents, parallel execution, approvals, budgets, and recovery. Significant existing orchestration overlap.
@agwab/pi-workflow	0.14.1	Declarative stages, fan-out/fan-in, loops, retained runs, and authoring skills. Relevant native-package precedent.
pi-subagents	0.70.0	Delegation, background agents, saved workflows, and artifacts. Possible later runner integration.
pi-taskflow	0.3.0-beta.1.2	A portable declarative runtime with a Pi adapter; close architectural precedent. Its beta and proposed control-plane features are distinct.

Pi already has workflow engines. AgentRun's case should rest on its particular combination: small typed primitives, Jev decisions alongside agent work and code, explicit dataflow, independent component evaluation, and examples that reveal the executed path. Do not claim to be the first, fastest, or uniquely safe.

What we can reuse

Existing owner	Reuse	Native-extension gap
packages/dsl	Interpreter, graph/schema validation, capability checks, events, digests, root-chain slices	Admission before executable validation; clear slice evaluation contracts
packages/jev	Typed decision adapter, retained probabilities, deadlines/retries/cancellation	Lazy extension configuration and readiness reporting
packages/pi/src/runner.ts	Bounded agent sessions, structured submit, same-session correction, explicit tools	Bind the extension's active model/provider without a private SDK escape hatch
packages/pi/src/author.ts	Versioned candidates, review retention, independent acceptance	Shared preparation policy; full authoring guidance; reviewed Jev rubric contracts
scripts/verify-packages.mjs	Packed-consumer and source checks	Install/discover the actual native extension, not only import the SDK or invoke the CLI

The existing adapter deliberately disables ambient shell/filesystem tools, project instructions, skills, and extensions in child sessions. Retain that boundary. The repository's existing tests are a useful baseline, not evidence that native extension discovery or integration already works.

Native experience

One /agentrun command opens the same operations the agent can call. Keep the initial surface small:

Operation	Proposed behavior
Demo / new	Run the bundled offline lesson, or have the current Pi agent draft a workflow using the installed skill.
Check / retain	Validate an admitted candidate, retain an immutable version, and report its declared inputs, outputs, capabilities, and limits.
Evaluate	Run frozen cases against an exact supported step or the complete workflow; compare actual results with independent expectations.
Run / stop	Execute a reviewed version with an input; show progress, propagate cancellation, and retain the outcome.
Inspect	Read a retained run's steps, decisions, repairs, output, or failure without inference or re-execution.

Use four model-facing tools backed by the same service: agentrun_prepare (check/retain), agentrun_eval, agentrun_run, and agentrun_inspect. A command handles demo setup, authoring prompts, and explicit stop. This is proposed API naming.

Authoring normally uses the current Pi conversation plus skills/author/SKILL.md. Keep authorWorkflow() for programmatic isolated authoring and its existing consumers; a second authoring conversation is not necessary for every interactive draft.

Tool replies carry compact structured results and a report location. TUI renderers show the active step and bounded review progress. Plain/JSON operation must also work. Guard terminal-only components with Pi's mode checks; do not make correctness depend on a dialog.

Resolve the host bridge first

Existing code pins Pi 0.84.2. Current published Pi is 0.86.1. The public registry gained streaming methods in 0.86.0. This is a compatibility change to prove, not a version bump to perform blindly.

ExtensionContext provides the selected model and a modelRegistry. Our production SDK runner requires ModelRuntime. Pi's createAgentSession does not accept a registry or custom streaming function, and the registry's internal runtime is private. Do not cast it, read a private field, or construct a replacement runtime and claim exact session inheritance.

Preferred implementation: adapt Pi's public pi-agent-core.Agent to the existing PiSession factory boundary. Its explicit streaming function delegates through ctx.modelRegistry.streamSimple using the selected model captured at invocation. The current runner continues owning submission validation, review feedback, timeouts, turn bounds, and cleanup. Split runner options so a host-authenticated factory does not require a fabricated ModelRuntime; retain that requirement for the default SDK path.

Reject a missing active ctx.model before constructing an Agent or making a request; never allow its placeholder default. Offline demos and structural operations do not require a selected model.

Use only the prepared tools and submit tool, explicitly select sequential child-tool execution, forward events, and make abort/disposal idempotent. Inherit the host's effective thinking setting when supported unless the workflow explicitly overrides it; today's adapter defaults omitted thinking to low. Do not silently claim support for unmapped tier/effort settings.

This reuses the selected model and configured provider authentication. It does not automatically inherit the main session's request/context hooks, permissions extensions, tools, transport overrides, or cache behavior. Host-only authentication hooks need separate integration proof. getAllTools() returns metadata, not executable handlers. Start with tool-free child agents and deliberately registered tool implementations; do not reconstruct ambient tools and call that inheritance.

Grounding: Pi extension API, registry implementation, SDK options, Agent API.

Jev integration

Use @agentrun/jev as the initial provider bridge. Construct it only when a workflow needs judgments; no credential should be required to load the extension or run the offline demo. Respect configured access and gateway settings, with no new model-selection UI or fallback selection.

pi-typesafe is a useful optional companion. Its published library exports credential-readiness and resolution helpers; an explicit bridge can reuse its configured credential through our existing adapter. That does not inherit its usage ledger. Independently installed Pi packages have separate module roots, so merely installing both does not make a JavaScript import available.

Do not make pi-typesafe a mandatory first-release dependency. Wrapping its evaluator as our injected client needs error, cancellation, retry, request-limit, and endpoint compatibility tests. Its public client options do not provide the same arbitrary gateway setting. Bundling another Pi package would also need a deliberate package/export allowlist change; our release verifier currently rejects packed node_modules. Optional credential integration can follow the first complete extension.

Grounding: pi-typesafe API, Pi package dependencies.

Candidate, evaluation, and execution boundaries

Admission precedes validation. validateWorkflow() can compile and probe literal JavaScript. Share the existing author's complete graph-aware policy: executable admission, whole-rubric coverage, and reviewed-question-contract restrictions, including nested workflows. Native agentrun_prepare must enforce these even when the current Pi conversation drafted the candidate without calling authorWorkflow(). Apply admission before calling validation, execution, slices, or dry-run. A generated tool argument cannot grant itself trust. Reviewed executable versions need host-owned authorization tied to the candidate digest; the bundled offline demo can use an explicitly shipped fixture policy. The DSL and a Pi extension are not security sandboxes.

Preserve the whole decision. A step evaluation retains its original schema and rubric, with an explicit frozen input mapping. Start with exact, unique root-chain labels; reject ambiguous prefixes and unsupported nested selections. runWorkflowSlice() is not a universal subgraph isolator and skips terminal workflow-output validation. Apply a step assertion separately; whole-workflow cases must still validate final output and coordination. Frozen expectations belong outside candidate output. For an authoring session with filesystem access, use separately retained fixture snapshots/digests; ordinary files in that same writable workspace do not become tamper-proof merely by naming them independent. Keep approved candidate and fixture bytes/digests in host session memory, verify them immediately before use, and invalidate approval when either changes. Persisted reports are evidence, not self-authenticating approval. After restart, require trusted re-admission rather than accepting a writable approval file. Test an author changing both fixtures and their recorded expected answers. Stronger isolation requires a host boundary outside that author's access; the extension cannot manufacture it.

Separate modes. Structural checks, synthetic dry-runs, scripted cases, and configured-provider evaluations answer different questions. Label them. Passing an answer's schema does not establish that the answer is right.

Keep current rubric restrictions until an explicit replacement passes. The author rejects Jev nodes and semantic verification when authoritative rubricSections are supplied. There is no existing API to approve the separately reviewed question contract mentioned in its docs. First release can use reviewed Jev templates and ordinary questions without supplied policy sections. For policy-bearing authoring, add host-owned question-contract inputs bound to the full source rubric, with rejection tests; do not remove the restriction or omit the rubric to get through it.

Retain inspectable outcomes. Proposed project storage: .agentrun/candidates/<id>/ and .agentrun/runs/<id>/. Store the workflow digest, fixture/input snapshot, adapter mode, events, final status, and result/error. Keep credentials out. Enforce path boundaries and capture immutable input bytes before executing. Await required writes and final event flushes; onEvent observers alone cannot prove persistence because their errors are best effort. Inspect never reruns. Interrupted work remains interrupted; do not silently restart uncertain effects.

Set a workflow-wide deadline and child concurrency/call bounds; per-node limits alone do not bound total work. Cancel and clean up on tool abort, explicit stop, session shutdown, and reload. Bind messages/results to the originating session so a late completion cannot land in a new session. Session entries should contain a compact report reference, not every trace event.

Packaging

Keep one public package, preserving existing imports and CLI. Proposed manifest addition:

{
  "keywords": ["pi-package", "workflow", "agentrun"],
  "pi": {
    "extensions": ["./dist/extension.js"],
    "skills": ["./skills"]
  }
}

Move imported Pi host packages and TypeBox to peer dependencies as Pi's packaging guide specifies, with exact development versions for the test matrix. Preserve dependencies on the portable DSL and Jev adapter. Avoid bundling a second Pi runtime. Document the supported Pi releases and check required capabilities at runtime; wildcard peer declarations do not prove compatibility. Test 0.86.0 and 0.86.1 before claiming both.

Ship compiled extension files, the authoring skill, schema/reference material, and bundled offline examples. No build or network setup should run when the extension loads. Use npm tarballs as the first distribution path. A Git install from a monorepo root is a separate discovery/build problem; do not advertise it until verified with production-only dependencies.

Pi package docs describe install/discovery and gallery metadata. Add an original PNG or MP4 preview and the pi-package keyword for discoverability. The demo should show a workflow, one bad decision caught by evaluation, and the repaired full result.

Implementation sequence and exit checks

Step	Work and likely files	Done when
1. Prove the host bridge	packages/pi/src/types.ts, runner.ts, new extension-session.ts; focused contract tests	Public registry path preserves selected model and request-time auth; no replacement runtime/model; isolated transcripts, sequential tools, repair, and cancellation pass on supported Pi versions.
2. Ship the smallest vertical slice	New extension.ts, extension-service.ts; package manifest and offline fixture assets	Publish exact packed DSL/Jev/Pi artifacts to an ephemeral test registry (or prove an equivalent packed-dependency arrangement), then install into isolated Pi settings with no workspace links. The installed package is discovered, /agentrun demo works without a key, its report is inspectable, and loading makes no inference call.
3. Add author/check/run/eval	Shared candidate policy, retained report store, expanded authoring skill, exact-step fixture API	A current Pi agent can retain a candidate, catch a wrong schema-valid judgment, test the whole workflow, and run the reviewed version. No self-approval of code or verifier rewrites.
4. Verify lifecycle and real integrations	Native extension test harness; update scripts/verify-packages.mjs, source allowlist, and package/type tests	TUI and headless behavior, abort/reload/session changes, missing access, provider errors, disk failures, and immutable report identity pass. Configured Pi/Jev smoke verifies actual integration separately from scripted tests. Packed native loading and retained SDK/CLI consumption must share compatible Pi package identities, including the existing ModelRuntime instanceof check.
5. Prepare public beta	README, example walkthrough, package metadata, release workflow, gallery asset	Clean packed install outside the monorepo succeeds; license/ownership/namespace decisions complete; provenance and source inventory checked; dependency-order publication and rollback documented.

Steps 2–3 can share service work once the bridge contract is settled. Authoring material and fixture design can proceed independently; avoid parallel changes to the runner until Step 1 passes.

Release acceptance must exercise the installed extension, not only a mocked registration API. Include provider authentication changing between turns, missing/old host capabilities, adversarial executable graph positions, no ambient-tool leakage, whole-rubric isolation, the chosen gallery demo’s standard and uncertain cases, failed report writes, and cancellation while a child session opens. No emitted success may rely on a swallowed observer error.

The existing release gates still apply: approved open-source license and copyright, package/repository ownership, clean public history, and publish credentials. Publish the DSL and Jev dependencies before the Pi package (with the test registry already verified in Step 2), use a beta tag initially, and verify an exact-version install from outside the workspace. These decisions remain pending; nothing in this research authorizes changing private repository visibility or publishing an unlicensed candidate.

Scope after the first release

Keep long-lived agent fleets, background schedulers, automatic checkpoint resume, autonomous workflow activation, a new visual editor, and broad interoperability with every workflow engine outside the initial extension. Add pi-typesafe credential reuse and other subagent backends only when their integration contracts are tested. AgentRun's host-neutral runtime and existing SDK/CLI remain supported throughout.