@diousk/pi-subagents-fast 0.20.0

package/src/skill-loader.ts

@@ -0,0 +1,102 @@
+/**
+ * skill-loader.ts — Preload named skills.
+ *
+ * Roots, in precedence order:
+ *   - <cwd>/.pi/skills           (project, Pi's standard)
+ *   - <cwd>/.agents/skills       (project, cross-tool Agent Skills spec — https://agentskills.io)
+ *   - getAgentDir()/skills       (user, default ~/.pi/agent/skills — Pi's standard)
+ *   - ~/.agents/skills           (user, cross-tool Agent Skills spec)
+ *   - ~/.pi/skills               (legacy global, pre-Pi)
+ *
+ * Layout per root:
+ *   - <root>/<name>.md            (flat file at the top level)
+ *   - <root>/.../<name>/SKILL.md  (directory skill, may be nested — Pi's standard)
+ *
+ * Recursion skips dotfile entries and node_modules. A directory that itself contains
+ * SKILL.md is a skill — we don't descend into it (Pi: skills don't nest).
+ *
+ * Symlinks are rejected for security (deviation from Pi, which follows them).
+ */
+
+import type { Dirent } from "node:fs";
+import { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { isSymlink, isUnsafeName, safeReadFile } from "./memory.js";
+
+export interface PreloadedSkill {
+  name: string;
+  content: string;
+}
+
+export function preloadSkills(skillNames: string[], cwd: string): PreloadedSkill[] {
+  return skillNames.map((name) => ({ name, content: loadSkillContent(name, cwd) }));
+}
+
+function loadSkillContent(name: string, cwd: string): string {
+  if (isUnsafeName(name)) {
+    return `(Skill "${name}" skipped: name contains path traversal characters)`;
+  }
+  const roots = [
+    join(cwd, ".pi", "skills"), // project — Pi standard
+    join(cwd, ".agents", "skills"), // project — Agent Skills spec
+    join(getAgentDir(), "skills"), // user — Pi standard
+    join(homedir(), ".agents", "skills"), // user — Agent Skills spec
+    join(homedir(), ".pi", "skills"), // legacy global, pre-Pi
+  ];
+  for (const root of roots) {
+    const content = findInRoot(root, name);
+    if (content !== undefined) return content;
+  }
+  return `(Skill "${name}" not found in .pi/skills/, .agents/skills/, or global skill locations)`;
+}
+
+function findInRoot(root: string, name: string): string | undefined {
+  if (isSymlink(root)) return undefined; // reject symlinked roots entirely
+  const flat = safeReadFile(join(root, `${name}.md`))?.trim();
+  if (flat !== undefined) return flat;
+  return findSkillDirectory(root, name);
+}
+
+/** BFS under `root` for a directory named `name` containing `SKILL.md`. Pi-conforming filters. */
+function findSkillDirectory(root: string, name: string): string | undefined {
+  if (!existsSync(root)) return undefined;
+  const queue: string[] = [root];
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (current === undefined) continue;
+
+    let entries: Dirent<string>[];
+    try {
+      entries = readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    // Deterministic byte-order traversal — locale-independent.
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+
+      // Symlinked dirs already filtered by entry.isDirectory() — Dirent uses lstat semantics.
+      const path = join(current, entry.name);
+      const skillMd = join(path, "SKILL.md");
+      const isSkillDir = existsSync(skillMd);
+
+      if (isSkillDir) {
+        if (entry.name === name) {
+          const content = safeReadFile(skillMd)?.trim();
+          if (content !== undefined) return content;
+        }
+        continue; // Pi rule: skills don't nest — don't descend into a skill dir
+      }
+
+      queue.push(path);
+    }
+  }
+  return undefined;
+}

package/src/status-note.ts

