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

package/dist/core/runtime/fake-provider.js

@@ -0,0 +1,87 @@
+/** Deterministic fake Provider for child-process integration tests. Yields one text
+ *  chunk then a natural stop - no network, no credentials. Registered by the
+ *  Worker when OMA_FAKE_PROVIDER=1 is in its env.
+ *
+ *  Scripted tool calls: when OMA_FAKE_TOOL is set to a JSON array of
+ *  `{ name, input }`, the provider emits one tool_use (with a deterministic
+ *  model tool-use id) per stream call until the script is exhausted, then
+ *  falls back to text. This lets full-stack tests drive real tool execution
+ *  (Product Tools, todo_write) through the real Worker loop. */
+const FAKE_MODEL = {
+    id: "echo",
+    name: "Fake Echo",
+    provider: "fake",
+    api: "anthropic-messages",
+    reasoning: false,
+    input: ["text"],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 200_000,
+    maxTokens: 8192,
+};
+/** Second deterministic model: LOOP.md requires generator.model !=
+ *  evaluator.model, and the child validates the model against the catalog. */
+const FAKE_MODEL_2 = {
+    ...FAKE_MODEL,
+    id: "echo2",
+    name: "Fake Echo 2",
+};
+let toolUseSeq = 0;
+export function fakeProvider(env = process.env) {
+    let script = [];
+    try {
+        const raw = env.OMA_FAKE_TOOL;
+        if (raw)
+            script = JSON.parse(raw);
+    }
+    catch {
+        script = [];
+    }
+    // OMA_FAKE_TOOLS_RECORD=<path>: write the tool names the provider
+    // actually received per request (first request only) — lets integration
+    // tests assert the loop advertised tool schemas to the model.
+    const toolsRecord = env.OMA_FAKE_TOOLS_RECORD;
+    let recorded = false;
+    return {
+        id: "fake",
+        name: "Fake",
+        getModels: () => [FAKE_MODEL, FAKE_MODEL_2],
+        async *stream(model, _messages, opts) {
+            if (toolsRecord && !recorded) {
+                recorded = true;
+                try {
+                    await Bun.write(toolsRecord, JSON.stringify((opts?.tools ?? []).map((t) => t.name)));
+                }
+                catch {
+                    /* record is best-effort */
+                }
+            }
+            const next = script.shift();
+            if (next) {
+                const id = `toolu-fake-${++toolUseSeq}`;
+                yield { delta: { type: "tool_use", id, name: next.name } };
+                yield {
+                    delta: { type: "input_json_delta", id, partial_json: JSON.stringify(next.input) },
+                };
+                yield { usage: { input: 10, output: 3, cacheRead: 1, cacheCreate: 0 } };
+                yield { stopReason: "tool_use" };
+                return;
+            }
+            // OMA_FAKE_THINKING emits a reasoning delta before the text so the
+            // thinking-transcript path (thinking_update events, TUI ctrl+t) is
+            // testable end to end.
+            if (env.OMA_FAKE_THINKING) {
+                yield { delta: { type: "reasoning", text: env.OMA_FAKE_THINKING } };
+            }
+            // Model-dependent text makes `--model` observable end to end.
+            // OMA_FAKE_TEXT overrides it (e.g. a JSON workflow verdict).
+            yield {
+                delta: {
+                    type: "text",
+                    text: env.OMA_FAKE_TEXT ?? (model.id === "echo2" ? "done2" : "done"),
+                },
+            };
+            yield { usage: { input: 10, output: 3, cacheRead: 1, cacheCreate: 0 } };
+            yield { stopReason: "end_turn" };
+        },
+    };
+}

package/dist/core/runtime/logger.d.ts

