@alisio/core 0.1.0-alpha.3

package/dist/core/contracts.d.ts

@@ -0,0 +1,141 @@
+import type { CompactionCheckpoint, Message, ToolCall, ToolResult } from "@alisio/sdk";
+export interface Session {
+    id: string;
+    workspace: string;
+    provider: string;
+    model: string;
+    /** Child sessions only. */
+    parentId?: string;
+    depth?: number;
+    agent?: string;
+    status?: import("@alisio/sdk").SessionStatus;
+    title?: string;
+    usage?: {
+        input: number;
+        output: number;
+    };
+    /** Persisted child spec (narrowing, limits) so resumed runs keep the same restrictions. */
+    options?: Record<string, unknown>;
+    createdAt?: number;
+    updatedAt?: number;
+}
+export interface ChildSessionRecord {
+    id?: string;
+    parentId: string;
+    workspace: string;
+    provider: string;
+    model: string;
+    agent: string;
+    title: string;
+    depth: number;
+    options: Record<string, unknown>;
+}
+export interface SessionStore {
+    create(workspace: string, provider: string, model: string): Session;
+    get(id: string): Session;
+    list(): Session[];
+    messages(id: string): Message[];
+    append(id: string, message: Message): void;
+    createChild(record: ChildSessionRecord): Session;
+    children(parentId: string): Session[];
+    updateSession(id: string, patch: {
+        status?: import("@alisio/sdk").SessionStatus;
+        usage?: {
+            input: number;
+            output: number;
+        };
+    }): void;
+    /** Updates a queued session after its provider/model selector has resolved. */
+    updateBinding(id: string, provider: string, model: string): void;
+    /** Marks queued/running child sessions not locked by a live process as interrupted. */
+    interruptStale(): number;
+    /** Record the model used for subsequent turns of the session. */
+    setModel(id: string, model: string): void;
+    /**
+     * Atomically replace the first `replaced` active messages with `summary`, keeping the
+     * rest verbatim and in order. Callers must never split a tool call from its results.
+     */
+    compact(id: string, replaced: number, summary: Message): void;
+    acquire(id: string): void;
+    release(id: string): void;
+    beginCall(session: string, call: ToolCall): void;
+    endCall(session: string, call: ToolCall, result: ToolResult): void;
+    reconcile(id: string, acknowledge?: boolean): void;
+    event(id: string, runId: string, type: string, data: unknown): void;
+}
+export interface ContextSource {
+    /** System instructions; `sessionId` scopes lazily attached nested instructions. */
+    instructions(sessionId?: string): Promise<string>;
+    /** Instructions newly relevant to paths a tool is about to touch (once per session). */
+    beforePaths(paths: string[], sessionId?: string): Promise<string | undefined>;
+}
+export interface Policy {
+    write: boolean;
+    process: boolean;
+    external: boolean;
+}
+export type ApprovalDecision = "once" | "session" | "deny";
+export interface ApprovalRequest {
+    call: ToolCall;
+    /** Session asking (a child session when delegated). */
+    session?: string;
+    /** Who is asking, e.g. an agent path such as "general › explore". */
+    label?: string;
+    effect: "write" | "process" | "external";
+    input: Record<string, unknown>;
+    signal: AbortSignal;
+}
+/** Optional interactive approval for write/process/external tools not pre-allowed by the Policy. */
+export type ApprovalHandler = (request: ApprovalRequest) => Promise<ApprovalDecision>;
+export interface HookFailure {
+    source: string;
+    hook: string;
+    error: string;
+}
+/**
+ * Generic extension points the runner calls. The plugin host implements them with per-hook
+ * timeouts and failure isolation; the core never knows what an extension does.
+ */
+export interface RunnerExtensions {
+    beforeCompact(input: {
+        sessionId: string;
+        reason: "manual" | "auto";
+        messages: readonly Message[];
+        focus?: string;
+    }): Promise<{
+        instructions: string[];
+        /** Field name → description, with the contributing source. */
+        fields: Record<string, {
+            source: string;
+            description: string;
+        }>;
+        failures: HookFailure[];
+    }>;
+    afterCompact(input: {
+        sessionId: string;
+        reason: "manual" | "auto";
+        messages: readonly Message[];
+        focus?: string;
+        model: string;
+        replaced: number;
+        structured: boolean;
+        checkpoint?: CompactionCheckpoint;
+        checkpointText: string;
+        extracted: Record<string, unknown>;
+    }): Promise<{
+        inject: string[];
+        reports: Record<string, Record<string, unknown>>;
+        failures: HookFailure[];
+    }>;
+    sessionStart(input: {
+        sessionId: string;
+        model: string;
+        workspace: string;
+    }): Promise<{
+        inject: Array<{
+            source: string;
+            text: string;
+        }>;
+        failures: HookFailure[];
+    }>;
+}

