@nac3/forge-cli 0.2.0-alpha.9 → 1.0.0

package/dist/core/learnings_client.js

@@ -0,0 +1,262 @@
+/**
+ * F103 HITO 6.2 + 6.3 -- CLI client for the server-side lessons +
+ * doctrines worker.
+ *
+ * Three responsibilities:
+ *   1. Fetch /v1/lessons/active + /v1/doctrines/active from the
+ *      worker on demand.
+ *   2. Cache the responses locally for 5 min to avoid hammering
+ *      the worker on every system-prompt rebuild.
+ *   3. Fall back gracefully:
+ *      a. Worker unreachable -> stale cache (if any) -> embedded
+ *         fallback in dist/docs/doctrine/*.md.
+ *      b. Lessons -- no embedded fallback exists; if both worker
+ *         and cache fail, return empty array (CLI keeps working,
+ *         just without server-side lessons).
+ *
+ * Why local cache aggressive: the system prompt is rebuilt on
+ * every chat turn. Without cache, every turn would HTTP to the
+ * worker, adding ~100-300ms of latency. 5-min cache amortises.
+ *
+ * Why offline fallback: Forge must keep working when the worker
+ * is down. Doctrines have an embedded fallback in dist/. Lessons
+ * are an additive layer; missing them degrades gracefully.
+ *
+ * Cache shape:
+ *   ~/.yujin-forge/cache/lessons.json
+ *   ~/.yujin-forge/cache/doctrines.json
+ *
+ * Each file has { fetched_at: <unix ms>, payload: <server body> }.
+ *
+ * ASCII-only.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { homedir } from 'node:os';
+import { VERSION } from '../version.js';
+const CACHE_DIR_NAME = '.yujin-forge';
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const STALE_TTL_MS = 24 * 60 * 60 * 1000; // 24h -- after this, stale cache is ignored even on worker failure
+function cacheDir() {
+    return path.join(homedir(), CACHE_DIR_NAME, 'cache');
+}
+function workerBaseUrl() {
+    return process.env.YUJIN_WORKER_URL
+        || process.env.YF_WORKER_URL
+        || 'https://yujin-hito4.yujinapp.workers.dev';
+}
+async function ensureCacheDir() {
+    await fs.mkdir(cacheDir(), { recursive: true });
+}
+async function readCache(file) {
+    try {
+        const raw = await fs.readFile(path.join(cacheDir(), file), 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+async function writeCache(file, envelope) {
+    try {
+        await ensureCacheDir();
+        await fs.writeFile(path.join(cacheDir(), file), JSON.stringify(envelope, null, 2), 'utf-8');
+    }
+    catch {
+        /* swallow -- cache is best-effort */
+    }
+}
+function isFresh(env) {
+    return Date.now() - env.fetched_at < CACHE_TTL_MS;
+}
+function isStale(env) {
+    return Date.now() - env.fetched_at < STALE_TTL_MS;
+}
+/* ===================================================================
+ * Lessons
+ * ================================================================ */
+/** Fetch the active lessons from the worker (cached 5 min locally).
+ *  Returns [] if the worker is unreachable AND no stale cache
+ *  exists -- the CLI keeps working, just without lessons. */
+export async function fetchActiveLessons(opts = {}) {
+    const cached = await readCache('lessons.json');
+    if (!opts.force && cached && isFresh(cached)) {
+        return cached.payload.lessons || [];
+    }
+    const url = workerBaseUrl() + '/v1/lessons/active';
+    try {
+        const r = await fetch(url, {
+            headers: { 'x-yf-cli-version': VERSION },
+        });
+        if (!r.ok) {
+            /* Worker reachable but error. Fall back to cache if stale-OK. */
+            if (cached && isStale(cached))
+                return cached.payload.lessons || [];
+            return [];
+        }
+        const body = await r.json();
+        if (!body.ok) {
+            if (cached && isStale(cached))
+                return cached.payload.lessons || [];
+            return [];
+        }
+        await writeCache('lessons.json', {
+            fetched_at: Date.now(), payload: { lessons: body.lessons }, worker_url: url,
+        });
+        return body.lessons || [];
+    }
+    catch {
+        /* Network failure. Fall back to stale cache if any. */
+        if (cached && isStale(cached))
+            return cached.payload.lessons || [];
+        return [];
+    }
+}
+/** Fetch a specific lesson by slug (for demoted lessons accessed
+ *  via yujin.doctrine.discover(learnings/<slug>)). No local cache --
+ *  these are infrequent + always go to the worker. */
+export async function fetchLessonBySlug(slug) {
+    const url = workerBaseUrl() + '/v1/lessons/by-slug/' + encodeURIComponent(slug);
+    try {
+        const r = await fetch(url, { headers: { 'x-yf-cli-version': VERSION } });
+        if (!r.ok)
+            return null;
+        const body = await r.json();
+        return body.ok ? body.lesson : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Report an anonymized hit. Fire-and-forget; failures swallowed.
+ *  Drives LRU eviction on the server side. */
+export async function reportLessonHit(slug) {
+    const url = workerBaseUrl() + '/v1/lessons/hit/' + encodeURIComponent(slug);
+    try {
+        await fetch(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', 'x-yf-cli-version': VERSION },
+            body: '{}',
+        });
+    }
+    catch { /* swallow -- telemetry is best-effort */ }
+}
+/* ===================================================================
+ * Doctrines
+ * ================================================================ */
+/** Fetch the list of active doctrine slugs + their versions.
+ *  Falls back to the local dist/docs/doctrine/*.md filename list
+ *  when the worker is unreachable. */
+export async function fetchActiveDoctrines() {
+    const cached = await readCache('doctrines.json');
+    if (cached && isFresh(cached)) {
+        return cached.payload.doctrines || [];
+    }
+    const url = workerBaseUrl() + '/v1/doctrines/active';
+    try {
+        const r = await fetch(url, { headers: { 'x-yf-cli-version': VERSION } });
+        if (!r.ok) {
+            if (cached && isStale(cached))
+                return cached.payload.doctrines || [];
+            return localDoctrineFallback();
+        }
+        const body = await r.json();
+        if (!body.ok) {
+            if (cached && isStale(cached))
+                return cached.payload.doctrines || [];
+            return localDoctrineFallback();
+        }
+        await writeCache('doctrines.json', {
+            fetched_at: Date.now(), payload: { doctrines: body.doctrines }, worker_url: url,
+        });
+        return body.doctrines || [];
+    }
+    catch {
+        if (cached && isStale(cached))
+            return cached.payload.doctrines || [];
+        return localDoctrineFallback();
+    }
+}
+/** Fetch the markdown body of a specific doctrine. Worker first,
+ *  filesystem fallback. */
+export async function fetchDoctrineBySlug(slug) {
+    const url = workerBaseUrl() + '/v1/doctrines/by-slug/' + encodeURIComponent(slug);
+    try {
+        const r = await fetch(url, { headers: { 'x-yf-cli-version': VERSION } });
+        if (r.ok) {
+            const body = await r.json();
+            if (body.ok && body.doctrine && typeof body.doctrine.content_md === 'string') {
+                return body.doctrine.content_md;
+            }
+        }
+    }
+    catch { /* fall through */ }
+    /* Filesystem fallback. */
+    return readLocalDoctrine(slug);
+}
+async function readLocalDoctrine(slug) {
+    /* Resolve from dist/docs/doctrine/ relative to this file. */
+    const candidates = [
+        path.resolve(path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, '$1')), '..', '..', 'docs', 'doctrine', slug + '.md'),
+        path.resolve(path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, '$1')), '..', '..', '..', 'docs', 'doctrine', slug + '.md'),
+    ];
+    for (const candidate of candidates) {
+        try {
+            return await fs.readFile(candidate, 'utf-8');
+        }
+        catch { /* try next */ }
+    }
+    return null;
+}
+async function localDoctrineFallback() {
+    /* When the worker is unreachable, return the slugs we know about
+     * from the dist filesystem. version = 0 indicates fallback. */
+    const KNOWN = ['workflow', 'yf-commands', 'gates', 'nac3-attrs', 'pizarron', 'r8-modal', 'g-doc'];
+    return KNOWN.map((slug) => ({ slug, version: 0, min_cli_version: '0.0.0' }));
+}
+/* ===================================================================
+ * HITO 6.3 -- prompt section builder
+ * ================================================================ */
+/** Build the GLOBAL LEARNINGS section to inject into the system
+ *  prompt. Returns empty string when:
+ *   - There are no active lessons.
+ *   - The token budget is exhausted before any lesson fits.
+ *
+ *  Token estimation uses a 4-chars-per-token heuristic; close
+ *  enough for the budget cap. */
+export async function buildGlobalLearningsSection(opts = {}) {
+    const maxTokens = opts.maxTokens ?? 2000;
+    const lessons = await fetchActiveLessons();
+    if (lessons.length === 0)
+        return '';
+    const parts = [];
+    parts.push('=================================================================');
+    parts.push('GLOBAL LEARNINGS (server-managed, promoted by admin)');
+    parts.push('=================================================================');
+    parts.push('');
+    parts.push('These rules are active for every Forge user. They came from');
+    parts.push('the brain matrix scenarios that validated each pattern.');
+    parts.push('');
+    let usedChars = parts.join('\n').length;
+    const maxChars = maxTokens * 4;
+    let injected = 0;
+    for (const lesson of lessons) {
+        const block = '* ' + lesson.slug + ': ' + lesson.rule_text + '\n';
+        if (usedChars + block.length > maxChars)
+            break;
+        parts.push(block);
+        usedChars += block.length;
+        injected++;
+    }
+    if (injected === 0)
+        return '';
+    parts.push('');
+    return parts.join('\n');
+}
+/* ===================================================================
+ * Internal exports for tests
+ * ================================================================ */
+export const _internal = {
+    cacheDir, workerBaseUrl, readCache, writeCache, isFresh, isStale,
+};
+//# sourceMappingURL=learnings_client.js.map

