instar 1.3.443 → 1.3.445

package/dist/permissions/AmbientContributionGate.d.ts

@@ -0,0 +1,149 @@
+/**
+ * AmbientContributionGate — the conservative "should I speak?" gate for Slack's
+ * `considered`/ambient mode (Slack org integration, Pillar 1 §5.2 / §6.9).
+ *
+ * In `mention-only` mode an UNDIRECTED message (no @mention, not a DM) is dropped
+ * — the agent stays quiet. Ambient mode keeps that default but adds ONE narrow
+ * escape: for a channel that has EXPLICITLY opted into proactive contribution, an
+ * undirected message may run this gate, which decides whether the agent has a
+ * concrete, meaningful contribution worth making unprompted.
+ *
+ * ── THE INVARIANT: FAIL-TO-SILENCE ─────────────────────────────────────────────
+ *
+ * This gate can only ever make the agent QUIETER. It returns `speak: true` ONLY
+ * when EVERY one of these holds:
+ *   (a) the channel is explicitly ambient-opted-in (config — default OFF everywhere),
+ *   (b) a hard per-channel rate-limit for the rolling window is NOT exceeded,
+ *   (c) an LLM judges it can contribute MEANINGFULLY above a conservative
+ *       confidence threshold AND explicitly says to speak.
+ *
+ * ANY failure, uncertainty, LLM error, missing provider, unparseable verdict, or
+ * rate-limit breach → `speak: false`. There is NO path through this gate that
+ * produces an over-speak on a degraded condition. This is the deliberate MIRROR of
+ * the floor gate's fail-CLOSED (deny-on-error): here the safe direction is SILENCE.
+ * (Spec §5.2 "Fail mode: fail to silence"; §11 "the ambient/should-speak gate fails
+ * to silence".)
+ *
+ * ── DARK / OPT-IN ──────────────────────────────────────────────────────────────
+ *
+ * Ambient contribution is disabled for every channel by default. With NO ambient
+ * config, this gate is never even constructed/consulted and `_handleMessage`
+ * behaves byte-for-byte as today (mention-only drops undirected messages). The gate
+ * runs ONLY for an explicitly-opted-in channel.
+ *
+ * The LLM is reached through instar's internal `IntelligenceProvider` (the same
+ * injected-provider pattern as `LlmIntentClassifier` / `MessagingToneGate`), NOT a
+ * raw API call. A `fast` model tier is used. The call is intentionally NOT marked
+ * `gating: true`: a gating call would provider-SWAP on failure to keep an authority
+ * decision alive, but the safe failure here is to stay silent — we WANT the error to
+ * land in our catch and return `speak: false`, never to escalate to keep speaking.
+ *
+ * NOTE: this gate decides ONLY whether to PROCESS an undirected message. It performs
+ * no Slack Web API calls and sends nothing itself — `_handleMessage` does the
+ * processing/sending downstream exactly as it does for a directed message.
+ *
+ * Design: docs/specs/SLACK-ORG-INTEGRATION-SPEC.md §5.2, §6.9, §11.
+ */
+import type { IntelligenceProvider } from '../core/types.js';
+/** The gate's decision for a single undirected message. */
+export interface AmbientDecision {
+    /** True ONLY when every fail-to-silence condition holds. Default false. */
+    speak: boolean;
+    /** Machine-readable reason for the decision (for logging / FP measurement). */
+    reason: AmbientDecisionReason;
+    /** Optional human-readable detail (e.g. the LLM's named contribution). */
+    detail?: string;
+}
+export type AmbientDecisionReason = 'channel-not-opted-in' | 'rate-limited' | 'no-intelligence' | 'llm-error' | 'llm-unparseable' | 'llm-declined' | 'low-confidence' | 'speak';
+/** Per-channel ambient configuration. Default: ambient OFF. */
+export interface AmbientChannelConfig {
+    /** Channels explicitly opted into proactive contribution. Default: none. */
+    enabledChannelIds?: string[];
+    /**
+     * Hard cap on proactive (unsolicited) messages per channel within the rolling
+     * window. Conservative default: 1. A bot that barges in is worse than a silent
+     * one, so this is deliberately tiny.
+     */
+    maxProactivePerChannel?: number;
+    /** Rolling rate-limit window in ms. Default: 30 minutes. */
+    windowMs?: number;
+    /**
+     * Conservative confidence floor for the LLM's "speak" verdict, in [0,1]. Below
+     * this, the gate stays silent even if the LLM said speak. Default: 0.85 (high bar).
+     */
+    minConfidence?: number;
+}
+export interface AmbientContributionGateDeps {
+    /** Per-channel ambient configuration. Absent/empty ⇒ ambient OFF everywhere. */
+    config?: AmbientChannelConfig;
+    /**
+     * The internal LLM provider (injected — never a direct framework import). When
+     * absent, the gate stays SILENT (fail-to-silence): no provider ⇒ no contribution.
+     */
+    intelligence?: IntelligenceProvider;
+    /** Per-call LLM timeout (ms). Default 8000. */
+    timeoutMs?: number;
+    /**
+     * Optional observability hook — fires on EVERY decision with the reason, so the
+     * FP-rate of proactive speaking can be measured before any aggressiveness change.
+     * Best-effort: it never affects the returned decision.
+     */
+    onDecision?: (decision: AmbientDecision, channelId: string) => void;
+    /** Injectable clock for deterministic tests. Defaults to Date.now. */
+    now?: () => number;
+}
+/** Context the gate needs about the channel + message. */
+export interface AmbientGateInput {
+    /** The Slack channel id the undirected message arrived in. */
+    channelId: string;
+    /** The (cleaned) message text. */
+    text: string;
+    /** Optional channel name, purely for the LLM prompt context. */
+    channelName?: string;
+}
+export declare class AmbientContributionGate {
+    private readonly enabledChannels;
+    private readonly maxProactive;
+    private readonly windowMs;
+    private readonly minConfidence;
+    private readonly intelligence?;
+    private readonly timeoutMs;
+    private readonly onDecision?;
+    private readonly now;
+    /**
+     * Rate-limit state lives HERE — a per-channel in-memory ring of the timestamps at
+     * which the gate last returned speak=true. It is recorded by recordSpoke() (called
+     * by _handleMessage only AFTER the gate cleared and the message is actually being
+     * processed), so a speak=true that the caller decides not to act on does not
+     * consume budget. In-memory is acceptable: a restart resetting the window can only
+     * make the agent quieter for a moment (it never over-speaks), which is on the safe
+     * side of the invariant. A future durable counter could replace this without
+     * changing the contract.
+     */
+    private readonly proactiveTimestamps;
+    constructor(deps?: AmbientContributionGateDeps);
+    /** Is ANY channel opted into ambient contribution? Used to skip the gate entirely. */
+    isAnyChannelEnabled(): boolean;
+    /** Is this specific channel opted into ambient contribution? */
+    isChannelEnabled(channelId: string): boolean;
+    /**
+     * Decide whether to speak on an UNDIRECTED message in an ambient channel.
+     * FAIL-TO-SILENCE: returns { speak: false } on every degraded/uncertain path.
+     */
+    shouldSpeak(input: AmbientGateInput): Promise<AmbientDecision>;
+    /**
+     * Record that the agent actually spoke proactively in a channel (call AFTER the
+     * gate cleared and _handleMessage commits to processing). Consumes one unit of the
+     * rolling window budget. Idempotency is not required — each proactive turn is one
+     * unit.
+     */
+    recordSpoke(channelId: string): void;
+    /** How many proactive sends remain in the current window for a channel (for status). */
+    remainingBudget(channelId: string): number;
+    /** True iff the per-channel proactive budget is exhausted for the rolling window. */
+    private isRateLimited;
+    /** Count of proactive sends within the rolling window; prunes expired entries. */
+    private recentCount;
+    private decide;
+}
+//# sourceMappingURL=AmbientContributionGate.d.ts.map

