@alisio/core 0.1.0-alpha.8 → 0.1.0

package/dist/mcp/rich.js

@@ -0,0 +1,362 @@
+/**
+ * MCP → Alisio result mapping ("Nivel 0" rich tool results).
+ *
+ * MCP protocol types never leak into the SDK: this adapter is the single place that folds an
+ * MCP `CallToolResult` / `ReadResourceResult` into the Alisio-owned `ToolResult` content union
+ * (text, image, ui blocks). Mapping is heuristic and conservative:
+ *
+ * - `text` parts stay text parts; an image part becomes `{type:"image"}` (base64 data + mime).
+ * - `structuredContent` (or a JSON-parseable text part) is folded into a `ui` block when it
+ *   matches a verified shape — `{columns,rows}` / `{headers,rows}` tables, all-scalar
+ *   key-value objects, or `{nodes:[{label,children,meta}]}` trees. Anything else stays text
+ *   (the previous flattening).
+ * - A canonical text projection of every ui block / image is ALWAYS appended as a text part so
+ *   providers, compaction and headless output only see text.
+ * - Unknown call results (no contents, nothing recognized) keep the previous
+ *   `JSON.stringify(result)` behavior verbatim.
+ */
+import { textResult } from "@alisio/sdk";
+import { stripAnsi } from "../startup/text.js";
+const scalar = (value) => typeof value === "string"
+    ? value
+    : typeof value === "number" || typeof value === "boolean" || value === null
+        ? String(value)
+        : undefined;
+/** Cell rendering: scalars verbatim, nested values compact-JSON'd (never raw bytes). */
+const cellText = (value) => typeof value === "string"
+    ? value
+    : value === null || value === undefined
+        ? ""
+        : typeof value === "object"
+            ? JSON.stringify(value)
+            : String(value);
+function tableShape(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const record = value;
+    const columnsRaw = Array.isArray(record.columns)
+        ? record.columns
+        : Array.isArray(record.headers)
+            ? record.headers
+            : undefined;
+    const rowsRaw = Array.isArray(record.rows) ? record.rows : undefined;
+    if (!columnsRaw || !rowsRaw)
+        return undefined;
+    const columns = [];
+    for (const column of columnsRaw) {
+        const text = scalar(column);
+        if (text === undefined)
+            return undefined;
+        columns.push(text);
+    }
+    const rows = [];
+    for (const row of rowsRaw) {
+        if (!row || typeof row !== "object")
+            return undefined;
+        if (Array.isArray(row)) {
+            rows.push(row.map(cellText));
+            continue;
+        }
+        // Object rows are keyed by the declared columns (`{columns, rows:[{a:1,b:2}]}`).
+        const named = row;
+        rows.push(columns.map((column) => cellText(named[column])));
+    }
+    if (!columns.length || !rows.length)
+        return undefined;
+    return { kind: "table", columns, rows };
+}
+function treeNode(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const record = value;
+    const label = scalar(record.label) ?? scalar(record.name);
+    if (label === undefined)
+        return undefined;
+    const meta = scalar(record.meta) ?? scalar(record.value) ?? scalar(record.detail);
+    const node = { label };
+    if (meta !== undefined && meta !== label)
+        node.meta = meta;
+    const children = Array.isArray(record.children) ? record.children : undefined;
+    if (children) {
+        const mapped = [];
+        for (const child of children) {
+            const next = treeNode(child);
+            if (!next)
+                return undefined;
+            mapped.push(next);
+        }
+        node.children = mapped;
+    }
+    return node;
+}
+function treeShape(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const record = value;
+    const nodes = Array.isArray(record.nodes)
+        ? record.nodes
+        : record.tree !== undefined && typeof record.tree === "object" && !Array.isArray(record.tree)
+            ? [record.tree]
+            : undefined;
+    if (!nodes)
+        return undefined;
+    const mapped = [];
+    for (const node of nodes) {
+        const next = treeNode(node);
+        if (!next)
+            return undefined;
+        mapped.push(next);
+    }
+    return mapped.length ? { kind: "tree", nodes: mapped } : undefined;
+}
+function keyValueShape(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const record = value;
+    const entries = Object.entries(record);
+    if (!entries.length || entries.some(([, v]) => typeof v === "object" && v !== null))
+        return undefined;
+    return { kind: "key-value", entries: entries.map(([key, v]) => [key, String(v)]) };
+}
+/**
+ * Folds a candidate value into a UiBlock when it matches one of the verified shapes:
+ * `{columns,rows}` / `{headers,rows}` tables, `{nodes:[...]}` trees, or flat scalar objects.
+ */
+export function blockFromUnknown(value) {
+    return tableShape(value) ?? treeShape(value) ?? keyValueShape(value);
+}
+/** Tries a JSON-parseable text part: recognized shapes become ui blocks, everything else stays text. */
+export function blockFromJsonText(text) {
+    const trimmed = text.trim();
+    if (!trimmed.startsWith("{"))
+        return undefined;
+    try {
+        return blockFromUnknown(JSON.parse(trimmed));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Compact plain-text rendering of a ui block, used as the canonical model-visible projection. */
+export function renderUiBlockText(block) {
+    switch (block.kind) {
+        case "table": {
+            const head = `| ${block.columns.join(" | ")} |`;
+            const sep = `| ${block.columns.map(() => "---").join(" | ")} |`;
+            const rows = block.rows.map((row) => `| ${row.join(" | ")} |`);
+            return [block.caption ? `[table: ${block.caption}]` : "", head, sep, ...rows]
+                .filter((line) => line !== "")
+                .join("\n");
+        }
+        case "key-value":
+            return [
+                block.caption ? `[key-value: ${block.caption}]` : "",
+                ...block.entries.map(([key, value]) => `${key}: ${value}`),
+            ]
+                .filter((line) => line !== "")
+                .join("\n");
+        case "tree": {
+            const lines = [];
+            const walk = (nodes, prefix) => {
+                nodes.forEach((node, index) => {
+                    const last = index === nodes.length - 1;
+                    lines.push(`${prefix}${last ? "└─ " : "├─ "}${node.label}${node.meta ? ` (${node.meta})` : ""}`);
+                    if (node.children?.length)
+                        walk(node.children, `${prefix}${last ? "   " : "│  "}`);
+                });
+            };
+            walk(block.nodes, "");
+            return lines.join("\n");
+        }
+        case "code": {
+            const fence = "```";
+            const lang = block.lang ? `${block.lang}\n` : "\n";
+            const body = block.code.endsWith("\n") ? block.code : `${block.code}\n`;
+            return [block.caption ? `[code: ${block.caption}]` : "", `${fence}${lang}${body}${fence}`]
+                .filter((line) => line !== "")
+                .join("\n");
+        }
+        case "markdown":
+            return block.text;
+        case "diff": {
+            const label = [block.caption, block.path].filter(Boolean).join(" · ");
+            const head = label ? `[diff: ${label}]` : "[diff]";
+            if (block.patch !== undefined)
+                return `${head}\n${fenced(block.patch, "diff")}`;
+            return [
+                head,
+                `before:\n${fenced(block.before ?? "", block.lang)}`,
+                `after:\n${fenced(block.after ?? "", block.lang)}`,
+            ].join("\n");
+        }
+        case "terminal": {
+            const status = [
+                block.exitCode !== undefined ? `exit ${block.exitCode}` : "",
+                block.durationMs !== undefined ? `${block.durationMs}ms` : "",
+                block.truncated ? "output truncated" : "",
+            ]
+                .filter(Boolean)
+                .join(" · ");
+            return [
+                block.command ? `$ ${block.command}` : "[terminal]",
+                fenced(stripAnsi(block.output)),
+                status,
+            ]
+                .filter((line) => line !== "")
+                .join("\n");
+        }
+        case "mermaid":
+            return [block.title ? `[mermaid: ${block.title}]` : "", fenced(block.source, "mermaid")]
+                .filter((line) => line !== "")
+                .join("\n");
+        case "math":
+            return block.display ? `$$\n${block.latex}\n$$` : `$${block.latex}$`;
+        case "json":
+            return [
+                block.caption ? `[json: ${block.caption}]` : "",
+                fenced(jsonText(block.value), "json"),
+            ]
+                .filter((line) => line !== "")
+                .join("\n");
+        case "test-results": {
+            const cases = block.suites.flatMap((suite) => suite.cases.map((c) => `${c.status.toUpperCase()} ${suite.name} › ${c.name}${c.error ? `: ${c.error}` : ""}`));
+            return [`[test-results${block.framework ? `: ${block.framework}` : ""}]`, ...cases].join("\n");
+        }
+        case "progress":
+            return [
+                block.title ? `[progress: ${block.title}]` : "[progress]",
+                ...block.steps.map((step) => `- [${step.status}] ${step.label}${step.detail ? ` (${step.detail})` : ""}`),
+            ].join("\n");
+        case "artifact": {
+            const a = block.artifact;
+            return `[artifact: ${a.fileName} · ${a.kind} · ${a.bytes} bytes · ${a.id}${a.partial ? " · partial" : ""}${a.status !== "ready" ? ` · ${a.status}` : ""}]`;
+        }
+        default: {
+            // A kind this build does not know (e.g. persisted by a newer Alisio): keep it readable.
+            const kind = String(block.kind ?? "unknown");
+            return `[ui block: ${kind}]\n${fenced(jsonText(block), "json")}`;
+        }
+    }
+}
+function fenced(text, lang) {
+    const body = text.endsWith("\n") ? text : `${text}\n`;
+    return `\`\`\`${lang ?? ""}\n${body}\`\`\``;
+}
+/** `JSON.stringify` that never throws and never returns `undefined`. */
+function jsonText(value) {
+    try {
+        return JSON.stringify(value, null, 2) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+const base64Bytes = (data) => Math.floor((data.length * 3) / 4);
+const projectionText = (parts) => parts
+    .map((part) => part.type === "ui"
+    ? renderUiBlockText(part.block)
+    : `[image: ${part.mimeType} (${base64Bytes(part.data)} bytes)]`)
+    .join("\n");
+/**
+ * Maps an MCP `CallToolResult` into an Alisio `ToolResult`. Text/image parts map directly;
+ * verified table/key-value/tree shapes (from `structuredContent` or JSON text parts) become
+ * `ui` blocks; a canonical text projection is always appended when non-text parts exist, and
+ * unrecognized results keep the previous `JSON.stringify` flattening verbatim.
+ */
+export function mapMcpCallResult(result) {
+    const raw = (result ?? {});
+    const parts = Array.isArray(raw.content) ? raw.content : [];
+    if (!parts.length && raw.structuredContent === undefined)
+        return textResult(JSON.stringify(result), raw.isError === true);
+    const content = [];
+    const rich = [];
+    const keepSourceOrder = (part) => {
+        rich.push(part);
+        content.push(part);
+    };
+    for (const part of parts) {
+        if (!part || typeof part !== "object")
+            continue;
+        const record = part;
+        const type = record.type;
+        if (type === "text") {
+            const text = typeof record.text === "string" ? record.text : JSON.stringify(record.text ?? "");
+            const block = blockFromJsonText(text);
+            if (block)
+                keepSourceOrder({ type: "ui", block });
+            else
+                content.push({ type: "text", text });
+        }
+        else if (type === "image") {
+            const data = typeof record.data === "string" ? record.data : "";
+            if (data)
+                keepSourceOrder({
+                    type: "image",
+                    mimeType: typeof record.mimeType === "string" ? record.mimeType : "application/octet-stream",
+                    data,
+                });
+        }
+        else {
+            // Audio / embedded resource / unknown part: never forward raw bytes; a marker keeps the model informed.
+            content.push({ type: "text", text: `[mcp part: ${type}]` });
+        }
+    }
+    const structured = blockFromUnknown(raw.structuredContent);
+    if (structured)
+        keepSourceOrder({ type: "ui", block: structured });
+    if (rich.length)
+        content.push({ type: "text", text: projectionText(rich) });
+    if (!content.length)
+        return textResult(JSON.stringify(result), raw.isError === true);
+    return { content, ...(raw.isError === true ? { isError: true } : {}) };
+}
+/**
+ * Maps an MCP `ReadResourceResult` / `ListResourcesResult` into an Alisio `ToolResult`.
+ * Text contents map to text parts; image blobs become `{type:"image"}` parts; non-image blobs
+ * become a text marker (never raw base64 in the model prompt). Results without contents (a
+ * resource listing, for example) keep the previous `JSON.stringify` flattening.
+ */
+export function mapMcpResourceResult(result) {
+    const raw = (result ?? {});
+    const contents = Array.isArray(raw.contents) ? raw.contents : [];
+    if (!contents.length)
+        return textResult(JSON.stringify(result), typeof result === "object" &&
+            result !== null &&
+            result.isError === true);
+    const content = [];
+    const rich = [];
+    for (const item of contents) {
+        if (!item || typeof item !== "object")
+            continue;
+        const record = item;
+        const mimeType = typeof record.mimeType === "string" ? record.mimeType : "application/octet-stream";
+        if (typeof record.text === "string") {
+            const block = blockFromJsonText(record.text);
+            if (block) {
+                rich.push({ type: "ui", block });
+                content.push({ type: "ui", block });
+            }
+            else
+                content.push({ type: "text", text: record.text });
+        }
+        else if (typeof record.blob === "string") {
+            if (mimeType.startsWith("image/")) {
+                const image = { type: "image", mimeType, data: record.blob };
+                rich.push(image);
+                content.push(image);
+            }
+            else
+                content.push({
+                    type: "text",
+                    text: `[resource blob: ${mimeType} (${base64Bytes(record.blob)} bytes)]`,
+                });
+        }
+    }
+    if (rich.length)
+        content.push({ type: "text", text: projectionText(rich) });
+    if (!content.length)
+        return textResult(JSON.stringify(result), typeof result === "object" &&
+            result !== null &&
+            result.isError === true);
+    return { content };
+}

package/dist/permissions/modes.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Permission modes (`ask`, `auto`, `full`): the ONE table that maps a mode to the runner policy,
+ * shared by the TUI (`/permission`) and the web presets (`host/presets.ts`). Pure: no I/O.
+ *
+ * A mode only decides which EFFECTS run without asking. It is not a sandbox and it does not change
+ * path confinement (`PathAccess` still asks per external directory) or the `analysis` pre-grant.
+ */
+import type { PermissionMode, PermissionPresetId } from "@alisio/sdk";
+import type { Policy } from "../core/contracts.ts";
+export type { PermissionMode };
+export declare const PERMISSION_MODES: readonly PermissionMode[];
+/** The effects a mode lets run without asking. `analysis` is never part of a mode. */
+export type ModePolicy = Pick<Policy, "write" | "process" | "external">;
+export interface PermissionModeSpec {
+    /** Effects allowed without asking; the rest ask (or are denied when `approvals` is false). */
+    policy: ModePolicy;
+    /** Whether the effects that are not allowed ask for approval. */
+    approvals: boolean;
+    /** The web preset that implements this mode. */
+    preset: Exclude<PermissionPresetId, "read-only">;
+    label: string;
+    summary: string;
+}
+/** The single mapping table (decision P3). Auto = fixed rules, no model classifier. */
+export declare const PERMISSION_MODE_TABLE: Readonly<Record<PermissionMode, PermissionModeSpec>>;
+/** The read-only preset: nothing runs and nothing can be approved. Not selectable as a mode. */
+export declare const READ_ONLY_POLICY: ModePolicy;
+export declare const FULL_ACCESS_WARNING = "Full access: writes, commands and network calls run without asking. This is not a sandbox: anything the agent runs has your user's permissions.";
+export declare const PERMISSION_MODES_LOCKED = "Permission modes are locked: Alisio was started with --read-only.";
+export declare const PERMISSION_USAGE = "Usage: /permission [ask|auto|full|status]";
+/** The mode a web preset implements; `read-only` has none. */
+export declare function presetToMode(preset: PermissionPresetId): PermissionMode | undefined;
+/** The web preset of a mode. */
+export declare function modeToPreset(mode: PermissionMode): PermissionPresetId;
+/** `ask`, `auto` or `full` (also the preset spellings `full-access` and `workspace-write`). */
+export declare function parsePermissionMode(text: string): PermissionMode | undefined;
+export type PermissionCommand = {
+    type: "menu";
+} | {
+    type: "status";
+} | {
+    type: "set";
+    mode: PermissionMode;
+} | {
+    type: "invalid";
+    input: string;
+};
+/** Parses the arguments of `/permission` (`ask|auto|full|status`; none opens the menu). */
+export declare function parsePermissionCommand(args: string): PermissionCommand;
+/** What a TUI shows for its mode: a real mode, a flag combination that matches none, or locked. */
+export type PermissionModeLabel = PermissionMode | "custom" | "locked";
+export interface ModeFlags {
+    allowWrite?: boolean;
+    allowProcess?: boolean;
+    allowExternal?: boolean;
+    readOnly?: boolean;
+}
+/**
+ * The initial mode label of a TUI process from its launch flags: `--read-only` is locked, no flags
+ * is `ask`, `--allow-write` alone is `auto`, the three allow flags are `full`, anything else is
+ * `custom`. It only LABELS the state: no policy is applied at startup.
+ */
+export declare function modeFromFlags(flags: ModeFlags): PermissionModeLabel;
+export type EffectState = "on" | "ask" | "off";
+/** How one effect behaves under a policy: runs, asks, or is denied. */
+export declare function effectState(allowed: boolean, approvals: boolean): EffectState;
+/** Markdown status of the permission state of a session (shared wording for TUI and API callers). */
+export declare function describePermissionStatus(input: {
+    mode: PermissionModeLabel;
+    policy: Readonly<Policy>;
+    approvals: boolean;
+}): string;

package/dist/permissions/modes.js

@@ -0,0 +1,98 @@
+export const PERMISSION_MODES = ["ask", "auto", "full"];
+/** The single mapping table (decision P3). Auto = fixed rules, no model classifier. */
+export const PERMISSION_MODE_TABLE = {
+    ask: {
+        policy: { write: false, process: false, external: false },
+        approvals: true,
+        preset: "ask",
+        label: "Ask",
+        summary: "Every write, command and network call asks first.",
+    },
+    auto: {
+        policy: { write: true, process: false, external: false },
+        approvals: true,
+        preset: "workspace-write",
+        label: "Auto",
+        summary: "File edits inside the workspace run without asking; commands, network calls and external directories still ask.",
+    },
+    full: {
+        policy: { write: true, process: true, external: true },
+        approvals: true,
+        preset: "full-access",
+        label: "Full access",
+        summary: "Writes, commands and network calls run without asking.",
+    },
+};
+/** The read-only preset: nothing runs and nothing can be approved. Not selectable as a mode. */
+export const READ_ONLY_POLICY = { write: false, process: false, external: false };
+export const FULL_ACCESS_WARNING = "Full access: writes, commands and network calls run without asking. This is not a sandbox: anything the agent runs has your user's permissions.";
+export const PERMISSION_MODES_LOCKED = "Permission modes are locked: Alisio was started with --read-only.";
+export const PERMISSION_USAGE = "Usage: /permission [ask|auto|full|status]";
+/** The mode a web preset implements; `read-only` has none. */
+export function presetToMode(preset) {
+    return PERMISSION_MODES.find((mode) => PERMISSION_MODE_TABLE[mode].preset === preset);
+}
+/** The web preset of a mode. */
+export function modeToPreset(mode) {
+    return PERMISSION_MODE_TABLE[mode].preset;
+}
+/** `ask`, `auto` or `full` (also the preset spellings `full-access` and `workspace-write`). */
+export function parsePermissionMode(text) {
+    const value = text.trim().toLowerCase();
+    if (value === "full-access")
+        return "full";
+    if (value === "workspace-write")
+        return "auto";
+    return PERMISSION_MODES.find((mode) => mode === value);
+}
+/** Parses the arguments of `/permission` (`ask|auto|full|status`; none opens the menu). */
+export function parsePermissionCommand(args) {
+    const text = args.trim().toLowerCase();
+    if (!text)
+        return { type: "menu" };
+    if (text === "status")
+        return { type: "status" };
+    const mode = parsePermissionMode(text);
+    return mode ? { type: "set", mode } : { type: "invalid", input: args.trim() };
+}
+/**
+ * The initial mode label of a TUI process from its launch flags: `--read-only` is locked, no flags
+ * is `ask`, `--allow-write` alone is `auto`, the three allow flags are `full`, anything else is
+ * `custom`. It only LABELS the state: no policy is applied at startup.
+ */
+export function modeFromFlags(flags) {
+    if (flags.readOnly)
+        return "locked";
+    const { allowWrite: write, allowProcess: process, allowExternal: external } = flags;
+    if (!write && !process && !external)
+        return "ask";
+    if (write && !process && !external)
+        return "auto";
+    if (write && process && external)
+        return "full";
+    return "custom";
+}
+/** How one effect behaves under a policy: runs, asks, or is denied. */
+export function effectState(allowed, approvals) {
+    return allowed ? "on" : approvals ? "ask" : "off";
+}
+/** Markdown status of the permission state of a session (shared wording for TUI and API callers). */
+export function describePermissionStatus(input) {
+    const { mode, policy, approvals } = input;
+    const row = (label, allowed) => `- ${label}: ${effectState(allowed, approvals)}`;
+    const head = mode === "locked"
+        ? "Permission mode: **locked** (read-only)"
+        : mode === "custom"
+            ? "Permission mode: **custom** (launch flags that match no mode)"
+            : `Permission mode: **${mode}** — ${PERMISSION_MODE_TABLE[mode].summary}`;
+    return [
+        head,
+        "",
+        row("write", policy.write),
+        row("process", policy.process),
+        row("external (network, MCP, plugin tools)", policy.external),
+        ...(policy.analysis ? ["- Python analysis: pre-allowed (--allow-analysis)"] : []),
+        "",
+        "`on` runs without asking, `ask` prompts first, `off` is denied. Paths outside the workspace ask per directory. Modes are not a sandbox.",
+    ].join("\n");
+}

package/dist/plan/exit-plan.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `exit_plan`: how the plan agent hands over its plan. The tool publishes the plan as a Markdown
+ * artifact (`plan.md`, one revision per call), asks the user for a decision through the same
+ * question infrastructure as `ask_user_question` and ALWAYS returns a tool result (approved,
+ * skipped or feedback), so a session never keeps a dangling call. It does not switch agents or
+ * start anything: an approved plan is recorded (`plan/state.ts`) and the host starts the
+ * implementation turn once the plan run has ended.
+ *
+ * The tool is opt-in (`core/opt-in.ts`): only the plan agent's run lists it. Its effect is
+ * `read`, so it is allowed under every policy; the plan agent stays read-only because its run
+ * policy has no write/process/external effect, whatever the permission mode.
+ */
+import type { AskQuestionsRequest, AskQuestionsResult } from "@alisio/sdk";
+import type { ToolRegistry } from "../core/registry.ts";
+import { type PlanStore } from "./state.ts";
+export interface ExitPlanDeps {
+    store: PlanStore;
+    ui: {
+        interactive(): boolean;
+        askQuestions(request: AskQuestionsRequest): Promise<AskQuestionsResult>;
+    };
+    /** `--read-only`: nothing can be implemented afterwards, so there is no decision to take. */
+    readOnly?: boolean;
+}
+export declare function registerExitPlan(registry: ToolRegistry, deps: ExitPlanDeps): void;