package/dist/core/learnings_client.js.map

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

package/dist/core/limits_config.d.ts

@@ -0,0 +1,81 @@
+export type ToolRoundsFamily = 'default' | 'reader_family' | 'search_family' | 'writer_family';
+export interface MaxToolRoundsConfig {
+    default: number;
+    reader_family: number;
+    search_family: number;
+    writer_family: number;
+    /** alpha.59e -- ceiling used when Danger Zone auto-approve
+     *  is ON. Lets the LLM run long chains of verbs without
+     *  intervention when the user has explicitly opted in to
+     *  velocity-over-safety mode. */
+    autonomous: number;
+}
+export interface RequestTimeoutsConfig {
+    managed_proxy: number;
+    byok_anthropic: number;
+    byok_openai: number;
+    byok_gemini: number;
+}
+export interface ShellLimitsConfig {
+    /** Default timeout per shell invocation. */
+    timeout_ms_default: number;
+    /** Hard ceiling -- caller cannot override above this. */
+    timeout_ms_max: number;
+    /** Combined stdout + stderr max bytes; output beyond is
+     *  truncated with a marker. */
+    max_output_bytes: number;
+    /** When true, ANY cwd outside the project root forces an
+     *  approval prompt -- even for safe-bucket commands. Pablo's
+     *  Q2: escape-with-approval. */
+    cwd_boundary_strict: boolean;
+}
+export interface DangerZoneConfig {
+    /** When true, EVERY approval prompt is auto-approved + logged
+     *  with approval_mode='danger_zone_bypass'. Trade-off:
+     *  velocity over safety. */
+    auto_approve_all: boolean;
+}
+export interface LimitsConfig {
+    version: 1;
+    max_tool_rounds: MaxToolRoundsConfig;
+    request_timeout_ms: RequestTimeoutsConfig;
+    classifier_timeout_ms: number;
+    managed_max_tokens_per_turn: number;
+    /** Plan-mode turn cap: max wall-clock for one `claude -p` subprocess
+     *  reasoning turn before Forge kills it (504). Default 30 min; raise it
+     *  for long autonomous turns. NOT the per-request HTTP timeout (that is
+     *  request_timeout_ms). */
+    claude_cli_timeout_ms: number;
+    shell: ShellLimitsConfig;
+    danger_zone: DangerZoneConfig;
+}
+export declare function defaultLimitsConfig(): LimitsConfig;
+/** Read the active config. Cached for ~3 seconds to avoid
+ *  hammering the FS on every router call. Use forceRefresh=true
+ *  in tests / CLI after a setValue. */
+export declare function readLimitsConfig(forceRefresh?: boolean): Promise<LimitsConfig>;
+export declare function writeLimitsConfig(cfg: LimitsConfig): Promise<void>;
+export declare function resetLimitsConfig(): Promise<LimitsConfig>;
+/** Reset the in-memory cache. Tests use this between specs. */
+export declare function _resetLimitsCache(): void;
+export declare function classifyVerbFamily(verbId: string): ToolRoundsFamily;
+/**
+ * Pick the max_tool_rounds limit for a turn based on the verb
+ * family the LLM is using. The family is derived from the
+ * FIRST nac3 verb the LLM emits in this turn -- once decided,
+ * the cap stays for the rest of the turn (no mid-turn shifts).
+ *
+ * Callers track the first verb invoked + pass it here.
+ */
+export declare function getMaxToolRoundsForFamily(cfg: MaxToolRoundsConfig, family: ToolRoundsFamily): number;
+/** All settable field paths in dotted notation, used by `yf
+ *  limits set <field> <value>`. */
+export declare const LIMITS_FIELD_PATHS: readonly string[];
+export declare function isLimitsFieldPath(p: string): boolean;
+export declare const LIMITS_BOOLEAN_FIELD_PATHS: readonly string[];
+export declare function isLimitsBooleanFieldPath(p: string): boolean;
+export declare function setLimitsBooleanField(field: string, value: boolean): Promise<LimitsConfig>;
+/** Apply a single setValue. Returns the updated config. Throws
+ *  on invalid path or non-numeric value. */
+export declare function setLimitsField(field: string, value: number): Promise<LimitsConfig>;
+//# sourceMappingURL=limits_config.d.ts.map

