@jungjaehoon/mama-core 2.4.1 → 4.1.0

package/dist/runtime/native-input-journal.js

@@ -0,0 +1,308 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NativeInputJournal = void 0;
+const node_crypto_1 = require("node:crypto");
+const canonicalize_js_1 = require("../canonicalize.js");
+function resultRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('Native turn result is not an object');
+    }
+    const record = value;
+    const usage = record.totalUsage;
+    if (typeof record.response !== 'string' ||
+        !Number.isSafeInteger(record.turns) ||
+        Number(record.turns) < 0 ||
+        !usage ||
+        typeof usage.input_tokens !== 'number' ||
+        !Number.isFinite(usage.input_tokens) ||
+        usage.input_tokens < 0 ||
+        typeof usage.output_tokens !== 'number' ||
+        !Number.isFinite(usage.output_tokens) ||
+        usage.output_tokens < 0 ||
+        ['cache_creation_input_tokens', 'cache_read_input_tokens', 'cost_usd'].some((key) => usage[key] !== undefined &&
+            (typeof usage[key] !== 'number' || !Number.isFinite(usage[key]) || Number(usage[key]) < 0)) ||
+        typeof record.stopReason !== 'string' ||
+        (record.modelRunId !== null && typeof record.modelRunId !== 'string') ||
+        !['available', 'backend_no_run', 'commit_failed'].includes(String(record.modelRunProvenance)) ||
+        (record.modelRunProvenance === 'available' &&
+            (typeof record.modelRunId !== 'string' || !record.modelRunId.trim())) ||
+        (record.modelRunProvenance !== 'available' && record.modelRunId !== null) ||
+        (record.stoppedBy !== undefined && typeof record.stoppedBy !== 'string') ||
+        (record.ownerJournalProvenance !== undefined &&
+            record.ownerJournalProvenance !== 'commit_failed')) {
+        throw new Error('Native turn result is invalid');
+    }
+    return {
+        response: record.response,
+        turns: Number(record.turns),
+        totalUsage: {
+            input_tokens: Number(usage.input_tokens),
+            output_tokens: Number(usage.output_tokens),
+            ...(usage.cache_creation_input_tokens === undefined
+                ? {}
+                : { cache_creation_input_tokens: Number(usage.cache_creation_input_tokens) }),
+            ...(usage.cache_read_input_tokens === undefined
+                ? {}
+                : { cache_read_input_tokens: Number(usage.cache_read_input_tokens) }),
+            ...(usage.cost_usd === undefined ? {} : { cost_usd: Number(usage.cost_usd) }),
+        },
+        stopReason: record.stopReason,
+        modelRunId: record.modelRunId,
+        modelRunProvenance: record.modelRunProvenance,
+        ...(record.stoppedBy === undefined
+            ? {}
+            : { stoppedBy: record.stoppedBy }),
+        ...(record.ownerJournalProvenance === 'commit_failed'
+            ? { ownerJournalProvenance: 'commit_failed' }
+            : {}),
+    };
+}
+function address(value) {
+    if (!value ||
+        typeof value !== 'object' ||
+        !['claude', 'codex'].includes(String(value.backend)) ||
+        typeof value.sessionId !== 'string' ||
+        !value.sessionId.trim()) {
+        throw new Error('Native input address is invalid');
+    }
+}
+function required(value) {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new Error('Native input identity is required');
+    }
+}
+/** One durable dispatch identity per accepted input. No task meaning or effect classification. */
+class NativeInputJournal {
+    db;
+    now;
+    constructor(db, now = Date.now) {
+        this.db = db;
+        this.now = now;
+        const existed = db
+            .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='native_input_deliveries'")
+            .get();
+        db.exec(`CREATE TABLE IF NOT EXISTS native_input_deliveries (
+      input_id INTEGER PRIMARY KEY REFERENCES mailbox_inputs(id) ON DELETE CASCADE,
+      invocation_id TEXT UNIQUE,
+      state TEXT NOT NULL CHECK (state IN ('prepared','dispatching','accepted','settled','uncertain')),
+      dispatch_json TEXT, receipt_json TEXT, error TEXT, updated_at INTEGER NOT NULL
+    )`);
+        db.exec(`CREATE TABLE IF NOT EXISTS native_turn_results (
+      receipt_json TEXT NOT NULL,
+      principal_id TEXT NOT NULL,
+      primary_stimulus_id TEXT NOT NULL,
+      primary_kind TEXT CHECK (primary_kind IS NULL OR primary_kind IN
+        ('owner_message','source_delta','scheduled','native_event')),
+      result_json TEXT NOT NULL CHECK (json_valid(result_json)),
+      created_at INTEGER NOT NULL,
+      PRIMARY KEY (receipt_json, principal_id)
+    )`);
+        if (!existed) {
+            db.exec(`INSERT OR IGNORE INTO native_input_deliveries (input_id,state,error,updated_at)
+      SELECT id,'uncertain','Legacy input has no native dispatch record',created_at
+      FROM mailbox_inputs WHERE status='claimed' OR (status='pending' AND attempts>0)`);
+        }
+    }
+    get(inputId) {
+        const row = this.db
+            .prepare('SELECT * FROM native_input_deliveries WHERE input_id=?')
+            .get(inputId);
+        if (!row) {
+            return null;
+        }
+        const dispatch = row.dispatch_json === null ? null : JSON.parse(row.dispatch_json);
+        const receipt = row.receipt_json === null ? null : JSON.parse(row.receipt_json);
+        if (row.dispatch_json !== null) {
+            address(dispatch);
+            required(dispatch.inputId);
+        }
+        if (row.receipt_json !== null) {
+            address(receipt);
+            required(receipt.backend === 'claude' ? receipt.inputId : receipt.turnId);
+        }
+        if (dispatch && dispatch.inputId !== row.invocation_id) {
+            throw new Error('Stored native input identity mismatch');
+        }
+        if (receipt &&
+            (!dispatch ||
+                receipt.backend !== dispatch.backend ||
+                receipt.sessionId !== dispatch.sessionId ||
+                (receipt.backend === 'claude' && receipt.inputId !== row.invocation_id))) {
+            throw new Error('Stored native receipt identity mismatch');
+        }
+        if (row.state === 'accepted' && !receipt) {
+            throw new Error('Accepted native input has no receipt');
+        }
+        if (row.state === 'dispatching' && !dispatch) {
+            throw new Error('Dispatched native input has no address');
+        }
+        return {
+            invocationId: row.invocation_id,
+            state: row.state,
+            dispatch,
+            receipt,
+            error: row.error,
+        };
+    }
+    /** Page the inputs that share one exact native receipt under one principal. */
+    listByReceipt(receipt, principalId, options = {}) {
+        address(receipt);
+        required(receipt.backend === 'codex' ? receipt.turnId : receipt.inputId);
+        required(principalId);
+        const afterId = options.afterId ?? 0;
+        const limit = options.limit ?? 25;
+        if (!Number.isSafeInteger(afterId) || afterId < 0) {
+            throw new Error('Native receipt cursor must be a non-negative integer');
+        }
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) {
+            throw new Error('Native receipt page limit must be 1 to 100');
+        }
+        const rows = this.db
+            .prepare(`SELECT n.input_id FROM native_input_deliveries n
+         JOIN mailbox_inputs m ON m.id=n.input_id
+         WHERE n.receipt_json=? AND m.principal_id=? AND n.input_id>?
+         ORDER BY n.input_id LIMIT ?`)
+            .all((0, canonicalize_js_1.canonicalizeJSON)(receipt), principalId, afterId, limit + 1);
+        const page = rows.slice(0, limit);
+        return {
+            inputIds: page.map((row) => row.input_id),
+            nextCursor: rows.length > limit ? page[page.length - 1].input_id : null,
+        };
+    }
+    /** One immutable final result per native turn, written before any consumer reply. */
+    storeResult(inputId, result) {
+        const native = this.get(inputId);
+        if (!native?.receipt)
+            throw new Error('Native result requires an accepted input receipt');
+        const mailbox = this.db
+            .prepare('SELECT stimulus_id, principal_id, kind FROM mailbox_inputs WHERE id=?')
+            .get(inputId);
+        if (!mailbox)
+            throw new Error('Native result input is missing');
+        if (!['owner_message', 'source_delta', 'scheduled', 'native_event'].includes(String(mailbox.kind))) {
+            throw new Error('Native result input has no producer-stated kind');
+        }
+        const receiptJson = (0, canonicalize_js_1.canonicalizeJSON)(native.receipt);
+        const resultJson = (0, canonicalize_js_1.canonicalizeJSON)(resultRecord(result));
+        this.db.transaction(() => {
+            const existing = this.db
+                .prepare('SELECT primary_stimulus_id, primary_kind, result_json FROM native_turn_results WHERE receipt_json=? AND principal_id=?')
+                .get(receiptJson, mailbox.principal_id);
+            if (existing) {
+                if (existing.primary_stimulus_id !== mailbox.stimulus_id ||
+                    existing.primary_kind !== mailbox.kind ||
+                    existing.result_json !== resultJson) {
+                    throw new Error('Native turn result conflicts with its durable receipt');
+                }
+                return;
+            }
+            this.db
+                .prepare(`INSERT INTO native_turn_results
+           (receipt_json,principal_id,primary_stimulus_id,primary_kind,result_json,created_at)
+           VALUES (?,?,?,?,?,?)`)
+                .run(receiptJson, mailbox.principal_id, mailbox.stimulus_id, mailbox.kind, resultJson, this.now());
+        });
+    }
+    /** A later accepted input can recover the one final result under its principal. */
+    resultForReceipt(receipt, principalId) {
+        address(receipt);
+        required(receipt.backend === 'codex' ? receipt.turnId : receipt.inputId);
+        required(principalId);
+        const row = this.db
+            .prepare('SELECT primary_stimulus_id, primary_kind, result_json FROM native_turn_results WHERE receipt_json=? AND principal_id=?')
+            .get((0, canonicalize_js_1.canonicalizeJSON)(receipt), principalId);
+        if (!row)
+            return null;
+        if (row.primary_kind !== null &&
+            !['owner_message', 'source_delta', 'scheduled', 'native_event'].includes(row.primary_kind)) {
+            throw new Error('Stored native primary kind is invalid');
+        }
+        return {
+            ...resultRecord(JSON.parse(row.result_json)),
+            primaryStimulusId: row.primary_stimulus_id,
+            primaryKind: row.primary_kind,
+        };
+    }
+    prepare(inputId) {
+        this.db
+            .prepare(`INSERT OR IGNORE INTO native_input_deliveries
+      (input_id,invocation_id,state,updated_at) VALUES (?,?,'prepared',?)`)
+            .run(inputId, (0, node_crypto_1.randomUUID)(), this.now());
+        return this.get(inputId);
+    }
+    dispatch(inputId, value) {
+        address(value);
+        required(value.inputId);
+        const record = this.get(inputId);
+        if (!record || record.invocationId !== value.inputId) {
+            throw new Error('Native dispatch input identity mismatch');
+        }
+        const encoded = (0, canonicalize_js_1.canonicalizeJSON)(value);
+        if (record.dispatch) {
+            if ((0, canonicalize_js_1.canonicalizeJSON)(record.dispatch) !== encoded) {
+                throw new Error('Native dispatch identity conflict');
+            }
+            throw new Error('Native input was already dispatched; reconciliation is required');
+        }
+        if (record.state !== 'prepared') {
+            throw new Error('Native input requires reconciliation before dispatch');
+        }
+        const changed = this.db
+            .prepare("UPDATE native_input_deliveries SET state='dispatching',dispatch_json=?,updated_at=? WHERE input_id=? AND state='prepared'")
+            .run(encoded, this.now(), inputId);
+        if (changed.changes !== 1) {
+            throw new Error('Native input was already dispatched; reconciliation is required');
+        }
+    }
+    accept(inputId, value) {
+        address(value);
+        required(value.backend === 'claude' ? value.inputId : value.turnId);
+        this.db.transaction(() => {
+            const record = this.get(inputId);
+            if (!record?.dispatch ||
+                record.dispatch.backend !== value.backend ||
+                record.dispatch.sessionId !== value.sessionId ||
+                (value.backend === 'claude' && value.inputId !== record.invocationId)) {
+                throw new Error('Native receipt does not match the dispatched input');
+            }
+            if (record.receipt) {
+                if ((0, canonicalize_js_1.canonicalizeJSON)(record.receipt) !== (0, canonicalize_js_1.canonicalizeJSON)(value)) {
+                    throw new Error('Native receipt identity conflict');
+                }
+                return;
+            }
+            this.db
+                .prepare("UPDATE native_input_deliveries SET state='accepted',receipt_json=?,error=NULL,updated_at=? WHERE input_id=?")
+                .run((0, canonicalize_js_1.canonicalizeJSON)(value), this.now(), inputId);
+        });
+    }
+    settle(inputId, reconciled = false) {
+        this.db.transaction(() => {
+            const record = this.get(inputId);
+            if (!record) {
+                throw new Error('Native delivery record is missing');
+            }
+            if (record.state !== 'prepared' && !record.receipt && !reconciled) {
+                throw new Error('Native input acknowledgement is unresolved');
+            }
+            this.db
+                .prepare("UPDATE native_input_deliveries SET state='settled',error=NULL,updated_at=? WHERE input_id=?")
+                .run(this.now(), inputId);
+            this.db
+                .prepare("UPDATE mailbox_inputs SET status='acked',acked_at=COALESCE(acked_at,?) WHERE id=?")
+                .run(this.now(), inputId);
+        });
+    }
+    uncertain(inputId, error) {
+        this.db
+            .prepare("UPDATE native_input_deliveries SET state='uncertain',error=?,updated_at=? WHERE input_id=? AND state!='settled' AND (state!='uncertain' OR error IS NOT ?)")
+            .run(error.slice(0, 500), this.now(), inputId, error.slice(0, 500));
+    }
+    pending(limit, afterId = 0) {
+        return this.db
+            .prepare("SELECT input_id FROM native_input_deliveries WHERE state IN ('dispatching','accepted','uncertain') AND input_id>? ORDER BY input_id LIMIT ?")
+            .all(afterId, limit).map((row) => row.input_id);
+    }
+}
+exports.NativeInputJournal = NativeInputJournal;
+//# sourceMappingURL=native-input-journal.js.map

