@abelxiaoxing/cadence 1.8.2 → 1.8.4

package/src/subagent-process.ts

@@ -0,0 +1,476 @@
+import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
+import path from "node:path";
+import { StringDecoder } from "node:string_decoder";
+import type { Usage } from "@earendil-works/pi-ai";
+import { loadAgentDefinitions } from "./agent-registry.ts";
+
+export const SUBAGENT_LIMITS = Object.freeze({
+  timeoutMs: 20 * 60_000,
+  maxOutputBytes: 256 * 1024,
+  terminateGraceMs: 1_000,
+  maxPromptBytes: 128 * 1024,
+});
+
+export type SubagentRole =
+  | "design-explorer"
+  | "implementation-worker"
+  | "diagnosis-worker";
+
+export interface SubagentCapabilities {
+  readonly tools: readonly string[];
+  readonly writes: boolean;
+}
+
+export const SUBAGENT_CAPABILITIES: Readonly<
+  Record<SubagentRole, SubagentCapabilities>
+> = Object.freeze({
+  "design-explorer": { tools: ["read", "grep", "find", "ls"], writes: false },
+  "implementation-worker": {
+    tools: ["read", "grep", "find", "ls", "write", "edit", "bash"],
+    writes: true,
+  },
+  "diagnosis-worker": {
+    tools: ["read", "grep", "find", "ls"],
+    writes: false,
+  },
+});
+
+export type SubagentTerminalStatus =
+  | "completed"
+  | "failed"
+  | "cancelled"
+  | "timed-out"
+  | "output-limit";
+
+export interface SubagentEvent {
+  readonly type: string;
+  readonly toolName?: string;
+  readonly text?: string;
+}
+
+export interface SubagentProcessResult {
+  readonly status: SubagentTerminalStatus;
+  readonly finalText: string;
+  readonly usage?: Usage;
+  readonly stderr: string;
+  readonly error?: string;
+  readonly events: readonly SubagentEvent[];
+  readonly outputBytes: number;
+  readonly outputTruncated: boolean;
+  readonly exitCode: number | null;
+}
+
+export interface SubagentProcessInput {
+  readonly role: SubagentRole;
+  readonly cwd: string;
+  readonly prompt: string;
+  readonly model?: { provider: string; id: string };
+  readonly signal?: AbortSignal;
+  readonly timeoutMs?: number;
+  readonly maxOutputBytes?: number;
+  readonly piExecutable?: string;
+  readonly onEvent?: (event: SubagentEvent) => void;
+}
+
+const TRUNCATION_MARKER = "…[truncated]";
+
+function decodeUtf8(value: Buffer): string {
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  const maxBoundary = Math.min(3, value.length);
+  // A bounded head may end, and a bounded tail may begin, in the middle of
+  // one UTF-8 sequence. Try only those small boundary adjustments; valid
+  // interior output is never discarded or rendered as U+FFFD.
+  for (let start = 0; start <= maxBoundary; start += 1) {
+    for (let end = value.length; end >= start; end -= 1) {
+      if (value.length - end > 3) break;
+      try {
+        return decoder.decode(value.subarray(start, end));
+      } catch {
+        // Try the next possible boundary.
+      }
+    }
+  }
+  return value.toString("utf8");
+}
+
+function utf8Prefix(value: Buffer, limit: number): string {
+  if (limit <= 0) return "";
+  let end = Math.min(value.length, limit);
+  while (end > 0 && (value[end - 1] & 0xc0) === 0x80) end -= 1;
+  if (end < Math.min(value.length, limit) && end > 0) {
+    const lead = value[end - 1];
+    const expected = lead < 0x80 ? 1 : lead < 0xe0 ? 2 : lead < 0xf0 ? 3 : 4;
+    if (expected <= Math.min(value.length, limit) - (end - 1)) {
+      end = Math.min(value.length, limit);
+    } else {
+      end -= 1;
+    }
+  }
+  return decodeUtf8(value.subarray(0, end));
+}
+
+function boundedText(value: string, limit: number): string {
+  const bytes = Buffer.from(value, "utf8");
+  if (bytes.length <= limit) return value;
+  const markerBytes = Buffer.byteLength(TRUNCATION_MARKER, "utf8");
+  if (limit <= markerBytes) return utf8Prefix(bytes, limit);
+  return `${utf8Prefix(bytes, limit - markerBytes)}${TRUNCATION_MARKER}`;
+}
+
+class BoundedBuffer {
+  #head = Buffer.alloc(0);
+  #tail = Buffer.alloc(0);
+  #bytes = 0;
+  constructor(readonly limit: number) {}
+  append(chunk: Buffer): void {
+    this.#bytes += chunk.byteLength;
+    if (this.limit <= 0) return;
+    const headLimit = Math.ceil(this.limit / 2);
+    if (this.#head.length < headLimit) {
+      const take = Math.min(headLimit - this.#head.length, chunk.length);
+      this.#head = Buffer.concat([this.#head, chunk.subarray(0, take)]);
+      chunk = chunk.subarray(take);
+    }
+    const tailLimit = this.limit - headLimit;
+    if (chunk.length > tailLimit) chunk = chunk.subarray(-tailLimit);
+    if (chunk.length > 0 && tailLimit > 0) {
+      this.#tail = Buffer.concat([this.#tail, chunk]).subarray(-tailLimit);
+    }
+  }
+  get bytes(): number {
+    return this.#bytes;
+  }
+  get truncated(): boolean {
+    return this.#bytes > this.limit;
+  }
+  text(): string {
+    return `${decodeUtf8(this.#head)}${decodeUtf8(this.#tail)}`;
+  }
+}
+
+function textFromMessage(message: unknown): string {
+  if (!message || typeof message !== "object") return "";
+  const content = (message as { content?: unknown }).content;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((part) => {
+      if (typeof part === "string") return part;
+      if (!part || typeof part !== "object") return "";
+      const value = part as {
+        type?: unknown;
+        text?: unknown;
+        thinking?: unknown;
+      };
+      if (value.type === "text" && typeof value.text === "string")
+        return value.text;
+      if (value.type === "thinking" && typeof value.thinking === "string")
+        return value.thinking;
+      return "";
+    })
+    .join("");
+}
+
+function usageFromMessage(message: unknown): Usage | undefined {
+  if (!message || typeof message !== "object") return undefined;
+  const usage = (message as { usage?: unknown }).usage;
+  return usage && typeof usage === "object" ? (usage as Usage) : undefined;
+}
+
+function executableFromEnvironment(env: NodeJS.ProcessEnv): string {
+  const explicit = env.CADENCE_PI_EXECUTABLE ?? env.PI_EXECUTABLE;
+  if (explicit) return explicit;
+  const current = process.argv[1];
+  if (
+    current &&
+    (path.basename(current) === "pi" ||
+      current
+        .replaceAll("\\", "/")
+        .endsWith("/pi-coding-agent/dist/bundle/cli.js") ||
+      current.endsWith("\\\\pi-coding-agent\\dist\\bundle\\cli.js"))
+  ) {
+    return current;
+  }
+  return "pi";
+}
+
+function modelArgument(model: SubagentProcessInput["model"]): string[] {
+  if (!model?.provider || !model.id) return [];
+  return ["--model", `${model.provider}/${model.id}`];
+}
+
+/** Parse the last JSON object in a fenced result block without trusting it as authority. */
+export function parseSubagentJson<T = unknown>(text: string): T | undefined {
+  const matches = [...text.matchAll(/```(?:json)?\s*([\s\S]*?)```/giu)];
+  for (let index = matches.length - 1; index >= 0; index -= 1) {
+    try {
+      const value: unknown = JSON.parse(matches[index]?.[1]?.trim() ?? "");
+      return value as T;
+    } catch {
+      // A malformed final block is a result failure, not an identity.
+    }
+  }
+  return undefined;
+}
+
+export function buildSubagentPrompt(input: {
+  role: SubagentRole;
+  objective: string;
+  context?: string;
+  agentContent?: string;
+  finalConvention?: string;
+}): string {
+  const definition =
+    input.agentContent ??
+    loadAgentDefinitions().find((agent) => agent.role === input.role)?.content;
+  if (!definition) throw new Error("subagent-role-unavailable");
+  return [
+    definition,
+    "You are running as an isolated one-shot Pi child. Do not invoke workflow control tools, submit tools, or another agent.",
+    `Your allowed tools are: ${SUBAGENT_CAPABILITIES[input.role].tools.join(", ")}.`,
+    SUBAGENT_CAPABILITIES[input.role].writes
+      ? "You may edit only the disposable workspace supplied as your current working directory. The parent will inspect all changes; never commit or claim verification success."
+      : "You are read-only and must not modify files or run commands.",
+    input.objective,
+    input.context ?? "",
+    input.finalConvention ??
+      "Finish with a concise summary. If structured evidence is required, put exactly one JSON object in a ```json code fence as the final answer.",
+  ]
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+function terminateProcess(
+  child: ChildProcessWithoutNullStreams,
+  graceMs: number,
+): Promise<void> {
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = () => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      resolve();
+    };
+    const timer = setTimeout(() => {
+      if (process.platform !== "win32" && child.pid) {
+        try {
+          process.kill(-child.pid, "SIGKILL");
+        } catch {
+          // The process group may already have exited.
+        }
+      } else if (!child.killed) {
+        child.kill("SIGKILL");
+      }
+      finish();
+    }, graceMs);
+    timer.unref?.();
+    child.once("close", finish);
+    if (process.platform !== "win32" && child.pid) {
+      try {
+        process.kill(-child.pid, "SIGTERM");
+      } catch {
+        child.kill("SIGTERM");
+      }
+    } else {
+      child.kill("SIGTERM");
+    }
+  });
+}
+
+/** Run a fresh Pi CLI. No cwd or tool allowlist is treated as an OS sandbox. */
+export async function runSubagentProcess(
+  input: SubagentProcessInput,
+): Promise<SubagentProcessResult> {
+  const timeoutMs = input.timeoutMs ?? SUBAGENT_LIMITS.timeoutMs;
+  const maxOutputBytes = input.maxOutputBytes ?? SUBAGENT_LIMITS.maxOutputBytes;
+  const promptBytes = Buffer.byteLength(input.prompt, "utf8");
+  if (promptBytes > SUBAGENT_LIMITS.maxPromptBytes) {
+    return {
+      status: "output-limit",
+      finalText: "",
+      stderr: "",
+      events: [],
+      outputBytes: promptBytes,
+      outputTruncated: true,
+      exitCode: null,
+      error: "subagent-prompt-limit",
+    };
+  }
+  if (input.signal?.aborted) {
+    return {
+      status: "cancelled",
+      finalText: "",
+      stderr: "",
+      events: [],
+      outputBytes: 0,
+      outputTruncated: false,
+      exitCode: null,
+      error: "cancelled",
+    };
+  }
+  const tools = SUBAGENT_CAPABILITIES[input.role].tools.join(",");
+  const args = [
+    "--mode",
+    "json",
+    "-p",
+    "--no-session",
+    "--no-extensions",
+    "--no-context-files",
+    "--no-approve",
+    "--tools",
+    tools,
+    ...modelArgument(input.model),
+  ];
+  const env = { ...process.env, CADENCE_SUBAGENT_CHILD: "1" };
+  const output = new BoundedBuffer(maxOutputBytes);
+  const stderr = new BoundedBuffer(Math.min(maxOutputBytes, 64 * 1024));
+  const events: SubagentEvent[] = [];
+  let child: ChildProcessWithoutNullStreams;
+  try {
+    child = spawn(
+      input.piExecutable ?? executableFromEnvironment(process.env),
+      args,
+      {
+        cwd: input.cwd,
+        env,
+        shell: false,
+        stdio: ["pipe", "pipe", "pipe"],
+        ...(process.platform === "win32" ? {} : { detached: true }),
+      },
+    );
+  } catch {
+    return {
+      status: "failed",
+      finalText: "",
+      stderr: "",
+      events,
+      outputBytes: 0,
+      outputTruncated: false,
+      exitCode: null,
+      error: "subagent-spawn-failed",
+    };
+  }
+  const decoder = new StringDecoder("utf8");
+  let finalText = "";
+  let usage: Usage | undefined;
+  let parseBuffer = "";
+  let terminal: SubagentTerminalStatus | undefined;
+  let terminalError: string | undefined;
+  const emit = (event: SubagentEvent) => {
+    events.push(event);
+    try {
+      input.onEvent?.(event);
+    } catch {
+      // Progress observers are presentation-only and cannot fail execution.
+    }
+  };
+  const processLine = (rawLine: string): void => {
+    const line = rawLine.replace(/\r$/u, "");
+    if (!line || terminal) return;
+    try {
+      const event = JSON.parse(line) as Record<string, unknown>;
+      const type = typeof event.type === "string" ? event.type : "unknown";
+      const message = event.message;
+      const text =
+        type === "message_end" ? textFromMessage(message) : undefined;
+      if (
+        text &&
+        message &&
+        typeof message === "object" &&
+        (message as { role?: unknown }).role === "assistant"
+      ) {
+        finalText = boundedText(text, maxOutputBytes);
+        usage = usageFromMessage(message) ?? usage;
+      }
+      if (
+        type === "message_update" &&
+        event.usage &&
+        typeof event.usage === "object"
+      )
+        usage = event.usage as Usage;
+      emit({
+        type,
+        ...(typeof event.toolName === "string"
+          ? { toolName: event.toolName }
+          : {}),
+        ...(text ? { text: boundedText(text, 4096) } : {}),
+      });
+    } catch {
+      emit({ type: "malformed-event" });
+      terminal = "failed";
+      terminalError = "subagent-jsonl-malformed";
+      void terminateProcess(child, SUBAGENT_LIMITS.terminateGraceMs);
+    }
+  };
+  const consumeDecoded = (decoded: string): void => {
+    if (!decoded || terminal) return;
+    if (
+      Buffer.byteLength(parseBuffer, "utf8") +
+        Buffer.byteLength(decoded, "utf8") >
+      maxOutputBytes
+    ) {
+      parseBuffer = "";
+      terminal = "output-limit";
+      void terminateProcess(child, SUBAGENT_LIMITS.terminateGraceMs);
+      return;
+    }
+    parseBuffer += decoded;
+    for (;;) {
+      const newline = parseBuffer.indexOf("\n");
+      if (newline < 0) break;
+      const line = parseBuffer.slice(0, newline);
+      parseBuffer = parseBuffer.slice(newline + 1);
+      processLine(line);
+      if (terminal) return;
+    }
+  };
+  const consume = (chunk: Buffer) => {
+    output.append(chunk);
+    consumeDecoded(decoder.write(chunk));
+    if (output.truncated && !terminal) {
+      terminal = "output-limit";
+      void terminateProcess(child, SUBAGENT_LIMITS.terminateGraceMs);
+    }
+  };
+  child.stdout.on("data", consume);
+  child.stderr.on("data", (chunk: Buffer) => stderr.append(chunk));
+  const termination = new Promise<number | null>((resolve) => {
+    // A spawn error is followed by close; keep the error listener only to
+    // prevent an uncaught event while waiting for the pipes to settle.
+    child.once("error", () => undefined);
+    child.once("close", (code) => resolve(code));
+  });
+  const cancel = (status: "cancelled" | "timed-out") => {
+    if (!terminal) terminal = status;
+    void terminateProcess(child, SUBAGENT_LIMITS.terminateGraceMs);
+  };
+  const abortHandler = () => cancel("cancelled");
+  input.signal?.addEventListener("abort", abortHandler, { once: true });
+  const timer = setTimeout(() => cancel("timed-out"), timeoutMs);
+  timer.unref?.();
+  child.stdin.end(input.prompt);
+  const exitCode = await termination;
+  if (timer) clearTimeout(timer);
+  input.signal?.removeEventListener("abort", abortHandler);
+  const trailing = decoder.end();
+  consumeDecoded(trailing);
+  if (parseBuffer && !terminal) {
+    processLine(parseBuffer);
+    parseBuffer = "";
+  }
+  if (!terminal) terminal = exitCode === 0 ? "completed" : "failed";
+  return {
+    status: terminal,
+    finalText,
+    usage,
+    stderr: boundedText(stderr.text(), 64 * 1024),
+    ...(terminal === "failed"
+      ? { error: terminalError ?? `subagent-exit-${exitCode ?? "unknown"}` }
+      : {}),
+    events,
+    outputBytes: output.bytes,
+    outputTruncated: output.truncated,
+    exitCode,
+  };
+}

