instar 1.3.442 → 1.3.444

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/LlmIntentClassifier.d.ts

@@ -0,0 +1,77 @@
+/**
+ * LlmIntentClassifier — the JUDGMENT-BAND intent classifier (Slack permission gate,
+ * Pillar 2, §6.5–6.6 / §6.6 "Layer 1 INTENT + SENSITIVITY").
+ *
+ * It implements the SAME `IntentClassifier` interface as `HeuristicIntentClassifier`
+ * and is interchangeable with it at the gate's `classifier` slot. The difference is
+ * the judgment band ABOVE the floor: an LLM call refines the sensitivity tier,
+ * directedness, and a non-floor action label more accurately than keyword matching.
+ *
+ * ── Two invariants this class is built around ──────────────────────────────────
+ *
+ * 1. THE FLOOR STAYS DETERMINISTIC. This class NEVER lets the LLM decide that a
+ *    floor action ISN'T one, and it never lets the LLM downgrade a heuristic-detected
+ *    floor candidate. It runs the deterministic `HeuristicIntentClassifier` FIRST;
+ *    when the heuristic flags a real floor action (a `floorAction`) OR the
+ *    ambiguous-deploy low-confidence case (action 'ambiguous', tier 4, low
+ *    confidence → the gate routes to CLARIFY), that verdict is returned AS-IS and the
+ *    LLM is never consulted. The LLM can only refine the NON-floor judgment band.
+ *    (Floor enumeration + role authority remain in RolePolicy / SlackPermissionGate;
+ *    this class only feeds them an intent and must not be the thing that misses a
+ *    floor action.)
+ *
+ * 2. NO SILENT DEGRADATION TO A BRITTLE — OR WIDER — FALLBACK
+ *    (docs/specs/no-silent-degradation-to-brittle-fallback.md,
+ *     docs/signal-vs-authority.md). On ANY LLM failure (no provider, throw, timeout,
+ *    empty/unparseable response, or a response that would WIDEN access beyond the
+ *    deterministic floor read) we fall back to the `HeuristicIntentClassifier`
+ *    result — which itself routes ambiguity to a tier-4 low-confidence 'ambiguous'
+ *    (→ the gate CLARIFIES, a safe non-allow). A classification failure must NEVER
+ *    return a confident low-tier "allow"-shaped intent on what might be sensitive.
+ *    The fallback is therefore at-least-as-conservative as the deterministic floor.
+ *
+ * The LLM is reached through instar's internal `IntelligenceProvider` (the same
+ * injected-provider pattern as `TopicIntentExtractor` / `MessagingToneGate`), NOT a
+ * raw API call. A `fast` model tier is used, and the call is marked `gating: true`
+ * so the IntelligenceRouter will provider-swap on failure before the error
+ * propagates (and we then fail closed to the heuristic).
+ *
+ * Design: docs/specs/SLACK-ORG-INTEGRATION-SPEC.md §6.5–6.6.
+ */
+import type { IntelligenceProvider } from '../core/types.js';
+import type { RequestIntent } from './types.js';
+import { type IntentClassifier } from './IntentClassifier.js';
+/** Observability hook reasons for why a classification fell back to the heuristic. */
+export type LlmIntentDegradeReason = 'no-intelligence' | 'error' | 'unparseable' | 'floor-deterministic';
+export interface LlmIntentClassifierDeps {
+    /**
+     * The internal LLM provider (injected — never a direct framework import). When
+     * absent, every classification degrades to the heuristic (fail-closed).
+     */
+    intelligence?: IntelligenceProvider;
+    /**
+     * The deterministic floor + fallback classifier. Defaults to a fresh
+     * `HeuristicIntentClassifier`. Injectable for tests.
+     */
+    heuristic?: IntentClassifier;
+    /** Per-call timeout for the LLM (ms). Default 8000. */
+    timeoutMs?: number;
+    /**
+     * Optional observability hook — fires on every degrade-to-heuristic path with the
+     * reason. Best-effort: it never affects the returned verdict (which is always the
+     * safe heuristic result on degrade).
+     */
+    onDegrade?: (reason: LlmIntentDegradeReason) => void;
+}
+export declare class LlmIntentClassifier implements IntentClassifier {
+    private readonly intelligence?;
+    private readonly heuristic;
+    private readonly timeoutMs;
+    private readonly onDegrade?;
+    constructor(deps?: LlmIntentClassifierDeps);
+    classify(text: string, ctx: {
+        directed: boolean;
+    }): Promise<RequestIntent>;
+    private report;
+}
+//# sourceMappingURL=LlmIntentClassifier.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"LlmIntentClassifier.d.ts","sourceRoot":"","sources":["../../src/permissions/LlmIntentClassifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAmB,MAAM,YAAY,CAAC;AACjE,OAAO,EAA6B,KAAK,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzF,sFAAsF;AACtF,MAAM,MAAM,sBAAsB,GAC9B,iBAAiB,GACjB,OAAO,GACP,aAAa,GACb,qBAAqB,CAAC;AAE1B,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,YAAY,CAAC,EAAE,oBAAoB,CAAC;IACpC;;;OAGG;IACH,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,sBAAsB,KAAK,IAAI,CAAC;CACtD;AAYD,qBAAa,mBAAoB,YAAW,gBAAgB;IAC1D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAuB;IACrD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmB;IAC7C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAA2C;gBAE1D,IAAI,GAAE,uBAA4B;IAOxC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,aAAa,CAAC;IA0DhF,OAAO,CAAC,MAAM;CAOf"}