@tangle-network/agent-runtime 0.17.2 → 0.19.0

package/dist/profiles.d.ts

@@ -0,0 +1,133 @@
+import { AgentProfile } from '@tangle-network/sandbox';
+import { O as OutputAdapter, V as Validator, A as AgentRunSpec, a as Driver } from './types-EKcAHfxI.js';
+import './runtime-run-4pbY3Jq5.js';
+import './types-DlyPgeI0.js';
+import '@tangle-network/agent-eval';
+
+/**
+ * @experimental
+ *
+ * `coderProfile` — opinionated preset for code-modification tasks.
+ *
+ * The agent is told to:
+ *   - work on a fresh branch inside the sandbox workspace
+ *   - keep the patch minimal (under `maxDiffLines`)
+ *   - avoid `forbiddenPaths`
+ *   - run `testCmd` and `typecheckCmd`
+ *   - emit a final JSON result the output adapter parses
+ *
+ * The profile is stateless and agent-agnostic — `harness` selects the
+ * sandbox-SDK backend (`claude-code`, `codex`, `opencode/*`). For
+ * heterogeneous fanout, use `multiHarnessCoderFanout`.
+ */
+
+/** @experimental */
+interface CoderTask {
+    /** What the agent must accomplish. Free-form prose. */
+    goal: string;
+    /** Absolute path inside the sandbox where the repo lives. */
+    repoRoot: string;
+    /** Default `main`. The branch the agent diffs against. */
+    baseBranch?: string;
+    /** Default `pnpm test --run`. */
+    testCmd?: string;
+    /** Default `pnpm typecheck`. */
+    typecheckCmd?: string;
+    /** Files the agent may inspect for context. Surfaced verbatim in the prompt. */
+    contextFiles?: string[];
+    /**
+     * Paths the agent must not touch. Validator hard-fails on any match.
+     * Use glob-free literal path prefixes for unambiguous enforcement.
+     */
+    forbiddenPaths?: string[];
+    /** Default 400. Hard cap; validator hard-fails when exceeded. */
+    maxDiffLines?: number;
+}
+/** @experimental */
+interface CoderOutput {
+    /** Branch the agent wrote the patch on. */
+    branch: string;
+    /** Unified diff (`git diff <base>..HEAD`). */
+    patch: string;
+    testResult: {
+        passed: boolean;
+        output: string;
+    };
+    typecheckResult: {
+        passed: boolean;
+        output: string;
+    };
+    diffStats: {
+        filesChanged: number;
+        insertions: number;
+        deletions: number;
+    };
+    /** Optional reviewer commentary surfaced by the agent. */
+    reviewerNotes?: string;
+}
+/** @experimental */
+interface CoderProfileOptions {
+    /** Sandbox-SDK backend.type. Default `'claude-code'`. */
+    harness?: string;
+    /** Default model id passed in `AgentProfile.model.default`. */
+    model?: string;
+    /** Custom system prompt replacement. Default = built-in coder preset. */
+    systemPrompt?: string;
+    /** Stable name for `AgentRunSpec.name`. Default = `coder-${harness}`. */
+    name?: string;
+}
+/**
+ * Build a coder preset.
+ *
+ * `validator` enforces test + typecheck + a 400-line default diff cap. For
+ * per-task `forbiddenPaths` / `maxDiffLines` enforcement, pass `task` here
+ * — the returned validator closes over its constraints. Without a task
+ * the validator falls back to the default cap and skips path enforcement.
+ *
+ * @experimental
+ */
+declare function coderProfile(options?: CoderProfileOptions & {
+    task?: CoderTask;
+}): {
+    profile: AgentProfile;
+    taskToPrompt: (task: CoderTask) => string;
+    output: OutputAdapter<CoderOutput>;
+    validator: Validator<CoderOutput>;
+    agentRunSpec: AgentRunSpec<CoderTask>;
+};
+/** @experimental */
+interface MultiHarnessCoderFanoutOptions {
+    /**
+     * Sandbox-SDK backend.type identifiers, one per parallel agent. Default:
+     * `['claude-code', 'codex', 'opencode/zai-coding-plan/glm-5.1']`.
+     */
+    harnesses?: string[];
+    /** Optional per-harness model override. Indexed parallel to `harnesses`. */
+    models?: (string | undefined)[];
+}
+/** @experimental */
+declare function multiHarnessCoderFanout(options?: MultiHarnessCoderFanoutOptions): {
+    agentRuns: AgentRunSpec<CoderTask>[];
+    output: OutputAdapter<CoderOutput>;
+    validator: Validator<CoderOutput>;
+    driver: Driver<CoderTask, CoderOutput, 'pick-winner' | 'fail'>;
+};
+/**
+ * Build a validator that closes over a specific `CoderTask`'s constraints.
+ *
+ * Checks in order:
+ *   1. Forbidden-path: any `+++` / `---` header in the patch matching a
+ *      path prefix in `task.forbiddenPaths` fails hard.
+ *   2. Diff size: line count above `task.maxDiffLines` (default 400) fails
+ *      hard; below cap, the score shrinks linearly.
+ *   3. Tests: `output.testResult.passed` must be `true`.
+ *   4. Typecheck: `output.typecheckResult.passed` must be `true`.
+ *
+ * Aggregate score: `0.5 * tests + 0.3 * typecheck + 0.2 * (1 - diffLines/maxDiff)`.
+ * `valid` is the conjunction of all four.
+ *
+ * @experimental
+ */
+declare function createCoderValidator(task: CoderTask): Validator<CoderOutput>;
+
+export { type CoderOutput, type CoderProfileOptions, type CoderTask, type MultiHarnessCoderFanoutOptions, coderProfile, createCoderValidator, multiHarnessCoderFanout };

