@alisio/core 0.5.2 → 0.7.0

package/dist/tools/execute.js

@@ -21,11 +21,9 @@
  */
 import { createContext, Script } from "node:vm";
 import { OPT_IN_TOOLS } from "../core/opt-in.js";
+import { decideEffect, effectOf } from "../permissions/decide.js";
 export const EXECUTE_TIMEOUT_MS = 10_000;
 export const MAX_NESTED_CALLS = 20;
-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();
@@ -47,10 +45,11 @@ export async function runExecute(code, deps) {
         // 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";
-        // 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))
+        const effect = effectOf(tool);
+        // A capability tool is reachable only when already allowed (never through a persisted grant),
+        // and a nested call never opens an approval: anything but an allow is a denial.
+        if (decideEffect(deps.policy, tool, { approvals: false, capabilityGranted: false }).kind !==
+            "allow")
             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/dist/tools/forge-guide.d.ts

@@ -0,0 +1,6 @@
+import type { ToolRegistry } from "../core/registry.ts";
+import { type GuideProvider } from "../forge/guides/provider.ts";
+/** Hard bound of the description (spec §8.2 budget). */
+export declare const FORGE_GUIDE_DESCRIPTION_MAX_CHARS = 300;
+export declare function forgeGuideDescription(topics: readonly string[]): string;
+export declare function registerForgeGuide(registry: ToolRegistry, provider: GuideProvider): void;

package/dist/tools/forge-guide.js

@@ -0,0 +1,60 @@
+import { callInternals } from "../core/call-internals.js";
+import { UnknownGuideTopicError } from "../forge/guides/provider.js";
+import { effectOf } from "../permissions/decide.js";
+/** Hard bound of the description (spec §8.2 budget). */
+export const FORGE_GUIDE_DESCRIPTION_MAX_CHARS = 300;
+export function forgeGuideDescription(topics) {
+    const js = topics.some((topic) => topic.startsWith("js."));
+    const py = topics.some((topic) => topic.startsWith("python."));
+    const about = [js ? "js_run" : "", py ? "python_run" : ""].filter(Boolean).join(" and ");
+    return (`Live guidance for ${about}: limits, tools, backends, packages. Call it before writing ` +
+        "non-trivial code. Send ifNoneMatch=etag to skip unchanged content.");
+}
+const fail = (text) => ({ content: [{ type: "text", text }], isError: true });
+export function registerForgeGuide(registry, provider) {
+    const topics = provider.topics();
+    if (topics.length === 0)
+        return;
+    const tool = {
+        name: "forge_guide",
+        effect: "read",
+        concurrent: true,
+        description: forgeGuideDescription(topics),
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["topic"],
+            properties: {
+                topic: { type: "string", enum: [...topics] },
+                ifNoneMatch: { type: "string", maxLength: 64 },
+            },
+        },
+        async execute(input, context) {
+            const topic = String(input.topic);
+            const catalog = topic === "js.tools"
+                ? callInternals(context)
+                    ?.nested()
+                    .catalog()
+                    .map((candidate) => ({ name: candidate.name, effect: effectOf(candidate) }))
+                : undefined;
+            try {
+                const answer = await provider.get({
+                    topic,
+                    ...(typeof input.ifNoneMatch === "string" ? { ifNoneMatch: input.ifNoneMatch } : {}),
+                    catalog,
+                });
+                if (answer.unchanged)
+                    return { content: [{ type: "text", text: JSON.stringify(answer) }] };
+                return {
+                    content: [{ type: "text", text: `etag: ${answer.etag}\n\n${answer.content}` }],
+                };
+            }
+            catch (error) {
+                if (error instanceof UnknownGuideTopicError)
+                    return fail(error.message);
+                throw error;
+            }
+        },
+    };
+    registry.register(tool);
+}

package/dist/tools/js-run.d.ts