@@ -0,0 +1,13 @@
+export type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
+export interface Logger {
+    level: LogLevel;
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+export declare function consoleLogger(options?: {
+    level?: LogLevel;
+}): Logger;
+export declare function noopLogger(): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/core/runtime/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../src/core/runtime/logger.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEtE,MAAM,WAAW,MAAM;IACrB,KAAK,EAAE,QAAQ,CAAC;IAChB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACjD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAClD;AAUD,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,QAAQ,CAAA;CAAE,GAAG,MAAM,CAkBpE;AAED,wBAAgB,UAAU,IAAI,MAAM,CAQnC"}

package/dist/core/runtime/logger.js

@@ -0,0 +1,38 @@
+const LEVEL_ORDER = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    silent: 4,
+};
+export function consoleLogger(options) {
+    const level = options?.level ?? "info";
+    return {
+        level,
+        debug(message, ...args) {
+            if (LEVEL_ORDER[level] <= LEVEL_ORDER.debug)
+                console.debug(message, ...args);
+        },
+        info(message, ...args) {
+            if (LEVEL_ORDER[level] <= LEVEL_ORDER.info)
+                console.log(message, ...args);
+        },
+        warn(message, ...args) {
+            if (LEVEL_ORDER[level] <= LEVEL_ORDER.warn)
+                console.warn(message, ...args);
+        },
+        error(message, ...args) {
+            if (LEVEL_ORDER[level] <= LEVEL_ORDER.error)
+                console.error(message, ...args);
+        },
+    };
+}
+export function noopLogger() {
+    return {
+        level: "silent",
+        debug: () => { },
+        info: () => { },
+        warn: () => { },
+        error: () => { },
+    };
+}

package/dist/core/runtime/loop-input.d.ts

@@ -0,0 +1,39 @@
+import type { AgentRunSnapshot, BackendInputMessage, ProjectedHistoryItem, WorkspaceBinding } from "@chengchenccc/agent-contract";
+import type { AppendBatchInput } from "../persistence/session-store.js";
+export interface LoopInputResult {
+    readonly batch: AppendBatchInput;
+    readonly systemPrompt: string;
+}
+/** Cross-boundary input for one loop. Carries only domain facts - NO metaText
+ *  and NO systemPrompt: the OmaSession renders the Meta Message
+ *  internally from run/workspace/plugin/todo state (renderLoopMeta is the sole
+ *  Meta owner), and reads the system prompt from `run.systemPrompt`. */
+export interface CodingLoopInput {
+    readonly history: readonly ProjectedHistoryItem[];
+    readonly input: BackendInputMessage;
+    readonly run: AgentRunSnapshot<"oma">;
+    readonly workspace: WorkspaceBinding;
+    /** Product-run identity, when this run is product-driven (RPC path).
+     *  Standalone CLI runs omit it: the agent has no product identity. */
+    readonly metadata?: {
+        readonly conversationId: string;
+        readonly agentId: string;
+        readonly branchId: string;
+    };
+}
+export interface LoopInputDeps {
+    readonly systemPrompt: string;
+    readonly metaText: string;
+    /** The actual driving input for this loop. Its `message` is persisted as the
+     *  prompt/follow-up entry (never inferred from history); `inputId` is the
+     *  durable idempotency source; `productEntryId`, when present, is written onto
+     *  the appended entry so the same canonical Message is never persisted twice. */
+    readonly input: BackendInputMessage;
+    /** Projected Product history to sync idempotently (productEntryId). */
+    readonly history?: readonly ProjectedHistoryItem[];
+}
+/** Build the append batch for a loop: projected history + one Meta + the
+ *  driving input Message (source = prompt for normal, follow_up otherwise).
+ *  The input Message is preserved verbatim (blocks, role, identity). */
+export declare function buildLoopInput(deps: LoopInputDeps, mode?: "normal" | "follow_up"): LoopInputResult;
+//# sourceMappingURL=loop-input.d.ts.map

package/dist/core/runtime/loop-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-input.d.ts","sourceRoot":"","sources":["../../../src/core/runtime/loop-input.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AACD;;;wEAGwE;AACxE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAClD,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;IACpC,QAAQ,CAAC,GAAG,EAAE,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAC;IACrC;0EACsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAClB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;QAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;KAC3B,CAAC;CACH;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;qFAGiF;IACjF,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;IACpC,uEAAuE;IACvE,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;CACpD;AAED;;wEAEwE;AACxE,wBAAgB,cAAc,CAC5B,IAAI,EAAE,aAAa,EACnB,IAAI,GAAE,QAAQ,GAAG,WAAsB,GACtC,eAAe,CAsCjB"}

