@bastani/atomic 0.5.12 → 0.5.13

package/dist/sdk/runtime/tmux.d.ts

@@ -0,0 +1,297 @@
+/**
+ * tmux session and pane management utilities.
+ *
+ * Provides low-level tmux operations for the workflow runtime:
+ * creating sessions, splitting panes, spawning commands, capturing output,
+ * sending keystrokes, and pane state detection.
+ */
+import type { Subprocess } from "bun";
+/** Dedicated tmux socket name — isolates Atomic sessions from the user's default server. */
+export declare const SOCKET_NAME = "atomic";
+/** Discriminated result from a tmux command execution. */
+export type TmuxResult = {
+    ok: true;
+    stdout: string;
+} | {
+    ok: false;
+    stderr: string;
+};
+export declare const TMUX_DEFAULT_STATUS_LEFT = " ";
+export declare const TMUX_DEFAULT_STATUS_LEFT_LENGTH = "10";
+export declare const TMUX_DEFAULT_STATUS_RIGHT = " #{session_name} | %H:%M ";
+export declare const TMUX_DEFAULT_STATUS_RIGHT_LENGTH = "60";
+export declare const TMUX_ATTACHED_STATUS_RIGHT = "#[fg=#cdd6f4]ctrl+g #[fg=#6c7086]graph #[fg=#585b70]\u00B7 #[fg=#cdd6f4]ctrl+\\ #[fg=#6c7086]next ";
+export declare const TMUX_ATTACHED_STATUS_RIGHT_LENGTH = "40";
+export declare const TMUX_ATTACHED_WINDOW_FMT = "#{?#{==:#{window_index},0},, #W }";
+export declare const TMUX_ATTACHED_WINDOW_STYLE = "fg=#6c7086";
+export declare const TMUX_ATTACHED_WINDOW_CURRENT_STYLE = "fg=#cdd6f4,bold";
+/**
+ * Resolve the terminal multiplexer binary for the current platform.
+ *
+ * On Windows, tries psmux → pmux → tmux (psmux ships all three as aliases).
+ * On Unix/macOS, uses tmux directly.
+ *
+ * Returns the binary name (not the full path) or null if none is found.
+ * The result is cached after the first call.
+ */
+export declare function getMuxBinary(): string | null;
+/**
+ * Reset the cached multiplexer binary resolution.
+ * Call after installing tmux/psmux to force re-detection.
+ */
+export declare function resetMuxBinaryCache(): void;
+/**
+ * Check if tmux is installed and available.
+ */
+export declare function isTmuxInstalled(): boolean;
+/**
+ * Check if we're currently inside a tmux session.
+ */
+export declare function isInsideTmux(): boolean;
+/**
+ * Check if we're inside the atomic tmux socket specifically.
+ *
+ * The `TMUX` env var has the format `<socket_path>,<pid>,<index>`.
+ * On Unix this looks like `/tmp/tmux-1000/atomic,12345,0` when the
+ * socket name is "atomic".
+ */
+export declare function isInsideAtomicSocket(): boolean;
+/**
+ * Run a tmux command and return a result object.
+ * Prefers this over the throwing `tmux()` for cases where callers
+ * need to handle failure gracefully.
+ */
+export declare function tmuxRun(args: string[]): TmuxResult;
+/**
+ * Create a new tmux session with the given name.
+ * The session starts detached with an initial command in the first pane.
+ *
+ * @param sessionName - Unique session name
+ * @param initialCommand - Shell command to run in the initial pane
+ * @param windowName - Optional name for the initial window
+ * @param cwd - Optional working directory for the initial pane
+ * @param envVars - Optional environment variables for the initial pane
+ * @returns The pane ID of the initial pane (e.g., "%0")
+ */
+export declare function createSession(sessionName: string, initialCommand: string, windowName?: string, cwd?: string, envVars?: Record<string, string>): string;
+/**
+ * Create a new window in an existing session without switching focus.
+ *
+ * @param sessionName - Target session name
+ * @param windowName - Name for the new window
+ * @param command - Shell command to run in the new window
+ * @param cwd - Optional working directory for the new window
+ * @param envVars - Optional environment variables for the new window
+ * @returns The pane ID of the new window's pane
+ */
+export declare function createWindow(sessionName: string, windowName: string, command: string, cwd?: string, envVars?: Record<string, string>): string;
+/**
+ * Create a new pane in an existing session by splitting.
+ *
+ * @returns The pane ID of the new pane
+ */
+export declare function createPane(sessionName: string, command: string): string;
+/**
+ * Send literal text to a tmux pane using `-l` flag (no special key interpretation).
+ * Uses `--` to prevent text starting with `-` from being parsed as flags.
+ *
+ * For large text payloads, prefer {@link sendViaPasteBuffer} which bypasses
+ * tmux's ~16 KB internal message buffer limit.
+ */
+export declare function sendLiteralText(paneId: string, text: string): void;
+/**
+ * Send text to a tmux pane via the paste buffer.
+ *
+ * More reliable than `send-keys -l` for large text:
+ * - No OS ARG_MAX / MAX_ARG_STRLEN limits (text goes through a temp file)
+ * - Atomic delivery — the entire text is pasted at once
+ * - No chunking needed
+ *
+ * Newlines are normalized to spaces to prevent premature submission,
+ * matching `sendLiteralText`'s behavior.
+ */
+export declare function sendViaPasteBuffer(paneId: string, text: string): void;
+/**
+ * Send a special key (C-m, C-c, C-u, Tab, etc.) to a tmux pane.
+ */
+export declare function sendSpecialKey(paneId: string, key: string): void;
+/**
+ * Send literal text and submit with C-m (carriage return).
+ * Uses C-m instead of Enter for raw-mode TUI compatibility.
+ *
+ * @param presses - Number of C-m presses (default: 1)
+ * @param delayMs - Delay between presses in ms (default: 100)
+ */
+export declare function sendKeysAndSubmit(paneId: string, text: string, presses?: number, delayMs?: number): Promise<void>;
+/**
+ * Capture the visible content of a tmux pane.
+ *
+ * @param paneId - The pane ID (e.g., "%0")
+ * @param start - Start line (negative = from bottom, default: capture visible only)
+ */
+export declare function capturePane(paneId: string, start?: number): string;
+/**
+ * Capture only the visible portion of a pane (no scrollback).
+ * Preferred for state detection (ready/busy) to avoid stale prompt lines
+ * or old activity indicators in scrollback triggering false positives.
+ * Returns empty string on failure instead of throwing.
+ */
+export declare function capturePaneVisible(paneId: string): string;
+/**
+ * Capture last N lines of scrollback from a pane.
+ * Preferred for output collection where you need recent history.
+ * Returns empty string on failure instead of throwing.
+ */
+export declare function capturePaneScrollback(paneId: string, lines?: number): string;
+/**
+ * Kill a tmux session.
+ */
+export declare function killSession(sessionName: string): void;
+/** Kill a specific tmux window within a session. Silences errors if already dead. */
+export declare function killWindow(sessionName: string, windowName: string): void;
+/**
+ * Check if a tmux session exists.
+ */
+export declare function sessionExists(sessionName: string): boolean;
+/**
+ * Set a session-level environment variable.
+ * Uses `tmux set-environment -t <session>` so the value is scoped to
+ * the individual session, not the global server environment.
+ */
+export declare function setSessionEnv(sessionName: string, key: string, value: string): void;
+/**
+ * Read a session-level environment variable.
+ * Returns `null` when the session doesn't exist or the variable isn't set.
+ */
+export declare function getSessionEnv(sessionName: string, key: string): string | null;
+/** Session type derived from the session name prefix. */
+export type SessionType = "chat" | "workflow";
+/**
+ * Parse a session name into its type and agent.
+ *
+ * Naming conventions:
+ *   Chat:     atomic-chat-<agent>-<id>
+ *   Workflow:  atomic-wf-<agent>-<name>-<id>
+ *
+ * Agent names are a known, hyphen-free set (claude, copilot, opencode)
+ * so parsing is unambiguous even when the workflow name contains hyphens.
+ */
+export declare function parseSessionName(name: string): {
+    type?: SessionType;
+    agent?: string;
+};
+/** A single tmux session on the atomic socket. */
+export interface TmuxSession {
+    /** Session name (e.g. "atomic-chat-claude-a1b2c3d4") */
+    name: string;
+    /** Number of windows in the session */
+    windows: number;
+    /** ISO 8601 creation timestamp */
+    created: string;
+    /** Whether a client is currently attached */
+    attached: boolean;
+    /** Session type derived from the name prefix */
+    type?: SessionType;
+    /** Agent backend that owns this session (e.g. "claude", "copilot", "opencode") */
+    agent?: string;
+}
+/**
+ * List all sessions on the atomic tmux socket.
+ *
+ * Uses a custom format string so output is machine-parseable regardless of
+ * locale. Returns an empty array when the server isn't running or has no
+ * sessions (tmux exits non-zero in both cases).
+ */
+export declare function listSessions(): TmuxSession[];
+/**
+ * Attach to an existing tmux session (takes over the current terminal).
+ */
+export declare function attachSession(sessionName: string): void;
+/**
+ * Spawn an interactive attach-session process.
+ * Encapsulates binary resolution, config injection, and socket isolation.
+ * Used by all async attach call sites (executor, chat).
+ */
+export declare function spawnMuxAttach(sessionName: string): Subprocess;
+/**
+ * Switch the current tmux client to a different session.
+ * Use this instead of `attachSession` when already inside tmux to avoid
+ * creating a nested tmux client.
+ */
+export declare function switchClient(sessionName: string): void;
+/**
+ * Get the name of the current tmux session (when running inside tmux).
+ * Returns null if not inside tmux or if the query fails.
+ */
+export declare function getCurrentSession(): string | null;
+/**
+ * Attach or switch to a tmux session depending on whether we're already
+ * inside tmux. Avoids nested tmux clients.
+ *
+ * - Outside tmux: spawns `attach-session` (blocks until session ends).
+ * - Inside tmux: runs `switch-client` (returns immediately).
+ */
+export declare function attachOrSwitch(sessionName: string): void;
+/**
+ * Detach from the user's current tmux session and replace the client
+ * with an attach to a session on the atomic socket.
+ *
+ * Uses `detach-client -E` so the user's terminal seamlessly transitions
+ * from their tmux session to the atomic session — no nesting.
+ * Their original tmux session stays alive; they can re-attach with
+ * `tmux attach` after leaving the atomic session.
+ *
+ * Only call when {@link isInsideTmux} returns `true`.
+ */
+export declare function detachAndAttachAtomic(sessionName: string): void;
+/**
+ * Select (switch to) a window within the current tmux session.
+ */
+export declare function selectWindow(target: string): void;
+/**
+ * Collapse all whitespace to single spaces for robust capture comparison.
+ * Prevents false negatives from tmux inserting/stripping whitespace.
+ */
+export declare function normalizeTmuxCapture(text: string): string;
+/**
+ * Normalize captured text preserving line structure (for display output).
+ */
+export declare function normalizeTmuxLines(text: string): string;
+/**
+ * Returns true when the pane shows an agent prompt ready for input.
+ * Detects Claude Code (❯), Codex (›), and generic (>) prompts.
+ */
+export declare function paneLooksReady(captured: string): boolean;
+/**
+ * Returns true when the agent has an active task in progress.
+ * Checks last 40 lines for known busy indicators.
+ */
+export declare function paneHasActiveTask(captured: string): boolean;
+/**
+ * Returns true when the pane is idle — showing a prompt and not processing.
+ * Uses visible-only capture to avoid stale scrollback matches.
+ */
+export declare function paneIsIdle(paneId: string): boolean;
+/**
+ * Wait for the pane to be idle (prompt visible, no active task) with
+ * exponential backoff. Returns the time spent waiting (ms).
+ */
+export declare function waitForPaneReady(paneId: string, timeoutMs?: number): Promise<number>;
+/**
+ * Attempt to submit by pressing C-m, verifying after each round.
+ * Returns true as soon as the trigger text disappears from the visible
+ * capture or an active task is detected.
+ */
+export declare function attemptSubmitRounds(paneId: string, normalizedPrompt: string, rounds: number, pressesPerRound?: number): Promise<boolean>;
+/**
+ * Wait for a pattern to appear in a tmux pane's output.
+ * Polls the pane content at the given interval until the pattern matches
+ * or the timeout is reached.
+ *
+ * @returns The full pane content when the pattern was found
+ */
+export declare function waitForOutput(paneId: string, pattern: RegExp, options?: {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+}): Promise<string>;
+//# sourceMappingURL=tmux.d.ts.map