package/dist/profiles.js

@@ -0,0 +1,249 @@
+import {
+  createFanoutVoteDriver
+} from "./chunk-XLWPTPRP.js";
+import "./chunk-RZAOYKCO.js";
+import "./chunk-DGUM43GV.js";
+
+// src/profiles/coder.ts
+var DEFAULT_MAX_DIFF_LINES = 400;
+function coderProfile(options = {}) {
+  const harness = options.harness ?? "claude-code";
+  const name = options.name ?? `coder-${harness}`;
+  const systemPrompt = options.systemPrompt ?? DEFAULT_CODER_SYSTEM_PROMPT;
+  const profile = {
+    name,
+    description: "Code-modification agent. Minimal-diff worktree-based coder.",
+    prompt: { systemPrompt },
+    model: options.model ? { default: options.model } : void 0,
+    tools: { git: true, fs: true, shell: true, test_runner: true },
+    metadata: { backendType: harness, role: "coder" }
+  };
+  const output = { parse: parseCoderEvents };
+  const validator = options.task ? createCoderValidator(options.task) : createCoderValidator({
+    goal: "",
+    repoRoot: "",
+    forbiddenPaths: [],
+    maxDiffLines: DEFAULT_MAX_DIFF_LINES
+  });
+  const agentRunSpec = {
+    name,
+    profile,
+    taskToPrompt: formatCoderPrompt
+  };
+  return { profile, taskToPrompt: formatCoderPrompt, output, validator, agentRunSpec };
+}
+function multiHarnessCoderFanout(options = {}) {
+  const harnesses = options.harnesses && options.harnesses.length > 0 ? options.harnesses : ["claude-code", "codex", "opencode/zai-coding-plan/glm-5.1"];
+  const models = options.models ?? [];
+  const agentRuns = harnesses.map((harness, i) => {
+    const { agentRunSpec } = coderProfile({ harness, model: models[i] });
+    return agentRunSpec;
+  });
+  const { output, validator } = coderProfile();
+  const driver = createFanoutVoteDriver({ n: harnesses.length });
+  return { agentRuns, output, validator, driver };
+}
+var DEFAULT_CODER_SYSTEM_PROMPT = [
+  "You are a coder agent operating inside an isolated sandbox workspace.",
+  "Your job is to deliver a minimal, correct patch for the user-supplied goal.",
+  "",
+  "Hard rules:",
+  "  1. Work on a fresh branch off the supplied base. Do not mutate the base branch.",
+  "  2. Never touch a forbidden path. The user will list them explicitly.",
+  "  3. Keep the diff under the max-diff cap. Prefer the smallest change that ships.",
+  "  4. Run the supplied test and typecheck commands before declaring done.",
+  "  5. If either command fails, fix the cause \u2014 do not weaken the test or hide the error.",
+  "",
+  "When you finish, emit a single final structured message of the shape:",
+  "  ```json",
+  '  { "branch": "<branch-name>",',
+  '    "patch": "<unified-diff>",',
+  '    "testResult": { "passed": <bool>, "output": "<stdout/stderr>" },',
+  '    "typecheckResult": { "passed": <bool>, "output": "<stdout/stderr>" },',
+  '    "diffStats": { "filesChanged": <int>, "insertions": <int>, "deletions": <int> },',
+  '    "reviewerNotes": "<optional commentary>" }',
+  "  ```"
+].join("\n");
+function formatCoderPrompt(task) {
+  const base = task.baseBranch ?? "main";
+  const testCmd = task.testCmd ?? "pnpm test --run";
+  const typecheckCmd = task.typecheckCmd ?? "pnpm typecheck";
+  const maxDiff = task.maxDiffLines ?? DEFAULT_MAX_DIFF_LINES;
+  const forbidden = task.forbiddenPaths?.length ? task.forbiddenPaths.join(", ") : "(none)";
+  const context = task.contextFiles?.length ? task.contextFiles.map((f) => `  - ${f}`).join("\n") : "  (none)";
+  return [
+    `Goal: ${task.goal}`,
+    `Repo: ${task.repoRoot}`,
+    `Base branch: ${base}`,
+    `Run tests with: ${testCmd}`,
+    `Run typecheck with: ${typecheckCmd}`,
+    `Forbidden paths: ${forbidden}`,
+    `Max diff lines: ${maxDiff}`,
+    "Context files:",
+    context,
+    "",
+    "Produce a minimal patch on a fresh branch. Run tests and typecheck before",
+    "returning. Emit the final JSON result block exactly as instructed."
+  ].join("\n");
+}
+function parseCoderEvents(events) {
+  for (let i = events.length - 1; i >= 0; i -= 1) {
+    const event = events[i];
+    if (!event) continue;
+    const type = String(event.type ?? "");
+    const data = isRecord(event.data) ? event.data : {};
+    if (type === "result" || type === "final" || type === "coder.result") {
+      const direct = coerceCoderOutput(data.result ?? data.output ?? data);
+      if (direct) return direct;
+    }
+  }
+  for (let i = events.length - 1; i >= 0; i -= 1) {
+    const event = events[i];
+    if (!event) continue;
+    const data = isRecord(event.data) ? event.data : {};
+    const text = pickString(data.text) ?? pickString(data.delta);
+    if (!text) continue;
+    const fenced = extractFencedJson(text);
+    if (!fenced) continue;
+    const coerced = coerceCoderOutput(fenced);
+    if (coerced) return coerced;
+  }
+  return {
+    branch: "",
+    patch: "",
+    testResult: { passed: false, output: "" },
+    typecheckResult: { passed: false, output: "" },
+    diffStats: { filesChanged: 0, insertions: 0, deletions: 0 }
+  };
+}
+function createCoderValidator(task) {
+  const maxDiff = task.maxDiffLines ?? DEFAULT_MAX_DIFF_LINES;
+  const forbidden = task.forbiddenPaths ?? [];
+  return {
+    async validate(output) {
+      const scores = {};
+      const notes = [];
+      let pass = true;
+      const touched = touchedPathsFromPatch(output.patch);
+      const touchedForbidden = forbidden.filter((path) => {
+        const prefix = path.endsWith("/") ? path : `${path}/`;
+        const exact = prefix.slice(0, -1);
+        return touched.some((p) => p === exact || p.startsWith(prefix));
+      });
+      if (touchedForbidden.length > 0) {
+        pass = false;
+        scores.forbiddenPath = 0;
+        notes.push(`touched forbidden paths: ${touchedForbidden.join(", ")}`);
+      } else {
+        scores.forbiddenPath = 1;
+      }
+      const diffLines = countDiffLines(output.patch);
+      if (diffLines > maxDiff) {
+        pass = false;
+        scores.diffSize = 0;
+        notes.push(`diff ${diffLines} lines exceeds cap ${maxDiff}`);
+      } else {
+        scores.diffSize = maxDiff === 0 ? 0 : Math.max(0, 1 - diffLines / maxDiff);
+      }
+      scores.tests = output.testResult.passed ? 1 : 0;
+      scores.typecheck = output.typecheckResult.passed ? 1 : 0;
+      if (!output.testResult.passed) {
+        pass = false;
+        notes.push("tests failed");
+      }
+      if (!output.typecheckResult.passed) {
+        pass = false;
+        notes.push("typecheck failed");
+      }
+      const score = 0.5 * scores.tests + 0.3 * scores.typecheck + 0.2 * scores.diffSize;
+      const verdict = {
+        valid: pass,
+        score: Number.isFinite(score) ? score : 0,
+        scores
+      };
+      if (notes.length > 0) verdict.notes = notes.join("; ");
+      return verdict;
+    }
+  };
+}
+function touchedPathsFromPatch(patch) {
+  const out = /* @__PURE__ */ new Set();
+  for (const line of patch.split(/\r?\n/)) {
+    if (line.startsWith("+++ ") || line.startsWith("--- ")) {
+      const rest = line.slice(4).trim();
+      if (rest === "/dev/null") continue;
+      const stripped = rest.startsWith("a/") || rest.startsWith("b/") ? rest.slice(2) : rest;
+      out.add(stripped);
+    }
+  }
+  return [...out];
+}
+function countDiffLines(patch) {
+  let count = 0;
+  for (const line of patch.split(/\r?\n/)) {
+    if ((line.startsWith("+") || line.startsWith("-")) && !line.startsWith("+++") && !line.startsWith("---")) {
+      count += 1;
+    }
+  }
+  return count;
+}
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function pickString(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function extractFencedJson(text) {
+  const match = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  if (!match) return void 0;
+  const body = (match[1] ?? "").trim();
+  if (!body) return void 0;
+  try {
+    return JSON.parse(body);
+  } catch {
+    return void 0;
+  }
+}
+function coerceCoderOutput(value) {
+  if (!isRecord(value)) return void 0;
+  const branch = pickString(value.branch);
+  const patch = pickString(value.patch) ?? "";
+  if (branch === void 0) return void 0;
+  const testResult = coerceCmdResult(value.testResult);
+  const typecheckResult = coerceCmdResult(value.typecheckResult);
+  const diffStats = coerceDiffStats(value.diffStats);
+  return {
+    branch,
+    patch,
+    testResult,
+    typecheckResult,
+    diffStats,
+    reviewerNotes: pickString(value.reviewerNotes)
+  };
+}
+function coerceCmdResult(value) {
+  if (!isRecord(value)) return { passed: false, output: "" };
+  return {
+    passed: value.passed === true,
+    output: pickString(value.output) ?? ""
+  };
+}
+function coerceDiffStats(value) {
+  if (!isRecord(value)) return { filesChanged: 0, insertions: 0, deletions: 0 };
+  return {
+    filesChanged: toFiniteInt(value.filesChanged),
+    insertions: toFiniteInt(value.insertions),
+    deletions: toFiniteInt(value.deletions)
+  };
+}
+function toFiniteInt(value) {
+  if (typeof value !== "number") return 0;
+  if (!Number.isFinite(value)) return 0;
+  return Math.max(0, Math.trunc(value));
+}
+export {
+  coderProfile,
+  createCoderValidator,
+  multiHarnessCoderFanout
+};
+//# sourceMappingURL=profiles.js.map

package/dist/profiles.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/profiles/coder.ts"],"sourcesContent":["/**\n * @experimental\n *\n * `coderProfile` — opinionated preset for code-modification tasks.\n *\n * The agent is told to:\n *   - work on a fresh branch inside the sandbox workspace\n *   - keep the patch minimal (under `maxDiffLines`)\n *   - avoid `forbiddenPaths`\n *   - run `testCmd` and `typecheckCmd`\n *   - emit a final JSON result the output adapter parses\n *\n * The profile is stateless and agent-agnostic — `harness` selects the\n * sandbox-SDK backend (`claude-code`, `codex`, `opencode/*`). For\n * heterogeneous fanout, use `multiHarnessCoderFanout`.\n */\n\nimport type { AgentProfile, SandboxEvent } from '@tangle-network/sandbox'\nimport { createFanoutVoteDriver } from '../loops/drivers/fanout-vote'\nimport type { AgentRunSpec, DefaultVerdict, Driver, OutputAdapter, Validator } from '../loops/types'\n\nconst DEFAULT_MAX_DIFF_LINES = 400\n\n/** @experimental */\nexport interface CoderTask {\n  /** What the agent must accomplish. Free-form prose. */\n  goal: string\n  /** Absolute path inside the sandbox where the repo lives. */\n  repoRoot: string\n  /** Default `main`. The branch the agent diffs against. */\n  baseBranch?: string\n  /** Default `pnpm test --run`. */\n  testCmd?: string\n  /** Default `pnpm typecheck`. */\n  typecheckCmd?: string\n  /** Files the agent may inspect for context. Surfaced verbatim in the prompt. */\n  contextFiles?: string[]\n  /**\n   * Paths the agent must not touch. Validator hard-fails on any match.\n   * Use glob-free literal path prefixes for unambiguous enforcement.\n   */\n  forbiddenPaths?: string[]\n  /** Default 400. Hard cap; validator hard-fails when exceeded. */\n  maxDiffLines?: number\n}\n\n/** @experimental */\nexport interface CoderOutput {\n  /** Branch the agent wrote the patch on. */\n  branch: string\n  /** Unified diff (`git diff <base>..HEAD`). */\n  patch: string\n  testResult: { passed: boolean; output: string }\n  typecheckResult: { passed: boolean; output: string }\n  diffStats: { filesChanged: number; insertions: number; deletions: number }\n  /** Optional reviewer commentary surfaced by the agent. */\n  reviewerNotes?: string\n}\n\n/** @experimental */\nexport interface CoderProfileOptions {\n  /** Sandbox-SDK backend.type. Default `'claude-code'`. */\n  harness?: string\n  /** Default model id passed in `AgentProfile.model.default`. */\n  model?: string\n  /** Custom system prompt replacement. Default = built-in coder preset. */\n  systemPrompt?: string\n  /** Stable name for `AgentRunSpec.name`. Default = `coder-${harness}`. */\n  name?: string\n}\n\n/**\n * Build a coder preset.\n *\n * `validator` enforces test + typecheck + a 400-line default diff cap. For\n * per-task `forbiddenPaths` / `maxDiffLines` enforcement, pass `task` here\n * — the returned validator closes over its constraints. Without a task\n * the validator falls back to the default cap and skips path enforcement.\n *\n * @experimental\n */\nexport function coderProfile(options: CoderProfileOptions & { task?: CoderTask } = {}): {\n  profile: AgentProfile\n  taskToPrompt: (task: CoderTask) => string\n  output: OutputAdapter<CoderOutput>\n  validator: Validator<CoderOutput>\n  agentRunSpec: AgentRunSpec<CoderTask>\n} {\n  const harness = options.harness ?? 'claude-code'\n  const name = options.name ?? `coder-${harness}`\n  const systemPrompt = options.systemPrompt ?? DEFAULT_CODER_SYSTEM_PROMPT\n  const profile: AgentProfile = {\n    name,\n    description: 'Code-modification agent. Minimal-diff worktree-based coder.',\n    prompt: { systemPrompt },\n    model: options.model ? { default: options.model } : undefined,\n    tools: { git: true, fs: true, shell: true, test_runner: true },\n    metadata: { backendType: harness, role: 'coder' },\n  }\n  const output: OutputAdapter<CoderOutput> = { parse: parseCoderEvents }\n  const validator: Validator<CoderOutput> = options.task\n    ? createCoderValidator(options.task)\n    : createCoderValidator({\n        goal: '',\n        repoRoot: '',\n        forbiddenPaths: [],\n        maxDiffLines: DEFAULT_MAX_DIFF_LINES,\n      })\n  const agentRunSpec: AgentRunSpec<CoderTask> = {\n    name,\n    profile,\n    taskToPrompt: formatCoderPrompt,\n  }\n  return { profile, taskToPrompt: formatCoderPrompt, output, validator, agentRunSpec }\n}\n\n/** @experimental */\nexport interface MultiHarnessCoderFanoutOptions {\n  /**\n   * Sandbox-SDK backend.type identifiers, one per parallel agent. Default:\n   * `['claude-code', 'codex', 'opencode/zai-coding-plan/glm-5.1']`.\n   */\n  harnesses?: string[]\n  /** Optional per-harness model override. Indexed parallel to `harnesses`. */\n  models?: (string | undefined)[]\n}\n\n/** @experimental */\nexport function multiHarnessCoderFanout(options: MultiHarnessCoderFanoutOptions = {}): {\n  agentRuns: AgentRunSpec<CoderTask>[]\n  output: OutputAdapter<CoderOutput>\n  validator: Validator<CoderOutput>\n  driver: Driver<CoderTask, CoderOutput, 'pick-winner' | 'fail'>\n} {\n  const harnesses =\n    options.harnesses && options.harnesses.length > 0\n      ? options.harnesses\n      : ['claude-code', 'codex', 'opencode/zai-coding-plan/glm-5.1']\n  const models = options.models ?? []\n  const agentRuns = harnesses.map((harness, i) => {\n    const { agentRunSpec } = coderProfile({ harness, model: models[i] })\n    return agentRunSpec\n  })\n  const { output, validator } = coderProfile()\n  const driver = createFanoutVoteDriver<CoderTask, CoderOutput>({ n: harnesses.length })\n  return { agentRuns, output, validator, driver }\n}\n\nconst DEFAULT_CODER_SYSTEM_PROMPT = [\n  'You are a coder agent operating inside an isolated sandbox workspace.',\n  'Your job is to deliver a minimal, correct patch for the user-supplied goal.',\n  '',\n  'Hard rules:',\n  '  1. Work on a fresh branch off the supplied base. Do not mutate the base branch.',\n  '  2. Never touch a forbidden path. The user will list them explicitly.',\n  '  3. Keep the diff under the max-diff cap. Prefer the smallest change that ships.',\n  '  4. Run the supplied test and typecheck commands before declaring done.',\n  '  5. If either command fails, fix the cause — do not weaken the test or hide the error.',\n  '',\n  'When you finish, emit a single final structured message of the shape:',\n  '  ```json',\n  '  { \"branch\": \"<branch-name>\",',\n  '    \"patch\": \"<unified-diff>\",',\n  '    \"testResult\": { \"passed\": <bool>, \"output\": \"<stdout/stderr>\" },',\n  '    \"typecheckResult\": { \"passed\": <bool>, \"output\": \"<stdout/stderr>\" },',\n  '    \"diffStats\": { \"filesChanged\": <int>, \"insertions\": <int>, \"deletions\": <int> },',\n  '    \"reviewerNotes\": \"<optional commentary>\" }',\n  '  ```',\n].join('\\n')\n\nfunction formatCoderPrompt(task: CoderTask): string {\n  const base = task.baseBranch ?? 'main'\n  const testCmd = task.testCmd ?? 'pnpm test --run'\n  const typecheckCmd = task.typecheckCmd ?? 'pnpm typecheck'\n  const maxDiff = task.maxDiffLines ?? DEFAULT_MAX_DIFF_LINES\n  const forbidden = task.forbiddenPaths?.length ? task.forbiddenPaths.join(', ') : '(none)'\n  const context = task.contextFiles?.length\n    ? task.contextFiles.map((f) => `  - ${f}`).join('\\n')\n    : '  (none)'\n  return [\n    `Goal: ${task.goal}`,\n    `Repo: ${task.repoRoot}`,\n    `Base branch: ${base}`,\n    `Run tests with: ${testCmd}`,\n    `Run typecheck with: ${typecheckCmd}`,\n    `Forbidden paths: ${forbidden}`,\n    `Max diff lines: ${maxDiff}`,\n    'Context files:',\n    context,\n    '',\n    'Produce a minimal patch on a fresh branch. Run tests and typecheck before',\n    'returning. Emit the final JSON result block exactly as instructed.',\n  ].join('\\n')\n}\n\n/**\n * Walk the event stream and return the last structured `coder.result` payload.\n *\n * The agent is instructed to emit a JSON block; in practice the sandbox SDK\n * lifts the structured payload onto `data.result` of a `result` / `final`\n * event. When the event stream does not contain a structured result, the\n * adapter scans text deltas for a fenced JSON block matching the expected\n * keys. Both shapes converge on `CoderOutput`.\n */\nfunction parseCoderEvents(events: SandboxEvent[]): CoderOutput {\n  for (let i = events.length - 1; i >= 0; i -= 1) {\n    const event = events[i]\n    if (!event) continue\n    const type = String(event.type ?? '')\n    const data = isRecord(event.data) ? event.data : {}\n    if (type === 'result' || type === 'final' || type === 'coder.result') {\n      const direct = coerceCoderOutput(data.result ?? data.output ?? data)\n      if (direct) return direct\n    }\n  }\n  // Fallback: scan text deltas in reverse for a fenced JSON block.\n  for (let i = events.length - 1; i >= 0; i -= 1) {\n    const event = events[i]\n    if (!event) continue\n    const data = isRecord(event.data) ? event.data : {}\n    const text = pickString(data.text) ?? pickString(data.delta)\n    if (!text) continue\n    const fenced = extractFencedJson(text)\n    if (!fenced) continue\n    const coerced = coerceCoderOutput(fenced)\n    if (coerced) return coerced\n  }\n  return {\n    branch: '',\n    patch: '',\n    testResult: { passed: false, output: '' },\n    typecheckResult: { passed: false, output: '' },\n    diffStats: { filesChanged: 0, insertions: 0, deletions: 0 },\n  }\n}\n\n/**\n * Build a validator that closes over a specific `CoderTask`'s constraints.\n *\n * Checks in order:\n *   1. Forbidden-path: any `+++` / `---` header in the patch matching a\n *      path prefix in `task.forbiddenPaths` fails hard.\n *   2. Diff size: line count above `task.maxDiffLines` (default 400) fails\n *      hard; below cap, the score shrinks linearly.\n *   3. Tests: `output.testResult.passed` must be `true`.\n *   4. Typecheck: `output.typecheckResult.passed` must be `true`.\n *\n * Aggregate score: `0.5 * tests + 0.3 * typecheck + 0.2 * (1 - diffLines/maxDiff)`.\n * `valid` is the conjunction of all four.\n *\n * @experimental\n */\nexport function createCoderValidator(task: CoderTask): Validator<CoderOutput> {\n  const maxDiff = task.maxDiffLines ?? DEFAULT_MAX_DIFF_LINES\n  const forbidden = task.forbiddenPaths ?? []\n  return {\n    async validate(output) {\n      const scores: Record<string, number> = {}\n      const notes: string[] = []\n      let pass = true\n\n      const touched = touchedPathsFromPatch(output.patch)\n      const touchedForbidden = forbidden.filter((path) => {\n        const prefix = path.endsWith('/') ? path : `${path}/`\n        const exact = prefix.slice(0, -1)\n        return touched.some((p) => p === exact || p.startsWith(prefix))\n      })\n      if (touchedForbidden.length > 0) {\n        pass = false\n        scores.forbiddenPath = 0\n        notes.push(`touched forbidden paths: ${touchedForbidden.join(', ')}`)\n      } else {\n        scores.forbiddenPath = 1\n      }\n\n      const diffLines = countDiffLines(output.patch)\n      if (diffLines > maxDiff) {\n        pass = false\n        scores.diffSize = 0\n        notes.push(`diff ${diffLines} lines exceeds cap ${maxDiff}`)\n      } else {\n        scores.diffSize = maxDiff === 0 ? 0 : Math.max(0, 1 - diffLines / maxDiff)\n      }\n\n      scores.tests = output.testResult.passed ? 1 : 0\n      scores.typecheck = output.typecheckResult.passed ? 1 : 0\n      if (!output.testResult.passed) {\n        pass = false\n        notes.push('tests failed')\n      }\n      if (!output.typecheckResult.passed) {\n        pass = false\n        notes.push('typecheck failed')\n      }\n\n      const score = 0.5 * scores.tests + 0.3 * scores.typecheck + 0.2 * scores.diffSize\n      const verdict: DefaultVerdict = {\n        valid: pass,\n        score: Number.isFinite(score) ? score : 0,\n        scores,\n      }\n      if (notes.length > 0) verdict.notes = notes.join('; ')\n      return verdict\n    },\n  }\n}\n\nfunction touchedPathsFromPatch(patch: string): string[] {\n  const out = new Set<string>()\n  for (const line of patch.split(/\\r?\\n/)) {\n    if (line.startsWith('+++ ') || line.startsWith('--- ')) {\n      const rest = line.slice(4).trim()\n      if (rest === '/dev/null') continue\n      const stripped = rest.startsWith('a/') || rest.startsWith('b/') ? rest.slice(2) : rest\n      out.add(stripped)\n    }\n  }\n  return [...out]\n}\n\nfunction countDiffLines(patch: string): number {\n  let count = 0\n  for (const line of patch.split(/\\r?\\n/)) {\n    if (\n      (line.startsWith('+') || line.startsWith('-')) &&\n      !line.startsWith('+++') &&\n      !line.startsWith('---')\n    ) {\n      count += 1\n    }\n  }\n  return count\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return value !== null && typeof value === 'object' && !Array.isArray(value)\n}\n\nfunction pickString(value: unknown): string | undefined {\n  return typeof value === 'string' && value.length > 0 ? value : undefined\n}\n\nfunction extractFencedJson(text: string): unknown | undefined {\n  const match = text.match(/```(?:json)?\\s*([\\s\\S]*?)```/i)\n  if (!match) return undefined\n  const body = (match[1] ?? '').trim()\n  if (!body) return undefined\n  try {\n    return JSON.parse(body)\n  } catch {\n    return undefined\n  }\n}\n\nfunction coerceCoderOutput(value: unknown): CoderOutput | undefined {\n  if (!isRecord(value)) return undefined\n  const branch = pickString(value.branch)\n  const patch = pickString(value.patch) ?? ''\n  if (branch === undefined) return undefined\n  const testResult = coerceCmdResult(value.testResult)\n  const typecheckResult = coerceCmdResult(value.typecheckResult)\n  const diffStats = coerceDiffStats(value.diffStats)\n  return {\n    branch,\n    patch,\n    testResult,\n    typecheckResult,\n    diffStats,\n    reviewerNotes: pickString(value.reviewerNotes),\n  }\n}\n\nfunction coerceCmdResult(value: unknown): { passed: boolean; output: string } {\n  if (!isRecord(value)) return { passed: false, output: '' }\n  return {\n    passed: value.passed === true,\n    output: pickString(value.output) ?? '',\n  }\n}\n\nfunction coerceDiffStats(value: unknown): {\n  filesChanged: number\n  insertions: number\n  deletions: number\n} {\n  if (!isRecord(value)) return { filesChanged: 0, insertions: 0, deletions: 0 }\n  return {\n    filesChanged: toFiniteInt(value.filesChanged),\n    insertions: toFiniteInt(value.insertions),\n    deletions: toFiniteInt(value.deletions),\n  }\n}\n\nfunction toFiniteInt(value: unknown): number {\n  if (typeof value !== 'number') return 0\n  if (!Number.isFinite(value)) return 0\n  return Math.max(0, Math.trunc(value))\n}\n"],"mappings":"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","names":[]}

package/dist/runtime-run-4pbY3Jq5.d.ts

@@ -0,0 +1,137 @@
+import { n as AgentTaskSpec, R as RuntimeStreamEvent } from './types-DlyPgeI0.js';
+
+/**
+ * @stable
+ *
+ * Production-run lifecycle: record what the agent did on behalf of a customer,
+ * what it cost, and how it ended.
+ *
+ * Three concerns live in this module:
+ *
+ *  1. **Lifecycle state machine** — `running` -> `completed | failed | cancelled`,
+ *     enforced by `RuntimeRunStateError`. Completion is idempotent for the same
+ *     status (a second `complete()` call is a no-op so retries / cleanup paths
+ *     don't double-fire side effects). A different terminal status is a state
+ *     error.
+ *
+ *  2. **Cost ledger** — every `llm_call` event the handle observes contributes
+ *     `tokensIn`, `tokensOut`, `costUsd`, and bumps `llmCalls`. Wall time is
+ *     measured from `startRuntimeRun()` to `complete()`. Surface via
+ *     `handle.cost()` for cost-per-task dashboards.
+ *
+ *  3. **Persistence adapter** — `RuntimeRunPersistenceAdapter` is the seam
+ *     consumers plug in to write a `RuntimeRunRow` to their D1 / postgres /
+ *     KV store. The adapter receives a sanitized row shape; no telemetry
+ *     payload bytes flow through it unless the consumer opts in via
+ *     `RuntimeRunOptions.telemetryEvents`.
+ */
+
+/** @stable */
+type RuntimeRunStatus = 'running' | 'completed' | 'failed' | 'cancelled';
+/** @stable */
+interface RuntimeRunCost {
+    /** Cumulative input tokens across every observed `llm_call` event. */
+    tokensIn: number;
+    /** Cumulative output tokens across every observed `llm_call` event. */
+    tokensOut: number;
+    /** Sum of `costUsd` from every observed `llm_call` event. */
+    costUsd: number;
+    /** Wall time from `startRuntimeRun()` to `complete()` (or `now()` if not yet completed). */
+    wallMs: number;
+    /** Count of `llm_call` events observed during the run. */
+    llmCalls: number;
+}
+/** @stable */
+interface RuntimeRunCompleteInput {
+    status: Exclude<RuntimeRunStatus, 'running'>;
+    resultSummary?: string;
+    /** Optional explicit cost override; if omitted, the accumulated ledger is used. */
+    cost?: Partial<RuntimeRunCost>;
+    /** Stable error message when `status === 'failed'`. */
+    error?: string;
+    /** Additional adapter-specific fields merged into the persisted row. */
+    metadata?: Record<string, unknown>;
+}
+/** @stable */
+interface RuntimeRunRow {
+    /** Stable runtime-side identifier. Adapters may translate to their own primary key. */
+    id: string;
+    workspaceId: string;
+    sessionId?: string;
+    agentId?: string;
+    domain?: string;
+    taskId: string;
+    scenarioId?: string;
+    status: RuntimeRunStatus;
+    resultSummary?: string;
+    error?: string;
+    cost: RuntimeRunCost;
+    startedAt: string;
+    completedAt?: string;
+    metadata?: Record<string, unknown>;
+}
+/** @stable */
+interface RuntimeRunPersistenceAdapter {
+    /**
+     * Called once when `handle.persist()` runs. Implementations write `row` to
+     * their durable store (D1, postgres, KV) and return whatever the consumer
+     * wants the caller to see (often the storage-side row id). Errors thrown
+     * here propagate out of `persist()` so the caller can decide whether to
+     * retry or log-and-continue.
+     */
+    upsert(row: RuntimeRunRow): Promise<void> | void;
+}
+/** @stable */
+interface RuntimeRunOptions {
+    workspaceId: string;
+    sessionId?: string;
+    agentId?: string;
+    taskSpec: AgentTaskSpec;
+    scenarioId?: string;
+    /** Optional persistence adapter; if omitted, `persist()` is a no-op. */
+    adapter?: RuntimeRunPersistenceAdapter;
+    /** Override the row id; default = `${taskSpec.id}:${random suffix}`. */
+    id?: string;
+    /** Override the clock; default = `Date.now()`. Useful for deterministic tests. */
+    now?: () => number;
+}
+/** @stable */
+interface RuntimeRunHandle {
+    /** Stable id assigned at start. */
+    readonly id: string;
+    readonly workspaceId: string;
+    readonly sessionId: string | undefined;
+    readonly taskSpec: AgentTaskSpec;
+    readonly status: RuntimeRunStatus;
+    /**
+     * Observe a single `RuntimeStreamEvent`. The handle ignores non-cost events
+     * (text deltas, tool calls) silently so consumers can pipe the whole stream
+     * through `handle.observe`. `llm_call` events update the ledger.
+     */
+    observe(event: RuntimeStreamEvent): void;
+    /** Snapshot of the current cost ledger. Safe to call at any time. */
+    cost(): RuntimeRunCost;
+    /**
+     * Transition to a terminal state. Idempotent for the same status; throws
+     * `RuntimeRunStateError` for a different terminal status (state machines
+     * don't time-travel).
+     */
+    complete(input: RuntimeRunCompleteInput): void;
+    /** Build the current row without writing it. Useful for tests + dry runs. */
+    toRow(metadata?: Record<string, unknown>): RuntimeRunRow;
+    /**
+     * Persist the current row via the configured adapter. Must be called after
+     * `complete()`. Idempotent for the same terminal state (the adapter sees
+     * the same row on retry).
+     */
+    persist(metadata?: Record<string, unknown>): Promise<void>;
+}
+/**
+ * @stable
+ *
+ * Construct a runtime-run handle. The returned handle is mutable across its
+ * lifetime; consumers should not share it across requests.
+ */
+declare function startRuntimeRun(options: RuntimeRunOptions): RuntimeRunHandle;
+
+export { type RuntimeRunHandle as R, type RuntimeRunPersistenceAdapter as a, type RuntimeRunRow as b, startRuntimeRun as s };

package/dist/{types-ByIhNRFk.d.ts → types-DlyPgeI0.d.ts}

@@ -376,4 +376,4 @@ interface KnowledgeReadinessDecision {
     nonBlockingGapIds: string[];
 }
 
-export type { AgentBackendInput as A, KnowledgeReadinessDecision as K, RuntimeStreamEvent as R, AgentExecutionBackend as a, AgentBackendContext as b, RunAgentTaskOptions as c, AgentTaskRunResult as d, RunAgentTaskStreamOptions as e, AgentTaskSpec as f, AgentRuntimeEvent as g, AgentTaskStatus as h, RuntimeSessionStore as i, RuntimeSession as j, AgentAdapter as k, AgentKnowledgeProvider as l, AgentRuntimeEventSink as m, AgentTaskContext as n };
+export type { AgentBackendInput as A, KnowledgeReadinessDecision as K, RuntimeStreamEvent as R, AgentExecutionBackend as a, AgentBackendContext as b, RunAgentTaskOptions as c, AgentTaskRunResult as d, RunAgentTaskStreamOptions as e, AgentRuntimeEvent as f, AgentTaskStatus as g, RuntimeSessionStore as h, RuntimeSession as i, AgentAdapter as j, AgentKnowledgeProvider as k, AgentRuntimeEventSink as l, AgentTaskContext as m, AgentTaskSpec as n };