package/dist/runtime/native-prompt.d.ts

@@ -0,0 +1,118 @@
+/**
+ * One native request: prepare its protocol options, forward acknowledgement and
+ * events, record observed exchanges, and return the harness result.
+ * Tool execution, compaction and continuation belong to the native harness.
+ */
+import type { BackendType, ContentBlock, HostExecutionContext, HostToolBridge, IModelRunner, Message, StopReason, StreamCallbacks, ToolResultBlock, TurnInfo, Usage } from './drivers/types.js';
+import type { SessionPool } from './session-pool.js';
+import type { NativeEffectReplayBoundary } from './native-effect-observer.js';
+/** Why a run stopped on the host's side, as distinct from the model's own stop reason. */
+export interface BudgetStopInfo {
+    channelKey: string;
+    modelRunId: string | null;
+    agentId?: string;
+    budgetTokens: number;
+    runTokenBudget: number;
+    turns: number;
+}
+/** Run-local observers and tier. Never instance state: two runs can overlap. */
+export interface RunScope {
+    streamCallbacks?: StreamCallbacks;
+    tier: 1 | 2 | 3;
+    onTurn?: (turn: TurnInfo) => void;
+    onToolUse?: (toolName: string, input: unknown, result: unknown) => void;
+}
+/** State the loop is handed and hands back. Everything here changes as turns run. */
+export interface NativePromptCarry {
+    turn: number;
+    stopReason: StopReason;
+    stoppedBy?: 'budget';
+    budgetTokens: number;
+    resolvedCliSessionId: string | null;
+    sessionIsNew: boolean;
+}
+/**
+ * The fourteen facts about this request the loop actually reads. The caller's own
+ * options object is wider and names things the core has no business knowing; this is
+ * the part that crosses.
+ */
+export interface NativePromptRequest {
+    nativeInputId?: string;
+    source?: string;
+    freshSession?: boolean;
+    resumeSession?: boolean;
+    model?: string;
+    requestTimeoutMs?: number;
+    onCliSessionReset?: (sessionId: string) => void;
+    systemPrompt?: string;
+    promptKind?: string;
+    promptBrief?: 'sent' | 'omitted';
+    agentContext?: {
+        roleName?: string;
+    };
+    modelRunId?: string;
+    stopAfterSuccessfulTools?: string[];
+}
+/** A tool result carries two host-only fields that history must not keep. */
+export type InternalToolResultBlock = ToolResultBlock & {
+    abort?: boolean;
+    terminalCode?: string;
+};
+/**
+ * Everything the loop reads that does not change while it runs. The caller builds it
+ * once, before the first turn.
+ */
+export interface NativePromptContext<TToolContext extends HostExecutionContext> {
+    prepareSessionContent?: (session: import('./drivers/types.js').NativeSessionState) => Promise<ContentBlock[]>;
+    channelKey: string;
+    claudeNativeTools: string | undefined;
+    effectiveSessionPolicyFingerprint: string | undefined;
+    restrictedReadRoots: readonly string[] | undefined;
+    nativeCwd: string | undefined;
+    history: Message[];
+    hostToolBridge: HostToolBridge | undefined;
+    isCodex: boolean;
+    isDurableRuntime: boolean;
+    nativeEffects: NativeEffectReplayBoundary;
+    ownedModelRunId: string | null;
+    standingPolicy: boolean;
+    /** What this call opens with, already composed by the entry. */
+    systemPrompt: string | undefined;
+    /**
+     * The complete current policy, asked for only when the durable thread this run was
+     * resuming turned out to be gone. The loop never composes one: it asks.
+     */
+    reanchor: (() => Promise<string>) | undefined;
+    resumeInstructions: (() => Promise<string>) | undefined;
+    runScope: RunScope;
+    toolExecutionContext: TToolContext | null;
+    totalUsage: Usage;
+    tracksSessionPolicy: boolean;
+}
+/**
+ * Native driver, lifecycle bookkeeping and the consumer's input formatting port.
+ */
+export interface NativePromptHost {
+    agent: IModelRunner;
+    backend: BackendType;
+    model: string;
+    runTokenBudget: number;
+    sessionPool: SessionPool;
+    onBudgetStop?: (info: BudgetStopInfo) => void;
+    onTokenUsage?: (record: {
+        channel_key: string;
+        agent_id?: string;
+        input_tokens: number;
+        output_tokens: number;
+        cache_read_tokens?: number;
+        cost_usd?: number;
+    }) => void;
+    onMetric?: (name: string, value: number, labels?: Record<string, string>) => void;
+    formatLastMessageOnly(history: Message[]): string;
+}
+/**
+ * Submit one native request and observe its completed exchanges and final result.
+ * `carry` is read and written: the caller reads the final state off it.
+ */
+export declare function runNativePrompt<TToolContext extends HostExecutionContext>(carry: NativePromptCarry, context: NativePromptContext<TToolContext>, request: NativePromptRequest, host: NativePromptHost): Promise<void>;
+//# sourceMappingURL=native-prompt.d.ts.map