@alisio/sdk 0.1.0-alpha.14 → 0.1.0-alpha.16

package/dist/index.d.ts

@@ -44,7 +44,86 @@ export type UiBlock = {
 } | {
     kind: "markdown";
     text: string;
+}
+/**
+ * A file change: a unified `patch`, or `before`/`after` contents when no patch is available.
+ * Producers bound the payload (about 200 KB).
+ */
+ | {
+    kind: "diff";
+    path?: string;
+    patch?: string;
+    before?: string;
+    after?: string;
+    lang?: string;
+    caption?: string;
+}
+/** Output of a command. `output` may contain ANSI escapes; producers bound it (about 256 KB). */
+ | {
+    kind: "terminal";
+    command?: string;
+    cwd?: string;
+    output: string;
+    exitCode?: number;
+    durationMs?: number;
+    truncated?: boolean;
+}
+/** Mermaid diagram source; text surfaces show the source verbatim. */
+ | {
+    kind: "mermaid";
+    source: string;
+    title?: string;
+}
+/** A LaTeX formula; `display` requests block (not inline) layout. */
+ | {
+    kind: "math";
+    latex: string;
+    display?: boolean;
+}
+/** Any JSON value, shown as a collapsible tree by rich surfaces (bounded to about 256 KB). */
+ | {
+    kind: "json";
+    value: unknown;
+    collapsedDepth?: number;
+    caption?: string;
+}
+/** Test run results grouped by suite. */
+ | {
+    kind: "test-results";
+    framework?: string;
+    durationMs?: number;
+    suites: Array<{
+        name: string;
+        file?: string;
+        cases: TestCaseResult[];
+    }>;
+}
+/** A checklist of steps with their current status. */
+ | {
+    kind: "progress";
+    title?: string;
+    steps: ProgressStep[];
 };