package/dist/permissions/AmbientContributionGate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AmbientContributionGate.d.ts","sourceRoot":"","sources":["../../src/permissions/AmbientContributionGate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAE7D,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,KAAK,EAAE,OAAO,CAAC;IACf,+EAA+E;IAC/E,MAAM,EAAE,qBAAqB,CAAC;IAC9B,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,qBAAqB,GAC7B,sBAAsB,GACtB,cAAc,GACd,iBAAiB,GACjB,WAAW,GACX,iBAAiB,GACjB,cAAc,GACd,gBAAgB,GAChB,OAAO,CAAC;AAEZ,+DAA+D;AAC/D,MAAM,WAAW,oBAAoB;IACnC,4EAA4E;IAC5E,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,2BAA2B;IAC1C,gFAAgF;IAChF,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B;;;OAGG;IACH,YAAY,CAAC,EAAE,oBAAoB,CAAC;IACpC,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACpE,sEAAsE;IACtE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,0DAA0D;AAC1D,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAYD,qBAAa,uBAAuB;IAClC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAc;IAC9C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAuB;IACrD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAyD;IACrF,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IAEnC;;;;;;;;;OASG;IACH,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAoC;gBAE5D,IAAI,GAAE,2BAAgC;IAalD,sFAAsF;IACtF,mBAAmB,IAAI,OAAO;IAI9B,gEAAgE;IAChE,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAI5C;;;OAGG;IACG,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;IA0DpE;;;;;OAKG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAMpC,wFAAwF;IACxF,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAK1C,qFAAqF;IACrF,OAAO,CAAC,aAAa;IAIrB,kFAAkF;IAClF,OAAO,CAAC,WAAW;IAanB,OAAO,CAAC,MAAM;CAQf"}

