zeitlich 0.2.13 → 0.2.15

package/src/lib/subagent/tool.ts

@@ -0,0 +1,80 @@
+import z from "zod";
+import type { SubagentConfig } from "./types";
+
+export const SUBAGENT_TOOL_NAME = "Subagent" as const;
+
+function buildSubagentDescription(subagents: SubagentConfig[]): string {
+  const subagentList = subagents
+    .map((s) => {
+      const continuation = s.allowThreadContinuation
+        ? "\n*(Supports thread continuation — pass a threadId to resume a previous conversation)*"
+        : "";
+      return `## ${s.agentName}\n${s.description}${continuation}`;
+    })
+    .join("\n\n");
+
+  return `The ${SUBAGENT_TOOL_NAME} tool launches specialized agents (subagents) that autonomously handle complex work. Each agent type has specific capabilities and tools available to it.
+
+# Available subagents:
+${subagentList}
+`;
+}
+
+/**
+ * Creates a Subagent tool configured with the available subagents.
+ *
+ * @param subagents - Array of subagent configurations (must have at least one)
+ * @returns A tool definition with dynamic schema based on available subagents
+ */
+export function createSubagentTool<T extends SubagentConfig[]>(
+  subagents: T
+): {
+  readonly name: typeof SUBAGENT_TOOL_NAME;
+  readonly description: string;
+  readonly schema: z.ZodObject<z.ZodRawShape>;
+} {
+  if (subagents.length === 0) {
+    throw new Error("createSubagentTool requires at least one subagent");
+  }
+
+  const names = subagents.map((s) => s.agentName);
+  const hasThreadContinuation = subagents.some(
+    (s) => s.allowThreadContinuation
+  );
+
+  const baseFields = {
+    subagent: z.enum(names).describe("The type of subagent to launch"),
+    description: z
+      .string()
+      .describe("A short (3-5 word) description of the task"),
+    prompt: z.string().describe("The task for the agent to perform"),
+  };
+
+  const schema = hasThreadContinuation
+    ? z.object({
+        ...baseFields,
+        threadId: z
+          .string()
+          .nullable()
+          .describe(
+            "Thread ID to continue an existing conversation, or null to start a new one"
+          ),
+      })
+    : z.object(baseFields);
+
+  return {
+    name: SUBAGENT_TOOL_NAME,
+    description: buildSubagentDescription(subagents),
+    schema,
+  } as const;
+}
+
+/**
+ * Subagent tool args type (when subagent names are not known at compile time)
+ */
+export type SubagentArgs = {
+  subagent: string;
+  description: string;
+  prompt: string;
+  threadId?: string | null;
+};

package/src/lib/subagent/types.ts

@@ -0,0 +1,92 @@
+import type { z } from "zod";
+import type {
+  ToolHandlerResponse,
+  PreToolUseHookResult,
+  PostToolUseFailureHookResult,
+} from "../tool-router/types";
+
+/** ToolHandlerResponse with threadId required (subagents must always surface their thread) */
+export type SubagentHandlerResponse<TResult = null> =
+  ToolHandlerResponse<TResult> & { threadId: string };
+
+export type SubagentWorkflow<TResult extends z.ZodType = z.ZodType> = (
+  input: SubagentInput
+) => Promise<SubagentHandlerResponse<z.infer<TResult> | null>>;
+
+/** Infer the z.infer'd result type from a SubagentConfig, or null if no schema */
+export type InferSubagentResult<T extends SubagentConfig> =
+  T extends SubagentConfig<infer S> ? z.infer<S> : null;
+
+/**
+ * Configuration for a subagent that can be spawned by the parent workflow.
+ *
+ * @template TResult - Zod schema type for validating the child workflow's result
+ */
+export interface SubagentConfig<TResult extends z.ZodType = z.ZodType> {
+  /** Identifier used in Task tool's subagent parameter */
+  agentName: string;
+  /** Description shown to the parent agent explaining what this subagent does */
+  description: string;
+  /** Whether this subagent is available (default: true). Disabled subagents are excluded from the Subagent tool. */
+  enabled?: boolean;
+  /** Temporal workflow function or type name (used with executeChild) */
+  workflow: string | SubagentWorkflow<TResult>;
+  /** Optional task queue - defaults to parent's queue if not specified */
+  taskQueue?: string;
+  /** Optional Zod schema to validate the child workflow's result. If omitted, result is passed through as-is. */
+  resultSchema?: TResult;
+  /** Optional static context passed to the subagent on every invocation */
+  context?: Record<string, unknown>;
+  /** Allow the parent agent to pass a threadId for this subagent to continue (default: false) */
+  allowThreadContinuation?: boolean;
+  /** Per-subagent lifecycle hooks */
+  hooks?: SubagentHooks;
+  /**
+   * Sandbox strategy for this subagent.
+   * - `'inherit'` (default): reuse the parent's sandbox (shared filesystem/exec).
+   * - `'own'`: the child creates and owns its own sandbox.
+   */
+  sandbox?: "inherit" | "own";
+}
+
+/**
+ * Per-subagent lifecycle hooks - defined on a SubagentConfig.
+ * Runs in addition to global hooks (global pre → subagent pre → execute → subagent post → global post).
+ */
+export interface SubagentHooks<TArgs = unknown, TResult = unknown> {
+  /** Called before this subagent executes - can skip or modify args */
+  onPreExecution?: (ctx: {
+    args: TArgs;
+    threadId: string;
+    turn: number;
+  }) => PreToolUseHookResult | Promise<PreToolUseHookResult>;
+  /** Called after this subagent executes successfully */
+  onPostExecution?: (ctx: {
+    args: TArgs;
+    result: TResult;
+    threadId: string;
+    turn: number;
+    durationMs: number;
+  }) => void | Promise<void>;
+  /** Called when this subagent execution fails */
+  onExecutionFailure?: (ctx: {
+    args: TArgs;
+    error: Error;
+    threadId: string;
+    turn: number;
+  }) => PostToolUseFailureHookResult | Promise<PostToolUseFailureHookResult>;
+}
+
+/**
+ * Input passed to child workflows when spawned as subagents
+ */
+export interface SubagentInput {
+  /** The prompt/task from the parent agent */
+  prompt: string;
+  /** Optional context parameters passed from the parent agent */
+  context?: Record<string, unknown>;
+  /** When set, the subagent should continue this thread instead of starting a new one */
+  previousThreadId?: string;
+  /** Sandbox ID inherited from the parent agent (when SubagentConfig.sandbox is 'inherit') */
+  sandboxId?: string;
+}