@@ -0,0 +1,90 @@
+/**
+ * status-note.ts — Honest framing for an agent result: the parenthetical status
+ * note for a non-normal outcome, and the salvaged partial output of a failure.
+ *
+ * Lives here rather than in an index.ts closure because both entry points need
+ * it — the top-level tools and the nested delegation tools, which can't import
+ * from index.ts (that is the extension entry, and it already reaches these tools
+ * through agent-runner).
+ */
+
+import type { AgentRecord } from "./types.js";
+
+/**
+ * Explicit parenthetical note for a non-normal terminal outcome, so the parent
+ * agent can't mistake partial output for a completed result. Empty string for a
+ * clean completion (and any unknown/non-terminal status).
+ *
+ * `stopped` (a human aborted it) is deliberately distinct from `aborted` (the
+ * turn limit was hit) — the parent should treat human intervention differently
+ * from a budget cutoff.
+ */
+export function getStatusNote(status: string): string {
+  switch (status) {
+    case "stopped":
+      return " (STOPPED BY THE USER before completion — output is partial; the task was NOT finished)";
+    case "aborted":
+      return " (aborted — hit the turn limit before completion; output may be incomplete)";
+    case "steered":
+      return " (wrapped up at the turn limit — output may be partial)";
+    default:
+      return "";
+  }
+}
+
+/**
+ * Foreground variant of `getStatusNote`. A foreground caller is in a different
+ * position from a background one, so it needs different text:
+ *
+ *   - It already holds the agent's ENTIRE output inline, whereas the background
+ *     notification carries a 500-char preview. So only here can we truthfully
+ *     say there is nothing more to fetch — which is the whole point, because
+ *   - it has no agent id. The id travels in the tool result's renderer
+ *     `details`, which is never serialized to the model. A parent that reads
+ *     "output may be partial" as "truncated, go retrieve the rest" therefore
+ *     has nothing valid to call `get_subagent_result` with, and will invent an
+ *     id (#174).
+ *
+ * Only the lead clause varies between the three, and each variation carries
+ * information: `wrapped up` vs `aborted` tells the parent whether the output is
+ * a considered final answer or a fragment, and `stopped` shouts because a human
+ * intervening outranks everything else in the string. Only `steered` hedges on
+ * completion — it was told to wrap up and did, so it may well have finished at
+ * the limit; an aborted run blew through its grace turns while still working,
+ * and `stopped` can only fire on a running agent, so neither ever delivered a
+ * final answer. Identical confidence gets identical wording: phrasing one fact
+ * two ways invites a hunt for a distinction that isn't there.
+ *
+ * Every clause is a statement about state, never an instruction to act, and
+ * `get_subagent_result` is never named — naming the tool we steer away from only
+ * raises its salience. Two instructions were tried here and cut: "re-spawn with
+ * a higher max_turns" (pushes a fresh multi-minute run to save one wasted tool
+ * call) and, on `stopped`, "ask before restarting it" (restates the lead, and
+ * presumes someone is present to ask — false under `pi -p`, in scheduled jobs,
+ * and in any background-driven run). Nothing here can measure whether wording
+ * improves parent behavior, so removing a false cue (which cannot induce new
+ * behavior) and adding an instruction (which can) are not equally safe bets.
+ * Don't add either back without a way to measure it.
+ */
+export function getForegroundOutcomeNote(status: string): string {
+  switch (status) {
+    case "stopped":
+      return " (STOPPED BY THE USER — everything the agent produced is above; the task is unfinished)";
+    case "aborted":
+      return " (aborted at the turn limit — everything the agent produced is above; the task is unfinished)";
+    case "steered":
+      return " (wrapped up at the turn limit — everything the agent produced is above; the task may be unfinished)";
+    default:
+      return "";
+  }
+}
+
+/**
+ * Salvaged partial output of a failed run, as a labeled suffix for the error
+ * surfaces (or "" if the run produced nothing). `record.result` is bounded to
+ * the run's own turns, so this is never a stale earlier answer (#144).
+ */
+export function partialOutputSuffix(record: AgentRecord): string {
+  const partial = record.result?.trim();
+  return partial ? `\n\nPartial output before the failure:\n${partial}` : "";
+}

package/src/structured-output.ts

