@tt-a1i/openpi 0.3.0 → 0.4.0

package/extensions/subagents/src/prompt.ts

@@ -3,54 +3,127 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 import { effectiveChildToolAllowlist } from "../../shared/child-session.ts";
-import type { AgentType } from "./agent-types.ts";
+import { SUBAGENT_ROLE_NAMES } from "../../shared/subagent-roles.ts";
+import { type AgentType, READ_ONLY_AGENT_TOOLS } from "./agent-types.ts";
+import { BACKEND_NAMES, REASONING_EFFORTS } from "./domain.ts";
 import { MAX_RUNNING } from "./manager.ts";
 
+export const SUBAGENT_SCHEMA_BUDGETS = Object.freeze({
+  rolePurposeBytes: 240,
+  roleDirectoryBytes: 4 * 1024,
+  defaultSpawnSurfaceBytes: 2.5 * 1024,
+  maximumSpawnSurfaceBytes: 16 * 1024,
+});
+
 /** Describes subagent_spawn, including the fixed concurrency cap. */
 export const SUBAGENT_SPAWN_TOOL_DESCRIPTION =
-  "Spawn a background subagent: a fully autonomous, headless pi session with its own context window, this environment's tools and config, and normal host permissions. Fire-and-forget: this returns immediately with an id, and the subagent's final output is automatically queued back to you as a message when it settles. In an interactive session, keep working or end your turn so the user remains able to interact; do not block merely because a later step depends on the result. Children cannot orchestrate more agents/workflows or ask the user, and cannot see this conversation, so the prompt must be self-contained. Only use trusted working directories. " +
+  "Spawn a background in-process Pi subagent with its own context, child-safe tools, and normal host permissions. Returns immediately; its final result is delivered automatically. The child cannot see this conversation, ask the user, or orchestrate agents/workflows. Use only trusted working directories. " +
   `Max ${MAX_RUNNING} subagents can be running at once.`;
 
