@xiaozhiclaw/qlogicagent-core 0.1.5 → 0.2.0

package/dist/types/embedded/cloud-agent.d.ts

@@ -0,0 +1,92 @@
+import type { ModelOperation } from "./model-operation.js";
+import { type BusinessAssistantContext, type BusinessGoal } from "./business-contracts.js";
+import { type AgentContentBlock } from "./content-blocks.js";
+import type { CreateEmbeddedAgentOptions, ToolResult, TurnCheckpoint, TurnEvent, TurnRequest, LLMRequest } from "./contracts.js";
+export interface CloudExecutionContext {
+    applicationId: string;
+    tenantId: string;
+    actorId: string;
+    scopeId: string;
+    definitionVersion: string;
+}
+export interface CloudToolInvocation {
+    context: Readonly<CloudExecutionContext>;
+    turnId: string;
+    sessionId: string;
+    callId: string;
+    round: number;
+    name: string;
+    arguments: string;
+}
+export interface CloudCheckpoint extends TurnCheckpoint {
+    schemaVersion: 1;
+    context: CloudExecutionContext;
+    /** Exact model/tool/Skill configuration, not a credential or an authorization. */
+    binding: string;
+    contentBlocks: AgentContentBlock[];
+    modelOperations?: ModelOperation[];
+}
+export interface CloudTurnRequest extends Omit<TurnRequest, "continuation"> {
+    context: CloudExecutionContext;
+    resume?: CloudCheckpoint;
+    assistantContext?: BusinessAssistantContext;
+    goal?: BusinessGoal;
+    /** Counts all attempts across checkpoints, including rejected attempts. */
+    executionBudget?: {
+        maxModelRequests?: number;
+        deadlineAtMs?: number;
+    };
+}
+export interface CloudToolWait {
+    kind: "wait";
+    wait: {
+        id: string;
+        kind: "input" | "confirmation" | "external";
+        reference: string;
+    };
+}
+export type CloudTurnEvent = TurnEvent | {
+    type: "waiting";
+    turnId: string;
+    invocation: CloudToolInvocation;
+    wait: CloudToolWait["wait"];
+};
+export interface CloudToolReceipt {
+    invocation: CloudToolInvocation;
+    result: ToolResult;
+}
+/** Only the product may supply reconciled receipts; this function never executes tools. */
+export declare function completeCloudToolCheckpoint(input: CloudCheckpoint, receipts: CloudToolReceipt[]): CloudCheckpoint;
+export interface CloudAgentOptions extends Omit<CreateEmbeddedAgentOptions, "toolInvoker" | "runtime"> {
+    toolInvoker: {
+        invoke(invocation: CloudToolInvocation, signal?: AbortSignal): Promise<ToolResult | CloudToolWait>;
+    };
+    /** The product revalidates the authenticated actor before inference and each effect. */
+    authorize(context: Readonly<CloudExecutionContext>, action: {
+        type: "model";
+    } | {
+        type: "tool";
+        name: string;
+        callId: string;
+    }): Promise<void>;
+    runtime?: Omit<NonNullable<CreateEmbeddedAgentOptions["runtime"]>, "onCheckpoint">;
+    checkpoints?: {
+        save(checkpoint: CloudCheckpoint): Promise<void>;
+    };
+    /** Awaited before a successful result is acknowledged or another model step starts. */
+    onToolResult?(invocation: CloudToolInvocation, result: ToolResult): Promise<void>;
+    onWait?(invocation: CloudToolInvocation, wait: CloudToolWait["wait"]): Promise<void>;
+    /** Await the durable attempt record before network I/O and before acknowledging completion. */
+    onModelOperation?(operation: ModelOperation): Promise<void>;
+    /** Product/model service atomically reserves money or token quota before network I/O. */
+    reserveModelBudget?(context: Readonly<CloudExecutionContext>, operation: Omit<ModelOperation, "response">, request: LLMRequest, signal?: AbortSignal): Promise<{
+        reference: string;
+    }>;
+}
+export interface CloudAgent {
+    run(request: CloudTurnRequest, signal?: AbortSignal): AsyncGenerator<CloudTurnEvent>;
+}
+declare function canonical(value: unknown): string;
+export { canonical as canonicalCloudValue };
+/** A product-hosted adapter over the canonical loop; it owns no database or job scheduler. */
+export declare function createCloudAgent(options: CloudAgentOptions): CloudAgent;

