zeitlich 0.2.8 → 0.2.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zeitlich",
-  "version": "0.2.8",
+  "version": "0.2.11",
   "description": "[EXPERIMENTAL] An opinionated AI agent implementation for Temporal",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -69,16 +69,16 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@temporalio/envconfig": "^1.14.1",
-    "@temporalio/worker": "^1.14.1",
-    "@types/node": "^25.3.0",
-    "eslint": "^10.0.0",
+    "@temporalio/envconfig": "^1.15.0",
+    "@temporalio/worker": "^1.15.0",
+    "@types/node": "^25.3.3",
+    "eslint": "^10.0.2",
     "husky": "^9.1.7",
-    "prettier": "^3.2.0",
-    "release-please": "^17.2.0",
-    "tsup": "^8.0.0",
-    "typescript": "^5.3.0",
-    "typescript-eslint": "^8.0.0",
+    "prettier": "^3.8.1",
+    "release-please": "^17.3.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.56.1",
     "vitest": "^4.0.18"
   },
   "peerDependencies": {
@@ -90,11 +90,11 @@
   },
   "homepage": "https://github.com/bead-ai/zeitlich#readme",
   "dependencies": {
-    "@langchain/core": "^1.1.18",
-    "@temporalio/common": "^1.14.1",
-    "@temporalio/plugin": "^1.14.1",
-    "@temporalio/workflow": "^1.14.1",
-    "just-bash": "^2.9.2",
+    "@langchain/core": "^1.1.29",
+    "@temporalio/common": "^1.15.0",
+    "@temporalio/plugin": "^1.15.0",
+    "@temporalio/workflow": "^1.15.0",
+    "just-bash": "^2.11.6",
     "zod": "^4.3.6"
   }
 }

package/src/index.ts

@@ -45,6 +45,9 @@ export { createBashHandler } from "./tools/bash/handler";
 
 export { toTree } from "./lib/fs";
 
