@alisio/core 0.5.2 → 0.6.0

package/dist/forge/nested.js

@@ -0,0 +1,214 @@
+import { OPT_IN_TOOLS, optInAllows } from "../core/opt-in.js";
+import { decideEffect, effectOf } from "../permissions/decide.js";
+import { isForgeError } from "./errors.js";
+import { forgeCallId } from "./journal.js";
+import { hasScratchEstimator, scratchIncomingBytes } from "./scratch-quota.js";
+/**
+ * Tools no script can reach in v1: Forja's own tools and `execute` (no recursion), the guide
+ * (a model-facing tool), and the subagent tools (`task`, `task_wait` and `send_message` can wait
+ * on a child session that is waiting for this very call: D-29), and `ask_user_question` (the only
+ * tool that opens an interactive prompt; approvals and installs are already refused). Opt-in tools (`OPT_IN_TOOLS`) are
+ * excluded as well.
+ */
+export const FORGE_EXCLUDED_TOOLS = new Set([
+    "js_run",
+    "forge_guide",
+    "task",
+    "task_wait",
+    "send_message",
+    "execute",
+    // Opens an interactive prompt; a script has nobody to ask (D7: never a new approval or UI).
+    "ask_user_question",
+]);
+const isPlainObject = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+const messageOf = (error) => error instanceof Error ? error.message : String(error);
+export function createNestedDispatcher(deps) {
+    let counter = 0;
+    /** The tool when this run lets a script reach it, else undefined (excluded, filtered, absent). */
+    const reachable = (name) => {
+        if (FORGE_EXCLUDED_TOOLS.has(name) || OPT_IN_TOOLS.has(name))
+            return undefined;
+        let tool;
+        try {
+            tool = deps.registry.get(name);
+        }
+        catch {
+            return undefined;
+        }
+        if (deps.toolFilter && !deps.toolFilter(tool))
+            return undefined;
+        if (!optInAllows(name, deps.optInTools))
+            return undefined;
+        return tool;
+    };
+    const decide = (tool, approvals) => decideEffect(deps.policy, tool, { approvals, capabilityGranted: false });
+    const allInScratch = async (targets) => {
+        const access = deps.pathAccess;
+        if (!access || targets.length === 0)
+            return false;
+        const inside = await Promise.all(targets.map((t) => access.isScratchPath(t, deps.session)));
+        return inside.every(Boolean);
+    };
+    return {
+        knows(name) {
+            try {
+                deps.registry.get(name);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        catalog() {
+            return deps.registry
+                .list()
+                .filter((tool) => reachable(tool.name) && decide(tool, false).kind === "allow");
+        },
+        async call(request) {
+            const nestedCallId = forgeCallId(deps.parentCallId, ++counter);
+            const fail = (code, message, effect) => ({
+                ok: false,
+                nestedCallId,
+                code,
+                message,
+                ...(effect ? { effect } : {}),
+            });
+            const name = request.name;
+            if (typeof name !== "string" || name === "")
+                return fail("TOOL_UNAVAILABLE", "tool name must be a non-empty string");
+            const tool = reachable(name);
+            if (!tool)
+                return fail("TOOL_UNAVAILABLE", `Tool "${name}" is not available from js_run`);
+            const effect = effectOf(tool);
+            const rawInput = request.input === undefined ? {} : request.input;
+            if (!isPlainObject(rawInput))
+                return fail("TOOL_INPUT_INVALID", "tool input must be a JSON object", effect);
+            let input;
+            try {
+                input = deps.registry.parse(name, JSON.stringify(rawInput));
+            }
+            catch (error) {
+                return fail("TOOL_INPUT_INVALID", messageOf(error), effect);
+            }
+            const signal = request.signal ? AbortSignal.any([deps.signal, request.signal]) : deps.signal;
+            // Declared paths are resolved first, like a direct call, but can never ask for a directory.
+            const resolved = new Map();
+            const targets = [];
+            try {
+                signal.throwIfAborted();
+                if (deps.pathAccess)
+                    for (const declared of tool.paths?.(input) ?? [])
+                        if (!resolved.has(declared)) {
+                            const target = await deps.pathAccess.resolve(declared, {
+                                workspace: deps.workspace,
+                                session: deps.session,
+                                ...(deps.label ? { label: deps.label } : {}),
+                                signal,
+                                interactive: false,
+                            });
+                            resolved.set(declared, target);
+                            resolved.set(target, target);
+                            targets.push(target);
+                        }
+            }
+            catch (error) {
+                if (signal.aborted)
+                    return fail("CANCELLED", "cancelled", effect);
+                return fail("PERMISSION_DENIED", messageOf(error), effect);
+            }
+            try {
+                deps.guard?.(effect);
+            }
+            catch (error) {
+                return fail("PERMISSION_DENIED", messageOf(error), effect);
+            }
+            if (decide(tool, false).kind !== "allow") {
+                // Same answer as a direct call: "would ask" is APPROVAL_REQUIRED, "never allowed" is denied.
+                const direct = decide(tool, deps.approvals);
+                // The scratchpad is an authorized write root: a write confined to it needs no approval,
+                // also when nobody could be asked (headless).
+                const scratchWrite = deps.scratchWrites !== false &&
+                    effect === "write" &&
+                    !tool.capability &&
+                    hasScratchEstimator(name) &&
+                    decide(tool, true).kind === "ask" &&
+                    (await allInScratch(targets));
+                if (!scratchWrite)
+                    return direct.kind === "ask"
+                        ? fail("APPROVAL_REQUIRED", `"${name}" needs approval (effect: ${effect}); a script cannot request one. ` +
+                            "Call it directly or ask the user to allow it for this session.", effect)
+                        : fail("PERMISSION_DENIED", `Capability denied: ${tool.capability ?? effect}`, effect);
+            }
+            // A write confined to the scratchpad is bound by its quota, however it was allowed. The check
+            // and the write run under one lock, so parallel writes cannot all pass it (L1).
+            let releaseScratch;
+            try {
+                if (effect === "write" && !tool.capability && (await allInScratch(targets))) {
+                    releaseScratch = await deps.pathAccess?.lockScratch(deps.session);
+                    const problem = await deps.pathAccess?.scratchQuotaProblem(deps.session, await scratchIncomingBytes(name, input, targets), targets);
+                    if (problem)
+                        return fail("BUDGET_EXCEEDED", problem, effect);
+                }
+                // From here the tool may leave effects, even if the script is then cancelled.
+                if (effect !== "read" && effect !== "internal")
+                    deps.markEffectful();
+                request.onStart?.({ nestedCallId, name, effect, paths: targets });
+                const context = {
+                    signal,
+                    workspace: deps.workspace,
+                    emit: () => { },
+                    session: deps.session,
+                    callId: deps.parentCallId,
+                    ...(deps.runId ? { runId: deps.runId } : {}),
+                    ...(deps.label ? { label: deps.label } : {}),
+                    ...(deps.artifacts ? { artifacts: deps.artifacts } : {}),
+                    ...(deps.decisions ? { decisions: deps.decisions } : {}),
+                    // A script can never open the installation prompt.
+                    approveInstall: async () => "deny",
+                    ...(deps.pathAccess
+                        ? {
+                            resolvePath: (path) => {
+                                const known = resolved.get(path);
+                                return known !== undefined
+                                    ? Promise.resolve(known)
+                                    : deps.pathAccess.resolve(path, {
+                                        workspace: deps.workspace,
+                                        session: deps.session,
+                                        ...(deps.label ? { label: deps.label } : {}),
+                                        signal,
+                                        interactive: false,
+                                    });
+                            },
+                        }
+                        : {}),
+                };
+                let result;
+                try {
+                    result = await tool.execute(input, context);
+                }
+                catch (error) {
+                    if (signal.aborted)
+                        return fail("CANCELLED", "cancelled", effect);
+                    return fail(isForgeError(error) ? error.code : "TOOL_FAILED", messageOf(error), effect);
+                }
+                const text = result.content
+                    .filter((part) => part.type === "text")
+                    .map((part) => part.text)
+                    .join("\n");
+                if (result.isError)
+                    return fail("TOOL_FAILED", text, effect);
+                let value = text;
+                try {
+                    value = JSON.parse(text);
+                }
+                catch {
+                    /* Not JSON: the text itself is the value. */
+                }
+                return { ok: true, nestedCallId, effect, text, value, result };
+            }
+            finally {
+                releaseScratch?.();
+            }
+        },
+    };
+}

package/dist/forge/ports.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Ports of the Forja core (hexagonal). Engines, hosts, transports and stores are adapters; the
+ * core never depends on QuickJS, Pyodide, Docker or SQLite. Types only: no runtime code.
+ *
+ * Later phases add the remaining ports (`IsolateHost`, `Transport`, `ExecutionJournal`,
+ * `StateStore`, `GuideProvider`) next to these.
+ */
+import type { EngineDescriptor, EngineId, EngineLanguage, IsolationLevel, PermissionMode } from "@alisio/sdk";
+import type { ForgeErrorCode } from "./errors.ts";
+import type { ForgeLimits } from "./limits.ts";
+import type { GuestMessage, HostMessage } from "./protocol.ts";
+export type { EngineDescriptor, EngineId, EngineLanguage, IsolationLevel };
+export interface ExecutionRequest {
+    language: EngineLanguage;
+    source: string;
+    title?: string;
+    /** Can only lower the effective limits. */
+    requestedLimits?: Partial<ForgeLimits>;
+    /** Configured or forced by the user; never chosen by the model. */
+    engineHint?: EngineId;
+    /** Per-engine extensions (inputs, extras, rerunOf...). */
+    payload?: Record<string, unknown>;
+}
+/**
+ * Built only by the core from the runner's tool context. No field of the model's input can
+ * override it.
+ */
+export interface TrustedExecutionContext {
+    executionId: string;
+    toolCallId: string;
+    rootSessionId: string;
+    workspace: string;
+    permissionMode: PermissionMode;
+    allowAnalysis: boolean;
+    allowProcess: boolean;
+    signal: AbortSignal;
+    limits: ForgeLimits;
+}
+/** An execution ready to run; engines extend it with their own handles. */
+export interface PreparedExecution {
+    readonly executionId: string;
+    readonly engine: EngineId;
+    readonly limits: ForgeLimits;
+    /** The `analysis_executions` row this execution created (Python); the journal links to it. */
+    readonly analysisExecutionId?: string;
+}
+export type TerminationReason = "cancelled" | "timeout" | "protocol_violation" | "limit_exceeded";
+export interface TerminationReport {
+    /** The host checked that the guest no longer runs. */
+    confirmed: boolean;
+    method: "interrupt" | "terminate" | "kill" | "container-kill";
+    elapsedMs: number;
+    /** Resolves once the guest is finally gone; lets an unconfirmed termination keep its slot until then. */
+    settled?: Promise<void>;
+}
+export type EngineOutcome = {
+    kind: "completed";
+    value?: unknown;
+} | {
+    kind: "failed";
+    code: ForgeErrorCode;
+    message: string;
+};
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+/** A message for the guest without the envelope fields the transport stamps (`protocol`, `seq`). */
+export type HostReply = DistributiveOmit<HostMessage, "protocol" | "seq">;
+/**
+ * The kernel's side of an execution, handed to the engine's `run`. The engine owns the transport
+ * and the isolate; the kernel decides what each guest message means.
+ */
+export interface KernelChannel {
+    /**
+     * Called by the engine for every guest message that passed validation (schema, sequence,
+     * correlation, size, capability gate), CONCURRENTLY: a slow `call` never blocks the next
+     * message. The optional reply goes to the guest. Throwing a `ForgeError` ends the execution with
+     * that code.
+     */
+    receive(message: GuestMessage): Promise<HostReply | undefined>;
+    /** Called once by the engine with the function that sends a message to the guest (credit grants). */
+    bind(send: (reply: HostReply) => void): void;
+    /** Aborted when the kernel stops the execution (cancellation or deadline). */
+    readonly signal: AbortSignal;
+}
+/** Isolation hosts (spec §6.3, D-20): where the VM runs, and how it is stopped. */
+export interface IsolateExit {
+    code: number | null;
+    signal: string | null;
+    /** Spawn or worker error, when the isolate could not run at all. */
+    error?: string;
+}
+export interface IsolateSession {
+    readonly kind: "worker" | "process";
+    /** Raw guest messages; validation is the engine's job. */
+    onMessage(handler: (raw: unknown) => void): void;
+    /** The stream broke (oversized or malformed frame): a protocol violation. */
+    onStreamError(handler: (reason: string) => void): void;
+    send(message: unknown): void;
+    readonly exited: Promise<IsolateExit>;
+    /** Stops the guest by the host's own means and reports whether it is confirmed gone. */
+    stop(reason: TerminationReason): Promise<TerminationReport>;
+}
+export interface IsolateHost {
+    readonly kind: "worker" | "process";
+    /** Starts an isolate. The guest sends `ready` first; nothing runs until the host sends `start`. */
+    start(): IsolateSession;
+}
+export interface ExecutionEngine {
+    readonly id: EngineId;
+    describe(): Promise<EngineDescriptor>;
+    prepare(request: ExecutionRequest, ctx: TrustedExecutionContext): Promise<PreparedExecution>;
+    run(prepared: PreparedExecution, channel: KernelChannel): Promise<EngineOutcome>;
+    terminate(prepared: PreparedExecution, reason: TerminationReason): Promise<TerminationReport>;
+    /**
+     * Optional step between `run` and the commit of the shared state, for engines whose results must
+     * be published first (Python's artifacts). It runs only when the host did not stop the execution,
+     * and may turn a completed outcome into a failed one: a failure discards the state delta.
+     */
+    collect?(prepared: PreparedExecution, outcome: EngineOutcome): Promise<EngineOutcome>;
+    dispose(prepared: PreparedExecution): Promise<void>;
+}

package/dist/forge/ports.js

@@ -0,0 +1 @@
+export {};

package/dist/forge/progress.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Progress coalescing (spec §5.4, D14): at most 4 progress events per second reach the UI, but a
+ * terminal event (a finished call, the end of a phase) is never dropped. Non-terminal events that
+ * arrive too soon are replaced by the newest one of their category (script progress, a call
+ * starting, anything else) and delivered when that category's window reopens, so a burst of
+ * calls never hides the script's own progress. Pure but for the injected clock and timer.
+ */
+import type { ForgeProgress } from "@alisio/sdk";
+export declare const PROGRESS_INTERVAL_MS = 250;
+export interface ProgressClock {
+    now(): number;
+    /** Schedules `run` after `ms` and returns how to cancel it. */
+    schedule(run: () => void, ms: number): () => void;
+}
+export declare class ProgressCoalescer {
+    #private;
+    constructor(sink: (progress: ForgeProgress) => void, clock?: ProgressClock);
+    /** A progress event that may be replaced by a newer one of its category. */
+    update(progress: ForgeProgress): void;
+    /** An event that must reach the UI: delivered now, after anything still waiting. */
+    terminal(progress: ForgeProgress): void;
+    /** Delivers what is waiting and stops the timers. */
+    close(): void;
+}

package/dist/forge/progress.js

@@ -0,0 +1,76 @@
+export const PROGRESS_INTERVAL_MS = 250;
+const realClock = {
+    now: () => Date.now(),
+    schedule(run, ms) {
+        const timer = setTimeout(run, ms);
+        timer.unref?.();
+        return () => clearTimeout(timer);
+    },
+};
+const categoryOf = (progress) => progress.phase === "call"
+    ? "call"
+    : progress.message !== undefined ||
+        progress.completed !== undefined ||
+        progress.total !== undefined
+        ? "progress"
+        : "other";
+export class ProgressCoalescer {
+    #sink;
+    #clock;
+    #lanes = new Map();
+    #order = 0;
+    constructor(sink, clock = realClock) {
+        this.#sink = sink;
+        this.#clock = clock;
+    }
+    /** A progress event that may be replaced by a newer one of its category. */
+    update(progress) {
+        const category = categoryOf(progress);
+        let lane = this.#lanes.get(category);
+        if (!lane) {
+            lane = { lastAt: Number.NEGATIVE_INFINITY };
+            this.#lanes.set(category, lane);
+        }
+        const wait = lane.lastAt + PROGRESS_INTERVAL_MS - this.#clock.now();
+        if (wait <= 0 && lane.pending === undefined)
+            return this.#deliver(lane, progress);
+        lane.pending = { progress, order: this.#order++ };
+        const owner = lane;
+        lane.cancel ??= this.#clock.schedule(() => {
+            owner.cancel = undefined;
+            this.#flushLane(owner);
+        }, Math.max(wait, 0));
+    }
+    /** An event that must reach the UI: delivered now, after anything still waiting. */
+    terminal(progress) {
+        this.#flush();
+        this.#sink(progress);
+    }
+    /** Delivers what is waiting and stops the timers. */
+    close() {
+        this.#flush();
+    }
+    /** Everything waiting, in arrival order. */
+    #flush() {
+        const waiting = [];
+        for (const lane of this.#lanes.values()) {
+            lane.cancel?.();
+            lane.cancel = undefined;
+            if (lane.pending)
+                waiting.push({ lane, ...lane.pending });
+            lane.pending = undefined;
+        }
+        for (const item of waiting.sort((a, b) => a.order - b.order))
+            this.#deliver(item.lane, item.progress);
+    }
+    #flushLane(lane) {
+        const pending = lane.pending;
+        lane.pending = undefined;
+        if (pending)
+            this.#deliver(lane, pending.progress);
+    }
+    #deliver(lane, progress) {
+        lane.lastAt = this.#clock.now();
+        this.#sink(progress);
+    }
+}

