zeitlich 0.2.22 → 0.2.24

package/dist/{types-ClsHhtwL.d.cts → types-hmferhc2.d.ts}

@@ -1,7 +1,7 @@
 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-YbL7JpEA.cjs';
+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-D_igp10o.js';
 import { z } from 'zod';
-import { g as SandboxOps } from './types-HBosetv3.cjs';
+import { g as SandboxOps } from './types-ChAMwU3q.js';
 import { QueryDefinition, ActivityInterfaceFor } from '@temporalio/workflow';
 import { UpdateDefinition } from '@temporalio/common/lib/interfaces';
 
@@ -69,19 +69,81 @@ interface Hooks<T extends ToolMap, TResult = unknown> extends ToolRouterHooks<T,
     onSessionEnd?: SessionEndHook;
 }
 
+/**
+ * Thread initialization strategy.
+ *
+ * - `"new"` — start a fresh thread (optionally specify its ID).
+ * - `"continue"` — append directly to an existing thread in-place.
+ * - `"fork"` — copy all messages from an existing thread into a new one and
+ *   continue there.
+ */
+type ThreadInit = {
+    mode: "new";
+    threadId?: string;
+} | {
+    mode: "continue";
+    threadId: string;
+} | {
+    mode: "fork";
+    threadId: string;
+};
+/**
+ * Sandbox initialization strategy.
+ *
+ * - `"new"` — create a fresh sandbox.
+ * - `"continue"` — resume a previously-paused sandbox (this session takes
+ *   ownership and the shutdown policy applies on exit).
+ * - `"fork"` — fork from an existing (or paused) sandbox; a new sandbox is
+ *   created and owned by this session.
+ * - `"inherit"` — use a sandbox owned by someone else (e.g. a parent agent).
+ *   The session will **not** manage its lifecycle on exit.
+ */
+type SandboxInit = {
+    mode: "new";
+} | {
+    mode: "continue";
+    sandboxId: string;
+} | {
+    mode: "fork";
+    sandboxId: string;
+} | {
+    mode: "inherit";
+    sandboxId: string;
+    stateUpdate?: Record<string, unknown>;
+};
+/**
+ * What to do with the sandbox when the session exits.
+ *
+ * - `"destroy"` — tear down the sandbox entirely.
+ * - `"pause"` — pause the sandbox so it can be resumed later.
+ * - `"keep"` — leave the sandbox running (no-op on exit).
+ */
+type SandboxShutdown = "destroy" | "pause" | "keep";
+/**
+ * Extended shutdown options available to subagent workflows.
+ *
+ * Includes all base {@link SandboxShutdown} values plus:
+ * - `"pause-until-parent-close"` — pause the sandbox on exit, then wait for
+ *   the parent workflow to signal when to destroy it.
+ */
+type SubagentSandboxShutdown = SandboxShutdown | "pause-until-parent-close";
+
 /** ToolHandlerResponse with threadId required (subagents must always surface their thread) */
 type SubagentHandlerResponse<TResult = null> = ToolHandlerResponse<TResult> & {
     threadId: string;
+    sandboxId?: string;
 };
 /**
  * Raw workflow input fields passed from parent to child workflow.
  * `defineSubagentWorkflow` maps this into `SubagentSessionInput`.
  */
 interface SubagentWorkflowInput {
-    /** Thread ID from parent for continuation */
-    previousThreadId?: string;
-    /** Sandbox ID inherited from parent */
-    sandboxId?: string;
+    /** Thread initialization strategy forwarded from the parent */
+    thread?: ThreadInit;
+    /** Sandbox initialization strategy forwarded from the parent */
+    sandbox?: SandboxInit;
+    /** Sandbox shutdown override from the parent (takes precedence over workflow default) */
+    sandboxShutdown?: SubagentSandboxShutdown;
 }
 type SubagentWorkflow<TResult extends z.ZodType = z.ZodType> = (prompt: string, workflowInput: SubagentWorkflowInput, context?: Record<string, unknown>) => Promise<SubagentHandlerResponse<z.infer<TResult> | null>>;
 /**
@@ -95,6 +157,21 @@ type SubagentDefinition<TResult extends z.ZodType = z.ZodType, TContext extends
 };
 /** Context value or factory — resolved at invocation time when a function is provided */
 type SubagentContext = Record<string, unknown> | (() => Record<string, unknown>);
+/**
+ * Sandbox configuration for a subagent.
+ *
+ * String shorthands:
+ * - `"none"` — no sandbox (default).
+ * - `"inherit"` — reuse the parent's sandbox (shared filesystem/exec).
+ * - `"own"` — the child creates and owns its own sandbox (shutdown defaults to `"destroy"`).
+ *
+ * Object form (only for `source: "own"`):
+ * - `{ source: "own", shutdown?: SubagentSandboxShutdown }` — own sandbox with explicit shutdown policy.
+ */
+type SubagentSandboxConfig = "none" | "inherit" | "own" | {
+    source: "own";
+    shutdown?: SubagentSandboxShutdown;
+};
 /**
  * Configuration for a subagent that can be spawned by the parent workflow.
  *
@@ -108,23 +185,34 @@ interface SubagentConfig<TResult extends z.ZodType = z.ZodType> {
     /** Whether this subagent is available (default: true). Disabled subagents are excluded from the Subagent tool. */
     enabled?: boolean | (() => boolean);
     /** Temporal workflow function or type name (used with executeChild) */
