zeitlich 0.2.11 → 0.2.13

package/src/tools/bash/handler.ts

@@ -11,6 +11,19 @@ type BashExecOut = {
 /** BashOptions with `fs` required */
 type BashToolOptions = Required<Pick<BashOptions, "fs">> & Omit<BashOptions, "fs">;
 
+/**
+ * Creates a Bash tool handler that executes shell commands in a sandboxed environment.
+ *
+ * @param bashOptions - Options including a required `fs` (file system implementation from `just-bash`)
+ * @returns Activity tool handler for Bash tool calls
+ *
+ * @example
+ * ```typescript
+ * import { createBashHandler } from 'zeitlich';
+ *
+ * const bashHandlerActivity = createBashHandler({ fs: inMemoryFileSystem });
+ * ```
+ */
 export const createBashHandler: (
     bashOptions: BashToolOptions,
 ) => ActivityToolHandler<BashArgs, BashExecOut | null> =

package/src/tools/subagent/handler.ts

@@ -1,5 +1,7 @@
-import { executeChild, workflowInfo, uuid4 } from "@temporalio/workflow";
+import { executeChild, workflowInfo } from "@temporalio/workflow";
+import { getShortId } from "../../lib/thread-id";
 import type { ToolHandlerResponse } from "../../lib/tool-router";
+import type { ToolMessageContent } from "../../lib/types";
 import type {
   InferSubagentResult,
   SubagentConfig,
@@ -40,12 +42,13 @@ export function createSubagentHandler<
       );
     }
 
-    const childWorkflowId = `${args.subagent}-${uuid4()}`;
+    const childWorkflowId = `${args.subagent}-${getShortId()}`;
 
-    // Execute the child workflow
     const input: SubagentInput = {
       prompt: args.prompt,
       ...(config.context && { context: config.context }),
+      ...(args.threadId &&
+        config.allowThreadContinuation && { threadId: args.threadId }),
     };
 
     const childOpts = {
@@ -54,7 +57,7 @@ export function createSubagentHandler<
       taskQueue: config.taskQueue ?? parentTaskQueue,
     };
 
-    const { toolResponse, data, usage } =
+    const { toolResponse, data, usage, threadId: childThreadId } =
       typeof config.workflow === "string"
         ? await executeChild(config.workflow, childOpts)
         : await executeChild(config.workflow, childOpts);
@@ -80,8 +83,16 @@ export function createSubagentHandler<
       };
     }
 
+    let finalToolResponse: ToolMessageContent = toolResponse;
+    if (config.allowThreadContinuation && childThreadId) {
+      finalToolResponse =
+        typeof toolResponse === "string"
+          ? `${toolResponse}\n\n[Thread ID: ${childThreadId}]`
+          : toolResponse;
+    }
+
     return {
-      toolResponse,
+      toolResponse: finalToolResponse,
       data: validated ? validated.data : data,
       ...(usage && { usage }),
     };

package/src/tools/subagent/tool.ts

@@ -8,7 +8,12 @@ export const SUBAGENT_TOOL_NAME = "Subagent" as const;
  */
 function buildSubagentDescription(subagents: SubagentConfig[]): string {
   const subagentList = subagents
-    .map((s) => `## ${s.agentName}\n${s.description}`)
+    .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.
@@ -37,30 +42,43 @@ ${subagentList}
 export function createSubagentTool<T extends SubagentConfig[]>(
   subagents: T
 ): {
-  name: string;
-  description: string;
-  schema: z.ZodObject<{
-    subagent: z.ZodEnum<Record<string, string>>;
-    description: z.ZodString;
-    prompt: z.ZodString;
-  }>;
+  readonly name: typeof SUBAGENT_TOOL_NAME;
+  readonly description: string;
+  readonly schema: z.ZodObject<z.ZodRawShape>;
 } {
   if (subagents.length === 0) {
     throw new Error("createTaskTool 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: z.object({
-      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"),
-    }),
+    schema,
   } as const;
 }
 
@@ -71,4 +89,5 @@ export type SubagentArgs = {
   subagent: string;
   description: string;
   prompt: string;
+  threadId?: string;
 };

package/src/workflow.ts

@@ -1,7 +1,7 @@
 /**
  * Workflow-safe exports for use in Temporal workflow code.
  *
- * Import from 'zeitlich/workflow' in workflow files.
+ * Import from `zeitlich/workflow` in workflow files.
  * These exports have no external dependencies (no Redis, no LangChain).
  *
  * @example
@@ -10,13 +10,19 @@
  * import {
  *   createSession,
  *   createAgentStateManager,
- *   createToolRouter,
+ *   askUserQuestionTool,
+ *   bashTool,
+ *   defineTool,
+ *   type SubagentWorkflow,
  * } from 'zeitlich/workflow';
  * ```
  */
 
 // Session
 export { createSession, proxyDefaultThreadOps } from "./lib/session";
+
+// Thread utilities
+export { getShortId } from "./lib/thread-id";
 export type { ZeitlichSession, SessionLifecycleHooks } from "./lib/session";
 
 // State management
