@superblocksteam/vite-plugin-file-sync 1.99.99-next.2 → 2.0.0-SNAPSHOT.2143e2e95d0107ab

package/dist/ai-service/knowledge/knowledge-metrics-emitters.js

@@ -0,0 +1,77 @@
+import { FactAccessType } from "@superblocksteam/shared";
+import { recordKnowledgeIndexFacts, recordKnowledgeRead, resetKnowledgeReadTrackerForTurn, } from "./knowledge-metrics.js";
+function countOnDemandFacts(facts) {
+    return facts.filter((fact) => fact.accessType === FactAccessType.ON_DEMAND)
+        .length;
+}
+/** Matches `generateOnDemandFactsSkillIndex`: integration entries include all facts. */
+function countIntegrationIndexFacts(facts) {
+    return Object.values(facts.integrations).reduce((total, integrationFacts) => total + integrationFacts.length, 0);
+}
+function recordAlwaysInjectReads(layer, facts) {
+    for (const fact of facts) {
+        if (fact.accessType !== FactAccessType.ALWAYS_INJECT) {
+            continue;
+        }
+        recordKnowledgeRead({
+            accessType: "always_inject",
+            dedupeKey: fact.id,
+            layer,
+        });
+    }
+}
+/**
+ * Emit read and index metrics at the start of an LLM turn after facts are loaded.
+ */
+export function recordKnowledgeTurnLoadMetrics(input) {
+    resetKnowledgeReadTrackerForTurn();
+    recordAlwaysInjectReads("org", input.rpcFacts.org);
+    recordAlwaysInjectReads("user", input.rpcFacts.user);
+    for (const integrationFacts of Object.values(input.rpcFacts.integrations)) {
+        recordAlwaysInjectReads("integration", integrationFacts);
+    }
+    const indexCounts = {
+        integration: countIntegrationIndexFacts(input.rpcFacts),
+        org: countOnDemandFacts(input.rpcFacts.org),
+        user: countOnDemandFacts(input.rpcFacts.user),
+    };
+    if (input.appMetrics) {
+        for (const dedupeKey of input.appMetrics.alwaysInjectDedupeKeys) {
+            recordKnowledgeRead({
+                accessType: "always_inject",
+                dedupeKey,
+                layer: "app",
+            });
+        }
+        indexCounts.app = input.appMetrics.onDemandIndexCount;
+    }
+    else {
+        // Explicit zero so a failed load does not leave a stale app count from a
+        // prior turn (ObservableGauge only overwrites layers present in payload).
+        indexCounts.app = 0;
+    }
+    recordKnowledgeIndexFacts({ counts: indexCounts });
+}
+export function recordKnowledgeOnDemandRead(input) {
+    recordKnowledgeRead({
+        accessType: "on_demand",
+        dedupeKey: input.dedupeKey,
+        layer: input.layer,
+    });
+}
+export function isAppKnowledgeReadPath(filePath) {
+    return filePath.startsWith("skills/app/") && filePath.endsWith(".md");
+}
+export function appKnowledgeReadDedupeKey(filePath) {
+    return filePath;
+}
+export function recordAppKnowledgeReadIfApplicable(filePath) {
+    if (!isAppKnowledgeReadPath(filePath)) {
+        return;
+    }
+    recordKnowledgeOnDemandRead({
+        dedupeKey: appKnowledgeReadDedupeKey(filePath),
+        layer: "app",
+    });
+}
+//# sourceMappingURL=knowledge-metrics-emitters.js.map

package/dist/ai-service/knowledge/knowledge-metrics-emitters.js.map

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

package/dist/ai-service/knowledge/knowledge-metrics.d.ts

