zeitlich 0.2.40 → 0.2.42

package/src/lib/session/session.integration.test.ts

@@ -895,6 +895,64 @@ describe("createSession integration", () => {
     });
   });
 
+  it("embeds skill resourceContents on synthetic file tree entries via inlineContent", async () => {
+    const { ops } = createMockThreadOps();
+
+    const session = await createSession({
+      agentName: "TestAgent",
+      thread: { mode: "new", threadId: "thread-1" },
+      runAgent: createScriptedRunAgent([{ message: "done", toolCalls: [] }]),
+      threadOps: ops,
+      buildContextMessage: () => "go",
+      virtualFs: { ctx: { projectId: "p" } },
+      virtualFsOps: {
+        resolveFileTree: async () => ({ fileTree: [] }),
+      },
+      skills: [
+        {
+          name: "test-skill",
+          description: "Test",
+          instructions: "Do test",
+          location: "/skills/test-skill",
+          resourceContents: {
+            "references/alpha.md": "# Alpha doc",
+            "references/beta.md": "# Beta doc",
+          },
+        },
+      ],
+      hooks: {
+        onSessionStart: async () => {},
+      },
+    });
+
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "test" },
+    });
+
+    await session.runSession({ stateManager });
+
+    const capturedFileTree = stateManager.getCurrentState().fileTree;
+    expect(Array.isArray(capturedFileTree)).toBe(true);
+    const entries = capturedFileTree as Array<{
+      path: string;
+      inlineContent?: string;
+    }>;
+
+    const alpha = entries.find(
+      (e) => e.path === "/skills/test-skill/references/alpha.md"
+    );
+    const beta = entries.find(
+      (e) => e.path === "/skills/test-skill/references/beta.md"
+    );
+    expect(alpha?.inlineContent).toBe("# Alpha doc");
+    expect(beta?.inlineContent).toBe("# Beta doc");
+
+    expect(stateManager.getCurrentState().inlineFiles).toEqual({
+      "/skills/test-skill/references/alpha.md": "# Alpha doc",
+      "/skills/test-skill/references/beta.md": "# Beta doc",
+    });
+  });
+
   it("does not pass initialFiles when skills have no resourceContents", async () => {
     const { ops } = createMockThreadOps();
     let capturedOptions: Record<string, unknown> | undefined;

package/src/lib/session/session.ts

@@ -1,5 +1,4 @@
 import {
-  condition,
   defineUpdate,
   setHandler,
   ApplicationFailure,
@@ -7,11 +6,14 @@ import {
 } from "@temporalio/workflow";
 import type { SessionExitReason } from "../types";
 import type { SessionConfig, ZeitlichSession } from "./types";
+import { resolveSessionLifecycle } from "./types";
 import type {
+  SandboxCapability,
   SandboxCreateOptions,
   SandboxOps,
   SandboxSnapshot,
 } from "../sandbox/types";
+import type { SandboxInit, SubagentSandboxShutdown } from "../lifecycle";
 import type {
   AgentState,
   AgentStateManager,
@@ -80,42 +82,89 @@ export async function createSession<
   T extends ToolMap,
   M = unknown,
   TContent = string,
+  TInit extends SandboxInit | undefined = undefined,
+  TShutdown extends SubagentSandboxShutdown | undefined = undefined,
 >(
-  config: SessionConfig<T, M, TContent> & { sandboxOps: SandboxOps }
+  config: SessionConfig<T, M, TContent, TInit, TShutdown> & {
+    sandboxOps: NonNullable<
+      SessionConfig<T, M, TContent, TInit, TShutdown>["sandboxOps"]
+    >;
+  }
 ): Promise<ZeitlichSession<M, true>>;
 export async function createSession<
   T extends ToolMap,
   M = unknown,
   TContent = string,
->(config: SessionConfig<T, M, TContent>): Promise<ZeitlichSession<M, false>>;
+  TInit extends SandboxInit | undefined = undefined,
+  TShutdown extends SubagentSandboxShutdown | undefined = undefined,
+>(
+  config: SessionConfig<T, M, TContent, TInit, TShutdown>
+): Promise<ZeitlichSession<M, false>>;
+// Implementation. The overloads above narrow the public contract per
+// `SessionRequiredCaps<TInit, TShutdown>`. The impl signature uses the
+// `never` cap floor — the structurally-narrowest shape that every
+// adapter (including Daytona/Bedrock) satisfies — so each overload's
+// possibly-narrow `sandboxOps` is assignable here. Gated method calls
+// inside the body go through `wideOps()` below, which casts the
+// narrow-typed binding to the wide shape. This is structurally safe:
+// the runtime gates each gated call on `sandboxMode === …` /
+// `resolvedShutdown === …`, and the type system has already ruled out
+// any (mode, shutdown, adapter) cell that would invoke a missing
+// method.
 export async function createSession<
   T extends ToolMap,
   M = unknown,
   TContent = string,
->({
-  agentName,
-  maxTurns = 50,
-  metadata = {},
-  runAgent,
-  threadOps,
-  buildContextMessage,
-  subagents,
-  skills,
-  tools = {} as T,
-  processToolsInParallel = true,
-  hooks = {},
-  appendSystemPrompt = true,
-  waitForInputTimeout = "48h",
-  threadKey,
-  sandboxOps,
-  thread: threadInit,
-  sandbox: sandboxInit,
-  sandboxShutdown = "destroy",
-  onSandboxReady,
-  onSessionExit,
-  virtualFs: virtualFsConfig,
-  virtualFsOps,
-}: SessionConfig<T, M, TContent>): Promise<ZeitlichSession<M, boolean>> {
+>(
+  config: Omit<
+    SessionConfig<T, M, TContent, SandboxInit | undefined, undefined>,
+    "sandboxOps"
+  > & {
+    sandboxOps?: SandboxOps<SandboxCreateOptions, unknown, never>;
+  }
+): Promise<ZeitlichSession<M, boolean>> {
+  const {
+    agentName,
+    maxTurns = 50,
+    metadata = {},
+    runAgent,
+    threadOps,
+    buildContextMessage,
+    subagents,
+    skills,
+    tools = {} as T,
+    processToolsInParallel = true,
+    hooks = {},
+    appendSystemPrompt = true,
+    threadKey,
+    sandboxOps,
+    thread: threadInit,
+    sandbox: sandboxInit,
+    sandboxShutdown,
+    onSandboxReady,
+    onSessionExit,
+    virtualFs: virtualFsConfig,
+    virtualFsOps,
+  } = config;
+
+  /**
+   * The narrow-typed `sandboxOps` binding cast to its wide
+   * (`SandboxCapability`) form. The overload signatures +
+   * `SessionRequiredCaps` SSOT have already ruled out `(sandbox.mode,
+   * sandboxShutdown, adapter)` combinations where a referenced method
+   * would be missing on the proxy, and each gated call site below is
+   * guarded by an `if (sandboxOps)` / `sandboxOps &&` runtime check,
+   * so the cast is structurally safe. `wideOps` returns the wide-cap
+   * shape; callers use it after their own runtime guard establishes
+   * that `sandboxOps` is defined.
+   */
+  type WideSandboxOps = SandboxOps<
+    SandboxCreateOptions,
+    unknown,
+    SandboxCapability
+  >;
+  const wideOps = (): WideSandboxOps =>
+    sandboxOps as unknown as WideSandboxOps;
   // ---------------------------------------------------------------------------
   // Thread resolution
   // ---------------------------------------------------------------------------
@@ -221,7 +270,18 @@ export async function createSession<
       );
 
       // --- Sandbox lifecycle: create, continue, fork, from-snapshot, or inherit ---
-      const sandboxMode = sandboxInit?.mode;
+      // Resolve `sandbox` / `sandboxShutdown` defaults through the SSOT
+      // so the runtime dispatch below and the type-level
+      // `SessionRequiredCaps` cannot disagree on what the documented
+      // defaults are. Both surfaces consult `resolveSessionLifecycle`
+      // (or its type-level equivalent) before checking individual
+      // mode/shutdown values.
+      const lifecycle = resolveSessionLifecycle(
+        sandboxInit,
+        sandboxShutdown
+      );
+      const sandboxMode: SandboxInit["mode"] | undefined = lifecycle.mode;
+      const resolvedShutdown: SubagentSandboxShutdown = lifecycle.shutdown;
       let sandboxId: string | undefined;
       let sandboxOwned = false;
       let baseSnapshot: SandboxSnapshot | undefined;
@@ -250,8 +310,8 @@ export async function createSession<
         }
         sandboxId = (sandboxInit as { mode: "continue"; sandboxId: string })
           .sandboxId;
-        if (sandboxShutdown === "pause-until-parent-close") {
-          await sandboxOps.resumeSandbox(sandboxId);
+        if (resolvedShutdown === "pause-until-parent-close") {
+          await wideOps().resumeSandbox(sandboxId);
         }
         sandboxOwned = true;
       } else if (sandboxMode === "fork") {
@@ -266,7 +326,7 @@ export async function createSession<
           sandboxId: string;
           options?: SandboxCreateOptions;
         };
-        sandboxId = await sandboxOps.forkSandbox(
+        sandboxId = await wideOps().forkSandbox(
           forkInit.sandboxId,
           forkInit.options
         );
@@ -283,7 +343,7 @@ export async function createSession<
           snapshot: SandboxSnapshot;
           options?: SandboxCreateOptions;
         };
-        sandboxId = await sandboxOps.restoreSandbox(
+        sandboxId = await wideOps().restoreSandbox(
           restoreInit.snapshot,
           restoreInit.options
         );
@@ -310,10 +370,10 @@ export async function createSession<
         sandboxId &&
         sandboxOwned &&
         freshlyCreated &&
-        sandboxShutdown === "snapshot" &&
+        resolvedShutdown === "snapshot" &&
         sandboxOps
       ) {
-        baseSnapshot = await sandboxOps.snapshotSandbox(sandboxId);
+        baseSnapshot = await wideOps().snapshotSandbox(sandboxId);
       }
 
       if (sandboxId && sandboxOwned && onSandboxReady) {
@@ -342,12 +402,23 @@ export async function createSession<
                 size: content.length,
                 mtime: new Date().toISOString(),
                 metadata: {},
+                // Carry the content directly on the entry so any handler that
+                // constructs a VirtualFileSystem from `fileTree` can read it
+                // without needing to also wire up `inlineFiles` from state.
+                inlineContent: content,
               })),
             ]
           : result.fileTree;
         stateManager.mergeUpdate({
           fileTree,
           virtualFsCtx: virtualFsConfig.ctx,
+          // `inlineFiles` is still the source of truth at read time:
+          // VirtualFileSystem checks the inlineFiles map first and only
+          // falls through to entry.inlineContent. Embedding the content on
+          // the entry is the migration target so that handlers building a
+          // VirtualFileSystem from `fileTree` alone (without forwarding
+          // `inlineFiles` from state) can read skill resources. Until a
+          // follow-up drops `inlineFiles`, both fields are populated.
           ...(skillFiles && { inlineFiles: skillFiles }),
         } as Partial<AgentState<TState>>);
       }
