zeitlich 0.2.38 → 0.2.40

package/dist/{types-DNr31FzL.d.ts → types-DeQH84C_.d.ts}

@@ -1,8 +1,8 @@
 import { Duration } from '@temporalio/common';
-import { ActivityFunctionWithOptions, QueryDefinition, ActivityInterfaceFor } from '@temporalio/workflow';
+import { ActivityFunctionWithOptions, QueryDefinition, ChildWorkflowOptions, ActivityInterfaceFor } from '@temporalio/workflow';
 import { UpdateDefinition } from '@temporalio/common/lib/interfaces';
 import { z } from 'zod';
-import { a as SandboxFileSystem, F as FileStat, D as DirentEntry, d as SandboxCreateOptions, f as SandboxSnapshot, g as SandboxOps } from './types-yx0LzPGn.js';
+import { f as SandboxSnapshot, a as SandboxFileSystem, F as FileStat, D as DirentEntry, d as SandboxCreateOptions, g as SandboxOps } from './types-yx0LzPGn.js';
 
 /**
  * A tool definition with a name, description, and Zod schema for arguments.
@@ -99,14 +99,16 @@ interface ToolHandlerResponse<TResult = null, TToolResponse = JsonValue> {
      */
     resultAppended?: boolean;
     /**
-     * When true, the session will rewind: any in-flight parallel tool calls
-     * are cancelled, previously appended tool results and the triggering
-     * assistant message are removed from the thread, and the LLM call that
-     * produced the tool calls is retried.
+     * When true, the session will rewind: any in-flight parallel tool
+     * calls are cancelled and the LLM call is retried. The session reuses
+     * the same `assistantMessageId` for the retry; the next `runAgent`
+     * activity truncates the thread from that id on entry, wiping the
+     * triggering assistant message and any tool results already appended
+     * before re-invoking the LLM.
      *
      * The `toolResponse` for a rewinding tool call is ignored (never
-     * appended) since the session truncates the thread back to the
-     * pre-invocation state.
+     * appended) since the thread is rewound back to the pre-assistant
+     * state on the next invocation.
      */
     rewind?: boolean;
     /** Token usage from the tool execution (e.g. child agent invocations) */
@@ -115,6 +117,10 @@ interface ToolHandlerResponse<TResult = null, TToolResponse = JsonValue> {
     threadId?: string;
     /** Sandbox ID created or used by the handler (e.g. child agent sandbox) */
     sandboxId?: string;
+    /** Snapshot captured on exit when `sandboxShutdown === "snapshot"`. */
+    snapshot?: SandboxSnapshot;
+    /** Snapshot captured immediately after sandbox seeding (before the agent loop starts) when `sandbox.mode === "new"` and `sandboxShutdown === "snapshot"`. Intended as a reusable "base" for new threads that want to skip re-seeding. */
+    baseSnapshot?: SandboxSnapshot;
     /** Unvalidated metadata passthrough from handler to hooks (e.g. infrastructure state) */
     metadata?: Record<string, unknown>;
 }