@@ -0,0 +1,19 @@
+import { type ToolResult } from "@alisio/sdk";
+import type { Policy } from "../core/contracts.ts";
+import type { ToolRegistry } from "../core/registry.ts";
+import type { ExecutionKernel } from "../forge/kernel.ts";
+import { type ForgeResult } from "../forge/result.ts";
+export declare const JS_RUN_DESCRIPTION: string;
+export declare const CODE_PATH_MAX_BYTES: number;
+export interface JsRunDeps {
+    kernel: ExecutionKernel;
+    /** The root session of a session (its scratchpad, state and slots are keyed by it). */
+    rootOf: (session: string) => string;
+    /** The verified scratchpad of a session; undefined while there is none (or under --read-only). */
+    scratchpad: (session: string) => Promise<string | undefined>;
+    /** The run's live policy, to label the permission mode and the `--allow-*` flags. */
+    policy: () => Policy;
+}
+export declare function registerJsRun(registry: ToolRegistry, deps: JsRunDeps): void;
+/** The ForgeResult as the model sees it. */
+export declare function toToolResult(result: ForgeResult, maxChars: number): ToolResult;

package/dist/tools/js-run.js

@@ -0,0 +1,126 @@
+/**
+ * `js_run` (spec §6.1, D6, D-23, D-30): runs a JavaScript script in the isolated QuickJS-WASM
+ * engine. It is a thin adapter: it validates the input, reads `codePath` from the scratchpad and
+ * hands everything to the `ExecutionKernel`, then renders the `ForgeResult` for the model.
+ *
+ * Declared `read` and `concurrent: false` on purpose. The script has no effects of its own; every
+ * effect happens in a nested call that passes the run's gate with ITS effect (D7). A run's
+ * parallel read batch skips this tool (D-23a), and the kernel allows one active execution per
+ * session. The nested-call port and the "left effects behind" flag come from the runner through
+ * `callInternals`, which plugin tools cannot reach.
+ */
+import { readFile, stat } from "node:fs/promises";
+import { dirname, extname, join } from "node:path";
+import { callInternals } from "../core/call-internals.js";
+import { ForgeError, isForgeError } from "../forge/errors.js";
+import { MAX_FORGE_LIMITS } from "../forge/limits.js";
+import { renderForgeResult } from "../forge/result.js";
+import { resolveScratchPath } from "../forge/session-dir.js";
+export const JS_RUN_DESCRIPTION = "Run JavaScript in an isolated QuickJS-WASM VM to combine tools and shape results (tools.call, " +
+    "catalog, parallel, state; `return` a small JSON value). No imports, network or files; nested " +
+    "calls use this session's permissions and never ask. Pass `code` or `codePath` (.js in the " +
+    "scratchpad). See forge_guide.";
+export const CODE_PATH_MAX_BYTES = 64 * 1024;
+const modeOf = (policy) => policy.write && policy.process && policy.external ? "full" : policy.write ? "auto" : "ask";
+const invalid = (message) => ({
+    content: [{ type: "text", text: `INVALID_INPUT: ${message}` }],
+    isError: true,
+});
+/** The script's source from `code` or `codePath` (exactly one), or a reason it cannot be had. */
+async function sourceOf(input, deps, session) {
+    const hasCode = input.code !== undefined;
+    const hasPath = input.codePath !== undefined;
+    if (hasCode === hasPath)
+        throw new ForgeError("INVALID_INPUT", "pass exactly one of `code` or `codePath`");
+    if (hasCode) {
+        if (typeof input.code !== "string")
+            throw new ForgeError("INVALID_INPUT", "`code` must be a string");
+        return input.code;
+    }
+    if (typeof input.codePath !== "string" || input.codePath === "")
+        throw new ForgeError("INVALID_INPUT", "`codePath` must be a non-empty string");
+    const pad = await deps.scratchpad(session);
+    if (!pad)
+        throw new ForgeError("INVALID_INPUT", "`codePath` needs the session scratchpad, which is not available");
+    const path = await resolveScratchPath(pad, input.codePath);
+    if (![".js", ".mjs"].includes(extname(path)))
+        throw new ForgeError("INVALID_INPUT", "`codePath` must be a .js file inside the scratchpad");
+    const info = await stat(path).catch(() => undefined);
+    if (!info?.isFile())
+        throw new ForgeError("INVALID_INPUT", `\`codePath\` does not name a file: ${input.codePath}`);
+    if (info.size > CODE_PATH_MAX_BYTES)
+        throw new ForgeError("INVALID_INPUT", `\`codePath\` file is larger than ${CODE_PATH_MAX_BYTES} bytes`);
+    return readFile(path, "utf8");
+}
+export function registerJsRun(registry, deps) {
+    const tool = {
+        name: "js_run",
+        effect: "read",
+        concurrent: false,
+        description: JS_RUN_DESCRIPTION,
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                code: { type: "string", minLength: 1, maxLength: 65536 },
+                title: { type: "string", maxLength: 120 },
+                timeoutMs: { type: "integer", minimum: 100 },
+                codePath: { type: "string", maxLength: 1024 },
+            },
+        },
+        async execute(input, context) {
+            const internals = callInternals(context);
+            const session = context.session;
+            if (!internals || !session || !context.callId)
+                return invalid("js_run can only run inside an agent run");
+            let source;
+            try {
+                source = await sourceOf(input, deps, session);
+            }
+            catch (error) {
+                if (isForgeError(error))
+                    return invalid(error.message);
+                throw error;
+            }
+            const policy = deps.policy();
+            const rootSessionId = deps.rootOf(session);
+            const pad = await deps.scratchpad(session).catch(() => undefined);
+            const outcome = await deps.kernel.execute({
+                source,
+                ...(typeof input.title === "string" ? { title: input.title } : {}),
+                ...(typeof input.timeoutMs === "number"
+                    ? {
+                        requestedLimits: { timeoutMs: Math.min(input.timeoutMs, MAX_FORGE_LIMITS.timeoutMs) },
+                    }
+                    : {}),
+                call: {
+                    toolCallId: context.callId,
+                    session,
+                    rootSessionId,
+                    workspace: context.workspace,
+                    signal: context.signal,
+                    permissionMode: modeOf(policy),
+                    allowAnalysis: !!policy.analysis,
+                    allowProcess: policy.process,
+                    dispatcher: internals.nested(),
+                    emit: (progress) => context.emit(progress),
+                    ...(pad ? { tasksDir: join(dirname(pad), "tasks") } : {}),
+                },
+            });
+            // A cancelled run ends by throwing, like any tool interrupted by the user: the runner then keeps
+            // a call that left effects pending for recovery (D-23b) and closes one that only read.
+            if (outcome.result.status === "cancelled")
+                throw new Error("js_run was cancelled");
+            return toToolResult(outcome.result, outcome.maxOutputChars);
+        },
+    };
+    registry.register(tool);
+}
+/** The ForgeResult as the model sees it. */
+export function toToolResult(result, maxChars) {
+    const rendered = renderForgeResult(result, maxChars);
+    return {
+        content: [{ type: "text", text: rendered.text }],
+        ...(result.status === "succeeded" ? {} : { isError: true }),
+    };
+}

