zeitlich 0.2.9 → 0.2.12

package/src/tools/read-skill/handler.ts

@@ -0,0 +1,31 @@
+import type { Skill } from "../../lib/skills/types";
+import type { ToolHandlerResponse } from "../../lib/tool-router";
+import type { ReadSkillArgs } from "./tool";
+
+/**
+ * Creates a ReadSkill handler that looks up skills from an in-memory array.
+ * Runs directly in the workflow (like task tools) — no activity needed.
+ */
+export function createReadSkillHandler(
+  skills: Skill[]
+): (args: ReadSkillArgs) => ToolHandlerResponse<null> {
+  const skillMap = new Map(skills.map((s) => [s.name, s]));
+
+  return (args: ReadSkillArgs): ToolHandlerResponse<null> => {
+    const skill = skillMap.get(args.skill_name);
+
+    if (!skill) {
+      return {
+        toolResponse: JSON.stringify({
+          error: `Skill "${args.skill_name}" not found`,
+        }),
+        data: null,
+      };
+    }
+
+    return {
+      toolResponse: skill.instructions,
+      data: null,
+    };
+  };
+}

package/src/tools/read-skill/tool.ts

@@ -0,0 +1,47 @@
+import z from "zod";
+import type { Skill } from "../../lib/skills/types";
+
+export const READ_SKILL_TOOL_NAME = "ReadSkill" as const;
+
+function buildReadSkillDescription(skills: Skill[]): string {
+  const skillList = skills
+    .map((s) => `- **${s.name}**: ${s.description}`)
+    .join("\n");
+
+  return `Load the full instructions for a skill. Read the skill before following its instructions.
+
+# Available skills:
+${skillList}
+`;
+}
+
+/**
+ * Creates a ReadSkill tool configured with the available skills.
+ * The tool description embeds skill metadata so the agent discovers
+ * skills purely through the tool definition.
+ */
+export function createReadSkillTool(skills: Skill[]): {
+  name: string;
+  description: string;
+  schema: z.ZodObject<{
+    skill_name: z.ZodEnum<Record<string, string>>;
+  }>;
+} {
+  if (skills.length === 0) {
+    throw new Error("createReadSkillTool requires at least one skill");
+  }
+
+  const names = skills.map((s) => s.name);
+
+  return {
+    name: READ_SKILL_TOOL_NAME,
+    description: buildReadSkillDescription(skills),
+    schema: z.object({
+      skill_name: z.enum(names).describe("The name of the skill to load"),
+    }),
+  } as const;
+}
+
+export type ReadSkillArgs = {
+  skill_name: string;
+};

package/src/tools/subagent/handler.ts

@@ -1,11 +1,14 @@
-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,
   SubagentInput,
 } from "../../lib/types";
 import type { SubagentArgs } from "./tool";
+import type { z } from "zod";
 
 /**
  * Creates a Subagent tool handler that spawns child workflows for configured subagents.
@@ -39,33 +42,58 @@ 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 = {
       workflowId: childWorkflowId,
-      args: [input],
+      args: [input] as const,
       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);
 
+    if (!toolResponse) {
+      return {
+        toolResponse: "Subagent workflow returned no response",
+        data: null,
+        ...(usage && { usage }),
+      };
+    }
+
     // Validate result if schema provided, otherwise pass through as-is
     const validated = (
-      config.resultSchema ? config.resultSchema.parse(data) : null
-    ) as InferSubagentResult<T[number]> | null;
+      config.resultSchema ? config.resultSchema.safeParse(data) : null
+    ) as z.ZodSafeParseResult<InferSubagentResult<T[number]>> | null;
+
+    if (validated && !validated.success) {
+      return {
+        toolResponse: `Subagent workflow returned invalid data: ${validated.error.message}`,
+        data: null,
+        ...(usage && { usage }),
+      };
+    }
+
+    let finalToolResponse: ToolMessageContent = toolResponse;
+    if (config.allowThreadContinuation && childThreadId) {
+      finalToolResponse =
+        typeof toolResponse === "string"
+          ? `${toolResponse}\n\n[Thread ID: ${childThreadId}]`
+          : toolResponse;
+    }
 
     return {
-      toolResponse,
-      data: validated,
+      toolResponse: finalToolResponse,
+      data: validated ? validated.data : data,
       ...(usage && { usage }),
     };
   };

package/src/tools/subagent/tool.ts

@@ -8,29 +8,19 @@ export const SUBAGENT_TOOL_NAME = "Subagent" as const;
  */
 function buildSubagentDescription(subagents: SubagentConfig[]): string {
   const subagentList = subagents
-    .map((s) => `- **${s.agentName}**: ${s.description}`)
-    .join("\n");
+    .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 `Launch a new agent to handle complex tasks autonomously.
-
-The ${SUBAGENT_TOOL_NAME} tool launches specialized agents (subprocesses) that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.
-
-Available agent types:
+  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}
-
-When using the ${SUBAGENT_TOOL_NAME} tool, you must specify a subagent parameter to select which agent type to use.
-
-Usage notes:
-
-- Always include a short description (3-5 words) summarizing what the agent will do
-- Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses
-- When the agent is done, it will return a single message back to you.
-- Each invocation starts fresh - provide a detailed task description with all necessary context.
-- Provide clear, detailed prompts so the agent can work autonomously and return exactly the information you need.
-- The agent's outputs should generally be trusted
-- Clearly tell the agent what type of work you expect since it is not aware of the user's intent
-- If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first. Use your judgement.`;
+`;
 }
 
 /**
@@ -52,30 +42,43 @@ Usage notes:
 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;
 }
 
@@ -86,4 +89,5 @@ export type SubagentArgs = {
   subagent: string;
   description: string;
   prompt: string;
+  threadId?: string;
 };

package/src/tools/task-create/tool.ts

@@ -3,7 +3,7 @@ import type { ToolDefinition } from "../../lib/tool-router";
 
 export const taskCreateTool = {
   name: "TaskCreate" as const,
-  description: `Use this tool to create a structured task list for the control test. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.
+  description: `Use this tool to create a structured task list. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.
   It also helps the user understand the progress of the task and overall progress of their requests.
   
   ## When to Use This Tool

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,20 +10,23 @@
  * 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
-export {
-  createAgentStateManager,
-  AGENT_HANDLER_NAMES,
-} from "./lib/state-manager";
+export { createAgentStateManager } from "./lib/state-manager";
 export type {
   AgentState,
   AgentStateManager,
@@ -62,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,
@@ -87,26 +97,44 @@ 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";
-export { isTerminalStatus } from "./lib/types";
+export {
+  isTerminalStatus,
+  agentQueryName,
+  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";
+export type { SubagentWorkflow } from "./lib/types";
 
-// Activity type interfaces (types only, no runtime code)
-// These are safe to import in workflows for typing proxyActivities
-export type { ZeitlichSharedActivities } from "./activities";
+// Skills (types + workflow-safe utilities)
+export type { Skill, SkillMetadata, SkillProvider } from "./lib/skills/types";
+export { parseSkillFile } from "./lib/skills/parse";
+export { createReadSkillTool } from "./tools/read-skill/tool";
+export { createReadSkillHandler } from "./tools/read-skill/handler";
+export type { ReadSkillArgs } from "./tools/read-skill/tool";
 
 // Tool definitions (schemas only - no handlers)
 export { globTool } 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),
-    });
-  }
-}