package/src/transport-budget.ts

@@ -28,9 +28,7 @@ export function isTransportTimeoutCode(
 export function transportFailureError(code: string): Error {
   return isTransportTimeoutCode(code)
     ? new TransportTimeout(code)
-    : new Error(
-        code === "child-provider-rate-limited" ? code : "transport-failure",
-      );
+    : new Error("transport-failure");
 }
 
 /** Snapshot at the start of each request; Workers cannot override these values. */

package/src/workflow-policy.ts

@@ -2,10 +2,15 @@ import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import type { WorkflowActivityUpdate } from "./activity-contracts.ts";
+import {
+  type CandidateContextBoundary,
+  type CandidateContextRef,
+  classifyCandidateContextRequest,
+  normalizeCandidateContextRefs,
+} from "./candidate-context.ts";
 import { compareCanonicalStrings } from "./canonical.ts";
 import {
   type ApprovalBoundaryCode,
-  CHILD_TRANSPORT_CODES,
   isValidRelativePath,
   type StructuredVerificationContract,
   verificationBoundInputPaths,
@@ -16,16 +21,9 @@ import type {
   ImplementPlan,
   PlanTaskDraft,
 } from "./delivery-compiler.ts";
-import type { RoutePolicy } from "./route-policy.ts";
 import { canonicalJson } from "./run-state.ts";
 import type { OperationLease } from "./run-store.ts";
 import type { ResolvedStateRoot } from "./state-root.ts";
-import {
-  type CandidateContextBoundary,
-  type CandidateContextRef,
-  classifyCandidateContextRequest,
-  normalizeCandidateContextRefs,
-} from "./submit-tool.ts";
 import type { WorkspaceEntry } from "./workspace-store.ts";
 
 export const SHA256 = /^[a-f0-9]{64}$/u;
@@ -242,13 +240,7 @@ export type ParentRecoveryStrategy =
   | "restore-runtime-environment"
   | "restore-verification-capability";
 
-const ROUTE_RECOVERY_CODES = new Set([
-  "endpoint-unavailable",
-  "route-capability-insufficient",
-  "route-not-declared",
-  "route-rebind-required",
-  ...CHILD_TRANSPORT_CODES,
-]);
+const ROUTE_RECOVERY_CODES = new Set(["child-timeout", "transport-failure"]);
 
 const ENVIRONMENT_RECOVERY_CODES = new Set([
   "bubblewrap-launch-failed",
@@ -277,7 +269,8 @@ const ENVIRONMENT_RECOVERY_CODES = new Set([
 ]);
 
 const CORRECTION_RECOVERY_CODES = new Set([
-  ...CHILD_TRANSPORT_CODES,
+  "child-timeout",
+  "transport-failure",
   "artifact-attempts-exhausted",
   "baseline-deletion-drift",
   "baseline-directory-drift",
@@ -655,8 +648,6 @@ export interface WorkflowWorker {
     baselineRevisionId: string;
     currentWorkspaceRevisionId: string;
   };
-  updateRoutePolicy?(policy: RoutePolicy): void;
-  routePolicyStatus?(): Record<string, unknown>;
 }
 
 export interface WorkflowDelivery {

package/src/workflow-state-machine.ts

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import path from "node:path";
 import { DatabaseSync } from "node:sqlite";
 import type { WorkflowActivityUpdate } from "./activity-contracts.ts";
+import { permitsContextRead } from "./candidate-context.ts";
 import {
   assertPlanWithinChangeContract,
   normalizeChangeContract,
@@ -21,7 +22,6 @@ import {
 } from "./delivery-compiler.ts";
 import { compareDeliveryRevision } from "./delivery-revision.ts";
 import { snapshotFiles } from "./file-snapshot.ts";
-import type { RoutePolicy } from "./route-policy.ts";
 import {
   canonicalJson,
   type RunProjection,
@@ -40,7 +40,6 @@ import {
   RECOVERY_SCHEMA,
   REJECTED_DELIVERY_SCHEMA,
 } from "./storage-schema.ts";
-import { permitsContextRead } from "./submit-tool.ts";
 import {
   type ActiveOperation,
   assertDelivery,
@@ -206,19 +205,6 @@ export class WorkflowEngine {
     return new WorkflowEngine(options);
   }
 
-  updateRoutePolicy(policy: RoutePolicy): void {
-    this.#assertOpen();
-    if (!this.#worker.updateRoutePolicy) {
-      throw new Error("route-policy-update-unavailable");
-    }
-    this.#worker.updateRoutePolicy(policy);
-  }
-
-  routePolicyStatus(): Record<string, unknown> | undefined {
-    this.#assertOpen();
-    return this.#worker.routePolicyStatus?.();
-  }
-
   #assertOpen(): void {
     if (this.#closed) throw new Error("workflow-engine-closed");
   }

package/config/routes.example.json

@@ -1,39 +0,0 @@
-{
-  "routes": {
-    "parent": {
-      "kind": "inherited",
-      "capabilities": {
-        "roles": [
-          "design-explorer",
-          "implementation-worker",
-          "diagnosis-worker"
-        ],
-        "dialects": [
-          "openai-completions",
-          "openai-responses",
-          "anthropic-messages"
-        ],
-        "contextWindow": 256000,
-        "maxTokens": 128000
-      }
-    },
-    "custom-worker": {
-      "kind": "custom",
-      "url": "https://example.invalid/v1",
-      "model": "example-model",
-      "dialect": "openai-responses",
-      "apiKeyEnv": "CADENCE_CUSTOM_WORKER_API_KEY",
-      "capabilities": {
-        "roles": ["implementation-worker"],
-        "dialects": ["openai-responses"],
-        "contextWindow": 256000,
-        "maxTokens": 128000
-      }
-    }
-  },
-  "roles": {
-    "design-explorer": ["parent"],
-    "implementation-worker": ["custom-worker", "parent"],
-    "diagnosis-worker": ["parent"]
-  }
-}

package/src/child-budget.ts

@@ -1,58 +0,0 @@
-import type { ChildFailure } from "./contracts.ts";
-
-/** Conservative admission estimate, not a tokenizer or a claim about provider billing. */
-export function childContextBudget(model: {
-  contextWindow?: number;
-  maxTokens?: number;
-}): number {
-  if (
-    !Number.isFinite(model.contextWindow) ||
-    !model.contextWindow ||
-    model.contextWindow < 1
-  )
-    return 4 * 1024 * 1024;
-  const reserve = Math.min(
-    model.maxTokens ?? 8192,
-    Math.floor(model.contextWindow / 2),
-  );
-  return Math.min(
-    4 * 1024 * 1024,
-    Math.max(1024, Math.floor((model.contextWindow - reserve - 1024) * 2)),
-  );
-}
-
-export function classifyProviderFailure(error: unknown): ChildFailure {
-  const text =
-    typeof error === "string"
-      ? error
-      : error instanceof Error
-        ? error.message
-        : "";
-  if (
-    /context.{0,30}(?:length|window|limit|exceed)|too many tokens|input.{0,20}too long/iu.test(
-      text,
-    )
-  )
-    return { kind: "execution-limit", code: "child-context-limit" };
-  if (
-    /\b(?:401|403)\b|invalid.{0,10}api.?key|unauthorized|authentication/iu.test(
-      text,
-    )
-  )
-    return {
-      kind: "environment",
-      code: "child-provider-authentication-failed",
-      stage: "child-provider-stream",
-    };
-  if (/\b429\b|rate.?limit|too many requests/iu.test(text))
-    return {
-      kind: "transport",
-      code: "child-provider-rate-limited",
-      stage: "child-provider-stream",
-    };
-  return {
-    kind: "transport",
-    code: "child-provider-stream-error",
-    stage: "child-provider-stream",
-  };
-}