@gtrabanco/pi-agentic-workflow 0.1.0

package/dist/config/types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The configuration vocabulary shared by every layer of the package (SPEC S5–S8).
+ *
+ * Two distinct shapes exist on purpose:
+ *  - `ConfigFile` is what an operator WRITES: everything optional, exactly the
+ *    three keys the SPEC's config schema names, nothing more.
+ *  - `EffectiveConfig` is what the extension READS after merge: every route
+ *    fully resolved, so no downstream code has to reason about optionality.
+ */
+/** Pi's thinking levels, mirrored here so the domain layer stays Pi-free. */
+export declare const THINKING_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+/** A thinking level, or `inherit` = "whatever the session already uses". */
+export type ThinkingSetting = ThinkingLevel | "inherit";
+/** `"inherit"` or an exact `provider/modelId` reference (split at the first slash). */
+export type ModelRef = `${string}/${string}`;
+export type ModelSetting = "inherit" | ModelRef;
+export interface Route {
+    model: ModelSetting;
+    thinking: ThinkingSetting;
+}
+/** What one config file may declare (SPEC "Config schema"). */
+export interface RouteFile {
+    model?: ModelSetting;
+    thinking?: ThinkingSetting;
+}
+export interface ConfigFile {
+    default?: RouteFile;
+    commands?: Record<string, RouteFile>;
+    onUnavailableRoute?: UnavailableRoutePolicy;
+}
+export type UnavailableRoutePolicy = "stop" | "inherit";
+/** One rejected field inside one config file, addressed by a JSON-path-ish string. */
+export interface ConfigIssue {
+    path: string;
+    message: string;
+}
+export declare const UNAVAILABLE_ROUTE_POLICIES: readonly UnavailableRoutePolicy[];
+export interface EffectiveConfig {
+    default: Route;
+    commands: Record<string, Route>;
+    onUnavailableRoute: UnavailableRoutePolicy;
+}
+export interface ConfigProblem {
+    scope: "global" | "project";
+    path: string;
+    message: string;
+}
+/** Absolute paths of the two dedicated JSON files (never Pi `settings.json`). */
+export interface ConfigPaths {
+    global: string;
+    project: string;
+}

package/dist/config/types.js

@@ -0,0 +1,12 @@
+/**
+ * The configuration vocabulary shared by every layer of the package (SPEC S5–S8).
+ *
+ * Two distinct shapes exist on purpose:
+ *  - `ConfigFile` is what an operator WRITES: everything optional, exactly the
+ *    three keys the SPEC's config schema names, nothing more.
+ *  - `EffectiveConfig` is what the extension READS after merge: every route
+ *    fully resolved, so no downstream code has to reason about optionality.
+ */
+/** Pi's thinking levels, mirrored here so the domain layer stays Pi-free. */
+export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+export const UNAVAILABLE_ROUTE_POLICIES = ["stop", "inherit"];

package/dist/extension/factory.d.ts

