@nac3/forge-cli 0.2.0-alpha.5 → 0.2.0-alpha.59z.118

package/README.md

@@ -7,7 +7,22 @@ loop: read design specs by voice, generate code scaffolds from
 those specs, decorate vanilla HTML into NAC-3, drive existing apps
 via voice + chat.
 
-> Status: **v0.2.0-alpha (HITO 0 + HITO 1 closed)**, 2026-05-23.
+> Status: **v0.2.0-alpha.59z.92** (2026-06-04). **100% manifest
+> verb coverage**: every one of the 72 declared NAC-3 verbs has
+> at least one fake-scripted scenario asserting it gets invoked
+> (or refuses to) in the right intent. Brain matrix QA harness
+> at 168 scenarios (+68 since z.61); 22 new verbs in the arc
+> (8 misc + git.status/branch-list + office.excel.append-sheet
+> + 12 others); 8 helper CLIs under `yf qa` (run, scenarios
+> list/show/validate/stats, verbs coverage/sample,
+> brain-matrix-compare); 5 ops docs (SECURITY, CONTRIBUTING,
+> TESTING_GUIDE, DEPLOYMENT, CI_PIPELINE); 2 new doctrines
+> (verb-composition, explain-results); 2 new invariant kinds
+> (min_text_length, verb_invoked_in_order) + structural
+> fixture validator + lefthook pre-commit gate. F101 MCP
+> bridge backend complete (slice 3 panel UI pending); F106
+> office.* + F107 a11y.* verbs shipped; HITO 5 agent
+> orchestrator design draft awaiting Pablo clarification.
 >
 > **HITO 0 -- credentials vault.** AES-256-GCM at-rest encryption
 > with machine fingerprint binding, atomic writes (0o600), one-shot

package/dist/a11y/helpers.d.ts

@@ -0,0 +1,88 @@
+/**
+ * F107 accessibility helpers -- screen-reader + voice-first hooks
+ * for adopter apps generated by Forge.
+ *
+ * These are pure helpers (no DOM dependency at this layer) that the
+ * panel + mobile adapters consume. They translate semantic intents
+ * ("announce this", "focus that element", "describe this element")
+ * into payloads the rendering layer can route to:
+ *   - ARIA live regions for screen readers
+ *   - Voice TTS for the Forge voice loop
+ *   - Mobile screen-reader bridges (VoiceOver / TalkBack)
+ *
+ * The verbs operate on NAC-3 element slugs (declared via
+ * data-nac-* attrs in the adopter app) so the brain never has to
+ * know about raw DOM identifiers.
+ *
+ * ASCII-only.
+ */
+export type Politeness = 'polite' | 'assertive';
+export interface AnnounceRequest {
+    /** Text to announce. */
+    text: string;
+    /** ARIA live-region politeness. Default 'polite'. */
+    politeness?: Politeness;
+    /** When set, also speak via TTS (voice loop). Default false. */
+    speak?: boolean;
+    /** Locale hint (BCP47). Default inherits the user's voice config. */
+    locale?: string;
+}
+export interface AnnouncePayload {
+    type: 'aria-live';
+    text: string;
+    politeness: Politeness;
+    /** Set when the runtime should also speak the text. */
+    speak: boolean;
+    locale: string | null;
+}
+export interface FocusRequest {
+    /** NAC-3 element slug (the value of data-nac-slug). */
+    slug: string;
+    /** When set, scrolls the element into view. Default true. */
+    scroll?: boolean;
+    /** Announce the focus change via screen reader. Default true. */
+    announce?: boolean;
+}
+export interface FocusPayload {
+    type: 'focus';
+    slug: string;
+    scroll: boolean;
+    announce: boolean;
+}
+export interface LabelRequest {
+    /** NAC-3 element slug. */
+    slug: string;
+    /** Human-readable description (will become aria-label /
+     *  aria-describedby depending on field). */
+    description: string;
+    /** Optional shortcut hint (e.g. 'Ctrl+S'). */
+    shortcut?: string;
+    /** Optional role hint (e.g. 'button', 'textbox'). */
+    role?: string;
+}
+export interface LabelPayload {
+    type: 'label';
+    slug: string;
+    /** Sanitised description -- max 500 chars, single line. */
+    description: string;
+    shortcut: string | null;
+    role: string | null;
+}
+export declare function buildAnnouncePayload(req: AnnounceRequest): AnnouncePayload | {
+    ok: false;
+    error: string;
+};
+export declare function buildFocusPayload(req: FocusRequest): FocusPayload | {
+    ok: false;
+    error: string;
+};
+export declare function buildLabelPayload(req: LabelRequest): LabelPayload | {
+    ok: false;
+    error: string;
+};
+/** NAC-3 data-nac-* attr -> ARIA attribute mapping. Used by the
+ *  panel renderer + mobile adapter to project the semantic layer
+ *  onto the native a11y tree. */
+export declare const NAC3_TO_ARIA: Record<string, string>;
+export declare function mapNac3ToAria(attrs: Record<string, string>): Record<string, string>;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/a11y/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/a11y/helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEhD,MAAM,WAAW,eAAe;IAC9B,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,gEAAgE;IAChE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,UAAU,CAAC;IACvB,uDAAuD;IACvD,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb;gDAC4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAOD,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,eAAe,GAAG,eAAe,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAiBzG;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,GAAG,YAAY,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAchG;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,GAAG,YAAY,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAmBhG;AAED;;iCAEiC;AACjC,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAU/C,CAAC;AAEF,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOnF"}

