@alisio/core 0.1.0-alpha.9 → 0.1.1

package/dist/plan/exit-plan.js

@@ -0,0 +1,130 @@
+import { textResult } from "@alisio/sdk";
+import { EXIT_PLAN_TOOL } from "../core/opt-in.js";
+import { objectSchema } from "../tools/standard.js";
+import { decidePlan, nextPlanRevision, PLAN_CONTEXT_MAX_CHARS, PLAN_MAX_CHARS, PLAN_OPTIONS, PLAN_QUESTION_ID, PLAN_REVIEW_TITLE, PLAN_TEXT_KEY, planHash, planTitle, proposePlan, withdrawPendingPlan, } from "./state.js";
+const withArtifact = (result, artifact) => artifact
+    ? {
+        ...result,
+        content: [...result.content, { type: "ui", block: { kind: "artifact", artifact } }],
+    }
+    : result;
+const answer = (decision, message, extra = {}) => JSON.stringify({ decision, ...extra, message });
+export function registerExitPlan(registry, deps) {
+    registry.register({
+        name: EXIT_PLAN_TOOL,
+        effect: "read",
+        description: "Finish planning: hand the complete plan, in Markdown, to the user for review. Call it once, " +
+            "when the plan is complete, instead of pasting the plan in your reply. The user can approve " +
+            "(the build agent then implements exactly this plan), skip for now, or add context (the " +
+            "result is `feedback`: revise the plan and call exit_plan again). Only the plan agent has " +
+            "this tool. If review is unavailable (headless or read-only sessions) the result says so: " +
+            "then give the complete plan as your final reply.",
+        inputSchema: objectSchema({
+            title: { type: "string", maxLength: 120, description: "Short plan title" },
+            plan: {
+                type: "string",
+                minLength: 1,
+                maxLength: PLAN_MAX_CHARS,
+                description: "The whole plan in Markdown",
+            },
+        }, ["plan"]),
+        async execute(input, context) {
+            const plan = String(input.plan ?? "").trim();
+            if (!plan)
+                throw new Error("exit_plan needs the whole plan in the `plan` field");
+            const sessionId = context.session;
+            const title = planTitle(plan, input.title);
+            const hash = planHash(plan);
+            const planId = crypto.randomUUID();
+            const reviewable = !!sessionId && deps.ui.interactive() && !deps.readOnly;
+            const revision = sessionId ? nextPlanRevision(deps.store, sessionId) : 1;
+            // The plan is saved first, so the review (and every later turn) can point at it.
+            let artifact;
+            let publishNote = "";
+            if (context.artifacts)
+                try {
+                    artifact = await context.artifacts.publishText({
+                        fileName: "plan.md",
+                        title: revision > 1 ? `${title} (revision ${revision})` : title,
+                        text: `${plan}\n`,
+                    });
+                }
+                catch (error) {
+                    publishNote = ` The plan could not be saved as an artifact: ${error instanceof Error ? error.message : String(error)}.`;
+                }
+            const record = {
+                planId,
+                revision,
+                hash,
+                title,
+                ...(context.callId ? { callId: context.callId } : {}),
+                ...(artifact ? { artifactId: artifact.id } : {}),
+            };
+            if (!reviewable) {
+                // Nobody to ask: keep the revision count honest and tell the model what to do instead.
+                if (sessionId)
+                    proposePlan(deps.store, sessionId, { ...record, status: "skipped" });
+                return withArtifact(textResult(answer("unavailable", `No plan review is possible in this session (${deps.readOnly ? "it is read-only" : "it is not interactive"}), so nothing will be implemented from here. Give the complete plan in Markdown as your final reply and stop.${publishNote}`, artifact ? { artifactId: artifact.id } : {})), artifact);
+            }
+            proposePlan(deps.store, sessionId, record);
+            context.emitEvent?.("plan_proposed", {
+                callId: context.callId ?? "",
+                planId,
+                revision,
+                hash,
+                title,
+                ...(artifact ? { artifactId: artifact.id } : {}),
+            });
+            const review = {
+                planId,
+                revision,
+                hash,
+                title,
+                markdown: plan,
+                ...(artifact ? { artifact } : {}),
+            };
+            const result = await deps.ui.askQuestions({
+                questions: [
+                    {
+                        id: PLAN_QUESTION_ID,
+                        header: "Plan review",
+                        question: PLAN_REVIEW_TITLE,
+                        options: PLAN_OPTIONS,
+                    },
+                ],
+                plan: review,
+                session: sessionId,
+                ...(context.label ? { label: context.label } : {}),
+                signal: context.signal,
+            });
+            const choice = result[PLAN_QUESTION_ID];
+            const raw = result[PLAN_TEXT_KEY];
+            const text = (typeof raw === "string" ? raw : "").trim().slice(0, PLAN_CONTEXT_MAX_CHARS);
+            // Anything but a clear answer (Esc, closed screen, cancelled run, empty context) is a skip.
+            const decision = choice === "approve" ? "approve" : choice === "context" && text ? "context" : "skip";
+            const decided = decidePlan(deps.store, sessionId, planId, decision, plan);
+            if (!decided) {
+                // Not pending any more (replaced or settled elsewhere): nothing to apply.
+                withdrawPendingPlan(deps.store, sessionId);
+                return withArtifact(textResult(answer("skipped", "This plan is no longer awaiting a decision. Stay in plan mode.")), artifact);
+            }
+            context.emitEvent?.("plan_decided", {
+                callId: context.callId ?? "",
+                planId,
+                hash,
+                decision,
+            });
+            const base = { planId, revision, ...(artifact ? { artifactId: artifact.id } : {}) };
+            const body = decision === "approve"
+                ? answer("approved", "The user approved the plan. The build agent will implement exactly this plan in the " +
+                    "next turn. Do not implement anything yourself: reply with one short sentence and " +
+                    "call no more tools.", base)
+                : decision === "context"
+                    ? answer("feedback", "The user added context instead of deciding. Revise the plan to account for it and " +
+                        "call exit_plan again with the complete updated plan.", { ...base, feedback: text })
+                    : answer("skipped", "The user chose to skip for now. Stay in plan mode and do not implement anything. " +
+                        "Do not call exit_plan again unless the user asks; end your turn with one short sentence.", base);
+            return withArtifact(textResult(body), artifact);
+        },
+    });
+}

