@alisio/core 0.1.0-alpha.17 → 0.1.0-alpha.19

package/dist/sessions/side-questions.js

@@ -0,0 +1,161 @@
+import { serializeForSummary } from "../core/compaction.js";
+/** `plugin_state.plugin` value of the side-question history (never a valid plugin id). */
+export const SIDE_QUESTIONS_NAMESPACE = "core:btw";
+export const SIDE_QUESTION_HISTORY_LIMIT = 20;
+export const SIDE_QUESTION_MAX_CHARS = 4_000;
+/** The line every surface prints for `/btw` without a question and without any history. */
+export const SIDE_QUESTION_USAGE = "Usage: /btw <question>";
+export const SIDE_QUESTION_DESCRIPTION = "Ask a side question about the current session without adding to the conversation.";
+/** Per-message clip of the transcript the side call sees (as in compaction summaries). */
+const MAX_ITEM_CHARS = 4_000;
+export const SIDE_QUESTION_INSTRUCTIONS = [
+    "The user is asking a quick side question (/btw) about the session transcript below.",
+    "It is NOT part of the conversation: answer it directly and concisely from the transcript and",
+    "your general knowledge. You have no tools in this reply, so do not take or promise any",
+    "action, do not continue the task and do not call tools; if the transcript does not contain",
+    "the answer, say so briefly.",
+].join(" ");
+/**
+ * The transcript lines for the side call, newest kept first: when the whole history does not fit
+ * `budget` characters, the oldest messages are dropped (and counted in a leading marker). The
+ * newest message alone is clipped from its start if it is still too large.
+ */
+export function sideTranscript(messages, budget) {
+    const lines = [];
+    let used = 0;
+    let omitted = 0;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i];
+        const text = serializeForSummary([message], MAX_ITEM_CHARS);
+        if (used + text.length + 1 > budget) {
+            if (lines.length)
+                omitted = i + 1;
+            else {
+                // Even the newest message alone is too large: keep its end (the most recent part).
+                lines.push(text.slice(Math.max(0, text.length - budget)));
+                omitted = i;
+            }
+            break;
+        }
+        lines.unshift(text);
+        used += text.length + 1;
+    }
+    if (omitted > 0)
+        lines.unshift(`[${omitted} earlier messages omitted to fit the context budget]`);
+    return lines.join("\n");
+}
+const isEntry = (value) => !!value &&
+    typeof value === "object" &&
+    typeof value.id === "string" &&
+    typeof value.question === "string" &&
+    typeof value.answer === "string";
+export class SideQuestions {
+    options;
+    now;
+    newId;
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? Date.now;
+        this.newId = options.id ?? (() => crypto.randomUUID());
+    }
+    /** The session's side questions, oldest first (newest last). */
+    history(sessionId) {
+        let stored;
+        try {
+            stored = this.options.state.getState(SIDE_QUESTIONS_NAMESPACE, sessionId);
+        }
+        catch {
+            return [];
+        }
+        return Array.isArray(stored) ? stored.filter(isEntry) : [];
+    }
+    /**
+     * Answers `question` about the session with one tool-less call of the session's model and
+     * records it in the history. Throws on an empty or oversized question, on cancellation (the
+     * signal's reason) and on provider failures (nothing is recorded then).
+     */
+    async ask(sessionId, question, options = {}) {
+        const text = question.trim();
+        if (!text)
+            throw new Error(SIDE_QUESTION_USAGE);
+        if (text.length > SIDE_QUESTION_MAX_CHARS)
+            throw new Error(`Side questions are limited to ${SIDE_QUESTION_MAX_CHARS} characters`);
+        const side = await this.options.runner.sideContext(sessionId);
+        const signal = AbortSignal.any([
+            AbortSignal.timeout(side.timeoutMs),
+            ...(options.signal ? [options.signal] : []),
+        ]);
+        signal.throwIfAborted();
+        const instructions = `${side.instructions}\n\n${SIDE_QUESTION_INSTRUCTIONS}`;
+        // The request must fit both the char budget and (when known) the model window, leaving room
+        // for the answer; ~3 chars per token keeps a conservative margin over the usual ~4.
+        const windowChars = side.contextWindow
+            ? Math.max(0, side.contextWindow - side.maxOutputTokens) * 3
+            : Number.POSITIVE_INFINITY;
+        const budget = Math.max(2_000, Math.min(side.maxContextChars, windowChars) - instructions.length - text.length - 200);
+        const transcript = sideTranscript(side.messages, budget);
+        const prompt = transcript
+            ? `<transcript>\n${transcript}\n</transcript>\n\nSide question: ${text}`
+            : `(The session has no messages yet.)\n\nSide question: ${text}`;
+        let answer = "";
+        let completed = false;
+        let truncated = false;
+        let usage = { input: 0, output: 0 };
+        try {
+            for await (const event of side.provider.stream({
+                instructions,
+                messages: [{ role: "user", text: prompt }],
+                tools: [],
+                maxOutputTokens: side.maxOutputTokens,
+                signal,
+                model: side.model,
+                sessionId,
+                ...(side.reasoningEffort ? { reasoningEffort: side.reasoningEffort } : {}),
+            })) {
+                signal.throwIfAborted();
+                if (event.type === "text_delta")
+                    answer += event.delta;
+                else if (event.type === "completed") {
+                    completed = true;
+                    truncated = event.message.truncated === true;
+                    answer = event.message.text || answer;
+                    if (event.usage)
+                        usage = { input: event.usage.input, output: event.usage.output };
+                }
+            }
+        }
+        catch (error) {
+            if (signal.aborted)
+                throw signal.reason ?? error;
+            throw new Error(`Side question failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        signal.throwIfAborted();
+        if (!completed)
+            throw new Error("Side question failed: the provider did not complete");
+        answer = answer.trim();
+        if (!answer)
+            throw new Error("Side question failed: the model returned an empty answer");
+        const entry = {
+            id: this.newId(),
+            question: text,
+            answer,
+            model: side.model,
+            usage,
+            createdAt: this.now(),
+            ...(truncated ? { truncated: true } : {}),
+        };
+        const next = [...this.history(sessionId), entry].slice(-SIDE_QUESTION_HISTORY_LIMIT);
+        this.options.state.setState(SIDE_QUESTIONS_NAMESPACE, sessionId, next);
+        return entry;
+    }
+}
+/** Plain Markdown for one entry (`position` is 1-based): readline, API callers and `/btw`. */
+export function formatSideQuestion(entry, position, total) {
+    return [
+        `**btw ${position}/${total}** · ${entry.question.replace(/\s+/g, " ")}`,
+        "",
+        entry.answer,
+        "",
+        `_${entry.model} · ${entry.usage.input} in · ${entry.usage.output} out tokens${entry.truncated ? " · truncated" : ""}_`,
+    ].join("\n");
+}

package/dist/tools/standard.js

@@ -1,10 +1,11 @@
 import { createHash } from "node:crypto";
 import { mkdir, rename, rm, stat, writeFile } from "node:fs/promises";
-import { dirname, relative } from "node:path";
+import { dirname, extname, relative } from "node:path";
 import { textResult, } from "@alisio/sdk";
+import { clipLines, unifiedPatch } from "../runtime/diff.js";
 import { fileSize, readHead, readText } from "../runtime/fs.js";
 import { safePath } from "../runtime/paths.js";
-import { isMissingCommand, RIPGREP_INSTALL_HINT, runProcess } from "../runtime/process.js";
+import { isMissingCommand, RIPGREP_INSTALL_HINT, runProcess, } from "../runtime/process.js";
 import { EXECUTE_TIMEOUT_MS, MAX_NESTED_CALLS, runExecute } from "./execute.js";
 import { searchWithFallback } from "./search.js";
 import { DEFAULT_TIMEOUT_SECONDS, MAX_RESPONSE_BYTES, MAX_TIMEOUT_SECONDS, webfetch, } from "./webfetch.js";
@@ -49,6 +50,50 @@ async function atomicWrite(resolve, path, content, expected) {
     finally {
         await rm(temporary, { force: true });
     }
+    return before;
+}
+/** Producer-side bounds of the web-only ui parts (spec §8.6). */
+const DIFF_LIMIT = 200 * 1024;
+const TERMINAL_LIMIT = 256 * 1024;
+/**
+ * Appends a display-only ui part after the tool's text (which stays the first part and is all
+ * that providers and headless output see, via `textProjection`).
+ */
+const withUi = (result, block) => block ? { ...result, content: [...result.content, { type: "ui", block }] } : result;
+/** A `diff` block of a file write, bounded to 200 KB at a line boundary. */
+function diffBlock(path, before, after) {
+    const patch = unifiedPatch(path, before, after);
+    if (!patch)
+        return undefined;
+    const { text, clipped } = clipLines(patch, DIFF_LIMIT);
+    const lang = extname(path).slice(1).toLowerCase();
+    return {
+        kind: "diff",
+        path,
+        patch: text,
+        ...(lang ? { lang } : {}),
+        ...(clipped ? { caption: `${path} (diff truncated to 200 KB)` } : {}),
+    };
+}
+/** A `terminal` block of a finished process: stdout then stderr, keeping the last 256 KB. */
+function terminalBlock(command, result, durationMs) {
+    const separator = result.stdout && result.stderr && !result.stdout.endsWith("\n") ? "\n" : "";
+    let output = `${result.stdout}${separator}${result.stderr}`;
+    const bytes = Buffer.byteLength(output);
+    const clipped = bytes > TERMINAL_LIMIT;
+    if (clipped)
+        output = Buffer.from(output)
+            .subarray(bytes - TERMINAL_LIMIT)
+            .toString("utf8")
+            .replace(/^\uFFFD+/, "");
+    return {
+        kind: "terminal",
+        command,
+        output,
+        exitCode: result.exitCode,
+        durationMs,
+        ...(result.truncated || clipped ? { truncated: true } : {}),
+    };
 }
 export function registerStandard(registry, workspace, skills, context, ui, 
 /** Live policy accessor for `execute`'s nested tool calls (bound once the runner exists). */
@@ -113,8 +158,8 @@ pathAccess) {
             const content = String(i.content);
             if (Buffer.byteLength(content) > 1_048_576)
                 throw new Error("Write exceeds 1 MiB");
-            await atomicWrite((path) => resolvePath(c, path), String(i.path), content, i.expectedHash);
-            return textResult(JSON.stringify({ path: i.path, sha256: hash(content) }));
+            const before = await atomicWrite((path) => resolvePath(c, path), String(i.path), content, i.expectedHash);
+            return withUi(textResult(JSON.stringify({ path: i.path, sha256: hash(content) })), diffBlock(String(i.path), before, content));
         },
     });
     register({
@@ -132,7 +177,7 @@ pathAccess) {
                 throw new Error("Edit must match exactly one occurrence");
             const after = before.slice(0, index) + String(i.newText) + before.slice(index + needle.length);
             await atomicWrite((p) => resolvePath(c, p), path, after, String(i.expectedHash));
-            return textResult(JSON.stringify({ path: i.path, sha256: hash(after) }));
+            return withUi(textResult(JSON.stringify({ path: i.path, sha256: hash(after) })), diffBlock(String(i.path), before, after));
         },
     });
     register({
@@ -201,12 +246,15 @@ pathAccess) {
             timeoutMs: { type: "integer", minimum: 1, maximum: 120000 },
         }, ["command", "args"]),
         async execute(i, c) {
-            return textResult(JSON.stringify(await runProcess(String(i.command), i.args, {
+            const started = Date.now();
+            const result = await runProcess(String(i.command), i.args, {
                 cwd: c.workspace,
                 signal: c.signal,
                 timeoutMs: Number(i.timeoutMs ?? 30000),
                 onData: c.emit,
-            })));
+            });
+            const command = [String(i.command), ...i.args].join(" ");
+            return withUi(textResult(JSON.stringify(result)), terminalBlock(command, result, Date.now() - started));
         },
     });
     register({
@@ -215,9 +263,11 @@ pathAccess) {
         description: "Run an arbitrary shell command. Explicit process capability required; not sandboxed.",
         inputSchema: objectSchema({ command: str }, ["command"]),
         async execute(i, c) {
-            return textResult(JSON.stringify(await runProcess(process.platform === "win32" ? "cmd.exe" : "/bin/sh", process.platform === "win32"
+            const started = Date.now();
+            const result = await runProcess(process.platform === "win32" ? "cmd.exe" : "/bin/sh", process.platform === "win32"
                 ? ["/d", "/s", "/c", String(i.command)]
-                : ["-c", String(i.command)], { cwd: c.workspace, signal: c.signal, onData: c.emit })));
+                : ["-c", String(i.command)], { cwd: c.workspace, signal: c.signal, onData: c.emit });
+            return withUi(textResult(JSON.stringify(result)), terminalBlock(String(i.command), result, Date.now() - started));
         },
     });
     for (const [name, args] of [

package/package.json

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