package/dist/core/contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/core/registry.d.ts

@@ -0,0 +1,8 @@
+import type { ToolDefinition } from "@alisio/sdk";
+export declare class ToolRegistry {
+    private entries;
+    register(tool: ToolDefinition): () => void;
+    list(): ToolDefinition[];
+    get(name: string): ToolDefinition;
+    parse(name: string, argumentsText: string): Record<string, unknown>;
+}

package/dist/core/registry.js

@@ -0,0 +1,54 @@
+import Ajv from "ajv";
+import Ajv2020 from "ajv/dist/2020.js";
+const ajv2020 = new Ajv2020({ allErrors: true, strict: true });
+const ajv = new Ajv({ allErrors: true, strict: true });
+function rejectReferences(value) {
+    if (!value || typeof value !== "object")
+        return;
+    for (const [k, v] of Object.entries(value)) {
+        if (["$ref", "$id", "$async"].includes(k))
+            throw new Error(`Schema keyword ${k} is not supported`);
+        rejectReferences(v);
+    }
+}
+export class ToolRegistry {
+    entries = new Map();
+    register(tool) {
+        if (!/^[a-zA-Z0-9_-]{1,64}$/.test(tool.name))
+            throw new Error(`Invalid tool name: ${tool.name}`);
+        if (this.entries.has(tool.name))
+            throw new Error(`Duplicate tool: ${tool.name}`);
+        if (tool.inputSchema.type !== "object")
+            throw new Error("Tool input schema must be an object");
+        rejectReferences(tool.inputSchema);
+        const entry = {
+            tool,
+            validate: (tool.inputSchema.$schema === "https://json-schema.org/draft/2020-12/schema"
+                ? ajv2020
+                : ajv).compile(tool.inputSchema),
+        };
+        this.entries.set(tool.name, entry);
+        return () => {
+            if (this.entries.get(tool.name) === entry)
+                this.entries.delete(tool.name);
+        };
+    }
+    list() {
+        return [...this.entries.values()].map((x) => x.tool);
+    }
+    get(name) {
+        const e = this.entries.get(name);
+        if (!e)
+            throw new Error(`Unknown tool: ${name}`);
+        return e.tool;
+    }
+    parse(name, argumentsText) {
+        const e = this.entries.get(name);
+        if (!e)
+            throw new Error(`Unknown tool: ${name}`);
+        const value = JSON.parse(argumentsText);
+        if (!e.validate(value))
+            throw new Error(ajv.errorsText(e.validate.errors));
+        return value;
+    }
+}

package/dist/core/runner.d.ts

