zeitlich 0.2.3 → 0.2.4

package/src/lib/session.ts

@@ -7,12 +7,10 @@ import type {
   SessionEndHook,
   SessionExitReason,
 } from "./types";
-import type { StoredMessage } from "@langchain/core/messages";
 import { type AgentStateManager, type JsonSerializable } from "./state-manager";
 import {
   createToolRouter,
   type ParsedToolCallUnion,
-  type RawToolCall,
   type ToolMap,
 } from "./tool-router";
 
@@ -95,28 +93,19 @@ export const createSession = async <T extends ToolMap, M = unknown>({
           stateManager.incrementTurns();
           const currentTurn = stateManager.getTurns();
 
-          const { message, stopReason } = await runAgent({
+          const { message, rawToolCalls } = await runAgent({
             threadId,
             agentName,
             metadata,
           });
 
-          if (stopReason === "end_turn") {
-            stateManager.complete();
-            exitReason = "completed";
-            return message;
-          }
-
           // No tools configured - treat any non-end_turn as completed
-          if (!toolRouter.hasTools()) {
+          if (!toolRouter.hasTools() || rawToolCalls.length === 0) {
             stateManager.complete();
             exitReason = "completed";
             return message;
           }
 
-          const rawToolCalls: RawToolCall[] =
-            await threadOps.parseToolCalls(message);
-
           // Parse all tool calls uniformly through the router
           const parsedToolCalls: ParsedToolCallUnion<T>[] = [];
           for (const tc of rawToolCalls) {
@@ -176,7 +165,7 @@ export const createSession = async <T extends ToolMap, M = unknown>({
  */
 export function proxyDefaultThreadOps(
   options?: Parameters<typeof proxyActivities>[0]
-): ThreadOps<StoredMessage> {
+): ThreadOps {
   const activities = proxyActivities<ZeitlichSharedActivities>(
     options ?? {
       startToCloseTimeout: "30m",
@@ -194,6 +183,5 @@ export function proxyDefaultThreadOps(
     initializeThread: activities.initializeThread,
     appendHumanMessage: activities.appendHumanMessage,
     appendToolResult: activities.appendToolResult,
-    parseToolCalls: activities.parseToolCalls,
   };
 }

package/src/lib/tool-router.ts

@@ -9,11 +9,11 @@ import type {
   ToolHooks,
   ToolResultConfig,
 } from "./types";
-import type { TaskArgs } from "../tools/task/tool";
+import type { SubagentArgs } from "../tools/subagent/tool";
 
 import type { z } from "zod";
-import { createTaskTool } from "../tools/task/tool";
-import { createTaskHandler } from "../tools/task/handler";
+import { createSubagentTool } from "../tools/subagent/tool";
+import { createSubagentHandler } from "../tools/subagent/handler";
 
 export type { ToolMessageContent };
 
@@ -422,11 +422,11 @@ export function createToolRouter<T extends ToolMap>(
     }
 
     const resolveSubagentName = (args: unknown): string =>
-      (args as TaskArgs).subagent;
+      (args as SubagentArgs).subagent;
 
-    toolMap.set("Task", {
-      ...createTaskTool(options.subagents),
-      handler: createTaskHandler(options.subagents),
+    toolMap.set("Subagent", {
+      ...createSubagentTool(options.subagents),
+      handler: createSubagentHandler(options.subagents),
       ...(subagentHooksMap.size > 0 && {
         hooks: {
           onPreToolUse: async (ctx): Promise<PreToolUseHookResult> => {
@@ -912,7 +912,7 @@ export function defineSubagent<
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       | ((input: { prompt: string; context: TContext }) => Promise<any>);
     context: TContext;
-    hooks?: SubagentHooks<TaskArgs, z.infer<TResult>>;
+    hooks?: SubagentHooks<SubagentArgs, z.infer<TResult>>;
   }
 ): SubagentConfig<TResult>;
 // Without context — verifies workflow accepts { prompt }
@@ -920,7 +920,7 @@ export function defineSubagent<TResult extends z.ZodType = z.ZodType>(
   config: Omit<SubagentConfig<TResult>, "hooks" | "workflow"> & {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     workflow: string | ((input: { prompt: string }) => Promise<any>);
-    hooks?: SubagentHooks<TaskArgs, z.infer<TResult>>;
+    hooks?: SubagentHooks<SubagentArgs, z.infer<TResult>>;
   }
 ): SubagentConfig<TResult>;
 // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/src/lib/types.ts

@@ -54,7 +54,7 @@ export interface AgentFile {
  */
 export interface AgentResponse<M = StoredMessage> {
   message: M;
-  stopReason: string | null;
+  rawToolCalls: RawToolCall[];
   usage?: {
     input_tokens?: number;
     output_tokens?: number;
@@ -67,7 +67,7 @@ export interface AgentResponse<M = StoredMessage> {
  * Consumers provide these — typically by wrapping Temporal activities.
  * Use `proxyDefaultThreadOps()` for the default StoredMessage implementation.
  */
-export interface ThreadOps<M = StoredMessage> {
+export interface ThreadOps {
   /** Initialize an empty thread */
   initializeThread(threadId: string): Promise<void>;
   /** Append a human message to the thread */
@@ -77,8 +77,6 @@ export interface ThreadOps<M = StoredMessage> {
   ): Promise<void>;
   /** Append a tool result to the thread */
   appendToolResult(config: ToolResultConfig): Promise<void>;
-  /** Extract raw tool calls from a message */
-  parseToolCalls(message: M): Promise<RawToolCall[]>;
 }
 
 /**
@@ -92,7 +90,7 @@ export interface ZeitlichAgentConfig<T extends ToolMap, M = StoredMessage> {
   /** Workflow-specific runAgent activity (with tools pre-bound) */
   runAgent: RunAgentActivity<M>;
   /** Thread operations (initialize, append messages, parse tool calls) */
-  threadOps: ThreadOps<M>;
+  threadOps: ThreadOps;
   /** Tool router for processing tool calls (optional if agent has no tools) */
   tools?: T;
   /** Subagent configurations */
@@ -152,6 +150,10 @@ export interface ToolResultConfig {
 // Subagent Configuration
 // ============================================================================
 
+/** 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;
+
 /**
  * Configuration for a subagent that can be spawned by the parent workflow.
  *

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

@@ -1,26 +1,20 @@
 import { executeChild, workflowInfo, uuid4 } from "@temporalio/workflow";
 import type { ToolHandlerResponse } from "../../lib/tool-router";
-import type { SubagentConfig, SubagentInput } from "../../lib/types";
-import type { TaskArgs } from "./tool";
+import type {
+  InferSubagentResult,
+  SubagentConfig,
+  SubagentInput,
+} from "../../lib/types";
+import type { SubagentArgs } from "./tool";
 
 /**
- * Result from a task handler execution
- */
-export interface TaskHandlerResult<TResult = unknown> {
-  /** The validated result from the child workflow */
-  result: TResult;
-  /** The child workflow ID (for reference/debugging) */
-  childWorkflowId: string;
-}
-
-/**
- * Creates a Task tool handler that spawns child workflows for configured subagents.
+ * 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
  *
  * @example
- * const taskHandler = taskHandler([
+ * const subagentHandler = subagentHandler([
  *   {
  *     name: "researcher",
  *     description: "Researches topics",
@@ -29,13 +23,15 @@ export interface TaskHandlerResult<TResult = unknown> {
  *   },
  * ]);
  */
-export function createTaskHandler(subagents: SubagentConfig[]) {
+export function createSubagentHandler<
+  const T extends readonly SubagentConfig[],
+>(subagents: [...T]) {
   const { workflowId: parentWorkflowId, taskQueue: parentTaskQueue } =
     workflowInfo();
 
   return async (
-    args: TaskArgs
-  ): Promise<ToolHandlerResponse<TaskHandlerResult>> => {
+    args: SubagentArgs
+  ): Promise<ToolHandlerResponse<InferSubagentResult<T[number]> | null>> => {
     const config = subagents.find((s) => s.name === args.subagent);
 
     if (!config) {
@@ -58,28 +54,19 @@ export function createTaskHandler(subagents: SubagentConfig[]) {
       taskQueue: config.taskQueue ?? parentTaskQueue,
     };
 
-    const childResult =
+    const { toolResponse, data } =
       typeof config.workflow === "string"
         ? await executeChild(config.workflow, childOpts)
         : await executeChild(config.workflow, childOpts);
 
     // Validate result if schema provided, otherwise pass through as-is
-    const validated = config.resultSchema
-      ? config.resultSchema.parse(childResult)
-      : childResult;
-
-    // Format content - stringify objects, pass strings through
-    const toolResponse =
-      typeof validated === "string"
-        ? validated
-        : JSON.stringify(validated, null, 2);
+    const validated = (
+      config.resultSchema ? config.resultSchema.parse(data) : null
+    ) as InferSubagentResult<T[number]> | null;
 
     return {
       toolResponse,
-      data: {
-        result: validated,
-        childWorkflowId,
-      },
+      data: validated,
     };
   };
 }

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,9 +80,9 @@ export function createTaskTool<T extends SubagentConfig[]>(
 }
 
 /**
- * Task tool args type (when subagent names are not known at compile time)
+ * Subagent tool args type (when subagent names are not known at compile time)
  */
-export type TaskArgs = {
+export type SubagentArgs = {
   subagent: string;
   description: string;
   prompt: string;

package/src/workflow.ts

@@ -101,9 +101,8 @@ export type {
 export { isTerminalStatus } from "./lib/types";
 
 // Subagent support
-export { createTaskTool } from "./tools/task/tool";
-export type { TaskArgs } 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