zeitlich 0.2.8 → 0.2.11

package/src/lib/tool-router.ts

@@ -10,11 +10,18 @@ import type {
   ToolHooks,
   ToolResultConfig,
 } from "./types";
+import type { Skill } from "./skills/types";
 import type { SubagentArgs } from "../tools/subagent/tool";
 
 import type { z } from "zod";
-import { createSubagentTool } from "../tools/subagent/tool";
+import { createSubagentTool, SUBAGENT_TOOL_NAME } from "../tools/subagent/tool";
 import { createSubagentHandler } from "../tools/subagent/handler";
+import {
+  createReadSkillTool,
+  READ_SKILL_TOOL_NAME,
+} from "../tools/read-skill/tool";
+import { createReadSkillHandler } from "../tools/read-skill/handler";
+import { ApplicationFailure } from "@temporalio/workflow";
 
 export type { ToolMessageContent };
 
@@ -54,7 +61,7 @@ export interface ToolWithHandler<
   strict?: boolean;
   max_uses?: number;
   /** Whether this tool is available to the agent (default: true). Disabled tools are excluded from definitions and rejected at parse time. */
-  enabled?: () => boolean;
+  enabled?: boolean;
   /** Per-tool lifecycle hooks (run in addition to global hooks) */
   hooks?: ToolHooks<z.infer<TSchema>, TResult>;
 }
@@ -77,7 +84,7 @@ export type ToolMap = Record<
     handler: ToolHandler<any, any, any>;
     strict?: boolean;
     max_uses?: number;
-    enabled?: () => boolean;
+    enabled?: boolean;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     hooks?: ToolHooks<any, any>;
   }
@@ -250,6 +257,8 @@ export interface ToolRouterOptions<T extends ToolMap> {
   hooks?: Hooks<T, ToolCallResultUnion<InferToolResults<T>>>;
   /** Subagent configurations */
   subagents?: SubagentConfig[];
+  /** Skills available to the agent (auto-adds ReadSkill tool when non-empty) */
+  skills?: Skill[];
 }
 
 /**
@@ -416,8 +425,8 @@ export function createToolRouter<T extends ToolMap>(
   }
 
   /** Check if a tool is enabled (defaults to true when not specified) */
