@alisio/core 0.1.0-alpha.11 → 0.1.0-alpha.13

package/dist/application.d.ts

@@ -171,6 +171,8 @@ export declare function createApplication(options?: AppOptions): Promise<{
      * (next instructions load), `websearch.provider` mutates the shared config object the search
      * chain reads per call, `pluginHooks.timeoutMs` lands in the plugin host (next hook call),
      * and `tui.*` is persisted for the host to apply. Nothing in this set requires a restart.
+     * `agents.*` (active agent id and reasoning effort) is persisted for the TUI to consume:
+     * the next `/agents`/`/effort` selection and the next prompt already read the live config.
      * `mcp.allow` is deliberately not routed here: it flows through
      * `rememberGlobalMcpConsent`/`revokeGlobalMcpConsent` instead.
      * Throws under `--read-only`. Returns the written config file.

package/dist/application.js

@@ -743,6 +743,8 @@ export async function createApplication(options = {}) {
              * (next instructions load), `websearch.provider` mutates the shared config object the search
              * chain reads per call, `pluginHooks.timeoutMs` lands in the plugin host (next hook call),
              * and `tui.*` is persisted for the host to apply. Nothing in this set requires a restart.
+             * `agents.*` (active agent id and reasoning effort) is persisted for the TUI to consume:
+             * the next `/agents`/`/effort` selection and the next prompt already read the live config.
              * `mcp.allow` is deliberately not routed here: it flows through
              * `rememberGlobalMcpConsent`/`revokeGlobalMcpConsent` instead.
              * Throws under `--read-only`. Returns the written config file.
@@ -790,6 +792,16 @@ export async function createApplication(options = {}) {
                     case "tui.skillSlashCommands":
                         config.tui = { ...config.tui, skillSlashCommands: value === true };
                         break;
+                    case "agents.active":
+                        config.agents = { ...config.agents, active: String(value) };
+                        break;
+                    case "agents.effort":
+                        // Clearing (undefined) drops the leaf from the live config and the JSON file.
+                        config.agents =
+                            value === undefined
+                                ? { active: config.agents.active }
+                                : { ...config.agents, effort: String(value) };
+                        break;
                     case "websearch.provider":
                         // Mutated in place (same object identity) so the tool chain's per-call
                         // `websearchCtx.config` sees the new provider on the very next search call.

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";
@@ -176,6 +177,10 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
         paddingX: z.ZodDefault<z.ZodNumber>;
         skillSlashCommands: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strict>>;
+    agents: z.ZodDefault<z.ZodObject<{
+        active: z.ZodDefault<z.ZodString>;
+        effort: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
 }, z.core.$strict>, z.ZodTransform<{
     schemaVersion: 1;
     provider: {
@@ -215,7 +220,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;
@@ -231,6 +236,10 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
         paddingX: number;
         skillSlashCommands: boolean;
     };
+    agents: {
+        active: string;
+        effort?: string | undefined;
+    };
     mcp: {
         allow?: boolean | undefined;
         servers: {
@@ -353,7 +362,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;
@@ -369,6 +378,10 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
         paddingX: number;
         skillSlashCommands: boolean;
     };
+    agents: {
+        active: string;
+        effort?: string | undefined;
+    };
 }>>;
 export type Config = z.infer<typeof configSchema>;
 export type ServerConfig = z.infer<typeof serverSchema>;
@@ -444,12 +457,15 @@ 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";
         serpapi: "serpapi";
         tavily: "tavily";
     }>>;
+    readonly "agents.active": z.ZodDefault<z.ZodString>;
+    readonly "agents.effort": z.ZodOptional<z.ZodString>;
 };
 export type SettableSettingKey = keyof typeof SETTABLE_KEYS;
 export declare function isSettableSettingKey(key: string): key is SettableSettingKey;

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(),
@@ -180,6 +188,27 @@ const configObjectSchema = z
     })
         .strict()
         .default(() => ({ paddingX: 1, skillSlashCommands: true })),
