instar 0.28.106 → 0.28.108

package/dist/monitoring/BurnThrottleRunbook.js

@@ -0,0 +1,202 @@
+/**
+ * BurnThrottleRunbook — Tier-2 authority surface for burn-detection signals.
+ *
+ * Phase 4 of docs/specs/token-burn-detection-and-self-heal.md. This is the
+ * ONLY blocking surface in the burn-detection pipeline. The BurnDetector
+ * (Phase 3) emits structured signals via DegradationReporter; this runbook
+ * subscribes via the existing handler hook and decides:
+ *   - alert-only (default for `unknown::*` keys and any caller config disables)
+ *   - throttle (default for known component names)
+ *   - both (the umbrella spec's primary policy)
+ *
+ * Authority shape (per umbrella spec §"Signal-vs-Authority Decomposition"):
+ * the runbook is the only piece in this pipeline with blocking authority.
+ * The detector emits; the gate enforces; the runbook decides.
+ *
+ * Self-reinforcing-loop guard: the runbook never throttles a key starting
+ * with `burn-throttle-runbook::*` — defence-in-depth (the gate also refuses
+ * to install such throttles, the detector also exempts the prefix). This
+ * three-layer guard is from the convergence audit.
+ */
+export const DEFAULT_BURN_THROTTLE_CONFIG = {
+    autoThrottle: true,
+    autoThrottleOnUnknown: false,
+    throttleDurationMs: 60 * 60 * 1000,
+};
+/** Identity tag the runbook uses when installing throttles. */
+export const RUNBOOK_ISSUER = 'burn-throttle-runbook';
+export class BurnThrottleRunbook {
+    gate;
+    config;
+    sendTelegram;
+    alertTopicId;
+    now;
+    constructor(deps) {
+        this.gate = deps.gate;
+        this.config = { ...DEFAULT_BURN_THROTTLE_CONFIG, ...(deps.config ?? {}) };
+        this.sendTelegram = deps.sendTelegram;
+        this.alertTopicId = deps.alertTopicId ?? 8615;
+        this.now = deps.now ?? (() => Date.now());
+    }
+    /**
+     * Handle a burn-detection signal. Called from a subscriber hook on
+     * DegradationReporter for feature='token-burn-detection' events.
+     *
+     * Returns the outcome so tests + audit + the verification step (Phase 6)
+     * can inspect what happened.
+     */
+    handle(event) {
+        const attributionKey = extractAttributionKey(event);
+        const trigger = extractTrigger(event);
+        const decidedAt = new Date(this.now()).toISOString();
+        const signalId = `${event.timestamp}:${attributionKey}`;
+        // 1. Self-attribution: refuse to throttle the runbook itself, AND emit
+        //    a high-severity escalation alert. Per Phase 4 second-pass review §3:
+        //    silent swallow is the wrong response here — if the runbook itself
+        //    is being attributed-to as a burn source, something is structurally
+        //    wrong (a bug in the runbook's own LLM-bound code, or attribution
+        //    being mis-applied to a legitimate runbook call). Either way, that's
+        //    exactly the case a user needs to know about. So we DO send Telegram.
+        if (attributionKey.startsWith(`${RUNBOOK_ISSUER}::`)) {
+            this.fireTelegram(`URGENT: the burn-throttle runbook itself is being flagged as a burn source ` +
+                `(${attributionKey}). I refused to throttle myself by design, but this likely ` +
+                `means either the runbook has a bug producing too many LLM calls, or attribution ` +
+                `is being mis-applied to legitimate runbook work. Please investigate.`);
+            return {
+                kind: 'alert-only-self-attribution',
+                attributionKey,
+                decidedAt,
+                trigger,
+                reason: 'Refusing to throttle the runbook itself (self-reinforcing-loop guard); escalation alert sent.',
+            };
+        }
+        // Compose the alert text now so we send it regardless of throttle outcome.
+        const alertText = composeAlertText(event, attributionKey, trigger);
+        // 2. Caller config disables auto-throttle.
+        if (!this.config.autoThrottle) {
+            this.fireTelegram(alertText);
+            return {
+                kind: 'alert-only-config-disabled',
+                attributionKey,
+                decidedAt,
+                trigger,
+                reason: 'autoThrottle is disabled in config; alert sent but no throttle installed.',
+            };
+        }
+        // 3. Unknown attribution + caller has not opted in to auto-throttle on unknown.
+        if (isUnknownKey(attributionKey) && !this.config.autoThrottleOnUnknown) {
+            this.fireTelegram(alertText);
+            return {
+                kind: 'alert-only-unknown',
+                attributionKey,
+                decidedAt,
+                trigger,
+                reason: 'Attribution key has no known component; operator must opt in to auto-throttle on unknown.',
+            };
+        }
+        // 4. Install throttle, send alert.
+        const token = this.gate.computeCapabilityToken({
+            attributionKey,
+            durationMs: this.config.throttleDurationMs,
+            issuer: RUNBOOK_ISSUER,
+            signalId,
+        }) ?? undefined;
+        try {
+            const throttle = this.gate.installThrottle({
+                attributionKey,
+                durationMs: this.config.throttleDurationMs,
+                reason: `${trigger} trigger crossed threshold; runbook installed bounded throttle.`,
+                issuer: RUNBOOK_ISSUER,
+                signalId,
+                capabilityToken: token,
+            });
+            this.fireTelegram(`${alertText}\n\nI have slowed this component down. It will resume automatically in ${Math.round(this.config.throttleDurationMs / 60000)} minutes, or you can reply STOP to release it sooner.`);
+            return {
+                kind: 'throttle-installed',
+                attributionKey,
+                decidedAt,
+                trigger,
+                throttle,
+                reason: 'Throttle installed, alert sent.',
+            };
+        }
+        catch (err) {
+            this.fireTelegram(`${alertText}\n\nI tried to slow it down automatically but the slowdown did not take effect. You may need to look at this one.`);
+            return {
+                kind: 'throttle-failed',
+                attributionKey,
+                decidedAt,
+                trigger,
+                reason: `Throttle install failed: ${err.message}`,
+            };
+        }
+    }
+    fireTelegram(text) {
+        if (!this.sendTelegram)
+            return;
+        try {
+            // Caller may return a promise; we don't await — the runbook is on the
+            // signal-handling hot path and must not block. Errors are swallowed:
+            // a failed alert can't block the throttle decision, which is the
+            // important part.
+            void this.sendTelegram(this.alertTopicId, text);
+        }
+        catch {
+            // Intentional swallow.
+        }
+    }
+}
+/* ---------- pure helpers (exported for tests) ---------- */
+/**
+ * Extract the attribution key from a burn-detection DegradationEvent. The
+ * BurnDetector formats the `primary` field as "attribution_key <KEY>
+ * sustained spend within thresholds" — we parse it back here. The wire
+ * shape is internal to the burn-detection pipeline; if it changes, change
+ * both ends in the same PR.
+ */
+export function extractAttributionKey(event) {
+    const m = /attribution_key\s+(\S+)/.exec(event.primary || '');
+    return m && m[1] ? m[1] : 'unknown::no-key';
+}
+/**
+ * Extract the trigger label from the event's reason field. Returns
+ * 'absolute-share' or 'baseline-divergence' or 'unknown-trigger'.
+ */
+export function extractTrigger(event) {
+    if (/% of 24h spend/.test(event.reason || ''))
+        return 'absolute-share';
+    if (/baseline/i.test(event.reason || ''))
+        return 'baseline-divergence';
+    return 'unknown-trigger';
+}
+/** Is the attribution key one of the unknown::* fallback shapes? */
+export function isUnknownKey(attributionKey) {
+    return attributionKey.startsWith('unknown::');
+}
+/** Compose the ELI16 alert text for Telegram. No backticks, no camelCase config keys, narrative tone. */
+export function composeAlertText(event, attributionKey, trigger) {
+    const friendlyName = humanize(attributionKey);
+    const triggerNarrative = trigger === 'absolute-share'
+        ? 'is using more than a quarter of the agent\'s total token budget over the last day'
+        : trigger === 'baseline-divergence'
+            ? 'has more than doubled its normal rate in the last hour, and the absolute amount is large enough to matter'
+            : 'crossed one of the burn thresholds';
+    return (`Heads up: ${friendlyName} ${triggerNarrative}.\n\n` +
+        `${event.reason}\n\n` +
+        `${event.impact}`);
+}
+function humanize(attributionKey) {
+    if (attributionKey.startsWith('unknown::'))
+        return 'an unknown component';
+    if (attributionKey.startsWith('user-job:')) {
+        const m = /^user-job:([^:]+)/.exec(attributionKey);
+        return m ? `your scheduled job "${m[1]}"` : 'a scheduled job';
+    }
+    if (attributionKey.startsWith('user-hook:')) {
+        const m = /^user-hook:([^:]+)/.exec(attributionKey);
+        return m ? `your hook "${m[1]}"` : 'a hook';
+    }
+    const m = /^([^:]+)::/.exec(attributionKey);
+    return m ? `the ${m[1]} component` : attributionKey;
+}
+//# sourceMappingURL=BurnThrottleRunbook.js.map