package/src/lib/thread/index.ts

@@ -0,0 +1,7 @@
+export { createThreadManager } from "./manager";
+export { getShortId } from "./id";
+
+export type {
+  ThreadManagerConfig,
+  BaseThreadManager,
+} from "./types";

package/src/lib/{thread-manager.ts → thread/manager.ts}

@@ -1,4 +1,7 @@
-import type Redis from "ioredis";
+import type {
+  ThreadManagerConfig,
+  BaseThreadManager,
+} from "./types";
 
 const THREAD_TTL_SECONDS = 60 * 60 * 24 * 90; // 90 days
 
@@ -27,38 +30,6 @@ function getThreadKey(threadId: string, key: string): string {
   return `thread:${threadId}:${key}`;
 }
 
-export interface ThreadManagerConfig<T> {
-  redis: Redis;
-  threadId: string;
-  /** Thread key, defaults to 'messages' */
-  key?: string;
-  /** Custom serializer, defaults to JSON.stringify */
-  serialize?: (message: T) => string;
-  /** Custom deserializer, defaults to JSON.parse */
-  deserialize?: (raw: string) => T;
-  /**
-   * Extract a unique id from a message for idempotent appends.
-   * When provided, `append` uses an atomic Lua script to skip duplicate writes.
-   */
-  idOf?: (message: T) => string;
-}
-
-/** Generic thread manager for any message type */
-export interface BaseThreadManager<T> {
-  /** Initialize an empty thread */
-  initialize(): Promise<void>;
-  /** Load all messages from the thread */
-  load(): Promise<T[]>;
-  /**
-   * Append messages to the thread.
-   * When `idOf` is configured, appends are idempotent — retries with the
-   * same message ids are atomically skipped via a Redis Lua script.
-   */
-  append(messages: T[]): Promise<void>;
-  /** Delete the thread */
-  delete(): Promise<void>;
-}
-
 /**
  * Creates a generic thread manager for handling conversation state in Redis.
  * Framework-agnostic — works with any serializable message type.
@@ -117,6 +88,22 @@ export function createThreadManager<T>(
       }
     },
 
+    async fork(newThreadId: string): Promise<BaseThreadManager<T>> {
+      await assertThreadExists();
+      const data = await redis.lrange(redisKey, 0, -1);
+      const forked = createThreadManager({
+        ...config,
+        threadId: newThreadId,
+      });
+      await forked.initialize();
+      if (data.length > 0) {
+        const newKey = getThreadKey(newThreadId, key);
+        await redis.rpush(newKey, ...data);
+        await redis.expire(newKey, THREAD_TTL_SECONDS);
+      }
+      return forked;
+    },
+
     async delete(): Promise<void> {
       await redis.del(redisKey, metaKey);
     },

package/src/lib/thread/types.ts

@@ -0,0 +1,39 @@
+import type Redis from "ioredis";
+
+export interface ThreadManagerConfig<T> {
+  redis: Redis;
+  threadId: string;
+  /** Thread key, defaults to 'messages' */
+  key?: string;
+  /** Custom serializer, defaults to JSON.stringify */
+  serialize?: (message: T) => string;
+  /** Custom deserializer, defaults to JSON.parse */
+  deserialize?: (raw: string) => T;
+  /**
+   * Extract a unique id from a message for idempotent appends.
+   * When provided, `append` uses an atomic Lua script to skip duplicate writes.
+   */
+  idOf?: (message: T) => string;
+}
+
+/** Generic thread manager for any message type */
+export interface BaseThreadManager<T> {
+  /** Initialize an empty thread */
+  initialize(): Promise<void>;
+  /** Load all messages from the thread */
+  load(): Promise<T[]>;
+  /**
+   * Append messages to the thread.
+   * When `idOf` is configured, appends are idempotent — retries with the
+   * same message ids are atomically skipped via a Redis Lua script.
+   */
+  append(messages: T[]): Promise<void>;
+  /**
+   * Copy all messages from this thread into a new thread, leaving the
+   * original intact. Returns the new thread's manager. Safe for parallel
+   * forks — each call creates an independent copy.
+   */
+  fork(newThreadId: string): Promise<BaseThreadManager<T>>;
+  /** Delete the thread */
+  delete(): Promise<void>;
+}

