@jungjaehoon/mama-core 2.4.1 → 4.1.0

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

@@ -0,0 +1,272 @@
+/**
+ * One run, from the moment a caller hands over content to the moment the answer,
+ * the receipts and the session lock are settled.
+ *
+ * This was a product's agent loop: the entry a consumer called to talk to a model.
+ * Everything it does here is the same whichever consumer asks and whatever the words
+ * mean - wait for the session's lane, decide NEW vs CONTINUE, open a model run, hold a
+ * native-effect boundary open, run the turns, run the tools the model asked for under
+ * the loop guards, give a native child its own authority, commit or fail the run,
+ * release the session. None of it needs to know the transport.
+ *
+ * What it cannot know, the caller states: the layers this turn opens with, which
+ * channel key it serializes on, what a tool call actually does, and what the consumer
+ * wants kept once the answer stands. A port is asked; it is never inferred.
+ */
+import type { BackendType, ContentBlock, HostExecutionContext, HostToolDefinition, IModelRunner, Message, NativeInputReceipt, StopReason, StreamCallbacks, TurnInfo, Usage } from './drivers/types.js';
+import { type NativeEffectObserver } from './native-effect-observer.js';
+import type { PostToolHandler } from './post-tool-handler.js';
+import { type PromptLayer } from './prompt-layers.js';
+import type { SubagentBridge, SubagentBridgeRequest } from './subagent-bridge.js';
+import type { SessionPool } from './session-pool.js';
+import type { NativeToolCaller } from '../action-contracts.js';
+import { type BudgetStopInfo, type NativePromptRequest } from './native-prompt.js';
+/** Background work a tool started that the run must outlive its own turns to drain. */
+export interface BackgroundTaskRegistry {
+    register(task: Promise<unknown>): void;
+}
+/**
+ * What the entry reads from the caller's wider options object. The caller's own type
+ * is much wider and names things the core has no business knowing; this is the part
+ * that crosses.
+ */
+export interface NativeTurnRequest extends NativePromptRequest {
+    /** Assembled only after the native driver has selected a new or retained session. */
+    prepareSessionContent?: (session: import('./drivers/types.js').NativeSessionState) => Promise<ContentBlock[]>;
+    sessionKey?: string;
+    channelId?: string;
+    lanePriority?: number;
+    /** Best-effort notification that an earlier turn already occupies this session lane. */
+    onQueued?: () => void;
+    /** Trace identity as soon as the run exists, including turns that never return a result. */
+    onModelRunStarted?: (modelRunId: string) => void;
+    cliSessionId?: string | null;
+    procedureRefs?: unknown;
+    streamCallbacks?: StreamCallbacks;
+    onTurn?: (turn: TurnInfo) => void;
+    onToolUse?: (toolName: string, input: unknown, result: unknown) => void;
+    /** Authority is asked for AFTER both queue waits, never before. */
+    prepareAccess?: () => unknown | Promise<unknown>;
+    /** Admission may replace the content it was handed. */
+    prepareContent?: () => {
+        content: ContentBlock[];
+        procedureRefs?: unknown;
+    } | Promise<{
+        content: ContentBlock[];
+        procedureRefs?: unknown;
+    }>;
+    /** A run the caller already owns; this entry opens none of its own for it. */
+    ownerJournalPrompt?: string;
+    tier?: 1 | 2 | 3;
+}
+/** Why a run stopped on the host's side. */
+export type NativeRunStoppedBy = 'budget';
+/** Whether this run's model-run record can be cited afterwards. */
+export type NativeRunProvenance = 'available' | 'backend_no_run' | 'commit_failed';
+export interface NativeTurnResult {
+    response: string;
+    turns: number;
+    history: Message[];
+    totalUsage: Usage;
+    stopReason: StopReason;
+    modelRunId: string | null;
+    modelRunProvenance: NativeRunProvenance;
+    stoppedBy?: NativeRunStoppedBy;
+    [extra: string]: unknown;
+}
+/**
+ * Everything about THIS turn the core cannot decide, stated in one answer so the core
+ * never assembles a policy out of fragments.
+ *
+ * The prompt crosses as LAYERS, not as a string. Joining them and keeping them inside
+ * a budget is arithmetic and belongs here; what each layer says belongs to the caller.
+ */
+export interface NativeTurnPolicy {
+    /** The session lane and pool key this run serializes on. */
+    channelKey: string;
+    /** What this call opens with. */
+    systemLayers: readonly PromptLayer[];
+    /**
+     * The complete current policy, asked for only when a durable thread was replaced.
+     * A resume stub would REPLACE the thread's full policy with a fragment, so the
+     * caller rebuilds it here - and, because rebuilding can cost a search, only here.
+     */
+    reanchorLayers?: () => Promise<readonly PromptLayer[]>;
+    /** Base instructions a durable runtime re-anchors a live thread with. */
+    resumeLayers?: () => Promise<readonly PromptLayer[]>;
+    /** The policy the spawned process carries; a changed one must respawn, not inherit. */
+    sessionPolicyFingerprint?: string;
+    /** An explicit per-session native read boundary; absent preserves driver defaults. */
+    restrictedReadRoots?: readonly string[];
+    /** Native working directory for this session, supplied by the host. */
+    nativeCwd?: string;
+    /** The native built-in surface this turn's grant projects onto the process. */
+    nativeTools?: string;
+    /**
+     * This session carries a standing composed policy rather than a per-call one, so a
+     * lost thread is re-anchored with the whole of it instead of with a resume stub.
+     */
+    standingPolicy?: boolean;
+}
+/**
+ * Opening and closing the record of one run.
+ *
+ * WHEN a run is opened is not this port's decision - the entry opens one for every
+ * turn it actually runs, unless the caller already owns one. The port used to carry a
+ * `shouldBegin` predicate, and the product answered it with its tool-routing mode, so
+ * a whole backend's turns went unrecorded while running real tools.
+ *
+ * A consumer that cannot record a run must fail here rather than return nothing: a
+ * turn whose run cannot be written must not run quietly.
+ */
+export interface NativeModelRunPort {
+    begin(request: NativeTurnRequest | undefined, cliSessionId: string | null): Promise<string>;
+    commit(modelRunId: string, summary: string, tokenCount?: number): Promise<void>;
+    fail(modelRunId: string, summary: string, tokenCount?: number): Promise<void>;
+}
+/** The queue that serializes one session's runs. The core asks; it does not own one. */
+export interface SessionLanes {
+    enqueueWithSession<T>(sessionKey: string, task: () => Promise<T>, globalLane?: string, options?: {
+        priority?: number;
+    }): Promise<T>;
+    /** Whether this exact session already has active or queued native work. */
+    hasSessionWork?(sessionKey: string): boolean;
+    getTotalQueueSize(): number;
+}
+/**
+ * The consumer, as the entry sees it: a handful of stated values and the ports it
+ * calls when only the consumer can answer.
+ */
+export interface NativeSessionHost<TToolContext extends HostExecutionContext = HostExecutionContext> {
+    readonly agent: IModelRunner;
+    readonly backend: BackendType;
+    readonly model: string;
+    readonly maxTurns: number;
+    readonly isGatewayMode: boolean;
+    readonly runTokenBudget: number;
+    readonly sessionPool: SessionPool;
+    readonly lanes?: SessionLanes;
+    readonly useLanes?: boolean;
+    readonly postToolHandler?: PostToolHandler | null;
+    /** Where an uploaded image is written so the runtime can read it back by path. */
+    readonly inboundMediaDir?: string;
+    /** Run-wide observers used when a request states none of its own. */
+    readonly onTurn?: (turn: TurnInfo) => void;
+    readonly onToolUse?: (toolName: string, input: unknown, result: unknown) => void;
+    readonly onBudgetStop?: (info: BudgetStopInfo) => void;
+    readonly onTokenUsage?: (record: {
+        channel_key: string;
+        agent_id?: string;
+        input_tokens: number;
+        output_tokens: number;
+        cache_read_tokens?: number;
+        cost_usd?: number;
+    }) => void;
+    readonly onMetric?: (name: string, value: number, labels?: Record<string, string>) => void;
+    /** Which global lane, if any, this session's runs share. */
+    globalLaneFor?(sessionKey: string): string | undefined;
+    /** Everything about this turn the core cannot decide. Asked once, after the waits. */
+    turnPolicy(request: NativeTurnRequest | undefined): NativeTurnPolicy;
+    /** A request may be narrowed before anything reads it (a private surface, a role). */
+    projectRequest?(request: NativeTurnRequest): NativeTurnRequest;
+    /** What a tool call is allowed to touch. Rebuilt once the run id exists. */
+    executionContext(request: NativeTurnRequest | undefined): TToolContext | null;
+    /** Conservatively rebind tool provenance when another input joins this native turn. */
+    onSteeredInput?(context: TToolContext | null): TToolContext | null;
+    /** What the runtime may be called with, for this turn's grant. */
+    hostToolDefinitions(request: NativeTurnRequest | undefined): readonly HostToolDefinition[];
+    createNativeEffectObserver?(executionContext: TToolContext | null): NativeEffectObserver | undefined;
+    modelRun?: NativeModelRunPort;
+    /** Run one tool the model asked for. The one thing the core cannot do itself. */
+    callTool(name: string, input: unknown, executionContext: TToolContext | null): Promise<unknown>;
+    /** Text a consumer wants in front of a specific tool's result, or nothing. */
+    toolPrelude?(name: string, input: unknown, executionContext: TToolContext | null): Promise<string>;
+    /** What the consumer wants kept once the answer stands. Observation, never a gate. */
+    onRunFinished?(finished: {
+        request: NativeTurnRequest | undefined;
+        result: NativeTurnResult;
+        channelKey: string;
+        modelRunId: string | null;
+        prompt: string;
+        response: string;
+    }): void | Promise<void>;
+}
+/**
+ * The last user message as the model will read it.
+ *
+ * An uploaded image reaches a file-backed runtime as evidence with a local path.
+ * The agent chooses how to inspect it; the host does not prescribe a tool order.
+ */
+export declare function formatLastUserMessage(history: Message[], options: {
+    mediaDir?: string;
+}): string;
+/**
+ * The entry a consumer holds: one session's runs, serialized on its lane.
+ */
+export declare class NativeSessionRunner<TToolContext extends HostExecutionContext = HostExecutionContext> {
+    private readonly host;
+    stopped: boolean;
+    private readonly activeSteerBindings;
+    /**
+     * What a native child started by a run on this session needs. Keyed by session key,
+     * overwritten by each run on that session, and dropped once the run finished and no
+     * child of it is still registered.
+     */
+    private readonly subagentRunContexts;
+    private nextCallerTurnId;
+    private readonly callerChildOwners;
+    constructor(host: NativeSessionHost<TToolContext>);
+    /** Retire native context only. Durable input, results and knowledge remain owned by the host. */
+    resetSession(sessionKey: string): Promise<void>;
+    /** Use the current turn's authority. Steering cannot replace its policy or open a new turn. */
+    steer(content: string, target: NativeInputReceipt, sessionKey: string, beforeSend?: () => void): Promise<NativeInputReceipt>;
+    /** Run one turn from text. */
+    run(prompt: string, request?: NativeTurnRequest): Promise<NativeTurnResult>;
+    /**
+     * Run one turn from content blocks.
+     *
+     * Per-call session key wins over the instance default: overlapping runs on a shared
+     * session must never depend on mutated state to pick their lane.
+     */
+    runTurn(content: ContentBlock[], request?: NativeTurnRequest): Promise<NativeTurnResult>;
+    /**
+     * Close the harness. The runner that opened the process is the one that closes it;
+     * queued work is given a bounded moment to drain first.
+     */
+    stop(): Promise<void>;
+    /**
+     * Run the tools one model turn asked for.
+     *
+     * The guards, the abort, the metrics and the history shape are the same whatever a
+     * tool does; what it does is `callTool`.
+     */
+    private runToolCalls;
+    /**
+     * One dynamic-tool bridge. The same-signature loop guard is private to the bridge, so a parent and its children
+     * never share a counter. `recordExchange` is the ONLY way a bridge writes to a
+     * conversation: a child passes none and therefore cannot touch the parent's history.
+     */
+    private buildHostToolBridge;
+    /**
+     * Give one native child its OWN authority.
+     *
+     * A parent's bridge closes over authority issued for the PARENT, which the child
+     * cannot renew - inheriting it meant a long delegated run losing every tool mid-flight
+     * and still reporting "done". So the child gets: its own model run under the parent's,
+     * its own authority from the host issuer, its own execution context, and its own
+     * bridge counters. When no issuer is reachable it gets nothing and says so - the
+     * process refuses its calls rather than quietly borrowing.
+     */
+    createSubagentBridge(info: SubagentBridgeRequest): Promise<SubagentBridge | null>;
+    /** Both native dynamic tools and an attributed socket call use this child run. */
+    private createChildRun;
+    /** Resolve a harness caller only against a currently dispatched turn. */
+    withToolCaller<T>(caller: NativeToolCaller, execute: (context: HostExecutionContext) => Promise<T>): Promise<T>;
+    private settleCallerRuns;
+    /** Drop a run's subagent context once the run finished and no child still holds it. */
+    private releaseSubagentRunContext;
+    /** The run itself, with no queue around it. */
+    private runTurnInternal;
+}
+export declare function createNativeSessionRunner<TToolContext extends HostExecutionContext>(host: NativeSessionHost<TToolContext>): NativeSessionRunner<TToolContext>;
+//# sourceMappingURL=native-turn.d.ts.map