@@ -516,19 +587,6 @@ export async function createSession<
 
           // Turn committed: fresh id for the next turn.
           assistantId = undefined;
-
-          if (stateManager.getStatus() === "WAITING_FOR_INPUT") {
-            const conditionMet = await condition(
-              () => stateManager.getStatus() === "RUNNING",
-              waitForInputTimeout
-            );
-            if (!conditionMet) {
-              stateManager.cancel();
-              exitReason = "cancelled";
-              await condition(() => false, "2s");
-              break;
-            }
-          }
         }
 
         if (stateManager.getTurns() >= maxTurns && stateManager.isRunning()) {
@@ -575,19 +633,19 @@ export async function createSession<
         await callSessionEnd(exitReason, stateManager.getTurns());
 
         if (sandboxOwned && sandboxId && sandboxOps) {
-          switch (sandboxShutdown) {
+          switch (resolvedShutdown) {
             case "destroy":
               await sandboxOps.destroySandbox(sandboxId);
               break;
             case "pause":
             case "pause-until-parent-close":
-              await sandboxOps.pauseSandbox(sandboxId);
+              await wideOps().pauseSandbox(sandboxId);
               break;
             case "keep":
             case "keep-until-parent-close":
               break;
             case "snapshot":
-              exitSnapshot = await sandboxOps.snapshotSandbox(sandboxId);
+              exitSnapshot = await wideOps().snapshotSandbox(sandboxId);
               await sandboxOps.destroySandbox(sandboxId);
               break;
           }
@@ -618,6 +676,7 @@ export async function createSession<
           ...(sandboxId && { sandboxId }),
           ...(exitSnapshot && { snapshot: exitSnapshot }),
           threadId,
+          usage: stateManager.getTotalUsage(),
         });
       }
 