@@ -0,0 +1,44 @@
+export declare const KNOWLEDGE_LAYERS: readonly ["app", "integration", "org", "user"];
+export type KnowledgeLayer = (typeof KNOWLEDGE_LAYERS)[number];
+export declare const KNOWLEDGE_ACCESS_TYPES: readonly ["always_inject", "on_demand"];
+type KnowledgeAccessType = (typeof KNOWLEDGE_ACCESS_TYPES)[number];
+export declare const KNOWLEDGE_SUGGESTION_SOURCES: readonly ["remember_knowledge"];
+type KnowledgeSuggestionSource = (typeof KNOWLEDGE_SUGGESTION_SOURCES)[number];
+export declare const KNOWLEDGE_APPROVAL_PROMPT_TYPES: readonly ["confirm", "multi_choice", "remember_knowledge_draft"];
+type KnowledgeApprovalPromptType = (typeof KNOWLEDGE_APPROVAL_PROMPT_TYPES)[number];
+export declare const KNOWLEDGE_APPROVAL_OUTCOMES: readonly ["approved", "denied"];
+type KnowledgeApprovalOutcome = (typeof KNOWLEDGE_APPROVAL_OUTCOMES)[number];
+export declare const KNOWLEDGE_WRITE_SCOPES: readonly ["app", "integration", "org", "user"];
+export type KnowledgeWriteScope = (typeof KNOWLEDGE_WRITE_SCOPES)[number];
+export declare const KNOWLEDGE_WRITE_ACTIONS: readonly ["create", "delete", "update"];
+export type KnowledgeWriteAction = (typeof KNOWLEDGE_WRITE_ACTIONS)[number];
+export declare const KNOWLEDGE_WRITE_STATUSES: readonly ["created", "created_remote", "deleted", "failed", "skipped_not_found", "updated"];
+export type KnowledgeWriteStatus = (typeof KNOWLEDGE_WRITE_STATUSES)[number];
+export declare function resetKnowledgeReadTrackerForTurn(): void;
+export declare function recordKnowledgeRead(input: {
+    accessType: KnowledgeAccessType;
+    dedupeKey: string;
+    layer: KnowledgeLayer;
+}): void;
+export declare function recordKnowledgeIndexFacts(input: {
+    counts: Partial<Record<KnowledgeLayer, number>>;
+}): void;
+export declare function recordKnowledgeSuggestion(input: {
+    candidateCount: number;
+    source: KnowledgeSuggestionSource;
+}): void;
+export declare function recordKnowledgeDuplicateHint(): void;
+export declare function recordKnowledgeApprovalPrompt(input: {
+    promptType: KnowledgeApprovalPromptType;
+}): void;
+export declare function recordKnowledgeApprovalResponse(input: {
+    outcome: KnowledgeApprovalOutcome;
+}): void;
+export declare function recordKnowledgeWrite(input: {
+    action: KnowledgeWriteAction;
+    scope: KnowledgeWriteScope;
+    status: KnowledgeWriteStatus;
+}): void;
+export declare function _resetClarkKnowledgeMetricsForTesting(): void;
+export {};
+//# sourceMappingURL=knowledge-metrics.d.ts.map

package/dist/ai-service/knowledge/knowledge-metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-metrics.d.ts","sourceRoot":"","sources":["../../../src/ai-service/knowledge/knowledge-metrics.ts"],"names":[],"mappings":"AAoCA,eAAO,MAAM,gBAAgB,gDAAiD,CAAC;AAC/E,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/D,eAAO,MAAM,sBAAsB,yCAA0C,CAAC;AAC9E,KAAK,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnE,eAAO,MAAM,4BAA4B,iCAAkC,CAAC;AAC5E,KAAK,yBAAyB,GAAG,CAAC,OAAO,4BAA4B,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/E,eAAO,MAAM,+BAA+B,kEAIlC,CAAC;AACX,KAAK,2BAA2B,GAC9B,CAAC,OAAO,+BAA+B,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,eAAO,MAAM,2BAA2B,iCAAkC,CAAC;AAC3E,KAAK,wBAAwB,GAAG,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7E,eAAO,MAAM,sBAAsB,gDAKzB,CAAC;AACX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1E,eAAO,MAAM,uBAAuB,yCAA0C,CAAC;AAC/E,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E,eAAO,MAAM,wBAAwB,6FAO3B,CAAC;AACX,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAyM7E,wBAAgB,gCAAgC,IAAI,IAAI,CAEvD;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE;IACzC,UAAU,EAAE,mBAAmB,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,cAAc,CAAC;CACvB,GAAG,IAAI,CAEP;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE;IAC/C,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC,CAAC;CACjD,GAAG,IAAI,CAEP;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE;IAC/C,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,yBAAyB,CAAC;CACnC,GAAG,IAAI,CAEP;AAED,wBAAgB,4BAA4B,IAAI,IAAI,CAEnD;AAED,wBAAgB,6BAA6B,CAAC,KAAK,EAAE;IACnD,UAAU,EAAE,2BAA2B,CAAC;CACzC,GAAG,IAAI,CAEP;AAED,wBAAgB,+BAA+B,CAAC,KAAK,EAAE;IACrD,OAAO,EAAE,wBAAwB,CAAC;CACnC,GAAG,IAAI,CAEP;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,MAAM,EAAE,oBAAoB,CAAC;IAC7B,KAAK,EAAE,mBAAmB,CAAC;IAC3B,MAAM,EAAE,oBAAoB,CAAC;CAC9B,GAAG,IAAI,CAEP;AAED,wBAAgB,qCAAqC,IAAI,IAAI,CAE5D"}