@@ -0,0 +1,47 @@
+import type { LoadedConfig } from "../config/load.js";
+import type { Catalogue } from "../routing/catalogue.js";
+import type { Router } from "../routing/dispatch.js";
+import type { ExtensionSurface, InvocationContext, ModelRef, RoutingControls } from "../routing/types.js";
+import type { HintStore } from "../routing/state.js";
+/**
+ * The Pi-free half of the extension entry (SPEC "Command surface (api)").
+ *
+ * Given something that can register commands and a surface shaped like
+ * `ExtensionAPI`, this wires one command per bundled public skill plus the
+ * settings console, and returns the router that owns model lifecycle. Every
+ * behaviour in AC3–AC12 is reachable from here, so `index.ts` stays a thin
+ * adapter over Pi's real objects and nothing has to be tested against a live
+ * session. `M` is the session model type — Pi's `Model` in production, a plain
+ * `{provider, id}` in tests.
+ */
+export interface CommandRegistrar<M extends ModelRef = ModelRef> {
+    registerCommand(name: string, options: {
+        description?: string;
+        handler: (args: string, ctx: InvocationContext<M>) => void | Promise<void>;
+    }): void;
+}
+/** What the settings command presents (SPEC S4): the console, over the same files. */
+export type SettingsHandler<M extends ModelRef = ModelRef> = (input: {
+    catalogue: Catalogue;
+    ctx: InvocationContext<M>;
+    /** Lets the console show and release a latch the operator can otherwise wait on. */
+    routing: RoutingControls;
+}) => unknown;
+export interface ExtensionDeps<M extends ModelRef = ModelRef> {
+    registrar: CommandRegistrar<M>;
+    /** Pi's API is session-bound, so the router resolves the surface per call. */
+    surface: (ctx: InvocationContext<M>) => ExtensionSurface<M>;
+    /** Directory holding the bundled `skills/` tree. */
+    skillsDir: string;
+    /** Global agent directory, from Pi's `getAgentDir()`. */
+    agentDir: string;
+    hint: HintStore;
+    settings: SettingsHandler<M>;
+    /** Overridable so a test can hand the router an in-memory configuration. */
+    loadConfig?: (ctx: InvocationContext<M>) => LoadedConfig;
+}
+export interface ExtensionHandle<M extends ModelRef = ModelRef> {
+    router: Router<M>;
+    catalogue: Catalogue;
+}
+export declare function createExtension<M extends ModelRef = ModelRef>(deps: ExtensionDeps<M>): ExtensionHandle<M>;

package/dist/extension/factory.js

@@ -0,0 +1,49 @@
+import { loadConfig } from "../config/load.js";
+import { readCatalogue } from "../routing/catalogue.js";
+import { createRouter } from "../routing/dispatch.js";
+import { SETTINGS_COMMAND } from "../routing/types.js";
+export function createExtension(deps) {
+    const { registrar, surface, skillsDir, agentDir, hint, settings } = deps;
+    const catalogue = readCatalogue(skillsDir);
+    const read = (ctx) => deps.loadConfig?.(ctx) ?? loadConfig({ agentDir, cwd: ctx.cwd, projectTrusted: ctx.isProjectTrusted() });
+    // A skill that cannot become a command is a packaging fact the operator must
+    // see, and Pi exposes notifications only through the invocation context — so
+    // the first command run in the session carries the report, once.
+    let reported = catalogue.issues.length === 0;
+    const reportCatalogueIssues = (ctx) => {
+        if (reported)
+            return;
+        reported = true;
+        for (const issue of catalogue.issues) {
+            ctx.notify(`pi-agentic-workflow: skills/${issue.dir}: ${issue.message}`, "warning");
+        }
+    };
+    const knownCommands = new Set([...catalogue.commands.map((entry) => entry.name), SETTINGS_COMMAND]);
+    const router = createRouter({ surface, loadConfig: read, hint, settingsCommand: SETTINGS_COMMAND, knownCommands });
+    for (const command of catalogue.commands) {
+        registrar.registerCommand(command.name, {
+            ...(command.description ? { description: command.description } : {}),
+            handler: async (args, ctx) => {
+                reportCatalogueIssues(ctx);
+                await router.dispatch(command, args, ctx);
+            },
+        });
+    }
+    registrar.registerCommand(SETTINGS_COMMAND, {
+        description: "Show and configure per-command model routing",
+        handler: async (_args, ctx) => {
+            reportCatalogueIssues(ctx);
+            // Bound for the console: two verbs and the session they act on, so it cannot
+            // reach for `settle` or `dispatch` by accident.
+            const routing = { inFlight: () => router.inFlight(), undoInFlight: () => router.undoInFlight(ctx) };
+            try {
+                await settings({ catalogue, ctx, routing });
+            }
+            catch (error) {
+                // A console that dies mid-question must say so, not take the session down.
+                ctx.notify(`Settings could not be opened: ${error.message}`, "error");
+            }
+        },
+    });
+    return { router, catalogue };
+}

package/dist/extension/index.d.ts

@@ -0,0 +1,4 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { SETTINGS_COMMAND } from "../routing/types.js";
+export default function extension(pi: ExtensionAPI): void;
+export { SETTINGS_COMMAND };

package/dist/extension/index.js

