@alisio/core 0.1.0-alpha.9 → 0.1.1

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/background.d.ts

@@ -0,0 +1,7 @@
+import type { BackgroundTasks } from "../background/service.ts";
+import type { ToolRegistry } from "../core/registry.ts";
+export declare const BACKGROUND_TOOLS: readonly ["bg_run", "bg_list", "bg_output", "bg_stop"];
+export declare function registerBackgroundTools(registry: ToolRegistry, deps: {
+    tasks: BackgroundTasks;
+    rootOf: (session: string) => string;
+}): void;

package/dist/tools/background.js

@@ -0,0 +1,165 @@
+/**
+ * `bg_run`, `bg_list`, `bg_output` and `bg_stop`: shell commands that keep running while the agent
+ * works. All four declare `effect: "process"`, so they pass through the SAME gates as `shell` and
+ * `run_process`: `--read-only` and the plan agent (no process effect) cannot start a task, and
+ * also cannot read the output of one or stop one; the permission modes and approvals apply as for
+ * any command. A task is not sandboxed and ends when Alisio exits.
+ *
+ * A task belongs to the root session of the session that started it; every call can only see the
+ * tasks of its own session tree ("not found" otherwise).
+ */
+import { stat } from "node:fs/promises";
+import { textResult } from "@alisio/sdk";
+import { DEFAULT_READ_BYTES, MAX_READ_BYTES } from "../background/output.js";
+import { safePath } from "../runtime/paths.js";
+import { objectSchema } from "./standard.js";
+export const BACKGROUND_TOOLS = ["bg_run", "bg_list", "bg_output", "bg_stop"];
+const STATUSES = [
+    "queued",
+    "running",
+    "stopping",
+    "succeeded",
+    "failed",
+    "cancelled",
+    "lost",
+];
+/** The model-facing view of a task (snake_case, no paths). */
+function brief(task) {
+    return {
+        id: task.id,
+        label: task.label,
+        status: task.status,
+        ...(task.exitCode !== undefined ? { exit_code: task.exitCode } : {}),
+        ...(task.errorCode ? { error: task.errorCode } : {}),
+        ...(task.abortOrigin ? { stopped_by: task.abortOrigin } : {}),
+        output_bytes: task.bytes,
+        ...(task.truncated ? { output_truncated: true } : {}),
+        ...(task.cwd ? { cwd: task.cwd } : {}),
+        created_at: new Date(task.createdAt).toISOString(),
+        ...(task.endedAt ? { ended_at: new Date(task.endedAt).toISOString() } : {}),
+    };
+}
+export function registerBackgroundTools(registry, deps) {
+    const { tasks } = deps;
+    const rootOf = (session) => {
+        if (!session)
+            throw new Error("Background tasks need a session");
+        return deps.rootOf(session);
+    };
+    registry.register({
+        name: "bg_run",
+        effect: "process",
+        description: "Start a shell command in the background and return its task id at once; the agent keeps " +
+            "working. Use it for long-running commands (servers, watchers, long builds or test suites). " +
+            "Not sandboxed: the command runs with your permissions and ends when Alisio exits. The " +
+            "output is stored in a log you read with bg_output. When the task finishes on its own you " +
+            "get ONE notification message (no polling needed). `timeoutMs` is capped by the " +
+            "tasks.maxRunMs setting (default 1 hour); a task that exceeds it is stopped and fails.",
+        inputSchema: objectSchema({
+            command: { type: "string", minLength: 1, maxLength: 8000 },
+            cwd: { type: "string", description: "Working directory, relative to the workspace." },
+            label: { type: "string", maxLength: 80, description: "Short name shown in task lists." },
+            timeoutMs: { type: "integer", minimum: 1000, maximum: 86_400_000 },
+        }, ["command"]),
+        paths: (input) => (typeof input.cwd === "string" && input.cwd ? [input.cwd] : []),
+        async execute(input, context) {
+            const session = context.session;
+            rootOf(session);
+            const cwd = typeof input.cwd === "string" && input.cwd
+                ? context.resolvePath
+                    ? await context.resolvePath(input.cwd)
+                    : await safePath(context.workspace, input.cwd)
+                : context.workspace;
+            let isDirectory = false;
+            try {
+                isDirectory = (await stat(cwd)).isDirectory();
+            }
+            catch {
+                /* reported below */
+            }
+            if (!isDirectory)
+                throw new Error(`The working directory does not exist: ${input.cwd}`);
+            const task = tasks.start({
+                session: session,
+                workspace: context.workspace,
+                command: String(input.command),
+                cwd,
+                ...(typeof input.label === "string" ? { label: input.label } : {}),
+                ...(typeof input.timeoutMs === "number" ? { timeoutMs: input.timeoutMs } : {}),
+            });
+            return textResult(JSON.stringify({
+                ...brief(task),
+                timeout_ms: task.timeoutMs,
+                note: tasks.notifies
+                    ? "Started in the background. You will get one notification when it finishes; use bg_output to read its output and bg_stop to stop it."
+                    : "Started in the background. Nothing notifies you here: use bg_output to read its output and bg_list to check its status. It ends when this Alisio process ends.",
+            }));
+        },
+    });
+    registry.register({
+        name: "bg_list",
+        effect: "process",
+        description: "List the background tasks of this session, newest first.",
+        inputSchema: objectSchema({
+            status: { enum: STATUSES },
+            limit: { type: "integer", minimum: 1, maximum: 50 },
+        }),
+        async execute(input, context) {
+            const root = rootOf(context.session);
+            const listed = tasks.list(root, {
+                ...(typeof input.status === "string"
+                    ? { status: [input.status] }
+                    : {}),
+                limit: typeof input.limit === "number" ? input.limit : 20,
+            });
+            // Listing a finished task tells the agent it ended: it will not be announced as well.
+            tasks.markSeen(listed
+                .filter((task) => task.status !== "running" && task.status !== "queued" && task.status !== "stopping")
+                .map((task) => task.id));
+            return textResult(JSON.stringify({ tasks: listed.map(brief) }));
+        },
+    });
+    registry.register({
+        name: "bg_output",
+        effect: "process",
+        description: "Read the output of a background task incrementally. Pass `offset` 0 (or omit it) the first " +
+            "time, then the `next_offset` of the previous call. `eof` is true only when the task has " +
+            "ended and everything was read. At most 64 KiB per call (16 KiB by default); the log keeps " +
+            "the first tasks.maxOutputBytes bytes and the last 32 KiB.",
+        inputSchema: objectSchema({
+            id: { type: "string", minLength: 1 },
+            offset: { type: "integer", minimum: 0 },
+            limit: { type: "integer", minimum: 1, maximum: MAX_READ_BYTES },
+        }, ["id"]),
+        async execute(input, context) {
+            const root = rootOf(context.session);
+            const out = await tasks.read(root, String(input.id), {
+                offset: typeof input.offset === "number" ? input.offset : 0,
+                limit: typeof input.limit === "number" ? input.limit : DEFAULT_READ_BYTES,
+                reader: "model",
+            });
+            return textResult(JSON.stringify({
+                id: String(input.id),
+                status: out.status,
+                ...(out.exitCode !== undefined ? { exit_code: out.exitCode } : {}),
+                text: out.text,
+                next_offset: out.nextOffset,
+                eof: out.eof,
+                ...(out.truncated ? { output_truncated: true } : {}),
+            }));
+        },
+    });
+    registry.register({
+        name: "bg_stop",
+        effect: "process",
+        description: "Stop a background task (SIGTERM to its process group, SIGKILL after 3 seconds; " +
+            "taskkill /T on Windows). A stopped task ends `cancelled`, never `failed`. Stopping a task " +
+            "that already ended returns its final state.",
+        inputSchema: objectSchema({ id: { type: "string", minLength: 1 } }, ["id"]),
+        async execute(input, context) {
+            const root = rootOf(context.session);
+            const task = await tasks.stop(root, String(input.id), "model");
+            return textResult(JSON.stringify(brief(task)));
+        },
+    });
+}

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.d.ts