@@ -199,8 +205,9 @@ interface ProcessToolCallsContext {
 }
 /**
  * Signal that a tool handler requested a rewind. Attached to the
- * {@link ProcessToolCallsResult} so the session can roll the thread
- * back to the pre-invocation snapshot and retry the LLM call.
+ * {@link ProcessToolCallsResult} so the session can reuse the same
+ * `assistantMessageId` for the retry; the next `runAgent` activity
+ * then truncates the thread from that id on entry.
  */
 interface RewindSignal {
     toolCallId: string;
@@ -420,6 +427,22 @@ type JsonSerializable<T> = {
  * Full state type combining base state with custom state
  */
 type AgentState<TCustom extends JsonSerializable<TCustom>> = BaseAgentState & TCustom;
+/**
+ * The slice of agent state that is persisted alongside the thread in the
+ * thread store (e.g. Redis) so that a workflow can terminate, store its
+ * state, and be continued or forked later with that state rehydrated.
+ *
+ * Only fields that make sense to carry across workflow runs belong here.
+ * Runtime bookkeeping like status, version, turns, tools, fileTree, token
+ * counters, and the system prompt is intentionally NOT persisted — each run
+ * rebuilds those from scratch.
+ */
+interface PersistedThreadState {
+    /** Task map serialized as entries so it round-trips through JSON. */
+    tasks: [string, WorkflowTask][];
+    /** All custom state fields declared by the caller. */
+    custom: Record<string, JsonValue>;
+}
 /**
  * Agent state manager interface
  * Note: Temporal handlers must be set up in the workflow file due to
@@ -479,6 +502,13 @@ interface AgentStateManager<TCustom extends JsonSerializable<TCustom>> {
     deleteTask(id: string): boolean;
     /** Set the tools (converts Zod schemas to JSON Schema for serialization) */
     setTools(newTools: ToolDefinition[]): void;
+    /**
+     * Snapshot the fields that should survive across workflow runs
+     * (tasks + all custom state). Safe to pass directly to
+     * {@link ThreadOps.saveThreadState}. Rehydrate on the next run with
+     * `mergeUpdate({ tasks: new Map(slice.tasks), ...slice.custom })`.
+     */
+    getPersistedSlice(): PersistedThreadState;
     /** Update the usage */
     updateUsage(usage: TokenUsage): void;
     /** Get the total usage */
@@ -699,6 +729,18 @@ interface RunAgentConfig extends AgentConfig {
     threadKey?: string;
     /** Metadata for the session */
     metadata?: Record<string, unknown>;
+    /**
+     * The id under which the assistant message produced by this call will
+     * be appended. The activity truncates the thread from this id on
+     * entry (no-op on the first attempt) so that:
+     *
+     * - Rewind retries can reuse the same id and the previous (bad)
+     *   assistant + its tool results are wiped before the retry LLM call.
+     * - Resetting the Temporal workflow to this activity restores the
+     *   pre-call thread state: replay re-truncates, re-invokes, and
+     *   appends under the same id.
+     */
+    assistantMessageId: string;
 }
 /**
  * Configuration for appending a tool result
@@ -817,7 +859,9 @@ interface Hooks<T extends ToolMap, TResult = unknown, TContent = unknown> extend
  * - `"new"` — start a fresh thread (optionally specify its ID).
  * - `"continue"` — append directly to an existing thread in-place.
  * - `"fork"` — copy all messages from an existing thread into a new one and
- *   continue there.
+ *   continue there. When the adapter has `onForkPrepareThread` and/or
+ *   `onForkTransform` hooks configured, they are applied once to the forked
+ *   thread before the session starts.
  */
 type ThreadInit = {
     mode: "new";
@@ -889,19 +933,20 @@ type SandboxShutdown = "destroy" | "pause" | "keep" | "snapshot";
  */
 type SubagentSandboxShutdown = SandboxShutdown | "pause-until-parent-close" | "keep-until-parent-close";
 
+/**
+ * Subset of {@link ChildWorkflowOptions} that callers may override when a
+ * subagent is invoked. `workflowId`, `taskQueue`, and `args` are managed by
+ * the subagent handler itself and therefore cannot be set here.
+ *
+ * Configuring `workflowRunTimeout` (or `workflowExecutionTimeout`) is strongly
+ * recommended: it is the only reliable way to guarantee that a child workflow
+ * which fails during initialization or repeatedly fails workflow tasks will
+ * eventually be terminated, allowing the parent's `Subagent` tool call to fail
+ * deterministically instead of hanging forever waiting for a result.
+ */
+type SubagentChildWorkflowOptions = Omit<ChildWorkflowOptions, "workflowId" | "taskQueue" | "args">;
 /** ToolHandlerResponse with threadId required (subagents must always surface their thread) */
-type SubagentHandlerResponse<TResult = null, TToolResponse = JsonValue> = ToolHandlerResponse<TResult, TToolResponse> & {
-    threadId: string;
-    sandboxId?: string;
-    /** Snapshot captured on session exit when `sandboxShutdown === "snapshot"`. */
-    snapshot?: SandboxSnapshot;
-    /**
-     * Snapshot captured immediately after the sandbox was seeded (before the
-     * first agent turn) when `continuation === "snapshot"`. Only set on the
-     * first call that actually created the sandbox.
-     */
-    baseSnapshot?: SandboxSnapshot;
-};
+type SubagentHandlerResponse<TResult = null, TToolResponse = JsonValue> = ToolHandlerResponse<TResult, TToolResponse>;
 /**
  * Raw workflow input fields passed from parent to child workflow.
  * `defineSubagentWorkflow` maps this into `SubagentSessionInput`.
@@ -972,6 +1017,24 @@ interface SubagentConfig<TResult extends z.ZodType = z.ZodType> {
     workflow: SubagentWorkflow<TResult>;
     /** Optional task queue - defaults to parent's queue if not specified */
     taskQueue?: string;
+    /**
+     * Optional child workflow options forwarded to `executeChild` when the
+     * subagent is spawned. Use this to configure timeouts, retry policies, or
+     * parent-close behavior for the child workflow.
+     *
+     * **Recommended:** configure a `workflowRunTimeout` (or
+     * `workflowExecutionTimeout`) so that a child workflow that fails to
+     * initialize — or repeatedly fails workflow tasks without ever reaching a
+     * terminal state — is eventually terminated by the Temporal server. Without
+     * such a timeout, the parent's `Subagent` tool call can hang indefinitely
+     * waiting for the child to finish. When Temporal terminates the child, the
+     * tool call fails with a structured `ChildWorkflowFailure` that the router's
+     * failure hooks can handle just like any other tool error.
+     *
+     * `workflowId`, `taskQueue`, and `args` are managed by the subagent handler
+     * and cannot be overridden here.
+     */
+    workflowOptions?: SubagentChildWorkflowOptions;
     /** Optional Zod schema to validate the child workflow's result. If omitted, result is passed through as-is. */
     resultSchema?: TResult;
     /** Optional context passed to the subagent — a static object or a function evaluated at invocation time */
@@ -1063,8 +1126,26 @@ interface SubagentSessionInput {
     sandbox?: SandboxInit;
     /** Sandbox shutdown policy (default: "destroy") */
     sandboxShutdown?: SubagentSandboxShutdown;
-    /** Called by the session as soon as the sandbox is created, before the agent loop starts. */
-    onSandboxReady?: (sandboxId: string) => void;
+    /**
+     * Called by the session as soon as the sandbox is created, before the
+     * agent loop starts. `baseSnapshot` is populated only when the session
+     * captured a seed snapshot (fresh creation + `sandboxShutdown === "snapshot"`).
+     */
+    onSandboxReady?: (args: {
+        sandboxId: string;
+        baseSnapshot?: SandboxSnapshot;
+    }) => void;
+    /**
+     * Called by the session right before `runSession` returns. Installed by
+     * `defineSubagentWorkflow` to capture sandbox outputs and auto-forward
+     * them to the subagent's final result so user code never has to thread
+     * `sandboxId` / `snapshot` manually.
+     */
+    onSessionExit?: (result: {
+        sandboxId?: string;
+        snapshot?: SandboxSnapshot;
+        threadId: string;
+    }) => void;
 }
 
 /**
@@ -1120,16 +1201,6 @@ interface AgentResponse<M = unknown> {
     message: M;
     rawToolCalls: RawToolCall[];
     usage?: TokenUsage;
-    /**
-     * Number of stored messages in the thread at the moment the LLM was
-     * invoked — i.e. *before* the assistant message is appended. The
-     * session uses this as a rewind snapshot so it can roll the thread
-     * back to this exact state if a tool requests a rewind.
-     *
-     * Adapters compute this for free from the array of stored messages
-     * they load when preparing the payload.
-     */
-    threadLengthAtCall?: number;
 }
 /**
  * Type signature for workflow-specific runAgent activity
@@ -1147,6 +1218,13 @@ interface ModelInvokerConfig {
     agentName: string;
     state: BaseAgentState;
     metadata?: Record<string, unknown>;
+    /**
+     * The id the assistant message produced by this call will be stored
+     * under. Invokers truncate the thread from this id on entry so that
+     * rewind retries and Temporal workflow resets restore the pre-call
+     * state before re-invoking the LLM. See {@link RunAgentConfig}.
+     */
+    assistantMessageId: string;
 }
 /**
  * Generic model invocation contract.
@@ -1178,16 +1256,39 @@ interface ThreadOps<TContent = string> {
     appendAgentMessage(threadId: string, id: string, message: unknown, threadKey?: string): Promise<void>;
     /** Append a system message to the thread */
     appendSystemMessage(threadId: string, id: string, content: unknown, threadKey?: string): Promise<void>;
-    /** Copy all messages from sourceThreadId into a new thread at targetThreadId */
+    /**
+     * Copy all messages AND the persisted state slice (tasks + custom
+     * state) from `sourceThreadId` into a new thread at `targetThreadId`.
+     * Adapters that have `onForkPrepareThread` and/or `onForkTransform`
+     * hooks configured apply them once to the new thread's messages
+     * before returning.
+     */
     forkThread(sourceThreadId: string, targetThreadId: string, threadKey?: string): Promise<void>;
     /**
-     * Truncate the thread back to `length` messages. Used by the session's
-     * rewind flow to roll the thread back before retrying a turn. The
-     * session obtains `length` from `AgentResponse.threadLengthAtCall`,
-     * which the model invoker computes for free from the messages it
-     * loaded before invoking the LLM.
+     * Truncate the thread starting at `messageId`: that message and every
+     * message after it are removed. If `messageId` is not present the call
+     * is a no-op.
+     *
+     * The `runAgent` activity invokes this on entry with the pre-generated
+     * `assistantMessageId`. On the happy path the id is not yet in the
+     * thread and the call is a no-op. On a rewind retry (same assistant
+     * id reused) or a Temporal workflow reset-to-this-activity the id is
+     * present, so the bad assistant + any tool results it produced are
+     * wiped and the call is then replayable.
+     */
+    truncateThread(threadId: string, messageId: string, threadKey?: string): Promise<void>;
+    /**
+     * Load the persisted state slice (tasks + custom state) associated with
+     * the thread, or `null` if none has been saved yet. Called on session
+     * start for `continue`/`fork` threads to rehydrate {@link AgentStateManager}.
      */
-    truncateThread(threadId: string, length: number, threadKey?: string): Promise<void>;
+    loadThreadState(threadId: string, threadKey?: string): Promise<PersistedThreadState | null>;
+    /**
+     * Overwrite the persisted state slice for the thread. Called once from
+     * the session's `finally` block on every exit path so that "finish,
+     * store, continue later" works regardless of exit reason.
+     */
+    saveThreadState(threadId: string, state: PersistedThreadState, threadKey?: string): Promise<void>;
 }
 /**
  * Composes an adapter prefix + workflow scope for activity naming.
@@ -1292,8 +1393,26 @@ interface SessionConfig<T extends ToolMap, M = unknown, TContent = string> {
     /**
      * Called as soon as the sandbox is created (or resumed/forked), before the
      * agent loop starts. Useful for signalling sandbox readiness to a parent.
+     *
+     * `baseSnapshot` is only populated when the sandbox was freshly created
+     * this run and `sandboxShutdown === "snapshot"` — i.e. when the session
+     * captured a seed snapshot intended for reuse.
      */