package/dist/core/runtime/loop-input.js

@@ -0,0 +1,38 @@
+/** Build the append batch for a loop: projected history + one Meta + the
+ *  driving input Message (source = prompt for normal, follow_up otherwise).
+ *  The input Message is preserved verbatim (blocks, role, identity). */
+export function buildLoopInput(deps, mode = "normal") {
+    const items = [];
+    for (const item of deps.history ?? []) {
+        items.push({
+            type: "message",
+            productEntryId: item.productEntryId,
+            role: item.message.role,
+            source: "product_history",
+            message: item.message,
+            createdAt: Date.now(),
+        });
+    }
+    // Every new loop gets exactly one Meta user message.
+    items.push({
+        type: "message",
+        productEntryId: null,
+        role: "user",
+        source: "meta",
+        message: { role: "user", text: deps.metaText },
+        createdAt: Date.now(),
+    });
+    // The driving input: the full canonical Message, source-tagged by mode.
+    items.push({
+        type: "message",
+        productEntryId: deps.input.productEntryId ?? null,
+        role: deps.input.message.role,
+        source: mode === "follow_up" ? "follow_up" : "prompt",
+        message: deps.input.message,
+        createdAt: Date.now(),
+    });
+    return {
+        batch: { entries: items },
+        systemPrompt: deps.systemPrompt,
+    };
+}

package/dist/core/runtime/message-cache.d.ts

@@ -0,0 +1,16 @@
+import type { Message } from "@chengchenccc/message";
+/** Per-entry token-estimate memoization:
+ *
+ *  Long sessions re-walk the settled branch every turn to compute total
+ *  tokens for threshold-compaction checks. Settled messages (append-only,
+ *  never mutated outside compaction) are estimated once and reused until
+ *  compaction clears the cache.
+ *
+ *  Keys on the session-tree entryId, which is stable and unique. Clear on
+ *  compaction — covered entries are gone, surviving ones may have shifted. */
+export declare class TokenEstimateCache {
+    private readonly cache;
+    estimate(entryId: string, message: Message, estimator: (message: Message) => number): number;
+    clear(): void;
+}
+//# sourceMappingURL=message-cache.d.ts.map

package/dist/core/runtime/message-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-cache.d.ts","sourceRoot":"","sources":["../../../src/core/runtime/message-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAErD;;;;;;;;8EAQ8E;AAC9E,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6B;IAEnD,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,GAAG,MAAM;IAQ5F,KAAK,IAAI,IAAI;CAGd"}

package/dist/core/runtime/message-cache.js

@@ -0,0 +1,23 @@
+/** Per-entry token-estimate memoization:
+ *
+ *  Long sessions re-walk the settled branch every turn to compute total
+ *  tokens for threshold-compaction checks. Settled messages (append-only,
+ *  never mutated outside compaction) are estimated once and reused until
+ *  compaction clears the cache.
+ *
+ *  Keys on the session-tree entryId, which is stable and unique. Clear on
+ *  compaction — covered entries are gone, surviving ones may have shifted. */
+export class TokenEstimateCache {
+    cache = new Map();
+    estimate(entryId, message, estimator) {
+        const cached = this.cache.get(entryId);
+        if (cached !== undefined)
+            return cached;
+        const tokens = estimator(message);
+        this.cache.set(entryId, tokens);
+        return tokens;
+    }
+    clear() {
+        this.cache.clear();
+    }
+}

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

