@chengchenccc/oh-my-agent 0.1.1-rc.1

package/dist/core/runtime/run-runtime.js

@@ -0,0 +1,664 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { debugLog, } from "@chengchenccc/agent-contract";
+import { resolveModelAlias } from "@chengchenccc/ai";
+import { createInMemorySessionStore, createOmaSession, } from "../agent-runtime.js";
+import { isFileTrusted, readTrustedPlugins } from "../plugins/plugin-trust.js";
+import { loadProjectSettings } from "../settings/project-settings.js";
+import { createAskQuestionTool } from "../tools/ask-question.js";
+import { createBashTool, createDdgWebSearchPort, createEditTool, createEvalTool, createGlobTool, createGrepTool, createPortWebFetchTool, createPortWebSearchTool, createReadImageTool, createReadTool, createStdWebFetchPort, createTreeTool, createWriteTool, } from "../tools/index.js";
+import { mountWorkspaceMcpServers, withCallTimeout } from "../tools/mcp-mount.js";
+import { createSkill } from "../tools/skill.js";
+import { createTodo, createTodoReadTool } from "../tools/todo.js";
+import { createFileTodoStore, readTodoFile } from "../tools/todo-store.js";
+import { evaluateWorkflowScript } from "../workflow/workflow-evaluator.js";
+import { createWorkflowExecutor } from "../workflow/workflow-executor.js";
+import { createWorkflowTools, isValidWorkflowName } from "../workflow/workflow-tools.js";
+import { approvalTimeoutMs, withApprovalDeadline } from "./approval.js";
+import { fakeProvider } from "./fake-provider.js";
+import { loadRuntimeCatalog, registerProvidersFromCatalog } from "./runtime-catalog.js";
+import { loadStreamRules } from "./stream-rules.js";
+import { toolFilterAllows } from "./tool-filter.js";
+/** Token estimation via content char/4 (approx 1 token per 4 chars of
+ *  English/code). More accurate than JSON.stringify char/4 which includes
+ *  ~30% syntax overhead from key names, quotes, braces. Counts actual text +
+ *  block content, adds a fixed overhead per message for role/structure
+ *  framing. Swap for a real tokenizer (tiktoken, provider SDK) by replacing
+ *  this function — the ContextBudget.estimate interface is the extension
+ *  point. */
+function estimateMessageTokens(message) {
+    let chars = message.text?.length ?? 0;
+    if (message.blocks) {
+        for (const b of message.blocks) {
+            if (b.type === "text")
+                chars += b.text.length;
+            else if (b.type === "tool_use")
+                chars += JSON.stringify(b.input).length;
+            else if (b.type === "tool_result" && typeof b.content === "string")
+                chars += b.content.length;
+            else if (b.type === "thinking" && typeof b.text === "string")
+                chars += b.text.length;
+        }
+    }
+    // ~4 chars/token for content + 4 tokens framing overhead per message
+    // (role tag, separators — matches Anthropic's documented overhead).
+    return Math.ceil(chars / 4) + 4;
+}
+/** Default native tool timeout (ms) for file/web/bash unless overridden. */
+const DEFAULT_NATIVE_TOOL_TIMEOUT_MS = 30_000;
+function resolveNativeToolTimeout(defaultMs) {
+    const capRaw = process.env.OMA_MAX_TOOL_TIMEOUT_MS;
+    const cap = capRaw ? Number(capRaw) : 0;
+    if (Number.isFinite(cap) && cap > 0)
+        return Math.min(defaultMs, cap);
+    return defaultMs;
+}
+async function withToolTimeout(tool, input, signal, options, defaultMs) {
+    const timeoutMs = resolveNativeToolTimeout(defaultMs);
+    if (timeoutMs <= 0)
+        return tool.execute(input, signal, options);
+    const controller = new AbortController();
+    const onAbort = () => controller.abort();
+    signal?.addEventListener("abort", onAbort, { once: true });
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await withCallTimeout(tool.execute(input, controller.signal, options), tool.name, timeoutMs, signal);
+    }
+    finally {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+    }
+}
+function wrapNativeTool(tool, defaultMs = DEFAULT_NATIVE_TOOL_TIMEOUT_MS) {
+    return {
+        ...tool,
+        timeoutMs: resolveNativeToolTimeout(defaultMs),
+        execute: (input, signal, options) => withToolTimeout(tool, input, signal, options, defaultMs),
+    };
+}
+/** Single provider assembly shared by the CLI catalog (--list-models) and
+ *  Run loops: register built-in providers from the process env. The fake
+ *  deterministic provider is available for tests. */
+export function registerBuiltinProviders(runtime, env = process.env) {
+    if (env.OMA_FAKE_PROVIDER === "1") {
+        runtime.registerProvider(fakeProvider(env));
+        return;
+    }
+    const catalog = loadRuntimeCatalog(env);
+    registerProvidersFromCatalog(runtime, catalog, env);
+}
+/** Build the complete Runtime assembly for exactly ONE Run. The Run's
+ *  in-memory SessionStore is created here (never shared with other Runs);
+ *  the model is resolved per run from the AgentRunSnapshot. */
+export async function assembleRunRuntime(deps) {
+    const store = createInMemorySessionStore();
+    // `.oma/settings.json` P0 knobs are normalized into the process env for
+    // the compatibility shim: the existing env-reading code paths pick them up
+    // without threading a settings object through every consumer.
+    // ponytail: per-process shim; a future refactor can pass settings as a dep.
+    const projectSettings = loadProjectSettings(deps.workspaceRoot);
+    if (projectSettings.maxSteps !== undefined)
+        process.env.OMA_MAX_STEPS = String(projectSettings.maxSteps);
+    if (projectSettings.modelTimeoutMs !== undefined) {
+        process.env.OMA_MODEL_TIMEOUT_MS = String(projectSettings.modelTimeoutMs);
+    }
+    if (projectSettings.mcpTimeoutMs !== undefined) {
+        process.env.OMA_MCP_TIMEOUT_MS = String(projectSettings.mcpTimeoutMs);
+    }
+    if (projectSettings.disableWeb !== undefined) {
+        process.env.OMA_DISABLE_WEB = projectSettings.disableWeb ? "1" : "0";
+    }
+    if (projectSettings.titleEnabled !== undefined) {
+        process.env.OMA_TITLE_ENABLED = projectSettings.titleEnabled ? "1" : "0";
+    }
+    if (projectSettings.memoryExtract !== undefined) {
+        process.env.OMA_MEMORY_EXTRACT = projectSettings.memoryExtract ? "1" : "0";
+    }
+    if (projectSettings.memoryModel !== undefined) {
+        process.env.OMA_MEMORY_MODEL = projectSettings.memoryModel;
+    }
+    if (projectSettings.bashTimeoutMs !== undefined) {
+        process.env.OMA_BASH_TIMEOUT_MS = String(projectSettings.bashTimeoutMs);
+    }
+    if (projectSettings.maxToolTimeoutMs !== undefined) {
+        process.env.OMA_MAX_TOOL_TIMEOUT_MS = String(projectSettings.maxToolTimeoutMs);
+    }
+    const catalog = await deps.modelRuntime.getCatalog();
+    // The Run's model is the ONLY budget/summarizer authority. A catalog-first
+    // model with a different window would compact at the wrong threshold or
+    // overflow the real context.
+    const currentModel = catalog.models.find((m) => `${m.providerId}/${m.modelId}` === resolveModelAlias(deps.modelId));
+    if (!currentModel) {
+        throw new Error(`model not found in catalog: ${deps.modelId}`);
+    }
+    const fileTools = [
+        createReadTool({ cwd: deps.workspaceRoot }),
+        createReadImageTool({ cwd: deps.workspaceRoot }),
+        createTreeTool({ cwd: deps.workspaceRoot }),
+        createGlobTool({ workspaceRoot: deps.workspaceRoot }),
+        createGrepTool({ workspaceRoot: deps.workspaceRoot }),
+    ];
+    if (deps.workspaceAccess === "read_write") {
+        fileTools.push(createWriteTool({ cwd: deps.workspaceRoot }));
+        fileTools.push(createEditTool({ cwd: deps.workspaceRoot }));
+        fileTools.push(createBashTool({ workspaceRoot: deps.workspaceRoot }));
+        fileTools.push(createEvalTool({ workspaceRoot: deps.workspaceRoot }));
+    }
+    // Generic .mcp.json mounting (ADR 0022): user servers + knowledge.
+    // Skips "product-tools" (the manifest path owns it) and names that
+    // collide with the native table. The mounted clients join the run's
+    // teardown set so stdio children never outlive the run.
+    // Standalone gating: an untrusted repo-controlled .mcp.json mounts
+    // nothing (fail-closed) — the mode layer surfaces the warning.
+    let includeWorkspaceMcp = true;
+    if (deps.gateWorkspaceMcp) {
+        const mcpJsonPath = join(deps.workspaceRoot, ".mcp.json");
+        if (existsSync(mcpJsonPath) && !isFileTrusted(mcpJsonPath, readTrustedPlugins())) {
+            includeWorkspaceMcp = false;
+            debugLog("oma", `workspace .mcp.json untrusted; servers not mounted (use /mcp trust)`);
+        }
+    }
+    const mounted = await mountWorkspaceMcpServers(deps.workspaceRoot, new Set(fileTools.map((t) => t.name)), deps.pluginMcpServers ?? [], includeWorkspaceMcp);
+    const closeMounted = mounted.close;
+    // Web tools default ON via the std ports (DDG search + guarded fetch);
+    // NOTE: mounted MCP tools intentionally do NOT join fileTools — they are
+    // appended once (unwrapped; withCallTimeout already binds their per-call
+    // timeout) to nativeToolsPlugin below. Pushing them here too duplicated
+    // every mounted tool and tripped validatePlugins on real servers.
+    if (process.env.OMA_DISABLE_WEB !== "1") {
+        fileTools.push(createPortWebSearchTool(deps.webSearch ?? createDdgWebSearchPort()), createPortWebFetchTool(deps.webFetch ?? createStdWebFetchPort()));
+    }
+    const bashDefault = Number(process.env.OMA_BASH_TIMEOUT_MS) || DEFAULT_NATIVE_TOOL_TIMEOUT_MS;
+    const nativeTools = fileTools.map((t) => wrapNativeTool(t, t.name === "bash" ? bashDefault : DEFAULT_NATIVE_TOOL_TIMEOUT_MS));
+    const nativeToolsPlugin = {
+        name: "native-tools",
+        tools: [...nativeTools, ...mounted.tools],
+    };
+    const plugins = [nativeToolsPlugin, createSkill({ roots: deps.skillRoots })];
+    if (deps.codePlugins?.length) {
+        if (deps.permissionMode !== "deny") {
+            // Native wins on tool-name conflicts (spec conflict matrix).
+            const nativeNames = new Set(plugins.flatMap((p) => (p.tools ?? []).map((t) => t.name)));
+            const askGate = deps.permissionMode === "ask";
+            for (const cp of deps.codePlugins) {
+                const tools = (cp.tools ?? [])
+                    .filter((t) => !nativeNames.has(t.name))
+                    .map((t) => askGate
+                    ? {
+                        ...t,
+                        async execute(args, signal, options) {
+                            if (!deps.approvalHandler) {
+                                return {
+                                    error: `${t.name}: approval required but no pipeline configured`,
+                                    isError: true,
+                                };
+                            }
+                            const verdict = await withApprovalDeadline(deps.approvalHandler({
+                                callId: options?.callId ?? "",
+                                toolName: t.name,
+                                input: args,
+                                source: "permission",
+                            }), approvalTimeoutMs());
+                            if (verdict.decision === "deny") {
+                                return {
+                                    error: `${t.name}: denied — ${verdict.reason ?? "user denied"}`,
+                                    isError: true,
+                                };
+                            }
+                            return t.execute(args, signal, options);
+                        },
+                    }
+                    : t);
+                plugins.push({
+                    name: cp.name,
+                    ...(cp.hooks ? { hooks: cp.hooks } : {}),
+                    ...(tools.length ? { tools } : {}),
+                });
+            }
+        }
+        // permissionMode "deny" drops plugin code components entirely (MVP
+        // enforcement point); native tools are unaffected and the Run proceeds.
+    }
+    // Native ask_question (oh-my-pi style HITL): same conflict rule as todo —
+    // the backend can inject its own MCP ask_question (product surfaces); the
+    // injected one wins, standalone workspaces get the native tool.
+    const hasInjectedAsk = mounted.tools.some((t) => t.name === "ask_question");
+    const askAllowed = deps.toolFilter ? toolFilterAllows(deps.toolFilter, "ask_question") : true;
+    if (!hasInjectedAsk && askAllowed) {
+        plugins.push({
+            name: "oma-native-ask",
+            tools: [createAskQuestionTool()],
+        });
+    }
+    // Native todo (.oma/todo.json): installed when NOTHING else already
+    // provides todo_write (the backend injects its own MCP todo_write into
+    // RPC workspaces — the specific injection wins over the built-in default;
+    // standalone workspaces get the native one). One rule replaces the old
+    // per-mode enableNativeTodo flag.
+    const hasInjectedTodo = mounted.tools.some((t) => t.name === "todo_write");
+    const todoAllowed = deps.toolFilter ? toolFilterAllows(deps.toolFilter, "todo_write") : true;
+    const nativeTodoWanted = !hasInjectedTodo && todoAllowed;
+    if (nativeTodoWanted) {
+        const todoStore = createFileTodoStore(deps.workspaceRoot);
+        const todoBase = createTodo({ sessionId: deps.runId, store: todoStore });
+        plugins.push({
+            name: todoBase.name,
+            hooks: todoBase.hooks,
+            tools: [
+                ...(todoBase.tools ?? []),
+                createTodoReadTool({ sessionId: deps.runId, store: todoStore }),
+            ],
+            meta: [
+                {
+                    name: "Current Tasks",
+                    render: () => {
+                        const items = readTodoFile(deps.workspaceRoot);
+                        if (items.length === 0)
+                            return "None yet. Use todo_write to track tasks.";
+                        const marks = {
+                            pending: "- [ ]",
+                            in_progress: "- [~]",
+                            done: "- [x]",
+                            cancelled: "- [ ]",
+                        };
+                        return items
+                            .map((t) => `${marks[t.status] ?? "- [ ]"} ${t.text} (id: ${t.id})`)
+                            .join("\n");
+                    },
+                },
+            ],
+        });
+    }
+    let activeRun = null;
+    // Resolve the model display identity for a run's ref - used by the Session
+    // to render the per-loop Meta (workspace/model fact line). The Session is
+    // the sole Meta owner; the Run runtime never passes a meta string.
+    const resolveModel = async (modelId) => {
+        const catalog = await deps.modelRuntime.getCatalog();
+        const model = catalog.models.find((m) => `${m.providerId}/${m.modelId}` === resolveModelAlias(modelId));
+        if (!model)
+            throw new Error(`model not found: ${modelId}`);
+        return { provider: model.providerId, id: model.modelId };
+    };
+    // Summarizer: call the RUN's model through ModelRuntime with full Message[]
+    // input and AbortSignal support. Same provider/credentials as the run -
+    // no surprise provider switch, no catalog-first cost surprises. No
+    // summaryModel config until real cost data demands one.
+    const summarize = async (messages, signal) => {
+        const summaryMessages = [
+            {
+                role: "system",
+                text: "Summarize the following conversation messages, preserving tool calls, results, decisions and next steps.",
+            },
+            ...messages,
+        ];
+        const timeoutSignal = AbortSignal.timeout(modelTimeoutMs);
+        const combined = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+        const stream = deps.modelRuntime.stream(currentModel.providerId, currentModel.modelId, summaryMessages, { signal: combined });
+        const iter = stream[Symbol.asyncIterator]();
+        let text = "";
+        try {
+            for (;;) {
+                const next = await nextBounded(iter, combined, timeoutSignal);
+                if (next.done)
+                    break;
+                if (next.value.delta?.type === "text")
+                    text += next.value.delta.text;
+            }
+        }
+        finally {
+            if (!combined.aborted)
+                await iter.return?.().catch(() => { });
+        }
+        return text || "[empty summary]";
+    };
+    // ContextBudget from the RUN model's context window: compaction triggers
+    // at the same threshold the real model would overflow, neither premature
+    // nor too late.
+    const contextBudget = {
+        estimate: (m) => estimateMessageTokens(m),
+        limit: currentModel.contextWindow,
+        triggerRatio: 0.7,
+    };
+    // Wall-clock cap on a single model call: a silent/stuck provider must not
+    // leave the Run in `running` forever. The timeout aborts the call and the
+    // Run fails (no auto-retry). Overridable via env for tests.
+    const modelTimeoutMs = (() => {
+        const raw = process.env.OMA_MODEL_TIMEOUT_MS;
+        return raw ? Number(raw) || 300_000 : 300_000;
+    })();
+    /** Advance an async iterator, racing each chunk against the combined
+     *  signal. Providers that ignore the signal (e.g. a generator sleeping
+     *  forever) can no longer hold the Run hostage: abort rejects immediately
+     *  instead of waiting for the provider to notice. */
+    const nextBounded = async (iter, combined, timeoutSignal) => {
+        if (combined.aborted) {
+            throw new Error(timeoutSignal.aborted ? "model timed out" : "model call aborted");
+        }
+        let settled = false;
+        return new Promise((resolve, reject) => {
+            const onAbort = () => {
+                settled = true;
+                void iter.return?.().catch(() => { });
+                reject(new Error(timeoutSignal.aborted ? "model timed out" : "model call aborted"));
+            };
+            combined.addEventListener("abort", onAbort, { once: true });
+            iter
+                .next()
+                .then((r) => {
+                if (settled)
+                    return; // aborted already; drop the late chunk
+                resolve(r);
+            }, (err) => {
+                if (!settled)
+                    reject(err);
+            })
+                .finally(() => combined.removeEventListener("abort", onAbort));
+        });
+    };
+    // PluginRuntime: gives hooks access to model stream, store, workspace,
+    // emit, and abort signal. Plugins capture config in closures; rt provides
+    // runtime capabilities at call time.
+    // Two-phase: sessionEmit is bound after session creation (the session's
+    // emit method doesn't exist until createOmaSession returns).
+    let sessionEmit = null;
+    // The workflow executor rides the SAME model stream + summarizer as the
+    // main loop; subagents get the file tools only (no workflow/product tools).
+    // Product budget gate (T11a): the Loop freezes its remaining daily budget
+    // on the Run; the executor refuses new spawns once the completed agents'
+    // usage estimate exceeds it. Advisory - the product dailyCap stays the
+    // hard gate. No budget on the run = no gate.
+    let workflowSpentTokens = 0;
+    const workflowUsageAccum = {
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0,
+    };
+    const workflowBudgetGate = () => {
+        const budget = activeRun?.workflowBudgetTokens;
+        if (budget == null)
+            return { allowed: true };
+        if (workflowSpentTokens >= budget) {
+            return { allowed: false, reason: "workflow budget exhausted" };
+        }
+        return { allowed: true };
+    };
+    const workflowExecutor = createWorkflowExecutor({
+        makeSubagentStream: (_sessionId, modelIdOverride, responseFormat) => (messages, signal, tools) => streamModel(messages, signal, tools, modelIdOverride, responseFormat),
+        modelId: deps.modelId,
+        summarize,
+        contextBudget,
+        tools: fileTools,
+        workspaceRoot: deps.workspaceRoot,
+        workspaceAccess: deps.workspaceAccess,
+        budgetGate: workflowBudgetGate,
+        emit: (event) => {
+            if (event.type === "workflow_agent_completed" && event.usage) {
+                const usage = event.usage;
+                if (typeof usage === "object") {
+                    const tokens = (v) => (typeof v === "number" && v > 0 ? v : 0);
+                    const u = usage;
+                    workflowSpentTokens +=
+                        tokens(u.inputTokens) +
+                            tokens(u.outputTokens) +
+                            tokens(u.cacheReadTokens) +
+                            tokens(u.cacheWriteTokens);
+                    workflowUsageAccum.inputTokens += tokens(u.inputTokens);
+                    workflowUsageAccum.outputTokens += tokens(u.outputTokens);
+                    workflowUsageAccum.cacheReadTokens += tokens(u.cacheReadTokens);
+                    workflowUsageAccum.cacheWriteTokens += tokens(u.cacheWriteTokens);
+                }
+            }
+            sessionEmit?.(event);
+        },
+        maxConcurrent: 8,
+        maxTotal: 64,
+    });
+    // Script runs: one workflowId shared by every agent() the script spawns.
+    // The vm evaluator has no fs/network; the executor enforces caps/budget.
+    const runScript = async ({ script, args, }) => {
+        const workflowId = `wf-${crypto.randomUUID()}`;
+        const results = [];
+        sessionEmit?.({
+            type: "workflow_started",
+            workflowId,
+            label: "script",
+            agentCount: 0,
+        });
+        const { value } = await evaluateWorkflowScript({
+            script,
+            args,
+            primitives: {
+                agent: async (prompt, opts) => {
+                    const result = await workflowExecutor.runSubagent({
+                        workflowId,
+                        agentId: randomUUID(),
+                        prompt,
+                        ...(opts?.schema ? { schema: opts.schema } : {}),
+                        ...(opts?.label ? { label: opts.label } : {}),
+                    });
+                    results.push(result);
+                    return result;
+                },
+                pipeline: (items, fn) => Promise.all(items.map(fn)),
+            },
+        });
+        const totalTokens = results.reduce((acc, r) => acc +
+            (r.usage?.inputTokens ?? 0) +
+            (r.usage?.outputTokens ?? 0) +
+            (r.usage?.cacheReadTokens ?? 0) +
+            (r.usage?.cacheWriteTokens ?? 0), 0);
+        const ok = results.every((r) => r.ok);
+        sessionEmit?.({
+            type: "workflow_completed",
+            workflowId,
+            ok,
+            agentCount: results.length,
+            totalTokens,
+        });
+        return { ok, totalTokens, value };
+    };
+    plugins.push({
+        name: "workflow-tools",
+        tools: createWorkflowTools({
+            runWorkflow: (input) => workflowExecutor.runWorkflow(input),
+            runScript,
+            writeScript: (name, content) => {
+                // The name is model-supplied: never treat it as a path segment
+                // (a "../" escape would write outside the workspace).
+                if (!isValidWorkflowName(name)) {
+                    throw new Error(`invalid workflow name (allowed: [a-z0-9-], max 64): ${name}`);
+                }
+                if (deps.workspaceAccess !== "read_write") {
+                    throw new Error("workflow scripts cannot be saved in a read_only workspace");
+                }
+                const dir = join(deps.workspaceRoot, ".oma/workflow");
+                mkdirSync(dir, { recursive: true });
+                writeFileSync(join(dir, `${name}.js`), content);
+            },
+            readScript: async (name) => {
+                if (!isValidWorkflowName(name))
+                    return null;
+                try {
+                    return await Bun.file(join(deps.workspaceRoot, ".oma/workflow", `${name}.js`)).text();
+                }
+                catch {
+                    return null;
+                }
+            },
+            runSubagent: (spec, signal) => workflowExecutor.runSubagent({
+                ...spec,
+                workflowId: `sub-${crypto.randomUUID()}`,
+                agentId: spec.label ?? "sub",
+            }, signal),
+            readAgentDefinition: async (name) => {
+                if (!isValidWorkflowName(name))
+                    return null;
+                // read_only workspaces have no local agent definitions — builtins only.
+                if (deps.workspaceAccess !== "read_write")
+                    return null;
+                try {
+                    return await Bun.file(join(deps.workspaceRoot, ".oma", "agents", `${name}.md`)).text();
+                }
+                catch {
+                    return null;
+                }
+            },
+            listSubagents: () => workflowExecutor.listSubagents(),
+            getSubagentOutput: (handle) => workflowExecutor.getSubagentOutput(handle),
+            stopSubagent: (handle) => workflowExecutor.stopSubagent(handle),
+        }),
+    });
+    const pluginRuntime = {
+        streamModel: (providerId, modelId, messages, opts) => deps.modelRuntime.stream(providerId, modelId, messages, opts),
+        store,
+        sessionId: deps.runId,
+        workspaceRoot: deps.workspaceRoot,
+        emit: (event) => {
+            sessionEmit?.(event);
+        },
+        signal: new AbortController().signal,
+    };
+    // Hoisted so both the main session and workflow subagent sessions share it.
+    async function* streamModel(messages, signal, tools, modelIdOverride, responseFormat) {
+        const run = activeRun;
+        if (!run)
+            throw new Error("no active run: model unresolved");
+        // 3.4: role-pinned model override resolves through the SAME catalog —
+        // an unknown/absent model throws here, which is the authorization
+        // boundary (no bypassing the catalog to mint expensive models).
+        const modelId = modelIdOverride ?? run.model.modelId;
+        const catalog = await deps.modelRuntime.getCatalog();
+        const model = catalog.models.find((m) => `${m.providerId}/${m.modelId}` === resolveModelAlias(modelId));
+        if (!model)
+            throw new Error(`model not found: ${modelId}`);
+        const timeoutSignal = AbortSignal.timeout(modelTimeoutMs);
+        const combined = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+        const reasoningEffort = run.model.reasoningEffort;
+        const reasoningOpts = reasoningEffort === "none"
+            ? { thinking: { type: "disabled" } }
+            : reasoningEffort === "low" || reasoningEffort === "high" || reasoningEffort === "max"
+                ? {
+                    thinking: { type: "adaptive", display: "summarized" },
+                    effort: (reasoningEffort === "max" ? "xhigh" : reasoningEffort),
+                }
+                : {};
+        const stream = deps.modelRuntime.stream(model.providerId, model.modelId, messages, {
+            signal: combined,
+            cacheControl: true,
+            ...reasoningOpts,
+            ...(responseFormat ? { responseFormat } : {}),
+            tools: tools?.map((t) => ({
+                name: t.name,
+                description: t.description,
+                inputSchema: t.inputSchema,
+            })),
+        });
+        const iter = stream[Symbol.asyncIterator]();
+        try {
+            for (;;) {
+                const next = await nextBounded(iter, combined, timeoutSignal);
+                if (next.done)
+                    return;
+                yield next.value;
+            }
+        }
+        finally {
+            if (!combined.aborted)
+                await iter.return?.().catch(() => { });
+        }
+    }
+    // pi's loop has no step cap: termination is the model's natural stop or
+    // user abort. We keep a high safety ceiling (runaway-cost guard) that is
+    // env-overridable; 32 was far too small for real tasks.
+    const maxSteps = Number(process.env.OMA_MAX_STEPS) || 500;
+    // TTSR-style stream rules from .oma/rules/*.md (workspace-scoped).
+    const streamRules = loadStreamRules(deps.workspaceRoot);
+    // Native-tool permission gate (ADR 0020): ask/deny apply to high-risk
+    // native tools. Auto/absent = allow. "deny" blocks outright; "ask" routes
+    // through the SAME approvalHandler as plugin code tools (one pipeline).
+    const HIGH_RISK_NATIVE_TOOLS = new Set(["bash", "write", "edit", "create_file", "mcp__"]);
+    const permissionGate = deps.permissionMode === "auto" || deps.permissionMode === undefined
+        ? undefined
+        : async (toolName, input) => {
+            const isHighRisk = HIGH_RISK_NATIVE_TOOLS.has(toolName) || toolName.startsWith("mcp__");
+            if (!isHighRisk)
+                return undefined;
+            if (deps.permissionMode === "deny") {
+                return { block: true, reason: `${toolName}: blocked by permissionMode=deny` };
+            }
+            // ask
+            if (!deps.approvalHandler) {
+                return {
+                    block: true,
+                    reason: `${toolName}: approval required but no pipeline configured`,
+                };
+            }
+            const verdict = await withApprovalDeadline(deps.approvalHandler({
+                callId: "",
+                toolName,
+                input,
+                source: "permission",
+            }), approvalTimeoutMs());
+            if (verdict.decision === "deny") {
+                return {
+                    block: true,
+                    reason: `${toolName}: denied — ${verdict.reason ?? "user denied"}`,
+                };
+            }
+            return undefined;
+        };
+    // --tools filter (CLI): applied ONCE to the final tool table (native +
+    //  MCP + plugin tools) — the model never sees filtered-out tools.
+    const finalPlugins = deps.toolFilter
+        ? plugins.map((p) => ({
+            ...p,
+            ...(p.tools
+                ? { tools: p.tools.filter((t) => toolFilterAllows(deps.toolFilter, t.name)) }
+                : {}),
+        }))
+        : plugins;
+    const session = createOmaSession({
+        sessionId: deps.runId,
+        store,
+        plugins: finalPlugins,
+        pluginRuntime,
+        maxSteps,
+        maxForceContinues: 4,
+        modelStream: streamModel,
+        summarize,
+        contextBudget,
+        resolveModel,
+        ...(streamRules.length > 0 ? { streamRules } : {}),
+        ...(deps.onPersistMessages ? { onPersistMessages: deps.onPersistMessages } : {}),
+        ...(permissionGate ? { permissionGate } : {}),
+    });
+    // Bind the plugin runtime's emit to the session's emit (two-phase init).
+    sessionEmit = (event) => session.emit(event);
+    return {
+        runId: deps.runId,
+        store,
+        session,
+        summarize,
+        contextBudget,
+        setActiveRun(run) {
+            activeRun = run;
+        },
+        executeWorkflow: (input) => runScript(input),
+        workflowUsage: () => ({ ...workflowUsageAccum }),
+        async close() {
+            // 3.4 Phase 3: background subagents must not outlive the Run.
+            workflowExecutor.abortAllSubagents();
+            // Tear down mounted MCP clients so no child process or connection
+            // outlives the Run. Each close is BOUNDED: a stuck transport (e.g. an
+            // SSE socket that never answers close) must not wedge the child.
+            const closeWithTimeout = (p) => Promise.race([p, new Promise((r) => setTimeout(r, 2000))]);
+            const closePromises = [];
+            closePromises.push(closeWithTimeout(closeMounted()));
+            closePromises.push(closeWithTimeout(store.close()));
+            await Promise.allSettled(closePromises);
+        },
+    };
+}

