@sema-ai/core 1.275.1

package/dist/orchestration/builtin-workflows.js

@@ -0,0 +1,165 @@
+/**
+ * design/140 §6 1c — BUILT-IN named workflows offered by the `Workflow` tool's `{name}` calling surface,
+ * mirroring the built-in agents precedent (src/agents/builtin-agents.ts: GA default-on, opt out via a
+ * deployment config flag, same-name deployment registration SHADOWS the built-in):
+ *  - `RunWorkflowToolDeps.builtinWorkflows: false` (threaded from `RunnerDeps.builtinWorkflows`) removes
+ *    them wholesale;
+ *  - a deployment `WorkflowScriptStore.resolveName` hit for the SAME NAME wins (the built-in is consulted
+ *    only when the deployment registry does not resolve the name).
+ *
+ * The first built-in is `team-discussion` — the round-based collab profile design/140 §1 verified live
+ * (docs/DESIGN-140-VERIFICATION-2026-07-11.md B 面: 2 members × 2 rounds + finalizer, 8.2s/10.5K tokens,
+ * round 2 genuinely responding to round 1). It is pure SCRIPT CONTENT over the existing primitives — zero
+ * new runtime mechanism:
+ *  - args schema (ALL optional — zero-config must run): `{ topic, members?: [{ role, prompt?, model? }],
+ *    rounds?, finalizer?: { prompt?, model? } }`; a bare STRING args is accepted as the topic.
+ *  - budget: reuses the workflow `budget` hard ceiling + DETERMINISTIC in-script truncation (a rounds/member
+ *    cap and a `budget.remaining()` early-stop — never an evaluator agent; design/140 §1 "预算" row).
+ *  - `meta.whenToUse` carries the REQUIRED negative boundary (when-NOT-to-use: single factual question /
+ *    budget-sensitive runs — design/140 §4 "两投影").
+ */
+import { parseWorkflowMeta } from "./workflow-meta.js";
+/** The built-in round-based team-discussion workflow's registered name. */
+export const TEAM_DISCUSSION_WORKFLOW_NAME = "team-discussion";
+/**
+ * The `team-discussion` script source (design/140 §1 table row 1, live-verified shape: for-loop rounds +
+ * `agent()` members with transcript re-feed + a schema'd finalizer). Deterministic by construction — no
+ * clock/randomness reads (locked by test against `workflowScriptReadsClockOrRandom`).
+ */
+export const TEAM_DISCUSSION_SCRIPT = `export const meta = {
+  name: "team-discussion",
+  description: "Round-based team discussion: configurable members debate a topic across rounds (each member sees the transcript so far), then a finalizer synthesizes a structured verdict.",
+  whenToUse: "Use for a genuinely contested question that benefits from several perspectives arguing across rounds - design trade-offs, plan or risk reviews, adversarial critique of a proposal. Do NOT use it for a single factual question, a task with one obvious answer, or a budget-sensitive run: every round costs one agent call per member, so a discussion is never cheaper than asking once. args (all optional): { topic, members?: [{ role, prompt?, model? }], rounds?, finalizer?: { prompt?, model? } }.",
+  phases: [
+    { title: "Discussion" },
+    { title: "Synthesis" },
+  ],
+};
+// Zero-config runnable (design/140 §6 1c): every arg has an opinionated fallback.
+const raw = args;
+const a = raw !== null && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+const topic =
+  typeof a.topic === "string" && a.topic.trim() !== ""
+    ? a.topic
+    : typeof raw === "string" && raw.trim() !== ""
+      ? raw // ergonomic form: a bare string args IS the topic
+      : "No topic was provided. Discuss: what information should a caller supply to make a team discussion like this productive, and when should they NOT convene one?";
+const defaultMembers = [
+  { role: "advocate", prompt: "Make the strongest constructive case. Propose concrete options and argue their benefits with specifics." },
+  { role: "skeptic", prompt: "Stress-test every claim made so far. Surface risks, hidden costs, failure modes, and cheaper alternatives." },
+];
+const rawMembers = Array.isArray(a.members) && a.members.length > 0 ? a.members : defaultMembers;
+const members = rawMembers.slice(0, 6).map((m, i) => {
+  const mm = m !== null && typeof m === "object" ? m : {};
+  const member = {
+    role: typeof mm.role === "string" && mm.role.trim() !== "" ? mm.role : "member-" + (i + 1),
+    prompt: typeof mm.prompt === "string" && mm.prompt.trim() !== "" ? mm.prompt : "Contribute your own distinct perspective: be concrete, give reasons, and engage with what others said.",
+  };
+  if (typeof mm.model === "string" && mm.model.trim() !== "") member.model = mm.model;
+  // Slot-tools carrier (design/140 ②-3 + F4): a member may BE a registered agent type ({agent:"reviewer"}) —
+  // persona/tools/model then come from the deployment's AgentDefinition (role library), args stay thin.
+  if (typeof mm.agent === "string" && mm.agent.trim() !== "") member.agent = mm.agent;
+  return member;
+});
+// Deterministic budget truncation (design/140 §1 预算 row): a HARD rounds ceiling + member cap — never an
+// evaluator agent. The engine's budget/maxAgents hard stops remain the backstop.
+const requestedRounds = Math.floor(Number(a.rounds));
+const rounds = Math.min(Number.isFinite(requestedRounds) && requestedRounds >= 1 ? requestedRounds : 2, 5);
+const fin = a.finalizer !== null && typeof a.finalizer === "object" && !Array.isArray(a.finalizer) ? a.finalizer : {};
+const finalizerPrompt = typeof fin.prompt === "string" && fin.prompt.trim() !== ""
+  ? fin.prompt
+  : "You are the synthesis lead. Read the full discussion transcript and produce the final verdict: the decision/answer, the key supporting points, and the strongest unresolved dissent (if any). Do not introduce new arguments of your own.";
+const clip = (s) => { const t = String(s); return t.length > 4000 ? t.slice(0, 4000) + " ...[truncated]" : t; };
+const isBudgetStop = (e) => e !== null && typeof e === "object" && e.code === "workflow.budget_exceeded";
+
+phase("Discussion");
+const transcript = [];
+let truncated = null;
+for (let r = 1; r <= rounds && truncated === null; r++) {
+  // Deterministic early stop on an exhausted budget (a live read of the engine budget; the engine's
+  // hard WorkflowBudgetExceededError remains the backstop if a member call itself crosses the line).
+  if (budget.total !== null && budget.remaining() <= 0) { truncated = "budget exhausted before round " + r; break; }
+  for (const m of members) {
+    const history = transcript.length === 0 ? "(none yet - you open the discussion)" : transcript.join("\\n\\n");
+    const spec = {
+      objective:
+        "Team discussion on: " + topic + "\\n\\n" +
+        'You are "' + m.role + '" in round ' + r + " of " + rounds + ".\\n" +
+        "Your brief: " + m.prompt + "\\n\\n" +
+        "Transcript so far:\\n" + history + "\\n\\n" +
+        "Respond to the strongest points others made (do not repeat yourself), then advance your own position. Be concise: a few tight paragraphs at most.",
+    };
+    if (m.model !== undefined) spec.modelName = m.model;
+    let res;
+    try {
+      res = await agent(spec, m.agent !== undefined ? { label: m.role + "-r" + r, phase: "Discussion", agentType: m.agent } : { label: m.role + "-r" + r, phase: "Discussion" });
+    } catch (e) {
+      // The engine's budget hard stop: keep what the discussion already produced instead of failing the run.
+      if (isBudgetStop(e)) { truncated = "budget exhausted at " + m.role + ", round " + r; break; }
+      throw e;
+    }
+    const text = res && res.status === "completed" ? clip(res.result) : "(no contribution - agent ended " + (res ? res.status : "unknown") + ")";
+    transcript.push(m.role + " (round " + r + "): " + text);
+  }
+}
+
+phase("Synthesis");
+const finalSpec = {
+  objective:
+    finalizerPrompt + "\\n\\nTopic: " + topic + "\\n\\nFull transcript:\\n" +
+    (transcript.length === 0 ? "(the discussion produced no contributions)" : transcript.join("\\n\\n")) +
+    (truncated ? "\\n\\nNote: the discussion was cut short (" + truncated + ")." : ""),
+};
+if (typeof fin.model === "string" && fin.model.trim() !== "") finalSpec.modelName = fin.model;
+let verdict = null;
+try {
+  verdict = await agent(finalSpec, {
+    label: "finalizer",
+    phase: "Synthesis",
+    schema: {
+      type: "object",
+      properties: {
+        decision: { type: "string", description: "The final answer/decision, one paragraph." },
+        keyPoints: { type: "array", items: { type: "string" }, description: "The strongest supporting points from the discussion." },
+        dissent: { type: "string", description: "The strongest unresolved counter-position, if any." },
+      },
+      required: ["decision", "keyPoints"],
+    },
+  });
+} catch (e) {
+  // Budget died before synthesis: return the transcript honestly rather than failing the whole run.
+  if (!isBudgetStop(e)) throw e;
+  truncated = truncated === null ? "budget exhausted before synthesis" : truncated;
+}
+
+return {
+  topic,
+  rounds,
+  members: members.map((m) => m.role),
+  ...(truncated ? { truncated } : {}),
+  transcript,
+  verdict: verdict && verdict.structuredOutput !== undefined ? verdict.structuredOutput : (verdict ? verdict.result : null),
+};
+`;
+/** The built-in named-workflow registry (CC `HCe`-analog shape, workflows arm). Order = card listing order. */
+export function builtinWorkflowDefinitions() {
+    return [{ name: TEAM_DISCUSSION_WORKFLOW_NAME, script: TEAM_DISCUSSION_SCRIPT }];
+}
+/** Resolve a built-in workflow by name (the `{name}` surface's SECOND lookup — a deployment
+ *  `scriptStore.resolveName` hit for the same name shadows this, design/140 §6 1c). */
+export function resolveBuiltinWorkflow(name) {
+    return builtinWorkflowDefinitions().find((w) => w.name === name);
+}
+/** design/140 §6 1b — the built-ins' listing projection rows (name + description + whenToUse, parsed from
+ *  each script's static meta). Consumed by the Workflow tool card renderer. */
+export function builtinWorkflowListings() {
+    return builtinWorkflowDefinitions().map((w) => {
+        const meta = parseWorkflowMeta(w.script);
+        return {
+            name: w.name,
+            description: meta.description,
+            ...(meta.whenToUse !== undefined ? { whenToUse: meta.whenToUse } : {}),
+        };
+    });
+}
+//# sourceMappingURL=builtin-workflows.js.map

