@zhihaohong52/sonata 0.8.2 → 0.9.0

package/dist/commands/reset.js

@@ -0,0 +1,340 @@
+/**
+ * `sonata reset` — undo what `sonata init` wrote, and nothing else.
+ *
+ * Init scatters its output across five places: the config, the generated tier
+ * agents, the loop skill, a block inside a `CLAUDE.md` sonata does not own,
+ * and two settings files holding the routing env, four lifecycle hooks, the
+ * permission hook and the tool allow-list. Undoing that by hand means knowing
+ * all five, which is why the only reliable answer used to be "delete the repo
+ * and start again".
+ *
+ * Three rules shape the whole command:
+ *
+ * - **It removes only what sonata wrote.** An agent file without sonata's
+ *   marker is left alone; `permissions.allow` keeps every entry that is not
+ *   sonata's; `CLAUDE.md` loses what is between the markers and not one byte
+ *   more. A settings file is rewritten, never deleted — sonata is one writer
+ *   of it among several.
+ * - **It keeps everything that is expensive to recreate**: API keys, the usage
+ *   ledger, the ranking catalogs, and the `.sonata/` run store. Those are not
+ *   configuration, and a user resetting a bad setup should not lose their
+ *   spend history or have to re-enter every key. The kept list is printed, so
+ *   "reset" cannot be read as "removed everything".
+ * - **It plans first, then applies.** The plan is a list of typed actions with
+ *   a label each, so the confirmation names every path before anything is
+ *   touched, and the set shown is exactly the set removed.
+ */
+import { existsSync, readFileSync, readdirSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { GLOBAL_CONFIG_RELATIVE } from '../config.js';
+import { isSonataAgentText } from '../detect.js';
+import { agentsDirFor, configPathFor } from '../init/helpers.js';
+import { removeGuidance } from '../init/guidance.js';
+import { readSettings, revokeSonataTools, settingsPath, uninstallHook, writeSettings, } from '../settings.js';
+import { planRouteManual, planRouteOff, routeSessionsFile, routeSettingsFile, routeSubagentsFile } from './route.js';
+/**
+ * The agent files in this directory that sonata generated.
+ *
+ * Only a missing directory is an empty answer. Every other failure — a
+ * permission error, a bad mount, an unreadable file — used to be flattened to
+ * `[]` or to `false`, which produced a plan with no agents in it and a command
+ * that reported success having left every agent installed. That is the worst
+ * shape a cleanup can fail in: silent, and indistinguishable from having had
+ * nothing to do. Unreadable files are named as warnings instead, and the
+ * ownership test is the same one `sync` and `prune` use.
+ */
+function sonataAgents(dir) {
+    const warnings = [];
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { files: [], warnings };
+        return { files: [], warnings: [`could not read ${dir}: ${err.message} — agent files left in place`] };
+    }
+    const files = [];
+    for (const f of entries.filter((name) => name.endsWith('.md')).sort()) {
+        const path = join(dir, f);
+        try {
+            if (isSonataAgentText(readFileSync(path, 'utf8')))
+                files.push(f);
+        }
+        catch (err) {
+            warnings.push(`could not read ${path}: ${err.message} — left in place`);
+        }
+    }
+    return { files, warnings };
+}
+/**
+ * Strip sonata out of one settings file.
+ *
+ * Every transform is by command *shape* rather than by this install's own
+ * path: a user who ran `sonata init` from a different checkout — an npm
+ * install now replaced by a clone, say — would otherwise have their hooks left
+ * behind by the very command whose job is removing them. `planRouteOff` can
+ * refuse (a non-localhost base URL it did not write), and that refusal must
+ * not take the rest of the file down with it, so it is caught and reported.
+ */
+export function planSettingsReset(settings, packageRoot, scope) {
+    let next = settings;
+    let changed = false;
+    const warnings = [];
+    try {
+        const off = planRouteOff(next, packageRoot);
+        next = off.settings;
+        changed = changed || off.changed;
+    }
+    catch (err) {
+        warnings.push(`left the routing env in place: ${err.message}`);
+    }
+    const manual = planRouteManual(next, packageRoot, scope);
+    next = manual.settings;
+    changed = changed || manual.changed;
+    // The permission hook is found by the file it runs, not by this install's
+    // absolute path, for the same reason `planRouteOff` finds its own that way.
+    for (const [event, needle] of [
+        ['PreToolUse', 'capture-mode.mjs'],
+        ['SessionStart', 'ensure-serve.mjs'],
+        ['SessionStart', 'route-session.mjs'],
+        ['SessionEnd', 'route-session.mjs'],
+        ['SubagentStart', 'route-subagent.mjs'],
+        ['SubagentStop', 'route-subagent.mjs'],
+    ]) {
+        for (;;) {
+            const command = (next.hooks?.[event] ?? [])
+                .flatMap((entry) => entry.hooks)
+                .find((h) => h.command.includes(needle))?.command;
+            if (command === undefined)
+                break;
+            const removed = uninstallHook(next, command, event);
+            next = removed.settings;
+            changed = changed || removed.changed;
+            // `uninstallHook` matches by exact command, so a second install's copy
+            // of the same hook survives the first pass. Without this guard, a
+            // no-op removal would also spin here forever.
+            if (!removed.changed)
+                break;
+        }
+    }
+    const revoked = revokeSonataTools(next);
+    next = revoked.settings;
+    changed = changed || revoked.changed;
+    return { settings: next, changed, warnings };
+}
+/**
+ * What `sonata reset` would do, without doing any of it.
+ *
+ * Reads the filesystem — the plan has to name real paths — but writes nothing,
+ * so it doubles as the dry run behind the confirmation prompt.
+ */
+export function planReset(opts) {
+    const scope = opts.scope ?? 'project';
+    const { cwd, home, packageRoot } = opts;
+    const base = scope === 'global' ? home : cwd;
+    const actions = [];
+    const warnings = [];
+    const configPath = configPathFor(scope, cwd, home);
+    if (existsSync(configPath)) {
+        actions.push({ kind: 'delete-file', label: 'config', path: configPath });
+    }
+    const agentsDir = agentsDirFor(scope, cwd, home);
+    const agents = sonataAgents(agentsDir);
+    warnings.push(...agents.warnings);
+    if (agents.files.length > 0) {
+        actions.push({
+            kind: 'delete-agents',
+            label: `${agents.files.length} generated agent${agents.files.length === 1 ? '' : 's'}`,
+            dir: agentsDir,
+            files: agents.files,
+        });
+    }
+    const skillDir = join(base, '.claude', 'skills', 'sonata-loop');
+    if (existsSync(skillDir)) {
+        actions.push({ kind: 'delete-dir', label: 'sonata-loop skill', path: skillDir });
+    }
+    // The CLAUDE.md block is the one artifact in a file sonata does not own, so
+    // it is spliced out rather than the file being removed — and a file whose
+    // markers do not pair up is left entirely alone, with the reason reported.
+    const guidancePath = scope === 'global'
+        ? join(home, '.claude', 'CLAUDE.md')
+        : join(cwd, 'CLAUDE.md');
+    if (existsSync(guidancePath)) {
+        try {
+            const existing = readFileSync(guidancePath, 'utf8');
+            const without = removeGuidance(existing);
+            if (without !== undefined) {
+                actions.push({
+                    kind: 'write-file', label: 'the sonata block in CLAUDE.md', path: guidancePath, content: without,
+                });
+            }
+        }
+        catch (err) {
+            warnings.push(`left ${guidancePath} unchanged: ${err.message}`);
+        }
+    }
+    // Project scope writes routing into `settings.local.json` and the permission
+    // hook into `settings.json`; global scope puts both in one file. Deduplicated
+    // so the same file is never planned twice.
+    const settingsFiles = [...new Set([
+            routeSettingsFile(cwd, scope, home),
+            settingsPath(scope, cwd, home),
+        ])];
+    for (const path of settingsFiles) {
+        if (!existsSync(path))
+            continue;
+        const current = readSettings(path);
+        const stripped = planSettingsReset(current, packageRoot, scope);
+        warnings.push(...stripped.warnings);
+        if (stripped.changed) {
+            actions.push({
+                kind: 'write-settings', label: 'routing, hooks and the tool allow-list', path, settings: stripped.settings,
+            });
+        }
+    }
+    for (const path of [routeSessionsFile(cwd, scope, home), routeSubagentsFile(cwd, scope, home)]) {
+        if (existsSync(path)) {
+            actions.push({ kind: 'delete-file', label: 'routed-session registry', path });
+        }
+    }
+    return {
+        scope,
+        actions,
+        kept: [
+            `gateway keys (${join(home, '.config', 'sonata', 'credentials')}) — \`sonata auth list\``,
+            `the usage ledger (${join(home, '.config', 'sonata', 'usage')}) — \`sonata usage\``,
+            'the ranking and pricing caches',
+            scope === 'global'
+                ? `any project's own sonata.toml`
+                : `the machine config (${join(home, GLOBAL_CONFIG_RELATIVE)})`,
+        ],
+        warnings,
+    };
+}
+/** The plan as the lines a user is asked to approve. */
+export function describeReset(plan) {
+    const lines = [];
+    if (plan.actions.length === 0) {
+        lines.push(`  nothing to remove — no sonata ${plan.scope} setup found`);
+    }
+    else {
+        lines.push(`  sonata reset (${plan.scope}) will remove:`);
+        for (const action of plan.actions) {
+            lines.push(`    ${action.kind === 'write-settings' || action.kind === 'write-file' ? '~' : '-'} ${action.label}`);
+            if (action.kind === 'delete-agents') {
+                // Every path, never a truncated sample. Elsewhere a "… and N more" is
+                // a courtesy; here the list *is* the thing being agreed to, and a
+                // confirmation that hides paths it then deletes is not a confirmation.
+                for (const f of action.files)
+                    lines.push(`        ${join(action.dir, f)}`);
+            }
+            else {
+                lines.push(`        ${action.path}`);
+                // `writeSettings` copies the file aside before writing, so the reset
+                // touches a second path — and would overwrite a backup already there.
+                // Naming it keeps "the set shown is the set touched" literally true,
+                // and the copy is the undo for this command, so it is kept.
+                if (action.kind === 'write-settings') {
+                    lines.push(`        ${action.path}.bak  (previous contents, overwritten if one exists)`);
+                }
+            }
+        }
+        lines.push('');
+        lines.push('  it keeps:');
+        for (const k of plan.kept)
+            lines.push(`    · ${k}`);
+    }
+    for (const w of plan.warnings)
+        lines.push(`    ! ${w}`);
+    return lines;
+}
+/**
+ * Delete one path, reporting anything that is not "it was already gone".
+ *
+ * `ENOENT` is the only benign failure: a concurrent `sonata sync` or a
+ * half-finished earlier reset is a race, not a fault. Every other errno —
+ * `EACCES`, `EPERM`, `EBUSY`, `EISDIR` — means the artifact is still there,
+ * and swallowing it let the command report success over a setup it had not
+ * removed.
+ */
+function removePath(path, touched, failures) {
+    try {
+        unlinkSync(path);
+        touched.push(path);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return;
+        failures.push(`${path}: ${err.message}`);
+    }
+}
+/** Carry out a plan. */
+export function applyReset(plan) {
+    const touched = [];
+    const failures = [];
+    for (const action of plan.actions) {
+        switch (action.kind) {
+            case 'delete-file':
+                removePath(action.path, touched, failures);
+                break;
+            case 'delete-dir':
+                try {
+                    rmSync(action.path, { recursive: true, force: true });
+                    touched.push(action.path);
+                }
+                catch (err) {
+                    failures.push(`${action.path}: ${err.message}`);
+                }
+                break;
+            case 'delete-agents':
+                for (const f of action.files)
+                    removePath(join(action.dir, f), touched, failures);
+                break;
+            case 'write-file':
+                try {
+                    writeFileSync(action.path, action.content);
+                    touched.push(action.path);
+                }
+                catch (err) {
+                    failures.push(`${action.path}: ${err.message}`);
+                }
+                break;
+            case 'write-settings':
+                try {
+                    writeSettings(action.path, action.settings);
+                    touched.push(action.path);
+                }
+                catch (err) {
+                    failures.push(`${action.path}: ${err.message}`);
+                }
+                break;
+        }
+    }
+    return { touched, failures };
+}
+export async function cmdReset(opts, io) {
+    const plan = planReset(opts);
+    for (const line of describeReset(plan))
+        io.out(line);
+    if (plan.actions.length === 0)
+        return 0;
+    io.out('');
+    if (!opts.yes && !await io.confirm('Remove these?')) {
+        io.out('  · nothing removed');
+        return 1;
+    }
+    const { touched, failures } = applyReset(plan);
+    io.out(`  ✓ removed ${touched.length} path${touched.length === 1 ? '' : 's'}`);
+    if (failures.length > 0) {
+        // A partial reset that exits 0 is the failure this command exists to
+        // avoid: the user believes the setup is gone and it is not.
+        io.out(`  ! ${failures.length} path(s) could not be removed:`);
+        for (const f of failures)
+            io.out(`      ${f}`);
+        return 1;
+    }
+    io.out('    ❯ run `sonata init` to set up again');
+    return 0;
+}
+//# sourceMappingURL=reset.js.map