package/dist/permissions/AmbientContributionGate.js

@@ -0,0 +1,261 @@
+/**
+ * AmbientContributionGate — the conservative "should I speak?" gate for Slack's
+ * `considered`/ambient mode (Slack org integration, Pillar 1 §5.2 / §6.9).
+ *
+ * In `mention-only` mode an UNDIRECTED message (no @mention, not a DM) is dropped
+ * — the agent stays quiet. Ambient mode keeps that default but adds ONE narrow
+ * escape: for a channel that has EXPLICITLY opted into proactive contribution, an
+ * undirected message may run this gate, which decides whether the agent has a
+ * concrete, meaningful contribution worth making unprompted.
+ *
+ * ── THE INVARIANT: FAIL-TO-SILENCE ─────────────────────────────────────────────
+ *
+ * This gate can only ever make the agent QUIETER. It returns `speak: true` ONLY
+ * when EVERY one of these holds:
+ *   (a) the channel is explicitly ambient-opted-in (config — default OFF everywhere),
+ *   (b) a hard per-channel rate-limit for the rolling window is NOT exceeded,
+ *   (c) an LLM judges it can contribute MEANINGFULLY above a conservative
+ *       confidence threshold AND explicitly says to speak.
+ *
+ * ANY failure, uncertainty, LLM error, missing provider, unparseable verdict, or
+ * rate-limit breach → `speak: false`. There is NO path through this gate that
+ * produces an over-speak on a degraded condition. This is the deliberate MIRROR of
+ * the floor gate's fail-CLOSED (deny-on-error): here the safe direction is SILENCE.
+ * (Spec §5.2 "Fail mode: fail to silence"; §11 "the ambient/should-speak gate fails
+ * to silence".)
+ *
+ * ── DARK / OPT-IN ──────────────────────────────────────────────────────────────
+ *
+ * Ambient contribution is disabled for every channel by default. With NO ambient
+ * config, this gate is never even constructed/consulted and `_handleMessage`
+ * behaves byte-for-byte as today (mention-only drops undirected messages). The gate
+ * runs ONLY for an explicitly-opted-in channel.
+ *
+ * The LLM is reached through instar's internal `IntelligenceProvider` (the same
+ * injected-provider pattern as `LlmIntentClassifier` / `MessagingToneGate`), NOT a
+ * raw API call. A `fast` model tier is used. The call is intentionally NOT marked
+ * `gating: true`: a gating call would provider-SWAP on failure to keep an authority
+ * decision alive, but the safe failure here is to stay silent — we WANT the error to
+ * land in our catch and return `speak: false`, never to escalate to keep speaking.
+ *
+ * NOTE: this gate decides ONLY whether to PROCESS an undirected message. It performs
+ * no Slack Web API calls and sends nothing itself — `_handleMessage` does the
+ * processing/sending downstream exactly as it does for a directed message.
+ *
+ * Design: docs/specs/SLACK-ORG-INTEGRATION-SPEC.md §5.2, §6.9, §11.
+ */
+const DEFAULT_MAX_PROACTIVE = 1;
+const DEFAULT_WINDOW_MS = 30 * 60 * 1000; // 30 minutes
+const DEFAULT_MIN_CONFIDENCE = 0.85;
+export class AmbientContributionGate {
+    enabledChannels;
+    maxProactive;
+    windowMs;
+    minConfidence;
+    intelligence;
+    timeoutMs;
+    onDecision;
+    now;
+    /**
+     * Rate-limit state lives HERE — a per-channel in-memory ring of the timestamps at
+     * which the gate last returned speak=true. It is recorded by recordSpoke() (called
+     * by _handleMessage only AFTER the gate cleared and the message is actually being
+     * processed), so a speak=true that the caller decides not to act on does not
+     * consume budget. In-memory is acceptable: a restart resetting the window can only
+     * make the agent quieter for a moment (it never over-speaks), which is on the safe
+     * side of the invariant. A future durable counter could replace this without
+     * changing the contract.
+     */
+    proactiveTimestamps = new Map();
+    constructor(deps = {}) {
+        const cfg = deps.config ?? {};
+        this.enabledChannels = new Set(cfg.enabledChannelIds ?? []);
+        // Nullish coalescing (zero is a valid — fully-silent — cap).
+        this.maxProactive = cfg.maxProactivePerChannel ?? DEFAULT_MAX_PROACTIVE;
+        this.windowMs = cfg.windowMs ?? DEFAULT_WINDOW_MS;
+        this.minConfidence = cfg.minConfidence ?? DEFAULT_MIN_CONFIDENCE;
+        this.intelligence = deps.intelligence;
+        this.timeoutMs = deps.timeoutMs ?? 8000;
+        this.onDecision = deps.onDecision;
+        this.now = deps.now ?? (() => Date.now());
+    }
+    /** Is ANY channel opted into ambient contribution? Used to skip the gate entirely. */
+    isAnyChannelEnabled() {
+        return this.enabledChannels.size > 0;
+    }
+    /** Is this specific channel opted into ambient contribution? */
+    isChannelEnabled(channelId) {
+        return this.enabledChannels.has(channelId);
+    }
+    /**
+     * Decide whether to speak on an UNDIRECTED message in an ambient channel.
+     * FAIL-TO-SILENCE: returns { speak: false } on every degraded/uncertain path.
+     */
+    async shouldSpeak(input) {
+        // (a) Channel opt-in. Default OFF — an un-opted channel never speaks.
+        if (!this.enabledChannels.has(input.channelId)) {
+            return this.decide(input.channelId, { speak: false, reason: 'channel-not-opted-in' });
+        }
+        // (b) Hard rate-limit. Budget exhausted in the rolling window → silent.
+        if (this.isRateLimited(input.channelId)) {
+            return this.decide(input.channelId, { speak: false, reason: 'rate-limited' });
+        }
+        // (c) LLM judgment. No provider → silent (we never speak on a heuristic guess).
+        if (!this.intelligence) {
+            return this.decide(input.channelId, { speak: false, reason: 'no-intelligence' });
+        }
+        let raw;
+        try {
+            const { systemPrompt, userPrompt } = buildAmbientPrompt(input);
+            raw = await this.intelligence.evaluate(`${systemPrompt}\n\n${userPrompt}`, {
+                model: 'fast',
+                temperature: 0,
+                maxTokens: 200,
+                timeoutMs: this.timeoutMs,
+                attribution: {
+                    component: 'AmbientContributionGate',
+                    category: 'gate',
+                    // Deliberately NOT gating:true. A gating call provider-SWAPS on failure to
+                    // keep an AUTHORITY decision alive; here the safe failure is SILENCE, so we
+                    // let the error reach the catch below and return speak:false. Escalating to
+                    // keep talking would be exactly the over-speak this invariant forbids.
+                },
+            });
+        }
+        catch {
+            // network/timeout/provider failure / circuit open → SILENCE (never escalate).
+            return this.decide(input.channelId, { speak: false, reason: 'llm-error' });
+        }
+        const parsed = parseAmbientVerdict(raw);
+        if (!parsed) {
+            // Unparseable LLM output is a judgment FAILURE → silence.
+            return this.decide(input.channelId, { speak: false, reason: 'llm-unparseable' });
+        }
+        // The LLM must explicitly say speak.
+        if (!parsed.speak) {
+            return this.decide(input.channelId, { speak: false, reason: 'llm-declined' });
+        }
+        // Conservative confidence bar. Below it (or no named contribution) → silence.
+        if (parsed.confidence < this.minConfidence || !parsed.contribution) {
+            return this.decide(input.channelId, { speak: false, reason: 'low-confidence', detail: parsed.contribution });
+        }
+        // ALL fail-to-silence conditions held → speak.
+        return this.decide(input.channelId, { speak: true, reason: 'speak', detail: parsed.contribution });
+    }
+    /**
+     * Record that the agent actually spoke proactively in a channel (call AFTER the
+     * gate cleared and _handleMessage commits to processing). Consumes one unit of the
+     * rolling window budget. Idempotency is not required — each proactive turn is one
+     * unit.
+     */
+    recordSpoke(channelId) {
+        const arr = this.proactiveTimestamps.get(channelId) ?? [];
+        arr.push(this.now());
+        this.proactiveTimestamps.set(channelId, arr);
+    }
+    /** How many proactive sends remain in the current window for a channel (for status). */
+    remainingBudget(channelId) {
+        const used = this.recentCount(channelId);
+        return Math.max(0, this.maxProactive - used);
+    }
+    /** True iff the per-channel proactive budget is exhausted for the rolling window. */
+    isRateLimited(channelId) {
+        return this.recentCount(channelId) >= this.maxProactive;
+    }
+    /** Count of proactive sends within the rolling window; prunes expired entries. */
+    recentCount(channelId) {
+        const arr = this.proactiveTimestamps.get(channelId);
+        if (!arr || arr.length === 0)
+            return 0;
+        const cutoff = this.now() - this.windowMs;
+        const fresh = arr.filter(ts => ts >= cutoff);
+        if (fresh.length !== arr.length) {
+            // Prune expired entries so the map can't grow unbounded.
+            if (fresh.length === 0)
+                this.proactiveTimestamps.delete(channelId);
+            else
+                this.proactiveTimestamps.set(channelId, fresh);
+        }
+        return fresh.length;
+    }
+    decide(channelId, decision) {
+        try {
+            this.onDecision?.(decision, channelId);
+        }
+        catch {
+            /* observability is best-effort and must never affect the verdict */
+        }
+        return decision;
+    }
+}
+/**
+ * Validate + clamp the LLM's raw JSON into a safe verdict. Returns null when the
+ * payload can't be read (→ caller fails to silence). A missing/false `speak` is a
+ * VALID parse (it means don't speak), so this only returns null on structural junk.
+ */
+function parseAmbientVerdict(raw) {
+    if (!raw || typeof raw !== 'string')
+        return null;
+    const start = raw.indexOf('{');
+    const end = raw.lastIndexOf('}');
+    if (start === -1 || end === -1 || end < start)
+        return null;
+    let obj;
+    try {
+        obj = JSON.parse(raw.slice(start, end + 1));
+    }
+    catch {
+        return null;
+    }
+    // `speak` must be present and boolean-ish; anything else is unreadable → null,
+    // so the caller fails to silence rather than guessing an affirmative.
+    let speak;
+    if (typeof obj.speak === 'boolean')
+        speak = obj.speak;
+    else if (obj.speak === 'true')
+        speak = true;
+    else if (obj.speak === 'false')
+        speak = false;
+    else
+        return null;
+    // Missing/invalid confidence is treated as the floor (0) — never an optimistic 1.
+    let confidence = typeof obj.confidence === 'number' ? obj.confidence : Number(obj.confidence);
+    if (!Number.isFinite(confidence))
+        confidence = 0;
+    confidence = Math.max(0, Math.min(1, confidence));
+    const contribution = typeof obj.contribution === 'string' && obj.contribution.trim()
+        ? obj.contribution.trim().slice(0, 500)
+        : undefined;
+    return { speak, confidence, contribution };
+}
+/**
+ * Build the "should I speak?" prompt. It DEFAULTS TO SILENCE and asks the model to
+ * return speak:true ONLY when it can name a concrete, meaningful contribution — and
+ * never to interrupt a human-to-human exchange without clear value (§5.2 guardrails).
+ */
+function buildAmbientPrompt(input) {
+    const systemPrompt = [
+        'You are an AI agent present in a shared Slack channel. You were NOT mentioned and',
+        'NO ONE addressed you. Decide whether to volunteer an UNPROMPTED contribution.',
+        'Your strong default is SILENCE. A bot that barges in is worse than a silent one;',
+        'the failure mode is annoyance. Speak ONLY when you can name a concrete, specific,',
+        'genuinely helpful contribution that the people in the channel would welcome —',
+        'never to chime in, agree, restate, or interrupt a human-to-human exchange.',
+        'Return ONLY a compact JSON object, no prose, with exactly these keys:',
+        '  "speak":        boolean — true ONLY for a clearly worthwhile unprompted contribution.',
+        '  "confidence":   0.0-1.0 — your confidence that speaking adds clear value AND is welcome.',
+        '                  Be honest; when unsure, return a LOW number. Uncertainty means stay silent.',
+        '  "contribution": one short sentence naming the concrete contribution (omit/empty if not speaking).',
+        'When in doubt, return {"speak": false, "confidence": 0.0}.',
+        'Never output anything but the JSON object.',
+    ].join('\n');
+    const userPrompt = [
+        input.channelName ? `channel: ${input.channelName}` : 'channel: (unnamed)',
+        'overheard message (you were NOT addressed):',
+        '"""',
+        (input.text || '').slice(0, 2000),
+        '"""',
+    ].join('\n');
+    return { systemPrompt, userPrompt };
+}
+//# sourceMappingURL=AmbientContributionGate.js.map