package/dist/tools/standard.d.ts

@@ -22,4 +22,10 @@ execCtx?: {
     } | undefined;
 }, 
 /** Mediated path policy (workspace plus declared extra directories and external approval). */
-pathAccess?: PathAccess): void;
+pathAccess?: PathAccess, features?: {
+    /**
+     * Register the legacy `execute` tool (default true). Forja's `js_run` replaces it (spec D6):
+     * the host turns this off while the JavaScript engine is enabled, with no fallback to `node:vm`.
+     */
+    execute?: boolean;
+}): void;

package/dist/tools/standard.js

@@ -99,7 +99,7 @@ export function registerStandard(registry, workspace, skills, context, ui,
 /** Live policy accessor for `execute`'s nested tool calls (bound once the runner exists). */
 execCtx, websearchCtx, 
 /** Mediated path policy (workspace plus declared extra directories and external approval). */
-pathAccess) {
+pathAccess, features = {}) {
     const register = (tool) => registry.register(tool);
     /**
      * Resolves one tool path through the host-injected policy when present, then the captured
@@ -455,46 +455,47 @@ pathAccess) {
                 }));
             },
         });
-    register({
-        name: "execute",
-        effect: "process",
-        description: "Run a short JavaScript snippet (Code Mode) that can call other tools via " +
-            "`await callTool(name, input)` and return one final JSON-serializable value, so " +
-            "intermediate tool results never re-enter your context — only the return value does. " +
-            "The snippet runs in an isolated context with no filesystem, network, imports or timers " +
-            "of its own; every nested callTool still goes through this session's normal permission " +
-            `gate (an effect not already allowed is denied, never newly approved). Bounded to ` +
-            `${EXECUTE_TIMEOUT_MS}ms wall-clock and ${MAX_NESTED_CALLS} nested tool calls. This is a ` +
-            "correctness sandbox, not an OS security boundary. Prefer plain sequential tool calls " +
-            "unless you are combining several read-only calls or post-processing their output.",
-        inputSchema: objectSchema({ code: { type: "string", minLength: 1 } }, ["code"]),
-        async execute(i, c) {
-            const policy = execCtx?.policy() ?? { write: false, process: false, external: false };
-            const result = await runExecute(String(i.code), {
-                registry,
-                policy,
-                workspace: c.workspace,
-                signal: c.signal,
-                emit: c.emit,
-                ...(c.session ? { session: c.session } : {}),
-                ...(c.label ? { label: c.label } : {}),
-                // Nested calls must never open a new external-directory prompt; only directories already
-                // approved for this session (or inside the workspace) are reachable.
-                ...(pathAccess
-                    ? {
-                        resolvePath: (path) => pathAccess.resolve(path, {
-                            workspace: c.workspace,
-                            ...(c.session ? { session: c.session } : {}),
-                            ...(c.label ? { label: c.label } : {}),
-                            signal: c.signal,
-                            interactive: false,
-                        }),
-                    }
-                    : c.resolvePath
-                        ? { resolvePath: c.resolvePath }
-                        : {}),
-            });
-            return textResult(JSON.stringify({ result: result ?? null }));
-        },
-    });
+    if (features.execute !== false)
+        register({
+            name: "execute",
+            effect: "process",
+            description: "Run a short JavaScript snippet (Code Mode) that can call other tools via " +
+                "`await callTool(name, input)` and return one final JSON-serializable value, so " +
+                "intermediate tool results never re-enter your context — only the return value does. " +
+                "The snippet runs in an isolated context with no filesystem, network, imports or timers " +
+                "of its own; every nested callTool still goes through this session's normal permission " +
+                `gate (an effect not already allowed is denied, never newly approved). Bounded to ` +
+                `${EXECUTE_TIMEOUT_MS}ms wall-clock and ${MAX_NESTED_CALLS} nested tool calls. This is a ` +
+                "correctness sandbox, not an OS security boundary. Prefer plain sequential tool calls " +
+                "unless you are combining several read-only calls or post-processing their output.",
+            inputSchema: objectSchema({ code: { type: "string", minLength: 1 } }, ["code"]),
+            async execute(i, c) {
+                const policy = execCtx?.policy() ?? { write: false, process: false, external: false };
+                const result = await runExecute(String(i.code), {
+                    registry,
+                    policy,
+                    workspace: c.workspace,
+                    signal: c.signal,
+                    emit: c.emit,
+                    ...(c.session ? { session: c.session } : {}),
+                    ...(c.label ? { label: c.label } : {}),
+                    // Nested calls must never open a new external-directory prompt; only directories already
+                    // approved for this session (or inside the workspace) are reachable.
+                    ...(pathAccess
+                        ? {
+                            resolvePath: (path) => pathAccess.resolve(path, {
+                                workspace: c.workspace,
+                                ...(c.session ? { session: c.session } : {}),
+                                ...(c.label ? { label: c.label } : {}),
+                                signal: c.signal,
+                                interactive: false,
+                            }),
+                        }
+                        : c.resolvePath
+                            ? { resolvePath: c.resolvePath }
+                            : {}),
+                });
+                return textResult(JSON.stringify({ result: result ?? null }));
+            },
+        });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alisio/core",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "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",
@@ -28,6 +28,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./forge-isolate": {
+      "types": "./dist/forge-isolate.d.ts",
+      "import": "./dist/forge-isolate.js"
     }
   },
   "types": "./dist/index.d.ts",
@@ -41,10 +45,11 @@
     "node": ">=22.16"
   },
   "dependencies": {
-    "@alisio/sdk": "0.5.2",
+    "@alisio/sdk": "0.7.0",
     "@mixmark-io/domino": "2.2.0",
     "@modelcontextprotocol/client": "2.1.0",
     "ajv": "8.20.0",
+    "quickjs-wasi": "3.6.2",
     "turndown": "7.2.4",
     "yaml": "2.9.1",
     "zod": "4.6.5"