package/dist/ai-service/knowledge/knowledge-metrics.js

@@ -0,0 +1,217 @@
+/**
+ * Clark knowledge lifecycle metrics (APPS-5064).
+ *
+ * Production counters/histograms/gauges for knowledge reads, the suggest→approve
+ * funnel, and writes. Complements retrieval spans from APPS-4708
+ * (`knowledge.facts`, `app_skills.load`).
+ *
+ * Wiring follows `ClarkContextMetrics` (APPS-4708): lazy meter resolution from
+ * the OTel global, instruments re-bound when the MeterProvider changes.
+ *
+ * Metrics:
+ *
+ *   - `superblocks.clark.knowledge.reads_total`              counter {layer, access_type}
+ *   - `superblocks.clark.knowledge.read_duplicates_total`    counter {layer}
+ *   - `superblocks.clark.knowledge.index_facts`              gauge     {layer}
+ *   - `superblocks.clark.knowledge.suggestions_total`        counter {source}
+ *   - `superblocks.clark.knowledge.suggestion_candidates`      histogram
+ *   - `superblocks.clark.knowledge.duplicate_hints_total`    counter
+ *   - `superblocks.clark.knowledge.approval_prompts_total`   counter {prompt_type}
+ *   - `superblocks.clark.knowledge.approval_responses_total` counter {outcome}
+ *   - `superblocks.clark.knowledge.writes_total`             counter {scope, action, status}
+ *
+ * Base cardinality budget (documented contract — growing an enum must be a
+ * deliberate, reviewed change; the regression test pins these counts):
+ *
+ *   reads(4×2) + read_duplicates(4) + index_facts(4) + suggestions(1) +
+ *   suggestion_candidates(1) + duplicate_hints(1) + approval_prompts(3) +
+ *   approval_responses(2) + writes(4×3×6) = 96 worst-case series.
+ */
+import { metrics, } from "@opentelemetry/api";
+export const KNOWLEDGE_LAYERS = ["app", "integration", "org", "user"];
+export const KNOWLEDGE_ACCESS_TYPES = ["always_inject", "on_demand"];
+export const KNOWLEDGE_SUGGESTION_SOURCES = ["remember_knowledge"];
+export const KNOWLEDGE_APPROVAL_PROMPT_TYPES = [
+    "confirm",
+    "multi_choice",
+    "remember_knowledge_draft",
+];
+export const KNOWLEDGE_APPROVAL_OUTCOMES = ["approved", "denied"];
+export const KNOWLEDGE_WRITE_SCOPES = [
+    "app",
+    "integration",
+    "org",
+    "user",
+];
+export const KNOWLEDGE_WRITE_ACTIONS = ["create", "delete", "update"];
+export const KNOWLEDGE_WRITE_STATUSES = [
+    "created",
+    "created_remote",
+    "deleted",
+    "failed",
+    "skipped_not_found",
+    "updated",
+];
+const METER_NAME = "superblocks.clark.knowledge";
+const METRIC_READS = "superblocks.clark.knowledge.reads_total";
+const METRIC_READ_DUPLICATES = "superblocks.clark.knowledge.read_duplicates_total";
+const METRIC_INDEX_FACTS = "superblocks.clark.knowledge.index_facts";
+const METRIC_SUGGESTIONS = "superblocks.clark.knowledge.suggestions_total";
+const METRIC_SUGGESTION_CANDIDATES = "superblocks.clark.knowledge.suggestion_candidates";
+const METRIC_DUPLICATE_HINTS = "superblocks.clark.knowledge.duplicate_hints_total";
+const METRIC_APPROVAL_PROMPTS = "superblocks.clark.knowledge.approval_prompts_total";
+const METRIC_APPROVAL_RESPONSES = "superblocks.clark.knowledge.approval_responses_total";
+const METRIC_WRITES = "superblocks.clark.knowledge.writes_total";
+const SUGGESTION_CANDIDATE_BUCKETS = [1, 2, 3, 5, 10, 20];
+class ClarkKnowledgeMetrics {
+    cachedInstruments;
+    cachedMeter;
+    indexFactCounts = new Map();
+    readKeysThisTurn = new Set();
+    observeIndexFacts = (result) => {
+        for (const [layer, value] of this.indexFactCounts.entries()) {
+            result.observe(value, { layer });
+        }
+    };
+    getInstruments() {
+        const meter = metrics.getMeter(METER_NAME);
+        if (meter === this.cachedMeter && this.cachedInstruments) {
+            return this.cachedInstruments;
+        }
+        this.cachedInstruments?.indexFactsGauge.removeCallback(this.observeIndexFacts);
+        this.cachedMeter = meter;
+        const indexFactsGauge = meter.createObservableGauge(METRIC_INDEX_FACTS, {
+            description: "Knowledge facts listed in the skill index at the last observed turn per layer (values persist until the next update for that layer). Org/user count on-demand entries only; integration counts all indexed integration facts.",
+            unit: "{fact}",
+        });
+        indexFactsGauge.addCallback(this.observeIndexFacts);
+        this.cachedInstruments = {
+            approvalPromptsCounter: meter.createCounter(METRIC_APPROVAL_PROMPTS, {
+                description: "Knowledge approval prompts shown to the user.",
+                unit: "{prompt}",
+            }),
+            approvalResponsesCounter: meter.createCounter(METRIC_APPROVAL_RESPONSES, {
+                description: "User responses to knowledge approval prompts.",
+                unit: "{response}",
+            }),
+            duplicateHintsCounter: meter.createCounter(METRIC_DUPLICATE_HINTS, {
+                description: "rememberKnowledge calls where recentlySavedMatches was non-empty.",
+                unit: "{hint}",
+            }),
+            indexFactsGauge,
+            readDuplicatesCounter: meter.createCounter(METRIC_READ_DUPLICATES, {
+                description: "Repeated reads of the same knowledge fact/path within one turn.",
+                unit: "{read}",
+            }),
+            readsCounter: meter.createCounter(METRIC_READS, {
+                description: "Knowledge surfaced into context via auto-inject or on-demand read.",
+                unit: "{read}",
+            }),
+            suggestionCandidatesHistogram: meter.createHistogram(METRIC_SUGGESTION_CANDIDATES, {
+                advice: { explicitBucketBoundaries: SUGGESTION_CANDIDATE_BUCKETS },
+                description: "Candidate count per rememberKnowledge call with valid candidates.",
+                unit: "{candidate}",
+            }),
+            suggestionsCounter: meter.createCounter(METRIC_SUGGESTIONS, {
+                description: "Valid knowledge suggestions from rememberKnowledge.",
+                unit: "{suggestion}",
+            }),
+            writesCounter: meter.createCounter(METRIC_WRITES, {
+                description: "Knowledge persistence attempts from saveKnowledgeAndNotify.",
+                unit: "{write}",
+            }),
+        };
+        return this.cachedInstruments;
+    }
+    resetReadTrackerForTurn() {
+        this.readKeysThisTurn.clear();
+    }
+    recordRead(input) {
+        const instruments = this.getInstruments();
+        const attributes = {
+            access_type: input.accessType,
+            layer: input.layer,
+        };
+        instruments.readsCounter.add(1, attributes);
+        const dedupeKey = `${input.layer}:${input.dedupeKey}`;
+        if (this.readKeysThisTurn.has(dedupeKey)) {
+            instruments.readDuplicatesCounter.add(1, { layer: input.layer });
+        }
+        else {
+            this.readKeysThisTurn.add(dedupeKey);
+        }
+    }
+    recordIndexFacts(input) {
+        this.getInstruments();
+        for (const layer of KNOWLEDGE_LAYERS) {
+            const count = input.counts[layer];
+            if (count === undefined) {
+                continue;
+            }
+            this.indexFactCounts.set(layer, Math.max(0, count));
+        }
+    }
+    recordSuggestion(input) {
+        const instruments = this.getInstruments();
+        instruments.suggestionsCounter.add(1, { source: input.source });
+        if (input.candidateCount > 0) {
+            instruments.suggestionCandidatesHistogram.record(input.candidateCount);
+        }
+    }
+    recordDuplicateHint() {
+        this.getInstruments().duplicateHintsCounter.add(1);
+    }
+    recordApprovalPrompt(input) {
+        this.getInstruments().approvalPromptsCounter.add(1, {
+            prompt_type: input.promptType,
+        });
+    }
+    recordApprovalResponse(input) {
+        this.getInstruments().approvalResponsesCounter.add(1, {
+            outcome: input.outcome,
+        });
+    }
+    recordWrite(input) {
+        this.getInstruments().writesCounter.add(1, {
+            action: input.action,
+            scope: input.scope,
+            status: input.status,
+        });
+    }
+    _resetForTesting() {
+        this.cachedInstruments?.indexFactsGauge.removeCallback(this.observeIndexFacts);
+        this.cachedMeter = undefined;
+        this.cachedInstruments = undefined;
+        this.indexFactCounts.clear();
+        this.readKeysThisTurn.clear();
+    }
+}
+const clarkKnowledgeMetrics = new ClarkKnowledgeMetrics();
+export function resetKnowledgeReadTrackerForTurn() {
+    clarkKnowledgeMetrics.resetReadTrackerForTurn();
+}
+export function recordKnowledgeRead(input) {
+    clarkKnowledgeMetrics.recordRead(input);
+}
+export function recordKnowledgeIndexFacts(input) {
+    clarkKnowledgeMetrics.recordIndexFacts(input);
+}
+export function recordKnowledgeSuggestion(input) {
+    clarkKnowledgeMetrics.recordSuggestion(input);
+}
+export function recordKnowledgeDuplicateHint() {
+    clarkKnowledgeMetrics.recordDuplicateHint();
+}
+export function recordKnowledgeApprovalPrompt(input) {
+    clarkKnowledgeMetrics.recordApprovalPrompt(input);
+}
+export function recordKnowledgeApprovalResponse(input) {
+    clarkKnowledgeMetrics.recordApprovalResponse(input);
+}
+export function recordKnowledgeWrite(input) {
+    clarkKnowledgeMetrics.recordWrite(input);
+}
+export function _resetClarkKnowledgeMetricsForTesting() {
+    clarkKnowledgeMetrics._resetForTesting();
+}
+//# sourceMappingURL=knowledge-metrics.js.map