package/dist/permissions/AmbientContributionGate.js.map

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

package/dist/permissions/index.d.ts

@@ -6,6 +6,7 @@ export * from './types.js';
 export * from './RolePolicy.js';
 export * from './IntentClassifier.js';
 export * from './LlmIntentClassifier.js';
+export * from './AmbientContributionGate.js';
 export * from './AnomalyScorer.js';
 export * from './PermissionDecisionLedger.js';
 export * from './SlackPermissionGate.js';

package/dist/permissions/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/permissions/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/permissions/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oBAAoB,CAAC;AACnC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,wBAAwB,CAAC"}

package/dist/permissions/index.js

@@ -6,6 +6,7 @@ export * from './types.js';
 export * from './RolePolicy.js';
 export * from './IntentClassifier.js';
 export * from './LlmIntentClassifier.js';
+export * from './AmbientContributionGate.js';
 export * from './AnomalyScorer.js';
 export * from './PermissionDecisionLedger.js';
 export * from './SlackPermissionGate.js';

package/dist/permissions/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/permissions/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,wBAAwB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/permissions/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oBAAoB,CAAC;AACnC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,wBAAwB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.443",
+  "version": "1.3.445",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-09T09:35:09.530Z",
-  "instarVersion": "1.3.443",
+  "generatedAt": "2026-06-09T17:12:42.642Z",
+  "instarVersion": "1.3.445",
   "entryCount": 199,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.444.md