-    onSandboxReady?: (sandboxId: string) => void;
+    onSandboxReady?: (args: {
+        sandboxId: string;
+        baseSnapshot?: SandboxSnapshot;
+    }) => void;
+    /**
+     * Called right before `runSession` returns, with the session's sandbox
+     * outputs. Useful for callers (e.g. `defineSubagentWorkflow`) that want to
+     * forward these fields to their own return value without requiring user
+     * code to manually thread them through.
+     */
+    onSessionExit?: (result: {
+        threadId: string;
+        sandboxId?: string;
+        snapshot?: SandboxSnapshot;
+    }) => void;
     virtualFsOps?: VirtualFsOps;
     /**
      * Virtual filesystem configuration (optional — independent of sandbox).
@@ -1336,4 +1455,4 @@ interface ZeitlichSession<M = unknown, HasSandbox extends boolean = boolean> {
     }): Promise<SessionResult<M, T, HasSandbox>>;
 }
 
-export { type SerializableToolDefinition as $, type AgentResponse as A, type BaseAgentState as B, type PostToolUseFailureHookResult as C, type PostToolUseHook as D, type PostToolUseHookContext as E, type FileEntryMetadata as F, type PreHumanMessageAppendHook as G, type Hooks as H, type InferToolResults as I, type JsonValue as J, type PreHumanMessageAppendHookContext as K, type PreToolUseHook as L, type ModelInvokerConfig as M, type PreToolUseHookContext as N, type PreToolUseHookResult as O, type PrefixedThreadOps as P, type ProcessToolCallsContext as Q, type RouterContext as R, type ScopedPrefix as S, type ThreadOps as T, type ProcessToolCallsResult as U, type VirtualFsContext as V, type RawToolCall as W, type RewindSignal as X, type RunAgentActivity as Y, type SandboxInit as Z, type SandboxShutdown as _, type ModelInvoker as a, type SessionConfig as a0, type SessionEndHook as a1, type SessionEndHookContext as a2, type SessionExitReason as a3, type SessionResult as a4, type SessionStartHook as a5, type SessionStartHookContext as a6, type SubagentConfig as a7, type SubagentDefinition as a8, type SubagentFnResult as a9, type WorkflowTask as aA, type ZeitlichSession as aB, isTerminalStatus as aC, type ToolRouterOptions as aD, type SubagentHandlerResponse as aa, type SubagentHooks as ab, type SubagentSandboxConfig as ac, type SubagentSandboxShutdown as ad, type SubagentSessionInput as ae, type SubagentWorkflow as af, type SubagentWorkflowInput as ag, type TaskStatus as ah, type ThreadInit as ai, type TokenUsage as aj, type ToolArgs as ak, type ToolCallResult as al, type ToolCallResultUnion as am, type ToolDefinition as an, type ToolHandler as ao, type ToolHooks as ap, type ToolMap as aq, type ToolNames as ar, type ToolResult as as, type ToolRouter as at, type ToolRouterHooks as au, type ToolWithHandler as av, VirtualFileSystem as aw, type VirtualFileTree as ax, type VirtualFsOps as ay, type VirtualFsState as az, type ToolHandlerResponse as b, type ActivityToolHandler as c, type ToolResultConfig as d, type RunAgentConfig as e, type SkillProvider as f, type SkillMetadata as g, type Skill as h, type FileResolver as i, type TreeMutation as j, type PrefixedVirtualFsOps as k, type AgentConfig as l, type AgentFile as m, type AgentState as n, type AgentStateManager as o, type AgentStatus as p, type AppendToolResultFn as q, type FileEntry as r, type JsonPrimitive as s, type JsonSerializable as t, type ParsedToolCall as u, type ParsedToolCallUnion as v, type PostHumanMessageAppendHook as w, type PostHumanMessageAppendHookContext as x, type PostToolUseFailureHook as y, type PostToolUseFailureHookContext as z };
+export { type SandboxShutdown as $, type AgentResponse as A, type BaseAgentState as B, type PostToolUseFailureHookContext as C, type PostToolUseFailureHookResult as D, type PostToolUseHook as E, type FileEntryMetadata as F, type PostToolUseHookContext as G, type Hooks as H, type InferToolResults as I, type JsonValue as J, type PreHumanMessageAppendHook as K, type PreHumanMessageAppendHookContext as L, type ModelInvokerConfig as M, type PreToolUseHook as N, type PreToolUseHookContext as O, type PersistedThreadState as P, type PreToolUseHookResult as Q, type RouterContext as R, type ScopedPrefix as S, type ThreadOps as T, type ProcessToolCallsContext as U, type VirtualFsContext as V, type ProcessToolCallsResult as W, type RawToolCall as X, type RewindSignal as Y, type RunAgentActivity as Z, type SandboxInit as _, type ModelInvoker as a, type SerializableToolDefinition as a0, type SessionConfig as a1, type SessionEndHook as a2, type SessionEndHookContext as a3, type SessionExitReason as a4, type SessionResult as a5, type SessionStartHook as a6, type SessionStartHookContext as a7, type SubagentChildWorkflowOptions as a8, type SubagentConfig as a9, type VirtualFsOps as aA, type VirtualFsState as aB, type WorkflowTask as aC, type ZeitlichSession as aD, isTerminalStatus as aE, type ToolRouterOptions as aF, type SubagentDefinition as aa, type SubagentFnResult as ab, type SubagentHandlerResponse as ac, type SubagentHooks as ad, type SubagentSandboxConfig as ae, type SubagentSandboxShutdown as af, type SubagentSessionInput as ag, type SubagentWorkflow as ah, type SubagentWorkflowInput as ai, type TaskStatus as aj, type ThreadInit as ak, type TokenUsage as al, type ToolArgs as am, type ToolCallResult as an, type ToolCallResultUnion as ao, type ToolDefinition as ap, type ToolHandler as aq, type ToolHooks as ar, type ToolMap as as, type ToolNames as at, type ToolResult as au, type ToolRouter as av, type ToolRouterHooks as aw, type ToolWithHandler as ax, VirtualFileSystem as ay, type VirtualFileTree as az, type PrefixedThreadOps as b, type ToolHandlerResponse as c, type ActivityToolHandler as d, type ToolResultConfig as e, type RunAgentConfig as f, type SkillProvider as g, type SkillMetadata as h, type Skill as i, type FileResolver as j, type TreeMutation as k, type PrefixedVirtualFsOps as l, type AgentConfig as m, type AgentFile as n, type AgentState as o, type AgentStateManager as p, type AgentStatus as q, type AppendToolResultFn as r, type FileEntry as s, type JsonPrimitive as t, type JsonSerializable as u, type ParsedToolCall as v, type ParsedToolCallUnion as w, type PostHumanMessageAppendHook as x, type PostHumanMessageAppendHookContext as y, type PostToolUseFailureHook as z };

package/dist/{workflow-CSCkpwAL.d.ts → workflow-C2MZZj5K.d.ts}

@@ -1,4 +1,4 @@
-import { aq as ToolMap, a0 as SessionConfig, aB as ZeitlichSession, _ as SandboxShutdown, ai as ThreadInit, Z as SandboxInit, t as JsonSerializable, B as BaseAgentState, o as AgentStateManager, aD as ToolRouterOptions, at as ToolRouter, R as RouterContext, J as JsonValue, av as ToolWithHandler, v as ParsedToolCallUnion, ar as ToolNames, a8 as SubagentDefinition, ab as SubagentHooks, ac as SubagentSandboxConfig, a7 as SubagentConfig, ad as SubagentSandboxShutdown, ae as SubagentSessionInput, a9 as SubagentFnResult, a5 as SessionStartHook, a1 as SessionEndHook, D as PostToolUseHook, y as PostToolUseFailureHook, a3 as SessionExitReason, aj as TokenUsage, e as RunAgentConfig, A as AgentResponse, F as FileEntryMetadata, ax as VirtualFileTree, j as TreeMutation, r as FileEntry, ay as VirtualFsOps, g as SkillMetadata, h as Skill, b as ToolHandlerResponse, ao as ToolHandler, aA as WorkflowTask, c as ActivityToolHandler } from './types-DNr31FzL.js';
+import { as as ToolMap, a1 as SessionConfig, aD as ZeitlichSession, $ as SandboxShutdown, ak as ThreadInit, _ as SandboxInit, u as JsonSerializable, B as BaseAgentState, p as AgentStateManager, aF as ToolRouterOptions, av as ToolRouter, R as RouterContext, J as JsonValue, ax as ToolWithHandler, w as ParsedToolCallUnion, at as ToolNames, aa as SubagentDefinition, ad as SubagentHooks, ae as SubagentSandboxConfig, a9 as SubagentConfig, af as SubagentSandboxShutdown, ag as SubagentSessionInput, ab as SubagentFnResult, a6 as SessionStartHook, a2 as SessionEndHook, E as PostToolUseHook, z as PostToolUseFailureHook, a4 as SessionExitReason, al as TokenUsage, f as RunAgentConfig, A as AgentResponse, F as FileEntryMetadata, az as VirtualFileTree, k as TreeMutation, s as FileEntry, aA as VirtualFsOps, h as SkillMetadata, i as Skill, c as ToolHandlerResponse, aq as ToolHandler, aC as WorkflowTask, d as ActivityToolHandler } from './types-DeQH84C_.js';
 import { g as SandboxOps } from './types-yx0LzPGn.js';
 import z$1, { z } from 'zod';
 import { Sinks, proxyActivities } from '@temporalio/workflow';
@@ -97,6 +97,68 @@ declare function defineWorkflow<TInput, TResult>(config: WorkflowConfig, fn: (in
  */
 declare function getShortId(length?: number): string;
 
