zeitlich 0.2.13 → 0.2.14

package/src/lib/skills/tool.ts

@@ -0,0 +1,47 @@
+import z from "zod";
+import type { Skill } from "./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/lib/state/index.ts

@@ -0,0 +1,9 @@
+export { createAgentStateManager } from "./manager";
+
+export type {
+  JsonPrimitive,
+  JsonValue,
+  JsonSerializable,
+  AgentState,
+  AgentStateManager,
+} from "./types";

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

@@ -3,152 +3,17 @@ import {
   defineQuery,
   defineUpdate,
   setHandler,
-  type QueryDefinition,
 } from "@temporalio/workflow";
-import type { UpdateDefinition } from "@temporalio/common/lib/interfaces";
 import {
   type AgentStatus,
   type BaseAgentState,
   type WorkflowTask,
   isTerminalStatus,
-  agentQueryName,
-  agentStateChangeUpdateName,
-} from "./types";
-import type { ToolDefinition } from "./tool-router";
+} from "../types";
+import type { ToolDefinition } from "../tool-router/types";
+import type { AgentState, AgentStateManager, JsonSerializable } from "./types";
 import { z } from "zod";
 
-/**
- * JSON primitive types that Temporal can serialize
- */
-export type JsonPrimitive = string | number | boolean | null | undefined;
-
-/**
- * JSON-serializable value (recursive type for Temporal compatibility)
- */
-export type JsonValue =
-  | JsonPrimitive
-  | JsonValue[]
-  | { [key: string]: JsonValue };
-
-/**
- * Type constraint ensuring T only contains JSON-serializable values.
- * Use this for custom state to ensure Temporal workflow compatibility.
- *
- * Allows: primitives, arrays, plain objects, and JsonValue
- * Rejects: functions, symbols, undefined, class instances with methods
- */
-export type JsonSerializable<T> = {
-  [K in keyof T]: T[K] extends JsonValue
-    ? T[K]
-    : T[K] extends JsonPrimitive
-      ? T[K]
-      : T[K] extends (infer U)[]
-        ? U extends JsonValue
-          ? T[K]
-          : JsonSerializable<U>[]
-        : T[K] extends object
-          ? JsonSerializable<T[K]>
-          : never;
-};
-
-/**
- * Full state type combining base state with custom state
- */
-export type AgentState<TCustom extends JsonSerializable<TCustom>> =
-  BaseAgentState & TCustom;
-
-/**
- * Agent state manager interface
- * Note: Temporal handlers must be set up in the workflow file due to
- * Temporal's workflow isolation requirements. This manager provides
- * the state and helpers needed for those handlers.
- */
-export interface AgentStateManager<TCustom extends JsonSerializable<TCustom>> {
-  /** Typed query definition registered for this agent's state */
-  readonly stateQuery: QueryDefinition<AgentState<TCustom>>;
-  /** Typed update definition registered for waiting on this agent's state change */
-  readonly stateChangeUpdate: UpdateDefinition<AgentState<TCustom>, [number]>;
-
-  /** Get current status */
-  getStatus(): AgentStatus;
-  /** Check if agent is running */
-  isRunning(): boolean;
-  /** Check if agent is in terminal state */
-  isTerminal(): boolean;
-  /** Get current state version */
-  getVersion(): number;
-
-  /** Set status to RUNNING */
-  run(): void;
-  /** Set status to WAITING_FOR_INPUT */
-  waitForInput(): void;
-  /** Set status to COMPLETED */
-  complete(): void;
-  /** Set status to FAILED */
-  fail(): void;
-  /** Set status to CANCELLED */
-  cancel(): void;
-
-  /** Increment state version (call after state changes) */
-  incrementVersion(): void;
-
-  /** Increment turns (call after each turn) */
-  incrementTurns(): void;
-
-  /** Get current turns */
-  getTurns(): number;
-
-  /** Get the system prompt */
-  getSystemPrompt(): string | undefined;
-
-  /** Set the system prompt */
-  setSystemPrompt(newSystemPrompt: string): void;
-
-  /** Get a custom state value by key */
-  get<K extends keyof TCustom>(key: K): TCustom[K];
-
-  /** Set a custom state value by key */
-  set<K extends keyof TCustom>(key: K, value: TCustom[K]): void;
-
-  /** Get full state for query handler */
-  getCurrentState(): AgentState<TCustom>;
-
-  /** Check if should return from waitForStateChange */
-  shouldReturnFromWait(lastKnownVersion: number): boolean;
-
-  // Task management methods
-  /** Get all tasks */
-  getTasks(): WorkflowTask[];
-  /** Get a task by ID */
-  getTask(id: string): WorkflowTask | undefined;
-  /** Add or update a task */
-  setTask(task: WorkflowTask): void;
-  /** Delete a task by ID */
-  deleteTask(id: string): boolean;
-
-  /** Set the tools (converts Zod schemas to JSON Schema for serialization) */
-  setTools(newTools: ToolDefinition[]): void;
-
-  /** Update the usage */
-  updateUsage(usage: {
-    inputTokens?: number;
-    outputTokens?: number;
-    cachedWriteTokens?: number;
-    cachedReadTokens?: number;
-    reasonTokens?: number;
-  }): void;
-
-  /** Get the total usage */
-  getTotalUsage(): {
-    totalInputTokens: number;
-    totalOutputTokens: number;
-    totalCachedWriteTokens: number;
-    totalCachedReadTokens: number;
-    totalReasonTokens: number;
-    turns: number;
-  };
-}
-
 /**
  * Creates an agent state manager for tracking workflow state.
  * Automatically registers Temporal query and update handlers for the agent.
@@ -181,12 +46,9 @@ export function createAgentStateManager<
   TCustom extends JsonSerializable<TCustom> = Record<string, never>,
 >({
   initialState,
-  agentName,
 }: {
   initialState?: Partial<BaseAgentState> & TCustom;
-  agentName: string;
 }): AgentStateManager<TCustom> {
-  // Default state (BaseAgentState fields)
   let status: AgentStatus = initialState?.status ?? "RUNNING";
   let version = initialState?.version ?? 0;
   let turns = initialState?.turns ?? 0;
@@ -198,10 +60,8 @@ export function createAgentStateManager<
   let totalReasonTokens = 0;
   let systemPrompt = initialState?.systemPrompt;
 
-  // Tasks state
   const tasks = new Map<string, WorkflowTask>(initialState?.tasks);
 
-  // Custom state - extract only custom fields (exclude base state keys)
   const {
     status: _,
     version: __,
@@ -222,11 +82,9 @@ export function createAgentStateManager<
     } as AgentState<TCustom>;
   }
 
-  const stateQuery = defineQuery<AgentState<TCustom>>(
-    agentQueryName(agentName)
-  );
+  const stateQuery = defineQuery<AgentState<TCustom>>("getAgentState");
   const stateChangeUpdate = defineUpdate<AgentState<TCustom>, [number]>(
-    agentStateChangeUpdateName(agentName)
+    "waitForAgentStateChange"
   );
 
   setHandler(stateQuery, () => buildState());
@@ -308,6 +166,11 @@ export function createAgentStateManager<
       version++;
     },
 
+    mergeUpdate(update: Partial<TCustom>): void {
+      Object.assign(customState as object, update);
+      version++;
+    },
+
     getCurrentState(): AgentState<TCustom> {
       return buildState();
     },

package/src/lib/state/types.ts

@@ -0,0 +1,134 @@
+import type {
+  QueryDefinition,
+} from "@temporalio/workflow";
+import type { UpdateDefinition } from "@temporalio/common/lib/interfaces";
+import type { AgentStatus, BaseAgentState, TokenUsage, WorkflowTask } from "../types";
+import type { ToolDefinition } from "../tool-router/types";
+
+/**
+ * JSON primitive types that Temporal can serialize
+ */
+export type JsonPrimitive = string | number | boolean | null | undefined;
+
+/**
+ * JSON-serializable value (recursive type for Temporal compatibility)
+ */
+export type JsonValue =
+  | JsonPrimitive
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+/**
+ * Type constraint ensuring T only contains JSON-serializable values.
+ * Use this for custom state to ensure Temporal workflow compatibility.
+ *
+ * Allows: primitives, arrays, plain objects, and JsonValue
+ * Rejects: functions, symbols, undefined, class instances with methods
+ */
+export type JsonSerializable<T> = {
+  [K in keyof T]: T[K] extends JsonValue
+    ? T[K]
+    : T[K] extends JsonPrimitive
+      ? T[K]
+      : T[K] extends (infer U)[]
+        ? U extends JsonValue
+          ? T[K]
+          : JsonSerializable<U>[]
+        : T[K] extends object
+          ? JsonSerializable<T[K]>
+          : never;
+};
+
+/**
+ * Full state type combining base state with custom state
+ */
+export type AgentState<TCustom extends JsonSerializable<TCustom>> =
+  BaseAgentState & TCustom;
+
+/**
+ * Agent state manager interface
+ * Note: Temporal handlers must be set up in the workflow file due to
+ * Temporal's workflow isolation requirements. This manager provides
+ * the state and helpers needed for those handlers.
+ */
+export interface AgentStateManager<TCustom extends JsonSerializable<TCustom>> {
+  /** Typed query definition registered for this agent's state */
+  readonly stateQuery: QueryDefinition<AgentState<TCustom>>;
+  /** Typed update definition registered for waiting on this agent's state change */
+  readonly stateChangeUpdate: UpdateDefinition<AgentState<TCustom>, [number]>;
+
+  /** Get current status */
+  getStatus(): AgentStatus;
+  /** Check if agent is running */
+  isRunning(): boolean;
+  /** Check if agent is in terminal state */
+  isTerminal(): boolean;
+  /** Get current state version */
+  getVersion(): number;
+
+  /** Set status to RUNNING */
+  run(): void;
+  /** Set status to WAITING_FOR_INPUT */
+  waitForInput(): void;
+  /** Set status to COMPLETED */
+  complete(): void;
+  /** Set status to FAILED */
+  fail(): void;
+  /** Set status to CANCELLED */
+  cancel(): void;
+
+  /** Increment state version (call after state changes) */
+  incrementVersion(): void;
+
+  /** Increment turns (call after each turn) */
+  incrementTurns(): void;
+
+  /** Get current turns */
+  getTurns(): number;
+
+  /** Get the system prompt */
+  getSystemPrompt(): string | undefined;
+
+  /** Set the system prompt */
+  setSystemPrompt(newSystemPrompt: string): void;
+
+  /** Get a custom state value by key */
+  get<K extends keyof TCustom>(key: K): TCustom[K];
+
+  /** Set a custom state value by key */
+  set<K extends keyof TCustom>(key: K, value: TCustom[K]): void;
+
+  /** Bulk-merge a partial update into custom state (e.g. from sandbox stateUpdate) */
+  mergeUpdate(update: Partial<TCustom>): void;
+
+  /** Get full state for query handler */
+  getCurrentState(): AgentState<TCustom>;
+
+  /** Check if should return from waitForStateChange */
+  shouldReturnFromWait(lastKnownVersion: number): boolean;
+
+  /** Get all tasks */
+  getTasks(): WorkflowTask[];
+  /** Get a task by ID */
+  getTask(id: string): WorkflowTask | undefined;
+  /** Add or update a task */
+  setTask(task: WorkflowTask): void;
+  /** Delete a task by ID */
+  deleteTask(id: string): boolean;
+
+  /** Set the tools (converts Zod schemas to JSON Schema for serialization) */
+  setTools(newTools: ToolDefinition[]): void;
+
+  /** Update the usage */
+  updateUsage(usage: TokenUsage): void;
+
+  /** Get the total usage */
+  getTotalUsage(): {
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalCachedWriteTokens: number;
+    totalCachedReadTokens: number;
+    totalReasonTokens: number;
+    turns: number;
+  };
+}

