@peer-agent/runtime-sdk 0.1.0-rc.3 → 0.1.0-rc.31

package/dist/contracts.d.ts

@@ -3,7 +3,7 @@ import type { ContextAccountingSnapshot, RuntimeExecuteRequest, RuntimeExecution
 export type { RuntimeExecuteRequest, RuntimeExecutionContext, RuntimeToolCall, RuntimeToolResult, } from '@peer-agent/protocol';
 export declare const RUNTIME_EVENT_PROTOCOL_VERSION: 1;
 export type RuntimeEventProtocolVersion = typeof RUNTIME_EVENT_PROTOCOL_VERSION;
-export type RuntimeSdkEventType = 'session.started' | 'message.delta' | 'reasoning.delta' | 'message.completed' | 'runtime.error' | 'tool.started' | 'hook.completed' | 'permission.requested' | 'permission.resolved' | 'tool.completed' | 'compaction.progress' | 'context.accounting';
+export type RuntimeSdkEventType = 'session.started' | 'message.delta' | 'reasoning.delta' | 'stream.discard' | 'message.completed' | 'runtime.error' | 'tool.started' | 'hook.completed' | 'permission.requested' | 'permission.resolved' | 'tool.completed' | 'compaction.progress' | 'context.accounting';
 export type RuntimeSdkToolCall = RuntimeToolCall;
 export type RuntimeSdkExecuteRequest = RuntimeExecuteRequest;
 export type RuntimeSdkExecutionContext = RuntimeExecutionContext;
@@ -93,6 +93,12 @@ export interface RuntimeSdkReasoningDeltaEvent extends RuntimeSdkEventBase {
  * Mid-turn / automatic compaction progress for host UI surfaces.
  * percent is 0-100; hosts should treat values below 100 as live progress.
  */
+export interface RuntimeSdkStreamDiscardEvent extends RuntimeSdkEventBase {
+    readonly type: 'stream.discard';
+    readonly streamId: string;
+    readonly textChars: number;
+    readonly reasoningChars: number;
+}
 export interface RuntimeSdkCompactionProgressEvent extends RuntimeSdkEventBase {
     readonly type: 'compaction.progress';
     readonly streamId: string;
@@ -153,7 +159,7 @@ export interface RuntimeSdkToolCompletedEvent extends RuntimeSdkEventBase {
     readonly decision: RuntimeDecision;
     readonly result: RuntimeSdkToolResult;
 }
-export type RuntimeSdkEvent = RuntimeSdkSessionStartedEvent | RuntimeSdkMessageDeltaEvent | RuntimeSdkReasoningDeltaEvent | RuntimeSdkCompactionProgressEvent | RuntimeSdkContextAccountingEvent | RuntimeSdkMessageCompletedEvent | RuntimeSdkRuntimeErrorEvent | RuntimeSdkToolStartedEvent | RuntimeSdkHookCompletedEvent | RuntimeSdkPermissionRequestedEvent | RuntimeSdkPermissionResolvedEvent | RuntimeSdkToolCompletedEvent;
+export type RuntimeSdkEvent = RuntimeSdkSessionStartedEvent | RuntimeSdkMessageDeltaEvent | RuntimeSdkReasoningDeltaEvent | RuntimeSdkStreamDiscardEvent | RuntimeSdkCompactionProgressEvent | RuntimeSdkContextAccountingEvent | RuntimeSdkMessageCompletedEvent | RuntimeSdkRuntimeErrorEvent | RuntimeSdkToolStartedEvent | RuntimeSdkHookCompletedEvent | RuntimeSdkPermissionRequestedEvent | RuntimeSdkPermissionResolvedEvent | RuntimeSdkToolCompletedEvent;
 export type RuntimeSdkEventInput = RuntimeSdkEvent extends infer Event ? Event extends RuntimeSdkEvent ? Omit<Event, 'protocolVersion' | 'eventId' | 'sequence' | 'occurredAt'> : never : never;
 export type RuntimeSdkEventListener = (event: RuntimeSdkEvent) => void;
 export interface RuntimeSdkOptions {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { RUNTIME_EVENT_PROTOCOL_VERSION } from './contracts.ts';
-export type { RuntimeEventProtocolVersion, RuntimeExecuteRequest, RuntimeExecutionContext, RuntimeToolCall, RuntimeToolResult, RuntimeSdk, RuntimeSdkApprovalDecision, RuntimeSdkApprovalPort, RuntimeSdkEvent, RuntimeSdkEventBase, RuntimeSdkEventInput, RuntimeSdkEventListener, RuntimeSdkEventType, RuntimeSdkSessionStartedEvent, RuntimeSdkMessageDeltaEvent, RuntimeSdkReasoningDeltaEvent, RuntimeSdkCompactionProgressEvent, RuntimeSdkContextAccountingEvent, RuntimeSdkMessageCompletedEvent, RuntimeSdkRuntimeErrorEvent, RuntimeSdkHookCompletedEvent, RuntimeSdkPermissionRequestedEvent, RuntimeSdkPermissionResolvedEvent, RuntimeSdkToolCompletedEvent, RuntimeSdkToolStartedEvent, RuntimeSdkExecuteRequest, RuntimeSdkExecutionContext, RuntimeSdkHookPayload, RuntimeSdkHookRecord, RuntimeSdkHookRunner, RuntimeSdkHostAdapter, RuntimeSdkOptions, RuntimeSdkPermissionRequest, RuntimeSdkProviderExecution, RuntimeSdkToolCall, RuntimeSdkToolResult, } from './contracts.ts';
+export type { RuntimeEventProtocolVersion, RuntimeExecuteRequest, RuntimeExecutionContext, RuntimeToolCall, RuntimeToolResult, RuntimeSdk, RuntimeSdkApprovalDecision, RuntimeSdkApprovalPort, RuntimeSdkEvent, RuntimeSdkEventBase, RuntimeSdkEventInput, RuntimeSdkEventListener, RuntimeSdkEventType, RuntimeSdkSessionStartedEvent, RuntimeSdkMessageDeltaEvent, RuntimeSdkReasoningDeltaEvent, RuntimeSdkStreamDiscardEvent, RuntimeSdkCompactionProgressEvent, RuntimeSdkContextAccountingEvent, RuntimeSdkMessageCompletedEvent, RuntimeSdkRuntimeErrorEvent, RuntimeSdkHookCompletedEvent, RuntimeSdkPermissionRequestedEvent, RuntimeSdkPermissionResolvedEvent, RuntimeSdkToolCompletedEvent, RuntimeSdkToolStartedEvent, RuntimeSdkExecuteRequest, RuntimeSdkExecutionContext, RuntimeSdkHookPayload, RuntimeSdkHookRecord, RuntimeSdkHookRunner, RuntimeSdkHostAdapter, RuntimeSdkOptions, RuntimeSdkPermissionRequest, RuntimeSdkProviderExecution, RuntimeSdkToolCall, RuntimeSdkToolResult, } from './contracts.ts';
 export type { RuntimePipeline, RuntimePipelineCompletedTurn, RuntimePipelineContinueTurn, RuntimePipelineEventSink, RuntimePipelineLifecycleObserver, RuntimePipelineModelAdapter, RuntimePipelineOptions, RuntimePipelineRunInput, RuntimePipelineRunResult, RuntimePipelineStatus, RuntimePipelineToolCall, RuntimePipelineToolCallsTurn, RuntimePipelineToolExecution, RuntimePipelineToolExecutor, RuntimePipelineTurnContext, RuntimePipelineTurnResult, } from './pipeline-contracts.ts';
 export { createRuntimePipeline } from './pipeline.ts';
 export { createRuntimeSdk } from './runtime.ts';

package/dist/pipeline-contracts.d.ts

@@ -1,5 +1,5 @@
 import type { RuntimeSdkEvent, RuntimeSdkEventInput, RuntimeSdkToolResult } from './contracts.ts';
-export type RuntimePipelineStatus = 'completed' | 'stopped' | 'cancelled' | 'exhausted' | 'failed';
+export type RuntimePipelineStatus = 'completed' | 'stopped' | 'cancelled' | 'yielded' | 'exhausted' | 'failed';
 export interface RuntimePipelineRunInput<TInput = unknown> {
     readonly sessionId: string;
     readonly streamId?: string;
@@ -9,6 +9,13 @@ export interface RuntimePipelineRunInput<TInput = unknown> {
     readonly model?: string;
     readonly input: TInput;
     readonly maxTurns?: number;
+    readonly maxToolCalls?: number;
+    /** Scheduling allowance; unlike maxToolCalls this can end at a batch boundary. */
+    readonly sliceToolCalls?: number;
+    readonly yieldAtTurnLimit?: boolean;
+    /** Host scheduling request, checked at durable batch boundaries. */
+    readonly shouldYield?: () => boolean;
+    readonly maxToolBatchCalls?: number;
 }
 export interface RuntimePipelineToolCall<TPayload = unknown> {
     readonly toolCallId: string;
@@ -49,12 +56,17 @@ export interface RuntimePipelineModelAdapter<TInput = unknown, TState = unknown,
     initialize(input: RuntimePipelineRunInput<TInput>, context: RuntimePipelineTurnContext<TInput>): TState | Promise<TState>;
     runTurn(state: TState, context: RuntimePipelineTurnContext<TInput>): RuntimePipelineTurnResult<TState, TCall, TOutput> | Promise<RuntimePipelineTurnResult<TState, TCall, TOutput>>;
     applyToolResults(state: TState, executions: readonly RuntimePipelineToolExecution<TCall, TToolResult>[], context: RuntimePipelineTurnContext<TInput>): TState | Promise<TState>;
+    /** Critical durable commit after paired tool results; failure ends execution. */
+    checkpoint?(state: TState, executions: readonly RuntimePipelineToolExecution<TCall, TToolResult>[], context: RuntimePipelineTurnContext<TInput>): void | Promise<void>;
     onCompleted?(state: TState, output: TOutput | undefined, context: RuntimePipelineTurnContext<TInput>): void | Promise<void>;
     onStopped?(state: TState, executions: readonly RuntimePipelineToolExecution<TCall, TToolResult>[], context: RuntimePipelineTurnContext<TInput>): void | Promise<void>;
     onCancelled?(state: TState | undefined, context: RuntimePipelineTurnContext<TInput>): void | Promise<void>;
-    onExhausted?(state: TState, context: RuntimePipelineTurnContext<TInput>): void | Promise<void>;
+    onYield?(state: TState, context: RuntimePipelineTurnContext<TInput>): void | Promise<void>;
+    onExhausted?(state: TState, context: RuntimePipelineTurnContext<TInput>, reason: 'max_turns_exceeded' | 'max_tool_calls_exceeded'): void | Promise<void>;
 }
 export interface RuntimePipelineToolExecutor<TInput = unknown, TCall extends RuntimePipelineToolCall = RuntimePipelineToolCall, TToolResult = RuntimeSdkToolResult> {
+    /** Build a paired, explicit non-execution result without dispatching a capability. */
+    notExecuted?(call: TCall, reason: string): RuntimePipelineToolExecution<TCall, TToolResult> | Promise<RuntimePipelineToolExecution<TCall, TToolResult>>;
     execute(call: TCall, context: RuntimePipelineTurnContext<TInput> & {
         readonly index: number;
     }): RuntimePipelineToolExecution<TCall, TToolResult> | Promise<RuntimePipelineToolExecution<TCall, TToolResult>>;

package/dist/pipeline.js

@@ -34,6 +34,10 @@ export function createRuntimePipeline(options) {
                 throw new Error('RuntimePipeline run requires sessionId.');
             const signal = context.signal;
             const maxTurns = normalizeMaxTurns(input.maxTurns, defaultMaxTurns);
+            const maxToolCalls = Number.isFinite(input.maxToolCalls)
+                ? Math.max(0, Math.floor(input.maxToolCalls)) : Number.POSITIVE_INFINITY;
+            const sliceToolCalls = Number.isFinite(input.sliceToolCalls) ? Math.max(1, input.sliceToolCalls) : Infinity;
+            const maxBatch = Number.isFinite(input.maxToolBatchCalls) ? Math.max(1, input.maxToolBatchCalls) : Infinity;
             let state;
             let turns = 0;
             let toolCalls = 0;
@@ -56,6 +60,15 @@ export function createRuntimePipeline(options) {
                 signal,
                 emit,
             });
+            const exhaust = async (reason) => {
+                await options.model.onExhausted?.(state, turnContext(turns), reason);
+                emit({ type: 'runtime.error', ...eventBase, code: reason, message: reason });
+                return { status: 'exhausted', state, turns, toolCalls, reason };
+            };
+            const yieldRun = async () => {
+                await options.model.onYield?.(state, turnContext(turns));
+                return { status: 'yielded', state, turns, toolCalls, reason: 'scheduling_slice' };
+            };
             try {
                 throwIfAborted(signal);
                 emit({
@@ -68,12 +81,17 @@ export function createRuntimePipeline(options) {
                 state = await options.model.initialize(input, turnContext(0));
                 for (let turn = 0; turn < maxTurns; turn += 1) {
                     throwIfAborted(signal);
+                    if (input.shouldYield?.() === true)
+                        return await yieldRun();
                     turns = turn + 1;
                     const currentContext = turnContext(turn);
                     const outcome = await options.model.runTurn(state, currentContext);
                     state = outcome.state;
-                    if (outcome.kind === 'continue')
+                    if (outcome.kind === 'continue') {
+                        if (input.shouldYield?.() === true)
+                            return await yieldRun();
                         continue;
+                    }
                     if (outcome.kind === 'completed') {
                         await options.model.onCompleted?.(state, outcome.output, currentContext);
                         if (input.streamId) {
@@ -93,30 +111,65 @@ export function createRuntimePipeline(options) {
                             ...(outcome.reason ? { reason: outcome.reason } : {}),
                         };
                     }
+                    // Reserve the whole batch before dispatch. Never execute a partial
+                    // write batch or exceed a caller's remaining budget inside one turn.
+                    if (outcome.calls.length > maxBatch)
+                        throw new Error('tool_batch_too_large');
+                    if (toolCalls + outcome.calls.length > maxToolCalls) {
+                        if (options.tools.notExecuted) {
+                            const denied = await Promise.all(outcome.calls.map(call => options.tools.notExecuted(call, 'max_tool_calls_exceeded')));
+                            state = await options.model.applyToolResults(state, denied, currentContext);
+                            await options.model.checkpoint?.(state, denied, currentContext);
+                        }
+                        return await exhaust('max_tool_calls_exceeded');
+                    }
                     const executions = [];
                     if (isParallelSafeLocalToolBatch(outcome.calls)) {
                         const batch = await Promise.all(outcome.calls.map(async (call, index) => {
+                            if (signal?.aborted && options.tools.notExecuted)
+                                return options.tools.notExecuted(call, 'cancelled');
                             throwIfAborted(signal);
-                            return options.tools.execute(call, {
-                                ...currentContext,
-                                index,
-                            });
+                            try {
+                                return await options.tools.execute(call, { ...currentContext, index });
+                            }
+                            catch (error) {
+                                if (!options.tools.notExecuted)
+                                    throw error;
+                                return options.tools.notExecuted(call, isAbortError(error) ? 'cancelled_outcome_unknown' : 'execution_outcome_unknown');
+                            }
                         }));
                         executions.push(...batch);
                         toolCalls += batch.length;
                     }
                     else {
                         for (const [index, call] of outcome.calls.entries()) {
-                            throwIfAborted(signal);
-                            const execution = await options.tools.execute(call, {
-                                ...currentContext,
-                                index,
-                            });
+                            let execution;
+                            if (signal?.aborted && options.tools.notExecuted)
+                                execution = await options.tools.notExecuted(call, 'cancelled');
+                            else {
+                                throwIfAborted(signal);
+                                try {
+                                    execution = await options.tools.execute(call, { ...currentContext, index });
+                                }
+                                catch (error) {
+                                    if (!options.tools.notExecuted)
+                                        throw error;
+                                    execution = await options.tools.notExecuted(call, isAbortError(error) ? 'cancelled_outcome_unknown' : 'execution_outcome_unknown');
+                                }
+                            }
                             executions.push(execution);
                             toolCalls += 1;
+                            if (execution.terminal && options.tools.notExecuted) {
+                                for (const remaining of outcome.calls.slice(index + 1))
+                                    executions.push(await options.tools.notExecuted(remaining, 'batch_stopped'));
+                                break;
+                            }
                         }
                     }
                     state = await options.model.applyToolResults(state, executions, currentContext);
+                    // Completed results remain durable even when cancellation arrived during execution.
+                    await options.model.checkpoint?.(state, executions, currentContext);
+                    throwIfAborted(signal);
                     try {
                         await options.lifecycle?.toolResultsApplied?.(state, executions, currentContext);
                     }
@@ -143,23 +196,10 @@ export function createRuntimePipeline(options) {
                             reason: terminalExecution.terminalReason || 'tool_requested_stop',
                         };
                     }
+                    if (toolCalls >= sliceToolCalls || input.shouldYield?.() === true)
+                        return await yieldRun();
                 }
-                const exhaustedContext = turnContext(turns);
-                await options.model.onExhausted?.(state, exhaustedContext);
-                const exhaustedReason = 'max_turns_exceeded';
-                emit({
-                    type: 'runtime.error',
-                    ...eventBase,
-                    code: exhaustedReason,
-                    message: exhaustedReason,
-                });
-                return {
-                    status: 'exhausted',
-                    state,
-                    turns,
-                    toolCalls,
-                    reason: exhaustedReason,
-                };
+                return input.yieldAtTurnLimit ? await yieldRun() : await exhaust('max_turns_exceeded');
             }
             catch (error) {
                 if (signal?.aborted || isAbortError(error)) {

package/dist/runtime.js

@@ -130,9 +130,15 @@ export function createRuntimeSdk(options) {
             decision: mostRestrictiveHookDecision(postRecords),
             records: postRecords,
         });
-        const result = options.host.appendHookEvidence
+        let result = options.host.appendHookEvidence
             ? options.host.appendHookEvidence(execution.result, [...preRecords, ...postRecords], preDecision)
             : execution.result;
+        // Host-only sideband must survive a Hook Evidence clone without becoming
+        // enumerable event/storage data. Model-supplied fields cannot create it.
+        const sideband = Object.getOwnPropertyDescriptor(execution.result, 'modelContext');
+        if (result !== execution.result && sideband && sideband.enumerable === false) {
+            result = Object.defineProperty({ ...result }, 'modelContext', sideband);
+        }
         const resolvedExecution = { ...execution, result };
         emit({ type: 'tool.completed', ...eventBase, decision: preDecision, result });
         return resolvedExecution;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peer-agent/runtime-sdk",
-  "version": "0.1.0-rc.3",
+  "version": "0.1.0-rc.31",
   "description": "Public host-neutral orchestration SDK for Peer Agent runtimes.",
   "type": "module",
   "license": "MIT",
@@ -34,8 +34,8 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@peer-agent/protocol": "^0.1.0-rc.3",
-    "@peer-agent/runtime-core": "^0.1.0-rc.3"
+    "@peer-agent/protocol": "^0.1.0-rc.31",
+    "@peer-agent/runtime-core": "^0.1.0-rc.31"
   },
   "devDependencies": {
     "typescript": "^5.9.3"