package/dist/plan/state.d.ts

@@ -0,0 +1,102 @@
+import type { QuestionOption } from "@alisio/sdk";
+/** The decision screen title (web: localized; the TUI prints it as is). */
+export declare const PLAN_REVIEW_TITLE = "Plan complete. What would you like to do?";
+export declare const PLAN_QUESTION_ID = "plan";
+export declare const PLAN_TEXT_KEY = "plan:text";
+/** The agent an approved plan is handed to. */
+export declare const IMPLEMENTATION_AGENT_ID = "build";
+export declare const PLAN_MAX_CHARS = 60000;
+/** Longest "Add context" text accepted (the same bound everywhere). */
+export declare const PLAN_CONTEXT_MAX_CHARS = 20000;
+/** The three decisions, with the exact visible English strings (the web localizes by `value`). */
+export declare const PLAN_OPTIONS: QuestionOption[];
+export type PlanStatus = "pending" | "approved" | "implementing" | "skipped" | "feedback" | "cancelled";
+export interface PlanState {
+    /** One per `exit_plan` call. */
+    planId: string;
+    revision: number;
+    hash: string;
+    title: string;
+    status: PlanStatus;
+    callId?: string;
+    artifactId?: string;
+    /** The approved snapshot; kept only while `approved` (afterwards it lives in the user message). */
+    plan?: string;
+    updatedAt: number;
+}
+/** What a store must offer to keep plan state (`SQLiteStore` does). */
+export interface PlanStore {
+    mutateSessionOptions<T>(id: string, change: (current: Record<string, unknown>) => {
+        patch?: Record<string, unknown>;
+        value: T;
+    }): T;
+    get(id: string): {
+        options?: Record<string, unknown>;
+    };
+}
+export declare const planHash: (plan: string) => string;
+/** The plan state stored in `options`, or undefined when absent or malformed. */
+export declare function readPlanState(options: Record<string, unknown> | undefined): PlanState | undefined;
+export declare const currentPlan: (store: PlanStore, sessionId: string) => PlanState | undefined;
+/** The revision the next proposal of this session gets. */
+export declare const nextPlanRevision: (store: PlanStore, sessionId: string) => number;
+/** Records a new proposal (replacing any earlier one: only the latest plan can be decided). */
+export declare function proposePlan(store: PlanStore, sessionId: string, input: Omit<PlanState, "status" | "updatedAt" | "plan"> & {
+    status?: PlanStatus;
+}): PlanState;
+export type PlanDecision = "approve" | "skip" | "context";
+/**
+ * Applies the user's decision to the pending proposal `planId`. Returns the new state, or
+ * undefined when that proposal is not pending any more (already decided, replaced, withdrawn).
+ */
+export declare function decidePlan(store: PlanStore, sessionId: string, planId: string, decision: PlanDecision, plan: string): PlanState | undefined;
+/**
+ * Hands an approved plan to the implementation turn, exactly once: `approved` becomes
+ * `implementing` and `alsoSet` is merged into the session options in the same transaction (the
+ * web switches the session to `build` there). A second call finds nothing and returns undefined.
+ */
+export declare function claimApprovedPlan(store: PlanStore, sessionId: string, alsoSet?: Record<string, unknown>): (PlanState & {
+    plan: string;
+}) | undefined;
+/** An approved plan whose run was cancelled never starts anything: it is marked `cancelled`. */
+export declare function discardApprovedPlan(store: PlanStore, sessionId: string): boolean;
+/** A proposal still `pending` when its run ends was never answered: it counts as skipped. */
+export declare function withdrawPendingPlan(store: PlanStore, sessionId: string): boolean;
+export type PlanFollowUp = {
+    kind: "none";
+}
+/** An approval the run's cancellation dropped before anything started. */
+ | {
+    kind: "dropped";
+}
+/** Start ONE implementation turn with this prompt (the claim already happened). */
+ | {
+    kind: "implement";
+    plan: PlanState & {
+        plan: string;
+    };
+    text: string;
+    display: string;
+};
+/**
+ * What a host does when a run has ended (the same rules for the TUI and the server): a cancelled
+ * run drops an approved plan, an unanswered review counts as skipped, and an approved plan is
+ * claimed exactly once and turned into the implementation prompt.
+ */
+export declare function settlePlanRun(store: PlanStore, sessionId: string, options: {
+    aborted: boolean;
+    alsoSet?: Record<string, unknown>;
+}): PlanFollowUp;
+/** The first Markdown heading, as a fallback title. */
+export declare function planTitle(plan: string, given?: unknown): string;
+/**
+ * The persisted user message of the implementation turn: the approved plan as an immutable
+ * snapshot, plus the short `display` the UIs show instead of the whole plan (they already showed
+ * it at review time).
+ */
+export declare function implementationPrompt(state: PlanState & {
+    plan: string;
+}): {
+    text: string;
+    display: string;
+};