package/dist/ai-service/knowledge/knowledge-metrics.js.map

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

package/dist/ai-service/live-edit-events/bridge.d.ts

@@ -0,0 +1,21 @@
+import type { LiveEditEventInput, LiveEditEventKind, LiveEditEventPayload } from "./forwarder.js";
+/**
+ * What the bridge needs of a forwarder. Narrow so Clark's call sites can be
+ * tested against a stub without standing up HTTP.
+ */
+export type LiveEditEventSink = {
+    enqueue: (input: LiveEditEventInput) => void;
+};
+export declare function setLiveEditEventForwarder(next: LiveEditEventSink): void;
+export declare function setGatewayTurnSource(source: () => string | undefined): void;
+/** Test seam; also the reset a fresh sandbox activation wants. */
+export declare function resetLiveEditEventForwarding(): void;
+/**
+ * Reports something Clark did to the Gateway turn that asked for it.
+ *
+ * Every Clark call site funnels through here, so it must never throw and never
+ * block: an unconfigured deployment, an editor-driven generation, and a
+ * wedged SABS all look the same from the caller's side, which is silence.
+ */
+export declare function emitLiveEditEvent(kind: LiveEditEventKind, payload: LiveEditEventPayload): void;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/ai-service/live-edit-events/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../../../src/ai-service/live-edit-events/bridge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACrB,MAAM,gBAAgB,CAAC;AAExB;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC;CAC9C,CAAC;AAsBF,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAEvE;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,MAAM,GAAG,SAAS,GAAG,IAAI,CAE3E;AAED,kEAAkE;AAClE,wBAAgB,4BAA4B,IAAI,IAAI,CAGnD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,iBAAiB,EACvB,OAAO,EAAE,oBAAoB,GAC5B,IAAI,CAaN"}