package/dist/types/embedded/cloud-task.d.ts

@@ -0,0 +1,93 @@
+import { type CloudAgentOptions, type CloudCheckpoint, type CloudExecutionContext, type CloudToolReceipt, type CloudToolWait, type CloudTurnEvent, type CloudTurnRequest } from "./cloud-agent.js";
+import type { ToolResult } from "./contracts.js";
+import type { ModelOperation, ModelRecoveryProof } from "./model-operation.js";
+import { type BusinessGoalEvidence, type BusinessGoalOutcome } from "./business-contracts.js";
+export type CloudTaskStatus = "queued" | "running" | "waiting_input" | "waiting_confirmation" | "waiting_external" | "reconciliation_required" | "completed" | "stopped" | "failed" | "cancelled";
+export interface CloudTaskSnapshot {
+    id: string;
+    revision: number;
+    cursor: number;
+    status: CloudTaskStatus;
+    request: CloudTurnRequest;
+    checkpoint?: CloudCheckpoint;
+    receipts: CloudToolReceipt[];
+    wait?: {
+        invocation: CloudToolReceipt["invocation"];
+        descriptor: CloudToolWait["wait"];
+    };
+    errorCode?: string;
+    modelOperations?: ModelOperation[];
+    /** Durable product cancellation intent; reconciliation never resumes subsequent work. */
+    cancellationRequested?: boolean;
+    outcome?: BusinessGoalOutcome;
+}
+export type CloudTaskEventPayload = CloudTurnEvent | {
+    type: "task_status";
+    status: CloudTaskStatus;
+} | {
+    type: "checkpoint";
+    phase: CloudCheckpoint["phase"];
+} | {
+    type: "receipt";
+    callId: string;
+    round: number;
+    name: string;
+} | {
+    type: "model_operation";
+    operation: Omit<ModelOperation, "response">;
+};
+export interface CloudTaskEvent {
+    cursor: number;
+    event: CloudTaskEventPayload;
+}
+export interface CloudTaskClaim {
+    task: CloudTaskSnapshot;
+    leaseId: string;
+}
+/** Product-owned atomic persistence. Every query is scope-bound; update and cancel fence workers. */
+export interface CloudTaskStore {
+    /** Deduplicate the id/request in the authenticated product scope. */
+    create(task: CloudTaskSnapshot): Promise<CloudTaskSnapshot>;
+    load(context: CloudExecutionContext, id: string): Promise<CloudTaskSnapshot>;
+    /** Atomically claim only queued work; never steal a running or terminal task. */
+    claim(context: CloudExecutionContext, id: string): Promise<CloudTaskClaim | null>;
+    /** False on expired/revoked lease or cancellation. Products set their lease duration. */
+    renew(context: CloudExecutionContext, id: string, leaseId: string): Promise<boolean>;
+    /** CAS + live lease check + snapshot + next contiguous event cursor in one transaction. */
+    update(context: CloudExecutionContext, id: string, expectedRevision: number, task: CloudTaskSnapshot, event: CloudTaskEventPayload, leaseId?: string): Promise<CloudTaskSnapshot>;
+    release(context: CloudExecutionContext, id: string, leaseId: string): Promise<void>;
+    events(context: CloudExecutionContext, id: string, after: number, limit: number): Promise<CloudTaskEvent[]>;
+    /** Atomic lease invalidation. Preserve unresolved model billing/effects as reconciliation_required;
+     * acknowledge cancelled only when their outcomes are known. Terminal tasks stay unchanged. */
+    cancel(context: CloudExecutionContext, id: string): Promise<CloudTaskSnapshot>;
+    /** Only an expired worker may be fenced and moved to reconciliation_required. */
+    interrupt(context: CloudExecutionContext, id: string): Promise<CloudTaskSnapshot>;
+}
+export interface CloudTaskRuntimeOptions {
+    store: CloudTaskStore;
+    agent: Omit<CloudAgentOptions, "checkpoints" | "onToolResult" | "onWait" | "onModelOperation">;
+    /** Query authoritative product state; an LLM's success text is never completion evidence. */
+    verifyGoal?(task: CloudTaskSnapshot): Promise<BusinessGoalEvidence>;
+    authorize(context: CloudExecutionContext, action: "create" | "read" | "execute" | "cancel" | "complete_wait" | "recover"): Promise<void>;
+    /** Validate actual employee approval/input or query the original external job; never trust browser results. */
+    authorizeCompletion(task: CloudTaskSnapshot, waitId: string, result: ToolResult): Promise<void>;
+    /** Required for interrupted model calls or unresolved effects. The product proves billing/retry safety. */
+    authorizeRecovery?(task: CloudTaskSnapshot, receipts: CloudToolReceipt[]): Promise<ModelRecoveryProof[] | void>;
+    heartbeatMs?: number;
+    /** Optional bounded text batching; all control events still flush in order. */
+    deltaBatch?: {
+        maxCharacters: number;
+        maxDelayMs: number;
+    };
+}
+export interface CloudTaskRuntime {
+    create(id: string, request: CloudTurnRequest): Promise<CloudTaskSnapshot>;
+    get(context: CloudExecutionContext, id: string): Promise<CloudTaskSnapshot>;
+    events(context: CloudExecutionContext, id: string, after?: number, limit?: number): Promise<CloudTaskEvent[]>;
+    /** Called by the existing product worker, independently from browser subscriptions. */
+    execute(context: CloudExecutionContext, id: string, workerSignal?: AbortSignal): Promise<void>;
+    cancel(context: CloudExecutionContext, id: string): Promise<CloudTaskSnapshot>;
+    completeWait(context: CloudExecutionContext, id: string, waitId: string, result: ToolResult): Promise<CloudTaskSnapshot>;
+    recover(context: CloudExecutionContext, id: string, receipts?: CloudToolReceipt[]): Promise<CloudTaskSnapshot>;
+}
+export declare function createCloudTaskRuntime(options: CloudTaskRuntimeOptions): CloudTaskRuntime;