package/dist/a11y/helpers.js

@@ -0,0 +1,109 @@
+/**
+ * F107 accessibility helpers -- screen-reader + voice-first hooks
+ * for adopter apps generated by Forge.
+ *
+ * These are pure helpers (no DOM dependency at this layer) that the
+ * panel + mobile adapters consume. They translate semantic intents
+ * ("announce this", "focus that element", "describe this element")
+ * into payloads the rendering layer can route to:
+ *   - ARIA live regions for screen readers
+ *   - Voice TTS for the Forge voice loop
+ *   - Mobile screen-reader bridges (VoiceOver / TalkBack)
+ *
+ * The verbs operate on NAC-3 element slugs (declared via
+ * data-nac-* attrs in the adopter app) so the brain never has to
+ * know about raw DOM identifiers.
+ *
+ * ASCII-only.
+ */
+const MAX_TEXT = 1000;
+const MAX_DESCRIPTION = 500;
+const MAX_SLUG = 120;
+const SLUG_RE = /^[a-z0-9][a-z0-9._-]*$/i;
+export function buildAnnouncePayload(req) {
+    if (typeof req.text !== 'string') {
+        return { ok: false, error: 'text must be a string' };
+    }
+    const t = req.text.trim();
+    if (!t)
+        return { ok: false, error: 'text is empty' };
+    if (t.length > MAX_TEXT) {
+        return { ok: false, error: 'text exceeds ' + MAX_TEXT + ' chars' };
+    }
+    const politeness = req.politeness === 'assertive' ? 'assertive' : 'polite';
+    return {
+        type: 'aria-live',
+        text: t,
+        politeness,
+        speak: req.speak === true,
+        locale: typeof req.locale === 'string' && req.locale ? req.locale : null,
+    };
+}
+export function buildFocusPayload(req) {
+    if (typeof req.slug !== 'string') {
+        return { ok: false, error: 'slug must be a string' };
+    }
+    const s = req.slug.trim();
+    if (!s)
+        return { ok: false, error: 'slug is empty' };
+    if (s.length > MAX_SLUG)
+        return { ok: false, error: 'slug too long' };
+    if (!SLUG_RE.test(s))
+        return { ok: false, error: 'slug must match [a-z0-9._-]' };
+    return {
+        type: 'focus',
+        slug: s,
+        scroll: req.scroll !== false,
+        announce: req.announce !== false,
+    };
+}
+export function buildLabelPayload(req) {
+    if (typeof req.slug !== 'string')
+        return { ok: false, error: 'slug must be a string' };
+    const s = req.slug.trim();
+    if (!s)
+        return { ok: false, error: 'slug is empty' };
+    if (s.length > MAX_SLUG)
+        return { ok: false, error: 'slug too long' };
+    if (!SLUG_RE.test(s))
+        return { ok: false, error: 'slug must match [a-z0-9._-]' };
+    if (typeof req.description !== 'string')
+        return { ok: false, error: 'description must be a string' };
+    const d = req.description.replace(/\s+/g, ' ').trim();
+    if (!d)
+        return { ok: false, error: 'description is empty' };
+    if (d.length > MAX_DESCRIPTION) {
+        return { ok: false, error: 'description exceeds ' + MAX_DESCRIPTION + ' chars' };
+    }
+    return {
+        type: 'label',
+        slug: s,
+        description: d,
+        shortcut: typeof req.shortcut === 'string' && req.shortcut ? req.shortcut : null,
+        role: typeof req.role === 'string' && req.role ? req.role : null,
+    };
+}
+/** NAC-3 data-nac-* attr -> ARIA attribute mapping. Used by the
+ *  panel renderer + mobile adapter to project the semantic layer
+ *  onto the native a11y tree. */
+export const NAC3_TO_ARIA = {
+    'data-nac-slug': 'data-yujin-slug',
+    'data-nac-role': 'role',
+    'data-nac-label': 'aria-label',
+    'data-nac-desc': 'aria-describedby',
+    'data-nac-busy': 'aria-busy',
+    'data-nac-pressed': 'aria-pressed',
+    'data-nac-checked': 'aria-checked',
+    'data-nac-hidden': 'aria-hidden',
+    'data-nac-live': 'aria-live',
+};
+export function mapNac3ToAria(attrs) {
+    const out = {};
+    for (const [k, v] of Object.entries(attrs)) {
+        const target = NAC3_TO_ARIA[k];
+        if (target)
+            out[target] = v;
+    }
+    return out;
+}
+//# sourceMappingURL=helpers.js.map

