@alisio/core 0.1.0-alpha.21 → 0.1.0-alpha.22

package/dist/tools/artifacts.js

@@ -0,0 +1,143 @@
+/**
+ * `artifact_read` (effect `read`) and `artifact_export` (effect `write`), spec §12. Reading is
+ * bounded (64 KiB, truncation marked); exporting copies a published artifact into the workspace,
+ * confined to it, through the existing `write` gate. Both only see the caller's root session.
+ */
+import { constants } from "node:fs";
+import { copyFile, lstat, mkdir, open, realpath } from "node:fs/promises";
+import { dirname, join, relative, sep } from "node:path";
+import { KIND_LABELS, looksLikeText } from "../artifacts/kinds.js";
+import { readHead } from "../artifacts/store.js";
+import { safePath } from "../runtime/paths.js";
+import { objectSchema } from "./standard.js";
+export const ARTIFACT_READ_MAX = 64 * 1024;
+const EXPORTED = "exported ";
+/** A ready artifact of the caller's root session, or a model-readable error. */
+function ownArtifact(deps, id, session) {
+    const record = typeof id === "string" ? deps.store.get(id) : undefined;
+    if (!record || record.sessionId !== deps.rootOf(session ?? ""))
+        throw new Error(`Artifact ${String(id)} not found in this session (see artifact_list)`);
+    if (record.status !== "ready")
+        throw new Error(`Artifact ${record.id} is ${record.status}`);
+    return record;
+}
+/**
+ * Workspace-relative paths an `artifact_export` result reports, in order (the Changes view of the
+ * web reads them; the first line of the text names the artifact and the target).
+ */
+export function exportedPaths(result) {
+    if (!result || result.isError)
+        return [];
+    const text = result.content.find((part) => part.type === "text");
+    if (!text || text.type !== "text" || !text.text.startsWith(EXPORTED))
+        return [];
+    return text.text
+        .split("\n")
+        .slice(1)
+        .map((line) => line.trim())
+        .filter(Boolean);
+}
+const toPosix = (path) => path.split(sep).join("/");
+export function registerArtifactTools(registry, deps) {
+    registry.register({
+        name: "artifact_read",
+        effect: "read",
+        description: "Read a published text artifact of this session (Markdown, CSV, JSON, HTML, code…), at " +
+            "most 64 KiB; longer files are truncated and say so. path selects one file inside a " +
+            "multi-file artifact (default: its entry).",
+        inputSchema: objectSchema({
+            id: { type: "string", minLength: 1, maxLength: 64 },
+            path: { type: "string", minLength: 1, maxLength: 512 },
+            maxBytes: { type: "integer", minimum: 1, maximum: ARTIFACT_READ_MAX },
+        }, ["id"]),
+        async execute(input, context) {
+            const record = ownArtifact(deps, input.id, context.session);
+            const wanted = typeof input.path === "string" ? input.path : (record.entry ?? record.fileName);
+            const file = await deps.store.resolveFile(record, wanted);
+            if (!file)
+                throw new Error(`${wanted} is not a file of ${record.id}; files: ${(await deps.store.files(record))
+                    .map((f) => f.path)
+                    .slice(0, 50)
+                    .join(", ")}`);
+            if (!looksLikeText(await readHead(file.abs)))
+                throw new Error(`${file.path} is not a text file; download it instead`);
+            const max = Math.min(Number(input.maxBytes ?? ARTIFACT_READ_MAX), ARTIFACT_READ_MAX);
+            const handle = await open(file.abs, "r");
+            let text;
+            try {
+                const buffer = Buffer.alloc(Math.min(max, file.bytes));
+                const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+                // A multi-byte character cut at the limit decodes as U+FFFD: drop it.
+                text = buffer.subarray(0, bytesRead).toString("utf8").replace(/�+$/, "");
+            }
+            finally {
+                await handle.close();
+            }
+            const truncated = file.bytes > max;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `${record.id} · ${KIND_LABELS[record.kind]} · ${file.path} · ${file.bytes} bytes`,
+                            text,
+                            ...(truncated ? [`[truncated: showing ${max} of ${file.bytes} bytes]`] : []),
+                        ].join("\n"),
+                    },
+                ],
+            };
+        },
+    });
+    registry.register({
+        name: "artifact_export",
+        effect: "write",
+        description: "Copy a published artifact of this session into the workspace (target: a workspace-" +
+            "relative directory; '.' is the root). A multi-file artifact becomes a folder named after " +
+            "it. Existing files are kept unless overwrite is true.",
+        inputSchema: objectSchema({
+            id: { type: "string", minLength: 1, maxLength: 64 },
+            target: { type: "string", maxLength: 1024 },
+            overwrite: { type: "boolean" },
+        }, ["id", "target"]),
+        async execute(input, context) {
+            const record = ownArtifact(deps, input.id, context.session);
+            const workspace = await realpath(context.workspace);
+            // `\` and `/` are both separators (Windows users type either).
+            const target = String(input.target).replace(/\\/g, "/").trim() || ".";
+            const directory = await safePath(workspace, target);
+            const files = await deps.store.files(record);
+            const folder = files.length > 1 ? record.fileName.replace(/\.zip$/i, "") || record.id : undefined;
+            const plan = [];
+            for (const file of files) {
+                const parts = files.length > 1 ? file.path.split("/") : [record.fileName];
+                // Every destination is confined again (no symlinked component, never outside).
+                const to = await safePath(workspace, join(directory, ...(folder ? [folder] : []), ...parts));
+                plan.push({ from: file.abs, to });
+            }
+            const overwrite = input.overwrite === true;
+            if (!overwrite)
+                for (const { to } of plan) {
+                    const existing = await lstat(to).catch(() => undefined);
+                    if (existing)
+                        throw new Error(`${toPosix(relative(workspace, to))} already exists; pass overwrite: true to replace it`);
+                }
+            const written = [];
+            for (const { from, to } of plan) {
+                await mkdir(dirname(to), { recursive: true });
+                await copyFile(from, to, overwrite ? 0 : constants.COPYFILE_EXCL);
+                written.push(toPosix(relative(workspace, to)));
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `${EXPORTED}${record.fileName} (${record.id}) to ${toPosix(relative(workspace, directory)) || "."}:`,
+                            ...written,
+                        ].join("\n"),
+                    },
+                ],
+            };
+        },
+    });
+}

