zeitlich 0.2.30 → 0.2.32

package/package.json

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

package/src/adapters/thread/anthropic/activities.ts

@@ -164,6 +164,16 @@ export function createAnthropicAdapter(
       await thread.appendToolResult(id, toolCallId, toolName, content);
     },
 
+    async appendAgentMessage(
+      threadId: string,
+      id: string,
+      message: Anthropic.Messages.Message,
+      threadKey?: string,
+    ): Promise<void> {
+      const thread = createAnthropicThreadManager({ redis, threadId, key: threadKey });
+      await thread.appendAssistantMessage(id, message.content);
+    },
+
     async forkThread(
       sourceThreadId: string,
       targetThreadId: string,

package/src/adapters/thread/anthropic/model-invoker.ts

@@ -3,7 +3,6 @@ import type Anthropic from "@anthropic-ai/sdk";
 import type { SerializableToolDefinition } from "../../../lib/types";
 import type { AgentResponse, ModelInvokerConfig } from "../../../lib/model";
 import { createAnthropicThreadManager, type AnthropicThreadManagerHooks } from "./thread-manager";
-import { v4 as uuidv4 } from "uuid";
 
 export interface AnthropicModelInvokerConfig {
   redis: Redis;
@@ -29,8 +28,8 @@ function toAnthropicTools(
  * `ModelInvoker<Anthropic.Messages.Message>` contract.
  *
  * Loads the conversation thread from Redis, invokes the Claude model via
- * `client.messages.create`, appends the AI response, and returns
- * a normalised AgentResponse.
+ * `client.messages.create`, and returns a normalised AgentResponse.
+ * The caller is responsible for appending the response to the thread.
  *
  * @example
  * ```typescript
@@ -74,8 +73,6 @@ export function createAnthropicModelInvoker({
       ...(tools ? { tools } : {}),
     });
 
-    await thread.appendAssistantMessage(uuidv4(), response.content);
-
     const toolCalls = response.content.filter(
       (block): block is Anthropic.Messages.ToolUseBlock =>
         block.type === "tool_use",

package/src/adapters/thread/google-genai/activities.ts

@@ -194,6 +194,20 @@ export function createGoogleGenAIAdapter(
       );
     },
 
+    async appendAgentMessage(
+      threadId: string,
+      id: string,
+      message: Content,
+      threadKey?: string,
+    ): Promise<void> {
+      const thread = createGoogleGenAIThreadManager({
+        redis,
+        threadId,
+        key: threadKey,
+      });
+      await thread.appendModelContent(id, message.parts ?? []);
+    },
+
     async forkThread(
       sourceThreadId: string,
       targetThreadId: string,

package/src/adapters/thread/google-genai/model-invoker.ts

@@ -3,7 +3,6 @@ import type { GoogleGenAI, Content, FunctionDeclaration } from "@google/genai";
 import type { SerializableToolDefinition } from "../../../lib/types";
 import type { AgentResponse, ModelInvokerConfig } from "../../../lib/model";
 import { createGoogleGenAIThreadManager, type GoogleGenAIThreadManagerHooks } from "./thread-manager";
-import { v4 as uuidv4 } from "uuid";
 
 export interface GoogleGenAIModelInvokerConfig {
   redis: Redis;
@@ -27,8 +26,8 @@ function toFunctionDeclarations(
  * `ModelInvoker<Content>` contract.
  *
  * Loads the conversation thread from Redis, invokes the Gemini model via
- * `client.models.generateContent`, appends the AI response, and returns
- * a normalised AgentResponse.
+ * `client.models.generateContent`, and returns a normalised AgentResponse.
+ * The caller is responsible for appending the response to the thread.
  *
  * @example
  * ```typescript
@@ -77,8 +76,6 @@ export function createGoogleGenAIModelInvoker({
     const responseParts = response.candidates?.[0]?.content?.parts ?? [];
     const modelContent: Content = { role: "model", parts: responseParts };
 
-    await thread.appendModelContent(uuidv4(), responseParts);
-
     const functionCalls = response.functionCalls ?? [];
 
     return {

package/src/adapters/thread/langchain/activities.ts

@@ -148,6 +148,17 @@ export function createLangChainAdapter(
       await thread.appendToolResult(id, toolCallId, "", content);
     },
 
+    async appendAgentMessage(
+      threadId: string,
+      id: string,
+      message: StoredMessage,
+      threadKey?: string,
+    ): Promise<void> {
+      const thread = createLangChainThreadManager({ redis, threadId, key: threadKey });
+      const patched = { ...message, data: { ...message.data, id } };
+      await thread.append([patched]);
+    },
+
     async forkThread(
       sourceThreadId: string,
       targetThreadId: string,

package/src/adapters/thread/langchain/model-invoker.ts

@@ -17,7 +17,8 @@ export interface LangChainModelInvokerConfig<TModel extends BaseChatModel<any> =
  * `ModelInvoker<StoredMessage>` contract.
  *
  * Loads the conversation thread from Redis, invokes a LangChain chat model,
- * appends the AI response, and returns a normalised AgentResponse.
+ * and returns a normalised AgentResponse.
+ * The caller is responsible for appending the response to the thread.
  *
  * @example
  * ```typescript
@@ -54,8 +55,6 @@ export function createLangChainModelInvoker<TModel extends BaseChatModel<any> =
       },
     );
 
-    await thread.append([response.toDict()]);
-
     const toolCalls = response.tool_calls ?? [];
 
     return {

package/src/lib/.env

@@ -0,0 +1 @@
+E2B_API_KEY=e2b_39af116424059782e2aee6942fd70237cc2126c9

package/src/lib/model/types.ts

@@ -33,8 +33,9 @@ export interface ModelInvokerConfig {
 
 /**
  * Generic model invocation contract.
- * Implementations load the thread, call the LLM, append the response,
- * and return a normalised AgentResponse.
+ * Implementations load the thread, call the LLM, and return a normalised
+ * AgentResponse. The caller (workflow) is responsible for appending the
+ * response to the thread with a deterministic ID.
  *
  * Framework adapters (e.g. `zeitlich/langchain`) provide concrete
  * implementations of this type.

package/src/lib/session/session-edge-cases.integration.test.ts

@@ -88,6 +88,9 @@ function createMockThreadOps() {
     appendSystemMessage: async (threadId, id, content) => {
       log.push({ op: "appendSystemMessage", args: [threadId, id, content] });
     },
+    appendAgentMessage: async (threadId, id, message) => {
+      log.push({ op: "appendAgentMessage", args: [threadId, id, message] });
+    },
     forkThread: async (source, target) => {
       log.push({ op: "forkThread", args: [source, target] });
     },
@@ -752,6 +755,9 @@ describe("createSession edge cases", () => {
       appendSystemMessage: async (threadId, id, content) => {
         log.push({ op: "appendSystemMessage", args: [threadId, id, content] });
       },
+      appendAgentMessage: async (threadId, id, message) => {
+        log.push({ op: "appendAgentMessage", args: [threadId, id, message] });
+      },
       forkThread: async (source, target) => {
         log.push({ op: "forkThread", args: [source, target] });
       },

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

@@ -99,6 +99,9 @@ function createMockThreadOps() {
     appendSystemMessage: async (threadId, id, content) => {
       log.push({ op: "appendSystemMessage", args: [threadId, id, content] });
     },
+    appendAgentMessage: async (threadId, id, message) => {
+      log.push({ op: "appendAgentMessage", args: [threadId, id, message] });
+    },
     forkThread: async (source, target) => {
       log.push({ op: "forkThread", args: [source, target] });
     },

package/src/lib/session/session.ts

@@ -139,6 +139,7 @@ export async function createSession<
     appendHumanMessage,
     initializeThread,
     appendSystemMessage,
+    appendAgentMessage,
     forkThread,
   } = threadOps;
 
@@ -270,8 +271,23 @@ export async function createSession<
           });
         }
         const result = await virtualFsOps.resolveFileTree(virtualFsConfig.ctx);
+        const skillFiles = skills ? collectSkillFiles(skills) : undefined;
+        const fileTree = skillFiles
+          ? [
+              ...result.fileTree,
+              ...Object.entries(skillFiles).map(([path, content]) => ({
+                id: `skill:${path}`,
+                path,
+                size: content.length,
+                mtime: new Date().toISOString(),
+                metadata: {},
+              })),
+            ]
+          : result.fileTree;
         stateManager.mergeUpdate({
-          fileTree: result.fileTree,
+          fileTree,
+          virtualFsCtx: virtualFsConfig.ctx,
+          ...(skillFiles && { inlineFiles: skillFiles }),
         } as Partial<AgentState<TState>>);
       }
 
@@ -341,6 +357,8 @@ export async function createSession<
             metadata,
           });
 
+          await appendAgentMessage(threadId, uuid4(), message, threadKey);
+
           if (usage) {
             stateManager.updateUsage(usage);
           }

package/src/lib/session/types.ts

@@ -39,6 +39,13 @@ export interface ThreadOps<TContent = string> {
   ): Promise<void>;
   /** Append a tool result to the thread */
   appendToolResult(id: string, config: ToolResultConfig): Promise<void>;
+  /** Append the model's response to the thread */
+  appendAgentMessage(
+    threadId: string,
+    id: string,
+    message: unknown,
+    threadKey?: string
+  ): Promise<void>;
   /** Append a system message to the thread */
   appendSystemMessage(
     threadId: string,

package/src/lib/thread/proxy.ts

@@ -51,6 +51,7 @@ export function createThreadOpsProxy(
     initializeThread: acts[p("initializeThread")],
     appendHumanMessage: acts[p("appendHumanMessage")],
     appendToolResult: acts[p("appendToolResult")],
+    appendAgentMessage: acts[p("appendAgentMessage")],
     appendSystemMessage: acts[p("appendSystemMessage")],
     forkThread: acts[p("forkThread")],
   } as ActivityInterfaceFor<ThreadOps>;

package/src/lib/types.ts

@@ -25,6 +25,9 @@ export interface BaseAgentState {
   turns: number;
   tasks: Map<string, WorkflowTask>;
   fileTree: FileEntry[];
+  /** In-memory file contents keyed by path, bypassing the resolver (e.g. skill resources). */
+  inlineFiles?: Record<string, string>;
+  virtualFsCtx?: unknown;
   systemPrompt?: string;
   totalInputTokens: number;
   totalOutputTokens: number;

package/src/lib/virtual-fs/filesystem.ts

@@ -60,17 +60,28 @@ export class VirtualFileSystem<
   private directories: Set<string>;
   private mutations: TreeMutation<TMeta>[] = [];
 
+  private inlineFiles: Map<string, string>;
+
   constructor(
     tree: FileEntry<TMeta>[],
     private resolver: FileResolver<TCtx, TMeta>,
     private ctx: TCtx,
     workspaceBase = "/",
+    inlineFiles?: Record<string, string>,
   ) {
     this.workspaceBase = normalisePath(workspaceBase);
     this.entries = new Map(
       tree.map((e) => [normalisePath(e.path, this.workspaceBase), e])
     );
     this.directories = inferDirectories(tree, this.workspaceBase);
+    this.inlineFiles = new Map(
+      inlineFiles
+        ? Object.entries(inlineFiles).map(([p, c]) => [
+            normalisePath(p, this.workspaceBase),
+            c,
+          ])
+        : []
+    );
   }
 
   /** Return all mutations accumulated during this invocation. */
@@ -89,6 +100,8 @@ export class VirtualFileSystem<
 
   async readFile(path: string): Promise<string> {
     const norm = normalisePath(path, this.workspaceBase);
+    const inline = this.inlineFiles.get(norm);
+    if (inline !== undefined) return inline;
     const entry = this.entries.get(norm);
     if (!entry) throw new Error(`ENOENT: no such file: ${path}`);
     return this.resolver.readFile(entry.id, this.ctx, entry.metadata);
@@ -96,6 +109,8 @@ export class VirtualFileSystem<
 
   async readFileBuffer(path: string): Promise<Uint8Array> {
     const norm = normalisePath(path, this.workspaceBase);
+    const inline = this.inlineFiles.get(norm);
+    if (inline !== undefined) return new TextEncoder().encode(inline);
     const entry = this.entries.get(norm);
     if (!entry) throw new Error(`ENOENT: no such file: ${path}`);
     return this.resolver.readFileBuffer(entry.id, this.ctx, entry.metadata);

package/src/lib/virtual-fs/manager.ts

@@ -30,7 +30,7 @@ export function createVirtualFsActivities<
   TMeta = FileEntryMetadata,
 >(
   resolver: FileResolver<TCtx, TMeta>,
-  scope: S,
+  scope: S
 ): PrefixedVirtualFsOps<S, TCtx, TMeta> {
   const ops: VirtualFsOps<TCtx, TMeta> = {
     resolveFileTree: async (ctx: TCtx) => {
@@ -39,10 +39,10 @@ export function createVirtualFsActivities<
     },
   };
 
-  const prefix = scope;
+  const prefix = `virtualFs${scope.charAt(0).toUpperCase()}${scope.slice(1)}`;
   const cap = (s: string): string => s.charAt(0).toUpperCase() + s.slice(1);
 
   return Object.fromEntries(
-    Object.entries(ops).map(([k, v]) => [`${prefix}${cap(k)}`, v]),
+    Object.entries(ops).map(([k, v]) => [`${prefix}${cap(k)}`, v])
   ) as PrefixedVirtualFsOps<S, TCtx, TMeta>;
 }

package/src/lib/virtual-fs/proxy.ts

@@ -18,7 +18,7 @@ import type { VirtualFsOps } from "./types";
 
 export function proxyVirtualFsOps<TCtx = unknown>(
   scope?: string,
-  options?: Parameters<typeof proxyActivities>[0],
+  options?: Parameters<typeof proxyActivities>[0]
 ): VirtualFsOps<TCtx> {
   const resolvedScope = scope ?? workflowInfo().workflowType;
 
@@ -32,10 +32,10 @@ export function proxyVirtualFsOps<TCtx = unknown>(
         maximumInterval: "30s",
         backoffCoefficient: 2,
       },
-    },
+    }
   );
 
-  const prefix = resolvedScope;
+  const prefix = `virtualFs${resolvedScope.charAt(0).toUpperCase()}${resolvedScope.slice(1)}`;
   const p = (key: string): string =>
     `${prefix}${key.charAt(0).toUpperCase()}${key.slice(1)}`;
 

package/src/lib/virtual-fs/types.ts

@@ -118,8 +118,9 @@ export type PrefixedVirtualFsOps<
  */
 export interface VirtualFsState<TCtx = unknown, TMeta = FileEntryMetadata> {
   fileTree: FileEntry<TMeta>[];
-  ctx: TCtx;
-  workspaceBase?: string;
+  virtualFsCtx: TCtx;
+  /** In-memory file contents keyed by path, bypassing the resolver (e.g. skill resources). */
+  inlineFiles?: Record<string, string>;
 }
 
 // ============================================================================

package/src/lib/virtual-fs/virtual-fs.test.ts

@@ -325,6 +325,70 @@ describe("VirtualFileSystem", () => {
   });
 });
 
+// ============================================================================
+// VirtualFileSystem — inlineFiles
+// ============================================================================
+
+describe("VirtualFileSystem — inlineFiles", () => {
+  const skillEntry: FileEntry = {
+    id: "skill:code-review:checklist.md",
+    path: "/skills/code-review/checklist.md",
+    size: 18,
+    mtime: "2025-01-01T00:00:00.000Z",
+    metadata: {},
+  };
+
+  const inlineFiles: Record<string, string> = {
+    "/skills/code-review/checklist.md": "# Review checklist",
+  };
+
+  function createFsWithInline() {
+    const { resolver } = createMockResolver();
+    return new VirtualFileSystem(
+      [...sampleTree, skillEntry],
+      resolver,
+      ctx,
+      "/",
+      inlineFiles,
+    );
+  }
+
+  it("readFile returns inline content instead of hitting the resolver", async () => {
+    const fs = createFsWithInline();
+    const content = await fs.readFile("/skills/code-review/checklist.md");
+    expect(content).toBe("# Review checklist");
+  });
+
+  it("readFileBuffer returns inline content as Uint8Array", async () => {
+    const fs = createFsWithInline();
+    const buf = await fs.readFileBuffer("/skills/code-review/checklist.md");
+    expect(new TextDecoder().decode(buf)).toBe("# Review checklist");
+  });
+
+  it("inline files are visible in readdir", async () => {
+    const fs = createFsWithInline();
+    const names = await fs.readdir("/skills/code-review");
+    expect(names).toContain("checklist.md");
+  });
+
+  it("inline file directories are inferred", async () => {
+    const fs = createFsWithInline();
+    expect(await fs.exists("/skills")).toBe(true);
+    expect(await fs.exists("/skills/code-review")).toBe(true);
+  });
+
+  it("readFile still falls back to resolver for non-inline files", async () => {
+    const fs = createFsWithInline();
+    const content = await fs.readFile("/src/index.ts");
+    expect(content).toBe('console.log("hello");');
+  });
+
+  it("readFile throws ENOENT for paths not in tree or inline", async () => {
+    const fs = createFsWithInline();
+    await expect(fs.readFile("/nope.txt")).rejects.toThrow("ENOENT");
+  });
+});
+
 // ============================================================================
 // createVirtualFsActivities
 // ============================================================================

package/src/lib/virtual-fs/with-virtual-fs.ts

@@ -66,7 +66,7 @@ export function withVirtualFs<
     const state =
       await queryParentWorkflowState<VirtualFsState<TCtx, TMeta>>(client);
 
-    const { fileTree, ctx, workspaceBase } = state;
+    const { fileTree, virtualFsCtx, inlineFiles } = state;
     if (!fileTree) {
       return {
         toolResponse: `Error: No fileTree in agent state. The ${context.toolName} tool requires a virtual filesystem.`,
@@ -77,8 +77,9 @@ export function withVirtualFs<
     const virtualFs = new VirtualFileSystem(
       fileTree,
       resolver,
-      ctx,
-      workspaceBase ?? "/"
+      virtualFsCtx,
+      "/",
+      inlineFiles
     );
     const response = await handler(args, { ...context, virtualFs });
     const mutations = virtualFs.getMutations();

package/src/tools/bash/.env

@@ -0,0 +1 @@
+E2B_API_KEY=e2b_39af116424059782e2aee6942fd70237cc2126c9