zeitlich 0.2.37 → 0.2.39

package/dist/{workflow-CjXHbZZc.d.ts → workflow-Bmf9EtDW.d.ts}

@@ -1,5 +1,5 @@
-import { ao as ToolMap, _ as SessionConfig, az as ZeitlichSession, Y as SandboxShutdown, ag as ThreadInit, X as SandboxInit, t as JsonSerializable, B as BaseAgentState, o as AgentStateManager, aB as ToolRouterOptions, ar as ToolRouter, R as RouterContext, J as JsonValue, at as ToolWithHandler, v as ParsedToolCallUnion, ap as ToolNames, a6 as SubagentDefinition, a9 as SubagentHooks, aa as SubagentSandboxConfig, a5 as SubagentConfig, ab as SubagentSandboxShutdown, ac as SubagentSessionInput, a7 as SubagentFnResult, a3 as SessionStartHook, $ as SessionEndHook, D as PostToolUseHook, y as PostToolUseFailureHook, a1 as SessionExitReason, ah as TokenUsage, e as RunAgentConfig, A as AgentResponse, F as FileEntryMetadata, av as VirtualFileTree, j as TreeMutation, r as FileEntry, aw as VirtualFsOps, g as SkillMetadata, h as Skill, b as ToolHandlerResponse, am as ToolHandler, ay as WorkflowTask, c as ActivityToolHandler } from './types-CPKDl-y_.js';
-import { g as SandboxOps } from './types-tQL9njTu.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-Dt8-HBBT.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-Do_lzJpT.d.cts → workflow-Bx9utBwb.d.cts}

@@ -1,5 +1,5 @@
-import { ao as ToolMap, _ as SessionConfig, az as ZeitlichSession, Y as SandboxShutdown, ag as ThreadInit, X as SandboxInit, t as JsonSerializable, B as BaseAgentState, o as AgentStateManager, aB as ToolRouterOptions, ar as ToolRouter, R as RouterContext, J as JsonValue, at as ToolWithHandler, v as ParsedToolCallUnion, ap as ToolNames, a6 as SubagentDefinition, a9 as SubagentHooks, aa as SubagentSandboxConfig, a5 as SubagentConfig, ab as SubagentSandboxShutdown, ac as SubagentSessionInput, a7 as SubagentFnResult, a3 as SessionStartHook, $ as SessionEndHook, D as PostToolUseHook, y as PostToolUseFailureHook, a1 as SessionExitReason, ah as TokenUsage, e as RunAgentConfig, A as AgentResponse, F as FileEntryMetadata, av as VirtualFileTree, j as TreeMutation, r as FileEntry, aw as VirtualFsOps, g as SkillMetadata, h as Skill, b as ToolHandlerResponse, am as ToolHandler, ay as WorkflowTask, c as ActivityToolHandler } from './types-BO7Yju20.cjs';
-import { g as SandboxOps } from './types-tQL9njTu.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-Bcbiq8iv.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 };