eve 0.71.2 → 0.72.0

package/dist/src/harness/session-machine/transitions.d.ts

@@ -0,0 +1,188 @@
+import type { ModelMessage, UserContent } from "ai";
+import type { SubagentAuthorizationEventHookPayload, SubagentInputRequestHookPayload } from "#channel/types.js";
+import type { AuthorizationChallenge } from "#harness/authorization.js";
+import { type TurnWaitingOn, createSessionCompletedEvent, createSessionFailedEvent, type InputResolution, type RuntimeIdentity, type RuntimeTraceContext, type TaskCancelReason, type TaskStartedStreamEvent, type UnstampedMessageStreamEvent } from "#protocol/message.js";
+import type { RuntimeActionResult } from "#shared/action-types.js";
+import type { InputRequest } from "#shared/input.js";
+import type { JsonObject, JsonValue } from "#shared/json.js";
+import type { TokenUsage } from "#shared/token-usage.js";
+import type { Transition } from "./commit.js";
+import type { StepCoordinates, SuspendedStep, TurnState } from "./state.js";
+import { type SessionView } from "./view.js";
+type ToolResponsePart = Extract<ModelMessage, {
+    role: "tool";
+}>["content"][number];
+export type ToolResultPart = Extract<ToolResponsePart, {
+    type: "tool-result";
+}>;
+/**
+ * Input arrives: the session starts once, a turn opens unless one is open (steering joins it),
+ * and a message is received.
+ */
+export declare function receive(view: SessionView, input: {
+    readonly message?: string | UserContent;
+    readonly runtime?: RuntimeIdentity;
+    readonly trace?: RuntimeTraceContext;
+}): Transition;
+/** The open turn calls the model. */
+export declare function startStep(view: SessionView, input: {
+    readonly modelId: string;
+}): Transition;
+/**
+ * The open turn parks: on `"tasks"` while work it started runs, on `"input"` while a person must
+ * act on a sign-in, approval, or question. It resumes in the same turn.
+ */
+export declare function hold(view: SessionView, input: {
+    readonly on: TurnWaitingOn;
+}): Transition;
+/** Nothing is left to run: the turn completes, with its structured result when it has one. */
+export declare function finishTurn(view: SessionView, input?: {
+    readonly result?: JsonValue;
+}): Transition;
+/**
+ * The step failed. A recoverable failure parks the session for the user to retry; a terminal
+ * one ends it.
+ */
+export declare function fail(view: SessionView, failure: {
+    readonly code: string;
+    readonly details?: JsonObject;
+    readonly message: string;
+    readonly terminal?: {
+        readonly sessionId: string;
+    };
+}): Transition;
+/** The session waits for its next delivery. */
+export declare function idle(view: SessionView): Transition;
+export declare function sessionCompleted(usage: TokenUsage | undefined): ReturnType<typeof createSessionCompletedEvent>;
+export declare function sessionFailed(input: {
+    readonly code: string;
+    readonly details?: JsonObject;
+    readonly message: string;
+    readonly sessionId: string;
+    readonly usage: TokenUsage | undefined;
+}): ReturnType<typeof createSessionFailedEvent>;
+/** One call's result, ready for its step's transcript. */
+export interface SettledCall {
+    readonly part: ToolResultPart;
+    /** A runtime result, reported at the coordinates of the step that made the call. */
+    readonly result?: RuntimeActionResult;
+}
+/**
+ * Results reach the steps that made their calls. A step whose every call now has a result
+ * commits to history, where the model reads it.
+ */
+export declare function settle(view: SessionView, input: {
+    readonly results: readonly SettledCall[];
+}): {
+    commit: ModelMessage[];
+    events: UnstampedMessageStreamEvent[];
+    turn: {
+        queued?: import("../types.ts").StepInput;
+        grants: readonly string[];
+        suspended: SuspendedStep[];
+    };
+};
+/**
+ * A model response made calls the runtime runs. The response waits in a suspended step until
+ * every call it made has a result, so a call never reaches the model without its result.
+ */
+export declare function suspendStep(view: SessionView, step: Pick<SuspendedStep, "event" | "messages" | "tasks">): Transition;
+/** The step without the approved calls in `callIds`, which have run or joined the runtime. */
+export declare function withoutApproved(step: SuspendedStep, callIds: ReadonlySet<string>): SuspendedStep;
+/** Approved calls of suspended steps that haven't run. */
+export declare function approvedCalls(turn: TurnState): readonly InputRequest[];
+export declare function suspend(turn: TurnState, step: SuspendedStep): TurnState;
+/** The ids of the calls a step's response made, except provider-executed ones. */
+export declare function stepCallIds(step: Pick<SuspendedStep, "messages">): ReadonlySet<string>;
+/** Places a result right after the message that made its call. */
+export declare function withResult(messages: readonly ModelMessage[], part: ToolResultPart): ModelMessage[];
+/** A call started or reached a task. */
+export declare function startTask(view: SessionView, task: TaskStartedStreamEvent["data"]): Transition;
+export type TaskCallOutcome = {
+    readonly status: "completed";
+    readonly output?: JsonValue;
+} | {
+    readonly status: "failed";
+    readonly error: string;
+} | {
+    readonly status: "cancelled";
+    readonly reason?: TaskCancelReason;
+};
+/** A task's run settled calls: each reports its outcome, naming the task as it started. */
+export declare function settleTask(view: SessionView, input: {
+    readonly task: {
+        readonly id: string;
+        readonly kind?: TaskStartedStreamEvent["data"]["kind"];
+        readonly name?: string;
+    };
+    readonly calls: readonly {
+        readonly callId: string;
+        readonly turnId: string;
+    }[];
+    readonly outcome: TaskCallOutcome;
+}): Transition;
+/**
+ * A task or workflow run ended, on its own or cancelled: nobody can answer what it relayed, so
+ * each request still open is withdrawn.
+ */
+export declare function finishRun(view: SessionView, run: {
+    readonly taskId?: string;
+    readonly requestIds?: Iterable<string>;
+}): Transition;
+/**
+ * A child session or workflow run asks a question or for a sign-in. The session passes it up
+ * with its original coordinates, and the open turn waits on the call it serves.
+ * A child's fresh batch replaces its earlier one, whose open requests are withdrawn.
+ */
+export declare function relay(view: SessionView, input: {
+    readonly payload: SubagentInputRequestHookPayload | SubagentAuthorizationEventHookPayload;
+    readonly replacedRequestIds?: Iterable<string>;
+}): Transition;
+/**
+ * Answers to relayed requests are on their way to the asker: each request resolves here.
+ */
+export declare function receiveRelayedAnswer(input: {
+    readonly message: string | UserContent;
+    readonly sequence: number;
+    readonly turnId: string;
+}): import("#protocol/message.js").MessageReceivedStreamEvent;
+export declare function routeAnswer(view: SessionView, input: {
+    readonly children: readonly {
+        readonly event: StepCoordinates;
+        readonly resolutions: readonly InputResolution[];
+    }[];
+}): Transition;
+/**
+ * A workflow run's sign-in, reported to the session that owns the run, which relays it. Built
+ * where the run asks, at the coordinates of the call it serves.
+ */
+export declare function runSignIn(from: {
+    readonly sequence: number;
+    readonly stepIndex: number;
+    readonly taskId?: string;
+    readonly turnId: string;
+}, challenge: AuthorizationChallenge, outcome?: "authorized" | "failed"): import("#protocol/message.js").AuthorizationCompletedStreamEvent | import("#protocol/message.js").AuthorizationRequiredStreamEvent;
+/** Sign-in callbacks arrived: each completion is reported at the coordinates of the turn that asked. */
+export declare function completeSignIn(view: SessionView, input: {
+    readonly completions: readonly AuthorizationChallenge[];
+}): Transition;
+/** Requests this session asked itself and still awaits; relayed requests answer elsewhere. */
+export declare function ownOpenRequestIds(view: Omit<SessionView, "turn">): ReadonlySet<string>;
+/** What the model reads for a call its turn's cancellation stopped before the call settled. */
+export declare const CANCELLED_CALL_RESULT = "The turn was cancelled before this call finished.";
+/**
+ * `session.cancel()`: the open turn ends cancelled. Its requests, its sign-ins, and every
+ * relayed request are withdrawn, since the cancel stops the work that asked them; its unsettled
+ * calls are stopped. The steps it ran commit to history, each unfinished call answered as
+ * cancelled, so the model sees that the work started and stopped.
+ */
+export declare function cancel(view: SessionView): Transition;
+/**
+ * `session.clear()`: everything the cleared history asked for is withdrawn, its approvals and
+ * the session-limit prompt and every sign-in, and the calls awaiting them stop. Requests relayed
+ * from live tasks stay: clearing doesn't stop the work that asked them.
+ */
+export declare function clear(view: SessionView, input: {
+    readonly sessionId: string;
+}): Transition;
+export {};

package/dist/src/harness/session-machine/transitions.js