@@ -0,0 +1,84 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "../config/load.js";
+import { createExtension } from "./factory.js";
+import { createHintStore, stateFilePath } from "../routing/state.js";
+import { runSettingsConsole } from "../settings/console.js";
+import { readConfigFile, writeConfigFile } from "../settings/store.js";
+import { SETTINGS_COMMAND } from "../routing/types.js";
+/**
+ * Pi adapter — the only file in the package that imports Pi values (SPEC
+ * "Package layout": `dist/extension/index.js`).
+ *
+ * Its whole job is translation between Pi's context and the narrow view the
+ * router understands, with no casts: `M` is bound to Pi's own `Model`, so every
+ * model reference the router stores and hands back is the exact object
+ * `ctx.modelRegistry` produced. Routing, configuration, and lifecycle live in
+ * the Pi-free modules this wires — which is what lets AC3–AC12 be tested
+ * without a session.
+ */
+const skillsDir = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "skills");
+const thinkingLevelsInSyncWithPi = true;
+function toInvocationContext(ctx) {
+    return {
+        cwd: ctx.cwd,
+        get model() {
+            return ctx.model;
+        },
+        isIdle: () => ctx.isIdle(),
+        isProjectTrusted: () => ctx.isProjectTrusted(),
+        notify: (message, kind) => ctx.ui.notify(message, kind),
+        ui: ctx.ui,
+        availableModels: () => ctx.modelRegistry.getAll(),
+        find: (provider, modelId) => ctx.modelRegistry.find(provider, modelId),
+        hasConfiguredAuth: (model) => ctx.modelRegistry.hasConfiguredAuth(model),
+    };
+}
+function toRegistrar(pi) {
+    return {
+        registerCommand: (name, options) => pi.registerCommand(name, {
+            ...(options.description ? { description: options.description } : {}),
+            handler: async (args, ctx) => {
+                await options.handler(args, toInvocationContext(ctx));
+            },
+        }),
+    };
+}
+export default function extension(pi) {
+    const agentDir = getAgentDir();
+    const hint = createHintStore({ path: stateFilePath(agentDir) });
+    const { router } = createExtension({
+        registrar: toRegistrar(pi),
+        // Resolved per call: the router must never hold a session-bound object
+        // between turns, because Pi can hand a new session to the same extension.
+        surface: () => ({
+            sendUserMessage: (content, options) => pi.sendUserMessage(content, options),
+            setModel: (model) => pi.setModel(model),
+            getThinkingLevel: () => pi.getThinkingLevel(),
+            setThinkingLevel: (level) => pi.setThinkingLevel(level),
+        }),
+        skillsDir,
+        agentDir,
+        hint,
+        loadConfig: (ctx) => loadConfig({ agentDir, cwd: ctx.cwd, projectTrusted: ctx.isProjectTrusted() }),
+        // The console edits the same files the dispatcher reads (SPEC S4, AC10).
+        settings: ({ ctx, catalogue: routed, routing }) => runSettingsConsole({
+            routing,
+            ui: ctx.ui,
+            agentDir,
+            cwd: ctx.cwd,
+            projectTrusted: ctx.isProjectTrusted(),
+            commands: routed.commands.map((command) => command.name),
+            models: ctx.availableModels().map((model) => `${model.provider}/${model.id}`),
+            readFile: readConfigFile,
+            writeFile: writeConfigFile,
+        }),
+    });
+    pi.on("model_select", (event) => router.noteModelSelect(event.model));
+    pi.on("thinking_level_select", (event) => router.noteThinkingLevelSelect(event.level));
+    pi.on("agent_settled", (_event, ctx) => void router.settle(toInvocationContext(ctx)));
+}
+// Exported so the settings console (P4) names the same command without relisting it.
+export { SETTINGS_COMMAND };
+void thinkingLevelsInSyncWithPi;

package/dist/routing/catalogue.d.ts

