zeitlich 0.2.38 → 0.2.40

package/README.md

@@ -482,6 +482,24 @@ const session = await createSession({
 
 The `Subagent` tool is automatically added when subagents are configured, allowing the LLM to spawn child workflows.
 
+#### Child workflow timeouts
+
+Every subagent child workflow runs with a default `workflowRunTimeout` of `1h` (exported as `DEFAULT_SUBAGENT_WORKFLOW_RUN_TIMEOUT`). This is a safety bound: without it, a child that fails to initialize or repeatedly fails workflow tasks is retried forever by Temporal and the parent's `Subagent` tool call would hang indefinitely. With it, Temporal eventually terminates the child and the parent receives a structured `ChildWorkflowFailure` which the tool router surfaces to the LLM through the normal failure-hook pipeline (`onPostToolUseFailure`, per-subagent `onExecutionFailure`).
+
+You can override the default — or set any other `ChildWorkflowOptions` — via the `workflowOptions` field:
+
+```typescript
+export const researcherSubagent = defineSubagent(researcherWorkflow, {
+  workflowOptions: {
+    workflowRunTimeout: "10m",
+    workflowTaskTimeout: "1m",
+    retry: { maximumAttempts: 2 },
+  },
+});
+```
+
+`workflowId`, `taskQueue`, and `args` are managed by the subagent handler itself and cannot be overridden via `workflowOptions` — use the top-level `taskQueue` field on `SubagentConfig` to route a subagent to a different task queue.
+
 ### Skills
 
 Zeitlich has first-class support for the [agentskills.io](https://agentskills.io) specification. Skills are reusable instruction sets that an agent can load on-demand via the built-in `ReadSkill` tool — progressive disclosure keeps token usage low while giving agents access to rich, domain-specific guidance.

package/dist/{activities-BKhMtKDd.d.ts → activities-CULxRzJ1.d.ts}

@@ -1,7 +1,8 @@
 import Redis from 'ioredis';
 import { Part, Content, GoogleGenAI } from '@google/genai';
-import { a as ModelInvoker, P as PrefixedThreadOps, S as ScopedPrefix, R as RouterContext, b as ToolHandlerResponse, c as ActivityToolHandler } from './types-DNr31FzL.js';
-import { T as ThreadManagerHooks, P as ProviderThreadManager } from './types-BH_IRryz.js';
+import { a as ModelInvoker, b as PrefixedThreadOps, S as ScopedPrefix, R as RouterContext, c as ToolHandlerResponse, d as ActivityToolHandler } from './types-DeQH84C_.js';
+import { T as ThreadManagerHooks, P as ProviderThreadManager } from './types-C7OoY7h8.js';
+import { A as ADAPTER_ID } from './adapter-id-BB-mmrts.js';
 
 /** SDK-native content type for Google GenAI human messages */
 type GoogleGenAIContent = string | Part[];
@@ -24,8 +25,6 @@ interface GoogleGenAIThreadManagerConfig {
 interface GoogleGenAIInvocationPayload {
     contents: Content[];
     systemInstruction?: Part[];
-    /** Number of stored messages loaded from Redis before preparation. */
-    storedLength: number;
 }
 /** Thread manager with Google GenAI Content convenience helpers */
 interface GoogleGenAIThreadManager extends ProviderThreadManager<StoredContent, GoogleGenAIContent, GoogleGenAIToolResponse, GoogleGenAISystemContent> {
@@ -39,8 +38,7 @@ interface GoogleGenAIThreadManager extends ProviderThreadManager<StoredContent,
  */
 declare function createGoogleGenAIThreadManager(config: GoogleGenAIThreadManagerConfig): GoogleGenAIThreadManager;
 
-declare const ADAPTER_PREFIX: "googleGenAI";
-type GoogleGenAIThreadOps<TScope extends string = ""> = PrefixedThreadOps<ScopedPrefix<TScope, typeof ADAPTER_PREFIX>, GoogleGenAIContent>;
+type GoogleGenAIThreadOps<TScope extends string = ""> = PrefixedThreadOps<ScopedPrefix<TScope, typeof ADAPTER_ID>, GoogleGenAIContent>;
 interface GoogleGenAIAdapterConfig {
     redis: Redis;
     client?: GoogleGenAI;

package/dist/{activities-CDcwkRZs.d.cts → activities-CvUrG3YG.d.cts}

@@ -1,7 +1,8 @@
 import Redis from 'ioredis';
 import { Part, Content, GoogleGenAI } from '@google/genai';
-import { a as ModelInvoker, P as PrefixedThreadOps, S as ScopedPrefix, R as RouterContext, b as ToolHandlerResponse, c as ActivityToolHandler } from './types-C06FwR96.cjs';
-import { T as ThreadManagerHooks, P as ProviderThreadManager } from './types-BaOw4hKI.cjs';
+import { a as ModelInvoker, b as PrefixedThreadOps, S as ScopedPrefix, R as RouterContext, c as ToolHandlerResponse, d as ActivityToolHandler } from './types-Cn2r3ol3.cjs';
+import { T as ThreadManagerHooks, P as ProviderThreadManager } from './types-CuISs0Ub.cjs';
+import { A as ADAPTER_ID } from './adapter-id-BB-mmrts.cjs';
 
 /** SDK-native content type for Google GenAI human messages */
 type GoogleGenAIContent = string | Part[];
@@ -24,8 +25,6 @@ interface GoogleGenAIThreadManagerConfig {
 interface GoogleGenAIInvocationPayload {
     contents: Content[];
     systemInstruction?: Part[];
-    /** Number of stored messages loaded from Redis before preparation. */
-    storedLength: number;
 }
 /** Thread manager with Google GenAI Content convenience helpers */
 interface GoogleGenAIThreadManager extends ProviderThreadManager<StoredContent, GoogleGenAIContent, GoogleGenAIToolResponse, GoogleGenAISystemContent> {
@@ -39,8 +38,7 @@ interface GoogleGenAIThreadManager extends ProviderThreadManager<StoredContent,
  */
 declare function createGoogleGenAIThreadManager(config: GoogleGenAIThreadManagerConfig): GoogleGenAIThreadManager;
 
-declare const ADAPTER_PREFIX: "googleGenAI";
-type GoogleGenAIThreadOps<TScope extends string = ""> = PrefixedThreadOps<ScopedPrefix<TScope, typeof ADAPTER_PREFIX>, GoogleGenAIContent>;
+type GoogleGenAIThreadOps<TScope extends string = ""> = PrefixedThreadOps<ScopedPrefix<TScope, typeof ADAPTER_ID>, GoogleGenAIContent>;
 interface GoogleGenAIAdapterConfig {
     redis: Redis;
     client?: GoogleGenAI;

package/dist/adapter-id-BB-mmrts.d.cts

@@ -0,0 +1,17 @@
+/**
+ * Public adapter identity for the Google GenAI thread adapter.
+ *
+ * This value is wire format — it appears as the prefix for Temporal
+ * activity names (e.g. `googleGenAICodingAgentInitializeThread`) and
+ * must never change, since renaming it would orphan existing persisted
+ * threads and break in-flight workflows.
+ *
+ * Re-exported from `zeitlich/adapters/thread/google-genai` so downstream
+ * consumers can use the exact same literal the adapter uses internally,
+ * typed as the narrow string literal `"googleGenAI"`.
+ */
+declare const ADAPTER_ID: "googleGenAI";
+/** Narrow string-literal type for {@link ADAPTER_ID}. */
+type AdapterId = typeof ADAPTER_ID;
+
+export { ADAPTER_ID as A, type AdapterId as a };

package/dist/adapter-id-BB-mmrts.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Public adapter identity for the Google GenAI thread adapter.
+ *
+ * This value is wire format — it appears as the prefix for Temporal
+ * activity names (e.g. `googleGenAICodingAgentInitializeThread`) and
+ * must never change, since renaming it would orphan existing persisted
+ * threads and break in-flight workflows.
+ *
+ * Re-exported from `zeitlich/adapters/thread/google-genai` so downstream
+ * consumers can use the exact same literal the adapter uses internally,
+ * typed as the narrow string literal `"googleGenAI"`.
+ */
+declare const ADAPTER_ID: "googleGenAI";
+/** Narrow string-literal type for {@link ADAPTER_ID}. */
+type AdapterId = typeof ADAPTER_ID;
+
+export { ADAPTER_ID as A, type AdapterId as a };

package/dist/adapter-id-CMwVrVqv.d.cts

@@ -0,0 +1,17 @@
+/**
+ * Public adapter identity for the Anthropic thread adapter.
+ *
+ * This value is wire format — it appears as the prefix for Temporal
+ * activity names (e.g. `anthropicCodingAgentInitializeThread`) and must
+ * never change, since renaming it would orphan existing persisted
+ * threads and break in-flight workflows.
+ *
+ * Re-exported from `zeitlich/adapters/thread/anthropic` so downstream
+ * consumers can use the exact same literal the adapter uses internally,
+ * typed as the narrow string literal `"anthropic"`.
+ */
+declare const ADAPTER_ID: "anthropic";
+/** Narrow string-literal type for {@link ADAPTER_ID}. */
+type AdapterId = typeof ADAPTER_ID;
+
+export { ADAPTER_ID as A, type AdapterId as a };

package/dist/adapter-id-CMwVrVqv.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Public adapter identity for the Anthropic thread adapter.
+ *
+ * This value is wire format — it appears as the prefix for Temporal
+ * activity names (e.g. `anthropicCodingAgentInitializeThread`) and must
+ * never change, since renaming it would orphan existing persisted
+ * threads and break in-flight workflows.
+ *
+ * Re-exported from `zeitlich/adapters/thread/anthropic` so downstream
+ * consumers can use the exact same literal the adapter uses internally,
+ * typed as the narrow string literal `"anthropic"`.
+ */
+declare const ADAPTER_ID: "anthropic";
+/** Narrow string-literal type for {@link ADAPTER_ID}. */
+type AdapterId = typeof ADAPTER_ID;
+
+export { ADAPTER_ID as A, type AdapterId as a };

package/dist/adapter-id-CbY2zeSt.d.cts

@@ -0,0 +1,17 @@
+/**
+ * Public adapter identity for the LangChain thread adapter.
+ *
+ * This value is wire format — it appears as the prefix for Temporal
+ * activity names (e.g. `langChainCodingAgentInitializeThread`) and must
+ * never change, since renaming it would orphan existing persisted
+ * threads and break in-flight workflows.
+ *
+ * Re-exported from `zeitlich/adapters/thread/langchain` so downstream
+ * consumers can use the exact same literal the adapter uses internally,
+ * typed as the narrow string literal `"langChain"`.
+ */
+declare const ADAPTER_ID: "langChain";
+/** Narrow string-literal type for {@link ADAPTER_ID}. */
+type AdapterId = typeof ADAPTER_ID;
+
+export { ADAPTER_ID as A, type AdapterId as a };

package/dist/adapter-id-CbY2zeSt.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Public adapter identity for the LangChain thread adapter.
+ *
+ * This value is wire format — it appears as the prefix for Temporal
+ * activity names (e.g. `langChainCodingAgentInitializeThread`) and must
+ * never change, since renaming it would orphan existing persisted
+ * threads and break in-flight workflows.
+ *
+ * Re-exported from `zeitlich/adapters/thread/langchain` so downstream
+ * consumers can use the exact same literal the adapter uses internally,
+ * typed as the narrow string literal `"langChain"`.
+ */
+declare const ADAPTER_ID: "langChain";
+/** Narrow string-literal type for {@link ADAPTER_ID}. */
+type AdapterId = typeof ADAPTER_ID;
+
+export { ADAPTER_ID as A, type AdapterId as a };

package/dist/adapters/thread/anthropic/index.cjs

@@ -2,8 +2,22 @@
 
 var activity = require('@temporalio/activity');
 
-// src/lib/thread/manager.ts
+// src/adapters/thread/anthropic/adapter-id.ts
+var ADAPTER_ID = "anthropic";
+
+// src/lib/thread/keys.ts
 var THREAD_TTL_SECONDS = 60 * 60 * 24 * 90;
+function getThreadListKey(threadKey, threadId) {
+  return `${threadKey}:thread:${threadId}`;
+}
+function getThreadMetaKey(threadKey, threadId) {
+  return `${threadKey}:meta:thread:${threadId}`;
+}
+function getThreadStateKey(threadKey, threadId) {
+  return `${threadKey}:state:thread:${threadId}`;
+}
+
+// src/lib/thread/manager.ts
 var APPEND_IDEMPOTENT_SCRIPT = `
 if redis.call('EXISTS', KEYS[1]) == 1 then
   return 0
@@ -15,8 +29,8 @@ redis.call('EXPIRE', KEYS[2], tonumber(ARGV[1]))
 redis.call('SET', KEYS[1], '1', 'EX', tonumber(ARGV[1]))
 return 1
 `;
-function getThreadKey(threadId, key) {
-  return `${key}:thread:${threadId}`;
+function getDedupKey(threadId, id) {
+  return `dedup:${id}:thread:${threadId}`;
 }
 function createThreadManager(config) {
   const {
@@ -27,8 +41,9 @@ function createThreadManager(config) {
     deserialize = (raw) => JSON.parse(raw),
     idOf
   } = config;
-  const redisKey = getThreadKey(threadId, key);
-  const metaKey = getThreadKey(threadId, `${key}:meta`);
+  const redisKey = getThreadListKey(key, threadId);
+  const metaKey = getThreadMetaKey(key, threadId);
+  const stateKey = getThreadStateKey(key, threadId);
   async function assertThreadExists() {
     const exists = await redis.exists(metaKey);
     if (!exists) {
@@ -50,7 +65,7 @@ function createThreadManager(config) {
       await assertThreadExists();
       if (idOf) {
         const dedupId = messages.map(idOf).join(":");
-        const dedupKey = getThreadKey(threadId, `dedup:${dedupId}`);
+        const dedupKey = getDedupKey(threadId, dedupId);
         await redis.eval(
           APPEND_IDEMPOTENT_SCRIPT,
           2,
@@ -67,34 +82,98 @@ function createThreadManager(config) {
     async fork(newThreadId) {
       await assertThreadExists();
       const data = await redis.lrange(redisKey, 0, -1);
+      const stateRaw = await redis.get(stateKey);
       const forked = createThreadManager({
         ...config,
         threadId: newThreadId
       });
       await forked.initialize();
       if (data.length > 0) {
-        const newKey = getThreadKey(newThreadId, key);
+        const newKey = getThreadListKey(key, newThreadId);
         await redis.rpush(newKey, ...data);
         await redis.expire(newKey, THREAD_TTL_SECONDS);
       }
+      if (stateRaw != null) {
+        const newStateKey = getThreadStateKey(key, newThreadId);
+        await redis.set(newStateKey, stateRaw, "EX", THREAD_TTL_SECONDS);
+      }
       return forked;
     },
+    async replaceAll(messages) {
+      await assertThreadExists();
+      if (!idOf) {
+        throw new Error(
+          "replaceAll requires the thread manager to be configured with `idOf`"
+        );
+      }
+      const existing = await redis.lrange(redisKey, 0, -1);
+      const existingIds = existing.map((raw) => idOf(deserialize(raw))).filter((id) => typeof id === "string");
+      await redis.del(redisKey);
+      if (existingIds.length > 0) {
+        await redis.del(
+          ...existingIds.map((id) => getDedupKey(threadId, id))
+        );
+      }
+      if (messages.length > 0) {
+        await redis.rpush(redisKey, ...messages.map(serialize));
+        await redis.expire(redisKey, THREAD_TTL_SECONDS);
+      }
+      await redis.expire(metaKey, THREAD_TTL_SECONDS);
+    },
     async delete() {
-      await redis.del(redisKey, metaKey);
+      await redis.del(redisKey, metaKey, stateKey);
+    },
+    async loadState() {
+      const raw = await redis.get(stateKey);
+      if (raw == null) return null;
+      return JSON.parse(raw);
+    },
+    async saveState(state) {
+      await assertThreadExists();
+      await redis.set(
+        stateKey,
+        JSON.stringify(state),
+        "EX",
+        THREAD_TTL_SECONDS
+      );
+    },
+    async deleteState() {
+      await redis.del(stateKey);
     },
     async length() {
       await assertThreadExists();
       return redis.llen(redisKey);
     },
-    async truncate(length) {
+    async truncateFromId(messageId) {
       await assertThreadExists();
-      if (length <= 0) {
+      if (!idOf) {
+        throw new Error(
+          "truncateFromId requires the thread manager to be configured with `idOf`"
+        );
+      }
+      const data = await redis.lrange(redisKey, 0, -1);
+      let idx = -1;
+      const removedIds = [];
+      for (let i = 0; i < data.length; i++) {
+        const raw = data[i];
+        if (raw === void 0) continue;
+        const id = idOf(deserialize(raw));
+        if (idx === -1 && id === messageId) idx = i;
+        if (idx !== -1) removedIds.push(id);
+      }
+      if (idx === -1) return;
+      if (idx === 0) {
         await redis.del(redisKey);
         await redis.expire(metaKey, THREAD_TTL_SECONDS);
       } else {
-        await redis.ltrim(redisKey, 0, length - 1);
+        await redis.ltrim(redisKey, 0, idx - 1);
         await redis.expire(redisKey, THREAD_TTL_SECONDS);
       }
+      if (removedIds.length > 0) {
+        await redis.del(
+          ...removedIds.map((id) => getDedupKey(threadId, id))
+        );
+      }
     }
   };
 }
@@ -203,12 +282,33 @@ function createAnthropicThreadManager(config) {
       const messages = mergeConsecutiveMessages(conversationMessages);
       return {
         messages: onPreparedMessage ? messages.map((msg, i) => onPreparedMessage(msg, i, messages)) : messages,
-        ...system ? { system } : {},
-        storedLength: stored.length
+        ...system ? { system } : {}
       };
     }
   };
-  return Object.assign(base, helpers);
+  const manager = Object.assign(base, helpers);
+  const originalFork = manager.fork.bind(manager);
+  manager.fork = async (newThreadId) => {
+    await originalFork(newThreadId);
+    const forked = createAnthropicThreadManager({
+      ...config,
+      threadId: newThreadId
+    });
+    const { onForkPrepareThread, onForkTransform } = config.hooks ?? {};
+    if (!onForkPrepareThread && !onForkTransform) {
+      return forked;
+    }
+    let next = await forked.load();
+    if (onForkPrepareThread) {
+      next = await onForkPrepareThread(next);
+    }
+    if (onForkTransform) {
+      next = next.map((msg, i) => onForkTransform(msg, i, next));
+    }
+    await forked.replaceAll(next);
+    return forked;
+  };
+  return manager;
 }
 function getActivityContext() {
   try {
@@ -235,7 +335,7 @@ function createAnthropicModelInvoker({
   hooks
 }) {
   return async function invokeAnthropicModel2(config) {
-    const { threadId, threadKey, state } = config;
+    const { threadId, threadKey, state, assistantMessageId } = config;
     const { heartbeat, signal } = getActivityContext();
     const thread = createAnthropicThreadManager({
       redis,
@@ -243,7 +343,8 @@ function createAnthropicModelInvoker({
       key: threadKey,
       hooks
     });
-    const { messages, system, storedLength } = await thread.prepareForInvocation();
+    await thread.truncateFromId(assistantMessageId);
+    const { messages, system } = await thread.prepareForInvocation();
     const anthropicTools = toAnthropicTools(state.tools);
     const tools = anthropicTools.length > 0 ? anthropicTools : void 0;
     const params = {
@@ -273,8 +374,7 @@ function createAnthropicModelInvoker({
         outputTokens: response.usage.output_tokens,
         cachedWriteTokens: response.usage.cache_creation_input_tokens ?? void 0,
         cachedReadTokens: response.usage.cache_read_input_tokens ?? void 0
-      },
-      threadLengthAtCall: storedLength
+      }
     };
   };
 }
@@ -297,7 +397,6 @@ async function invokeAnthropicModel({
 }
 
 // src/adapters/thread/anthropic/activities.ts
-var ADAPTER_PREFIX = "anthropic";
 function createAnthropicAdapter(config) {
   const { redis, client } = config;
   const threadOps = {
@@ -346,17 +445,34 @@ function createAnthropicAdapter(config) {
       const thread = createAnthropicThreadManager({
         redis,
         threadId: sourceThreadId,
-        key: threadKey
+        key: threadKey,
+        hooks: config.hooks
       });
       await thread.fork(targetThreadId);
     },
-    async truncateThread(threadId, length, threadKey) {
+    async truncateThread(threadId, messageId, threadKey) {
       const thread = createAnthropicThreadManager({ redis, threadId, key: threadKey });
-      await thread.truncate(length);
+      await thread.truncateFromId(messageId);
+    },
+    async loadThreadState(threadId, threadKey) {
+      const thread = createAnthropicThreadManager({
+        redis,
+        threadId,
+        key: threadKey
+      });
+      return thread.loadState();
+    },
+    async saveThreadState(threadId, state, threadKey) {
+      const thread = createAnthropicThreadManager({
+        redis,
+        threadId,
+        key: threadKey
+      });
+      await thread.saveState(state);
     }
   };
   function createActivities(scope) {
-    const prefix = scope ? `${ADAPTER_PREFIX}${scope.charAt(0).toUpperCase()}${scope.slice(1)}` : ADAPTER_PREFIX;
+    const prefix = scope ? `${ADAPTER_ID}${scope.charAt(0).toUpperCase()}${scope.slice(1)}` : ADAPTER_ID;
     const cap = (s) => s.charAt(0).toUpperCase() + s.slice(1);
     return Object.fromEntries(
       Object.entries(threadOps).map(([k, v]) => [`${prefix}${cap(k)}`, v])
@@ -386,6 +502,7 @@ function createAnthropicAdapter(config) {
   };
 }
 
+exports.ADAPTER_ID = ADAPTER_ID;
 exports.createAnthropicAdapter = createAnthropicAdapter;
 exports.createAnthropicModelInvoker = createAnthropicModelInvoker;
 exports.createAnthropicThreadManager = createAnthropicThreadManager;