@@ -0,0 +1 @@
+import{activeTurnId,answeredCallIds,nextStepIndex,turnPosition}from"./view.js";import{inputWithdrawn,signInWithdrawn}from"./events.js";import{openInputs,openSignIns,turnCoordinates}from"#protocol/session-projection.js";import{createActionResultEvent,createAuthorizationCompletedEvent,createAuthorizationRequiredEvent,createContextClearedEvent,createInputRequestedEvent,createInputResolvedEvent,createMessageReceivedEvent,createResultCompletedEvent,createSessionCompletedEvent,createSessionFailedEvent,createSessionStartedEvent,createSessionWaitingEvent,createStepFailedEvent,createStepStartedEvent,createTaskSettledEvent,createTaskStartedEvent,createTurnCancelledEvent,createTurnCompletedEvent,createTurnFailedEvent,createTurnStartedEvent,createTurnWaitingEvent}from"#protocol/message.js";import{authorizationEventFields}from"#harness/authorization-event-fields.js";const unchanged=(e,t)=>({events:t,turn:e.turn});function at(e){let t=turnPosition(e);return{sequence:t.sequence,stepIndex:t.stepIndex,turnId:activeTurnId(t)}}function receive(e,t){let n=turnPosition(e.projection),r=activeTurnId(n),i=[];return n.sessionStarted||i.push(createSessionStartedEvent({runtime:t.runtime,trace:t.trace})),n.turnId===``&&i.push(createTurnStartedEvent({sequence:n.sequence,trace:t.trace,turnId:r})),t.message!==void 0&&i.push(createMessageReceivedEvent({message:t.message,sequence:n.sequence,turnId:r})),unchanged(e,i)}function startStep(e,t){let{sequence:n,turnId:r}=at(e.projection);return unchanged(e,[createStepStartedEvent({modelId:t.modelId,sequence:n,stepIndex:nextStepIndex(e.projection),turnId:r})])}function hold(e,t){let{sequence:n,turnId:r}=turnPosition(e.projection);return r===``?unchanged(e,[]):unchanged(e,[createTurnWaitingEvent({on:t.on,sequence:n,turnId:r,usage:e.usage})])}function finishTurn(e,t={}){let{sequence:n,stepIndex:r,turnId:i}=at(e.projection),a=[];return t.result!==void 0&&a.push(createResultCompletedEvent({result:t.result,sequence:n,stepIndex:r,turnId:i})),e.projection.activeTurnId!==void 0&&a.push(createTurnCompletedEvent({sequence:n,turnId:i})),a.push(createSessionWaitingEvent(e.usage)),unchanged(e,a)}function fail(e,t){let{sequence:n,stepIndex:r,turnId:i}=at(e.projection),a=e.turn.suspended.filter(e=>(e.approved?.length??0)>0);return{commit:a.flatMap(cancelledTranscript),events:failedEvents(e,t,{sequence:n,stepIndex:r,turnId:i}),turn:{...e.turn,suspended:e.turn.suspended.filter(e=>!a.includes(e))}}}function failedEvents(e,t,n){let{sequence:r,stepIndex:i,turnId:a}=n,{code:o,details:s,message:c}=t;return[createStepFailedEvent({code:o,details:s,message:c,sequence:r,stepIndex:i,turnId:a}),createTurnFailedEvent({code:o,details:s,message:c,sequence:r,turnId:a}),t.terminal===void 0?createSessionWaitingEvent(e.usage):createSessionFailedEvent({code:o,details:s,message:c,sessionId:t.terminal.sessionId,usage:e.usage})]}function idle(e){return unchanged(e,[createSessionWaitingEvent(e.usage)])}function sessionCompleted(e){return createSessionCompletedEvent(e)}function sessionFailed(e){return createSessionFailedEvent(e)}function settle(e,t){let n=[],r=[...e.turn.suspended];for(let{part:e,result:i}of t.results){let t=r.findIndex(t=>stepCallIds(t).has(e.toolCallId)),a=r[t];a!==void 0&&(r[t]=withoutApproved({...a,messages:withResult(a.messages,e)},new Set([e.toolCallId])),i!==void 0&&n.push(createActionResultEvent({result:i,...a.event})))}let i=r.filter(isComplete);return{commit:i.flatMap(e=>e.messages),events:n,turn:{...e.turn,suspended:r.filter(e=>!i.includes(e))}}}function suspendStep(e,t){return{events:[],turn:suspend(e.turn,{...t,requests:[]})}}function withoutApproved(e,t){if(e.approved===void 0)return e;let n=e.approved.filter(e=>!t.has(e.action.callId));if(n.length===e.approved.length)return e;let{approved:r,...i}=e;return n.length===0?i:{...i,approved:n}}function approvedCalls(e){return e.suspended.flatMap(e=>e.approved??[])}function suspend(e,t){return{...e,suspended:[...e.suspended,t]}}function stepCallIds(e){let t=new Set;for(let n of e.messages)if(n.role===`assistant`&&typeof n.content!=`string`)for(let e of n.content)e.type===`tool-call`&&e.providerExecuted!==!0&&t.add(e.toolCallId);return t}function isComplete(e){if(e.requests.length>0)return!1;let t=answeredCallIds(e.messages);return[...stepCallIds(e)].every(e=>t.has(e))}function withResult(e,t){let n=[...e],r=n.findIndex(e=>e.role===`assistant`&&Array.isArray(e.content)&&e.content.some(e=>e.type===`tool-call`&&e.toolCallId===t.toolCallId)),i=n[r+1];return r>=0&&i?.role===`tool`?n[r+1]={...i,content:[...i.content,t]}:n.splice(r>=0?r+1:n.length,0,{content:[t],role:`tool`}),n}function startTask(e,t){return unchanged(e,[createTaskStartedEvent(t)])}function settleTask(e,t){let{outcome:n,task:r}=t;return unchanged(e,t.calls.map(e=>{let t={callId:e.callId,kind:r.kind,name:r.name,taskId:r.id,turnId:e.turnId};switch(n.status){case`completed`:return createTaskSettledEvent({...t,output:n.output,status:`completed`});case`failed`:return createTaskSettledEvent({...t,error:{message:n.error},status:`failed`});case`cancelled`:return createTaskSettledEvent(n.reason===void 0?{...t,status:`cancelled`}:{...t,cancel:{reason:n.reason},status:`cancelled`})}}))}function finishRun(e,t){let n=new Set(t.requestIds);return unchanged(e,openInputs(e.projection).filter(e=>n.has(e.request.requestId)||t.taskId!==void 0&&e.taskId===t.taskId).map(inputWithdrawn))}function relay(e,t){let{payload:n}=t,r=[...finishRun(e,{requestIds:t.replacedRequestIds}).events];if(n.kind===`subagent-input-request`){let{event:e}=n;r.push(createInputRequestedEvent({callId:n.callId,requests:e.requests,sequence:e.sequence,stepIndex:e.stepIndex,taskId:e.taskId,turnId:e.turnId}))}else{let{event:t}=n;if(r.push(t),t.type!==`authorization.required`)return unchanged(e,r)}return r.push(...hold(e,{on:`input`}).events),unchanged(e,r)}function receiveRelayedAnswer(e){return createMessageReceivedEvent(e)}function routeAnswer(e,t){let n=t.children.filter(e=>e.resolutions.length>0).map(e=>createInputResolvedEvent({resolutions:e.resolutions,...e.event}));return unchanged(e,n)}function runSignIn(e,t,n){let r={...authorizationEventFields(t),sequence:e.sequence,stepIndex:e.stepIndex,taskId:e.taskId,turnId:e.turnId};return n===void 0?createAuthorizationRequiredEvent({...r,description:`Sign in to ${t.name} to continue.`,webhookUrl:t.hookUrl}):createAuthorizationCompletedEvent({...r,outcome:n})}function completeSignIn(e,t){let n=at(e.projection);return unchanged(e,t.completions.map(t=>{let r=t.attemptId===void 0?void 0:e.projection.authorizations[t.attemptId];return createAuthorizationCompletedEvent({...authorizationEventFields(t),outcome:`authorized`,sequence:r?.sequence??n.sequence,stepIndex:r?.stepIndex??n.stepIndex,turnId:r?.turnId??n.turnId})}))}function ownOpenRequestIds(e){return new Set(openInputs(e.projection).filter(t=>t.callId===void 0&&t.taskId===void 0&&!e.relayedRequestIds.has(t.request.requestId)).map(e=>e.request.requestId))}const CANCELLED_CALL_RESULT=`The turn was cancelled before this call finished.`;function cancel(e){let{projection:t}=e,n=t.activeTurnId,r=e.turn.suspended.filter(e=>n!==void 0&&e.event.turnId===n||e.tasks.some(t=>!answeredCallIds(e.messages).has(t.callId))||(e.approved?.length??0)>0),i=new Set(r.flatMap(e=>e.requests.map(e=>e.requestId))),a=[...openInputs(t).filter(t=>t.turnId===n||i.has(t.request.requestId)||e.relayedRequestIds.has(t.request.requestId)||t.request.kind===`session-limit`).map(inputWithdrawn),...openSignIns(t).filter(e=>e.turnId===n).map(e=>signInWithdrawn(e,`Cancelled.`))];if(n!==void 0){let{sequence:e}=turnCoordinates(t);a.push(createTurnCancelledEvent({sequence:e,turnId:n}))}return a.push(createSessionWaitingEvent(e.usage)),{commit:r.flatMap(cancelledTranscript),events:a,signIns:[],turn:{...e.turn,suspended:e.turn.suspended.filter(e=>!r.includes(e))}}}function cancelledTranscript(e){let t=answeredCallIds(e.messages),n=[...e.messages];for(let r of e.messages)if(r.role===`assistant`&&typeof r.content!=`string`)for(let e of r.content)e.type===`tool-call`&&e.providerExecuted!==!0&&(t.has(e.toolCallId)||(n=withResult(n,{output:{type:`text`,value:CANCELLED_CALL_RESULT},toolCallId:e.toolCallId,toolName:e.toolName,type:`tool-result`})));return n}function clear(e,t){let{projection:n}=e,{sequence:r,turnId:i}=turnCoordinates(n);return{clearsHistory:!0,events:[...openInputs(n).filter(t=>!e.relayedRequestIds.has(t.request.requestId)).map(inputWithdrawn),...openSignIns(n).map(e=>signInWithdrawn(e,`The context was cleared.`)),createContextClearedEvent({sequence:r,sessionId:t.sessionId,turnId:i}),createSessionWaitingEvent(e.usage)],turn:{grants:e.turn.grants,suspended:[]}}}export{CANCELLED_CALL_RESULT,approvedCalls,cancel,clear,completeSignIn,fail,finishRun,finishTurn,hold,idle,ownOpenRequestIds,receive,receiveRelayedAnswer,relay,routeAnswer,runSignIn,sessionCompleted,sessionFailed,settle,settleTask,startStep,startTask,stepCallIds,suspend,suspendStep,withResult,withoutApproved};

