@alisio/core 0.1.0-alpha.16 → 0.1.0-alpha.18

package/dist/commands/catalog.js

@@ -0,0 +1,268 @@
+import { agentCatalogFromState, resolveActiveAgent } from "../agents/active.js";
+import { BUILTIN_COMMANDS } from "./builtins.js";
+export { BUILTIN_COMMANDS };
+const builtinDescriptor = (c) => ({
+    name: c.name,
+    description: c.description,
+    ...(c.aliases ? { aliases: [...c.aliases] } : {}),
+    ...(c.argumentHint ? { argumentHint: c.argumentHint } : {}),
+    source: "builtin",
+    surfaces: [...c.surfaces],
+    execution: c.execution,
+});
+const ALL = ["tui", "web", "api"];
+/** Root sessions of this workspace bound to the current provider, newest first (as the TUI). */
+const workspaceSessions = (host) => host.store
+    .list()
+    .filter((s) => s.workspace === host.workspace && s.provider === host.provider.id);
+const firstPrompt = (host, id) => {
+    const first = host.store.messages(id).find((m) => m.role === "user" && !m.summary);
+    return first?.role === "user" ? first.text.replace(/\s+/g, " ").slice(0, 60) : "";
+};
+const HANDLERS = {
+    async tools(_args, _ctx, host) {
+        const policy = host.runner.policy;
+        const rows = host.registry
+            .list()
+            .map((t) => {
+            const effect = t.effect ?? "external";
+            const state = effect === "read" || effect === "internal" || policy[effect]
+                ? "enabled"
+                : host.runner.approvals && (effect === "write" || effect === "process")
+                    ? "ask"
+                    : "disabled";
+            return `| \`${t.name}\` | ${effect} | ${state} |`;
+        })
+            .join("\n");
+        return {
+            text: `**Tools**\n\n| Tool | Effect | State |\n| --- | --- | --- |\n${rows}\n\n\`ask\` prompts before running (allow once / session / deny). Use --allow-write / --allow-process to pre-allow; --read-only disables them. Paths outside the workspace ask per directory; pre-allow with --add-dir or the \`additionalDirectories\` config key. \`internal\` tools (built-in plugins) only write Alisio's own state.`,
+        };
+    },
+    async sessions(_args, ctx, host) {
+        const list = workspaceSessions(host).slice(0, 20);
+        if (!list.length)
+            return { text: "No sessions in this workspace", tone: "notice" };
+        return {
+            text: [
+                "**Recent sessions** (use `/resume <id-prefix>`)",
+                "",
+                ...list.map((s) => `- \`${s.id}\` ${s.id === ctx.sessionId ? "**(current)** " : ""}${s.model} · ${host.store.messages(s.id).length} msgs · ${firstPrompt(host, s.id) || "_empty_"}`),
+            ].join("\n"),
+            data: list,
+        };
+    },
+    async resume(args, _ctx, host) {
+        const target = args.trim();
+        if (!target)
+            throw new Error("Usage: /resume <id>");
+        const matches = workspaceSessions(host).filter((s) => s.id.startsWith(target));
+        if (matches.length !== 1)
+            throw new Error(matches.length
+                ? `Ambiguous session prefix: ${target}`
+                : `No session in this workspace matches ${target}`);
+        const found = matches[0];
+        return { text: `Resumed session ${found.id}`, tone: "notice", sessionId: found.id };
+    },
+    async clear(_args, ctx, host) {
+        const model = host.store.get(ctx.sessionId).model;
+        const created = host.store.create(host.workspace, host.provider.id, model);
+        return { text: `New session ${created.id}`, tone: "notice", sessionId: created.id };
+    },
+    async compact(args, ctx, host) {
+        const result = await host.runner.compact(ctx.sessionId, {
+            ...(args.trim() ? { focus: args.trim() } : {}),
+            ...(ctx.signal ? { signal: ctx.signal } : {}),
+        });
+        return result
+            ? {
+                text: `Compacted ${result.replaced} messages: ~${result.before} → ~${result.after} tokens`,
+                tone: "notice",
+                data: result,
+            }
+            : { text: "Not enough history to compact", tone: "notice" };
+    },
+    async model(args, ctx, host) {
+        const model = args.trim();
+        if (!model)
+            throw new Error("Usage: /model <model id>");
+        host.runner.setModel(ctx.sessionId, model);
+        return { text: `Model set to \`${model}\``, tone: "notice", data: { model } };
+    },
+    async effort(args, _ctx, host) {
+        const level = args.trim();
+        if (!level)
+            return {
+                text: `Reasoning effort: ${host.config?.agents.effort ?? "model default"}`,
+                tone: "notice",
+            };
+        if (!host.updateSetting)
+            throw new Error("Effort changes are unavailable here");
+        const value = level === "!clear" ? undefined : level;
+        await host.updateSetting("agents.effort", value);
+        return {
+            text: value ? `Reasoning effort set to ${value}` : "Reasoning effort cleared",
+            tone: "notice",
+            data: { effort: value },
+        };
+    },
+    async stats(_args, ctx, host) {
+        const session = host.store.get(ctx.sessionId);
+        const runs = host.store.runs?.(ctx.sessionId) ?? [];
+        const tokens = runs.reduce((sum, r) => ({
+            input: sum.input + (r.usage?.input ?? 0),
+            output: sum.output + (r.usage?.output ?? 0),
+        }), { input: 0, output: 0 });
+        return {
+            text: [
+                "**Session statistics**",
+                "",
+                `- Session: \`${session.id}\``,
+                `- Model: \`${session.model}\``,
+                `- Messages: ${host.store.messages(session.id).length}`,
+                `- Runs: ${runs.length}`,
+                `- Tokens: in ${tokens.input} · out ${tokens.output}`,
+            ].join("\n"),
+            data: { session, runs: runs.length, tokens },
+        };
+    },
+    async skills(_args, _ctx, host) {
+        const skills = host.skillCatalog?.() ?? [];
+        if (!skills.length)
+            return { text: "No skills found", tone: "notice" };
+        const state = (s) => s.effective ? "enabled" : s.shadowedBy ? `shadowed by ${s.shadowedBy}` : "disabled";
+        return {
+            text: `**Skills**\n\n| Skill | Scope | State |\n| --- | --- | --- |\n${skills
+                .map((s) => `| \`${s.displayId}\` | ${s.scope} | ${state(s)} |`)
+                .join("\n")}`,
+            data: skills,
+        };
+    },
+    async plugins(_args, _ctx, host) {
+        const plugins = host.pluginCatalog?.() ?? [];
+        if (!plugins.length)
+            return { text: "No plugins loaded", tone: "notice" };
+        return {
+            text: `**Plugins**\n\n| Plugin | Status | Enabled |\n| --- | --- | --- |\n${plugins
+                .map((p) => `| \`${p.id}\` | ${p.status} | ${p.enabled ? "yes" : "no"} |`)
+                .join("\n")}`,
+            data: plugins,
+        };
+    },
+    async mcp(_args, _ctx, host) {
+        const servers = host.mcp?.list() ?? [];
+        if (!servers.length)
+            return { text: "No MCP servers configured", tone: "notice" };
+        return {
+            text: `**MCP servers**\n\n| Server | Status | Tools |\n| --- | --- | --- |\n${servers
+                .map((s) => `| \`${s.name}\` | ${s.status} | ${s.counts.tools} |`)
+                .join("\n")}`,
+            data: servers,
+        };
+    },
+    async agents(args, ctx, host) {
+        // With arguments, `/agents <verb>` belongs to the subagents plugin's own command (as in the
+        // TUI); without them it lists the active-agent catalog.
+        const plugin = args.trim() ? host.plugins?.commands.get("agents") : undefined;
+        if (plugin)
+            return { text: await plugin(args.trim(), { sessionId: ctx.sessionId }) };
+        let state;
+        try {
+            state = host.plugins?.pluginState?.("subagents", "mainAgents");
+        }
+        catch {
+            /* agent contributions are best-effort */
+        }
+        const agents = agentCatalogFromState(state);
+        const active = resolveActiveAgent(agents, host.config?.agents.active);
+        return {
+            text: [
+                "**Agents**",
+                "",
+                ...agents.map((a) => `- **${a.name}**${a.id === active.id ? " (current)" : ""}${a.readOnly ? " · read-only" : ""} — ${a.description}`),
+            ].join("\n"),
+            data: { agents, active: active.id },
+        };
+    },
+};
+export class CommandCatalog {
+    host;
+    constructor(host) {
+        this.host = host;
+    }
+    builtins() {
+        return BUILTIN_COMMANDS.map(builtinDescriptor);
+    }
+    /** Every descriptor (optionally for one surface). Precedence: builtin > plugin > prompt > skill. */
+    list(surface) {
+        const out = this.builtins();
+        const taken = new Set(out.flatMap((c) => [c.name, ...(c.aliases ?? [])]));
+        const push = (descriptor) => {
+            if (taken.has(descriptor.name))
+                return;
+            taken.add(descriptor.name);
+            out.push(descriptor);
+        };
+        const host = this.host;
+        if (host?.plugins)
+            for (const [name, info] of host.plugins.commandInfo)
+                push({
+                    name,
+                    description: info.description ?? `plugin ${info.plugin}`,
+                    ...(info.argumentHint ? { argumentHint: info.argumentHint } : {}),
+                    source: "plugin",
+                    owner: info.plugin,
+                    surfaces: [...ALL],
+                    execution: "core",
+                });
+        if (host?.prompts)
+            for (const template of host.prompts.templates.values())
+                push({
+                    name: template.name,
+                    description: template.description,
+                    ...(template.argumentHint ? { argumentHint: template.argumentHint } : {}),
+                    source: "prompt",
+                    owner: template.source,
+                    surfaces: [...ALL],
+                    execution: "surface",
+                });
+        for (const skill of host?.skillCatalog?.() ?? [])
+            if (skill.effective && skill.enabled)
+                push({
+                    name: `skill:${skill.id}`,
+                    description: skill.description,
+                    source: "skill",
+                    ...(skill.owner ? { owner: skill.owner.id } : {}),
+                    surfaces: [...ALL],
+                    execution: "surface",
+                });
+        return surface ? out.filter((c) => c.surfaces.includes(surface)) : out;
+    }
+    /** A command by name or alias (built-in names and aliases are case-insensitive). */
+    resolve(name) {
+        const lower = name.toLowerCase();
+        const all = this.list();
+        return (all.find((c) => c.source === "builtin" && (c.name === lower || c.aliases?.includes(lower))) ??
+            all.find((c) => c.source !== "builtin" && c.name === name));
+    }
+    /** Runs an `execution: "core"` command. Surface commands and unknown names throw. */
+    async execute(name, args, ctx) {
+        const descriptor = this.resolve(name);
+        if (!descriptor)
+            throw new Error(`Unknown command /${name}. Type /help.`);
+        if (descriptor.execution !== "core")
+            throw new Error(`/${descriptor.name} is handled by each surface, not by the core catalog`);
+        const host = this.host;
+        if (!host)
+            throw new Error(`/${descriptor.name} needs an application host`);
+        if (descriptor.source === "plugin") {
+            const handler = host.plugins?.commands.get(descriptor.name);
+            if (!handler)
+                throw new Error(`Unknown plugin command: ${descriptor.name}`);
+            return { text: await handler(args, { sessionId: ctx.sessionId }) };
+        }
+        const handler = HANDLERS[descriptor.name];
+        if (!handler)
+            throw new Error(`/${descriptor.name} has no core handler`);
+        return handler(args, ctx, host);
+    }
+}

package/dist/config.d.ts

@@ -36,6 +36,7 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
     }, z.core.$strict>>;
     plugins: z.ZodDefault<z.ZodArray<z.ZodString>>;
     skills: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    additionalDirectories: z.ZodDefault<z.ZodArray<z.ZodString>>;
     skillOverrides: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         enabled: z.ZodBoolean;
     }, z.core.$strict>>>;
@@ -175,6 +176,7 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
     }, z.core.$strip>>;
     tui: z.ZodDefault<z.ZodObject<{
         paddingX: z.ZodDefault<z.ZodNumber>;
+        contentPaddingX: z.ZodDefault<z.ZodNumber>;
         skillSlashCommands: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strict>>;
     agents: z.ZodDefault<z.ZodObject<{
@@ -195,6 +197,7 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
     };
     plugins: string[];
     skills: string[];
+    additionalDirectories: string[];
     skillOverrides: Record<string, {
         enabled: boolean;
     }>;
@@ -234,6 +237,7 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
     };
     tui: {
         paddingX: number;
+        contentPaddingX: number;
         skillSlashCommands: boolean;
     };
     agents: {
@@ -284,6 +288,7 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
     };
     plugins: string[];
     skills: string[];
+    additionalDirectories: string[];
     skillOverrides: Record<string, {
         enabled: boolean;
     }>;
@@ -376,6 +381,7 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
     };
     tui: {
         paddingX: number;
+        contentPaddingX: number;
         skillSlashCommands: boolean;
     };
     agents: {
@@ -454,6 +460,7 @@ declare const SETTABLE_KEYS: {
     readonly "limits.timeoutMs": z.ZodDefault<z.ZodNumber>;
     readonly "pluginHooks.timeoutMs": z.ZodDefault<z.ZodNumber>;
     readonly "tui.paddingX": z.ZodDefault<z.ZodNumber>;
+    readonly "tui.contentPaddingX": z.ZodDefault<z.ZodNumber>;
     readonly "tui.skillSlashCommands": z.ZodDefault<z.ZodBoolean>;
     readonly "websearch.provider": z.ZodOptional<z.ZodEnum<{
         brave: "brave";
@@ -469,6 +476,13 @@ declare const SETTABLE_KEYS: {
 };
 export type SettableSettingKey = keyof typeof SETTABLE_KEYS;
 export declare function isSettableSettingKey(key: string): key is SettableSettingKey;
+export interface SettableSettingInfo {
+    key: SettableSettingKey;
+    kind: "boolean" | "number" | "string" | "enum";
+    options?: string[];
+}
+/** Every settable key with its value kind (and enum options), for settings editors. */
+export declare function settableSettings(): SettableSettingInfo[];
 /**
  * Atomically sets one user-facing setting in the global config file (`<config home>/config.json`)
  * while preserving every unrelated JSON field. The value is validated against the same zod leaf

package/dist/config.js

@@ -1,4 +1,4 @@
-import { chmod, mkdir, open, readFile, rename, unlink } from "node:fs/promises";
+import { chmod, mkdir, open, readFile, realpath, rename, unlink } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { z } from "zod";
@@ -81,6 +81,12 @@ const configObjectSchema = z
     provider: providerSchema.default(() => providerSchema.parse({})),
     plugins: z.array(z.string()).default([]),
     skills: z.array(z.string()).default([]),
+    /**
+     * Extra directories the mediated path policy may touch outside the workspace. Resolved
+     * relative to the defining configuration file and canonicalized on load. Additive across
+     * layers like `plugins`/`skills`: a lower layer can only ADD, never clear the global list.
+     */
+    additionalDirectories: z.array(z.string().trim().min(1)).default([]),
     /** Project-local enable/disable overrides for effective non-plugin skills. */
     skillOverrides: z.record(z.string(), z.object({ enabled: z.boolean() }).strict()).default({}),
     mcp: z
@@ -178,8 +184,15 @@ const configObjectSchema = z
     })),
     tui: z
         .object({
-        /** Horizontal padding (columns) around the editor input box. */
+        /** Horizontal padding (columns) around the editor input box. Editor-only. */
         paddingX: z.number().int().min(0).max(4).default(1),
+        /**
+         * Horizontal inset (columns) applied to each side of the transcript content, so
+         * agent-written rows keep breathing room from the window borders. Independent of
+         * `paddingX` (which styles only the editor input box). Clamped on narrow terminals so the
+         * content column never collapses below a usable width.
+         */
+        contentPaddingX: z.number().int().min(0).max(12).default(2),
         /**
          * Offer effective skills as first-class `skill:<id>` editor slash-autocomplete entries.
          * Off hides those entries; the `/skills` manager and its argument completion stay available.
@@ -187,7 +200,7 @@ const configObjectSchema = z
         skillSlashCommands: z.boolean().default(true),
     })
         .strict()
-        .default(() => ({ paddingX: 1, skillSlashCommands: true })),
+        .default(() => ({ paddingX: 1, contentPaddingX: 2, skillSlashCommands: true })),
     /**
      * The ACTIVE agent drives the main session: its system prompt is appended to every prompt and
      * its optional model selector is offered when the agent is chosen (`/agents`). `build` is the
@@ -237,6 +250,26 @@ function isUsableLegacyModel(model) {
     const normalized = model.trim();
     return normalized !== "" && normalized !== LEGACY_PROVIDER_MODEL_PLACEHOLDER;
 }
+/**
+ * Appends the entries of `selected` after the `global` list, dropping exact duplicates so the
+ * global entries keep their order and the selected layer only ever ADDS to the collection. An
+ * empty `selected` list therefore leaves the global list intact. Entries were already resolved
+ * per layer by `parseLayer`, so deduplication happens on the resolved strings.
+ */
+function mergeUnique(global, selected) {
+    const seen = new Set(global);
+    const merged = [...global];
+    for (const entry of selected)
+        if (!seen.has(entry)) {
+            seen.add(entry);
+            merged.push(entry);
+        }
+    return merged;
+}
+/** Absolute, canonical directory when it exists; a missing path keeps its resolved absolute form. */
+async function canonicalDirectory(path) {
+    return realpath(path).catch(() => resolve(path));
+}
 /**
  * Whether legacy provider selection should take priority over a saved plugin profile for this
  * run: an explicit endpoint override, or a trusted project/explicit layer whose parsed root
@@ -269,6 +302,9 @@ export async function loadConfigWithProvenance(workspace, options = {}) {
         const raw = (await readJson(file)) ?? {};
         const config = configSchema.parse(raw);
         config.skills = config.skills.map((p) => resolve(file, "..", p));
+        // Extra tool roots are paths relative to the config file; canonicalize so containment checks
+        // compare real directories (a symlinked root never escapes its declared location).
+        config.additionalDirectories = await Promise.all(config.additionalDirectories.map((p) => canonicalDirectory(resolve(file, "..", p))));
         // Plugin entries are paths (relative to the config file) or npm package names.
         config.plugins = config.plugins.map((p) => (isPathSpec(p) ? resolve(file, "..", p) : p));
         for (const server of Object.values(config.mcp.servers))
@@ -310,8 +346,44 @@ export async function loadConfigWithProvenance(workspace, options = {}) {
         for (const key of selected.keys) {
             if (key === "mcp" || key === "mcpServers")
                 continue;
-            if (key in selected.config)
-                overlaid[key] = selected.config[key];
+            if (!(key in selected.config))
+                continue;
+            // Additive collections: the selected layer ADDS to the global list (global entries
+            // first, exact duplicates dropped); an empty selected list never clears the global one.
+            if (key === "plugins") {
+                overlaid.plugins = mergeUnique(overlaid.plugins, selected.config.plugins);
+                continue;
+            }
+            if (key === "skills") {
+                overlaid.skills = mergeUnique(overlaid.skills, selected.config.skills);
+                continue;
+            }
+            if (key === "additionalDirectories") {
+                overlaid.additionalDirectories = mergeUnique(overlaid.additionalDirectories, selected.config.additionalDirectories);
+                continue;
+            }
+            // Additive records: merge by key, the selected layer wins per key.
+            if (key === "pluginOverrides") {
+                overlaid.pluginOverrides = {
+                    ...overlaid.pluginOverrides,
+                    ...selected.config.pluginOverrides,
+                };
+                continue;
+            }
+            if (key === "skillOverrides") {
+                // Global skill overrides were reset above (skill activation is project-local); the
+                // selected overrides still merge into that empty record and win per key.
+                overlaid.skillOverrides = { ...overlaid.skillOverrides, ...selected.config.skillOverrides };
+                continue;
+            }
+            if (key === "builtinPlugins") {
+                // Per-plugin options merge by plugin id: the selected entry wins per id, so
+                // `{id: {enabled: false}}` in the selected layer still disables that built-in while
+                // every other global entry stays.
+                overlaid.builtinPlugins = { ...overlaid.builtinPlugins, ...selected.config.builtinPlugins };
+                continue;
+            }
+            overlaid[key] = selected.config[key];
         }
         if (selected.keys.has("mcp") || selected.keys.has("mcpServers"))
             // Only servers merge upward; `mcp.allow` is a global/user preference and is deliberately
@@ -470,6 +542,7 @@ const SETTABLE_KEYS = {
     "limits.timeoutMs": SETTABLE_SECTIONS.limits.shape.timeoutMs,
     "pluginHooks.timeoutMs": SETTABLE_SECTIONS.pluginHooks.shape.timeoutMs,
     "tui.paddingX": SETTABLE_SECTIONS.tui.shape.paddingX,
+    "tui.contentPaddingX": SETTABLE_SECTIONS.tui.shape.contentPaddingX,
     "tui.skillSlashCommands": SETTABLE_SECTIONS.tui.shape.skillSlashCommands,
     "websearch.provider": SETTABLE_SECTIONS.websearch.shape.provider,
     "agents.active": SETTABLE_SECTIONS.agents.shape.active,
@@ -478,6 +551,33 @@ const SETTABLE_KEYS = {
 export function isSettableSettingKey(key) {
     return Object.prototype.hasOwnProperty.call(SETTABLE_KEYS, key);
 }
+/** Unwraps optional/default/nullable wrappers down to the value schema. */
+function settingLeaf(schema) {
+    let current = schema;
+    for (let depth = 0; depth < 8; depth++) {
+        const type = current.def?.type;
+        if ((type === "optional" || type === "default" || type === "nullable") &&
+            current.def?.innerType)
+            current = current.def.innerType;
+        else
+            break;
+    }
+    return current;
+}
+/** Every settable key with its value kind (and enum options), for settings editors. */
+export function settableSettings() {
+    return Object.keys(SETTABLE_KEYS).map((key) => {
+        const leaf = settingLeaf(SETTABLE_KEYS[key]);
+        const type = leaf.def?.type;
+        if (type === "enum")
+            return { key, kind: "enum", options: (leaf.options ?? []).map((o) => String(o)) };
+        if (type === "boolean")
+            return { key, kind: "boolean" };
+        if (type === "number" || type === "int")
+            return { key, kind: "number" };
+        return { key, kind: "string" };
+    });
+}
 /**
  * Atomically sets one user-facing setting in the global config file (`<config home>/config.json`)
  * while preserving every unrelated JSON field. The value is validated against the same zod leaf

package/dist/core/contracts.d.ts

@@ -18,6 +18,10 @@ export interface Session {
     options?: Record<string, unknown>;
     createdAt?: number;
     updatedAt?: number;
+    /** Root sessions pinned in web clients (v4). */
+    pinned?: boolean;
+    /** When a root session was archived in web clients (v4); absent when not archived. */
+    archivedAt?: number;
 }
 export interface ChildSessionRecord {
     id?: string;
@@ -30,6 +34,82 @@ export interface ChildSessionRecord {
     depth: number;
     options: Record<string, unknown>;
 }
+/** `queued` and `running` are the only non-terminal run states. */
+export type RunStatus = "queued" | "running" | "completed" | "turns_exceeded" | "failed" | "cancelled" | "interrupted";
+export type TerminalRunStatus = Exclude<RunStatus, "queued" | "running">;
+/** One `AgentRunner.run` execution (v4 `runs` table). `id` equals `RunEvent.runId`. */
+export interface RunRecord {
+    id: string;
+    session: string;
+    status: RunStatus;
+    /** Client idempotency key; absent for TUI/headless runs. */
+    requestId?: string;
+    correlationId?: string;
+    /** Process that executes (or executed) the run, for startup reconciliation. */
+    ownerPid?: number;
+    model?: string;
+    createdAt: number;
+    startedAt?: number;
+    endedAt?: number;
+    error?: string;
+    usage?: {
+        input: number;
+        output: number;
+        cachedInput?: number;
+    };
+}
+export interface BeginRunInput {
+    id: string;
+    session: string;
+    /** `queued` for scheduled runs, `running` (default) when execution starts now. */
+    status?: "queued" | "running";
+    requestId?: string;
+    correlationId?: string;
+    model?: string;
+}
+export interface EndRunInput {
+    status: TerminalRunStatus;
+    error?: string;
+    usage?: {
+        input: number;
+        output: number;
+        cachedInput?: number;
+    };
+}
+export interface PageOptions {
+    /** Only rows with a sequence greater than this (ascending from there). */
+    after?: number;
+    /** Only rows with a sequence lower than this (the newest `limit` of them). */
+    before?: number;
+    limit?: number;
+}
+export interface MessagePage {
+    items: Array<{
+        seq: number;
+        message: Message;
+        compacted: boolean;
+    }>;
+    /** More rows exist beyond the page in the paging direction. */
+    hasMore: boolean;
+}
+export interface StoredEvent {
+    /** Global `events.seq` as a string (same value as `RunEvent.eventId`). */
+    eventId: string;
+    runId: string;
+    type: string;
+    data: unknown;
+    createdAt?: number;
+    correlationId?: string;
+}
+export interface EventPage {
+    items: StoredEvent[];
+    hasMore: boolean;
+}
+/** Optional tool-call metadata (v4 columns); stores may ignore it. */
+export interface ToolCallMeta {
+    runId?: string;
+    effect?: string;
+}
 export interface SessionStore {
     create(workspace: string, provider: string, model: string): Session;
     get(id: string): Session;
@@ -64,12 +144,39 @@ export interface SessionStore {
     overwrite(id: string, messages: Message[]): void;
     acquire(id: string): void;
     release(id: string): void;
-    beginCall(session: string, call: ToolCall): void;
+    beginCall(session: string, call: ToolCall, meta?: ToolCallMeta): void;
     endCall(session: string, call: ToolCall, result: ToolResult): void;
     /** The persisted result of a completed tool call, for replay of rich (ui/image) parts. */
     callResult(session: string, callId: string): ToolResult | undefined;
     reconcile(id: string, acknowledge?: boolean): void;
-    event(id: string, runId: string, type: string, data: unknown): void;
+    /**
+     * Persist a durable run event. Stores that assign a global, monotonic sequence return it; the
+     * runner exposes it as `RunEvent.eventId`. Returning nothing is allowed (no `eventId`).
+     */
+    event(id: string, runId: string, type: string, data: unknown, meta?: {
+        correlationId?: string;
+    }): number | void;
+    /**
+     * Records a run, or moves an existing `queued` run with the same id to `running`. A run whose
+     * `(session, requestId)` already exists is returned as is (`created: false`): idempotency.
+     */
+    beginRun?(input: BeginRunInput): {
+        run: RunRecord;
+        created: boolean;
+    };
+    /** Moves a non-terminal run to a terminal state; terminal runs are never overwritten. */
+    endRun?(id: string, input: EndRunInput): void;
+    runByRequest?(session: string, requestId: string): RunRecord | undefined;
+    /** Runs of a session, newest first. */
+    runs?(session: string, options?: {
+        limit?: number;
+    }): RunRecord[];
+    messagesPage?(session: string, options?: PageOptions & {
+        compacted?: boolean;
+    }): MessagePage;
+    eventsPage?(session: string, options?: PageOptions): EventPage;
+    /** Marks queued/running runs whose owner process is not alive as interrupted. */
+    interruptRuns?(): number;
 }
 export interface ContextSource {
     /** System instructions; `sessionId` scopes lazily attached nested instructions. */

package/dist/core/runner.d.ts

@@ -1,4 +1,5 @@
 import { type Attachment, type Message, type ModelProvider, type RunEvent, type ToolDefinition } from "@alisio/sdk";
+import type { PathAccess } from "../runtime/access.ts";
 import type { ApprovalHandler, ContextSource, Policy, RunnerExtensions, SessionStore } from "./contracts.ts";
 import type { ToolRegistry } from "./registry.ts";
 export interface CompactionSettings {
@@ -34,6 +35,11 @@ export interface RunnerOptions {
     compaction?: CompactionSettings;
     /** When set, write/process tools not allowed by the policy are offered and ask first. */
     approve?: ApprovalHandler;
+    /**
+     * Mediated path policy (workspace plus declared extra directories and external approval).
+     * When set, declared tool paths outside the allowed roots ask before the effect gate runs.
+     */
+    pathAccess?: PathAccess;
     /** Generic hooks (implemented by the plugin host) for compaction and session start. */
     extensions?: RunnerExtensions;
     /**
@@ -87,6 +93,10 @@ export interface RunOptions {
     timeoutMs?: number;
     /** Reasoning effort level for this run; beats the runner-level default when set. */
     reasoningEffort?: string;
+    /** Run id to use for this run's events (e.g. preassigned by an embedder); a UUID otherwise. */
+    runId?: string;
+    /** Copied to every event of this run as `RunEvent.correlationId` (e.g. an HTTP request id). */
+    correlationId?: string;
 }
 /**
  * Default cumulative token budget for one run: several context windows (each turn re-sends the