package/dist/a11y/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/a11y/helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AA6DH,MAAM,QAAQ,GAAY,IAAI,CAAC;AAC/B,MAAM,eAAe,GAAK,GAAG,CAAC;AAC9B,MAAM,QAAQ,GAAY,GAAG,CAAC;AAC9B,MAAM,OAAO,GAAa,yBAAyB,CAAC;AAEpD,MAAM,UAAU,oBAAoB,CAAC,GAAoB;IACvD,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACjC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,uBAAuB,EAAE,CAAC;IACvD,CAAC;IACD,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IAC1B,IAAI,CAAC,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC;IACrD,IAAI,CAAC,CAAC,MAAM,GAAG,QAAQ,EAAE,CAAC;QACxB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,eAAe,GAAG,QAAQ,GAAG,QAAQ,EAAE,CAAC;IACrE,CAAC;IACD,MAAM,UAAU,GAAe,GAAG,CAAC,UAAU,KAAK,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC;IACvF,OAAO;QACL,IAAI,EAAE,WAAW;QACjB,IAAI,EAAE,CAAC;QACP,UAAU;QACV,KAAK,EAAE,GAAG,CAAC,KAAK,KAAK,IAAI;QACzB,MAAM,EAAE,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI;KACzE,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,GAAiB;IACjD,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACjC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,uBAAuB,EAAE,CAAC;IACvD,CAAC;IACD,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IAC1B,IAAI,CAAC,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC;IACrD,IAAI,CAAC,CAAC,MAAM,GAAG,QAAQ;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC;IACtE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,6BAA6B,EAAE,CAAC;IACjF,OAAO;QACL,IAAI,EAAE,OAAO;QACb,IAAI,EAAE,CAAC;QACP,MAAM,EAAI,GAAG,CAAC,MAAM,KAAO,KAAK;QAChC,QAAQ,EAAE,GAAG,CAAC,QAAQ,KAAK,KAAK;KACjC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,GAAiB;IACjD,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,uBAAuB,EAAE,CAAC;IACvF,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IAC1B,IAAI,CAAC,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC;IACrD,IAAI,CAAC,CAAC,MAAM,GAAG,QAAQ;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC;IACtE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,6BAA6B,EAAE,CAAC;IACjF,IAAI,OAAO,GAAG,CAAC,WAAW,KAAK,QAAQ;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,8BAA8B,EAAE,CAAC;IACrG,MAAM,CAAC,GAAG,GAAG,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACtD,IAAI,CAAC,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,sBAAsB,EAAE,CAAC;IAC5D,IAAI,CAAC,CAAC,MAAM,GAAG,eAAe,EAAE,CAAC;QAC/B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,sBAAsB,GAAG,eAAe,GAAG,QAAQ,EAAE,CAAC;IACnF,CAAC;IACD,OAAO;QACL,IAAI,EAAS,OAAO;QACpB,IAAI,EAAS,CAAC;QACd,WAAW,EAAE,CAAC;QACd,QAAQ,EAAK,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI;QACnF,IAAI,EAAS,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI;KACxE,CAAC;AACJ,CAAC;AAED;;iCAEiC;AACjC,MAAM,CAAC,MAAM,YAAY,GAA2B;IAClD,eAAe,EAAK,iBAAiB;IACrC,eAAe,EAAK,MAAM;IAC1B,gBAAgB,EAAI,YAAY;IAChC,eAAe,EAAK,kBAAkB;IACtC,eAAe,EAAK,WAAW;IAC/B,kBAAkB,EAAE,cAAc;IAClC,kBAAkB,EAAE,cAAc;IAClC,iBAAiB,EAAG,aAAa;IACjC,eAAe,EAAK,WAAW;CAChC,CAAC;AAEF,MAAM,UAAU,aAAa,CAAC,KAA6B;IACzD,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3C,MAAM,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;QAC/B,IAAI,MAAM;YAAE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/agents/config_resolver.d.ts