package/dist/src/harness/session-machine/view.d.ts

@@ -0,0 +1,58 @@
+import type { SessionAuthContext } from "#channel/types.js";
+import type { TokenUsage } from "#shared/token-usage.js";
+import type { ModelMessage } from "ai";
+import type { AuthorizationChallenge } from "#harness/authorization.js";
+import { type TaskToolCall } from "#execution/tasks/calls.js";
+import type { SessionStateMap, StepInput } from "#harness/types.js";
+import type { RuntimeWorkflowTaskRequest } from "#shared/action-types.js";
+import { type SessionProjection } from "#protocol/session-projection.js";
+import { type StepCoordinates, type SuspendedStep, type TurnState } from "./state.js";
+export type { StepCoordinates, SuspendedStep, TurnState } from "./state.js";
+export declare const SESSION_PROJECTION_STATE_KEY = "eve.harness.sessionProjection";
+/** What a transition sees. */
+export interface SessionView {
+    readonly turn: TurnState;
+    readonly projection: SessionProjection;
+    /** Requests this session relays for a child session or a workflow run, by `requestId`. */
+    readonly relayedRequestIds: ReadonlySet<string>;
+    /** The sign-in attempts the session waits on, with what completing them needs. */
+    readonly signIns: readonly AuthorizationChallenge[];
+    /** The session's token usage so far, which its waiting and terminal events report. */
+    readonly usage: TokenUsage;
+}
+/** Reads the authoritative lifecycle facts saved alongside execution state. */
+export declare function storedProjection(state: SessionStateMap | undefined): SessionProjection;
+/** Coordinates the next lifecycle event carries, and whether a turn is open. */
+export interface TurnPosition {
+    readonly sessionStarted: boolean;
+    readonly sequence: number;
+    readonly stepIndex: number;
+    /** The open turn's id, or `""` between turns. */
+    readonly turnId: string;
+    /** The open turn streamed assistant output, so steering can no longer restart it. */
+    readonly assistantOutputStarted?: boolean;
+}
+export declare function turnPosition(projection: SessionProjection): TurnPosition;
+/** The open turn's id, or the id the next turn takes. */
+export declare function activeTurnId(position: Pick<TurnPosition, "sequence" | "turnId">): string;
+export declare function isBetweenTurns(projection: SessionProjection): boolean;
+/** The index the open turn's next `step.started` takes. */
+export declare function nextStepIndex(projection: SessionProjection): number;
+/** Input the session holds until it can run. */
+export declare function queuedInput(state: SessionStateMap | undefined): StepInput | undefined;
+export declare function suspendedSteps(state: SessionStateMap | undefined): readonly SuspendedStep[];
+/** The ids of calls that already have a result in `messages`. */
+export declare function answeredCallIds(messages: readonly ModelMessage[]): ReadonlySet<string>;
+/** Workflow and agent calls of `step` the runtime still runs. */
+export declare function runningTasks(step: SuspendedStep): readonly RuntimeWorkflowTaskRequest[];
+/** What the turn waits on the runtime for: dispatched runs and the task tool calls. */
+export interface RuntimeWait {
+    readonly event: StepCoordinates;
+    readonly callIds: readonly string[];
+    readonly tasks: readonly RuntimeWorkflowTaskRequest[];
+    readonly taskToolCalls: readonly TaskToolCall[];
+    /** Who approved each task an approval started, by call id. */
+    readonly approvers: Readonly<Record<string, SessionAuthContext>>;
+}
+/** The calls suspended steps wait on the runtime for, or `undefined` when none do. */
+export declare function runtimeWait(state: SessionStateMap | undefined): RuntimeWait | undefined;

package/dist/src/harness/session-machine/view.js

@@ -0,0 +1 @@
+import{readTurnState}from"./state.js";import{initialSessionProjection,turnCoordinates}from"#protocol/session-projection.js";import{pendingTaskToolCalls}from"#execution/tasks/calls.js";const SESSION_PROJECTION_STATE_KEY=`eve.harness.sessionProjection`;function storedProjection(e){return e?.[`eve.harness.sessionProjection`]??initialSessionProjection()}function turnPosition(e){let{sequence:t,stepIndex:n}=turnCoordinates(e),r=e.activeTurnId===void 0?void 0:e.turns[e.activeTurnId],i={sessionStarted:e.started===!0,sequence:t,stepIndex:n,turnId:r?.turnId??``};return r?.outputStarted===!0&&(i.assistantOutputStarted=!0),i}function activeTurnId(e){return e.turnId===``?`turn_${e.sequence}`:e.turnId}function isBetweenTurns(e){return e.activeTurnId===void 0}function nextStepIndex(e){let t=e.activeTurnId===void 0?void 0:e.turns[e.activeTurnId];return t?.stepIndex===void 0?0:t.stepIndex+1}function queuedInput(e){return readTurnState(e).queued}function suspendedSteps(e){return readTurnState(e).suspended}function answeredCallIds(e){let t=new Set;for(let n of e)if((n.role===`tool`||n.role===`assistant`)&&typeof n.content!=`string`)for(let e of n.content)e.type===`tool-result`&&t.add(e.toolCallId);return t}function runningTasks(e){let t=answeredCallIds(e.messages);return e.tasks.filter(e=>!t.has(e.callId))}function runtimeWait(e){let t=suspendedSteps(e).flatMap(e=>{let t=runningTasks(e),n=pendingTaskToolCalls(e.messages);return t.length===0&&n.length===0?[]:[{step:e,tasks:t,taskToolCalls:n}]}),n=t[0];if(n===void 0)return;let r=t.flatMap(e=>e.tasks),i=t.flatMap(e=>e.taskToolCalls);return{approvers:Object.assign({},...t.map(e=>e.step.approvers)),callIds:[...r.map(e=>e.callId),...i.map(e=>e.callId)],event:n.step.event,taskToolCalls:i,tasks:r}}export{SESSION_PROJECTION_STATE_KEY,activeTurnId,answeredCallIds,isBetweenTurns,nextStepIndex,queuedInput,runningTasks,runtimeWait,storedProjection,suspendedSteps,turnPosition};

package/dist/src/harness/step/after-model.d.ts

@@ -0,0 +1,7 @@
+import type { ModelMessage } from "ai";
+import type { StepResult } from "#harness/types.js";
+import type { ModelResponse } from "#harness/model-call/run.js";
+import type { Step } from "#harness/step/context.js";
+export declare function handleStepResult(step: Step, input: ModelResponse): Promise<StepResult>;
+/** The SDK's approval parts: eve answers approvals itself, so history never holds them. */
+export declare function withoutApprovalParts(messages: readonly ModelMessage[]): ModelMessage[];

package/dist/src/harness/step/after-model.js