package/dist/orchestration/builtin-workflows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin-workflows.js","sourceRoot":"","sources":["../../src/orchestration/builtin-workflows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAGvD,2EAA2E;AAC3E,MAAM,CAAC,MAAM,6BAA6B,GAAG,iBAAiB,CAAC;AAE/D;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkHrC,CAAC;AASF,+GAA+G;AAC/G,MAAM,UAAU,0BAA0B;IACxC,OAAO,CAAC,EAAE,IAAI,EAAE,6BAA6B,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC,CAAC;AACnF,CAAC;AAED;uFACuF;AACvF,MAAM,UAAU,sBAAsB,CAAC,IAAY;IACjD,OAAO,0BAA0B,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AACnE,CAAC;AAED;+EAC+E;AAC/E,MAAM,UAAU,uBAAuB;IACrC,OAAO,0BAA0B,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAC5C,MAAM,IAAI,GAAG,iBAAiB,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACzC,OAAO;YACL,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,GAAG,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACvE,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/orchestration/dev-vm-script-runner.d.ts

@@ -0,0 +1,24 @@
+/**
+ * design/98 §2.2 (S8b) — a `WorkflowScriptRunner` backed by Node's `vm`, for TRUSTED, DEVELOPER-authored
+ * workflow scripts ONLY.
+ *
+ * 🔴🔴 NOT A SECURITY BOUNDARY. Node `vm` does NOT isolate untrusted code: a script can reach the host realm
+ * through the prototype chain of ANY injected host object —
+ *   `agent.constructor.constructor("return process")()`
+ * yields the host `process` (the injected `agent` is a host function; its `.constructor.constructor` is the
+ * HOST `Function`, evaluated in the host realm where code-generation is unrestricted). The
+ * `codeGeneration:{strings:false}` below hardens the vm context's OWN eval/Function but CANNOT close that
+ * constructor-chain escape — see `test/workflow-vm-escape.test.ts`, which PROVES the escape so no one ever
+ * mistakes this for a sandbox.
+ *
+ * Therefore `safeForUntrustedScripts === false`: the S8 self-orchestration gate (design/98 §C) refuses to
+ * mount `run_workflow` with this runner. An LLM-authored script REQUIRES a runner whose
+ * `safeForUntrustedScripts === true` (isolated-vm / separate process + container), supplied by the deployment
+ * or a separate `@ai-only/workflow-sandbox` package. Core ships this dev runner + the conformance contract a
+ * hard runner must pass ({@link import("./workflow-sandbox-conformance.js").assertWorkflowSandboxConformance}).
+ */
+import type { WorkflowScriptRunner } from "./workflow-script-runner.js";
+export declare const WORKFLOW_DATE_ERR = "Date.now() / new Date() are unavailable in workflow scripts (breaks resume). Stamp results after the workflow returns, or pass timestamps via args.";
+export declare const WORKFLOW_RANDOM_ERR = "Math.random() is unavailable in workflow scripts (breaks resume). For N independent samples, include the index in the agent label or prompt.";
+export declare const devWorkflowScriptRunner: WorkflowScriptRunner;
+//# sourceMappingURL=dev-vm-script-runner.d.ts.map

