@truefoundry/trueforge-core 0.0.0 → 0.1.0-rc.0

package/dist/agent-session/TurnHandle.mjs

@@ -0,0 +1,469 @@
+// src/agent-session/TurnHandle.ts
+import { AgentHarnessError } from "../core/errors.mjs";
+import { EventType as HarnessEventType, newEventId } from "../core/events/schema.mjs";
+import {
+  InternalEventType
+} from "../core/runtime/AgentThread.types.mjs";
+import { getEmptyCurrentContextUsage } from "../core/runtime/contextUsage.mjs";
+import { EventType } from "./schemas/events.mjs";
+import {
+  CancellationReason
+} from "./schemas/turn.mjs";
+import { TurnNotRunningError } from "./store/SessionStoreErrors.mjs";
+function cancellationReasonFromAbortReason(abortReason) {
+  if (abortReason === CancellationReason.ServerExecutionTimeout) {
+    return CancellationReason.ServerExecutionTimeout;
+  }
+  if (abortReason === CancellationReason.CancelledForNextTurn) {
+    return CancellationReason.CancelledForNextTurn;
+  }
+  if (abortReason === CancellationReason.Abandoned) {
+    return CancellationReason.Abandoned;
+  }
+  return CancellationReason.ClientCancelled;
+}
+function toThreadDoneEvent(event) {
+  const state = event.status === "error" ? { status: "error", error: event.error, ...event.output && { output: event.output } } : { status: "done", output: event.output };
+  return {
+    type: HarnessEventType.THREAD_DONE,
+    id: newEventId(),
+    created_at: (/* @__PURE__ */ new Date()).toISOString(),
+    parent: event.parent,
+    thread_id: event.thread_id,
+    title: event.title,
+    state
+  };
+}
+function toMCPAuthRequiredEvent(event) {
+  return {
+    type: HarnessEventType.MCP_AUTH_REQUIRED,
+    id: event.id,
+    created_at: event.created_at,
+    thread_id: event.thread_id,
+    mcp_servers: event.mcp_servers.map(({ thread_ids, ...server }) => {
+      void thread_ids;
+      return server;
+    })
+  };
+}
+function turnMetricsFromAgentThreadMetrics(metrics) {
+  return {
+    total_input_tokens: metrics.total_input_tokens,
+    total_output_tokens: metrics.total_output_tokens,
+    total_tokens: metrics.total_tokens,
+    total_cache_read_tokens: metrics.total_cache_read_tokens,
+    total_cache_write_tokens: metrics.total_cache_write_tokens,
+    total_reasoning_tokens: metrics.total_reasoning_tokens,
+    total_cost_in_usd: metrics.total_cost_in_usd
+  };
+}
+var TurnHandle = class _TurnHandle {
+  store;
+  turn;
+  orchestrator;
+  resolver;
+  signal;
+  streamStarted = false;
+  constructor(options) {
+    this.store = options.store;
+    this.turn = options.turn;
+    this.orchestrator = options.orchestrator;
+    this.resolver = options.resolver;
+    this.signal = options.signal;
+  }
+  /** Store-only handle (e.g. from {@link SessionHandle.getTurn}) — stream() is not available. */
+  static fromRecord(options) {
+    return new _TurnHandle(options);
+  }
+  static async get(options) {
+    const turn = await options.store.getTurn({
+      session_id: options.session_id,
+      turn_id: options.turn_id
+    });
+    if (!turn) {
+      return void 0;
+    }
+    return _TurnHandle.fromRecord({
+      store: options.store,
+      turn
+    });
+  }
+  get id() {
+    return this.turn.turn_id;
+  }
+  get session_id() {
+    return this.turn.session_id;
+  }
+  get previous_turn_id() {
+    return this.turn.previous_turn_id;
+  }
+  get input() {
+    return this.turn.input;
+  }
+  get state() {
+    return this.turn.state;
+  }
+  get created_at() {
+    return this.turn.created_at;
+  }
+  get custom() {
+    return this.turn.custom;
+  }
+  get record() {
+    return this.turn;
+  }
+  /**
+   * Executes the turn. Single consumer, callable ONCE — a second call throws:
+   * this generator IS the execution (persist-before-yield). Execute-only: the
+   * input was already sent and validated in run(); nothing is sent here.
+   * Sole terminal writer — done/cancelled/error is written to the store from
+   * inside this generator; honors the AbortSignal passed to run(). On every
+   * exit path the resolver is closed best-effort in a finally, after the
+   * terminal write.
+   *
+   * Two consumption patterns (both caller-side; this method is identical for both):
+   *
+   *   // STREAMING — pipe events out as they happen (e.g. SSE):
+   *   for await (const e of turn.stream()) yield sse(e);
+   *
+   *   // NON-STREAMING — drain in background, respond immediately with the
+   *   // running turn. The caller owns the active-turn registry, the .catch
+   *   // (store-write failures reject the drain; agent errors do NOT — they
+   *   // become terminal 'error' events inside), and graceful shutdown.
+   *   const drain = (async () => { for await (const _ of turn.stream()); })()
+   *     .catch(err => logger.error('turn drain failed', err));
+   *   activeTurns.set(turn.id, { controller, drain });
+   *   drain.finally(() => activeTurns.delete(turn.id));
+   *   return turnCreatedResponse(turn);
+   *
+   * Yields the delta-inclusive streaming union: deltas pass through to the
+   * consumer but are NEVER persisted. Events carry no sequence_number; yield
+   * order ≡ persist order (single sequential generator), so callers that need
+   * numbering (e.g. SSE resume) stamp it at their own transport boundary.
+   */
+  async *stream() {
+    if (this.streamStarted) {
+      throw new Error("TurnHandle.stream() is single-use and was already called");
+    }
+    this.streamStarted = true;
+    const orchestrator = this.orchestrator;
+    const resolver = this.resolver;
+    const signal = this.signal;
+    if (!orchestrator || !resolver || !signal) {
+      throw new Error("TurnHandle.stream() is only available on turns returned from SessionHandle.createTurn()");
+    }
+    let caughtError;
+    let frozenByStore = false;
+    let executeResult;
+    let generator;
+    try {
+      const turnCreated = {
+        type: EventType.TURN_CREATED,
+        id: newEventId(),
+        turn_id: this.turn.turn_id,
+        previous_turn_id: this.turn.previous_turn_id,
+        ...this.turn.input.length > 0 ? { input: this.turn.input } : {},
+        state: { status: "running" },
+        created_at: this.turn.created_at.toISOString(),
+        thread_id: null
+      };
+      await this.store.appendToEvents({
+        session_id: this.turn.session_id,
+        turn_id: this.turn.turn_id,
+        events: [turnCreated]
+      });
+      yield turnCreated;
+      generator = orchestrator.execute({ signal });
+      let iterResult = await generator.next();
+      while (!iterResult.done) {
+        const event = iterResult.value;
+        try {
+          const yielded = await this.persistExecutionEvent(event);
+          if (yielded) {
+            yield yielded;
+          }
+        } catch (error) {
+          if (error instanceof TurnNotRunningError) {
+            frozenByStore = true;
+            const emptyResult = {
+              output: null,
+              required_actions: []
+            };
+            await generator.return(emptyResult);
+            generator = void 0;
+            const updatedAt = /* @__PURE__ */ new Date();
+            const createdAtIso = updatedAt.toISOString();
+            const state = {
+              ...error.state,
+              metrics: turnMetricsFromAgentThreadMetrics(orchestrator.getMetrics())
+            };
+            this.turn = { ...this.turn, state, updated_at: updatedAt };
+            yield {
+              type: EventType.TURN_DONE,
+              id: newEventId(),
+              created_at: createdAtIso,
+              state,
+              thread_id: null
+            };
+            return;
+          }
+          throw error;
+        }
+        iterResult = await generator.next();
+      }
+      executeResult = iterResult.value;
+    } catch (error) {
+      caughtError = error instanceof Error ? error : new Error(String(error));
+    } finally {
+      if (generator) {
+        const emptyResult = {
+          output: null,
+          required_actions: []
+        };
+        await generator.return(emptyResult);
+      }
+      const updatedAt = /* @__PURE__ */ new Date();
+      const createdAtIso = updatedAt.toISOString();
+      const metrics = turnMetricsFromAgentThreadMetrics(orchestrator.getMetrics());
+      let terminalState;
+      if (signal.aborted) {
+        terminalState = {
+          status: "cancelled",
+          reason: cancellationReasonFromAbortReason(signal.reason),
+          completed_at: createdAtIso,
+          metrics
+        };
+      } else if (caughtError) {
+        terminalState = {
+          status: "error",
+          message: caughtError.message,
+          completed_at: createdAtIso,
+          metrics
+        };
+      } else if (executeResult?.root_agent_error) {
+        terminalState = {
+          status: "error",
+          message: executeResult.root_agent_error.error,
+          completed_at: createdAtIso,
+          metrics
+        };
+      } else if (executeResult === void 0) {
+        terminalState = {
+          status: "cancelled",
+          reason: CancellationReason.ClientCancelled,
+          completed_at: createdAtIso,
+          metrics
+        };
+      } else {
+        terminalState = {
+          status: "done",
+          output: executeResult.output,
+          required_actions: executeResult.required_actions,
+          completed_at: createdAtIso,
+          metrics
+        };
+      }
+      const turnDone = {
+        type: EventType.TURN_DONE,
+        id: newEventId(),
+        created_at: createdAtIso,
+        state: terminalState,
+        thread_id: null
+      };
+      if (!frozenByStore) {
+        try {
+          await this.store.updateTurnState({
+            session_id: this.turn.session_id,
+            turn_id: this.turn.turn_id,
+            state: terminalState,
+            turn_done_event: turnDone
+          });
+          this.turn = { ...this.turn, state: terminalState, updated_at: updatedAt };
+        } catch (persistError) {
+          if (persistError instanceof TurnNotRunningError) {
+            const state = { ...persistError.state, metrics };
+            this.turn = { ...this.turn, state, updated_at: updatedAt };
+            await resolver.close().catch(() => {
+            });
+            yield {
+              type: EventType.TURN_DONE,
+              id: newEventId(),
+              created_at: createdAtIso,
+              state,
+              thread_id: null
+            };
+            return;
+          }
+          await resolver.close().catch(() => {
+          });
+          throw persistError;
+        }
+      }
+      await resolver.close().catch((err) => {
+        resolver.logger.warn("TurnResourceResolver.close() failed", { err });
+      });
+      if (!frozenByStore) {
+        yield turnDone;
+      }
+    }
+  }
+  /** Paginated read of this turn's persisted events. */
+  async listEvents(input) {
+    return this.store.listTurnEvents({
+      session_id: this.turn.session_id,
+      turn_id: this.turn.turn_id,
+      limit: input.limit,
+      page_token: input.page_token,
+      order: input.order
+    });
+  }
+  /**
+   * Persist side effects for one execution event; return a streaming yield when
+   * the event should be emitted to the consumer (null = side-effect only / skip).
+   */
+  async persistExecutionEvent(event) {
+    const scope = {
+      session_id: this.turn.session_id,
+      turn_id: this.turn.turn_id
+    };
+    switch (event.type) {
+      case HarnessEventType.MODEL_MESSAGE:
+      case HarnessEventType.MODEL_MESSAGE_DELTA:
+        return event;
+      case HarnessEventType.TOOL_RESPONSE:
+        await this.store.appendToEvents({
+          ...scope,
+          events: [event]
+        });
+        return event;
+      case InternalEventType.AGENT_CREATE_SUBAGENT:
+        return null;
+      case InternalEventType.CAPABILITY_STATE: {
+        const state = event.state;
+        if (state === void 0) {
+          throw new AgentHarnessError(
+            "capability_state_error",
+            `CAPABILITY_STATE for key '${event.key}' must not be undefined \u2014 use null to clear durable state`
+          );
+        }
+        await this.store.patchThreadCapabilityState({
+          ...scope,
+          thread_id: event.thread_id,
+          key: event.key,
+          state: event.state
+        });
+        return null;
+      }
+      case HarnessEventType.AGENT_CONTEXT_OVERWRITE: {
+        await this.store.overwriteThreadContext({ ...scope, event });
+        return null;
+      }
+      case InternalEventType.AGENT_CONTEXT_APPEND: {
+        await this.store.appendToThreadContext({
+          ...scope,
+          thread_id: event.thread_id,
+          context: event.context,
+          current_context_usage: event.current_context_usage ?? null,
+          completion: event.completion ?? null
+        });
+        if (event.output.length > 0) {
+          await this.store.appendToEvents({
+            ...scope,
+            events: event.output
+          });
+        }
+        return null;
+      }
+      case InternalEventType.AGENT_DONE: {
+        if (!event.parent) {
+          return null;
+        }
+        const threadDone = toThreadDoneEvent(event);
+        await this.store.removeThreads({
+          ...scope,
+          thread_ids: [event.thread_id]
+        });
+        await this.store.appendToEvents({
+          ...scope,
+          events: [threadDone]
+        });
+        return threadDone;
+      }
+      case HarnessEventType.THREAD_CREATED: {
+        await this.store.addThreads({
+          ...scope,
+          threads: [
+            {
+              thread_id: event.thread_id,
+              parent: event.parent,
+              agent_info: event.agent_info,
+              context: [],
+              current_context_usage: getEmptyCurrentContextUsage(),
+              completion: null,
+              capability_state: null
+            }
+          ]
+        });
+        await this.store.appendToEvents({
+          ...scope,
+          events: [event]
+        });
+        return event;
+      }
+      case InternalEventType.MCP_AUTH_REQUIRED: {
+        const authEvent = toMCPAuthRequiredEvent(event);
+        await this.store.appendToEvents({
+          ...scope,
+          events: [authEvent]
+        });
+        return authEvent;
+      }
+      case HarnessEventType.MCP_INITIALIZE: {
+        await this.store.patchMCPServers({
+          ...scope,
+          mcp_servers: event.mcp_servers.map((initInfo) => ({
+            id: initInfo.id,
+            name: initInfo.name,
+            session_id: initInfo.session_id,
+            transport_type: initInfo.transport_type
+          }))
+        });
+        await this.store.appendToEvents({
+          ...scope,
+          events: [event]
+        });
+        return event;
+      }
+      case HarnessEventType.SANDBOX_CREATED: {
+        await this.store.patchSandboxInfo({
+          ...scope,
+          sandbox_info: { sandbox_id: event.sandbox_id }
+        });
+        await this.store.appendToEvents({
+          ...scope,
+          events: [event]
+        });
+        return event;
+      }
+      case HarnessEventType.TOOL_APPROVAL_REQUIRED:
+      case HarnessEventType.TOOL_RESPONSE_REQUIRED: {
+        await this.store.appendToEvents({
+          ...scope,
+          events: [event]
+        });
+        return event;
+      }
+      default: {
+        await this.store.appendToEvents({
+          ...scope,
+          events: [event]
+        });
+        return event;
+      }
+    }
+  }
+};
+export {
+  TurnHandle
+};
+//# sourceMappingURL=TurnHandle.mjs.map