package/dist/ai-service/live-edit-events/bridge.js

@@ -0,0 +1,52 @@
+/**
+ * Process-wide, like the logger and the dev-server metrics: one sandbox serves
+ * one live edit, and Clark's emission sites are spread across the FSM,
+ * agent, and task layers with no shared object to thread this through.
+ */
+let sink;
+/**
+ * Reads the turn Gateway minted for the prompt in flight — the same correlator
+ * Task 3 hands to `beginHeadlessTurn`, not a second one.
+ *
+ * Deliberately a function rather than a stored id: `StablePeer` releases a turn
+ * from several paths, and a copy kept here would outlive some of them and
+ * attribute later work to a turn that has already finished.
+ *
+ * Undefined means no Gateway caller is waiting — an editor-driven generation —
+ * and nothing is forwarded.
+ */
+let gatewayTurnIdSource = () => undefined;
+export function setLiveEditEventForwarder(next) {
+    sink = next;
+}
+export function setGatewayTurnSource(source) {
+    gatewayTurnIdSource = source;
+}
+/** Test seam; also the reset a fresh sandbox activation wants. */
+export function resetLiveEditEventForwarding() {
+    sink = undefined;
+    gatewayTurnIdSource = () => undefined;
+}
+/**
+ * Reports something Clark did to the Gateway turn that asked for it.
+ *
+ * Every Clark call site funnels through here, so it must never throw and never
+ * block: an unconfigured deployment, an editor-driven generation, and a
+ * wedged SABS all look the same from the caller's side, which is silence.
+ */
+export function emitLiveEditEvent(kind, payload) {
+    try {
+        const gatewayTurnId = gatewayTurnIdSource();
+        if (!sink || !gatewayTurnId) {
+            return;
+        }
+        sink.enqueue({ gatewayTurnId, kind, payload });
+    }
+    catch {
+        // Swallowed on purpose. These call sites are inside Clark's own RPC paths
+        // and none of them wraps the call, so anything escaping here would fail
+        // the very turn this is only meant to report on. The forwarder counts its
+        // own drops; there is nothing useful to add per event.
+    }
+}
+//# sourceMappingURL=bridge.js.map