package/src/lib/subagent/define.ts

@@ -0,0 +1,71 @@
+import type { z } from "zod";
+import type {
+  SubagentConfig,
+  SubagentHandlerResponse,
+  SubagentHooks,
+} from "./types";
+import type { SubagentArgs } from "./tool";
+
+/**
+ * Identity function that provides full type inference for subagent configurations.
+ * Verifies the workflow function's input parameters match the configured context,
+ * and properly types the lifecycle hooks with Task tool args and inferred result type.
+ *
+ * @example
+ * ```ts
+ * // With typed context — workflow must accept { prompt, context }
+ * const researcher = defineSubagent({
+ *   name: "researcher",
+ *   description: "Researches topics",
+ *   workflow: researcherWorkflow, // (input: { prompt: string; context: { apiKey: string } }) => Promise<...>
+ *   context: { apiKey: "..." },
+ *   resultSchema: z.object({ findings: z.string() }),
+ *   hooks: {
+ *     onPostExecution: ({ result }) => {
+ *       // result is typed as { findings: string }
+ *     },
+ *   },
+ * });
+ *
+ * // Without context — workflow only needs { prompt }
+ * const writer = defineSubagent({
+ *   name: "writer",
+ *   description: "Writes content",
+ *   workflow: writerWorkflow, // (input: { prompt: string }) => Promise<...>
+ *   resultSchema: z.object({ content: z.string() }),
+ * });
+ * ```
+ */
+// With context — verifies workflow accepts { prompt, context: TContext }
+export function defineSubagent<
+  TResult extends z.ZodType = z.ZodType,
+  TContext extends Record<string, unknown> = Record<string, unknown>,
+>(
+  config: Omit<SubagentConfig<TResult>, "hooks" | "workflow" | "context"> & {
+    workflow:
+      | string
+      | ((input: {
+          prompt: string;
+          previousThreadId?: string;
+          context: TContext;
+        }) => Promise<SubagentHandlerResponse<z.infer<TResult> | null>>);
+    context: TContext;
+    hooks?: SubagentHooks<SubagentArgs, z.infer<TResult>>;
+  }
+): SubagentConfig<TResult>;
+// Without context — verifies workflow accepts { prompt }
+export function defineSubagent<TResult extends z.ZodType = z.ZodType>(
+  config: Omit<SubagentConfig<TResult>, "hooks" | "workflow"> & {
+    workflow:
+      | string
+      | ((input: {
+          prompt: string;
+          previousThreadId?: string;
+        }) => Promise<SubagentHandlerResponse<z.infer<TResult> | null>>);
+    hooks?: SubagentHooks<SubagentArgs, z.infer<TResult>>;
+  }
+): SubagentConfig<TResult>;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function defineSubagent(config: any): SubagentConfig {
+  return config;
+}