@@ -0,0 +1 @@
+import{createLogger}from"#internal/logging.js";import{resolveAssistantStepText,validateHarnessModelMessages}from"#harness/messages.js";import{renderFinalOutputWhileWorkingError}from"#execution/tasks/render.js";import{stageToolResultMedia}from"#harness/attachment-staging.js";import{collectDeferredCalls}from"#harness/coordination.js";import{fail,finishTurn,hold,suspendStep,withResult}from"#harness/session-machine/transitions.js";import{extractToolApprovalInputRequests,hasRunnableQueue,parkOnApprovals,stopForToolSignIn}from"#harness/hitl/index.js";import{createToolResultMessagePartFromToolError,isToolResultError}from"#harness/action-result-helpers.js";import{setRequestEnvelopeTokens}from"#harness/request-envelope.js";import{isTaskTool,workingTaskIds}from"#execution/tasks/model-step.js";import{getInvalidToolCallInputError,isInvalidToolCall}from"#harness/tool-call-input-errors.js";import{resolveInlineAuthorizationInterrupt}from"#harness/inline-tool-authorization.js";import{FINAL_OUTPUT_BESIDE_PENDING_CALLS,FINAL_OUTPUT_TOOL_NAME}from"#harness/final-output.js";import{getAdvertisedTools}from"#harness/advertised-tools.js";import{appendMissingToolResultMessages,extractToolResultCallIds}from"#harness/model-call/response.js";import{clearTurnClientContextState}from"#harness/turn-client-context.js";import{normalizeProviderToolHistory}from"#harness/provider-tool-history.js";const log=createLogger(`harness.tool-loop`);function getInvalidToolCallInputErrors(e){let t=[];for(let n of e.toolCalls){if(n.toolName===FINAL_OUTPUT_TOOL_NAME)continue;let e=getInvalidToolCallInputError({toolCall:n});e!==void 0&&t.push(e)}return t}async function handleStepResult(e,t){let{promptMessages:n,result:r}=t,i=resolveAssistantStepText(r.response.messages,r.text),a=getInvalidToolCallInputErrors({toolCalls:r.toolCalls}),o=new Set([...r.invalidInputToolCallIds??[],...r.toolCalls.filter(isInvalidToolCall).map(e=>e.toolCallId),...a.map(e=>e.toolCallId)]),s=appendMissingToolResultMessages({append:a.map(e=>createToolResultMessagePartFromToolError(e)),responseMessages:r.response.messages}),c=new Set;for(let e of[...r.content??[],...r.toolResults??[]])(e.type===`tool-result`||e.type===`tool-error`)&&e.providerExecuted===!0&&c.add(e.toolCallId);let l=normalizeProviderToolHistory({messages:s,providerExecutedOutcomeIds:c}),u=await stageToolResultMedia(withoutApprovalParts(l.messages));e.session=setRequestEnvelopeTokens({...e.session,compaction:createNextCompactionConfig(e.session.compaction,t.durableModelPromptMessageCount,r)},r.usage?.inputTokens!==void 0&&t.durableModelPromptMessageCount!==void 0?t.requestEnvelopeTokens:void 0);let d=extractToolApprovalInputRequests({content:r.content??[],excludedCallIds:o}),f=getAdvertisedTools({session:e.session,tools:t.coordinationTools}),p=new Set([...d.map(e=>e.action.callId),...extractToolResultCallIds(u)]),m=[],h=(r.toolCalls??[]).filter(e=>!o.has(e.toolCallId)).filter(e=>!p.has(e.toolCallId)).filter(e=>isDeferredHarnessTool(t.coordinationTools.get(e.toolName))).filter(t=>isDeferredHarnessTool(f.get(t.toolName))?!0:(log.warn(`deferred tool call blocked because tool is not advertised`,{callId:t.toolCallId,sessionId:e.session.sessionId,toolName:t.toolName}),m.push(t),!1));if(h.length>0||d.length>0){let{sequence:t,stepIndex:i,turnId:a}=e.position(),o=collectDeferredCalls({session:e.session,toolCalls:h,tools:f,turnId:a});e.session={...o.session,history:validateHarnessModelMessages(n)};let s={event:{sequence:t,stepIndex:i,turnId:a},messages:answerCallsThatWontRun(u,r,m),tasks:o.workflowRequests};return d.length>0?parkOnApprovals(e,{...s,requests:d,waitsOnRuntime:h.length>0}):(await e.apply(suspendStep(e.view(),s)),{next:null,session:e.session})}let g=resolveInlineAuthorizationInterrupt({messages:[...n,...u],toolResults:r.toolResults});if(g)return stopForToolSignIn(e,g);e.session={...e.session,history:validateHarnessModelMessages([...n,...u])};let _=e.session.outputSchema!==void 0&&extractFinalOutput(r)!==void 0,v=workingTaskIds(e.session),y=_&&v.length>0,b=u;y&&(b=rejectFinalOutput(u,r,v),e.session={...e.session,history:validateHarnessModelMessages([...n,...b])});let x=await stepEndsTurn(r,u,t.endsTurnTools);return(!_||y)&&(b.at(-1)?.role===`tool`&&!x||l.outcomeEndsResponse||hasRunnableQueue(e.view()))?{next:e.runStep,session:e.session}:v.length>0?(await e.apply(hold(e.view(),{on:`tasks`})),{held:{kind:`tasks`,taskIds:v},next:null,session:e.session}):settleTurn(e,{history:n,result:r,stepOutput:x?null:i})}function answerCallsThatWontRun(e,t,n){let r=extractToolResultCallIds(e);return[...(t.toolCalls??[]).filter(e=>e.toolName===FINAL_OUTPUT_TOOL_NAME).map(e=>({output:{type:`error-text`,value:FINAL_OUTPUT_BESIDE_PENDING_CALLS},toolCallId:e.toolCallId,toolName:e.toolName,type:`tool-result`})),...n.map(e=>({output:{type:`error-text`,value:`The tool "${e.toolName}" isn't available in this step, so the call didn't run.`},toolCallId:e.toolCallId,toolName:e.toolName,type:`tool-result`}))].filter(e=>!r.has(e.toolCallId)).reduce((e,t)=>withResult(e,t),[...e])}function withoutApprovalParts(e){return e.flatMap(e=>{if(e.role!==`assistant`&&e.role!==`tool`||!Array.isArray(e.content))return[e];let t=e.content.filter(e=>e.type!==`tool-approval-request`&&e.type!==`tool-approval-response`);return t.length===0?[]:[{...e,content:t}]})}async function stepEndsTurn(e,t,n){let r=e.toolCalls??[];if(r.length===0)return!1;let i=new Map;for(let e of t)if(e.role===`tool`)for(let t of e.content)t.type===`tool-result`&&i.set(t.toolCallId,t.output);if(!r.every(e=>{let t=i.get(e.toolCallId);return n.has(e.toolName)&&t!==void 0&&!isToolResultError(t)}))return!1;let a=new Map((e.toolResults??[]).map(e=>[e.toolCallId,e.output]));for(let e of r){let t=n.get(e.toolName);if(typeof t==`function`&&!await callEndsTurn(t,a.get(e.toolCallId),e))return!1}return!0}async function callEndsTurn(e,t,n){try{return await e(t)===!0}catch(e){return log.warn(`endsTurn threw; continuing the turn`,{callId:n.toolCallId,error:e,toolName:n.toolName}),!1}}function isDeferredHarnessTool(e){return e?.workflowId!==void 0||isTaskTool(e)}function rejectFinalOutput(e,t,n){let r=(t.toolCalls??[]).find(e=>e.toolName===FINAL_OUTPUT_TOOL_NAME);if(r===void 0)return[...e];let i={output:{type:`error-text`,value:renderFinalOutputWhileWorkingError(n)},toolCallId:r.toolCallId,toolName:FINAL_OUTPUT_TOOL_NAME,type:`tool-result`};return[...e,{content:[i],role:`tool`}]}const OUTPUT_SCHEMA_NOT_FULFILLED={code:`OUTPUT_SCHEMA_NOT_FULFILLED`,message:`The agent could not produce a result matching the requested schema.`};function extractFinalOutput(e){return(e.toolCalls??[]).find(e=>e.toolName===FINAL_OUTPUT_TOOL_NAME&&!isInvalidToolCall(e))?.input}async function settleTurn(e,t){let{history:n,result:r,stepOutput:i}=t,a=e.session.outputSchema;if(e.session=clearTurnClientContextState(e.session),a===void 0)return await e.apply(finishTurn(e.view()),e.session.history),{next:null,session:e.session,settledTurn:{output:i??``}};let o=extractFinalOutput(r);return o===void 0?(e.session={...e.session,outputSchema:void 0},await e.apply(fail(e.view(),OUTPUT_SCHEMA_NOT_FULFILLED)),{next:null,session:e.session,settledTurn:{isError:!0,output:OUTPUT_SCHEMA_NOT_FULFILLED.message}}):(e.session={...e.session,history:[...n,{content:JSON.stringify(o),role:`assistant`}],outputSchema:void 0},await e.apply(finishTurn(e.view(),{result:o}),e.session.history),{next:null,session:e.session,settledTurn:{output:o}})}function createNextCompactionConfig(e,t,n){let r={recentWindowSize:e.recentWindowSize,threshold:e.threshold,thresholdPercent:e.thresholdPercent};return n.usage?.inputTokens!==void 0&&t!==void 0&&(r.lastKnownInputTokens=n.usage.inputTokens,r.lastKnownPromptMessageCount=t),r}export{handleStepResult,withoutApprovalParts};

package/dist/src/harness/step/context.d.ts

