@openhex-ai/agent-sdk 0.0.1 → 0.1.0

package/dist/client-1lMkhPMb.d.ts

@@ -0,0 +1,1066 @@
+import { T as ToolName, S as SdkMcpServer } from './tools-DWFaPtFE.js';
+
+/**
+ * Permission model for the Openhex Agent SDK.
+ *
+ * Controls which tools an agent may invoke and how approvals are
+ * resolved. Mirrors the Claude Agent SDK permission surface so existing
+ * mental models transfer directly.
+ *
+ * NOTE: scaffold only — types are stable, runtime enforcement is wired
+ * up in a follow-up MR.
+ */
+/**
+ * How the agent loop treats tool calls that are not pre-approved.
+ *
+ * - `default`         — prompt (via {@link CanUseTool}) for anything not allowlisted.
+ * - `acceptEdits`     — auto-approve file-editing tools (Write/Edit), prompt for the rest.
+ * - `bypassPermissions` — run every tool without prompting. Use only in trusted automation.
+ * - `plan`            — read-only: the agent may plan but not mutate anything.
+ */
+type PermissionMode = 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan';
+/** The result of a permission decision for a single tool call. */
+type PermissionResult = {
+    behavior: 'allow';
+    /** Optionally override the arguments the tool is invoked with. */
+    updatedInput?: Record<string, unknown>;
+} | {
+    behavior: 'deny';
+    /** Human-readable reason surfaced back to the agent. */
+    message?: string;
+};
+/**
+ * Callback invoked when a tool call needs an approval decision.
+ * Return an allow/deny result. When omitted, {@link PermissionMode}
+ * governs the outcome.
+ */
+type CanUseTool = (toolName: string, input: Record<string, unknown>, options: {
+    signal?: AbortSignal;
+}) => Promise<PermissionResult> | PermissionResult;
+
+/**
+ * Lifecycle hooks for the Openhex Agent SDK.
+ *
+ * Hooks run custom code at key points in the agent loop to validate,
+ * log, block, or transform behavior. Mirrors the Claude Agent SDK hook
+ * surface (PreToolUse, PostToolUse, Stop, ...).
+ *
+ * NOTE: scaffold only — hook dispatch is wired up in a follow-up MR.
+ */
+/** The lifecycle events a hook can subscribe to. */
+type HookEvent = 'PreToolUse' | 'PostToolUse' | 'UserPromptSubmit' | 'Stop' | 'SubagentStop' | 'SessionStart' | 'SessionEnd';
+/** Input payload passed to a hook callback. Shape varies by event. */
+interface HookInput {
+    event: HookEvent;
+    sessionId: string;
+    /** Present for tool-related events. */
+    toolName?: string;
+    toolInput?: Record<string, unknown>;
+    toolResponse?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * Value a hook may return to influence the loop.
+ * An empty object is a no-op. `decision: 'block'` stops the pending
+ * action and surfaces `reason` back to the agent.
+ */
+interface HookOutput {
+    decision?: 'block';
+    reason?: string;
+    /** Optionally rewrite the tool input before it executes (PreToolUse). */
+    updatedInput?: Record<string, unknown>;
+}
+/** A single hook callback. */
+type HookCallback = (input: HookInput, toolUseId: string | undefined, context: {
+    signal?: AbortSignal;
+}) => Promise<HookOutput> | HookOutput;
+/**
+ * Binds one or more callbacks to a tool-name matcher (a regex string,
+ * e.g. `"Edit|Write"`). Omit `matcher` to match every tool.
+ */
+interface HookMatcher {
+    matcher?: string;
+    hooks: HookCallback[];
+}
+/** Map of event → matchers. Passed via {@link AgentOptions.hooks}. */
+type HookRegistry = Partial<Record<HookEvent, HookMatcher[]>>;
+
+/**
+ * Subagent definitions.
+ *
+ * A subagent is a specialized agent the main agent can delegate focused
+ * subtasks to (invoked via the built-in `Agent` tool). Mirrors the
+ * Claude Agent SDK `AgentDefinition`.
+ *
+ * NOTE: scaffold only.
+ */
+
+interface AgentDefinition {
+    /** When the main agent should reach for this subagent. */
+    description: string;
+    /** System prompt that specializes the subagent. */
+    prompt: string;
+    /** Tools this subagent may use. Defaults to the parent's allowlist. */
+    tools?: ToolName[];
+    /** Optional per-subagent model override (e.g. a cheaper/faster model). */
+    model?: string;
+}
+/** Map of subagent name → definition. Passed via {@link AgentOptions.agents}. */
+type AgentRegistry = Record<string, AgentDefinition>;
+
+/**
+ * MCP (Model Context Protocol) server configuration.
+ *
+ * Connect agents to external systems — databases, browsers, APIs — over
+ * MCP. Three transports are supported, mirroring the Claude Agent SDK:
+ *   - `stdio`  : spawn a local process and talk over stdio
+ *   - `http`   : a remote streamable-HTTP MCP server
+ *   - `sdk`    : an in-process server defined with {@link createSdkMcpServer}
+ *
+ * NOTE: scaffold only — connection management lands in a follow-up MR.
+ */
+
+interface StdioMcpServerConfig {
+    type?: 'stdio';
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+interface HttpMcpServerConfig {
+    type: 'http';
+    url: string;
+    headers?: Record<string, string>;
+}
+/** Any MCP server config accepted by {@link AgentOptions.mcpServers}. */
+type McpServerConfig = StdioMcpServerConfig | HttpMcpServerConfig | SdkMcpServer;
+/** Map of server name → config. */
+type McpServerRegistry = Record<string, McpServerConfig>;
+
+/**
+ * The options object accepted by {@link query} and {@link OpenhexClient}.
+ *
+ * Mirrors the Claude Agent SDK `ClaudeAgentOptions` so the surface is
+ * familiar, with Openhex-specific connection fields added on top.
+ *
+ * NOTE: scaffold only — every field is typed; runtime wiring follows.
+ */
+
+/** Where filesystem-based config (skills, commands, CLAUDE.md) is loaded from. */
+type SettingSource = 'user' | 'project' | 'local';
+/** Connection details for reaching the Openhex platform. */
+interface OpenhexConnection {
+    /**
+     * API key for the Openhex platform. Falls back to the
+     * `OPENHEX_API_KEY` environment variable when omitted.
+     */
+    apiKey?: string;
+    /**
+     * Base URL of the Openhex API. Defaults to the production endpoint;
+     * override for self-hosted or staging.
+     */
+    baseUrl?: string;
+    /**
+     * ID of a published platform agent to run against. When set, the
+     * agent's persona, skills, and knowledge base are used as the base.
+     */
+    agentId?: string;
+}
+interface AgentOptions extends OpenhexConnection {
+    /** Model id to run with (e.g. a platform model alias). */
+    model?: string;
+    /** System prompt — a string, or a preset reference with an append. */
+    systemPrompt?: string | {
+        preset: string;
+        append?: string;
+    };
+    /** Tools the agent is allowed to use without prompting. */
+    allowedTools?: ToolName[];
+    /** Tools the agent may never use, even if otherwise allowed. */
+    disallowedTools?: ToolName[];
+    /** How unapproved tool calls are handled. @see PermissionMode */
+    permissionMode?: PermissionMode;
+    /** Programmatic per-call approval callback. */
+    canUseTool?: CanUseTool;
+    /** Lifecycle hooks. @see HookRegistry */
+    hooks?: HookRegistry;
+    /** Named subagents the main agent can delegate to. @see AgentRegistry */
+    agents?: AgentRegistry;
+    /** External + in-process MCP servers. @see McpServerRegistry */
+    mcpServers?: McpServerRegistry;
+    /** Working directory the agent operates in. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** Hard cap on agent loop turns before forcing a result. */
+    maxTurns?: number;
+    /** Resume a prior run by session id (continues with full context). */
+    resume?: string;
+    /** Fork from a prior session instead of mutating it. */
+    forkSession?: boolean;
+    /**
+     * Which on-disk config sources to load. Defaults to none (no implicit
+     * filesystem reads) — opt in explicitly for skills/commands/memory.
+     */
+    settingSources?: SettingSource[];
+    /** Stream incremental assistant deltas as `stream_event` messages. */
+    includePartialMessages?: boolean;
+    /** Abort the run cooperatively. */
+    signal?: AbortSignal;
+}
+
+/**
+ * Session types.
+ *
+ * Sessions carry context across exchanges (files read, prior turns).
+ * They can be resumed or forked via {@link AgentOptions.resume} /
+ * {@link AgentOptions.forkSession}.
+ *
+ * NOTE: scaffold only — persistence backend wired up in a follow-up MR.
+ */
+interface SessionInfo {
+    sessionId: string;
+    /** ISO-8601 creation timestamp. */
+    createdAt: string;
+    /** ISO-8601 timestamp of the last turn. */
+    updatedAt: string;
+    /** Number of turns recorded so far. */
+    numTurns: number;
+    /** The model the session is bound to. */
+    model: string;
+}
+
+/**
+ * Message types streamed out of an agent run.
+ *
+ * The {@link query} async iterator yields a stream of {@link SDKMessage}
+ * values. Consumers narrow on the `type` discriminant. Mirrors the
+ * Claude Agent SDK message surface.
+ *
+ * NOTE: scaffold only — shapes are intentionally close to the platform
+ * wire format but may gain fields as the runtime is wired up.
+ */
+/** A single block of assistant or user content. */
+type ContentBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+} | {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: unknown;
+    is_error?: boolean;
+} | {
+    type: 'image';
+    source: {
+        url: string;
+    } | {
+        data: string;
+        media_type: string;
+    };
+};
+/** Roll-up of tokens / cost for a run. */
+interface UsageInfo {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+    /** Total cost in USD, when the platform reports it. */
+    totalCostUsd?: number;
+}
+/** Emitted once at the start of a run with the resolved session/config. */
+interface SDKSystemMessage {
+    type: 'system';
+    subtype: 'init';
+    sessionId: string;
+    model: string;
+    tools: string[];
+    permissionMode: string;
+}
+/** A full assistant turn (may contain text and/or tool_use blocks). */
+interface SDKAssistantMessage {
+    type: 'assistant';
+    sessionId: string;
+    /** Set when this message originates inside a subagent's context. */
+    parentToolUseId?: string;
+    content: ContentBlock[];
+}
+/** A user turn — usually a tool_result fed back into the loop. */
+interface SDKUserMessage {
+    type: 'user';
+    sessionId: string;
+    parentToolUseId?: string;
+    content: ContentBlock[];
+}
+/** Incremental streaming delta of an in-flight assistant turn. */
+interface SDKPartialAssistantMessage {
+    type: 'stream_event';
+    sessionId: string;
+    parentToolUseId?: string;
+    /** Raw streaming delta (text chunk or tool-input delta). */
+    delta: {
+        type: 'text_delta';
+        text: string;
+    } | {
+        type: 'input_json_delta';
+        partialJson: string;
+    };
+}
+/** Terminal message of a run — success or error, with final result text. */
+interface SDKResultMessage {
+    type: 'result';
+    subtype: 'success' | 'error_max_turns' | 'error_during_execution';
+    sessionId: string;
+    /** Final assistant text, present on success. */
+    result?: string;
+    isError: boolean;
+    numTurns: number;
+    durationMs: number;
+    usage?: UsageInfo;
+}
+/** Discriminated union of everything the agent run can emit. */
+type SDKMessage = SDKSystemMessage | SDKAssistantMessage | SDKUserMessage | SDKPartialAssistantMessage | SDKResultMessage;
+
+/**
+ * Wire + high-level types for chatting with a platform agent.
+ *
+ * These mirror the exact protocol the user-side apps use (the platform's
+ * `conversationRoutes`: `POST /conversations/send` +
+ * `GET /conversations/:id/stream`), so an SDK conversation is
+ * indistinguishable from one started in the app.
+ *
+ * A conversation is a 12-char chat group. Sending without a
+ * `conversationId` creates one and routes the message to the agent(s) in
+ * `targetAgentIds`; sending with a `conversationId` continues it.
+ */
+
+/** Body for `POST /conversations/send`. */
+interface SendRequest {
+    /** The message text. (The platform send endpoint is text-only.) */
+    message: string;
+    /** Continue an existing conversation. Omit to create a new one. */
+    conversationId?: string;
+    /**
+     * Agents for a NEW conversation:
+     *  - 1 id  → route directly to that agent (no coordinator)
+     *  - 2+    → provision a coordinator + the selected agents
+     *  - omitted → coordinator handles agent discovery
+     */
+    targetAgentIds?: string[];
+    /** Display name to label the user in the conversation log. */
+    senderName?: string;
+    /** Per-message avatar URL stored alongside the message. */
+    senderAvatar?: string;
+    /** Free-form metadata forwarded to the agent (e.g. card answers). */
+    metadata?: Record<string, unknown>;
+    /**
+     * Tool-action message from a UI card (confirm/cancel). Routed to the
+     * agent but not recorded in the event stream.
+     */
+    toolAction?: boolean;
+    /** Where the conversation was started (set on creation, immutable). */
+    source?: string;
+    /** Profile id for service-account connectors (new conversations). */
+    profileId?: string;
+}
+/** Per-agent dispatch outcome inside a {@link SendResult}. */
+interface AgentDispatchResult {
+    agentId: string;
+    /** Correlation id of the published command (not a stream cursor). */
+    msgId: string;
+    /** Command-stream id for the dispatch. */
+    streamId: string;
+}
+/** Response from `POST /conversations/send`. */
+interface SendResult {
+    /** The conversation id (created if the request omitted one). */
+    conversationId: string;
+    /** Echo of the user message text. */
+    userMessage?: string;
+    /**
+     * Event-stream id of the recorded user message. This is the cursor to
+     * resume `stream()` from to capture exactly the agent's reply to it.
+     */
+    userEventId?: string;
+    /** One entry per agent the message was dispatched to. */
+    results: AgentDispatchResult[];
+}
+/** Response from `POST /conversations/:id/interrupt`. */
+interface InterruptResult {
+    ok: boolean;
+    interrupted?: boolean;
+    reason?: string;
+}
+/**
+ * The inner agent-runtime event carried inside a stream record's `raw`.
+ * The platform forwards the agent SDK's own message shapes here; the
+ * common discriminants are modeled, with an index signature for the rest.
+ */
+type ChatRawEvent = {
+    type: 'user';
+    message: string | {
+        content: ContentBlock[];
+    };
+    [k: string]: unknown;
+} | {
+    type: 'assistant';
+    message: {
+        content: ContentBlock[];
+    };
+    [k: string]: unknown;
+} | {
+    type: 'thinking';
+    [k: string]: unknown;
+} | {
+    type: 'result';
+    subtype?: string;
+    [k: string]: unknown;
+} | {
+    type: 'system';
+    subtype?: string;
+    [k: string]: unknown;
+} | {
+    type: 'ask_user_question_resolution';
+    toolUseId: string;
+    answers: Record<string, string>;
+} | {
+    type: string;
+    [k: string]: unknown;
+};
+/**
+ * One SSE record from the conversation stream. `data:` payload from the
+ * wire, with `id` populated from the SSE `id:` line (the resumable cursor).
+ */
+interface ChatStreamRecord {
+    /** SSE cursor (event-stream id) — pass back as `lastEventId` to resume. */
+    id?: string;
+    seq: number;
+    /** `agent` is used for multi-agent conversations; `assistant` for 1:1. */
+    sender: 'user' | 'assistant' | 'agent' | 'system';
+    senderId?: string;
+    senderType?: 'user' | 'agent' | 'system';
+    /** Event channel, e.g. `message` | `attachment` | `ack` | `onboarding_welcome`. */
+    event: string;
+    timestamp: number;
+    sessionId: string | null;
+    raw: ChatRawEvent;
+}
+/** Options for opening a raw conversation stream. */
+interface StreamOptions {
+    /** Resume strictly after this event-stream cursor (from a record `id`). */
+    lastEventId?: string;
+    /** Initial-load turn count (ignored when `lastEventId` is set). Default 10. */
+    turns?: number;
+    /** Hard cap on entries per page. */
+    maxEntries?: number;
+    /** Auto-reconnect with backoff on drop (default true). The generator
+     *  still ends when the consumer breaks/returns or `signal` aborts. */
+    reconnect?: boolean;
+    /** Abort the stream. */
+    signal?: AbortSignal;
+}
+/** Options for a single high-level turn. */
+interface TurnOptions {
+    signal?: AbortSignal;
+    /** Continue this conversation instead of creating a new one. */
+    conversationId?: string;
+    /** Agents to route a NEW conversation to (defaults to the client's agent). */
+    targetAgentIds?: string[];
+    /** Abort the turn if no event arrives for this long (ms). Default 180_000
+     *  — generous to cover cold-start pod provisioning on the first message. */
+    idleTimeoutMs?: number;
+}
+/** Aggregated result of a completed turn. */
+interface AgentTurn {
+    /** The conversation this turn belongs to (reuse it to continue). */
+    conversationId: string;
+    /** Concatenated assistant text across the turn. */
+    text: string;
+    /** Tool calls the agent made during the turn. */
+    toolCalls: Array<{
+        id?: string;
+        name: string;
+        input: Record<string, unknown>;
+    }>;
+    /** Every record observed for the turn (assistant + tool results + system). */
+    records: ChatStreamRecord[];
+    /** The terminal `result` event, if one was seen. */
+    result?: ChatRawEvent;
+    /** Session id reported by the stream, if any. */
+    sessionId: string | null;
+    /** Last SSE cursor seen — pass as `lastEventId` to the next turn. */
+    lastEventId?: string;
+}
+/** A page of historical records from `GET /conversations/:id/history`. */
+interface HistoryPage {
+    entries: Array<{
+        id: string;
+        data: ChatStreamRecord;
+    }>;
+    hasMore: boolean;
+}
+
+/**
+ * The primary entry point: `query`.
+ *
+ * Runs an agent against the Openhex platform and streams back the
+ * resulting messages. Mirrors the Claude Agent SDK's `query` so the
+ * ergonomics are familiar:
+ *
+ * @example
+ * import { query } from '@openhex-ai/agent-sdk';
+ *
+ * for await (const message of query({
+ *   prompt: 'Summarize the latest support tickets',
+ *   options: { allowedTools: ['WebSearch', 'Read'] },
+ * })) {
+ *   if (message.type === 'result') console.log(message.result);
+ * }
+ *
+ * NOTE: scaffold only — resolves config and constructs the transport,
+ * then defers to it. The transport itself is not implemented yet.
+ */
+
+interface QueryParams {
+    /**
+     * The instruction for the agent. A string for a one-shot run, or an
+     * async iterable of strings for an interactive/streaming-input session.
+     */
+    prompt: string | AsyncIterable<string>;
+    options?: AgentOptions;
+}
+/**
+ * The handle returned by {@link query}: an async iterable of
+ * {@link SDKMessage}s plus control methods for an in-flight run.
+ */
+interface Query extends AsyncGenerator<SDKMessage, void, void> {
+    /** Cooperatively abort the run. */
+    interrupt(): Promise<void>;
+}
+/**
+ * Start an agent run. Returns a {@link Query} you iterate to consume the
+ * message stream.
+ */
+declare function query(params: QueryParams): Query;
+
+/** API version prefix every platform route lives under. */
+declare const API_PREFIX = "/api/v2";
+interface HttpClientConfig {
+    /** API key or JWT. Falls back to `OPENHEX_API_KEY` when omitted. */
+    apiKey?: string;
+    /** Base URL of the platform API. Defaults to {@link DEFAULT_BASE_URL}. */
+    baseUrl?: string;
+    /**
+     * Login type stamped as `X-Login-Type` (matches the web/app clients).
+     * Only relevant for JWT auth; harmless to omit for API-key auth.
+     */
+    loginType?: string;
+    /**
+     * Service-account id to impersonate via `X-Act-As`. The caller must own
+     * the service account (enforced server-side).
+     */
+    actAs?: string;
+    /** Extra headers merged into every request. */
+    headers?: Record<string, string>;
+    /** Per-request timeout for non-streaming calls (ms). Default 30_000. */
+    timeoutMs?: number;
+    /** Override the global fetch (testing / custom agents). */
+    fetch?: typeof fetch;
+}
+interface RequestOptions {
+    method?: string;
+    /** JSON-serializable request body. */
+    body?: unknown;
+    /** Extra/override headers for this request. */
+    headers?: Record<string, string>;
+    /** Caller-supplied abort signal (merged with the timeout signal). */
+    signal?: AbortSignal;
+    /** Override the default timeout for this request (ms). 0 disables it. */
+    timeoutMs?: number;
+}
+declare class HttpClient {
+    private readonly apiKey;
+    readonly baseUrl: string;
+    private readonly loginType?;
+    private readonly actAs?;
+    private readonly extraHeaders;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(config?: HttpClientConfig);
+    /** Build the full URL for an API path (prefixing `/api/v2` if needed). */
+    url(path: string): string;
+    /** Headers common to every request. `accept` differs for SSE vs JSON. */
+    buildHeaders(accept: string, extra?: Record<string, string>): Record<string, string>;
+    /** Map a non-2xx response to an {@link ApiError}, extracting `detail`. */
+    private toError;
+    /** Perform a JSON request and parse the response body. */
+    requestJson<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+    /** Perform a request and return the raw {@link Response} (used for SSE). */
+    requestRaw(path: string, options?: RequestOptions, accept?: string): Promise<Response>;
+}
+
+/**
+ * AgentChatClient — chat with a platform agent over the exact protocol
+ * the user-side apps use (`conversationRoutes`).
+ *
+ * Endpoints (all under `/api/v2`):
+ *   POST /conversations/send             — create/continue a conversation, route a message
+ *   GET  /conversations/:id/stream       — SSE record stream (resumable)
+ *   GET  /conversations/:id/messages     — full history (JSON)
+ *   GET  /conversations/:id/history      — paginated older history (JSON)
+ *   POST /conversations/:id/interrupt    — interrupt the running turn
+ *
+ * Low-level methods (`send`, `stream`, `messages`, `history`, `interrupt`)
+ * map 1:1 to the wire. High-level helpers (`runTurn`, `sendMessage`) add
+ * turn isolation (resume the stream from the user message's event id),
+ * reconnection, and an idle-timeout for cold-start pod provisioning.
+ */
+
+declare class AgentChatClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Create or continue a conversation and route a message to its agent(s).
+     * Returns immediately (non-blocking); consume {@link stream} for the reply.
+     */
+    send(req: SendRequest, opts?: {
+        signal?: AbortSignal;
+    }): Promise<SendResult>;
+    /** Interrupt the conversation's currently-running turn. */
+    interrupt(conversationId: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<InterruptResult>;
+    /** Full conversation history (all messages as JSON). */
+    messages(conversationId: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        entries: Array<{
+            id: string;
+            data: ChatStreamRecord;
+        }>;
+    }>;
+    /** A page of older history, before a cursor. */
+    history(conversationId: string, params: {
+        before: string;
+        turns?: number;
+        maxEntries?: number;
+    }, opts?: {
+        signal?: AbortSignal;
+    }): Promise<HistoryPage>;
+    /**
+     * Open the conversation's SSE record stream. Yields every record
+     * (replayed history then live tail), auto-reconnecting with capped
+     * backoff on drop. The generator ends when the consumer breaks/returns
+     * or `signal` aborts.
+     */
+    stream(conversationId: string, opts?: StreamOptions): AsyncGenerator<ChatStreamRecord, void, void>;
+    /**
+     * Stream a single turn over an existing conversation: resume the event
+     * stream strictly after `opts.lastEventId` (the user message's event id)
+     * and stop at the agent's terminal `result`. Reconnects on drop; an
+     * `idleTimeoutMs` gap with no events aborts (covers cold-start pod
+     * provisioning). Use when you sent the message yourself via {@link send}.
+     */
+    resumeTurn(conversationId: string, opts?: TurnOptions & {
+        lastEventId?: string;
+    }): AsyncGenerator<ChatStreamRecord, void, void>;
+    /**
+     * Send a message and stream just this turn's records, ending when the
+     * agent's `result` event arrives.
+     *
+     * The message is sent first; the stream then resumes precisely from the
+     * user message's event id, so only the agent's reply is surfaced — no
+     * history, no heuristics. To learn the (possibly new) conversation id
+     * while streaming, use {@link sendMessage} or the stateful
+     * {@link Conversation}.
+     *
+     * The first message in a new conversation auto-provisions the agent's
+     * pod, so the first turn can take tens of seconds before any record
+     * arrives; `idleTimeoutMs` (default 180s) bounds the wait.
+     */
+    runTurn(req: SendRequest, opts?: TurnOptions): AsyncGenerator<ChatStreamRecord, void, void>;
+    /**
+     * Send a message and resolve with the aggregated turn (assistant text,
+     * tool calls, all records, conversation id, and a resume cursor).
+     */
+    sendMessage(req: SendRequest, opts?: TurnOptions): Promise<AgentTurn>;
+    /**
+     * Start a stateful conversation handle that remembers its id across
+     * turns. The first {@link Conversation.send} creates the conversation
+     * (routed to `targetAgentIds`); subsequent sends continue it.
+     */
+    conversation(opts?: {
+        conversationId?: string;
+        targetAgentIds?: string[];
+    }): Conversation;
+}
+/**
+ * A stateful 1:1 (or multi-agent) conversation. Tracks the conversation
+ * id so you can `send` repeated turns without re-passing it, and continues
+ * the same chat-group context each time.
+ */
+declare class Conversation {
+    private readonly client;
+    private conversationId;
+    private readonly targetAgentIds;
+    constructor(client: AgentChatClient, conversationId: string | undefined, targetAgentIds: string[] | undefined);
+    /** The conversation id, once the first message has been sent. */
+    get id(): string | undefined;
+    /** Build the send request for the next turn (create vs continue). */
+    private buildRequest;
+    /** Send a turn and resolve with the aggregated result. */
+    send(message: string, opts?: TurnOptions & Partial<SendRequest>): Promise<AgentTurn>;
+    /** Send a turn and stream its records as they arrive. */
+    stream(message: string, opts?: TurnOptions & Partial<SendRequest>): AsyncGenerator<ChatStreamRecord, void, void>;
+    /** Interrupt the running turn in this conversation. */
+    interrupt(): Promise<InterruptResult>;
+}
+
+/**
+ * Training-mode chat — talk to an agent AS ITS OWNER over the dev/train
+ * protocol (the agent runs in CREATION/TRAINING mode, so it can learn:
+ * edit skills/knowledge/persona, accept feedback, etc.). This is distinct
+ * from {@link AgentChatClient}, which is the user-side conversations
+ * protocol.
+ *
+ * Wire (all under /api/v2, owner/collaborator auth):
+ *   POST /agents/:id/dev/send          — send a training message → { ok, msgId }
+ *   GET  /agents/:id/messages/stream    — SSE record stream (seq-keyed, resumable
+ *                                         via lastEventId; `turns=1` = latest turn)
+ *   GET  /agents/:id/messages/history   — JSON history
+ *   POST /agents/:id/dev/interrupt      — interrupt the running turn
+ *
+ * The training thread is agent-scoped (one per owner), so there's no
+ * conversationId — the agent id IS the thread.
+ */
+
+interface TrainingSendResult {
+    ok: boolean;
+    msgId?: string;
+}
+interface TrainingStreamOptions extends TurnOptions {
+    /** Resume strictly after this record seq (stringified). */
+    lastEventId?: string;
+    /** Return only the latest N turns (server-side turn paging). */
+    turns?: number;
+    reconnect?: boolean;
+}
+/** A training (owner-mode) chat bound to one agent. */
+declare class TrainingChat {
+    private readonly http;
+    private readonly agentId;
+    constructor(http: HttpClient, agentId: string);
+    /** Send a training message; the reply streams asynchronously (see {@link stream}). */
+    send(message: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<TrainingSendResult>;
+    /** Interrupt the running training turn. */
+    interrupt(opts?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        ok: boolean;
+    }>;
+    /**
+     * Training transcript (JSON), paginated backward from `before` (a Redis
+     * stream id). The endpoint REQUIRES `before`, so we default to a
+     * far-future sentinel to fetch the latest turns; pass a real id to page
+     * older history.
+     */
+    messages(opts?: {
+        before?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        entries: Array<{
+            data?: ChatStreamRecord;
+        }>;
+        hasMore?: boolean;
+    }>;
+    /** Raw SSE record stream of the training thread (replayed + live tail). */
+    stream(opts?: TrainingStreamOptions): AsyncGenerator<ChatStreamRecord, void, void>;
+    /**
+     * Send a training message and stream just that turn's records, ending at
+     * the agent's terminal `result`. Streams the latest turn (`turns=1`) after
+     * the send; an `idleTimeoutMs` gap (default 180s) bounds cold-start waits.
+     */
+    runTurn(message: string, opts?: TurnOptions): AsyncGenerator<ChatStreamRecord, void, void>;
+}
+
+/**
+ * Wire types for the Workspace API (`/api/v2/workspaces/*`).
+ *
+ * These mirror the platform's published OpenAPI surface 1:1 — the same
+ * contract documented at `/api/v2/workspaces/openapi.json`. A workspace
+ * is a billing + membership boundary an SP (service provider / partner)
+ * owns; the API lets a partner backend provision members, mint member
+ * sessions, grant credits, and read reporting.
+ *
+ * Auth is a `Bearer` token in every case (see {@link WorkspaceClient}):
+ *  - a workspace API key (`sk_ws_…`) for partner-backend operations,
+ *  - or no token for the public SMS-signup endpoints.
+ *
+ * The owner-JWT admin surface (workspace ledger, insights, API-key
+ * management) is deliberately NOT mirrored in the SDK — those routes
+ * power the SP admin UI and aren't in the published partner spec.
+ *
+ * Date fields cross the wire as ISO-8601 strings (the server serializes
+ * its `Date`s to JSON), so they're typed as `string` here.
+ */
+/** Identity of the workspace a key/JWT is acting on. */
+interface WorkspaceWhoami {
+    workspace_id: string;
+    slug: string;
+    display_name: string;
+    status: string;
+    /** The API key id the request authenticated with. */
+    api_key_id: string;
+}
+/** One member row from {@link WorkspaceClient.listMembers}. */
+interface WorkspaceMember {
+    user_id: string;
+    billing_account_id: string;
+    /** The SP's own reference for this user (may be null for legacy rows). */
+    sp_user_ref: string | null;
+    status: string;
+    /** ISO-8601 timestamp. */
+    joined_at: string;
+    /** Current credit balance on the member's billing account. */
+    balance: number;
+}
+interface MembersListResponse {
+    members: WorkspaceMember[];
+}
+/** Body for {@link WorkspaceClient.provisionMember}. */
+interface ProvisionMemberRequest {
+    /** The SP's stable reference for this user. Idempotency key for the member. */
+    sp_user_ref: string;
+    /** Optional display name to label the member. */
+    display_name?: string;
+}
+interface ProvisionMemberResponse {
+    member_id: string;
+    billing_account_id: string;
+    /** `true` if this call created the member; `false` if it already existed. */
+    created: boolean;
+}
+/** Body for {@link WorkspaceClient.grantCredits}. */
+interface GrantCreditsRequest {
+    /** Positive credit amount to grant (max 1e9). */
+    amount: number;
+    /** Caller-supplied idempotency key; replays return the original purchase. */
+    idempotency_key: string;
+}
+interface GrantCreditsResponse {
+    /** Member's balance after the grant. */
+    balance: number;
+    purchase_id: string;
+    /** `true` when this was a replay of a prior identical grant. */
+    idempotent: boolean;
+}
+/** Body for {@link WorkspaceClient.mintSession}. */
+interface MintSessionRequest {
+    /** The already-provisioned member's SP reference. */
+    sp_user_ref: string;
+    /** Token lifetime in seconds (max 86_400). Server picks a default if omitted. */
+    ttl_seconds?: number;
+}
+/** A minted member session — returned by mintSession + SMS verify. */
+interface SessionTokenResponse {
+    /** JWT the member's client presents to the platform. */
+    token: string;
+    user_id: string;
+    /** ISO-8601 expiry timestamp. */
+    expires_at: string;
+}
+/** Body for {@link WorkspaceClient.sendSmsCode}. */
+interface SmsSendRequest {
+    phone: string;
+}
+/** Body for {@link WorkspaceClient.verifySmsCode}. */
+interface SmsVerifyRequest {
+    phone: string;
+    code: string;
+}
+/** Options accepted by every workspace request. */
+interface WorkspaceRequestOptions {
+    /** Abort the request. */
+    signal?: AbortSignal;
+}
+
+/**
+ * WorkspaceClient — manage a platform workspace over the partner-facing
+ * subset of `/api/v2/workspaces/*` (the same surface the published
+ * OpenAPI spec exposes).
+ *
+ * Endpoints (all under `/api/v2`):
+ *
+ *   Workspace API key (`sk_ws_…`) — partner backend:
+ *     GET    /workspaces/whoami
+ *     POST   /workspaces/:slug/members
+ *     DELETE /workspaces/:slug/members/:memberId
+ *     POST   /workspaces/:slug/sessions
+ *
+ *   Either auth (owner JWT or workspace API key):
+ *     GET    /workspaces/:slug/members
+ *     POST   /workspaces/:slug/members/:memberId/credits
+ *
+ *   Public (no auth):
+ *     POST   /workspaces/:slug/sms/send
+ *     POST   /workspaces/:slug/sms/verify
+ *
+ * Deliberately omitted: the 6 owner-JWT admin routes (workspace ledger,
+ * insights, per-member ledger, API-key CRUD). They power the SP admin
+ * UI in `webapp/src/app/[locale]/(app)/settings/*` and don't appear in
+ * the published partner OpenAPI spec (hidden in
+ * `mysta-server/src/routes/workspacesOwnerRoutes.ts`). Wrapping them in
+ * the SDK would invite partners to call routes the docs say don't exist;
+ * with a workspace API key they'd just 401.
+ *
+ * Auth is the `Bearer` token carried by the underlying {@link HttpClient}.
+ * Configure the client with the token the operation needs: a workspace
+ * API key for partner calls, or skip the header entirely for the public
+ * SMS endpoints.
+ *
+ * Use {@link WorkspaceClient.workspace} for a slug-bound handle so you
+ * don't repeat the slug on every call.
+ */
+
+declare class WorkspaceClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Identify the workspace the configured API key belongs to. Solves the
+     * bootstrap problem for a new partner who holds only the `sk_ws_…` token
+     * but every slug-keyed route needs a slug.
+     */
+    whoami(opts?: WorkspaceRequestOptions): Promise<WorkspaceWhoami>;
+    /**
+     * Provision (or look up) a workspace member by SP user reference.
+     * Idempotent on `(workspace, sp_user_ref)` — the first call creates the
+     * member, later calls return the existing ids (`created: false`).
+     */
+    provisionMember(slug: string, body: ProvisionMemberRequest, opts?: WorkspaceRequestOptions): Promise<ProvisionMemberResponse>;
+    /** Suspend a member (soft — sets status to `suspended`). */
+    suspendMember(slug: string, memberId: string, opts?: WorkspaceRequestOptions): Promise<void>;
+    /**
+     * Mint a session JWT for an already-provisioned member. The partner
+     * authenticates the human on their side, then calls this with the same
+     * `sp_user_ref` to get a token the member's client presents to the platform.
+     */
+    mintSession(slug: string, body: MintSessionRequest, opts?: WorkspaceRequestOptions): Promise<SessionTokenResponse>;
+    /** List workspace members with current balances (capped at 500). */
+    listMembers(slug: string, opts?: WorkspaceRequestOptions): Promise<MembersListResponse>;
+    /**
+     * Grant credits to a member from the workspace pool. Idempotent on
+     * `body.idempotency_key` — replays return the original purchase.
+     */
+    grantCredits(slug: string, memberId: string, body: GrantCreditsRequest, opts?: WorkspaceRequestOptions): Promise<GrantCreditsResponse>;
+    /**
+     * Send a one-time SMS verification code for public signup. Requires the
+     * workspace to have `public_sms_signup_enabled`.
+     */
+    sendSmsCode(slug: string, body: SmsSendRequest, opts?: WorkspaceRequestOptions): Promise<void>;
+    /** Verify an SMS code and mint a member session JWT in one shot. */
+    verifySmsCode(slug: string, body: SmsVerifyRequest, opts?: WorkspaceRequestOptions): Promise<SessionTokenResponse>;
+    /**
+     * A slug-bound handle so you don't repeat the slug on every call.
+     * `client.workspaces.workspace('acme').listMembers()`.
+     */
+    workspace(slug: string): Workspace;
+}
+/**
+ * A workspace pinned to one slug. Thin sugar over {@link WorkspaceClient}
+ * that drops the leading `slug` argument from every method. `whoami` stays
+ * on the parent client (it's key-bound, not slug-bound).
+ */
+declare class Workspace {
+    private readonly client;
+    readonly slug: string;
+    constructor(client: WorkspaceClient, slug: string);
+    listMembers(opts?: WorkspaceRequestOptions): Promise<MembersListResponse>;
+    provisionMember(body: ProvisionMemberRequest, opts?: WorkspaceRequestOptions): Promise<ProvisionMemberResponse>;
+    suspendMember(memberId: string, opts?: WorkspaceRequestOptions): Promise<void>;
+    grantCredits(memberId: string, body: GrantCreditsRequest, opts?: WorkspaceRequestOptions): Promise<GrantCreditsResponse>;
+    mintSession(body: MintSessionRequest, opts?: WorkspaceRequestOptions): Promise<SessionTokenResponse>;
+    sendSmsCode(body: SmsSendRequest, opts?: WorkspaceRequestOptions): Promise<void>;
+    verifySmsCode(body: SmsVerifyRequest, opts?: WorkspaceRequestOptions): Promise<SessionTokenResponse>;
+}
+
+/**
+ * `OpenhexClient` — a stateful, higher-level wrapper over the SDK.
+ *
+ * Pin connection + agent config once, then chat with an agent (`chat`,
+ * `sendMessage`, `conversation`), run local-style queries (`query`,
+ * scaffold), or manage sessions.
+ */
+
+interface OpenhexClientConfig extends OpenhexConnection {
+    /** `X-Login-Type` header (matches the web/app clients). JWT auth only. */
+    loginType?: string;
+    /** Service-account id to impersonate via `X-Act-As` (caller must own it). */
+    actAs?: string;
+    /** Per-request timeout for non-streaming calls (ms). Default 30_000. */
+    timeoutMs?: number;
+    /** Override the global fetch (testing / custom runtimes). */
+    fetch?: typeof fetch;
+    /** Default options merged into every {@link OpenhexClient.query} call. */
+    defaultOptions?: Omit<AgentOptions, keyof OpenhexConnection>;
+}
+declare class OpenhexClient {
+    private readonly config;
+    /** Low- and high-level chat API (conversations protocol). */
+    readonly chat: AgentChatClient;
+    /**
+     * Workspace API (`/api/v2/workspaces/*`) — provision members, mint
+     * member sessions, grant credits, read reporting. Auth is whatever
+     * token the client is configured with (a `sk_ws_…` workspace API key
+     * for partner calls, or the owner's JWT for SP-admin calls).
+     */
+    readonly workspaces: WorkspaceClient;
+    private readonly http;
+    constructor(config?: OpenhexClientConfig);
+    /**
+     * A slug-bound workspace handle so you don't repeat the slug on every
+     * call. Equivalent to `client.workspaces.workspace(slug)`.
+     */
+    workspace(slug: string): Workspace;
+    /**
+     * Training-mode chat with an agent AS ITS OWNER (the dev/train protocol —
+     * the agent runs in CREATION/TRAINING mode and can learn from feedback).
+     * Defaults to the client's configured `agentId`; pass one to override.
+     */
+    training(agentId?: string): TrainingChat;
+    /** Default target agents for new conversations (from `config.agentId`). */
+    private defaultTargets;
+    /** Build a {@link SendRequest} from a message + turn options. */
+    private buildRequest;
+    /**
+     * Send a message and resolve with the aggregated turn. Creates a new
+     * conversation routed to the configured agent unless `opts.conversationId`
+     * is given. The returned turn carries `conversationId` to continue.
+     */
+    sendMessage(message: string, opts?: TurnOptions): Promise<AgentTurn>;
+    /** Stream a single turn's records (see {@link sendMessage}). */
+    runTurn(message: string, opts?: TurnOptions): AsyncGenerator<ChatStreamRecord, void, void>;
+    /**
+     * Start a stateful conversation that remembers its id across turns,
+     * defaulting its target agents to the configured agent.
+     */
+    conversation(opts?: {
+        conversationId?: string;
+        targetAgentIds?: string[];
+    }): Conversation;
+    /**
+     * Run an agent query using this client's connection + default options.
+     * Per-call `options` are shallow-merged over the client defaults.
+     */
+    query(params: QueryParams): Query;
+    /** List recent sessions for the configured agent. */
+    listSessions(): Promise<SessionInfo[]>;
+    /** Fetch metadata for a single session. */
+    getSession(_sessionId: string): Promise<SessionInfo>;
+    /** Delete a session and its stored context. */
+    deleteSession(_sessionId: string): Promise<void>;
+}
+
+export { type StreamOptions as $, type AgentOptions as A, type ProvisionMemberRequest as B, type ChatStreamRecord as C, type ProvisionMemberResponse as D, type QueryParams as E, type SDKAssistantMessage as F, type GrantCreditsRequest as G, type HookCallback as H, type InterruptResult as I, type SDKPartialAssistantMessage as J, type SDKResultMessage as K, type SDKSystemMessage as L, type McpServerConfig as M, type SDKUserMessage as N, OpenhexClient as O, type PermissionMode as P, type Query as Q, type RequestOptions as R, type SDKMessage as S, type SendRequest as T, type SendResult as U, type SessionInfo as V, type SessionTokenResponse as W, type SettingSource as X, type SmsSendRequest as Y, type SmsVerifyRequest as Z, type StdioMcpServerConfig as _, type HookMatcher as a, TrainingChat as a0, type TrainingSendResult as a1, type TurnOptions as a2, type UsageInfo as a3, Workspace as a4, WorkspaceClient as a5, type WorkspaceMember as a6, type WorkspaceRequestOptions as a7, type WorkspaceWhoami as a8, query as a9, API_PREFIX as b, AgentChatClient as c, type AgentDefinition as d, type AgentDispatchResult as e, type AgentRegistry as f, type AgentTurn as g, type CanUseTool as h, type ChatRawEvent as i, type ContentBlock as j, Conversation as k, type GrantCreditsResponse as l, type HistoryPage as m, type HookEvent as n, type HookInput as o, type HookOutput as p, type HookRegistry as q, HttpClient as r, type HttpClientConfig as s, type HttpMcpServerConfig as t, type McpServerRegistry as u, type MembersListResponse as v, type MintSessionRequest as w, type OpenhexClientConfig as x, type OpenhexConnection as y, type PermissionResult as z };