zeitlich 0.1.1 → 0.2.0

package/src/lib/types.ts

@@ -0,0 +1,354 @@
+import type { ToolMessageContent } from "./thread-manager";
+import type {
+  BuildInToolDefinitions,
+  InferToolResults,
+  ParsedToolCallUnion,
+  ToolCallResultUnion,
+  ToolDefinition,
+  ToolMap,
+} from "./tool-router";
+
+import type { MessageContent, StoredMessage } from "@langchain/core/messages";
+import type { z } from "zod";
+
+/**
+ * Agent execution status
+ */
+export type AgentStatus =
+  | "RUNNING"
+  | "WAITING_FOR_INPUT"
+  | "COMPLETED"
+  | "FAILED"
+  | "CANCELLED";
+
+/**
+ * Base state that all agents must have
+ */
+export interface BaseAgentState {
+  tools: ToolDefinition[];
+  status: AgentStatus;
+  version: number;
+  turns: number;
+  tasks: Map<string, WorkflowTask>;
+}
+
+/**
+ * File representation for agent workflows
+ */
+export interface AgentFile {
+  /** Database/S3 file ID */
+  id: string;
+  /** Virtual path for agent (e.g., "evidence/invoice.pdf") */
+  path: string;
+  /** Original filename */
+  filename: string;
+  /** Generic description for prompt */
+  description?: string;
+  /** MIME type of the file */
+  mimeType?: string;
+}
+
+/**
+ * Agent response from LLM invocation
+ */
+export interface AgentResponse {
+  message: StoredMessage;
+  stopReason: string | null;
+  usage?: {
+    input_tokens?: number;
+    output_tokens?: number;
+    total_tokens?: number;
+  };
+}
+
+/**
+ * Configuration for a Zeitlich agent session
+ */
+export interface ZeitlichAgentConfig<T extends ToolMap> {
+  buildFileTree?: () => Promise<string>;
+  threadId: string;
+  agentName: string;
+  metadata?: Record<string, unknown>;
+  maxTurns?: number;
+  /** Workflow-specific runAgent activity (with tools pre-bound) */
+  runAgent: RunAgentActivity;
+  /** Tool router for processing tool calls (optional if agent has no tools) */
+  tools?: T;
+  /** Subagent configurations */
+  subagents?: SubagentConfig[];
+  /** Session lifecycle hooks */
+  hooks?: Hooks<T, ToolCallResultUnion<InferToolResults<T>>>;
+  /** Whether to process tools in parallel */
+  processToolsInParallel?: boolean;
+  /**
+   * Base system prompt (e.g., Auditron identity).
+   * Can be a static string or async function.
+   */
+  baseSystemPrompt: string | (() => string | Promise<string>);
+  /**
+   * Agent-specific instructions prompt.
+   * Can be a static string or async function.
+   */
+  instructionsPrompt: string | (() => string | Promise<string>);
+  /**
+   * Build context message content from agent-specific context.
+   * Returns MessageContent array for the initial HumanMessage.
+   */
+  buildContextMessage: () => MessageContent | Promise<MessageContent>;
+  /**
+   * Build in tools - accepts raw handlers or proxied activities
+   */
+  buildInTools?: {
+    [K in keyof BuildInToolDefinitions]?: BuildInToolDefinitions[K]["handler"];
+  };
+}
+
+/**
+ * Configuration passed to runAgent activity
+ */
+export interface RunAgentConfig {
+  threadId: string;
+  agentName: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Type signature for workflow-specific runAgent activity
+ */
+export type RunAgentActivity = (
+  config: RunAgentConfig
+) => Promise<AgentResponse>;
+/**
+ * Configuration for appending a tool result
+ */
+export interface ToolResultConfig {
+  threadId: string;
+  toolCallId: string;
+  /** Content for the tool message (string or complex content parts) */
+  content: ToolMessageContent;
+}
+
+// ============================================================================
+// Subagent Configuration
+// ============================================================================
+
+/**
+ * Configuration for a subagent that can be spawned by the parent workflow.
+ *
+ * @template TResult - Zod schema type for validating the child workflow's result
+ */
+export interface SubagentConfig<TResult extends z.ZodType = z.ZodType> {
+  /** Identifier used in Task tool's subagent parameter */
+  name: string;
+  /** Description shown to the parent agent explaining what this subagent does */
+  description: string;
+  /** Temporal workflow type name (used with executeChild) */
+  workflowType: string;
+  /** Optional task queue - defaults to parent's queue if not specified */
+  taskQueue?: string;
+  /** Optional Zod schema to validate the child workflow's result. If omitted, result is passed through as-is. */
+  resultSchema?: TResult;
+}
+
+/**
+ * Input passed to child workflows when spawned as subagents
+ */
+export interface SubagentInput {
+  /** The prompt/task from the parent agent */
+  prompt: string;
+}
+
+// ============================================================================
+// Workflow Tasks
+// ============================================================================
+
+/**
+ * Status of a workflow task
+ */
+export type TaskStatus = "pending" | "in_progress" | "completed";
+
+/**
+ * A task managed within a workflow for tracking work items
+ */
+export interface WorkflowTask {
+  /** Unique task identifier */
+  id: string;
+  /** Brief, actionable title in imperative form */
+  subject: string;
+  /** Detailed description of what needs to be done */
+  description: string;
+  /** Present continuous form shown in spinner when in_progress */
+  activeForm: string;
+  /** Current status of the task */
+  status: TaskStatus;
+  /** Arbitrary key-value pairs for tracking */
+  metadata: Record<string, string>;
+  /** IDs of tasks that must complete before this one can start */
+  blockedBy: string[];
+  /** IDs of tasks that are waiting for this one to complete */
+  blocks: string[];
+}
+
+// ============================================================================
+// Session Lifecycle Hooks
+// ============================================================================
+
+/**
+ * Exit reasons for session termination
+ */
+export type SessionExitReason =
+  | "completed"
+  | "max_turns"
+  | "waiting_for_input"
+  | "failed"
+  | "cancelled";
+
+/**
+ * Context for PreToolUse hook - called before tool execution
+ */
+export interface PreToolUseHookContext<T extends ToolMap> {
+  /** The tool call about to be executed */
+  toolCall: ParsedToolCallUnion<T>;
+  /** Thread identifier */
+  threadId: string;
+  /** Current turn number */
+  turn: number;
+}
+
+/**
+ * Result from PreToolUse hook - can block or modify execution
+ */
+export interface PreToolUseHookResult {
+  /** Skip this tool call entirely */
+  skip?: boolean;
+  /** Modified args to use instead (must match schema) */
+  modifiedArgs?: unknown;
+}
+
+/**
+ * PreToolUse hook - called before tool execution, can block or modify
+ */
+export type PreToolUseHook<T extends ToolMap> = (
+  ctx: PreToolUseHookContext<T>
+) => PreToolUseHookResult | Promise<PreToolUseHookResult>;
+
+/**
+ * Context for PostToolUse hook - called after successful tool execution
+ */
+export interface PostToolUseHookContext<T extends ToolMap, TResult = unknown> {
+  /** The tool call that was executed */
+  toolCall: ParsedToolCallUnion<T>;
+  /** The result from the tool handler */
+  result: TResult;
+  /** Thread identifier */
+  threadId: string;
+  /** Current turn number */
+  turn: number;
+  /** Execution duration in milliseconds */
+  durationMs: number;
+}
+
+/**
+ * PostToolUse hook - called after successful tool execution
+ */
+export type PostToolUseHook<T extends ToolMap, TResult = unknown> = (
+  ctx: PostToolUseHookContext<T, TResult>
+) => void | Promise<void>;
+
+/**
+ * Context for PostToolUseFailure hook - called when tool execution fails
+ */
+export interface PostToolUseFailureHookContext<T extends ToolMap> {
+  /** The tool call that failed */
+  toolCall: ParsedToolCallUnion<T>;
+  /** The error that occurred */
+  error: Error;
+  /** Thread identifier */
+  threadId: string;
+  /** Current turn number */
+  turn: number;
+}
+
+/**
+ * Result from PostToolUseFailure hook - can recover from errors
+ */
+export interface PostToolUseFailureHookResult {
+  /** Provide a fallback result instead of throwing */
+  fallbackContent?: ToolMessageContent;
+  /** Whether to suppress the error (still logs, but continues) */
+  suppress?: boolean;
+}
+
+/**
+ * PostToolUseFailure hook - called when tool execution fails
+ */
+export type PostToolUseFailureHook<T extends ToolMap> = (
+  ctx: PostToolUseFailureHookContext<T>
+) => PostToolUseFailureHookResult | Promise<PostToolUseFailureHookResult>;
+
+/**
+ * Context for SessionStart hook - called when session begins
+ */
+export interface SessionStartHookContext {
+  /** Thread identifier */
+  threadId: string;
+  /** Name of the agent */
+  agentName: string;
+  /** Session metadata */
+  metadata: Record<string, unknown>;
+}
+
+/**
+ * SessionStart hook - called when session begins
+ */
+export type SessionStartHook = (
+  ctx: SessionStartHookContext
+) => void | Promise<void>;
+
+/**
+ * Context for SessionEnd hook - called when session ends
+ */
+export interface SessionEndHookContext {
+  /** Thread identifier */
+  threadId: string;
+  /** Name of the agent */
+  agentName: string;
+  /** Reason the session ended */
+  exitReason: SessionExitReason;
+  /** Total turns executed */
+  turns: number;
+  /** Session metadata */
+  metadata: Record<string, unknown>;
+}
+
+/**
+ * SessionEnd hook - called when session ends
+ */
+export type SessionEndHook = (
+  ctx: SessionEndHookContext
+) => void | Promise<void>;
+
+/**
+ * Combined hooks interface for session lifecycle
+ */
+export interface Hooks<T extends ToolMap, TResult = unknown> {
+  /** Called before each tool execution - can block or modify */
+  onPreToolUse?: PreToolUseHook<T>;
+  /** Called after each successful tool execution */
+  onPostToolUse?: PostToolUseHook<T, TResult>;
+  /** Called when tool execution fails */
+  onPostToolUseFailure?: PostToolUseFailureHook<T>;
+  /** Called when session starts */
+  onSessionStart?: SessionStartHook;
+  /** Called when session ends */
+  onSessionEnd?: SessionEndHook;
+}
+
+/**
+ * Helper to check if status is terminal
+ */
+export function isTerminalStatus(status: AgentStatus): boolean {
+  return (
+    status === "COMPLETED" || status === "FAILED" || status === "CANCELLED"
+  );
+}

package/src/plugin.ts

@@ -0,0 +1,28 @@
+import { SimplePlugin } from "@temporalio/plugin";
+import { createSharedActivities } from "./activities";
+import type Redis from "ioredis";
+
+/**
+ * Options for the Zeitlich plugin
+ *
+ * @experimental The Zeitlich plugin is an experimental feature; APIs may change without notice.
+ */
+export interface ZeitlichPluginOptions {
+  redis: Redis;
+}
+
+/**
+ * A Temporal plugin that integrates Zeitlich for use in workflows.
+ * This plugin creates shared activities for thread management.
+ * Workflow-specific activities (like runAgent) should be created separately.
+ *
+ * @experimental The Zeitlich plugin is an experimental feature; APIs may change without notice.
+ */
+export class ZeitlichPlugin extends SimplePlugin {
+  constructor(options: ZeitlichPluginOptions) {
+    super({
+      name: "ZeitlichPlugin",
+      activities: createSharedActivities(options.redis),
+    });
+  }
+}

package/src/tools/ask-user-question/handler.ts

@@ -0,0 +1,25 @@
+import { AIMessage, type StoredMessage } from "@langchain/core/messages";
+import type { ActivityToolHandler } from "../../lib/tool-router";
+import type { AskUserQuestionToolSchemaType } from "./tool";
+
+/**
+ * Handle user interaction tool result - creates AI messages for display.
+ */
+export const handleAskUserQuestionToolResult: ActivityToolHandler<
+  AskUserQuestionToolSchemaType,
+  { chatMessages: StoredMessage[] }
+> = async (args) => {
+  const messages = args.questions.map(
+    ({ question, header, options, multiSelect }) =>
+      new AIMessage({
+        content: question,
+        additional_kwargs: {
+          header,
+          options,
+          multiSelect,
+        },
+      }).toDict()
+  );
+
+  return { content: "Question submitted", result: { chatMessages: messages } };
+};

package/src/tools/ask-user-question/tool.ts

@@ -0,0 +1,46 @@
+import z from "zod";
+
+export const askUserQuestionTool = {
+  name: "AskUserQuestion" as const,
+  description: `Use this tool when you need to ask the user questions during execution. This allows you to:
+
+1. Gather user preferences or requirements
+2. Clarify ambiguous instructions
+3. Get decisions on implementation choices as you work
+4. Offer choices to the user about what direction to take.
+
+Usage notes:
+
+* Users will always be able to select "Other" to provide custom text input
+* Use multiSelect: true to allow multiple answers to be selected for a question
+* If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label
+`,
+  schema: z.object({
+    questions: z.array(
+      z.object({
+        question: z.string().describe("The full question text to display"),
+        header: z
+          .string()
+          .describe("Short label for the question (max 12 characters)"),
+        options: z
+          .array(
+            z.object({
+              label: z.string(),
+              description: z.string(),
+            })
+          )
+          .min(0)
+          .max(4)
+          .describe("Array of 0-4 choices, each with label and description"),
+        multiSelect: z
+          .boolean()
+          .describe("If true, users can select multiple options"),
+      })
+    ),
+  }),
+  strict: true,
+};
+
+export type AskUserQuestionToolSchemaType = z.infer<
+  typeof askUserQuestionTool.schema
+>;

package/src/tools/bash/bash.test.ts

@@ -0,0 +1,104 @@
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { describe, expect, it } from "vitest";
+import { handleBashTool } from "./handler";
+import { OverlayFs } from "just-bash";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+describe("bash with default options", () => {
+  const fs = new OverlayFs({ root: __dirname, mountPoint: "/home/user" });
+
+  it("executes echo and captures stdout", async () => {
+    const { result } = await handleBashTool(fs)(
+      { command: "echo 'hello world'" },
+      {}
+    );
+    expect(result).not.toBeNull();
+    expect(result?.stdout.trim()).toBe("hello world");
+    expect(result?.exitCode).toBe(0);
+  });
+
+  it("returns exit code 0 for successful commands", async () => {
+    const { result } = await handleBashTool(fs)({ command: "true" }, {});
+    expect(result?.exitCode).toBe(0);
+  });
+
+  it("returns non-zero exit code for failed commands", async () => {
+    const { result } = await handleBashTool(fs)({ command: "false" }, {});
+    expect(result?.exitCode).toBe(1);
+  });
+
+  it("captures stderr output", async () => {
+    const { result } = await handleBashTool(fs)(
+      { command: "echo 'error message' >&2" },
+      {}
+    );
+    expect(result?.stderr.trim()).toBe("error message");
+    expect(result?.stdout.trim()).toBe("");
+  });
+
+  it("supports piping between commands", async () => {
+    const { result } = await handleBashTool(fs)(
+      { command: "echo 'hello world' | tr 'a-z' 'A-Z'" },
+      {}
+    );
+    expect(result?.stdout.trim()).toBe("HELLO WORLD");
+  });
+
+  it("supports command chaining with &&", async () => {
+    const { result } = await handleBashTool(fs)(
+      { command: "echo 'first' && echo 'second'" },
+      {}
+    );
+    expect(result?.stdout).toContain("first");
+    expect(result?.stdout).toContain("second");
+  });
+
+  it("handles multi-line output", async () => {
+    const { result } = await handleBashTool(fs)(
+      { command: "printf 'line1\\nline2\\nline3'" },
+      {}
+    );
+    const lines = result?.stdout.split("\n");
+    expect(lines).toHaveLength(3);
+    expect(lines?.[0]).toBe("line1");
+    expect(lines?.[2]).toBe("line3");
+  });
+
+  it("handles commands with arguments and flags", async () => {
+    const { result } = await handleBashTool(fs)(
+      { command: "echo -n 'no newline'" },
+      {}
+    );
+    expect(result?.stdout).toBe("no newline");
+  });
+
+  it("supports command substitution", async () => {
+    const { result } = await handleBashTool(fs)(
+      { command: "echo \"count: $(echo 'a b c' | wc -w | tr -d ' ')\"" },
+      {}
+    );
+    expect(result?.stdout.trim()).toBe("count: 3");
+  });
+
+  it("returns content string with formatted output", async () => {
+    const { content } = await handleBashTool(fs)(
+      { command: "echo 'test'" },
+      {}
+    );
+    expect(content).toContain("Exit code: 0");
+    expect(content).toContain("stdout:");
+    expect(content).toContain("test");
+  });
+});
+
+describe("bash with overlay filesystem", () => {
+  it("sees files in the current directory", async () => {
+    const fs = new OverlayFs({ root: __dirname, mountPoint: "/home/user" });
+    const { result } = await handleBashTool(fs)({ command: "ls" }, {});
+    expect(result?.stdout).toContain("bash.test.ts");
+    expect(result?.stdout).toContain("handler.ts");
+    expect(result?.stdout).toContain("tool.ts");
+  });
+});

package/src/tools/bash/handler.ts

@@ -0,0 +1,36 @@
+import type { ActivityToolHandler } from "../../workflow";
+import type { bashToolSchemaType } from "./tool";
+import { Bash, type IFileSystem } from "just-bash";
+
+type BashExecOut = {
+  exitCode: number;
+  stderr: string;
+  stdout: string;
+};
+
+export const handleBashTool: (
+  fs: IFileSystem
+) => ActivityToolHandler<bashToolSchemaType, BashExecOut | null> =
+  (fs: IFileSystem) => async (args: bashToolSchemaType, _context) => {
+    const { command } = args;
+
+    const bashOptions = fs ? { fs } : {};
+
+    const bash = new Bash(bashOptions);
+
+    try {
+      const { exitCode, stderr, stdout } = await bash.exec(command);
+      const bashExecOut = { exitCode, stderr, stdout };
+
+      return {
+        content: `Exit code: ${exitCode}\n\nstdout:\n${stdout}\n\nstderr:\n${stderr}`,
+        result: bashExecOut,
+      };
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error("Unknown error");
+      return {
+        content: `Error executing bash command: ${err.message}`,
+        result: null,
+      };
+    }
+  };

package/src/tools/bash/tool.ts

@@ -0,0 +1,20 @@
+import z from "zod";
+
+export const createBashToolDescription = ({
+  fileTree,
+}: {
+  fileTree: string;
+}): string => `tool to execute bash commands, the file tree is: ${fileTree}`;
+
+export const bashTool = {
+  name: "Bash" as const,
+  description: "tool to execute bash commands",
+  schema: z.object({
+    command: z
+      .string()
+      .describe("stringified command to be executed inside the Bash"),
+  }),
+  strict: true,
+};
+
+export type bashToolSchemaType = z.infer<typeof bashTool.schema>;