+/**
+ * Public helpers for zeitlich's Redis thread storage layout.
+ *
+ * These are the exact string-building primitives zeitlich's internal thread
+ * manager uses for every adapter. Downstream consumers that need to read a
+ * persisted thread (for evaluation, observability, admin tooling, etc.)
+ * should use these helpers rather than reconstructing the key layout by
+ * hand — the layout is versioned with this module, so upgrading zeitlich
+ * keeps the consumer in sync.
+ *
+ * The layout is adapter-agnostic: every thread adapter stores messages the
+ * same way.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   getThreadListKey,
+ *   getThreadMetaKey,
+ *   THREAD_TTL_SECONDS,
+ * } from 'zeitlich';
+ *
+ * const listKey = getThreadListKey('messages', threadId);
+ * const metaKey = getThreadMetaKey('messages', threadId);
+ * const ttl = await redis.ttl(listKey); // <= THREAD_TTL_SECONDS
+ * ```
+ */
+/**
+ * TTL (in seconds) applied to every thread list and thread meta key that
+ * zeitlich's {@link createThreadManager} writes. Exposed so downstream
+ * consumers can size their Redis retention / query windows to match.
+ *
+ * Current value: 90 days.
+ */
+declare const THREAD_TTL_SECONDS: number;
+/**
+ * Build the Redis list key that holds a thread's serialized messages.
+ *
+ * Mirrors the exact key used internally by zeitlich's thread manager,
+ * so a consumer calling `redis.lrange(getThreadListKey(key, id), 0, -1)`
+ * sees the same data the writer wrote.
+ *
+ * @param threadKey - Thread key (defaults to `"messages"` inside the
+ *                    thread manager, but downstream adapters may pass
+ *                    their own value).
+ * @param threadId  - Thread id as provided to the thread manager.
+ */
+declare function getThreadListKey(threadKey: string, threadId: string): string;
+/**
+ * Build the Redis key that stores a thread's existence marker / metadata.
+ *
+ * Zeitlich treats the presence of this key as "thread has been
+ * initialized"; append/load/fork/truncate operations fail when it is
+ * missing. Consumers can use it as a cheap existence probe without
+ * scanning the message list.
+ *
+ * @param threadKey - Thread key (defaults to `"messages"` inside the
+ *                    thread manager, but downstream adapters may pass
+ *                    their own value).
+ * @param threadId  - Thread id as provided to the thread manager.
+ */
+declare function getThreadMetaKey(threadKey: string, threadId: string): string;
+
 /**
  * Creates an agent state manager for tracking workflow state.
  * Automatically registers Temporal query and update handlers for the agent.
@@ -194,6 +256,22 @@ type SubagentArgs = {
     threadId?: string | null;
 };
 
+/**
+ * Default `workflowRunTimeout` applied to every subagent child workflow
+ * unless overridden via `SubagentConfig.workflowOptions.workflowRunTimeout`.
+ *
+ * Chosen as a safety bound: Temporal retries failing workflow tasks forever
+ * by default, so a child that fails to initialize (e.g. missing workflow
+ * export) or is otherwise broken will never reach a terminal state on its
+ * own and the parent's `Subagent` tool call would hang indefinitely. A
+ * bounded run timeout guarantees the child is eventually terminated and the
+ * parent receives a structured `ChildWorkflowFailure` it can surface to the
+ * agent. One hour is generous enough for realistic agent sessions while
+ * still catching hangs; agents that legitimately need longer should set an
+ * explicit `workflowOptions.workflowRunTimeout`.
+ */
+declare const DEFAULT_SUBAGENT_WORKFLOW_RUN_TIMEOUT = "1h";
+
 /**
  * Creates a `SubagentConfig` from a `SubagentDefinition` (returned by `defineSubagentWorkflow`).
  * Metadata (name, description, resultSchema) is read from the definition — only configure
@@ -264,6 +342,8 @@ declare function defineSubagent<TResult extends z.ZodType = z.ZodType, TContext
  *     });
  *
  *     const { finalMessage, threadId } = await session.runSession({ stateManager });
+ *     // `sandboxId`, `snapshot`, and `baseSnapshot` are auto-forwarded
+ *     // from the session — no need to thread them through manually.
  *     return { toolResponse: finalMessage ?? "No response", data: null, threadId };
  *   },
  * );
@@ -775,4 +855,4 @@ declare const createAskUserQuestionHandler: () => ActivityToolHandler<AskUserQue
     }[];
 }>;
 
-export { proxyRunAgent as $, type AskUserQuestionArgs as A, type BashArgs as B, createTaskListHandler as C, createTaskUpdateHandler as D, createToolRouter as E, type FileEditArgs as F, type GlobArgs as G, defineSubagent as H, defineSubagentWorkflow as I, defineTool as J, defineWorkflow as K, editTool as L, filesWithMimeType as M, formatVirtualFileTree as N, type ObservabilityHooks as O, getShortId as P, globTool as Q, type ReadSkillArgs as R, type SessionEndedEvent as S, type TaskCreateArgs as T, grepTool as U, hasDirectory as V, type WorkflowConfig as W, hasFileWithMimeType as X, hasNoOtherToolCalls as Y, type ZeitlichObservabilitySinks as Z, parseSkillFile as _, type FileReadArgs as a, proxyVirtualFsOps as a0, readFileTool as a1, taskCreateTool as a2, taskGetTool as a3, taskListTool as a4, taskUpdateTool as a5, writeFileTool as a6, type FileWriteArgs as b, type FileTreeAccessor as c, type GrepArgs as d, type SessionStartedEvent as e, type SubagentArgs as f, type TaskGetArgs as g, type TaskListArgs as h, type TaskUpdateArgs as i, type ToolExecutedEvent as j, type TurnCompletedEvent as k, type WorkflowInput as l, type WorkflowSessionInput as m, applyVirtualTreeMutations as n, askUserQuestionTool as o, bashTool as p, composeHooks as q, createAgentStateManager as r, createAskUserQuestionHandler as s, createBashToolDescription as t, createObservabilityHooks as u, createReadSkillHandler as v, createReadSkillTool as w, createSession as x, createTaskCreateHandler as y, createTaskGetHandler as z };
+export { hasDirectory as $, type AskUserQuestionArgs as A, type BashArgs as B, createTaskGetHandler as C, DEFAULT_SUBAGENT_WORKFLOW_RUN_TIMEOUT as D, createTaskListHandler as E, type FileEditArgs as F, type GlobArgs as G, createTaskUpdateHandler as H, createToolRouter as I, defineSubagent as J, defineSubagentWorkflow as K, defineTool as L, defineWorkflow as M, editTool as N, type ObservabilityHooks as O, filesWithMimeType as P, formatVirtualFileTree as Q, type ReadSkillArgs as R, type SessionEndedEvent as S, THREAD_TTL_SECONDS as T, getShortId as U, getThreadListKey as V, type WorkflowConfig as W, getThreadMetaKey as X, globTool as Y, type ZeitlichObservabilitySinks as Z, grepTool as _, type FileReadArgs as a, hasFileWithMimeType as a0, hasNoOtherToolCalls as a1, parseSkillFile as a2, proxyRunAgent as a3, proxyVirtualFsOps as a4, readFileTool as a5, taskCreateTool as a6, taskGetTool as a7, taskListTool as a8, taskUpdateTool as a9, writeFileTool as aa, type FileWriteArgs as b, type FileTreeAccessor as c, type GrepArgs as d, type SessionStartedEvent as e, type SubagentArgs as f, type TaskCreateArgs as g, type TaskGetArgs as h, type TaskListArgs as i, type TaskUpdateArgs as j, type ToolExecutedEvent as k, type TurnCompletedEvent as l, type WorkflowInput as m, type WorkflowSessionInput as n, applyVirtualTreeMutations as o, askUserQuestionTool as p, bashTool as q, composeHooks as r, createAgentStateManager as s, createAskUserQuestionHandler as t, createBashToolDescription as u, createObservabilityHooks as v, createReadSkillHandler as w, createReadSkillTool as x, createSession as y, createTaskCreateHandler as z };

package/dist/{workflow-DuvMZ8Vm.d.cts → workflow-DhplIN65.d.cts}

@@ -1,4 +1,4 @@
-import { aq as ToolMap, a0 as SessionConfig, aB as ZeitlichSession, _ as SandboxShutdown, ai as ThreadInit, Z as SandboxInit, t as JsonSerializable, B as BaseAgentState, o as AgentStateManager, aD as ToolRouterOptions, at as ToolRouter, R as RouterContext, J as JsonValue, av as ToolWithHandler, v as ParsedToolCallUnion, ar as ToolNames, a8 as SubagentDefinition, ab as SubagentHooks, ac as SubagentSandboxConfig, a7 as SubagentConfig, ad as SubagentSandboxShutdown, ae as SubagentSessionInput, a9 as SubagentFnResult, a5 as SessionStartHook, a1 as SessionEndHook, D as PostToolUseHook, y as PostToolUseFailureHook, a3 as SessionExitReason, aj as TokenUsage, e as RunAgentConfig, A as AgentResponse, F as FileEntryMetadata, ax as VirtualFileTree, j as TreeMutation, r as FileEntry, ay as VirtualFsOps, g as SkillMetadata, h as Skill, b as ToolHandlerResponse, ao as ToolHandler, aA as WorkflowTask, c as ActivityToolHandler } from './types-C06FwR96.cjs';
+import { as as ToolMap, a1 as SessionConfig, aD as ZeitlichSession, $ as SandboxShutdown, ak as ThreadInit, _ as SandboxInit, u as JsonSerializable, B as BaseAgentState, p as AgentStateManager, aF as ToolRouterOptions, av as ToolRouter, R as RouterContext, J as JsonValue, ax as ToolWithHandler, w as ParsedToolCallUnion, at as ToolNames, aa as SubagentDefinition, ad as SubagentHooks, ae as SubagentSandboxConfig, a9 as SubagentConfig, af as SubagentSandboxShutdown, ag as SubagentSessionInput, ab as SubagentFnResult, a6 as SessionStartHook, a2 as SessionEndHook, E as PostToolUseHook, z as PostToolUseFailureHook, a4 as SessionExitReason, al as TokenUsage, f as RunAgentConfig, A as AgentResponse, F as FileEntryMetadata, az as VirtualFileTree, k as TreeMutation, s as FileEntry, aA as VirtualFsOps, h as SkillMetadata, i as Skill, c as ToolHandlerResponse, aq as ToolHandler, aC as WorkflowTask, d as ActivityToolHandler } from './types-Cn2r3ol3.cjs';
 import { g as SandboxOps } from './types-yx0LzPGn.cjs';
 import z$1, { z } from 'zod';
 import { Sinks, proxyActivities } from '@temporalio/workflow';
@@ -97,6 +97,68 @@ declare function defineWorkflow<TInput, TResult>(config: WorkflowConfig, fn: (in
  */
 declare function getShortId(length?: number): string;
 