@@ -0,0 +1,10 @@
+import type { BackendModelCatalog } from "@chengchenccc/agent-contract";
+import type { ModelRuntime } from "@chengchenccc/ai";
+/** Map the process ModelRuntime catalog to the Backend model contract.
+ *  Never exposes credentials, headers, Provider objects, or internal runtime
+ *  state — only configured/missing availability. */
+export interface ModelCatalogOptions {
+    modelRuntime: ModelRuntime;
+}
+export declare function buildBackendModelCatalog(opts: ModelCatalogOptions): Promise<BackendModelCatalog>;
+//# sourceMappingURL=model-catalog.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"model-catalog.d.ts","sourceRoot":"","sources":["../../../src/core/runtime/model-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACtF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD;;oDAEoD;AAEpD,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,YAAY,CAAC;CAC5B;AAED,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,mBAAmB,CAAC,CAa9B"}

package/dist/core/runtime/model-catalog.js

@@ -0,0 +1,14 @@
+export async function buildBackendModelCatalog(opts) {
+    const catalog = await opts.modelRuntime.getCatalog();
+    const models = catalog.models.map((entry) => ({
+        id: `${entry.providerId}/${entry.modelId}`,
+        displayName: entry.displayName,
+        reasoning: entry.reasoning,
+        inputModalities: entry.inputModalities,
+        contextWindow: entry.contextWindow,
+        maxOutputTokens: entry.maxOutputTokens,
+        available: entry.available,
+        cost: entry.cost,
+    }));
+    return { backendKind: "oma", models };
+}

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

@@ -0,0 +1,41 @@
+import type { AIMessageChunk, Message } from "@chengchenccc/message";
+import type { SessionStore } from "../persistence/session-store.js";
+import type { OmaLoopEvent } from "./agent-event.js";
+/** Runtime capabilities injected into plugin hooks. Mirrors a subset of
+ *  model stream, store, workspace, event emit.
+ *
+ *  Plugins receive this as the last parameter of each hook, so factory
+ *  closures capture configuration (modelRef, enabled) while runtime
+ *  capabilities come from the `rt` argument. */
+export interface PluginRuntime {
+    /** Stream a model call (bounded by the same modelTimeoutMs as the main
+     *  loop). Plugins use this for side-channel summaries - never for the main
+     *  agent turn. */
+    readonly streamModel: (providerId: string, modelId: string, messages: readonly Message[], opts?: {
+        signal?: AbortSignal;
+    }) => AsyncIterable<AIMessageChunk>;
+    /** Run an ephemeral side-channel model turn: appends `prompt` as a user
+     *  message to the current branch history, streams through the run's model
+     *  (with the same system prompt + tool catalog for prompt cache), collects
+     *  text output, and discards any tool calls. The result is NEVER persisted
+     *  to the session branch — it's a pure side-channel read.
+     *
+     *  An ephemeral side-channel turn. Used by title/summary features so
+     *  plugins don't need to manually construct messages or know the model
+     *  ref. One call: `const text = await rt.runEphemeralTurn(prompt);` */
+    /** Set by the loop (not by external code). Optional on the interface
+     *  so run-runtime/tests don't need a stub. */
+    readonly runEphemeralTurn?: (prompt: string, opts?: {
+        signal?: AbortSignal;
+    }) => Promise<string>;
+    /** Session store (read-only for plugins): branch history, todo state. */
+    readonly store: SessionStore;
+    readonly sessionId: string;
+    /** Run workspace root. */
+    readonly workspaceRoot: string;
+    /** Emit a UI-transient event to the Run SSE (never to History). */
+    readonly emit: (event: OmaLoopEvent) => void;
+    /** The run's abort signal (for graceful shutdown). */
+    readonly signal: AbortSignal;
+}
+//# sourceMappingURL=plugin-runtime.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-runtime.d.ts","sourceRoot":"","sources":["../../../src/core/runtime/plugin-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD;;;;;gDAKgD;AAChD,MAAM,WAAW,aAAa;IAC5B;;sBAEkB;IAClB,QAAQ,CAAC,WAAW,EAAE,CACpB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,KAC5B,aAAa,CAAC,cAAc,CAAC,CAAC;IAEnC;;;;;;;;2EAQuE;IACvE;kDAC8C;IAC9C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAEjG,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,0BAA0B;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IAE7C,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B"}

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

@@ -0,0 +1 @@
+export {};

package/dist/core/runtime/plugin.d.ts