package/dist/plan/state.js

@@ -0,0 +1,165 @@
+/**
+ * Plan review state (`sessions.options.plan`) and the pure helpers around it. One entry per
+ * session: the latest `exit_plan` proposal. Every transition is a compare-and-set inside one
+ * `BEGIN IMMEDIATE` transaction, so it is safe across surfaces (and processes) that share the
+ * database: whatever happens twice (a double click, a reload, two tabs) changes the state once.
+ *
+ * pending ──approve──▶ approved ──claim──▶ implementing
+ *    ├────skip──────▶ skipped          └─discard─▶ cancelled (the run was cancelled)
+ *    └────context───▶ feedback         (a later `exit_plan` call starts a new revision)
+ */
+import { createHash } from "node:crypto";
+/** The decision screen title (web: localized; the TUI prints it as is). */
+export const PLAN_REVIEW_TITLE = "Plan complete. What would you like to do?";
+export const PLAN_QUESTION_ID = "plan";
+export const PLAN_TEXT_KEY = `${PLAN_QUESTION_ID}:text`;
+/** The agent an approved plan is handed to. */
+export const IMPLEMENTATION_AGENT_ID = "build";
+export const PLAN_MAX_CHARS = 60_000;
+/** Longest "Add context" text accepted (the same bound everywhere). */
+export const PLAN_CONTEXT_MAX_CHARS = 20_000;
+/** The three decisions, with the exact visible English strings (the web localizes by `value`). */
+export const PLAN_OPTIONS = [
+    { value: "approve", label: "Agree and start implementation", recommended: true },
+    { value: "skip", label: "Skip for now" },
+    {
+        value: "context",
+        label: "Add context",
+        textInput: { placeholder: "Add context for the plan" },
+    },
+];
+export const planHash = (plan) => createHash("sha256").update(plan, "utf8").digest("hex");
+const STATUSES = new Set([
+    "pending",
+    "approved",
+    "implementing",
+    "skipped",
+    "feedback",
+    "cancelled",
+]);
+/** The plan state stored in `options`, or undefined when absent or malformed. */
+export function readPlanState(options) {
+    const raw = options?.plan;
+    if (!raw ||
+        typeof raw !== "object" ||
+        typeof raw.planId !== "string" ||
+        typeof raw.hash !== "string" ||
+        typeof raw.revision !== "number" ||
+        typeof raw.status !== "string" ||
+        !STATUSES.has(raw.status))
+        return undefined;
+    return raw;
+}
+export const currentPlan = (store, sessionId) => readPlanState(store.get(sessionId).options);
+/** The revision the next proposal of this session gets. */
+export const nextPlanRevision = (store, sessionId) => (currentPlan(store, sessionId)?.revision ?? 0) + 1;
+/** Records a new proposal (replacing any earlier one: only the latest plan can be decided). */
+export function proposePlan(store, sessionId, input) {
+    const state = { ...input, status: input.status ?? "pending", updatedAt: Date.now() };
+    return store.mutateSessionOptions(sessionId, () => ({ patch: { plan: state }, value: state }));
+}
+/**
+ * Applies the user's decision to the pending proposal `planId`. Returns the new state, or
+ * undefined when that proposal is not pending any more (already decided, replaced, withdrawn).
+ */
+export function decidePlan(store, sessionId, planId, decision, plan) {
+    return store.mutateSessionOptions(sessionId, (options) => {
+        const current = readPlanState(options);
+        if (!current || current.planId !== planId || current.status !== "pending")
+            return { value: undefined };
+        const next = {
+            ...current,
+            status: decision === "approve" ? "approved" : decision === "skip" ? "skipped" : "feedback",
+            ...(decision === "approve" ? { plan } : {}),
+            updatedAt: Date.now(),
+        };
+        return { patch: { plan: next }, value: next };
+    });
+}
+/**
+ * Hands an approved plan to the implementation turn, exactly once: `approved` becomes
+ * `implementing` and `alsoSet` is merged into the session options in the same transaction (the
+ * web switches the session to `build` there). A second call finds nothing and returns undefined.
+ */
+export function claimApprovedPlan(store, sessionId, alsoSet = {}) {
+    return store.mutateSessionOptions(sessionId, (options) => {
+        const current = readPlanState(options);
+        if (!current || current.status !== "approved" || typeof current.plan !== "string")
+            return { value: undefined };
+        const { plan, ...rest } = current;
+        const claimed = { ...rest, status: "implementing", updatedAt: Date.now() };
+        return { patch: { ...alsoSet, plan: claimed }, value: { ...claimed, plan } };
+    });
+}
+/** An approved plan whose run was cancelled never starts anything: it is marked `cancelled`. */
+export function discardApprovedPlan(store, sessionId) {
+    return store.mutateSessionOptions(sessionId, (options) => {
+        const current = readPlanState(options);
+        if (!current || current.status !== "approved")
+            return { value: false };
+        const { plan: _snapshot, ...rest } = current;
+        return {
+            patch: { plan: { ...rest, status: "cancelled", updatedAt: Date.now() } },
+            value: true,
+        };
+    });
+}
+/** A proposal still `pending` when its run ends was never answered: it counts as skipped. */
+export function withdrawPendingPlan(store, sessionId) {
+    return store.mutateSessionOptions(sessionId, (options) => {
+        const current = readPlanState(options);
+        if (!current || current.status !== "pending")
+            return { value: false };
+        return {
+            patch: { plan: { ...current, status: "skipped", updatedAt: Date.now() } },
+            value: true,
+        };
+    });
+}
+/**
+ * What a host does when a run has ended (the same rules for the TUI and the server): a cancelled
+ * run drops an approved plan, an unanswered review counts as skipped, and an approved plan is
+ * claimed exactly once and turned into the implementation prompt.
+ */
+export function settlePlanRun(store, sessionId, options) {
+    withdrawPendingPlan(store, sessionId);
+    if (options.aborted)
+        return discardApprovedPlan(store, sessionId) ? { kind: "dropped" } : { kind: "none" };
+    const claimed = claimApprovedPlan(store, sessionId, options.alsoSet);
+    if (!claimed)
+        return { kind: "none" };
+    return { kind: "implement", plan: claimed, ...implementationPrompt(claimed) };
+}
+/** The first Markdown heading, as a fallback title. */
+export function planTitle(plan, given) {
+    const explicit = typeof given === "string" ? given.trim() : "";
+    if (explicit)
+        return explicit.slice(0, 120);
+    const heading = /^#{1,3}\s+(.+?)\s*#*\s*$/m.exec(plan)?.[1]?.trim();
+    return (heading || "Implementation plan").slice(0, 120);
+}
+const oneLine = (text, max) => {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+};
+/**
+ * The persisted user message of the implementation turn: the approved plan as an immutable
+ * snapshot, plus the short `display` the UIs show instead of the whole plan (they already showed
+ * it at review time).
+ */
+export function implementationPrompt(state) {
+    const artifact = state.artifactId ? `, artifact ${state.artifactId}` : "";
+    return {
+        text: [
+            `Implement the approved plan (revision ${state.revision}, sha256 ${state.hash.slice(0, 12)}${artifact}).`,
+            "The plan below is the approved snapshot. Follow it: do not plan again and do not ask for",
+            "approval again. If a step turns out to be wrong or impossible, say so and make the smallest",
+            "adjustment that keeps the plan's goal.",
+            "",
+            `<approved_plan title="${state.title.replace(/"/g, "'")}">`,
+            state.plan,
+            "</approved_plan>",
+        ].join("\n"),
+        display: `Implement the approved plan: ${oneLine(state.title, 100)}`,
+    };
+}

