@alisio/core 0.1.0-alpha.3

package/dist/plugins/host.d.ts

@@ -0,0 +1,164 @@
+import type { AskQuestionsRequest, AskQuestionsResult, CommandContext, CommandOptions, CompletionRequest, Message, PanelProvider, Plugin, PluginAPI, PluginMetadata, RunEvent, SelectRequest } from "@alisio/sdk";
+import type { HookFailure, RunnerExtensions } from "../core/contracts.ts";
+import type { ToolRegistry } from "../core/registry.ts";
+import { ExtensionRegistry } from "../extensions/registry.ts";
+import type { ProviderRegistry } from "../providers/registry.ts";
+export declare const pluginPrefix: (id: string) => string;
+export interface PluginHostOptions {
+    /** Timeout for compaction and session-start hooks. */
+    hookTimeoutMs?: number;
+    /** Timeout for session-end hooks (for example an automatic summary). */
+    sessionEndTimeoutMs?: number;
+}
+export declare class PluginHost implements RunnerExtensions {
+    private registry;
+    private state;
+    private options;
+    private providers?;
+    commands: Map<string, (args: string, context?: CommandContext) => Promise<string>>;
+    commandInfo: Map<string, CommandOptions & {
+        plugin: string;
+        builtin: boolean;
+    }>;
+    /** Ids of active built-in plugins. */
+    builtins: Set<string>;
+    /** Status entries contributed through `ui.status`, keyed `plugin:key`. */
+    status: Map<string, {
+        plugin: string;
+        text: string;
+        detail?: string;
+    }>;
+    onStatusChange?: () => void;
+    /** Providers for typed extension points (mascot, startup-screen, ...). */
+    readonly extensions: ExtensionRegistry;
+    /** Loaded plugins that did not come from the built-in registry. */
+    externalCount: number;
+    private compactionHooks;
+    private startHandlers;
+    private endHandlers;
+    private fieldOwners;
+    private completer?;
+    private modelsImpl?;
+    observers: Set<(event: Readonly<RunEvent>) => void>;
+    contexts: Array<() => Promise<string>>;
+    /** Skill directories registered by plugins, retaining trusted registration ownership. */
+    skillSources: Array<{
+        plugin: string;
+        name: string;
+        dir: string;
+    }>;
+    /** Prompt template directories registered by plugins, with their plugin id. */
+    promptSources: Array<{
+        plugin: string;
+        dir: string;
+    }>;
+    /** Agent definition directories registered by plugins, with their plugin id. */
+    agentSources: Array<{
+        plugin: string;
+        dir: string;
+    }>;
+    /** Tree panels contributed by plugins, keyed `plugin:id`. */
+    panels: Map<string, {
+        plugin: string;
+        provider: PanelProvider;
+    }>;
+    private sessionsImpl?;
+    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. */
+    setInteractiveUI(ui: {
+        select(request: SelectRequest): Promise<string | undefined>;
+        askQuestions(request: AskQuestionsRequest): Promise<AskQuestionsResult>;
+        open(sessionId: string): boolean;
+    }): void;
+    get sessions(): PluginAPI["sessions"];
+    /**
+     * Live accessor for core standard tools (e.g. `ask_user_question`), which are not "a plugin"
+     * with an id and so cannot use the per-plugin `ui` wrapper built in `activate()`. Bound lazily
+     * (reads `this.uiImpl` at call time) since `registerStandard` runs before the TUI calls
+     * `setInteractiveUI`. `interactive()` reflects whether ANY interactive UI is bound at all,
+     * never which session is asking, so child sessions under an interactive root TUI pass too.
+     */
+    get ui(): {
+        interactive(): boolean;
+        askQuestions(request: AskQuestionsRequest): Promise<AskQuestionsResult>;
+    };
+    get promptRoots(): string[];
+    get skillRoots(): string[];
+    private loaded;
+    constructor(registry: ToolRegistry, state: {
+        getState(plugin: string, key: string): unknown;
+        setState(plugin: string, key: string, value: unknown): void;
+    }, options?: PluginHostOptions, providers?: ProviderRegistry | undefined);
+    /** Binds the provider-agnostic completion service once a provider exists. */
+    setCompleter(fn: (request: CompletionRequest & {
+        signal: AbortSignal;
+    }) => Promise<string>): void;
+    /** Binds credential-free model discovery/resolution after provider startup is complete. */
+    setModels(models: PluginAPI["models"]): void;
+    /**
+     * Loads an explicitly trusted plugin: a file/directory path, or an npm package name resolved
+     * from `from` (project) upwards and then global roots. Never called for untrusted input.
+     */
+    load(spec: string, options?: {
+        from?: string;
+        globalRoots?: string[];
+    }): Promise<void>;
+    /** Imports and validates a trusted plugin without running setup, for cataloging disabled entries. */
+    inspect(spec: string, options?: {
+        from?: string;
+        globalRoots?: string[];
+    }): Promise<{
+        plugin: Plugin;
+        base: string;
+    }>;
+    private validate;
+    /**
+     * `builtin` is reserved for first-party plugins from the built-in registry: their tools and
+     * commands keep unprefixed names and may declare the `internal` effect.
+     */
+    activate(plugin: Plugin, base: string, options?: {
+        builtin?: boolean;
+    }): Promise<void>;
+    /** Runs one hook with a host-enforced timeout; the hook receives an abort signal. */
+    private guarded;
+    beforeCompact(input: Parameters<RunnerExtensions["beforeCompact"]>[0]): Promise<{
+        instructions: string[];
+        fields: Record<string, {
+            source: string;
+            description: string;
+        }>;
+        failures: HookFailure[];
+    }>;
+    afterCompact(input: Parameters<RunnerExtensions["afterCompact"]>[0]): Promise<{
+        inject: string[];
+        reports: Record<string, Record<string, unknown>>;
+        failures: HookFailure[];
+    }>;
+    sessionStart(input: Parameters<RunnerExtensions["sessionStart"]>[0]): Promise<{
+        inject: {
+            source: string;
+            text: string;
+        }[];
+        failures: HookFailure[];
+    }>;
+    /** Session end hooks run concurrently and are bounded by one host timeout. */
+    sessionEnd(input: {
+        sessionId: string;
+        model: string;
+        workspace: string;
+        reason: "clear" | "exit";
+        messages: readonly Message[];
+    }): Promise<{
+        failures: HookFailure[];
+    }>;
+    /** Loaded plugins (id, version, built-in flag), ordered by id. */
+    metadata(): PluginMetadata[];
+    get hasSessionEndHooks(): boolean;
+    /** Conservative ownership check used to protect a live session from plugin removal. */
+    ownsSessionResources(plugin: string): boolean;
+    emit(event: RunEvent): void;
+    close(): Promise<void>;
+}
+export declare function discoverPlugins(root: string): Promise<string[]>;