@chances-ai/engine 24.0.0

package/dist/core/engine.d.ts

@@ -0,0 +1,268 @@
+import { type ApprovalMode, type AsyncTaskRegistry, type CancellationToken, type EventBus, type TaskNotification, ModelSelection } from "@chances-ai/runtime";
+import { type ModelRouter, type RetryConfig } from "../ai/index.js";
+import type { SessionManager } from "../session/index.js";
+import type { MemoryStore } from "../memory/index.js";
+import type { PermissionGate, ToolRegistry } from "../tools/index.js";
+import type { PluginHost } from "../plugin-api/index.js";
+export interface AgentEngineOptions {
+    bus: EventBus;
+    router: ModelRouter;
+    tools: ToolRegistry;
+    gate: PermissionGate;
+    session: SessionManager;
+    workspaceRoot: string;
+    memory?: MemoryStore;
+    plugins?: PluginHost;
+    /**
+     * (5.3) Session approval-mode getter. Read at the start of every turn (for
+     * the plan-mode system reminder) and per tool call (for the `blockByMode`
+     * pre-check). When omitted the engine behaves as `default` mode. The same
+     * getter is passed to the `PermissionGate`; child engines (`createTaskTool`)
+     * receive it too so a subagent in plan mode is told to stay read-only rather
+     * than discovering it via repeated denials (codex Round-1 SHOULD-FIX #2).
+     */
+    getApprovalMode?: () => ApprovalMode;
+    /**
+     * Mutable model-preference holder. The engine reads it at the start of every
+     * turn, so `/model` switches land on the next request without an engine
+     * rebuild. When omitted, the engine seeds one from the deprecated scalar
+     * fields below for backwards compatibility with v2.x callers.
+     */
+    selection?: ModelSelection;
+    /** @deprecated since v3.0 — pass `selection` instead. Still honored when
+     * `selection` is absent so existing tests / external callers don't break. */
+    preferredModel?: string;
+    /** @deprecated since v3.0 — pass `selection` instead. */
+    preferredProvider?: string;
+    /**
+     * Safety valve against runaway tool loops. Matches claude-code's `maxTurns`
+     * (`src/QueryEngine.ts:154`) and pi's `MAX_TURNS` test convention. When the
+     * loop exhausts this budget without the model returning a final answer, the
+     * engine throws `AppError(Provider, "Reached maximum number of turns (N)")`
+     * — claude-code's terminal-error pattern. Defaults to 12 when omitted; the
+     * CLI threads `ChancesConfig.agent.maxTurns` in here.
+     */
+    maxTurns?: number;
+    /**
+     * @deprecated Renamed to `maxTurns` in 3.0.1 for parity with claude-code /
+     * pi. The old name still works for one minor cycle so any out-of-tree
+     * caller doesn't break silently; removal target is 4.x. New callers should
+     * use `maxTurns`. When both are set, `maxTurns` wins.
+     */
+    maxIterations?: number;
+    /** Override default per-attempt backoff for provider stream retries. */
+    retry?: RetryConfig;
+    /**
+     * When true, the engine does NOT emit `error` events on the shared bus for
+     * its own terminal failures (provider exhaustion, max-turns). It still
+     * throws `AppError` so the caller can surface the failure on its own
+     * channel. Set this for child engines (e.g. the `task` subagent tool) that
+     * share a bus with a parent loop — without it the parent's `lastError`
+     * listener (see `apps/cli/src/commands/prompt.ts:26`) would record the
+     * child's failure as the *parent's* exit code, even when the parent's
+     * overall turn succeeded.
+     *
+     * Telemetry / TUI still see the child's per-call `usage`, `tool:call`, and
+     * `tool:result` frames — only the terminal `error` event is suppressed.
+     * The `tool:result` for the parent's `task` call carries the failure text
+     * (e.g. "Subagent failed: PROVIDER: ..."), which is the contextual story
+     * users actually need.
+     */
+    suppressTerminalErrors?: boolean;
+    /**
+     * Replaces the hardcoded base system prompt with caller-supplied text.
+     * Memory context (`MemoryStore.asSystemContext()`) is still appended after
+     * it. Set by the subagent `task` tool when spawning a catalog persona —
+     * the agent's body becomes the child's prompt INSTEAD of the generic
+     * "You are chances..." base, so a read-only `explore` agent doesn't carry
+     * the parent's "you may modify the workspace" framing into its turn.
+     * (3.3 design doc: codex Round-1 #3.) Undefined → engine keeps the v3.0
+     * baseline.
+     */
+    systemBaseOverride?: string;
+    /**
+     * (3.4) Identity tag for events this engine emits. Child engines (the
+     * `task` subagent tool) set this so subscribers can demultiplex
+     * parent vs. child output on a shared bus. Parent engines leave undefined.
+     * Tagged event variants: `assistant:delta`, `assistant:message`,
+     * `tool:call`, `tool:permission`, `tool:result`, `usage`. Lifecycle
+     * events (`turn:start`, `turn:end`, `error`) are not tagged — child
+     * engines suppress those via `suppressLifecycleEvents`.
+     *
+     * `agentId` is optional (3.6 codex Round-1 MUST-FIX #3): sync subagents
+     * have no registry-issued id (they complete before the parent's
+     * `tool:call`/`tool:result` boundary closes — the parent already
+     * labels them at that level). Background subagents always set it.
+     */
+    agentContext?: {
+        agentId?: string;
+        agentName: string;
+    };
+    /**
+     * (3.4 — codex Round-1 MUST-FIX #2) When true, the engine does NOT emit
+     * `turn:start` / `turn:end` / `error` events on the shared bus. Set for
+     * child engines because the TUI flips its `busy` flag on every `turn:*`
+     * event (`packages/tui/src/view-model.ts:74-101`) — a child's turn
+     * lifecycle would otherwise end the parent's busy state and confuse the
+     * NDJSON / `-p` mode renderers that assume one bus = one conversation.
+     *
+     * `error` is suppressed too because the existing `suppressTerminalErrors`
+     * only gated the engine's *terminal* error emits (provider exhaustion,
+     * max-turns) — but with `agentContext` plumbing children can also emit
+     * mid-turn errors, and those should stay off the shared bus.
+     */
+    suppressLifecycleEvents?: boolean;
+    /**
+     * (3.4) Optional registry of background subagent tasks. When provided:
+     *   - At the top of every `runTurn`, the engine drains queued
+     *     completion notifications and prepends an XML block to the turn's
+     *     user-role message so the model sees them on the next request.
+     *   - The `task` tool is expected to wire the launch path through the
+     *     same registry (handled in `createTaskTool`, not here).
+     * When undefined: drain is a no-op (same as 3.3). The `task` tool's
+     * schema omits `run_in_background`. Used to scope the feature to
+     * interactive `chat` mode — `-p` one-shot mode passes undefined so
+     * backgrounds never accidentally orphan into a process exit.
+     */
+    backgroundTasks?: AsyncTaskRegistry;
+    /**
+     * (3.5) Auto-compaction orchestrator. When provided:
+     *   - After every appendTurn + before turn:end, the engine asks
+     *     `compactor.shouldCompact(...)` with the last provider
+     *     request's `inputTokens`, and `await`s
+     *     `compactor.compact("threshold", token.signal)` when true.
+     *   - On Anthropic overflow errors (`"prompt is too long"` /
+     *     `"request_too_large"` / `"maximum.*context.*length"`),
+     *     the engine triggers `compactor.compact("overflow", ...)`
+     *     once per turn and retries the failed stream.
+     *   - Engine emits `usage:turn` carrying `lastRequestInputTokens`
+     *     BEFORE the compaction await; `turn:end` fires AFTER (codex
+     *     Round-1 MUST-FIX #4 — TUI / slash should not see "turn
+     *     over" while session is still mutating).
+     * When undefined (subagent engines, `-p` one-shot mode), the
+     * engine still emits `usage:turn` but never compacts.
+     */
+    compactor?: import("./compaction/index.js").Compactor;
+    /**
+     * (4.1) Active worktree path for an isolated subagent. When set:
+     *   - `ToolContext.workspaceRoot` and `ToolContext.cwd` BOTH flip to
+     *     `worktreeCwd` for the duration of `runTurn`. `safePath`
+     *     therefore resolves against the worktree tree, not the parent's.
+     *   - The engine wraps `runTurn` body in `runWithCwd(worktreeCwd,
+     *     …)` so descendant tool calls inherit the override transparently
+     *     via AsyncLocalStorage (same pattern claude-code uses in
+     *     `src/utils/cwd.ts`).
+     *   - At every `runTurn` top, `refreshActiveMarker(worktreeCwd)`
+     *     fires so cross-process GC can tell this worktree has a live
+     *     owner.
+     *   - The system prompt gains a paragraph informing the model that
+     *     uncommitted parent changes are invisible here and the parent
+     *     will see the final diff after the task completes.
+     * Set by `task-tool.ts` when `isolation: 'worktree'` is resolved for
+     * the spawning agent. Undefined → no isolation (the 3.x default).
+     */
+    worktreeCwd?: string;
+    /**
+     * (4.2) Optional LSP host wired in at boot. Threaded through to
+     * `ToolContext.lsp` so the `lsp` built-in can reach it without a
+     * module-global. Undefined → tool returns `ok:false` "LSP not
+     * available". codex Round-1 MUST-FIX #1 — keeps the wrapper free
+     * of CLI-boot-state imports.
+     */
+    lsp?: import("../tools/index.js").ToolLspHost;
+    /**
+     * (5.4) Optional MCP resource-mention resolver. When set, `runTurn`
+     * expands `@<server>:<uri>` mentions in DIRECTLY-TYPED user input into a
+     * synthetic resource message before the turn. Injected by boot (closed over
+     * the `McpHost`); typed structurally so `@chances-ai/core` stays decoupled
+     * from `@chances-ai/mcp` (no boundary edge). NOT applied to submitted/prompt
+     * text — see `runTurn`'s `expandMentions` (codex 5.4 R1 M3).
+     */
+    resolveMcpMentions?: (prompt: string, signal: AbortSignal) => Promise<ResolvedMention[]>;
+}
+/**
+ * (5.4) Structural shape of a resolved `@<server>:<uri>` mention — mirrors
+ * `@chances-ai/mcp#McpResolvedResource` without importing it (boundary).
+ */
+export interface ResolvedMention {
+    ref: string;
+    server: string;
+    uri: string;
+    /** Rendered resource content (present on success). */
+    text?: string;
+    /** Why it couldn't be read (mutually exclusive with `text`). */
+    note?: string;
+}
+/** Engine default when no caller-supplied or config-supplied value applies. */
+export declare const DEFAULT_MAX_TURNS = 12;
+/** Default base prompt the engine uses when no `systemBaseOverride` is set.
+ * Exported so tests can assert "is this the default or an agent override?" and
+ * so the doc + plugin authors can read the exact text. */
+export declare const DEFAULT_BASE_PROMPT: string;
+export interface AgentResult {
+    text: string;
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number;
+}
+/**
+ * Mediator over ai/session/tools/memory. Depends only on interfaces (ports), so
+ * any ProviderAdapter or Tool plugs in unchanged. Communicates outward purely by
+ * emitting events on the bus — it never imports the TUI.
+ */
+export declare class AgentEngine {
+    private readonly opts;
+    private readonly selection;
+    constructor(opts: AgentEngineOptions);
+    /**
+     * Exposes the mutable selection so callers — typically slash commands like
+     * `/model` — can update it between turns. Returning the live instance (not a
+     * copy) is intentional: writes must propagate back.
+     */
+    getSelection(): ModelSelection;
+    /** Bus-emit wrapper. Three responsibilities (3.4):
+     *  1. Suppress lifecycle frames (`turn:*`, `error`) when the engine is a
+     *     child (`suppressLifecycleEvents=true`). Codex Round-1 MUST-FIX #2.
+     *  2. Stamp `agentId/agentName` on tagged event variants when an
+     *     `agentContext` was supplied. Skipped silently when undefined.
+     *  3. Forward to `bus.emit` otherwise — fully transparent for parent engines.
+     */
+    private emit;
+    runTurn(prompt: string, token: CancellationToken, opts?: {
+        expandMentions?: boolean;
+    }): Promise<AgentResult>;
+    private runTurnImpl;
+    private runTool;
+    private composeSystem;
+}
+/** (5.3) Inserted into the system prompt while the session approval mode is
+ * `plan`. Tells the model it is read-only and should produce a plan instead of
+ * editing — the same posture claude-code's plan mode enforces. */
+export declare const PLAN_MODE_NOTICE: string;
+/** (4.1) Inserted at the END of the child engine's system prompt when
+ * `worktreeCwd` is set. Tells the model two load-bearing facts: the
+ * worktree starts from HEAD (parent's uncommitted state is invisible),
+ * and writes are sandboxed (parent sees them as a diff after the task
+ * completes, not live). Round-1 SHOULD-FIX #2 wording. */
+export declare const ISOLATED_WORKTREE_NOTICE: string;
+/** Renders one `<task-notification>` XML block, fully entity-escaped so
+ * `result`/`summary` text containing `<`, `>`, `&`, `"`, `'` can't break
+ * the surrounding tag structure or impersonate a different role.
+ *
+ * This is the format the model receives at the top of its next turn
+ * after a background subagent completes. The shape matches the one we
+ * (chances-cli's own host) observe receiving from background research
+ * subagents — claude-code's `<task_notification>` convention, with our
+ * hyphen-separated tag style.
+ */
+export declare function renderTaskNotificationXml(n: TaskNotification): string;
+/**
+ * (5.4) Build the synthetic resource message for `@<server>:<uri>` mentions.
+ * EVERY inserted field — server, uri, body, note — is XML-escaped (codex R1 M5:
+ * a malicious resource could otherwise close the tag and inject instructions),
+ * exactly like `renderTaskNotificationXml`. The resolver already stripped
+ * controls + redacted the body. Returns "" when nothing resolved (the caller
+ * skips the message entirely).
+ */
+export declare function renderMcpResourcesXml(resolved: ResolvedMention[]): string;
+//# sourceMappingURL=engine.d.ts.map

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

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