@parcha/agentrun-pi 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,2 @@
+AgentRun
+Copyright 2026 Parcha Labs, Inc.

package/README.md

@@ -0,0 +1,209 @@
+# 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:
+
+```sh
+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:
+
+```text
+/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
+
+```text
+/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](../jev/README.md). 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](skills/author/examples/read-source-decision.json) 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:
+
+```js
+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:
+
+```js
+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:
+
+```js
+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](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md#dependencies) 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.

package/dist/admission.d.ts

@@ -0,0 +1,6 @@
+export interface WorkflowAdmissionOptions {
+    rubricSections?: Record<string, string>;
+    allowExecutableCandidates?: boolean;
+    allowedEffectTools?: readonly string[];
+}
+export declare function workflowPolicyErrors(candidate: unknown, options: WorkflowAdmissionOptions): string[];

package/dist/admission.js

@@ -0,0 +1,51 @@
+export function workflowPolicyErrors(candidate, options) {
+    const errors = [];
+    const sections = Object.keys(options.rubricSections ?? {});
+    const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+    const visit = (value) => {
+        const node = record(value);
+        if (!node)
+            return;
+        const kind = node.node;
+        if (!options.allowExecutableCandidates && ["code", "call", "artifact"].includes(String(kind)) && !(kind === "call" && node.via === "tool" && typeof node.tool === "string" && options.allowedEffectTools?.includes(node.tool)))
+            errors.push(`${kind} requires allowExecutableCandidates`);
+        if (sections.length && ["judge", "pick", "sift", "route"].includes(String(kind)))
+            errors.push(`${String(kind)} cannot carry supplied SOP sections; use an LLM node with sopSection`);
+        const llm = ["agent", "decide", "extract", "report"].includes(String(kind));
+        const predicate = kind === "loop" ? record(node.until) : kind === "escalate" ? record(node.when) : undefined;
+        if (sections.length && (predicate?.predicate === "ask" || (llm && node.verify !== undefined)))
+            errors.push("Semantic predicates and verify clauses require a separately reviewed question contract when rubric sections are supplied");
+        const proseArtifact = kind === "artifact" && (node.type === "markdown" || node.type === "report");
+        if (llm || proseArtifact) {
+            const included = Array.isArray(node.sopSection) ? node.sopSection : [node.sopSection];
+            for (const section of sections)
+                if (!included.includes(section))
+                    errors.push(`${String(node.label)} must include rubric section ${section}`);
+        }
+        switch (kind) {
+            case "chain":
+                if (Array.isArray(node.steps))
+                    node.steps.forEach(visit);
+                break;
+            case "parallel":
+                if (Array.isArray(node.branches))
+                    node.branches.forEach(visit);
+                break;
+            case "map":
+            case "loop":
+                visit(node.body);
+                break;
+            case "route": {
+                const branches = record(node.branches);
+                if (branches)
+                    Object.values(branches).forEach(branch => visit(record(branch)?.body));
+                break;
+            }
+            case "workflow":
+                visit(record(node.workflow)?.root);
+                break;
+        }
+    };
+    visit(record(candidate)?.root);
+    return errors;
+}

package/dist/author.d.ts

@@ -0,0 +1,21 @@
+import { type Workflow } from "@parcha/agentrun-dsl";
+import { type PiRunnerOptions } from "./runner.js";
+export declare const AUTHOR_CONTRACT = "You author AgentRun DSL v2 workflows as JSON data.\nDeliver with the submit tool, never prose or a filename. Make the smallest workflow satisfying the request.\nThe document has v:2, name, schemas (JSON Schema catalog), optional input:{schemaId}, output:{schemaId,path?}, root.\nEvery referenced schema must exist. Each LLM node has node:agent|decide|extract, label, instructions, out (schema id), as (state key), optional requires/tools/sopSection.\nA chain has node:chain, steps:[nodes]. A map has label, itemsPath, body, as, maxConcurrency. A loop has label, body, until, maxIters.\nA judge has label,state,out,as. Judge schemas use flat boolean/enum/integer properties; each property's description states its question. A route has label,state,instructions,branches:{name:{criteria,body}}, optional unsure:{branch,gte} and as.\nLLM instructions are literal text, never interpolated. The node receives workflow state as a JSON user message; refer to its keys in ordinary prose and declare required keys in requires. Use {stateKey} placeholders only in interpolated fields such as judge.state and call.args; whole placeholders preserve their value's type. Output.path selects a final state value validated by output.schemaId.\nOnly use tools named by the host. Never invent a tool, capability, evidence source or successful test.\nKeep the full rubric in its original source text. Every LLM node's sopSection must include ALL supplied rubric section names. Merged judgments inherit their parents' union. Do not paraphrase policy into instructions. If rubric sections are supplied, use LLM nodes for judgment; Jev nodes do not carry sopSection and require a separately reviewed question contract.\nKeep independent acceptance checks host-owned; never change their implementation, fixtures or thresholds to pass. A valid candidate is not automatically activated.\nCode, shell/effect calls and artifact delivery require explicit host authorization. Bound loops and parallelism; uncertainty should escalate or select an explicit fallback.\nExample: {\"v\":2,\"name\":\"summarize\",\"schemas\":{\"Result\":{\"type\":\"object\",\"properties\":{\"summary\":{\"type\":\"string\"}},\"required\":[\"summary\"],\"additionalProperties\":false}},\"output\":{\"schemaId\":\"Result\",\"path\":\"result\"},\"root\":{\"node\":\"extract\",\"label\":\"summarize\",\"instructions\":\"Summarize the text field from the JSON input faithfully.\",\"out\":\"Result\",\"as\":\"result\",\"requires\":[\"text\"]}}";
+export interface AuthorWorkflowOptions {
+    request: string;
+    outputDir: string;
+    pi: PiRunnerOptions;
+    inputKeys?: string[];
+    rubricSections?: Record<string, string>;
+    allowExecutableCandidates?: boolean;
+    maxCandidates?: number;
+    acceptance?: (candidate: Workflow) => Promise<string[]> | string[];
+}
+export interface AuthoredWorkflow {
+    workflow: Workflow;
+    path: string;
+    directory: string;
+    candidates: number;
+    checks: "structural" | "structural-and-host";
+}
+export declare function authorWorkflow(options: AuthorWorkflowOptions): Promise<AuthoredWorkflow>;

package/dist/author.js

@@ -0,0 +1,72 @@
+import { workflowPolicyErrors } from "./admission.js";
+import { randomUUID } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { resolve, join } from "node:path";
+import { validateWorkflow } from "@parcha/agentrun-dsl";
+import { createPiRunner } from "./runner.js";
+export const AUTHOR_CONTRACT = `You author AgentRun DSL v2 workflows as JSON data.
+Deliver with the submit tool, never prose or a filename. Make the smallest workflow satisfying the request.
+The document has v:2, name, schemas (JSON Schema catalog), optional input:{schemaId}, output:{schemaId,path?}, root.
+Every referenced schema must exist. Each LLM node has node:agent|decide|extract, label, instructions, out (schema id), as (state key), optional requires/tools/sopSection.
+A chain has node:chain, steps:[nodes]. A map has label, itemsPath, body, as, maxConcurrency. A loop has label, body, until, maxIters.
+A judge has label,state,out,as. Judge schemas use flat boolean/enum/integer properties; each property's description states its question. A route has label,state,instructions,branches:{name:{criteria,body}}, optional unsure:{branch,gte} and as.
+LLM instructions are literal text, never interpolated. The node receives workflow state as a JSON user message; refer to its keys in ordinary prose and declare required keys in requires. Use {stateKey} placeholders only in interpolated fields such as judge.state and call.args; whole placeholders preserve their value's type. Output.path selects a final state value validated by output.schemaId.
+Only use tools named by the host. Never invent a tool, capability, evidence source or successful test.
+Keep the full rubric in its original source text. Every LLM node's sopSection must include ALL supplied rubric section names. Merged judgments inherit their parents' union. Do not paraphrase policy into instructions. If rubric sections are supplied, use LLM nodes for judgment; Jev nodes do not carry sopSection and require a separately reviewed question contract.
+Keep independent acceptance checks host-owned; never change their implementation, fixtures or thresholds to pass. A valid candidate is not automatically activated.
+Code, shell/effect calls and artifact delivery require explicit host authorization. Bound loops and parallelism; uncertainty should escalate or select an explicit fallback.
+Example: {"v":2,"name":"summarize","schemas":{"Result":{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"],"additionalProperties":false}},"output":{"schemaId":"Result","path":"result"},"root":{"node":"extract","label":"summarize","instructions":"Summarize the text field from the JSON input faithfully.","out":"Result","as":"result","requires":["text"]}}`;
+export async function authorWorkflow(options) {
+    if (!options.request.trim())
+        throw new Error("Workflow request is required");
+    const maxCandidates = options.maxCandidates ?? 4;
+    if (!Number.isSafeInteger(maxCandidates) || maxCandidates < 1)
+        throw new Error("maxCandidates must be a positive integer");
+    const directory = resolve(options.outputDir, `candidate-${randomUUID()}`);
+    await mkdir(directory, { recursive: true });
+    await writeFile(join(directory, "request.json"), JSON.stringify({ request: options.request, inputKeys: options.inputKeys ?? [], rubricSections: options.rubricSections ?? {}, allowExecutableCandidates: options.allowExecutableCandidates ?? false, maxCandidates }, null, 2), { flag: "wx" });
+    let candidates = 0;
+    let acceptedPath;
+    const runner = createPiRunner({ ...options.pi, tools: [], maxSubmissions: maxCandidates });
+    try {
+        const workflow = await runner({
+            kind: "agent", label: "author-workflow", tools: [],
+            system: [AUTHOR_CONTRACT, `Executable candidates authorized: ${options.allowExecutableCandidates ?? false}.`, `All supplied rubric sections (authoritative): ${JSON.stringify(options.rubricSections ?? {})}`],
+            user: `${options.request}\nAvailable input keys: ${JSON.stringify(options.inputKeys ?? [])}`,
+            schema: { type: "object", additionalProperties: true },
+            async review(value) {
+                candidates++;
+                if (candidates > maxCandidates)
+                    throw new Error("Candidate limit exceeded");
+                const candidatePath = join(directory, `${String(candidates).padStart(3, "0")}.json`);
+                await writeFile(candidatePath, JSON.stringify(value, null, 2), { flag: "wx" });
+                const errors = workflowPolicyErrors(value, options);
+                if (!errors.length) {
+                    try {
+                        const verdict = validateWorkflow(value, { inputKeys: options.inputKeys });
+                        if (!verdict.ok)
+                            errors.push(...verdict.errors);
+                    }
+                    catch (error) {
+                        errors.push(`Invalid workflow: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                }
+                if (!errors.length && options.acceptance)
+                    errors.push(...await options.acceptance(structuredClone(value)));
+                await writeFile(join(directory, `${String(candidates).padStart(3, "0")}.review.json`), JSON.stringify({ accepted: !errors.length, checks: options.acceptance ? "structural-and-host" : "structural", errors }, null, 2), { flag: "wx" });
+                if (errors.length)
+                    return { accepted: false, message: errors.join("\n") };
+                acceptedPath = candidatePath;
+                return { accepted: true };
+            },
+        });
+        if (!acceptedPath)
+            throw new Error("Author returned without a retained accepted candidate");
+        await writeFile(join(directory, "result.json"), JSON.stringify({ status: "candidate", path: acceptedPath, candidates }, null, 2), { flag: "wx" });
+        return { workflow, path: acceptedPath, directory, candidates, checks: options.acceptance ? "structural-and-host" : "structural" };
+    }
+    catch (error) {
+        await writeFile(join(directory, "result.json"), JSON.stringify({ status: "failed", candidates, message: error instanceof Error ? error.message : String(error) }, null, 2), { flag: "wx" });
+        throw error;
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};