+// Skills (activity-side: filesystem provider)
+export { FileSystemSkillProvider } from "./lib/skills/fs-provider";
+
 export { createThreadManager } from "./lib/thread-manager";
 export type {
   BaseThreadManager,

package/src/lib/model-invoker.ts

@@ -1,6 +1,6 @@
 import type Redis from "ioredis";
 import { createThreadManager } from "./thread-manager";
-import type { AgentResponse, BaseAgentState } from "./types";
+import { agentQueryName, type AgentResponse, type BaseAgentState } from "./types";
 import { Context } from "@temporalio/activity";
 import type { WorkflowClient } from "@temporalio/client";
 import { mapStoredMessagesToChatMessages } from "@langchain/core/messages";
@@ -48,7 +48,7 @@ export async function invokeModel({
   const parentRunId = info.workflowExecution.runId;
 
   const handle = client.getHandle(parentWorkflowId, parentRunId);
-  const { tools } = await handle.query<BaseAgentState>(`get${agentName}State`);
+  const { tools } = await handle.query<BaseAgentState>(agentQueryName(agentName));
 
   const messages = await thread.load();
   const response = await model.invoke(

package/src/lib/session.ts

@@ -3,6 +3,7 @@ import {
   condition,
   defineUpdate,
   setHandler,
+  ApplicationFailure,
 } from "@temporalio/workflow";
 import type { ZeitlichSharedActivities } from "../activities";
 import type {
@@ -44,18 +45,17 @@ export interface SessionLifecycleHooks {
 export const createSession = async <T extends ToolMap, M = unknown>({
   threadId,
   agentName,
-  description,
   maxTurns = 50,
   metadata = {},
   runAgent,
   threadOps,
   buildContextMessage,
   subagents,
+  skills,
   tools = {} as T,
   processToolsInParallel = true,
   hooks = {},
   appendSystemPrompt = true,
-  systemPrompt,
   waitForInputTimeout = "48h",
 }: SessionConfig<T, M> & AgentConfig): Promise<ZeitlichSession<M>> => {
   const {
@@ -71,6 +71,7 @@ export const createSession = async <T extends ToolMap, M = unknown>({
     threadId,
     hooks,
     subagents,
+    skills,
     parallel: processToolsInParallel,
   });
 
@@ -126,8 +127,16 @@ export const createSession = async <T extends ToolMap, M = unknown>({
         });
       }
 
+      const systemPrompt = stateManager.getSystemPrompt();
+
       await initializeThread(threadId);
-      if (appendSystemPrompt && systemPrompt && systemPrompt.trim() !== "") {
+      if (appendSystemPrompt) {
+        if (!systemPrompt || systemPrompt.trim() === "") {
+          throw ApplicationFailure.create({
+            message: "No system prompt in state",
+            nonRetryable: true,
+          });
+        }
         await appendSystemMessage(threadId, systemPrompt);
       }
       await appendHumanMessage(threadId, await buildContextMessage());
@@ -149,8 +158,6 @@ export const createSession = async <T extends ToolMap, M = unknown>({
             threadId,
             agentName,
             metadata,
-            systemPrompt,
-            description,
           });
 
           if (usage) {
@@ -219,7 +226,7 @@ export const createSession = async <T extends ToolMap, M = unknown>({
         }
       } catch (error) {
         exitReason = "failed";
-        throw error;
+        throw ApplicationFailure.fromError(error);
       } finally {
         // SessionEnd hook - always called
         await callSessionEnd(exitReason, stateManager.getTurns());
@@ -251,14 +258,13 @@ export function proxyDefaultThreadOps(
 ): ThreadOps {
   const activities = proxyActivities<ZeitlichSharedActivities>(
     options ?? {
-      startToCloseTimeout: "30m",
+      startToCloseTimeout: "10s",
       retry: {
         maximumAttempts: 6,
         initialInterval: "5s",
         maximumInterval: "15m",
         backoffCoefficient: 4,
       },
-      heartbeatTimeout: "5m",
     }
   );
 

package/src/lib/skills/fs-provider.ts

@@ -0,0 +1,84 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { Skill, SkillMetadata, SkillProvider } from "./types";
+import { parseSkillFile } from "./parse";
+
+/**
+ * Loads skills from a filesystem directory following the agentskills.io layout:
+ *
+ * ```
+ * skills/
+ * ├── code-review/
+ * │   └── SKILL.md
+ * ├── pdf-processing/
+ * │   └── SKILL.md
+ * ```
+ *
+ * Activity-side only — cannot be used in Temporal workflow code.
+ */
+export class FileSystemSkillProvider implements SkillProvider {
+  constructor(private readonly baseDir: string) {}
+
+  async listSkills(): Promise<SkillMetadata[]> {
+    const dirs = await this.discoverSkillDirs();
+    const skills: SkillMetadata[] = [];
+
+    for (const dir of dirs) {
+      const raw = await readFile(join(this.baseDir, dir, "SKILL.md"), "utf-8");
+      const { frontmatter } = parseSkillFile(raw);
+      skills.push(frontmatter);
+    }
+
+    return skills;
+  }
+
+  async getSkill(name: string): Promise<Skill> {
+    const raw = await readFile(
+      join(this.baseDir, name, "SKILL.md"),
+      "utf-8"
+    );
+    const { frontmatter, body } = parseSkillFile(raw);
+
+    if (frontmatter.name !== name) {
+      throw new Error(
+        `Skill directory "${name}" contains SKILL.md with mismatched name "${frontmatter.name}"`
+      );
+    }
+
+    return { ...frontmatter, instructions: body };
+  }
+
+  /**
+   * Convenience method to load all skills with full instructions.
+   * Returns `Skill[]` ready to pass into a workflow.
+   */
+  async loadAll(): Promise<Skill[]> {
+    const dirs = await this.discoverSkillDirs();
+    const skills: Skill[] = [];
+
+    for (const dir of dirs) {
+      const raw = await readFile(join(this.baseDir, dir, "SKILL.md"), "utf-8");
+      const { frontmatter, body } = parseSkillFile(raw);
+      skills.push({ ...frontmatter, instructions: body });
+    }
+
+    return skills;
+  }
+
+  private async discoverSkillDirs(): Promise<string[]> {
+    const entries = await readdir(this.baseDir, { withFileTypes: true });
+    const dirs: string[] = [];
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      try {
+        await readFile(join(this.baseDir, entry.name, "SKILL.md"), "utf-8");
+        dirs.push(entry.name);
+      } catch {
+        // No SKILL.md — skip
+      }
+    }
+
+    return dirs;
+  }
+}

package/src/lib/skills/index.ts

@@ -0,0 +1,3 @@
+export type { Skill, SkillMetadata, SkillProvider } from "./types";
+export { parseSkillFile } from "./parse";
+export { FileSystemSkillProvider } from "./fs-provider";

package/src/lib/skills/parse.ts

@@ -0,0 +1,117 @@
+import type { SkillMetadata } from "./types";
+
+/**
+ * Parse a SKILL.md file into its frontmatter fields and markdown body.
+ *
+ * Handles the limited YAML subset used by the agentskills.io spec:
+ * flat key-value pairs plus one-level nested `metadata` map.
+ * No external YAML dependency required.
+ */
+export function parseSkillFile(raw: string): {
+  frontmatter: SkillMetadata;
+  body: string;
+} {
+  const trimmed = raw.replace(/^\uFEFF/, ""); // strip BOM
+  const match = trimmed.match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n?([\s\S]*)$/);
+
+  if (!match) {
+    throw new Error(
+      "SKILL.md must start with YAML frontmatter delimited by ---"
+    );
+  }
+
+  const [, yamlBlock, body] = match as [string, string, string];
+  const frontmatter = parseSimpleYaml(yamlBlock);
+
+  if (!frontmatter.name || typeof frontmatter.name !== "string") {
+    throw new Error("SKILL.md frontmatter must include a 'name' field");
+  }
+  if (!frontmatter.description || typeof frontmatter.description !== "string") {
+    throw new Error("SKILL.md frontmatter must include a 'description' field");
+  }
+
+  const result: SkillMetadata = {
+    name: frontmatter.name,
+    description: frontmatter.description,
+  };
+
+  if (frontmatter.license) result.license = String(frontmatter.license);
+  if (frontmatter.compatibility)
+    result.compatibility = String(frontmatter.compatibility);
+  if (frontmatter["allowed-tools"]) {
+    result.allowedTools = String(frontmatter["allowed-tools"])
+      .split(/\s+/)
+      .filter(Boolean);
+  }
+  if (
+    frontmatter.metadata &&
+    typeof frontmatter.metadata === "object" &&
+    !Array.isArray(frontmatter.metadata)
+  ) {
+    result.metadata = frontmatter.metadata as Record<string, string>;
+  }
+
+  return { frontmatter: result, body: body.trim() };
+}
+
+type YamlValue = string | Record<string, string>;
+
+/**
+ * Minimal YAML parser for the agentskills.io frontmatter subset.
+ * Supports: scalar key-value pairs, one-level nested maps (metadata).
+ * Does NOT support arrays, multi-line strings, anchors, etc.
+ */
+function parseSimpleYaml(yaml: string): Record<string, YamlValue> {
+  const result: Record<string, YamlValue> = {};
+  const lines = yaml.split(/\r?\n/);
+
+  let currentMapKey: string | null = null;
+  let currentMap: Record<string, string> | null = null;
+
+  for (const line of lines) {
+    if (line.trim() === "" || line.trim().startsWith("#")) continue;
+
+    const nestedMatch = line.match(/^(\s{2,}|\t+)(\S+)\s*:\s*(.*)$/);
+    if (nestedMatch && currentMapKey && currentMap) {
+      const [, , key, rawVal] = nestedMatch as [string, string, string, string];
+      currentMap[key] = unquote(rawVal.trim());
+      continue;
+    }
+
+    // Flush any pending nested map
+    if (currentMapKey && currentMap) {
+      result[currentMapKey] = currentMap;
+      currentMapKey = null;
+      currentMap = null;
+    }
+
+    const topMatch = line.match(/^(\S+)\s*:\s*(.*)$/);
+    if (!topMatch) continue;
+
+    const [, key, rawVal] = topMatch as [string, string, string];
+    const val = rawVal.trim();
+
+    if (val === "" || val === "|" || val === ">") {
+      currentMapKey = key;
+      currentMap = {};
+    } else {
+      result[key] = unquote(val);
+    }
+  }
+
+  if (currentMapKey && currentMap) {
+    result[currentMapKey] = currentMap;
+  }
+
+  return result;
+}
+
+function unquote(s: string): string {
+  if (
+    (s.startsWith('"') && s.endsWith('"')) ||
+    (s.startsWith("'") && s.endsWith("'"))
+  ) {
+    return s.slice(1, -1);
+  }
+  return s;
+}

package/src/lib/skills/types.ts

@@ -0,0 +1,41 @@
+/**
+ * Skill metadata — the lightweight subset loaded at startup for all skills.
+ * Follows the agentskills.io specification frontmatter fields.
+ */
+export interface SkillMetadata {
+  /** Lowercase alphanumeric + hyphens, max 64 chars, must match directory name */
+  name: string;
+  /** What the skill does and when to use it (max 1024 chars) */
+  description: string;
+  /** License name or reference to a bundled license file */
+  license?: string;
+  /** Environment requirements (intended product, system packages, network access) */
+  compatibility?: string;
+  /** Arbitrary key-value pairs for additional metadata */
+  metadata?: Record<string, string>;
+  /** Space-delimited list of pre-approved tools the skill may use */
+  allowedTools?: string[];
+}
+
+/**
+ * A fully-loaded skill including the SKILL.md instruction body.
+ * Progressive disclosure: metadata is always available, instructions
+ * are loaded on-demand via the ReadSkill tool.
+ */
+export interface Skill extends SkillMetadata {
+  /** The markdown body of SKILL.md (everything after the frontmatter) */
+  instructions: string;
+}
+
+/**
+ * Abstraction for discovering and loading skills.
+ *
+ * Implement this interface to provide skills from any source
+ * (filesystem, database, API, in-memory, etc.).
+ */
+export interface SkillProvider {
+  /** Return lightweight metadata for all available skills */
+  listSkills(): Promise<SkillMetadata[]>;
+  /** Load a single skill with full instructions by name */
+  getSkill(name: string): Promise<Skill>;
+}

package/src/lib/state-manager.ts

@@ -3,13 +3,16 @@ import {
   defineQuery,
   defineUpdate,
   setHandler,
+  type QueryDefinition,
 } from "@temporalio/workflow";
+import type { UpdateDefinition } from "@temporalio/common/lib/interfaces";
 import {
-  type AgentConfig,
   type AgentStatus,
   type BaseAgentState,
   type WorkflowTask,
   isTerminalStatus,
+  agentQueryName,
+  agentStateChangeUpdateName,
 } from "./types";
 import type { ToolDefinition } from "./tool-router";
 import { z } from "zod";
@@ -61,6 +64,11 @@ export type AgentState<TCustom extends JsonSerializable<TCustom>> =
  * the state and helpers needed for those handlers.
  */
 export interface AgentStateManager<TCustom extends JsonSerializable<TCustom>> {
+  /** Typed query definition registered for this agent's state */
+  readonly stateQuery: QueryDefinition<AgentState<TCustom>>;
+  /** Typed update definition registered for waiting on this agent's state change */
+  readonly stateChangeUpdate: UpdateDefinition<AgentState<TCustom>, [number]>;
+
   /** Get current status */
   getStatus(): AgentStatus;
   /** Check if agent is running */
@@ -90,6 +98,12 @@ export interface AgentStateManager<TCustom extends JsonSerializable<TCustom>> {
   /** Get current turns */
   getTurns(): number;
 
+  /** Get the system prompt */
+  getSystemPrompt(): string | undefined;
+
+  /** Set the system prompt */
+  setSystemPrompt(newSystemPrompt: string): void;
+
   /** Get a custom state value by key */
   get<K extends keyof TCustom>(key: K): TCustom[K];
 
@@ -149,10 +163,10 @@ export function createAgentStateManager<
   TCustom extends JsonSerializable<TCustom> = Record<string, never>,
 >({
   initialState,
-  agentConfig,
+  agentName,
 }: {
   initialState?: Partial<BaseAgentState> & TCustom;
-  agentConfig: AgentConfig;
+  agentName: string;
 }): AgentStateManager<TCustom> {
   // Default state (BaseAgentState fields)
   let status: AgentStatus = initialState?.status ?? "RUNNING";
@@ -164,6 +178,7 @@ export function createAgentStateManager<
   let totalCachedWriteTokens = 0;
   let totalCachedReadTokens = 0;
   let totalReasonTokens = 0;
+  let systemPrompt = initialState?.systemPrompt;
 
   // Tasks state
   const tasks = new Map<string, WorkflowTask>(initialState?.tasks);
@@ -189,24 +204,26 @@ export function createAgentStateManager<
     } as AgentState<TCustom>;
   }
 
-  setHandler(defineQuery(`get${agentConfig.agentName}State`), () => {
+  const stateQuery = defineQuery<AgentState<TCustom>>(
+    agentQueryName(agentName)
+  );
+  const stateChangeUpdate = defineUpdate<AgentState<TCustom>, [number]>(
+    agentStateChangeUpdateName(agentName)
+  );
+
+  setHandler(stateQuery, () => buildState());
+  setHandler(stateChangeUpdate, async (lastKnownVersion: number) => {
+    await condition(
+      () => version > lastKnownVersion || isTerminalStatus(status),
+      "55s"
+    );
     return buildState();
   });
 
-  setHandler(
-    defineUpdate<AgentState<TCustom>, [number]>(
-      `waitFor${agentConfig.agentName}StateChange`
-    ),
-    async (lastKnownVersion: number) => {
-      await condition(
-        () => version > lastKnownVersion || isTerminalStatus(status),
-        "55s"
-      );
-      return buildState();
-    }
-  );
-
   return {
+    stateQuery,
+    stateChangeUpdate,
+
     getStatus(): AgentStatus {
       return status;
     },
@@ -215,6 +232,10 @@ export function createAgentStateManager<
       return status === "RUNNING";
     },
 
+    getSystemPrompt(): string | undefined {
+      return systemPrompt;
+    },
+
     isTerminal(): boolean {
       return isTerminalStatus(status);
     },
@@ -300,6 +321,10 @@ export function createAgentStateManager<
       }));
     },
 
+    setSystemPrompt(newSystemPrompt: string): void {
+      systemPrompt = newSystemPrompt;
+    },
+
     deleteTask(id: string): boolean {
       const deleted = tasks.delete(id);
       if (deleted) {
@@ -341,12 +366,3 @@ export function createAgentStateManager<
     },
   };
 }
-
-/**
- * Handler names used across agents
- */
-export const AGENT_HANDLER_NAMES = {
-  getAgentState: "getAgentState",
-  waitForStateChange: "waitForStateChange",
-  addMessage: "addMessage",
-} as const;

package/src/lib/thread-manager.ts

@@ -14,6 +14,27 @@ import { v4 as uuidv4 } from "uuid";
 
 const THREAD_TTL_SECONDS = 60 * 60 * 24 * 90; // 90 days
 
+/**
+ * Lua script for atomic idempotent append.
+ * Checks a dedup key; if it exists the message was already appended and we
+ * return 0. Otherwise appends all messages to the list, sets TTL on both
+ * the list and the dedup key, and returns 1.
+ *
+ * KEYS[1] = dedup key, KEYS[2] = list key
+ * ARGV[1] = TTL seconds, ARGV[2..N] = serialised messages
+ */
+const APPEND_IDEMPOTENT_SCRIPT = `
+if redis.call('EXISTS', KEYS[1]) == 1 then
+  return 0
+end
+for i = 2, #ARGV do
+  redis.call('RPUSH', KEYS[2], ARGV[i])
+end
+redis.call('EXPIRE', KEYS[2], tonumber(ARGV[1]))
+redis.call('SET', KEYS[1], '1', 'EX', tonumber(ARGV[1]))
+return 1
+`;
+
 function getThreadKey(threadId: string, key: string): string {
   return `thread:${threadId}:${key}`;
 }
@@ -33,6 +54,12 @@ export interface ThreadManagerConfig<T = StoredMessage> {
   serialize?: (message: T) => string;
   /** Custom deserializer, defaults to JSON.parse */
   deserialize?: (raw: string) => T;
+  /**
+   * Extract a unique id from a message for idempotent appends.
+   * When provided, `append` uses an atomic Lua script to skip duplicate writes.
+   * Defaults to `StoredMessage.data.id` for the standard ThreadManager.
+   */
+  idOf?: (message: T) => string;
 }
 
 /** Generic thread manager for any message type */
@@ -41,7 +68,11 @@ export interface BaseThreadManager<T> {
   initialize(): Promise<void>;
   /** Load all messages from the thread */
   load(): Promise<T[]>;
-  /** Append messages to the thread */
+  /**
+   * Append messages to the thread.
+   * When `idOf` is configured, appends are idempotent — retries with the
+   * same message ids are atomically skipped via a Redis Lua script.
+   */
   append(messages: T[]): Promise<void>;
   /** Delete the thread */
   delete(): Promise<void>;
@@ -51,6 +82,8 @@ export interface BaseThreadManager<T> {
 export interface ThreadManager extends BaseThreadManager<StoredMessage> {
   /** Create a HumanMessage (returns StoredMessage for storage) */
   createHumanMessage(content: string | MessageContent): StoredMessage;
+  /** Create a SystemMessage (returns StoredMessage for storage) */
+  createSystemMessage(content: string): StoredMessage;
   /** Create an AIMessage with optional additional kwargs */
   createAIMessage(
     content: string | MessageContent,
@@ -74,6 +107,11 @@ export interface ThreadManager extends BaseThreadManager<StoredMessage> {
   appendAIMessage(content: string | MessageContent): Promise<void>;
 }
 
+/** Default id extractor for StoredMessage */
+function storedMessageId(msg: StoredMessage): string {
+  return msg.data.id ?? "";
+}
+
 /**
  * Creates a thread manager for handling conversation state in Redis.
  * Without generic args, returns a full ThreadManager with StoredMessage helpers.
@@ -95,6 +133,13 @@ export function createThreadManager<T>(
   } = config;
   const redisKey = getThreadKey(threadId, key);
 
+  // Default idOf for StoredMessage when no custom serialization is used
+  const idOf =
+    config.idOf ??
+    (!config.serialize
+      ? (storedMessageId as unknown as (m: T) => string)
+      : undefined);
+
   const base: BaseThreadManager<T> = {
     async initialize(): Promise<void> {
       await redis.del(redisKey);
@@ -106,7 +151,20 @@ export function createThreadManager<T>(
     },
 
     async append(messages: T[]): Promise<void> {
-      if (messages.length > 0) {
+      if (messages.length === 0) return;
+
+      if (idOf) {
+        const dedupId = messages.map(idOf).join(":");
+        const dedupKey = getThreadKey(threadId, `dedup:${dedupId}`);
+        await redis.eval(
+          APPEND_IDEMPOTENT_SCRIPT,
+          2,
+          dedupKey,
+          redisKey,
+          String(THREAD_TTL_SECONDS),
+          ...messages.map(serialize)
+        );
+      } else {
         await redis.rpush(redisKey, ...messages.map(serialize));
         await redis.expire(redisKey, THREAD_TTL_SECONDS);
       }
@@ -156,6 +214,7 @@ export function createThreadManager<T>(
       toolCallId: string
     ): StoredMessage {
       return new ToolMessage({
+        id: uuidv4(),
         content: content as MessageContent,
         tool_call_id: toolCallId,
       }).toDict();