@introspection-ai/recipes 0.13.0

package/LICENSE

@@ -0,0 +1,191 @@
+
+                                 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 the 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 the 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 any 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
+
+   Copyright 2026 Introspection AI Inc.
+
+   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/README.md

@@ -0,0 +1,184 @@
+<div align="center">
+  <a href="https://pi.recipes">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset=".github/images/logo-dark.svg">
+      <source media="(prefers-color-scheme: light)" srcset=".github/images/logo-light.svg">
+      <img alt="Recipes" src=".github/images/logo-light.svg" width="165">
+    </picture>
+  </a>
+</div>
+
+<h4 align="center">The open package format for complete, portable Pi agents.</h4>
+
+<div align="center">
+  <a href="https://pi.recipes"><img src="https://img.shields.io/badge/website-pi.recipes-blue" alt="Website"></a>
+  <a href="https://github.com/introspection-org/pi-recipes/actions/workflows/ci.yml"><img src="https://github.com/introspection-org/pi-recipes/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/@introspection-ai/recipes"><img src="https://img.shields.io/npm/v/@introspection-ai/recipes?label=npm" alt="npm version"></a>
+  <a href="https://crates.io/crates/pi-recipe-check"><img src="https://img.shields.io/crates/v/pi-recipe-check?label=crates.io" alt="crates.io version"></a>
+  <a href="https://www.apache.org/licenses/LICENSE-2.0"><img src="https://img.shields.io/badge/license-Apache%202.0-green" alt="License"></a>
+</div>
+
+<br>
+
+**Everything that makes your agent yours, in one portable package.**
+
+A Recipe keeps a complete Pi agent—its instructions, models, tools, skills,
+extensions, subagents, capability policy, and quality definitions—together as
+ordinary source you can inspect, fork, validate, and own.
+
+Run the same Recipe locally, on Introspection, or in another compatible Pi
+host. The Recipe is portable; credentials, isolation, persistence, scheduling,
+and deployment remain the host's responsibility.
+
+## What Recipes is
+
+Recipes has two deliberately small surfaces:
+
+1. **The Recipe Format** is the open, Git-native package contract.
+2. **The Recipes runtime library** resolves that package into a live Pi session
+   without imposing a server, queue, database, or deployment platform.
+
+[Pi](https://pi.dev/docs/latest) is the minimal agent harness. A Recipe packages
+the complete configured agent built on that harness. It is more than a prompt
+template or a collection of Pi resources, but it is not a hosting framework.
+
+## Package anatomy
+
+```text
+my-recipe/
+├── package.json          # identity and Pi resource declarations
+├── SYSTEM.md             # optional shared instructions
+├── agents/*.yaml         # models, tools, skills, subagents, policy
+├── skills/**/SKILL.md    # reusable domain workflows
+├── extensions/*.ts       # optional Recipe-owned Pi extensions
+├── judges/*.yaml         # optional portable quality definitions
+└── .pi/mcp.local.example.json # optional binding template
+```
+
+The normative contract is documented in [Recipe Format](docs/recipe-format.md).
+
+## Use a Recipe
+
+The [`introspection`](https://github.com/introspection-org/introspection-cli)
+CLI owns the end-to-end local workflow:
+
+```bash
+npm install -g @introspection-ai/cli
+introspection init
+introspection check
+introspection local
+```
+
+`introspection init` installs a compatible Pi and Recipes extension when they
+are missing. `introspection local` launches the selected local Recipe directly
+with Pi. It does not require an Introspection login or managed runtime.
+
+To install the extension without the Introspection CLI:
+
+```bash
+pi install npm:@introspection-ai/recipes
+pi --recipe ./path/to/recipe --agent agent
+```
+
+## Embed the runtime
+
+Install the library in a Pi host:
+
+```bash
+npm install @introspection-ai/recipes
+```
+
+Choose the lowest useful layer:
+
+```ts
+import { resolveRecipe } from "@introspection-ai/recipes/recipe";
+
+const recipe = resolveRecipe({
+  recipeDir: "./my-recipe",
+  agentName: "agent",
+});
+```
+
+```ts
+import { createRecipeSession } from "@introspection-ai/recipes/session";
+
+const handle = await createRecipeSession({
+  recipeDir: "./my-recipe",
+  cwd: "./workspace",
+  agentName: "agent",
+  credentials,
+  mcpBindings,
+  sessionManager,
+  otel: { tracer, meta: { conversationId } },
+});
+
+await handle.session.prompt("Start the task");
+await handle.dispose();
+```
+
+```ts
+import { runRecipe } from "@introspection-ai/recipes/run";
+
+const result = await runRecipe({
+  recipeDir: "./my-recipe",
+  cwd: "./workspace",
+  prompt: "Produce the report",
+});
+```
+
+`createRecipeSession` is the primary host boundary. It owns Recipe semantics
+and Pi session construction. The host still owns task lifecycle, durable state,
+auth, networking, isolation, protocol translation, and deployment.
+
+See [Runtime library](docs/runtime-library.md) for the complete API boundary and
+[host conformance](docs/runtime-library.md#host-conformance) for compatibility
+tests.
+
+## Public exports
+
+- `@introspection-ai/recipes` — core Recipe types and runtime helpers
+- `@introspection-ai/recipes/recipe` — resolve a Recipe into session inputs
+- `@introspection-ai/recipes/session` — create a live Pi Recipe session
+- `@introspection-ai/recipes/run` — execute one Recipe turn
+- `@introspection-ai/recipes/pi-extension` — Pi extension entrypoint
+- `@introspection-ai/recipes/pi` — shared subagent tool and controller types
+- `@introspection-ai/recipes/interactions` — portable user-input and approval contract
+- `@introspection-ai/recipes/inspect` — derive host requirements
+- `@introspection-ai/recipes/test-utils` — host conformance cases
+
+The package intentionally has no `recipes` executable and no generic HTTP
+server. The `introspection` CLI owns authoring and local operation. Hosting
+adapters and deployment cookbooks belong outside this runtime package.
+
+## Validation
+
+The format validator is independently reusable:
+
+- [`pi-recipe-check`](https://crates.io/crates/pi-recipe-check) — Rust crate and
+  standalone validator
+- [`pi-recipe-check`](https://pypi.org/project/pi-recipe-check/) — Python
+  bindings for validating in-memory Recipe snapshots
+
+The Introspection CLI embeds the same validation engine used by managed
+deployments.
+
+## Documentation
+
+- [Recipe Format](docs/recipe-format.md)
+- [Runtime library](docs/runtime-library.md)
+- [Pi extension](docs/pi-extension.md)
+- [Agent composition](docs/agent-composition.md)
+- [Interactions](docs/interactions.md)
+- [MCP configuration](docs/mcp-configuration.md)
+- [Deployment configuration](docs/deployment-configuration.md)
+- [Recipe judges](docs/recipe-judges.md)
+- [Recipe eval declarations](docs/recipe-evals.md)
+- [Migration from `@introspection-ai/pi-recipes`](docs/migration.md)
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+Apache-2.0

package/dist/agent-tool.d.ts

@@ -0,0 +1,42 @@
+import { type ToolDefinition } from "@earendil-works/pi-coding-agent";
+export type AgentRunStatus = "running" | "completed" | "failed" | "interrupted" | "closed";
+export interface AgentNestedToolSummary {
+    toolName: string;
+    verb: string;
+    detail: string;
+    toolInput?: Record<string, unknown>;
+}
+export interface AgentRunSummary {
+    agent_run_id: string;
+    invocation_name: string;
+    agent_name: string;
+    label: string;
+    prompt: string;
+    status: AgentRunStatus;
+    started_at: number;
+    completed_at?: number;
+    last_activity_at: number;
+    current_tool?: string;
+    nested_tools?: AgentNestedToolSummary[];
+    output_preview?: string;
+    output?: string;
+    error?: string;
+}
+export interface AgentRunController {
+    list(): AgentRunSummary[];
+    get(id: string): AgentRunSummary | null;
+    start(input: {
+        name: string;
+        prompt: string;
+        label?: string;
+        onUpdate?: (summary: AgentRunSummary) => void | Promise<void>;
+    }): Promise<AgentRunSummary>;
+    wait(id: string, signal?: AbortSignal): Promise<AgentRunSummary>;
+    message(id: string, message: string): Promise<AgentRunSummary>;
+    interrupt(id: string): Promise<AgentRunSummary>;
+    close(id: string): Promise<AgentRunSummary>;
+}
+export declare function createAgentTool(controller: AgentRunController, agents: ReadonlyMap<string, unknown>, opts?: {
+    acknowledgeCompletions?(ids: readonly string[]): void;
+}): ToolDefinition;
+//# sourceMappingURL=agent-tool.d.ts.map

package/dist/agent-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-tool.d.ts","sourceRoot":"","sources":["../src/agent-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAGlF,MAAM,MAAM,cAAc,GACtB,SAAS,GACT,WAAW,GACX,QAAQ,GACR,aAAa,GACb,QAAQ,CAAC;AAEb,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,cAAc,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,sBAAsB,EAAE,CAAC;IACxC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,IAAI,eAAe,EAAE,CAAC;IAC1B,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAAC;IACxC,KAAK,CAAC,KAAK,EAAE;QACX,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KAC/D,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAC7B,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IACjE,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAC/D,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAChD,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CAC7C;AAyED,wBAAgB,eAAe,CAC7B,UAAU,EAAE,kBAAkB,EAC9B,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,IAAI,GAAE;IAAE,sBAAsB,CAAC,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAA;CAAO,GACnE,cAAc,CAuGhB"}

package/dist/agent-tool.js

@@ -0,0 +1,159 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+const AgentToolParams = Type.Object({
+    action: Type.Optional(Type.Union([
+        Type.Literal("start"),
+        Type.Literal("status"),
+        Type.Literal("wait"),
+        Type.Literal("message"),
+        Type.Literal("interrupt"),
+        Type.Literal("close"),
+    ])),
+    name: Type.Optional(Type.String()),
+    prompt: Type.Optional(Type.String()),
+    label: Type.Optional(Type.String()),
+    id: Type.Optional(Type.String()),
+    message: Type.Optional(Type.String()),
+});
+function terminal(run) {
+    return run.status !== "running";
+}
+function runLine(run) {
+    return `${run.invocation_name} (${run.agent_run_id}) — ${run.label} [${run.status}]`;
+}
+function statusBlock(run) {
+    if (!terminal(run))
+        return runLine(run);
+    const output = run.output?.trim() ||
+        (run.error ? `Agent failed: ${run.error}` : `Agent ${run.status}.`);
+    return `${runLine(run)}\n${output}`;
+}
+function subtask(run) {
+    const nestedTools = [...(run.nested_tools ?? [])];
+    if (run.current_tool && !nestedTools.some((tool) => tool.toolName === run.current_tool)) {
+        nestedTools.push({ toolName: run.current_tool, verb: run.current_tool, detail: "" });
+    }
+    return {
+        agentName: run.invocation_name,
+        label: run.label,
+        task: run.prompt,
+        nestedTools,
+        transcript: run.output_preview
+            ? [{ type: "assistant", text: run.output_preview }]
+            : [],
+        status: terminal(run) ? "completed" : "running",
+        finishReason: run.status === "completed" ? "stop" : run.error ?? run.status,
+        startedAt: run.started_at,
+        completedAt: run.completed_at,
+    };
+}
+function result(run, text) {
+    return {
+        content: [{ type: "text", text }],
+        details: { agent: run, subtasks: [subtask(run)] },
+    };
+}
+function errorResult(text, controller) {
+    return {
+        content: [{ type: "text", text }],
+        details: { agents: controller.list() },
+        isError: true,
+    };
+}
+export function createAgentTool(controller, agents, opts = {}) {
+    const closedRunIds = new Set();
+    const acknowledge = (run) => {
+        if (terminal(run))
+            opts.acknowledgeCompletions?.([run.agent_run_id]);
+    };
+    return defineTool({
+        name: "agent",
+        label: "Agent",
+        description: [
+            "Start or manage background child agents.",
+            "Omit action to start one child with name and prompt; it returns a run id immediately.",
+            `Available agent roles: ${[...agents.keys()].join(", ")}. Pass a role as name; use label to distinguish concurrent runs.`,
+            "Use status, wait, message, interrupt, or close with that id.",
+            "Message steers a running child at the next message boundary; on a settled child it resumes the same session.",
+        ].join(" "),
+        parameters: AgentToolParams,
+        async execute(_callId, rawParams, signal, onUpdate) {
+            const params = rawParams;
+            try {
+                if (!params.action || params.action === "start") {
+                    if (!params.name || !params.prompt) {
+                        return errorResult("Starting an agent requires name and prompt.", controller);
+                    }
+                    if (!agents.has(params.name)) {
+                        return errorResult(`Unknown agent "${params.name}". Available: ${[...agents.keys()].join(", ")}`, controller);
+                    }
+                    const run = await controller.start({
+                        name: params.name,
+                        prompt: params.prompt,
+                        label: params.label,
+                        onUpdate(update) {
+                            return onUpdate?.({
+                                content: [{ type: "text", text: "" }],
+                                details: { subtasks: [subtask(update)] },
+                            });
+                        },
+                    });
+                    return result(run, `Started ${runLine(run)}`);
+                }
+                if (params.action === "status" && !params.id) {
+                    const runs = controller.list();
+                    runs.forEach(acknowledge);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: runs.length
+                                    ? runs.map(statusBlock).join("\n\n")
+                                    : "No agent runs.",
+                            },
+                        ],
+                        details: { agents: runs, subtasks: runs.map(subtask) },
+                    };
+                }
+                if (!params.id)
+                    return errorResult(`${params.action} requires id`, controller);
+                if (closedRunIds.has(params.id)) {
+                    return errorResult(`Agent run already closed: ${params.id}`, controller);
+                }
+                if (params.action === "status") {
+                    const run = controller.get(params.id);
+                    if (!run)
+                        return errorResult(`Unknown agent run: ${params.id}`, controller);
+                    acknowledge(run);
+                    return result(run, statusBlock(run));
+                }
+                if (params.action === "wait") {
+                    const run = await controller.wait(params.id, signal);
+                    acknowledge(run);
+                    return result(run, statusBlock(run));
+                }
+                if (params.action === "message") {
+                    if (!params.message)
+                        return errorResult("message requires message", controller);
+                    const run = await controller.message(params.id, params.message);
+                    return result(run, `Sent message to ${runLine(run)}`);
+                }
+                if (params.action === "interrupt") {
+                    const run = await controller.interrupt(params.id);
+                    if (run.status !== "interrupted") {
+                        return result(run, `No interrupt sent: ${runLine(run)} is already ${run.status}.`);
+                    }
+                    return result(run, `Interrupted ${runLine(run)}`);
+                }
+                const run = await controller.close(params.id);
+                closedRunIds.add(params.id);
+                opts.acknowledgeCompletions?.([params.id]);
+                return result(run, `Closed ${runLine(run)}`);
+            }
+            catch (error) {
+                return errorResult(`Agent ${params.action ?? "start"} failed: ${error instanceof Error ? error.message : String(error)}`, controller);
+            }
+        },
+    });
+}
+//# sourceMappingURL=agent-tool.js.map

package/dist/agent-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-tool.js","sourceRoot":"","sources":["../src/agent-tool.ts"],"names":[],"mappings":"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"}

package/dist/child-agent-completions.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Child agent-run completion queue.
+ *
+ * When a background child run settles as `completed`/`failed`, the extension
+ * enqueues an envelope here. The registered deliverer — wired up in
+ * `pi-extension.ts` — drains the queue into a parent-waking custom message
+ * (`pi.sendMessage(..., { triggerTurn: true })`) once the parent session is
+ * idle; while the parent is mid-turn the deliverer holds the queue and
+ * retries shortly after the `agent_end` boundary poke (a message queued
+ * during the turn teardown itself would be stranded on current pi releases).
+ *
+ * Successes batch briefly so N parallel children produce one notice;
+ * failures flush immediately. Runs whose terminal output the model already
+ * saw synchronously (`action:"wait"` or a terminal `status` read) are
+ * acknowledged out of the queue so nothing is delivered
+ * twice.
+ */
+import type { ChildRunSnapshot } from "./child-agent-store.js";
+/** Batching window for successful completions. Failures skip it. */
+export declare const COMPLETION_BATCH_WINDOW_MS = 2000;
+/** Cap on inline output previews; full output stays in status.json. */
+export declare const OUTPUT_PREVIEW_CHARS = 4000;
+export interface ChildCompletionEnvelope {
+    id: string;
+    agent: string;
+    label?: string;
+    status: "completed" | "failed";
+    output_preview?: string;
+    error?: string;
+    duration_ms?: number;
+}
+export declare function envelopeFromRun(run: ChildRunSnapshot): ChildCompletionEnvelope | null;
+/**
+ * Model-facing notice. The `<agent_run_completions>` wrapper marks it as a
+ * runtime notification rather than user input.
+ */
+export declare function renderCompletionNotice(batch: readonly ChildCompletionEnvelope[]): string;
+export declare class ChildCompletionQueue {
+    private pending;
+    private deliverer;
+    private flushTimer;
+    private deliveryScheduled;
+    setDeliverer(deliverer: (() => void) | null): void;
+    enqueue(envelope: ChildCompletionEnvelope): void;
+    /**
+     * Re-attempt delivery of anything still queued (no-op when empty). Called
+     * at the `agent_end` settle boundary: a batch held mid-turn delivers here,
+     * bypassing any open batch window.
+     */
+    poke(): void;
+    /**
+     * Drop queued envelopes whose terminal output the model just saw
+     * synchronously (wait or terminal status read).
+     */
+    acknowledge(ids: readonly string[]): void;
+    hasPending(): boolean;
+    consumeBatch(): ChildCompletionEnvelope[];
+    clear(): void;
+    private flushNow;
+}
+//# sourceMappingURL=child-agent-completions.d.ts.map

package/dist/child-agent-completions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"child-agent-completions.d.ts","sourceRoot":"","sources":["../src/child-agent-completions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,oEAAoE;AACpE,eAAO,MAAM,0BAA0B,OAAQ,CAAC;AAEhD,uEAAuE;AACvE,eAAO,MAAM,oBAAoB,OAAQ,CAAC;AAE1C,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,WAAW,GAAG,QAAQ,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,eAAe,CAC7B,GAAG,EAAE,gBAAgB,GACpB,uBAAuB,GAAG,IAAI,CAiBhC;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,SAAS,uBAAuB,EAAE,GACxC,MAAM,CAiBR;AAED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,OAAO,CAAiC;IAChD,OAAO,CAAC,SAAS,CAA6B;IAC9C,OAAO,CAAC,UAAU,CAA+B;IACjD,OAAO,CAAC,iBAAiB,CAAS;IAElC,YAAY,CAAC,SAAS,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI;IAKlD,OAAO,CAAC,QAAQ,EAAE,uBAAuB,GAAG,IAAI;IAehD;;;;OAIG;IACH,IAAI,IAAI,IAAI;IASZ;;;OAGG;IACH,WAAW,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI;IAQzC,UAAU,IAAI,OAAO;IAIrB,YAAY,IAAI,uBAAuB,EAAE;IAKzC,KAAK,IAAI,IAAI;IAQb,OAAO,CAAC,QAAQ;CAYjB"}