@@ -59,23 +65,30 @@ export type {
   ToolCallResultUnion,
   InferToolResults,
   // Other
-  ToolMessageContent,
   AppendToolResultFn,
   ProcessToolCallsContext,
 } from "./lib/tool-router";
 
 // Types
 export type {
+  // Message types (framework-agnostic)
+  ContentPart,
+  MessageContent,
+  ToolMessageContent,
+  TokenUsage,
+  // Agent types
   AgentStatus,
   BaseAgentState,
   AgentFile,
   AgentResponse,
   ThreadOps,
   AgentConfig,
+  SessionConfig,
   RunAgentConfig,
   RunAgentActivity,
   ToolResultConfig,
   SessionExitReason,
+  // Hook types
   PreToolUseHook,
   PreToolUseHookContext,
   PreToolUseHookResult,
@@ -84,14 +97,21 @@ export type {
   PostToolUseFailureHook,
   PostToolUseFailureHookContext,
   PostToolUseFailureHookResult,
+  PreHumanMessageAppendHook,
+  PreHumanMessageAppendHookContext,
+  PostHumanMessageAppendHook,
+  PostHumanMessageAppendHookContext,
+  Hooks,
   ToolHooks,
   SessionStartHook,
   SessionStartHookContext,
   SessionEndHook,
   SessionEndHookContext,
+  // Subagent types
   SubagentConfig,
   SubagentHooks,
   SubagentInput,
+  // Task types
   TaskStatus,
   WorkflowTask,
 } from "./lib/types";
@@ -101,6 +121,9 @@ export {
   agentStateChangeUpdateName,
 } from "./lib/types";
 
+// Model invoker contract
+export type { ModelInvoker, ModelInvokerConfig } from "./lib/model-invoker";
+
 // Subagent support
 export { createSubagentTool } from "./tools/subagent/tool";
 export type { SubagentArgs } from "./tools/subagent/tool";
@@ -113,10 +136,6 @@ export { createReadSkillTool } from "./tools/read-skill/tool";
 export { createReadSkillHandler } from "./tools/read-skill/handler";
 export type { ReadSkillArgs } from "./tools/read-skill/tool";
 
-// Activity type interfaces (types only, no runtime code)
-// These are safe to import in workflows for typing proxyActivities
-export type { ZeitlichSharedActivities } from "./activities";
-
 // Tool definitions (schemas only - no handlers)
 export { globTool } from "./tools/glob/tool";
 export type { GlobArgs } from "./tools/glob/tool";

package/tsup.config.ts

@@ -4,6 +4,7 @@ export default defineConfig({
   entry: {
     index: "src/index.ts",
     workflow: "src/workflow.ts",
+    "adapters/langchain/index": "src/adapters/langchain/index.ts",
   },
   format: ["esm", "cjs"],
   dts: true,

package/src/activities.ts

@@ -1,91 +0,0 @@
-import type Redis from "ioredis";
-import { createThreadManager } from "./lib/thread-manager";
-import type { ToolResultConfig } from "./lib/types";
-import {
-  type MessageContent,
-  type StoredMessage,
-} from "@langchain/core/messages";
-/**
- * Shared Zeitlich activities - thread management and message handling
- * Note: runAgent is workflow-specific and should be created per-workflow
- */
-export interface ZeitlichSharedActivities {
-  /**
-   * Append a tool result to the thread.
-   * Handles JSON serialization and optional cache points.
-   */
-  appendToolResult(config: ToolResultConfig): Promise<void>;
-
-  /**
-   * Initialize an empty thread.
-   */
-  initializeThread(threadId: string): Promise<void>;
-
-  /**
-   * Append messages to a thread.
-   */
-  appendThreadMessages(
-    threadId: string,
-    messages: StoredMessage[]
-  ): Promise<void>;
-
-  /**
-   * Append a human message to a thread.
-   */
-  appendHumanMessage(
-    threadId: string,
-    content: string | MessageContent
-  ): Promise<void>;
-
-  /**
-   * Append a system message to a thread.
-   */
-  appendSystemMessage(threadId: string, content: string): Promise<void>;
-}
-
-/**
- * Creates shared Temporal activities for thread management
- *
- * @returns An object containing the shared activity functions
- *
- * @experimental The Zeitlich integration is an experimental feature; APIs may change without notice.
- */
-export function createSharedActivities(redis: Redis): ZeitlichSharedActivities {
-  return {
-    async appendToolResult(config: ToolResultConfig): Promise<void> {
-      const { threadId, toolCallId, content } = config;
-      const thread = createThreadManager({ redis, threadId });
-
-      await thread.appendToolMessage(content, toolCallId);
-    },
-
-    async initializeThread(threadId: string): Promise<void> {
-      const thread = createThreadManager({ redis, threadId });
-      await thread.initialize();
-    },
-
-    async appendThreadMessages(
-      threadId: string,
-      messages: StoredMessage[]
-    ): Promise<void> {
-      const thread = createThreadManager({ redis, threadId });
-      await thread.append(messages);
-    },
-
-    async appendHumanMessage(
-      threadId: string,
-      content: string | MessageContent
-    ): Promise<void> {
-      const thread = createThreadManager({ redis, threadId });
-      await thread.appendHumanMessage(content);
-    },
-
-    async appendSystemMessage(
-      threadId: string,
-      content: string
-    ): Promise<void> {
-      const thread = createThreadManager({ redis, threadId });
-      await thread.appendSystemMessage(content);
-    },
-  };
-}

package/src/plugin.ts

@@ -1,28 +0,0 @@
-import { SimplePlugin } from "@temporalio/plugin";
-import { createSharedActivities } from "./activities";
-import type Redis from "ioredis";
-
-/**
- * Options for the Zeitlich plugin
- *
- * @experimental The Zeitlich plugin is an experimental feature; APIs may change without notice.
- */
-export interface ZeitlichPluginOptions {
-  redis: Redis;
-}
-
-/**
- * A Temporal plugin that integrates Zeitlich for use in workflows.
- * This plugin creates shared activities for thread management.
- * Workflow-specific activities (like runAgent) should be created separately.
- *
- * @experimental The Zeitlich plugin is an experimental feature; APIs may change without notice.
- */
-export class ZeitlichPlugin extends SimplePlugin {
-  constructor(options: ZeitlichPluginOptions) {
-    super({
-      name: "ZeitlichPlugin",
-      activities: createSharedActivities(options.redis),
-    });
-  }
-}