package/dist/types/embedded/content-blocks.d.ts

@@ -1,3 +1,5 @@
+/** MCP wire blocks are opaque product evidence; only presentation blocks go to the UI parser. */
+export declare function parsePresentationBlocks(blocks: Array<AgentContentBlock | Record<string, unknown>>): AgentContentBlock[];
 export type AgentEngineeringFormat = "dxf" | "dwg" | "step" | "stp" | "glb" | "gltf";
 export type AgentEngineeringPreviewMode = "direct" | "browser_conversion" | "external_conversion_required";
 export type AgentEngineeringParseStatus = "parsed" | "partial" | "conversion_required";

package/dist/types/embedded/contracts.d.ts

@@ -1,4 +1,3 @@
-import type { AgentContentBlock } from "./content-blocks.js";
 export interface AgentLogger {
     info(message: string): void;
     info(context: Record<string, unknown>, message: string): void;
@@ -9,125 +8,31 @@ export interface AgentLogger {
     debug(message: string): void;
     debug(context: Record<string, unknown>, message: string): void;
 }
-export interface ToolCallMessage {
-    id: string;
-    type: "function";
-    function: {
-        name: string;
-        arguments: string;
-    };
-}
-export interface ChatMessage {
-    role: "system" | "user" | "assistant" | "tool";
-    content: string | null;
-    tool_calls?: ToolCallMessage[];
-    tool_call_id?: string;
-    name?: string;
-    is_error?: boolean;
-    reasoning_content?: string;
-    thinkingBlocks?: Array<{
-        thinking: string;
-        signature: string;
-    }>;
+export type { ToolCallMessage, ChatMessage, ToolDefinition, ContextAnchor, ContextEnvelope, SemanticToolCapability, ToolIdentity } from '../contracts/chat.js';
+export type { LLMRequest, LLMChunk, LLMTransport } from '../runtime/ports/model-transport-contracts.js';
+export type { ToolResult } from '../contracts/tool-result.js';
+import type { ChatMessage, ToolDefinition } from '../contracts/chat.js';
+import type { LLMTransport } from '../runtime/ports/model-transport-contracts.js';
+import type { ToolResult } from '../contracts/tool-result.js';
+export type { WireUsageRecord as UsageRecord, WireUsageSource as UsageSource } from '../contracts/usage.js';
+export type TokenUsage = import('../contracts/usage.js').WireTokenUsage;
+export type TurnEvent = import('../contracts/turn-event.js').TurnEvent;
+export type TurnConfig = Omit<import('../agent/types.js').TurnConfig, 'apiKey'>;
+/** All three must be true on a thrown transport error before core can retry a model request. */
+export interface ModelRetryAuthorization {
+    retryable: boolean;
+    safeToRetry: boolean;
+    automaticRetryAuthorized: boolean;
+    /** Product transport evidence: a definitive rejection is terminal; unknown outcomes require reconciliation. */
+    outcome?: "rejected" | "unknown";
 }
-export interface ToolDefinition {
-    type: "function";
-    function: {
-        name: string;
-        description: string;
-        parameters?: Record<string, unknown>;
-    };
-}
-export interface LLMRequest {
-    model: string;
-    messages: ChatMessage[];
-    tools?: ToolDefinition[];
-    toolChoice?: "auto" | "none" | "required" | {
-        type: "function";
-        name: string;
-    };
-    temperature?: number;
-    maxTokens?: number;
-    reasoning?: {
-        effort: "minimal" | "low" | "medium" | "high" | "xhigh";
-        includeEncryptedReasoning?: boolean;
-    };
-    maxToolCalls?: number;
-    streamRequired?: boolean;
-    promptCacheKey?: string;
-    promptCacheRetention?: "in_memory" | "24h";
-    serviceTier?: "auto" | "default" | "flex" | "priority";
-    parallelToolCalls?: boolean;
-    textVerbosity?: "low" | "medium" | "high";
-}
-export type LLMChunk = {
-    type: "delta";
-    text: string;
-} | {
-    type: "tool_call_delta";
-    index: number;
-    id?: string;
-    name?: string;
-    arguments: string;
-} | {
-    type: "reasoning_delta";
-    text: string;
-} | {
-    type: "reasoning_block_complete";
-    thinking: string;
-    signature: string;
-} | {
-    type: "usage";
-    totalPromptTokens?: number;
-    promptTokens: number;
-    completionTokens: number;
-    reasoningTokens?: number;
-    cacheReadTokens?: number;
-    cacheCreationTokens?: number;
-} | {
-    type: "response_id";
-    id: string;
-} | {
-    type: "annotations";
-    annotations: Array<{
-        type: string;
-        url?: string;
-        title?: string;
-        [key: string]: unknown;
-    }>;
-} | {
-    type: "error";
-    message: string;
-} | {
-    type: "done";
-    finishReason: string;
-};
-export interface LLMTransport {
-    stream(request: LLMRequest, apiKey: string, signal?: AbortSignal): AsyncGenerator<LLMChunk>;
+export interface ToolInvocationContext {
+    callId: string;
+    sessionId: string;
+    round: number;
 }
 export interface ToolInvoker {
-    invoke(turnId: string, name: string, args: string, signal?: AbortSignal): Promise<{
-        result: string;
-        error?: string;
-        toolReferences?: string[];
-        imageUrls?: string[];
-        contentBlocks?: AgentContentBlock[];
-        details?: Record<string, unknown>;
-    }>;
-}
-export interface TurnConfig {
-    model?: string;
-    maxRounds?: number;
-    temperature?: number;
-    contextWindowTokens?: number;
-    maxOutputTokens?: number;
-    modelMaxOutputTokens?: number;
-    maxTurns?: number;
-    maxToolCalls?: number;
-    maxConcurrentTools?: number;
-    parallelToolCalls?: boolean;
-    streamRequired?: boolean;
-    toolChoice?: "auto" | "none" | "required";
+    invoke(turnId: string, name: string, args: string, signal?: AbortSignal, invocation?: ToolInvocationContext): Promise<ToolResult>;
 }
 export interface TurnRequest {
     turnId: string;
@@ -137,102 +42,23 @@ export interface TurnRequest {
     tools: ToolDefinition[];
     systemPrompt?: string;
     config?: TurnConfig;
+    /** product-validated continuation; cloud consumers should use CloudCheckpoint. */
+    continuation?: {
+        completedRounds: number;
+        usage: TokenUsage;
+    };
 }
-export interface TokenUsage {
-    inputTokens?: number;
-    outputTokens?: number;
-    reasoningTokens?: number;
-    cacheRead?: number;
-    cacheWrite?: number;
-}
-export type TurnEvent = {
-    type: "start";
-    turnId: string;
-    effectiveMaxRounds?: number;
-    effectiveMaxToolCalls?: number;
-} | {
-    type: "delta";
-    turnId: string;
-    text: string;
-} | {
-    type: "tool_call";
-    turnId: string;
-    callId: string;
-    name: string;
-    displayName?: string;
-    arguments: string;
-    inputSummary?: string;
-} | {
-    type: "tool_result";
-    turnId: string;
-    callId: string;
-    name: string;
-    ok: boolean;
-    error?: string;
-    outputPreview?: string;
-    durationMs?: number;
-    details?: Record<string, unknown>;
-} | {
-    type: "tool_blocked";
-    turnId: string;
-    callId: string;
-    name: string;
-    reason: string;
-} | {
-    type: "recovery";
-    turnId: string;
-    action: string;
-    detail?: string;
-} | {
-    type: "text_rollback";
-    turnId: string;
-    keepLength: number;
-    reason: string;
-} | {
-    type: "reasoning_delta";
-    turnId: string;
-    text: string;
-} | {
-    type: "annotations";
-    turnId: string;
-    annotations: Array<{
-        type: string;
-        url?: string;
-        title?: string;
-        [key: string]: unknown;
-    }>;
-} | {
-    type: "tool_use_summary";
-    turnId: string;
-    ledgerSchemaVersion: 5;
-    toolCalls: Array<Record<string, unknown>>;
-    availableToolNames: string[];
-    enabledToolNames: string[];
-    toolCallNames: string[];
-    blockedToolCalls: Array<{
-        name: string;
-        reason: string;
-    }>;
-} | {
-    type: "end";
-    turnId: string;
-    content: string;
-    turnStatus?: "completed" | "stopped";
-    taskOutcome?: "unverified";
-    usage?: TokenUsage;
-    model?: string;
-    provider?: string;
-    recoveryTrace?: Record<string, number>;
-    contentBlocks?: AgentContentBlock[];
-} | {
-    type: "error";
-    turnId: string;
-    error: string;
-    code?: string;
-    usage?: TokenUsage;
-};
 export interface EmbeddedRuntimeOptions {
     maxToolResultChars?: number;
+    onCheckpoint?: (checkpoint: TurnCheckpoint) => Promise<void>;
+}
+export interface TurnCheckpoint {
+    turnId: string;
+    sessionId: string;
+    phase: "model_ready" | "tools_pending";
+    messages: ChatMessage[];
+    completedRounds: number;
+    usage: TokenUsage;
 }
 export interface EmbeddedAgent {
     run(request: TurnRequest, signal?: AbortSignal): AsyncGenerator<TurnEvent>;

package/dist/types/embedded/embedded-agent.d.ts

@@ -0,0 +1,2 @@
+import type { CreateEmbeddedAgentOptions, EmbeddedAgent } from "./contracts.js";
+export declare function createEmbeddedAgent(options: CreateEmbeddedAgentOptions): EmbeddedAgent;

package/dist/types/embedded/index.d.ts

@@ -1,5 +1,10 @@
-import type { CreateEmbeddedAgentOptions, EmbeddedAgent } from "./contracts.js";
-export declare function createEmbeddedAgent(options: CreateEmbeddedAgentOptions): EmbeddedAgent;
+export { createEmbeddedAgent } from "./embedded-agent.js";
 export { AgentContentBlockValidationError, analyzeEngineeringFile, createStandardPresentationToolResult, isEngineeringFile, parseAgentContentBlock, standardPresentationToolDefinitions, standardPresentationToolNames, } from "./content-blocks.js";
-export type { AgentLogger, ChatMessage, CreateEmbeddedAgentOptions, EmbeddedAgent, EmbeddedRuntimeOptions, LLMChunk, LLMRequest, LLMTransport, ToolDefinition, ToolInvoker, TurnConfig, TurnEvent, TurnRequest, } from "./contracts.js";
+export type { ContextAnchor, ContextEnvelope, SemanticToolCapability, ToolIdentity, UsageRecord, UsageSource, AgentLogger, ChatMessage, CreateEmbeddedAgentOptions, EmbeddedAgent, EmbeddedRuntimeOptions, LLMChunk, LLMRequest, LLMTransport, ModelRetryAuthorization, ToolDefinition, ToolInvoker, ToolInvocationContext, ToolResult, TurnCheckpoint, TokenUsage, TurnConfig, TurnEvent, TurnRequest, } from "./contracts.js";
+export type { ModelOperation, ModelRecoveryProof } from "./model-operation.js";
+export type { BusinessAssistantContext, BusinessGoal, BusinessGoalEvidence, BusinessGoalOutcome } from "./business-contracts.js";
+export { createCloudAgent, completeCloudToolCheckpoint, canonicalCloudValue } from "./cloud-agent.js";
+export type { CloudAgent, CloudAgentOptions, CloudCheckpoint, CloudExecutionContext, CloudToolInvocation, CloudToolReceipt, CloudToolWait, CloudTurnEvent, CloudTurnRequest, } from "./cloud-agent.js";
+export { createCloudTaskRuntime } from "./cloud-task.js";
+export type { CloudTaskStore, CloudTaskSnapshot, CloudTaskStatus, CloudTaskClaim, CloudTaskEvent, CloudTaskEventPayload, CloudTaskRuntime, CloudTaskRuntimeOptions, } from "./cloud-task.js";
 export type { AgentAttachment, AgentAttachmentContentBlock, AgentAttachmentKind, AgentChoiceContentBlock, AgentContentBlock, AgentDiagramContentBlock, AgentEngineeringFormat, AgentEngineeringMetadata, AgentEngineeringParseStatus, AgentEngineeringPreviewMode, AgentInputAttachmentEvidence, AgentTableCell, AgentTableContentBlock, EngineeringFileAnalysis, StandardPresentationToolDefinition, StandardPresentationToolName, } from "./content-blocks.js";

package/dist/types/embedded/model-operation.d.ts

@@ -0,0 +1,40 @@
+import type { UsageRecord } from "./contracts.js";
+import type { LLMChunk } from "./contracts.js";
+/** Product-persisted inference attempt. Request bodies/credentials are excluded; response is separately sensitive. */
+export interface ModelOperation {
+    requestId: string;
+    round: number;
+    attempt: number;
+    requestDigest: string;
+    model: string;
+    startedAtMs?: number;
+    finishedAtMs?: number;
+    status: "prepared" | "responding" | "completed" | "rejected" | "unknown";
+    responseId?: string;
+    finishReason?: string;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        records?: UsageRecord[];
+    };
+    /** Sensitive original response, owned by the product store; never included in progress events. */
+    response?: LLMChunk[];
+    reconciliationReference?: string;
+    budgetReference?: string;
+}
+/** Evidence returned by the authorized product after querying its model/billing service. */
+interface ModelRecoveryIdentity {
+    requestId: string;
+    requestDigest: string;
+    evidenceReference: string;
+}
+export type ModelRecoveryProof = ModelRecoveryIdentity & ({
+    outcome: "rejected";
+    safeToRetry: true;
+} | {
+    outcome: "completed";
+    response: LLMChunk[];
+    responseId: string;
+    usage?: ModelOperation["usage"];
+});
+export {};

package/dist/types/runtime/ports/agent-execution-contracts.d.ts

@@ -0,0 +1,25 @@
+import type { HookRegistry } from "../../contracts/hooks.js";
+import type { WireTokenUsage } from "../../contracts/usage.js";
+import type { ChatMessage as WireChatMessage, ToolDefinition as WireToolDefinition } from "../../contracts/chat.js";
+export type { TurnEvent } from "../../contracts/turn-event.js";
+export type ChatMessage = WireChatMessage;
+export type TokenUsage = WireTokenUsage;
+export type ToolDefinition = WireToolDefinition;
+export interface ToolInvoker {
+    invoke(turnId: string, name: string, args: string, signal?: AbortSignal, invocation?: {
+        callId: string;
+        sessionId: string;
+        round: number;
+    }): Promise<import("../../contracts/tool-result.js").ToolResult>;
+}
+export interface AgentLogger {
+    info(message: string): void;
+    info(obj: Record<string, unknown>, message: string): void;
+    warn(message: string): void;
+    warn(obj: Record<string, unknown>, message: string): void;
+    error(message: string): void;
+    error(obj: Record<string, unknown>, message: string): void;
+    debug(message: string): void;
+    debug(obj: Record<string, unknown>, message: string): void;
+}
+export type { HookRegistry };

package/dist/types/runtime/ports/agent-runtime-ports.d.ts

@@ -0,0 +1,66 @@
+import type { HookRegistry } from "../../contracts/hooks.js";
+import type { OpenAiToolCall } from "./tool-call-contracts.js";
+import type { AgentLogger, ChatMessage, TokenUsage, ToolInvoker } from "./agent-execution-contracts.js";
+export interface RuntimeCompressibleMessage {
+    role: string;
+    content?: string | unknown;
+}
+export interface RuntimeCompressionResult {
+    messages: RuntimeCompressibleMessage[];
+    droppedCount: number;
+    tokensFreed?: number;
+    strategy: string;
+}
+export interface ToolExecutionResultPort {
+    callId: string;
+    toolName: string;
+    ok: boolean;
+    error?: string;
+    blocked?: boolean;
+    blockReason?: string;
+    durationMs?: number;
+    details?: Record<string, unknown>;
+    message: unknown;
+}
+export interface StreamingToolExecutorPort {
+    addTool(toolCall: OpenAiToolCall): void;
+    getRemainingResults(): AsyncIterable<ToolExecutionResultPort>;
+}
+export interface StreamingToolExecutorPortConfig {
+    toolInvoker: ToolInvoker;
+    round?: number;
+    hooks?: HookRegistry;
+    sessionId: string;
+    turnId: string;
+    log: AgentLogger;
+    signal?: AbortSignal;
+    maxConcurrentTools?: number;
+    maxExecutionMs?: number;
+    executionTimeoutMsByTool?: ReadonlyMap<string, number>;
+}
+export interface ToolLoopRuntimePorts {
+    saveCheckpoint?(checkpoint: {
+        turnId: string;
+        sessionId: string;
+        phase: "model_ready" | "tools_pending";
+        messages: ChatMessage[];
+        completedRounds: number;
+        usage: TokenUsage;
+    }): Promise<void>;
+    enforceToolResultBudget(messages: Array<{
+        role: string;
+        content?: string | unknown;
+        tool_call_id?: string;
+    }>): Promise<{
+        messages: unknown[];
+        newlyReplacedCount: number;
+    }>;
+    compressMessages(messages: RuntimeCompressibleMessage[], options: {
+        budget: number;
+        model: string;
+    }): RuntimeCompressionResult;
+    createStreamingToolExecutor(config: StreamingToolExecutorPortConfig): StreamingToolExecutorPort;
+}
+export interface AgentRuntimePorts {
+    toolLoop: ToolLoopRuntimePorts;
+}

package/dist/types/runtime/ports/index.d.ts

@@ -0,0 +1,5 @@
+export { buildToolResultMessage, type OpenAiToolCall, type ToolResultMessageInput } from "./tool-call-contracts.js";
+export type { AgentLogger, ChatMessage, TokenUsage, ToolDefinition, ToolInvoker, TurnEvent } from "./agent-execution-contracts.js";
+export type { AccumulatedToolCall, LLMChunk, LLMRequest, LLMTransport } from "./model-transport-contracts.js";
+export { accumulateToolCalls } from "./model-transport-contracts.js";
+export type { AgentRuntimePorts, RuntimeCompressibleMessage, RuntimeCompressionResult, StreamingToolExecutorPort, StreamingToolExecutorPortConfig, ToolExecutionResultPort, ToolLoopRuntimePorts } from "./agent-runtime-ports.js";