@@ -0,0 +1,16 @@
+import { type AgentConfigKey } from './config_schema.js';
+export interface ResolveOptions {
+    /** Override the user config path (test isolation). */
+    userConfigPath?: string;
+    /** Disable env layer (test isolation). */
+    noEnv?: boolean;
+}
+export declare function invalidateAgentConfigCache(): void;
+export declare function getAgentConfig<T extends number | string | boolean>(key: AgentConfigKey, opts?: ResolveOptions): Promise<T>;
+export declare function snapshotAgentConfig(opts?: ResolveOptions): Promise<Array<{
+    key: AgentConfigKey;
+    value: unknown;
+    source: 'env' | 'user' | 'default';
+    description: string;
+}>>;
+//# sourceMappingURL=config_resolver.d.ts.map

package/dist/agents/config_resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config_resolver.d.ts","sourceRoot":"","sources":["../../src/agents/config_resolver.ts"],"names":[],"mappings":"AAcA,OAAO,EAEL,KAAK,cAAc,EAIpB,MAAM,oBAAoB,CAAC;AAM5B,MAAM,WAAW,cAAc;IAC7B,sDAAsD;IACtD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAuCD,wBAAgB,0BAA0B,IAAI,IAAI,CAGjD;AAED,wBAAsB,cAAc,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,OAAO,EACtE,GAAG,EAAE,cAAc,EACnB,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,CAAC,CAAC,CA2BZ;AAKD,wBAAsB,mBAAmB,CACvC,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,KAAK,CAAC;IAAE,GAAG,EAAE,cAAc,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,SAAS,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAgClH"}

package/dist/agents/config_resolver.js

