@alisio/alisio-code 0.1.0-alpha.9 → 0.1.0

package/README.md

@@ -1,23 +1,102 @@
-# alisio
+# @alisio/alisio-code
 
-**Alisio is an extensible, provider-agnostic coding-agent harness for your terminal.** It pairs a
-fast TUI with any OpenAI-compatible model, runs local tools behind explicit permissions, compacts
-long conversations into structured checkpoints, remembers decisions across sessions with an
-Engram-style memory plugin, and exposes a typed plugin SDK.
+**Alisio is an extensible, provider-agnostic coding-agent harness for your terminal.** It pairs a fast
+TUI with any OpenAI-compatible model, runs local tools behind explicit permissions, compacts long
+conversations into structured checkpoints, remembers decisions across sessions with an Engram-style
+memory plugin, and exposes a typed plugin SDK.
+
+## What it is
+
+`alisio` is the CLI of the Alisio project. It connects to any OpenAI-compatible endpoint (Chat
+Completions or Responses), drives its own agent tool loop, and runs interactively as a TUI or
+headless for scripts and CI. Provider SDKs stay out of the harness: the CLI ships built-in DeepSeek,
+OpenAI-compatible, OpenCode Console (Zen) and OpenCode Go providers, plus memory and subagents
+plugins.
+
+## Installation
+
+```sh
+npm i -g @alisio/alisio-code        # or: pnpm add -g @alisio/alisio-code · bun add -g @alisio/alisio-code
+alisio                              # the binary is installed as `alisio`
+```
+
+Standalone binaries (Bun embedded, no Node required) are attached to GitHub releases.
+
+## Quick start
+
+The fastest path is the TUI's `/connect` form: pick a provider, enter its settings and key, choose a
+model, and Alisio persists the selection globally (`/model` re-opens the same selector). A plain
+config start looks like:
+
+```sh
+alisio setup                        # writes a secret-free .alisio/config.json in .alisio/
+export DEEPSEEK_API_KEY=...         # keys come from environment variables or /connect, never config files
+alisio --config .alisio/config.json
+```
+
+Run one prompt headless, emitting versioned JSONL events:
 
 ```sh
-npm install -g @alisio/alisio-code        # or: pnpm add -g @alisio/alisio-code · bun add -g @alisio/alisio-code
-alisio                                      # the CLI binary is installed as `alisio`
-export DEEPSEEK_API_KEY=...  # keys are read from environment variables only
-alisio --config ./alisio.json
+alisio run "Summarize this repository" --json
+alisio run "/init" --allow-write    # generate AGENTS.md from the built-in /init template
 ```
 
