@alisio/alisio-code 0.1.0-alpha.12 → 0.1.0-alpha.13

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`, `/mcp`, `/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/tui/app.js

@@ -326,7 +326,13 @@ export async function runTui(options) {
             tui.requestRender();
             return;
         }
-        if (["run_completed", "run_failed", "run_cancelled", "compaction_failed"].includes(event.type))
+        if ([
+            "run_completed",
+            "run_failed",
+            "run_cancelled",
+            "run_turns_exceeded",
+            "compaction_failed",
+        ].includes(event.type))
             terminalEvent = true;
         view = reduceEvent(view, event);
         sync();

package/dist/tui/components.js

@@ -30,7 +30,7 @@ export class Header {
     render(width) {
         const i = this.info(), v = this.view();
         const line1 = line([
-            { text: "◆ alisio", priority: 8, paint: (t) => style.bold(style.brightCyan(t)) },
+            { text: "◆ Alisio Code", priority: 8, paint: (t) => style.bold(style.brightCyan(t)) },
             { text: `v${i.version}`, priority: 1, paint: style.gray },
             {
                 text: v.model || "not connected",

package/dist/tui/settings.js

@@ -11,7 +11,7 @@ export const WEBSEARCH_PROVIDERS = [
 export const defaultConfig = {
     compaction: { auto: true, threshold: 0.85, keepTurns: 2, maxOutputTokens: 16_000 },
     context: { claudeMdFallback: false, maxBytes: 32 * 1024 },
-    limits: { maxTurns: 20, maxOutputTokens: 16_384, maxContextChars: 800_000, timeoutMs: 300_000 },
+    limits: { maxTurns: 100, maxOutputTokens: 16_384, maxContextChars: 800_000, timeoutMs: 300_000 },
     tui: { paddingX: 1, skillSlashCommands: true },
     mcp: { allow: false },
     websearch: { provider: undefined },
@@ -112,7 +112,7 @@ export const SETTINGS_DEFINITIONS = [
         valueType: "number",
         values: [5, 10, 15, 20, 30, 50, 100],
         read: (config) => config.limits.maxTurns,
-        description: "Maximum agent-loop turns per run before the run ends. Applied from the next run; longer tasks may need a higher budget.",
+        description: "Maximum agent-loop turns per run. Reaching the limit ends the run softly: everything so far is kept and the session stays usable, so you can just say continue. Raise it for long read-heavy audits. Applied from the next run.",
     },
     {
         id: "limits.maxOutputTokens",

package/dist/tui/state.js

@@ -529,7 +529,8 @@ export function reduceEvent(state, event) {
         }
         case "run_completed":
         case "run_failed":
-        case "run_cancelled": {
+        case "run_cancelled":
+        case "run_turns_exceeded": {
             const ended = {
                 ...state,
                 streaming: false,
@@ -541,6 +542,11 @@ export function reduceEvent(state, event) {
             };
             if (event.type === "run_failed")
                 return addItem(ended, { kind: "error", text: String(d.error ?? "Run failed") });
+            if (event.type === "run_turns_exceeded")
+                return addItem(ended, {
+                    kind: "notice",
+                    text: "Turn limit reached — the answer may be incomplete. Continue with another prompt or raise limits.maxTurns (/settings → Max turns).",
+                });
             if (event.type === "run_cancelled") {
                 const reason = String(d.error ?? "cancelled");
                 return addItem(ended, {

package/dist/version.d.ts

@@ -1,8 +1,10 @@
 /**
- * Reads the package version at runtime so --version, doctor, plugin metadata and MCP client
- * metadata stay in sync with the published package without a build-time constant to update.
- * The manifest is resolved relative to the module (`src/version.ts` → `../package.json` in the
- * source tree; `dist/version.js` → `../package.json` of the installed package). Standalone
- * binaries inject the version at build time via ALISIO_PACKAGE_VERSION (scripts/binary-build.ts).
+ * Reads the package version at runtime so --version, the TUI header, doctor, plugin metadata and
+ * MCP client metadata stay in sync with the published package without a build-time constant to
+ * update. The manifest is resolved by walking UP from the module directory until a package.json
+ * with a string `version` is found (bounded, any depth: module, then up to 8 parents), so deeply
+ * nested call sites like `src/tui/app.ts` and compiled `dist/*` resolve the same manifest as
+ * `src/main.ts`. Standalone binaries inject the version at build time via
+ * ALISIO_PACKAGE_VERSION (scripts/binary-build.ts).
  */
 export declare function loadVersion(fromHere: string): string;

package/dist/version.js

@@ -8,19 +8,55 @@ import { fileURLToPath } from "node:url";
  */
 const FALLBACK = "dev";
 /**
- * Reads the package version at runtime so --version, doctor, plugin metadata and MCP client
- * metadata stay in sync with the published package without a build-time constant to update.
- * The manifest is resolved relative to the module (`src/version.ts` → `../package.json` in the
- * source tree; `dist/version.js` → `../package.json` of the installed package). Standalone
- * binaries inject the version at build time via ALISIO_PACKAGE_VERSION (scripts/binary-build.ts).
+ * How many parent directories the loader walks up before giving up. Bounded so a missing
+ * manifest can never make the lookup climb an unbounded path.
+ */
+const MAX_PARENT_HOPS = 8;
+/** Manifests whose `name` identifies the CLI package; preferred when several are hit. */
+const CLI_MANIFEST_NAMES = new Set(["@alisio/alisio-code", "alisio"]);
+/**
+ * Walks up from `dir` looking for a package manifest. Returns the version of the nearest
+ * manifest that declares a string `version`, preferring a manifest whose `name` identifies the
+ * CLI package (`@alisio/alisio-code`/`alisio`) when several are hit — e.g. running from source
+ * inside the monorepo, where the repo-root manifest is also a candidate. `undefined` when no
+ * manifest with a version is reached within the bound.
+ */
+function findManifestVersion(dir) {
+    let nearest;
+    let current = dir;
+    for (let hop = 0; hop <= MAX_PARENT_HOPS; hop++) {
+        try {
+            const parsed = JSON.parse(readFileSync(join(current, "package.json"), "utf8"));
+            if (typeof parsed.version === "string" && parsed.version) {
+                if (typeof parsed.name === "string" && CLI_MANIFEST_NAMES.has(parsed.name))
+                    return parsed.version;
+                nearest ??= parsed.version;
+            }
+        }
+        catch {
+            // No manifest here; keep walking up.
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            break; // Filesystem root.
+        current = parent;
+    }
+    return nearest;
+}
+/**
+ * Reads the package version at runtime so --version, the TUI header, doctor, plugin metadata and
+ * MCP client metadata stay in sync with the published package without a build-time constant to
+ * update. The manifest is resolved by walking UP from the module directory until a package.json
+ * with a string `version` is found (bounded, any depth: module, then up to 8 parents), so deeply
+ * nested call sites like `src/tui/app.ts` and compiled `dist/*` resolve the same manifest as
+ * `src/main.ts`. Standalone binaries inject the version at build time via
+ * ALISIO_PACKAGE_VERSION (scripts/binary-build.ts).
  */
 export function loadVersion(fromHere) {
     if (process.env.ALISIO_PACKAGE_VERSION)
         return process.env.ALISIO_PACKAGE_VERSION;
     try {
-        const manifest = join(dirname(fileURLToPath(fromHere)), "..", "package.json");
-        const parsed = JSON.parse(readFileSync(manifest, "utf8"));
-        return typeof parsed.version === "string" && parsed.version ? parsed.version : FALLBACK;
+        return findManifestVersion(dirname(fileURLToPath(fromHere))) ?? FALLBACK;
     }
     catch {
         return FALLBACK;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alisio/alisio-code",
-  "version": "0.1.0-alpha.12",
+  "version": "0.1.0-alpha.13",
   "description": "Alisio: an extensible, provider-agnostic coding-agent harness for your terminal. TUI, OpenAI-compatible providers, permissioned local tools, context compaction, persistent memory and a typed plugin SDK.",
   "author": "Gustavo Gutiérrez",
   "license": "MIT",
@@ -45,14 +45,14 @@
     "alisio": "./dist/main.js"
   },
   "dependencies": {
-    "@alisio/core": "0.1.0-alpha.10",
-    "@alisio/plugin-deepseek": "0.1.0-alpha.8",
-    "@alisio/plugin-memory": "0.1.0-alpha.6",
-    "@alisio/plugin-openai-compatible": "0.1.0-alpha.8",
-    "@alisio/plugin-opencode": "0.1.0-alpha.7",
-    "@alisio/plugin-opencode-go": "0.1.0-alpha.7",
-    "@alisio/plugin-subagents": "0.1.0-alpha.7",
-    "@alisio/sdk": "0.1.0-alpha.6",
+    "@alisio/core": "0.1.0-alpha.11",
+    "@alisio/plugin-deepseek": "0.1.0-alpha.9",
+    "@alisio/plugin-memory": "0.1.0-alpha.7",
+    "@alisio/plugin-openai-compatible": "0.1.0-alpha.9",
+    "@alisio/plugin-opencode": "0.1.0-alpha.8",
+    "@alisio/plugin-opencode-go": "0.1.0-alpha.8",
+    "@alisio/plugin-subagents": "0.1.0-alpha.8",
+    "@alisio/sdk": "0.1.0-alpha.7",
     "@earendil-works/pi-tui": "0.87.1",
     "commander": "15.0.0"
   },