@@ -0,0 +1,133 @@
+/**
+ * Agent config resolver. Walks the override chain:
+ *   1. process.env[YF_AGENT_<UPPER_SNAKE>] (highest precedence, dev)
+ *   2. project-level override (left out of slice 1 -- TBD when the
+ *      project store wires in; falls back to user level for now)
+ *   3. user-level ~/.yujin-forge/agents/config.json
+ *   4. published default (config_schema.ts)
+ *
+ * Returns the validated, type-coerced value. Invalid overrides
+ * log a single warning + fall through to the next layer.
+ */
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { AGENT_CONFIG_SCHEMA, validateAgentConfigValue, getAgentConfigDefault, getAgentConfigDescriptor, } from './config_schema.js';
+let cachedUserConfig = null;
+let cachedAt = 0;
+const USER_CONFIG_TTL_MS = 5_000; /* re-read after 5s so edits show up without restart */
+function envKeyFor(key) {
+    /* `agent.bridge.tokens_per_pair_hourly` ->
+     *  `YF_AGENT_BRIDGE_TOKENS_PER_PAIR_HOURLY` */
+    return 'YF_' + key.replace(/[.\-]/g, '_').toUpperCase();
+}
+function defaultUserConfigPath() {
+    return path.join(os.homedir(), '.yujin-forge', 'agents', 'config.json');
+}
+async function loadUserConfig(p) {
+    const now = Date.now();
+    if (cachedUserConfig !== null && (now - cachedAt) < USER_CONFIG_TTL_MS) {
+        return cachedUserConfig;
+    }
+    try {
+        const raw = await fs.readFile(p, 'utf-8');
+        const obj = JSON.parse(raw);
+        if (obj && typeof obj === 'object' && !Array.isArray(obj)) {
+            cachedUserConfig = obj;
+            cachedAt = now;
+            return cachedUserConfig;
+        }
+        /* JSON parsed but is array / primitive -- treat as empty. */
+        cachedUserConfig = {};
+        cachedAt = now;
+        return cachedUserConfig;
+    }
+    catch {
+        /* File missing or unreadable -- empty override is the safe default. */
+        cachedUserConfig = {};
+        cachedAt = now;
+        return cachedUserConfig;
+    }
+}
+/* Reset the cache. Used by `yf limits set agent.<key>` after a
+ * successful write so subsequent reads see the new value. */
+export function invalidateAgentConfigCache() {
+    cachedUserConfig = null;
+    cachedAt = 0;
+}
+export async function getAgentConfig(key, opts = {}) {
+    /* Layer 1 -- env */
+    if (!opts.noEnv) {
+        const envValue = process.env[envKeyFor(key)];
+        if (envValue !== undefined) {
+            try {
+                return validateAgentConfigValue(key, envValue);
+            }
+            catch {
+                /* fall through; env override invalid */
+                console.warn('[agent-config] env override for ' + key + ' invalid, falling through');
+            }
+        }
+    }
+    /* Layer 2 -- project override (TBD in a later slice when the
+     *  project store exposes a `limits_config` row. Skipping for
+     *  slice 1.) */
+    /* Layer 3 -- user config */
+    const userConfig = await loadUserConfig(opts.userConfigPath ?? defaultUserConfigPath());
+    if (userConfig[key] !== undefined) {
+        try {
+            return validateAgentConfigValue(key, userConfig[key]);
+        }
+        catch {
+            console.warn('[agent-config] user override for ' + key + ' invalid, falling through');
+        }
+    }
+    /* Layer 4 -- published default */
+    return getAgentConfigDefault(key);
+}
+/* Snapshot every key as the resolver would currently see them.
+ * Used by `yf agent doctor` + the panel settings tab to show the
+ * effective config without surprise. */
+export async function snapshotAgentConfig(opts = {}) {
+    const userConfig = await loadUserConfig(opts.userConfigPath ?? defaultUserConfigPath());
+    const out = [];
+    for (const d of AGENT_CONFIG_SCHEMA) {
+        const envValue = opts.noEnv ? undefined : process.env[envKeyFor(d.key)];
+        let value;
+        let source;
+        if (envValue !== undefined) {
+            try {
+                value = validateAgentConfigValue(d.key, envValue);
+                source = 'env';
+            }
+            catch {
+                value = userConfig[d.key] !== undefined
+                    ? (() => { try {
+                        return validateAgentConfigValue(d.key, userConfig[d.key]);
+                    }
+                    catch {
+                        return d.default;
+                    } })()
+                    : d.default;
+                source = userConfig[d.key] !== undefined ? 'user' : 'default';
+            }
+        }
+        else if (userConfig[d.key] !== undefined) {
+            try {
+                value = validateAgentConfigValue(d.key, userConfig[d.key]);
+                source = 'user';
+            }
+            catch {
+                value = d.default;
+                source = 'default';
+            }
+        }
+        else {
+            value = d.default;
+            source = 'default';
+        }
+        out.push({ key: d.key, value, source, description: getAgentConfigDescriptor(d.key).description });
+    }
+    return out;
+}
+//# sourceMappingURL=config_resolver.js.map

package/dist/agents/config_resolver.js.map

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