@@ -0,0 +1,59 @@
+import type { ModelMessage } from "ai";
+import type { AlsContext } from "#context/container.js";
+import { type HarnessModelMessage } from "#harness/messages.js";
+import { type Publish, type Transition } from "#harness/session-machine/commit.js";
+import type { StepProjection } from "#harness/session-machine/current.js";
+import { type SessionView, type TurnPosition } from "#harness/session-machine/view.js";
+import type { HarnessEmitFn, HarnessSession, StepFn, StepInput, StepResult, ToolLoopHarnessConfig } from "#harness/types.js";
+import type { InstrumentationStepScope } from "#instrumentation/runtime.js";
+import type { createHistoryViewPreparer } from "#shared/history-view.js";
+type HistoryViewPreparer = ReturnType<typeof createHistoryViewPreparer>;
+/**
+ * One harness step: the session it changes, and the machine it changes the session through.
+ * Every lifecycle change goes through `apply`, which publishes the transition's events and saves
+ * what it changed; `position` reads where those events left the session.
+ */
+export interface Step {
+    session: HarnessSession;
+    frameworkToolNames: ReadonlySet<string>;
+    readonly config: ToolLoopHarnessConfig;
+    /** The step's context; direct harness tests may run without one. */
+    readonly ctx: AlsContext | undefined;
+    readonly runStep: StepFn;
+    readonly publish: Publish;
+    /** The caller's event handler. Without one, a failure throws instead of being reported. */
+    readonly emit: HarnessEmitFn | undefined;
+    readonly instrumentation: InstrumentationStepScope<HarnessSession> | undefined;
+    /** A child's caller or a schedule hears only the turn's real end. */
+    readonly hasDelegatedCaller: boolean;
+    view(): SessionView;
+    position(): TurnPosition;
+    apply(transition: Transition, messages?: readonly ModelMessage[]): Promise<void>;
+    /** History as the model and hooks see it, under `state`, the session's by default. */
+    projectHistory(messages: readonly ModelMessage[], state?: HarnessSession["state"]): readonly ModelMessage[];
+}
+export declare function createStep(input: {
+    readonly config: ToolLoopHarnessConfig;
+    readonly ctx: AlsContext | undefined;
+    readonly emit: HarnessEmitFn | undefined;
+    readonly instrumentation: InstrumentationStepScope<HarnessSession> | undefined;
+    readonly live: StepProjection;
+    readonly prepareHistory: HistoryViewPreparer;
+    readonly publish: Publish;
+    readonly runStep: StepFn;
+    readonly session: HarnessSession;
+}): Step;
+/**
+ * Opens the turn, or joins the open one, with the preamble its hooks prepare: memory recall and
+ * dynamic instructions join history ahead of the turn's input. Returns the step's result when the
+ * preamble failed the session.
+ */
+export declare function openTurn(step: Step, opened: {
+    readonly input: readonly HarnessModelMessage[];
+    readonly message?: StepInput["message"];
+}): Promise<StepResult | undefined>;
+/** A lifecycle event failed to publish: only a dynamic model selection failure is reported. */
+export declare function failBoundaryEvent(step: Step, error: unknown): Promise<StepResult>;
+/** No model can serve the turn: the session fails. */
+export declare function failModelSelection(step: Step, error: unknown): Promise<StepResult>;
+export {};

package/dist/src/harness/step/context.js

@@ -0,0 +1 @@
+import{createErrorId,createLogger}from"#internal/logging.js";import{ParentSessionKey,SessionCallbackKey}from"#context/keys.js";import{toErrorMessage}from"#shared/errors.js";import{validateHarnessModelMessages}from"#harness/messages.js";import{drainMemoryCommit,prepareMemoryPreamble}from"#context/memory-lifecycle.js";import{activeTurnId,turnPosition}from"#harness/session-machine/view.js";import{applyTransition,sessionView}from"#harness/session-machine/commit.js";import{fail,receive}from"#harness/session-machine/transitions.js";import{isDynamicModelSelectionError}from"#context/dynamic-model-lifecycle.js";import{isTurnCancellation,throwIfTurnAborted}from"#harness/turn-cancellation.js";import{drainDynamicInstructionUserMessages,prepareDynamicInstructionPreamble}from"#context/dynamic-instruction-lifecycle.js";const log=createLogger(`harness.step`);function createStep(e){let{ctx:t,live:n}=e,r={session:e.session,frameworkToolNames:new Set,config:e.config,ctx:t,runStep:e.runStep,publish:e.publish,emit:e.emit,instrumentation:e.instrumentation,hasDelegatedCaller:t?.get(ParentSessionKey)!==void 0||t?.get(SessionCallbackKey)!==void 0,view:()=>sessionView(n.read(),r.session.state),position:()=>turnPosition(n.read()),async apply(t,n){r.session=await applyTransition(r.session,t,e.publish,n)},projectHistory:(t,n=r.session.state)=>e.prepareHistory(t,n).messages};return r}async function openTurn(e,t){let{config:n,ctx:r}=e;r!==void 0&&(prepareDynamicInstructionPreamble(r,e.projectHistory(e.session.history)),prepareMemoryPreamble(r,{history:e.session.history,input:[...t.input],projector:n.historyProjector,state:e.session.state}));let i;try{let r=e.position(),i=await e.instrumentation?.preparePreamble({sequence:r.sequence,sessionStarted:r.sessionStarted,traceContext:e.instrumentation?.traceContext,turnId:activeTurnId(r)});await e.apply(receive(e.view(),{message:t.message,runtime:n.runtimeIdentity,trace:i}),e.projectHistory([...e.session.history,...t.input]))}catch(e){i={error:e}}let a=r===void 0?[]:drainDynamicInstructionUserMessages(r),o=r===void 0?void 0:drainMemoryCommit(r);if(e.session={...e.session,history:validateHarnessModelMessages([...e.session.history,...o?.recalledMessages??[],...a]),state:o?.state??e.session.state},i!==void 0)return failBoundaryEvent(e,i.error);e.instrumentation?.setTurnId(e.position().turnId)}async function failBoundaryEvent(e,t){if(throwIfTurnAborted(e.config.abortSignal),isTurnCancellation(t))throw t;if(isDynamicModelSelectionError(t))return failModelSelection(e,t);throw t}async function failModelSelection(e,t){if(throwIfTurnAborted(e.config.abortSignal),e.instrumentation?.recordError(t),e.emit===void 0)throw t;let n=createErrorId(),r=toErrorMessage(t),{session:i}=e;return log.error(`model selection failed terminally`,{error:t,errorId:n,sessionId:i.sessionId,turnId:activeTurnId(e.position())}),await e.apply(fail(e.view(),{code:`MODEL_SELECTION_FAILED`,details:{errorId:n},message:r,terminal:{sessionId:i.sessionId}})),{next:e.hasDelegatedCaller?{done:!0,isError:!0,output:r}:{done:!0,output:``},session:e.session}}export{createStep,failBoundaryEvent,failModelSelection,openTurn};

package/dist/src/harness/step/intake.d.ts

@@ -0,0 +1,34 @@
+import { type HarnessModelMessage, type UserModelMessage } from "#harness/messages.js";
+import { getTurnClientContextState } from "#harness/turn-client-context.js";
+import type { StepInput } from "#harness/types.js";
+import type { Step } from "./context.js";
+/**
+ * Settles the calls the runtime ran for parked steps. Returns `undefined` while some are still
+ * running: input queued behind them waits until they have. Otherwise returns the step's input
+ * without the results it settled, and whether the step waited on any.
+ */
+export declare function settleRuntimeWork(step: Step, input: StepInput | undefined): Promise<{
+    readonly input: StepInput | undefined;
+    readonly waited: boolean;
+} | undefined>;
+/** The turn's input as the model reads it. */
+export interface TurnInput {
+    readonly turnId: string;
+    /** Context the client sent for this turn, which never joins history. */
+    readonly clientContext: readonly string[] | undefined;
+    readonly storedClientContext: ReturnType<typeof getTurnClientContextState>;
+    readonly ephemeral: readonly UserModelMessage[];
+    /** The context entries and the message, in history order. */
+    readonly messages: readonly UserModelMessage[];
+    /** The input carries a user's message, which follows tool results across a boundary. */
+    readonly hasUserMessage: boolean;
+}
+/**
+ * Prepares the turn's input: client and context entries, and the message with its attachments
+ * staged to the sandbox. A message a plain-text answer consumed never reaches the model.
+ */
+export declare function prepareTurnInput(step: Step, input: StepInput | undefined, options: {
+    readonly consumedMessage: boolean;
+}): Promise<TurnInput>;
+/** The turn's input as it follows tool results: a user message needs a boundary before it. */
+export declare function followingToolResults(turn: TurnInput): HarnessModelMessage[];

package/dist/src/harness/step/intake.js