package/src/lib/tool-router/auto-append.ts

@@ -0,0 +1,55 @@
+import type { ToolResultConfig } from "../types";
+import type { ActivityToolHandler, RouterContext } from "./types";
+
+/**
+ * Wraps a tool handler to automatically append its result directly to the
+ * thread and sets `resultAppended: true` on the response.
+ *
+ * Use this for tools whose responses may exceed Temporal's activity payload
+ * limit. The wrapper appends to the thread inside the activity (where Redis
+ * is available), then replaces `toolResponse` with an empty string so the
+ * large payload never travels through the Temporal workflow boundary.
+ *
+ * @param getThread - Factory that returns a thread manager for the given threadId
+ * @param handler   - The original tool handler
+ * @returns A wrapped handler that auto-appends and flags the response
+ *
+ * @example
+ * ```typescript
+ * import { withAutoAppend } from '@bead-ai/zeitlich/workflow';
+ * import { createThreadManager } from '@bead-ai/zeitlich';
+ *
+ * const handler = withAutoAppend(
+ *   (threadId) => createThreadManager({ redis, threadId }),
+ *   async (args, ctx) => ({
+ *     toolResponse: JSON.stringify(largeResult), // appended directly to Redis
+ *     data: { summary: "..." },                  // small data for workflow
+ *   }),
+ * );
+ * ```
+ */
+export function withAutoAppend<
+  TArgs,
+  TResult,
+  TContext extends RouterContext = RouterContext,
+>(
+  threadHandler: (config: ToolResultConfig) => Promise<void>,
+  handler: ActivityToolHandler<TArgs, TResult, TContext>
+): ActivityToolHandler<TArgs, TResult, TContext> {
+  return async (args: TArgs, context: TContext) => {
+    const response = await handler(args, context);
+
+    await threadHandler({
+      threadId: context.threadId,
+      toolCallId: context.toolCallId,
+      toolName: context.toolName,
+      content: response.toolResponse,
+    });
+
+    return {
+      toolResponse: "Response appended via withAutoAppend",
+      data: response.data,
+      resultAppended: true,
+    };
+  };
+}

package/src/lib/tool-router/index.ts

@@ -0,0 +1,41 @@
+export {
+  createToolRouter,
+  defineTool,
+  hasNoOtherToolCalls,
+} from "./router";
+export { withAutoAppend } from "./auto-append";
+export { withSandbox } from "./with-sandbox";
+export type { SandboxContext } from "./with-sandbox";
+
+export type {
+  ToolDefinition,
+  ToolWithHandler,
+  ToolMap,
+  ToolNames,
+  RawToolCall,
+  ParsedToolCall,
+  ParsedToolCallUnion,
+  AppendToolResultFn,
+  ToolHandlerResponse,
+  RouterContext,
+  ToolHandler,
+  ActivityToolHandler,
+  ToolArgs,
+  ToolResult,
+  ToolCallResult,
+  InferToolResults,
+  ToolCallResultUnion,
+  ProcessToolCallsContext,
+  PreToolUseHookResult,
+  PostToolUseFailureHookResult,
+  ToolHooks,
+  PreToolUseHookContext,
+  PreToolUseHook,
+  PostToolUseHookContext,
+  PostToolUseHook,
+  PostToolUseFailureHookContext,
+  PostToolUseFailureHook,
+  ToolRouterHooks,
+  ToolRouterOptions,
+  ToolRouter,
+} from "./types";