package/src/lib/subagent/handler.ts

@@ -0,0 +1,99 @@
+import { executeChild, workflowInfo } from "@temporalio/workflow";
+import { getShortId } from "../thread/id";
+import type { ToolHandlerResponse, RouterContext } from "../tool-router";
+import type { ToolMessageContent } from "../types";
+import type {
+  InferSubagentResult,
+  SubagentConfig,
+  SubagentInput,
+} from "./types";
+import type { SubagentArgs } from "./tool";
+import type { z } from "zod";
+
+/**
+ * Creates a Subagent tool handler that spawns child workflows for configured subagents.
+ *
+ * @param subagents - Array of subagent configurations
+ * @returns A tool handler function that can be used with the tool router
+ */
+export function createSubagentHandler<
+  const T extends readonly SubagentConfig[],
+>(subagents: [...T]) {
+  const { taskQueue: parentTaskQueue } = workflowInfo();
+
+  return async (
+    args: SubagentArgs,
+    context: RouterContext
+  ): Promise<ToolHandlerResponse<InferSubagentResult<T[number]> | null>> => {
+    const config = subagents.find((s) => s.agentName === args.subagent);
+
+    if (!config) {
+      throw new Error(
+        `Unknown subagent: ${args.subagent}. Available: ${subagents.map((s) => s.agentName).join(", ")}`
+      );
+    }
+
+    const childWorkflowId = `${args.subagent}-${getShortId()}`;
+
+    const { sandboxId: parentSandboxId } = context;
+    const inheritSandbox = config.sandbox !== "own" && !!parentSandboxId;
+
+    const input: SubagentInput = {
+      prompt: args.prompt,
+      ...(config.context && { context: config.context }),
+      ...(args.threadId &&
+        args.threadId !== null &&
+        config.allowThreadContinuation && { previousThreadId: args.threadId }),
+      ...(inheritSandbox && { sandboxId: parentSandboxId }),
+    };
+
+    const childOpts = {
+      workflowId: childWorkflowId,
+      args: [input] as const,
+      taskQueue: config.taskQueue ?? parentTaskQueue,
+    };
+
+    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 }),
+      };
+    }
+
+    const validated = (
+      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: finalToolResponse,
+      data: validated ? validated.data : data,
+      ...(usage && { usage }),
+    };
+  };
+}

