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

package/dist/index.d.ts

@@ -103,7 +103,154 @@ export type UiBlock = {
     kind: "progress";
     title?: string;
     steps: ProgressStep[];
+}
+/** A published, downloadable artifact (`ToolContext.artifacts`). Text surfaces show one line. */
+ | {
+    kind: "artifact";
+    artifact: ArtifactRef;
 };
+/** Kind of a published artifact; decides the icon, the label and the renderer. */
+export type ArtifactKind = "dashboard" | "document" | "spreadsheet" | "image" | "data" | "code" | "archive" | "file";
+/** Public reference to a published artifact. Never carries absolute paths. */
+export interface ArtifactRef {
+    /** `art_<ULID>`. */
+    id: string;
+    /** Root session that owns the artifact. */
+    sessionId: string;
+    title: string;
+    /** Download name, e.g. `report.md`, or `site.zip` for a multi-file artifact. */
+    fileName: string;
+    kind: ArtifactKind;
+    mimeType: string;
+    bytes: number;
+    /** More than 1 for multi-file dashboards. */
+    fileCount: number;
+    /** Decided by the host from the artifact kind and size. */
+    previewable: boolean;
+    createdAt: number;
+    /** Published from a failed execution (`publishOnError`). */
+    partial?: boolean;
+    status: "ready" | "deleted" | "expired";
+}
+/** Input of `ArtifactPublisher.publish`: files already written by the caller. */
+export interface ArtifactPublishInput {
+    /** Absolute path of a file or a directory owned by the caller. */
+    source: string;
+    title?: string;
+    /** Entry file for a directory; defaults to `index.html` when present. */
+    entry?: string;
+}
+/** Publishes caller-owned files as downloadable artifacts of the current session. */
+export interface ArtifactPublisher {
+    /** Validates, copies and registers; throws with a user-readable message on rejection. */
+    publish(input: ArtifactPublishInput): Promise<ArtifactRef>;
+    /** Creates a single-file artifact from text the tool already holds. */
+    publishText(input: {
+        fileName: string;
+        title?: string;
+        text: string;
+    }): Promise<ArtifactRef>;
+}
+/** Finer-grained permissions inside an effect (closed union; extended additively). */
+export type AnalysisCapability = "analysis.run" | "analysis.install";
+/**
+ * What an `analysis.install` approval shows (phase 4): the optional Python packages that would be
+ * installed, an estimate of the download and that it needs the network. Always asks, only `once`.
+ */
+export interface InstallPreview {
+    extras: "analysis" | "science";
+    /** Top-level packages, e.g. `pandas`, `numpy`. */
+    packages: string[];
+    /** Pinned distributions in the lockfile (the packages plus their dependencies). */
+    packageCount: number;
+    /** Rough download size (wheels only); an estimate, not a measurement. */
+    estimatedBytes: number;
+    network: true;
+}
+/** What a tool asks the host to approve before installing packages (capability `analysis.install`). */
+export type InstallApprover = (request: InstallPreview) => Promise<"once" | "deny">;
+/** A persisted capability decision as exposed by the web API. */
+export interface CapabilityGrantWire {
+    id: string;
+    capability: AnalysisCapability;
+    sessionId: string;
+    scope: "once" | "session";
+    decision: "allow" | "deny";
+    source: "tui" | "web" | "flag" | "headless-grant";
+    createdAt: number;
+    revokedAt?: number;
+}
+/** Tabular formats the data tools ingest into one SQLite file per dataset. */
+export type DatasetFormat = "csv" | "tsv" | "json" | "jsonl" | "xlsx";
+/** A dataset (a CSV/TSV/JSON/JSONL/XLSX file ingested into SQLite). Never carries paths. */
+export interface DatasetRef {
+    /** `ds_<ULID>`. */
+    id: string;
+    /** Original file name. */
+    name: string;
+    format: DatasetFormat;
+    bytes: number;
+    sha256: string;
+    sheets: Array<{
+        name: string;
+        table: string;
+        rows: number;
+        columns: number;
+    }>;
+}
+/** Column of a dataset table with the statistics computed at ingestion. */
+export interface DatasetColumnWire {
+    name: string;
+    /** Original header text. */
+    label: string;
+    /** A hint (`integer`, `real`, `date`, `boolean`, `text`); values are stored without conversion. */
+    type: string;
+    nulls: number;
+    distinct: number;
+    distinctExact: boolean;
+    min?: string;
+    max?: string;
+    mean?: number;
+    textFallbacks: number;
+    top: Array<{
+        value: string;
+        count: number;
+    }>;
+}
+/** `GET /api/datasets/:did`: the dataset with the schema and statistics of every sheet. */
+export interface DatasetDetailWire extends DatasetRef {
+    ingestVersion: number;
+    encoding?: string;
+    delimiter?: string;
+    sheetDetails: Array<{
+        name: string;
+        table: string;
+        rows: number;
+        columns: DatasetColumnWire[];
+    }>;
+    /** Sorting and filtering are disabled above this many rows (`analysis.data.maxInteractiveRows`). */
+    maxInteractiveRows: number;
+}
+/** `GET /api/datasets/:did/rows`: one page of a sheet (keyset-paginated). */
+export interface DatasetRowsPage {
+    columns: Array<{
+        name: string;
+        label: string;
+        type: string;
+    }>;
+    /** Cell values as stored: numbers stay numbers, everything else is text, empty cells are null. */
+    rows: Array<Array<string | number | null>>;
+    /** 1-based position of the first row in the (unfiltered, unsorted) sheet, per row. */
+    rowids: number[];
+    /** Opaque cursor for the next page; absent on the last page. */
+    next?: string;
+    /** Rows in the sheet. */
+    total: number;
+    /** Rows matching the filter (first page only). */
+    matched?: number;
+    /** Sorting and filtering were ignored because the sheet exceeds `maxInteractiveRows`. */
+    interactive: boolean;
+}
 /** One case of a `{ kind: "test-results" }` UI block. */
 export interface TestCaseResult {
     name: string;
@@ -123,7 +270,7 @@ export interface ProgressStep {
  * 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 declare const UI_BLOCK_KINDS: readonly ["table", "key-value", "tree", "code", "markdown", "diff", "terminal", "mermaid", "math", "json", "test-results", "progress", "artifact"];
 export interface ToolResult {
     content: Array<{
         type: "text";
@@ -167,6 +314,8 @@ export type Message =
     summary?: boolean;
     display?: string;
     attachments?: Attachment[];
+    /** Datasets attached to this prompt (UI chips); the model sees their text summary in `text`. */
+    datasets?: DatasetRef[];
 } | {
     role: "assistant";
     text: string;
@@ -324,6 +473,17 @@ export interface ToolContext {
      * do not inject this fall back to the workspace-only `safePath` policy.
      */
     resolvePath?: (path: string) => Promise<string>;
+    /** Run and tool call that issued this execution, when run by the agent loop. */
+    runId?: string;
+    callId?: string;
+    /** Present when the host has an artifact store for this session (built-in tools only in v1). */
+    artifacts?: ArtifactPublisher;
+    /**
+     * Asks the user to approve installing the optional Python packages (capability
+     * `analysis.install`; built-in tools only). Resolves `deny` where nobody can be asked
+     * (headless, `--read-only`), because no flag grants an installation.
+     */
+    approveInstall?: InstallApprover;
 }
 export interface ToolDefinition {
     name: string;
@@ -334,6 +494,11 @@ export interface ToolDefinition {
     /** May run concurrently with other read/concurrent calls of the same turn (e.g. delegation). */
     concurrent?: boolean;
     paths?: (input: Record<string, unknown>) => string[];
+    /**
+     * Finer-grained permission inside `effect`: a broad grant of `effect` covers it, a grant of the
+     * capability never widens `effect`. Honored for built-in tools only (ignored for plugins in v1).
+     */
+    capability?: AnalysisCapability;
     execute(input: Record<string, unknown>, context: ToolContext): Promise<ToolResult>;
 }
 /**
@@ -411,12 +576,29 @@ export interface RunEventDataMap {
         name: string;
         effect: "write" | "process" | "external";
         label?: string;
+        /** The approval is for this capability (not the whole effect). */
+        capability?: AnalysisCapability;
+        /** `analysis.install` approvals: the packages, the size estimate and the network need. */
+        install?: InstallPreview;
     };
     approval_resolved: {
         id: string;
         name: string;
         effect: "write" | "process" | "external";
         decision: "once" | "session" | "deny";
+        capability?: AnalysisCapability;
+        /** A `session` capability decision was stored and survives restarts. */
+        persisted?: boolean;
+    };
+    /**
+     * A tool published an artifact. `path` is the absolute local path of the file (or the entry of a
+     * multi-file artifact) for local consumers (TUI, JSONL); web clients ignore it.
+     */
+    artifact_published: {
+        artifact: ArtifactRef;
+        path: string;
+        callId?: string;
+        executionId?: string;
     };
     run_completed: {
         tokens: number;
@@ -1041,6 +1223,14 @@ export interface PendingApproval {
     /** Pretty-printed tool input, truncated to 4 KB. */
     input: string;
     expiresAt?: number;
+    /** The approval is for this capability (for example running Python), not the whole effect. */
+    capability?: AnalysisCapability;
+    /** A short preview for capability approvals (the first 40 lines of the script). */
+    preview?: string;
+    /** Capability approvals: `managed` (not sandboxed) or `oci` (container). */
+    runtime?: "managed" | "oci";
+    /** `analysis.install` approvals: only `once` and `deny` are offered. */
+    install?: InstallPreview;
 }
 /** A plugin UI request (`ui.select` / `ui.askQuestions`) waiting for a web client. */
 export interface PendingInteraction {
@@ -1063,7 +1253,7 @@ export interface CommandDescriptor {
     description: string;
     aliases?: string[];
     argumentHint?: string;
-    source: "builtin" | "plugin" | "prompt" | "skill";
+    source: "builtin" | "plugin" | "prompt" | "skill" | "agent";
     /** Plugin id or resource owner, when not built in. */
     owner?: string;
     surfaces: Array<"tui" | "web" | "api">;
@@ -1153,6 +1343,24 @@ export type ServerFrame = {
     t: "resync";
     sessionId?: string;
     reason: "overflow" | "gap" | "server_restart";
+}
+/** A persisted capability grant of this root session was added or revoked. */
+ | {
+    t: "capabilities_changed";
+    sessionId: string;
+}
+/** A dataset uploaded from the web finished ingesting (root session). */
+ | {
+    t: "dataset_ready";
+    sessionId: string;
+    dataset: DatasetRef;
+}
+/** A dataset upload could not be ingested. */
+ | {
+    t: "dataset_failed";
+    sessionId: string;
+    name: string;
+    error: string;
 };
 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). */
@@ -1168,7 +1376,19 @@ export type ApiErrorCode = "unauthorized" | "forbidden_origin" | "forbidden_host
 /** 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";
+ | "cancelled"
+/** The artifact does not exist or belongs to another session (404). */
+ | "artifact_not_found"
+/** The artifact exceeds a size limit for this operation (413). */
+ | "artifact_too_large"
+/** No usable Python runtime (503). */
+ | "runtime_unavailable"
+/** The file is not a supported dataset, or needs a runtime that is missing (415/503 body code). */
+ | "dataset_unsupported"
+/** A data query was rejected by the read-only guard (400). */
+ | "query_rejected"
+/** A data query exceeded `analysis.data.queryTimeoutMs` (408). */
+ | "query_timeout" | "internal";
 /** `GET /api/health` (the only unauthenticated API route). */
 export interface HealthInfo {
     name: "alisio";
@@ -1405,6 +1625,55 @@ export interface McpServerWire {
     };
     diagnostic?: string;
 }
+/**
+ * `GET /api/analysis`: the state of the data-analysis runtime for Settings (read only). Never
+ * carries a script or a repository path; interpreter paths are the user's own.
+ */
+export interface AnalysisStatus {
+    /** `analysis.enabled` and not `--read-only`: python_run is registered. */
+    enabled: boolean;
+    readOnly: boolean;
+    mode: "managed" | "oci";
+    /** The discovered (or `--python`) interpreter and the extras environment. */
+    python: {
+        found: true;
+        path: string;
+        version: string;
+        source: string;
+        extras: string[];
+        runtimeVersion?: string;
+    } | {
+        found: false;
+        reason: string;
+        /** Installation guidance for this system (commands are shown, never run). */
+        hints: {
+            system: string;
+            heading?: string;
+            primary: string;
+            alternatives: string[];
+            notes: string[];
+        };
+    };
+    /** Container settings; `available` is probed only when the mode is `oci` or an image is set. */
+    oci: {
+        engine: "docker" | "podman";
+        image?: string;
+        memoryMb: number;
+        cpus: number;
+        available?: boolean;
+        version?: string;
+        reason?: string;
+    };
+    limits: {
+        timeoutMs: number;
+    };
+    retention: {
+        jobsDays: number;
+        intermediateDays: number;
+        artifactsDays: number;
+        lastSweep?: number;
+    };
+}
 /** `GET /api/mcp`: the workspace's MCP runtime permission and servers. */
 export interface McpOverview {
     permission: "granted" | "not-granted" | "read-only";
@@ -1489,6 +1758,140 @@ export interface ProviderModelsInfo {
     models: ModelInfo[];
     unavailable: boolean;
 }
+/** Output format of an agent's answers (`text.format.type`). */
+export type AgentTextFormatType = "text" | "json_object" | "json_schema";
+/** Reasoning summary preference of an agent (`reasoning.summary`). */
+export type AgentReasoningSummary = "auto" | "none" | "concise" | "detailed";
+/** Answer verbosity preference of an agent (`text.verbosity`). */
+export type AgentVerbosity = "low" | "medium" | "high";
+/**
+ * Where a user agent file lives: `project` is `<workspace>/.agents/agents/<id>.md`, `global` is
+ * `~/.agents/agents/<id>.md`. A project agent overrides a global one with the same id.
+ */
+export type AgentScope = "project" | "global";
+/** Body of `POST /api/agents` and `PUT /api/agents/:id`: a user agent definition. */
+export interface AgentDefinitionInput {
+    /** Display name; the stable id is derived from it once, on creation. */
+    name: string;
+    description?: string;
+    /** System prompt appended to the session instructions when the agent is active. */
+    instructions?: string;
+    /** Model selector (`provider/model` or an unambiguous model id). */
+    model: string;
+    reasoning?: {
+        effort?: string;
+        summary?: AgentReasoningSummary;
+    };
+    text?: {
+        format?: {
+            type: AgentTextFormatType;
+        };
+        verbosity?: AgentVerbosity;
+    };
+}
+/** A stored user agent definition (`GET /api/agents/definitions`). Times are epoch ms. */
+export interface AgentDefinitionInfo extends AgentDefinitionInput {
+    /** File slug: the frontmatter `name` other harnesses use as the agent identifier. */
+    id: string;
+    scope: AgentScope;
+    description: string;
+    instructions: string;
+    /** Absolute path of the Markdown file. */
+    path: string;
+    createdAt: number;
+    updatedAt: number;
+    /** A project agent that takes precedence over the global agent with the same id. */
+    overridesGlobal?: boolean;
+    /** A global agent hidden by the project agent with the same id. */
+    overriddenByProject?: boolean;
+}
+/**
+ * Answer of agent writes. `live`: the running Alisio already uses the change (its agent registry
+ * reloaded and loaded the file); false means it is saved but needs a restart (or a trusted
+ * workspace / the subagents plugin) before sessions can use it.
+ */
+export interface AgentSaveResult {
+    agent: AgentDefinitionInfo;
+    live: boolean;
+}
+/** `GET /api/agents/definitions`: both scopes merged, plus where new agents go by default. */
+export interface AgentDefinitionsOverview {
+    agents: AgentDefinitionInfo[];
+    scopes: AgentScope[];
+    defaultScope: AgentScope;
+    /** Directory of each available scope. */
+    dirs: Partial<Record<AgentScope, string>>;
+    /** Project agents load only in trusted workspaces. */
+    trusted: boolean;
+}
+/** A predefined starting point for a new agent (`GET /api/agents/templates`). */
+export interface AgentTemplateInfo {
+    id: string;
+    name: string;
+    description: string;
+    instructions: string;
+    reasoning?: {
+        effort?: string;
+        summary?: AgentReasoningSummary;
+    };
+    text?: {
+        format?: {
+            type: AgentTextFormatType;
+        };
+        verbosity?: AgentVerbosity;
+    };
+}
+/** What a model supports for the agent editor, derived from its catalog metadata. */
+export interface AgentModelCapabilities {
+    /** The catalog declared any capability metadata; otherwise every option is offered. */
+    known: boolean;
+    reasoning: boolean;
+    /** Reasoning effort levels to offer (empty when reasoning is unsupported). */
+    effortLevels: string[];
+    defaultEffort?: string;
+    summary: boolean;
+    verbosity: boolean;
+    textFormats: AgentTextFormatType[];
+    /** Declared tool calling support; absent when unknown. */
+    tools?: boolean;
+    /** Declared image input support; absent when unknown. */
+    vision?: boolean;
+}
+/** A configured model the agent editor can select (`GET /api/agents/models`). */
+export interface AgentModelOption {
+    /** Canonical selector `<provider>/<model>`. */
+    reference: string;
+    provider: string;
+    profile: string;
+    providerName: string;
+    id: string;
+    name?: string;
+    /** The workspace application runs this model right now. */
+    active: boolean;
+    capabilities: AgentModelCapabilities;
+    /** Short capability labels such as "Reasoning", "Tools", "Vision". */
+    labels: string[];
+}
+/** Answer of `POST /api/agents/draft`: a definition drafted by the active model. */
+export interface AgentDraft {
+    name: string;
+    description: string;
+    instructions: string;
+    reasoning?: {
+        effort?: string;
+        summary?: AgentReasoningSummary;
+    };
+    text?: {
+        format?: {
+            type: AgentTextFormatType;
+        };
+        verbosity?: AgentVerbosity;
+    };
+    /** The model that wrote the draft. */
+    generatedBy: string;
+    /** Authoring guidance used: `skill:<name>` (a discovered skill) or `bundled:create-agent`. */
+    guidance: string;
+}
 /** Body of every non-2xx web API response. */
 export interface ApiError {
     error: {

package/dist/index.js

@@ -16,6 +16,7 @@ export const UI_BLOCK_KINDS = [
     "json",
     "test-results",
     "progress",
+    "artifact",
 ];
 export const EPHEMERAL_RUN_EVENT_TYPES = [
     "text_delta",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alisio/sdk",
-  "version": "0.1.0-alpha.16",
+  "version": "0.1.0-alpha.18",
   "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",