@coder/ai-sdk-agent 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,526 @@
+import { ToolSet, Agent, SystemModelMessage, ToolChoice, StopCondition, ToolLoopAgent } from 'ai';
+import { LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3StreamResult, LanguageModelV3GenerateResult, LanguageModelV3StreamPart, LanguageModelV3Prompt } from '@ai-sdk/provider';
+
+/**
+ * Wire types for Coder's experimental `chatd` chat API
+ * (`/api/experimental/chats`). These mirror the Go types in
+ * `coder/coder`'s `codersdk/chats.go` (JSON shapes), restricted to the subset
+ * this client uses. Field names use snake_case to match the wire format.
+ *
+ * NOTE: The chatd API is experimental and may change between Coder releases.
+ */
+type ChatInputPartType = "text" | "file" | "file-reference";
+interface ChatInputPart {
+    type: ChatInputPartType;
+    text?: string;
+    file_id?: string;
+    file_name?: string;
+    start_line?: number;
+    end_line?: number;
+    content?: string;
+}
+type ChatClientType = "ui" | "api";
+type ChatPlanMode = "" | "plan";
+type ChatBusyBehavior = "queue" | "interrupt";
+/**
+ * A client-executed ("dynamic") tool definition. chatd never executes these;
+ * when the model calls one, the chat enters `requires_action` and the client
+ * must execute it and submit results via {@link SubmitToolResultsRequest}.
+ *
+ * NOTE: the JSON key is `input_schema` (snake_case), per chatd.
+ */
+interface DynamicTool {
+    name: string;
+    description?: string;
+    /** A JSON Schema object describing the tool input. */
+    input_schema: unknown;
+}
+interface CreateChatRequest {
+    organization_id: string;
+    content: ChatInputPart[];
+    system_prompt?: string;
+    workspace_id?: string;
+    model_config_id?: string;
+    mcp_server_ids?: string[];
+    labels?: Record<string, string>;
+    unsafe_dynamic_tools?: DynamicTool[];
+    plan_mode?: ChatPlanMode;
+    client_type?: ChatClientType;
+}
+interface CreateChatMessageRequest {
+    content: ChatInputPart[];
+    model_config_id?: string;
+    mcp_server_ids?: string[];
+    busy_behavior?: ChatBusyBehavior;
+    plan_mode?: ChatPlanMode;
+}
+/** Result of a single client-executed tool call. */
+interface ToolResult {
+    tool_call_id: string;
+    /** JSON-serializable tool output. */
+    output: unknown;
+    is_error?: boolean;
+}
+interface SubmitToolResultsRequest {
+    results: ToolResult[];
+}
+interface UpdateChatRequest {
+    title?: string;
+    archived?: boolean;
+}
+type ChatStatus = "waiting" | "pending" | "running" | "paused" | "completed" | "error" | "requires_action" | "interrupting";
+type ChatMessageRole = "system" | "user" | "assistant" | "tool";
+type ChatMessagePartType = "text" | "reasoning" | "tool-call" | "tool-result" | "source" | "file" | "file-reference" | "context-file" | "skill";
+/**
+ * A part of a chat message. chatd models this as a single flat struct with a
+ * `type` discriminator and many optional fields (see `codersdk.ChatMessagePart`),
+ * so we mirror that shape rather than a strict discriminated union.
+ */
+interface ChatMessagePart {
+    type: ChatMessagePartType;
+    text?: string;
+    signature?: string;
+    tool_call_id?: string;
+    tool_name?: string;
+    mcp_server_config_id?: string | null;
+    /** tool-call: complete arguments (JSON value). */
+    args?: unknown;
+    /** tool-call: incremental argument text chunk during streaming. */
+    args_delta?: string;
+    parsed_commands?: string[][];
+    /** tool-result: complete result (JSON value). */
+    result?: unknown;
+    /** tool-result: incremental result text chunk during streaming. */
+    result_delta?: string;
+    result_reset?: boolean;
+    is_error?: boolean;
+    is_media?: boolean;
+    provider_executed?: boolean;
+    created_at?: string;
+    completed_at?: string;
+    source_id?: string;
+    url?: string;
+    title?: string;
+    media_type?: string;
+    name?: string;
+    file_id?: string | null;
+    file_name?: string;
+    start_line?: number;
+    end_line?: number;
+    content?: string;
+    skill_name?: string;
+    skill_description?: string;
+}
+interface ChatMessageUsage {
+    input_tokens?: number;
+    output_tokens?: number;
+    total_tokens?: number;
+    reasoning_tokens?: number;
+    cache_creation_tokens?: number;
+    cache_read_tokens?: number;
+    context_limit?: number;
+}
+interface ChatMessage {
+    id: number;
+    chat_id: string;
+    created_by?: string;
+    model_config_id?: string;
+    created_at: string;
+    role: ChatMessageRole;
+    content?: ChatMessagePart[];
+    usage?: ChatMessageUsage;
+}
+interface ChatErrorPayload {
+    message: string;
+    detail?: string;
+    kind?: string;
+    provider?: string;
+    retryable?: boolean;
+    status_code?: number;
+}
+interface Chat {
+    id: string;
+    organization_id: string;
+    owner_id: string;
+    owner_username?: string;
+    workspace_id?: string | null;
+    agent_id?: string | null;
+    parent_chat_id?: string | null;
+    root_chat_id?: string | null;
+    last_model_config_id?: string;
+    title: string;
+    status: ChatStatus;
+    plan_mode?: ChatPlanMode;
+    last_error?: ChatErrorPayload | null;
+    created_at: string;
+    updated_at: string;
+    archived: boolean;
+    mcp_server_ids?: string[];
+    client_type?: ChatClientType;
+}
+interface ChatQueuedMessage {
+    id: number;
+    chat_id: string;
+    content: ChatMessagePart[];
+    created_at: string;
+}
+interface CreateChatMessageResponse {
+    message?: ChatMessage;
+    queued_message?: ChatQueuedMessage;
+    queued: boolean;
+    warnings?: string[];
+}
+interface ChatMessagesResponse {
+    messages: ChatMessage[];
+    queued_messages: ChatQueuedMessage[];
+    has_more: boolean;
+}
+interface ChatModelConfig {
+    id: string;
+    provider: string;
+    ai_provider_id?: string;
+    model: string;
+    display_name: string;
+    enabled?: boolean;
+    is_default?: boolean;
+    context_limit?: number;
+    compression_threshold?: number;
+}
+type ChatStreamEventType = "message_part" | "message" | "status" | "error" | "queue_update" | "retry" | "action_required" | "preview_reset" | "history_reset";
+interface ChatStreamMessagePart {
+    role?: ChatMessageRole;
+    part: ChatMessagePart;
+    history_version?: number;
+    generation_attempt?: number;
+    seq?: number;
+}
+interface ChatStreamStatus {
+    status: ChatStatus;
+}
+interface ChatStreamToolCall {
+    tool_call_id: string;
+    tool_name: string;
+    /** JSON string of the tool-call arguments. */
+    args: string;
+}
+interface ChatStreamActionRequired {
+    tool_calls: ChatStreamToolCall[];
+}
+interface ChatStreamRetry {
+    attempt: number;
+    delay_ms: number;
+    error: string;
+    kind?: string;
+    provider?: string;
+    status_code?: number;
+    retrying_at: string;
+}
+interface ChatStreamEvent {
+    type: ChatStreamEventType;
+    chat_id: string;
+    message?: ChatMessage;
+    message_part?: ChatStreamMessagePart;
+    status?: ChatStreamStatus;
+    error?: ChatErrorPayload;
+    retry?: ChatStreamRetry;
+    queued_messages?: ChatQueuedMessage[];
+    action_required?: ChatStreamActionRequired;
+}
+/** Terminal statuses: the chat has stopped generating for this turn. */
+declare const TERMINAL_STATUSES: ReadonlySet<ChatStatus>;
+
+/**
+ * A minimal WebSocket factory abstraction so the stream reader can run on
+ * Node (via the `ws` package, with header auth) or in environments that
+ * provide a global `WebSocket` (browsers, where auth must go in the query
+ * string). Node is the default target.
+ */
+interface WebSocketLike {
+    send(data: string): void;
+    close(code?: number): void;
+    addEventListener(type: "open", cb: () => void): void;
+    addEventListener(type: "message", cb: (ev: {
+        data: unknown;
+    }) => void): void;
+    addEventListener(type: "error", cb: (ev: unknown) => void): void;
+    addEventListener(type: "close", cb: (ev: {
+        code?: number;
+        reason?: string;
+    }) => void): void;
+    removeEventListener(type: "open", cb: () => void): void;
+    removeEventListener(type: "message", cb: (ev: {
+        data: unknown;
+    }) => void): void;
+    removeEventListener(type: "error", cb: (ev: unknown) => void): void;
+    removeEventListener(type: "close", cb: (ev: {
+        code?: number;
+        reason?: string;
+    }) => void): void;
+}
+type WebSocketFactory = (url: string, protocols: {
+    headers: Record<string, string>;
+}) => WebSocketLike;
+interface StreamChatEventsOptions {
+    baseUrl: string;
+    token: string;
+    chatId: string;
+    /** Only stream events for messages with id greater than this. */
+    afterId?: number;
+    signal?: AbortSignal;
+    webSocketFactory?: WebSocketFactory;
+}
+/**
+ * Opens the chatd `/stream` WebSocket and yields decoded {@link ChatStreamEvent}s
+ * as an async iterable. Each text frame from chatd is a JSON array of events;
+ * we flatten them into a single stream.
+ *
+ * The chat stream is a live subscription that stays open after a turn settles,
+ * so callers should `break` out of the loop once they observe a terminal status
+ * — that triggers generator cleanup, which closes the socket.
+ */
+declare function streamChatEvents(options: StreamChatEventsOptions): AsyncGenerator<ChatStreamEvent, void, void>;
+
+interface CoderChatClientOptions {
+    /** Base URL of the Coder deployment, e.g. `https://dev.coder.com`. */
+    baseUrl: string;
+    /** Coder API token or session token (sent as `Coder-Session-Token`). */
+    token: string;
+    /** Custom fetch implementation (defaults to global `fetch`). */
+    fetch?: typeof globalThis.fetch;
+    /** Custom WebSocket factory (defaults to the `ws` package on Node). */
+    webSocketFactory?: WebSocketFactory;
+}
+/**
+ * A thin, typed client for Coder's experimental `chatd` API. This is a
+ * TypeScript port of the chat surface of `codersdk.ExperimentalClient`.
+ */
+declare class CoderChatClient {
+    #private;
+    readonly baseUrl: string;
+    constructor(options: CoderChatClientOptions);
+    listModelConfigs(signal?: AbortSignal): Promise<ChatModelConfig[]>;
+    createChat(req: CreateChatRequest, signal?: AbortSignal): Promise<Chat>;
+    getChat(chatId: string, signal?: AbortSignal): Promise<Chat>;
+    createChatMessage(chatId: string, req: CreateChatMessageRequest, signal?: AbortSignal): Promise<CreateChatMessageResponse>;
+    getMessages(chatId: string, opts?: {
+        before_id?: number;
+        after_id?: number;
+        limit?: number;
+    }, signal?: AbortSignal): Promise<ChatMessagesResponse>;
+    submitToolResults(chatId: string, req: SubmitToolResultsRequest, signal?: AbortSignal): Promise<void>;
+    interruptChat(chatId: string, signal?: AbortSignal): Promise<Chat>;
+    updateChat(chatId: string, req: UpdateChatRequest, signal?: AbortSignal): Promise<void>;
+    /** Convenience: archive a chat (soft-hide; safe for cleanup). */
+    archiveChat(chatId: string, signal?: AbortSignal): Promise<void>;
+    streamEvents(chatId: string, opts?: {
+        afterId?: number;
+        signal?: AbortSignal;
+    }): AsyncGenerator<ChatStreamEvent, void, void>;
+    /**
+     * Resolves a user-friendly model hint to a model-config UUID.
+     *
+     * Accepts: a config UUID (returned as-is), a `provider:model` id
+     * (e.g. `anthropic:claude-haiku-4-5-20251001`), a bare model id, or a
+     * display-name substring (case-insensitive). Returns `undefined` if no
+     * match is found, in which case the caller should let chatd pick the default.
+     */
+    resolveModelConfigId(hint: string, signal?: AbortSignal): Promise<string | undefined>;
+}
+
+type InnerAgent<TOOLS extends ToolSet> = ToolLoopAgent<never, TOOLS, never>;
+interface CoderAgentSettings<TOOLS extends ToolSet = {}> {
+    /** A pre-built {@link CoderChatClient}. Mutually exclusive with baseUrl/token. */
+    client?: CoderChatClient;
+    /** Coder deployment base URL, e.g. `https://dev.coder.com`. */
+    baseUrl?: string;
+    /** Coder API/session token (sent as `Coder-Session-Token`). */
+    token?: string;
+    fetch?: CoderChatClientOptions["fetch"];
+    webSocketFactory?: CoderChatClientOptions["webSocketFactory"];
+    /** Organization UUID that owns the chat (required). */
+    organizationId: string;
+    /** Model hint: UUID, `provider:model`, model id, or display-name substring. */
+    model?: string;
+    /** Bind the chat to a Coder workspace (enables workspace-scoped tools). */
+    workspaceId?: string;
+    /** chatd-side MCP servers to enable for this chat. */
+    mcpServerIds?: string[];
+    /** chatd plan mode. */
+    planMode?: "" | "plan";
+    /** Resume an existing chat (session) instead of creating a new one. */
+    chatId?: string;
+    /** Stable agent id (exposed as {@link CoderAgent.id}). */
+    id?: string;
+    /** System instructions → chatd `system_prompt`. */
+    instructions?: string | SystemModelMessage | Array<SystemModelMessage>;
+    /** Custom (client-executed) tools. Each should have an `execute` for scripting. */
+    tools?: TOOLS;
+    toolChoice?: ToolChoice<NoInfer<TOOLS>>;
+    /** Stop condition(s) for the AI SDK loop. Default `stepCountIs(64)`. */
+    stopWhen?: StopCondition<NoInfer<TOOLS>> | Array<StopCondition<NoInfer<TOOLS>>>;
+    /**
+     * SDK-level retries. Default `0`: this agent owns server-side chat state, so
+     * SDK retries could duplicate a turn. Override with care.
+     */
+    maxRetries?: number;
+}
+/**
+ * An AI SDK-compliant agent backed by a remote Coder `chatd` agent runtime.
+ *
+ * `new CoderAgent({ ... })` returns an object that implements the AI SDK
+ * `Agent` interface (`generate()`/`stream()`), so it composes with the rest of
+ * the AI SDK ecosystem. Internally it wraps a {@link ToolLoopAgent} whose model
+ * is a {@link CoderLanguageModel}; chatd runs the actual agent loop server-side.
+ *
+ * One `CoderAgent` instance corresponds to one chatd chat ("session"): the chat
+ * is created on the first `generate()`/`stream()` and reused for subsequent
+ * turns. Use {@link CoderAgent.resetSession} to start a fresh chat.
+ */
+declare class CoderAgent<TOOLS extends ToolSet = {}> implements Agent<never, TOOLS, never> {
+    #private;
+    readonly version: "agent-v1";
+    constructor(settings: CoderAgentSettings<TOOLS>);
+    get id(): string | undefined;
+    get tools(): TOOLS;
+    /** The underlying chatd client. */
+    get client(): CoderChatClient;
+    /** The current chatd chat id, once a turn has started. */
+    get chatId(): string | undefined;
+    generate(options: Parameters<InnerAgent<TOOLS>["generate"]>[0]): ReturnType<InnerAgent<TOOLS>["generate"]>;
+    stream(options: Parameters<InnerAgent<TOOLS>["stream"]>[0]): ReturnType<InnerAgent<TOOLS>["stream"]>;
+    /** Start a fresh chatd chat on the next turn. */
+    resetSession(): void;
+    /** Interrupt the in-flight generation, if any. */
+    interrupt(): Promise<void>;
+    /** Archive the underlying chat (safe cleanup; hides it from listings). */
+    archive(): Promise<void>;
+}
+
+interface CoderLanguageModelConfig {
+    client: CoderChatClient;
+    organizationId: string;
+    /** Model hint (UUID, `provider:model`, model id, or display-name substring). */
+    model?: string;
+    /** Bind the chat to a Coder workspace (enables workspace tools). */
+    workspaceId?: string;
+    /** chatd-side MCP servers to enable. */
+    mcpServerIds?: string[];
+    planMode?: "" | "plan";
+    /** Resume an existing chat instead of creating a new one. */
+    chatId?: string;
+}
+/**
+ * A {@link LanguageModelV3} that is backed by a remote Coder `chatd` agent
+ * runtime instead of a raw LLM. One model instance owns one chatd chat
+ * (a "session"): the chat is created lazily on the first turn and reused for
+ * subsequent turns and for client-tool resume steps.
+ *
+ * The chatd server runs the agent loop (model calls, server-side tools,
+ * compaction) itself. This model therefore represents *one chatd segment* per
+ * `doStream` call — it advances the chat until it settles (`waiting`/
+ * `completed`) or pauses for a client tool (`requires_action`). When the AI SDK
+ * executes a client tool and calls `doStream` again with the tool result, this
+ * model resumes the same chat. The two loops mesh at the client-tool boundary.
+ *
+ * NOTE: a single model instance is single-flight — do not run concurrent
+ * generations against the same instance/session.
+ */
+declare class CoderLanguageModel implements LanguageModelV3 {
+    #private;
+    readonly specificationVersion: "v3";
+    readonly provider = "coder.chatd";
+    readonly modelId: string;
+    readonly supportedUrls: Record<string, RegExp[]>;
+    constructor(config: CoderLanguageModelConfig);
+    get chatId(): string | undefined;
+    /** Drops the current session so the next turn creates a fresh chat. */
+    resetSession(): void;
+    doStream(options: LanguageModelV3CallOptions): Promise<LanguageModelV3StreamResult>;
+    doGenerate(options: LanguageModelV3CallOptions): Promise<LanguageModelV3GenerateResult>;
+}
+
+/**
+ * Translates one chatd turn's {@link ChatStreamEvent} stream into a sequence of
+ * `LanguageModelV3StreamPart`s for the AI SDK.
+ *
+ * Two text/reasoning modes, decided per turn from the wire behavior:
+ *  - **delta mode** — chatd streamed `message_part` deltas; we emit those and
+ *    treat the trailing full `message` snapshot as a no-op for text/reasoning.
+ *  - **snapshot mode** — fast turns where only full `message` snapshots arrive;
+ *    we diff each snapshot's full text against what we've already emitted.
+ * Both paths track an emitted-length cursor, so neither double-counts.
+ *
+ * Client (custom) tool calls are emitted from the reliable `action_required`
+ * event and left for the AI SDK to execute. chatd's own server-side tools are
+ * surfaced best-effort as `providerExecuted` tool calls/results.
+ */
+declare class TurnTranslator {
+    #private;
+    constructor(opts: {
+        dynamicToolNames: ReadonlySet<string>;
+    });
+    get terminalStatus(): ChatStatus | undefined;
+    /** Whether a client (custom) tool call has been emitted this turn. */
+    get clientToolCallSeen(): boolean;
+    get maxMessageId(): number;
+    get error(): ChatErrorPayload | undefined;
+    ingest(ev: ChatStreamEvent): LanguageModelV3StreamPart[];
+    finish(): LanguageModelV3StreamPart[];
+}
+
+/** Concatenated system messages, mapped to chatd's `system_prompt`. */
+declare function extractSystemPrompt(prompt: LanguageModelV3Prompt): string | undefined;
+type TurnAction = {
+    kind: "new-turn";
+    content: ChatInputPart[];
+} | {
+    kind: "resume";
+    toolResults: ToolResult[];
+} | {
+    kind: "noop";
+};
+/**
+ * Decides what to do with a fresh `doStream`/`doGenerate` prompt:
+ *  - trailing `tool` message(s) → resume the in-flight chatd turn by submitting
+ *    those tool results (the AI SDK executed a client tool between steps);
+ *  - otherwise the trailing `user` message → a new turn.
+ */
+declare function classifyTurnAction(prompt: LanguageModelV3Prompt): TurnAction;
+/** Maps AI SDK function tools to chatd client-executed ("dynamic") tools. */
+declare function toolsToDynamicTools(tools: LanguageModelV3CallOptions["tools"]): DynamicTool[];
+/** The set of tool names the AI SDK side owns (i.e. client-executed). */
+declare function dynamicToolNames(tools: LanguageModelV3CallOptions["tools"]): Set<string>;
+
+/** Base error for all `@coder/ai-sdk-agent` failures. */
+declare class CoderAgentError extends Error {
+    name: string;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** An HTTP request to the Coder API failed. */
+declare class CoderApiError extends CoderAgentError {
+    name: string;
+    readonly status: number;
+    readonly detail: string | undefined;
+    readonly method: string;
+    readonly path: string;
+    constructor(args: {
+        status: number;
+        method: string;
+        path: string;
+        message: string;
+        detail?: string;
+    });
+}
+/** A chat generation ended in an error status. */
+declare class CoderChatError extends CoderAgentError {
+    name: string;
+    readonly kind: string | undefined;
+    readonly provider: string | undefined;
+    readonly retryable: boolean;
+    readonly statusCode: number | undefined;
+    constructor(payload: ChatErrorPayload);
+}
+
+export { type Chat, type ChatBusyBehavior, type ChatClientType, type ChatErrorPayload, type ChatInputPart, type ChatInputPartType, type ChatMessage, type ChatMessagePart, type ChatMessagePartType, type ChatMessageRole, type ChatMessageUsage, type ChatMessagesResponse, type ChatModelConfig, type ChatPlanMode, type ChatQueuedMessage, type ChatStatus, type ChatStreamActionRequired, type ChatStreamEvent, type ChatStreamEventType, type ChatStreamMessagePart, type ChatStreamRetry, type ChatStreamStatus, type ChatStreamToolCall, CoderAgent, CoderAgentError, type CoderAgentSettings, CoderApiError, CoderChatClient, type CoderChatClientOptions, CoderChatError, CoderLanguageModel, type CoderLanguageModelConfig, type CreateChatMessageRequest, type CreateChatMessageResponse, type CreateChatRequest, type DynamicTool, type SubmitToolResultsRequest, TERMINAL_STATUSES, type ToolResult, type TurnAction, TurnTranslator, type UpdateChatRequest, type WebSocketFactory, type WebSocketLike, classifyTurnAction, dynamicToolNames, extractSystemPrompt, streamChatEvents, toolsToDynamicTools };