package/dist/core/runtime/runtime-catalog.d.ts

@@ -0,0 +1,12 @@
+import { type CatalogSpec, type ModelRuntime } from "@chengchenccc/ai";
+/** Read and merge the first available runtime models.yml with BUILTIN_CATALOG.
+ *  Returns BUILTIN_CATALOG unchanged if no file is found. */
+export declare function loadRuntimeCatalog(env?: Record<string, string | undefined>): CatalogSpec;
+/** Deep-merge two catalogs: override providers/models win; new entries added.
+ *  Provider-level fields (api, baseUrl, apiKeyEnv) are overridden when present.
+ *  Within a provider, models merge by id. */
+export declare function mergeCatalogs(base: CatalogSpec, override: CatalogSpec): CatalogSpec;
+/** Register every provider in the catalog whose apiKey env var is set.
+ *  Providers without credentials are silently skipped. */
+export declare function registerProvidersFromCatalog(runtime: ModelRuntime, catalog: CatalogSpec, env: Record<string, string | undefined>): void;
+//# sourceMappingURL=runtime-catalog.d.ts.map

package/dist/core/runtime/runtime-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-catalog.d.ts","sourceRoot":"","sources":["../../../src/core/runtime/runtime-catalog.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,WAAW,EAEhB,KAAK,YAAY,EAIlB,MAAM,kBAAkB,CAAC;AAW1B;6DAC6D;AAC7D,wBAAgB,kBAAkB,CAChC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,WAAW,CAOb;AAED;;6CAE6C;AAC7C,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,GAAG,WAAW,CASnF;AASD;0DAC0D;AAC1D,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,WAAW,EACpB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC,IAAI,CAgBN"}