agent.run() + Pi

Describe a task in Pi. AgentRun turns it into a workflow you can inspect and runs its steps using your current Pi model. Requires Node 22.19+ and Pi 0.87.0.

Install from source

Build the extension and use the included Pi CLI. From a new terminal:

git clone --branch main --single-branch https://github.com/Parcha-ai/agentrun.git
cd agentrun
npm ci --ignore-scripts
npm run build
./node_modules/.bin/pi install ./packages/pi -l
./node_modules/.bin/pi --offline

-l writes project settings in .pi/settings.json. Omit it to install for all your Pi sessions. --offline skips startup downloads; it does not disable model calls.

On first launch, Pi asks whether you trust the project before loading its extension. Review the checkout before accepting.

Already built this checkout? Start at the pi install line. The included CLI is the tested Pi 0.87.0 version; a global Pi installation is unnecessary. If Pi 0.87.0 is already open, use /reload. Keep this checkout: Pi loads the extension and skill from it. Rebuild after source changes, then reload. /reload clears the current workflow definition; run the demo or describe your task again to create one.

For live tasks, configure model access in Pi first. AgentRun uses Pi's current model and authentication; it needs no separate model configuration. The scripted demo below works without provider access.

Try the bundled example inside Pi:

/agentrun demo

The demo shows the workflow graph, progress, and a completed result with call counts. It uses scripted responses over fictional sources. It makes no model calls and does not test model quality. Run /agentrun status to check the loaded skill and Pi host version. The tested version is 0.87.0; status flags a different host without blocking it. Missing Pi or Jev access does not prevent the scripted demo. To repeat it, run /agentrun run or /agentrun demo. A scripted demo stays scripted on rerun, including its missing-evidence path. Use /agentrun demo live to switch to real Pi and Jev calls. Workflows authored by Pi use real adapters.

For an offline Pi startup, use ./node_modules/.bin/pi --offline. Without that flag, Pi may download optional command-line tools on first launch. This is separate from the scripted demo, which makes no network calls.

Describe, inspect, run

/agentrun Find the main entry points in this repository and summarize how requests reach them.

The command loads the packaged agentrun-author skill. Pi reads the available tools, builds a workflow, inspects its graph, then runs it with the task's input. You can also invoke /skill:agentrun-author <task> directly. Ask Pi to change a step or explain a result as you would in an ordinary conversation.

Command	What happens
/agentrun <task>	Ask Pi to build, inspect, and run a workflow for the task.
/agentrun help	List commands and demo modes.
/agentrun	Show the current workflow, or help if there is none.
/agentrun run	Repeat the current workflow with its last supplied input. Scripted demos stay scripted; authored workflows use real adapters.
/agentrun status	Check skill discovery, active Pi selection, and Jev configuration without making provider calls.
/agentrun stop	Request cancellation of the running workflow.

A progress widget shows active steps and the number finished. Results appear in Pi, with full output and events in the structured result.

Pi 0.87.0 cannot export a fresh session containing only slash-command results. To save an offline research receipt from the checkout, run node examples/research-live.mjs --out research-result.json. This runs the scripted example again and writes its result; it does not export the Pi session.

One workflow runs at a time. Definitions and run state belong to the current Pi session; switching sessions or closing Pi does not create a saved workflow library. Named saves and reuse across sessions are planned for V2. This extension does not support them.

Three demo modes

Command	What it demonstrates
/agentrun demo	Scripted successful execution over the bundled fictional sources, without model calls.
/agentrun demo empty	Scripted insufficient-evidence path, without model calls.
/agentrun demo live	Real Pi agent steps and Jev system one decisions over the same fictional sources.

Live mode uses your active Pi model and requires configured TypeSafe access for Jev. It still does not search the web or prove accuracy on real research. See the Jev adapter configuration. Live calls can incur usage charges; scripted mode needs no provider access.

Tools and execution

By default, the extension exposes currently active Pi built-in read, grep, find, and ls tools. A workflow can narrow that set; it cannot enable a tool that the host has not supplied. The additional search tool reads only the bundled fictional demo sources.

The user must issue /agentrun run --trusted for each run that needs code nodes or active built-in bash, edit, or write tools. This permits local, unsandboxed execution; authorization does not carry into the next run. A model cannot grant itself that permission with a tool argument.

Native V1 does not supply SOP text. Workflows declaring sopSection stop before execution with a setup error; keep the required sections and use an SDK host that supplies the complete SOP.

Custom extension tools and the outer Pi session's permission hooks are not inherited, including in trusted runs. A configured host can explicitly supply its own tool definitions as described below. Shell/executor effect transports and artifact delivery are unavailable in this extension; declared tool effects must use an available tool.