package/src/lib/session/types.ts

@@ -1,4 +1,3 @@
-import type { Duration } from "@temporalio/common";
 import type { SessionExitReason, ToolResultConfig } from "../types";
 import type {
   ToolMap,
@@ -8,7 +7,12 @@ import type {
 import type { Hooks } from "../hooks/types";
 import type { SubagentConfig } from "../subagent/types";
 import type { Skill } from "../skills/types";
-import type { SandboxOps, SandboxSnapshot } from "../sandbox/types";
+import type {
+  SandboxCapability,
+  SandboxCreateOptions,
+  SandboxOps,
+  SandboxSnapshot,
+} from "../sandbox/types";
 import type { VirtualFsOps } from "../virtual-fs/types";
 import type { RunAgentActivity } from "../model/types";
 import type {
@@ -138,17 +142,171 @@ export type PrefixedThreadOps<TPrefix extends string, TContent = string> = {
   [K in keyof ThreadOps<TContent> as `${TPrefix}${Capitalize<K & string>}`]: ThreadOps<TContent>[K];
 };
 
+// ============================================================================
+// Session sandbox-lifecycle decision table (SSOT)
+//
+// `createSession` (`src/lib/session/session.ts`) dispatches gated
+// sandbox methods based on `(sandbox.mode, sandboxShutdown)`. When a
+// caller omits either field, the session uses the documented defaults
+// (`sandbox: { mode: "new" }` and `sandboxShutdown: "destroy"`),
+// which trigger only base ops (`createSandbox` / `destroySandbox`).
+//
+// Two surfaces have to agree on what gated methods may fire for a
+// given config:
+//
+//   1. The runtime — what the session dispatches per `(mode,
+//      shutdown)` pair.
+//   2. The type level — what caps `sandboxOps` has to advertise.
+//
+// `SessionRequiredCaps<TInit, TShutdown>` is the SSOT for the type
+// level. `resolveSessionLifecycle(init, shutdown)` (in `session.ts`,
+// re-exported below) is the runtime mirror. Adding a new branch to
+// `session.ts` requires extending **both**; the
+// `(sandbox.mode × sandboxShutdown × adapter)` matrix in
+// `src/lib/sandbox/capability-types.test.ts` enforces agreement.
+// ============================================================================
+
+/**
+ * Caps the session's sandbox-init dispatch may invoke for a given
+ * `(mode, shutdown)`. Mirror of `src/lib/session/session.ts:241-313`.
+ *
+ * The conditional branches are written non-distributively (each cap
+ * checked against the input `M` / `S` rather than over a union) so
+ * that the *omitted* case (defaults: M = "new", S = "destroy") flows
+ * through to `never`, not to "I don't know, assume everything."
+ */
+type _SessionInitCaps<M, S> =
+  | (M extends "fork" ? "fork" : never)
+  | (M extends "from-snapshot" ? "restore" : never)
+  | (M extends "continue"
+      ? S extends "pause-until-parent-close"
+        ? "resume"
+        : never
+      : never);
+
+/**
+ * Caps the session's exit dispatch may invoke. `"inherit"` mode keeps
+ * `sandboxOwned = false` so exit-shutdown caps NEVER fire — mirror of
+ * `src/lib/session/session.ts:598-615`.
+ */
+type _SessionExitCaps<M, S> = M extends "inherit"
+  ? never
+  :
+      | (S extends "snapshot" ? "snapshot" : never)
+      | (S extends "pause" | "pause-until-parent-close" ? "pause" : never);
+
+/**
+ * Cap captured on entry for `mode: "new"` + `shutdown: "snapshot"` (the
+ * seeding-base-snapshot path). Mirror of
+ * `src/lib/session/session.ts:316-317`.
+ */
+type _SessionSeedCaps<M, S> = M extends "new"
+  ? S extends "snapshot"
+    ? "snapshot"
+    : never
+  : never;
+
+/**
+ * Resolves an omitted `sandbox` field to the runtime default
+ * `{ mode: "new" }`, and an omitted `sandboxShutdown` field to the
+ * runtime default `"destroy"`. The two `_Resolve…` helpers are the
+ * sole bridge between "user didn't set the field" and the SSOT below
+ * — keeping the defaults out of the conditional table itself.
+ */
+type _ResolveInit<TInit> = [TInit] extends [undefined]
+  ? { mode: "new" }
+  : Exclude<TInit, undefined> extends infer Defined
+    ? // If the user passed `SandboxInit | undefined` (the wide default),
+      // collapse `undefined` to the runtime default.
+      undefined extends TInit
+      ? Defined | { mode: "new" }
+      : Defined
+    : never;
+
+type _ResolveShutdown<TShutdown> = [TShutdown] extends [undefined]
+  ? "destroy"
+  : Exclude<TShutdown, undefined> extends infer Defined
+    ? undefined extends TShutdown
+      ? Defined | "destroy"
+      : Defined
+    : never;
+
+/**
+ * Sandbox capabilities a session actually invokes on its
+ * `sandboxOps`, derived from the literal types of the surrounding
+ * `sandbox` and `sandboxShutdown` fields.
+ *
+ * `TInit` / `TShutdown` default to `undefined` so an un-parameterised
+ * `SessionRequiredCaps` resolves to the caps the runtime *defaults*
+ * (`{ mode: "new" }` + `"destroy"`) actually require — i.e.
+ * `never`. This lets a narrow adapter (e.g. `proxyDaytonaSandboxOps`)
+ * satisfy `sandboxOps?: SandboxOps<…, SessionRequiredCaps<…>>` when
+ * the caller doesn't pin literals, matching what's runtime-safe.
+ *
+ * Pin literals via `as const` or by ascribing `SessionConfig<…, TInit,
+ * TShutdown>` to tighten the requirement on a per-call basis.
+ */
+export type SessionRequiredCaps<
+  TInit extends SandboxInit | undefined = undefined,
+  TShutdown extends SubagentSandboxShutdown | undefined = undefined,
+> = _ResolveInit<TInit> extends infer M
+  ? _ResolveShutdown<TShutdown> extends infer S
+    ? M extends { mode: infer Mode }
+      ? S extends SubagentSandboxShutdown
+        ?
+            | _SessionInitCaps<Mode, S>
+            | _SessionExitCaps<Mode, S>
+            | _SessionSeedCaps<Mode, S>
+        : never
+      : never
+    : never
+  : never;
+
+/**
+ * Runtime mirror of `SessionRequiredCaps`. Returns the names of the
+ * gated `sandboxOps` methods the session will invoke for a given
+ * `(sandboxInit, sandboxShutdown)` pair (after resolving documented
+ * defaults). Mirror of the dispatch in
+ * `src/lib/session/session.ts:241-313` and `:598-615`.
+ *
+ * Both surfaces consult this same table — the `(mode × shutdown ×
+ * adapter)` matrix in `src/lib/sandbox/capability-types.test.ts`
+ * enforces agreement.
+ */
+export function resolveSessionLifecycle(
+  init: SandboxInit | undefined,
+  shutdown: SubagentSandboxShutdown | undefined
+): { mode: SandboxInit["mode"]; shutdown: SubagentSandboxShutdown } {
+  const resolvedInit: SandboxInit = init ?? { mode: "new" };
+  const resolvedShutdown: SubagentSandboxShutdown = shutdown ?? "destroy";
+  return {
+    mode: resolvedInit.mode,
+    shutdown: resolvedShutdown,
+  };
+}
+
 /**
  * Configuration for a Zeitlich agent session.
  *
  * @typeParam T - Tool map
  * @typeParam M - SDK-native message type returned by the model invoker
  * @typeParam TContent - SDK-native content type for human messages (defaults to `string`)
+ * @typeParam TInit - Literal type of `sandbox` (a {@link SandboxInit}
+ *   variant or `undefined`). Defaults to the wide union; pin it via
+ *   `as const` on the call site to narrow the cap requirement on
+ *   `sandboxOps`.
+ * @typeParam TShutdown - Literal type of `sandboxShutdown`. Defaults
+ *   to the wide union; pin it via `as const` on the call site to
+ *   narrow the cap requirement on `sandboxOps`.
  */
 export interface SessionConfig<
   T extends ToolMap,
   M = unknown,
   TContent = string,
+  TInit extends SandboxInit | undefined = SandboxInit | undefined,
+  TShutdown extends
+    | SubagentSandboxShutdown
+    | undefined = SubagentSandboxShutdown | undefined,
 > {
   /** The name of the agent, should be unique within the workflows */
   agentName: string;
@@ -177,8 +335,6 @@ export interface SessionConfig<
    * Returns SDK-native content for the initial human message.
    */
   buildContextMessage: () => TContent | Promise<TContent>;
-  /** How long to wait for input before cancelling the workflow */
-  waitForInputTimeout?: Duration;
 
   // ---------------------------------------------------------------------------
   // Thread lifecycle
@@ -206,8 +362,25 @@ export interface SessionConfig<
   // Sandbox lifecycle
   // ---------------------------------------------------------------------------
 
-  /** Sandbox lifecycle operations (optional — omit for agents that don't need a sandbox) */
-  sandboxOps?: SandboxOps;
+  /**
+   * Sandbox lifecycle operations (optional — omit for agents that don't
+   * need a sandbox).
+   *
+   * The `TCaps` argument is derived from {@link SessionRequiredCaps}
+   * over the literal types of the surrounding `sandbox` and
+   * `sandboxShutdown` fields. With the default wide
+   * `TInit` / `TShutdown`, this resolves to the full
+   * {@link SandboxCapability} union (current behaviour). When the
+   * caller pins those literals via `as const`, the cap requirement
+   * tightens so a narrow adapter (e.g. Daytona's
+   * `SandboxOps<…, never>`) can satisfy combinations that don't need
+   * a gated method.
+   */
+  sandboxOps?: SandboxOps<
+    SandboxCreateOptions,
+    unknown,
+    SessionRequiredCaps<TInit, TShutdown> & SandboxCapability
+  >;
   /**
    * Sandbox initialization strategy.
    *
@@ -218,14 +391,14 @@ export interface SessionConfig<
    *
    * When omitted and `sandboxOps` is provided, defaults to `{ mode: "new" }`.
    */
-  sandbox?: SandboxInit;
+  sandbox?: TInit;
   /**
    * What to do with the sandbox when this session exits.
    *
    * Defaults to `"destroy"` when omitted.
    * Has no effect when the sandbox is inherited (`sandbox.mode === "inherit"`).
    */
-  sandboxShutdown?: SubagentSandboxShutdown;
+  sandboxShutdown?: TShutdown;
   /**
    * Called as soon as the sandbox is created (or resumed/forked), before the
    * agent loop starts. Useful for signalling sandbox readiness to a parent.
@@ -248,6 +421,14 @@ export interface SessionConfig<
     threadId: string;
     sandboxId?: string;
     snapshot?: SandboxSnapshot;
+    usage: {
+      totalInputTokens: number;
+      totalOutputTokens: number;
+      totalCachedWriteTokens: number;
+      totalCachedReadTokens: number;
+      totalReasonTokens: number;
+      turns: number;
+    };
   }) => void;
 
   // ---------------------------------------------------------------------------