@@ -0,0 +1,86 @@
+import type { AskQuestionInput, AskQuestionResult } from "@chengchenccc/agent-contract";
+import type { Message } from "@chengchenccc/message";
+import type { OmaLoopEvent } from "./agent-event.js";
+import type { ApprovalDecision } from "./approval.js";
+import type { PluginRuntime } from "./plugin-runtime.js";
+export interface PluginTool {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema?: Readonly<Record<string, unknown>>;
+    /** "serial" (default) = must run alone; "concurrent" = read-only, safe to
+     *  run in parallel with other concurrent tools in the same turn. */
+    readonly executionMode?: "serial" | "concurrent";
+    /** Wall-clock timeout for this tool in ms (0 = disabled). Shown in the
+     *  TUI tool card and surfaced on tool_execution_start for live display. */
+    readonly timeoutMs?: number;
+    execute(args: Readonly<Record<string, unknown>>, signal?: AbortSignal, 
+    /** Per-call execution context: the model tool-use id (stable per-run
+     *  idempotency identity for Product Tools). */
+    options?: {
+        callId?: string;
+        /** Streaming partial output (e.g. bash stdout) for live display. */
+        onOutput?: (partial: string) => void;
+        /** HITL: ask the human for an approval decision. Absent = no pipeline
+         *  configured (the tool decides; fail closed itself when sensitive).
+         *  Resolves null when no verdict could be obtained. */
+        request?: (req: {
+            reason?: string;
+        }) => Promise<ApprovalDecision | null>;
+        /** HITL: ask the user structured questions (ask_question tool).
+         *  Absent = no ask pipeline (tool fails closed). Resolves null when
+         *  no answer could be obtained. */
+        ask?: (input: AskQuestionInput) => Promise<AskQuestionResult | null>;
+    }): Promise<Readonly<Record<string, unknown>>>;
+}
+export interface PluginHooks {
+    /** Called ONCE at Run start (after agent_start, before the first model
+     *  turn). Plugins use it for per-Run setup (load state, reset counters). */
+    beforeRun?(messages: readonly Message[], rt: PluginRuntime): void;
+    /** Called ONCE after the entire agent loop ends (all turns done), before
+     *  agent_end. Plugins use this for per-Run summaries. */
+    afterRun?(status: "completed" | "failed" | "stopped", messages: readonly Message[], rt: PluginRuntime): void | Promise<void>;
+    /** Called before each model request; may transform messages. */
+    beforeModel?(messages: readonly Message[], rt: PluginRuntime): readonly Message[];
+    /** Called after each model turn (assistant text persisted, tools executed),
+     *  before turn_end. */
+    afterModel?(messages: readonly Message[], rt: PluginRuntime): void;
+    /** Called before a tool executes. May return `{ block: true, reason }` to
+     *  prevent execution — an error tool result is emitted instead.
+     *  Returning void/undefined = observe only. */
+    beforeTool?(toolName: string, input: unknown, rt: PluginRuntime): undefined | {
+        block?: boolean;
+        reason?: string;
+    };
+    /** Called after a tool executes. May return a UI-transient event OR a
+     *  patch object `{ content?, isError?, terminate? }` that overrides the
+     *  executed result field-by-field. */
+    afterTool?(toolName: string, result: unknown, rt: PluginRuntime): OmaLoopEvent | {
+        content?: unknown;
+        isError?: boolean;
+        terminate?: boolean;
+    } | undefined;
+    /** Rewrite tool call arguments before execution.
+     *  Use for deobfuscation, normalization, or injecting context. */
+    transformToolArgs?(toolName: string, input: unknown, rt: PluginRuntime): unknown;
+    /** Called when the model naturally stops (no more tool calls). A plugin
+     *  can veto by calling cancel() to force one more turn. */
+    beforeStop?(cancel: () => void, rt: PluginRuntime): void;
+    /** Called after the stop decision is finalized. `vetoed=true` means a
+     *  plugin forced the loop to continue; `vetoed=false` means the loop
+     *  accepted the natural stop (afterRun follows). */
+    afterStop?(vetoed: boolean, rt: PluginRuntime): void;
+}
+export interface MetaSectionProvider {
+    readonly name: string;
+    render(): string;
+}
+export interface Plugin {
+    readonly name: string;
+    readonly hooks?: PluginHooks;
+    readonly tools?: readonly PluginTool[];
+    readonly meta?: readonly MetaSectionProvider[];
+}
+export declare function validatePlugins(plugins: readonly Plugin[]): void;
+export declare function renderMeta(plugins: readonly Plugin[]): string;
+export declare function collectTools(plugins: readonly Plugin[]): PluginTool[];
+//# sourceMappingURL=plugin.d.ts.map

