@qduc/term2 0.11.0 → 0.12.0

package/dist/services/agent-runtime/application-run-loop.d.ts

@@ -0,0 +1,205 @@
+import type { ProviderInput, ProviderInputItem } from '../../contracts/provider-input.js';
+import type { JsonSchemaDefinition } from '../../contracts/model-types.js';
+import { type ContinuationHandle } from '../../contracts/continuation-handle.js';
+import { type AgentStream } from '../agent-stream.js';
+import type { StreamedModelTurn, StreamedModelTurnInput, ContextCompactionSessionState, StreamedModelTurnRequest } from '../../contracts/streamed-model-turn.js';
+import type { ToolExecutionLifecyclePort, ToolRegistry } from '../../tools/types.js';
+import type { Term2HookScope } from '../hooks/hook-contracts.js';
+import { ApprovalLedger } from './tool-invocation-context.js';
+import { type GenerationGuardOptions } from './generation-guard.js';
+/**
+ * Fields of `modelSettings` the run loop and provider adapters actually read.
+ * Codex-only request fields are modeled separately so they cannot escape into
+ * another provider's opaque option bag. The index signature remains for legacy
+ * provider settings before they are projected by the application configuration.
+ */
+export interface AgentModelSettings {
+    temperature?: number;
+    reasoning?: {
+        effort?: string;
+        summary?: string;
+    };
+    maxTokens?: number;
+    /** Hard per-request stream-output budget across text, reasoning, and tool arguments. */
+    maxStreamOutputChars?: number;
+    /** Total wall-clock limit for each individual provider request. */
+    maxModelRequestDurationMs?: number;
+    retry?: {
+        maxRetries?: number;
+    };
+    providerData?: Record<string, unknown>;
+    codex?: {
+        promptCacheKey?: string;
+        include?: readonly string[];
+    };
+    [key: string]: unknown;
+}
+/** The application-owned agent shape consumed by the replacement run loop. */
+export interface ApplicationAgent {
+    readonly name: string;
+    readonly instructions: string;
+    readonly model: string;
+    modelSettings?: AgentModelSettings;
+    defaultRunOptions?: any;
+    outputType?: JsonSchemaDefinition | 'text';
+    readonly tools: ToolRegistry;
+}
+export interface ApplicationRequestPreparation {
+    /** Observe the exact application request immediately before model dispatch. */
+    readonly prepare: (request: StreamedModelTurnRequest) => void;
+    /** Keep request preparation context alive for the complete async model request. */
+    readonly run: <T>(operation: () => Promise<T>) => Promise<T>;
+}
+export interface ApplicationRunLoopOptions {
+    readonly signal?: AbortSignal;
+    /** Existing provider response to continue from on the first model turn. */
+    readonly previousResponseId?: string | null;
+    /** Identity of the provider making this run. Required to establish response provenance. */
+    readonly providerId?: string;
+    /** Whether this provider accepts response IDs for continuation requests. */
+    readonly supportsConversationChaining?: boolean;
+    readonly sessionId?: string;
+    /** Public hook correlation for the logical session turn. */
+    readonly turnId?: string;
+    /** Root/subagent ownership for observational tool events. */
+    readonly hookScope?: Term2HookScope;
+    /** Per-run user context delivered to tools as `ToolInvocationContext.context`. */
+    readonly context?: unknown;
+    /**
+     * The run's approval ledger; a fresh one is created when omitted. Pass a
+     * pre-seeded ledger to honor decisions already taken (e.g. parent approvals
+     * replayed into a nested run — the F5 mechanism).
+     */
+    readonly approvals?: ApprovalLedger;
+    /**
+     * Maximum model turns for this run. One turn is one model call, matching the
+     * removed SDK's accounting. Exceeding it throws {@link MaxTurnsExceededError}.
+     * Omitted means unbounded — callers that had a limit under the SDK (the chat
+     * client, subagents, the mentor) must pass theirs.
+     */
+    readonly maxTurns?: number;
+    /** Root-only provider request preparation, retained by continuations. */
+    readonly requestPreparation?: ApplicationRequestPreparation;
+    /** Per-request output and deadline guard; model settings provide the normal runtime defaults. */
+    readonly generationGuard?: GenerationGuardOptions;
+    /**
+     * End the segment once the pending approval's tool result is in history,
+     * instead of crossing the request boundary into another model call. The
+     * segment then finishes with no interruptions, so it is terminal and its
+     * history — the tool call *and* its result — is committed. Cancelling an
+     * `ask_user` prompt uses this: the user gets the turn back, and the model
+     * still sees that the question was asked and went unanswered.
+     */
+    readonly stopAfterApprovalResolution?: boolean;
+}
+/**
+ * Raised when a run exceeds its `maxTurns` budget. The loop owns turn counting
+ * — the SDK-era `callModelInputFilter` hook is deliberately not reintroduced.
+ */
+export declare class MaxTurnsExceededError extends Error {
+    readonly maxTurns: number;
+    constructor(maxTurns: number);
+}
+export interface ApplicationRunLoopDeps {
+    readonly resolveModel: (model: string) => StreamedModelTurn | Promise<StreamedModelTurn>;
+    readonly toolLifecycle?: ToolExecutionLifecyclePort;
+    /**
+     * Diagnostics sink. Optional so no construction site or test has to supply
+     * one. Used to report the fate of steers, which is otherwise invisible: a
+     * turn spans several runs, and a steer only survives the run it was handed to.
+     */
+    readonly logDiagnostic?: (message: string, meta: Record<string, unknown>) => void;
+    readonly contextCompactionSessionState?: ContextCompactionSessionState;
+}
+/**
+ * The fate of a message handed to `steer`/`retractSteer`/`editSteer`.
+ *
+ * `'admitted'` — the running turn took it at a request boundary.
+ * `'released'` — no further boundary is coming (turn ending, or none
+ * running); the caller must send it as its own turn instead.
+ * `'retracted'` — `retractSteer` pulled it out before either of the above.
+ */
+export type SteerOutcome = 'admitted' | 'released' | 'retracted';
+/**
+ * Small provider-neutral agent loop. It owns model-turn sequencing and tool
+ * execution; providers only implement `StreamedModelTurn`.
+ */
+export declare class ApplicationRunLoop {
+    #private;
+    constructor(deps: ApplicationRunLoopDeps);
+    /**
+     * Declare a turn open, making it steerable before its first run exists.
+     *
+     * Anything still waiting belongs to a turn that never closed, and can never
+     * be admitted now.
+     */
+    openTurn(): void;
+    /**
+     * Declare the turn over. Whatever is still waiting had no boundary left, so
+     * it is handed back for the caller to send as its own turn.
+     */
+    closeTurn(): void;
+    abort(): void;
+    /**
+     * Stop the segment currently streaming without judging the turn's fate.
+     *
+     * Resuming a paused turn goes through here, so waiting injections survive;
+     * only `abort`, which means the turn itself is over, discards them.
+     */
+    abortSegment(): void;
+    /**
+     * Hand the running turn a user message to send with its next model request.
+     *
+     * The loop admits it at a request boundary — after the tool results of the
+     * current round are in history and before the next request is built — so the
+     * model reads it in sequence without the turn being interrupted. Nothing is
+     * cancelled, and a tool already running is untouched.
+     *
+     * The wait spans the whole turn, not just the segment it was offered to: a
+     * turn that pauses for an approval resumes as a new segment, and the message
+     * is admitted at that segment's first boundary. A caller that declares its
+     * turn boundaries with `openTurn`/`closeTurn` extends the wait further still,
+     * to the gaps where no segment exists at all — before the first request, and
+     * across a retry that restarts the stream.
+     *
+     * Resolves `'admitted'` once the message has been admitted, `'released'`
+     * when the turn ends first (or none is running) — it offered no further
+     * request boundary, so the caller must send the message as its own turn
+     * instead — and `'retracted'` when `retractSteer` pulled it out first.
+     *
+     * `options.id` correlates this steer with `retractSteer`/`editSteer`. A
+     * steer offered without an id can never be retracted or edited in place —
+     * only released or admitted.
+     */
+    steer(items: readonly ProviderInputItem[], options?: {
+        id?: string;
+    }): Promise<SteerOutcome>;
+    /**
+     * Drop a still-waiting steer before it reaches a request boundary. Returns
+     * `false` when the id is unknown, including when it was already admitted.
+     *
+     * Invariant: this and `#admitPendingSteers` are both synchronous, and the
+     * latter drains `#pendingSteers` in a single pass — so the two can never
+     * interleave. A retraction is decided in the same tick against whatever is
+     * currently in `#pendingSteers`; once an item has been admitted it is no
+     * longer in that array for this method to find. No locking is needed to
+     * close the race between "the user retracts" and "the turn admits".
+     */
+    retractSteer(id: string): boolean;
+    /**
+     * Replace a waiting steer's items in place, keeping its position (and thus
+     * its priority relative to other pending steers) and its id. Returns
+     * `false` when the id is unknown, including when it was already admitted —
+     * same synchronicity invariant as `retractSteer`.
+     */
+    editSteer(id: string, items: readonly ProviderInputItem[]): boolean;
+    startStream(agent: ApplicationAgent, input: ProviderInput, options?: ApplicationRunLoopOptions): AgentStream;
+    continueRunStream(handle: ContinuationHandle, options?: ApplicationRunLoopOptions): AgentStream;
+}
+/**
+ * The canonical application projection used for both model requests and
+ * continuation-prefix comparisons. Keep this at the application boundary so
+ * callers never need to inspect opaque continuation state.
+ */
+export declare function normalizeApplicationInput(input: ProviderInput | readonly ProviderInputItem[]): StreamedModelTurnInput[];
+//# sourceMappingURL=application-run-loop.d.ts.map

package/dist/services/agent-runtime/application-run-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"application-run-loop.d.ts","sourceRoot":"","sources":["../../../source/services/agent-runtime/application-run-loop.ts"],"names":[],"mappings":"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"}