@alisio/core 0.1.0-alpha.20 → 0.1.0-alpha.22

package/dist/artifacts/store.js

@@ -0,0 +1,581 @@
+/**
+ * Published artifacts: staging → scan → validate → classify → copy → manifest → row. A tool never
+ * publishes a folder in place: files are COPIED into `<root>/artifacts/<workspaceKey>/<root
+ * session>/<slug>--<id>/files/`, next to a public `manifest.json` without absolute paths or code.
+ * Publishing several outputs is all-or-nothing: on any rejection no folder and no row remains.
+ */
+import { createHash } from "node:crypto";
+import { constants, createReadStream, createWriteStream } from "node:fs";
+import { copyFile, lstat, mkdir, open, readdir, readFile, realpath, rename, rm, writeFile, } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { newId } from "../runtime/ids.js";
+import { inside, workspaceKey } from "../runtime/paths.js";
+import { writeZip } from "../runtime/zip.js";
+import { classifyArtifact, isPreviewable } from "./kinds.js";
+export const DEFAULT_ARTIFACT_LIMITS = {
+    maxFiles: 200,
+    maxFileBytes: 100 * 1024 * 1024,
+    maxOutputBytes: 500 * 1024 * 1024,
+};
+/** A rejected publication: the message is user-readable and names the offending path. */
+export class ArtifactRejected extends Error {
+}
+const MAX_DEPTH = 8;
+const HEAD_BYTES = 8192;
+/** `title` → `[a-z0-9-]`, at most 48 characters (`artifact` when nothing remains). */
+export function slugify(title) {
+    const slug = title
+        .normalize("NFKD")
+        .replace(/[̀-ͯ]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48)
+        .replace(/-+$/, "");
+    return slug || "artifact";
+}
+/** Validates one relative path component list; returns the NFC-normalized relative path. */
+function checkName(rel) {
+    const parts = rel.split(/[\\/]/);
+    if (parts.length > MAX_DEPTH)
+        throw new ArtifactRejected(`${rel}: nested deeper than ${MAX_DEPTH} levels`);
+    for (const part of parts) {
+        if (!part || part === "." || part === "..")
+            throw new ArtifactRejected(`${rel}: relative path components are not allowed`);
+        if (part.startsWith(".") && part !== ".nojekyll")
+            throw new ArtifactRejected(`${rel}: hidden files are not published`);
+        if (/[\u0000-\u001f\u007f]/.test(part))
+            throw new ArtifactRejected(`${rel}: control characters in file names`);
+    }
+    return parts.map((part) => part.normalize("NFC")).join("/");
+}
+async function sha256File(path) {
+    const hash = createHash("sha256");
+    for await (const chunk of createReadStream(path))
+        hash.update(chunk);
+    return hash.digest("hex");
+}
+/** The first bytes of a file (the sample `classifyArtifact` needs). */
+export async function readHead(path) {
+    const handle = await open(path, "r");
+    try {
+        const buffer = Buffer.alloc(HEAD_BYTES);
+        const { bytesRead } = await handle.read(buffer, 0, HEAD_BYTES, 0);
+        return buffer.subarray(0, bytesRead);
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Relative `src`/`href` references of an HTML page that point to files not in the set. */
+function missingReferences(html, entryDir, present) {
+    const missing = new Set();
+    for (const match of html.matchAll(/\b(?:src|href)\s*=\s*["']([^"'#?]+)/gi)) {
+        const ref = match[1]?.trim() ?? "";
+        if (!ref || /^[a-z][a-z0-9+.-]*:/i.test(ref) || ref.startsWith("/") || ref.startsWith("//"))
+            continue;
+        const joined = join(entryDir, decodeURIComponentSafe(ref)).split(sep).join("/");
+        if (!present.has(joined))
+            missing.add(ref);
+    }
+    return [...missing];
+}
+const decodeURIComponentSafe = (value) => {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+};
+const row = (r) => {
+    const provenance = JSON.parse(String(r.provenance ?? "{}"));
+    return {
+        id: String(r.id),
+        sessionId: String(r.root_session),
+        title: String(r.title),
+        fileName: String(r.file_name),
+        kind: String(r.kind),
+        mimeType: String(r.mime),
+        bytes: Number(r.bytes),
+        fileCount: Number(r.file_count),
+        previewable: !!provenance.previewable,
+        createdAt: Number(r.created_at),
+        ...(provenance.partial ? { partial: true } : {}),
+        status: String(r.status),
+        ...(r.entry != null ? { entry: String(r.entry) } : {}),
+        ...(r.execution_id != null ? { executionId: String(r.execution_id) } : {}),
+        ...(r.run_id != null ? { runId: String(r.run_id) } : {}),
+        ...(r.call_id != null ? { callId: String(r.call_id) } : {}),
+        provenance,
+        relDir: String(r.rel_dir),
+    };
+};
+/** The public part of a record (what the SDK `ArtifactRef` carries). */
+export const toRef = (record) => ({
+    id: record.id,
+    sessionId: record.sessionId,
+    title: record.title,
+    fileName: record.fileName,
+    kind: record.kind,
+    mimeType: record.mimeType,
+    bytes: record.bytes,
+    fileCount: record.fileCount,
+    previewable: record.previewable,
+    createdAt: record.createdAt,
+    ...(record.partial ? { partial: true } : {}),
+    status: record.status,
+});
+export class ArtifactStore {
+    options;
+    limits;
+    now;
+    constructor(options) {
+        this.options = options;
+        this.limits = { ...DEFAULT_ARTIFACT_LIMITS, ...options.limits };
+        this.now = options.now ?? Date.now;
+    }
+    get root() {
+        return this.options.root;
+    }
+    /** Session folder of an owner (artifacts of child sessions live with their root). */
+    sessionDir(owner) {
+        return join(this.options.root, "artifacts", workspaceKey(owner.workspace), owner.rootSessionId);
+    }
+    /**
+     * Publishes the outputs a script left in `staging`: the entries of `staging/outputs.json`, or
+     * else every top-level file (and every top-level folder; with `index.html` a multi-file
+     * dashboard, otherwise one ZIP archive). Everything or nothing is published.
+     */
+    async publishOutputs(staging, owner, defaults = {}) {
+        const candidates = [];
+        const declared = join(staging, "outputs.json");
+        let manifest;
+        try {
+            manifest = JSON.parse(await readFile(declared, "utf8"));
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw new ArtifactRejected(`outputs.json is not valid JSON: ${error instanceof Error ? error.message : error}`);
+        }
+        if (manifest !== undefined) {
+            const list = manifest.artifacts;
+            if (!Array.isArray(list))
+                throw new ArtifactRejected('outputs.json must be { "artifacts": [{ "path": … }] }');
+            for (const item of list) {
+                const entry = item;
+                if (typeof entry.path !== "string" || !entry.path)
+                    throw new ArtifactRejected("outputs.json: every artifact needs a relative path");
+                const rel = checkName(entry.path.replace(/\\/g, "/"));
+                if (rel === "outputs.json")
+                    throw new ArtifactRejected("outputs.json cannot publish itself");
+                candidates.push({
+                    source: resolve(staging, rel),
+                    sourceRel: rel,
+                    ...(typeof entry.title === "string" && entry.title.trim()
+                        ? { title: entry.title.trim() }
+                        : {}),
+                    ...(typeof entry.entry === "string" ? { entry: entry.entry } : {}),
+                });
+            }
+        }
+        else {
+            for (const name of (await readdir(staging)).sort()) {
+                if (name === "outputs.json")
+                    continue;
+                candidates.push({ source: join(staging, name), sourceRel: name });
+            }
+        }
+        if (candidates.length === 1 && defaults.title && candidates[0] && !candidates[0].title)
+            candidates[0].title = defaults.title;
+        for (const candidate of candidates)
+            if (!inside(staging, candidate.source))
+                throw new ArtifactRejected(`${candidate.sourceRel}: outside the output folder`);
+        return this.publishAll(candidates, owner);
+    }
+    /** Publishes one caller-owned file or directory. */
+    async publish(input, owner) {
+        const [published] = await this.publishAll([
+            {
+                source: resolve(input.source),
+                ...(input.title ? { title: input.title } : {}),
+                ...(input.entry ? { entry: input.entry } : {}),
+            },
+        ], owner);
+        return published;
+    }
+    /** Publishes a single text file the caller holds in memory. */
+    async publishText(input, owner) {
+        const name = checkName(basename(input.fileName.replace(/\\/g, "/")));
+        const scratch = join(this.options.root, "artifacts", ".incoming", newId("txt"));
+        await mkdir(scratch, { recursive: true });
+        try {
+            const file = join(scratch, name);
+            await writeFile(file, input.text, { flag: "wx" });
+            return await this.publish({ source: file, ...(input.title ? { title: input.title } : {}) }, owner);
+        }
+        finally {
+            await rm(scratch, { recursive: true, force: true });
+        }
+    }
+    async scan(candidate) {
+        const label = candidate.sourceRel ?? basename(candidate.source);
+        let stats;
+        try {
+            stats = await lstat(candidate.source);
+        }
+        catch {
+            throw new ArtifactRejected(`${label}: not found`);
+        }
+        const check = (rel, s) => {
+            if (s.isSymbolicLink())
+                throw new ArtifactRejected(`${rel}: symbolic links are not published`);
+            if (s.isFile() && s.nlink > 1)
+                throw new ArtifactRejected(`${rel}: hard-linked files are not published`);
+            if (!s.isFile() && !s.isDirectory())
+                throw new ArtifactRejected(`${rel}: only regular files and folders are published`);
+        };
+        check(label, stats);
+        if (stats.isFile()) {
+            const rel = checkName(basename(candidate.source));
+            return {
+                candidate,
+                files: [{ rel, abs: candidate.source, bytes: stats.size }],
+                directory: false,
+            };
+        }
+        const files = [];
+        const walk = async (dir, prefix, depth) => {
+            if (depth > MAX_DEPTH)
+                throw new ArtifactRejected(`${label}: nested deeper than ${MAX_DEPTH} levels`);
+            for (const name of (await readdir(dir)).sort()) {
+                const abs = join(dir, name);
+                const rel = prefix ? `${prefix}/${name}` : name;
+                const s = await lstat(abs);
+                check(`${label}/${rel}`, s);
+                const normalized = checkName(rel);
+                if (s.isDirectory())
+                    await walk(abs, normalized, depth + 1);
+                else
+                    files.push({ rel: normalized, abs, bytes: s.size });
+                if (files.length > this.limits.maxFiles)
+                    throw new ArtifactRejected(`${label}: more than ${this.limits.maxFiles} files (analysis.limits.maxFiles)`);
+            }
+        };
+        await walk(candidate.source, "", 1);
+        if (!files.length)
+            throw new ArtifactRejected(`${label}: the folder is empty`);
+        const names = new Set(files.map((f) => f.rel));
+        if (names.size !== files.length)
+            throw new ArtifactRejected(`${label}: two files have the same normalized name`);
+        const entry = candidate.entry
+            ? checkName(candidate.entry.replace(/\\/g, "/"))
+            : names.has("index.html")
+                ? "index.html"
+                : undefined;
+        if (entry && !names.has(entry))
+            throw new ArtifactRejected(`${label}: entry ${entry} does not exist in the folder`);
+        return { candidate, files, directory: true, ...(entry ? { entry } : {}) };
+    }
+    async publishAll(candidates, owner) {
+        if (!candidates.length)
+            return [];
+        // 1. Scan and validate everything before writing anything.
+        const plans = [];
+        let total = 0, count = 0;
+        for (const candidate of candidates) {
+            const plan = await this.scan(candidate);
+            for (const file of plan.files) {
+                if (file.bytes > this.limits.maxFileBytes)
+                    throw new ArtifactRejected(`${file.rel}: larger than ${this.limits.maxFileBytes} bytes (analysis.limits.maxFileBytes)`);
+                total += file.bytes;
+            }
+            count += plan.files.length;
+            plans.push(plan);
+        }
+        if (count > this.limits.maxFiles)
+            throw new ArtifactRejected(`${count} files exceed the limit of ${this.limits.maxFiles} (analysis.limits.maxFiles)`);
+        if (total > this.limits.maxOutputBytes)
+            throw new ArtifactRejected(`${total} bytes exceed the limit of ${this.limits.maxOutputBytes} (analysis.limits.maxOutputBytes)`);
+        // Idempotency: a source already published by this execution is returned as is.
+        const existing = new Map();
+        if (owner.executionId)
+            for (const plan of plans) {
+                if (!plan.candidate.sourceRel)
+                    continue;
+                const found = this.options.db
+                    .prepare("SELECT * FROM artifacts WHERE execution_id=? AND source_path=?")
+                    .get(owner.executionId, plan.candidate.sourceRel);
+                if (found)
+                    existing.set(plan.candidate.source, row(found));
+            }
+        // 2. Build each artifact in a temporary sibling folder, then rename them all into place.
+        const sessionDir = this.sessionDir(owner);
+        await mkdir(sessionDir, { recursive: true });
+        const built = [];
+        const results = [];
+        try {
+            for (const plan of plans) {
+                const known = existing.get(plan.candidate.source);
+                if (known) {
+                    results.push({ artifact: toRef(known), path: this.localPath(known), warnings: [] });
+                    continue;
+                }
+                const item = await this.build(plan, owner, sessionDir);
+                built.push(item);
+                results.push({ artifact: toRef(item.record), path: item.path, warnings: item.warnings });
+            }
+            for (const item of built)
+                await rename(item.temp, item.final);
+            // 3. Register every row in one transaction.
+            this.options.db.transaction(() => {
+                for (const { record } of built)
+                    this.options.db
+                        .prepare(`INSERT INTO artifacts(id,session,root_session,workspace,run_id,call_id,execution_id,
+                 source_path,title,file_name,kind,mime,bytes,file_count,sha256,entry,rel_dir,status,
+                 provenance,created_at)
+               VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`)
+                        .run(record.id, owner.sessionId, owner.rootSessionId, owner.workspace, owner.runId ?? null, owner.callId ?? null, owner.executionId ?? null, record.provenance.sourcePath ?? null, record.title, record.fileName, record.kind, record.mimeType, record.bytes, record.fileCount, String(record.provenance.sha256 ?? ""), record.entry ?? null, record.relDir, "ready", JSON.stringify(record.provenance), record.createdAt);
+            });
+        }
+        catch (error) {
+            for (const item of built) {
+                await rm(item.temp, { recursive: true, force: true });
+                await rm(item.final, { recursive: true, force: true });
+            }
+            throw error;
+        }
+        // The final path replaces the temporary folder in every returned location.
+        return results.map((result) => {
+            const item = built.find((b) => b.record.id === result.artifact.id);
+            return item ? { ...result, path: item.path.replace(item.temp, item.final) } : result;
+        });
+    }
+    async build(plan, owner, sessionDir) {
+        const id = newId("art", this.now());
+        const label = plan.candidate.sourceRel ?? basename(plan.candidate.source);
+        const baseName = basename(plan.candidate.source);
+        const title = plan.candidate.title ??
+            (plan.directory ? baseName : baseName.replace(/\.[^.]+$/, "") || baseName);
+        const folder = `${slugify(title)}--${id}`;
+        const temp = join(sessionDir, `.tmp-${id}`);
+        const final = join(sessionDir, folder);
+        const filesDir = join(temp, "files");
+        await mkdir(filesDir, { recursive: true });
+        const warnings = [];
+        let kind, mimeType, fileName, entry, files;
+        try {
+            if (!plan.directory || plan.entry) {
+                // A file, or a folder with an entry (multi-file dashboard): copy verbatim.
+                files = [];
+                for (const file of plan.files) {
+                    const target = join(filesDir, ...file.rel.split("/"));
+                    await mkdir(dirname(target), { recursive: true });
+                    await copyFile(file.abs, target, constants.COPYFILE_EXCL);
+                    files.push({ path: file.rel, bytes: file.bytes, sha256: await sha256File(target) });
+                }
+                if (!plan.directory) {
+                    const only = files[0];
+                    const type = classifyArtifact(only.path, await readHead(join(filesDir, only.path)));
+                    kind = type.kind;
+                    mimeType = type.mimeType;
+                    fileName = only.path;
+                }
+                else {
+                    entry = plan.entry;
+                    const type = classifyArtifact(entry, await readHead(join(filesDir, ...entry.split("/"))));
+                    kind = type.kind;
+                    mimeType = type.mimeType;
+                    fileName = files.length > 1 ? `${baseName}.zip` : basename(entry);
+                    if (type.kind === "dashboard") {
+                        const html = await readFile(join(filesDir, ...entry.split("/")), "utf8");
+                        const entryDir = entry.includes("/") ? entry.slice(0, entry.lastIndexOf("/")) : "";
+                        const missing = missingReferences(html, entryDir, new Set(files.map((f) => f.path)));
+                        if (missing.length)
+                            warnings.push(`${label}: ${entry} references missing files: ${missing.join(", ")}`);
+                    }
+                }
+            }
+            else {
+                // A folder without an entry: one ZIP archive of its files.
+                fileName = `${baseName}.zip`;
+                const target = join(filesDir, fileName);
+                const out = createWriteStream(target, { flags: "wx" });
+                const done = new Promise((resolveDone, reject) => {
+                    out.once("finish", resolveDone);
+                    out.once("error", reject);
+                });
+                await writeZip(plan.files.map((file) => ({ name: file.rel, source: file.abs })), out);
+                out.end();
+                await done;
+                const { size } = await lstat(target);
+                if (size > this.limits.maxFileBytes)
+                    throw new ArtifactRejected(`${label}: the archive exceeds analysis.limits.maxFileBytes`);
+                files = [{ path: fileName, bytes: size, sha256: await sha256File(target) }];
+                kind = "archive";
+                mimeType = "application/zip";
+            }
+        }
+        catch (error) {
+            await rm(temp, { recursive: true, force: true });
+            throw error;
+        }
+        const bytes = files.reduce((sum, file) => sum + file.bytes, 0);
+        const setHash = createHash("sha256")
+            .update([...files]
+            .sort((a, b) => a.path.localeCompare(b.path))
+            .map((f) => `${f.sha256}  ${f.path}\n`)
+            .join(""))
+            .digest("hex");
+        const type = { kind, mimeType };
+        const previewable = kind !== "file" &&
+            (entry ? isPreviewable(entry, type, bytes) : isPreviewable(fileName, type, bytes));
+        const createdAt = this.now();
+        const provenance = {
+            sessionId: owner.sessionId,
+            ...(owner.runId ? { runId: owner.runId } : {}),
+            ...(owner.callId ? { callId: owner.callId } : {}),
+            ...(owner.executionId ? { executionId: owner.executionId } : {}),
+            ...(owner.provenance ?? {}),
+            partial: !!owner.partial,
+        };
+        const manifest = {
+            schemaVersion: 1,
+            id,
+            title,
+            fileName,
+            kind,
+            mimeType,
+            ...(entry ? { entry } : {}),
+            files,
+            bytes,
+            sha256: setHash,
+            createdAt,
+            provenance,
+        };
+        await writeFile(join(temp, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+        const record = {
+            id,
+            sessionId: owner.rootSessionId,
+            title,
+            fileName,
+            kind,
+            mimeType,
+            bytes,
+            fileCount: files.length,
+            previewable,
+            createdAt,
+            ...(owner.partial ? { partial: true } : {}),
+            status: "ready",
+            ...(entry ? { entry } : {}),
+            ...(owner.executionId ? { executionId: owner.executionId } : {}),
+            ...(owner.runId ? { runId: owner.runId } : {}),
+            ...(owner.callId ? { callId: owner.callId } : {}),
+            // Stored only in the row (not the manifest): the idempotency key and flags for listings.
+            provenance: {
+                ...provenance,
+                previewable,
+                sha256: setHash,
+                ...(plan.candidate.sourceRel ? { sourcePath: plan.candidate.sourceRel } : {}),
+            },
+            relDir: relative(this.options.root, final),
+        };
+        const local = join(temp, "files", ...(entry ?? fileName).split("/"));
+        return { record, path: local, warnings, temp, final };
+    }
+    /** Artifacts of a root session, newest first. */
+    list(rootSessionId, options = {}) {
+        const limit = Math.max(1, Math.min(500, options.limit ?? 100));
+        const rows = this.options.db
+            .prepare(`SELECT * FROM artifacts WHERE root_session=?
+           AND (? IS NULL OR kind=?) AND (? IS NULL OR created_at<?)
+           AND (? = 1 OR status='ready' OR (? = 1 AND status='expired'))
+         ORDER BY created_at DESC, id DESC LIMIT ?`)
+            .all(rootSessionId, options.kind ?? null, options.kind ?? null, options.before ?? null, options.before ?? null, options.includeDeleted ? 1 : 0, options.includeExpired ? 1 : 0, limit);
+        return rows.map(row);
+    }
+    get(id) {
+        const found = this.options.db.prepare("SELECT * FROM artifacts WHERE id=?").get(id);
+        return found ? row(found) : undefined;
+    }
+    /** Absolute folder holding `manifest.json` and `files/`. */
+    folder(record) {
+        return join(this.options.root, record.relDir);
+    }
+    /** Absolute path of the file (or the entry of a multi-file artifact). */
+    localPath(record) {
+        return join(this.folder(record), "files", ...(record.entry ?? record.fileName).split("/"));
+    }
+    /** Files of an artifact from its manifest, with absolute paths (inside `files/`). */
+    async files(record) {
+        const manifest = JSON.parse(await readFile(join(this.folder(record), "manifest.json"), "utf8"));
+        const root = join(this.folder(record), "files");
+        return manifest.files.map((file) => {
+            const abs = join(root, ...file.path.split("/"));
+            if (!inside(root, abs))
+                throw new ArtifactRejected(`${file.path}: outside the artifact`);
+            return { ...file, abs };
+        });
+    }
+    /**
+     * One file of a ready artifact by its manifest path (`files/` only, never `manifest.json`):
+     * the path must be listed in the manifest and its real path must stay inside `files/`.
+     */
+    async resolveFile(record, path) {
+        if (record.status !== "ready")
+            return undefined;
+        const wanted = path.replace(/\\/g, "/").normalize("NFC");
+        let files;
+        try {
+            files = await this.files(record);
+        }
+        catch {
+            return undefined;
+        }
+        const file = files.find((candidate) => candidate.path === wanted);
+        if (!file)
+            return undefined;
+        try {
+            const root = await realpath(join(this.folder(record), "files"));
+            const real = await realpath(file.abs);
+            if (!inside(root, real) || real === root)
+                return undefined;
+            const info = await lstat(real);
+            return info.isFile() ? { ...file, abs: real, bytes: info.size } : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Retention: marks a `ready` artifact `expired` and removes its folder; the row stays so cards
+     * and listings keep showing it as `Expired`. False when it is not `ready`.
+     */
+    async markExpired(id) {
+        const record = this.get(id);
+        if (!record || record.status !== "ready")
+            return false;
+        this.options.db
+            .prepare("UPDATE artifacts SET status='expired', deleted_at=? WHERE id=? AND status='ready'")
+            .run(this.now(), id);
+        await rm(this.folder(record), { recursive: true, force: true });
+        return true;
+    }
+    /** Ready artifacts created before `cutoff` (epoch ms), oldest first (for the retention sweep). */
+    readyBefore(cutoff) {
+        return this.options.db
+            .prepare("SELECT * FROM artifacts WHERE status='ready' AND created_at<? ORDER BY created_at")
+            .all(cutoff).map(row);
+    }
+    /** Marks an artifact deleted and removes its folder (the row stays for references). */
+    async delete(id) {
+        const record = this.get(id);
+        if (!record || record.status !== "ready")
+            return false;
+        this.options.db
+            .prepare("UPDATE artifacts SET status='deleted', deleted_at=? WHERE id=?")
+            .run(this.now(), id);
+        await rm(this.folder(record), { recursive: true, force: true });
+        return true;
+    }
+}

package/dist/commands/builtins.js

@@ -110,6 +110,19 @@ export const BUILTIN_COMMANDS = [
         surfaces: ALL,
         execution: "core",
     },
+    {
+        name: "artifacts",
+        description: "Browse this session's artifacts",
+        argumentHint: "[filter]",
+        surfaces: INTERACTIVE,
+        execution: "surface",
+    },
+    {
+        name: "permissions",
+        description: "Review and revoke this session's saved permissions",
+        surfaces: INTERACTIVE,
+        execution: "surface",
+    },
     {
         name: "exit",
         description: "Exit Alisio",

package/dist/commands/catalog.js

@@ -1,4 +1,4 @@
-import { agentCatalogFromState, resolveActiveAgent } from "../agents/active.js";
+import { agentCatalogFromState, agentCommandDescriptors, resolveActiveAgent, } from "../agents/active.js";
 import { formatSideQuestion, SIDE_QUESTION_DESCRIPTION, SIDE_QUESTION_USAGE, } from "../sessions/side-questions.js";
 import { BUILTIN_COMMANDS } from "./builtins.js";
 export { BUILTIN_COMMANDS };
@@ -259,6 +259,18 @@ export class CommandCatalog {
                     surfaces: [...ALL],
                     execution: "surface",
                 });
+        // `/agent:<id>` activates a loaded agent (built-ins, project and global agent files).
+        if (host?.plugins) {
+            let state;
+            try {
+                state = host.plugins.pluginState?.("subagents", "mainAgents");
+            }
+            catch {
+                /* agent contributions are best-effort */
+            }
+            for (const descriptor of agentCommandDescriptors(agentCatalogFromState(state), taken))
+                push(descriptor);
+        }
         return surface ? out.filter((c) => c.surfaces.includes(surface)) : out;
     }
     /** A command by name or alias (built-in names and aliases are case-insensitive). */