@alisio/server 0.1.0-alpha.1

package/dist/routes/commands.js

@@ -0,0 +1,149 @@
+import { CommandCatalog } from "@alisio/core";
+import { readJson } from "../http/body.js";
+import { HttpError } from "../http/errors.js";
+import { is, validate } from "../schemas.js";
+import { RecentRequests } from "./prompts.js";
+/** Commands that change the session's own run state: refused while it runs or compacts. */
+const EXCLUSIVE = new Set(["model", "compact"]);
+/**
+ * The `/ask` prompt: the TUI sends the same instruction (packages/cli/src/tui/app.ts); both turn
+ * the user's question into a multiple-choice `ask_user_question` call.
+ */
+export const askPrompt = (question) => `The user has a question of their own and wants help turning it into a multiple-choice ` +
+    `question: "${question}"\n\nPropose 2-4 concrete, mutually distinct options that ` +
+    `would resolve it. Mark at most one option "recommended" only if you have a clear, ` +
+    `well-justified opinion; it is a suggestion, never forced on the user. Then ` +
+    `immediately call ask_user_question with exactly one question built from this ` +
+    `(reuse the user's own wording for the question text). Do not answer in plain text ` +
+    `first; call the tool right away.`;
+const helpText = (commands) => [
+    "**Commands**",
+    "",
+    ...commands.map((c) => `- \`/${c.name}${c.argumentHint ? ` ${c.argumentHint}` : ""}\` — ${c.description}${c.aliases?.length ? ` (${c.aliases.map((a) => `/${a}`).join(", ")})` : ""}`),
+    "",
+    "**Keys**: Enter send · Shift+Enter newline · ↑↓ prompt history · `/` focus the composer · Esc close popovers",
+].join("\n");
+/**
+ * The shared slash-command catalog for the web (RF-07): `GET /api/commands` lists the commands
+ * whose surfaces include `web`; `POST /api/sessions/:sid/commands` runs core commands and expands
+ * prompt templates, skills and `/ask` into a prompt the client sends itself.
+ */
+export function registerCommandRoutes(router, ctx) {
+    const { sessions, scheduler } = ctx;
+    const recent = ctx.recent ?? new RecentRequests();
+    const catalogOf = (opened) => new CommandCatalog(opened?.app);
+    router.get("/api/commands", async ({ url }) => {
+        const sid = url.searchParams.get("session");
+        const wid = url.searchParams.get("workspace");
+        let opened;
+        if (sid)
+            opened = await sessions.app(sessions.get(sid));
+        else if (wid) {
+            const path = await ctx.workspaces.pathOf(wid);
+            if (!path)
+                throw new HttpError("not_found", "Workspace not found");
+            opened = await ctx.workspaces.openPath(path);
+        }
+        return { body: catalogOf(opened).list("web") };
+    });
+    router.post("/api/sessions/:sid/commands", async ({ req, params }) => {
+        const session = sessions.get(params.sid ?? "");
+        const input = validate(await readJson(req), {
+            requestId: { check: is.requestId(), required: true },
+            name: { check: is.nonEmpty(200), required: true },
+            args: { check: is.string(100_000) },
+        });
+        if (recent.has(session.id, input.requestId))
+            return { body: { duplicate: true } };
+        const opened = await sessions.app(session);
+        const catalog = catalogOf(opened);
+        const name = input.name.replace(/^\//, "");
+        const descriptor = catalog.resolve(name);
+        if (!descriptor || !descriptor.surfaces.includes("web"))
+            throw new HttpError("unknown_command", `Unknown command /${name}`);
+        const args = (input.args ?? "").trim();
+        const busy = () => scheduler.busy(session.id) ||
+            scheduler.compacting(session.id) ||
+            opened.app.runner.isRunning(session.id);
+        if (EXCLUSIVE.has(descriptor.name) && busy())
+            throw new HttpError("session_busy", `/${descriptor.name} is unavailable while the session runs`);
+        recent.add(session.id, input.requestId);
+        const display = `/${descriptor.name}${args ? ` ${args}` : ""}`;
+        const fail = (error) => {
+            throw new HttpError("validation_failed", error instanceof Error ? error.message : "Command failed", { fields: ["args"] });
+        };
+        let outcome;
+        try {
+            outcome = await run();
+        }
+        catch (error) {
+            if (error instanceof HttpError)
+                throw error;
+            return fail(error);
+        }
+        sessions.notify(session.id);
+        return { body: outcome };
+        async function run() {
+            if (!descriptor)
+                throw new HttpError("unknown_command", `Unknown command /${name}`);
+            if (descriptor.source === "prompt") {
+                const expanded = opened.app.expandPrompt(display);
+                if (!expanded)
+                    throw new HttpError("unknown_command", `Unknown command /${name}`);
+                return { prompt: { text: expanded.text, display: expanded.display } };
+            }
+            if (descriptor.source === "skill") {
+                const skill = await opened.app.skills.load(descriptor.name.slice("skill:".length));
+                return { prompt: { text: `${skill}\n\nUser request: ${args}`, display } };
+            }
+            if (descriptor.name === "help")
+                return { output: helpText(catalog.list("web")) };
+            if (descriptor.name === "ask") {
+                if (!args)
+                    throw new Error("Usage: /ask <question>");
+                return { prompt: { text: askPrompt(args), display } };
+            }
+            if (descriptor.name === "effort") {
+                // Per session on the web (the TUI's /effort changes the global setting).
+                if (!args)
+                    return {
+                        output: `Reasoning effort: ${String(session.options?.effort ?? "model default")}`,
+                        tone: "notice",
+                    };
+                const effort = args === "!clear" ? undefined : args;
+                sessions.setOptions(session.id, { effort });
+                return {
+                    output: effort ? `Reasoning effort set to ${effort}` : "Reasoning effort cleared",
+                    tone: "notice",
+                    effects: ["effort"],
+                };
+            }
+            if (descriptor.name === "compact") {
+                const work = opened.app.runner.compact(session.id, args ? { focus: args } : {});
+                scheduler.track(session.id, opened.id, work, {
+                    onDone: () => sessions.notify(session.id),
+                });
+                sessions.notify(session.id);
+                const result = await work;
+                return result
+                    ? {
+                        output: `Compacted ${result.replaced} messages: ~${result.before} → ~${result.after} tokens`,
+                        tone: "notice",
+                        effects: ["messages"],
+                    }
+                    : { output: "Not enough history to compact", tone: "notice" };
+            }
+            const result = await catalog.execute(descriptor.name, args, { sessionId: session.id });
+            if (result.sessionId && result.sessionId !== session.id)
+                sessions.notify(result.sessionId);
+            return {
+                ...(result.text ? { output: result.text } : {}),
+                ...(result.tone ? { tone: result.tone } : {}),
+                ...(result.sessionId && result.sessionId !== session.id
+                    ? { sessionId: result.sessionId }
+                    : {}),
+                ...(descriptor.name === "model" ? { effects: ["model"] } : {}),
+            };
+        }
+    });
+}

package/dist/routes/events.d.ts

@@ -0,0 +1,14 @@
+import type { SessionService } from "../host/sessions.ts";
+import type { Router } from "../http/router.ts";
+import type { SseHub } from "../sse/hub.ts";
+/**
+ * `GET /api/events?session=<sid>&session=…`: one multiplexed SSE stream per tab. Every
+ * (re)connection gets a full snapshot per session (v1 ignores `Last-Event-ID` beyond that:
+ * the snapshot cursor tells the client which durable events it already has).
+ */
+export declare function registerEventRoutes(router: Router, ctx: {
+    hub: SseHub;
+    sessions: SessionService;
+    maxStreams?: number;
+    maxSessionsPerStream?: number;
+}): void;

package/dist/routes/events.js

@@ -0,0 +1,32 @@
+import { HttpError } from "../http/errors.js";
+/**
+ * `GET /api/events?session=<sid>&session=…`: one multiplexed SSE stream per tab. Every
+ * (re)connection gets a full snapshot per session (v1 ignores `Last-Event-ID` beyond that:
+ * the snapshot cursor tells the client which durable events it already has).
+ */
+export function registerEventRoutes(router, ctx) {
+    const maxStreams = ctx.maxStreams ?? 16;
+    const maxSessions = ctx.maxSessionsPerStream ?? 8;
+    router.get("/api/events", ({ req, res, url }) => {
+        const ids = [...new Set(url.searchParams.getAll("session").filter(Boolean))];
+        if (ids.length > maxSessions)
+            throw new HttpError("validation_failed", `At most ${maxSessions} sessions per stream`, {
+                fields: ["session"],
+            });
+        for (const id of ids)
+            ctx.sessions.get(id);
+        if (ctx.hub.size >= maxStreams)
+            throw new HttpError("stream_limit", `At most ${maxStreams} event streams at once`);
+        res.writeHead(200, {
+            "Content-Type": "text/event-stream; charset=utf-8",
+            "Cache-Control": "no-store",
+            Connection: "keep-alive",
+            "X-Accel-Buffering": "no",
+        });
+        res.flushHeaders();
+        req.socket.setNoDelay(true);
+        const detach = ctx.hub.attach(res, ids);
+        res.on("close", detach);
+        return undefined;
+    });
+}

package/dist/routes/files.d.ts

@@ -0,0 +1,21 @@
+import { type SQLiteStore } from "@alisio/core";
+import type { SessionService } from "../host/sessions.ts";
+import type { WorkspaceHost } from "../host/workspace-host.ts";
+import type { Router } from "../http/router.ts";
+/** Entries per tree page (RF-12). */
+export declare const TREE_PAGE = 1000;
+/** Default and maximum bytes of a previewed file (RF-12: larger files are truncated). */
+export declare const FILE_PREVIEW_BYTES: number;
+/**
+ * Resolves a workspace-relative (or absolute) path inside `root`. `mustExist` also requires the
+ * target to exist (404 otherwise); either way its realpath must stay inside the root (403).
+ */
+export declare function confine(root: string, path: string, mustExist?: boolean): Promise<{
+    abs: string;
+    rel: string;
+}>;
+export declare function registerFileRoutes(router: Router, ctx: {
+    workspaces: WorkspaceHost;
+    catalog: SQLiteStore;
+    sessions: SessionService;
+}): void;

package/dist/routes/files.js

@@ -0,0 +1,262 @@
+/**
+ * Workspace files for the web dock (RF-12, spec §8.2/§9.4): lazy tree, bounded file reads,
+ * git diffs and the files a session changed. Every path is confined to the workspace with the
+ * core's `safePath` rules (resolve against the canonical root, no symlink segment) and then
+ * re-checked on its `realpath`, so neither `..` nor a symlink ever leaves the workspace (403).
+ */
+import { lstat, open, readdir, realpath, stat } from "node:fs/promises";
+import { basename, extname, relative, resolve, sep } from "node:path";
+import { clipLines, inside, safePath, unifiedPatch } from "@alisio/core";
+import { gitIgnored, gitRoot, gitStatus, runGit } from "../host/git.js";
+import { HttpError } from "../http/errors.js";
+import { sniffImage } from "./images.js";
+/** Entries per tree page (RF-12). */
+export const TREE_PAGE = 1000;
+/** Default and maximum bytes of a previewed file (RF-12: larger files are truncated). */
+export const FILE_PREVIEW_BYTES = 2 * 1024 * 1024;
+const DIFF_LIMIT = 200 * 1024;
+const toPosix = (path) => path.split(sep).join("/");
+const errno = (error) => error?.code;
+/**
+ * Resolves a workspace-relative (or absolute) path inside `root`. `mustExist` also requires the
+ * target to exist (404 otherwise); either way its realpath must stay inside the root (403).
+ */
+export async function confine(root, path, mustExist = true) {
+    let canonical;
+    let target;
+    try {
+        canonical = await realpath(root);
+        target = await safePath(canonical, path || ".");
+    }
+    catch (error) {
+        if (errno(error) === "ENOENT")
+            throw new HttpError("not_found", "Workspace not found");
+        throw new HttpError("path_outside_workspace", "The path is outside the workspace");
+    }
+    let real = target;
+    try {
+        real = await realpath(target);
+    }
+    catch (error) {
+        if (mustExist || errno(error) !== "ENOENT")
+            throw new HttpError("not_found", "File not found");
+    }
+    if (!inside(canonical, real))
+        throw new HttpError("path_outside_workspace", "The path is outside the workspace");
+    return { abs: real, rel: toPosix(relative(canonical, real)) };
+}
+const kindOf = (entry) => entry.isSymbolicLink()
+    ? "symlink"
+    : entry.isDirectory()
+        ? "dir"
+        : entry.isFile()
+            ? "file"
+            : "other";
+async function readHeadBytes(path, max) {
+    const handle = await open(path, "r");
+    try {
+        const buffer = Buffer.alloc(max);
+        const { bytesRead } = await handle.read(buffer, 0, max, 0);
+        return buffer.subarray(0, bytesRead);
+    }
+    finally {
+        await handle.close();
+    }
+}
+const looksBinary = (bytes) => bytes.subarray(0, 8192).includes(0);
+export function registerFileRoutes(router, ctx) {
+    const { workspaces, catalog, sessions } = ctx;
+    const rootOf = async (wid) => {
+        const path = await workspaces.pathOf(wid ?? "");
+        if (!path)
+            throw new HttpError("not_found", "Workspace not found");
+        return path;
+    };
+    router.get("/api/workspaces/:wid/tree", async ({ params, url }) => {
+        const root = await rootOf(params.wid);
+        const { abs, rel } = await confine(root, url.searchParams.get("path") ?? "");
+        if (!(await stat(abs)).isDirectory())
+            throw new HttpError("validation_failed", "path is not a directory", { fields: ["path"] });
+        const offset = Math.max(0, Number.parseInt(url.searchParams.get("cursor") ?? "0", 10) || 0);
+        const dirents = (await readdir(abs, { withFileTypes: true })).filter((d) => d.name !== ".git");
+        const prefix = rel ? `${rel}/` : "";
+        const all = dirents
+            .map((d) => ({ name: d.name, path: `${prefix}${d.name}`, type: kindOf(d) }))
+            .sort((a, b) => (a.type === "dir") !== (b.type === "dir")
+            ? a.type === "dir"
+                ? -1
+                : 1
+            : a.name < b.name
+                ? -1
+                : a.name > b.name
+                    ? 1
+                    : 0);
+        const page = all.slice(offset, offset + TREE_PAGE);
+        // `.gitignore` applies when git is available; ignored entries of this page are hidden.
+        const ignored = await gitIgnored(abs, page.map((e) => (e.type === "dir" ? `${e.name}/` : e.name)));
+        const entries = [];
+        for (const entry of page) {
+            if (ignored.has(entry.name) || ignored.has(`${entry.name}/`))
+                continue;
+            const info = { ...entry };
+            if (entry.type === "file")
+                try {
+                    const s = await lstat(resolve(abs, entry.name));
+                    info.size = s.size;
+                    info.mtime = Math.round(s.mtimeMs);
+                }
+                catch {
+                    /* vanished meanwhile */
+                }
+            entries.push(info);
+        }
+        const next = offset + TREE_PAGE < all.length ? String(offset + TREE_PAGE) : undefined;
+        return { body: { entries, ...(next ? { next } : {}) } };
+    });
+    router.get("/api/workspaces/:wid/file", async ({ params, url, res }) => {
+        const root = await rootOf(params.wid);
+        const { abs } = await confine(root, url.searchParams.get("path") ?? "");
+        const info = await stat(abs);
+        if (!info.isFile())
+            throw new HttpError("validation_failed", "path is not a file", { fields: ["path"] });
+        const name = basename(abs).replace(/["\\\r\n]/g, "_");
+        if (url.searchParams.get("download") === "1") {
+            res.writeHead(200, {
+                "Content-Type": "application/octet-stream",
+                "Content-Length": info.size,
+                "Content-Disposition": `attachment; filename="${name}"`,
+            });
+            const handle = await open(abs, "r");
+            try {
+                for await (const chunk of handle.createReadStream())
+                    res.write(chunk);
+            }
+            finally {
+                await handle.close().catch(() => { });
+            }
+            res.end();
+            return undefined;
+        }
+        const requested = Number.parseInt(url.searchParams.get("maxBytes") ?? "", 10);
+        const max = Number.isFinite(requested) && requested > 0
+            ? Math.min(requested, FILE_PREVIEW_BYTES)
+            : FILE_PREVIEW_BYTES;
+        const bytes = await readHeadBytes(abs, Math.min(max, info.size));
+        const image = sniffImage(bytes);
+        const type = image
+            ? image.mimeType
+            : looksBinary(bytes)
+                ? "application/octet-stream"
+                : "text/plain; charset=utf-8";
+        res.writeHead(200, {
+            "Content-Type": type,
+            "Content-Length": bytes.length,
+            "Content-Disposition": `${type === "application/octet-stream" ? "attachment" : "inline"}; filename="${name}"`,
+            "X-Truncated": String(bytes.length < info.size),
+            "X-File-Size": String(info.size),
+        });
+        res.end(bytes);
+        return undefined;
+    });
+    router.get("/api/workspaces/:wid/diff", async ({ params, url }) => {
+        const root = await rootOf(params.wid);
+        const { abs, rel } = await confine(root, url.searchParams.get("path") ?? "", false);
+        const top = await gitRoot(root);
+        if (!top)
+            throw new HttpError("not_a_git_repo", "The workspace is not a git repository");
+        const canonical = await realpath(root);
+        let patch = "";
+        const tracked = await runGit(canonical, ["ls-files", "--error-unmatch", "--", rel], {
+            literal: true,
+        });
+        if (tracked.code === 0) {
+            const diff = await runGit(canonical, ["diff", "--no-ext-diff", "--no-textconv", "--no-color", "HEAD", "--", rel], { literal: true });
+            patch = diff.code === 0 ? diff.stdout : "";
+        }
+        else {
+            // Untracked (or a repository without commits): the whole file is new.
+            try {
+                const bytes = await readHeadBytes(abs, 1024 * 1024);
+                patch = looksBinary(bytes) ? "" : unifiedPatch(rel, undefined, bytes.toString("utf8"));
+            }
+            catch {
+                throw new HttpError("not_found", "File not found");
+            }
+        }
+        const { text, clipped } = clipLines(patch, DIFF_LIMIT);
+        const lang = extname(rel).slice(1).toLowerCase();
+        return {
+            body: {
+                kind: "diff",
+                path: rel,
+                patch: text,
+                ...(lang ? { lang } : {}),
+                ...(clipped ? { caption: `${rel} (diff truncated to 200 KB)` } : {}),
+            },
+        };
+    });
+    router.get("/api/sessions/:sid/changes", async ({ params }) => {
+        const session = sessions.get(params.sid ?? "");
+        const workspace = await realpath(session.workspace).catch(() => session.workspace);
+        // The session and its children (subagents write too), depth-first.
+        const ids = [];
+        const walk = (id) => {
+            ids.push(id);
+            for (const child of catalog.children(id))
+                walk(child.id);
+        };
+        walk(session.id);
+        const latest = new Map();
+        for (const id of ids) {
+            const calls = catalog.effectCalls(id, "write");
+            if (!calls.length)
+                continue;
+            const wanted = new Map(calls.map((c) => [c.callId, c]));
+            let after = -1;
+            for (;;) {
+                const page = catalog.messagesPage(id, { after, limit: 500, compacted: true });
+                for (const { message } of page.items) {
+                    if (message.role !== "assistant")
+                        continue;
+                    for (const call of message.calls) {
+                        const meta = wanted.get(call.id);
+                        if (!meta)
+                            continue;
+                        let path;
+                        try {
+                            path = JSON.parse(call.arguments).path;
+                        }
+                        catch {
+                            continue;
+                        }
+                        if (typeof path !== "string" || !path)
+                            continue;
+                        const absolute = resolve(workspace, path);
+                        if (!inside(workspace, absolute))
+                            continue;
+                        const rel = toPosix(relative(workspace, absolute));
+                        const at = meta.startedAt ?? 0;
+                        const prev = latest.get(rel);
+                        if (!prev || at >= prev.at)
+                            latest.set(rel, { ...(meta.runId ? { runId: meta.runId } : {}), at });
+                    }
+                }
+                const last = page.items.at(-1);
+                if (!page.hasMore || !last)
+                    break;
+                after = last.seq;
+            }
+        }
+        const top = latest.size ? await gitRoot(workspace) : undefined;
+        const marks = top ? await gitStatus(workspace, top) : new Map();
+        const files = [...latest.entries()]
+            .sort((a, b) => b[1].at - a[1].at || (a[0] < b[0] ? -1 : 1))
+            .map(([path, meta]) => ({
+            path,
+            ...(meta.runId ? { lastRunId: meta.runId } : {}),
+            effect: "write",
+            ...(marks.has(path) ? { gitStatus: marks.get(path) } : {}),
+        }));
+        return { body: { files } };
+    });
+}

package/dist/routes/health.d.ts

@@ -0,0 +1,18 @@
+import type { Router } from "../http/router.ts";
+/** Web protocol version (§8.9); independent of `RunEvent.schemaVersion`. */
+export declare const PROTOCOL_VERSION: 1;
+export interface ServerStats {
+    shuttingDown: boolean;
+    activeRuns: number;
+    queuedRuns: number;
+    openWorkspaces: number;
+    subscribers: number;
+    pendingApprovals: number;
+    sseDropped: number;
+}
+/** `/api/health` (unauthenticated), `/api/ready` and `/api/metrics`. */
+export declare function registerHealthRoutes(router: Router, options: {
+    version: string;
+    remote: boolean;
+    stats: () => ServerStats;
+}): void;

package/dist/routes/health.js

@@ -0,0 +1,38 @@
+import { UI_BLOCK_KINDS } from "@alisio/sdk";
+import { HttpError } from "../http/errors.js";
+/** Web protocol version (§8.9); independent of `RunEvent.schemaVersion`. */
+export const PROTOCOL_VERSION = 1;
+/** `/api/health` (unauthenticated), `/api/ready` and `/api/metrics`. */
+export function registerHealthRoutes(router, options) {
+    router.get("/api/health", () => {
+        const body = {
+            name: "alisio",
+            version: options.version,
+            protocolVersion: PROTOCOL_VERSION,
+            capabilities: {
+                sse: true,
+                websocket: false,
+                multiWorkspace: true,
+                // Uploads (`POST /api/blobs`) arrive in phase 4.
+                attachments: false,
+                uiBlocks: [...UI_BLOCK_KINDS],
+                mcpApps: false,
+                automation: false,
+                remote: options.remote,
+            },
+        };
+        return { body };
+    });
+    router.get("/api/ready", () => {
+        const stats = options.stats();
+        if (stats.shuttingDown)
+            throw new HttpError("shutting_down", "Server is shutting down");
+        return {
+            body: { ready: true, workspaces: stats.openWorkspaces, activeRuns: stats.activeRuns },
+        };
+    });
+    router.get("/api/metrics", () => {
+        const { shuttingDown: _, ...metrics } = options.stats();
+        return { body: metrics };
+    });
+}

package/dist/routes/images.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Image detection by magic bytes (never by name or declared type) for uploads and file previews:
+ * PNG, JPEG, GIF and WebP, the formats the TUI and providers accept (spec §11.1). Dimensions are
+ * read from the header when present; they are advisory metadata, not validation.
+ */
+export interface SniffedImage {
+    mimeType: "image/png" | "image/jpeg" | "image/gif" | "image/webp";
+    width?: number;
+    height?: number;
+}
+/** The image type (and size when readable) of `bytes`, or undefined when it is not one. */
+export declare function sniffImage(bytes: Uint8Array): SniffedImage | undefined;

package/dist/routes/images.js

@@ -0,0 +1,60 @@
+const ascii = (bytes, at, text) => bytes.length >= at + text.length &&
+    [...text].every((ch, i) => bytes[at + i] === ch.charCodeAt(0));
+const dims = (width, height) => (width > 0 && height > 0 ? { width, height } : {});
+function jpegSize(b) {
+    let i = 2;
+    while (i + 9 < b.length) {
+        if (b[i] !== 0xff)
+            return {};
+        const marker = b[i + 1];
+        if (marker === 0xd8 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) {
+            i += 2;
+            continue;
+        }
+        const length = (b[i + 2] << 8) | b[i + 3];
+        // SOF0–SOF15 except DHT (C4), JPG (C8) and DAC (CC) carry the frame size.
+        if (marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker))
+            return dims((b[i + 7] << 8) | b[i + 8], (b[i + 5] << 8) | b[i + 6]);
+        if (length < 2)
+            return {};
+        i += 2 + length;
+    }
+    return {};
+}
+function webpSize(b) {
+    const u24 = (at) => b[at] | (b[at + 1] << 8) | (b[at + 2] << 16);
+    if (ascii(b, 12, "VP8X") && b.length >= 30)
+        return dims(u24(24) + 1, u24(27) + 1);
+    if (ascii(b, 12, "VP8 ") && b.length >= 30)
+        return dims((b[26] | (b[27] << 8)) & 0x3fff, (b[28] | (b[29] << 8)) & 0x3fff);
+    if (ascii(b, 12, "VP8L") && b.length >= 25) {
+        const bits = b[21] |
+            (b[22] << 8) |
+            (b[23] << 16) |
+            (b[24] << 24);
+        return dims((bits & 0x3fff) + 1, ((bits >>> 14) & 0x3fff) + 1);
+    }
+    return {};
+}
+/** The image type (and size when readable) of `bytes`, or undefined when it is not one. */
+export function sniffImage(bytes) {
+    const b = bytes;
+    if (b.length >= 8 && b[0] === 0x89 && ascii(b, 1, "PNG\r\n\x1a\n")) {
+        const size = b.length >= 24 && ascii(b, 12, "IHDR")
+            ? dims(Buffer.from(b.subarray(16, 20)).readUInt32BE(0), Buffer.from(b.subarray(20, 24)).readUInt32BE(0))
+            : {};
+        return { mimeType: "image/png", ...size };
+    }
+    if (b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff)
+        return { mimeType: "image/jpeg", ...jpegSize(b) };
+    if (ascii(b, 0, "GIF87a") || ascii(b, 0, "GIF89a"))
+        return {
+            mimeType: "image/gif",
+            ...(b.length >= 10
+                ? dims(b[6] | (b[7] << 8), b[8] | (b[9] << 8))
+                : {}),
+        };
+    if (ascii(b, 0, "RIFF") && ascii(b, 8, "WEBP"))
+        return { mimeType: "image/webp", ...webpSize(b) };
+    return undefined;
+}

package/dist/routes/management.d.ts

@@ -0,0 +1,32 @@
+import type { ServerFrame } from "@alisio/sdk";
+import type { RunScheduler } from "../host/run-scheduler.ts";
+import type { OpenWorkspace, ServerAppOptions, WorkspaceHost } from "../host/workspace-host.ts";
+import type { Router } from "../http/router.ts";
+type CatalogScope = Extract<ServerFrame, {
+    t: "catalog_changed";
+}>["scope"];
+export interface ManagementContext {
+    workspaces: WorkspaceHost;
+    scheduler: RunScheduler;
+    base: ServerAppOptions;
+    broadcast: (frame: ServerFrame) => void;
+}
+/** Resolves `?workspace=` / `{workspace}` (an opaque id or an absolute path) to its open app. */
+export declare function workspaceApp(workspaces: WorkspaceHost, reference: string | null | undefined): Promise<OpenWorkspace>;
+/**
+ * Plugin and skill toggles persist a project override; the running app reflects plugin changes
+ * only after a restart. The server recycles the workspace app as soon as it has no runs (now,
+ * or when its last run finishes), so the change applies without restarting `alisio serve`.
+ */
+export declare class WorkspaceRecycler {
+    private ctx;
+    private pending;
+    constructor(ctx: ManagementContext);
+    /** Recycles now when idle; otherwise once the workspace's runs finish. */
+    request(id: string): Promise<OpenWorkspace | undefined>;
+    /** Called when a run finishes: applies a deferred recycle once nothing runs. */
+    idle(id: string): void;
+    announce(workspaceId: string, scopes: CatalogScope[]): void;
+}
+export declare function registerManagementRoutes(router: Router, ctx: ManagementContext, recycler: WorkspaceRecycler): void;
+export {};