package/dist/core/runtime/plugin.d.ts.map

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

package/dist/core/runtime/plugin.js

@@ -0,0 +1,23 @@
+export function validatePlugins(plugins) {
+    const names = new Set();
+    const toolNames = new Set();
+    for (const p of plugins) {
+        if (names.has(p.name))
+            throw new Error(`Duplicate plugin name: ${p.name}`);
+        names.add(p.name);
+        for (const t of p.tools ?? []) {
+            if (toolNames.has(t.name))
+                throw new Error(`Duplicate tool name: ${t.name} (plugin ${p.name})`);
+            toolNames.add(t.name);
+        }
+    }
+}
+export function renderMeta(plugins) {
+    return plugins
+        .flatMap((p) => p.meta ?? [])
+        .map((m) => `## ${m.name}\n${m.render()}`)
+        .join("\n\n");
+}
+export function collectTools(plugins) {
+    return plugins.flatMap((p) => p.tools ?? []);
+}

package/dist/core/runtime/process-tree.d.ts

@@ -0,0 +1,12 @@
+/** Process-tree teardown helper shared by MCP stdio clients.
+
+ *  The MCP SDK's StdioClientTransport.close() only SIGKILLs its direct
+ *  child. npm/npx-style servers spawn grandchildren (npm -> sh -> node)
+ *  that inherit the stdio pipes; once the direct child dies they are
+ *  reparented to init, so a post-close pgrep -P walk cannot find them.
+ *  Collect the whole descendant tree BEFORE closing, then SIGKILL every
+ *  pid after the SDK close. */
+export declare function collectDescendants(pid: number): number[];
+/** Collect pid + descendants, then SIGKILL them all (best-effort). */
+export declare function killProcessTree(pid: number): void;
+//# sourceMappingURL=process-tree.d.ts.map

package/dist/core/runtime/process-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-tree.d.ts","sourceRoot":"","sources":["../../../src/core/runtime/process-tree.ts"],"names":[],"mappings":"AAAA;;;;;;;+BAO+B;AAC/B,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBxD;AAED,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CASjD"}

package/dist/core/runtime/process-tree.js

@@ -0,0 +1,40 @@
+/** Process-tree teardown helper shared by MCP stdio clients.
+
+ *  The MCP SDK's StdioClientTransport.close() only SIGKILLs its direct
+ *  child. npm/npx-style servers spawn grandchildren (npm -> sh -> node)
+ *  that inherit the stdio pipes; once the direct child dies they are
+ *  reparented to init, so a post-close pgrep -P walk cannot find them.
+ *  Collect the whole descendant tree BEFORE closing, then SIGKILL every
+ *  pid after the SDK close. */
+export function collectDescendants(pid) {
+    const descendants = [];
+    const queue = [pid];
+    while (queue.length > 0) {
+        const parent = queue.shift();
+        const out = Bun.spawnSync(["pgrep", "-P", String(parent)], { stdout: "pipe" })
+            .stdout.toString()
+            .trim();
+        if (!out)
+            continue;
+        for (const line of out.split("\n")) {
+            const child = Number(line);
+            if (child > 0) {
+                descendants.push(child);
+                queue.push(child);
+            }
+        }
+    }
+    return descendants;
+}
+/** Collect pid + descendants, then SIGKILL them all (best-effort). */
+export function killProcessTree(pid) {
+    const tree = [pid, ...collectDescendants(pid)];
+    for (const target of tree) {
+        try {
+            process.kill(target, "SIGKILL");
+        }
+        catch {
+            /* already gone */
+        }
+    }
+}