-  const isEnabled = (tool: ToolMap[string]): boolean =>
-    tool.enabled?.() ?? true;
+  const isEnabled = (tool: ToolMap[string] | SubagentConfig): boolean =>
+    tool.enabled ?? true;
 
   if (options.subagents) {
     if (options.subagents.length > 0) {
@@ -430,7 +439,7 @@ export function createToolRouter<T extends ToolMap>(
       const resolveSubagentName = (args: unknown): string =>
         (args as SubagentArgs).subagent;
 
-      toolMap.set("Subagent", {
+      toolMap.set(SUBAGENT_TOOL_NAME, {
         ...createSubagentTool(options.subagents),
         handler: createSubagentHandler(options.subagents),
         ...(subagentHooksMap.size > 0 && {
@@ -455,6 +464,13 @@ export function createToolRouter<T extends ToolMap>(
     }
   }
 
+  if (options.skills && options.skills.length > 0) {
+    toolMap.set(READ_SKILL_TOOL_NAME, {
+      ...createReadSkillTool(options.skills),
+      handler: createReadSkillHandler(options.skills),
+    });
+  }
+
   async function processToolCall(
     toolCall: ParsedToolCallUnion<T>,
     turn: number,
@@ -577,7 +593,9 @@ export function createToolRouter<T extends ToolMap>(
       }
 
       if (!recovered) {
-        throw error;
+        throw ApplicationFailure.fromError(error, {
+          nonRetryable: true,
+        });
       }
     }
 
@@ -657,15 +675,30 @@ export function createToolRouter<T extends ToolMap>(
     },
 
     getToolDefinitions(): ToolDefinition[] {
-      return Array.from(toolMap)
-        .filter(([, tool]) => isEnabled(tool))
-        .map(([name, tool]) => ({
-          name,
-          description: tool.description,
-          schema: tool.schema,
-          strict: tool.strict,
-          max_uses: tool.max_uses,
-        }));
+      const activeSubagents =
+        options.subagents?.filter((subagent) => isEnabled(subagent)) ?? [];
+      const activeSkills = options.skills ?? [];
+
+      return [
+        ...Array.from(toolMap)
+          .filter(
+            ([, tool]) =>
+              isEnabled(tool) &&
+              tool.name !== SUBAGENT_TOOL_NAME &&
+              tool.name !== READ_SKILL_TOOL_NAME
+          )
+          .map(([name, tool]) => ({
+            name,
+            description: tool.description,
+            schema: tool.schema,
+            strict: tool.strict,
+            max_uses: tool.max_uses,
+          })),
+        ...(activeSubagents.length > 0
+          ? [createSubagentTool(activeSubagents)]
+          : []),
+        ...(activeSkills.length > 0 ? [createReadSkillTool(activeSkills)] : []),
+      ];
     },
 
     // --- Methods for processing tool calls ---

package/src/lib/types.ts

@@ -4,12 +4,13 @@ import type {
   ParsedToolCallUnion,
   RawToolCall,
   ToolCallResultUnion,
+  ToolHandlerResponse,
   ToolMap,
 } from "./tool-router";
+import type { Skill } from "./skills/types";
 
 import type { MessageContent, StoredMessage } from "@langchain/core/messages";
 import type { Duration } from "@temporalio/common";
-import type { Workflow } from "@temporalio/workflow";
 import type { z } from "zod";
 
 /**
@@ -31,7 +32,7 @@ export interface BaseAgentState {
   version: number;
   turns: number;
   tasks: Map<string, WorkflowTask>;
-  systemPrompt: string;
+  systemPrompt?: string;
   totalInputTokens: number;
   totalOutputTokens: number;
   cachedWriteTokens: number;
@@ -98,8 +99,6 @@ export interface AgentConfig {
   agentName: string;
   /** Description, used for sub agents */
   description?: string;
-  /** The system prompt to append to the thread */
-  systemPrompt?: string;
 }
 
 /**
@@ -122,6 +121,8 @@ export interface SessionConfig<T extends ToolMap, M = StoredMessage> {
   tools?: T;
   /** Subagent configurations */
   subagents?: SubagentConfig[];
+  /** Skills available to this agent (metadata + instructions, loaded activity-side) */
+  skills?: Skill[];
   /** Session lifecycle hooks */
   hooks?: Hooks<T, ToolCallResultUnion<InferToolResults<T>>>;
   /** Whether to process tools in parallel */
@@ -181,6 +182,10 @@ export interface ToolResultConfig {
 // Subagent Configuration
 // ============================================================================
 
+export type SubagentWorkflow<TResult extends z.ZodType = z.ZodType> = (
+  input: SubagentInput
+) => Promise<ToolHandlerResponse<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;
@@ -196,9 +201,9 @@ export interface SubagentConfig<TResult extends z.ZodType = z.ZodType> {
   /** 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;
+  enabled?: boolean;
   /** Temporal workflow function or type name (used with executeChild) */
-  workflow: string | Workflow;
+  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. */
@@ -499,6 +504,18 @@ export interface Hooks<T extends ToolMap, TResult = unknown> {
   onSessionEnd?: SessionEndHook;
 }
 
+// ============================================================================
+// Agent Query/Update Name Helpers
+// ============================================================================
+
+/** Derives the query name for an agent's state (usable in both workflow and activity code) */
+export const agentQueryName = (agentName: string) =>
+  `get${agentName}State` as const;
+
+/** Derives the update name for waiting on an agent's state change */
+export const agentStateChangeUpdateName = (agentName: string) =>
+  `waitFor${agentName}StateChange` as const;
+
 /**
  * Helper to check if status is terminal
  */

package/src/tools/ask-user-question/handler.ts

@@ -1,11 +1,11 @@
-import type { ToolHandler } from "../../lib/tool-router";
+import type { ActivityToolHandler } from "../../lib/tool-router";
 import type { AskUserQuestionArgs } from "./tool";
 
 /**
  * Creates handler for user interaction tool - creates AI messages for display.
  */
 export const createAskUserQuestionHandler =
-  (): ToolHandler<
+  (): ActivityToolHandler<
     AskUserQuestionArgs,
     {
       questions: {
@@ -16,7 +16,7 @@ export const createAskUserQuestionHandler =
       }[];
     }
   > =>
-  (args) => {
+  async (args) => {
     return {
       toolResponse: "Question submitted",
       data: { questions: args.questions },

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

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import type { ToolDefinition } from "../../lib/tool-router";
 
-export const readTool = {
+export const readFileTool = {
   name: "FileRead" as const,
   description: `Read file contents with optional pagination.
 
@@ -31,4 +31,4 @@ The tool returns the file content in an appropriate format:
   strict: true,
 } satisfies ToolDefinition;
 
-export type FileReadArgs = z.infer<typeof readTool.schema>;
+export type FileReadArgs = z.infer<typeof readFileTool.schema>;

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

@@ -6,6 +6,7 @@ import type {
   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.
@@ -49,7 +50,7 @@ export function createSubagentHandler<
 
     const childOpts = {
       workflowId: childWorkflowId,
-      args: [input],
+      args: [input] as const,
       taskQueue: config.taskQueue ?? parentTaskQueue,
     };
 
@@ -58,14 +59,30 @@ export function createSubagentHandler<
         ? 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 }),
+      };
+    }
 
     return {
       toolResponse,
-      data: validated,
+      data: validated ? validated.data : data,
       ...(usage && { usage }),
     };
   };

package/src/tools/subagent/tool.ts

@@ -1,36 +1,21 @@
 import z from "zod";
 import type { SubagentConfig } from "../../lib/types";
 
-const SUBAGENT_TOOL = "Subagent" as const;
+export const SUBAGENT_TOOL_NAME = "Subagent" as const;
 
 /**
  * Builds the tool description with available subagent information
  */
 function buildSubagentDescription(subagents: SubagentConfig[]): string {
   const subagentList = subagents
-    .map((s) => `- **${s.agentName}**: ${s.description}`)
-    .join("\n");
+    .map((s) => `## ${s.agentName}\n${s.description}`)
+    .join("\n\n");
 
-  return `Launch a new agent to handle complex tasks autonomously.
-
-The ${SUBAGENT_TOOL} 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} 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.`;
+`;
 }
 
 /**
@@ -67,7 +52,7 @@ export function createSubagentTool<T extends SubagentConfig[]>(
   const names = subagents.map((s) => s.agentName);
 
   return {
-    name: SUBAGENT_TOOL,
+    name: SUBAGENT_TOOL_NAME,
     description: buildSubagentDescription(subagents),
     schema: z.object({
       subagent: z.enum(names).describe("The type of subagent to launch"),

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/tools/write-file/tool.ts

@@ -1,25 +1,24 @@
 import { z } from "zod";
 import type { ToolDefinition } from "../../lib/tool-router";
 
-export const writeTool = {
+export const writeFileTool = {
   name: "FileWrite" as const,
   description: `Create or overwrite a file with new content.
 
 Usage:
-- Provide the absolute path to the file
 - The file will be created if it doesn't exist
 - If the file exists, it will be completely overwritten
 
 IMPORTANT:
 - You must read the file first (in this session) before writing to it
 - This is an atomic write operation - the entire file is replaced
-- Path must be absolute (e.g., "/docs/readme.md", not "docs/readme.md")
+- Path must be relative to the root of the file system (e.g., "docs/readme.md", not "/docs/readme.md")
 `,
   schema: z.object({
-    file_path: z.string().describe("The absolute path to the file to write"),
+    file_path: z.string().describe("The path to the file to write"),
     content: z.string().describe("The content to write to the file"),
   }),
   strict: true,
 } satisfies ToolDefinition;
 
-export type FileWriteArgs = z.infer<typeof writeTool.schema>;
+export type FileWriteArgs = z.infer<typeof writeFileTool.schema>;

package/src/workflow.ts

@@ -20,10 +20,7 @@ export { createSession, proxyDefaultThreadOps } from "./lib/session";
 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,
@@ -98,11 +95,23 @@ export type {
   TaskStatus,
   WorkflowTask,
 } from "./lib/types";
-export { isTerminalStatus } from "./lib/types";
+export {
+  isTerminalStatus,
+  agentQueryName,
+  agentStateChangeUpdateName,
+} from "./lib/types";
 
 // Subagent support
 export { createSubagentTool } from "./tools/subagent/tool";
 export type { SubagentArgs } from "./tools/subagent/tool";
+export type { SubagentWorkflow } from "./lib/types";
+
+// 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";
 
 // Activity type interfaces (types only, no runtime code)
 // These are safe to import in workflows for typing proxyActivities
@@ -113,9 +122,9 @@ export { globTool } from "./tools/glob/tool";
 export type { GlobArgs } from "./tools/glob/tool";
 export { grepTool } from "./tools/grep/tool";
 export type { GrepArgs } from "./tools/grep/tool";
-export { readTool } from "./tools/read-file/tool";
+export { readFileTool } from "./tools/read-file/tool";
 export type { FileReadArgs } from "./tools/read-file/tool";
-export { writeTool } from "./tools/write-file/tool";
+export { writeFileTool } from "./tools/write-file/tool";
 export type { FileWriteArgs } from "./tools/write-file/tool";
 export { editTool } from "./tools/edit/tool";
 export type { FileEditArgs } from "./tools/edit/tool";