package/src/lib/subagent/index.ts

@@ -0,0 +1,13 @@
+export type {
+  SubagentConfig,
+  SubagentHooks,
+  SubagentInput,
+  SubagentHandlerResponse,
+  SubagentWorkflow,
+  InferSubagentResult,
+} from "./types";
+export { createSubagentTool, SUBAGENT_TOOL_NAME } from "./tool";
+export type { SubagentArgs } from "./tool";
+export { createSubagentHandler } from "./handler";
+export { defineSubagent } from "./define";
+export { buildSubagentRegistration } from "./register";

package/src/lib/subagent/register.ts

@@ -0,0 +1,53 @@
+import type {
+  PreToolUseHookResult,
+  PostToolUseFailureHookResult,
+  ToolHooks,
+  ToolMap,
+} from "../tool-router/types";
+import type { SubagentConfig, SubagentHooks } from "./types";
+import { createSubagentTool, type SubagentArgs } from "./tool";
+import { createSubagentHandler } from "./handler";
+
+/**
+ * Builds a fully wired tool entry for the Subagent tool,
+ * including per-subagent hook delegation.
+ *
+ * Returns null if no enabled subagents are configured.
+ */
+export function buildSubagentRegistration(
+  subagents: SubagentConfig[]
+): ToolMap[string] | null {
+  const enabled = subagents.filter((s) => s.enabled ?? true);
+  if (enabled.length === 0) return null;
+
+  const subagentHooksMap = new Map<string, SubagentHooks>();
+  for (const s of enabled) {
+    if (s.hooks) subagentHooksMap.set(s.agentName, s.hooks);
+  }
+
+  const resolveSubagentName = (args: unknown): string =>
+    (args as SubagentArgs).subagent;
+
+  return {
+    ...createSubagentTool(enabled),
+    handler: createSubagentHandler(enabled),
+    ...(subagentHooksMap.size > 0 && {
+      hooks: {
+        onPreToolUse: async (ctx): Promise<PreToolUseHookResult> => {
+          const hooks = subagentHooksMap.get(resolveSubagentName(ctx.args));
+          return hooks?.onPreExecution?.(ctx) ?? {};
+        },
+        onPostToolUse: async (ctx): Promise<void> => {
+          const hooks = subagentHooksMap.get(resolveSubagentName(ctx.args));
+          await hooks?.onPostExecution?.(ctx);
+        },
+        onPostToolUseFailure: async (
+          ctx
+        ): Promise<PostToolUseFailureHookResult> => {
+          const hooks = subagentHooksMap.get(resolveSubagentName(ctx.args));
+          return hooks?.onExecutionFailure?.(ctx) ?? {};
+        },
+      } satisfies ToolHooks,
+    }),
+  };
+}