package/dist/tools/data.d.ts

@@ -0,0 +1,7 @@
+import { type DatasetService } from "../analysis/data/datasets.ts";
+import type { ToolRegistry } from "../core/registry.ts";
+export interface DataToolDeps {
+    datasets: DatasetService;
+    rootOf: (sessionId: string) => string;
+}
+export declare function registerDataTools(registry: ToolRegistry, deps: DataToolDeps): void;

package/dist/tools/data.js

@@ -0,0 +1,160 @@
+import { DataError, PageParamError, } from "../analysis/data/datasets.js";
+import { cellText, formatCount } from "../analysis/data/describe.js";
+import { safePath } from "../runtime/paths.js";
+import { objectSchema } from "./standard.js";
+const INSPECT_TEXT_CHARS = 12_000;
+const QUERY_TEXT_CHARS = 24_000;
+/** A model-readable failure: `code: message` (the codes of §14.1 are also tool error prefixes). */
+function failure(error) {
+    if (error instanceof DataError)
+        throw new Error(`${error.code}: ${error.message}`);
+    if (error instanceof PageParamError)
+        throw new Error(`invalid_request: ${error.message}`);
+    throw error;
+}
+function tableBlock(columns, rows, caption) {
+    return {
+        kind: "table",
+        columns,
+        rows: rows.map((row) => columns.map((_, i) => cellText(row[i], 120))),
+        ...(caption ? { caption } : {}),
+    };
+}
+export function registerDataTools(registry, deps) {
+    const own = (context) => deps.rootOf(context.session ?? "");
+    registry.register({
+        name: "data_inspect",
+        effect: "read",
+        description: "Describe a tabular file: sheets, columns with type hints and statistics (nulls, distinct, " +
+            "min/max/mean, top values) and sample rows. Pass a workspace file `path` (CSV, TSV, JSON, " +
+            "JSONL or XLSX; ingested once into a SQLite dataset of this session) or the `datasetId` of " +
+            "a dataset the user attached. The result gives the datasetId to use with data_query and " +
+            "python_run { inputs: [{ datasetId }] }. XLSX needs Python 3.10+; for the other formats no " +
+            "Python is needed.",
+        inputSchema: objectSchema({
+            path: { type: "string", minLength: 1, maxLength: 1024 },
+            datasetId: { type: "string", minLength: 1, maxLength: 64 },
+            sheet: { type: "string", maxLength: 200 },
+            sampleRows: { type: "integer", minimum: 0, maximum: 20 },
+        }),
+        paths: (input) => (typeof input.path === "string" ? [input.path] : []),
+        async execute(input, context) {
+            const hasPath = typeof input.path === "string" && input.path !== "";
+            const hasId = typeof input.datasetId === "string" && input.datasetId !== "";
+            if (hasPath === hasId)
+                throw new Error("Pass exactly one of path or datasetId");
+            const root = own(context);
+            try {
+                let record;
+                let note = "";
+                if (hasId)
+                    record = deps.datasets.getFor(String(input.datasetId), root);
+                else {
+                    const resolved = context.resolvePath
+                        ? await context.resolvePath(String(input.path))
+                        : await safePath(context.workspace, String(input.path));
+                    let last = 0;
+                    const result = await deps.datasets.ingest({
+                        rootSessionId: root,
+                        sessionId: context.session ?? "headless",
+                        workspace: context.workspace,
+                        path: resolved,
+                        sourcePath: resolved,
+                        signal: context.signal,
+                        onProgress: (rows) => {
+                            const now = Date.now();
+                            if (now - last < 1000)
+                                return;
+                            last = now;
+                            context.emit(`reading ${formatCount(rows)} rows…\n`);
+                        },
+                    });
+                    record = result.record;
+                    note = result.reused ? "(already ingested in this session)\n" : "";
+                }
+                const sample = Number(input.sampleRows ?? 5);
+                const described = await deps.datasets.describe(record, sample, INSPECT_TEXT_CHARS, context.signal);
+                const wantedSheet = typeof input.sheet === "string" ? input.sheet : undefined;
+                const shown = wantedSheet
+                    ? described.detail.sheetDetails.filter((s) => s.name === wantedSheet || s.table === wantedSheet)
+                    : described.detail.sheetDetails;
+                if (wantedSheet && !shown.length)
+                    throw new Error(`Sheet ${wantedSheet} not found; sheets: ${described.detail.sheetDetails.map((s) => s.name).join(", ")}`);
+                const blocks = [];
+                for (const sheet of shown.slice(0, 5)) {
+                    blocks.push(tableBlock(["column", "type", "nulls", "distinct", "min", "max", "mean"], sheet.columns.map((c) => [
+                        c.name,
+                        c.type,
+                        formatCount(c.nulls),
+                        `${formatCount(c.distinct)}${c.distinctExact ? "" : "~"}`,
+                        c.min ?? "",
+                        c.max ?? "",
+                        c.mean !== undefined ? Number(c.mean.toPrecision(6)) : "",
+                    ]), `${sheet.table} · ${formatCount(sheet.rows)} rows`));
+                    const rows = described.samples.get(sheet.table);
+                    if (rows?.rows.length)
+                        blocks.push(tableBlock(rows.columns, rows.rows, `${sheet.table} · first ${rows.rows.length} rows`));
+                }
+                return {
+                    content: [
+                        { type: "text", text: `${note}${described.text}` },
+                        ...blocks.map((block) => ({ type: "ui", block })),
+                    ],
+                };
+            }
+            catch (error) {
+                return failure(error);
+            }
+        },
+    });
+    registry.register({
+        name: "data_query",
+        effect: "read",
+        description: "Run one read-only SQL query (SQLite dialect: a single SELECT or WITH statement) on a " +
+            "dataset of this session. Tables: `data` for CSV/TSV/JSON/JSONL, `s_<sheet>` for XLSX; " +
+            'quote column names ("revenue"). Values are stored exactly: numbers are numbers, other ' +
+            "cells (007, 1,234, N/A) are their original text, so cast or filter before arithmetic. At " +
+            "most maxRows (default 200, max 1000) rows; statements longer than the time limit are " +
+            "stopped. Heavy analysis belongs in python_run.",
+        inputSchema: objectSchema({
+            datasetId: { type: "string", minLength: 1, maxLength: 64 },
+            sql: { type: "string", minLength: 1, maxLength: 20_000 },
+            maxRows: { type: "integer", minimum: 1, maximum: 1000 },
+        }, ["datasetId", "sql"]),
+        async execute(input, context) {
+            try {
+                const record = deps.datasets.getFor(String(input.datasetId), own(context));
+                const maxRows = Number(input.maxRows ?? 200);
+                const result = await deps.datasets.query(record, String(input.sql), {
+                    maxRows,
+                    signal: context.signal,
+                });
+                const lines = [
+                    result.columns.join("\t"),
+                    ...result.rows.map((row) => row.map((v) => cellText(v, 2048)).join("\t")),
+                ];
+                let text = lines.join("\n");
+                let cut = false;
+                if (text.length > QUERY_TEXT_CHARS) {
+                    text = `${text.slice(0, QUERY_TEXT_CHARS)}…`;
+                    cut = true;
+                }
+                const summary = `${formatCount(result.rows.length)} row${result.rows.length === 1 ? "" : "s"}${result.truncated
+                    ? ` (truncated at maxRows ${maxRows}; add LIMIT/OFFSET or aggregate)`
+                    : ""}${result.clipped ? "; long cells were shortened" : ""}${cut ? "; output shortened" : ""}`;
+                return {
+                    content: [
+                        { type: "text", text: `${text}\n[${summary}]` },
+                        {
+                            type: "ui",
+                            block: tableBlock(result.columns, result.rows, `${record.name} · ${summary}`),
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                return failure(error);
+            }
+        },
+    });
+}

package/dist/tools/execute.js

@@ -22,7 +22,9 @@
 import { createContext, Script } from "node:vm";
 export const EXECUTE_TIMEOUT_MS = 10_000;
 export const MAX_NESTED_CALLS = 20;
-const allowedEffect = (policy, effect) => effect === "read" || effect === "internal" || !!policy[effect];
+const allowedEffect = (policy, effect) => effect === "read" ||
+    effect === "internal" ||
+    ((effect === "write" || effect === "process" || effect === "external") && !!policy[effect]);
 export async function runExecute(code, deps) {
     let calls = 0;
     const controller = new AbortController();
@@ -42,7 +44,9 @@ export async function runExecute(code, deps) {
             throw new Error(`callTool: exceeded the limit of ${MAX_NESTED_CALLS} nested tool calls`);
         const tool = deps.registry.get(name); // throws "Unknown tool: <name>" when absent
         const effect = tool.effect ?? "external";
-        if (!allowedEffect(deps.policy, effect))
+        // A capability tool is reachable only when already allowed (never through a persisted grant).
+        if (!allowedEffect(deps.policy, effect) &&
+            !(tool.capability === "analysis.run" && deps.policy.analysis))
             throw new Error(`callTool: capability denied for "${name}" (effect: ${effect}); execute cannot request ` +
                 "new approvals, only use capabilities already allowed for this session");
         const rawInput = input && typeof input === "object" ? input : {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alisio/core",
-  "version": "0.1.0-alpha.21",
+  "version": "0.1.0-alpha.22",
   "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.17",
+    "@alisio/sdk": "0.1.0-alpha.18",
     "@mixmark-io/domino": "2.2.0",
     "@modelcontextprotocol/client": "2.1.0",
     "ajv": "8.20.0",