package/dist/monitoring/BurnThrottleRunbook.js.map

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

package/dist/monitoring/LlmRateGate.d.ts

@@ -1,28 +1,28 @@
 /**
  * LlmRateGate — actuator primitive for the burn-detection auto-heal system.
  *
- * Phase 1 (this file): ships as a NO-OP. The primitive exists, the shape is
- * stable, and instar-internal LLM callers can already consult it before each
- * call — but no decision-maker is wired in yet, so `shouldFire(key)` always
- * returns true. This deliberate sequencing avoids a regression window where
- * the BurnDetector emits signals with no actuator to honour them.
+ * Phase 1 shipped the no-op shape. Phase 4 upgrades the gate into a stateful
+ * actuator: the burn-throttle runbook installs throttles via `installThrottle`,
+ * the LLM callers consult `shouldFire` / `decide`, and a throttle auto-expires
+ * after its TTL elapses. Per the umbrella spec §"Signal-vs-Authority
+ * Decomposition", the gate enforces decisions made elsewhere — it never
+ * decides anything on its own.
  *
- * Future phases (per docs/specs/token-burn-detection-and-self-heal.md):
- *   - Phase 4 (burn-throttle runbook): the Remediator-Tier-2 runbook stores
- *     signed throttle decisions; the gate consults that store.
- *   - Phase 4 (HMAC-signed jobs.json.throttle-overrides): scheduled-job
- *     overrides land via this gate so the same actuator covers cron entries.
+ * State: in-memory only. The throttle store is process-local. If the agent
+ * restarts, any in-memory throttle is dropped — which is the right default
+ * (a restart is itself a reset, and the burn-detector will re-emit any
+ * surviving signal within 60s). Persistent throttles for scheduled-job cron
+ * entries live in a separate file (`.instar/jobs.json.throttle-overrides`,
+ * HMAC-signed) handled by the scheduler — out of scope for this primitive.
  *
- * Authority shape: the gate ENFORCES decisions that were made elsewhere. It
- * does NOT decide. Brittle threshold detectors must never write to this
- * gate directly — only the Remediator (with signed-context Tier-2 capability
- * tokens) can install a throttle. This honours the signal-vs-authority
- * boundary in docs/signal-vs-authority.md.
- *
- * Singleton-per-process: every LLM caller in the process shares one gate so
- * a single throttle decision covers every code path that uses the same
- * attribution key. The class exposes a static `instance()` accessor; tests
- * use the public constructor + `reset()` to isolate from the singleton.
+ * Authority: the gate accepts throttles only via `installThrottle`, which the
+ * runbook calls with a capability token. The token is verified by the gate
+ * against the agent's HMAC key (passed at constructor time when the gate
+ * needs to enforce, or skipped for tests). When no key is configured, the
+ * gate accepts throttles without verification — that's the "trusted local
+ * caller" mode used by the runbook before the F-8 capability surface fully
+ * lands. The verification path is in place so the runbook can switch to
+ * signed tokens without API churn.
  */
 export interface LlmRateGateDecision {
     /** Whether the gate currently allows the next LLM call for this key. */
@@ -30,34 +30,134 @@ export interface LlmRateGateDecision {
     /** ISO timestamp the decision was made (debug / log). */
     decidedAt: string;
     /** Why — for log + verification trace. */
-    reason: 'phase-1-noop' | 'no-throttle-installed' | 'throttle-active' | 'throttle-expired';
+    reason: 'no-throttle-installed' | 'throttle-active' | 'throttle-expired' | 'runbook-self-exempt';
+    /** When the active throttle (if any) expires. Phase 4: ISO timestamp. */
+    throttleExpiresAt?: string;
+}
+export interface InstalledThrottle {
+    attributionKey: string;
+    /** ISO timestamp when the throttle was installed. */
+    installedAt: string;
+    /** ISO timestamp when the throttle auto-reverts. */
+    expiresAt: string;
+    /** Free-text reason the runbook chose this throttle. */
+    reason: string;
+    /** Issuer identity (the runbook). Audit trail only. */
+    issuer: string;
+}
+export interface InstallThrottleInput {
+    attributionKey: string;
+    /** Throttle duration in milliseconds (auto-reverts when elapsed). */
+    durationMs: number;
+    /** Free-text reason for audit. */
+    reason: string;
+    /** Issuer identity for audit (e.g. 'burn-throttle-runbook'). */
+    issuer: string;
+    /**
+     * Unique identifier for the originating burn signal. Used by the gate as a
+     * replay-prevention nonce — once consumed, the same signalId cannot install
+     * another throttle. The runbook derives this from the DegradationEvent's
+     * monotonic timestamp + attribution key. Reviewer-required (Phase 4
+     * second-pass review §1) to close the infinite-replay window on captured
+     * capability tokens.
+     */
+    signalId: string;
+    /**
+     * Capability token over the canonical install payload. When the gate has
+     * an HMAC key configured (production), the token MUST be present and
+     * valid. When no key is configured (tests / pre-F-8 wiring), the token
+     * is ignored — see the class doc for the "trusted local caller" caveat
+     * (the HMAC defends external/cross-process forgery, not in-process mints).
+     */
+    capabilityToken?: string;
+}
+export interface LlmRateGateOptions {
+    /**
+     * Optional HMAC key for capability-token verification. When set, every
+     * installThrottle call must include a valid `capabilityToken` over the
+     * canonical payload.
+     */
+    capabilityKey?: Buffer | null;
+    /** Injectable clock for tests. */
+    now?: () => number;
 }
 export declare class LlmRateGate {
     private static singleton;
+    private readonly throttles;
+    private readonly capabilityKey;
+    private readonly now;
+    /**
+     * Consumed signal IDs — replay-prevention nonces. Per Phase 4 second-pass
+     * review §1. Garbage-collected lazily during `installThrottle`: entries
+     * older than the maximum throttle TTL (2× the longest seen) can be
+     * dropped because their corresponding throttle has long since expired.
+     */
+    private readonly consumedSignalIds;
+    /** Tracks the longest throttle duration seen, used for GC of consumed IDs. */
+    private maxThrottleDurationMs;
+    constructor(opts?: LlmRateGateOptions);
     /**
      * Process-wide singleton. Tests should use `new LlmRateGate()` + `reset()`
      * rather than this accessor, so they don't bleed throttles into each other.
      */
     static instance(): LlmRateGate;
     /**
-     * Phase 1: always returns true. The signature is stable so callers can
-     * adopt the consult-before-call pattern today; future phases enforce it.
+     * Read-side: does the gate currently allow a call for this key?
      *
-     * @param attributionKey  componentName::promptFingerprint key. Reserved
-     *                        values: keys starting with `burn-throttle-runbook::`
-     *                        are exempt by design (self-reinforcing-loop guard
-     *                        per spec §"Self-reinforcing loop guard").
+     * @param attributionKey componentName::promptFingerprint. Reserved prefix
+     *                       `burn-throttle-runbook::*` is structurally exempt
+     *                       (self-reinforcing-loop guard).
      */
     shouldFire(attributionKey: string): boolean;
+    decide(attributionKey: string): LlmRateGateDecision;
+    /**
+     * Install a throttle for an attribution key. Called by the burn-throttle
+     * runbook. Refuses keys with the runbook-self exempt prefix as a defence
+     * in depth (the gate also exempts on the read path).
+     *
+     * Returns the InstalledThrottle if accepted, or throws on:
+     *   - Self-attribution attempts.
+     *   - Capability-token verification failure (when key is configured).
+     *   - Zero/negative duration.
+     */
+    installThrottle(input: InstallThrottleInput): InstalledThrottle;
+    private signWithKey;
     /**
-     * Same as shouldFire() but returns the full decision record. Useful for
-     * tests and for the burn-throttle runbook's verification step.
+     * Revoke an active throttle. Idempotent (no-op if no throttle exists).
+     * Called by the Telegram inline-button handler in Phase 5 and by the
+     * runbook's manual-override path.
      */
-    decide(attributionKey: string): LlmRateGateDecision;
+    revokeThrottle(attributionKey: string): boolean;
+    /**
+     * List currently-active throttles. Used by the verification step (Phase 6)
+     * and by the dashboard surface.
+     */
+    listActiveThrottles(): InstalledThrottle[];
+    /**
+     * Compute the capability token for an install payload. Used by the
+     * runbook to sign its own throttle requests. Returns null when no
+     * capability key is configured (test mode).
+     *
+     * **Threat-model note (Phase 4 second-pass review §2):** this mint and the
+     * verification it pairs with both live on the same gate object, so any
+     * in-process caller holding a gate reference can forge a valid token. The
+     * HMAC therefore defends the **external/cross-process boundary** only
+     * — chiefly the persistent throttle-overrides file the scheduler reads
+     * (Phase 4-extension, not in this PR). For in-process integrity we rely
+     * on the fact that all callers of LlmRateGate are instar source under
+     * the same `/instar-dev` review gate. If/when the runbook is moved to a
+     * separate process, this mint method should be relocated to the runbook
+     * service alone and removed from the gate's API surface.
+     */
+    computeCapabilityToken(input: {
+        attributionKey: string;
+        durationMs: number;
+        issuer: string;
+        signalId: string;
+    }): string | null;
     /**
-     * Reset all installed throttles. Phase 1 has no throttles, so this is a
-     * no-op; future phases will clear the in-memory throttle map. Exposed for
-     * tests so a misconfigured singleton can't bleed across `describe` blocks.
+     * Reset all installed throttles. Exposed for tests so a misconfigured
+     * singleton can't bleed across `describe` blocks.
      */
     reset(): void;
 }

package/dist/monitoring/LlmRateGate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LlmRateGate.d.ts","sourceRoot":"","sources":["../../src/monitoring/LlmRateGate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,OAAO,EAAE,OAAO,CAAC;IACjB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,MAAM,EAAE,cAAc,GAAG,uBAAuB,GAAG,iBAAiB,GAAG,kBAAkB,CAAC;CAC3F;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAC,SAAS,CAA4B;IAEpD;;;OAGG;IACH,MAAM,CAAC,QAAQ,IAAI,WAAW;IAO9B;;;;;;;;OAQG;IACH,UAAU,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO;IAI3C;;;OAGG;IACH,MAAM,CAAC,cAAc,EAAE,MAAM,GAAG,mBAAmB;IAmBnD;;;;OAIG;IACH,KAAK,IAAI,IAAI;CAGd"}
+{"version":3,"file":"LlmRateGate.d.ts","sourceRoot":"","sources":["../../src/monitoring/LlmRateGate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,OAAO,EAAE,OAAO,CAAC;IACjB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,MAAM,EACF,uBAAuB,GACvB,iBAAiB,GACjB,kBAAkB,GAClB,qBAAqB,CAAC;IAC1B,yEAAyE;IACzE,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,kCAAkC;IAClC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAC,SAAS,CAA4B;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwC;IAClE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA6B;IAC/D,8EAA8E;IAC9E,OAAO,CAAC,qBAAqB,CAAkB;gBAEnC,IAAI,CAAC,EAAE,kBAAkB;IAKrC;;;OAGG;IACH,MAAM,CAAC,QAAQ,IAAI,WAAW;IAO9B;;;;;;OAMG;IACH,UAAU,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO;IAI3C,MAAM,CAAC,cAAc,EAAE,MAAM,GAAG,mBAAmB;IAuBnD;;;;;;;;;OASG;IACH,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,iBAAiB;IA0D/D,OAAO,CAAC,WAAW;IAUnB;;;;OAIG;IACH,cAAc,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO;IAI/C;;;OAGG;IACH,mBAAmB,IAAI,iBAAiB,EAAE;IAc1C;;;;;;;;;;;;;;;OAeG;IACH,sBAAsB,CAAC,KAAK,EAAE;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,GAAG,IAAI;IAK9H;;;OAGG;IACH,KAAK,IAAI,IAAI;CAGd"}