@alisio/core 0.1.0-alpha.10 → 0.1.0-alpha.12

package/README.md

@@ -1,9 +1,24 @@
 # @alisio/core
 
-Embeddable core of [Alisio](https://github.com/GustavoGutierrez/alisio): the agent tool loop, structured
-context compaction, the OpenAI-compatible provider (Chat Completions and Responses), local tools with
-explicit permissions, the MCP client, the plugin host (with hook timeouts and failure isolation) and a
-SQLite session store. Runs on Node.js >= 22.16 (`node:sqlite` with FTS5) and on Bun.
+**The embeddable core of [Alisio](https://github.com/GustavoGutierrez/alisio): a provider-agnostic
+agent you can drive from your own program.** No TUI, no CLI — just the tool loop, compaction, MCP
+and plugin host as a library.
+
+## What it is
+
+`@alisio/core` wires the agent tool loop, structured context compaction, the OpenAI-compatible
+provider (Chat Completions and Responses), local tools behind explicit permissions, the MCP client,
+the plugin host (hook timeouts and failure isolation) and a SQLite session store into one
+`createApplication` entry point. It runs on Node.js >= 22.16 (`node:sqlite` with FTS5) and on Bun,
+and uses only portable Node APIs.
+
+## Installation
+
+```sh
+npm i @alisio/core        # or: pnpm add @alisio/core · bun add @alisio/core
+```
+
+## Quick start
 
 ```ts
 import { createApplication } from "@alisio/core";
@@ -18,8 +33,38 @@ try {
 }
 ```
 
+## What you get
+
+- **Runner**: `AgentRunner` with turn limits, timeouts, token budgets and versioned `RunEvent`
+  output (`schemaVersion: 1`).
+- **Context compaction**: `planCompaction`, `summarize`, `renderCheckpoint`,
+  `shouldCompactContext` and checkpoint helpers; memory plugins hook in via `CompactionHooks`.
+- **Providers**: `ProviderRegistry` / `ActiveProvider` for OpenAI-compatible, DeepSeek, OpenCode
+  Console and OpenCode Go; `ProviderSettingsStore` for non-secret profiles plus a separate
+  credentials store.
+- **Local tools**: reads by default, `--allow-write`/`--allow-process`-style policy, path checks
+  and standard tools (`ToolRegistry`, `registerStandard`).
+- **MCP**: `McpConnector`, server discovery and tool projection.
+- **Plugin host**: `PluginHost` with built-in plugin catalogs, npm install (`installPlugin`,
+  `cliInstall`), hook timeouts and failure isolation.
+- **Sessions**: `SQLiteStore` with reconciliation and crash recovery.
+- **Skills and prompts**: `Skills`, `ProjectContext` (`AGENTS.md`), `loadPromptTemplates`.
+- **Trust**: `resolveTrust` / `setTrust` / `listTrust` for per-directory project trust.
+- **Startup screen**: reusable `renderStartup` sections and the default mascot.
+
 Built-in plugins are opt-in for embedders: pass `builtins` (the `alisio` CLI wires
-`@alisio/plugin-memory`). See the [architecture](https://gustavogutierrez.github.io/alisio/architecture) and
-[configuration](https://gustavogutierrez.github.io/alisio/configuration) docs.
+`@alisio/plugin-memory` and `@alisio/plugin-subagents`).
+
+## Docs
+
+Architecture: <https://gustavogutierrez.github.io/alisio/architecture> ·
+Configuration: <https://gustavogutierrez.github.io/alisio/configuration>.
+
+## Requirements
+
+Node.js **>= 22.16** or Bun **>= 1.4.2**.
+
+## 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/config.d.ts

@@ -155,6 +155,7 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
     websearch: z.ZodDefault<z.ZodObject<{
         provider: z.ZodOptional<z.ZodEnum<{
             brave: "brave";
+            "duckduckgo-html": "duckduckgo-html";
             "duckduckgo-instant": "duckduckgo-instant";
             native: "native";
             searxng: "searxng";
@@ -215,7 +216,7 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
         maxOutputTokens: number;
     };
     websearch: {
-        provider?: "brave" | "duckduckgo-instant" | "native" | "searxng" | "serpapi" | "tavily" | undefined;
+        provider?: "brave" | "duckduckgo-html" | "duckduckgo-instant" | "native" | "searxng" | "serpapi" | "tavily" | undefined;
         searxngUrl?: string | undefined;
         apiKeyEnv?: string | undefined;
         nativeToolType: string;
@@ -353,7 +354,7 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
         maxOutputTokens: number;
     };
     websearch: {
-        provider?: "brave" | "duckduckgo-instant" | "native" | "searxng" | "serpapi" | "tavily" | undefined;
+        provider?: "brave" | "duckduckgo-html" | "duckduckgo-instant" | "native" | "searxng" | "serpapi" | "tavily" | undefined;
         searxngUrl?: string | undefined;
         apiKeyEnv?: string | undefined;
         nativeToolType: string;
@@ -444,6 +445,7 @@ declare const SETTABLE_KEYS: {
     readonly "tui.skillSlashCommands": z.ZodDefault<z.ZodBoolean>;
     readonly "websearch.provider": z.ZodOptional<z.ZodEnum<{
         brave: "brave";
+        "duckduckgo-html": "duckduckgo-html";
         "duckduckgo-instant": "duckduckgo-instant";
         native: "native";
         searxng: "searxng";

package/dist/config.js

@@ -140,7 +140,15 @@ const configObjectSchema = z
     websearch: z
         .object({
         provider: z
-            .enum(["searxng", "duckduckgo-instant", "tavily", "brave", "serpapi", "native"])
+            .enum([
+            "searxng",
+            "duckduckgo-instant",
+            "duckduckgo-html",
+            "tavily",
+            "brave",
+            "serpapi",
+            "native",
+        ])
             .optional(),
         searxngUrl: z.string().optional(),
         apiKeyEnv: z.string().optional(),
@@ -151,7 +159,7 @@ const configObjectSchema = z
         .default(() => ({ nativeToolType: "web_search" })),
     limits: z
         .object({
-        maxTurns: z.number().int().min(1).max(100).default(20),
+        maxTurns: z.number().int().min(1).max(100).default(100),
         timeoutMs: z.number().int().min(100).default(300000),
         maxContextChars: z.number().int().positive().default(800000),
         /**
@@ -163,7 +171,7 @@ const configObjectSchema = z
         maxTokens: z.number().int().positive().optional(),
     })
         .default(() => ({
-        maxTurns: 20,
+        maxTurns: 100,
         timeoutMs: 300000,
         maxContextChars: 800000,
         maxOutputTokens: 16384,

package/dist/core/runner.js

@@ -348,7 +348,8 @@ export class AgentRunner {
             emit("run_started", { model });
             const budget = options.maxTokens ?? o.maxTokens ?? defaultTokenBudget(o.contextWindow?.(model));
             const compaction = o.compaction ?? {};
-            for (let turn = 0; turn < (options.maxTurns ?? o.maxTurns ?? 20); turn++) {
+            const maxTurns = options.maxTurns ?? o.maxTurns ?? 100;
+            for (let turn = 0; turn < maxTurns; turn++) {
                 combined.throwIfAborted();
                 // Input queued while the run was working (e.g. a parent's message to a child).
                 if (turn > 0)
@@ -606,7 +607,12 @@ export class AgentRunner {
                 if (tokens >= budget)
                     throw new Error("Token budget exhausted");
             }
-            throw new Error("Maximum turns reached");
+            // Turn cap reached. This is NOT a failure: everything produced up to this point stays in
+            // the transcript and the run returns a successful-but-marked partial result, so the user
+            // can simply prompt again to continue in the same session. The real hard stops remain the
+            // token budget (`maxTokens`) and the timeout; the turn count is a safety rail.
+            emit("run_turns_exceeded", { turns: maxTurns, maxTurns });
+            return { sessionId, text: lastText, status: "turns-exceeded", usage: usageTotal };
         }
         catch (error) {
             // On cancellation report the abort reason, not the transport's secondary error.

package/dist/sessions/children.js

@@ -160,8 +160,18 @@ export class ChildSessions {
             });
             usage.input += result.usage.input;
             usage.output += result.usage.output;
+            // A child that hit its turn limit still produced a usable partial result: it completes
+            // with a turnsExceeded marker instead of failing, so orchestration treats the text as
+            // partial output. state "failed" stays reserved for real errors/aborts.
+            const turnsExceeded = result.status === "turns-exceeded";
             this.o.store.updateSession(id, { status: "completed", usage });
-            return { id, status: "completed", text: result.text, usage };
+            return {
+                id,
+                status: "completed",
+                text: result.text,
+                usage,
+                ...(turnsExceeded ? { turnsExceeded: true } : {}),
+            };
         }
         catch (error) {
             const aborted = this.cancelled.has(id) || signals.some((s) => s.aborted);

package/dist/tools/search.d.ts

@@ -8,8 +8,8 @@
  *      A throwing plugin provider falls back to the built-in chain with a diagnostic, never a hard
  *      failure of the tool call.
  *   2. `websearch.provider` from config, when set: `"searxng"` (with a custom `searxngUrl`),
- *      `"duckduckgo-instant"`, `"tavily"`, `"brave"` or `"serpapi"` (the last three need an API key
- *      env var).
+ *      `"duckduckgo-instant"`, `"duckduckgo-html"`, `"tavily"`, `"brave"` or `"serpapi"` (the last
+ *      three need an API key env var).
  *   3. Nothing configured: a public SearXNG instance (see `DEFAULT_SEARXNG_URL`) — genuinely free
  *      and keyless, but empirically unreliable: while building this tool, nearly every public
  *      instance tried (searx.be and several others from https://searx.space) rate-limited or
@@ -23,7 +23,7 @@
  */
 import type { SearchProvider, SearchResult } from "@alisio/sdk";
 export interface WebsearchConfig {
-    provider?: "searxng" | "duckduckgo-instant" | "tavily" | "brave" | "serpapi" | "native";
+    provider?: "searxng" | "duckduckgo-instant" | "duckduckgo-html" | "tavily" | "brave" | "serpapi" | "native";
     /** Overrides the default public instance; self-hosted or another public instance. */
     searxngUrl?: string;
     /** Environment variable holding the API key for `tavily`, `brave` or `serpapi`. */
@@ -50,6 +50,20 @@ export declare function searxngProvider(baseUrl: string): SearchProvider;
  * search engine. Callers must not treat an empty result as "nothing found on the web".
  */
 export declare function duckDuckGoInstantProvider(): SearchProvider;
+/**
+ * Parses DuckDuckGo lite HTML into `SearchResult`s (exported so tests can exercise it without the
+ * network). Ignores every anchor that is not a `result-link` whose href starts with
+ * `//duckduckgo.com/l/?uddg=` — ads and related-search links never count. Snippets are taken from
+ * the `result-snippet` cell that follows each result and precedes the next one. Returns [] for a
+ * lite page that legitimately has no results.
+ */
+export declare function parseDuckDuckGoLiteHtml(html: string): SearchResult[];
+/**
+ * DuckDuckGo's keyless HTML "lite" endpoint: a real general web search (unlike the Instant Answer
+ * API), scraped without an API key or cookie machinery. Works when the default public SearXNG
+ * instance is bot-blocked. See `parseDuckDuckGoLiteHtml` for the HTML parsing contract.
+ */
+export declare function duckDuckGoHtmlProvider(): SearchProvider;
 export declare function tavilyProvider(apiKey: string): SearchProvider;
 export declare function braveProvider(apiKey: string): SearchProvider;
 export declare function serpApiProvider(apiKey: string): SearchProvider;

package/dist/tools/search.js

@@ -116,6 +116,150 @@ export function duckDuckGoInstantProvider() {
         },
     };
 }
+// --- DuckDuckGo lite (HTML) ---
+// The keyless `lite.duckduckgo.com/lite/` page answers a plain GET with real, general web-search
+// results (unlike the Instant Answer API). It is a scrape of HTML that DuckDuckGo may change at any
+// time, so the parser below is deliberately tolerant: only `result-link` anchors whose href goes
+// through the `//duckduckgo.com/l/?uddg=` redirector are trusted as results; ads/related links and
+// the surrounding table/div markup are ignored. Verified live (2026-09): the full
+// `html.duckduckgo.com/html/` endpoint returns HTTP 202 with a captcha challenge for automated
+// requests, while `lite.duckduckgo.com/lite/` answers HTTP 200 with results and no key.
+const DUCKDUCKGO_LITE_UA = "Mozilla/5.0 (X11; Linux x86_64; rv:130.0) Gecko/20100101 Firefox/130.0";
+const DUCKDUCKGO_LITE_URL = "https://lite.duckduckgo.com/lite/";
+/** Minimal local HTML-entity decoder (no dependency): the common named ones plus numeric forms. */
+function decodeHtmlEntities(text) {
+    return text.replace(/&(#x?[0-9a-fA-F]+|amp|lt|gt|quot|apos|nbsp);/g, (raw, entity) => {
+        const lower = entity.toLowerCase();
+        if (lower === "amp")
+            return "&";
+        if (lower === "lt")
+            return "<";
+        if (lower === "gt")
+            return ">";
+        if (lower === "quot")
+            return '"';
+        if (lower === "apos")
+            return "'";
+        if (lower === "nbsp")
+            return "\u00a0";
+        try {
+            const code = lower.startsWith("#x")
+                ? parseInt(lower.slice(2), 16)
+                : lower.startsWith("#")
+                    ? parseInt(lower.slice(1), 10)
+                    : NaN;
+            return Number.isFinite(code) && code >= 0 && code <= 0x10ffff
+                ? String.fromCodePoint(code)
+                : raw;
+        }
+        catch {
+            return raw;
+        }
+    });
+}
+/** Strips tags and collapses whitespace, keeping the text usable as a title or snippet. */
+function htmlToText(fragment) {
+    return decodeHtmlEntities(fragment.replace(/<[^>]*>/g, ""))
+        .replace(/\s+/g, " ")
+        .trim();
+}
+const RESULT_LINK = /<a\b[^>]*class=['"]result-link['"][^>]*>([\s\S]*?)<\/a>/gi;
+const HREF_ATTR = /href\s*=\s*"([^"]*)"/i;
+const SNIPPET_CELL = /class=['"]result-snippet['"]>([\s\S]*?)<\/td>/gi;
+const UDDG_PARAM = /uddg=([^&"]+)/i;
+/**
+ * Parses DuckDuckGo lite HTML into `SearchResult`s (exported so tests can exercise it without the
+ * network). Ignores every anchor that is not a `result-link` whose href starts with
+ * `//duckduckgo.com/l/?uddg=` — ads and related-search links never count. Snippets are taken from
+ * the `result-snippet` cell that follows each result and precedes the next one. Returns [] for a
+ * lite page that legitimately has no results.
+ */
+export function parseDuckDuckGoLiteHtml(html) {
+    const anchors = [...html.matchAll(RESULT_LINK)];
+    const snippets = [...html.matchAll(SNIPPET_CELL)];
+    const results = [];
+    for (let i = 0; i < anchors.length; i++) {
+        const anchor = anchors[i];
+        const tag = anchor[0];
+        const href = HREF_ATTR.exec(tag)?.[1] ?? "";
+        if (!href.startsWith("//duckduckgo.com/l/?uddg="))
+            continue;
+        const raw = UDDG_PARAM.exec(href)?.[1];
+        let url = "";
+        if (raw) {
+            try {
+                url = decodeURIComponent(raw);
+            }
+            catch {
+                url = "";
+            }
+        }
+        if (!url)
+            continue;
+        const title = htmlToText(anchor[1] ?? "");
+        if (!title)
+            continue;
+        let snippet = "";
+        const limit = anchors[i + 1] ? anchors[i + 1].index : html.length;
+        for (const cell of snippets) {
+            if (cell.index !== undefined && cell.index > (anchor.index ?? 0) && cell.index < limit) {
+                snippet = htmlToText(cell[1] ?? "");
+                break;
+            }
+        }
+        results.push({ title, url, snippet });
+    }
+    return results;
+}
+/**
+ * DuckDuckGo's keyless HTML "lite" endpoint: a real general web search (unlike the Instant Answer
+ * API), scraped without an API key or cookie machinery. Works when the default public SearXNG
+ * instance is bot-blocked. See `parseDuckDuckGoLiteHtml` for the HTML parsing contract.
+ */
+export function duckDuckGoHtmlProvider() {
+    return {
+        id: "duckduckgo-html",
+        async search(query, options) {
+            const url = new URL(DUCKDUCKGO_LITE_URL);
+            url.searchParams.set("q", query);
+            url.searchParams.set("kl", "us-en");
+            let res;
+            try {
+                res = await fetch(url, {
+                    headers: { "User-Agent": DUCKDUCKGO_LITE_UA, Accept: "text/html" },
+                    // Never follow a redirect blindly: on this endpoint a redirect is a bot-check detour,
+                    // not a moved page, and following it would just land on a captcha.
+                    redirect: "error",
+                    signal: options?.signal,
+                });
+            }
+            catch (error) {
+                throw new Error(`DuckDuckGo lite search request failed: ${error instanceof Error ? error.message : String(error)}. The provider is duckduckgo-html (${DUCKDUCKGO_LITE_URL}); possible causes: a network ` +
+                    "failure, a redirect (treated as a bot-check detour), or rate limiting. Try again later " +
+                    "or switch websearch.provider via /settings.");
+            }
+            if (res.status !== 200) {
+                throw new Error(`DuckDuckGo lite search failed: HTTP ${res.status}. The endpoint may be showing a ` +
+                    "bot-check/captcha challenge instead of results (the full html.duckduckgo.com endpoint " +
+                    "returns HTTP 202 for automated requests). Try again later, or switch websearch.provider " +
+                    "via /settings (e.g. searxng with your own instance).");
+            }
+            const html = await res.text();
+            if (html.length <= 200) {
+                throw new Error("DuckDuckGo lite search returned an unexpectedly empty response (no HTML to parse); the " +
+                    "endpoint may be bot-blocked. Try again later or switch websearch.provider via /settings.");
+            }
+            if (!html.includes("result-link") &&
+                !html.includes("result-snippet") &&
+                !/action=['"]\/lite\/['"]/.test(html)) {
+                throw new Error("DuckDuckGo lite did not return recognizable DuckDuckGo lite HTML results; it may be " +
+                    "showing a bot-check/captcha challenge instead. Try again later or switch " +
+                    "websearch.provider via /settings.");
+            }
+            return parseDuckDuckGoLiteHtml(html).slice(0, 10);
+        },
+    };
+}
 export function tavilyProvider(apiKey) {
     return {
         id: "tavily",
@@ -197,6 +341,15 @@ function resolveBuiltin(config) {
             limitation: "DuckDuckGo's Instant Answer API only answers direct factual/infobox-style queries, not " +
                 "general web search. An empty result here does not mean nothing exists on the web.",
         };
+    if (provider === "duckduckgo-html")
+        return {
+            provider: duckDuckGoHtmlProvider(),
+            source: "duckduckgo-html",
+            limitation: "DuckDuckGo lite HTML provider: keyless and free, but it scrapes HTML DuckDuckGo may " +
+                "change at any time, and heavy automation can be bot-checked. Use it as a keyless fallback " +
+                "when the default public SearXNG instance is bot-blocked; self-hosted SearXNG remains the " +
+                "most reliable option.",
+        };
     if (provider === "native")
         throw new Error('websearch.provider is "native": search runs server-side through the model provider; ' +
             "this tool should never be registered or called in that mode.");

package/dist/version.d.ts

@@ -1,7 +1,9 @@
 /**
  * Reads the @alisio/core package version at runtime so the MCP client metadata stays in sync
- * with the published package. Resolves the manifest relative to the module (`src/version.ts` →
- * `../package.json` in the source tree; `dist/version.js` → `../package.json` when installed).
- * Standalone binaries inject ALISIO_PACKAGE_VERSION at build time (scripts/binary-build.ts).
+ * with the published package. 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 a deeply nested call site like `src/mcp/connector.ts` resolves the same
+ * manifest as `src/version.ts`. Standalone binaries inject ALISIO_PACKAGE_VERSION at build time
+ * (scripts/binary-build.ts).
  */
 export declare function loadVersion(fromHere: string): string;

package/dist/version.js

@@ -6,19 +6,48 @@ import { fileURLToPath } from "node:url";
  * A development marker, never a publish literal: it cannot silently desync from the package.
  */
 const FALLBACK = "dev";
+/**
+ * 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;
+/**
+ * Walks up from `dir` looking for a package manifest. Returns the version of the nearest
+ * manifest that declares a string `version`. `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)
+                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 @alisio/core package version at runtime so the MCP client metadata stays in sync
- * with the published package. Resolves the manifest relative to the module (`src/version.ts` →
- * `../package.json` in the source tree; `dist/version.js` → `../package.json` when installed).
- * Standalone binaries inject ALISIO_PACKAGE_VERSION at build time (scripts/binary-build.ts).
+ * with the published package. 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 a deeply nested call site like `src/mcp/connector.ts` resolves the same
+ * manifest as `src/version.ts`. Standalone binaries inject ALISIO_PACKAGE_VERSION at build time
+ * (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/core",
-  "version": "0.1.0-alpha.10",
+  "version": "0.1.0-alpha.12",
   "description": "Embeddable provider-agnostic Alisio agent core: tool loop, context compaction, local tools, MCP, plugin host and SQLite session store. Runs on Node >=22.16 and Bun.",
   "author": "Gustavo Gutiérrez",
   "license": "MIT",
@@ -41,7 +41,7 @@
     "node": ">=22.16"
   },
   "dependencies": {
-    "@alisio/sdk": "0.1.0-alpha.6",
+    "@alisio/sdk": "0.1.0-alpha.7",
     "@mixmark-io/domino": "2.2.0",
     "@modelcontextprotocol/client": "2.1.0",
     "ajv": "8.20.0",