zeitlich 0.2.4 → 0.2.6

package/src/lib/model-invoker.ts

@@ -23,10 +23,11 @@ export interface InvokeModelConfig {
 /**
  * Core model invocation logic - shared utility for workflow-specific activities
  *
- * @param redis - Redis client for thread management
- * @param config - Model invocation configuration
- * @param model - Pre-instantiated LangChain chat model
- * @param invocationConfig - Per-invocation configuration (system prompt, etc.)
+ * @param options - Named options object
+ * @param options.redis - Redis client for thread management
+ * @param options.config - Model invocation configuration (threadId, agentName)
+ * @param options.model - Pre-instantiated LangChain chat model
+ * @param options.client - Temporal WorkflowClient for querying workflow state
  * @returns Agent response with message and metadata
  */
 export async function invokeModel({

package/src/lib/session.ts

@@ -42,10 +42,18 @@ export const createSession = async <T extends ToolMap, M = unknown>({
   tools = {} as T,
   processToolsInParallel = true,
   hooks = {},
+  appendSystemPrompt = true,
+  systemPrompt,
 }: ZeitlichAgentConfig<T, M>): Promise<ZeitlichSession<M>> => {
+  const {
+    appendToolResult,
+    appendHumanMessage,
+    initializeThread,
+    appendSystemMessage,
+  } = threadOps ?? proxyDefaultThreadOps();
   const toolRouter = createToolRouter({
     tools,
-    appendToolResult: threadOps.appendToolResult,
+    appendToolResult,
     threadId,
     hooks,
     subagents,
@@ -77,10 +85,14 @@ export const createSession = async <T extends ToolMap, M = unknown>({
           metadata,
         });
       }
+
       stateManager.setTools(toolRouter.getToolDefinitions());
 
-      await threadOps.initializeThread(threadId);
-      await threadOps.appendHumanMessage(threadId, await buildContextMessage());
+      await initializeThread(threadId);
+      if (appendSystemPrompt && systemPrompt && systemPrompt.trim() !== "") {
+        await appendSystemMessage(threadId, systemPrompt);
+      }
+      await appendHumanMessage(threadId, await buildContextMessage());
 
       let exitReason: SessionExitReason = "completed";
 
@@ -112,7 +124,7 @@ export const createSession = async <T extends ToolMap, M = unknown>({
             try {
               parsedToolCalls.push(toolRouter.parseToolCall(tc));
             } catch (error) {
-              await threadOps.appendToolResult({
+              await appendToolResult({
                 threadId,
                 toolCallId: tc.id ?? "",
                 toolName: tc.name,
@@ -183,5 +195,6 @@ export function proxyDefaultThreadOps(
     initializeThread: activities.initializeThread,
     appendHumanMessage: activities.appendHumanMessage,
     appendToolResult: activities.appendToolResult,
+    appendSystemMessage: activities.appendSystemMessage,
   };
 }

package/src/lib/thread-manager.ts

@@ -7,6 +7,7 @@ import {
   type MessageContent,
   type MessageStructure,
   type StoredMessage,
+  SystemMessage,
   ToolMessage,
 } from "@langchain/core/messages";
 import { v4 as uuidv4 } from "uuid";
@@ -50,21 +51,20 @@ export interface BaseThreadManager<T> {
 export interface ThreadManager extends BaseThreadManager<StoredMessage> {
   /** Create a HumanMessage (returns StoredMessage for storage) */
   createHumanMessage(content: string | MessageContent): StoredMessage;
-
   /** Create an AIMessage with optional additional kwargs */
   createAIMessage(
     content: string | MessageContent,
     kwargs?: { header?: string; options?: string[]; multiSelect?: boolean }
   ): StoredMessage;
-
   /** Create a ToolMessage */
   createToolMessage(
     content: ToolMessageContent,
     toolCallId: string
   ): StoredMessage;
-
   /** Create and append a HumanMessage */
   appendHumanMessage(content: string | MessageContent): Promise<void>;
+  /** Create and append a SystemMessage */
+  appendSystemMessage(content: string): Promise<void>;
   /** Create and append a ToolMessage */
   appendToolMessage(
     content: ToolMessageContent,
@@ -127,6 +127,13 @@ export function createThreadManager<T>(
       }).toDict();
     },
 
+    createSystemMessage(content: string): StoredMessage {
+      return new SystemMessage({
+        id: uuidv4(),
+        content: content as string,
+      }).toDict();
+    },
+
     createAIMessage(
       content: string,
       kwargs?: { header?: string; options?: string[]; multiSelect?: boolean }
@@ -171,6 +178,11 @@ export function createThreadManager<T>(
       const message = helpers.createAIMessage(content as string);
       await (base as BaseThreadManager<StoredMessage>).append([message]);
     },
+
+    async appendSystemMessage(content: string): Promise<void> {
+      const message = helpers.createSystemMessage(content);
+      await (base as BaseThreadManager<StoredMessage>).append([message]);
+    },
   };
 
   return Object.assign(base, helpers);

package/src/lib/tool-router.ts

@@ -415,37 +415,42 @@ export function createToolRouter<T extends ToolMap>(
   const isEnabled = (tool: ToolMap[string]): boolean => tool.enabled !== false;
 
   if (options.subagents) {
-    // Build per-subagent hook dispatcher keyed by subagent name
-    const subagentHooksMap = new Map<string, SubagentHooks>();
-    for (const s of options.subagents) {
-      if (s.hooks) subagentHooksMap.set(s.name, s.hooks);
-    }
+    const enabledSubagents = options.subagents.filter(
+      (s) => s.enabled !== false
+    );
+    if (enabledSubagents.length > 0) {
+      // Build per-subagent hook dispatcher keyed by subagent name
+      const subagentHooksMap = new Map<string, SubagentHooks>();
+      for (const s of enabledSubagents) {
+        if (s.hooks) subagentHooksMap.set(s.agentName, s.hooks);
+      }
 
-    const resolveSubagentName = (args: unknown): string =>
-      (args as SubagentArgs).subagent;
-
-    toolMap.set("Subagent", {
-      ...createSubagentTool(options.subagents),
-      handler: createSubagentHandler(options.subagents),
-      ...(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,
-      }),
-    });
+      const resolveSubagentName = (args: unknown): string =>
+        (args as SubagentArgs).subagent;
+
+      toolMap.set("Subagent", {
+        ...createSubagentTool(enabledSubagents),
+        handler: createSubagentHandler(enabledSubagents),
+        ...(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,
+        }),
+      });
+    }
   }
 
   async function processToolCall(
@@ -837,7 +842,11 @@ export function withAutoAppend<
     });
 
     // Return with empty toolResponse to keep the Temporal payload small
-    return { toolResponse: "", data: response.data, resultAppended: true };
+    return {
+      toolResponse: "Response appended via withAutoAppend",
+      data: response.data,
+      resultAppended: true,
+    };
   };
 }
 

package/src/lib/types.ts

@@ -77,6 +77,8 @@ export interface ThreadOps {
   ): Promise<void>;
   /** Append a tool result to the thread */
   appendToolResult(config: ToolResultConfig): Promise<void>;
+  /** Append a system message to the thread */
+  appendSystemMessage(threadId: string, content: string): Promise<void>;
 }
 
 /**
@@ -85,12 +87,16 @@ export interface ThreadOps {
 export interface ZeitlichAgentConfig<T extends ToolMap, M = StoredMessage> {
   threadId: string;
   agentName: string;
+  /** Description, used for sub agents */
+  description?: string;
+  systemPrompt?: string;
   metadata?: Record<string, unknown>;
+  appendSystemPrompt?: boolean;
   maxTurns?: number;
   /** Workflow-specific runAgent activity (with tools pre-bound) */
   runAgent: RunAgentActivity<M>;
   /** Thread operations (initialize, append messages, parse tool calls) */
-  threadOps: ThreadOps;
+  threadOps?: ThreadOps;
   /** Tool router for processing tool calls (optional if agent has no tools) */
   tools?: T;
   /** Subagent configurations */
@@ -161,9 +167,11 @@ export type InferSubagentResult<T extends SubagentConfig> =
  */
 export interface SubagentConfig<TResult extends z.ZodType = z.ZodType> {
   /** Identifier used in Task tool's subagent parameter */
-  name: string;
+  agentName: string;
   /** 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;
   /** Temporal workflow function or type name (used with executeChild) */
   workflow: string | Workflow;
   /** Optional task queue - defaults to parent's queue if not specified */

package/src/tools/subagent/handler.ts

@@ -26,21 +26,20 @@ import type { SubagentArgs } from "./tool";
 export function createSubagentHandler<
   const T extends readonly SubagentConfig[],
 >(subagents: [...T]) {
-  const { workflowId: parentWorkflowId, taskQueue: parentTaskQueue } =
-    workflowInfo();
+  const { taskQueue: parentTaskQueue } = workflowInfo();
 
   return async (
     args: SubagentArgs
   ): Promise<ToolHandlerResponse<InferSubagentResult<T[number]> | null>> => {
-    const config = subagents.find((s) => s.name === args.subagent);
+    const config = subagents.find((s) => s.agentName === args.subagent);
 
     if (!config) {
       throw new Error(
-        `Unknown subagent: ${args.subagent}. Available: ${subagents.map((s) => s.name).join(", ")}`
+        `Unknown subagent: ${args.subagent}. Available: ${subagents.map((s) => s.agentName).join(", ")}`
       );
     }
 
-    const childWorkflowId = `${parentWorkflowId}-${args.subagent}-${uuid4()}`;
+    const childWorkflowId = `${args.subagent}-${uuid4()}`;
 
     // Execute the child workflow
     const input: SubagentInput = {

package/src/tools/subagent/tool.ts

@@ -8,7 +8,7 @@ const SUBAGENT_TOOL = "Subagent" as const;
  */
 function buildSubagentDescription(subagents: SubagentConfig[]): string {
   const subagentList = subagents
-    .map((s) => `- **${s.name}**: ${s.description}`)
+    .map((s) => `- **${s.agentName}**: ${s.description}`)
     .join("\n");
 
   return `Launch a new agent to handle complex tasks autonomously.
@@ -42,7 +42,7 @@ Usage notes:
  * @example
  * const subagentTool = createSubagentTool([
  *   {
- *     name: "researcher",
+ *     agentName: "researcher",
  *     description: "Researches topics and gathers information",
  *     workflow: "researcherWorkflow",
  *     resultSchema: z.object({ findings: z.string() }),
@@ -64,7 +64,7 @@ export function createSubagentTool<T extends SubagentConfig[]>(
     throw new Error("createTaskTool requires at least one subagent");
   }
 
-  const names = subagents.map((s) => s.name);
+  const names = subagents.map((s) => s.agentName);
 
   return {
     name: SUBAGENT_TOOL,

package/src/workflow.ts

@@ -1,7 +1,7 @@
 /**
  * Workflow-safe exports for use in Temporal workflow code.
  *
- * Import from '@bead-ai/zeitlich/workflow' in workflow files.
+ * Import from 'zeitlich/workflow' in workflow files.
  * These exports have no external dependencies (no Redis, no LangChain).
  *
  * @example
@@ -11,7 +11,7 @@
  *   createSession,
  *   createAgentStateManager,
  *   createToolRouter,
- * } from '@bead-ai/zeitlich/workflow';
+ * } from 'zeitlich/workflow';
  * ```
  */