@jungjaehoon/mama-core 2.4.1 → 4.0.0

package/dist/runtime/runtime-process.js

@@ -0,0 +1,206 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CodexRuntimeProcess = void 0;
+const events_1 = require("events");
+const codex_app_server_process_js_1 = require("./drivers/codex-app-server-process.js");
+const codex_auxiliary_tools_js_1 = require("./drivers/codex-auxiliary-tools.js");
+/**
+ * Session-persistent Codex wrapper with the same minimal contract used by
+ * multi-agent runtime (sendMessage/isReady/stop + idle events).
+ *
+ * Implements both AgentRuntimeProcess (multi-agent) and IModelRunner (agent-loop).
+ * Uses one Codex app-server connection and multiplexes durable threads by
+ * session key. Different sessions may run concurrently; turns for the same
+ * session are serialized by CodexAppServerProcess.
+ */
+class CodexRuntimeProcess extends events_1.EventEmitter {
+    backendType = 'codex';
+    /** codex app-server spawns native subagents and reports the spawn via onSubagentStart. */
+    supportsNativeSubagents = true;
+    options;
+    appServer;
+    auxiliaryToolBridge;
+    defaultSessionKey;
+    systemPrompt;
+    stopped = false;
+    activeRequests = 0;
+    subagentCompletionAcceptance = null;
+    subagentCompletionAcceptanceRequired = false;
+    // ─── Metrics tracking ───
+    _requestCount = 0;
+    _failureCount = 0;
+    _totalLatencyMs = 0;
+    _lastRequestAt = null;
+    constructor(options) {
+        super();
+        this.options = { ...options };
+        this.defaultSessionKey = options.defaultSessionKey ?? 'default';
+        this.systemPrompt = options.systemPrompt ?? '';
+        this.appServer = new codex_app_server_process_js_1.CodexAppServerProcess({
+            hostRootDir: options.hostRootDir,
+            sessionKey: this.defaultSessionKey,
+            model: options.model ?? 'gpt-5.4',
+            systemPrompt: this.systemPrompt,
+            cwd: options.cwd ?? process.cwd(),
+            sandbox: options.sandbox ?? 'workspace-write',
+            command: options.command,
+            requestTimeout: options.requestTimeout,
+            codexHome: options.codexHome,
+            isolatedHome: options.isolatedHome,
+            registryRoot: options.registryRoot,
+            mcpConfigPath: options.mcpConfigPath,
+            authSourcePath: options.authSourcePath,
+            effort: options.effort,
+            shellTool: options.shellTool,
+            webSearch: options.webSearch,
+            shellEnvironment: options.shellEnvironment,
+            processEnv: options.processEnv,
+            deniedReadPaths: options.deniedReadPaths,
+            allowLoginShell: options.allowLoginShell,
+            // A completed child is accepted by the consumer's durable intake before the
+            // driver forgets it. Started events remain observational.
+            onSubagentEvent: (event) => {
+                if (event.kind === 'completed') {
+                    if (this.subagentCompletionAcceptanceRequired && !this.subagentCompletionAcceptance) {
+                        throw new Error('Subagent completion acceptance is detached');
+                    }
+                    this.subagentCompletionAcceptance?.(event);
+                }
+                try {
+                    this.emit('subagent', event);
+                }
+                catch (error) {
+                    console.warn(`[CodexRuntimeProcess] subagent observer failed: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            },
+            createSubagentBridge: options.createSubagentBridge,
+        });
+        this.auxiliaryToolBridge = options.auxiliaryToolPolicy
+            ? (0, codex_auxiliary_tools_js_1.createCodexAuxiliaryToolBridge)({
+                ...options.auxiliaryToolPolicy,
+                executeCommand: (command, cwd, roots, signal) => this.appServer.executeSandboxedCommand(command, cwd, roots, signal),
+            })
+            : undefined;
+    }
+    /** Synchronous durable acceptance of child completion, before driver cleanup. */
+    registerSubagentCompletionAcceptance(accept) {
+        if (this.subagentCompletionAcceptance) {
+            throw new Error('Subagent completion acceptance is already registered');
+        }
+        this.subagentCompletionAcceptanceRequired = true;
+        this.subagentCompletionAcceptance = accept;
+        return () => {
+            if (this.subagentCompletionAcceptance === accept)
+                this.subagentCompletionAcceptance = null;
+        };
+    }
+    // ─── IModelRunner.prompt() ─────────────────────────────────────────────
+    async prompt(content, callbacks, options) {
+        return this.execute(content, callbacks, options);
+    }
+    steer(content, target, options) {
+        return this.appServer.steer(content, target, options?.sessionKey ?? options?.sessionId ?? this.defaultSessionKey, options?.beforeSend);
+    }
+    getSessionPolicyStatus(options) {
+        return this.appServer.getSessionPolicyStatus({
+            sessionKey: options.sessionKey ?? options.sessionId ?? this.defaultSessionKey,
+            model: options.model ?? this.options.model,
+            systemPrompt: options.systemPrompt ?? this.systemPrompt,
+            requestTimeout: options.requestTimeout ?? this.options.requestTimeout,
+            policyFingerprint: options.sessionPolicyFingerprint,
+            restrictedReadRoots: options.restrictedReadRoots,
+            cwd: options.cwd,
+            resumeSession: options.resumeSession,
+            hostToolBridge: options.hostToolBridge ?? this.auxiliaryToolBridge,
+        });
+    }
+    resetSession(sessionId, sessionKey) {
+        return this.appServer.reset(sessionKey ?? sessionId ?? this.defaultSessionKey);
+    }
+    // ─── AgentRuntimeProcess.sendMessage() ─────────────────────────────────
+    async sendMessage(content, callbacks) {
+        return this.execute(content, callbacks);
+    }
+    async execute(content, callbacks, promptOptions) {
+        if (this.stopped) {
+            throw this.notifyError(new Error('Process is dead'), callbacks);
+        }
+        this.activeRequests++;
+        const startTime = Date.now();
+        this._requestCount++;
+        this._lastRequestAt = startTime;
+        try {
+            const normalized = await this.appServer.prompt(content, callbacks, {
+                nativeInputId: promptOptions?.nativeInputId,
+                sessionKey: promptOptions?.sessionKey ?? promptOptions?.sessionId ?? this.defaultSessionKey,
+                model: promptOptions?.model ?? this.options.model,
+                systemPrompt: promptOptions?.systemPrompt ?? this.systemPrompt,
+                requestTimeout: promptOptions?.requestTimeout ?? this.options.requestTimeout,
+                policyFingerprint: promptOptions?.sessionPolicyFingerprint,
+                restrictedReadRoots: promptOptions?.restrictedReadRoots,
+                cwd: promptOptions?.cwd,
+                resumeSession: promptOptions?.resumeSession,
+                hostToolBridge: promptOptions?.hostToolBridge ?? this.auxiliaryToolBridge,
+                resumeInstructions: promptOptions?.resumeInstructions,
+                preparePrompt: promptOptions?.preparePrompt,
+                promptTelemetry: promptOptions?.promptTelemetry,
+            });
+            this._totalLatencyMs += Date.now() - startTime;
+            callbacks?.onFinal?.({ content: normalized.response, toolUseBlocks: [] });
+            return normalized;
+        }
+        catch (err) {
+            this._failureCount++;
+            this._totalLatencyMs += Date.now() - startTime;
+            throw this.notifyError(err, callbacks);
+        }
+        finally {
+            this.activeRequests--;
+            if (!this.stopped && this.activeRequests === 0) {
+                this.emit('idle');
+            }
+        }
+    }
+    notifyError(error, callbacks) {
+        const normalized = error instanceof Error ? error : new Error(String(error));
+        try {
+            callbacks?.onError?.(normalized);
+        }
+        catch {
+            // Consumer callback failures must not replace the model failure.
+        }
+        return normalized;
+    }
+    // ─── IModelRunner session management ───────────────────────────────────
+    setSessionId(id) {
+        this.defaultSessionKey = id;
+    }
+    setSystemPrompt(prompt) {
+        this.systemPrompt = prompt;
+    }
+    // ─── IModelRunner health & metrics ─────────────────────────────────────
+    isReady() {
+        return !this.stopped;
+    }
+    isHealthy() {
+        return !this.stopped;
+    }
+    getMetrics() {
+        return {
+            requestCount: this._requestCount,
+            failureCount: this._failureCount,
+            avgLatencyMs: this._requestCount > 0 ? Math.round(this._totalLatencyMs / this._requestCount) : 0,
+            lastRequestAt: this._lastRequestAt,
+        };
+    }
+    async stop() {
+        this.stopped = true;
+        await this.appServer.stop();
+        this.emit('close', 0);
+    }
+    getSessionId() {
+        return this.appServer.getThreadId(this.defaultSessionKey) ?? '';
+    }
+}
+exports.CodexRuntimeProcess = CodexRuntimeProcess;
+//# sourceMappingURL=runtime-process.js.map

package/dist/runtime/runtime.d.ts

@@ -0,0 +1,278 @@
+import type { ContentBlock, PromptCallbacks } from './drivers/types.js';
+import type { NativeTurnResult } from './native-turn.js';
+import type { ActionSessionFacts } from '../action-contracts.js';
+import type { ActionCatalog } from '../api/catalog.js';
+import type { ActionDispatcher } from '../api/dispatch.js';
+import type { TextCompletion } from './text-completion.js';
+import type { JudgmentAccess } from '../knowledge/judgments.js';
+import type { DatabaseAdapter } from '../db-manager.js';
+import type { NativeInputDispatch, NativeInputReceipt } from './drivers/types.js';
+import type { NativeTurnResultRecord } from './native-input-journal.js';
+import { type IpcRequest } from '../client/ipc.js';
+import { Mailbox, type MailboxRow, type Stimulus, type StimulusKind } from './mailbox.js';
+/** The paths product assembly must state — the runtime never derives them. */
+export interface RuntimePaths {
+    /** Private Unix socket the action catalog is served on. */
+    socketPath: string;
+}
+/**
+ * One caller of this runtime. The credential file is what names the principal:
+ * whoever presents that token is that principal and gets exactly its access.
+ * The path is stated by the product for the same reason every other path is —
+ * core composing `<dir>/<principalId>` would let a principal's name choose a
+ * file.
+ */
+export interface RuntimePrincipal {
+    access: JudgmentAccess;
+    /** Rotated-per-boot token file (0600) this principal's callers present. */
+    credentialPath: string;
+    /**
+     * The run this principal's calls answer to, when its host can name one.
+     *
+     * An action whose authority is the run — execution evidence — is uncallable
+     * on a surface that names none, and a socket cannot derive a run from a
+     * request. The host that assembles the principal states it here, once, beside
+     * the access; a host that cannot name it omits it and its calls stay honestly
+     * unattributed.
+     */
+    runEvidenceScope?: ActionSessionFacts['runEvidenceScope'];
+}
+/**
+ * The harness this runtime opened, from the outside.
+ *
+ * §4.3 gives `runtime.start` the DB, the native session, the model and the
+ * socket, and gives `stop` exactly what start opened. The session itself is
+ * built by product assembly - which harness, which workspace, which persona is
+ * the product's statement - and handed here so that ONE subject decides when it
+ * is alive. Before this, shutdown stopped the loop, disposed the session pool
+ * and closed the socket as three separate steps in one function, and the order
+ * between them was that function's private knowledge.
+ */
+export interface NativeInvocationOptions {
+    nativeInputId?: string;
+    onModelRunStarted?: (modelRunId: string) => void;
+    prepareSessionContent?: (session: import('./drivers/types.js').NativeSessionState) => Promise<ContentBlock[]>;
+    streamCallbacks?: PromptCallbacks;
+}
+export interface NativeSessionHandle {
+    /** One request to the native harness; model/tool iteration remains inside that harness. */
+    runTurn?(content: ContentBlock[], request?: NativeInvocationOptions): Promise<NativeTurnResult>;
+    /** Retire the native context and its pool route, preserving durable product records. */
+    resetSession?(sessionKey: string): Promise<void>;
+    /** Add input to the exact active turn; the runtime journals this input separately. */
+    steer?(content: string, target: NativeInputReceipt, sessionKey: string, beforeSend?: () => void): Promise<NativeInputReceipt>;
+    /** Release the harness and the sessions it holds. Called once, by `stop`. */
+    stop(): Promise<void>;
+}
+/**
+ * A delivery that must NOT be tried again.
+ *
+ * Retry is the runtime's default because most failures are transient. Some are
+ * not: an external effect whose outcome is unknown cannot be replayed on a
+ * guess (§4.3), and a stimulus whose delivery already spent one must park where
+ * a person can see it rather than repeat it. Throwing this from `deliver` says
+ * exactly that — park the row dead, spend no attempt, and name it through
+ * `onDead`.
+ */
+export declare class StimulusQuarantine extends Error {
+    constructor(reason: string);
+}
+/**
+ * How an accepted stimulus reaches the loop.
+ *
+ * The runtime journals dispatch before native IO and ACKs the native receipt.
+ * Returning from `deliver` settles the consumer adapter; it does not prove a
+ * judgment or an external effect. After dispatch, failures require reconciliation.
+ * Only failures known to precede dispatch remain eligible for automatic retry.
+ *
+ * This is delivery, not a second turn loop: what runs inside `deliver` is the
+ * native session the product already has, with its own resume, steering and
+ * turn observation. Nothing here interprets the stimulus, and nothing here
+ * decides a turn is finished — an ack says the loop took it and no more.
+ */
+export interface NativeDeliveryContext {
+    nativeInputId: string;
+    /** Read the one final result for a shared turn under this input's principal. */
+    resultForReceipt(receipt: NativeInputReceipt): NativeTurnResultRecord | null;
+    run<TRequest extends object>(content: ContentBlock[], request?: TRequest & NativeInvocationOptions): Promise<NativeTurnResult>;
+    /** Native steer acceptance, never a model result or an effect receipt. */
+    steer(content: string, target: NativeInputReceipt, sessionKey: string): Promise<NativeInputReceipt>;
+    wasDispatched(): boolean;
+    /** Must persist successfully before writing the input to the native transport. */
+    onInputDispatch(input: NativeInputDispatch): void;
+    /** Native acknowledgement, distinct from model completion and external effects. */
+    onAccepted(receipt: NativeInputReceipt): void;
+}
+export interface StimulusDelivery {
+    deliver(row: MailboxRow, context: NativeDeliveryContext): Promise<void>;
+    /** Reuse recorded results only. Never submit the input to a model again. */
+    reconcile?(row: MailboxRow): Promise<'settled' | 'unresolved'>;
+    onUncertain?(row: MailboxRow, reason: string): void | Promise<void>;
+    /** Consumer ports may still be opening; keep accepted inputs without spending attempts. */
+    ready?(): boolean;
+    /**
+     * A row this runtime parked dead, named once, as it happens.
+     *
+     * The runtime owns the claim and the retry, so it is the only subject that
+     * knows a stimulus was lost for good. A consumer that had to discover its own
+     * losses by re-reading the table would be claiming rows again to find them -
+     * which is the second claimer this door exists to remove.
+     */
+    onDead?(row: MailboxRow, reason: string): void | Promise<void>;
+    /**
+     * Kinds delivered ahead of the rest. §4.3 forbids a host FIFO in which the
+     * person's current request waits behind a mass replay; stating the owner's
+     * own message here is what keeps that from happening.
+     */
+    prefer?: readonly StimulusKind[];
+    /** How long a claim may go unacked before it returns to pending. */
+    leaseMs?: number;
+    /** How many rows one tick delivers before yielding. */
+    maxPerTick?: number;
+    /** Bound inputs waiting for native ACK; accepted model results do not consume this window. */
+    maxPendingInputs?: number;
+    /**
+     * How often to look when nothing has been accepted. `0` means only on accept.
+     *
+     * This is the floor under acceptance, not the way work normally arrives, so
+     * it is paced to the shortest retry backoff rather than to latency: an accept
+     * drains immediately, and nothing else becomes deliverable between ticks
+     * except a retry whose minimum wait is a minute.
+     */
+    intervalMs?: number;
+}
+/**
+ * What acceptance means, and what it does not.
+ *
+ * `accepted` says the stimulus is durable and will be delivered. It is not a
+ * claim that anything has been read, decided or done — v7 §4.4 is explicit that
+ * a delivery ACK is not a work receipt, and this receipt is one step earlier
+ * than that. `duplicate` says every ref the producer stated was already
+ * durable, so there is no new row and nothing was lost.
+ */
+export interface StimulusReceipt {
+    /** The durable row, or `null` when the stimulus was already held. */
+    inputId: string | null;
+    state: 'accepted' | 'duplicate';
+}
+export interface StartRuntimeOptions {
+    paths: RuntimePaths;
+    catalog: ActionCatalog;
+    dispatch: ActionDispatcher;
+    /**
+     * Every principal this runtime serves, each with its own credential file.
+     * The credential is a bearer token for local session proof only; it is never
+     * written to prompts, shared env, or logs. Two principals may not share a
+     * credential path — the token would no longer name one caller.
+     */
+    principals: readonly RuntimePrincipal[];
+    /**
+     * Passed through to the socket server — host-stated call-site facts for
+     * calls on this socket (e.g. the surface name and the credential binding
+     * hash). Facts the socket cannot truthfully state stay absent.
+     */
+    sessionFacts?: (access: JudgmentAccess, request: IpcRequest) => ActionSessionFacts | undefined;
+    /** Passed through to the socket server — reclaim a dead socket file, refuse a live one. */
+    reclaimStaleSocket?: boolean;
+    /**
+     * The one model this runtime opens, for the actions that need text back.
+     *
+     * A library that opens its own model decides for every host that installs it
+     * (§2.1). Absent means this runtime has no model to ask, and the actions
+     * that would have used one say so rather than answering as if they had.
+     */
+    runner?: TextCompletion;
+    /**
+     * The store the durable intake is opened against.
+     *
+     * Stated by the product for the same reason every path is: core does not
+     * choose which database a consumer's mailbox lives in. Absent means this
+     * runtime has no intake, and `accept` refuses instead of quietly dropping a
+     * stimulus whose producer believes it is now durable.
+     */
+    mailbox?: {
+        adapter: DatabaseAdapter;
+        clock?: () => number;
+    };
+    /**
+     * Where an accepted stimulus goes. Absent means this runtime accepts and
+     * keeps but hands nothing on — the store is then drained by whoever states
+     * they own it, and `drainOnce` is the door they use.
+     */
+    delivery?: StimulusDelivery;
+    /**
+     * The harness this runtime owns for its lifetime.
+     *
+     * Absent means this runtime serves actions and keeps stimuli but opened no
+     * model session - an MCP-only profile is exactly that, and it should not
+     * pretend to close one.
+     */
+    nativeSession?: NativeSessionHandle;
+}
+export interface RuntimeHandle {
+    /** Internal host port: only a currently claimed input may invoke the native session. */
+    runNative<TRequest extends object>(nativeInputId: string, content: ContentBlock[], request?: TRequest & NativeInvocationOptions): Promise<NativeTurnResult>;
+    socketPath: string;
+    /** The model this runtime opened, or undefined when it opened none. */
+    runner?: TextCompletion;
+    /**
+     * The durable intake this runtime opened, for the consumer that drains it.
+     *
+     * One store, opened once, by the subject that owns the loop's material. A
+     * product that constructed its own would have two openers of one table and
+     * no single place that says when it exists.
+     */
+    mailbox?: Mailbox;
+    /**
+     * The one door a stimulus enters by. Durable on return, and nothing else.
+     *
+     * Refuses — loudly — a principal this runtime does not serve, an unknown
+     * kind, a stimulus with no channel identity, and a runtime that opened no
+     * intake. A producer holding a receipt believes the stimulus is kept, so
+     * none of those may pass quietly.
+     */
+    accept(stimulus: Stimulus): StimulusReceipt;
+    /**
+     * Deliver what is pending, once. Returns what happened, so a caller that
+     * drives the drain itself can tell idle from failing.
+     *
+     * Runs the stale-claim replay first: a claim is a lease, so a delivery that
+     * died mid-flight is owed again rather than lost.
+     */
+    drainOnce(): Promise<{
+        delivered: number;
+        failed: number;
+        dead: number;
+    }>;
+    /**
+     * The principal a presented credential names, or `undefined` for nobody.
+     *
+     * One boot issues the credentials; this is the same table the socket
+     * resolves against, read by a second local door rather than duplicated. It
+     * only ever narrows: an absent or unknown credential resolves to nobody, and
+     * there is no caller this answers for that the socket would not.
+     */
+    principalFor(credential: string | undefined): RuntimePrincipal | undefined;
+    /** Whether this boot currently serves an exact principal for durable intake. */
+    servesPrincipal(principalId: string): boolean;
+    /** Add a product-identified caller to the live socket and intake without reopening either. */
+    servePrincipal(principal: RuntimePrincipal): void;
+    /** Remove a caller's socket identity and durable-intake admission immediately. */
+    unservePrincipal(principalId: string): void;
+    /** The harness this runtime opened, or undefined when it opened none. */
+    nativeSession?: Pick<NativeSessionHandle, 'stop' | 'resetSession'>;
+    /**
+     * Closes what start opened, in the order that makes each close safe: the
+     * drain first so nothing new is handed out, then the harness, then the socket
+     * and this boot's credential. A caller that stops answering action calls
+     * before the turn using them has ended would fail that turn on the way out.
+     */
+    stop(): Promise<void>;
+}
+/**
+ * Opens the action surface: issues the session credential and serves
+ * `catalog`/`dispatch` on the private socket. `stop` closes the socket and
+ * removes the credential file it wrote — nothing else.
+ */
+export declare function startRuntime(options: StartRuntimeOptions): Promise<RuntimeHandle>;
+//# sourceMappingURL=runtime.d.ts.map