zeitlich 0.2.15 → 0.2.16

package/src/lib/session/session.ts

@@ -67,7 +67,9 @@ export const createSession = async <T extends ToolMap, M = unknown>({
 }: SessionConfig<T, M>): Promise<ZeitlichSession<M>> => {
   const sourceThreadId = continueThread ? providedThreadId : undefined;
   const threadId =
-    continueThread && providedThreadId ? getShortId() : (providedThreadId ?? getShortId());
+    continueThread && providedThreadId
+      ? getShortId()
+      : (providedThreadId ?? getShortId());
 
   const {
     appendToolResult,
@@ -149,9 +151,7 @@ export const createSession = async <T extends ToolMap, M = unknown>({
         const result = await sandboxOps.createSandbox({ id: threadId });
         sandboxId = result.sandboxId;
         if (result.stateUpdate) {
-          stateManager.mergeUpdate(
-            result.stateUpdate as Partial<TState>,
-          );
+          stateManager.mergeUpdate(result.stateUpdate as Partial<TState>);
         }
       }
 
@@ -253,6 +253,7 @@ export const createSession = async <T extends ToolMap, M = unknown>({
             );
             if (!conditionMet) {
               stateManager.cancel();
+              exitReason = "cancelled";
               await condition(() => false, "2s");
               break;
             }

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

@@ -0,0 +1,308 @@
+import { describe, expect, it } from "vitest";
+import { parseSkillFile } from "./parse";
+import { createReadSkillTool } from "./tool";
+import { createReadSkillHandler } from "./handler";
+import { buildSkillRegistration } from "./register";
+import type { Skill } from "./types";
+
+// ---------------------------------------------------------------------------
+// parseSkillFile
+// ---------------------------------------------------------------------------
+
+describe("parseSkillFile", () => {
+  it("parses a minimal SKILL.md with name and description", () => {
+    const raw = `---
+name: my-skill
+description: Does useful things
+---
+# Instructions
+Do the thing.`;
+
+    const { frontmatter, body } = parseSkillFile(raw);
+
+    expect(frontmatter.name).toBe("my-skill");
+    expect(frontmatter.description).toBe("Does useful things");
+    expect(body).toBe("# Instructions\nDo the thing.");
+  });
+
+  it("parses full frontmatter with all optional fields", () => {
+    const raw = `---
+name: advanced-skill
+description: A more complex skill
+license: MIT
+compatibility: linux-only
+allowed-tools: bash grep read-file
+metadata:
+  author: test-author
+  version: 1.0
+---
+Body content here.`;
+
+    const { frontmatter, body } = parseSkillFile(raw);
+
+    expect(frontmatter.name).toBe("advanced-skill");
+    expect(frontmatter.description).toBe("A more complex skill");
+    expect(frontmatter.license).toBe("MIT");
+    expect(frontmatter.compatibility).toBe("linux-only");
+    expect(frontmatter.allowedTools).toEqual(["bash", "grep", "read-file"]);
+    expect(frontmatter.metadata).toEqual({ author: "test-author", version: "1.0" });
+    expect(body).toBe("Body content here.");
+  });
+
+  it("strips BOM from input", () => {
+    const raw = `\uFEFF---
+name: bom-skill
+description: Has BOM
+---
+Content`;
+
+    const { frontmatter } = parseSkillFile(raw);
+    expect(frontmatter.name).toBe("bom-skill");
+  });
+
+  it("handles quoted values in frontmatter", () => {
+    const raw = `---
+name: "quoted-skill"
+description: 'single quoted description'
+---
+Body`;
+
+    const { frontmatter } = parseSkillFile(raw);
+    expect(frontmatter.name).toBe("quoted-skill");
+    expect(frontmatter.description).toBe("single quoted description");
+  });
+
+  it("throws when frontmatter is missing", () => {
+    expect(() => parseSkillFile("No frontmatter here")).toThrow(
+      "SKILL.md must start with YAML frontmatter",
+    );
+  });
+
+  it("throws when name is missing", () => {
+    const raw = `---
+description: Missing name
+---
+Body`;
+
+    expect(() => parseSkillFile(raw)).toThrow(
+      "SKILL.md frontmatter must include a 'name' field",
+    );
+  });
+
+  it("throws when description is missing", () => {
+    const raw = `---
+name: no-desc
+---
+Body`;
+
+    expect(() => parseSkillFile(raw)).toThrow(
+      "SKILL.md frontmatter must include a 'description' field",
+    );
+  });
+
+  it("handles empty body", () => {
+    const raw = `---
+name: empty-body
+description: No body content
+---
+`;
+
+    const { body } = parseSkillFile(raw);
+    expect(body).toBe("");
+  });
+
+  it("handles CRLF line endings", () => {
+    const raw = "---\r\nname: crlf-skill\r\ndescription: CRLF test\r\n---\r\nBody with CRLF";
+
+    const { frontmatter, body } = parseSkillFile(raw);
+    expect(frontmatter.name).toBe("crlf-skill");
+    expect(body).toBe("Body with CRLF");
+  });
+
+  it("ignores comment lines in frontmatter", () => {
+    const raw = `---
+name: commented
+# This is a comment
+description: Has comments
+---
+Body`;
+
+    const { frontmatter } = parseSkillFile(raw);
+    expect(frontmatter.name).toBe("commented");
+    expect(frontmatter.description).toBe("Has comments");
+  });
+
+  it("handles metadata with empty map (key with no value)", () => {
+    const raw = `---
+name: meta-skill
+description: Has metadata section
+metadata:
+  key1: value1
+  key2: value2
+---
+Body`;
+
+    const { frontmatter } = parseSkillFile(raw);
+    expect(frontmatter.metadata).toEqual({ key1: "value1", key2: "value2" });
+  });
+
+  it("trims body whitespace", () => {
+    const raw = `---
+name: trimmed
+description: Trims body
+---
+
+  
+  Body with leading whitespace
+  And trailing
+  `;
+
+    const { body } = parseSkillFile(raw);
+    expect(body).toBe("Body with leading whitespace\n  And trailing");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// createReadSkillTool
+// ---------------------------------------------------------------------------
+
+describe("createReadSkillTool", () => {
+  const skills: Skill[] = [
+    {
+      name: "skill-a",
+      description: "First skill",
+      instructions: "Do A",
+    },
+    {
+      name: "skill-b",
+      description: "Second skill",
+      instructions: "Do B",
+    },
+  ];
+
+  it("creates a tool with correct name and dynamic schema", () => {
+    const tool = createReadSkillTool(skills);
+
+    expect(tool.name).toBe("ReadSkill");
+    expect(tool.description).toContain("skill-a");
+    expect(tool.description).toContain("skill-b");
+    expect(tool.description).toContain("First skill");
+    expect(tool.description).toContain("Second skill");
+  });
+
+  it("schema validates skill_name enum", () => {
+    const tool = createReadSkillTool(skills);
+
+    const validResult = tool.schema.safeParse({ skill_name: "skill-a" });
+    expect(validResult.success).toBe(true);
+
+    const invalidResult = tool.schema.safeParse({ skill_name: "nonexistent" });
+    expect(invalidResult.success).toBe(false);
+  });
+
+  it("throws when no skills are provided", () => {
+    expect(() => createReadSkillTool([])).toThrow(
+      "createReadSkillTool requires at least one skill",
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// createReadSkillHandler
+// ---------------------------------------------------------------------------
+
+describe("createReadSkillHandler", () => {
+  const skills: Skill[] = [
+    {
+      name: "skill-a",
+      description: "First skill",
+      instructions: "Instructions for A",
+    },
+    {
+      name: "skill-b",
+      description: "Second skill",
+      instructions: "Instructions for B",
+    },
+  ];
+
+  it("returns skill instructions for a valid skill name", () => {
+    const handler = createReadSkillHandler(skills);
+    const result = handler({ skill_name: "skill-a" });
+
+    expect(result.toolResponse).toBe("Instructions for A");
+    expect(result.data).toBeNull();
+  });
+
+  it("returns error for unknown skill name", () => {
+    const handler = createReadSkillHandler(skills);
+    const result = handler({ skill_name: "nonexistent" });
+
+    expect(typeof result.toolResponse).toBe("string");
+    expect((result.toolResponse as string)).toContain("not found");
+    expect(result.data).toBeNull();
+  });
+
+  it("handles single skill", () => {
+    const firstSkill = skills[0];
+    if (!firstSkill) throw new Error("expected skill");
+    const handler = createReadSkillHandler([firstSkill]);
+    const result = handler({ skill_name: "skill-a" });
+    expect(result.toolResponse).toBe("Instructions for A");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildSkillRegistration
+// ---------------------------------------------------------------------------
+
+describe("buildSkillRegistration", () => {
+  it("returns null for empty skills array", () => {
+    expect(buildSkillRegistration([])).toBeNull();
+  });
+
+  it("returns a complete tool entry with handler", () => {
+    const skills: Skill[] = [
+      {
+        name: "my-skill",
+        description: "My skill",
+        instructions: "Do things",
+      },
+    ];
+
+    const registration = buildSkillRegistration(skills);
+
+    expect(registration).not.toBeNull();
+    expect(registration).toBeDefined();
+    if (registration) {
+      expect(registration.name).toBe("ReadSkill");
+      expect(registration.handler).toBeDefined();
+      expect(typeof registration.handler).toBe("function");
+    }
+  });
+
+  it("registered handler works end-to-end", () => {
+    const skills: Skill[] = [
+      {
+        name: "test-skill",
+        description: "Test",
+        instructions: "Test instructions content",
+      },
+    ];
+
+    const registration = buildSkillRegistration(skills);
+    expect(registration).toBeDefined();
+    if (!registration) return;
+    const result = registration.handler(
+      { skill_name: "test-skill" },
+      { threadId: "t-1", toolCallId: "tc-1", toolName: "ReadSkill" },
+    );
+
+    if (result instanceof Promise) {
+      return result.then((r) => {
+        expect(r.toolResponse).toBe("Test instructions content");
+      });
+    }
+    expect(result.toolResponse).toBe("Test instructions content");
+    return;
+  });
+});

package/src/lib/state/manager.integration.test.ts

@@ -0,0 +1,342 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { z } from "zod";
+
+let idCounter = 0;
+
+vi.mock("@temporalio/workflow", () => {
+  return {
+    condition: async (fn: () => boolean) => fn(),
+    defineUpdate: (name: string) => ({ __type: "update", name }),
+    defineQuery: (name: string) => ({ __type: "query", name }),
+    setHandler: (_def: unknown, _handler: unknown) => {},
+    uuid4: () =>
+      `00000000-0000-0000-0000-${String(++idCounter).padStart(12, "0")}`,
+  };
+});
+
+import { createAgentStateManager } from "./manager";
+import type { WorkflowTask } from "../types";
+
+describe("createAgentStateManager integration", () => {
+  beforeEach(() => {
+    idCounter = 0;
+  });
+
+  // --- Default initial state ---
+
+  it("initializes with default values when no initialState given", () => {
+    const sm = createAgentStateManager({});
+
+    expect(sm.getStatus()).toBe("RUNNING");
+    expect(sm.getTurns()).toBe(0);
+    expect(sm.getVersion()).toBe(0);
+    expect(sm.isRunning()).toBe(true);
+    expect(sm.isTerminal()).toBe(false);
+    expect(sm.getSystemPrompt()).toBeUndefined();
+    expect(sm.getTasks()).toEqual([]);
+    expect(sm.getTotalUsage()).toEqual({
+      totalInputTokens: 0,
+      totalOutputTokens: 0,
+      totalCachedWriteTokens: 0,
+      totalCachedReadTokens: 0,
+      totalReasonTokens: 0,
+      turns: 0,
+    });
+  });
+
+  // --- Status transitions ---
+
+  it("transitions through all status states and increments version", () => {
+    const sm = createAgentStateManager({});
+
+    expect(sm.getStatus()).toBe("RUNNING");
+    expect(sm.getVersion()).toBe(0);
+
+    sm.waitForInput();
+    expect(sm.getStatus()).toBe("WAITING_FOR_INPUT");
+    expect(sm.getVersion()).toBe(1);
+    expect(sm.isRunning()).toBe(false);
+    expect(sm.isTerminal()).toBe(false);
+
+    sm.run();
+    expect(sm.getStatus()).toBe("RUNNING");
+    expect(sm.getVersion()).toBe(2);
+    expect(sm.isRunning()).toBe(true);
+
+    sm.complete();
+    expect(sm.getStatus()).toBe("COMPLETED");
+    expect(sm.isTerminal()).toBe(true);
+
+    sm.fail();
+    expect(sm.getStatus()).toBe("FAILED");
+    expect(sm.isTerminal()).toBe(true);
+
+    sm.cancel();
+    expect(sm.getStatus()).toBe("CANCELLED");
+    expect(sm.isTerminal()).toBe(true);
+  });
+
+  // --- Turns ---
+
+  it("increments turns independently of version", () => {
+    const sm = createAgentStateManager({});
+
+    sm.incrementTurns();
+    sm.incrementTurns();
+    sm.incrementTurns();
+    expect(sm.getTurns()).toBe(3);
+    expect(sm.getVersion()).toBe(0);
+  });
+
+  // --- Custom state ---
+
+  it("manages custom state via get/set with version increments", () => {
+    const sm = createAgentStateManager<{ score: number; label: string }>({
+      initialState: { systemPrompt: "test", score: 0, label: "init" },
+    });
+
+    expect(sm.get("score")).toBe(0);
+    expect(sm.get("label")).toBe("init");
+
+    sm.set("score", 42);
+    expect(sm.get("score")).toBe(42);
+    expect(sm.getVersion()).toBe(1);
+
+    sm.set("label", "updated");
+    expect(sm.get("label")).toBe("updated");
+    expect(sm.getVersion()).toBe(2);
+  });
+
+  it("mergeUpdate bulk-updates custom state", () => {
+    const sm = createAgentStateManager<{ a: string; b: number }>({
+      initialState: { systemPrompt: "test", a: "old", b: 0 },
+    });
+
+    sm.mergeUpdate({ a: "new", b: 99 });
+    expect(sm.get("a")).toBe("new");
+    expect(sm.get("b")).toBe(99);
+    expect(sm.getVersion()).toBe(1);
+  });
+
+  it("mergeUpdate with partial fields only updates provided keys", () => {
+    const sm = createAgentStateManager<{ x: string; y: string }>({
+      initialState: { systemPrompt: "test", x: "orig-x", y: "orig-y" },
+    });
+
+    sm.mergeUpdate({ x: "changed" });
+    expect(sm.get("x")).toBe("changed");
+    expect(sm.get("y")).toBe("orig-y");
+  });
+
+  // --- System prompt ---
+
+  it("manages system prompt lifecycle", () => {
+    const sm = createAgentStateManager({
+      initialState: { systemPrompt: "initial prompt" },
+    });
+
+    expect(sm.getSystemPrompt()).toBe("initial prompt");
+
+    sm.setSystemPrompt("updated prompt");
+    expect(sm.getSystemPrompt()).toBe("updated prompt");
+  });
+
+  // --- Token usage accumulation ---
+
+  it("accumulates token usage across multiple updates", () => {
+    const sm = createAgentStateManager({});
+
+    sm.updateUsage({ inputTokens: 100, outputTokens: 50 });
+    sm.updateUsage({ inputTokens: 200, outputTokens: 100, cachedWriteTokens: 30 });
+    sm.updateUsage({ cachedReadTokens: 20, reasonTokens: 10 });
+
+    expect(sm.getTotalUsage()).toEqual({
+      totalInputTokens: 300,
+      totalOutputTokens: 150,
+      totalCachedWriteTokens: 30,
+      totalCachedReadTokens: 20,
+      totalReasonTokens: 10,
+      turns: 0,
+    });
+  });
+
+  it("handles updateUsage with undefined fields gracefully", () => {
+    const sm = createAgentStateManager({});
+
+    sm.updateUsage({});
+    sm.updateUsage({ inputTokens: undefined, outputTokens: undefined });
+
+    expect(sm.getTotalUsage().totalInputTokens).toBe(0);
+    expect(sm.getTotalUsage().totalOutputTokens).toBe(0);
+  });
+
+  // --- Task management ---
+
+  it("CRUD operations on tasks", () => {
+    const sm = createAgentStateManager({});
+
+    const task: WorkflowTask = {
+      id: "task-1",
+      subject: "Test task",
+      description: "A test task",
+      activeForm: "Testing",
+      status: "pending",
+      metadata: {},
+      blockedBy: [],
+      blocks: [],
+    };
+
+    sm.setTask(task);
+    expect(sm.getTasks()).toHaveLength(1);
+    expect(sm.getTask("task-1")).toEqual(task);
+    expect(sm.getVersion()).toBe(1);
+
+    sm.setTask({ ...task, status: "in_progress" });
+    expect(sm.getTask("task-1")?.status).toBe("in_progress");
+    expect(sm.getVersion()).toBe(2);
+
+    expect(sm.deleteTask("task-1")).toBe(true);
+    expect(sm.getTasks()).toHaveLength(0);
+    expect(sm.getTask("task-1")).toBeUndefined();
+    expect(sm.getVersion()).toBe(3);
+  });
+
+  it("deleteTask returns false for nonexistent task and does not increment version", () => {
+    const sm = createAgentStateManager({});
+
+    expect(sm.deleteTask("nonexistent")).toBe(false);
+    expect(sm.getVersion()).toBe(0);
+  });
+
+  it("manages multiple tasks simultaneously", () => {
+    const sm = createAgentStateManager({});
+
+    const makeTask = (id: string, subject: string): WorkflowTask => ({
+      id,
+      subject,
+      description: "",
+      activeForm: "",
+      status: "pending",
+      metadata: {},
+      blockedBy: [],
+      blocks: [],
+    });
+
+    sm.setTask(makeTask("t1", "Task 1"));
+    sm.setTask(makeTask("t2", "Task 2"));
+    sm.setTask(makeTask("t3", "Task 3"));
+
+    expect(sm.getTasks()).toHaveLength(3);
+    sm.deleteTask("t2");
+    expect(sm.getTasks()).toHaveLength(2);
+    expect(sm.getTask("t2")).toBeUndefined();
+    expect(sm.getTask("t1")).toBeDefined();
+    expect(sm.getTask("t3")).toBeDefined();
+  });
+
+  // --- getCurrentState ---
+
+  it("getCurrentState returns a snapshot including custom state", () => {
+    const sm = createAgentStateManager<{ mood: string }>({
+      initialState: { systemPrompt: "test", mood: "happy", status: "RUNNING" },
+    });
+
+    sm.incrementTurns();
+    sm.incrementTurns();
+
+    const state = sm.getCurrentState();
+    expect(state.status).toBe("RUNNING");
+    expect(state.turns).toBe(2);
+    expect(state.mood).toBe("happy");
+  });
+
+  // --- shouldReturnFromWait ---
+
+  it("shouldReturnFromWait returns true when version advanced", () => {
+    const sm = createAgentStateManager({});
+
+    expect(sm.shouldReturnFromWait(0)).toBe(false);
+    sm.incrementVersion();
+    expect(sm.shouldReturnFromWait(0)).toBe(true);
+    expect(sm.shouldReturnFromWait(1)).toBe(false);
+  });
+
+  it("shouldReturnFromWait returns true in terminal state regardless of version", () => {
+    const sm = createAgentStateManager({});
+
+    sm.complete();
+    expect(sm.shouldReturnFromWait(999)).toBe(true);
+  });
+
+  // --- Initial state with pre-set tasks ---
+
+  it("initializes with provided tasks map", () => {
+    const tasks = new Map<string, WorkflowTask>([
+      [
+        "preloaded",
+        {
+          id: "preloaded",
+          subject: "Preloaded task",
+          description: "",
+          activeForm: "",
+          status: "completed",
+          metadata: {},
+          blockedBy: [],
+          blocks: [],
+        },
+      ],
+    ]);
+
+    const sm = createAgentStateManager({
+      initialState: { systemPrompt: "test", tasks },
+    });
+
+    expect(sm.getTasks()).toHaveLength(1);
+    expect(sm.getTask("preloaded")?.status).toBe("completed");
+  });
+
+  // --- setTools ---
+
+  it("setTools stores serializable tool definitions in state", () => {
+    const sm = createAgentStateManager({});
+
+    sm.setTools([
+      {
+        name: "TestTool",
+        description: "A test tool",
+        schema: z.object({ input: z.string() }),
+      },
+    ]);
+
+    const state = sm.getCurrentState();
+    expect(state.tools).toHaveLength(1);
+    const firstTool = state.tools[0];
+    if (!firstTool) throw new Error("expected tool");
+    expect(firstTool.name).toBe("TestTool");
+    expect(firstTool.description).toBe("A test tool");
+    expect(firstTool.schema).toBeDefined();
+    expect(typeof firstTool.schema).toBe("object");
+  });
+
+  // --- incrementVersion standalone ---
+
+  it("incrementVersion works independently", () => {
+    const sm = createAgentStateManager({});
+
+    sm.incrementVersion();
+    sm.incrementVersion();
+    sm.incrementVersion();
+    expect(sm.getVersion()).toBe(3);
+    expect(sm.getStatus()).toBe("RUNNING");
+  });
+
+  // --- Usage turns are linked to incrementTurns ---
+
+  it("getTotalUsage.turns reflects incrementTurns count", () => {
+    const sm = createAgentStateManager({});
+
+    sm.incrementTurns();
+    sm.incrementTurns();
+    expect(sm.getTotalUsage().turns).toBe(2);
+  });
+});