package/dist/core/runtime/prompt.d.ts

@@ -0,0 +1,23 @@
+import type { Plugin } from "./plugin.js";
+/** Inputs for rendering the per-loop <system-reminder> Meta user message.
+ *  Runtime facts only: plugin-loaded meta sections (skill index) and the
+ *  workspace/model echo. Product-side content never rides this channel -
+ *  backend-owned identity/config lives in the workspace files the system
+ *  prompt reads (ADR 0003). */
+export interface LoopMetaInput {
+    readonly plugins: readonly Plugin[];
+    readonly workspace: {
+        readonly root: string;
+        readonly cwd?: string;
+    };
+    /** Resolved model display identity for the workspace/model fact line.
+     *  Kept minimal so Meta rendering does not depend on a full Model type. */
+    readonly model?: {
+        readonly provider: string;
+        readonly id: string;
+    };
+}
+/** Render the unified <system-reminder> Meta user message from runtime facts.
+ *  Empty sections are omitted. The structure follows oma-prompt.md. */
+export declare function renderLoopMeta(input: LoopMetaInput): string;
+//# sourceMappingURL=prompt.d.ts.map

package/dist/core/runtime/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../../src/core/runtime/prompt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;+BAI+B;AAC/B,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACrE;+EAC2E;IAC3E,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;CACrE;AAQD;uEACuE;AACvE,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAmB3D"}

package/dist/core/runtime/prompt.js

@@ -0,0 +1,29 @@
+function section(heading, body) {
+    const trimmed = body.trim();
+    if (!trimmed)
+        return null;
+    return `# ${heading}\n\n${trimmed}`;
+}
+/** Render the unified <system-reminder> Meta user message from runtime facts.
+ *  Empty sections are omitted. The structure follows oma-prompt.md. */
+export function renderLoopMeta(input) {
+    const sections = [];
+    // Plugin Meta sections (skill index, todo helper, etc.)
+    const pluginSections = input.plugins
+        .flatMap((p) => p.meta ?? [])
+        .map((m) => section(m.name, m.render()))
+        .filter((s) => s !== null);
+    sections.push(...pluginSections);
+    // Workspace / runtime facts
+    const wsParts = [`Workspace root: ${input.workspace.root}`];
+    if (input.workspace.cwd)
+        wsParts.push(`Working directory: ${input.workspace.cwd}`);
+    if (input.model)
+        wsParts.push(`Model: ${input.model.provider}/${input.model.id}`);
+    const ws = section("Workspace", wsParts.join("\n"));
+    if (ws)
+        sections.push(ws);
+    if (sections.length === 0)
+        return "";
+    return `<system-reminder>\n${sections.join("\n\n")}\n</system-reminder>`;
+}

package/dist/core/runtime/prompts.d.ts

@@ -0,0 +1,16 @@
+/** oma's own prompt layer (mirrors omp's src/prompts layout): base
+ *  identity + safety + memory discipline live here as md files; workspace
+ *  files (AGENTS.md / SOUL.md / USER.md + knowledge index) remain the
+ *  agent-specific layer and are appended when present. Explicit
+ *  run-input systemPrompt (Loop scopes) still wins wholesale — callers
+ *  bypass this builder. */
+export declare function buildSystemPrompt(input: {
+    workspacePrompt?: string;
+    cwd: string;
+    /** Pre-read memory summary (workspace memory/memory_summary.md). */
+    memorySummary?: string;
+}): string;
+/** Workspace memory summary for prompt injection (absent when the agent
+ *  has never written memories). */
+export declare function readMemorySummary(cwd: string): string | undefined;
+//# sourceMappingURL=prompts.d.ts.map

package/dist/core/runtime/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/core/runtime/prompts.ts"],"names":[],"mappings":"AAKA;;;;;2BAK2B;AAC3B,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,MAAM,CAgBT;AAED;mCACmC;AACnC,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAOjE"}