-    workflow: string | SubagentWorkflow<TResult>;
+    workflow: 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 context passed to the subagent — a static object or a function evaluated at invocation time */
     context?: SubagentContext;
-    /** Allow the parent agent to pass a threadId for this subagent to continue (default: false) */
-    allowThreadContinuation?: boolean;
     /** Per-subagent lifecycle hooks */
     hooks?: SubagentHooks;
+    /**
+     * Thread mode for this subagent.
+     *
+     * - `"new"` (default) — always start a fresh thread.
+     * - `"fork"` — the parent can pass a `threadId`; messages are copied into
+     *   a new thread and the subagent continues there.
+     * - `"continue"` — the parent can pass a `threadId`; the subagent appends
+     *   directly to the existing thread in-place.
+     */
+    thread?: "new" | "fork" | "continue";
     /**
      * Sandbox strategy for this subagent.
-     * - `'inherit'` (default): reuse the parent's sandbox (shared filesystem/exec).
-     * - `'own'`: the child creates and owns its own sandbox.
+     *
+     * String shorthands: `"none"` (default) | `"inherit"` | `"own"`.
+     * Object form: `{ source: "own", shutdown?: SubagentSandboxShutdown }`.
+     *
+     * @see {@link SubagentSandboxConfig}
      */
-    sandbox?: "inherit" | "own";
+    sandbox?: SubagentSandboxConfig;
 }
 /**
  * Per-subagent lifecycle hooks - defined on a SubagentConfig.
@@ -144,6 +232,8 @@ interface SubagentHooks<TArgs = unknown, TResult = unknown> {
         threadId: string;
         turn: number;
         durationMs: number;
+        /** Unvalidated metadata from the child workflow (e.g. infrastructure state) */
+        metadata?: Record<string, unknown>;
     }) => void | Promise<void>;
     /** Called when this subagent execution fails */
     onExecutionFailure?: (ctx: {
@@ -153,18 +243,31 @@ interface SubagentHooks<TArgs = unknown, TResult = unknown> {
         turn: number;
     }) => PostToolUseFailureHookResult | Promise<PostToolUseFailureHookResult>;
 }
+/**
+ * Extended response from the subagent `fn` — includes optional cleanup callbacks
+ * stripped before signaling the parent.
+ *
+ * When `TSandboxShutdown` is `"pause-until-parent-close"`, both `destroySandbox`
+ * and `sandboxId` become required so the parent can coordinate cleanup.
+ */
+type SubagentFnResult<TResult = null, TSandboxShutdown extends SubagentSandboxShutdown = SubagentSandboxShutdown> = SubagentHandlerResponse<TResult> & (TSandboxShutdown extends "pause-until-parent-close" ? {
+    destroySandbox: () => Promise<void>;
+    sandboxId: string;
+} : {
+    destroySandbox?: () => Promise<void>;
+});
 /**
  * Session config fields passed from parent to child workflow.
  */
 interface SubagentSessionInput {
     /** Agent name — spread directly into `createSession` */
     agentName: string;
-    /** Thread ID to continue from */
-    threadId?: string;
-    /** Whether to continue an existing thread */
-    continueThread?: boolean;
-    /** Sandbox ID inherited from the parent agent */
-    sandboxId?: string;
+    /** Thread initialization strategy */
+    thread?: ThreadInit;
+    /** Sandbox initialization strategy */
+    sandbox?: SandboxInit;
+    /** Sandbox shutdown policy (default: "destroy") */
+    sandboxShutdown?: SubagentSandboxShutdown;
 }
 
 /**
@@ -184,6 +287,8 @@ interface SkillMetadata {
     metadata?: Record<string, string>;
     /** Space-delimited list of pre-approved tools the skill may use */
     allowedTools?: string[];
+    /** Absolute path to the skill directory (parent of SKILL.md) */
+    location?: string;
 }
 /**
  * A fully-loaded skill including the SKILL.md instruction body.
@@ -193,6 +298,8 @@ interface SkillMetadata {
 interface Skill extends SkillMetadata {
     /** The markdown body of SKILL.md (everything after the frontmatter) */
     instructions: string;
+    /** Resource file contents keyed by relative path (e.g. `references/overview.md` → content) */
+    resourceContents?: Record<string, string>;
 }
 /**
  * Abstraction for discovering and loading skills.
@@ -205,6 +312,8 @@ interface SkillProvider {
     listSkills(): Promise<SkillMetadata[]>;
     /** Load a single skill with full instructions by name */
     getSkill(name: string): Promise<Skill>;
+    /** Load all skills with full instructions */
+    loadAll(): Promise<Skill[]>;
 }
 
 /**
@@ -384,8 +493,6 @@ type PrefixedThreadOps<TPrefix extends string> = {
 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 */