@@ -0,0 +1,24 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+feat(permissions): conservative ambient "should I speak?" gate for Slack (`AmbientContributionGate`) — Phase 2, piece 2. For an UNDIRECTED message in an explicitly opted-in channel, the agent decides whether to proactively contribute, defaulting to **silence**. **FAIL-TO-SILENCE + dark/opt-in.**
+
+- Speak=true only when ALL hold: channel opted-in + under a hard per-channel rolling-window rate-limit (default 1 / 30 min) + LLM judges meaningful contribution above a conservative confidence floor (default 0.85). Any failure / uncertainty / malformed LLM output → silent.
+- Wires at the `_handleMessage` mention-only skip; **directed messages (DM/@mention) are untouched**; no config → byte-for-byte today's mention-only behavior. **Zero new Slack Web API calls.**
+
+## What to Tell Your User
+
+Nothing changes by default — this ships dark/opt-in. When you turn ambient mode on for a specific channel, the agent can occasionally chime in on messages that weren't addressed to it — but only when it genuinely adds value, at most rarely (a hard rate limit), and never if it's uncertain. It defaults to staying quiet; the worst case is it's too quiet, never too chatty, and it can't be talked into over-speaking by a crafted message. Direct mentions and DMs are unaffected.
+
+## Summary of New Capabilities
+
+- **`ambientContribution.enabledChannelIds` (+ `maxProactivePerChannel`, `windowMs`, `minConfidence`)** (opt-in, per-channel) — turns on the conservative ambient "should I speak?" gate for the named channels. Off everywhere by default; operator/internal config; the gate grants no permissions (a proactive turn still passes the permission gate).
+
+## Evidence
+
+- 32 tests: 23 gate (dark/opt-in, speak-path, silence-on-low-value, 8 fail-to-silence paths, rate-limit incl. per-channel/zero-cap/window-refill) + 9 wiring (dark default drops with no LLM call, DM/@mention unaffected, ambient+speak processes, ambient+silent drops, LLM-throws drops, rate-limit drops, unauthorized rejected-before-gate). `tsc --noEmit` clean; full lint suite green (incl. notification-flood-burst-invariant); 42 adjacent slack-permission tests green.
+- Side-effects review (`upgrades/side-effects/slack-ambient-gate.md`) + an independent adversarial Phase-5 second-pass on over-speak / fail-open / opt-in-bypass.