@@ -10,6 +10,11 @@ export interface ExecuteDeps {
     emit: (data: unknown) => void;
     session?: string;
     label?: string;
+    /**
+     * Non-interactive path resolver for nested calls: the snippet can only use directories this
+     * session already has; it never triggers a new external-directory approval prompt.
+     */
+    resolvePath?: (path: string) => Promise<string>;
     /** Overrides `EXECUTE_TIMEOUT_MS`, mainly for tests. */
     timeoutMs?: number;
 }

package/dist/tools/execute.js

@@ -20,9 +20,12 @@
  * otherwise need approval is denied outright here, never silently granted.
  */
 import { createContext, Script } from "node:vm";
+import { OPT_IN_TOOLS } from "../core/opt-in.js";
 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();
@@ -41,8 +44,13 @@ export async function runExecute(code, deps) {
         if (calls > MAX_NESTED_CALLS)
             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
+        // Opt-in tools (`exit_plan`) belong to the run that lists them, never to a nested call.
+        if (OPT_IN_TOOLS.has(name))
+            throw new Error(`callTool: "${name}" is not available from execute`);
         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 : {};
@@ -53,8 +61,12 @@ export async function runExecute(code, deps) {
             emit: deps.emit,
             ...(deps.session ? { session: deps.session } : {}),
             ...(deps.label ? { label: deps.label } : {}),
+            ...(deps.resolvePath ? { resolvePath: deps.resolvePath } : {}),
         });
-        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/dist/tools/goal.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `get_goal` and `update_goal`: the model's two handles on the session goal. Both are OPT-IN
+ * tools (`core/opt-in.ts`): a run only sees them while its session has an `active` goal and the
+ * agent is not the plan agent, so their descriptions cost no tokens anywhere else. The model can
+ * only report the goal `complete` or `blocked`, with evidence; pausing, resuming, editing,
+ * clearing and the budget belong to the user and have no tool.
+ *
+ * `effect: "internal"`: reporting changes Alisio's own bookkeeping, never the workspace.
+ */
+import { type GoalEvidence } from "@alisio/sdk";
+import type { ToolRegistry } from "../core/registry.ts";
+import type { GoalService } from "../goal/service.ts";
+export declare const GET_GOAL_TOOL = "get_goal";
+export declare const UPDATE_GOAL_TOOL = "update_goal";
+/** Parses the evidence list defensively (the schema is advisory for some providers). */
+export declare function parseEvidence(raw: unknown): GoalEvidence[] | string;
+export declare function registerGoalTools(registry: ToolRegistry, deps: {
+    goals: GoalService;
+}): void;