package/dist/ai-service/live-edit-events/bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.js","sourceRoot":"","sources":["../../../src/ai-service/live-edit-events/bridge.ts"],"names":[],"mappings":"AAcA;;;;GAIG;AACH,IAAI,IAAmC,CAAC;AAExC;;;;;;;;;;GAUG;AACH,IAAI,mBAAmB,GAA6B,GAAG,EAAE,CAAC,SAAS,CAAC;AAEpE,MAAM,UAAU,yBAAyB,CAAC,IAAuB;IAC/D,IAAI,GAAG,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,MAAgC;IACnE,mBAAmB,GAAG,MAAM,CAAC;AAC/B,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,4BAA4B;IAC1C,IAAI,GAAG,SAAS,CAAC;IACjB,mBAAmB,GAAG,GAAG,EAAE,CAAC,SAAS,CAAC;AACxC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAuB,EACvB,OAA6B;IAE7B,IAAI,CAAC;QACH,MAAM,aAAa,GAAG,mBAAmB,EAAE,CAAC;QAC5C,IAAI,CAAC,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YAC5B,OAAO;QACT,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,0EAA0E;QAC1E,wEAAwE;QACxE,0EAA0E;QAC1E,uDAAuD;IACzD,CAAC;AACH,CAAC"}

package/dist/ai-service/live-edit-events/forwarder.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Matches MaxEventsPerPublish in SABS (internal/handlers/liveedit/events.go).
+ * SABS rejects an oversized batch outright, so exceeding this loses every
+ * event in the batch rather than just the excess.
+ */
+export declare const MAX_EVENTS_PER_PUBLISH = 64;
+/**
+ * How many events may wait for a flush. A sandbox that cannot reach SABS must
+ * not grow a queue for the life of the session; past this point new events are
+ * dropped and counted.
+ */
+export declare const MAX_QUEUED_EVENTS = 512;
+/**
+ * Payload bounds and allowlists mirroring SABS (internal/gateway/event.go).
+ *
+ * SABS rejects the whole batch when a single event fails validation, so an
+ * event Clark can legitimately produce but SABS will not accept has to be
+ * caught here — otherwise one long message loses up to 63 unrelated events.
+ * Truncating a string keeps the event; a value outside an allowlist has no
+ * honest substitute, so that event is dropped and counted.
+ */
+export declare const MAX_IDENTIFIER_LEN = 128;
+export declare const MAX_LABEL_LEN = 512;
+export declare const MAX_TEXT_LEN = 8192;
+export declare const LIVE_EDIT_EVENT_KINDS: readonly ["auth_required", "chat_message", "generation_state", "progress"];
+export type LiveEditEventKind = (typeof LIVE_EDIT_EVENT_KINDS)[number];
+/**
+ * Kind-specific body. SABS rejects an event carrying a field its kind does not
+ * own, so each call site must set only its own.
+ */
+export type LiveEditEventPayload = {
+    hasError?: boolean;
+    hasSuggestions?: boolean;
+    label?: string;
+    messageId?: string;
+    messageType?: string;
+    reason?: string;
+    role?: string;
+    state?: string;
+    text?: string;
+};
+/**
+ * What a call site hands over. The forwarder supplies everything else: event
+ * id, sequence, occurrence time, and the identity the sandbox was started with.
+ */
+export type LiveEditEventInput = {
+    /**
+     * The turn Gateway minted for this prompt. An editor-driven generation has
+     * none, and is not forwarded: no Gateway caller is waiting on it, and
+     * attributing it to a turn that does not exist would be a lie.
+     */
+    gatewayTurnId: string | undefined;
+    kind: LiveEditEventKind;
+    payload: LiveEditEventPayload;
+};
+export type LiveEditEventForwarderConfig = {
+    applicationId: string;
+    liveEditId: string;
+    organizationId: string;
+    sabsBaseUrl: string;
+    /**
+     * Resolved per send, never captured. The edit-scoped JWT rotates while a
+     * sandbox is alive (the editor pushes a new one to `/_sb_update_token`), and
+     * a token captured at construction would start 401ing mid-session with every
+     * batch dropped.
+     */
+    token: () => string | undefined;
+};
+/**
+ * Reads the identity the sandbox was started with. Cold-start pods receive
+ * these as environment; warm pods have them written in at activation.
+ *
+ * Anything missing means this deployment does not run the push channel, which
+ * is a reason to stay quiet rather than to fail starting up.
+ *
+ * `token` is returned as a getter over the environment rather than a captured
+ * value, so a caller with a live source (the token manager) can override it
+ * and a caller without one still sees later writes to the variable.
+ */
+export declare function readForwarderConfigFromEnv(environment?: NodeJS.ProcessEnv): LiveEditEventForwarderConfig | undefined;
+/**
+ * Forwards what Clark reports inside a live-edit sandbox to SABS, which relays
+ * it to Gateway.
+ *
+ * Not the only way Gateway hears about a turn, and never was: a gateway peer
+ * holds its own socket here, and the headless turn bound to it routes Clark's
+ * pushes there as they happen. What this path adds is that it depends on
+ * neither that socket nor the process behind it. A socket that dies mid-turn,
+ * or a Gateway that restarts or scales out, leaves the stream this feeds as the
+ * only account of the build - which is why the turn Gateway holds in memory is
+ * an accelerator and this is the record.
+ *
+ * Delivery here is best-effort by design: Clark's own work must not slow down
+ * or fail because SABS is unreachable.
+ */
+export declare class LiveEditEventForwarder {
+    private readonly config;
+    private readonly fetchFn;
+    private readonly now;
+    private readonly uuid;
+    private closed;
+    private draining;
+    private droppedEvents;
+    private queue;
+    private sequence;
+    private timer;
+    constructor(deps: {
+        config: LiveEditEventForwarderConfig;
+        fetchFn?: typeof fetch;
+        now?: () => Date;
+        uuid?: () => string;
+    });
+    /**
+     * Hands an event over. Called from Clark's own paths, so it never throws and
+     * never waits: the worst it does is drop.
+     */
+    enqueue(input: LiveEditEventInput): void;
+    queueDepth(): number;
+    /** Cumulative events dropped over this forwarder's lifetime, by any reason. */
+    droppedCount(): number;
+    /**
+     * Sends everything queued, in batches SABS will accept. Never rejects.
+     *
+     * Flushes are chained rather than run concurrently: the size trigger and the
+     * timer can both fire, and putting two batches on the wire at once would let
+     * the later one arrive first.
+     */
+    flush(): Promise<void>;
+    /**
+     * Stops the timer, marks the forwarder closed (so anything offered from
+     * here on is dropped rather than queued), and flushes what was already
+     * queued before returning.
+     *
+     * A sandbox is torn down the moment its process exits, so a close() that
+     * discarded the queue outright lost whatever was waiting for the next
+     * timer tick without a trace. Flushing first gives that last batch the
+     * same best-effort delivery as any other.
+     */
+    close(): Promise<void>;
+    private arm;
+    private disarm;
+    /**
+     * Publishes one batch. Returns true when the batch was put back on the queue
+     * for a later retry (429/503), so the flush loop can stop spinning.
+     */
+    private publish;
+    /**
+     * Records a drop consistently: the metric (bounded, outcome-only labels),
+     * the running total exposed by {@link droppedCount}, and a single bounded
+     * warn log carrying the reason.
+     *
+     * Without the log, a live-edit session silently losing every event looked
+     * identical to one that simply had nothing to report; the metric alone
+     * required already knowing to look for it on a dashboard.
+     */
+    private recordDrop;
+}
+//# sourceMappingURL=forwarder.d.ts.map