@@ -0,0 +1,35 @@
+import type { WorkflowCommand } from "./types.js";
+export interface SkillMeta {
+    /** Directory name inside the bundle — the fallback when `name:` is absent. */
+    dir: string;
+    name: string;
+    description?: string;
+    userInvocable: boolean;
+}
+/**
+ * Minimal frontmatter reader: `name`, `description`, `user-invocable` only.
+ *
+ * `user-invocable` must say `true` to count: this repository's own rule
+ * (CLAUDE.md — the key "REQUIRED for it to appear in the agent's /command menu")
+ * makes absence mean internal, and `scripts/bundle-skills.mjs` reads it the same
+ * way. The two scanners agree because the rule is stated once per scanner and
+ * pinned by `test/alias-coverage.test.mjs`, not because either default is safe.
+ */
+export declare function readSkillMeta(text: string, dir: string): SkillMeta;
+export interface CatalogueIssue {
+    dir: string;
+    message: string;
+}
+export interface Catalogue {
+    commands: WorkflowCommand[];
+    /** Skills present but unusable as commands (missing file, duplicate name). */
+    issues: CatalogueIssue[];
+    /** Every scanned skill that is callable, used by the alias-coverage assertions. */
+    invocable: SkillMeta[];
+}
+/**
+ * Read a bundled skills directory. A duplicate `name:` is reported instead of
+ * silently shadowing an alias: two skills claiming one command is a packaging
+ * bug the operator must see.
+ */
+export declare function readCatalogue(skillsDir: string, readFile?: (path: string) => string): Catalogue;

package/dist/routing/catalogue.js