+    /**
+     * The ACTIVE agent drives the main session: its system prompt is appended to every prompt and
+     * its optional model selector is offered when the agent is chosen (`/agents`). `build` is the
+     * built-in default (full-power, no added persona); `plan` is the built-in read-only planner.
+     * `effort` holds a reasoning effort level chosen with `/effort` for a model that advertises
+     * `effort.supportedLevels`; it is validated against the ACTIVE model on use, falling back to
+     * the model's default level when unsupported.
+     */
+    agents: z
+        .object({
+        active: z
+            .string()
+            .trim()
+            .min(1)
+            .max(100)
+            .regex(/^[a-zA-Z0-9][a-zA-Z0-9._:-]*$/, "invalid agent name")
+            .default("build"),
+        effort: z.string().trim().min(1).max(50).optional(),
+    })
+        .strict()
+        .default(() => ({ active: "build" })),
 })
     .strict()
     .superRefine((config, context) => {
@@ -426,6 +455,7 @@ const SETTABLE_SECTIONS = {
     pluginHooks: configObjectSchema.shape.pluginHooks.removeDefault(),
     tui: configObjectSchema.shape.tui.removeDefault(),
     websearch: configObjectSchema.shape.websearch.removeDefault(),
+    agents: configObjectSchema.shape.agents.removeDefault(),
 };
 const SETTABLE_KEYS = {
     "compaction.auto": SETTABLE_SECTIONS.compaction.shape.auto,
@@ -442,6 +472,8 @@ const SETTABLE_KEYS = {
     "tui.paddingX": SETTABLE_SECTIONS.tui.shape.paddingX,
     "tui.skillSlashCommands": SETTABLE_SECTIONS.tui.shape.skillSlashCommands,
     "websearch.provider": SETTABLE_SECTIONS.websearch.shape.provider,
+    "agents.active": SETTABLE_SECTIONS.agents.shape.active,
+    "agents.effort": SETTABLE_SECTIONS.agents.shape.effort,
 };
 export function isSettableSettingKey(key) {
     return Object.prototype.hasOwnProperty.call(SETTABLE_KEYS, key);

package/dist/core/compaction.js

@@ -381,6 +381,7 @@ async function completeTextWithMeta(provider, request) {
         signal: request.signal,
         ...(request.model ? { model: request.model } : {}),
         ...(request.sessionId ? { sessionId: request.sessionId } : {}),
+        ...(request.reasoningEffort ? { reasoningEffort: request.reasoningEffort } : {}),
     })) {
         request.signal.throwIfAborted();
         if (event.type === "completed") {

package/dist/core/runner.d.ts

@@ -42,6 +42,11 @@ export interface RunnerOptions {
      * runner; only meaningful for a provider that documents an equivalent server-side tool.
      */
     nativeTools?: Array<Record<string, unknown>>;
+    /**
+     * Default reasoning effort level (a value from the current model's `ModelInfo.effort`), sent on
+     * every run unless overridden per-run. Providers that do not advertise effort levels ignore it.
+     */
+    reasoningEffort?: string;
 }
 /** The settings a running TUI can change live; merged into the runner options on apply. */
 export interface RunnerSettingsPatch {
@@ -80,6 +85,8 @@ export interface RunOptions {
     /** Per-call output token budget for this run; beats the runner-level budget when set. */
     maxOutputTokens?: number;
     timeoutMs?: number;
+    /** Reasoning effort level for this run; beats the runner-level default when set. */
+    reasoningEffort?: string;
 }
 /**
  * Default cumulative token budget for one run: several context windows (each turn re-sends the

package/dist/core/runner.js

@@ -418,6 +418,9 @@ export class AgentRunner {
                     model,
                     sessionId,
                     ...(o.nativeTools?.length ? { nativeTools: o.nativeTools } : {}),
+                    ...((options.reasoningEffort ?? o.reasoningEffort)
+                        ? { reasoningEffort: options.reasoningEffort ?? o.reasoningEffort }
+                        : {}),
                 })) {
                     combined.throwIfAborted();
                     if (e.type === "text_delta")

package/dist/plugins/host.d.ts

@@ -72,6 +72,12 @@ export declare class PluginHost implements RunnerExtensions {
         askQuestions(request: AskQuestionsRequest): Promise<AskQuestionsResult>;
         open(sessionId: string): boolean;
     }): void;
+    /**
+     * Read-only view of one plugin's shared state (written through `api.state.set`). The host layer
+     * uses this to consume plugin-published data (for example the main-capable agent definitions the
+     * built-in subagents plugin publishes) without importing the plugin package.
+     */
+    pluginState(plugin: string, key: string): unknown;
     get sessions(): PluginAPI["sessions"];
     /**
      * Live accessor for core standard tools (e.g. `ask_user_question`), which are not "a plugin"

package/dist/plugins/host.js

@@ -60,6 +60,14 @@ export class PluginHost {
     setInteractiveUI(ui) {
         this.uiImpl = ui;
     }
+    /**
+     * Read-only view of one plugin's shared state (written through `api.state.set`). The host layer
+     * uses this to consume plugin-published data (for example the main-capable agent definitions the
+     * built-in subagents plugin publishes) without importing the plugin package.
+     */
+    pluginState(plugin, key) {
+        return this.state.getState(plugin, key);
+    }
     get sessions() {
         if (!this.sessionsImpl)
             throw new Error("Child sessions are not available yet");

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alisio/core",
-  "version": "0.1.0-alpha.11",
+  "version": "0.1.0-alpha.13",
   "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.7",
+    "@alisio/sdk": "0.1.0-alpha.8",
     "@mixmark-io/domino": "2.2.0",
     "@modelcontextprotocol/client": "2.1.0",
     "ajv": "8.20.0",