botmux 2.93.1 → 2.95.0

package/dist/workflows/v3/contract.d.ts

@@ -0,0 +1,302 @@
+/**
+ * v3 runtime ⇄ ephemeral-pool IPC contract.
+ *
+ * This is the SHARED boundary between the two halves of the v3 engine:
+ *   - scheduling / persistence side (claude): `runtime.ts` calls `runNode`,
+ *     consumes the returned manifest, writes the next node's `inputs.json`.
+ *   - execution / IPC side (codex): `ephemeral-pool.ts` implements `runNode`
+ *     (spawns a throwaway worker in goal-mode), `manifest.ts` implements the
+ *     `Manifest` validator.
+ *
+ * Both sides import the *types* from here so the contract can't silently drift.
+ * Implementations live in their owners' files; this module is types + frozen
+ * string constants only (no runtime logic).  See
+ * `docs/design/2026-06-01-v3-mvp-engine-split.md` §2 for prose.
+ */
+import type { CliId } from '../../adapters/cli/types.js';
+import type { V3GoalNode } from './dag.js';
+/** Enumerated, NOT free-string (design Q8 / §7).  Unknown → validator rejects
+ *  (or the producer downgrades to `binary`). */
+export type ManifestFileKind = 'markdown' | 'json' | 'text' | 'code' | 'log' | 'binary' | 'directory';
+export declare const MANIFEST_FILE_KINDS: readonly ManifestFileKind[];
+/** Soft limits the manifest validator enforces (codex point 2). */
+export declare const MANIFEST_SUMMARY_MAX_BYTES: number;
+export declare const MANIFEST_PREVIEW_MAX_BYTES: number;
+export interface ManifestFile {
+    name: string;
+    /** Relative to the node's `outputDir` — absolute paths are REJECTED by the
+     *  validator (which canonicalizes `outputDir/path` and asserts it stays
+     *  inside outputDir).  Downstream `inputs.json` carries the resolved
+     *  absolute path; the manifest author may only write relative. */
+    path: string;
+    kind: ManifestFileKind;
+    bytes: number;
+    /** sha256 of the file; the empty string is the agreed sentinel for
+     *  `kind: 'directory'`. */
+    sha256: string;
+    mime: string;
+    /** Optional human-readable excerpt; validator truncates to
+     *  MANIFEST_PREVIEW_MAX_BYTES. */
+    preview?: string;
+}
+export type ManifestStatus = 'ok' | 'fail';
+export declare const MANIFEST_STATUSES: readonly ManifestStatus[];
+/**
+ * Written by a goal-mode worker at `BOTMUX_GOAL_MANIFEST_PATH` before exit.
+ * Invariants (enforced by the validator on codex's side):
+ *   - `status:'ok'`  → `files.length >= 1`, `error` absent
+ *   - `status:'fail'` → `error` required, `files` may be empty
+ */
+export interface Manifest {
+    schemaVersion: 1;
+    status: ManifestStatus;
+    /** Truncated to MANIFEST_SUMMARY_MAX_BYTES. */
+    summary: string;
+    error?: {
+        code: string;
+        message: string;
+        retryable?: boolean;
+    };
+    files: ManifestFile[];
+}
+export declare const MANIFEST_SCHEMA_VERSION: 1;
+/**
+ * Written by the runtime at `BOTMUX_GOAL_INPUTS_PATH` for each node, resolved
+ * from the manifests of the node's upstream `inputs.from`.  Unlike the
+ * manifest, the `path` here is ABSOLUTE so the consuming agent can `Read` it
+ * directly without knowing the upstream layout.
+ */
+export interface GoalInputs {
+    inputs: Array<{
+        from: string;
+        name: string;
+        path: string;
+        kind: ManifestFileKind;
+        preview?: string;
+    }>;
+    /** Declared inputs NOT injected: edge resolved inactive / source skipped
+     *  (edge-activation design §6) or a P3 per-file selector matched nothing in
+     *  the upstream manifest ('selectorMiss').  Telling the agent "this absence
+     *  is known" stops it from hallucinating the missing product. */
+    omitted?: Array<{
+        from: string;
+        reason: 'edgeInactive' | 'sourceSkipped' | 'sourceCancelled' | 'earlyRelease' | 'selectorMiss';
+    }>;
+}
+/**
+ * The fixed env keys the runtime injects into every goal-mode worker.  The
+ * `botmux-goal` skill / bootstrap prompt reads these by name — keeping the
+ * names here (not magic strings scattered across files) is the contract.
+ */
+export declare const GOAL_ENV: {
+    /** Path to the single-sentence goal text file. */
+    readonly GOAL_PATH: "BOTMUX_GOAL_PATH";
+    /** Path to this node's resolved `GoalInputs` JSON. */
+    readonly INPUTS_PATH: "BOTMUX_GOAL_INPUTS_PATH";
+    /** Directory the worker may write products into (and ONLY here). */
+    readonly OUTPUT_DIR: "BOTMUX_GOAL_OUTPUT_DIR";
+    /** Path the worker MUST write its `Manifest` to before exiting. */
+    readonly MANIFEST_PATH: "BOTMUX_GOAL_MANIFEST_PATH";
+    /** This attempt's directory (logs, manifest, work/ live under it). */
+    readonly ATTEMPT_DIR: "BOTMUX_GOAL_ATTEMPT_DIR";
+    /** Set to '1' — marks a goal-mode run so worker chat/card/ask side effects
+     *  stay silent (codex point 4). */
+    readonly V3_MARKER: "BOTMUX_V3_GOAL";
+};
+/**
+ * A goal worker that needs a human decision mid-run does NOT block in-process.
+ * Instead it writes its question to `GOAL_ASK_FILE` under the attempt
+ * dir, then exits with a fail manifest carrying `error.code = ASK_HUMAN_ERROR_CODE`
+ * and `error.retryable: true`.  classifyTerminal routes that to `blocked` (the
+ * retryable half), and the daemon posts an ask card instead of a plain retry
+ * card.  When the human answers, the daemon writes `GOAL_ANSWER_FILE` next to the
+ * ask and re-dispatches the node; the next attempt's GoalInputs injects the
+ * answer as `{from:'human', name:'answer'}`.  No suspend machinery, no held worker — it
+ * is the ordinary blocked→retry lifecycle with question/answer payloads bolted
+ * onto the two journal events.
+ */
+export declare const ASK_HUMAN_ERROR_CODE = "ASK_HUMAN";
+/** Filename (relative to the attempt dir) the goal worker writes its
+ *  {@link GoalAsk} to before exiting with an ASK_HUMAN fail manifest. */
+export declare const GOAL_ASK_FILE = "ask.json";
+/** Filename (relative to the *asked* attempt's dir) the daemon writes the
+ *  human's {@link GoalAnswer} to; the retry's GoalInputs points at this path. */
+export declare const GOAL_ANSWER_FILE = "answer.json";
+export type GoalAsk = {
+    /** The single question to put to the human. */
+    question: string;
+    /** 2–6 concrete options the human picks from; each becomes a card button. */
+    options: string[];
+    freeText?: false;
+} | {
+    /** The single question to put to the human. */
+    question: string;
+    /** Ask the human to provide free-form text instead of picking an option. */
+    freeText: true;
+    options?: never;
+};
+export type GoalAnswer = {
+    /** The option the human selected (one of {@link GoalAsk.options}). */
+    selected: string;
+    /** open_id of the human who answered. */
+    by: string;
+} | {
+    /** Free-form text the human provided. */
+    text: string;
+    /** open_id of the human who answered. */
+    by: string;
+};
+/**
+ * v3 goal-mode is delivered via the native `/goal` command, which only Claude
+ * Code, Codex, and Seed support (老滕 directive 2026-06-01, Seed added
+ * 2026-06-02).  We deliberately do NOT abstract goal delivery across every CLI
+ * — instead the feature is scoped to the CLIs whose command mechanism can host
+ * `/goal`.  Seed is ByteDance's Claude Code fork (`@bytedance-seed/claude-code`,
+ * binary `seed`): identical flags, slash commands, and session layout — it
+ * reuses the entire claude-family adapter, so `/goal`, paste-detection
+ * avoidance, and the manifest watcher all behave exactly as on claude-code with
+ * zero CLI-specific branching.  The runtime rejects a run whose nodes resolve
+ * to any other CLI at start time.
+ */
+export declare const V3_SUPPORTED_CLIS: readonly CliId[];
+export declare function isV3SupportedCli(cliId: CliId): boolean;
+/**
+ * The spawn-relevant bot config, FROZEN when the run starts and persisted in
+ * the runDir.  The pool spawns ephemeral workers from this snapshot rather
+ * than re-reading `bots.json` at execution time, so a retry / daemon-restart
+ * reproduces the original cliId / model / workingDir even if the live bot
+ * config drifted (codex point 1).
+ *
+ * Deliberately omits `larkAppSecret`: secrets are not written into the runDir.
+ * The pool re-reads the secret by `larkAppId` from the live registry at spawn
+ * (secret rotation is not the drift we're guarding against).  If we later need
+ * fully-hermetic replay we can revisit, but not at the cost of secrets on disk.
+ */
+export interface BotSnapshot {
+    larkAppId: string;
+    cliId: CliId;
+    cliPathOverride?: string;
+    model?: string;
+    /** Frozen from the bot's `disableCliBypass` config — when true the CLI's
+     *  permission bypass stays OFF for every node of this run.  A node-level
+     *  `override.permissionMode:'restricted'` can additionally set this per
+     *  dispatch; nothing can clear it (no-escalation red line, P2). */
+    disableCliBypass?: boolean;
+    /** The resolved working directory for this run. */
+    workingDir: string;
+}
+/** Returned alongside the result so dashboard terminal / replay / resume can
+ *  attach later without a contract change (codex point 1).  All optional —
+ *  MVP may leave it undefined. */
+export interface WorkerSessionInfo {
+    sessionId: string;
+    webPort?: number;
+    token?: string;
+}
+export interface RunNodeRequest {
+    runId: string;
+    /** Stable id e.g. `research/attempts/001`, used for sessionId / log naming. */
+    attemptId: string;
+    node: V3GoalNode;
+    /** Frozen at run start; do NOT re-resolve the bot here. */
+    botSnapshot: BotSnapshot;
+    runDir: string;
+    attemptDir: string;
+    inputsPath: string;
+    outputDir: string;
+    /** Already includes the GOAL_ENV keys; pool merges into the worker env. */
+    env: Record<string, string>;
+    timeoutMs: number;
+    cancelSignal?: AbortSignal;
+    /** Called as soon as the worker web terminal is ready, before the node
+     *  reaches terminal.  Runtime uses this to append `nodeSessionReady` so the
+     *  dashboard can attach to an in-flight node instead of waiting for
+     *  RunNodeResult at completion. */
+    onSessionReady?: (info: WorkerSessionInfo & {
+        ptyLogPath?: string;
+    }) => void | Promise<void>;
+    /** Defaults to `${attemptDir}/stdout.log` when omitted. */
+    stdoutPath?: string;
+    /** Defaults to `${attemptDir}/stderr.log` when omitted. */
+    stderrPath?: string;
+}
+export interface RunNodeResult {
+    /** Process-level outcome.  Final node verdict = this AND manifest validation
+     *  (runtime validates the manifest at `manifestPath` after `runNode`
+     *  resolves — codex point 4: NOT v0.2 final_output semantics). */
+    status: 'ok' | 'fail';
+    /** Where the worker wrote its manifest (defaults to attemptDir/manifest.json
+     *  but returned explicitly so the layout stays the pool's choice within
+     *  attemptDir). */
+    manifestPath: string;
+    sessionInfo?: WorkerSessionInfo;
+}
+/**
+ * Implemented by `ephemeral-pool.ts` (codex), called by `runtime.ts` (claude).
+ * Spawns one throwaway worker that runs the node's goal in goal-mode, waits
+ * for it to exit (or the timeout / cancel to fire), and resolves with the
+ * process outcome + manifest location.  The pool does NOT interpret the
+ * manifest — the runtime validates it.
+ */
+export type RunNode = (req: RunNodeRequest) => Promise<RunNodeResult>;
+export interface ManifestValidationResult {
+    ok: boolean;
+    /** Present when `ok` — the parsed, normalized manifest. */
+    manifest?: Manifest;
+    /** Present when `!ok` — the full problem list (mirror dag.ts's style). */
+    problems?: string[];
+}
+/**
+ * The runtime's view of manifest validation: read + validate the manifest at
+ * `manifestPath` against `outputDir`, returning a result object (never throws,
+ * so the dispatch loop stays branch-clean).
+ *
+ * codex's `manifest.ts` exposes the validation in a throw-based async form
+ * (`readAndValidateManifest(path, outputDir): Promise<Manifest>`); the daemon /
+ * CLI wiring adapts it to this shape at the injection boundary
+ * (try → `{ok:true, manifest}` / catch `ManifestValidationError` →
+ * `{ok:false, problems}`).  Async because the underlying impl reads the file
+ * and hashes its contents.
+ */
+export type ValidateManifest = (manifestPath: string, outputDir: string) => Promise<ManifestValidationResult>;
+export declare const SPEC_SCHEMA_VERSION = 1;
+/**
+ * One prospective node in the requirement-decomposition sketch.  grill writes
+ * these (the WHAT); architect turns them into formal dag.json nodes (the HOW).
+ *
+ * `input_needs` is FREE TEXT ("需要 research 阶段产出的竞品事实"), NOT a list of
+ * upstream sketchIds — grill must not draw edges; architect parses `input_needs`
+ * into the dag's `depends`. (codex review 2026-06-02.)  `risk_gate` → dag.json
+ * humanGate on the corresponding node.
+ */
+export interface SpecNodeSketch {
+    sketchId: string;
+    goal: string;
+    input_needs: string[];
+    expected_outputs: string[];
+    acceptance: string;
+    risk_gate: boolean;
+    unknowns: string[];
+}
+/**
+ * The canonical, machine-readable spec.  `workflow spec-finalize` parses the
+ * fenced ```json block out of spec.md, validates it, and materializes this as
+ * `spec.json` (parse/validate failure blocks handoff — codex review 2026-06-02).
+ * architect reads `spec.json` for STRUCTURE; `spec.md` is narrative context only.
+ *
+ * Node sketch ships as fenced JSON (not YAML) — dependency-free, mirrors v0.2's
+ * JSON workflow definitions, and an LLM emits valid JSON reliably.
+ */
+export interface Spec {
+    schemaVersion: number;
+    runId: string;
+    title: string;
+    /** grill 收敛后的清晰需求陈述. */
+    requirement: string;
+    /** 整体验收标准（人读叙事在 spec.md，这里给 architect 的结构化副本）. */
+    acceptance?: string;
+    /** 明确不做的. */
+    nonGoals?: string[];
+    nodes: SpecNodeSketch[];
+}
+//# sourceMappingURL=contract.d.ts.map