package/dist/commands/reset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reset.js","sourceRoot":"","sources":["../../src/commands/reset.ts"],"names":[],"mappings":"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"}

package/dist/commands/route.js

@@ -17,8 +17,12 @@
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
+import { spawn } from 'node:child_process';
 import { readSettings, writeSettings, installHook, uninstallHook, hookInstalled } from '../settings.js';
 import { loadConfig, GLOBAL_CONFIG_RELATIVE, NoConfigError, parseConfig } from '../config.js';
+import { assertEffortsPinned, loadAaCatalog } from '../catalog.js';
+import { loadModelsDev } from '../modelsdev.js';
+import { configUpstreamFor } from '../pricing.js';
 import { SONATA_PROJECT_HEADER } from '../native/tenants.js';
 import { SONATA_TOKEN_HEADER, ensureRouterToken } from '../native/router-token.js';
 import { nativeSessionEnv } from './code.js';
@@ -290,14 +294,22 @@ export function sessionHookCommand(packageRoot, phase, scope = 'project') {
 /**
  * Which subagents are worth turning routing on for.
  *
- * Every agent `sonata sync` generates is `<role>-…` or `native-<role>-…`, and
- * the four roles are fixed. Matching those rather than every subagent keeps
- * the window — the only period in which a launching session loses Remote
- * Control — as short as the work actually requires. Claude Code's own
- * built-ins (`general-purpose`, `Explore`, `Plan`) do not match: the regex is
- * case-sensitive and requires the trailing hyphen.
+ * Every agent `sonata sync` generates is `<role>-<tier>`, `native-<role>-…`,
+ * or — when a role's two tier lists are element-wise identical and
+ * `tiersCollapse` folds them — the bare `<role>`. The four roles are fixed.
+ *
+ * The role may therefore be the WHOLE name, which is why the boundary is
+ * `(-|$)` and not a bare hyphen. Requiring the hyphen silently excluded every
+ * collapsed agent: an `explore` dispatch fired no hook, wrote no routing env,
+ * and died with `model_not_found` at api.anthropic.com, indistinguishable from
+ * a broken agent (measured 2026-09-14). A matcher and a filename rule that
+ * disagree about what sonata generates is the failure this shape prevents.
+ *
+ * Claude Code's own built-ins still do not match: the regex is case-sensitive,
+ * so `Explore` and `Plan` are excluded by their capital, and the boundary
+ * keeps a longer name like `planner` out rather than matching on its prefix.
  */
-export const SONATA_AGENT_MATCHER = '^(native-)?(code|review|explore|plan)-';
+export const SONATA_AGENT_MATCHER = '^(native-)?(code|review|explore|plan)(-|$)';
 /**
  * The SubagentStart/SubagentStop command auto mode installs, alongside the
  * session pair.
@@ -482,7 +494,15 @@ export async function cmdRoute(action, opts) {
             if (!existsSync(globalPath)) {
                 throw new NoConfigError(`No sonata.toml found at ${globalPath}. Run \`sonata init\` or create one.`);
             }
-            return { config: parseConfig(readFileSync(globalPath, 'utf8')) };
+            const config = parseConfig(readFileSync(globalPath, 'utf8'));
+            // The project branch above goes through `loadConfig`, which refuses an
+            // unpinned effort candidate; this one parsed the text directly, so
+            // `route on --global` installed env and hooks for a router that then
+            // refuses every request — and reported success. The comment above about
+            // `on`/`auto` installing something that depends on the config loading
+            // applies to the machine config exactly as it does to the project's.
+            assertEffortsPinned(config, loadAaCatalog(opts.home), configUpstreamFor(config, loadModelsDev(opts.home)));
+            return { config };
         }
         catch (err) {
             return { config: { native: undefined }, error: err };
@@ -541,6 +561,67 @@ export async function cmdRoute(action, opts) {
     }
     return status(settings);
 }
+/**
+ * How long the routing env stays in the settings file before the settle takes
+ * it out again.
+ *
+ * It only has to outlast this session's own read of the file, which was
+ * measured as effectively immediate — a session's first routed request landed
+ * in the same second as the hook's write. The margin is for a loaded machine,
+ * not for a slow mechanism.
+ */
+export const ROUTE_SETTLE_MS = 5_000;
+/**
+ * Takes the routing env back out of the settings file, leaving the session
+ * registered and still routing.
+ *
+ * This is the half of the design that buys Remote Control back. A session
+ * keeps routing on the value it has already read — measured 2026-09-14 at 54
+ * minutes and still routing, confirmed per session id in the ledger rather
+ * than by log line — so what the removal changes is not this session but the
+ * NEXT one, which then launches into a clean file and keeps Remote Control.
+ *
+ * The registries are deliberately left alone: clearing this session's
+ * registration would make the next SessionEnd believe it was the last one out
+ * and tear routing down under a session that is still working.
+ *
+ * **Only the newest registered session clears.** Two sessions starting inside
+ * one settle window otherwise race: s1's settle fires while s2 has written the
+ * env but may not have read it yet, and s2 then runs unrouted — silently, and
+ * indistinguishably from a broken agent, which is the single failure this
+ * design exists to remove. Deferring to the newest registration means the env
+ * survives until a full window after the LAST start, and every session in the
+ * burst has had its own window.
+ *
+ * The check and the removal are taken under the session lock, the same lock
+ * `cmdRouteSession('start')` holds while it registers and writes the env, so
+ * "is anyone newer?" cannot be answered against a list that changes underneath.
+ *
+ * A session that is no longer registered does nothing. That direction is
+ * deliberate: an env left in place costs the NEXT session's Remote Control,
+ * which is visible at launch and recoverable, while clearing one that a live
+ * session has not read yet costs that session's routing, which is not.
+ *
+ * The honest limit: the earlier `bdf8e27` experiment saw a session keep
+ * routing for tens of minutes after a removal and then stop, so the value a
+ * session holds is known to be long-lived and NOT known to be permanent.
+ */
+export async function cmdRouteSettle(sessionId, opts, deps = {}) {
+    const scope = opts.scope ?? 'project';
+    const wait = deps.delay ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    await wait(ROUTE_SETTLE_MS);
+    const registry = routeSessionsFile(opts.cwd, scope, opts.home);
+    await withSessionLock(registry, () => {
+        const registered = readSessions(registry);
+        // The newest registration, not merely membership. Registration order is
+        // the file's order — `cmdRouteSession('start')` appends — so the last
+        // entry is the most recent session to have written the env, and only its
+        // own settle may take that env away again.
+        if (registered[registered.length - 1] !== sessionId)
+            return;
+        routeOffKeepingRegistries(opts, scope);
+    });
+}
 export async function cmdRouteSession(phase, sessionId, opts, deps = {}) {
     // ONE scope resolution for this entry point; everything below takes the
     // resolved value. The writer and the cleaner of `route-subagents.json` used
@@ -645,9 +726,15 @@ export async function cmdRouteSession(phase, sessionId, opts, deps = {}) {
             }
         }
     }