@@ -0,0 +1 @@
+import{readClientContext}from"#internal/client-context.js";import{TOOL_RESULT_BOUNDARY,createFrameworkUserMessage,createUserMessage,frameworkMessageKindForStepInput,normalizeUserContent}from"#harness/messages.js";import{activeTurnId,runtimeWait}from"#harness/session-machine/view.js";import{stageAttachmentsToSandbox,stageToolResultMedia}from"#harness/attachment-staging.js";import{forgetFinishedRuns,runtimeResultCalls}from"#harness/coordination.js";import{finishRun,settle}from"#harness/session-machine/transitions.js";import{resolveRuntimeActionResultsForCallIds}from"#runtime/actions/results.js";import{getTurnClientContextState}from"#harness/turn-client-context.js";async function settleRuntimeWork(e,t){let n=runtimeWait(e.session.state);if(n===void 0)return{input:t,waited:!1};let r=resolveRuntimeActionResultsForCallIds({pendingCallIds:n.callIds,results:t?.runtimeActionResults??[]});if(r===void 0)return;let i=forgetFinishedRuns(e.session,r,n.event.turnId);e.session=i.session,await e.apply(finishRun(e.view(),{requestIds:i.requestIds}));let a=await runtimeResultCalls(r,e.config.tools),o=(await stageToolResultMedia([{role:`tool`,content:a.map(({part:e})=>e)}])).flatMap(e=>e.role===`tool`?e.content.filter(e=>e.type===`tool-result`):[]);if(await e.apply(settle(e.view(),{results:a.map((e,t)=>({...e,part:o[t]}))})),t===void 0)return{input:t,waited:!0};let{runtimeActionResults:s,...c}=t;return{input:c,waited:!0}}async function prepareTurnInput(e,t,n){let r=activeTurnId(e.position()),i=getTurnClientContextState(e.session.state,r),a=readClientContext(t),o=(a??i?.messages)?.map(e=>createFrameworkUserMessage(`context.instruction`,e))??[],s=(t?.context??[]).map(e=>createFrameworkUserMessage(`context.instruction`,e)),c=frameworkMessageKindForStepInput(t),l=normalizeUserContent(t?.message),u=l!==void 0&&!n.consumedMessage?await stageAttachmentsToSandbox(l):void 0;return u!==void 0&&s.push(c===void 0?createUserMessage(`user`,u):createFrameworkUserMessage(c,u)),{clientContext:a,ephemeral:o,hasUserMessage:u!==void 0&&c===void 0,messages:s,storedClientContext:i,turnId:r}}function followingToolResults(e){return[...e.hasUserMessage?[{content:TOOL_RESULT_BOUNDARY,role:`assistant`}]:[],...e.messages]}export{followingToolResults,prepareTurnInput,settleRuntimeWork};

package/dist/src/harness/step/prompt.d.ts

@@ -0,0 +1,37 @@
+import { type HarnessModelMessage } from "#harness/messages.js";
+import { getTurnClientContextState } from "#harness/turn-client-context.js";
+import type { Step } from "./context.js";
+import { type TurnInput } from "./intake.js";
+type ClientContext = NonNullable<ReturnType<typeof getTurnClientContextState>>;
+/**
+ * What the model reads this step: durable history, with the task results and notes the step
+ * delivers and the turn's input, and the client's context for the turn, which keeps one position
+ * across the turn's steps and never joins history.
+ */
+export interface Prompt {
+    /** Durable messages. Compaction may rewrite them. */
+    messages: HarnessModelMessage[];
+    clientContext: ClientContext | undefined;
+}
+export declare function buildPrompt(step: Step, turn: TurnInput): Promise<Prompt>;
+/**
+ * The prompt a step starts on while approved calls wait to run: history and the turn's input,
+ * without the task results and the client context's position a prompt settles, which wait for
+ * the prompt the model reads once the calls have run.
+ */
+export declare function previewPrompt(step: Step, turn: TurnInput): Prompt;
+/**
+ * The turn's input after `messages`, past a tool-result boundary when they end in tool results.
+ * The client's context takes its position here, and never joins the messages.
+ */
+export declare function placeTurnInput(step: Step, messages: readonly HarnessModelMessage[], turn: TurnInput): HarnessModelMessage[];
+/** `messages`, the prompt's by default, with the client's context at its position. */
+export declare function withClientContext(prompt: Prompt, messages?: readonly HarnessModelMessage[]): HarnessModelMessage[];
+/** The prompt as the model reads it: with the client's context, projected for its history view. */
+export declare function projectPrompt(step: Step, prompt: Prompt): HarnessModelMessage[];
+/**
+ * Compaction rewrote the durable messages: the client's context keeps its distance from the end,
+ * so it stays after the turn's input.
+ */
+export declare function compactPrompt(step: Step, prompt: Prompt, messages: HarnessModelMessage[]): void;
+export {};

package/dist/src/harness/step/prompt.js

@@ -0,0 +1 @@
+import{followingToolResults}from"./intake.js";import{createFrameworkUserMessage,followsToolResults,normalizeModelMessages,validateHarnessModelMessages}from"#harness/messages.js";import{appendTaskContext}from"#execution/tasks/model-step.js";import{hasUnansweredToolCall}from"#harness/model-call/response.js";import{getTurnClientContextState,setTurnClientContextState}from"#harness/turn-client-context.js";async function buildPrompt(e,t){let n=validateHarnessModelMessages([...e.session.history]);if(!hasUnansweredToolCall(n)){let t=await appendTaskContext({messages:n,projectHistory:e.projectHistory,session:e.session,tools:e.config.tools});e.session=t.session,n.push(...t.messages)}let r=placeTurnInput(e,n,t);return{clientContext:getTurnClientContextState(e.session.state,t.turnId),messages:r}}function previewPrompt(e,t){let n=validateHarnessModelMessages([...e.session.history]);return{clientContext:turnClientContext(n,t),messages:withTurnInput(n,t)}}function placeTurnInput(e,t,n){let r=turnClientContext(t,n);return r!==void 0&&(e.session=setTurnClientContextState(e.session,r)),withTurnInput(t,n)}function turnClientContext(e,t){return t.clientContext===void 0?t.storedClientContext:{insertionIndex:t.storedClientContext?.insertionIndex??e.length,messages:t.clientContext,turnId:t.turnId}}function withTurnInput(e,t){return[...e,...followsToolResults(e)?followingToolResults(t):t.messages]}function withClientContext(e,t=e.messages){let{clientContext:n}=e;if(n===void 0||n.messages.length===0)return[...t];let r=Math.min(Math.max(0,n.insertionIndex),t.length);return[...t.slice(0,r),...n.messages.map(e=>createFrameworkUserMessage(`context.instruction`,e)),...t.slice(r)]}function projectPrompt(e,t){return validateHarnessModelMessages(normalizeModelMessages(e.projectHistory(withClientContext(t))))}function compactPrompt(e,t,n){let{clientContext:r}=t;if(r!==void 0){let i=Math.max(0,t.messages.length-r.insertionIndex);t.clientContext={...r,insertionIndex:Math.max(0,n.length-i)},e.session=setTurnClientContextState(e.session,t.clientContext)}t.messages=n}export{buildPrompt,compactPrompt,placeTurnInput,previewPrompt,projectPrompt,withClientContext};

package/dist/src/harness/step-hooks.d.ts

@@ -1,5 +1,5 @@
-import type { GenerateTextOnStepStartCallback, PrepareStepFunction, ProviderMetadata, StepResult, ToolSet } from "ai";
-import type { HarnessEmissionState } from "#harness/emission.js";
+import type { GenerateTextOnStepStartCallback, ModelMessage, PrepareStepFunction, ProviderMetadata, StepResult, ToolSet } from "ai";
+import type { TurnPosition } from "#harness/session-machine/view.js";
 import { type AnthropicCacheMarker, type PromptCachePath } from "#harness/prompt-cache.js";
 import { type HarnessEmitFn, type HarnessSession, type ToolLoopHarnessConfig } from "#harness/types.js";
 /**
@@ -17,16 +17,11 @@ export type HarnessStepResult = Pick<StepResult<ToolSet>, "content" | "finishRea
 interface StepHooksInput {
     readonly auth?: import("#channel/types.js").SessionAuthContext | null;
     readonly cachePath: PromptCachePath;
-    readonly emit?: HarnessEmitFn;
-    readonly emissionState: HarnessEmissionState;
     /**
-     * When `false`, `onStepStart` skips the `step.started` emission.
-     * Used by the harness recovery path to avoid emitting `step.started`
-     * twice when retrying the same step with a degraded toolset.
-     *
-     * Defaults to `true`.
+     * Starts the model step the SDK is about to run. Omitted when the step already started, as
+     * it has for a retry of the same step.
      */
-    readonly emitStepStarted?: boolean;
+    readonly startStep?: (messages: readonly ModelMessage[]) => Promise<void>;
     readonly marker: AnthropicCacheMarker | undefined;
     readonly session: HarnessSession;
 }
