@alisio/core 0.1.0-alpha.13 → 0.1.0-alpha.14

package/dist/core/compaction.js

@@ -116,6 +116,10 @@ function clampMessage(message, maxToolResultChars, maxTextChars) {
     let used = 0;
     let changed = false;
     const content = message.result.content.map((part) => {
+        // Only the text projection is clipped: ui/image parts are display-only transcript data and
+        // are never truncated (raw bytes never reach the model, which only sees the projection).
+        if (part.type !== "text")
+            return part;
         const room = maxToolResultChars - used;
         const text = room <= 0
             ? TRUNCATION_MARKER
@@ -213,7 +217,8 @@ export function reduceMessagesToBudget(messages, targetChars, options = {}) {
                     : m.role === "assistant"
                         ? m.text.length > textCap
                         : m.role === "tool" &&
-                            m.result.content.reduce((a, p) => a + p.text.length, 0) > toolCap;
+                            m.result.content.reduce((a, p) => a + (p.type === "text" ? p.text.length : 0), 0) >
+                                toolCap;
                 if (over) {
                     best = i;
                     bestSize = current;
@@ -260,7 +265,12 @@ export function serializeForSummary(messages, maxItemChars = 4_000) {
                 lines.push(`TOOL CALL ${c.id} ${c.name}: ${clip(c.arguments, maxItemChars)}`);
         }
         else {
-            const text = m.result.content.map((c) => c.text).join("\n");
+            // Only the text projection is summarized: ui/image parts are display data and never
+            // reach the summarizer (raw image bytes in particular stay out of the checkpoint).
+            const text = m.result.content
+                .filter((p) => p.type === "text")
+                .map((c) => c.text)
+                .join("\n");
             lines.push(`TOOL RESULT ${m.callId}${m.result.isError ? " (error)" : ""}: ${clip(text, maxItemChars)}`);
         }
     }

package/dist/core/contracts.d.ts

@@ -66,6 +66,8 @@ export interface SessionStore {
     release(id: string): void;
     beginCall(session: string, call: ToolCall): void;
     endCall(session: string, call: ToolCall, result: ToolResult): void;
+    /** The persisted result of a completed tool call, for replay of rich (ui/image) parts. */
+    callResult(session: string, callId: string): ToolResult | undefined;
     reconcile(id: string, acknowledge?: boolean): void;
     event(id: string, runId: string, type: string, data: unknown): void;
 }

package/dist/core/runner.js

@@ -1,4 +1,4 @@
-import { textResult, } from "@alisio/sdk";
+import { textProjection, textResult, } from "@alisio/sdk";
 import { checkpointInstructions, estimateTokens, MAX_TRUSTED_WINDOW, parseCheckpointOutput, planCompaction, reduceMessagesToBudget, shouldCompactContext, summarize, summaryMessage, } from "./compaction.js";
 /**
  * Default cumulative token budget for one run: several context windows (each turn re-sends the
@@ -409,9 +409,13 @@ export class AgentRunner {
                 let completion;
                 let truncated = false;
                 let usage;
+                // Providers only ever see the text projection of tool results: ui/image parts are a
+                // display-only extension of the persisted transcript and never reach a model prompt
+                // (raw image bytes included). The store keeps the rich parts for TUI replay.
+                const providerMessages = messages.map((m) => m.role === "tool" ? { ...m, result: textProjection(m.result) } : m);
                 for await (const e of provider.stream({
                     instructions,
-                    messages,
+                    messages: providerMessages,
                     tools,
                     maxOutputTokens: options.maxOutputTokens ?? o.maxOutputTokens ?? 4096,
                     signal: combined,
@@ -498,7 +502,14 @@ export class AgentRunner {
                     const { call } = p;
                     let result;
                     const started = Date.now();
-                    emit("tool_started", { name: call.name, id: call.id, arguments: call.arguments });
+                    // `effect` rides along so the TUI can group consecutive calls by capability kind
+                    // (read batches, write batches, commands…) without a name heuristic. Additive field.
+                    emit("tool_started", {
+                        name: call.name,
+                        id: call.id,
+                        arguments: call.arguments,
+                        effect: p.tool?.effect ?? "external",
+                    });
                     try {
                         combined.throwIfAborted();
                         if (p.error)
@@ -572,6 +583,7 @@ export class AgentRunner {
                         isError: result.isError ?? false,
                         durationMs: Date.now() - started,
                         preview: result.content
+                            .filter((part) => part.type === "text")
                             .map((c) => c.text)
                             .join("\n")
                             .slice(0, 2_000),

package/dist/mcp/connector.js

@@ -4,6 +4,7 @@ import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/cli
 import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
 import { objectSchema } from "../tools/standard.js";
 import { loadVersion } from "../version.js";
+import { mapMcpCallResult, mapMcpResourceResult } from "./rich.js";
 const TOOL_NAME_LIMIT = 64;
 /**
  * Per-server client close cap used ONLY by the terminal `close()`: the MCP SDK's stdio close can
@@ -111,7 +112,7 @@ export class McpConnector {
                     const result = i.uri
                         ? await client.readResource({ uri: String(i.uri) }, { signal: c.signal, timeout: 15000 })
                         : await client.listResources(undefined, { signal: c.signal, timeout: 15000 });
-                    return textResult(JSON.stringify(result));
+                    return mapMcpResourceResult(result);
                 },
             }));
             undo.push(this.registry.register({
@@ -329,7 +330,7 @@ export class McpConnector {
                             JSON.stringify(current.inputSchema) !== JSON.stringify(tool.inputSchema))
                             throw new Error("MCP schema changed; reconnect the server to refresh tools");
                         const result = await client.callTool({ name: tool.name, arguments: input }, { signal: ctx.signal, timeout: 30000 });
-                        return textResult(JSON.stringify(result), "isError" in result && result.isError === true);
+                        return mapMcpCallResult(result);
                     },
                 }));
             }

package/dist/mcp/rich.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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 { type ToolResult, type UiBlock } from "@alisio/sdk";
+/**
+ * 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 declare function blockFromUnknown(value: unknown): UiBlock | undefined;
+/** Tries a JSON-parseable text part: recognized shapes become ui blocks, everything else stays text. */
+export declare function blockFromJsonText(text: string): UiBlock | undefined;
+/** Compact plain-text rendering of a ui block, used as the canonical model-visible projection. */
+export declare function renderUiBlockText(block: UiBlock): string;
+/**
+ * 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 declare function mapMcpCallResult(result: unknown): ToolResult;
+/**
+ * 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 declare function mapMcpResourceResult(result: unknown): ToolResult;

package/dist/mcp/rich.js

@@ -0,0 +1,290 @@
+/**
+ * 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";
+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;
+    }
+}
+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/runtime/store.d.ts

@@ -30,6 +30,8 @@ export declare class SQLiteStore implements SessionStore {
     release(id: string): void;
     beginCall(id: string, call: ToolCall): void;
     endCall(id: string, call: ToolCall, result: ToolResult): void;
+    /** Rich (ui/image) parts persist as part of the serialized result and replay verbatim. */
+    callResult(id: string, callId: string): ToolResult | undefined;
     reconcile(id: string, acknowledge?: boolean): void;
     event(id: string, runId: string, type: string, data: unknown): void;
     getState(plugin: string, key: string): unknown;

package/dist/runtime/store.js

@@ -211,6 +211,13 @@ export class SQLiteStore {
             .prepare("INSERT INTO tool_calls(session,call_id,status,result) VALUES(?,?,'completed',?) ON CONFLICT(session,call_id) DO UPDATE SET status='completed',result=excluded.result")
             .run(id, call.id, JSON.stringify(result));
     }
+    /** Rich (ui/image) parts persist as part of the serialized result and replay verbatim. */
+    callResult(id, callId) {
+        const row = this.db
+            .prepare("SELECT result FROM tool_calls WHERE session=? AND call_id=? AND status='completed'")
+            .get(id, callId);
+        return row?.result ? JSON.parse(row.result) : undefined;
+    }
     reconcile(id, acknowledge = false) {
         this.db.transaction(() => {
             const messages = this.messages(id);

package/dist/tools/execute.js

@@ -54,7 +54,10 @@ export async function runExecute(code, deps) {
             ...(deps.session ? { session: deps.session } : {}),
             ...(deps.label ? { label: deps.label } : {}),
         });
-        const text = result.content.map((c) => c.text).join("\n");
+        const text = result.content
+            .filter((p) => p.type === "text")
+            .map((c) => c.text)
+            .join("\n");
         if (result.isError)
             throw new Error(text);
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alisio/core",
-  "version": "0.1.0-alpha.13",
+  "version": "0.1.0-alpha.14",
   "description": "Embeddable provider-agnostic Alisio agent core: tool loop, context compaction, local tools, MCP, plugin host and SQLite session store. Runs on Node >=22.16 and Bun.",
   "author": "Gustavo Gutiérrez",
   "license": "MIT",
@@ -41,7 +41,7 @@
     "node": ">=22.16"
   },
   "dependencies": {
-    "@alisio/sdk": "0.1.0-alpha.8",
+    "@alisio/sdk": "0.1.0-alpha.9",
     "@mixmark-io/domino": "2.2.0",
     "@modelcontextprotocol/client": "2.1.0",
     "ajv": "8.20.0",