-    await withSessionLock(registry, () => {
+    // Registering and writing the routing env are ONE critical section, because
+    // `cmdRouteSettle` decides whether to clear that env by asking who is
+    // newest. Split apart, a settle could read the registry between another
+    // session's append and its write and answer that question against a list
+    // that was about to change.
+    await withSessionLock(registry, async () => {
         const current = readSessions(registry);
         writeSessions(registry, current.includes(sessionId) ? current : [...current, sessionId]);
+        await cmdRoute('on', opts);
     });
     // Records which project this session belongs to, so `sonata usage --by
     // project` can attribute the router's rows. Guarded: a session must start
@@ -656,14 +743,50 @@ export async function cmdRouteSession(phase, sessionId, opts, deps = {}) {
         await recordSession(opts.home, { session: sessionId, cwd: opts.cwd, started: new Date().toISOString() });
     }
     catch { /* attribution is a nicety; starting the session is not */ }
-    // Deliberately does NOT route. Routing on here is what made `route auto`
-    // degrade into `route on`: it stayed on while any registered session lived,
-    // which with overlapping sessions is forever, so every session after the
-    // first launched into a dirty file and lost Remote Control. Routing is now
-    // turned on per foreign-model subagent instead — see cmdRouteSubagent. This
-    // phase only ensures the router daemon is up and records liveness.
+    // Routes, and then schedules the settle that takes the env back out.
+    //
+    // Routing here once made `route auto` degrade into `route on` — the env
+    // stayed for as long as any session lived, so every later session read it at
+    // startup and lost Remote Control. The answer then was to route at
+    // SubagentStart instead, which routes nothing: the subagent that FIRES that
+    // hook has already resolved its endpoint, so it reaches api.anthropic.com
+    // and dies with `model_not_found`, which reads as a broken agent.
+    //
+    // Writing it HERE happens before any subagent exists, so nothing races it;
+    // taking it out again a moment later is what keeps the next session's launch
+    // clean. Both halves were measured on 2026-09-14 (Claude Code 2.1.270) — see
+    // `cmdRouteSettle` and the tests.
+    (deps.settle ?? ((id) => spawnSettle(id, opts, scope)))(sessionId);
     const after = readSessions(registry);
-    return { sessions: after.length, routing: 'off' };
+    return { sessions: after.length, routing: 'on' };
+}
+/**
+ * Runs the settle in a detached child, so the hook that started this session
+ * returns immediately.
+ *
+ * The delay must not be waited out in-process: Claude Code blocks on a
+ * SessionStart hook, so every session would pay it before showing a prompt.
+ */
+function spawnSettle(sessionId, opts, scope) {
+    try {
+        // The installed CLI, resolved the same way the hook commands are, rather
+        // than `process.argv[1]`: that is whatever binary happens to be running
+        // this code — a test runner, an editor integration — and re-invoking it
+        // with sonata's arguments is not a thing to do blind. A package root with
+        // no built CLI simply schedules nothing.
+        const cli = join(opts.packageRoot, 'dist', 'cli.js');
+        if (!existsSync(cli))
+            return;
+        const args = [cli, 'route', 'session-settle', '--id', sessionId];
+        if (scope === 'global')
+            args.push('--global');
+        spawn(process.execPath, args, { cwd: opts.cwd, detached: true, stdio: 'ignore' }).unref();
+    }
+    catch {
+        // A settle that cannot be scheduled costs the NEXT session's Remote
+        // Control, never this session's routing. Failing the hook over it would
+        // trade a small loss for the whole feature.
+    }
 }
 /**
  * Removes the routing env, leaving both registries alone.