zeitlich 0.2.13 → 0.2.14

package/dist/types-GpMU4b0w.d.cts

@@ -0,0 +1,389 @@
+import { Duration } from '@temporalio/common';
+import { a as ToolMap, b as ToolRouterHooks, M as MessageContent, S as SessionExitReason, c as ToolHandlerResponse, P as PreToolUseHookResult, d as PostToolUseFailureHookResult, e as RawToolCall, f as TokenUsage, B as BaseAgentState, g as RunAgentConfig, h as AgentStatus, W as WorkflowTask, i as ToolDefinition, j as ToolResultConfig, k as ToolCallResultUnion, I as InferToolResults } from './types-BMXzv7TN.cjs';
+import { z } from 'zod';
+import { g as SandboxOps } from './types-CDubRtad.cjs';
+import { QueryDefinition } from '@temporalio/workflow';
+import { UpdateDefinition } from '@temporalio/common/lib/interfaces';
+
+/**
+ * Context for SessionStart hook - called when session begins
+ */
+interface SessionStartHookContext {
+    threadId: string;
+    agentName: string;
+    metadata: Record<string, unknown>;
+}
+/**
+ * SessionStart hook - called when session begins
+ */
+type SessionStartHook = (ctx: SessionStartHookContext) => void | Promise<void>;
+/**
+ * Context for SessionEnd hook - called when session ends
+ */
+interface SessionEndHookContext {
+    threadId: string;
+    agentName: string;
+    exitReason: SessionExitReason;
+    turns: number;
+    metadata: Record<string, unknown>;
+}
+/**
+ * SessionEnd hook - called when session ends
+ */
+type SessionEndHook = (ctx: SessionEndHookContext) => void | Promise<void>;
+/**
+ * Context for PreHumanMessageAppend hook - called before each human message is appended to the thread
+ */
+interface PreHumanMessageAppendHookContext {
+    message: MessageContent;
+    threadId: string;
+}
+/**
+ * PreHumanMessageAppend hook - called before each human message is appended to the thread
+ */
+type PreHumanMessageAppendHook = (ctx: PreHumanMessageAppendHookContext) => void | Promise<void>;
+/**
+ * Context for PostHumanMessageAppend hook - called after each human message is appended to the thread
+ */
+interface PostHumanMessageAppendHookContext {
+    message: MessageContent;
+    threadId: string;
+}
+/**
+ * PostHumanMessageAppend hook - called after each human message is appended to the thread
+ */
+type PostHumanMessageAppendHook = (ctx: PostHumanMessageAppendHookContext) => void | Promise<void>;
+/**
+ * Full hooks interface for a session — combines tool execution hooks
+ * (consumed by the router) with session/message lifecycle hooks
+ * (consumed directly by the session).
+ */
+interface Hooks<T extends ToolMap, TResult = unknown> extends ToolRouterHooks<T, TResult> {
+    /** Called before each human message is appended to the thread */
+    onPreHumanMessageAppend?: PreHumanMessageAppendHook;
+    /** Called after each human message is appended to the thread */
+    onPostHumanMessageAppend?: PostHumanMessageAppendHook;
+    /** Called when session starts */
+    onSessionStart?: SessionStartHook;
+    /** Called when session ends */
+    onSessionEnd?: SessionEndHook;
+}
+
+/** ToolHandlerResponse with threadId required (subagents must always surface their thread) */
+type SubagentHandlerResponse<TResult = null> = ToolHandlerResponse<TResult> & {
+    threadId: string;
+};
+type SubagentWorkflow<TResult extends z.ZodType = z.ZodType> = (input: SubagentInput) => Promise<SubagentHandlerResponse<z.infer<TResult> | null>>;
+/**
+ * Configuration for a subagent that can be spawned by the parent workflow.
+ *
+ * @template TResult - Zod schema type for validating the child workflow's result
+ */
+interface SubagentConfig<TResult extends z.ZodType = z.ZodType> {
+    /** Identifier used in Task tool's subagent parameter */
+    agentName: string;
+    /** Description shown to the parent agent explaining what this subagent does */
+    description: string;
+    /** Whether this subagent is available (default: true). Disabled subagents are excluded from the Subagent tool. */
+    enabled?: boolean;
+    /** Temporal workflow function or type name (used with executeChild) */
+    workflow: string | SubagentWorkflow<TResult>;
+    /** 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;
+    /** Optional static context passed to the subagent on every invocation */
+    context?: Record<string, unknown>;
+    /** Allow the parent agent to pass a threadId for this subagent to continue (default: false) */
+    allowThreadContinuation?: boolean;
+    /** Per-subagent lifecycle hooks */
+    hooks?: SubagentHooks;
+    /**
+     * Sandbox strategy for this subagent.
+     * - `'inherit'` (default): reuse the parent's sandbox (shared filesystem/exec).
+     * - `'own'`: the child creates and owns its own sandbox.
+     */
+    sandbox?: "inherit" | "own";
+}
+/**
+ * Per-subagent lifecycle hooks - defined on a SubagentConfig.
+ * Runs in addition to global hooks (global pre → subagent pre → execute → subagent post → global post).
+ */
+interface SubagentHooks<TArgs = unknown, TResult = unknown> {
+    /** Called before this subagent executes - can skip or modify args */
+    onPreExecution?: (ctx: {
+        args: TArgs;
+        threadId: string;
+        turn: number;
+    }) => PreToolUseHookResult | Promise<PreToolUseHookResult>;
+    /** Called after this subagent executes successfully */
+    onPostExecution?: (ctx: {
+        args: TArgs;
+        result: TResult;
+        threadId: string;
+        turn: number;
+        durationMs: number;
+    }) => void | Promise<void>;
+    /** Called when this subagent execution fails */
+    onExecutionFailure?: (ctx: {
+        args: TArgs;
+        error: Error;
+        threadId: string;
+        turn: number;
+    }) => PostToolUseFailureHookResult | Promise<PostToolUseFailureHookResult>;
+}
+/**
+ * Input passed to child workflows when spawned as subagents
+ */
+interface SubagentInput {
+    /** The prompt/task from the parent agent */
+    prompt: string;
+    /** Optional context parameters passed from the parent agent */
+    context?: Record<string, unknown>;
+    /** When set, the subagent should continue this thread instead of starting a new one */
+    previousThreadId?: string;
+    /** Sandbox ID inherited from the parent agent (when SubagentConfig.sandbox is 'inherit') */
+    sandboxId?: string;
+}
+
+/**
+ * Skill metadata — the lightweight subset loaded at startup for all skills.
+ * Follows the agentskills.io specification frontmatter fields.
+ */
+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.
+ */
+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.).
+ */
+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>;
+}
+
+/**
+ * Agent response from LLM invocation
+ */
+interface AgentResponse<M = unknown> {
+    message: M;
+    rawToolCalls: RawToolCall[];
+    usage?: TokenUsage;
+}
+/**
+ * Type signature for workflow-specific runAgent activity
+ */
+type RunAgentActivity<M = unknown> = (config: RunAgentConfig) => Promise<AgentResponse<M>>;
+/**
+ * Configuration passed to a ModelInvoker.
+ * Includes the full agent state so adapters can read tools, system prompt,
+ * token usage, or any custom state fields for model configuration.
+ */
+interface ModelInvokerConfig {
+    threadId: string;
+    agentName: string;
+    state: BaseAgentState;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Generic model invocation contract.
+ * Implementations load the thread, call the LLM, append the response,
+ * and return a normalised AgentResponse.
+ *
+ * Framework adapters (e.g. `zeitlich/langchain`) provide concrete
+ * implementations of this type.
+ */
+type ModelInvoker<M = unknown> = (config: ModelInvokerConfig) => Promise<AgentResponse<M>>;
+
+/**
+ * JSON primitive types that Temporal can serialize
+ */
+type JsonPrimitive = string | number | boolean | null | undefined;
+/**
+ * JSON-serializable value (recursive type for Temporal compatibility)
+ */
+type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * Type constraint ensuring T only contains JSON-serializable values.
+ * Use this for custom state to ensure Temporal workflow compatibility.
+ *
+ * Allows: primitives, arrays, plain objects, and JsonValue
+ * Rejects: functions, symbols, undefined, class instances with methods
+ */
+type JsonSerializable<T> = {
+    [K in keyof T]: T[K] extends JsonValue ? T[K] : T[K] extends JsonPrimitive ? T[K] : T[K] extends (infer U)[] ? U extends JsonValue ? T[K] : JsonSerializable<U>[] : T[K] extends object ? JsonSerializable<T[K]> : never;
+};
+/**
+ * Full state type combining base state with custom state
+ */
+type AgentState<TCustom extends JsonSerializable<TCustom>> = BaseAgentState & TCustom;
+/**
+ * Agent state manager interface
+ * Note: Temporal handlers must be set up in the workflow file due to
+ * Temporal's workflow isolation requirements. This manager provides
+ * the state and helpers needed for those handlers.
+ */
+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 */
+    isRunning(): boolean;
+    /** Check if agent is in terminal state */
+    isTerminal(): boolean;
+    /** Get current state version */
+    getVersion(): number;
+    /** Set status to RUNNING */
+    run(): void;
+    /** Set status to WAITING_FOR_INPUT */
+    waitForInput(): void;
+    /** Set status to COMPLETED */
+    complete(): void;
+    /** Set status to FAILED */
+    fail(): void;
+    /** Set status to CANCELLED */
+    cancel(): void;
+    /** Increment state version (call after state changes) */
+    incrementVersion(): void;
+    /** Increment turns (call after each turn) */
+    incrementTurns(): void;
+    /** 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];
+    /** Set a custom state value by key */
+    set<K extends keyof TCustom>(key: K, value: TCustom[K]): void;
+    /** Bulk-merge a partial update into custom state (e.g. from sandbox stateUpdate) */
+    mergeUpdate(update: Partial<TCustom>): void;
+    /** Get full state for query handler */
+    getCurrentState(): AgentState<TCustom>;
+    /** Check if should return from waitForStateChange */
+    shouldReturnFromWait(lastKnownVersion: number): boolean;
+    /** Get all tasks */
+    getTasks(): WorkflowTask[];
+    /** Get a task by ID */
+    getTask(id: string): WorkflowTask | undefined;
+    /** Add or update a task */
+    setTask(task: WorkflowTask): void;
+    /** Delete a task by ID */
+    deleteTask(id: string): boolean;
+    /** Set the tools (converts Zod schemas to JSON Schema for serialization) */
+    setTools(newTools: ToolDefinition[]): void;
+    /** Update the usage */
+    updateUsage(usage: TokenUsage): void;
+    /** Get the total usage */
+    getTotalUsage(): {
+        totalInputTokens: number;
+        totalOutputTokens: number;
+        totalCachedWriteTokens: number;
+        totalCachedReadTokens: number;
+        totalReasonTokens: number;
+        turns: number;
+    };
+}
+
+/**
+ * Thread operations required by a session.
+ * Consumers provide these — typically by wrapping Temporal activities.
+ */
+interface ThreadOps {
+    /** Initialize an empty thread */
+    initializeThread(threadId: string): Promise<void>;
+    /** Append a human message to the thread */
+    appendHumanMessage(threadId: string, content: string | MessageContent): Promise<void>;
+    /** Append a tool result to the thread */
+    appendToolResult(config: ToolResultConfig): Promise<void>;
+    /** Append a system message to the thread */
+    appendSystemMessage(threadId: string, content: string): Promise<void>;
+}
+/**
+ * Configuration for a Zeitlich agent session
+ */
+interface SessionConfig<T extends ToolMap, M = unknown> {
+    /** The name of the agent, should be unique within the workflows */
+    agentName: string;
+    /** The thread ID to use for the session (defaults to a short generated ID) */
+    threadId?: string;
+    /** Metadata for the session */
+    metadata?: Record<string, unknown>;
+    /** Whether to append the system prompt as message to the thread */
+    appendSystemPrompt?: boolean;
+    /** How many turns to run the session for */
+    maxTurns?: number;
+    /** Workflow-specific runAgent activity (with tools pre-bound) */
+    runAgent: RunAgentActivity<M>;
+    /** Thread operations (initialize, append messages, parse tool calls) */
+    threadOps?: ThreadOps;
+    /** Tool router for processing tool calls (optional if agent has no tools) */
+    tools?: T;
+    /** Subagent configurations */
+    subagents?: SubagentConfig[];
+    /** Skills available to this agent (metadata + instructions, loaded activity-side) */
+    skills?: Skill[];
+    /** Session lifecycle hooks */
+    hooks?: Hooks<T, ToolCallResultUnion<InferToolResults<T>>>;
+    /** Whether to process tools in parallel */
+    processToolsInParallel?: boolean;
+    /**
+     * Build context message content from agent-specific context.
+     * Returns MessageContent array for the initial HumanMessage.
+     */
+    buildContextMessage: () => MessageContent | Promise<MessageContent>;
+    /** When true, skip thread initialization and system prompt — append only the new human message to the existing thread. */
+    continueThread?: boolean;
+    /** How long to wait for input before cancelling the workflow */
+    waitForInputTimeout?: Duration;
+    /** Sandbox lifecycle operations (optional — omit for agents that don't need a sandbox) */
+    sandbox?: SandboxOps;
+    /**
+     * Pre-existing sandbox ID to reuse (e.g. inherited from a parent agent).
+     * When set, the session skips `createSandbox` and will not destroy the
+     * sandbox on exit (the owner is responsible for cleanup).
+     */
+    sandboxId?: string;
+}
+interface ZeitlichSession<M = unknown> {
+    runSession<T extends JsonSerializable<T>>(args: {
+        stateManager: AgentStateManager<T>;
+    }): Promise<{
+        threadId: string;
+        finalMessage: M | null;
+        exitReason: SessionExitReason;
+        usage: ReturnType<AgentStateManager<T>["getTotalUsage"]>;
+    }>;
+}
+
+export type { AgentResponse as A, Hooks as H, JsonPrimitive as J, ModelInvoker as M, PostHumanMessageAppendHook as P, RunAgentActivity as R, SkillProvider as S, ThreadOps as T, ZeitlichSession as Z, ModelInvokerConfig as a, SkillMetadata as b, Skill as c, AgentState as d, AgentStateManager as e, JsonSerializable as f, JsonValue as g, PostHumanMessageAppendHookContext as h, PreHumanMessageAppendHook as i, PreHumanMessageAppendHookContext as j, SessionConfig as k, SessionEndHook as l, SessionEndHookContext as m, SessionStartHook as n, SessionStartHookContext as o, SubagentConfig as p, SubagentHandlerResponse as q, SubagentHooks as r, SubagentInput as s, SubagentWorkflow as t };