@@ -37,7 +32,7 @@ interface StepHooks {
     /**
      * `ToolLoopAgent` `onStepStart` callback.
      *
-     * Emits the `step.started` event from the prepared step input.
+     * Starts the step from the prepared step input.
      */
     readonly onStepStart: GenerateTextOnStepStartCallback<ToolSet>;
     /**
@@ -61,7 +56,7 @@ interface StepHooks {
      * have been emitted before proceeding to post-step handling.
      *
      * Resolves once per hooks instance: a retried model call must rebuild
-     * hooks via a fresh `runOneModelCall` attempt. Re-running a call against
+     * hooks via a fresh `ModelCaller.call` attempt. Re-running a call against
      * hooks whose `stepResult` already resolved reads the previous attempt's
      * result, not the retry's.
      *
@@ -96,7 +91,7 @@ export declare function buildStepHooks(input: StepHooksInput): StepHooks;
  * `handledInlineToolResultCallIds` contains results emitted by
  * `emitStreamContent` or sent to authorization. Skip them here.
  */
-export declare function emitStepActions(emitFn: HarnessEmitFn, state: HarnessEmissionState, step: HarnessStepResult, options: {
+export declare function emitStepActions(emitFn: HarnessEmitFn, state: TurnPosition, step: HarnessStepResult, options: {
     readonly emittedActionCallIds?: ReadonlySet<string>;
     readonly excludedActionCallIds?: ReadonlySet<string>;
     readonly excludedActionToolNames: ReadonlySet<string>;

package/dist/src/harness/step-hooks.js

@@ -1 +1 @@
-import{contextStorage}from"#context/container.js";import{AuthKey}from"#context/keys.js";import{createActionResultEvent,createActionsRequestedEvent,createStepCompletedEvent}from"#protocol/message.js";import{emitStepStarted}from"#harness/emission.js";import{resolveConversationId}from"#shared/conversation-identity.js";import{isAuthorizationSignal,isPendingAuthorizationToolOutput}from"#harness/authorization.js";import{createRuntimeToolResultFromMessagePart,createRuntimeToolResultFromStepResult,createRuntimeToolResultFromToolError}from"#harness/action-result-helpers.js";import{emitNestedToolActions}from"#harness/nested-actions.js";import{extractToolApprovalInputRequests}from"#harness/input-extraction.js";import{isInvalidToolCall}from"#harness/tool-call-input-errors.js";import{collectActionPresentation,createPresentedRuntimeActionRequestFromToolCall}from"#harness/action-presentation.js";import{normalizeAssistantStepFinishReason}from"#harness/finish-reason.js";import{readToolInterrupt}from"#harness/tool-interrupts.js";import{applyConversationCacheControl,mergeGatewayAutoCaching}from"#harness/prompt-cache.js";import{resolveCallProviderOptions}from"#harness/provider-safety.js";import{requireSessionModelReference}from"#harness/types.js";function buildStepHooks(e){let t=e.session,n=e.emit,r;return{onStepEnd:async e=>{r(e)},onStepStart:async({messages:r})=>{n&&e.emitStepStarted!==!1&&await emitStepStarted(n,e.emissionState,requireSessionModelReference(t).id,r)},prepareStep:async({messages:n,model:r})=>{let i=n;e.cachePath.kind===`anthropic-direct`&&e.marker&&(i=applyConversationCacheControl([...n],e.marker));let a={messages:i},o=requireSessionModelReference(t),s=resolveCallProviderOptions({auth:e.auth??contextStorage.getStore()?.get(AuthKey)??null,conversationId:resolveConversationId(t.rootSessionId??t.sessionId),model:r,modelReference:o,providerOptions:o.providerOptions});return e.cachePath.kind===`gateway-auto`?a.providerOptions=mergeGatewayAutoCaching(s):s!==void 0&&(a.providerOptions=s),a},stepResult:new Promise(e=>{r=e})}}async function emitStepActions(e,t,n,r){let i=new Set(n.toolCalls.filter(isProviderExecutedToolCall).map(e=>e.toolCallId)),a=new Set([...r.excludedActionCallIds??[],...i,...extractToolApprovalInputRequests({content:n.content??[],excludedCallIds:r.excludedActionCallIds}).map(e=>e.action.callId),...n.toolCalls.filter(isInvalidToolCall).map(e=>e.toolCallId)]),isExcluded=(e,t)=>a.has(e)||r.excludedActionToolNames.has(t),o=n.toolCalls.filter(e=>!isExcluded(e.toolCallId,e.toolName)&&!r.emittedActionCallIds?.has(e.toolCallId)).map(e=>createPresentedRuntimeActionRequestFromToolCall({toolCall:e,tools:r.tools}));o.length>0&&await e(createActionsRequestedEvent({actions:o.map(({action:e})=>e),presentation:collectActionPresentation(o),sequence:t.sequence,stepIndex:t.stepIndex,turnId:t.turnId}));let s=r.handledInlineToolResultCallIds,c=new Map(n.toolResults.map(e=>[e.toolCallId,e.output]));for(let r of reconcileToolResults(n)){if(isExcluded(r.callId,r.toolName)||s?.has(r.callId))continue;let n=c.get(r.callId);shouldSkipAuthorizationActionResult(r.callId,n)||(await emitNestedToolActions(e,t,r.callId),await e(createActionResultEvent({result:r,sequence:t.sequence,stepIndex:t.stepIndex,turnId:t.turnId})))}await e(createStepCompletedEvent({finishReason:normalizeAssistantStepFinishReason(n.finishReason),providerMetadata:extractStepProviderMetadata(n.providerMetadata),sequence:t.sequence,stepIndex:t.stepIndex,turnId:t.turnId,usage:extractStepUsage({costUsd:extractGatewayCostUsd(n.providerMetadata),usage:n.usage})}))}function isProviderExecutedToolCall(e){return e.providerExecuted===!0}function reconcileToolResults(e){let t=new Map;for(let n of e.toolResults)n.providerExecuted!==!0&&t.set(n.toolCallId,createRuntimeToolResultFromStepResult(n));for(let n of e.content??[])n.type===`tool-error`&&n.providerExecuted!==!0&&(t.has(n.toolCallId)||t.set(n.toolCallId,createRuntimeToolResultFromToolError(n)));for(let n of extractToolResultParts(e.response.messages))n.providerExecuted!==!0&&(t.has(n.toolCallId)||t.set(n.toolCallId,createRuntimeToolResultFromMessagePart(n)));return[...t.values()]}function shouldSkipAuthorizationActionResult(e,t){if(t!==void 0&&isPendingAuthorizationToolOutput(t))return!0;let n=contextStorage.getStore();if(n===void 0)return!1;let r=readToolInterrupt(n,e);return r!==void 0&&isAuthorizationSignal(r)}function extractToolResultParts(e){let t=[];for(let n of e)if(n.role===`tool`&&Array.isArray(n.content))for(let e of n.content)e.type===`tool-result`&&t.push(e);return t}function extractStepUsage(e){let t={};e.costUsd!==void 0&&(t.costUsd=e.costUsd);let n=e.usage;return n===void 0?Object.keys(t).length>0?t:void 0:(n.inputTokens!==void 0&&(t.inputTokens=n.inputTokens),n.outputTokens!==void 0&&(t.outputTokens=n.outputTokens),n.inputTokenDetails?.cacheReadTokens!==void 0&&(t.cacheReadTokens=n.inputTokenDetails.cacheReadTokens),n.inputTokenDetails?.cacheWriteTokens!==void 0&&(t.cacheWriteTokens=n.inputTokenDetails.cacheWriteTokens),Object.keys(t).length>0?t:void 0)}function extractStepProviderMetadata(e){let t=readGatewayGenerationId(e);return t===void 0?void 0:{gateway:{generationId:t}}}function extractGatewayCostUsd(e){let t=readGatewayMetadata(e)?.cost;if(typeof t==`number`&&Number.isFinite(t))return t;if(typeof t==`string`){let e=Number(t);return Number.isFinite(e)?e:void 0}}function readGatewayGenerationId(e){let t=readGatewayMetadata(e)?.generationId;return typeof t==`string`&&t.length>0?t:void 0}function readGatewayMetadata(e){let t=e?.gateway;return t&&typeof t==`object`&&!Array.isArray(t)?t:void 0}export{buildStepHooks,emitStepActions,readGatewayGenerationId};
+import{contextStorage}from"#context/container.js";import{AuthKey}from"#context/keys.js";import{createActionResultEvent,createActionsRequestedEvent,createStepCompletedEvent}from"#protocol/message.js";import{resolveConversationId}from"#shared/conversation-identity.js";import{isAuthorizationSignal,isPendingAuthorizationToolOutput}from"#harness/authorization.js";import{createRuntimeToolResultFromMessagePart,createRuntimeToolResultFromStepResult,createRuntimeToolResultFromToolError}from"#harness/action-result-helpers.js";import{emitNestedToolActions}from"#harness/nested-actions.js";import{requireSessionModelReference}from"#harness/types.js";import{resolveCallProviderOptions}from"#harness/provider-safety.js";import{isInvalidToolCall}from"#harness/tool-call-input-errors.js";import{collectActionPresentation,createPresentedRuntimeActionRequestFromToolCall}from"#harness/action-presentation.js";import{normalizeAssistantStepFinishReason}from"#harness/finish-reason.js";import{extractToolApprovalInputRequests}from"#harness/input-extraction.js";import{readToolInterrupt}from"#harness/tool-interrupts.js";import{applyConversationCacheControl,mergeGatewayAutoCaching}from"#harness/prompt-cache.js";function buildStepHooks(e){let t=e.session,n;return{onStepEnd:async e=>{n(e)},onStepStart:async({messages:t})=>{await e.startStep?.(t)},prepareStep:async({messages:n,model:r})=>{let i=n;e.cachePath.kind===`anthropic-direct`&&e.marker&&(i=applyConversationCacheControl([...n],e.marker));let a={messages:i},o=requireSessionModelReference(t),s=resolveCallProviderOptions({auth:e.auth??contextStorage.getStore()?.get(AuthKey)??null,conversationId:resolveConversationId(t.rootSessionId??t.sessionId),model:r,modelReference:o,providerOptions:o.providerOptions});return e.cachePath.kind===`gateway-auto`?a.providerOptions=mergeGatewayAutoCaching(s):s!==void 0&&(a.providerOptions=s),a},stepResult:new Promise(e=>{n=e})}}async function emitStepActions(e,t,n,r){let i=new Set(n.toolCalls.filter(isProviderExecutedToolCall).map(e=>e.toolCallId)),a=new Set([...r.excludedActionCallIds??[],...i,...extractToolApprovalInputRequests({content:n.content??[],excludedCallIds:r.excludedActionCallIds}).map(e=>e.action.callId),...n.toolCalls.filter(isInvalidToolCall).map(e=>e.toolCallId)]),isExcluded=(e,t)=>a.has(e)||r.excludedActionToolNames.has(t),o=n.toolCalls.filter(e=>!isExcluded(e.toolCallId,e.toolName)&&!r.emittedActionCallIds?.has(e.toolCallId)).map(e=>createPresentedRuntimeActionRequestFromToolCall({toolCall:e,tools:r.tools}));o.length>0&&await e(createActionsRequestedEvent({actions:o.map(({action:e})=>e),presentation:collectActionPresentation(o),sequence:t.sequence,stepIndex:t.stepIndex,turnId:t.turnId}));let s=r.handledInlineToolResultCallIds,c=new Map(n.toolResults.map(e=>[e.toolCallId,e.output]));for(let r of reconcileToolResults(n)){if(isExcluded(r.callId,r.toolName)||s?.has(r.callId))continue;let n=c.get(r.callId);shouldSkipAuthorizationActionResult(r.callId,n)||(await emitNestedToolActions(e,t,r.callId),await e(createActionResultEvent({result:r,sequence:t.sequence,stepIndex:t.stepIndex,turnId:t.turnId})))}await e(createStepCompletedEvent({finishReason:normalizeAssistantStepFinishReason(n.finishReason),providerMetadata:extractStepProviderMetadata(n.providerMetadata),sequence:t.sequence,stepIndex:t.stepIndex,turnId:t.turnId,usage:extractStepUsage({costUsd:extractGatewayCostUsd(n.providerMetadata),usage:n.usage})}))}function isProviderExecutedToolCall(e){return e.providerExecuted===!0}function reconcileToolResults(e){let t=new Map;for(let n of e.toolResults)n.providerExecuted!==!0&&t.set(n.toolCallId,createRuntimeToolResultFromStepResult(n));for(let n of e.content??[])n.type===`tool-error`&&n.providerExecuted!==!0&&(t.has(n.toolCallId)||t.set(n.toolCallId,createRuntimeToolResultFromToolError(n)));for(let n of extractToolResultParts(e.response.messages))n.providerExecuted!==!0&&(t.has(n.toolCallId)||t.set(n.toolCallId,createRuntimeToolResultFromMessagePart(n)));return[...t.values()]}function shouldSkipAuthorizationActionResult(e,t){if(t!==void 0&&isPendingAuthorizationToolOutput(t))return!0;let n=contextStorage.getStore();if(n===void 0)return!1;let r=readToolInterrupt(n,e);return r!==void 0&&isAuthorizationSignal(r)}function extractToolResultParts(e){let t=[];for(let n of e)if(n.role===`tool`&&Array.isArray(n.content))for(let e of n.content)e.type===`tool-result`&&t.push(e);return t}function extractStepUsage(e){let t={};e.costUsd!==void 0&&(t.costUsd=e.costUsd);let n=e.usage;return n===void 0?Object.keys(t).length>0?t:void 0:(n.inputTokens!==void 0&&(t.inputTokens=n.inputTokens),n.outputTokens!==void 0&&(t.outputTokens=n.outputTokens),n.inputTokenDetails?.cacheReadTokens!==void 0&&(t.cacheReadTokens=n.inputTokenDetails.cacheReadTokens),n.inputTokenDetails?.cacheWriteTokens!==void 0&&(t.cacheWriteTokens=n.inputTokenDetails.cacheWriteTokens),Object.keys(t).length>0?t:void 0)}function extractStepProviderMetadata(e){let t=readGatewayGenerationId(e);return t===void 0?void 0:{gateway:{generationId:t}}}function extractGatewayCostUsd(e){let t=readGatewayMetadata(e)?.cost;if(typeof t==`number`&&Number.isFinite(t))return t;if(typeof t==`string`){let e=Number(t);return Number.isFinite(e)?e:void 0}}function readGatewayGenerationId(e){let t=readGatewayMetadata(e)?.generationId;return typeof t==`string`&&t.length>0?t:void 0}function readGatewayMetadata(e){let t=e?.gateway;return t&&typeof t==`object`&&!Array.isArray(t)?t:void 0}export{buildStepHooks,emitStepActions,readGatewayGenerationId};

package/dist/src/harness/tool-call-io.d.ts

@@ -0,0 +1,25 @@
+import type { HarnessToolDefinition } from "#harness/execute-tool.js";
+import { type ToolModelOutputValue } from "#harness/tool-model-output.js";
+import type { JsonObject } from "#shared/json.js";
+/** The result of checking one tool call's input the way a model-issued call is checked. */
+export type ToolCallInputCheck = {
+    readonly kind: "valid";
+    readonly value: JsonObject;
+} | {
+    readonly kind: "invalid";
+    readonly message: string;
+} | {
+    readonly kind: "threw";
+    readonly error: unknown;
+};
+/**
+ * Checks a tool call's input the way a conversation does: no input (or an
+ * empty string) is `{}`, anything else that is not a JSON object is
+ * rejected, and the rest must satisfy the schema the model was given.
+ */
+export declare function checkToolCallInput(definition: Pick<HarnessToolDefinition, "inputSchema" | "name">, input: unknown, callId: string): Promise<ToolCallInputCheck>;
+/**
+ * What the model sees for a tool's output: pending sign-in text, the
+ * author's `toModelOutput`, or the output as text or JSON.
+ */
+export declare function toolCallModelOutput(definition: Pick<HarnessToolDefinition, "name" | "toModelOutput">, output: unknown, toolCallId: string | undefined): Promise<ToolModelOutputValue>;

package/dist/src/harness/tool-call-io.js

@@ -0,0 +1 @@
+import{asSchema}from"ai";import{toErrorMessage}from"#shared/errors.js";import{toModelSchema}from"#tools/schema.js";import{resolveToolCallInputObject}from"#harness/coordination.js";import{authorizationPendingModelText,isAuthorizationPendingModelOutput}from"#harness/authorization.js";import{normalizeToolModelOutput}from"#harness/tool-model-output.js";async function checkToolCallInput(e,t,n){let r;try{r=resolveToolCallInputObject(t,{callId:n,toolName:e.name})}catch(t){return{kind:`invalid`,message:`Invalid input for tool "${e.name}": ${toErrorMessage(t)}`}}let i;try{let t=asSchema(toModelSchema(e.inputSchema,`input`));if(t.validate===void 0)return{kind:`valid`,value:r};i=await t.validate(r)}catch(e){return{error:e,kind:`threw`}}return i.success?{kind:`valid`,value:i.value}:{kind:`invalid`,message:`Invalid input for tool "${e.name}": ${toErrorMessage(i.error)}`}}async function toolCallModelOutput(e,t,n){return isAuthorizationPendingModelOutput(t)?{type:`text`,value:authorizationPendingModelText(t.connections)}:e.toModelOutput===void 0?typeof t==`string`?{type:`text`,value:t}:normalizeToolModelOutput({output:{type:`json`,value:t??null},toolCallId:n,toolName:e.name}):normalizeToolModelOutput({output:await e.toModelOutput(t),toolCallId:n,toolName:e.name})}export{checkToolCallInput,toolCallModelOutput};

package/dist/src/harness/tool-loop.d.ts

@@ -1,24 +1,9 @@
-import { type ModelMessage } from "ai";
-import { type HarnessStepResult } from "#harness/step-hooks.js";
-import { type StepFn, type ToolLoopHarnessConfig } from "#harness/types.js";
-export declare function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn;
-type ToolResponsePart = Extract<ModelMessage, {
-    role: "tool";
-}>["content"][number];
-type ToolResultPart = Extract<ToolResponsePart, {
-    type: "tool-result";
-}>;
-type StepResponseMessage = HarnessStepResult["response"]["messages"][number];
+import type { StepFn, ToolLoopHarnessConfig } from "#harness/types.js";
 /**
- * Appends synthesized tool results for calls that have no result anywhere in
- * the step's response messages. Exported for its dedupe contract: a call
- * already answered — including provider-executed results the SDK keeps
- * inline in the assistant message — must never receive a second
- * `tool-result`, or the next Anthropic call rejects the history with
- * "each tool_use must have a single result".
+ * Creates the harness step: one step of a session, backed by the AI SDK's `ToolLoopAgent`.
+ *
+ * A step settles what earlier steps parked and takes its delivery's answers, opens or joins the
+ * turn, runs the work those answers approved, then makes one model step and acts on its response.
+ * Every lifecycle change goes through the session machine (`Step.apply`).
  */
-export declare function appendMissingToolResultMessages(input: {
-    readonly append: readonly ToolResultPart[];
-    readonly responseMessages: readonly StepResponseMessage[];
-}): StepResponseMessage[];
-export {};
+export declare function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn;