@chances-ai/engine 27.0.0 → 28.0.0

package/dist/core/coordinator-tools.js

@@ -0,0 +1,262 @@
+import { AppError, ErrorCode } from "@chances-ai/runtime";
+import { DEFAULT_MAX_TURNS } from "./engine.js";
+import { CREATE_TEAM_TOOL_NAME, DISMISS_WORKER_TOOL_NAME, LIST_WORKERS_TOOL_NAME, SEND_MESSAGE_TOOL_NAME, SPAWN_WORKER_TOOL_NAME, STOP_WORKER_TOOL_NAME, createChildAgentRuntime, } from "./task-tool.js";
+/** Upper bound on a worker child's `maxTurns` — matches the one-shot `task`
+ * tool's `CHILD_MAX_TURNS_CEILING` so a worker can't wedge for hours. */
+const WORKER_MAX_TURNS_CEILING = 50;
+function strArg(args, key, required) {
+    const v = args[key];
+    if (v === undefined || v === null) {
+        if (required)
+            throw new AppError(ErrorCode.Tool, `Expected string arg "${key}"`);
+        return undefined;
+    }
+    if (typeof v !== "string") {
+        throw new AppError(ErrorCode.Tool, `Expected string arg "${key}"`);
+    }
+    return v;
+}
+/** A `to` target of the form `team:<id>` → the team id, else null. */
+function teamTarget(to) {
+    return to.startsWith("team:") ? to.slice("team:".length) : null;
+}
+/**
+ * (7.8 §3.2) Build the coordinator's orchestration tool set:
+ * `spawn_worker` / `send_message` / `stop_worker` / `create_team` /
+ * `list_workers`. Registered on the COORDINATOR's main engine ONLY (coordinator
+ * mode) — a normal session never sees them, and the one-shot `task` stays the
+ * simple-delegation default. All orchestration ops are `isConcurrencySafe:false`
+ * (stateful side effects); only `list_workers` is read-only/parallel-safe.
+ */
+export function createCoordinatorTools(deps) {
+    const reg = deps.workerRegistry;
+    const childMaxTurns = Math.min(Math.max(1, deps.maxTurns ?? DEFAULT_MAX_TURNS), WORKER_MAX_TURNS_CEILING);
+    const spawnWorker = {
+        name: SPAWN_WORKER_TOOL_NAME,
+        description: "Spawn a PERSISTENT worker (a child agent that stays alive so you can continue it with send_message, reusing its context). Unlike the one-shot `task` tool, the worker does not die after one reply — direct it to research/implement/verify, then `send_message` it follow-up work or `stop_worker` it if it goes the wrong way. Returns an agent_id you address it by. The worker has full tool access (it does the editing); YOU only direct.",
+        category: "integration",
+        parameters: {
+            type: "object",
+            properties: {
+                description: {
+                    type: "string",
+                    description: "Short label (1–3 words) for this worker. Shown in the permission prompt and the worker panel.",
+                },
+                prompt: {
+                    type: "string",
+                    description: "The worker's first instruction. Make it self-contained — include specific file paths, line numbers, and exactly what to do (you must understand the work before delegating it).",
+                },
+                subagent_type: {
+                    type: "string",
+                    description: "Optional persona from the agent catalog. Omit for a full-inheritance worker.",
+                },
+                team: {
+                    type: "string",
+                    description: "Optional team id (from create_team) to group this worker under, for broadcast / batch-stop.",
+                },
+                isolation: {
+                    type: "string",
+                    enum: ["worktree", "none"],
+                    description: "'worktree' runs the worker in an isolated git worktree; 'none' (default) shares the working tree.",
+                },
+                context: {
+                    type: "string",
+                    enum: ["fork", "fresh"],
+                    description: "'fresh' (default) = empty context. 'fork' = inherit a copy of THIS conversation's completed turns as background.",
+                },
+            },
+            required: ["prompt"],
+        },
+        isConcurrencySafe: () => false,
+        summarize: (args) => {
+            const prompt = strArg(args, "prompt", true);
+            const desc = strArg(args, "description", false);
+            const head = prompt.length > 80 ? prompt.slice(0, 80) + "…" : prompt;
+            return `spawn_worker${desc ? `[${desc}]` : ""}: ${head}`;
+        },
+        async execute(args, ctx) {
+            const prompt = strArg(args, "prompt", true);
+            const team = strArg(args, "team", false);
+            if (team !== undefined && !reg.hasTeam(team)) {
+                return { ok: false, output: `Unknown team '${team}'. Create it first with create_team.` };
+            }
+            const built = await createChildAgentRuntime(deps, {
+                prompt,
+                subagentType: strArg(args, "subagent_type", false),
+                isolation: strArg(args, "isolation", false),
+                context: strArg(args, "context", false),
+            }, childMaxTurns, ctx.signal);
+            if (!built.ok)
+                return { ok: false, output: built.output };
+            try {
+                const { agentId } = reg.spawn({
+                    teamId: team,
+                    firstPrompt: built.firstPrompt,
+                    runtime: built.runtime,
+                });
+                return {
+                    ok: true,
+                    output: [
+                        `(worker spawned) agent_id=${agentId} name=${built.runtime.agentName}${team ? ` team=${team}` : ""}`,
+                        "Continue it with send_message(to: \"" + agentId + "\", message: …); stop it with stop_worker. You will get its result as a <task-notification> on a future turn.",
+                    ].join("\n"),
+                };
+            }
+            catch (e) {
+                // Capacity refusal etc. → AppError(Tool) folded to ok:false.
+                if (e instanceof AppError) {
+                    // worktree was created inside createChildAgentRuntime; close-on-failure
+                    // happens via finalize() at the registry's next teardown — but since
+                    // spawn never registered the worker, finalize the runtime now.
+                    await built.runtime.finalize().catch(() => { });
+                    await built.runtime.drainPty().catch(() => { });
+                    return { ok: false, output: e.message };
+                }
+                throw e;
+            }
+        },
+    };
+    const sendMessage = {
+        name: SEND_MESSAGE_TOOL_NAME,
+        description: "Send a follow-up instruction to a live worker, CONTINUING it on its existing context (it remembers what it already read/did). `to` is an agent_id, a worker name, or `team:<id>` to broadcast to every worker in a team. If the worker is busy the message queues (FIFO); if it's idle/stopped it resumes. Synthesize the worker's prior findings into a concrete spec before sending — never delegate understanding back to it.",
+        category: "integration",
+        parameters: {
+            type: "object",
+            properties: {
+                to: { type: "string", description: "agent_id, worker name, or 'team:<id>' to broadcast." },
+                message: { type: "string", description: "The follow-up instruction (self-contained, with specifics)." },
+            },
+            required: ["to", "message"],
+        },
+        isConcurrencySafe: () => false,
+        summarize: (args) => {
+            const to = strArg(args, "to", true);
+            const msg = strArg(args, "message", true);
+            const head = msg.length > 60 ? msg.slice(0, 60) + "…" : msg;
+            return `send_message → ${to}: ${head}`;
+        },
+        async execute(args) {
+            const to = strArg(args, "to", true);
+            const message = strArg(args, "message", true);
+            const team = teamTarget(to);
+            if (team !== null) {
+                if (!reg.hasTeam(team))
+                    return { ok: false, output: `Unknown team '${team}'.` };
+                const n = reg.broadcast(team, message);
+                return { ok: true, output: `Broadcast to ${n} worker(s) in team ${team}.` };
+            }
+            const delivered = reg.send(to, message);
+            if (!delivered) {
+                return {
+                    ok: false,
+                    output: `No live worker matches '${to}' (it may have been stopped-and-evicted or never existed). Use list_workers, or spawn_worker a fresh one.`,
+                };
+            }
+            return { ok: true, output: `Message queued for worker ${to}.` };
+        },
+    };
+    const stopWorker = {
+        name: STOP_WORKER_TOOL_NAME,
+        description: "Stop a worker that's going the wrong way: cancels its in-flight work but KEEPS it resumable (a later send_message continues it on the same context). `to` is an agent_id, a worker name, or `team:<id>` to stop every worker in a team.",
+        category: "integration",
+        parameters: {
+            type: "object",
+            properties: {
+                to: { type: "string", description: "agent_id, worker name, or 'team:<id>'." },
+            },
+            required: ["to"],
+        },
+        isConcurrencySafe: () => false,
+        summarize: (args) => `stop_worker → ${strArg(args, "to", true)}`,
+        async execute(args) {
+            const to = strArg(args, "to", true);
+            const team = teamTarget(to);
+            if (team !== null) {
+                if (!reg.hasTeam(team))
+                    return { ok: false, output: `Unknown team '${team}'.` };
+                const n = reg.stopTeam(team);
+                return { ok: true, output: `Stopped ${n} worker(s) in team ${team}.` };
+            }
+            const stopped = reg.stop(to);
+            if (!stopped)
+                return { ok: false, output: `No live worker matches '${to}'.` };
+            return { ok: true, output: `Stopped worker ${to} (resumable with send_message).` };
+        },
+    };
+    const dismissWorker = {
+        name: DISMISS_WORKER_TOOL_NAME,
+        description: "Permanently dismiss a worker you are DONE with — it is closed (its worktree/PTY finalized) and its capacity slot is freed immediately. Unlike stop_worker (which keeps the worker resumable), a dismissed worker cannot be continued. Use this to reclaim a slot when you hit the worker capacity limit and no longer need a finished worker. `to` is an agent_id, a worker name, or `team:<id>` to dismiss every worker in a team.",
+        category: "integration",
+        parameters: {
+            type: "object",
+            properties: {
+                to: { type: "string", description: "agent_id, worker name, or 'team:<id>'." },
+            },
+            required: ["to"],
+        },
+        isConcurrencySafe: () => false,
+        summarize: (args) => `dismiss_worker → ${strArg(args, "to", true)}`,
+        async execute(args) {
+            const to = strArg(args, "to", true);
+            const team = teamTarget(to);
+            if (team !== null) {
+                if (!reg.hasTeam(team))
+                    return { ok: false, output: `Unknown team '${team}'.` };
+                const n = await reg.dismissTeam(team);
+                return { ok: true, output: `Dismissed ${n} worker(s) in team ${team} (slots freed).` };
+            }
+            // Resolve a name → agentId so a name target works (close() is by agentId).
+            const match = reg.listWorkers().find((w) => w.agentId === to || w.name === to);
+            const dismissed = match ? await reg.close(match.agentId) : false;
+            if (!dismissed)
+                return { ok: false, output: `No live worker matches '${to}'.` };
+            return { ok: true, output: `Dismissed worker ${to} (slot freed; not resumable).` };
+        },
+    };
+    const createTeam = {
+        name: CREATE_TEAM_TOOL_NAME,
+        description: "Create a team to group related workers. Returns a team_id; pass it as spawn_worker's `team`, then send_message/stop_worker with `to: \"team:<id>\"` to broadcast / batch-stop.",
+        category: "integration",
+        parameters: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "Human-readable team label." },
+            },
+            required: ["name"],
+        },
+        isConcurrencySafe: () => false,
+        summarize: (args) => `create_team: ${strArg(args, "name", true)}`,
+        async execute(args) {
+            const name = strArg(args, "name", true);
+            const { teamId } = reg.createTeam(name);
+            return { ok: true, output: `(team created) team_id=${teamId} name=${name}` };
+        },
+    };
+    const listWorkers = {
+        name: LIST_WORKERS_TOOL_NAME,
+        description: "List your live workers and their status (running / idle / stopped / failed), optionally filtered by team. Use it to see what's in flight before directing more work.",
+        category: "file-read",
+        parameters: {
+            type: "object",
+            properties: {
+                team: { type: "string", description: "Optional team id to filter by." },
+            },
+        },
+        isConcurrencySafe: () => true,
+        summarize: (args) => {
+            const team = strArg(args, "team", false);
+            return team ? `list_workers (team ${team})` : "list_workers";
+        },
+        async execute(args) {
+            const team = strArg(args, "team", false);
+            const workers = reg.listWorkers(team);
+            if (workers.length === 0) {
+                return { ok: true, output: team ? `No workers in team ${team}.` : "No live workers." };
+            }
+            const lines = workers.map((w) => `- ${w.agentId} "${w.name}" [${w.status}]${w.teamId ? ` team=${w.teamId}` : ""} turns=${w.turnsRun} queued=${w.queued} — ${w.lastMessageHead}`);
+            return { ok: true, output: lines.join("\n") };
+        },
+    };
+    return [spawnWorker, sendMessage, stopWorker, dismissWorker, createTeam, listWorkers];
+}
+//# sourceMappingURL=coordinator-tools.js.map

package/dist/core/coordinator-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinator-tools.js","sourceRoot":"","sources":["../../src/core/coordinator-tools.ts"],"names":[],"mappings":"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"}

package/dist/core/engine.d.ts

@@ -1,4 +1,4 @@
-import { type ApprovalMode, type AsyncTaskRegistry, type BoundaryInjectionQueue, type CancellationToken, type EventBus, type TaskNotification, ModelSelection } from "@chances-ai/runtime";
+import { type ApprovalMode, type AsyncTaskRegistry, type BoundaryInjectionQueue, type NotificationSource, type CancellationToken, type EventBus, type TaskNotification, ModelSelection } from "@chances-ai/runtime";
 import { type Message, type ModelRouter, type Route, type RetryConfig, type ToolCallRequest, type ToolDefinition } from "../ai/index.js";
 import type { SessionManager } from "../session/index.js";
 import type { MemoryStore } from "../memory/index.js";
@@ -126,6 +126,15 @@ export interface AgentEngineOptions {
      * backgrounds never accidentally orphan into a process exit.
      */
     backgroundTasks?: AsyncTaskRegistry;
+    /**
+     * (7.8 §3.4) Persistent coordinator worker registry. A SECOND
+     * {@link NotificationSource} the engine drains alongside `backgroundTasks` at
+     * every turn boundary — a worker's per-message result reaches the coordinator
+     * as a `<task-notification>` exactly like a background subagent's. Undefined on
+     * a normal (non-coordinator) session (drain is a no-op). Per-session in the
+     * isolated serve path, same as `backgroundTasks`.
+     */
+    workerRegistry?: NotificationSource;
     /**
      * (7.7 §4) Per-session steering queue. When provided, the engine drains it at
      * every turn boundary (turn-top + after each tool batch) and injects the
@@ -273,14 +282,19 @@ interface TurnState {
  * `injected*Ids` collections are mutated in place (append-only) by the loop and
  * its hooks; the engine reads them back after the loop to persist + acknowledge.
  */
+/** (7.8 §3.4 — codex R2 M1) Per-source injected-notification tracking. Keyed by
+ * the `NotificationSource` object so each source's ack set is independent — a
+ * cross-source id collision can't shadow or mis-ack a note. Turn-local. */
+export type InjectedNotifs = Map<NotificationSource, Set<string>>;
 export interface LoopRun {
     turnId: string;
     system: string;
     toolDefs: ToolDefinition[];
     /** Accumulator: assistant/tool/steering messages appended as the loop runs. */
     turnMessages: Message[];
-    /** Notification ids already injected (turn-top + mid-turn) — ack after persist. */
-    injectedNotifIds: Set<string>;
+    /** (codex R2 M1) Notification ids already injected this turn, keyed PER source
+     *  (turn-top + mid-turn) — ack the right source's own ids after persist. */
+    injectedNotifIds: InjectedNotifs;
     /** Steering ids already injected — ack after persist. */
     injectedSteerIds: string[];
     /** Soft turn ceiling for THIS run (already clamped to the hard cap). */
@@ -315,7 +329,7 @@ export interface AgentLoopHooks {
     /** Iteration-boundary injections: steering the user queued mid-turn + bg-task
      *  notifications that completed mid-turn (peek-not-drain; ids recorded for the
      *  post-persist ack). pi `getSteeringMessages`. */
-    getBoundaryMessages(injectedNotifIds: Set<string>, injectedSteerIds: string[]): Message[];
+    getBoundaryMessages(injectedNotifIds: InjectedNotifs, injectedSteerIds: string[]): Message[];
     /** When the model returned NO tool calls: a `user`-role reminder to finish
      *  open todos (loop continues) or `null` to let the turn resolve. The inverse
      *  of pi's `shouldStopAfterTurn`. */
@@ -347,8 +361,24 @@ export declare class AgentEngine {
      *  render each as a user message, and append its id to `injectedSteerIds` for
      *  post-persist ack. Peek-not-drain: a cancelled turn re-delivers. */
     private drainSteering;
-    /** (7.7 §4) Iteration-boundary drain: background-task notifications that
-     *  arrived mid-turn (combined render, same as turn-top) PLUS steering. Both
+    /** (7.8 §3.4) The notification sources the engine drains at turn boundaries:
+     *  background subagent tasks AND persistent coordinator workers. Both
+     *  implement {@link NotificationSource}; the engine renders their pending
+     *  `<task-notification>`s together (FIFO within each) and acks EACH source's
+     *  own ids after persist — never broadcasting a global id list (codex R1-§5). */
+    private notificationSources;
+    /** (7.7 §4 / 7.8 §3.4 — codex R2 M1) Collect notifications not yet injected this
+     *  turn, across ALL sources, recording each into its OWN per-source injected set
+     *  as it's taken. The injected tracking is keyed by `NotificationSource` (NOT a
+     *  flat id set) so a hypothetical cross-source id collision can never make one
+     *  source's note shadow another's, nor ack a note that was never injected. */
+    private collectFreshNotifications;
+    /** (7.7 §4 / 7.8 — codex R2 M1) Ack AFTER persist: each source acks EXACTLY the
+     *  ids injected FROM it this turn (per-source set), never a merged global list.
+     *  A cancelled turn (no ack) re-delivers; injected ids are turn-local. */
+    private ackNotifications;
+    /** (7.7 §4) Iteration-boundary drain: notifications that arrived mid-turn
+     *  (combined render across all sources, same as turn-top) PLUS steering. Both
      *  peek-not-drain; ids recorded for post-persist ack. */
     private drainBoundaryInjections;
     /** (7.7 §5.3) Build an incomplete-todos reminder when the model stopped with

package/dist/core/engine.d.ts.map

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

package/dist/core/engine.js

@@ -112,19 +112,62 @@ export class AgentEngine {
         }
         return out;
     }
-    /** (7.7 §4) Iteration-boundary drain: background-task notifications that
-     *  arrived mid-turn (combined render, same as turn-top) PLUS steering. Both
+    /** (7.8 §3.4) The notification sources the engine drains at turn boundaries:
+     *  background subagent tasks AND persistent coordinator workers. Both
+     *  implement {@link NotificationSource}; the engine renders their pending
+     *  `<task-notification>`s together (FIFO within each) and acks EACH source's
+     *  own ids after persist — never broadcasting a global id list (codex R1-§5). */
+    notificationSources() {
+        const out = [];
+        if (this.opts.backgroundTasks)
+            out.push(this.opts.backgroundTasks);
+        if (this.opts.workerRegistry)
+            out.push(this.opts.workerRegistry);
+        return out;
+    }
+    /** (7.7 §4 / 7.8 §3.4 — codex R2 M1) Collect notifications not yet injected this
+     *  turn, across ALL sources, recording each into its OWN per-source injected set
+     *  as it's taken. The injected tracking is keyed by `NotificationSource` (NOT a
+     *  flat id set) so a hypothetical cross-source id collision can never make one
+     *  source's note shadow another's, nor ack a note that was never injected. */
+    collectFreshNotifications(injected) {
+        const out = [];
+        for (const src of this.notificationSources()) {
+            let set = injected.get(src);
+            if (!set) {
+                set = new Set();
+                injected.set(src, set);
+            }
+            for (const n of src.peekPendingNotifications()) {
+                if (set.has(n.taskId))
+                    continue;
+                out.push(n);
+                set.add(n.taskId); // record immediately so the boundary drain won't re-inject
+            }
+        }
+        return out;
+    }
+    /** (7.7 §4 / 7.8 — codex R2 M1) Ack AFTER persist: each source acks EXACTLY the
+     *  ids injected FROM it this turn (per-source set), never a merged global list.
+     *  A cancelled turn (no ack) re-delivers; injected ids are turn-local. */
+    ackNotifications(injected) {
+        for (const src of this.notificationSources()) {
+            const set = injected.get(src);
+            if (set && set.size > 0)
+                src.acknowledgeNotifications([...set]);
+        }
+    }
+    /** (7.7 §4) Iteration-boundary drain: notifications that arrived mid-turn
+     *  (combined render across all sources, same as turn-top) PLUS steering. Both
      *  peek-not-drain; ids recorded for post-persist ack. */
     drainBoundaryInjections(injectedNotifIds, injectedSteerIds) {
         const out = [];
-        const fresh = (this.opts.backgroundTasks?.peekPendingNotifications() ?? []).filter((n) => !injectedNotifIds.has(n.taskId));
+        const fresh = this.collectFreshNotifications(injectedNotifIds);
         if (fresh.length > 0) {
             out.push({
                 role: "user",
                 content: [{ type: "text", text: fresh.map(renderTaskNotificationXml).join("\n") }],
             });
-            for (const n of fresh)
-                injectedNotifIds.add(n.taskId);
         }
         out.push(...this.drainSteering(injectedSteerIds));
         return out;
@@ -211,7 +254,7 @@ export class AgentEngine {
         return this.runTurnImpl(prompt, token, opts.expandMentions !== false, opts.trustedContext);
     }
     async runTurnImpl(prompt, token, expandMentions, trustedContext) {
-        const { tools, session, plugins, backgroundTasks } = this.opts;
+        const { tools, session, plugins } = this.opts;
         const turnId = createId("turn");
         // (3.6) Carry the active session id on `turn:start` so the OTel
         // exporter can stamp `chances.gen_ai.session.id` correctly across
@@ -240,8 +283,10 @@ export class AgentEngine {
         // persisted to `session.messages()`. Acknowledgement (queue removal)
         // happens immediately after `session.appendTurn(turnMessages)`
         // succeeds.
-        const notifications = backgroundTasks?.peekPendingNotifications() ?? [];
-        const notificationIds = notifications.map((n) => n.taskId);
+        // (7.8 §3.4 — codex R2 M1) Collect across ALL notification sources (background
+        // tasks + persistent workers), recording each into its per-source injected set.
+        const injectedNotifIds = new Map();
+        const notifications = this.collectFreshNotifications(injectedNotifIds);
         const turnMessages = [];
         if (notifications.length > 0) {
             const xml = notifications.map(renderTaskNotificationXml).join("\n");
@@ -270,10 +315,9 @@ export class AgentEngine {
             turnMessages.push({ role: "user", content: [{ type: "text", text: trustedContext }] });
         }
         turnMessages.push({ role: "user", content: [{ type: "text", text: prompt }] });
-        // (7.7 §4) Drain any steering queued before this turn started, plus track
-        // which notifications/steering ids have been injected so the iteration-
-        // boundary drain (and the post-persist ack) don't double-count.
-        const injectedNotifIds = new Set(notificationIds);
+        // (7.7 §4) Drain any steering queued before this turn started. `injectedNotifIds`
+        // (above) tracks per-source notification ids; `injectedSteerIds` tracks steering
+        // — both so the iteration-boundary drain + post-persist ack don't double-count.
         const injectedSteerIds = [];
         turnMessages.push(...this.drainSteering(injectedSteerIds));
         const result = { text: "", inputTokens: 0, outputTokens: 0, costUsd: 0 };
@@ -300,9 +344,9 @@ export class AgentEngine {
         // a cancellation between peek and persist leaves both queues intact (the
         // next turn re-delivers). `injectedNotifIds` covers turn-top AND mid-turn
         // notifications; `injectedSteerIds` covers all injected steering.
-        if (injectedNotifIds.size > 0) {
-            backgroundTasks?.acknowledgeNotifications([...injectedNotifIds]);
-        }
+        // (7.8 §3.4) Ack per source, each only its own injected ids (no global
+        // broadcast) — drains across backgroundTasks + workerRegistry uniformly.
+        this.ackNotifications(injectedNotifIds);
         if (injectedSteerIds.length > 0) {
             this.opts.steering?.acknowledge(injectedSteerIds);
         }