package/dist/ai-service/live-edit-events/forwarder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forwarder.d.ts","sourceRoot":"","sources":["../../../src/ai-service/live-edit-events/forwarder.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAerC;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,MAAM,CAAC;AACtC,eAAO,MAAM,aAAa,MAAM,CAAC;AACjC,eAAO,MAAM,YAAY,OAAO,CAAC;AAcjC,eAAO,MAAM,qBAAqB,4EAKxB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAavE;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;;;OAIG;IACH,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,IAAI,EAAE,iBAAiB,CAAC;IACxB,OAAO,EAAE,oBAAoB,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG;IACzC,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,KAAK,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;CACjC,CAAC;AA8HF;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,GAAE,MAAM,CAAC,UAAwB,GAC3C,4BAA4B,GAAG,SAAS,CAmB1C;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;IACtD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAa;IACjC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;IAEpC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAoC;IACpD,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,KAAK,CAAqB;IAClC,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,KAAK,CAA6B;gBAE9B,IAAI,EAAE;QAChB,MAAM,EAAE,4BAA4B,CAAC;QACrC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;QACvB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;QACjB,IAAI,CAAC,EAAE,MAAM,MAAM,CAAC;KACrB;IAOD;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI;IA2CxC,UAAU,IAAI,MAAM;IAIpB,+EAA+E;IAC/E,YAAY,IAAI,MAAM;IAItB;;;;;;OAMG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAqB5B;;;;;;;;;OASG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B,OAAO,CAAC,GAAG;IAYX,OAAO,CAAC,MAAM;IAOd;;;OAGG;YACW,OAAO;IAkErB;;;;;;;;OAQG;IACH,OAAO,CAAC,UAAU;CAUnB"}