@alisio/sdk 0.1.0-alpha.15 → 0.1.0-alpha.17

package/dist/index.d.ts

@@ -1063,7 +1063,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">;
@@ -1154,9 +1154,21 @@ export type ServerFrame = {
     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" | "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"
+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" | "internal";
+ | "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";
@@ -1172,8 +1184,45 @@ export interface HealthInfo {
         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. */
@@ -1184,10 +1233,17 @@ export interface WorkspaceInfo {
     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). */
@@ -1252,6 +1308,27 @@ export interface CommandOutcome {
     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;
@@ -1412,6 +1489,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/package.json

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