package/dist/agent-session/TurnHandle.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/agent-session/TurnHandle.ts"],"sourcesContent":["/**\n * Durable turn handle. {@link TurnHandle.stream} is execute-once (persist-before-yield).\n */\nimport { AgentHarnessError } from '../core/errors';\nimport type { MCPAuthRequiredEvent, ModelMessageDeltaEvent, ThreadDoneEvent } from '../core/events/schema';\nimport { EventType as HarnessEventType, newEventId } from '../core/events/schema';\nimport {\n  InternalEventType,\n  type AgentThreadExecutionEvent,\n  type AgentThreadExecutionResult,\n  type InternalMCPAuthRequiredEvent,\n  type InternalThreadDoneEvent,\n} from '../core/runtime/AgentThread.types';\nimport type { AgentThreadOrchestrator } from '../core/runtime/AgentThreadOrchestrator';\nimport { getEmptyCurrentContextUsage } from '../core/runtime/contextUsage';\nimport type { AgentThreadMetrics } from '../core/runtime/metrics';\nimport type { ITurnResourceResolver } from './ITurnResourceResolver';\nimport type { TurnRecord } from './models/TurnRecord';\nimport { EventType, type PersistedTurnEvent, type TurnCreatedEvent, type TurnDoneEvent } from './schemas/events';\nimport type { TokenPagination } from './schemas/pagination';\nimport {\n  CancellationReason,\n  type TerminalTurnState,\n  type TurnInputItem,\n  type TurnMetrics,\n  type TurnState,\n} from './schemas/turn';\nimport type { ISessionStore } from './store/ISessionStore';\nimport { TurnNotRunningError } from './store/SessionStoreErrors';\n\n/** Streaming yield union — deltas pass through; never persisted. No sequence_number. */\nexport type TurnStreamingEvent = PersistedTurnEvent | ModelMessageDeltaEvent;\n\nfunction cancellationReasonFromAbortReason(abortReason: unknown): CancellationReason {\n  if (abortReason === CancellationReason.ServerExecutionTimeout) {\n    return CancellationReason.ServerExecutionTimeout;\n  }\n  if (abortReason === CancellationReason.CancelledForNextTurn) {\n    return CancellationReason.CancelledForNextTurn;\n  }\n  if (abortReason === CancellationReason.Abandoned) {\n    return CancellationReason.Abandoned;\n  }\n  return CancellationReason.ClientCancelled;\n}\n\nfunction toThreadDoneEvent(event: InternalThreadDoneEvent): ThreadDoneEvent {\n  const state =\n    event.status === 'error'\n      ? { status: 'error' as const, error: event.error, ...(event.output && { output: event.output }) }\n      : { status: 'done' as const, output: event.output };\n  return {\n    type: HarnessEventType.THREAD_DONE,\n    id: newEventId(),\n    created_at: new Date().toISOString(),\n    parent: event.parent,\n    thread_id: event.thread_id,\n    title: event.title,\n    state,\n  };\n}\n\nfunction toMCPAuthRequiredEvent(event: InternalMCPAuthRequiredEvent): MCPAuthRequiredEvent {\n  return {\n    type: HarnessEventType.MCP_AUTH_REQUIRED,\n    id: event.id,\n    created_at: event.created_at,\n    thread_id: event.thread_id,\n    mcp_servers: event.mcp_servers.map(({ thread_ids, ...server }) => {\n      void thread_ids;\n      return server;\n    }),\n  };\n}\n\nfunction turnMetricsFromAgentThreadMetrics(metrics: AgentThreadMetrics): TurnMetrics {\n  return {\n    total_input_tokens: metrics.total_input_tokens,\n    total_output_tokens: metrics.total_output_tokens,\n    total_tokens: metrics.total_tokens,\n    total_cache_read_tokens: metrics.total_cache_read_tokens,\n    total_cache_write_tokens: metrics.total_cache_write_tokens,\n    total_reasoning_tokens: metrics.total_reasoning_tokens,\n    total_cost_in_usd: metrics.total_cost_in_usd,\n  };\n}\n\nexport class TurnHandle<TTurnCustom extends object = Record<string, never>> {\n  private readonly store: ISessionStore<object, TTurnCustom>;\n  private turn: TurnRecord<TTurnCustom>;\n  private readonly orchestrator: AgentThreadOrchestrator | undefined;\n  private readonly resolver: ITurnResourceResolver<TTurnCustom> | undefined;\n  private readonly signal: AbortSignal | undefined;\n  private streamStarted = false;\n\n  constructor(options: {\n    store: ISessionStore<object, TTurnCustom>;\n    turn: TurnRecord<TTurnCustom>;\n    orchestrator?: AgentThreadOrchestrator | undefined;\n    resolver?: ITurnResourceResolver<TTurnCustom> | undefined;\n    signal?: AbortSignal | undefined;\n  }) {\n    this.store = options.store;\n    this.turn = options.turn;\n    this.orchestrator = options.orchestrator;\n    this.resolver = options.resolver;\n    this.signal = options.signal;\n  }\n\n  /** Store-only handle (e.g. from {@link SessionHandle.getTurn}) — stream() is not available. */\n  static fromRecord<TCustom extends object = Record<string, never>>(options: {\n    store: ISessionStore<object, TCustom>;\n    turn: TurnRecord<TCustom>;\n  }): TurnHandle<TCustom> {\n    return new TurnHandle(options);\n  }\n\n  static async get<TCustom extends object = Record<string, never>>(options: {\n    store: ISessionStore<object, TCustom>;\n    session_id: string;\n    turn_id: string;\n  }): Promise<TurnHandle<TCustom> | undefined> {\n    const turn = await options.store.getTurn({\n      session_id: options.session_id,\n      turn_id: options.turn_id,\n    });\n    if (!turn) {\n      return undefined;\n    }\n    return TurnHandle.fromRecord({\n      store: options.store,\n      turn,\n    });\n  }\n\n  get id(): string {\n    return this.turn.turn_id;\n  }\n\n  get session_id(): string {\n    return this.turn.session_id;\n  }\n\n  get previous_turn_id(): string | null {\n    return this.turn.previous_turn_id;\n  }\n\n  get input(): TurnInputItem[] {\n    return this.turn.input;\n  }\n\n  get state(): TurnState {\n    return this.turn.state;\n  }\n\n  get created_at(): Date {\n    return this.turn.created_at;\n  }\n\n  get custom(): TTurnCustom | null {\n    return this.turn.custom;\n  }\n\n  get record(): TurnRecord<TTurnCustom> {\n    return this.turn;\n  }\n\n  /**\n   * Executes the turn. Single consumer, callable ONCE — a second call throws:\n   * this generator IS the execution (persist-before-yield). Execute-only: the\n   * input was already sent and validated in run(); nothing is sent here.\n   * Sole terminal writer — done/cancelled/error is written to the store from\n   * inside this generator; honors the AbortSignal passed to run(). On every\n   * exit path the resolver is closed best-effort in a finally, after the\n   * terminal write.\n   *\n   * Two consumption patterns (both caller-side; this method is identical for both):\n   *\n   *   // STREAMING — pipe events out as they happen (e.g. SSE):\n   *   for await (const e of turn.stream()) yield sse(e);\n   *\n   *   // NON-STREAMING — drain in background, respond immediately with the\n   *   // running turn. The caller owns the active-turn registry, the .catch\n   *   // (store-write failures reject the drain; agent errors do NOT — they\n   *   // become terminal 'error' events inside), and graceful shutdown.\n   *   const drain = (async () => { for await (const _ of turn.stream()); })()\n   *     .catch(err => logger.error('turn drain failed', err));\n   *   activeTurns.set(turn.id, { controller, drain });\n   *   drain.finally(() => activeTurns.delete(turn.id));\n   *   return turnCreatedResponse(turn);\n   *\n   * Yields the delta-inclusive streaming union: deltas pass through to the\n   * consumer but are NEVER persisted. Events carry no sequence_number; yield\n   * order ≡ persist order (single sequential generator), so callers that need\n   * numbering (e.g. SSE resume) stamp it at their own transport boundary.\n   */\n  async *stream(): AsyncGenerator<TurnStreamingEvent> {\n    if (this.streamStarted) {\n      throw new Error('TurnHandle.stream() is single-use and was already called');\n    }\n    this.streamStarted = true;\n\n    const orchestrator = this.orchestrator;\n    const resolver = this.resolver;\n    const signal = this.signal;\n    if (!orchestrator || !resolver || !signal) {\n      throw new Error('TurnHandle.stream() is only available on turns returned from SessionHandle.createTurn()');\n    }\n\n    let caughtError: Error | undefined;\n    let frozenByStore = false;\n    let executeResult: AgentThreadExecutionResult | undefined;\n    let generator: AsyncGenerator<AgentThreadExecutionEvent, AgentThreadExecutionResult, unknown> | undefined;\n\n    try {\n      const turnCreated: TurnCreatedEvent = {\n        type: EventType.TURN_CREATED,\n        id: newEventId(),\n        turn_id: this.turn.turn_id,\n        previous_turn_id: this.turn.previous_turn_id,\n        ...(this.turn.input.length > 0 ? { input: this.turn.input } : {}),\n        state: { status: 'running' },\n        created_at: this.turn.created_at.toISOString(),\n        thread_id: null,\n      };\n      await this.store.appendToEvents({\n        session_id: this.turn.session_id,\n        turn_id: this.turn.turn_id,\n        events: [turnCreated],\n      });\n      yield turnCreated;\n\n      generator = orchestrator.execute({ signal });\n      let iterResult = await generator.next();\n      while (!iterResult.done) {\n        const event = iterResult.value;\n        try {\n          const yielded = await this.persistExecutionEvent(event);\n          if (yielded) {\n            yield yielded;\n          }\n        } catch (error) {\n          if (error instanceof TurnNotRunningError) {\n            frozenByStore = true;\n            const emptyResult: AgentThreadExecutionResult = {\n              output: null,\n              required_actions: [],\n            };\n            await generator.return(emptyResult);\n            // Cleared so the finally block does not close the generator a second time.\n            generator = undefined;\n            const updatedAt = new Date();\n            const createdAtIso = updatedAt.toISOString();\n            const state: TerminalTurnState = {\n              ...error.state,\n              metrics: turnMetricsFromAgentThreadMetrics(orchestrator.getMetrics()),\n            };\n            this.turn = { ...this.turn, state, updated_at: updatedAt };\n            yield {\n              type: EventType.TURN_DONE,\n              id: newEventId(),\n              created_at: createdAtIso,\n              state,\n              thread_id: null,\n            };\n            return;\n          }\n          throw error;\n        }\n        iterResult = await generator.next();\n      }\n      executeResult = iterResult.value;\n    } catch (error) {\n      caughtError = error instanceof Error ? error : new Error(String(error));\n    } finally {\n      if (generator) {\n        const emptyResult: AgentThreadExecutionResult = {\n          output: null,\n          required_actions: [],\n        };\n        await generator.return(emptyResult);\n      }\n\n      const updatedAt = new Date();\n      const createdAtIso = updatedAt.toISOString();\n      const metrics = turnMetricsFromAgentThreadMetrics(orchestrator.getMetrics());\n      let terminalState: TerminalTurnState;\n      if (signal.aborted) {\n        terminalState = {\n          status: 'cancelled',\n          reason: cancellationReasonFromAbortReason(signal.reason),\n          completed_at: createdAtIso,\n          metrics,\n        };\n      } else if (caughtError) {\n        terminalState = {\n          status: 'error',\n          message: caughtError.message,\n          completed_at: createdAtIso,\n          metrics,\n        };\n      } else if (executeResult?.root_agent_error) {\n        terminalState = {\n          status: 'error',\n          message: executeResult.root_agent_error.error,\n          completed_at: createdAtIso,\n          metrics,\n        };\n      } else if (executeResult === undefined) {\n        // Consumer abandoned the generator (break/return) without aborting —\n        // no executeResult, no error, signal not aborted.\n        terminalState = {\n          status: 'cancelled',\n          reason: CancellationReason.ClientCancelled,\n          completed_at: createdAtIso,\n          metrics,\n        };\n      } else {\n        terminalState = {\n          status: 'done',\n          output: executeResult.output,\n          required_actions: executeResult.required_actions,\n          completed_at: createdAtIso,\n          metrics,\n        };\n      }\n\n      const turnDone: TurnDoneEvent = {\n        type: EventType.TURN_DONE,\n        id: newEventId(),\n        created_at: createdAtIso,\n        state: terminalState,\n        thread_id: null,\n      };\n\n      if (!frozenByStore) {\n        try {\n          await this.store.updateTurnState({\n            session_id: this.turn.session_id,\n            turn_id: this.turn.turn_id,\n            state: terminalState,\n            turn_done_event: turnDone,\n          });\n          this.turn = { ...this.turn, state: terminalState, updated_at: updatedAt };\n        } catch (persistError) {\n          if (persistError instanceof TurnNotRunningError) {\n            const state: TerminalTurnState = { ...persistError.state, metrics };\n            this.turn = { ...this.turn, state, updated_at: updatedAt };\n            await resolver.close().catch(() => {\n              /* no-op */\n            });\n            yield {\n              type: EventType.TURN_DONE,\n              id: newEventId(),\n              created_at: createdAtIso,\n              state,\n              thread_id: null,\n            };\n            // eslint-disable-next-line no-unsafe-finally -- deliberate: a concurrent freeze during the terminal write makes the store's state authoritative, so the stream ends here\n            return;\n          }\n          // Store-write failures reject the stream (caller drain .catch).\n          await resolver.close().catch(() => {\n            /* no-op */\n          });\n          // eslint-disable-next-line no-unsafe-finally -- deliberate: the terminal-state write runs in finally and its failure must reject the stream\n          throw persistError;\n        }\n      }\n\n      await resolver.close().catch((err: unknown) => {\n        resolver.logger.warn('TurnResourceResolver.close() failed', { err });\n      });\n\n      if (!frozenByStore) {\n        yield turnDone;\n      }\n    }\n  }\n\n  /** Paginated read of this turn's persisted events. */\n  async listEvents(input: {\n    limit: number;\n    page_token?: string | undefined;\n    order?: 'asc' | 'desc' | undefined;\n  }): Promise<{\n    data: PersistedTurnEvent[];\n    pagination: TokenPagination;\n  }> {\n    return this.store.listTurnEvents({\n      session_id: this.turn.session_id,\n      turn_id: this.turn.turn_id,\n      limit: input.limit,\n      page_token: input.page_token,\n      order: input.order,\n    });\n  }\n\n  /**\n   * Persist side effects for one execution event; return a streaming yield when\n   * the event should be emitted to the consumer (null = side-effect only / skip).\n   */\n  private async persistExecutionEvent(event: AgentThreadExecutionEvent): Promise<TurnStreamingEvent | null> {\n    const scope = {\n      session_id: this.turn.session_id,\n      turn_id: this.turn.turn_id,\n    };\n\n    switch (event.type) {\n      case HarnessEventType.MODEL_MESSAGE:\n      case HarnessEventType.MODEL_MESSAGE_DELTA:\n        // Stream only — durable model content lands via AGENT_CONTEXT_APPEND.output.\n        return event;\n\n      case HarnessEventType.TOOL_RESPONSE:\n        await this.store.appendToEvents({\n          ...scope,\n          events: [event],\n        });\n        return event;\n\n      case InternalEventType.AGENT_CREATE_SUBAGENT:\n        return null;\n\n      case InternalEventType.CAPABILITY_STATE: {\n        // Persist boundary: types exclude undefined; reject it at runtime so stores never see it.\n        const state: unknown = event.state;\n        if (state === undefined) {\n          throw new AgentHarnessError(\n            'capability_state_error',\n            `CAPABILITY_STATE for key '${event.key}' must not be undefined — use null to clear durable state`,\n          );\n        }\n        await this.store.patchThreadCapabilityState({\n          ...scope,\n          thread_id: event.thread_id,\n          key: event.key,\n          state: event.state,\n        });\n        return null;\n      }\n\n      case HarnessEventType.AGENT_CONTEXT_OVERWRITE: {\n        await this.store.overwriteThreadContext({ ...scope, event });\n        return null;\n      }\n\n      case InternalEventType.AGENT_CONTEXT_APPEND: {\n        await this.store.appendToThreadContext({\n          ...scope,\n          thread_id: event.thread_id,\n          context: event.context,\n          current_context_usage: event.current_context_usage ?? null,\n          completion: event.completion ?? null,\n        });\n        if (event.output.length > 0) {\n          await this.store.appendToEvents({\n            ...scope,\n            events: event.output,\n          });\n        }\n        return null;\n      }\n\n      case InternalEventType.AGENT_DONE: {\n        if (!event.parent) {\n          return null;\n        }\n        const threadDone = toThreadDoneEvent(event);\n        await this.store.removeThreads({\n          ...scope,\n          thread_ids: [event.thread_id],\n        });\n        await this.store.appendToEvents({\n          ...scope,\n          events: [threadDone],\n        });\n        return threadDone;\n      }\n\n      case HarnessEventType.THREAD_CREATED: {\n        await this.store.addThreads({\n          ...scope,\n          threads: [\n            {\n              thread_id: event.thread_id,\n              parent: event.parent,\n              agent_info: event.agent_info,\n              context: [],\n              current_context_usage: getEmptyCurrentContextUsage(),\n              completion: null,\n              capability_state: null,\n            },\n          ],\n        });\n        await this.store.appendToEvents({\n          ...scope,\n          events: [event],\n        });\n        return event;\n      }\n\n      case InternalEventType.MCP_AUTH_REQUIRED: {\n        const authEvent = toMCPAuthRequiredEvent(event);\n        await this.store.appendToEvents({\n          ...scope,\n          events: [authEvent],\n        });\n        return authEvent;\n      }\n\n      case HarnessEventType.MCP_INITIALIZE: {\n        await this.store.patchMCPServers({\n          ...scope,\n          mcp_servers: event.mcp_servers.map(initInfo => ({\n            id: initInfo.id,\n            name: initInfo.name,\n            session_id: initInfo.session_id,\n            transport_type: initInfo.transport_type,\n          })),\n        });\n        await this.store.appendToEvents({\n          ...scope,\n          events: [event],\n        });\n        return event;\n      }\n\n      case HarnessEventType.SANDBOX_CREATED: {\n        await this.store.patchSandboxInfo({\n          ...scope,\n          sandbox_info: { sandbox_id: event.sandbox_id },\n        });\n        await this.store.appendToEvents({\n          ...scope,\n          events: [event],\n        });\n        return event;\n      }\n\n      case HarnessEventType.TOOL_APPROVAL_REQUIRED:\n      case HarnessEventType.TOOL_RESPONSE_REQUIRED: {\n        await this.store.appendToEvents({\n          ...scope,\n          events: [event],\n        });\n        return event;\n      }\n\n      default: {\n        // Registered passthrough (orchestrator unwraps PASSTHROUGH before yield).\n        await this.store.appendToEvents({\n          ...scope,\n          events: [event],\n        });\n        return event;\n      }\n    }\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/agent-session/TurnResourceResolver.d.ts

@@ -0,0 +1,154 @@
+import type { Logger } from 'winston';
+import type { AgentCapability } from '../core/capabilities/AgentCapability';
+import type { ILLM } from '../core/llm/ILLM';
+import type { ToolSource } from '../core/mcp/IMCPServer';
+import { type RemoteMcpHeaders } from '../core/mcp/RemoteMCP';
+import type { AgentDefinition, ModelParams } from '../core/runtime/AgentDefinition';
+import type { AgentInfo } from '../core/runtime/AgentThread.types';
+import type { Sandbox, SandboxInfo } from '../core/sandbox/Sandbox';
+import type { AgentTracing } from '../core/tracing/AgentTracing';
+import type { ITurnResourceResolver } from './ITurnResourceResolver';
+import type { TurnRecord } from './models/TurnRecord';
+import type { AgentSpec } from './schemas/agentSpec';
+/**
+ * Factory that creates a Sandbox handle for a run (reattach via
+ * existingSandboxId). `spec` carries the sandbox-relevant agent settings
+ * (e.g. config.sandbox.file_downloads) so implementations can shape the
+ * Sandbox per run without the factory type growing a field per option.
+ */
+export type TurnSandboxFactory = (input: {
+    spec: AgentSpec;
+    existingSandboxId?: string | undefined;
+    signal: AbortSignal;
+    tracing: AgentTracing;
+}) => Promise<Sandbox>;
+/**
+ * Batteries-included base implementation. Construct-and-go for the default
+ * behavior; subclass and override to customize (tool sources, sandbox,
+ * tracing).
+ */
+export declare class TurnResourceResolver<TTurnCustom extends object = Record<string, never>> implements ITurnResourceResolver<TTurnCustom> {
+    #private;
+    protected readonly deps: {
+        /** Model name → client and defaults. Called once per resolved definition; may load provider config. */
+        llm: (model: string) => Promise<{
+            modelClient: ILLM;
+            defaultModelParams: ModelParams;
+        }>;
+        /**
+         * MCP server name → connection details. Required to use spec.mcp_servers:
+         * the AgentSpec carries names only (no url/headers on the wire) — the
+         * runtime supplies the catalog. Called once per distinct server name per
+         * turn. Throw for unknown names. `headers` supports the async resolver form.
+         */
+        mcp: (name: string) => Promise<{
+            url: string;
+            headers?: RemoteMcpHeaders;
+        }>;
+        mcpRequestTimeoutMs: number;
+        mcpConnectTimeoutMs: number;
+        /** One sandbox type per runtime. Omit = no sandbox support. */
+        sandboxProvider?: TurnSandboxFactory | undefined;
+        /**
+         * Named-agent lookup (registry id → live AgentSpec). Required when a
+         * session is bound by reference; omit only if all sessions use inline agents.
+         */
+        agent?: ((agentId: string) => Promise<AgentSpec>) | undefined;
+        /** Forwarded to RemoteMCP / AgentThread (required by their constructors). */
+        logger: Logger;
+    };
+    constructor(deps: {
+        /** Model name → client and defaults. Called once per resolved definition; may load provider config. */
+        llm: (model: string) => Promise<{
+            modelClient: ILLM;
+            defaultModelParams: ModelParams;
+        }>;
+        /**
+         * MCP server name → connection details. Required to use spec.mcp_servers:
+         * the AgentSpec carries names only (no url/headers on the wire) — the
+         * runtime supplies the catalog. Called once per distinct server name per
+         * turn. Throw for unknown names. `headers` supports the async resolver form.
+         */
+        mcp: (name: string) => Promise<{
+            url: string;
+            headers?: RemoteMcpHeaders;
+        }>;
+        mcpRequestTimeoutMs: number;
+        mcpConnectTimeoutMs: number;
+        /** One sandbox type per runtime. Omit = no sandbox support. */
+        sandboxProvider?: TurnSandboxFactory | undefined;
+        /**
+         * Named-agent lookup (registry id → live AgentSpec). Required when a
+         * session is bound by reference; omit only if all sessions use inline agents.
+         */
+        agent?: ((agentId: string) => Promise<AgentSpec>) | undefined;
+        /** Forwarded to RemoteMCP / AgentThread (required by their constructors). */
+        logger: Logger;
+    });
+    get logger(): Logger;
+    /** Default: no-op tracing. Override to plug in a real tracer. */
+    createTracing(): AgentTracing;
+    /** Named (ref) session agent → live registry lookup via deps.agent. */
+    resolveAgentSpec(input: {
+        agent_id: string;
+    }): Promise<AgentSpec>;
+    /**
+     * Default: creates a sandbox iff a provider is configured AND the spec wants
+     * one; reattaches to the previous turn's VM via `existing.sandbox_id` when
+     * present. Overrides that resolve their own sandbox must assign it so
+     * close() can release it (or override close() too).
+     */
+    resolveSandbox(input: {
+        spec: AgentSpec;
+        existing?: SandboxInfo | undefined;
+        previousTurn?: TurnRecord<TTurnCustom> | undefined;
+        signal: AbortSignal;
+        tracing: AgentTracing;
+    }): Promise<Sandbox | undefined>;
+    /**
+     * Closes the sandbox HANDLE if one was resolved. This releases only this
+     * process's connection (local bridge); the sandbox VM keeps running and the
+     * next turn reattaches via `existing.sandbox_id`.
+     *
+     * Tool sources (MCP connections) are intentionally NOT closed: the run's
+     * AbortSignal already aborts their in-flight calls, and connections are
+     * per-run objects that are simply dropped. If deterministic MCP socket
+     * release is ever needed, add it here — no contract change required.
+     *
+     * Subclasses that acquire additional resources MUST override, release
+     * their own resources best-effort, and call `await super.close()`.
+     * Idempotent; never throws.
+     */
+    close(): Promise<void>;
+    /**
+     * Default: maps the spec directly to a definition — spec.mcp_servers carry
+     * names only; deps.mcp resolves each name to url/headers, and the result
+     * becomes a RemoteMCP source (deduped per turn via getOrCreateToolSource)
+     * wrapped in a per-agent ToolSet view. Passes the previous turn's persisted
+     * MCP session_id into RemoteMCP for cross-turn stateful resume.
+     */
+    resolveAgentDefinition(input: {
+        spec: AgentSpec;
+        thread_id: string;
+        agent_info?: AgentInfo | undefined;
+        previousTurn?: TurnRecord<TTurnCustom> | undefined;
+        signal: AbortSignal;
+        tracing: AgentTracing;
+    }): Promise<{
+        definition: AgentDefinition;
+        extraCapabilities?: AgentCapability[] | undefined;
+    }>;
+    /**
+     * Returns the tool source for `id`, creating it on first call — use from
+     * resolveAgentDefinition overrides so agents sharing a server share one
+     * connection. Single-flight by id: the promise is stored synchronously (no
+     * await between get and set), so overlapping resolveAgentDefinition calls
+     * can never double-create. Rejections stay cached: one attempt per turn.
+     * Do not override.
+     */
+    protected getOrCreateToolSource(input: {
+        id: string;
+        create: () => Promise<ToolSource>;
+    }): Promise<ToolSource>;
+}
+//# sourceMappingURL=TurnResourceResolver.d.ts.map