A direct call to a Pi built-in returns a Pi tool result. Its content is an array of text/image blocks; details may be absent from the workflow's JSON result. Declare that result shape in the output schema. Custom PiToolDefinition implementations follow Pi's SDK contract and return a details field; use details: undefined when there is no extra data. Only the demo search tool returns {sources} directly. A tool-only workflow does not create an agent session. Jev is needed only for system one decisions.

Jev design guidance is bundled with the author skill and returned by describe under authoring.jev, including for hosts without a file-reading tool. No separate TypeSafe skill install is required for DSL authoring. The source-read example preserves original tool evidence through a Jev decision and deterministic projection; its fictional tests demonstrate wiring, not measured semantic accuracy. Explicit tools: [] disables tools for an agent node; omission inherits the host allowlist.

Inspection checks nonexecuting host admission as well as DSL structure; describe also exposes structural limits. Runtime contract failures provide safe error codes, stages and schema problems for repair. Unknown provider failures remain opaque; provider bodies and arbitrary code exception text are not included in reports. Recognized Jev response/transport failures use fixed jev_* categories, and a Pi session response failure uses model_response_failed, with the failing node label. Pi runner stops use pi_timeout, pi_turn_limit, pi_submission_limit, pi_no_submission, or pi_aborted, with a fixed message explaining the next step. Operator cancellation of the workflow still reports cancelled. Jev reports may also include a fixed error.reason identifying the rejected response invariant, or a numeric HTTP error.status. A recognized token-capacity rejection reports max_tokens_exceeded; this is not a byte-to-token estimate or permission to truncate evidence. Provider text remains private. These diagnostics add no retry and do not infer an unobserved provider cause.

Use /agentrun stop to cancel a slash-command run; pressing Escape is not a guaranteed cancellation path. Stopping signals admitted tools, but already-started effects may still finish. Check their results before retrying; a stop does not undo a write.

Displayed workflow counts include direct tool calls, system one decisions, and model steps. They do not include tools called inside an agent step or measure tokens, requests, or spending. Hosts can count child tool attempts through onToolAttempt.

Agent steps capture the active Pi model when the run starts and keep that selection for the run. Request-count and deadline limits bound execution; they are not token or spending caps.

The native model-facing interface starts with agentrun and action: "describe" for available tool schemas and configuration presence, then action: "inspect" and a complete workflow, followed by action: "run" and input. There is no outer submit tool: submit belongs to the internal child runner and the SDK author described below.

Configure the native extension from a host

Hosts that own a restricted corpus, an approved Jev transport, or shared accounting can configure the same native extension:

import { createAgentRunExtension } from '@parcha/agentrun-pi/extension';

// These definitions and callbacks belong to the embedding host.
export default createAgentRunExtension({
  hostTools: ctx => approvedToolsFor(ctx),
  createJudge: ({ signal }) => makeHostJudge({ signal }),
  onToolAttempt: () => sharedBudget.admit('tool'),
});

All options are optional; the default export retains ordinary Pi setup. hostTools replaces the complete built-in and demo tool inventory, including during trusted runs. describe reports the supplied schemas. Direct calls to these tools return {content, details?} even if a supplied tool is named search. Definitions refresh from the execution context before each run. Tool names must be unique; agentrun and submit are reserved.

createJudge supplies the runner for workflow Jev nodes and is called only when the graph requires one. A failed factory never falls back to ambient configuration. The host receives cancellation signals and owns transport configuration and accounting. onToolAttempt is synchronous admission: it runs before each direct tool call and each native child tool attempt, including invalid arguments, unknown tools, and submit. Throwing prevents the attempted effect. Outer authoring calls are counted by their own host. describe.limits reports the configured workflow deadline, model-request, judge-call and tool-attempt ceilings, and per-node turn, submission, and timeout limits. The callback can impose a shared budget across authoring and execution.

Hosts may supply runtimeLimits to lower a finite limit or explicitly disable it with null: deadlineMs, modelRequests, judgeCalls, toolAttempts, nodeMaxTurns, nodeMaxSubmissions, and nodeTimeoutMs. Omitted values keep existing finite defaults. Disabling all seven removes extension inference/time admission caps while preserving operator cancellation, schema validation, graph structure, concurrency, and trace/data guards. This is host configuration; neither a workflow nor an author tool argument can change it. Tool-specific timeouts and provider limits are separate host/tool contracts.

Trace retention is not an execution budget. A run keeps recent sanitized events within a bounded in-memory report and continues when that retention fills. The report's trace counts received, retained, dropped and rejected events/bytes; traceTruncated discloses incomplete retained history, not incomplete output. Individual events still have plain-JSON, byte, depth and value-count safety guards. The SDK service configures those separately with maxTraceBytes (retention) and maxEventBytes (individual safety).

For complete host-owned observation, configure onWorkflowEvent(frame). Each frame has workflowDigest, a registration-local runOrdinal, a per-run sequence, and an isolated sanitized event. Valid events arrive even after report retention fills, including cancellation cleanup before run closure. This callback cannot grant authority or change execution. It is not a durable-store guarantee: the host must record write failures, drain asynchronous work, and check received sequences against report counters before claiming a complete journal. Callback errors are nonfatal to the workflow. Do not store source material without an appropriate host-owned storage policy.

An operator may select a different active Pi model between inspection and execution; child agent steps capture that execution selection. The workflow cannot choose a replacement model or configure host callbacks. Code still requires the per-run trusted command and remains unsandboxed: a restricted tool inventory is not a sandbox for executable code. The host must review executable candidates before granting that authority.

SDK: embed the runner

The native extension handles configuration above. For another Pi extension that already has a context:

import { runWorkflow } from '@parcha/agentrun-dsl';
import { createPiHostRunner } from '@parcha/agentrun-pi';

const result = await runWorkflow(workflow, input, {
  runNode: createPiHostRunner(ctx, { tools: allowedTools }),
  // Supply runJudge separately for Jev nodes or semantic verification.
});

ctx supplies the active model and public model registry. Tools are explicitly supplied and receive the original context; outer hooks are not copied. The captured active model remains fixed for the run. The host thinking level is inherited when provided, and a node can override it. The runner bounds turns, submissions, and time, and refuses an absent model instead of selecting a fallback. These limits do not impose token or spending caps.

For a standalone application, createPiRunner(options) accepts a configured SDK ModelRuntime and its selected model. Supply tools explicitly. It loads no ambient filesystem tools, workspace instructions, extensions, prompt templates, or skills. createPiHostSessionFactory(ctx) exposes the same native child session transport for integrations that own their own runner. Factories are unnecessary for ordinary extension use.

LLM instructions are literal text. Refer to "the text field in the JSON input" and declare requires: ["text"]; {text} inside instructions stays literal. An optional node state map scopes the JSON user message. Placeholder substitution applies to designated fields such as state and call.args.

The child model delivers {value: result} through its submit tool. Schema and review rejections return feedback to the same session. Exhausting a turn, submission, timeout, or cancellation limit throws PiRunError; a rejected draft is never returned as success. A host can explicitly pass null for runner maxTurns, maxSubmissions, or timeoutMs to disable that limit. Omission keeps the default; external cancellation still interrupts unlimited runs.

SDK: retain candidates and check fixed fixtures

The SDK author saves candidate files separately from the native extension's session-local workflow. Supply configured runner options and host-owned acceptance checks:

import { authorWorkflow } from '@parcha/agentrun-pi';

const candidate = await authorWorkflow({
  request: 'Extract a numeric count from text',
  outputDir: './candidates',
  inputKeys: ['text'],
  pi: options, // Your configured PiRunnerOptions.
  maxCandidates: 4,
  acceptance: workflow => checkAgainstYourFixtures(workflow),
});
console.log(candidate.path, candidate.checks);

The host owns checkAgainstYourFixtures: return diagnostics, or [] to accept. Without that callback, acceptance is labeled structural and does not establish correct behavior. The author retains each submitted version and its feedback, never activates it, and cannot edit the host's acceptance checks.

With rubricSections, every supplied section must appear on every generated LLM node, including child workflows. The author conservatively rejects Jev nodes, semantic ask predicates, and verify clauses under that policy; those need a separately reviewed question contract. Schema properties named node, verify, or predicate remain ordinary data. Supply the authoritative rubric as deps.sop when executing the candidate.

The standalone CLI remains available as node packages/pi/dist/cli.js --help from source. It imports a trusted caller-owned --config module for author and run; importing that module executes its code. validate can evaluate code probes. Review executable workflows before using it.

Dependencies and retained data

Pi is optional for @parcha/agentrun-dsl. This package brings the Pi coding-agent SDK, its provider dependencies, and the Jev adapter; its dependency footprint is larger than the core. The release inventory records the locked versions.

The SDK dependencies remain pinned so standalone applications and the CLI have a complete runtime. When loaded as an extension, Pi resolves its core packages and TypeBox through the host loader. The tested host is Pi 0.87.0; installed SDK pins do not make an older or newer host compatible. The offline loader regression checks competing local dependencies, a native file read, and the scripted workflow. Pi's package guidance recommends peers for extension-only packages; this package also provides the standalone SDK.

Candidate directories retain request text, rubric text, workflow versions, and feedback. Native Pi messages can contain workflow inputs and results. Choose storage and tool access appropriate for that data. The accompanying skills/author/SKILL.md describes the native and SDK authoring paths for agents.

License

Apache-2.0. See the included LICENSE and NOTICE files.