@truefoundry/trueforge-core 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 TrueFoundry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -0,0 +1,69 @@
+import type { Logger } from 'winston';
+import type { AgentCapability } from '../core/capabilities/AgentCapability';
+import type { AgentDefinition } 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 { TurnRecord } from './models/TurnRecord';
+import type { AgentSpec } from './schemas/agentSpec';
+/**
+ * Per-run wiring contract consumed by SessionHandle.createTurn(). Implementations hold
+ * per-request state (secrets, providers, caches) freely.
+ */
+export interface ITurnResourceResolver<TTurnCustom extends object = Record<string, never>> {
+    /** Forwarded to AgentThread / orchestrator / RemoteMCP. */
+    readonly logger: Logger;
+    /** Called exactly once per run, before any other method. */
+    createTracing(): AgentTracing;
+    /**
+     * Look up the live AgentSpec for a named (ref) session agent.
+     * Value sessions use the stored spec and never call this.
+     */
+    resolveAgentSpec(input: {
+        agent_id: string;
+    }): Promise<AgentSpec>;
+    /**
+     * Called exactly once per run, before any thread is built; the harness holds
+     * the result and shares the same reference across all threads. Return
+     * undefined when the run needs no sandbox. `existing` carries the previous
+     * turn's sandbox info for cross-turn reattach.
+     */
+    resolveSandbox(input: {
+        spec: AgentSpec;
+        existing?: SandboxInfo | undefined;
+        previousTurn?: TurnRecord<TTurnCustom> | undefined;
+        signal: AbortSignal;
+        tracing: AgentTracing;
+    }): Promise<Sandbox | undefined>;
+    /**
+     * Called once per thread_id; calls for different ids may overlap (parallel
+     * sub-agent spawns), so implementations must be concurrency-safe across ids.
+     * `agent_info` is set for sub-agent threads. `previousTurn` is read-only:
+     * branch on it, but never load state into capabilities — return blank
+     * instances; the AgentThread constructor is the sole hydration path.
+     * `extraCapabilities` are appended after the built-in capabilities.
+     */
+    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;
+    }>;
+    /**
+     * Release per-run resources. Called by the harness at the end of the run:
+     * by TurnHandle.stream() in its finally (AFTER the terminal state write), or by
+     * SessionHandle.createTurn() when it throws before a TurnHandle exists — so resources acquired
+     * during a failed run (e.g. a sandbox VM) are still released. Best-effort:
+     * the harness logs and swallows errors — close() can never flip a terminal
+     * state or fail the turn. Must be idempotent. The resolver owns cleanup
+     * because it owns acquisition: the run flow calls this one method without
+     * knowing what was resolved.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=ITurnResourceResolver.d.ts.map

package/dist/agent-session/ITurnResourceResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ITurnResourceResolver.d.ts","sourceRoot":"","sources":["../../src/agent-session/ITurnResourceResolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACtC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAC;AAC5E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD;;;GAGG;AACH,MAAM,WAAW,qBAAqB,CAAC,WAAW,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;IACvF,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4DAA4D;IAC5D,aAAa,IAAI,YAAY,CAAC;IAC9B;;;OAGG;IACH,gBAAgB,CAAC,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAClE;;;;;OAKG;IACH,cAAc,CAAC,KAAK,EAAE;QACpB,IAAI,EAAE,SAAS,CAAC;QAChB,QAAQ,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;QACnC,YAAY,CAAC,EAAE,UAAU,CAAC,WAAW,CAAC,GAAG,SAAS,CAAC;QACnD,MAAM,EAAE,WAAW,CAAC;QACpB,OAAO,EAAE,YAAY,CAAC;KACvB,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAC;IACjC;;;;;;;OAOG;IACH,sBAAsB,CAAC,KAAK,EAAE;QAC5B,IAAI,EAAE,SAAS,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;QACnC,YAAY,CAAC,EAAE,UAAU,CAAC,WAAW,CAAC,GAAG,SAAS,CAAC;QACnD,MAAM,EAAE,WAAW,CAAC;QACpB,OAAO,EAAE,YAAY,CAAC;KACvB,GAAG,OAAO,CAAC;QACV,UAAU,EAAE,eAAe,CAAC;QAC5B,iBAAiB,CAAC,EAAE,eAAe,EAAE,GAAG,SAAS,CAAC;KACnD,CAAC,CAAC;IACH;;;;;;;;;OASG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB"}

package/dist/agent-session/ITurnResourceResolver.js

@@ -0,0 +1,19 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/agent-session/ITurnResourceResolver.ts
+var ITurnResourceResolver_exports = {};
+module.exports = __toCommonJS(ITurnResourceResolver_exports);
+//# sourceMappingURL=ITurnResourceResolver.js.map

package/dist/agent-session/ITurnResourceResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/agent-session/ITurnResourceResolver.ts"],"sourcesContent":["import type { Logger } from 'winston';\nimport type { AgentCapability } from '../core/capabilities/AgentCapability';\nimport type { AgentDefinition } from '../core/runtime/AgentDefinition';\nimport type { AgentInfo } from '../core/runtime/AgentThread.types';\nimport type { Sandbox, SandboxInfo } from '../core/sandbox/Sandbox';\nimport type { AgentTracing } from '../core/tracing/AgentTracing';\nimport type { TurnRecord } from './models/TurnRecord';\nimport type { AgentSpec } from './schemas/agentSpec';\n\n/**\n * Per-run wiring contract consumed by SessionHandle.createTurn(). Implementations hold\n * per-request state (secrets, providers, caches) freely.\n */\nexport interface ITurnResourceResolver<TTurnCustom extends object = Record<string, never>> {\n  /** Forwarded to AgentThread / orchestrator / RemoteMCP. */\n  readonly logger: Logger;\n  /** Called exactly once per run, before any other method. */\n  createTracing(): AgentTracing;\n  /**\n   * Look up the live AgentSpec for a named (ref) session agent.\n   * Value sessions use the stored spec and never call this.\n   */\n  resolveAgentSpec(input: { agent_id: string }): Promise<AgentSpec>;\n  /**\n   * Called exactly once per run, before any thread is built; the harness holds\n   * the result and shares the same reference across all threads. Return\n   * undefined when the run needs no sandbox. `existing` carries the previous\n   * turn's sandbox info for cross-turn reattach.\n   */\n  resolveSandbox(input: {\n    spec: AgentSpec;\n    existing?: SandboxInfo | undefined;\n    previousTurn?: TurnRecord<TTurnCustom> | undefined;\n    signal: AbortSignal;\n    tracing: AgentTracing;\n  }): Promise<Sandbox | undefined>;\n  /**\n   * Called once per thread_id; calls for different ids may overlap (parallel\n   * sub-agent spawns), so implementations must be concurrency-safe across ids.\n   * `agent_info` is set for sub-agent threads. `previousTurn` is read-only:\n   * branch on it, but never load state into capabilities — return blank\n   * instances; the AgentThread constructor is the sole hydration path.\n   * `extraCapabilities` are appended after the built-in capabilities.\n   */\n  resolveAgentDefinition(input: {\n    spec: AgentSpec;\n    thread_id: string;\n    agent_info?: AgentInfo | undefined;\n    previousTurn?: TurnRecord<TTurnCustom> | undefined;\n    signal: AbortSignal;\n    tracing: AgentTracing;\n  }): Promise<{\n    definition: AgentDefinition;\n    extraCapabilities?: AgentCapability[] | undefined;\n  }>;\n  /**\n   * Release per-run resources. Called by the harness at the end of the run:\n   * by TurnHandle.stream() in its finally (AFTER the terminal state write), or by\n   * SessionHandle.createTurn() when it throws before a TurnHandle exists — so resources acquired\n   * during a failed run (e.g. a sandbox VM) are still released. Best-effort:\n   * the harness logs and swallows errors — close() can never flip a terminal\n   * state or fail the turn. Must be idempotent. The resolver owns cleanup\n   * because it owns acquisition: the run flow calls this one method without\n   * knowing what was resolved.\n   */\n  close(): Promise<void>;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/agent-session/ITurnResourceResolver.mjs

@@ -0,0 +1 @@
+//# sourceMappingURL=ITurnResourceResolver.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

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

@@ -0,0 +1,81 @@
+import type { ITurnResourceResolver } from './ITurnResourceResolver';
+import type { SessionRecord } from './models/SessionRecord';
+import type { SessionEventItem } from './schemas/events';
+import type { TokenPagination } from './schemas/pagination';
+import type { SessionAgent } from './schemas/session';
+import type { TurnInputItem } from './schemas/turn';
+import type { ISessionStore, TurnRecordWithoutSnapshot } from './store/ISessionStore';
+import { TurnHandle } from './TurnHandle';
+export declare class SessionHandle<TSessionCustom extends object = Record<string, never>, TTurnCustom extends object = Record<string, never>> {
+    private readonly store;
+    private session;
+    constructor(options: {
+        store: ISessionStore<TSessionCustom, TTurnCustom>;
+        session: SessionRecord<TSessionCustom>;
+    });
+    get session_id(): string;
+    get tenant_id(): string;
+    get agent(): SessionAgent;
+    get custom(): TSessionCustom | null;
+    get record(): SessionRecord<TSessionCustom>;
+    /**
+     * Prepares and commits a new turn — NO execution happens here (execution =
+     * TurnHandle.stream()). Builds threads from the previous turn's snapshot, then
+     * sends the input through the orchestrator fully drained (validation +
+     * context append; empty input still preflights threads awaiting user input),
+     * then persists via one atomic store.createTurn LAST. A send/validation
+     * failure therefore persists nothing. The returned turn is durable with
+     * state { status: 'running' }.
+     *
+     * On any failure, createTurn() closes the resolver (best-effort) before rethrowing,
+     * so resources acquired here (e.g. a sandbox VM) never outlive a failed run.
+     * On success, ownership of resolver.close() passes to TurnHandle.stream().
+     *
+     * `previous_turn_id`: omitted/`'auto'` → session tip; `'none'` → new root
+     * (no parent, even on a non-empty session); string → fork from that turn
+     * (must exist). Concurrent `'auto'` forks both succeed.
+     */
+    createTurn(input: {
+        turn_id: string;
+        input?: TurnInputItem[] | undefined;
+        /** 'auto'/omitted → session.last_turn_id; 'none' → new root; id → fork from that turn. */
+        previous_turn_id?: string | undefined;
+        signal: AbortSignal;
+        resolver: ITurnResourceResolver<TTurnCustom>;
+        /** Value = stored as-is. Fn = merge over previous turn's custom. Omitted = undefined. */
+        custom?: TTurnCustom | ((previous?: TTurnCustom) => TTurnCustom) | undefined;
+        /**
+         * Forwarded to store.createTurn: sets session.title in the same atomic
+         * unit IF the session has none; never overwrites. The caller derives the
+         * value (e.g. from the first user message) — the library does not.
+         */
+        update_session_title_if_not_exist?: string | undefined;
+    }): Promise<TurnHandle<TTurnCustom>>;
+    /** Returns the turn handle (store-backed; not executable), or undefined if not found. */
+    getTurn(turn_id: string): Promise<TurnHandle<TTurnCustom> | undefined>;
+    /** Paginated list of this session's turn rows (no snapshot). */
+    listTurns(input: {
+        limit: number;
+        page_token?: string | undefined;
+    }): Promise<{
+        data: TurnRecordWithoutSnapshot<TTurnCustom>[];
+        pagination: TokenPagination;
+    }>;
+    /**
+     * Paginated session-wide feed of persisted events across turns, including
+     * turn.created / turn.done lifecycle events. Reads from the store only —
+     * nothing is synthesized on read.
+     */
+    listEvents(input: {
+        limit: number;
+        page_token?: string | undefined;
+        last_turn_id?: string | undefined;
+    }): Promise<{
+        data: SessionEventItem[];
+        pagination: TokenPagination;
+    }>;
+    private buildThreads;
+    private buildThread;
+    private makeCreateDynamicSubAgentThread;
+}
+//# sourceMappingURL=SessionHandle.d.ts.map

package/dist/agent-session/SessionHandle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionHandle.d.ts","sourceRoot":"","sources":["../../src/agent-session/SessionHandle.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAG5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,OAAO,KAAK,EAAE,aAAa,EAAoC,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACxH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAkF1C,qBAAa,aAAa,CACxB,cAAc,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EACrD,WAAW,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;IAElD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6C;IACnE,OAAO,CAAC,OAAO,CAAgC;IAE/C,YAAY,OAAO,EAAE;QAAE,KAAK,EAAE,aAAa,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;QAAC,OAAO,EAAE,aAAa,CAAC,cAAc,CAAC,CAAA;KAAE,EAGjH;IAED,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,IAAI,KAAK,IAAI,YAAY,CAExB;IAED,IAAI,MAAM,IAAI,cAAc,GAAG,IAAI,CAElC;IAED,IAAI,MAAM,IAAI,aAAa,CAAC,cAAc,CAAC,CAE1C;IAED;;;;;;;;;;;;;;;;OAgBG;IACG,UAAU,CAAC,KAAK,EAAE;QACtB,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,aAAa,EAAE,GAAG,SAAS,CAAC;QACpC,0FAA0F;QAC1F,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QACtC,MAAM,EAAE,WAAW,CAAC;QACpB,QAAQ,EAAE,qBAAqB,CAAC,WAAW,CAAC,CAAC;QAC7C,yFAAyF;QACzF,MAAM,CAAC,EAAE,WAAW,GAAG,CAAC,CAAC,QAAQ,CAAC,EAAE,WAAW,KAAK,WAAW,CAAC,GAAG,SAAS,CAAC;QAC7E;;;;WAIG;QACH,iCAAiC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KACxD,GAAG,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAmInC;IAED,yFAAyF;IACnF,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,GAAG,SAAS,CAAC,CAM3E;IAED,gEAAgE;IAC1D,SAAS,CAAC,KAAK,EAAE;QACrB,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KACjC,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,yBAAyB,CAAC,WAAW,CAAC,EAAE,CAAC;QAAC,UAAU,EAAE,eAAe,CAAA;KAAE,CAAC,CAM3F;IAED;;;;OAIG;IACG,UAAU,CAAC,KAAK,EAAE;QACtB,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAChC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KACnC,GAAG,OAAO,CAAC;QACV,IAAI,EAAE,gBAAgB,EAAE,CAAC;QACzB,UAAU,EAAE,eAAe,CAAC;KAC7B,CAAC,CAOD;YAEa,YAAY;YA8BZ,WAAW;IA+CzB,OAAO,CAAC,+BAA+B;CAoDxC"}

package/dist/agent-session/SessionHandle.js

@@ -0,0 +1,392 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/agent-session/SessionHandle.ts
+var SessionHandle_exports = {};
+__export(SessionHandle_exports, {
+  SessionHandle: () => SessionHandle
+});
+module.exports = __toCommonJS(SessionHandle_exports);
+var import_schema = require("../core/events/schema.js");
+var import_AgentThread = require("../core/runtime/AgentThread.js");
+var import_AgentThreadOrchestrator = require("../core/runtime/AgentThreadOrchestrator.js");
+var import_contextUtils = require("../core/runtime/contextUtils.js");
+var import_builtinsFromSpec = require("./builtinsFromSpec.js");
+var import_TurnRecord = require("./models/TurnRecord.js");
+var import_events = require("./schemas/events.js");
+var import_turn = require("./schemas/turn.js");
+var import_TurnHandle = require("./TurnHandle.js");
+var MAX_TURN_ANCESTORS = 20;
+function resolvePreviousTurnId(requested, lastTurnId) {
+  if (requested === "none") {
+    return null;
+  }
+  if (requested === void 0 || requested === "auto") {
+    return lastTurnId ?? null;
+  }
+  return requested;
+}
+function toSendBatch(input) {
+  if (!input || input.length === 0) {
+    return [];
+  }
+  if (input.every((msg) => (0, import_contextUtils.isApprovalDecisionMessage)(msg) || (0, import_contextUtils.isClientSideToolResponseMessage)(msg))) {
+    return input;
+  }
+  if (input.every(import_contextUtils.isInputUserMessage)) {
+    return input;
+  }
+  throw new Error("input must be homogeneous: all user messages, or all approval/tool-response messages");
+}
+function toNewThreadInit(snapshot) {
+  const { context, current_context_usage, completion, capability_state, ...rest } = snapshot;
+  void context;
+  void current_context_usage;
+  void completion;
+  void capability_state;
+  return rest;
+}
+function collectContextAppends(events) {
+  return (async () => {
+    const appendMap = /* @__PURE__ */ new Map();
+    for await (const event of events) {
+      const existing = appendMap.get(event.thread_id);
+      if (existing) {
+        existing.context.push(...event.context);
+        if (event.current_context_usage !== void 0) {
+          existing.current_context_usage = event.current_context_usage;
+        }
+      } else {
+        appendMap.set(event.thread_id, {
+          thread_id: event.thread_id,
+          context: [...event.context],
+          current_context_usage: event.current_context_usage ?? null
+        });
+      }
+    }
+    return [...appendMap.values()];
+  })();
+}
+function cancelledTurnDoneEvent() {
+  return {
+    type: import_events.EventType.TURN_DONE,
+    id: (0, import_schema.newEventId)(),
+    created_at: (/* @__PURE__ */ new Date()).toISOString(),
+    state: {
+      status: "cancelled",
+      reason: import_turn.CancellationReason.CancelledForNextTurn,
+      completed_at: (/* @__PURE__ */ new Date()).toISOString()
+    },
+    thread_id: null
+  };
+}
+function threadsRecordFromMap(threads) {
+  const out = {};
+  for (const [id, thread] of threads) {
+    out[id] = thread.toSnapshot();
+  }
+  return out;
+}
+var SessionHandle = class {
+  store;
+  session;
+  constructor(options) {
+    this.store = options.store;
+    this.session = options.session;
+  }
+  get session_id() {
+    return this.session.session_id;
+  }
+  get tenant_id() {
+    return this.session.tenant_id;
+  }
+  get agent() {
+    return this.session.agent;
+  }
+  get custom() {
+    return this.session.custom;
+  }
+  get record() {
+    return this.session;
+  }
+  /**
+   * Prepares and commits a new turn — NO execution happens here (execution =
+   * TurnHandle.stream()). Builds threads from the previous turn's snapshot, then
+   * sends the input through the orchestrator fully drained (validation +
+   * context append; empty input still preflights threads awaiting user input),
+   * then persists via one atomic store.createTurn LAST. A send/validation
+   * failure therefore persists nothing. The returned turn is durable with
+   * state { status: 'running' }.
+   *
+   * On any failure, createTurn() closes the resolver (best-effort) before rethrowing,
+   * so resources acquired here (e.g. a sandbox VM) never outlive a failed run.
+   * On success, ownership of resolver.close() passes to TurnHandle.stream().
+   *
+   * `previous_turn_id`: omitted/`'auto'` → session tip; `'none'` → new root
+   * (no parent, even on a non-empty session); string → fork from that turn
+   * (must exist). Concurrent `'auto'` forks both succeed.
+   */
+  async createTurn(input) {
+    const previousTurnId = resolvePreviousTurnId(input.previous_turn_id, this.session.last_turn_id);
+    const previous = previousTurnId ? await this.store.freezeAndGetTurn({
+      session_id: this.session.session_id,
+      turn_id: previousTurnId,
+      turn_done_event: cancelledTurnDoneEvent()
+    }) : void 0;
+    const custom = typeof input.custom === "function" ? input.custom(previous?.custom ?? void 0) : input.custom;
+    try {
+      const tracing = input.resolver.createTracing();
+      const agent = this.session.agent;
+      const spec = agent.type === "inline" ? agent.spec : await input.resolver.resolveAgentSpec({ agent_id: agent.id });
+      const sandbox = await input.resolver.resolveSandbox({
+        spec,
+        existing: previous?.snapshot.sandbox_info ?? void 0,
+        previousTurn: previous,
+        signal: input.signal,
+        tracing
+      });
+      const agentThreads = await this.buildThreads({
+        previous,
+        resolver: input.resolver,
+        spec,
+        sandbox,
+        tracing,
+        signal: input.signal
+      });
+      const createDynamicSubAgentThread = this.makeCreateDynamicSubAgentThread({
+        resolver: input.resolver,
+        previous,
+        spec,
+        sandbox,
+        tracing
+      });
+      const orchestrator = new import_AgentThreadOrchestrator.AgentThreadOrchestrator({
+        agentThreads,
+        createDynamicSubAgentThread,
+        tracing,
+        logger: input.resolver.logger
+      });
+      const sendBatch = toSendBatch(input.input);
+      const new_context_appends = await collectContextAppends(orchestrator.send(sendBatch));
+      const turnId = input.turn_id;
+      const now = /* @__PURE__ */ new Date();
+      const new_threads = [];
+      if (!previous) {
+        const root = agentThreads.get(import_TurnRecord.MAIN_THREAD_ID);
+        if (root) {
+          new_threads.push(toNewThreadInit(root.toSnapshot()));
+        }
+      } else {
+        for (const [threadId, thread] of agentThreads) {
+          if (previous.snapshot.threads[threadId] === void 0) {
+            new_threads.push(toNewThreadInit(thread.toSnapshot()));
+          }
+        }
+      }
+      const turnInit = {
+        turn_id: turnId,
+        session_id: this.session.session_id,
+        first_turn_id: previous?.first_turn_id ?? turnId,
+        ancestor_ids: previous ? [...previous.ancestor_ids, previous.turn_id].slice(-MAX_TURN_ANCESTORS) : [],
+        previous_turn_id: previousTurnId,
+        state: { status: "running" },
+        input: input.input ?? [],
+        created_at: now,
+        updated_at: now,
+        custom: custom ?? null
+      };
+      const turnRecord = {
+        ...turnInit,
+        snapshot: {
+          threads: threadsRecordFromMap(agentThreads),
+          mcp_servers: previous?.snapshot.mcp_servers ?? null,
+          sandbox_info: previous?.snapshot.sandbox_info ?? null
+        }
+      };
+      await this.store.createTurn({
+        turn: turnInit,
+        new_threads,
+        new_context_appends,
+        capability_states: [...agentThreads].map(([thread_id, thread]) => ({
+          thread_id,
+          capability_state: thread.toSnapshot().capability_state
+        })),
+        update_session_title_if_not_exist: input.update_session_title_if_not_exist ?? null
+      });
+      const refreshed = await this.store.getSession({
+        tenant_id: this.tenant_id,
+        session_id: this.session.session_id
+      });
+      if (refreshed) {
+        this.session = refreshed;
+      }
+      return new import_TurnHandle.TurnHandle({
+        store: this.store,
+        turn: turnRecord,
+        orchestrator,
+        resolver: input.resolver,
+        signal: input.signal
+      });
+    } catch (error) {
+      await input.resolver.close().catch((closeError) => {
+        input.resolver.logger.warn("TurnResourceResolver.close() failed after createTurn() error", {
+          err: closeError
+        });
+      });
+      throw error;
+    }
+  }
+  /** Returns the turn handle (store-backed; not executable), or undefined if not found. */
+  async getTurn(turn_id) {
+    return import_TurnHandle.TurnHandle.get({
+      store: this.store,
+      session_id: this.session.session_id,
+      turn_id
+    });
+  }
+  /** Paginated list of this session's turn rows (no snapshot). */
+  async listTurns(input) {
+    return this.store.listTurns({
+      session_id: this.session.session_id,
+      limit: input.limit,
+      page_token: input.page_token
+    });
+  }
+  /**
+   * Paginated session-wide feed of persisted events across turns, including
+   * turn.created / turn.done lifecycle events. Reads from the store only —
+   * nothing is synthesized on read.
+   */
+  async listEvents(input) {
+    return this.store.listSessionEvents({
+      session_id: this.session.session_id,
+      limit: input.limit,
+      page_token: input.page_token,
+      last_turn_id: input.last_turn_id
+    });
+  }
+  async buildThreads(input) {
+    const snapshots = input.previous?.snapshot.threads;
+    const threadIds = snapshots ? Object.keys(snapshots) : [import_TurnRecord.MAIN_THREAD_ID];
+    const map = /* @__PURE__ */ new Map();
+    for (const threadId of threadIds) {
+      const data = snapshots?.[threadId];
+      map.set(
+        threadId,
+        await this.buildThread({
+          threadId,
+          data,
+          resolver: input.resolver,
+          previous: input.previous,
+          spec: input.spec,
+          sandbox: input.sandbox,
+          tracing: input.tracing,
+          signal: input.signal
+        })
+      );
+    }
+    return map;
+  }
+  async buildThread(input) {
+    const { definition, extraCapabilities } = await input.resolver.resolveAgentDefinition({
+      spec: input.spec,
+      thread_id: input.threadId,
+      agent_info: input.data?.agent_info ?? void 0,
+      previousTurn: input.previous,
+      signal: input.signal,
+      tracing: input.tracing
+    });
+    const isChild = Boolean(input.data?.parent);
+    const capabilities = [
+      ...(0, import_builtinsFromSpec.builtinsFromSpec)({
+        spec: input.spec,
+        definition,
+        isChild,
+        sandboxAvailable: Boolean(input.sandbox),
+        tracing: input.tracing,
+        logger: input.resolver.logger
+      }),
+      ...extraCapabilities ?? []
+    ];
+    return new import_AgentThread.AgentThread({
+      definition,
+      threadId: input.threadId,
+      title: input.data?.agent_info?.name ?? (isChild ? input.threadId : "main"),
+      sandbox: input.sandbox,
+      context: input.data?.context,
+      currentContextUsage: input.data?.current_context_usage,
+      parent: input.data?.parent ?? void 0,
+      agentInfo: input.data?.agent_info ?? void 0,
+      preComputedCompletion: input.data?.completion ?? void 0,
+      capabilities,
+      capabilityState: input.data?.capability_state ?? void 0,
+      tracing: input.tracing,
+      logger: input.resolver.logger
+    });
+  }
+  makeCreateDynamicSubAgentThread(input) {
+    return async (params) => {
+      const { definition, extraCapabilities } = await input.resolver.resolveAgentDefinition({
+        spec: input.spec,
+        thread_id: params.threadId,
+        agent_info: params.request,
+        previousTurn: input.previous,
+        signal: params.signal,
+        tracing: input.tracing
+      });
+      const childDefinition = {
+        ...definition,
+        toolSets: params.parentDefinition.toolSets ?? definition.toolSets,
+        // The delegated task goes in as the initial user message; the sub-agent
+        // system prompt is SUB_AGENT_IDENTITY (added by AgentThread.buildInstruction).
+        instruction: void 0,
+        messages: [{ role: "user", content: params.request.input }],
+        // Sub-agents should return free-form summaries to the parent, not the user-facing structured response.
+        responseFormat: void 0
+      };
+      const capabilities = [
+        ...(0, import_builtinsFromSpec.builtinsFromSpec)({
+          spec: input.spec,
+          definition: childDefinition,
+          isChild: true,
+          sandboxAvailable: Boolean(input.sandbox),
+          tracing: input.tracing,
+          logger: input.resolver.logger
+        }),
+        ...extraCapabilities ?? []
+      ];
+      return new import_AgentThread.AgentThread({
+        definition: childDefinition,
+        threadId: params.threadId,
+        title: params.request.name,
+        sandbox: input.sandbox,
+        parent: params.parent,
+        agentInfo: params.request,
+        capabilities,
+        tracing: input.tracing,
+        logger: input.resolver.logger
+      });
+    };
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SessionHandle
+});
+//# sourceMappingURL=SessionHandle.js.map