+/** One case of a `{ kind: "test-results" }` UI block. */
+export interface TestCaseResult {
+    name: string;
+    status: "passed" | "failed" | "skipped" | "todo";
+    durationMs?: number;
+    error?: string;
+    line?: number;
+}
+/** One step of a `{ kind: "progress" }` UI block. */
+export interface ProgressStep {
+    label: string;
+    status: "pending" | "running" | "completed" | "failed" | "cancelled";
+    detail?: string;
+}
+/**
+ * Every `UiBlock` kind, for surfaces that dispatch on the kind at runtime (renderer registries,
+ * validators). Surfaces must still render an unknown kind as text: blocks persisted by a newer
+ * Alisio can be replayed by an older one.
+ */
+export declare const UI_BLOCK_KINDS: readonly ["table", "key-value", "tree", "code", "markdown", "diff", "terminal", "mermaid", "math", "json", "test-results", "progress"];
 export interface ToolResult {
     content: Array<{
         type: "text";
@@ -67,7 +146,11 @@ export interface ToolResult {
 export interface Attachment {
     kind: "image";
     mimeType: string;
-    /** Base64-encoded bytes, no `data:` prefix. */
+    /**
+     * Base64-encoded bytes, no `data:` prefix. Required: providers and plugins read it directly,
+     * and no runtime check yet guarantees an alternative source. Content-addressed uploads travel
+     * as `BlobRef` and are resolved to `data` by the host before they reach an `Attachment`.
+     */
     data: string;
     bytes: number;
     width?: number;
@@ -253,15 +336,170 @@ export interface ToolDefinition {
     paths?: (input: Record<string, unknown>) => string[];
     execute(input: Record<string, unknown>, context: ToolContext): Promise<ToolResult>;
 }
+/**
+ * One event of an agent run, as delivered to `onEvent`, plugins and `alisio run --json` (JSONL).
+ * `schemaVersion` stays `1` while changes are additive (new optional fields, new event types);
+ * consumers must ignore unknown fields and unknown `type` values. See `KnownRunEvent` for the
+ * typed payloads of the events the core emits today.
+ */
 export interface RunEvent {
     schemaVersion: 1;
     runId: string;
     sessionId: string;
+    /** Per-run counter starting at 1 (restarts on every run; not unique within a session). */
     seq: number;
     type: string;
     timestamp: string;
     data: unknown;
+    /**
+     * Stable id of a durable event: the persisted global `events.seq`, as a decimal string. Absent
+     * for ephemeral events (`EphemeralRunEventType`) and when the host store does not report it.
+     */
+    eventId?: string;
+    /** Embedder-supplied correlation id (for example an HTTP `X-Request-Id`), when given. */
+    correlationId?: string;
 }
+/**
+ * Payload of each event type the core emits today, keyed by `RunEvent.type`. Additive: new
+ * types and new optional fields may appear; existing fields keep their meaning.
+ */
+export interface RunEventDataMap {
+    run_started: {
+        model: string;
+    };
+    text_delta: {
+        delta: string;
+    };
+    /** Provider-visible reasoning text; display only, never persisted. */
+    reasoning_delta: {
+        delta: string;
+    };
+    turn_completed: {
+        /** 1-based turn number within the run. */
+        turn: number;
+        /** Cumulative input + output tokens of the run so far. */
+        tokens: number;
+        calls: number;
+        model: string;
+        usage?: Usage;
+        /** Milliseconds from sending the provider request to its completed response. */
+        durationMs?: number;
+        /** Milliseconds to the first streamed text/reasoning delta; absent when nothing streamed. */
+        ttftMs?: number;
+    };
+    tool_started: {
+        id: string;
+        name: string;
+        arguments: string;
+        effect: Effect;
+    };
+    /** `data` is whatever the tool passed to `ToolContext.emit`. */
+    tool_progress: {
+        id: string;
+        data: unknown;
+    };
+    tool_completed: {
+        id: string;
+        name: string;
+        isError: boolean;
+        durationMs: number;
+        /** Text projection of the result, capped at 2,000 characters. */
+        preview: string;
+    };
+    approval_requested: {
+        id: string;
+        name: string;
+        effect: "write" | "process" | "external";
+        label?: string;
+    };
+    approval_resolved: {
+        id: string;
+        name: string;
+        effect: "write" | "process" | "external";
+        decision: "once" | "session" | "deny";
+    };
+    run_completed: {
+        tokens: number;
+        text: string;
+        truncated?: boolean;
+    };
+    response_truncated: {
+        turn: number;
+        maxOutputTokens: number;
+    };
+    run_turns_exceeded: {
+        turns: number;
+        maxTurns: number;
+    };
+    run_failed: {
+        error: string;
+    };
+    run_cancelled: {
+        error: string;
+    };
+    model_changed: {
+        model: string;
+        previous: string;
+    };
+    compaction_started: {
+        reason: "manual" | "auto";
+        before: number;
+        messages: number;
+    };
+    compaction_completed: {
+        reason: "manual" | "auto";
+        before: number;
+        after: number;
+        replaced: number;
+        structured: boolean;
+        summarizedTokens: number;
+        checkpointTokens: number;
+        /** Per-plugin `CompactionOutcome.report`, keyed by plugin id. */
+        plugins: Record<string, Record<string, unknown>>;
+        /** The summary hit its output budget and was accepted as partial. */
+        partial?: true;
+    };
+    compaction_skipped: {
+        reason: "manual" | "auto";
+        before: number;
+        detail: string;
+    };
+    compaction_failed: {
+        reason: "manual" | "auto";
+        error: string;
+    };
+    /** Tool results clipped in place to fit the context budget. */
+    context_reduced: {
+        messages: number;
+    };
+    session_context_injected: {
+        tokens: number;
+        sources: string[];
+    };
+    plugin_hook_failed: {
+        source: string;
+        hook: string;
+        error: string;
+        continued: true;
+    };
+}
+/** Every `RunEvent.type` the core emits today. `RunEvent.type` itself stays `string`. */
+export type RunEventType = keyof RunEventDataMap;
+/** Event types never persisted to the session store (and therefore without `eventId`). */
+export type EphemeralRunEventType = "text_delta" | "reasoning_delta" | "tool_progress";
+export declare const EPHEMERAL_RUN_EVENT_TYPES: readonly EphemeralRunEventType[];
+/** True for streaming-only event types that are never persisted. */
+export declare function isEphemeralRunEventType(type: string): type is EphemeralRunEventType;
+/**
+ * Discriminated view of `RunEvent` with typed `data`, for consumers that narrow on `type`.
+ * Every member is assignable to `RunEvent`; events of unknown types remain plain `RunEvent`s.
+ */
+export type KnownRunEvent = {
+    [K in RunEventType]: RunEvent & {
+        type: K;
+        data: RunEventDataMap[K];
+    };
+}[RunEventType];
 /** Generic structured checkpoint produced by core context compaction. */
 export interface CompactionCheckpoint {
     goal: string;
@@ -717,6 +955,549 @@ export interface Plugin {
     setup(api: PluginAPI): void | Promise<void>;
     dispose?(): void | Promise<void>;
 }
+/** Derived status of a root session as shown by web clients (never persisted). */
+export type SessionUiStatus = "idle" | "queued" | "running" | "awaiting_input" | "locked" | "error";
+/** A content-addressed upload (for example an image attached from the web composer). */
+export interface BlobRef {
+    /** Lowercase hex sha256 of the bytes. */
+    hash: string;
+    mimeType: string;
+    bytes: number;
+    width?: number;
+    height?: number;
+}
+/** One entry of `GET /api/workspaces/:wid/tree` (paths are workspace-relative, `/`-separated). */
+export interface FileEntry {
+    name: string;
+    path: string;
+    type: "file" | "dir" | "symlink" | "other";
+    /** Bytes, for files. */
+    size?: number;
+    /** Last modification, ms epoch. */
+    mtime?: number;
+}
+/** A page of a directory listing; `next` is an opaque cursor for the following page. */
+export interface FileTreePage {
+    entries: FileEntry[];
+    next?: string;
+}
+/** A file the session changed (write-effect tool calls), for the Changes dock. */
+export interface SessionChange {
+    path: string;
+    lastRunId?: string;
+    effect: "write";
+    /** `git status --porcelain` code when the workspace is a git repository (`M`, `A`, `D`, `??`…). */
+    gitStatus?: string;
+}
+/** Session metadata carried by snapshot frames. */
+export interface SessionDetailWire {
+    id: string;
+    /** Opaque, stable workspace id (never a filesystem path in URLs). */
+    workspaceId: string;
+    /** Absolute workspace path, for display. */
+    workspace: string;
+    provider: string;
+    model: string;
+    status: SessionUiStatus;
+    title?: string;
+    parentId?: string;
+    /** Persisted child-session status, shown verbatim for child sessions. */
+    childStatus?: SessionStatus;
+    createdAt?: number;
+    updatedAt?: number;
+}
+/** In-flight state of a running run, rebuilt by the server for snapshots. */
+export interface InflightState {
+    runId: string;
+    status: "queued" | "running";
+    /** Assistant text streamed since the last `turn_completed`. */
+    text: string;
+    /** Reasoning streamed since the last `turn_completed` (never persisted). */
+    reasoning: string;
+    tools: Array<{
+        id: string;
+        name: string;
+        arguments: string;
+        effect: Effect;
+        startedAt: number;
+        /** Latest progress output, bounded. */
+        tail: string;
+    }>;
+}
+/** An approval waiting for a decision from a web client. */
+export interface PendingApproval {
+    /** `<sessionId>:<callId>` for tool effects; `<sessionId>:dir:<uuid>` for directories. */
+    approvalId: string;
+    sessionId: string;
+    /** Root of `sessionId`, so child-session approvals show in the root session view. */
+    rootSessionId: string;
+    runId?: string;
+    kind: "effect" | "directory";
+    callId?: string;
+    name?: string;
+    effect?: "write" | "process" | "external";
+    label?: string;
+    directory?: string;
+    /** Pretty-printed tool input, truncated to 4 KB. */
+    input: string;
+    expiresAt?: number;
+}
+/** A plugin UI request (`ui.select` / `ui.askQuestions`) waiting for a web client. */
+export interface PendingInteraction {
+    interactionId: string;
+    /** Present when the request names a session (`AskQuestionsRequest.session`). */
+    sessionId?: string;
+    workspaceId: string;
+    request: {
+        kind: "select";
+        select: SelectRequest;
+    } | {
+        kind: "questions";
+        questions: Question[];
+        label?: string;
+    };
+}
+/** One entry of the shared slash-command catalog. */
+export interface CommandDescriptor {
+    name: string;
+    description: string;
+    aliases?: string[];
+    argumentHint?: string;
+    source: "builtin" | "plugin" | "prompt" | "skill";
+    /** Plugin id or resource owner, when not built in. */
+    owner?: string;
+    surfaces: Array<"tui" | "web" | "api">;
+    /** `core` commands run through the catalog; `surface` commands are handled by each UI. */
+    execution: "core" | "surface";
+}
+/** One JSON object per SSE `data:` line. Clients ignore unknown `t` values. */
+export type ServerFrame = {
+    t: "hello";
+    protocolVersion: 1;
+    streamId: string;
+    serverTime: number;
+} | {
+    t: "snapshot";
+    sessionId: string;
+    /** `MAX(events.seq)` of the session when the snapshot was taken. */
+    cursor: number;
+    session: SessionDetailWire;
+    messages: {
+        items: Array<{
+            seq: number;
+            message: Message;
+            compacted: boolean;
+        }>;
+        hasMore: boolean;
+    };
+    inflight?: InflightState;
+    pending: {
+        approvals: PendingApproval[];
+        interactions: PendingInteraction[];
+    };
+}
+/** Durable event; its SSE `id` is `event.eventId`. */
+ | {
+    t: "event";
+    sessionId: string;
+    event: RunEvent;
+}
+/** Coalesced ephemeral output; carries no SSE `id`. */
+ | {
+    t: "delta";
+    sessionId: string;
+    runId: string;
+    text?: string;
+    reasoning?: string;
+    progress?: Array<{
+        toolId: string;
+        chunk: string;
+    }>;
+} | {
+    t: "tool_result";
+    sessionId: string;
+    runId: string;
+    callId: string;
+    result: ToolResult;
+    truncated?: boolean;
+} | {
+    t: "message";
+    sessionId: string;
+    seq: number;
+    message: Message;
+} | {
+    t: "approval";
+    approval: PendingApproval;
+} | {
+    t: "approval_withdrawn";
+    approvalId: string;
+    reason: "cancelled" | "timeout" | "resolved_elsewhere";
+} | {
+    t: "interaction";
+    interaction: PendingInteraction;
+} | {
+    t: "interaction_withdrawn";
+    interactionId: string;
+} | {
+    t: "session_status";
+    sessionId: string;
+    workspaceId: string;
+    status: SessionUiStatus;
+    title?: string;
+    updatedAt?: number;
+} | {
+    t: "catalog_changed";
+    workspaceId: string;
+    scope: "commands" | "plugins" | "skills" | "mcp" | "models" | "agents";
+} | {
+    t: "resync";
+    sessionId?: string;
+    reason: "overflow" | "gap" | "server_restart";
+};
+export type ApiErrorCode = "unauthorized" | "forbidden_origin" | "forbidden_host" | "validation_failed" | "not_found" | "unknown_command" | "session_busy" | "session_locked" | "workspace_limit"
+/** A known workspace whose folder was deleted, moved or is no longer accessible (404). */
+ | "workspace_missing" | "payload_too_large" | "unsupported_media_type" | "path_outside_workspace" | "not_a_git_repo" | "approval_resolved" | "capability_ceiling" | "not_manageable" | "mcp_not_permitted" | "runs_active" | "provider_unavailable" | "protocol_mismatch" | "shutting_down"
+/** Too many concurrent event streams (SSE) for this server. */
+ | "stream_limit"
+/** The workspace is archived: unarchive it before starting new sessions (409). */
+ | "workspace_archived"
+/** A native folder dialog is already open on the server machine (409). */
+ | "picker_busy"
+/** No native folder dialog / folder browser on this server (remote bind, no desktop) (503). */
+ | "picker_unavailable"
+/** The server user may not read that directory (403). */
+ | "permission_denied"
+/** The request was cancelled before it finished, e.g. a `/btw` side question (409). */
+ | "cancelled" | "internal";
+/** `GET /api/health` (the only unauthenticated API route). */
+export interface HealthInfo {
+    name: "alisio";
+    version: string;
+    protocolVersion: 1;
+    capabilities: {
+        sse: boolean;
+        websocket: boolean;
+        multiWorkspace: boolean;
+        attachments: boolean;
+        uiBlocks: string[];
+        mcpApps: boolean;
+        automation: boolean;
+        /** The server listens on a non-loopback address (`--allow-remote`). */
+        remote: boolean;
+        /**
+         * `POST /api/workspaces/pick` can open a native folder dialog on this machine (loopback only,
+         * with a desktop session and a dialog tool). Absent on older servers.
+         */
+        nativePicker?: boolean;
+        /** `GET /api/fs/dirs` lists directory names for the in-app folder browser (loopback only). */
+        folderBrowser?: boolean;
+    };
+}
+/** `POST /api/workspaces/pick`: the folder chosen in the native dialog, or a cancellation. */
+export type FolderPickResult = {
+    path: string;
+} | {
+    cancelled: true;
+};
+/** One page of the in-app folder browser (`GET /api/fs/dirs`): subdirectory names only. */
+export interface DirectoryListing {
+    /** Absolute path listed (the server's own separators; `""` for the drive list on Windows). */
+    path: string;
+    /** Parent directory, absent at a filesystem root (and at the drive list). */
+    parent?: string;
+    /** Breadcrumbs from the root to `path`, built by the server (no separator assumptions). */
+    segments: Array<{
+        name: string;
+        path: string;
+    }>;
+    /** Subdirectories (names and absolute paths; never files, never contents). */
+    entries: Array<{
+        name: string;
+        path: string;
+        hidden: boolean;
+    }>;
+    /** The server user's home directory (where browsing starts). */
+    home: string;
+    /** Path separator of the server platform. */
+    separator: "/" | "\\";
+    /** More than the listing cap: the rest is not shown. */
+    truncated?: boolean;
+}
+/** A workspace known to the server (`GET /api/workspaces`). */
+export interface WorkspaceInfo {
+    /** Opaque, stable id: a short sha256 of the canonical path. */
+    id: string;
+    /** Canonical absolute path (display only; URLs use `id`). */
+    path: string;
+    label?: string;
+    pinned: boolean;
+    /** An `Application` is open for it in the server right now. */
+    open: boolean;
+    /**
+     * The folder is still an accessible directory. A workspace known from old sessions may have been
+     * deleted or moved: its sessions stay readable, but it cannot be opened (`workspace_missing`).
+     */
+    exists: boolean;
+    /** Project resources load (trusted from the terminal or by a launch flag). */
+    trusted: boolean;
+    /** The directory has project resources that are not trusted (shown as "untrusted"). */
+    untrustedResources: boolean;
+    /** Archived: hidden from the default list; its sessions stay readable, new ones are refused. */
+    archived: boolean;
+    lastOpenedAt?: number;
+}
+/** Permission presets of the web composer (RF-08). */
+export type PermissionPresetId = "read-only" | "ask" | "workspace-write" | "full-access";
+export interface PermissionPresetInfo {
+    id: PermissionPresetId;
+    /** Selectable under the server's launch flags (its capability ceiling). */
+    available: boolean;
+    /** Why it is unavailable, or which effects still ask because of the ceiling. */
+    reason?: string;
+    /** Effects allowed without asking once the ceiling is applied. */
+    policy: {
+        write: boolean;
+        process: boolean;
+        external: boolean;
+    };
+    /** Whether non-allowed effects ask for approval (false: they are denied). */
+    approvals: boolean;
+}
+/** A row of the session list (`GET /api/sessions`). */
+export interface SessionSummary extends SessionDetailWire {
+    pinned: boolean;
+    archived: boolean;
+}
+/** `GET /api/sessions/:sid` and the result of creating or patching a session. */
+export interface SessionDetail extends SessionSummary {
+    preset: PermissionPresetId;
+    effort?: string;
+    agent?: string;
+    presets: PermissionPresetInfo[];
+    children: SessionDetailWire[];
+}
+/** Answer of `POST /api/sessions/:sid/prompts`. */
+export type PromptAccepted = {
+    runId: string;
+    status: "queued" | "running";
+    duplicate?: false;
+} | {
+    runId: string;
+    status: string;
+    duplicate: true;
+} | {
+    status: "enqueued";
+    duplicate?: boolean;
+};
+/**
+ * Answer of `POST /api/sessions/:sid/commands`. A command either reports (`output`, Markdown),
+ * points the client at another session (`/clear`, `/resume`) or expands into a prompt the client
+ * sends through `POST .../prompts` (prompt templates, skills, `/ask`). A repeated `requestId`
+ * answers `{duplicate: true}` without running the command again.
+ */
+export interface CommandOutcome {
+    output?: string;
+    /** `notice` is a short status line; `info` (default) a report. */
+    tone?: "info" | "notice";
+    sessionId?: string;
+    prompt?: {
+        text: string;
+        display: string;
+    };
+    /** What changed, e.g. `"model"` or `"effort"`, so clients refresh the session. */
+    effects?: string[];
+    duplicate?: boolean;
+}
+/**
+ * One `/btw` side question: a tool-less question about a session answered outside its
+ * conversation (never persisted as messages, events, runs or session usage). Answer of
+ * `POST /api/sessions/:sid/btw`; `GET /api/sessions/:sid/btw` lists them, oldest first.
+ */
+export interface SideQuestionEntry {
+    id: string;
+    question: string;
+    /** Markdown answer. */
+    answer: string;
+    /** Model that answered (the session's model at the time). */
+    model: string;
+    usage: {
+        input: number;
+        output: number;
+    };
+    /** Epoch milliseconds. */
+    createdAt: number;
+    /** The provider cut the answer at the output-token budget. */
+    truncated?: boolean;
+}
+/** `GET /api/sessions/:sid/models`: models of the session's provider (credential-free). */
+export interface SessionModels {
+    provider: string;
+    model: string;
+    /** Session reasoning effort, when set. */
+    effort?: string;
+    models: ModelInfo[];
+    /** The provider could not list its models (the current model still works). */
+    unavailable: boolean;
+}
+/** `GET /api/sessions/:sid/context`: estimated tokens of the next request and the budget. */
+export interface SessionContextUsage {
+    estimated: number;
+    /** Model context window, when known. */
+    total?: number;
+    basis: "window" | "unknown";
+    /** Percentage of `total` at which auto-compaction triggers. */
+    compactionAt: number;
+}
+/** `GET /api/plugins`: one plugin of a workspace (credential- and path-safe). */
+export interface PluginInfo {
+    id: string;
+    name: string;
+    description: string;
+    version?: string;
+    categories: string[];
+    builtin: boolean;
+    source: string;
+    status: "active" | "inactive" | "failed" | "restart-required";
+    enabled: boolean;
+    /** Whether the web may toggle it (else `diagnostic` says why). */
+    manageable: boolean;
+    diagnostic?: string;
+    /** Tools it contributes, without the namespacing prefix. */
+    tools: string[];
+    /** Slash commands it contributes. */
+    commands: string[];
+    /** Prefix of its namespaced tool names (`p_<hash>`), to label tool calls. */
+    toolPrefix: string;
+}
+/** `GET /api/skills`: one discovered skill (no file paths). */
+export interface SkillInfo {
+    id: string;
+    name: string;
+    displayId: string;
+    description: string;
+    scope: "project" | "config" | "user" | "plugin";
+    source: string;
+    owner?: {
+        id: string;
+        name: string;
+    };
+    manageable: boolean;
+    locked: boolean;
+    enabled: boolean;
+    effective: boolean;
+    shadowedBy?: string;
+    approximateTokens: number;
+}
+/** One MCP server of a workspace; commands, arguments and URLs are never sent. */
+export interface McpServerWire {
+    name: string;
+    displayName: string;
+    /** Configuration layer that defines it (`global`, `project`, …). */
+    source: string;
+    status: string;
+    enabled: boolean;
+    transport: "stdio" | "http";
+    capabilities: string[];
+    counts: {
+        tools: number;
+        resources: number;
+        prompts: number;
+    };
+    diagnostic?: string;
+}
+/** `GET /api/mcp`: the workspace's MCP runtime permission and servers. */
+export interface McpOverview {
+    permission: "granted" | "not-granted" | "read-only";
+    /** Global consent (`mcp.allow`) is persisted for this user. */
+    persisted: boolean;
+    servers: McpServerWire[];
+}
+/** `GET /api/agents`: a selectable main-session agent. */
+export interface AgentInfo {
+    id: string;
+    name: string;
+    description: string;
+    instructions?: string;
+    model?: string;
+    readOnly?: boolean;
+    source: "builtin" | "user" | "plugin";
+    /** The workspace default (`agents.active`) used by sessions without their own agent. */
+    default: boolean;
+}
+/** One user-facing setting (`SettableSettingKey`) and its effective value. */
+export interface SettingInfo {
+    key: string;
+    kind: "boolean" | "number" | "string" | "enum";
+    options?: string[];
+    value?: string | number | boolean;
+}
+/** `GET /api/settings`: effective settings and where configuration lives. */
+export interface SettingsOverview {
+    /** Highest-priority configuration file of the workspace (it may not exist yet). */
+    configPath: string;
+    /** Global file that setting changes are written to. */
+    settingsPath: string;
+    /** Provider profiles (`providers.json`); credentials live apart, never shown. */
+    providersPath: string;
+    trusted: boolean;
+    readOnly: boolean;
+    settings: SettingInfo[];
+}
+/** A credential as the web sees it: never the value, at most a short masked tail. */
+export interface CredentialStatus {
+    configured: boolean;
+    source?: "file" | "env";
+    /** Last characters behind an ellipsis (`…71B`), only for long stored secrets. */
+    tail?: string;
+}
+/** One stored provider profile (non-secret values only). */
+export interface ProviderProfileInfo {
+    name: string;
+    provider: string;
+    model: string;
+    values: Record<string, ProviderConfigurationValue>;
+    /** The globally active profile (`providers.json`). */
+    active: boolean;
+    credentials: Record<string, CredentialStatus>;
+}
+/** A provider type a profile can use, with its configuration fields. */
+export interface ProviderTypeInfo {
+    id: string;
+    name: string;
+    description?: string;
+    fields: ProviderConfigurationField[];
+}
+/** `GET /api/providers`. */
+export interface ProvidersOverview {
+    active?: string;
+    profiles: ProviderProfileInfo[];
+    /** Provider types of the requested workspace (empty without `?workspace=`). */
+    types: ProviderTypeInfo[];
+    /** What the requested workspace's application currently runs. */
+    current?: {
+        provider: string;
+        model: string;
+        profile?: string;
+    };
+}
+/** `GET /api/models`: models of every configured profile (credential-free). */
+export interface ProviderModelsInfo {
+    profile: string;
+    provider: string;
+    title: string;
+    configuredModel: string;
+    models: ModelInfo[];
+    unavailable: boolean;
+}
+/** Body of every non-2xx web API response. */
+export interface ApiError {
+    error: {
+        code: ApiErrorCode;
+        message: string;
+        details?: unknown;
+    };
+    correlationId: string;
+}
 export declare function definePlugin<T extends Plugin>(plugin: T): T;
 export declare const textResult: (text: string, isError?: boolean) => ToolResult;
 /**

package/dist/index.js

@@ -1,3 +1,31 @@
+/**
+ * Every `UiBlock` kind, for surfaces that dispatch on the kind at runtime (renderer registries,
+ * validators). Surfaces must still render an unknown kind as text: blocks persisted by a newer
+ * Alisio can be replayed by an older one.
+ */
+export const UI_BLOCK_KINDS = [
+    "table",
+    "key-value",
+    "tree",
+    "code",
+    "markdown",
+    "diff",
+    "terminal",
+    "mermaid",
+    "math",
+    "json",
+    "test-results",
+    "progress",
+];
+export const EPHEMERAL_RUN_EVENT_TYPES = [
+    "text_delta",
+    "reasoning_delta",
+    "tool_progress",
+];
+/** True for streaming-only event types that are never persisted. */
+export function isEphemeralRunEventType(type) {
+    return EPHEMERAL_RUN_EVENT_TYPES.includes(type);
+}
 export function definePlugin(plugin) {
     return plugin;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alisio/sdk",
-  "version": "0.1.0-alpha.14",
+  "version": "0.1.0-alpha.16",
   "description": "Typed plugin SDK for Alisio: the stable contract for tools, commands, context, compaction and session hooks, model completions and storage. Types only plus tiny helpers; zero runtime dependencies.",
   "author": "Gustavo Gutiérrez",
   "license": "MIT",