@@ -0,0 +1,79 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * The command catalogue: one entry per bundled `user-invocable: true` skill,
+ * named exactly after that skill's frontmatter `name:` (SPEC S3, D-P9).
+ *
+ * The rule is intentionally the bundler's rule, read from the OTHER side:
+ * `scripts/bundle-skills.mjs` decides what ships at build time, this module
+ * decides what is callable at runtime. Both scan the same three frontmatter
+ * fields, and `test/skill-parity.test.mjs` + `test/alias-coverage.test.mjs`
+ * pin the two views against the live tree, so a skill that stops being
+ * user-invocable loses its command in the same commit.
+ */
+const SKILL_FILE = "SKILL.md";
+/**
+ * Minimal frontmatter reader: `name`, `description`, `user-invocable` only.
+ *
+ * `user-invocable` must say `true` to count: this repository's own rule
+ * (CLAUDE.md — the key "REQUIRED for it to appear in the agent's /command menu")
+ * makes absence mean internal, and `scripts/bundle-skills.mjs` reads it the same
+ * way. The two scanners agree because the rule is stated once per scanner and
+ * pinned by `test/alias-coverage.test.mjs`, not because either default is safe.
+ */
+export function readSkillMeta(text, dir) {
+    const lines = text.split(/\r?\n/u);
+    const meta = { dir, name: dir, userInvocable: false };
+    if (lines[0]?.trim() !== "---")
+        return meta;
+    for (let index = 1; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (line.trim() === "---")
+            break;
+        const colon = line.indexOf(":");
+        if (colon === -1)
+            continue;
+        const key = line.slice(0, colon).trim();
+        const value = line.slice(colon + 1).trim().replace(/^["']|["']$/gu, "");
+        if (key === "name" && value !== "")
+            meta.name = value;
+        else if (key === "description" && value !== "")
+            meta.description = value;
+        else if (key === "user-invocable")
+            meta.userInvocable = value === "true";
+    }
+    return meta;
+}
+/**
+ * Read a bundled skills directory. A duplicate `name:` is reported instead of
+ * silently shadowing an alias: two skills claiming one command is a packaging
+ * bug the operator must see.
+ */
+export function readCatalogue(skillsDir, readFile = (p) => readFileSync(p, "utf8")) {
+    const commands = [];
+    const invocable = [];
+    const issues = [];
+    const taken = new Map();
+    for (const dir of readdirSync(skillsDir, { withFileTypes: true }).filter((entry) => entry.isDirectory())) {
+        let meta;
+        try {
+            meta = readSkillMeta(readFile(join(skillsDir, dir.name, SKILL_FILE)), dir.name);
+        }
+        catch {
+            issues.push({ dir: dir.name, message: "no readable SKILL.md" });
+            continue;
+        }
+        if (!meta.userInvocable)
+            continue;
+        const owner = taken.get(meta.name);
+        if (owner) {
+            issues.push({ dir: dir.name, message: `command name "${meta.name}" already claimed by ${owner}/` });
+            continue;
+        }
+        taken.set(meta.name, dir.name);
+        invocable.push(meta);
+        commands.push({ name: meta.name, skill: dir.name, ...(meta.description ? { description: meta.description } : {}) });
+    }
+    commands.sort((left, right) => left.name.localeCompare(right.name));
+    return { commands, issues, invocable };
+}

package/dist/routing/dispatch.d.ts

@@ -0,0 +1,34 @@
+import type { LoadedConfig } from "../config/load.js";
+import type { ThinkingLevel } from "../config/types.js";
+import type { DispatchOutcome, ExtensionSurface, InvocationContext, ModelRef, WorkflowCommand } from "./types.js";
+export interface RouterDeps<M extends ModelRef = ModelRef> {
+    /** Pi's API is session-bound, so the surface is resolved per call. */
+    surface: (ctx: InvocationContext<M>) => ExtensionSurface<M>;
+    /** Fresh read per dispatch: project trust and file validity change between commands. */
+    loadConfig: (ctx: InvocationContext<M>) => LoadedConfig;
+    hint: {
+        pending(): boolean;
+        acknowledge(now?: string): boolean;
+    };
+    /** Slash name of the settings console, quoted in every refusal. */
+    settingsCommand: string;
+    /** Command names that actually exist — a route for anything else is a typo. */
+    knownCommands: ReadonlySet<string>;
+}
+export interface Router<M extends ModelRef = ModelRef> {
+    dispatch(command: WorkflowCommand, args: string, ctx: InvocationContext<M>): Promise<DispatchOutcome>;
+    /** Pi `model_select` — distinguishes our own switch from the operator's. */
+    noteModelSelect(model: M): void;
+    /** Pi `thinking_level_select` — same distinction for the thinking level. */
+    noteThinkingLevelSelect(level: ThinkingLevel): void;
+    /** Pi `agent_settled` — restores whatever this turn still owns. */
+    settle(ctx: InvocationContext<M>): Promise<void>;
+    /** True while a routed turn owns the session. The console shows and clears it. */
+    inFlight(): boolean;
+    /**
+     * Undo a routed turn the operator can see will never settle, putting the session
+     * back exactly as `settle()` would. Returns false when nothing was in flight.
+     */
+    undoInFlight(ctx: InvocationContext<M>): Promise<boolean>;
+}
+export declare function createRouter<M extends ModelRef = ModelRef>({ surface, loadConfig, hint, settingsCommand, knownCommands, }: RouterDeps<M>): Router<M>;

package/dist/routing/dispatch.js

@@ -0,0 +1,191 @@
+import { effectiveRoute } from "../config/merge.js";
+import { parseModelReference } from "../config/schema.js";
+import { modelRefKey } from "./types.js";
+/**
+ * Put a routed turn's session back (AC8). Shared by `settle()` and the console's
+ * release so the two can never disagree about what "restore" means; `why` is only
+ * the operator's word for what happened to the turn.
+ */
+async function restore(turn, session, ctx, why) {
+    if (turn.userChangedModel) {
+        if (turn.applied.model || turn.applied.thinking) {
+            ctx.notify(`/${turn.command}: ${why}; leaving the model you chose in place.`, "info");
+        }
+        return;
+    }
+    const touched = Boolean(turn.applied.model || turn.applied.thinking);
+    if (turn.applied.model) {
+        if (turn.snapshot.model)
+            await session.setModel(turn.snapshot.model);
+        else
+            ctx.notify(`/${turn.command} switched a session that had no model; nothing to restore.`, "warning");
+    }
+    if (!touched)
+        return;
+    // Thinking last, and always: selecting a model re-derives the level inside Pi, so
+    // restoring the model alone leaves a model-only route with the operator's level
+    // moved (AC8 asks for the session to equal its start). An operator who moved the
+    // level themselves keeps it — including over the model restore's side effect.
+    const wanted = turn.userChangedThinking && turn.operatorThinking ? turn.operatorThinking : turn.snapshot.thinking;
+    if (session.getThinkingLevel() !== wanted)
+        session.setThinkingLevel(wanted);
+}
+export function createRouter({ surface, loadConfig, hint, settingsCommand, knownCommands, }) {
+    let pending;
+    // Reported once per session: an operator who ignores it once does not need it
+    // on every command, and a route that matches nothing must not fail silently.
+    let unknownRoutesReported = false;
+    const refuse = (ctx, reason, message) => {
+        ctx.notify(message, "error");
+        return { status: "refused", reason, message };
+    };
+    const configureHint = `Configure routes with /${settingsCommand} or the pi-agentic-workflow.json files.`;
+    return {
+        noteModelSelect(model) {
+            if (!pending)
+                return;
+            const applied = pending.applied.model;
+            // Pi fires `model_select` for our own switch too. Anything else is the
+            // operator taking the model, and then we back off entirely — restoring on
+            // top of their choice would fight the session.
+            if (applied && modelRefKey(applied) === modelRefKey(model))
+                return;
+            pending.userChangedModel = true;
+        },
+        noteThinkingLevelSelect(level) {
+            if (!pending)
+                return;
+            // A level we just applied ourselves is not an operator change. A model
+            // switch counts as "ours" too: Pi re-derives thinking inside `setModel`,
+            // and this router performs that switch.
+            if (pending.applied.thinking === level || pending.applied.modelThinking === level)
+                return;
+            pending.userChangedThinking = true;
+            pending.operatorThinking = level;
+        },
+        inFlight: () => pending !== undefined,
+        async undoInFlight(ctx) {
+            const turn = pending;
+            if (!turn)
+                return false;
+            pending = undefined;
+            await restore(turn, surface(ctx), ctx, `undo: nothing was dispatched by /${turn.command}`);
+            return true;
+        },
+        async settle(ctx) {
+            const turn = pending;
+            if (!turn)
+                return;
+            // Cleared first: the restore fires its own select events, and a turn that is
+            // already over must not read them as operator changes.
+            pending = undefined;
+            await restore(turn, surface(ctx), ctx, "finished");
+        },
+        async dispatch(command, args, ctx) {
+            if (pending) {
+                // Refuse even when `ctx.isIdle()` reads true: idleness says the agent loop
+                // is quiet, not that the routed turn is over, and guessing here is how a
+                // session gets restored mid-turn. Pi starts a routed turn inside an action
+                // that swallows failures and `prompt()` can throw before the loop runs, so a
+                // latch with no turn behind it is real — and the operator releases it through
+                // the console (`undoInFlight`), which is why the refusal points there (N-4).
+                return refuse(ctx, "routed-turn-in-flight", `/${command.name} refused: /${pending.command} is still routed. Wait for it to settle, or undo it with /${settingsCommand}.`);
+            }
+            if (!ctx.isIdle()) {
+                return refuse(ctx, "busy", `/${command.name} refused: the agent is busy, and routing changes the session model. Run it when the agent is idle.`);
+            }
+            const loaded = loadConfig(ctx);
+            if (!loaded.ok) {
+                const detail = loaded.problems
+                    .map((problem) => `${problem.scope} config, ${problem.path}: ${problem.message}`)
+                    .join(" | ");
+                return refuse(ctx, "invalid-config", `/${command.name} refused: invalid configuration (${detail}). Nothing was dispatched and no model was changed.`);
+            }
+            if (!unknownRoutesReported) {
+                unknownRoutesReported = true;
+                const typos = Object.keys(loaded.config.commands).filter((name) => !knownCommands.has(name));
+                if (typos.length > 0) {
+                    ctx.notify(`/${command.name}: these configured routes match no command and do nothing: ${typos.join(", ")}. Fix the spelling or remove them with /${settingsCommand}.`, "warning");
+                }
+            }
+            const session = surface(ctx);
+            const route = effectiveRoute(loaded.config, command.name);
+            let target;
+            if (route.model !== "inherit") {
+                const reference = parseModelReference(route.model);
+                const found = reference ? ctx.find(reference.provider, reference.id) : undefined;
+                const blocker = !found
+                    ? "is not in the model registry"
+                    : !ctx.hasConfiguredAuth(found)
+                        ? "has no configured credentials"
+                        : undefined;
+                if (blocker) {
+                    if (loaded.config.onUnavailableRoute !== "inherit") {
+                        return refuse(ctx, "unavailable-route", `/${command.name} stopped: the configured model ${route.model} ${blocker}. ${configureHint}`);
+                    }
+                    ctx.notify(`/${command.name}: ${route.model} ${blocker}, so it runs on the current session model. ${configureHint}`, "warning");
+                }
+                else {
+                    target = found;
+                }
+            }
+            const snapshot = { model: ctx.model, thinking: session.getThinkingLevel() };
+            const applied = { model: undefined, thinking: undefined };
+            if (target) {
+                const selected = await session.setModel(target);
+                if (!selected) {
+                    if (loaded.config.onUnavailableRoute !== "inherit") {
+                        return refuse(ctx, "unavailable-route", `/${command.name} stopped: ${route.model} could not be selected. ${configureHint}`);
+                    }
+                    ctx.notify(`/${command.name}: ${route.model} could not be selected, so it runs on the current session model. ${configureHint}`, "warning");
+                }
+                else {
+                    applied.model = target;
+                    // Pi re-derives thinking inside `setModel`; whatever level the session
+                    // holds now came from us, not from the operator.
+                    applied.modelThinking = session.getThinkingLevel();
+                }
+            }
+            if (route.thinking !== "inherit") {
+                session.setThinkingLevel(route.thinking);
+                // The *effective* level, never the requested one: Pi clamps a level the model
+                // cannot run (`_modelSupportsThinking` → `clampThinkingLevel`) and announces
+                // that one a microtask later. Bookkeeping the request made our own clamped
+                // write read as an operator move, so the restore preserved the clamp instead
+                // of the operator's level (N-3).
+                applied.thinking = session.getThinkingLevel() ?? route.thinking;
+            }
+            let hintShown = false;
+            if (hint.pending()) {
+                hintShown = true;
+                hint.acknowledge();
+                ctx.notify(`/${command.name} is running. Per-command models are optional: configure them with /${settingsCommand} or the pi-agentic-workflow.json files. This hint appears once.`, "info");
+            }
+            if (applied.model || applied.thinking) {
+                pending = { command: command.name, snapshot, applied, userChangedModel: false, userChangedThinking: false };
+            }
+            // Pi expands `/skill:<x>` by the skill's frontmatter `name:`, and passes an
+            // unknown key through as literal text — so the name is the only correct
+            // wire value. The bundled directory (`command.skill`) is not it: it happens
+            // to match today and would silently stop expanding if a skill ever renamed.
+            const invocation = args === "" ? `/skill:${command.name}` : `/skill:${command.name} ${args}`;
+            // The send is where Pi's own path can throw first (`prompt()` refuses while
+            // compaction is in progress, with no model, or without credentials — before
+            // the agent loop ever runs). That throw is proof the turn never started, so
+            // the routing applied a moment ago is undone here and now: leaving it would
+            // wedge the latch behind a refusal that names no cause (N-4).
+            try {
+                session.sendUserMessage(invocation, { expandPromptTemplates: true });
+            }
+            catch (error) {
+                pending = undefined;
+                const rolledBack = Boolean(applied.model || applied.thinking);
+                if (rolledBack) {
+                    await restore({ command: command.name, snapshot, applied, userChangedModel: false, userChangedThinking: false }, session, ctx, `dispatch failed (${error.message}); the session was put back`);
+                }
+                return refuse(ctx, "dispatch-failed", `/${command.name} was not dispatched: ${error.message}. Nothing was sent${rolledBack ? ", and the session model was put back" : ""}.`);
+            }
+            return { status: "dispatched", routed: Boolean(applied.model || applied.thinking), hintShown };
+        },
+    };
+}

package/dist/routing/state.d.ts

@@ -0,0 +1,13 @@
+export declare const stateFilePath: (agentDir: string) => string;
+export interface HintStore {
+    /** Whether the hint still needs showing. Cached after the first read. */
+    pending(): boolean;
+    /** Record that the hint was shown. Returns false when persistence failed. */
+    acknowledge(now?: string): boolean;
+}
+export interface HintStoreOptions {
+    path: string;
+    readFile?: (path: string) => string | null;
+    writeFile?: (path: string, text: string) => void;
+}
+export declare function createHintStore({ path, readFile, writeFile, }: HintStoreOptions): HintStore;