@@ -400,7 +507,7 @@ interface SessionConfig<T extends ToolMap, M = unknown> {
     tools?: T;
     /** Subagent configurations */
     subagents?: SubagentConfig[];
-    /** Skills available to this agent (metadata + instructions, loaded activity-side) */
+    /** Skills available to this agent (metadata + instructions, loaded before session creation) */
     skills?: Skill[];
     /** Session lifecycle hooks */
     hooks?: Hooks<T, ToolCallResultUnion<InferToolResults<T>>>;
@@ -411,28 +518,52 @@ interface SessionConfig<T extends ToolMap, M = unknown> {
      * 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;
+    /**
+     * Thread initialization strategy (default: `{ mode: "new" }`).
+     *
+     * - `{ mode: "new" }` — start a fresh thread.
+     * - `{ mode: "new", threadId: "..." }` — start a fresh thread with a specific ID.
+     * - `{ mode: "continue", threadId: "..." }` — append to an existing thread in-place.
+     * - `{ mode: "fork", threadId: "..." }` — fork an existing thread and continue in the copy.
+     */
+    thread?: ThreadInit;
     /** Sandbox lifecycle operations (optional — omit for agents that don't need a sandbox) */
-    sandbox?: SandboxOps;
+    sandboxOps?: 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).
+     * Sandbox initialization strategy.
+     *
+     * - `{ mode: "new" }` — create a fresh sandbox.
+     * - `{ mode: "continue", sandboxId: "..." }` — resume a paused sandbox (session owns it).
+     * - `{ mode: "fork", sandboxId: "..." }` — fork from an existing sandbox.
+     * - `{ mode: "inherit", sandboxId: "..." }` — use a parent's sandbox without ownership.
+     *
+     * When omitted and `sandboxOps` is provided, defaults to `{ mode: "new" }`.
      */
-    sandboxId?: string;
+    sandbox?: SandboxInit;
+    /**
+     * What to do with the sandbox when this session exits.
+     *
+     * Defaults to `"destroy"` when omitted.
+     * Has no effect when the sandbox is inherited (`sandbox.mode === "inherit"`).
+     */
+    sandboxShutdown?: SubagentSandboxShutdown;
 }
-interface ZeitlichSession<M = unknown> {
+type SessionResult<M, TState extends JsonSerializable<TState>, HasSandbox extends boolean = boolean> = {
+    threadId: string;
+    finalMessage: M | null;
+    exitReason: SessionExitReason;
+    usage: ReturnType<AgentStateManager<TState>["getTotalUsage"]>;
+} & (HasSandbox extends true ? {
+    sandboxId: string;
+} : {
+    sandboxId?: undefined;
+});
+interface ZeitlichSession<M = unknown, HasSandbox extends boolean = boolean> {
     runSession<T extends JsonSerializable<T>>(args: {
         stateManager: AgentStateManager<T>;
-    }): Promise<{
-        threadId: string;
-        finalMessage: M | null;
-        exitReason: SessionExitReason;
-        usage: ReturnType<AgentStateManager<T>["getTotalUsage"]>;
-    }>;
+    }): Promise<SessionResult<M, T, HasSandbox>>;
 }
 
-export type { AgentResponse as A, Hooks as H, JsonPrimitive as J, ModelInvoker as M, PrefixedThreadOps as P, RunAgentActivity as R, ScopedPrefix as S, ThreadOps as T, ZeitlichSession as Z, ModelInvokerConfig as a, SkillProvider as b, SkillMetadata as c, Skill as d, AgentState as e, AgentStateManager as f, JsonSerializable as g, JsonValue as h, PostHumanMessageAppendHook as i, PostHumanMessageAppendHookContext as j, PreHumanMessageAppendHook as k, PreHumanMessageAppendHookContext as l, SessionConfig as m, SessionEndHook as n, SessionEndHookContext as o, SessionStartHook as p, SessionStartHookContext as q, SubagentConfig as r, SubagentDefinition as s, SubagentHandlerResponse as t, SubagentHooks as u, SubagentSessionInput as v, SubagentWorkflow as w, SubagentWorkflowInput as x };
+export type { AgentResponse as A, SubagentSandboxShutdown as B, SubagentSessionInput as C, SubagentWorkflow as D, SubagentWorkflowInput as E, ThreadInit as F, Hooks as H, JsonPrimitive as J, ModelInvoker as M, PrefixedThreadOps as P, RunAgentActivity as R, ScopedPrefix as S, ThreadOps as T, ZeitlichSession as Z, ModelInvokerConfig as a, SkillProvider as b, SkillMetadata as c, Skill as d, AgentState as e, AgentStateManager as f, JsonSerializable as g, JsonValue as h, PostHumanMessageAppendHook as i, PostHumanMessageAppendHookContext as j, PreHumanMessageAppendHook as k, PreHumanMessageAppendHookContext as l, SandboxInit as m, SandboxShutdown as n, SessionConfig as o, SessionEndHook as p, SessionEndHookContext as q, SessionResult as r, SessionStartHook as s, SessionStartHookContext as t, SubagentConfig as u, SubagentDefinition as v, SubagentFnResult as w, SubagentHandlerResponse as x, SubagentHooks as y, SubagentSandboxConfig as z };