zeitlich 0.2.2 → 0.2.4

package/src/tools/{task → subagent}/tool.ts

@@ -1,31 +1,31 @@
 import z from "zod";
 import type { SubagentConfig } from "../../lib/types";
 
-const TASK_TOOL = "Task" as const;
+const SUBAGENT_TOOL = "Subagent" as const;
 
 /**
  * Builds the tool description with available subagent information
  */
-function buildTaskDescription(subagents: SubagentConfig[]): string {
+function buildSubagentDescription(subagents: SubagentConfig[]): string {
   const subagentList = subagents
     .map((s) => `- **${s.name}**: ${s.description}`)
     .join("\n");
 
-  return `Launch a new agent to handle complex, multi-step tasks autonomously.
+  return `Launch a new agent to handle complex tasks autonomously.
 
-The ${TASK_TOOL} tool launches specialized agents (subprocesses) that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.
+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:
 
 ${subagentList}
 
-When using the ${TASK_TOOL} tool, you must specify a subagent parameter to select which agent type to use.
+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. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result.
+- 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
@@ -34,13 +34,13 @@ Usage notes:
 }
 
 /**
- * Creates a Task tool configured with the available subagents.
+ * 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
  *
  * @example
- * const taskTool = createTaskTool([
+ * const subagentTool = createSubagentTool([
  *   {
  *     name: "researcher",
  *     description: "Researches topics and gathers information",
@@ -49,7 +49,7 @@ Usage notes:
  *   },
  * ]);
  */
-export function createTaskTool<T extends SubagentConfig[]>(
+export function createSubagentTool<T extends SubagentConfig[]>(
   subagents: T
 ): {
   name: string;
@@ -67,8 +67,8 @@ export function createTaskTool<T extends SubagentConfig[]>(
   const names = subagents.map((s) => s.name);
 
   return {
-    name: TASK_TOOL,
-    description: buildTaskDescription(subagents),
+    name: SUBAGENT_TOOL,
+    description: buildSubagentDescription(subagents),
     schema: z.object({
       subagent: z.enum(names).describe("The type of subagent to launch"),
       description: z
@@ -80,16 +80,9 @@ export function createTaskTool<T extends SubagentConfig[]>(
 }
 
 /**
- * Infer the schema type for a task tool created with specific subagents
+ * Subagent tool args type (when subagent names are not known at compile time)
  */
-export type TaskToolSchemaType<T extends SubagentConfig[]> = z.infer<
-  ReturnType<typeof createTaskTool<T>>["schema"]
->;
-
-/**
- * Generic task tool schema type (when subagent names are not known at compile time)
- */
-export type GenericTaskToolSchemaType = {
+export type SubagentArgs = {
   subagent: string;
   description: string;
   prompt: string;

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

@@ -2,29 +2,23 @@ import type {
   AgentStateManager,
   JsonSerializable,
 } from "../../lib/state-manager";
-import type { ToolHandlerResponse } from "../../lib/tool-router";
+import type { ToolHandler } from "../../lib/tool-router";
 import type { WorkflowTask } from "../../lib/types";
-import type { TaskCreateToolSchemaType } from "./tool";
+import type { TaskCreateArgs } from "./tool";
 import { uuid4 } from "@temporalio/workflow";
 
 /**
  * Creates a TaskCreate handler that adds tasks to the workflow state.
  *
  * @param stateManager - State manager containing tasks state
- * @param idGenerator - Function to generate unique task IDs (e.g., uuid4 from Temporal)
- * @returns A tool handler function
- *
- * @example
- * const handler = createTaskCreateHandler(stateManager, uuid4);
+ * @returns A ToolHandler for TaskCreate tool calls
  */
 export function createTaskCreateHandler<
   TCustom extends JsonSerializable<TCustom>,
 >(
   stateManager: AgentStateManager<TCustom>
-): (args: TaskCreateToolSchemaType) => ToolHandlerResponse<WorkflowTask> {
-  return (
-    args: TaskCreateToolSchemaType
-  ): ToolHandlerResponse<WorkflowTask> => {
+): ToolHandler<TaskCreateArgs, WorkflowTask> {
+  return (args) => {
     const task: WorkflowTask = {
       id: uuid4(),
       subject: args.subject,

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

@@ -1,4 +1,5 @@
 import z from "zod";
+import type { ToolDefinition } from "../../lib/tool-router";
 
 export const taskCreateTool = {
   name: "TaskCreate" as const,
@@ -61,6 +62,6 @@ export const taskCreateTool = {
       .record(z.string(), z.string())
       .describe("Arbitrary key-value pairs for tracking"),
   }),
-};
+} satisfies ToolDefinition;
 
-export type TaskCreateToolSchemaType = z.infer<typeof taskCreateTool.schema>;
+export type TaskCreateArgs = z.infer<typeof taskCreateTool.schema>;

package/src/tools/task-get/handler.ts

@@ -2,25 +2,20 @@ import type {
   AgentStateManager,
   JsonSerializable,
 } from "../../lib/state-manager";
-import type { ToolHandlerResponse } from "../../lib/tool-router";
+import type { ToolHandler } from "../../lib/tool-router";
 import type { WorkflowTask } from "../../lib/types";
-import type { TaskGetToolSchemaType } from "./tool";
+import type { TaskGetArgs } from "./tool";
 
 /**
  * Creates a TaskGet handler that retrieves a task by ID.
  *
  * @param stateManager - State manager containing tasks state
- * @returns A tool handler function
- *
- * @example
- * const handler = createTaskGetHandler(stateManager);
+ * @returns A ToolHandler for TaskGet tool calls
  */
 export function createTaskGetHandler<TCustom extends JsonSerializable<TCustom>>(
   stateManager: AgentStateManager<TCustom>
-): (args: TaskGetToolSchemaType) => ToolHandlerResponse<WorkflowTask | null> {
-  return (
-    args: TaskGetToolSchemaType
-  ): ToolHandlerResponse<WorkflowTask | null> => {
+): ToolHandler<TaskGetArgs, WorkflowTask | null> {
+  return (args) => {
     const task = stateManager.getTask(args.taskId) ?? null;
 
     if (!task) {

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

@@ -1,4 +1,5 @@
 import z from "zod";
+import type { ToolDefinition } from "../../lib/tool-router";
 
 export const taskGetTool = {
   name: "TaskGet" as const,
@@ -6,6 +7,6 @@ export const taskGetTool = {
   schema: z.object({
     taskId: z.string().describe("The ID of the task to get"),
   }),
-};
+} satisfies ToolDefinition;
 
-export type TaskGetToolSchemaType = z.infer<typeof taskGetTool.schema>;
+export type TaskGetArgs = z.infer<typeof taskGetTool.schema>;

package/src/tools/task-list/handler.ts

@@ -2,27 +2,22 @@ import type {
   AgentStateManager,
   JsonSerializable,
 } from "../../lib/state-manager";
-import type { ToolHandlerResponse } from "../../lib/tool-router";
+import type { ToolHandler } from "../../lib/tool-router";
 import type { WorkflowTask } from "../../lib/types";
-import type { TaskListToolSchemaType } from "./tool";
+import type { TaskListArgs } from "./tool";
 
 /**
  * Creates a TaskList handler that returns all tasks.
  *
  * @param stateManager - State manager containing tasks state
- * @returns A tool handler function
- *
- * @example
- * const handler = createTaskListHandler(stateManager);
+ * @returns A ToolHandler for TaskList tool calls
  */
 export function createTaskListHandler<
   TCustom extends JsonSerializable<TCustom>,
 >(
   stateManager: AgentStateManager<TCustom>
-): (args: TaskListToolSchemaType) => ToolHandlerResponse<WorkflowTask[]> {
-  return (
-    _args: TaskListToolSchemaType
-  ): ToolHandlerResponse<WorkflowTask[]> => {
+): ToolHandler<TaskListArgs, WorkflowTask[]> {
+  return () => {
     const taskList = stateManager.getTasks();
 
     return {

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

@@ -1,9 +1,10 @@
 import z from "zod";
+import type { ToolDefinition } from "../../lib/tool-router";
 
 export const taskListTool = {
   name: "TaskList" as const,
   description: `List all tasks with current state.`,
   schema: z.object({}),
-};
+} satisfies ToolDefinition;
 
-export type TaskListToolSchemaType = z.infer<typeof taskListTool.schema>;
+export type TaskListArgs = z.infer<typeof taskListTool.schema>;

package/src/tools/task-update/handler.ts

@@ -2,29 +2,22 @@ import type {
   AgentStateManager,
   JsonSerializable,
 } from "../../lib/state-manager";
-import type { ToolHandlerResponse } from "../../lib/tool-router";
+import type { ToolHandler } from "../../lib/tool-router";
 import type { WorkflowTask } from "../../lib/types";
-import type { TaskUpdateToolSchemaType } from "./tool";
+import type { TaskUpdateArgs } from "./tool";
 
 /**
  * Creates a TaskUpdate handler that modifies task status and dependencies.
  *
  * @param stateManager - State manager containing tasks state
- * @returns A tool handler function
- *
- * @example
- * const handler = createTaskUpdateHandler(stateManager);
+ * @returns A ToolHandler for TaskUpdate tool calls
  */
 export function createTaskUpdateHandler<
   TCustom extends JsonSerializable<TCustom>,
 >(
   stateManager: AgentStateManager<TCustom>
-): (
-  args: TaskUpdateToolSchemaType
-) => ToolHandlerResponse<WorkflowTask | null> {
-  return (
-    args: TaskUpdateToolSchemaType
-  ): ToolHandlerResponse<WorkflowTask | null> => {
+): ToolHandler<TaskUpdateArgs, WorkflowTask | null> {
+  return (args) => {
     const task = stateManager.getTask(args.taskId);
 
     if (!task) {

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

@@ -1,4 +1,5 @@
 import z from "zod";
+import type { ToolDefinition } from "../../lib/tool-router";
 
 export const taskUpdateTool = {
   name: "TaskUpdate" as const,
@@ -15,6 +16,6 @@ export const taskUpdateTool = {
       .array(z.string())
       .describe("The IDs of the tasks that this task is blocking"),
   }),
-};
+} satisfies ToolDefinition;
 
-export type TaskUpdateToolSchemaType = z.infer<typeof taskUpdateTool.schema>;
+export type TaskUpdateArgs = z.infer<typeof taskUpdateTool.schema>;

package/src/tools/{write → write-file}/tool.ts

@@ -1,11 +1,12 @@
 import { z } from "zod";
+import type { ToolDefinition } from "../../lib/tool-router";
 
 export const writeTool = {
   name: "FileWrite" as const,
   description: `Create or overwrite a file with new content.
 
 Usage:
-- Provide the absolute virtual path to the file
+- 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
 
@@ -15,12 +16,10 @@ IMPORTANT:
 - Path must be absolute (e.g., "/docs/readme.md", not "docs/readme.md")
 `,
   schema: z.object({
-    file_path: z
-      .string()
-      .describe("The absolute virtual path to the file to write"),
+    file_path: z.string().describe("The absolute path to the file to write"),
     content: z.string().describe("The content to write to the file"),
   }),
   strict: true,
-};
+} satisfies ToolDefinition;
 
-export type WriteToolSchemaType = z.infer<typeof writeTool.schema>;
+export type FileWriteArgs = z.infer<typeof writeTool.schema>;

package/src/workflow.ts

@@ -16,7 +16,7 @@
  */
 
 // Session
-export { createSession } from "./lib/session";
+export { createSession, proxyDefaultThreadOps } from "./lib/session";
 export type { ZeitlichSession, SessionLifecycleHooks } from "./lib/session";
 
 // State management
@@ -33,7 +33,12 @@ export type {
 } from "./lib/state-manager";
 
 // Tool router (includes registry functionality)
-export { createToolRouter, hasNoOtherToolCalls, defineTool, defineSubagent } from "./lib/tool-router";
+export {
+  createToolRouter,
+  hasNoOtherToolCalls,
+  defineTool,
+  defineSubagent,
+} from "./lib/tool-router";
 export type {
   // Tool definition types
   ToolDefinition,
@@ -68,6 +73,7 @@ export type {
   BaseAgentState,
   AgentFile,
   AgentResponse,
+  ThreadOps,
   ZeitlichAgentConfig,
   RunAgentConfig,
   RunAgentActivity,
@@ -95,12 +101,8 @@ export type {
 export { isTerminalStatus } from "./lib/types";
 
 // Subagent support
-export { createTaskTool } from "./tools/task/tool";
-export type {
-  TaskToolSchemaType,
-  GenericTaskToolSchemaType,
-} from "./tools/task/tool";
-export type { TaskHandlerResult } from "./tools/task/handler";
+export { createSubagentTool } from "./tools/subagent/tool";
+export type { SubagentArgs } from "./tools/subagent/tool";
 
 // Activity type interfaces (types only, no runtime code)
 // These are safe to import in workflows for typing proxyActivities
@@ -108,33 +110,34 @@ export type { ZeitlichSharedActivities } from "./activities";
 
 // Tool definitions (schemas only - no handlers)
 export { askUserQuestionTool } from "./tools/ask-user-question/tool";
-export type { AskUserQuestionToolSchemaType } from "./tools/ask-user-question/tool";
+export type { AskUserQuestionArgs } from "./tools/ask-user-question/tool";
 export { globTool } from "./tools/glob/tool";
-export type { GlobToolSchemaType } from "./tools/glob/tool";
+export type { GlobArgs } from "./tools/glob/tool";
 export { grepTool } from "./tools/grep/tool";
-export type { GrepToolSchemaType } from "./tools/grep/tool";
-export { readTool } from "./tools/read/tool";
-export type { ReadToolSchemaType } from "./tools/read/tool";
-export { writeTool } from "./tools/write/tool";
-export type { WriteToolSchemaType } from "./tools/write/tool";
+export type { GrepArgs } from "./tools/grep/tool";
+export { readTool } from "./tools/read-file/tool";
+export type { FileReadArgs } from "./tools/read-file/tool";
+export { writeTool } from "./tools/write-file/tool";
+export type { FileWriteArgs } from "./tools/write-file/tool";
 export { editTool } from "./tools/edit/tool";
-export type { EditToolSchemaType } from "./tools/edit/tool";
+export type { FileEditArgs } from "./tools/edit/tool";
 
 // Workflow task tools (state-only, no activities needed)
 export { taskCreateTool } from "./tools/task-create/tool";
-export type { TaskCreateToolSchemaType } from "./tools/task-create/tool";
+export type { TaskCreateArgs } from "./tools/task-create/tool";
 export { createTaskCreateHandler } from "./tools/task-create/handler";
 
 export { taskGetTool } from "./tools/task-get/tool";
-export type { TaskGetToolSchemaType } from "./tools/task-get/tool";
+export type { TaskGetArgs } from "./tools/task-get/tool";
 export { createTaskGetHandler } from "./tools/task-get/handler";
 
 export { taskListTool } from "./tools/task-list/tool";
+export type { TaskListArgs } from "./tools/task-list/tool";
 export { createTaskListHandler } from "./tools/task-list/handler";
 
 export { taskUpdateTool } from "./tools/task-update/tool";
-export type { TaskUpdateToolSchemaType } from "./tools/task-update/tool";
+export type { TaskUpdateArgs } from "./tools/task-update/tool";
 export { createTaskUpdateHandler } from "./tools/task-update/handler";
 
-export { bashTool } from "./tools/bash/tool";
-export type { bashToolSchemaType } from "./tools/bash/tool";
+export { bashTool, createBashToolDescription } from "./tools/bash/tool";
+export type { BashArgs } from "./tools/bash/tool";