zeitlich 0.2.17 → 0.2.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zeitlich",
-  "version": "0.2.17",
+  "version": "0.2.19",
   "description": "[EXPERIMENTAL] An opinionated AI agent implementation for Temporal",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/src/lib/subagent/define.ts

@@ -40,7 +40,7 @@ export function defineSubagent<
   overrides?: {
     context?: TContext;
     hooks?: SubagentHooks<SubagentArgs, z.infer<TResult>>;
-    enabled?: boolean;
+    enabled?: boolean | (() => boolean);
     taskQueue?: string;
     allowThreadContinuation?: boolean;
     sandbox?: "inherit" | "own";

package/src/lib/subagent/register.ts

@@ -13,9 +13,9 @@ import { createSubagentHandler } from "./handler";
  * Builds a fully wired tool entry for the Subagent tool,
  * including per-subagent hook delegation.
  *
- * Uses getters for `enabled`, `description`, and `schema` so that
- * dynamic changes to SubagentConfig.enabled are re-evaluated each
- * time getToolDefinitions() is called.
+ * Lazily evaluates `enabled` (supports `boolean | () => boolean`)
+ * so that `description` and `schema` reflect the current set of
+ * active subagents each time getToolDefinitions() is called.
  *
  * Returns null if no subagents are configured.
  */
@@ -24,7 +24,10 @@ export function buildSubagentRegistration(
 ): ToolMap[string] | null {
   if (subagents.length === 0) return null;
 
-  const getEnabled = (): SubagentConfig[] => subagents.filter((s) => s.enabled ?? true);
+  const getEnabled = (): SubagentConfig[] =>
+    subagents.filter((s) =>
+      typeof s.enabled === "function" ? s.enabled() : (s.enabled ?? true),
+    );
 
   const subagentHooksMap = new Map<string, SubagentHooks>();
   for (const s of subagents) {
@@ -36,15 +39,9 @@ export function buildSubagentRegistration(
 
   return {
     name: SUBAGENT_TOOL_NAME,
-    get enabled(): boolean {
-      return getEnabled().length > 0;
-    },
-    get description(): string {
-      return createSubagentTool(getEnabled()).description;
-    },
-    get schema(): z.ZodObject<z.ZodRawShape> {
-      return createSubagentTool(getEnabled()).schema;
-    },
+    enabled: (): boolean => getEnabled().length > 0,
+    description: (): string => createSubagentTool(getEnabled()).description,
+    schema: (): z.ZodObject<z.ZodRawShape> => createSubagentTool(getEnabled()).schema,
     handler: createSubagentHandler(subagents),
     ...(subagentHooksMap.size > 0 && {
       hooks: {

package/src/lib/subagent/subagent.integration.test.ts

@@ -5,19 +5,21 @@ vi.mock("@temporalio/workflow", () => {
   let counter = 0;
   return {
     workflowInfo: () => ({ taskQueue: "default-queue" }),
-    executeChild: vi.fn(async (_workflow: unknown, opts: { args: unknown[] }) => {
-      const prompt = (opts.args as [string])[0];
-      return {
-        toolResponse: `Response to: ${prompt}`,
-        data: { result: "child-data" },
-        threadId: "child-thread-1",
-        usage: { inputTokens: 100, outputTokens: 50 },
-      };
-    }),
+    executeChild: vi.fn(
+      async (_workflow: unknown, opts: { args: unknown[] }) => {
+        const prompt = (opts.args as [string])[0];
+        return {
+          toolResponse: `Response to: ${prompt}`,
+          data: { result: "child-data" },
+          threadId: "child-thread-1",
+          usage: { inputTokens: 100, outputTokens: 50 },
+        };
+      }
+    ),
     uuid4: () => {
       counter++;
       const bytes = Array.from({ length: 16 }, (_, i) =>
-        ((counter * 31 + i * 7) & 0xff).toString(16).padStart(2, "0"),
+        ((counter * 31 + i * 7) & 0xff).toString(16).padStart(2, "0")
       ).join("");
       return `${bytes.slice(0, 8)}-${bytes.slice(8, 12)}-${bytes.slice(12, 16)}-${bytes.slice(16, 20)}-${bytes.slice(20, 32)}`;
     },
@@ -28,6 +30,7 @@ import { createSubagentTool, SUBAGENT_TOOL_NAME } from "./tool";
 import { createSubagentHandler } from "./handler";
 import { buildSubagentRegistration } from "./register";
 import { defineSubagentWorkflow } from "./workflow";
+import { defineSubagent } from "./define";
 import type {
   SubagentConfig,
   SubagentSessionInput,
@@ -146,7 +149,7 @@ describe("createSubagentTool", () => {
 
   it("throws when no subagents are provided", () => {
     expect(() => createSubagentTool([])).toThrow(
-      "createSubagentTool requires at least one subagent",
+      "createSubagentTool requires at least one subagent"
     );
   });
 
@@ -180,7 +183,7 @@ describe("createSubagentHandler", () => {
 
     const result = await handler(
       { subagent: "researcher", description: "test", prompt: "Find info" },
-      { threadId: "parent-thread", toolCallId: "tc-1", toolName: "Subagent" },
+      { threadId: "parent-thread", toolCallId: "tc-1", toolName: "Subagent" }
     );
 
     expect(result.toolResponse).toContain("Response to: Find info");
@@ -193,8 +196,8 @@ describe("createSubagentHandler", () => {
     await expect(
       handler(
         { subagent: "nonexistent", description: "test", prompt: "test" },
-        { threadId: "t", toolCallId: "tc", toolName: "Subagent" },
-      ),
+        { threadId: "t", toolCallId: "tc", toolName: "Subagent" }
+      )
     ).rejects.toThrow("Unknown subagent: nonexistent");
   });
 
@@ -211,8 +214,8 @@ describe("createSubagentHandler", () => {
     await expect(
       handler(
         { subagent: "bad", description: "test", prompt: "test" },
-        { threadId: "t", toolCallId: "tc", toolName: "Subagent" },
-      ),
+        { threadId: "t", toolCallId: "tc", toolName: "Subagent" }
+      )
     ).rejects.toThrow(/researcher.*writer/);
   });
 
@@ -235,7 +238,7 @@ describe("createSubagentHandler", () => {
 
     const result = await handler(
       { subagent: "validated", description: "test", prompt: "test" },
-      { threadId: "t", toolCallId: "tc", toolName: "Subagent" },
+      { threadId: "t", toolCallId: "tc", toolName: "Subagent" }
     );
 
     expect(result.toolResponse).toContain("invalid data");
@@ -261,7 +264,7 @@ describe("createSubagentHandler", () => {
 
     const result = await handler(
       { subagent: "cont", description: "test", prompt: "test" },
-      { threadId: "t", toolCallId: "tc", toolName: "Subagent" },
+      { threadId: "t", toolCallId: "tc", toolName: "Subagent" }
     );
 
     expect(result.toolResponse).toContain("Thread ID: child-thread-99");
@@ -279,7 +282,7 @@ describe("createSubagentHandler", () => {
 
     const result = await handler(
       { subagent: "researcher", description: "test", prompt: "test" },
-      { threadId: "t", toolCallId: "tc", toolName: "Subagent" },
+      { threadId: "t", toolCallId: "tc", toolName: "Subagent" }
     );
 
     expect(result.toolResponse).toContain("no response");
@@ -306,7 +309,12 @@ describe("createSubagentHandler", () => {
 
     await handler(
       { subagent: "inherit-agent", description: "test", prompt: "test" },
-      { threadId: "t", toolCallId: "tc", toolName: "Subagent", sandboxId: "parent-sb" },
+      {
+        threadId: "t",
+        toolCallId: "tc",
+        toolName: "Subagent",
+        sandboxId: "parent-sb",
+      }
     );
 
     const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
@@ -335,7 +343,12 @@ describe("createSubagentHandler", () => {
 
     await handler(
       { subagent: "own-agent", description: "test", prompt: "test" },
-      { threadId: "t", toolCallId: "tc", toolName: "Subagent", sandboxId: "parent-sb" },
+      {
+        threadId: "t",
+        toolCallId: "tc",
+        toolName: "Subagent",
+        sandboxId: "parent-sb",
+      }
     );
 
     const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
@@ -371,21 +384,23 @@ describe("buildSubagentRegistration", () => {
     }
   });
 
-  it("enabled getter reflects dynamic subagent state", () => {
-    const config: SubagentConfig = {
-      agentName: "toggle",
-      description: "Toggleable",
-      workflow: "workflow",
-      enabled: true,
-    };
+  it("enabled function is re-evaluated dynamically", () => {
+    let flag = true;
+    const reg = buildSubagentRegistration([
+      {
+        agentName: "toggle",
+        description: "Toggleable",
+        workflow: "workflow",
+        enabled: () => flag,
+      },
+    ]);
 
-    const reg = buildSubagentRegistration([config]);
     expect(reg).toBeDefined();
     if (!reg) return;
-    expect(reg.enabled).toBe(true);
+    expect((reg.enabled as () => boolean)()).toBe(true);
 
-    config.enabled = false;
-    expect(reg.enabled).toBe(false);
+    flag = false;
+    expect((reg.enabled as () => boolean)()).toBe(false);
   });
 
   it("disabled when all subagents are disabled", () => {
@@ -400,7 +415,7 @@ describe("buildSubagentRegistration", () => {
 
     expect(reg).toBeDefined();
     if (reg) {
-      expect(reg.enabled).toBe(false);
+      expect((reg.enabled as () => boolean)()).toBe(false);
     }
   });
 
@@ -442,28 +457,29 @@ describe("buildSubagentRegistration", () => {
     }
   });
 
-  it("dynamic schema/description updates when subagents change enabled state", () => {
-    const config1: SubagentConfig = {
-      agentName: "a",
-      description: "Agent A",
-      workflow: "workflow",
-      enabled: true,
-    };
-    const config2: SubagentConfig = {
-      agentName: "b",
-      description: "Agent B",
-      workflow: "workflow",
-      enabled: true,
-    };
-
-    const reg = buildSubagentRegistration([config1, config2]);
+  it("dynamic schema/description updates when enabled function changes", () => {
+    let bEnabled = true;
+    const reg = buildSubagentRegistration([
+      {
+        agentName: "a",
+        description: "Agent A",
+        workflow: "workflow",
+        enabled: true,
+      },
+      {
+        agentName: "b",
+        description: "Agent B",
+        workflow: "workflow",
+        enabled: () => bEnabled,
+      },
+    ]);
 
     expect(reg).toBeDefined();
     if (reg) {
       expect(reg.description).toContain("Agent A");
       expect(reg.description).toContain("Agent B");
 
-      config2.enabled = false;
+      bEnabled = false;
 
       expect(reg.description).toContain("Agent A");
       expect(reg.description).not.toContain("Agent B");
@@ -471,6 +487,45 @@ describe("buildSubagentRegistration", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// defineSubagent
+// ---------------------------------------------------------------------------
+
+describe("defineSubagent", () => {
+  const makeDef = (name: string) =>
+    defineSubagentWorkflow(
+      { name, description: `${name} agent` },
+      async () => ({ toolResponse: "ok", data: null, threadId: "t" })
+    );
+
+  it("enabled function is re-evaluated dynamically", () => {
+    let flag = true;
+    const config = defineSubagent(makeDef("dynamic"), {
+      enabled: () => flag,
+    });
+
+    const resolve = config.enabled as () => boolean;
+    expect(resolve()).toBe(true);
+    flag = false;
+    expect(resolve()).toBe(false);
+  });
+
+  it("enabled function works through buildSubagentRegistration", () => {
+    let flag = true;
+    const config = defineSubagent(makeDef("dynamic"), {
+      enabled: () => flag,
+    });
+
+    const reg = buildSubagentRegistration([config]);
+    expect(reg).toBeDefined();
+    if (!reg) return;
+    expect((reg.enabled as () => boolean)()).toBe(true);
+
+    flag = false;
+    expect((reg.enabled as () => boolean)()).toBe(false);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // defineSubagentWorkflow
 // ---------------------------------------------------------------------------
@@ -486,7 +541,7 @@ describe("defineSubagentWorkflow", () => {
         capturedPrompt = prompt;
         capturedSession = sessionInput;
         return { toolResponse: "ok", data: null, threadId: "t" };
-      },
+      }
     );
 
     await workflow("go", { previousThreadId: "prev-42" });
@@ -506,7 +561,7 @@ describe("defineSubagentWorkflow", () => {
       async (_prompt, sessionInput) => {
         capturedSession = sessionInput;
         return { toolResponse: "ok", data: null, threadId: "t" };
-      },
+      }
     );
 
     await workflow("go", { sandboxId: "sb-123" });
@@ -520,7 +575,7 @@ describe("defineSubagentWorkflow", () => {
       async (_prompt, _sessionInput, context) => {
         capturedContext = context;
         return { toolResponse: "ok", data: null, threadId: "t" };
-      },
+      }
     );
 
     await workflow("go", {}, { key: "val" });
@@ -528,28 +583,18 @@ describe("defineSubagentWorkflow", () => {
     expect(capturedContext).toEqual({ key: "val" });
   });
 
-  it("supports omitted context", async () => {
-    let capturedContext: Record<string, unknown> | undefined;
-    const workflow = defineSubagentWorkflow(
-      { name: "test", description: "test agent" },
-      async (_prompt, _sessionInput, context) => {
-        capturedContext = context;
-        return { toolResponse: "ok", data: null, threadId: "t" };
-      },
-    );
-
-    await workflow("go", { sandboxId: "sb" });
-    expect(capturedContext).toBeUndefined();
-  });
-
   it("returns the handler response unchanged", async () => {
     const workflow = defineSubagentWorkflow(
-      { name: "test", description: "test agent", resultSchema: z.object({ count: z.number() }) },
+      {
+        name: "test",
+        description: "test agent",
+        resultSchema: z.object({ count: z.number() }),
+      },
       async () => ({
         toolResponse: "result text",
         data: { count: 42 },
         threadId: "child-thread",
-      }),
+      })
     );
 
     const result = await workflow("go", {});
@@ -562,8 +607,12 @@ describe("defineSubagentWorkflow", () => {
   it("attaches metadata to the returned workflow function", () => {
     const schema = z.object({ findings: z.string() });
     const workflow = defineSubagentWorkflow(
-      { name: "researcher", description: "Researches topics", resultSchema: schema },
-      async () => ({ toolResponse: "ok", data: null, threadId: "t" }),
+      {
+        name: "researcher",
+        description: "Researches topics",
+        resultSchema: schema,
+      },
+      async () => ({ toolResponse: "ok", data: null, threadId: "t" })
     );
 
     expect(workflow.agentName).toBe("researcher");

package/src/lib/subagent/types.ts

@@ -58,7 +58,7 @@ 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 | (() => boolean);
   /** Temporal workflow function or type name (used with executeChild) */
   workflow: string | SubagentWorkflow<TResult>;
   /** Optional task queue - defaults to parent's queue if not specified */

package/src/lib/tool-router/router.ts

@@ -63,8 +63,11 @@ export function createToolRouter<T extends ToolMap>(
     toolMap.set(tool.name, tool as T[keyof T]);
   }
 
-  /** Check if a tool is enabled (defaults to true when not specified) */
-  const isEnabled = (tool: ToolMap[string]): boolean => tool.enabled ?? true;
+  const resolve = <T,>(v: T | (() => T)): T =>
+    typeof v === "function" ? (v as () => T)() : v;
+
+  const isEnabled = (tool: ToolMap[string]): boolean =>
+    resolve(tool.enabled) ?? true;
 
   if (options.plugins) {
     for (const plugin of options.plugins) {
@@ -268,7 +271,7 @@ export function createToolRouter<T extends ToolMap>(
         throw new Error(`Tool ${toolCall.name} not found`);
       }
 
-      const parsedArgs = tool.schema.parse(toolCall.args);
+      const parsedArgs = resolve(tool.schema).parse(toolCall.args);
 
       return {
         id: toolCall.id ?? "",
@@ -293,8 +296,8 @@ export function createToolRouter<T extends ToolMap>(
         .filter(([, tool]) => isEnabled(tool))
         .map(([name, tool]) => ({
           name,
-          description: tool.description,
-          schema: tool.schema,
+          description: resolve(tool.description),
+          schema: resolve(tool.schema),
           strict: tool.strict,
           max_uses: tool.max_uses,
         }));

package/src/lib/tool-router/types.ts

@@ -41,7 +41,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 | (() => boolean);
   /** Per-tool lifecycle hooks (run in addition to global hooks) */
   hooks?: ToolHooks<z.infer<TSchema>, TResult>;
 }
@@ -58,13 +58,13 @@ export type ToolMap = Record<
   string,
   {
     name: string;
-    description: string;
-    schema: z.ZodType;
+    description: string | (() => string);
+    schema: z.ZodType | (() => z.ZodType);
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     handler: ToolHandler<any, any, any>;
     strict?: boolean;
     max_uses?: number;
-    enabled?: boolean;
+    enabled?: boolean | (() => boolean);
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     hooks?: ToolHooks<any, any>;
   }