@@ -0,0 +1,130 @@
+/**
+ * structured-output.ts — the synthetic tool behind `agent(prompt, { schema })`.
+ *
+ * A workflow script that passes a `schema` wants an *object* back, not prose it
+ * has to parse. Claude Code does this by giving the child a `StructuredOutput`
+ * tool whose input schema is the caller's schema, so the provider fills the
+ * fields, and returning the validated payload as the agent's result.
+ *
+ * We do the same, with one gap named up front: Claude Code *forces* the call,
+ * and we cannot. `toolChoice` exists in pi-ai's provider layer but is not
+ * plumbed through `AgentSession`, so an extension has no way to require a
+ * particular tool. What we have instead is three softer pressures —
+ *
+ *   1. `constrainedSampling`, so providers that support it hold the payload to
+ *      the schema at sampling time;
+ *   2. the tool's description, snippet and guideline, which say the answer must
+ *      come through this call;
+ *   3. validation here, answering a bad payload with `isError` so the model
+ *      sees what was wrong and calls again inside the same run.
+ *
+ * — and, when all three fail, one more prompt from `runAgent`. See
+ * {@link structuredRetryPrompt}.
+ *
+ * The name matches Claude Code's exactly, so a ported prompt that mentions
+ * `StructuredOutput` is still telling the truth.
+ */
+
+import { defineTool, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { CompiledSchema } from "./workflow/json-schema.js";
+
+/**
+ * Deliberately NOT added to `SUBAGENT_TOOL_NAMES`: that list becomes
+ * `EXCLUDED_TOOL_NAMES`, which is exactly the denial this tool has to avoid.
+ * Nor to `BUILTIN_TOOL_NAMES` — it is ours to inject, never a name a user may
+ * ask for in an agent's `tools:` frontmatter.
+ */
+export const STRUCTURED_OUTPUT_TOOL_NAME = "StructuredOutput";
+
+/** What the child produced, filled in as the tool is called. */
+export interface StructuredCapture {
+  /** The last payload that validated, canonicalised. Absent until one does. */
+  json?: string;
+  /** Why the most recent attempt was rejected, for the retry prompt. */
+  lastError?: string;
+  /** Whether the tool was called at all — "never tried" reads differently. */
+  called: boolean;
+}
+
+export function createStructuredCapture(): StructuredCapture {
+  return { called: false };
+}
+
+/**
+ * Build the tool for one child.
+ *
+ * `capture` is the box the caller reads afterwards. It is passed in rather than
+ * returned so `runAgent` owns its lifetime and can consult it on every exit
+ * path, including the ones where the tool was never reached.
+ */
+export function createStructuredOutputTool(
+  compiled: CompiledSchema,
+  capture: StructuredCapture,
+): ToolDefinition {
+  return defineTool({
+    name: STRUCTURED_OUTPUT_TOOL_NAME,
+    label: "Structured Output",
+    description:
+      "Report your final answer. Call this exactly once, with the complete result, and put everything the "
+      + "caller needs inside the arguments — text written outside this call is discarded. If a call is "
+      + "rejected for not matching the schema, fix the reported fields and call it again.",
+    promptSnippet: "Report your final answer as structured data",
+    promptGuidelines: [
+      "Your final answer MUST be reported by calling StructuredOutput. Prose outside that call is discarded.",
+    ],
+    // The caller's schema *is* the tool's input schema, verbatim — that is what
+    // makes the provider fill the fields. pi types this as TypeBox's `TSchema`,
+    // which v1 defines as an open interface, so a plain JSON Schema satisfies
+    // it without a cast at runtime or a conversion at author time.
+    parameters: compiled.schema as never,
+    // "prefer", not "require": a provider that cannot constrain sampling should
+    // fall through to validation-and-retry rather than fail the call outright.
+    constrainedSampling: { type: "json_schema", strict: "prefer" },
+    // Models occasionally send the whole payload as one JSON string instead of
+    // an object. Recovering that costs nothing and saves a whole retry.
+    prepareArguments: (args: unknown) => {
+      if (typeof args !== "string") return args as never;
+      try {
+        return JSON.parse(args) as never;
+      } catch {
+        return args as never;
+      }
+    },
+    execute: async (_toolCallId, params) => {
+      capture.called = true;
+      const verdict = compiled.check(params);
+      if (verdict !== true) {
+        capture.lastError = verdict;
+        // `isError` puts the reason in front of the model as a tool result, so
+        // it can correct itself inside this same run. This is where most
+        // mismatches are resolved; the prompt-level retry is the backstop.
+        return {
+          content: [{
+            type: "text",
+            text: `StructuredOutput did not match the required schema:\n${verdict}\nCall it again with a corrected value.`,
+          }],
+          isError: true,
+          details: {},
+        };
+      }
+      // Last valid call wins: a model that calls twice meant the second one.
+      capture.json = JSON.stringify(params);
+      capture.lastError = undefined;
+      return { content: [{ type: "text", text: "Recorded." }], details: {} };
+    },
+  }) as ToolDefinition;
+}
+
+/**
+ * The one extra prompt sent when a run ended with nothing captured.
+ *
+ * Distinguishes "never called it" from "called it wrongly" — the two need
+ * different corrections, and telling a model it got the shape wrong when it
+ * never answered at all sends it looking for a mistake it did not make.
+ */
+export function structuredRetryPrompt(capture: StructuredCapture): string {
+  const reason = capture.called && capture.lastError !== undefined
+    ? `Your last ${STRUCTURED_OUTPUT_TOOL_NAME} call did not match the required schema: ${capture.lastError}`
+    : `You did not call ${STRUCTURED_OUTPUT_TOOL_NAME}, so your answer was not recorded.`;
+  return `${reason}\n\nCall ${STRUCTURED_OUTPUT_TOOL_NAME} now with your complete final answer. Do not reply with prose.`;
+}