package/dist/plugins/host.d.ts

@@ -1,4 +1,4 @@
-import type { AskQuestionsRequest, AskQuestionsResult, CommandContext, CommandOptions, CompletionRequest, Message, PanelProvider, Plugin, PluginAPI, PluginMetadata, RunEvent, SelectRequest } from "@alisio/sdk";
+import type { AskQuestionsRequest, AskQuestionsResult, CommandContext, CommandOptions, CompletionRequest, Message, PanelProvider, Plugin, PluginAPI, PluginMetadata, RunEvent, SelectRequest, ViewContext } from "@alisio/sdk";
 import type { HookFailure, RunnerExtensions } from "../core/contracts.ts";
 import type { ToolRegistry } from "../core/registry.ts";
 import { ExtensionRegistry } from "../extensions/registry.ts";
@@ -10,6 +10,19 @@ export interface PluginHostOptions {
     /** Timeout for session-end hooks (for example an automatic summary). */
     sessionEndTimeoutMs?: number;
 }
+/** A failed data view: the host maps `code` to an API error (never echoing parameter values). */
+export declare class ViewRunError extends Error {
+    readonly code: "not_found" | "invalid_params" | "failed";
+    readonly fields: string[];
+    constructor(code: "not_found" | "invalid_params" | "failed", message: string, fields?: string[], options?: {
+        cause?: unknown;
+    });
+}
+export interface ViewInfo {
+    id: string;
+    description: string;
+    params: Record<string, unknown>;
+}
 export declare class PluginHost implements RunnerExtensions {
     private registry;
     private state;
@@ -37,6 +50,8 @@ export declare class PluginHost implements RunnerExtensions {
     private startHandlers;
     private endHandlers;
     private fieldOwners;
+    /** Registered tool name → contributing plugin id. */
+    private toolOwners;
     private completer?;
     private modelsImpl?;
     observers: Set<(event: Readonly<RunEvent>) => void>;
@@ -57,6 +72,8 @@ export declare class PluginHost implements RunnerExtensions {
         plugin: string;
         dir: string;
     }>;
+    /** Read-only data views contributed by plugins, keyed `plugin:view`. */
+    private views;
     /** Tree panels contributed by plugins, keyed `plugin:id`. */
     panels: Map<string, {
         plugin: string;
@@ -72,6 +89,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"
@@ -160,6 +183,16 @@ export declare class PluginHost implements RunnerExtensions {
     }>;
     /** Loaded plugins (id, version, built-in flag), ordered by id. */
     metadata(): PluginMetadata[];
+    /** Data views a plugin registered (without their handlers). */
+    viewsOf(plugin: string): ViewInfo[];
+    /**
+     * Validates `query` against the view's declared schema (coerced from strings) and runs it.
+     * Timeouts and response caps are the caller's job (the server enforces both). Errors are
+     * `ViewRunError`s whose messages never include parameter values or handler internals.
+     */
+    runView(plugin: string, id: string, query: Record<string, string>, context: ViewContext): Promise<unknown>;
+    /** Registered names of the tools a plugin contributes (namespaced unless built in). */
+    toolsOf(plugin: string): string[];
     get hasSessionEndHooks(): boolean;
     /** Conservative ownership check used to protect a live session from plugin removal. */
     ownsSessionResources(plugin: string): boolean;