package/dist/forge/protocol.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The common Forja protocol (spec §5.4, D10): one logical message schema over several transports.
+ * This module is the host-side validator of what the guest sends. Shape is checked with Ajv; the
+ * stateful rules (sequence, call correlation, terminal closure, capability gate) are plain code.
+ * Every rejection is a `PROTOCOL_VIOLATION` and the caller terminates the execution.
+ */
+import type { EngineId } from "@alisio/sdk";
+import { ForgeError, type ForgeErrorCode } from "./errors.ts";
+import type { GuestLimits } from "./limits.ts";
+export declare const MAX_MESSAGE_BYTES: number;
+/** The registry's naming rule (`ToolRegistry.register`); the protocol refuses any other name. */
+export declare const TOOL_NAME_PATTERN = "^[a-zA-Z0-9_-]{1,64}$";
+export declare const MAX_JSON_DEPTH = 32;
+export type ForgeOutputItem = {
+    type: "text";
+    text: string;
+} | {
+    type: "json";
+    value: unknown;
+};
+export interface Envelope<T extends string, P> {
+    protocol: 1;
+    type: T;
+    /** Strictly increasing per direction. */
+    seq: number;
+    payload: P;
+}
+/** Guest to host. */
+export type GuestMessage = Envelope<"ready", {
+    engine: EngineId;
+    preludeHash: string;
+}> | Envelope<"progress", {
+    message: string;
+    completed?: number;
+    total?: number;
+}> | Envelope<"output", ForgeOutputItem> | Envelope<"state.set", {
+    key: string;
+    value: unknown;
+}> | Envelope<"state.delete", {
+    key: string;
+}>
+/** Only when the engine's `capabilities.toolCalls` is true. */
+ | Envelope<"call", {
+    callId: number;
+    tool: string;
+    input: unknown;
+}> | Envelope<"catalog", {
+    requestId: number;
+    op: "search" | "describe";
+    query: string;
+    limit?: number;
+}> | Envelope<"complete", {
+    value?: unknown;
+}> | Envelope<"fatal", {
+    code: ForgeErrorCode;
+    message: string;
+}>;
+/** Host to guest. */
+export type HostMessage = Envelope<"start", {
+    source: string;
+    state: Record<string, unknown>;
+    limits: GuestLimits;
+    catalogSize: number;
+}> | Envelope<"result", {
+    callId: number;
+    ok: true;
+    value: unknown;
+} | {
+    callId: number;
+    ok: false;
+    error: {
+        code: ForgeErrorCode;
+        message: string;
+    };
+}> | Envelope<"catalog.result", {
+    requestId: number;
+    entries: unknown[];
+}>
+/** Backpressure credits. */
+ | Envelope<"grant", {
+    calls: number;
+    bytes: number;
+}>;
+export type GuestMessageType = GuestMessage["type"];
+export type GuestValidation = {
+    ok: true;
+    message: GuestMessage;
+} | {
+    ok: false;
+    error: ForgeError;
+};
+export type Correlation = {
+    ok: true;
+} | {
+    ok: false;
+    error: ForgeError;
+};
+export declare class GuestMessageValidator {
+    #private;
+    constructor(options: {
+        toolCalls: boolean;
+    });
+    /** Validates one guest message. Any violation closes the validator for good. */
+    accept(raw: unknown): GuestValidation;
+    /** Marks a call as answered by the host; unknown or already answered ids are violations. */
+    resolveCall(callId: number): Correlation;
+    resolveCatalog(requestId: number): Correlation;
+    /** The execution reached a terminal state: nothing more is accepted. */
+    close(): void;
+}