@@ -0,0 +1,121 @@
+import { type Attachment, type Message, type ModelProvider, type RunEvent, type ToolDefinition } from "@alisio/sdk";
+import type { ApprovalHandler, ContextSource, Policy, RunnerExtensions, SessionStore } from "./contracts.ts";
+import type { ToolRegistry } from "./registry.ts";
+export interface CompactionSettings {
+    /** Compact automatically when context usage crosses `threshold` of a known window. */
+    auto?: boolean;
+    threshold?: number;
+    keepTurns?: number;
+}
+export interface RunnerOptions {
+    /** Provider bound to this persisted session. */
+    provider: ModelProvider;
+    providerFor?: (session: import("./contracts.ts").Session) => Promise<ModelProvider>;
+    registry: ToolRegistry;
+    store: SessionStore;
+    context: ContextSource;
+    policy: Policy;
+    workspace: string;
+    maxTurns?: number;
+    timeoutMs?: number;
+    maxContextChars?: number;
+    maxOutputTokens?: number;
+    maxTokens?: number;
+    onEvent?: (event: RunEvent) => void;
+    readConcurrency?: number;
+    /** Context window in tokens for a model, when known. Unknown disables auto compaction. */
+    contextWindow?: (model: string) => number | undefined;
+    compaction?: CompactionSettings;
+    /** When set, write/process tools not allowed by the policy are offered and ask first. */
+    approve?: ApprovalHandler;
+    /** Generic hooks (implemented by the plugin host) for compaction and session start. */
+    extensions?: RunnerExtensions;
+    /**
+     * Provider-native tool definitions (for example a hosted `web_search` tool) appended to every
+     * request's `tools` alongside the registry's function tools. Opt-in, set once for the whole
+     * runner; only meaningful for a provider that documents an equivalent server-side tool.
+     */
+    nativeTools?: Array<Record<string, unknown>>;
+}
+/**
+ * Per-run overrides used by embedders and child sessions. Callers must only NARROW: `policy`
+ * and `toolFilter` are applied on top of the runner's policy and tools.
+ */
+export interface RunOptions {
+    /** What UIs show instead of the prompt (e.g. `/init`). */
+    display?: string;
+    /** Images attached to this turn's user message, sent as vision content parts. */
+    attachments?: Attachment[];
+    /** Extra system instructions for this run (e.g. an agent persona). */
+    instructions?: string;
+    toolFilter?: (tool: ToolDefinition) => boolean;
+    policy?: Policy;
+    /** Allow interactive approvals for this run (default: when the runner has a handler). */
+    approvals?: boolean;
+    /** Shown with approval requests, e.g. the agent path of a child session. */
+    label?: string;
+    workspace?: string;
+    context?: ContextSource;
+    maxTurns?: number;
+    maxTokens?: number;
+    timeoutMs?: number;
+}
+/**
+ * Default cumulative token budget for one run: several context windows (each turn re-sends the
+ * context), clamped; 1M tokens when the window is unknown.
+ */
+export declare function defaultTokenBudget(contextWindow?: number): number;
+export interface CompactionResult {
+    replaced: number;
+    before: number;
+    after: number;
+    summary: Extract<Message, {
+        role: "user";
+    }>;
+}
+export declare class AgentRunner {
+    private options;
+    /** Sessions with an active run or compaction (one at a time per session). */
+    private active;
+    /** Messages queued for a session's next turn (e.g. input for a running child). */
+    private inbox;
+    /** Last provider-reported context size per session and the history length it covered. */
+    private reported;
+    constructor(options: RunnerOptions);
+    /** Current capability policy (may widen when the user approves an effect for the session). */
+    get policy(): Readonly<Policy>;
+    /** Whether write/process tools can be approved interactively. */
+    get approvals(): boolean;
+    private emitter;
+    /** Tools offered to the model under the current policy (and optional run narrowing). */
+    availableTools(run?: RunOptions): ToolDefinition[];
+    /** Abort signal of the session's active run, if any (used to cascade cancellation). */
+    signal(sessionId: string): AbortSignal | undefined;
+    isRunning(sessionId: string): boolean;
+    /** Aborts the active run (or compaction) of a session. */
+    abort(sessionId: string, reason?: unknown): boolean;
+    /** Queues text as a user message for the session's next turn (or next run when idle). */
+    enqueue(sessionId: string, text: string): void;
+    private drain;
+    private claim;
+    private toolsText;
+    /** Estimated tokens the next request of a session would send. */
+    estimateContext(sessionId: string): Promise<number>;
+    /** Change the model used by subsequent turns of a session; recorded in the store. */
+    setModel(sessionId: string, model: string): void;
+    /** Manually compact a session outside a run. */
+    compact(sessionId: string, request?: {
+        focus?: string;
+        signal?: AbortSignal;
+    }): Promise<CompactionResult | undefined>;
+    private compactLocked;
+    run(sessionId: string, prompt: string, signal?: AbortSignal, options?: RunOptions): Promise<{
+        sessionId: string;
+        text: string;
+        status: string;
+        usage: {
+            input: number;
+            output: number;
+        };
+    }>;
+}