package/dist/agents/config_schema.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Agent orchestrator config schema (HITO 5 slice 1).
+ *
+ * Source of truth for every threshold / cap / default that the
+ * agent runtime + bridge use. Per Pablo's locked decision:
+ * NOTHING in src/agents/* may hardcode a number. Every dial
+ * lands here, with a published default + a description that the
+ * config-file generator uses as the comment.
+ *
+ * Read order at runtime:
+ *   1. process.env override (`YF_AGENT_<UPPER_SNAKE_CASE>`)
+ *   2. project-level limits_config row (`agent.<key>` namespace)
+ *   3. user-level `~/.yujin-forge/agents/config.json`
+ *   4. published default (this file)
+ *
+ * The published default is the LAST fallback, never inlined into
+ * a handler. Handlers call `getAgentConfig(key)` which walks the
+ * chain. Invalid types log a warning + fall back to default.
+ *
+ * Changes to defaults ship as a config-file edit, not a code
+ * change in src/agents/*.ts.
+ */
+export type AgentConfigKey = 'agent.bridge.tokens_per_pair_hourly' | 'agent.bridge.round_trips_window_seconds' | 'agent.bridge.round_trips_max' | 'agent.bridge.message_ttl_seconds' | 'agent.bridge.inbox_drain_batch' | 'agent.runtime.max_consecutive_rejected_approvals' | 'agent.runtime.run_timeout_seconds' | 'agent.cron.missed_runs_warning_threshold' | 'agent.audit.retention_days' | 'agent.deletion.grace_period_days' | 'agent.web_search.provider' | 'agent.web_search.daily_query_cap';
+export type AgentConfigType = 'number' | 'string' | 'boolean';
+export interface AgentConfigDescriptor {
+    key: AgentConfigKey;
+    type: AgentConfigType;
+    default: number | string | boolean;
+    description: string;
+    /** Optional enum -- for string keys that must be one of N values. */
+    enum?: readonly string[];
+    /** Optional bounds for number keys. */
+    min?: number;
+    max?: number;
+}
+export declare const AGENT_CONFIG_SCHEMA: readonly AgentConfigDescriptor[];
+export declare function getAgentConfigDescriptor(key: AgentConfigKey): AgentConfigDescriptor;
+export declare function getAgentConfigDefault(key: AgentConfigKey): number | string | boolean;
+export declare function validateAgentConfigValue(key: AgentConfigKey, raw: unknown): number | string | boolean;
+export declare function renderDefaultConfigJson(): string;
+export declare function renderConfigDocsMarkdown(): string;
+//# sourceMappingURL=config_schema.d.ts.map

package/dist/agents/config_schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config_schema.d.ts","sourceRoot":"","sources":["../../src/agents/config_schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,MAAM,cAAc,GAEtB,qCAAqC,GACrC,yCAAyC,GACzC,8BAA8B,GAC9B,kCAAkC,GAClC,gCAAgC,GAEhC,kDAAkD,GAClD,mCAAmC,GAEnC,0CAA0C,GAE1C,4BAA4B,GAC5B,kCAAkC,GAElC,2BAA2B,GAC3B,kCAAkC,CAAC;AAEvC,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9D,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAU,cAAc,CAAC;IAC5B,IAAI,EAAS,eAAe,CAAC;IAC7B,OAAO,EAAM,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,IAAI,CAAC,EAAQ,SAAS,MAAM,EAAE,CAAC;IAC/B,uCAAuC;IACvC,GAAG,CAAC,EAAS,MAAM,CAAC;IACpB,GAAG,CAAC,EAAS,MAAM,CAAC;CACrB;AAMD,eAAO,MAAM,mBAAmB,EAAE,SAAS,qBAAqB,EAgGtD,CAAC;AAWX,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,cAAc,GAAG,qBAAqB,CAMnF;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAEpF;AAKD,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,cAAc,EACnB,GAAG,EAAE,OAAO,GACX,MAAM,GAAG,MAAM,GAAG,OAAO,CA6B3B;AAMD,wBAAgB,uBAAuB,IAAI,MAAM,CAMhD;AAKD,wBAAgB,wBAAwB,IAAI,MAAM,CAYjD"}