package/dist/sdk/runtime/tmux.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tmux.d.ts","sourceRoot":"","sources":["../../../src/sdk/runtime/tmux.ts"],"names":[],"mappings":"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"}

package/dist/sdk/types.d.ts

@@ -0,0 +1,309 @@
+/**
+ * Workflow SDK Types
+ *
+ * Uses native SDK types directly — no re-definitions.
+ */
+import type { SessionEvent } from "@github/copilot-sdk";
+import type { SessionPromptResponse } from "@opencode-ai/sdk/v2";
+import type { SessionMessage } from "@anthropic-ai/claude-agent-sdk";
+import type { CopilotClient, CopilotClientOptions, CopilotSession, SessionConfig as CopilotSessionConfig } from "@github/copilot-sdk";
+import type { OpencodeClient, Session as OpencodeSession } from "@opencode-ai/sdk/v2";
+import type { ClaudeClientWrapper, ClaudeSessionWrapper, ClaudeQueryDefaults } from "./providers/claude.ts";
+/** Supported agent types */
+export type AgentType = "copilot" | "opencode" | "claude";
+/**
+ * Maps each agent to the client init options the user passes to `ctx.stage()`.
+ * Auto-injected fields (`cliUrl`, `baseUrl`, `paneId`) are omitted.
+ */
+type ClientOptionsMap = {
+    opencode: {
+        directory?: string;
+        experimental_workspaceID?: string;
+    };
+    copilot: Omit<CopilotClientOptions, "cliUrl">;
+    claude: {
+        chatFlags?: string[];
+        readyTimeoutMs?: number;
+    };
+};
+/**
+ * Maps each agent to the session create options the user passes to `ctx.stage()`.
+ * - OpenCode: `client.session.create()` body params
+ * - Copilot: `client.createSession()` config (onPermissionRequest defaults to approveAll)
+ * - Claude: `claudeQuery()` defaults for subsequent queries
+ */
+type SessionOptionsMap = {
+    opencode: {
+        parentID?: string;
+        title?: string;
+        workspaceID?: string;
+    };
+    copilot: Partial<CopilotSessionConfig>;
+    claude: ClaudeQueryDefaults;
+};
+/** Maps each agent to the `s.client` type provided in the stage callback. */
+type ClientMap = {
+    opencode: OpencodeClient;
+    copilot: CopilotClient;
+    claude: ClaudeClientWrapper;
+};
+/** Maps each agent to the `s.session` type provided in the stage callback. */
+type SessionMap = {
+    opencode: OpencodeSession;
+    copilot: CopilotSession;
+    claude: ClaudeSessionWrapper;
+};
+/** Client init options for `ctx.stage()`, resolved by agent type. */
+export type StageClientOptions<A extends AgentType> = ClientOptionsMap[A];
+/** Session create options for `ctx.stage()`, resolved by agent type. */
+export type StageSessionOptions<A extends AgentType> = SessionOptionsMap[A];
+/** The `s.client` type in a stage callback, resolved by agent type. */
+export type ProviderClient<A extends AgentType> = ClientMap[A];
+/** The `s.session` type in a stage callback, resolved by agent type. */
+export type ProviderSession<A extends AgentType> = SessionMap[A];
+export type { CopilotClient, CopilotClientOptions, CopilotSession, CopilotSessionConfig, OpencodeClient, OpencodeSession, ClaudeClientWrapper, ClaudeSessionWrapper, ClaudeQueryDefaults, };
+/** A source validation warning emitted by provider-specific workflow validators. */
+export interface ValidationWarning {
+    rule: string;
+    message: string;
+}
+/** A declarative validation rule: pattern to match + warning to emit. */
+export interface ValidationRule {
+    pattern: RegExp;
+    rule: string;
+    message: string;
+}
+/**
+ * Run a set of regex-based validation rules against workflow source code.
+ * Returns a warning for each matching pattern.
+ */
+export declare function validateWorkflowSource(source: string, rules: readonly ValidationRule[]): ValidationWarning[];
+/**
+ * Create a provider-specific workflow validator from a set of rules.
+ * Eliminates boilerplate — each provider file only needs to declare its rules.
+ */
+export declare function createProviderValidator(rules: readonly ValidationRule[]): (source: string) => ValidationWarning[];
+/**
+ * Supported field types for a workflow's declared inputs.
+ *
+ * - `"string"` — single-line free-form input (short values, identifiers, paths)
+ * - `"text"`   — multi-line free-form input (long prose, prompts, specs)
+ * - `"enum"`   — one of a fixed list of allowed `values`
+ */
+export type WorkflowInputType = "string" | "text" | "enum";
+/**
+ * A declared input for a workflow. When a workflow provides an `inputs`
+ * array, the CLI materialises one `--<name>` flag per input (and the
+ * interactive picker renders one field per input) so users can pass
+ * structured values rather than a single free-form prompt.
+ *
+ * Leaving `inputs` unset (or empty) signals that the workflow consumes a
+ * single free-form prompt instead — the legacy
+ * `atomic workflow -n <name> -a <agent> "prompt"` form.
+ */
+export interface WorkflowInput {
+    /** Field name — also the CLI flag (`--<name>`) and form field identifier. */
+    name: string;
+    /** Input kind — see {@link WorkflowInputType}. */
+    type: WorkflowInputType;
+    /** Whether the field must be non-empty before the workflow can run. */
+    required?: boolean;
+    /** Short human description shown as the field caption. */
+    description?: string;
+    /** Placeholder text shown when the field is empty. */
+    placeholder?: string;
+    /** Default value pre-filled into the field. Enums use this to pick their initial value. */
+    default?: string;
+    /** Allowed values — required when `type` is `"enum"`. */
+    values?: readonly string[];
+}
+/**
+ * A transcript from a completed session.
+ * Provides both the file path and rendered text content.
+ */
+export interface Transcript {
+    /** Absolute path to the transcript file on disk */
+    path: string;
+    /** The transcript content (assistant text extracted from messages) */
+    content: string;
+}
+/**
+ * A saved message from any provider, stored as JSON.
+ * Uses native SDK types directly.
+ */
+export type SavedMessage = {
+    provider: "copilot";
+    data: SessionEvent;
+} | {
+    provider: "opencode";
+    data: SessionPromptResponse;
+} | {
+    provider: "claude";
+    data: SessionMessage;
+};
+/**
+ * Save native message objects from the provider SDK.
+ *
+ * - **Copilot**: `s.save(await s.session.getMessages())`
+ * - **OpenCode**: `s.save(result.data)` — the full `{ info, parts }` response
+ * - **Claude**: `s.save(sessionId)` — auto-reads via `getSessionMessages()`
+ */
+export interface SaveTranscript {
+    /** Save Copilot SessionEvent[] from session.getMessages() */
+    (messages: SessionEvent[]): Promise<void>;
+    /** Save OpenCode prompt response `{ info, parts }` from session.prompt().data */
+    (response: SessionPromptResponse): Promise<void>;
+    /** Save Claude messages — pass the session ID to auto-read transcript */
+    (claudeSessionId: string): Promise<void>;
+}
+/** A reference to a completed session — either a handle or a session name string. */
+export type SessionRef = string | SessionHandle<unknown>;
+/**
+ * Handle returned by `ctx.stage()`. Used for type-safe transcript references
+ * and carries the callback's return value.
+ */
+export interface SessionHandle<T = void> {
+    /** The session's unique name */
+    readonly name: string;
+    /** The session's generated UUID */
+    readonly id: string;
+    /** The value returned by the session callback */
+    readonly result: T;
+}
+/**
+ * Options for spawning a session via `ctx.stage()`.
+ */
+export interface SessionRunOptions {
+    /** Unique name for this session (used for transcript references and graph display) */
+    name: string;
+    /** Human-readable description */
+    description?: string;
+    /**
+     * When true, spawn the CLI server as a background child process (Bun.spawn)
+     * instead of creating a tmux window. The provider client/session are still
+     * auto-created but the stage is invisible in the graph. Useful for
+     * Copilot/OpenCode SDKs that need a server but don't need a visible TUI.
+     */
+    headless?: boolean;
+}
+/**
+ * Context provided to each session's callback.
+ * Created by `ctx.stage(opts, clientOpts, sessionOpts, fn)` — the callback
+ * receives this as its argument with pre-initialized `client` and `session`.
+ */
+export interface SessionContext<A extends AgentType = AgentType, N extends string = string> {
+    /** Provider-specific SDK client (auto-created by runtime) */
+    client: ProviderClient<A>;
+    /** Provider-specific session (auto-created by runtime) */
+    session: ProviderSession<A>;
+    /**
+     * Structured inputs for this workflow run. Populated from CLI flags
+     * (`--<name>=<value>`) or the interactive picker.
+     *
+     * When the workflow declares an `inputs` schema, only the declared
+     * field names are valid keys — accessing undeclared fields is a
+     * compile-time error. Free-form workflows (no declared schema)
+     * allow any key, including the conventional `prompt` key.
+     */
+    inputs: {
+        [K in N]?: string;
+    };
+    /** Which agent is running */
+    agent: A;
+    /**
+     * Get a completed session's transcript as rendered text.
+     * Accepts a SessionHandle (recommended) or session name string.
+     */
+    transcript(ref: SessionRef): Promise<Transcript>;
+    /**
+     * Get a completed session's raw native messages.
+     * Accepts a SessionHandle (recommended) or session name string.
+     */
+    getMessages(ref: SessionRef): Promise<SavedMessage[]>;
+    /**
+     * Save this session's output for subsequent sessions.
+     * Accepts native SDK message objects only.
+     */
+    save: SaveTranscript;
+    /** Path to this session's storage directory on disk */
+    sessionDir: string;
+    /** tmux pane ID for this session */
+    paneId: string;
+    /** Session UUID */
+    sessionId: string;
+    /**
+     * Spawn a nested sub-session with its own tmux window and graph node.
+     * The sub-session is a child of this session in the graph.
+     * The callback's return value is available as `handle.result`.
+     */
+    stage<T = void>(options: SessionRunOptions, clientOpts: StageClientOptions<A>, sessionOpts: StageSessionOptions<A>, run: (ctx: SessionContext<A, N>) => Promise<T>): Promise<SessionHandle<T>>;
+}
+/**
+ * Top-level context provided to the workflow's `.run()` callback.
+ * Does not have session-specific fields (paneId, save, etc.).
+ */
+export interface WorkflowContext<A extends AgentType = AgentType, N extends string = string> {
+    /**
+     * Structured inputs for this workflow run. Populated from CLI flags
+     * (`--<name>=<value>`) or the interactive picker.
+     *
+     * When the workflow declares an `inputs` schema, only the declared
+     * field names are valid keys — accessing undeclared fields is a
+     * compile-time error. Free-form workflows (no declared schema)
+     * allow any key, including the conventional `prompt` key.
+     */
+    inputs: {
+        [K in N]?: string;
+    };
+    /** Which agent is running */
+    agent: A;
+    /**
+     * Spawn a session with its own tmux window and graph node.
+     * The runtime manages the full lifecycle: create client → create session →
+     * run callback → cleanup. The callback's return value is available as
+     * `handle.result`.
+     */
+    stage<T = void>(options: SessionRunOptions, clientOpts: StageClientOptions<A>, sessionOpts: StageSessionOptions<A>, run: (ctx: SessionContext<A, N>) => Promise<T>): Promise<SessionHandle<T>>;
+    /**
+     * Get a completed session's transcript as rendered text.
+     * Accepts a SessionHandle (recommended) or session name string.
+     */
+    transcript(ref: SessionRef): Promise<Transcript>;
+    /**
+     * Get a completed session's raw native messages.
+     * Accepts a SessionHandle (recommended) or session name string.
+     */
+    getMessages(ref: SessionRef): Promise<SavedMessage[]>;
+}
+/**
+ * Options for defining a workflow.
+ */
+export interface WorkflowOptions<I extends readonly WorkflowInput[] = readonly WorkflowInput[]> {
+    /** Unique workflow name */
+    name: string;
+    /** Human-readable description */
+    description?: string;
+    /**
+     * Optional declared inputs. When provided, the CLI materialises one
+     * `--<name>` flag per entry and the interactive picker renders one form
+     * field per entry. Leave unset to keep the workflow free-form (a single
+     * positional prompt argument).
+     *
+     * Write the array inline so TypeScript can infer literal input names
+     * and enforce them on `ctx.inputs`.
+     */
+    inputs?: I;
+}
+/**
+ * A compiled workflow definition — the sealed output of defineWorkflow().compile().
+ */
+export interface WorkflowDefinition<A extends AgentType = AgentType, N extends string = string> {
+    readonly __brand: "WorkflowDefinition";
+    readonly name: string;
+    readonly description: string;
+    /** Declared input schema — empty array for free-form workflows. */
+    readonly inputs: readonly WorkflowInput[];
+    /** The workflow's entry point. Called by the executor with a WorkflowContext. */
+    readonly run: (ctx: WorkflowContext<A, N>) => Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/sdk/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/sdk/types.ts"],"names":[],"mappings":"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"}