package/dist/workflows/v3/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../../src/workflows/v3/contract.ts"],"names":[],"mappings":"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"}

package/dist/workflows/v3/contract.js

@@ -0,0 +1,91 @@
+/**
+ * v3 runtime ⇄ ephemeral-pool IPC contract.
+ *
+ * This is the SHARED boundary between the two halves of the v3 engine:
+ *   - scheduling / persistence side (claude): `runtime.ts` calls `runNode`,
+ *     consumes the returned manifest, writes the next node's `inputs.json`.
+ *   - execution / IPC side (codex): `ephemeral-pool.ts` implements `runNode`
+ *     (spawns a throwaway worker in goal-mode), `manifest.ts` implements the
+ *     `Manifest` validator.
+ *
+ * Both sides import the *types* from here so the contract can't silently drift.
+ * Implementations live in their owners' files; this module is types + frozen
+ * string constants only (no runtime logic).  See
+ * `docs/design/2026-06-01-v3-mvp-engine-split.md` §2 for prose.
+ */
+export const MANIFEST_FILE_KINDS = [
+    'markdown', 'json', 'text', 'code', 'log', 'binary', 'directory',
+];
+/** Soft limits the manifest validator enforces (codex point 2). */
+export const MANIFEST_SUMMARY_MAX_BYTES = 4 * 1024;
+export const MANIFEST_PREVIEW_MAX_BYTES = 4 * 1024;
+export const MANIFEST_STATUSES = ['ok', 'fail'];
+export const MANIFEST_SCHEMA_VERSION = 1;
+// ─── goal-mode env contract (runtime fills, skill reads) ────────────────────
+/**
+ * The fixed env keys the runtime injects into every goal-mode worker.  The
+ * `botmux-goal` skill / bootstrap prompt reads these by name — keeping the
+ * names here (not magic strings scattered across files) is the contract.
+ */
+export const GOAL_ENV = {
+    /** Path to the single-sentence goal text file. */
+    GOAL_PATH: 'BOTMUX_GOAL_PATH',
+    /** Path to this node's resolved `GoalInputs` JSON. */
+    INPUTS_PATH: 'BOTMUX_GOAL_INPUTS_PATH',
+    /** Directory the worker may write products into (and ONLY here). */
+    OUTPUT_DIR: 'BOTMUX_GOAL_OUTPUT_DIR',
+    /** Path the worker MUST write its `Manifest` to before exiting. */
+    MANIFEST_PATH: 'BOTMUX_GOAL_MANIFEST_PATH',
+    /** This attempt's directory (logs, manifest, work/ live under it). */
+    ATTEMPT_DIR: 'BOTMUX_GOAL_ATTEMPT_DIR',
+    /** Set to '1' — marks a goal-mode run so worker chat/card/ask side effects
+     *  stay silent (codex point 4). */
+    V3_MARKER: 'BOTMUX_V3_GOAL',
+};
+// ─── Runtime human-ask (goal worker → human, rides the blocked+retry rail) ──
+/**
+ * A goal worker that needs a human decision mid-run does NOT block in-process.
+ * Instead it writes its question to `GOAL_ASK_FILE` under the attempt
+ * dir, then exits with a fail manifest carrying `error.code = ASK_HUMAN_ERROR_CODE`
+ * and `error.retryable: true`.  classifyTerminal routes that to `blocked` (the
+ * retryable half), and the daemon posts an ask card instead of a plain retry
+ * card.  When the human answers, the daemon writes `GOAL_ANSWER_FILE` next to the
+ * ask and re-dispatches the node; the next attempt's GoalInputs injects the
+ * answer as `{from:'human', name:'answer'}`.  No suspend machinery, no held worker — it
+ * is the ordinary blocked→retry lifecycle with question/answer payloads bolted
+ * onto the two journal events.
+ */
+export const ASK_HUMAN_ERROR_CODE = 'ASK_HUMAN';
+/** Filename (relative to the attempt dir) the goal worker writes its
+ *  {@link GoalAsk} to before exiting with an ASK_HUMAN fail manifest. */
+export const GOAL_ASK_FILE = 'ask.json';
+/** Filename (relative to the *asked* attempt's dir) the daemon writes the
+ *  human's {@link GoalAnswer} to; the retry's GoalInputs points at this path. */
+export const GOAL_ANSWER_FILE = 'answer.json';
+// ─── Supported CLIs ─────────────────────────────────────────────────────────
+/**
+ * v3 goal-mode is delivered via the native `/goal` command, which only Claude
+ * Code, Codex, and Seed support (老滕 directive 2026-06-01, Seed added
+ * 2026-06-02).  We deliberately do NOT abstract goal delivery across every CLI
+ * — instead the feature is scoped to the CLIs whose command mechanism can host
+ * `/goal`.  Seed is ByteDance's Claude Code fork (`@bytedance-seed/claude-code`,
+ * binary `seed`): identical flags, slash commands, and session layout — it
+ * reuses the entire claude-family adapter, so `/goal`, paste-detection
+ * avoidance, and the manifest watcher all behave exactly as on claude-code with
+ * zero CLI-specific branching.  The runtime rejects a run whose nodes resolve
+ * to any other CLI at start time.
+ */
+export const V3_SUPPORTED_CLIS = ['claude-code', 'codex', 'seed'];
+export function isV3SupportedCli(cliId) {
+    return V3_SUPPORTED_CLIS.includes(cliId);
+}
+// ─── Spec (grill 产物 → architect 输入) ──────────────────────────────────────
+export const SPEC_SCHEMA_VERSION = 1;
+// ─── Architect seam ─────────────────────────────────────────────────────────
+// `runArchitect(...)` + its `RunArchitectInput`/`RunArchitectResult` live in
+// `architect.ts` (codex owns the architect goal-worker).  The host controller
+// imports them from there directly — they are NOT redefined here (one-directional
+// host→architect call, not a bidirectional injection contract like RunNode).
+// The host still runs loadDag/validateDag on the returned dagPath; it does NOT
+// trust architect's self-claim of validity. (seam agreed w/ codex 2026-06-02.)
+//# sourceMappingURL=contract.js.map