package/dist/agents/config_schema.js

@@ -0,0 +1,204 @@
+/**
+ * Agent orchestrator config schema (HITO 5 slice 1).
+ *
+ * Source of truth for every threshold / cap / default that the
+ * agent runtime + bridge use. Per Pablo's locked decision:
+ * NOTHING in src/agents/* may hardcode a number. Every dial
+ * lands here, with a published default + a description that the
+ * config-file generator uses as the comment.
+ *
+ * Read order at runtime:
+ *   1. process.env override (`YF_AGENT_<UPPER_SNAKE_CASE>`)
+ *   2. project-level limits_config row (`agent.<key>` namespace)
+ *   3. user-level `~/.yujin-forge/agents/config.json`
+ *   4. published default (this file)
+ *
+ * The published default is the LAST fallback, never inlined into
+ * a handler. Handlers call `getAgentConfig(key)` which walks the
+ * chain. Invalid types log a warning + fall back to default.
+ *
+ * Changes to defaults ship as a config-file edit, not a code
+ * change in src/agents/*.ts.
+ */
+/* The canonical schema. The config-file generator + the runtime
+ * validator + the `yf limits` CLI all read from this list. Order
+ * matters for the generated config file (it's the section order
+ * users see). */
+export const AGENT_CONFIG_SCHEMA = [
+    {
+        key: 'agent.bridge.tokens_per_pair_hourly',
+        type: 'number',
+        default: 100_000,
+        description: 'Token cap per (agent_a, agent_b) pair per rolling 1-hour window. When exhausted, both ends receive bridge_token_cap_reached + the pair freezes until the window resets.',
+        min: 1_000,
+        max: 10_000_000,
+    },
+    {
+        key: 'agent.bridge.round_trips_window_seconds',
+        type: 'number',
+        default: 60,
+        description: 'Sliding window in seconds for the round-trip loop detector. Round trips inside this window are counted; outside, ignored.',
+        min: 10,
+        max: 3600,
+    },
+    {
+        key: 'agent.bridge.round_trips_max',
+        type: 'number',
+        default: 10,
+        description: 'Round trips between an (a,b) pair inside the window that trigger auto-revoke. Pair is closed, status=auto_revoked, manual re-enable required.',
+        min: 2,
+        max: 1000,
+    },
+    {
+        key: 'agent.bridge.message_ttl_seconds',
+        type: 'number',
+        default: 86_400,
+        description: 'Inbox message expiry. Undelivered messages older than this are marked expired + skipped on next drain.',
+        min: 60,
+        max: 2_592_000, /* 30 days */
+    },
+    {
+        key: 'agent.bridge.inbox_drain_batch',
+        type: 'number',
+        default: 20,
+        description: 'Max messages an agent drains per wake. Prevents a single agent from blocking the others by processing a huge inbox.',
+        min: 1,
+        max: 1000,
+    },
+    {
+        key: 'agent.runtime.max_consecutive_rejected_approvals',
+        type: 'number',
+        default: 3,
+        description: 'Consecutive rejected approvals that kill an agent run. Resets to 0 on every accepted approval.',
+        min: 1,
+        max: 100,
+    },
+    {
+        key: 'agent.runtime.run_timeout_seconds',
+        type: 'number',
+        default: 1800, /* 30 min */
+        description: 'Hard cap per agent run. Run is force-stopped, status=timeout, partial results preserved.',
+        min: 10,
+        max: 86_400,
+    },
+    {
+        key: 'agent.cron.missed_runs_warning_threshold',
+        type: 'number',
+        default: 3,
+        description: 'How many missed cron ticks before the panel warns the user. Local-only agents only fire while the panel is open; this catches "I closed the laptop for a week".',
+        min: 1,
+        max: 100,
+    },
+    {
+        key: 'agent.audit.retention_days',
+        type: 'number',
+        default: 90,
+        description: 'How long agent runs + bridge messages stay in audit_log. Matches the global audit-log default.',
+        min: 1,
+        max: 3650,
+    },
+    {
+        key: 'agent.deletion.grace_period_days',
+        type: 'number',
+        default: 30,
+        description: 'When an agent is deleted, runs move to the deleted/ partition for this many days before purge. Lets the user un-delete.',
+        min: 0,
+        max: 3650,
+    },
+    {
+        key: 'agent.web_search.provider',
+        type: 'string',
+        default: 'brave',
+        description: 'Web search provider for the default agent:web-search delegate (managed-only). User-created BYOK web-search agents pick their own.',
+        enum: ['brave', 'tavily', 'google'],
+    },
+    {
+        key: 'agent.web_search.daily_query_cap',
+        type: 'number',
+        default: 100,
+        description: 'Daily query cap for the managed agent:web-search delegate using the central API key. Per-user. Resets at UTC midnight.',
+        min: 1,
+        max: 100_000,
+    },
+];
+/* Map for O(1) lookup. */
+const SCHEMA_BY_KEY = (() => {
+    const out = {};
+    for (const d of AGENT_CONFIG_SCHEMA) {
+        out[d.key] = d;
+    }
+    return out;
+})();
+export function getAgentConfigDescriptor(key) {
+    const d = SCHEMA_BY_KEY[key];
+    if (!d) {
+        throw new Error('Unknown agent config key: ' + String(key));
+    }
+    return d;
+}
+export function getAgentConfigDefault(key) {
+    return getAgentConfigDescriptor(key).default;
+}
+/* Validation -- used by both the runtime config loader + the
+ * `yf limits set agent.<key> <value>` CLI. Returns the coerced
+ * value on success, throws on failure. */
+export function validateAgentConfigValue(key, raw) {
+    const d = getAgentConfigDescriptor(key);
+    switch (d.type) {
+        case 'number': {
+            const n = typeof raw === 'number' ? raw : Number(raw);
+            if (!Number.isFinite(n)) {
+                throw new Error('agent config ' + key + ' must be a number, got ' + typeof raw);
+            }
+            if (d.min !== undefined && n < d.min) {
+                throw new Error('agent config ' + key + ' below min (' + d.min + '): got ' + n);
+            }
+            if (d.max !== undefined && n > d.max) {
+                throw new Error('agent config ' + key + ' above max (' + d.max + '): got ' + n);
+            }
+            return n;
+        }
+        case 'string': {
+            const s = String(raw);
+            if (d.enum && !d.enum.includes(s)) {
+                throw new Error('agent config ' + key + ' must be one of [' + d.enum.join(', ') + '], got ' + JSON.stringify(s));
+            }
+            return s;
+        }
+        case 'boolean': {
+            if (raw === true || raw === 'true' || raw === 1 || raw === '1')
+                return true;
+            if (raw === false || raw === 'false' || raw === 0 || raw === '0')
+                return false;
+            throw new Error('agent config ' + key + ' must be a boolean, got ' + JSON.stringify(raw));
+        }
+    }
+}
+/* Generates the user-facing config file body (json with a leading
+ * comment block listing every key + description + default). The
+ * config file lives at `~/.yujin-forge/agents/config.json` and is
+ * created on first `yf agent install --defaults`. */
+export function renderDefaultConfigJson() {
+    const obj = {};
+    for (const d of AGENT_CONFIG_SCHEMA) {
+        obj[d.key] = d.default;
+    }
+    return JSON.stringify(obj, null, 2);
+}
+/* Generates a markdown doc of every key + description + default
+ * for inclusion in docs/HITO_5_AGENT_ORCHESTRATOR_DESIGN.md or
+ * the user-facing settings panel. */
+export function renderConfigDocsMarkdown() {
+    const rows = AGENT_CONFIG_SCHEMA.map((d) => {
+        const bounds = d.type === 'number'
+            ? ' (range: ' + (d.min ?? '-') + '..' + (d.max ?? '-') + ')'
+            : (d.enum ? ' (one of: ' + d.enum.join(', ') + ')' : '');
+        return '| `' + d.key + '` | ' + d.type + bounds + ' | ' + JSON.stringify(d.default) + ' | ' + d.description + ' |';
+    });
+    return [
+        '| Key | Type | Default | Description |',
+        '|---|---|---|---|',
+        ...rows,
+    ].join('\n');
+}
+//# sourceMappingURL=config_schema.js.map

package/dist/agents/config_schema.js.map

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