package/upgrades/1.3.445.md

@@ -0,0 +1,99 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Scopes the emergency "fix command" gate to the **Agent Attention topic** so it can no longer swallow ordinary messages in other topics. The gate in `wireTelegramRouting` (`src/commands/server.ts`) used to intercept any message starting with `restart`, `fix `, or `clean ` in **every** topic, hand it to `handleFixCommand`, and `return` — but `handleFixCommand` only does anything in the Agent Attention topic and returns `false` everywhere else. So in a normal topic the message was bounced back with *"I didn't recognize that command. Available fix commands: …"* (a list that even advertised "restart sessions" as valid) **and never routed to the session**. A user typing "restart sessions" to revive a stuck session in that session's own topic was hit by exactly this: the gate ate the message. The decision is now a pure, unit-tested helper `shouldInterceptFixCommand(text, topicId, attentionTopicId)` that returns true only inside the attention topic; `wireTelegramRouting` resolves the attention topic via a late-bound `getAttentionTopicId` and both call sites pass it. Outside the attention topic the message falls through to normal session routing — including plain phrases like "restart the build" or "fix the login page" that were silently eaten before.
+
+## What to Tell Your User
+
+If you ever messaged a session something starting with "restart", "fix", or "clean" — including trying to revive a stuck session by typing "restart sessions" — and got a confusing *"I didn't recognize that command"* reply (with a list that literally showed the command you typed), that message was being intercepted and never reached the session. That's fixed: those messages now go through to the session like any other. The "fix command" shortcuts (restart, fix auth, clean processes, …) still work — they just only apply in the Agent Attention topic, which is where I post the notifications you tap to resolve.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Fix-command shortcuts scoped to the Agent Attention topic | unchanged — tap/reply in the Attention topic; everywhere else your message reaches the session |
+| Ordinary "restart/fix/clean …" messages reach the session | just send them normally in any session topic |
+
+## Evidence
+
+Reproduction (live, 2026-06-09, topic 21624 "initiatives and maturation check-ins"): the user typed `restart sessions` to unstick a session and got *"I didn't recognize that command. Available fix commands: … • restart sessions — Restart stuck sessions"* — the gate swallowed the message (no `restart sessions` ever appeared in the session's tmux pane) while listing the exact command as valid. Root cause traced in code: the gate's `isFixCommand` verb test ran in all topics and `return`ed after `handleFixCommand` (which guards on `topicId === agent-attention-topic` and returns `false` otherwise).
+
+After the fix: new unit suite `tests/unit/fix-command-routing.test.ts` (17 tests) pins both sides of the boundary — in the attention topic every fix verb intercepts (and verb-lookalikes "fixture"/"cleanup" do not), while in a non-attention topic "restart sessions", "restart the build", "fix the login page", "clean up this function" all return `false` (fall through to the session); a null/undefined attention topic never intercepts. `tsc --noEmit` clean; the full set of unit tests importing `commands/server` (38 files, 364 tests) green.
+
+## The problem
+
+You sent a session a message to wake it up — "restart sessions" — and instead
+of doing anything, I replied *"I didn't recognize that command"* and showed you
+a list of commands that literally included "restart sessions." That's
+maddening: I rejected the exact thing I told you to type. Worse, your message
+never actually reached the session at all.
+
+Here's what was really happening under the hood.
+
+I have a set of emergency "fix command" shortcuts — short things you can type
+like "restart", "fix auth", "clean processes" — that I handle directly without
+spinning up a whole AI session. They exist for one specific place: the **Agent
+Attention topic**, where I post little "something needs fixing, tap to resolve"
+notifications. In that topic, typing "restart" should just work.
+
+The bug: the code that *catches* those shortcut words was running in **every
+topic**, not just the Attention topic. So any message you sent that happened to
+start with "restart", "fix ", or "clean " got grabbed by the shortcut-catcher
+first. The catcher then asked the real handler to run it — but the real handler
+checks "am I in the Attention topic?" and, if not, quietly says "not mine" and
+does nothing. At that point the catcher gave up with the confusing "I didn't
+recognize that command" message **and threw your message away** — it never got
+passed along to the session you were actually talking to.
+
+So two everyday things were broken:
+1. Trying to revive a stuck session by typing "restart sessions" in that
+   session's own topic — eaten, with a misleading reply.
+2. Just talking normally — "restart the build", "fix the login page", "clean up
+   this function" — anything that started with one of those words got silently
+   swallowed instead of reaching the session.
+
+## What already exists
+
+- The fix-command shortcuts ("restart", "fix auth", etc.) and the handler that
+  runs them. These were already correctly limited to the Attention topic *on
+  the execution side* — the handler refuses to act anywhere else.
+- The normal path that routes a message to its session. That path was always
+  there; the shortcut-catcher was just jumping in front of it and stopping it.
+
+## What's new
+
+One small, surgical change: the shortcut-catcher now checks **which topic it's
+in before grabbing the message.** It only intercepts inside the Agent Attention
+topic. Everywhere else, the message flows straight through to the session like
+any other message.
+
+The check is a tiny pure function, `shouldInterceptFixCommand(text, topicId,
+attentionTopicId)`, that returns "yes, intercept" only when the message is in
+the Attention topic AND looks like a fix command. It's covered by 17 unit tests
+that nail down both sides: in the Attention topic the shortcuts still fire (and
+lookalike words like "fixture" or "cleanup" correctly don't); in any other
+topic, "restart sessions" and friends fall through to the session.
+
+## The safeguards in plain terms
+
+- **Nothing is removed.** The fix-command shortcuts still work exactly as
+  before — they were always Attention-topic-only on the execution side; now the
+  catching side agrees. So no real capability is lost.
+- **Fail-safe default.** If I don't yet know which topic is the Attention topic
+  (e.g. very early at startup), the catcher simply doesn't intercept — messages
+  go to the session. That's the safe direction: route, don't swallow.
+- **It only makes the gate *less* aggressive.** This change can only let more
+  messages through to sessions; it can never block a message that wasn't already
+  being blocked. That's why the risk is low.
+
+## What you need to decide
+
+Nothing complicated. This is a bug fix that makes your messages reliably reach
+your sessions. The only judgment call is whether to ship it as a normal patch
+(yes) — there's no new setting to configure and no behavior you have to opt
+into. After it deploys, "restart sessions" (and ordinary chat starting with
+restart/fix/clean) will reach the session instead of being eaten.