@alisio/core 0.2.0 → 0.3.0

package/dist/plugins/host.d.ts

@@ -1,6 +1,9 @@
-import type { AskQuestionsRequest, AskQuestionsResult, CommandContext, CommandOptions, CompletionRequest, Message, PanelProvider, Plugin, PluginAPI, PluginMetadata, RunEvent, SelectRequest, ViewContext } from "@alisio/sdk";
+import type { AskQuestionsRequest, AskQuestionsResult, CommandContext, CommandOptions, CompletionRequest, JsonValue, Message, PanelProvider, Plugin, PluginAPI, PluginMetadata, RunEvent, SelectRequest, ViewContext } from "@alisio/sdk";
 import type { HookFailure, RunnerExtensions } from "../core/contracts.ts";
+import type { HumanWaits } from "../core/human-wait.ts";
 import type { ToolRegistry } from "../core/registry.ts";
+import type { DecisionRegistry } from "../decisions/registry.ts";
+import type { DecisionService } from "../decisions/service.ts";
 import { ExtensionRegistry } from "../extensions/registry.ts";
 import type { ProviderRegistry } from "../providers/registry.ts";
 export declare const pluginPrefix: (id: string) => string;
@@ -9,6 +12,16 @@ export interface PluginHostOptions {
     hookTimeoutMs?: number;
     /** Timeout for session-end hooks (for example an automatic summary). */
     sessionEndTimeoutMs?: number;
+    /** Per-plugin limit for `dispose()` on close (default 2000 ms). */
+    disposeTimeoutMs?: number;
+}
+/** What the host needs to hand each plugin its `api.paths` and `api.options`. */
+export interface PluginEnvironment {
+    /** Root of the application state (the one analysis and artifacts use). */
+    stateRoot: string;
+    configHome: string;
+    /** `pluginOverrides[id].options` (external) or `builtinPlugins.<id>` without `enabled`. */
+    options(id: string, builtin: boolean): Record<string, JsonValue>;
 }
 /** A failed data view: the host maps `code` to an API error (never echoing parameter values). */
 export declare class ViewRunError extends Error {
@@ -83,7 +96,15 @@ export declare class PluginHost implements RunnerExtensions {
     private uiImpl?;
     /** Binds the child session service once the runner exists. */
     setSessions(sessions: PluginAPI["sessions"]): void;
-    /** Binds interactive UI services (the TUI); without them select/askQuestions resolve undefined. */
+    /** Where waits for a person are opened (see `HumanWaits`); bound once the runner exists. */
+    private humanWaits?;
+    setHumanWaits(waits: HumanWaits): void;
+    /**
+     * Binds interactive UI services (the TUI, the web server); without them select/askQuestions
+     * resolve undefined. Every question that reaches the person through here (plugins, the
+     * `ask_user_question` tool, the plan review) is a human wait: the bound UI is wrapped ONCE so no
+     * host and no caller can forget to mark it.
+     */
     setInteractiveUI(ui: {
         select(request: SelectRequest): Promise<string | undefined>;
         askQuestions(request: AskQuestionsRequest): Promise<AskQuestionsResult>;
@@ -123,6 +144,21 @@ export declare class PluginHost implements RunnerExtensions {
     setCompleter(fn: (request: CompletionRequest & {
         signal: AbortSignal;
     }) => Promise<string>): void;
+    /**
+     * Binds Decision Intelligence. Plugins activated afterwards see `api.decisions`; without it the
+     * member is absent, exactly like on a core that predates the feature.
+     */
+    setDecisions(decisions: {
+        registry: DecisionRegistry;
+        service: DecisionService;
+    }): void;
+    private decisionsImpl?;
+    /**
+     * Binds the directories and options plugins receive (`api.paths`, `api.options`). Plugins
+     * activated before this call, or on a host without it, see neither member.
+     */
+    setPluginEnvironment(environment: PluginEnvironment): void;
+    private environment?;
     /** Binds credential-free model discovery/resolution after provider startup is complete. */
     setModels(models: PluginAPI["models"]): void;
     /**
@@ -197,6 +233,11 @@ export declare class PluginHost implements RunnerExtensions {
     /** Conservative ownership check used to protect a live session from plugin removal. */
     ownsSessionResources(plugin: string): boolean;
     emit(event: RunEvent): void;
+    /**
+     * Disposes every plugin in parallel, each bounded by `disposeTimeoutMs`: a slow or hung
+     * `dispose()` neither delays the others nor holds the close past its limit. Registrations are
+     * undone either way. Failures (including a timeout) are reported together afterwards.
+     */
     close(): Promise<void>;
 }
 export declare function discoverPlugins(root: string): Promise<string[]>;

package/dist/plugins/host.js

@@ -7,17 +7,26 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 import { createHash } from "node:crypto";
+import { mkdirSync } from "node:fs";
 import { readdir, stat } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import Ajv from "ajv";
 import { z } from "zod";
 import { ExtensionRegistry } from "../extensions/registry.js";
-import { readJson } from "../runtime/fs.js";
+import { exists, readJson } from "../runtime/fs.js";
 import { resolvePluginSpec } from "../runtime/modules.js";
 import { inside } from "../runtime/paths.js";
 import { openDatabase } from "../runtime/sqlite.js";
 export const pluginPrefix = (id) => `p_${createHash("sha256").update(id).digest("hex").slice(0, 10)}`;
+const deepFreeze = (value) => {
+    if (value && typeof value === "object" && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            deepFreeze(child);
+    }
+    return value;
+};
 const VIEW_ID = /^[a-z][a-z0-9-]{0,39}$/;
 const VIEW_PARAM_TYPES = new Set(["string", "integer", "number", "boolean"]);
 /** Query strings arrive as text: coerce them to the declared primitives and apply defaults. */
@@ -85,9 +94,24 @@ export class PluginHost {
     setSessions(sessions) {
         this.sessionsImpl = sessions;
     }
-    /** Binds interactive UI services (the TUI); without them select/askQuestions resolve undefined. */
+    /** Where waits for a person are opened (see `HumanWaits`); bound once the runner exists. */
+    humanWaits;
+    setHumanWaits(waits) {
+        this.humanWaits = waits;
+    }
+    /**
+     * Binds interactive UI services (the TUI, the web server); without them select/askQuestions
+     * resolve undefined. Every question that reaches the person through here (plugins, the
+     * `ask_user_question` tool, the plan review) is a human wait: the bound UI is wrapped ONCE so no
+     * host and no caller can forget to mark it.
+     */
     setInteractiveUI(ui) {
-        this.uiImpl = ui;
+        const wait = (session, ask) => this.humanWaits ? this.humanWaits.track(session, ask) : ask();
+        this.uiImpl = {
+            select: (request) => wait(undefined, () => ui.select(request)),
+            askQuestions: (request) => wait(request.session, () => ui.askQuestions(request)),
+            open: (sessionId) => ui.open(sessionId),
+        };
     }
     /**
      * Read-only view of one plugin's shared state (written through `api.state.set`). The host layer
@@ -141,6 +165,22 @@ export class PluginHost {
     setCompleter(fn) {
         this.completer = fn;
     }
+    /**
+     * Binds Decision Intelligence. Plugins activated afterwards see `api.decisions`; without it the
+     * member is absent, exactly like on a core that predates the feature.
+     */
+    setDecisions(decisions) {
+        this.decisionsImpl = decisions;
+    }
+    decisionsImpl;
+    /**
+     * Binds the directories and options plugins receive (`api.paths`, `api.options`). Plugins
+     * activated before this call, or on a host without it, see neither member.
+     */
+    setPluginEnvironment(environment) {
+        this.environment = environment;
+    }
+    environment;
     /** Binds credential-free model discovery/resolution after provider startup is complete. */
     setModels(models) {
         this.modelsImpl = models;
@@ -203,6 +243,7 @@ export class PluginHost {
                 "mcp",
                 "storage",
                 "ui",
+                "decisions",
             ]))
                 .optional(),
             setup: z.function(),
@@ -361,6 +402,42 @@ export class PluginHost {
                     });
                 },
             },
+            ...(this.environment
+                ? (({ stateRoot, configHome, options }) => {
+                    // The id is validated (`^[a-z0-9][a-z0-9.-]{0,63}$`): it cannot be `.`/`..` or hold a
+                    // separator, so these stay inside their roots. Created 0700 on first read.
+                    const state = join(stateRoot, "plugins", plugin.id);
+                    const directories = {
+                        state,
+                        config: join(configHome, "plugins", plugin.id),
+                        cache: join(state, "cache"),
+                    };
+                    const paths = {};
+                    for (const key of ["state", "config", "cache"])
+                        Object.defineProperty(paths, key, {
+                            enumerable: true,
+                            get: () => {
+                                mkdirSync(directories[key], { recursive: true, mode: 0o700 });
+                                return directories[key];
+                            },
+                        });
+                    return {
+                        paths: Object.freeze(paths),
+                        options: deepFreeze(structuredClone(options(plugin.id, builtin))),
+                    };
+                })(this.environment)
+                : {}),
+            ...(this.decisionsImpl
+                ? {
+                    decisions: (({ registry, service }) => ({
+                        // Registering never activates: `decisions.provider` in the configuration does.
+                        registerProvider: (provider) => track(registry.register(plugin.id, provider)),
+                        available: () => service.available(),
+                        activeProvider: () => service.activeProvider(),
+                        tryDecide: (request, options) => service.tryDecide(request, options),
+                    }))(this.decisionsImpl),
+                }
+                : {}),
             compaction: {
                 register: (hooks) => {
                     const entry = { plugin: plugin.id, hooks };
@@ -675,23 +752,34 @@ export class PluginHost {
             }
         }
     }
+    /**
+     * Disposes every plugin in parallel, each bounded by `disposeTimeoutMs`: a slow or hung
+     * `dispose()` neither delays the others nor holds the close past its limit. Registrations are
+     * undone either way. Failures (including a timeout) are reported together afterwards.
+     */
     async close() {
-        const errors = [];
-        for (const { plugin, undo } of [...this.loaded.values()].reverse()) {
+        const limit = this.options.disposeTimeoutMs ?? 2000;
+        const entries = [...this.loaded.entries()].reverse();
+        this.loaded.clear();
+        this.externalCount = 0;
+        this.builtins.clear();
+        const results = await Promise.allSettled(entries.map(async ([id, { plugin, undo }]) => {
+            let timer;
             try {
-                await plugin.dispose?.();
-            }
-            catch (e) {
-                errors.push(e);
+                await Promise.race([
+                    Promise.resolve().then(() => plugin.dispose?.()),
+                    new Promise((_, reject) => {
+                        timer = setTimeout(() => reject(new Error(`Plugin ${id} dispose timed out after ${limit}ms`)), limit);
+                    }),
+                ]);
             }
             finally {
+                clearTimeout(timer);
                 for (const fn of undo.reverse())
                     fn();
             }
-        }
-        this.loaded.clear();
-        this.externalCount = 0;
-        this.builtins.clear();
+        }));
+        const errors = results.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
         if (errors.length)
             throw new AggregateError(errors, "Plugin disposal failed");
     }
@@ -706,7 +794,7 @@ export async function discoverPlugins(root) {
             return [];
         throw e;
     }
-    return entries
+    const found = await Promise.all(entries
         .filter(
     // A root may hold an `npm install --prefix` layout (`node_modules`, package.json/lock);
     // npm packages there are resolved through the configured `plugins` array instead.
@@ -714,6 +802,13 @@ export async function discoverPlugins(root) {
         e.name !== "package.json" &&
         e.name !== "package-lock.json" &&
         ((e.isFile() && /\.[cm]?[jt]s$/.test(e.name)) || e.isDirectory()))
-        .map((e) => join(root, e.name))
-        .sort();
+        .map(async (e) => {
+        const path = join(root, e.name);
+        // A directory is a plugin only with its manifest: `<config home>/plugins/<id>` is also
+        // where `api.paths.config` puts a plugin's own files, and those are not plugins.
+        if (e.isDirectory() && !(await exists(join(path, "alisio-plugin.json"))))
+            return undefined;
+        return path;
+    }));
+    return found.filter((path) => path !== undefined).sort();
 }

package/package.json

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