package/dist/core/limits_config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits_config.d.ts","sourceRoot":"","sources":["../../src/core/limits_config.ts"],"names":[],"mappings":"AAqDA,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,eAAe,GAAG,eAAe,GAAG,eAAe,CAAC;AAE/F,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB;;;qCAGiC;IACjC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAGD,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,kBAAkB,EAAE,MAAM,CAAC;IAC3B,yDAAyD;IACzD,cAAc,EAAE,MAAM,CAAC;IACvB;mCAC+B;IAC/B,gBAAgB,EAAE,MAAM,CAAC;IACzB;;oCAEgC;IAChC,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAGD,MAAM,WAAW,gBAAgB;IAC/B;;gCAE4B;IAC5B,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,CAAC,CAAC;IACX,eAAe,EAAE,mBAAmB,CAAC;IACrC,kBAAkB,EAAE,qBAAqB,CAAC;IAC1C,qBAAqB,EAAE,MAAM,CAAC;IAC9B,2BAA2B,EAAE,MAAM,CAAC;IACpC;;;+BAG2B;IAC3B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,KAAK,EAAE,iBAAiB,CAAC;IACzB,WAAW,EAAE,gBAAgB,CAAC;CAC/B;AAED,wBAAgB,mBAAmB,IAAI,YAAY,CA6BlD;AAiED;;uCAEuC;AACvC,wBAAsB,gBAAgB,CAAC,YAAY,UAAQ,GAAG,OAAO,CAAC,YAAY,CAAC,CAalF;AAED,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CASxE;AAED,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,YAAY,CAAC,CAI/D;AAED,+DAA+D;AAC/D,wBAAgB,iBAAiB,IAAI,IAAI,CAGxC;AAqBD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAMnE;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,mBAAmB,EACxB,MAAM,EAAE,gBAAgB,GACvB,MAAM,CAOR;AAID;mCACmC;AACnC,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAgB/C,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAEpD;AAID,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EAGvD,CAAC;AAEF,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC,CAgBhG;AAED;4CAC4C;AAC5C,wBAAsB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAkBxF"}