package/dist/workflows/v3/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../../src/workflows/v3/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAkBH,MAAM,CAAC,MAAM,mBAAmB,GAAgC;IAC9D,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW;CACjE,CAAC;AAEF,mEAAmE;AACnE,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,GAAG,IAAI,CAAC;AACnD,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,GAAG,IAAI,CAAC;AAsBnD,MAAM,CAAC,MAAM,iBAAiB,GAA8B,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAiB3E,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAU,CAAC;AA4BlD,+EAA+E;AAE/E;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,kDAAkD;IAClD,SAAS,EAAE,kBAAkB;IAC7B,sDAAsD;IACtD,WAAW,EAAE,yBAAyB;IACtC,oEAAoE;IACpE,UAAU,EAAE,wBAAwB;IACpC,mEAAmE;IACnE,aAAa,EAAE,2BAA2B;IAC1C,sEAAsE;IACtE,WAAW,EAAE,yBAAyB;IACtC;uCACmC;IACnC,SAAS,EAAE,gBAAgB;CACnB,CAAC;AAEX,+EAA+E;AAE/E;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,WAAW,CAAC;AAEhD;yEACyE;AACzE,MAAM,CAAC,MAAM,aAAa,GAAG,UAAU,CAAC;AAExC;iFACiF;AACjF,MAAM,CAAC,MAAM,gBAAgB,GAAG,aAAa,CAAC;AAgC9C,+EAA+E;AAE/E;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAqB,CAAC,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AAEpF,MAAM,UAAU,gBAAgB,CAAC,KAAY;IAC3C,OAAO,iBAAiB,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC3C,CAAC;AAmHD,4EAA4E;AAE5E,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC;AA2CrC,+EAA+E;AAC/E,6EAA6E;AAC7E,8EAA8E;AAC9E,kFAAkF;AAClF,6EAA6E;AAC7E,+EAA+E;AAC/E,+EAA+E"}