+/**
+ * Public helpers for zeitlich's Redis thread storage layout.
+ *
+ * These are the exact string-building primitives zeitlich's internal thread
+ * manager uses for every adapter. Downstream consumers that need to read a
+ * persisted thread (for evaluation, observability, admin tooling, etc.)
+ * should use these helpers rather than reconstructing the key layout by
+ * hand — the layout is versioned with this module, so upgrading zeitlich
+ * keeps the consumer in sync.
+ *
+ * The layout is adapter-agnostic: every thread adapter stores messages the
+ * same way.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   getThreadListKey,
+ *   getThreadMetaKey,
+ *   THREAD_TTL_SECONDS,
+ * } from 'zeitlich';
+ *
+ * const listKey = getThreadListKey('messages', threadId);
+ * const metaKey = getThreadMetaKey('messages', threadId);
+ * const ttl = await redis.ttl(listKey); // <= THREAD_TTL_SECONDS
+ * ```
+ */
+/**
+ * TTL (in seconds) applied to every thread list and thread meta key that
+ * zeitlich's {@link createThreadManager} writes. Exposed so downstream
+ * consumers can size their Redis retention / query windows to match.
+ *
+ * Current value: 90 days.
+ */
+declare const THREAD_TTL_SECONDS: number;
+/**
+ * Build the Redis list key that holds a thread's serialized messages.
+ *
+ * Mirrors the exact key used internally by zeitlich's thread manager,
+ * so a consumer calling `redis.lrange(getThreadListKey(key, id), 0, -1)`
+ * sees the same data the writer wrote.
+ *
+ * @param threadKey - Thread key (defaults to `"messages"` inside the
+ *                    thread manager, but downstream adapters may pass
+ *                    their own value).
+ * @param threadId  - Thread id as provided to the thread manager.
+ */
+declare function getThreadListKey(threadKey: string, threadId: string): string;
+/**
+ * Build the Redis key that stores a thread's existence marker / metadata.
+ *
+ * Zeitlich treats the presence of this key as "thread has been
+ * initialized"; append/load/fork/truncate operations fail when it is
+ * missing. Consumers can use it as a cheap existence probe without
+ * scanning the message list.
+ *
+ * @param threadKey - Thread key (defaults to `"messages"` inside the
+ *                    thread manager, but downstream adapters may pass
+ *                    their own value).
+ * @param threadId  - Thread id as provided to the thread manager.
+ */
+declare function getThreadMetaKey(threadKey: string, threadId: string): string;
+
 /**
  * Creates an agent state manager for tracking workflow state.
  * Automatically registers Temporal query and update handlers for the agent.
@@ -194,6 +256,22 @@ type SubagentArgs = {
     threadId?: string | null;
 };
 
+/**
+ * Default `workflowRunTimeout` applied to every subagent child workflow
+ * unless overridden via `SubagentConfig.workflowOptions.workflowRunTimeout`.
+ *
+ * Chosen as a safety bound: Temporal retries failing workflow tasks forever
+ * by default, so a child that fails to initialize (e.g. missing workflow
+ * export) or is otherwise broken will never reach a terminal state on its
+ * own and the parent's `Subagent` tool call would hang indefinitely. A
+ * bounded run timeout guarantees the child is eventually terminated and the
+ * parent receives a structured `ChildWorkflowFailure` it can surface to the
+ * agent. One hour is generous enough for realistic agent sessions while
+ * still catching hangs; agents that legitimately need longer should set an
+ * explicit `workflowOptions.workflowRunTimeout`.
+ */
+declare const DEFAULT_SUBAGENT_WORKFLOW_RUN_TIMEOUT = "1h";
+
 /**
  * Creates a `SubagentConfig` from a `SubagentDefinition` (returned by `defineSubagentWorkflow`).
  * Metadata (name, description, resultSchema) is read from the definition — only configure
@@ -264,6 +342,8 @@ declare function defineSubagent<TResult extends z.ZodType = z.ZodType, TContext
  *     });
  *
  *     const { finalMessage, threadId } = await session.runSession({ stateManager });
+ *     // `sandboxId`, `snapshot`, and `baseSnapshot` are auto-forwarded
+ *     // from the session — no need to thread them through manually.
  *     return { toolResponse: finalMessage ?? "No response", data: null, threadId };
  *   },
  * );
@@ -775,4 +855,4 @@ declare const createAskUserQuestionHandler: () => ActivityToolHandler<AskUserQue
     }[];
 }>;
 
-export { proxyRunAgent as $, type AskUserQuestionArgs as A, type BashArgs as B, createTaskListHandler as C, createTaskUpdateHandler as D, createToolRouter as E, type FileEditArgs as F, type GlobArgs as G, defineSubagent as H, defineSubagentWorkflow as I, defineTool as J, defineWorkflow as K, editTool as L, filesWithMimeType as M, formatVirtualFileTree as N, type ObservabilityHooks as O, getShortId as P, globTool as Q, type ReadSkillArgs as R, type SessionEndedEvent as S, type TaskCreateArgs as T, grepTool as U, hasDirectory as V, type WorkflowConfig as W, hasFileWithMimeType as X, hasNoOtherToolCalls as Y, type ZeitlichObservabilitySinks as Z, parseSkillFile as _, type FileReadArgs as a, proxyVirtualFsOps as a0, readFileTool as a1, taskCreateTool as a2, taskGetTool as a3, taskListTool as a4, taskUpdateTool as a5, writeFileTool as a6, type FileWriteArgs as b, type FileTreeAccessor as c, type GrepArgs as d, type SessionStartedEvent as e, type SubagentArgs as f, type TaskGetArgs as g, type TaskListArgs as h, type TaskUpdateArgs as i, type ToolExecutedEvent as j, type TurnCompletedEvent as k, type WorkflowInput as l, type WorkflowSessionInput as m, applyVirtualTreeMutations as n, askUserQuestionTool as o, bashTool as p, composeHooks as q, createAgentStateManager as r, createAskUserQuestionHandler as s, createBashToolDescription as t, createObservabilityHooks as u, createReadSkillHandler as v, createReadSkillTool as w, createSession as x, createTaskCreateHandler as y, createTaskGetHandler as z };
+export { hasDirectory as $, type AskUserQuestionArgs as A, type BashArgs as B, createTaskGetHandler as C, DEFAULT_SUBAGENT_WORKFLOW_RUN_TIMEOUT as D, createTaskListHandler as E, type FileEditArgs as F, type GlobArgs as G, createTaskUpdateHandler as H, createToolRouter as I, defineSubagent as J, defineSubagentWorkflow as K, defineTool as L, defineWorkflow as M, editTool as N, type ObservabilityHooks as O, filesWithMimeType as P, formatVirtualFileTree as Q, type ReadSkillArgs as R, type SessionEndedEvent as S, THREAD_TTL_SECONDS as T, getShortId as U, getThreadListKey as V, type WorkflowConfig as W, getThreadMetaKey as X, globTool as Y, type ZeitlichObservabilitySinks as Z, grepTool as _, type FileReadArgs as a, hasFileWithMimeType as a0, hasNoOtherToolCalls as a1, parseSkillFile as a2, proxyRunAgent as a3, proxyVirtualFsOps as a4, readFileTool as a5, taskCreateTool as a6, taskGetTool as a7, taskListTool as a8, taskUpdateTool as a9, writeFileTool as aa, type FileWriteArgs as b, type FileTreeAccessor as c, type GrepArgs as d, type SessionStartedEvent as e, type SubagentArgs as f, type TaskCreateArgs as g, type TaskGetArgs as h, type TaskListArgs as i, type TaskUpdateArgs as j, type ToolExecutedEvent as k, type TurnCompletedEvent as l, type WorkflowInput as m, type WorkflowSessionInput as n, applyVirtualTreeMutations as o, askUserQuestionTool as p, bashTool as q, composeHooks as r, createAgentStateManager as s, createAskUserQuestionHandler as t, createBashToolDescription as u, createObservabilityHooks as v, createReadSkillHandler as w, createReadSkillTool as x, createSession as y, createTaskCreateHandler as z };