package/dist/orchestration/dev-vm-script-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-vm-script-runner.d.ts","sourceRoot":"","sources":["../../src/orchestration/dev-vm-script-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAOxE,eAAO,MAAM,iBAAiB,wJACyH,CAAC;AACxJ,eAAO,MAAM,mBAAmB,iJACgH,CAAC;AA0BjJ,eAAO,MAAM,uBAAuB,EAAE,oBA6DrC,CAAC"}

package/dist/orchestration/dev-vm-script-runner.js

@@ -0,0 +1,106 @@
+/**
+ * design/98 §2.2 (S8b) — a `WorkflowScriptRunner` backed by Node's `vm`, for TRUSTED, DEVELOPER-authored
+ * workflow scripts ONLY.
+ *
+ * 🔴🔴 NOT A SECURITY BOUNDARY. Node `vm` does NOT isolate untrusted code: a script can reach the host realm
+ * through the prototype chain of ANY injected host object —
+ *   `agent.constructor.constructor("return process")()`
+ * yields the host `process` (the injected `agent` is a host function; its `.constructor.constructor` is the
+ * HOST `Function`, evaluated in the host realm where code-generation is unrestricted). The
+ * `codeGeneration:{strings:false}` below hardens the vm context's OWN eval/Function but CANNOT close that
+ * constructor-chain escape — see `test/workflow-vm-escape.test.ts`, which PROVES the escape so no one ever
+ * mistakes this for a sandbox.
+ *
+ * Therefore `safeForUntrustedScripts === false`: the S8 self-orchestration gate (design/98 §C) refuses to
+ * mount `run_workflow` with this runner. An LLM-authored script REQUIRES a runner whose
+ * `safeForUntrustedScripts === true` (isolated-vm / separate process + container), supplied by the deployment
+ * or a separate `@ai-only/workflow-sandbox` package. Core ships this dev runner + the conformance contract a
+ * hard runner must pass ({@link import("./workflow-sandbox-conformance.js").assertWorkflowSandboxConformance}).
+ */
+import vm from "node:vm";
+import { splitWorkflowMeta, WorkflowScriptError } from "./workflow-meta.js";
+// ── B2/F3 (PARITY-SPOT-WORKFLOW): determinism shim — CC `S0m`/`y0m`/`T0m` verbatim port ─────────────────
+// A workflow script that reads the clock or randomness produces a different agent-call identity every run,
+// SILENTLY busting the resume journal's prefix cache (callKey divergence → the whole suffix re-runs). CC makes
+// this a hard, TEACHING error at runtime (and statically at the tool layer — run-workflow-tool.ts); we
+// previously let Date/Math through untouched (silent degradation). Messages verbatim (pretty.js:445972-445975).
+export const WORKFLOW_DATE_ERR = "Date.now() / new Date() are unavailable in workflow scripts (breaks resume). Stamp results after the workflow returns, or pass timestamps via args.";
+export const WORKFLOW_RANDOM_ERR = "Math.random() is unavailable in workflow scripts (breaks resume). For N independent samples, include the index in the agent label or prompt.";
+/** CC `S0m` (pretty.js:445983-446003): runs INSIDE the vm context BEFORE the body — throws on Math.random /
+ *  Date.now / bare Date() / argless new Date(); dated construction (`new Date(x)`) stays available; the
+ *  `.constructor` backdoor to the real Date is closed and the real Date frozen so the shim can't be undone. */
+const DETERMINISM_SHIM = `(() => {
+  const NOW_ERR = ${JSON.stringify(WORKFLOW_DATE_ERR)};
+  const RANDOM_ERR = ${JSON.stringify(WORKFLOW_RANDOM_ERR)};
+  Math.random = function random() { throw new Error(RANDOM_ERR) };
+  const RealDate = Date;
+  RealDate.now = function now() { throw new Error(NOW_ERR) };
+  function ShimDate(...a) {
+    if (!new.target) throw new Error(NOW_ERR); // bare Date() → now-string
+    if (a.length === 0) throw new Error(NOW_ERR);
+    return Reflect.construct(RealDate, a, new.target);
+  }
+  ShimDate.now = RealDate.now;
+  ShimDate.parse = RealDate.parse;
+  ShimDate.UTC = RealDate.UTC;
+  ShimDate.prototype = RealDate.prototype;
+  // Close the (new Date(x)).constructor backdoor to RealDate.now — point
+  // .constructor at the shim, then freeze RealDate so it can't be undone.
+  RealDate.prototype.constructor = ShimDate;
+  Object.freeze(RealDate);
+  globalThis.Date = ShimDate;
+})()`;
+export const devWorkflowScriptRunner = {
+    safeForUntrustedScripts: false,
+    async run({ scriptSource, primitives, scriptArgs, signal }) {
+        if (signal?.aborted)
+            throw new Error("workflow script aborted before start");
+        // The meta is parsed STATICALLY (no eval — workflow-meta.ts); only the BODY is compiled + run.
+        const { meta, body } = splitWorkflowMeta(scriptSource);
+        const wrapped = `(async function(agent, parallel, pipeline, phase, log, budget, args) {\n${body}\n})`;
+        // B2/F3: a dynamic `import()` gets the CC teaching error (pretty.js:445963) instead of Node's bare
+        // ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING. Older Node rejects the callback option at construction —
+        // fall back to compiling without it (the default error still blocks the import).
+        const importThrow = () => {
+            throw new WorkflowScriptError("import() is not available in workflow scripts.");
+        };
+        let compiled;
+        try {
+            try {
+                compiled = new vm.Script(wrapped, { filename: "workflow-script.js", importModuleDynamically: importThrow });
+            }
+            catch (err) {
+                if (err instanceof SyntaxError)
+                    throw err;
+                compiled = new vm.Script(wrapped, { filename: "workflow-script.js" });
+            }
+        }
+        catch (err) {
+            throw new WorkflowScriptError(`workflow script failed to compile: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // A fresh context. codeGeneration:{strings:false} blocks the context's OWN eval/Function (defense in depth)
+        // — it does NOT make this a boundary (see the file header + the escape regression test).
+        // Self-explaining host-API stubs (blackboard 2026-07-03, clay dogfood v5): a bare
+        // `ReferenceError: require is not defined` sent the model down a trial-and-error chain; calling
+        // any of these now explains the sandbox instead. Scripts can still shadow the names locally.
+        const noHostApi = (name) => () => {
+            throw new WorkflowScriptError(`${name} is not available in workflow scripts — there are no Node/host APIs here. Use agent()/log()/` +
+                `budget for work, and schedule time-based behavior outside the workflow.`);
+        };
+        const context = vm.createContext({
+            require: noHostApi("require"),
+            setTimeout: noHostApi("setTimeout"),
+            setInterval: noHostApi("setInterval"),
+            setImmediate: noHostApi("setImmediate"),
+            fetch: noHostApi("fetch"),
+            queueMicrotask: noHostApi("queueMicrotask"),
+        }, { codeGeneration: { strings: false, wasm: false } });
+        // B2/F3: arm the determinism shim on the context's OWN intrinsics BEFORE any body code runs — Date.now /
+        // Math.random / argless new Date throw the CC-verbatim teaching error instead of silently busting resume.
+        new vm.Script(DETERMINISM_SHIM, { filename: "workflow-determinism-shim.js" }).runInContext(context);
+        const fn = compiled.runInContext(context);
+        const result = await fn(primitives.agent, primitives.parallel, primitives.pipeline, primitives.phase, primitives.log, primitives.budget, scriptArgs);
+        return { result, meta };
+    },
+};
+//# sourceMappingURL=dev-vm-script-runner.js.map

package/dist/orchestration/dev-vm-script-runner.js.map

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

package/dist/orchestration/goal.d.ts

@@ -0,0 +1,97 @@
+/**
+ * design/96 §C (S2) — **Goal 模式**:LLM 自报完成 + core 校验续跑(CC goal 对标:目标 + 完成判定 + 续跑)。
+ * `runGoal` 是 `runRepairLoop`/`verifyCompleted` 的 SIBLING —— thin composition over `runner.runTask`,零
+ * Runner core 改动。详 `design/96-references/GOAL-IMPLEMENTER-SPEC.md`(v3,codex r1+r2 异源对抗收敛)。
+ *
+ * 🔴 **完成判定双闸(reward-hack 红线)**:① LLM 自报完成 = 调内置 `declare_done` 工具(或 `submit_output`,有
+ * outputSchema 时)= **机器信号**,非泛化 `completed`;② core `doneCheck`(机械/oracle 校验)。**AND**:仅二者
+ * 都满足才停 —— LLM 自报但 doneCheck 否决 → 续跑(把 reason 围栏喂回),这是防"模型说我完成了就算数"的核心。
+ *
+ * 🔴 **G1 脱钩(不可绕)**:`status:"achieved"` = 双闸过 → **停迭代 + SURFACE**,`accepted` 恒 false。runGoal
+ * **无任何 commit/accept 副作用**(纯 loop,同 runRepairLoop SAFE-tier 永不 `fixed`)。要 accept,caller 自走
+ * design/77 Gate-1 out-of-process oracle 隔离边界,不在 goal helper 开后门。
+ */
+import type { Runner } from "../core/runner/runtask.js";
+import type { CheckpointToken } from "../core/checkpoint-store.js";
+import type { TaskResult, TaskSpec } from "../core/types.js";
+/** Read-only snapshot a `doneCheck` sees after one iteration. */
+export interface GoalTurnState {
+    /** This iteration's full {@link TaskResult}. */
+    readonly result: TaskResult;
+    /** 1-based iteration index. */
+    readonly iteration: number;
+    /** The session threaded through the whole goal (so a doneCheck can read the session/working tree). */
+    readonly sessionId: string;
+    /** Cumulative tokens (own + nested) across iterations — observe-only (the budget gate is in the engine). */
+    readonly cumulativeTokens: number;
+}
+export interface GoalVerdict {
+    /** core verification passed? (AND-ed with the LLM self-report — the double gate). */
+    readonly done: boolean;
+    /** When not done: the specific feedback fed back to the LLM (fenced as untrusted data). */
+    readonly reason: string;
+}
+/** The caller's HONEST declaration of how `doneCheck` verifies — surfaced on the result so a
+ *  `self_report_only` "achieved" is never mistaken for a mechanically-verified one (G1, reward-hack honesty). */
+export type GoalVerificationKind = "mechanical" | "self_report_only";
+export interface GoalSpec {
+    /** The goal (injected as iteration 1's objective + GOAL_COMPLETION_GUIDANCE via the trusted goalMode flag). */
+    objective: string;
+    /**
+     * 🔴 The CORE completion gate (REQUIRED). The LLM self-report (gate 1) is necessary but NOT sufficient: the
+     * goal stops as `achieved` only when gate 1 AND `doneCheck.done`. Provide a PURE read-check (it may read the
+     * session/working tree but must have no side effects — it can be cancelled/timed out). A throw/reject
+     * fail-closes to `failed`/`goal.donecheck_error` (never treated as achieved). Core ships no default —
+     * supplying it forces the caller to confront the reward-hack red line.
+     */
+    doneCheck: (state: GoalTurnState, signal: AbortSignal) => Promise<GoalVerdict>;
+    /** Honest declaration of `doneCheck`'s substance (§3.2). `self_report_only` ⇒ surfaced on the result. */
+    verificationKind: GoalVerificationKind;
+    /** Hard iteration cap (≥1) — exceeding without the double gate → `max_iterations` (NOT achieved). */
+    maxIterations: number;
+    /** Per-iteration base spec (model/tools/toolPolicy/principal/env/outputSchema/…). `objective` is overridden
+     *  per iteration; `sessionId` is minted to thread the whole goal if absent; `signal` is set by the engine. */
+    taskSpec: Omit<TaskSpec, "objective">;
+    /** Cumulative token ceiling (own + nested); reaching it stops with `budget`. */
+    budgetTokens?: number;
+    /** Whole-goal wall-clock ceiling (ms); reaching it stops with `budget`. */
+    totalTimeoutMs?: number;
+    /** Cancels the whole goal (folded into each iteration's signal + the doneCheck). */
+    signal?: AbortSignal;
+    /**
+     * design/73 §1 — aggregation key of the `TaskOutcome` emitted at the goal's terminal state (only when
+     * `verificationKind:"mechanical"` — the red line). Default: `goal:<sha256(objective) first 16 hex>`,
+     * deterministic per objective. Set it when the "same task" spans differently-worded objectives.
+     */
+    taskSignature?: string;
+}
+export type GoalStatus = "achieved" | "max_iterations" | "budget" | "blocked" | "suspended" | "needs_review" | "failed" | "aborted";
+export interface GoalResult {
+    readonly status: GoalStatus;
+    /** Last iteration's result; absent on a preflight-terminate (a stop BEFORE iteration 1 ran). */
+    readonly result?: TaskResult;
+    readonly iterations: number;
+    /** The last `doneCheck` verdict (present once a doneCheck ran). */
+    readonly lastVerdict?: GoalVerdict;
+    /** The caller's declared verification kind (always present — replaces the ambiguous "verifiedBy"). */
+    readonly verificationKind: GoalVerificationKind;
+    /** 🔴 G1 explicit: runGoal NEVER accepts the artifact. Always false. `achieved` = "stopped + awaiting
+     *  review"; the caller decides acceptance (via a Gate-1 boundary), never runGoal. */
+    readonly accepted: false;
+    readonly cumulativeTokens: number;
+    /** Carried up on suspended/needs_review so the caller can resume the underlying task. */
+    readonly checkpointToken?: CheckpointToken;
+    /** Set on `failed` (incl. `goal.donecheck_error`). */
+    readonly errorCode?: string;
+}
+/** Reserved name of the goal-completion signal tool (injected by `runGoal` when there is no outputSchema). */
+export declare const DECLARE_DONE_TOOL_NAME = "DeclareDone";
+/**
+ * Run a goal to a double-gated completion (or a bound). Iterates `runner.runTask` on ONE session: each
+ * iteration the LLM works and signals completion (declare_done / submit_output); `doneCheck` then verifies.
+ * Only `declare_done` AND `doneCheck.done` → `achieved` (surfaced, NEVER auto-accepted, G1). A rejected
+ * doneCheck feeds its reason back (fenced) and continues. Bounded by maxIterations / budget / wall-clock /
+ * cancel; a durable pause (suspended/needs_review) is a hard boundary that surfaces the checkpointToken.
+ */
+export declare function runGoal(runner: Runner, spec: GoalSpec): Promise<GoalResult>;
+//# sourceMappingURL=goal.d.ts.map

package/dist/orchestration/goal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"goal.d.ts","sourceRoot":"","sources":["../../src/orchestration/goal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAY,MAAM,kBAAkB,CAAC;AASvE,iEAAiE;AACjE,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,+BAA+B;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sGAAsG;IACtG,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4GAA4G;IAC5G,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED,MAAM,WAAW,WAAW;IAC1B,qFAAqF;IACrF,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,2FAA2F;IAC3F,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;iHACiH;AACjH,MAAM,MAAM,oBAAoB,GAAG,YAAY,GAAG,kBAAkB,CAAC;AAErE,MAAM,WAAW,QAAQ;IACvB,+GAA+G;IAC/G,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IAC/E,yGAAyG;IACzG,gBAAgB,EAAE,oBAAoB,CAAC;IACvC,qGAAqG;IACrG,aAAa,EAAE,MAAM,CAAC;IACtB;kHAC8G;IAC9G,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;IACtC,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oFAAoF;IACpF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,UAAU,GAClB,UAAU,GACV,gBAAgB,GAChB,QAAQ,GACR,SAAS,GACT,WAAW,GACX,cAAc,GACd,QAAQ,GACR,SAAS,CAAC;AAEd,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,gGAAgG;IAChG,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,mEAAmE;IACnE,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC,sGAAsG;IACtG,QAAQ,CAAC,gBAAgB,EAAE,oBAAoB,CAAC;IAChD;yFACqF;IACrF,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;IACzB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,yFAAyF;IACzF,QAAQ,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC;IAC3C,sDAAsD;IACtD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAMD,8GAA8G;AAC9G,eAAO,MAAM,sBAAsB,gBAAgB,CAAC;AAwEpD;;;;;;GAMG;AACH,wBAAsB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,CAiKjF"}