package/dist/core/limits_config.js

@@ -0,0 +1,302 @@
+/**
+ * limits_config.ts -- runtime limits Pablo (or any operator) can
+ * tune without rebuilding the CLI (alpha.59c).
+ *
+ * Pablo rule: NADA hardcode. Every limit a turn enforces lives
+ * here and the panel + CLI expose it for editing. Defaults are
+ * conservative; the user widens them when they hit a wall (e.g.
+ * reader-heavy turn exhausts the default 5 rounds -> bump the
+ * reader_family cap).
+ *
+ * Storage:
+ *   $YF_CONFIG_DIR/limits.json (or ~/.yujin-forge/limits.json)
+ *
+ * Shape:
+ *   {
+ *     "version": 1,
+ *     "max_tool_rounds": {
+ *       "default":          5,
+ *       "reader_family":   25,
+ *       "search_family":   15,
+ *       "writer_family":   10
+ *     },
+ *     "request_timeout_ms": {
+ *       "managed_proxy":   60000,
+ *       "byok_anthropic":  60000,
+ *       "byok_openai":     60000,
+ *       "byok_gemini":     30000
+ *     },
+ *     "classifier_timeout_ms": 2500,
+ *     "managed_max_tokens_per_turn": 8192
+ *   }
+ *
+ * Verb-family detection: each turn the LLM may invoke verbs
+ * from different families. We look at the FIRST verb the LLM
+ * tries to call and the family it belongs to to pick the cap.
+ * If subsequent verbs are from different families, the cap
+ * stays at whatever the first family suggested -- this avoids
+ * mid-turn cap shifts that would surprise the model.
+ *
+ * Families:
+ *   reader_family : yujin.reader.* + yujin.fs.read-*
+ *                   + yujin.docs.read-*
+ *   search_family : yujin.reader.search + future search verbs
+ *   writer_family : yujin.fs.write-* + yujin.fs.append-*
+ *   default       : everything else (cap = 5 -- short tool
+ *                   loops, chats, single-action verbs)
+ *
+ * ASCII-only.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+export function defaultLimitsConfig() {
+    return {
+        version: 1,
+        max_tool_rounds: {
+            default: 5,
+            reader_family: 25,
+            search_family: 15,
+            writer_family: 10,
+            autonomous: 50,
+        },
+        request_timeout_ms: {
+            managed_proxy: 60000,
+            byok_anthropic: 60000,
+            byok_openai: 60000,
+            byok_gemini: 30000,
+        },
+        classifier_timeout_ms: 2500,
+        managed_max_tokens_per_turn: 8192,
+        claude_cli_timeout_ms: 30 * 60 * 1000,
+        shell: {
+            timeout_ms_default: 30000,
+            timeout_ms_max: 300000,
+            max_output_bytes: 1048576,
+            cwd_boundary_strict: true,
+        },
+        danger_zone: {
+            auto_approve_all: false,
+        },
+    };
+}
+function limitsConfigPath() {
+    const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+    const base = process.env.YF_CONFIG_DIR || path.join(home, '.yujin-forge');
+    return path.join(base, 'limits.json');
+}
+function clamp(v, min, max, fallback) {
+    if (typeof v !== 'number' || !Number.isFinite(v))
+        return fallback;
+    if (v < min)
+        return min;
+    if (v > max)
+        return max;
+    return Math.floor(v);
+}
+/** Apply per-field validation + clamping when reading from
+ *  disk. Out-of-range values silently snap to safe bounds so a
+ *  fat-fingered edit doesn't brick the CLI. */
+function normaliseLimitsConfig(raw) {
+    const def = defaultLimitsConfig();
+    if (!raw || typeof raw !== 'object')
+        return def;
+    const j = raw;
+    const rounds = j.max_tool_rounds || {};
+    const timeouts = j.request_timeout_ms || {};
+    const shell = j.shell || {};
+    const danger = j.danger_zone || {};
+    return {
+        version: 1,
+        max_tool_rounds: {
+            default: clamp(rounds.default, 1, 100, def.max_tool_rounds.default),
+            reader_family: clamp(rounds.reader_family, 1, 100, def.max_tool_rounds.reader_family),
+            search_family: clamp(rounds.search_family, 1, 100, def.max_tool_rounds.search_family),
+            writer_family: clamp(rounds.writer_family, 1, 100, def.max_tool_rounds.writer_family),
+            autonomous: clamp(rounds.autonomous, 1, 200, def.max_tool_rounds.autonomous),
+        },
+        request_timeout_ms: {
+            managed_proxy: clamp(timeouts.managed_proxy, 1000, 300000, def.request_timeout_ms.managed_proxy),
+            byok_anthropic: clamp(timeouts.byok_anthropic, 1000, 300000, def.request_timeout_ms.byok_anthropic),
+            byok_openai: clamp(timeouts.byok_openai, 1000, 300000, def.request_timeout_ms.byok_openai),
+            byok_gemini: clamp(timeouts.byok_gemini, 1000, 300000, def.request_timeout_ms.byok_gemini),
+        },
+        classifier_timeout_ms: clamp(j.classifier_timeout_ms, 250, 30000, def.classifier_timeout_ms),
+        managed_max_tokens_per_turn: clamp(j.managed_max_tokens_per_turn, 64, 64000, def.managed_max_tokens_per_turn),
+        /* 1 min .. 4 hours. Lets long autonomous turns run; the floor keeps
+         * a fat-fingered 0 from disabling the safety net. */
+        claude_cli_timeout_ms: clamp(j.claude_cli_timeout_ms, 60000, 4 * 60 * 60 * 1000, def.claude_cli_timeout_ms),
+        shell: {
+            timeout_ms_default: clamp(shell.timeout_ms_default, 1000, 600000, def.shell.timeout_ms_default),
+            timeout_ms_max: clamp(shell.timeout_ms_max, 1000, 600000, def.shell.timeout_ms_max),
+            max_output_bytes: clamp(shell.max_output_bytes, 1024, 16 * 1024 * 1024, def.shell.max_output_bytes),
+            cwd_boundary_strict: typeof shell.cwd_boundary_strict === 'boolean'
+                ? shell.cwd_boundary_strict
+                : def.shell.cwd_boundary_strict,
+        },
+        danger_zone: {
+            auto_approve_all: typeof danger.auto_approve_all === 'boolean'
+                ? danger.auto_approve_all
+                : def.danger_zone.auto_approve_all,
+        },
+    };
+}
+let _cache = null;
+let _cacheMTime = 0;
+/** Read the active config. Cached for ~3 seconds to avoid
+ *  hammering the FS on every router call. Use forceRefresh=true
+ *  in tests / CLI after a setValue. */
+export async function readLimitsConfig(forceRefresh = false) {
+    if (!forceRefresh && _cache && Date.now() - _cacheMTime < 3000) {
+        return _cache;
+    }
+    try {
+        const raw = await fs.readFile(limitsConfigPath(), 'utf-8');
+        const j = JSON.parse(raw);
+        _cache = normaliseLimitsConfig(j);
+    }
+    catch {
+        _cache = defaultLimitsConfig();
+    }
+    _cacheMTime = Date.now();
+    return _cache;
+}
+export async function writeLimitsConfig(cfg) {
+    const p = limitsConfigPath();
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    const tmp = p + '.tmp';
+    const normalised = normaliseLimitsConfig(cfg);
+    await fs.writeFile(tmp, JSON.stringify(normalised, null, 2), 'utf-8');
+    await fs.rename(tmp, p);
+    _cache = normalised;
+    _cacheMTime = Date.now();
+}
+export async function resetLimitsConfig() {
+    const def = defaultLimitsConfig();
+    await writeLimitsConfig(def);
+    return def;
+}
+/** Reset the in-memory cache. Tests use this between specs. */
+export function _resetLimitsCache() {
+    _cache = null;
+    _cacheMTime = 0;
+}
+/* ----- Verb family detection ------------------------------- */
+const READER_VERB_PATTERNS = [
+    /^yujin\.reader\.(open|next-block|read-section|recap|bookmark-set|bookmark-jump|list-docs)$/,
+    /^yujin\.fs\.read-/,
+    /^yujin\.docs\.read-/,
+];
+const SEARCH_VERB_PATTERNS = [
+    /^yujin\.reader\.search$/,
+    /^yujin\.search\./,
+    /^yujin\.web\.search/,
+];
+const WRITER_VERB_PATTERNS = [
+    /^yujin\.fs\.write-/,
+    /^yujin\.fs\.append-/,
+];
+export function classifyVerbFamily(verbId) {
+    if (!verbId)
+        return 'default';
+    for (const p of READER_VERB_PATTERNS)
+        if (p.test(verbId))
+            return 'reader_family';
+    for (const p of SEARCH_VERB_PATTERNS)
+        if (p.test(verbId))
+            return 'search_family';
+    for (const p of WRITER_VERB_PATTERNS)
+        if (p.test(verbId))
+            return 'writer_family';
+    return 'default';
+}
+/**
+ * Pick the max_tool_rounds limit for a turn based on the verb
+ * family the LLM is using. The family is derived from the
+ * FIRST nac3 verb the LLM emits in this turn -- once decided,
+ * the cap stays for the rest of the turn (no mid-turn shifts).
+ *
+ * Callers track the first verb invoked + pass it here.
+ */
+export function getMaxToolRoundsForFamily(cfg, family) {
+    switch (family) {
+        case 'reader_family': return cfg.reader_family;
+        case 'search_family': return cfg.search_family;
+        case 'writer_family': return cfg.writer_family;
+        case 'default': return cfg.default;
+    }
+}
+/* ----- Field-path API for CLI setter ----------------------- */
+/** All settable field paths in dotted notation, used by `yf
+ *  limits set <field> <value>`. */
+export const LIMITS_FIELD_PATHS = [
+    'max_tool_rounds.default',
+    'max_tool_rounds.reader_family',
+    'max_tool_rounds.search_family',
+    'max_tool_rounds.writer_family',
+    'max_tool_rounds.autonomous',
+    'request_timeout_ms.managed_proxy',
+    'request_timeout_ms.byok_anthropic',
+    'request_timeout_ms.byok_openai',
+    'request_timeout_ms.byok_gemini',
+    'classifier_timeout_ms',
+    'managed_max_tokens_per_turn',
+    'claude_cli_timeout_ms',
+    'shell.timeout_ms_default',
+    'shell.timeout_ms_max',
+    'shell.max_output_bytes',
+];
+export function isLimitsFieldPath(p) {
+    return LIMITS_FIELD_PATHS.includes(p);
+}
+/* alpha.59d -- boolean settings live apart so setLimitsField
+ *  can stay numeric-only. */
+export const LIMITS_BOOLEAN_FIELD_PATHS = [
+    'shell.cwd_boundary_strict',
+    'danger_zone.auto_approve_all',
+];
+export function isLimitsBooleanFieldPath(p) {
+    return LIMITS_BOOLEAN_FIELD_PATHS.includes(p);
+}
+export async function setLimitsBooleanField(field, value) {
+    if (!isLimitsBooleanFieldPath(field)) {
+        throw new Error('limits: unknown boolean field path "' + field + '"');
+    }
+    if (typeof value !== 'boolean') {
+        throw new Error('limits: boolean field value must be a boolean');
+    }
+    const cur = await readLimitsConfig(true);
+    const parts = field.split('.');
+    if (parts.length === 2 && parts[0] && parts[1]) {
+        const root = cur[parts[0]];
+        if (!root)
+            throw new Error('limits: parent field missing: ' + parts[0]);
+        root[parts[1]] = value;
+    }
+    await writeLimitsConfig(cur);
+    return cur;
+}
+/** Apply a single setValue. Returns the updated config. Throws
+ *  on invalid path or non-numeric value. */
+export async function setLimitsField(field, value) {
+    if (!isLimitsFieldPath(field)) {
+        throw new Error('limits: unknown field path "' + field + '". Run `yf limits list-fields` to see options.');
+    }
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new Error('limits: value must be a finite number, got ' + String(value));
+    }
+    const cur = await readLimitsConfig(true);
+    const parts = field.split('.');
+    if (parts.length === 1 && parts[0]) {
+        cur[parts[0]] = value;
+    }
+    else if (parts.length === 2 && parts[0] && parts[1]) {
+        const root = cur[parts[0]];
+        if (!root)
+            throw new Error('limits: parent field missing: ' + parts[0]);
+        root[parts[1]] = value;
+    }
+    await writeLimitsConfig(cur);
+    return cur;
+}
+//# sourceMappingURL=limits_config.js.map