-/**
- * Appends the configured agent types, if any. They are a runtime resource, so
- * the roster has to be baked into the description at registration time.
- */
-export function buildSubagentSpawnToolDescription(
-  agentTypes: readonly AgentType[],
-) {
-  if (agentTypes.length === 0) return SUBAGENT_SPAWN_TOOL_DESCRIPTION;
-  return `${SUBAGENT_SPAWN_TOOL_DESCRIPTION} This environment also defines agent types (see agent_type): named presets that fix a child's system prompt, and often restrict it to a subset of tools. Prefer one when it matches the task — a type's tool restriction is enforced, not advisory.`;
+/** UTF-8 bounded, whitespace-normalized text for the parent-facing roster. */
+function boundedPurpose(description: string) {
+  const normalized = description.trim().replace(/\s+/gu, " ");
+  const limit = SUBAGENT_SCHEMA_BUDGETS.rolePurposeBytes;
+  if (Buffer.byteLength(normalized, "utf8") <= limit) return normalized;
+  const suffix = "…";
+  let used = Buffer.byteLength(suffix, "utf8");
+  let output = "";
+  for (const character of normalized) {
+    const bytes = Buffer.byteLength(character, "utf8");
+    if (used + bytes > limit) break;
+    output += character;
+    used += bytes;
+  }
+  return output.trimEnd() + suffix;
+}
+
+function compareNames(left: string, right: string) {
+  return left < right ? -1 : left > right ? 1 : 0;
 }
 
-/** Lists each agent type's enforced capabilities and reasoning default. */
+/** Built-ins stay familiar; project/global additions are stable by name. */
+function orderedAgentTypes(agentTypes: readonly AgentType[]) {
+  const builtInOrder = new Map<string, number>(
+    SUBAGENT_ROLE_NAMES.map((name, index) => [name, index]),
+  );
+  return [...agentTypes].sort((left, right) => {
+    const leftIndex = builtInOrder.get(left.name);
+    const rightIndex = builtInOrder.get(right.name);
+    if (leftIndex !== undefined || rightIndex !== undefined) {
+      if (leftIndex === undefined) return 1;
+      if (rightIndex === undefined) return -1;
+      return leftIndex - rightIndex;
+    }
+    return compareNames(left.name, right.name);
+  });
+}
+
+function capabilityClass(agentType: AgentType) {
+  if (agentType.tools === undefined) return "inherited-tools";
+  const tools = effectiveChildToolAllowlist(agentType.tools) ?? [];
+  if (tools.length === 0) return "no-tools";
+  if (tools.every((tool) => READ_ONLY_AGENT_TOOLS.includes(tool))) {
+    return "read-only";
+  }
+  if (
+    tools.some((tool) => tool === "bash" || tool === "edit" || tool === "write")
+  ) {
+    return "workspace-write";
+  }
+  // Third-party child-safe tools may still have side effects, so only claim
+  // the enforceable fact: this preset has a restricted tool set.
+  return "restricted";
+}
+
+function agentTypeSummary(agentType: AgentType) {
+  const effort = agentType.reasoningEffort
+    ? ` [default reasoning_effort: ${agentType.reasoningEffort}]`
+    : "";
+  return `"${agentType.name}" — ${boundedPurpose(agentType.description)} [${capabilityClass(agentType)}]${effort}`;
+}
+
+/** A deterministic, bounded selection index; execution details stay in Skill. */
 export function buildAgentTypeParameterDescription(
   agentTypes: readonly AgentType[],
 ) {
-  const entries = agentTypes.map((agentType) => {
-    const tools = agentType.tools
-      ? (() => {
-          const effectiveTools = effectiveChildToolAllowlist(agentType.tools);
-          return effectiveTools?.length
-            ? ` [only: ${effectiveTools.join(", ")}]`
-            : " [only: no child-safe tools]";
-        })()
-      : "";
-    const effort = agentType.reasoningEffort
-      ? ` [default reasoning_effort: ${agentType.reasoningEffort}]`
-      : " [reasoning_effort: inherits parent]";
-    return `"${agentType.name}" — ${agentType.description}${tools}${effort}`;
-  });
-  return `Optional agent type: a preset that gives the child a specialized system prompt and, when listed, restricts it to exactly those child-safe tools. Omit for a general-purpose subagent with the normal tool set. Available: ${entries.join("; ")}. Model precedence: explicit spawn model > selected type file model > configured built-in role model > parent model. Reasoning precedence: explicit spawn reasoning_effort > selected type default > parent reasoning effort.`;
+  const ordered = orderedAgentTypes(agentTypes);
+  const intro =
+    "Optional named preset for the child prompt and capability boundary. Omit for a general-purpose child. Available: ";
+  const outro =
+    " Preset restrictions are enforced; read the Subagents Skill or role file for full details.";
+  const entries: string[] = [];
+  for (const agentType of ordered) {
+    const summary = agentTypeSummary(agentType);
+    const next = [...entries, summary];
+    const omitted = ordered.length - next.length;
+    const omission = omitted
+      ? `; ${omitted} presets omitted from this summary; their exact enum names remain valid.`
+      : ".";
+    const candidate = `${intro}${next.join("; ")}${omission}${outro}`;
+    if (
+      Buffer.byteLength(candidate, "utf8") >
+      SUBAGENT_SCHEMA_BUDGETS.roleDirectoryBytes
+    ) {
+      break;
+    }
+    entries.push(summary);
+  }
+  const omitted = ordered.length - entries.length;
+  const omission = omitted
+    ? `; ${omitted} presets omitted from this summary; their exact enum names remain valid.`
+    : ".";
+  return `${intro}${entries.join("; ")}${omission}${outro}`;
 }
 
 /** Generated schema for the dynamic agent-type roster. */
 export function createAgentTypeParameterSchema(
   agentTypes: readonly AgentType[],
 ) {
+  const ordered = orderedAgentTypes(agentTypes);
   return Type.Optional(
     StringEnum(
-      agentTypes.map((agentType) => agentType.name) as [string, ...string[]],
-      { description: buildAgentTypeParameterDescription(agentTypes) },
+      ordered.map((agentType) => agentType.name) as [string, ...string[]],
+      { description: buildAgentTypeParameterDescription(ordered) },
     ),
   );
 }
@@ -61,27 +134,69 @@ export const SUBAGENT_SPAWN_PROMPT_SNIPPET =
 
 /** Guides the parent model to delegate standalone tasks and avoid unnecessary blocking waits. */
 export const SUBAGENT_SPAWN_PROMPT_GUIDELINES = [
-  "Reserve subagent_spawn for substantial, self-contained work; give it a complete, standalone prompt. For a single lookup or edit you can do inline, just do it — each subagent spends a fresh context window and cannot see this conversation.",
-  "After subagent_spawn, keep working on independent work. If none remains in an interactive session, briefly tell the user the subagent is running in the background and end your turn; its result arrives automatically and you are re-invoked when it settles. Do not poll with subagent_check. Do not call subagent_wait merely because your next step depends on the result or because you have nothing else to do. Block only when the user explicitly asks you to keep the current response open for these results, or when a non-interactive automation must return them in the same invocation. Never answer from a guessed result before it arrives.",
+  "Delegate substantial independent work; do a single lookup or edit inline.",
+  "After spawning, continue independent work. In an interactive session, end your turn when none remains; automatic delivery will re-invoke you. Do not call subagent_wait merely because the next step depends on the result; use it only when the user explicitly asks to keep the response open, or the same non-interactive invocation must return the result. Never poll or guess the result.",
 ];
 
 /** Model-facing schema descriptions for subagent_spawn task and execution options. */
 export const SUBAGENT_SPAWN_PARAMETER_DESCRIPTIONS = {
   prompt:
     "Task prompt for the subagent. Must be self-contained: include all needed context, file paths, and what to report back.",
-  name: "Short human-readable name for this subagent, shown in listings and the UI",
-  harness:
-    'Optional. The only harness is "pi" (an in-process Pi session that inherits this environment), which is the default; you can omit this.',
+  name: "Short human-readable name shown in listings and the UI",
+  harness: 'Optional; "pi" is the only harness and the default.',
   workingDir:
-    "Trusted working directory for the autonomous child (default: current working directory)",
+    "Trusted child working directory; defaults to the current directory",
   isolation:
-    'Set to "worktree" for concurrent writers and tell the child to commit. Requires Git and a clean checkout. Read the subagents Skill for lifecycle, merge location, and costs.',
+    'Use "worktree" for concurrent writers and tell the child to commit. See the Subagents Skill for lifecycle details.',
   model:
-    'Optional model override, as "provider/model-id" or a bare id resolved against the current provider. Precedence: explicit spawn model > selected type file model > configured built-in role model > parent model. Never guess a model name.',
+    'Optional "provider/model-id" or current-provider model override. Omit to use the preset, configured role, or parent default. Never guess a model name.',
   reasoningEffort:
-    "Optional thinking level for the child. Precedence: explicit spawn reasoning_effort > selected type default > parent reasoning effort.",
+    "Optional child thinking level. Honor the user's requested level. Otherwise choose a level supported by the resolved child model based on the selected role and task difficulty. An explicit value overrides a role default.",
 };
 
+/** The exact name/description/wire-schema source used by registration/tests. */
+export function createSubagentSpawnToolSurface(
+  agentTypes: readonly AgentType[],
+) {
+  return {
+    description: SUBAGENT_SPAWN_TOOL_DESCRIPTION,
+    parameters: Type.Object({
+      agent_type: createAgentTypeParameterSchema(agentTypes),
+      prompt: Type.String({
+        description: SUBAGENT_SPAWN_PARAMETER_DESCRIPTIONS.prompt,
+      }),
+      name: Type.String({
+        description: SUBAGENT_SPAWN_PARAMETER_DESCRIPTIONS.name,
+      }),
+      harness: Type.Optional(
+        StringEnum(BACKEND_NAMES, {
+          description: SUBAGENT_SPAWN_PARAMETER_DESCRIPTIONS.harness,
+        }),
+      ),
+      working_dir: Type.Optional(
+        Type.String({
+          description: SUBAGENT_SPAWN_PARAMETER_DESCRIPTIONS.workingDir,
+        }),
+      ),
+      isolation: Type.Optional(
+        StringEnum(["worktree"] as const, {
+          description: SUBAGENT_SPAWN_PARAMETER_DESCRIPTIONS.isolation,
+        }),
+      ),
+      model: Type.Optional(
+        Type.String({
+          description: SUBAGENT_SPAWN_PARAMETER_DESCRIPTIONS.model,
+        }),
+      ),
+      reasoning_effort: Type.Optional(
+        StringEnum(REASONING_EFFORTS, {
+          description: SUBAGENT_SPAWN_PARAMETER_DESCRIPTIONS.reasoningEffort,
+        }),
+      ),
+    }),
+  };
+}
+
 /** Builds the subagent_spawn result that tells the parent model how to continue or inspect the child. */
 export function buildSubagentSpawnResult(options: {
   id: string;

package/extensions/subagents/src/result-artifact.ts

@@ -0,0 +1,142 @@
+import { createHash } from "node:crypto";
+import { lstatSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import {
+  formatSize,
+  truncateHead,
+  truncateTail,
+} from "@earendil-works/pi-coding-agent";
+
+const HEAD_SHARE = 0.75;
+const RESULT_ARTIFACT_DIR = ["cache", "openpi", "subagent-results"];
+
+export interface ResultProjectionOptions {
+  readonly maxBytes: number;
+  readonly maxLines: number;
+  readonly writeArtifact: (content: string) => string;
+}
+
+export interface ResultProjection {
+  readonly text: string;
+  readonly truncated: boolean;
+  readonly artifactPath?: string;
+}
+
+function sliceStartToUtf8Bytes(content: string, maxBytes: number) {
+  const bytes = Buffer.from(content, "utf8");
+  if (bytes.length <= maxBytes) return content;
+  let end = maxBytes;
+  while (end > 0 && (bytes[end] & 0xc0) === 0x80) end--;
+  return bytes.subarray(0, end).toString("utf8");
+}
+
+function ensureDirectory(parent: string, name: string) {
+  const directory = path.join(parent, name);
+  try {
+    mkdirSync(directory, { mode: 0o700 });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+  }
+  const stat = lstatSync(directory);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) {
+    throw new Error(`Unsafe result artifact directory: ${directory}`);
+  }
+  return directory;
+}
+
+/**
+ * Persist one immutable, content-addressed final answer below Pi's cache.
+ * Model-authored titles and paths never participate in the filename.
+ */
+export function persistResultArtifact(agentDir: string, content: string) {
+  let directory = path.resolve(agentDir);
+  for (const segment of RESULT_ARTIFACT_DIR) {
+    directory = ensureDirectory(directory, segment);
+  }
+
+  const digest = createHash("sha256").update(content).digest("hex");
+  const artifactPath = path.join(directory, `${digest}.txt`);
+  try {
+    writeFileSync(artifactPath, content, {
+      encoding: "utf8",
+      flag: "wx",
+      mode: 0o600,
+    });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    const stat = lstatSync(artifactPath);
+    if (
+      !stat.isFile() ||
+      stat.isSymbolicLink() ||
+      readFileSync(artifactPath, "utf8") !== content
+    ) {
+      throw new Error(`Result artifact collision: ${artifactPath}`);
+    }
+  }
+  return artifactPath;
+}
+
+/**
+ * Build the single model-visible projection used by automatic delivery and
+ * explicit waits. Short answers pass through byte-for-byte. Long answers keep
+ * both decision context at the start and verdict/evidence at the end, while a
+ * plain-text artifact preserves the exact final answer for Pi's native read.
+ */
+export function projectResult(
+  content: string,
+  options: ResultProjectionOptions,
+): ResultProjection {
+  const probe = truncateHead(content, {
+    maxBytes: options.maxBytes,
+    maxLines: options.maxLines,
+  });
+  if (!probe.truncated) return { text: content, truncated: false };
+
+  const headLines = Math.max(1, Math.floor(options.maxLines * HEAD_SHARE));
+  const tailLines = Math.max(1, options.maxLines - headLines);
+
+  let artifactPath: string | undefined;
+  try {
+    artifactPath = options.writeArtifact(content);
+  } catch {
+    // Delivery is more important than the optional recovery cache. The footer
+    // below stays explicit so a failed write never advertises a false path.
+  }
+
+  let bodyBudget = options.maxBytes;
+  let text = "";
+  for (let attempt = 0; attempt < 8; attempt++) {
+    const headBytes = Math.max(1, Math.floor(bodyBudget * HEAD_SHARE));
+    const tailBytes = Math.max(1, bodyBudget - headBytes);
+    const headResult = truncateHead(content, {
+      maxBytes: headBytes,
+      maxLines: headLines,
+    });
+    const tailResult = truncateTail(content, {
+      maxBytes: tailBytes,
+      maxLines: tailLines,
+    });
+    const head =
+      headResult.content || sliceStartToUtf8Bytes(content, headBytes);
+    const tail = tailResult.content;
+    const shownBytes =
+      Buffer.byteLength(head, "utf8") + Buffer.byteLength(tail, "utf8");
+    const recovery = artifactPath
+      ? `Full final answer: ${JSON.stringify(artifactPath)}\nUse Pi's read tool with path=${JSON.stringify(artifactPath)}, offset=${Math.max(1, headResult.outputLines + 1)}, limit=200 to inspect the omitted middle; adjust offset to continue.`
+      : "Full final answer could not be saved; only the head and tail above are available.";
+    const footer =
+      `[Output truncated: showing ${formatSize(shownBytes)} of ${formatSize(probe.totalBytes)} ` +
+      `across the head and tail (${probe.totalLines} total lines).\n${recovery}]`;
+    text = `${head}\n\n[... middle omitted ...]\n\n${tail}\n\n${footer}`;
+
+    const overflow = Buffer.byteLength(text, "utf8") - options.maxBytes;
+    if (overflow <= 0 || bodyBudget <= overflow + 2) break;
+    bodyBudget -= overflow;
+  }
+
+  return {
+    text,
+    truncated: true,
+    ...(artifactPath ? { artifactPath } : {}),
+  };
+}

package/extensions/subagents/src/result-delivery.ts

@@ -1,17 +1,62 @@
-export function createDeferredResultDelivery<T extends { id: string }>() {
+export interface SubagentResultDeliveryOptions<T> {
+  /** True only when the parent has no run or queued continuation in flight. */
+  readonly isIdle: () => boolean;
+  /** Deliver one drained batch and wake the parent. */
+  readonly deliver: (results: readonly T[]) => void;
+}
+
+/**
+ * One-shot result delivery for fire-and-forget subagents.
+ *
+ * The tool contract promises that a settled child re-invokes the parent. A
+ * child that settles while the parent is busy therefore remains retractable
+ * until the parent's `agent_settled` event, but it must never be downgraded to
+ * a `nextTurn` message that needs another user prompt. There are two symmetric
+ * wake-up edges so no ordering can lose the notification:
+ *
+ * 1. child settles after the parent became idle -> `defer` flushes now;
+ * 2. parent settles after the child -> `parentSettled` flushes the batch.
+ *
+ * The parent boundary wakes even if an earlier extension handler has already
+ * started another turn: Pi queues the follow-up into that active run.
+ *
+ * The Map is the one-shot gate: `subagent_wait` may consume a result before it
+ * is delivered, and whichever path drains first prevents duplicate delivery.
+ */
+export function createSubagentResultDelivery<T extends { id: string }>(
+  options: SubagentResultDeliveryOptions<T>,
+) {
   const pending = new Map<string, T>();
 
+  const flush = () => {
+    if (pending.size === 0) return;
+    const results = [...pending.values()];
+    pending.clear();
+    try {
+      options.deliver(results);
+    } catch (error) {
+      // A synchronous session teardown may reject append/send. Preserve the
+      // original batch ahead of anything deferred re-entrantly while delivery
+      // ran, so a later boundary can retry without loss or reordering.
+      const current = [...pending.values()];
+      pending.clear();
+      for (const result of results) pending.set(result.id, result);
+      for (const result of current) pending.set(result.id, result);
+      throw error;
+    }
+  };
+
   return {
     defer(result: T) {
       pending.set(result.id, result);
+      if (options.isIdle()) flush();
     },
     consume(ids: Iterable<string>) {
       for (const id of ids) pending.delete(id);
     },
-    drain() {
-      const results = [...pending.values()];
-      pending.clear();
-      return results;
+    /** Flush at the authoritative parent boundary. */
+    parentSettled() {
+      flush();
     },
     clear() {
       pending.clear();

package/extensions/subagents/src/runtime.ts

@@ -18,12 +18,15 @@ const BackendRegistryLive = Layer.sync(BackendRegistry, () => {
   );
 });
 
-import { SubagentManagerLive } from "./manager.ts";
+import {
+  makeSubagentManagerLayer,
+  type SubagentManagerConfig,
+} from "./manager.ts";
 
-const AppLayer = SubagentManagerLive.pipe(Layer.provide(BackendRegistryLive));
-
-export function createSubagentRuntime() {
-  return ManagedRuntime.make(AppLayer);
+export function createSubagentRuntime(config: SubagentManagerConfig = {}) {
+  return ManagedRuntime.make(
+    makeSubagentManagerLayer(config).pipe(Layer.provide(BackendRegistryLive)),
+  );
 }
 
 export type SubagentRuntime = ReturnType<typeof createSubagentRuntime>;