-- Terminal UI: streaming Markdown, tool blocks with diffs, context/token bar, slash commands, copy-on-select.
-- Headless: `alisio run "prompt" --json` emits versioned JSONL events.
-- Permissions: reads by default; `--allow-write`, `--allow-process` or interactive approval; `--read-only`.
-- Built-in memory plugin (disable with `--disable-plugin memory`); npm plugins via `--plugin <package>`.
-- Runs on Node.js >= 22.16 or Bun; standalone binaries are attached to GitHub releases.
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `alisio` | Interactive TUI (readline with `--no-tui`) |
+| `alisio run <prompt>` | Headless run; `/name args` runs a prompt template |
+| `alisio resume <session> [prompt]` | Resume a session |
+| `alisio setup` | Write a secret-free example `.alisio/config.json` |
+| `alisio doctor` | Environment and provider diagnostics |
+| `alisio trust list` / `trust revoke <path>` | Inspect or revoke per-directory project trust |
+| `alisio sessions list` / `sessions recover <id> --acknowledge` | List sessions; recover after a crash |
+| `alisio skills list` / `skills validate` | Discover and validate Agent Skills |
+| `alisio plugins list` / `plugins doctor` | List/load plugins and show their tools and commands |
+| `alisio mcp list` / `mcp doctor <server>` | List configured MCP servers; connect to one (`--allow-mcp`) |
+| `alisio context explain <path>` | Show which `AGENTS.md` files apply to a path |
+| `alisio install npm:<package>` | Install an npm plugin into the global plugins directory |
+
+## Permissions and key flags
+
+Reads run by default; anything else needs a flag or interactive approval:
+
+| Flag | Effect |
+| --- | --- |
+| `--allow-write` | Allow file writes |
+| `--allow-process` | Allow arbitrary subprocesses (not sandboxed) |
+| `--allow-external` | Allow network tools: `webfetch`, `websearch`, provider-native search |
+| `--allow-mcp` | Allow configured MCP servers and remote tool calls |
+| `--allow-agents` | Allow messaging neighboring agents through Herdr |
+| `--read-only` | Disable writes, subprocesses, network tools, executable plugins and MCP |
+| `--plugin <path…>` / `--trust-project` | Load explicitly trusted plugins / trust project config |
+| `--disable-plugin <ids…>` | Disable built-in plugins (e.g. `memory`) |
+| `--json` | Emit versioned JSONL events (headless) |
+
+Other global flags: `--cwd`, `--config`, `--model`, `--base-url`, `--api-mode`, `--db`,
+`--no-tui`, `--no-banner`, `--no-herdr`, `--agents <json>`, `--quiet`, `-V`, `-h`.
+
+## In the TUI
+
+`/connect` adds a provider; `/model` picks a saved provider/model; `/compact`, `/stats`, `/clear`,
+`/sessions`, `/resume` manage conversations; `/plugins`, `/skills`, `/mcps`, `/settings` manage
+extensions and preferences; `/memory` and `/agents` drive the built-in plugins; `/init` writes
+`AGENTS.md`.
+
+## Requirements
+
+Node.js **>= 22.16** (`node:sqlite` with FTS5) or Bun **>= 1.4.2**. Git and ripgrep on `PATH` for the
+Git and search tools; `alisio doctor` reports what it detects.
+
+## Docs
+
+Documentation (EN/ES): <https://gustavogutierrez.github.io/alisio/> — [quick start](https://gustavogutierrez.github.io/alisio/quick-start),
+[configuration](https://gustavogutierrez.github.io/alisio/configuration), [plugins](https://gustavogutierrez.github.io/alisio/plugins),
+[subagents](https://gustavogutierrez.github.io/alisio/subagents), [memory](https://gustavogutierrez.github.io/alisio/memory),
+[TUI](https://gustavogutierrez.github.io/alisio/tui).
 
-Documentation: [English](https://gustavogutierrez.github.io/alisio/) · [Español](https://gustavogutierrez.github.io/alisio/es/)
+## License
 
-Maintainer: Gustavo Gutiérrez · License: MIT
+MIT. Maintained by Gustavo Gutiérrez Mercado. Source: <https://github.com/GustavoGutierrez/alisio> ·
+npm: <https://www.npmjs.com/settings/alisio/packages>.

package/dist/analysis.d.ts

@@ -0,0 +1,27 @@
+import type { AnalysisStatus } from "@alisio/sdk";
+type Common = {
+    db?: string;
+    python?: string;
+    cwd?: string;
+    config?: string;
+    trustProject?: boolean;
+};
+/** The unified runtime state and, when Python is missing, the install guidance for this system. */
+export declare function analysisState(o: Common): Promise<{
+    status: AnalysisStatus;
+    guidance?: string;
+    ignored: string[];
+}>;
+/** Prints `alisio analysis status`. */
+export declare function printAnalysisStatus(o: Common): Promise<void>;
+/** `alisio analysis setup --extras analysis|science`: needs network; offline it fails cleanly. */
+export declare function setupExtras(o: Common, extras: string | undefined): Promise<void>;
+/**
+ * `alisio analysis setup --oci [--image <name>]`: pulls the image once and verifies it. With a
+ * digest-pinned reference the pull verifies the digest; with a tag it prints the digest to put in
+ * `analysis.oci.image` (Alisio never writes it: only you choose what runs your code).
+ */
+export declare function setupOci(o: Common, image: string | undefined): Promise<void>;
+/** `alisio analysis sweep [--force]`: the retention sweep now (it also runs by itself, daily). */
+export declare function sweep(o: Common, force: boolean): Promise<void>;
+export {};

package/dist/analysis.js

@@ -0,0 +1,145 @@
+/**
+ * `alisio analysis …` and the analysis line of `alisio doctor`: the state of the Python runtime,
+ * the optional extras (`setup --extras`, hash-locked, needs network), the optional container
+ * runtime (`setup --oci`) and the retention sweep (`sweep`). None of these is needed to run
+ * `python_run`: the base runtime is the discovered Python with only the standard library.
+ */
+import { dirname, join } from "node:path";
+async function context(o) {
+    const core = await import("@alisio/core");
+    const workspace = await core.findWorkspace(o.cwd ?? process.cwd());
+    const { config, provenance } = await core.loadConfigWithProvenance(workspace, {
+        file: o.config,
+        trustProject: o.trustProject,
+    });
+    const stateDir = o.db && o.db !== ":memory:" ? dirname(o.db) : core.stateHome();
+    const manager = new core.AnalysisRuntimeManager({
+        stateDir,
+        ...(o.python ? { python: o.python } : {}),
+    });
+    const oci = () => new core.OciRuntime({ ...config.analysis.oci });
+    return { core, config, provenance, stateDir, manager, oci };
+}
+/** The unified runtime state and, when Python is missing, the install guidance for this system. */
+export async function analysisState(o) {
+    const { core, config, provenance, stateDir, manager, oci } = await context(o);
+    const janitor = {
+        lastSweep: () => import("node:fs/promises")
+            .then((fs) => fs.readFile(join(stateDir, "analysis", ".last-sweep"), "utf8"))
+            .then((text) => {
+            const value = Number(text.trim());
+            return Number.isFinite(value) ? value : undefined;
+        })
+            .catch(() => undefined),
+    };
+    const status = await core.analysisStatus({
+        config: config.analysis,
+        runtime: manager,
+        oci,
+        janitor,
+        enabled: config.analysis.enabled,
+        readOnly: false,
+    });
+    const guidance = status.python.found
+        ? undefined
+        : (async () => {
+            const resolved = await manager.interpreter();
+            return resolved.ok
+                ? undefined
+                : core.installHintsText(core.pythonInstallHints(await core.detectHintHost(resolved.found)));
+        })();
+    return {
+        status,
+        ...(guidance ? { guidance: await guidance } : {}),
+        ignored: provenance.ignored ?? [],
+    };
+}
+/** Prints `alisio analysis status`. */
+export async function printAnalysisStatus(o) {
+    const { status, guidance, ignored } = await analysisState(o);
+    console.log(JSON.stringify(status, null, 2));
+    if (guidance)
+        process.stderr.write(`\n${guidance}\n`);
+    if (status.mode === "oci" && status.oci.available === false)
+        process.stderr.write(`\nThe container runtime is configured but not usable: ${status.oci.reason ?? "unknown reason"}\n`);
+    for (const key of ignored)
+        process.stderr.write(`\nIgnored ${key} from the project configuration: only your user configuration decides it.\n`);
+}
+/** `alisio analysis setup --extras analysis|science`: needs network; offline it fails cleanly. */
+export async function setupExtras(o, extras) {
+    if (extras !== "analysis" && extras !== "science")
+        throw new Error("Choose the extras to install: --extras analysis or --extras science");
+    const { core, manager } = await context(o);
+    const preview = core.installPreview(extras);
+    const controller = new AbortController();
+    process.on("SIGINT", () => controller.abort(new Error("Interrupted")));
+    process.stderr.write(`Installing the ${extras} extras: ${preview.packages.join(", ")} (+ dependencies, ${preview.packageCount} packages, about ${Math.round(preview.estimatedBytes / (1024 * 1024))} MB). ` +
+        "Wheels only, hashes required, needs network.\n");
+    try {
+        const state = await manager.installExtras(extras, {
+            signal: controller.signal,
+            onOutput: (text) => process.stderr.write(text),
+        });
+        console.log(JSON.stringify(state, null, 2));
+    }
+    catch (error) {
+        // A clean message and a failing exit code; the base runtime is untouched.
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
+    }
+}
+/**
+ * `alisio analysis setup --oci [--image <name>]`: pulls the image once and verifies it. With a
+ * digest-pinned reference the pull verifies the digest; with a tag it prints the digest to put in
+ * `analysis.oci.image` (Alisio never writes it: only you choose what runs your code).
+ */
+export async function setupOci(o, image) {
+    const { core, config } = await context(o);
+    const reference = image ?? config.analysis.oci.image;
+    if (!reference)
+        throw new Error("Pass --image <name[:tag]> (or set analysis.oci.image in your user configuration) to pull.");
+    const runtime = new core.OciRuntime({ ...config.analysis.oci, image: undefined });
+    const status = await runtime.status();
+    if (!status.ok)
+        throw new Error(`${status.reason}${status.alternative ? `; ${status.alternative} is installed (set analysis.oci.engine to "${status.alternative}")` : ""}. The container runtime is optional; python_run works without it.`);
+    process.stderr.write(`Pulling ${reference} with ${status.engine} ${status.version}…\n`);
+    const controller = new AbortController();
+    process.on("SIGINT", () => controller.abort(new Error("Interrupted")));
+    const { digest } = await runtime.pull(reference, controller.signal);
+    const pinned = core.OCI_IMAGE_PATTERN.test(reference);
+    if (pinned) {
+        const wanted = reference.slice(reference.indexOf("@") + 1);
+        if (digest && !digest.endsWith(wanted))
+            throw new Error(`The pulled image reports ${digest}, not the pinned ${wanted}`);
+        console.log(`Verified ${reference}. Set analysis.runtime to "oci" to use it.`);
+    }
+    else if (digest)
+        console.log(`Pulled ${reference}. To use it, put this in your user configuration (${core.configHome()}):\n` +
+            `  "analysis": { "runtime": "oci", "oci": { "engine": "${status.engine}", "image": "${digest}" } }`);
+    else
+        throw new Error(`${reference} has no repository digest (a locally built image?). Push it to a registry or pull a published image.`);
+}
+/** `alisio analysis sweep [--force]`: the retention sweep now (it also runs by itself, daily). */
+export async function sweep(o, force) {
+    const { core, config, stateDir } = await context(o);
+    const store = new core.SQLiteStore(o.db ?? join(stateDir, "sessions.sqlite"));
+    try {
+        const artifacts = new core.ArtifactStore({ root: stateDir, db: store.db });
+        const datasets = new core.DatasetService({ root: stateDir, db: store.db });
+        const blobs = new core.BlobStore({ root: join(stateDir, "blobs"), db: store.db });
+        const janitor = new core.AnalysisJanitor({
+            root: stateDir,
+            db: store.db,
+            artifacts,
+            datasets,
+            blobs,
+            retention: () => config.analysis.retention,
+        });
+        const report = await janitor.sweep({ force });
+        console.log(JSON.stringify(report, null, 2));
+        datasets.close();
+    }
+    finally {
+        store.close();
+    }
+}

package/dist/banner.js

@@ -21,7 +21,8 @@ export function terminalCapabilities(input) {
     const locale = env.LC_ALL || env.LC_CTYPE || env.LANG || "";
     return {
         color: input.tty && !dumb && env.NO_COLOR === undefined,
-        unicode: !dumb && !/^(C|POSIX)(\.|$)/i.test(locale),
+        // `C.UTF-8` is a UTF-8 locale (the default on CI runners); only bare C/POSIX is ASCII.
+        unicode: !dumb && (/utf-?8/i.test(locale) || !/^(C|POSIX)(\.|$)/i.test(locale)),
         columns: input.columns > 0 ? input.columns : 80,
         interactive: input.tty,
     };

package/dist/builtin.d.ts

@@ -2,7 +2,9 @@
  * Built-in plugin registry wired by the CLI. Built-ins load through the trusted path of the
  * plugin host (unprefixed names, `internal` effect) and can be disabled by configuration
  * (`builtinPlugins.<id>.enabled: false`) or `--disable-plugin <id>`. Add a built-in by
- * appending an entry here.
+ * appending an entry here. Dedicated model providers (DeepSeek, OpenCode Console, OpenCode Go)
+ * are no longer built-ins: users install them independently via
+ * `alisio install npm:@alisio/plugin-{deepseek,opencode,opencode-go}`.
  */
 import type { BuiltinPlugin } from "@alisio/core";
 export declare const BUILTIN_PLUGINS: BuiltinPlugin[];

package/dist/builtin.js

@@ -1,31 +1,7 @@
-import { createDeepSeekPlugin } from "@alisio/plugin-deepseek";
 import { createMemoryPlugin } from "@alisio/plugin-memory";
 import { createOpenAICompatiblePlugin } from "@alisio/plugin-openai-compatible";
-import { createOpenCodePlugin } from "@alisio/plugin-opencode";
-import { createOpenCodeGoPlugin } from "@alisio/plugin-opencode-go";
 import { createSubagentsPlugin } from "@alisio/plugin-subagents";
 export const BUILTIN_PLUGINS = [
-    {
-        id: "deepseek",
-        name: "DeepSeek",
-        description: "Dedicated DeepSeek Chat Completions and Responses provider",
-        categories: ["model-provider"],
-        create: createDeepSeekPlugin,
-    },
-    {
-        id: "opencode",
-        name: "OpenCode Console (Zen)",
-        description: "Dedicated OpenCode Console (Zen) multi-protocol provider",
-        categories: ["model-provider"],
-        create: createOpenCodePlugin,
-    },
-    {
-        id: "opencode-go",
-        name: "OpenCode Go",
-        description: "Dedicated OpenCode Go multi-protocol provider",
-        categories: ["model-provider"],
-        create: createOpenCodeGoPlugin,
-    },
     {
         id: "openai-compatible",
         name: "OpenAI compatible",

package/dist/main.js

@@ -35,9 +35,12 @@ program
     .option("--api-mode <mode>", "chat or responses")
     .option("--allow-write", "Allow file writes")
     .option("--allow-process", "Allow arbitrary subprocesses; not sandboxed")
+    .option("--allow-analysis", "Allow Python analysis (python_run) without asking; not sandboxed, never allows shell")
+    .option("--python <path>", "Python 3.10+ interpreter for python_run (default: discovered)")
     .option("--allow-external", "Allow network tools: webfetch, websearch and provider-native search")
     .option("--allow-mcp", "Allow configured MCP servers and remote tool calls")
     .option("--allow-agents", "Allow messaging neighboring agents through Herdr")
+    .option("--add-dir <paths...>", "Additional directories tools may read/write outside the workspace (repeatable)")
     .option("--no-herdr", "Disable automatic Herdr lifecycle reports")
     .option("--read-only", "Disable writes, arbitrary processes, network tools, executable plugins and MCP")
     .option("--db <path>", "Session database")
@@ -54,6 +57,7 @@ const options = (cmd) => {
         baseURL: o.baseUrl,
         noHerdr: o.herdr === false,
         disablePlugins: o.disablePlugin,
+        addDirs: o.addDir,
         ...(o.agents
             ? { pluginOptions: { subagents: { agents: parseAgents(String(o.agents)) } } }
             : {}),
@@ -114,7 +118,7 @@ async function run(cmd, prompt, sessionId) {
         const trusted = await withProjectTrust(opts);
         return runTui({ ...trusted, ...(sessionId ? { session: sessionId } : {}) });
     }
-    const { createApplication } = await import("@alisio/core");
+    const { createApplication, formatBytes, KIND_LABELS } = await import("@alisio/core");
     const app = await createApplication({
         ...(await cliDefaults()),
         ...opts,
@@ -123,12 +127,40 @@ async function run(cmd, prompt, sessionId) {
                 process.stdout.write(`${JSON.stringify(event)}\n`);
             else if (event.type === "text_delta")
                 process.stdout.write(String(event.data.delta));
+            else if (event.type === "request_retry") {
+                const retry = event.data;
+                process.stderr.write(`\nThe model did not respond; retrying (${retry.attempt}/${retry.of})…\n`);
+            }
+            else if (event.type === "truncation_recovery") {
+                const recovery = event.data;
+                process.stderr.write(`\nThe response was cut off by the output limit; retrying in smaller steps (${recovery.attempt}/${recovery.of})…\n`);
+            }
             else if (event.type === "tool_started")
                 process.stderr.write(`\n→ ${event.data.name}\n`);
+            else if (event.type === "artifact_published")
+                process.stderr.write(artifactLine(event));
         },
     });
+    /** `artifact: Dashboard site.zip (48 KB) → /abs/path` (nothing is opened automatically). */
+    function artifactLine(event) {
+        const data = event.data;
+        return `artifact: ${KIND_LABELS[data.artifact.kind] ?? "File"} ${data.artifact.fileName} (${formatBytes(data.artifact.bytes)}) → ${data.path}\n`;
+    }
     for (const failure of app.mcpStartupFailures())
         process.stderr.write(`[startup] ${failure}\n`);
+    // The ACTIVE agent (built-in `build`/`plan` or a main-capable definition) drives the main
+    // session here too: its system prompt is appended and a read-only agent narrows the run. The
+    // TUI adds the picker and the model switch; effort is a TUI feature (validated against the
+    // active model's catalog).
+    const { agentCatalogFromState, agentRunOptions, resolveActiveAgent } = await import("./tui/agents.js");
+    let activeRunOptions = {};
+    try {
+        const reported = app.plugins.pluginState("subagents", "mainAgents");
+        activeRunOptions = agentRunOptions(resolveActiveAgent(agentCatalogFromState(reported), app.config.agents.active));
+    }
+    catch {
+        /* agent resolution is best-effort */
+    }
     const controller = new AbortController();
     const interrupt = () => controller.abort(new Error("Interrupted"));
     process.on("SIGINT", interrupt);
@@ -151,7 +183,10 @@ async function run(cmd, prompt, sessionId) {
             const match = /^\/skill:([a-z0-9-]+)\s*([\s\S]*)$/.exec(prompt);
             if (match?.[1])
                 prompt = `${await app.skills.load(match[1])}\n\nUser request: ${match[2] ?? ""}`;
-            await app.runner.run(session, template?.text ?? prompt, controller.signal, template ? { display: template.display } : {});
+            await app.runner.run(session, template?.text ?? prompt, controller.signal, {
+                ...activeRunOptions,
+                ...(template ? { display: template.display } : {}),
+            });
             if (!opts.json)
                 process.stdout.write(`\nSession: ${session}\n`);
             return;
@@ -182,7 +217,7 @@ async function run(cmd, prompt, sessionId) {
                 process.stderr.write(`[startup] ${JSON.stringify(d)}\n`);
         }
         if (!opts.quiet)
-            console.log("Alisio · /exit /new /skill:name /command plugin.id:name args");
+            console.log("Alisio · /exit /new /btw question /skill:name /command plugin.id:name args");
         process.stdout.write("\nalisio › ");
         try {
             for await (const rawLine of rl) {
@@ -199,6 +234,22 @@ async function run(cmd, prompt, sessionId) {
                     process.stdout.write("\nalisio › ");
                     continue;
                 }
+                if (line === "/btw" || line.startsWith("/btw ")) {
+                    // Side question: printed here only, never added to the conversation.
+                    try {
+                        const { CommandCatalog } = await import("@alisio/core");
+                        const result = await new CommandCatalog(app).execute("btw", line.slice(4), {
+                            sessionId: session,
+                            signal: controller.signal,
+                        });
+                        console.log(result.text ?? "");
+                    }
+                    catch (e) {
+                        console.error(e instanceof Error ? e.message : String(e));
+                    }
+                    process.stdout.write("\nalisio › ");
+                    continue;
+                }
                 if (line.startsWith("/command ")) {
                     const [name, ...args] = line.slice(9).split(" ");
                     const handler = app.plugins.commands.get(name ?? "");
@@ -211,7 +262,10 @@ async function run(cmd, prompt, sessionId) {
                 const input = match?.[1] ? `${await app.skills.load(match[1])}\n\n${match[2] ?? ""}` : line;
                 try {
                     const template = app.expandPrompt(input);
-                    await app.runner.run(session, template?.text ?? input, controller.signal, template ? { display: template.display } : {});
+                    await app.runner.run(session, template?.text ?? input, controller.signal, {
+                        ...activeRunOptions,
+                        ...(template ? { display: template.display } : {}),
+                    });
                 }
                 catch (e) {
                     console.error(String(e));
@@ -225,7 +279,11 @@ async function run(cmd, prompt, sessionId) {
     }
     finally {
         process.off("SIGINT", interrupt);
+        // Background tasks end with Alisio: `run` waits for none of them, it stops them and says so.
+        const live = app.tasks.liveCount();
         await app.close();
+        if (live)
+            process.stderr.write(`${live} background task${live === 1 ? " was" : "s were"} still running and ${live === 1 ? "was" : "were"} stopped: background tasks end when Alisio exits.\n`);
     }
 }
 program
@@ -239,6 +297,19 @@ program
     .argument("[prompt]")
     .action((id, prompt, _opts, cmd) => run(cmd, prompt, id));
 program.action((_opts, cmd) => run(cmd));
+program
+    .command("serve")
+    .description("Start the local web UI server (HTTP + SSE)")
+    .option("--port <port>", "Port to listen on (0 picks a free one)", "4317")
+    .option("--host <address>", "Address to bind; non-loopback requires --allow-remote", "127.0.0.1")
+    .option("--allow-remote", "Allow a non-loopback --host (no TLS; prefer an SSH tunnel)")
+    .option("--no-open", "Do not open the browser")
+    .option("--max-workspaces <n>", "Maximum workspaces open at once", "4")
+    .option("--max-runs <n>", "Maximum concurrent runs across all sessions", "4")
+    .action(async (flags, cmd) => {
+    const { serve } = await import("./serve.js");
+    await serve(flags, { ...(await cliDefaults()), ...options(cmd) }, VERSION);
+});
 program
     .command("setup")
     .description("Write an example configuration without secrets (for AGENTS.md use /init)")
@@ -255,7 +326,7 @@ program
     console.log('To generate AGENTS.md for this project, run /init inside alisio (or: alisio run "/init" --allow-write).');
 });
 program.command("doctor").action(async (_opts, cmd) => {
-    const { findWorkspace, loadConfigWithProvenance, overridesSavedProviderProfile, ProviderSettingsStore, RIPGREP_INSTALL_HINT, which, } = await import("@alisio/core");
+    const { DEFAULT_MAX_OUTPUT_TOKENS, findWorkspace, loadConfigWithProvenance, MAX_AUTO_OUTPUT_TOKENS, overridesSavedProviderProfile, ProviderSettingsStore, RIPGREP_INSTALL_HINT, which, } = await import("@alisio/core");
     const o = options(cmd);
     const workspace = await findWorkspace(o.cwd ?? process.cwd());
     const { config, provenance } = await loadConfigWithProvenance(workspace, {
@@ -278,6 +349,14 @@ program.command("doctor").action(async (_opts, cmd) => {
         workspace,
         git: (await which("git")) ?? null,
         ripgrep: (await which("rg")) ?? null,
+        // The per-request output budget is resolved when a run starts, from the model's catalog;
+        // doctor does not contact the provider, so it reports what the configuration decides.
+        outputTokens: config.limits.maxOutputTokens !== undefined
+            ? { limit: config.limits.maxOutputTokens, source: "set by you (limits.maxOutputTokens)" }
+            : {
+                limit: null,
+                source: `the model catalog's declared limit (capped at ${MAX_AUTO_OUTPUT_TOKENS}), else ${DEFAULT_MAX_OUTPUT_TOKENS}`,
+            },
         provider: {
             id: useSaved ? saved.profile.provider : "openai-compatible",
             baseURL: useSaved ? saved.profile.values.baseURL : config.provider.baseURL,
@@ -299,13 +378,61 @@ program.command("doctor").action(async (_opts, cmd) => {
                 : config.provider.auth === "none" || !!process.env[config.provider.apiKeyEnv],
         },
     };
-    console.log(JSON.stringify(status, null, 2));
+    const { analysisState } = await import("./analysis.js");
+    const analysisInfo = await analysisState(o);
+    const { hints: _hints, ...pythonInfo } = analysisInfo.status.python;
+    console.log(JSON.stringify({
+        ...status,
+        python: { mode: analysisInfo.status.mode, ...pythonInfo },
+        analysis: {
+            mode: analysisInfo.status.mode,
+            oci: analysisInfo.status.oci,
+            limits: analysisInfo.status.limits,
+            retention: analysisInfo.status.retention,
+            ...(analysisInfo.ignored.length ? { ignored: analysisInfo.ignored } : {}),
+        },
+    }, null, 2));
+    if (analysisInfo.guidance)
+        process.stderr.write(`\n${analysisInfo.guidance}\n`);
+    for (const key of provenance.ignored ?? [])
+        process.stderr.write(`\nIgnored ${key} from the project configuration: only your user configuration decides it.\n`);
     if (!status.ripgrep)
         process.stderr.write(`\nWarning: ripgrep (rg) is not installed; search_text and list_files will not work. ${RIPGREP_INSTALL_HINT}\n`);
     if (!model || model === "YOUR_MODEL_ID")
         console.error("\nNo model configured yet: set provider.model in your config, --model, or ALISIO_MODEL " +
             "before starting a real conversation (it will otherwise fail on the first turn).");
 });
+const analysis = program
+    .command("analysis")
+    .description("Python analysis runtime (python_run): status, optional extras and containers");
+analysis
+    .command("status")
+    .description("Show the runtime: Python, extras, container engine, limits and retention")
+    .action(async (_opts, cmd) => {
+    const { printAnalysisStatus } = await import("./analysis.js");
+    await printAnalysisStatus(options(cmd));
+});
+analysis
+    .command("setup")
+    .description("Optional: install hash-locked Python extras (--extras) or pull the container image (--oci). " +
+    "python_run never needs this for the standard library.")
+    .option("--extras <set>", "analysis (pandas, numpy, matplotlib…) or science (adds scipy…)")
+    .option("--oci", "Pull the container image once and verify its digest (Docker or Podman)")
+    .option("--image <name>", "With --oci: the image to pull (default: analysis.oci.image)")
+    .action(async (flags, cmd) => {
+    const { setupExtras, setupOci } = await import("./analysis.js");
+    if (flags.oci)
+        return setupOci(options(cmd), flags.image);
+    return setupExtras(options(cmd), flags.extras);
+});
+analysis
+    .command("sweep")
+    .description("Run the retention sweep now (it also runs by itself at most once a day)")
+    .option("--force", "Ignore the once-a-day mark")
+    .action(async (flags, cmd) => {
+    const { sweep } = await import("./analysis.js");
+    await sweep(options(cmd), !!flags.force);
+});
 const trust = program.command("trust").description("Inspect or revoke per-directory project trust");
 trust.command("list").action(async () => {
     const { listTrust } = await import("@alisio/core");

package/dist/serve.d.ts

@@ -0,0 +1,15 @@
+import type { AppOptions } from "@alisio/core";
+export interface ServeFlags {
+    port: string;
+    host: string;
+    allowRemote?: boolean;
+    open: boolean;
+    maxWorkspaces: string;
+    maxRuns: string;
+}
+/** The operating system's URL opener for `platform`, as `[command, ...args]`. */
+export declare function browserCommand(platform: NodeJS.Platform, url: string): string[];
+/** Opens `url` in the default browser; failures are reported, never fatal. */
+export declare function openBrowser(url: string): void;
+/** Starts the server, prints the launch URL and stops cleanly on SIGINT/SIGTERM. */
+export declare function serve(flags: ServeFlags, app: AppOptions & Record<string, unknown>, version: string): Promise<void>;