@alisio/core 0.1.0-alpha.17 → 0.1.0-alpha.19

package/dist/commands/catalog.js

@@ -0,0 +1,292 @@
+import { agentCatalogFromState, resolveActiveAgent } from "../agents/active.js";
+import { formatSideQuestion, SIDE_QUESTION_DESCRIPTION, SIDE_QUESTION_USAGE, } from "../sessions/side-questions.js";
+import { BUILTIN_COMMANDS } from "./builtins.js";
+export { BUILTIN_COMMANDS };
+const builtinDescriptor = (c) => ({
+    name: c.name,
+    description: c.description,
+    ...(c.aliases ? { aliases: [...c.aliases] } : {}),
+    ...(c.argumentHint ? { argumentHint: c.argumentHint } : {}),
+    source: "builtin",
+    surfaces: [...c.surfaces],
+    execution: c.execution,
+});
+const ALL = ["tui", "web", "api"];
+/** Root sessions of this workspace bound to the current provider, newest first (as the TUI). */
+const workspaceSessions = (host) => host.store
+    .list()
+    .filter((s) => s.workspace === host.workspace && s.provider === host.provider.id);
+const firstPrompt = (host, id) => {
+    const first = host.store.messages(id).find((m) => m.role === "user" && !m.summary);
+    return first?.role === "user" ? first.text.replace(/\s+/g, " ").slice(0, 60) : "";
+};
+const HANDLERS = {
+    async tools(_args, _ctx, host) {
+        const policy = host.runner.policy;
+        const rows = host.registry
+            .list()
+            .map((t) => {
+            const effect = t.effect ?? "external";
+            const state = effect === "read" || effect === "internal" || policy[effect]
+                ? "enabled"
+                : host.runner.approvals && (effect === "write" || effect === "process")
+                    ? "ask"
+                    : "disabled";
+            return `| \`${t.name}\` | ${effect} | ${state} |`;
+        })
+            .join("\n");
+        return {
+            text: `**Tools**\n\n| Tool | Effect | State |\n| --- | --- | --- |\n${rows}\n\n\`ask\` prompts before running (allow once / session / deny). Use --allow-write / --allow-process to pre-allow; --read-only disables them. Paths outside the workspace ask per directory; pre-allow with --add-dir or the \`additionalDirectories\` config key. \`internal\` tools (built-in plugins) only write Alisio's own state.`,
+        };
+    },
+    async sessions(_args, ctx, host) {
+        const list = workspaceSessions(host).slice(0, 20);
+        if (!list.length)
+            return { text: "No sessions in this workspace", tone: "notice" };
+        return {
+            text: [
+                "**Recent sessions** (use `/resume <id-prefix>`)",
+                "",
+                ...list.map((s) => `- \`${s.id}\` ${s.id === ctx.sessionId ? "**(current)** " : ""}${s.model} · ${host.store.messages(s.id).length} msgs · ${firstPrompt(host, s.id) || "_empty_"}`),
+            ].join("\n"),
+            data: list,
+        };
+    },
+    async resume(args, _ctx, host) {
+        const target = args.trim();
+        if (!target)
+            throw new Error("Usage: /resume <id>");
+        const matches = workspaceSessions(host).filter((s) => s.id.startsWith(target));
+        if (matches.length !== 1)
+            throw new Error(matches.length
+                ? `Ambiguous session prefix: ${target}`
+                : `No session in this workspace matches ${target}`);
+        const found = matches[0];
+        return { text: `Resumed session ${found.id}`, tone: "notice", sessionId: found.id };
+    },
+    async clear(_args, ctx, host) {
+        const model = host.store.get(ctx.sessionId).model;
+        const created = host.store.create(host.workspace, host.provider.id, model);
+        return { text: `New session ${created.id}`, tone: "notice", sessionId: created.id };
+    },
+    async compact(args, ctx, host) {
+        const result = await host.runner.compact(ctx.sessionId, {
+            ...(args.trim() ? { focus: args.trim() } : {}),
+            ...(ctx.signal ? { signal: ctx.signal } : {}),
+        });
+        return result
+            ? {
+                text: `Compacted ${result.replaced} messages: ~${result.before} → ~${result.after} tokens`,
+                tone: "notice",
+                data: result,
+            }
+            : { text: "Not enough history to compact", tone: "notice" };
+    },
+    async model(args, ctx, host) {
+        const model = args.trim();
+        if (!model)
+            throw new Error("Usage: /model <model id>");
+        host.runner.setModel(ctx.sessionId, model);
+        return { text: `Model set to \`${model}\``, tone: "notice", data: { model } };
+    },
+    async effort(args, _ctx, host) {
+        const level = args.trim();
+        if (!level)
+            return {
+                text: `Reasoning effort: ${host.config?.agents.effort ?? "model default"}`,
+                tone: "notice",
+            };
+        if (!host.updateSetting)
+            throw new Error("Effort changes are unavailable here");
+        const value = level === "!clear" ? undefined : level;
+        await host.updateSetting("agents.effort", value);
+        return {
+            text: value ? `Reasoning effort set to ${value}` : "Reasoning effort cleared",
+            tone: "notice",
+            data: { effort: value },
+        };
+    },
+    async stats(_args, ctx, host) {
+        const session = host.store.get(ctx.sessionId);
+        const runs = host.store.runs?.(ctx.sessionId) ?? [];
+        const tokens = runs.reduce((sum, r) => ({
+            input: sum.input + (r.usage?.input ?? 0),
+            output: sum.output + (r.usage?.output ?? 0),
+        }), { input: 0, output: 0 });
+        return {
+            text: [
+                "**Session statistics**",
+                "",
+                `- Session: \`${session.id}\``,
+                `- Model: \`${session.model}\``,
+                `- Messages: ${host.store.messages(session.id).length}`,
+                `- Runs: ${runs.length}`,
+                `- Tokens: in ${tokens.input} · out ${tokens.output}`,
+            ].join("\n"),
+            data: { session, runs: runs.length, tokens },
+        };
+    },
+    async skills(_args, _ctx, host) {
+        const skills = host.skillCatalog?.() ?? [];
+        if (!skills.length)
+            return { text: "No skills found", tone: "notice" };
+        const state = (s) => s.effective ? "enabled" : s.shadowedBy ? `shadowed by ${s.shadowedBy}` : "disabled";
+        return {
+            text: `**Skills**\n\n| Skill | Scope | State |\n| --- | --- | --- |\n${skills
+                .map((s) => `| \`${s.displayId}\` | ${s.scope} | ${state(s)} |`)
+                .join("\n")}`,
+            data: skills,
+        };
+    },
+    async plugins(_args, _ctx, host) {
+        const plugins = host.pluginCatalog?.() ?? [];
+        if (!plugins.length)
+            return { text: "No plugins loaded", tone: "notice" };
+        return {
+            text: `**Plugins**\n\n| Plugin | Status | Enabled |\n| --- | --- | --- |\n${plugins
+                .map((p) => `| \`${p.id}\` | ${p.status} | ${p.enabled ? "yes" : "no"} |`)
+                .join("\n")}`,
+            data: plugins,
+        };
+    },
+    async mcp(_args, _ctx, host) {
+        const servers = host.mcp?.list() ?? [];
+        if (!servers.length)
+            return { text: "No MCP servers configured", tone: "notice" };
+        return {
+            text: `**MCP servers**\n\n| Server | Status | Tools |\n| --- | --- | --- |\n${servers
+                .map((s) => `| \`${s.name}\` | ${s.status} | ${s.counts.tools} |`)
+                .join("\n")}`,
+            data: servers,
+        };
+    },
+    async btw(args, ctx, host) {
+        const question = args.trim();
+        const side = host.sideQuestions;
+        if (!question) {
+            const history = side?.history(ctx.sessionId) ?? [];
+            const latest = history.at(-1);
+            if (!latest)
+                return {
+                    text: `${SIDE_QUESTION_USAGE}\n${SIDE_QUESTION_DESCRIPTION}`,
+                    tone: "notice",
+                    data: { history },
+                };
+            return {
+                text: formatSideQuestion(latest, history.length, history.length),
+                data: { history, entry: latest },
+            };
+        }
+        if (!side)
+            throw new Error("Side questions are unavailable here");
+        const entry = await side.ask(ctx.sessionId, question, ctx.signal ? { signal: ctx.signal } : {});
+        const total = side.history(ctx.sessionId).length;
+        return { text: formatSideQuestion(entry, total, total), data: { entry } };
+    },
+    async agents(args, ctx, host) {
+        // With arguments, `/agents <verb>` belongs to the subagents plugin's own command (as in the
+        // TUI); without them it lists the active-agent catalog.
+        const plugin = args.trim() ? host.plugins?.commands.get("agents") : undefined;
+        if (plugin)
+            return { text: await plugin(args.trim(), { sessionId: ctx.sessionId }) };
+        let state;
+        try {
+            state = host.plugins?.pluginState?.("subagents", "mainAgents");
+        }
+        catch {
+            /* agent contributions are best-effort */
+        }
+        const agents = agentCatalogFromState(state);
+        const active = resolveActiveAgent(agents, host.config?.agents.active);
+        return {
+            text: [
+                "**Agents**",
+                "",
+                ...agents.map((a) => `- **${a.name}**${a.id === active.id ? " (current)" : ""}${a.readOnly ? " · read-only" : ""} — ${a.description}`),
+            ].join("\n"),
+            data: { agents, active: active.id },
+        };
+    },
+};
+export class CommandCatalog {
+    host;
+    constructor(host) {
+        this.host = host;
+    }
+    builtins() {
+        return BUILTIN_COMMANDS.map(builtinDescriptor);
+    }
+    /** Every descriptor (optionally for one surface). Precedence: builtin > plugin > prompt > skill. */
+    list(surface) {
+        const out = this.builtins();
+        const taken = new Set(out.flatMap((c) => [c.name, ...(c.aliases ?? [])]));
+        const push = (descriptor) => {
+            if (taken.has(descriptor.name))
+                return;
+            taken.add(descriptor.name);
+            out.push(descriptor);
+        };
+        const host = this.host;
+        if (host?.plugins)
+            for (const [name, info] of host.plugins.commandInfo)
+                push({
+                    name,
+                    description: info.description ?? `plugin ${info.plugin}`,
+                    ...(info.argumentHint ? { argumentHint: info.argumentHint } : {}),
+                    source: "plugin",
+                    owner: info.plugin,
+                    surfaces: [...ALL],
+                    execution: "core",
+                });
+        if (host?.prompts)
+            for (const template of host.prompts.templates.values())
+                push({
+                    name: template.name,
+                    description: template.description,
+                    ...(template.argumentHint ? { argumentHint: template.argumentHint } : {}),
+                    source: "prompt",
+                    owner: template.source,
+                    surfaces: [...ALL],
+                    execution: "surface",
+                });
+        for (const skill of host?.skillCatalog?.() ?? [])
+            if (skill.effective && skill.enabled)
+                push({
+                    name: `skill:${skill.id}`,
+                    description: skill.description,
+                    source: "skill",
+                    ...(skill.owner ? { owner: skill.owner.id } : {}),
+                    surfaces: [...ALL],
+                    execution: "surface",
+                });
+        return surface ? out.filter((c) => c.surfaces.includes(surface)) : out;
+    }
+    /** A command by name or alias (built-in names and aliases are case-insensitive). */
+    resolve(name) {
+        const lower = name.toLowerCase();
+        const all = this.list();
+        return (all.find((c) => c.source === "builtin" && (c.name === lower || c.aliases?.includes(lower))) ??
+            all.find((c) => c.source !== "builtin" && c.name === name));
+    }
+    /** Runs an `execution: "core"` command. Surface commands and unknown names throw. */
+    async execute(name, args, ctx) {
+        const descriptor = this.resolve(name);
+        if (!descriptor)
+            throw new Error(`Unknown command /${name}. Type /help.`);
+        if (descriptor.execution !== "core")
+            throw new Error(`/${descriptor.name} is handled by each surface, not by the core catalog`);
+        const host = this.host;
+        if (!host)
+            throw new Error(`/${descriptor.name} needs an application host`);
+        if (descriptor.source === "plugin") {
+            const handler = host.plugins?.commands.get(descriptor.name);
+            if (!handler)
+                throw new Error(`Unknown plugin command: ${descriptor.name}`);
+            return { text: await handler(args, { sessionId: ctx.sessionId }) };
+        }
+        const handler = HANDLERS[descriptor.name];
+        if (!handler)
+            throw new Error(`/${descriptor.name} has no core handler`);
+        return handler(args, ctx, host);
+    }
+}

package/dist/config.d.ts

@@ -476,6 +476,13 @@ declare const SETTABLE_KEYS: {
 };
 export type SettableSettingKey = keyof typeof SETTABLE_KEYS;
 export declare function isSettableSettingKey(key: string): key is SettableSettingKey;
+export interface SettableSettingInfo {
+    key: SettableSettingKey;
+    kind: "boolean" | "number" | "string" | "enum";
+    options?: string[];
+}
+/** Every settable key with its value kind (and enum options), for settings editors. */
+export declare function settableSettings(): SettableSettingInfo[];
 /**
  * Atomically sets one user-facing setting in the global config file (`<config home>/config.json`)
  * while preserving every unrelated JSON field. The value is validated against the same zod leaf

package/dist/config.js

@@ -551,6 +551,33 @@ const SETTABLE_KEYS = {
 export function isSettableSettingKey(key) {
     return Object.prototype.hasOwnProperty.call(SETTABLE_KEYS, key);
 }
+/** Unwraps optional/default/nullable wrappers down to the value schema. */
+function settingLeaf(schema) {
+    let current = schema;
+    for (let depth = 0; depth < 8; depth++) {
+        const type = current.def?.type;
+        if ((type === "optional" || type === "default" || type === "nullable") &&
+            current.def?.innerType)
+            current = current.def.innerType;
+        else
+            break;
+    }
+    return current;
+}
+/** Every settable key with its value kind (and enum options), for settings editors. */
+export function settableSettings() {
+    return Object.keys(SETTABLE_KEYS).map((key) => {
+        const leaf = settingLeaf(SETTABLE_KEYS[key]);
+        const type = leaf.def?.type;
+        if (type === "enum")
+            return { key, kind: "enum", options: (leaf.options ?? []).map((o) => String(o)) };
+        if (type === "boolean")
+            return { key, kind: "boolean" };
+        if (type === "number" || type === "int")
+            return { key, kind: "number" };
+        return { key, kind: "string" };
+    });
+}
 /**
  * Atomically sets one user-facing setting in the global config file (`<config home>/config.json`)
  * while preserving every unrelated JSON field. The value is validated against the same zod leaf

package/dist/core/contracts.d.ts

@@ -18,6 +18,10 @@ export interface Session {
     options?: Record<string, unknown>;
     createdAt?: number;
     updatedAt?: number;
+    /** Root sessions pinned in web clients (v4). */
+    pinned?: boolean;
+    /** When a root session was archived in web clients (v4); absent when not archived. */
+    archivedAt?: number;
 }
 export interface ChildSessionRecord {
     id?: string;
@@ -30,6 +34,82 @@ export interface ChildSessionRecord {
     depth: number;
     options: Record<string, unknown>;
 }
+/** `queued` and `running` are the only non-terminal run states. */
+export type RunStatus = "queued" | "running" | "completed" | "turns_exceeded" | "failed" | "cancelled" | "interrupted";
+export type TerminalRunStatus = Exclude<RunStatus, "queued" | "running">;
+/** One `AgentRunner.run` execution (v4 `runs` table). `id` equals `RunEvent.runId`. */
+export interface RunRecord {
+    id: string;
+    session: string;
+    status: RunStatus;
+    /** Client idempotency key; absent for TUI/headless runs. */
+    requestId?: string;
+    correlationId?: string;
+    /** Process that executes (or executed) the run, for startup reconciliation. */
+    ownerPid?: number;
+    model?: string;
+    createdAt: number;
+    startedAt?: number;
+    endedAt?: number;
+    error?: string;
+    usage?: {
+        input: number;
+        output: number;
+        cachedInput?: number;
+    };
+}
+export interface BeginRunInput {
+    id: string;
+    session: string;
+    /** `queued` for scheduled runs, `running` (default) when execution starts now. */
+    status?: "queued" | "running";
+    requestId?: string;
+    correlationId?: string;
+    model?: string;
+}
+export interface EndRunInput {
+    status: TerminalRunStatus;
+    error?: string;
+    usage?: {
+        input: number;
+        output: number;
+        cachedInput?: number;
+    };
+}
+export interface PageOptions {
+    /** Only rows with a sequence greater than this (ascending from there). */
+    after?: number;
+    /** Only rows with a sequence lower than this (the newest `limit` of them). */
+    before?: number;
+    limit?: number;
+}
+export interface MessagePage {
+    items: Array<{
+        seq: number;
+        message: Message;
+        compacted: boolean;
+    }>;
+    /** More rows exist beyond the page in the paging direction. */
+    hasMore: boolean;
+}
+export interface StoredEvent {
+    /** Global `events.seq` as a string (same value as `RunEvent.eventId`). */
+    eventId: string;
+    runId: string;
+    type: string;
+    data: unknown;
+    createdAt?: number;
+    correlationId?: string;
+}
+export interface EventPage {
+    items: StoredEvent[];
+    hasMore: boolean;
+}
+/** Optional tool-call metadata (v4 columns); stores may ignore it. */
+export interface ToolCallMeta {
+    runId?: string;
+    effect?: string;
+}
 export interface SessionStore {
     create(workspace: string, provider: string, model: string): Session;
     get(id: string): Session;
@@ -64,12 +144,39 @@ export interface SessionStore {
     overwrite(id: string, messages: Message[]): void;
     acquire(id: string): void;
     release(id: string): void;
-    beginCall(session: string, call: ToolCall): void;
+    beginCall(session: string, call: ToolCall, meta?: ToolCallMeta): void;
     endCall(session: string, call: ToolCall, result: ToolResult): void;
     /** The persisted result of a completed tool call, for replay of rich (ui/image) parts. */
     callResult(session: string, callId: string): ToolResult | undefined;
     reconcile(id: string, acknowledge?: boolean): void;
-    event(id: string, runId: string, type: string, data: unknown): void;
+    /**
+     * Persist a durable run event. Stores that assign a global, monotonic sequence return it; the
+     * runner exposes it as `RunEvent.eventId`. Returning nothing is allowed (no `eventId`).
+     */
+    event(id: string, runId: string, type: string, data: unknown, meta?: {
+        correlationId?: string;
+    }): number | void;
+    /**
+     * Records a run, or moves an existing `queued` run with the same id to `running`. A run whose
+     * `(session, requestId)` already exists is returned as is (`created: false`): idempotency.
+     */
+    beginRun?(input: BeginRunInput): {
+        run: RunRecord;
+        created: boolean;
+    };
+    /** Moves a non-terminal run to a terminal state; terminal runs are never overwritten. */
+    endRun?(id: string, input: EndRunInput): void;
+    runByRequest?(session: string, requestId: string): RunRecord | undefined;
+    /** Runs of a session, newest first. */
+    runs?(session: string, options?: {
+        limit?: number;
+    }): RunRecord[];
+    messagesPage?(session: string, options?: PageOptions & {
+        compacted?: boolean;
+    }): MessagePage;
+    eventsPage?(session: string, options?: PageOptions): EventPage;
+    /** Marks queued/running runs whose owner process is not alive as interrupted. */
+    interruptRuns?(): number;
 }
 export interface ContextSource {
     /** System instructions; `sessionId` scopes lazily attached nested instructions. */

package/dist/core/runner.d.ts

@@ -93,6 +93,10 @@ export interface RunOptions {
     timeoutMs?: number;
     /** Reasoning effort level for this run; beats the runner-level default when set. */
     reasoningEffort?: string;
+    /** Run id to use for this run's events (e.g. preassigned by an embedder); a UUID otherwise. */
+    runId?: string;
+    /** Copied to every event of this run as `RunEvent.correlationId` (e.g. an HTTP request id). */
+    correlationId?: string;
 }
 /**
  * Default cumulative token budget for one run: several context windows (each turn re-sends the
@@ -153,6 +157,23 @@ export declare class AgentRunner {
         basis: "window" | "unknown";
         compactionAt: number;
     };
+    /**
+     * What a tool-less side call about a session needs (for example a `/btw` side question): the
+     * session's provider and model, its system instructions, its ACTIVE history and the current
+     * limits. Claims no lock and writes nothing, so it is safe while a run is active.
+     */
+    sideContext(sessionId: string): Promise<{
+        provider: ModelProvider;
+        model: string;
+        instructions: string;
+        messages: Message[];
+        maxContextChars: number;
+        maxOutputTokens: number;
+        timeoutMs: number;
+        /** Context window of the model in tokens, when known and trusted. */
+        contextWindow?: number;
+        reasoningEffort?: string;
+    }>;
     /** 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. */