@vibesdotdev/external 0.0.0-stage → 1.0.0-rc.1

package/dist/ambient/cloud-touch-projection.impl.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Default `external/touch-projection` — batched, debounced, best-effort push
+ * of file touches to the platform, plus a bounded cross-machine read.
+ *
+ * THE RULES THIS FILE EXISTS TO KEEP
+ *
+ *  - NOTHING HERE MAY SLOW AN EDIT. `project()` is synchronous and returns
+ *    immediately; the flush happens on a timer. `peersForPath()` is time-boxed
+ *    well under the fs settle budget.
+ *  - OFFLINE IS A NORMAL STATE, NOT AN ERROR. No retries pile up, no queue
+ *    grows without bound, nothing is surfaced to the user. A machine that never
+ *    reaches the network keeps working with local-only collisions.
+ *  - ONLY EXPLICIT PATH/IDENTITY FIELDS LEAVE THE MACHINE. The payload is built
+ *    by picking fields through a `.strict()` schema — never by spreading a
+ *    record. Contents, diffs, and arbitrary metadata remain local.
+ *  - DISABLE-ABLE. No configured origin means this silently does nothing, which
+ *    is the zero-telemetry posture.
+ */
+import { type VibesRuntime } from '@vibesdotdev/kernel';
+import type { TouchPeer } from '../schemas/collision.ts';
+import { type ProjectedTouch, type TouchProjectionImplementation } from '../schemas/touch-projection.ts';
+import { type AmbientRuntime } from './cloud-authenticated-json.ts';
+export declare class CloudTouchProjection implements TouchProjectionImplementation {
+    private readonly runtime;
+    private queue;
+    private disposed;
+    /** The debounce timer, owned by the runtime's lifecycle (cleared on dispose). */
+    private timer;
+    private oldestQueuedAt;
+    private inFlight;
+    /** `runtime` is the one whose caller's bearer every request presents. */
+    constructor(runtime: AmbientRuntime);
+    project(touches: ProjectedTouch[]): void;
+    /**
+     * A flush nobody awaits (debounce or age trigger). Its failure is reported
+     * with its reason, never dropped as an unhandled rejection; the batch stays
+     * local, as an unauthenticated flush's does.
+     */
+    private flushInBackground;
+    dispose(): void;
+    flush(): Promise<void>;
+    peersForPath(input: {
+        filePath: string;
+        workspaceRoot?: string;
+        excludeSessionId: string;
+        since: Date;
+        limit?: number;
+    }): Promise<TouchPeer[]>;
+}
+/** Build the wire payload by PICKING fields — never by spreading a record. */
+export declare function toProjectedTouch(input: {
+    sessionId: string;
+    filePath: string;
+    operation: ProjectedTouch['operation'];
+    timestamp: Date;
+    machineId?: string;
+    machineName?: string;
+    participantId?: string;
+    participantSlug?: string;
+    workspaceRoot?: string;
+    gitBranch?: string;
+    workItemId?: string;
+    workItemTitle?: string;
+}): ProjectedTouch;
+/** One projector owned by the activated runtime client, shared across tool calls. */
+export declare function getCloudTouchProjection(runtime: VibesRuntime): CloudTouchProjection;
+/**
+ * Resolve the configured projection, falling back to the built-in cloud one
+ * when no provider is registered. A registered provider whose loader fails
+ * propagates: every caller reads through `attempt()`, so the edit stays local.
+ */
+export declare function resolveTouchProjection(runtime: VibesRuntime): Promise<TouchProjectionImplementation>;
+export default CloudTouchProjection;
+//# sourceMappingURL=cloud-touch-projection.impl.d.ts.map

package/dist/ambient/cloud-touch-projection.impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-touch-projection.impl.d.ts","sourceRoot":"","sources":["../../src/ambient/cloud-touch-projection.impl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,EAAkE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAEN,KAAK,cAAc,EACnB,KAAK,6BAA6B,EAClC,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAKN,KAAK,cAAc,EACnB,MAAM,+BAA+B,CAAC;AAmBvC,qBAAa,oBAAqB,YAAW,6BAA6B;IAS7D,OAAO,CAAC,QAAQ,CAAC,OAAO;IARpC,OAAO,CAAC,KAAK,CAAwB;IACrC,OAAO,CAAC,QAAQ,CAAS;IACzB,iFAAiF;IACjF,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,QAAQ,CAA8B;IAE9C,yEAAyE;gBAC5C,OAAO,EAAE,cAAc;IAEpD,OAAO,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,IAAI;IAyBxC;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAWzB,OAAO,IAAI,IAAI;IAQT,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA2CtB,YAAY,CAAC,KAAK,EAAE;QACzB,QAAQ,EAAE,MAAM,CAAC;QACjB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,gBAAgB,EAAE,MAAM,CAAC;QACzB,KAAK,EAAE,IAAI,CAAC;QACZ,KAAK,CAAC,EAAE,MAAM,CAAC;KACf,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;CAgDxB;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,cAAc,CAAC,WAAW,CAAC,CAAC;IACvC,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,cAAc,CAejB;AAED,qFAAqF;AACrF,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,YAAY,GAAG,oBAAoB,CAEnF;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC3C,OAAO,EAAE,YAAY,GACnB,OAAO,CAAC,6BAA6B,CAAC,CASxC;AAED,eAAe,oBAAoB,CAAC"}

package/dist/ambient/cloud-touch-projection.impl.js

@@ -0,0 +1,225 @@
+/**
+ * Default `external/touch-projection` — batched, debounced, best-effort push
+ * of file touches to the platform, plus a bounded cross-machine read.
+ *
+ * THE RULES THIS FILE EXISTS TO KEEP
+ *
+ *  - NOTHING HERE MAY SLOW AN EDIT. `project()` is synchronous and returns
+ *    immediately; the flush happens on a timer. `peersForPath()` is time-boxed
+ *    well under the fs settle budget.
+ *  - OFFLINE IS A NORMAL STATE, NOT AN ERROR. No retries pile up, no queue
+ *    grows without bound, nothing is surfaced to the user. A machine that never
+ *    reaches the network keeps working with local-only collisions.
+ *  - ONLY EXPLICIT PATH/IDENTITY FIELDS LEAVE THE MACHINE. The payload is built
+ *    by picking fields through a `.strict()` schema — never by spreading a
+ *    record. Contents, diffs, and arbitrary metadata remain local.
+ *  - DISABLE-ABLE. No configured origin means this silently does nothing, which
+ *    is the zero-telemetry posture.
+ */
+import { activeExternalClient } from "./pending-notices.js";
+import * as z from 'zod/v4';
+import { getLogger } from '@vibesdotdev/logging';
+import { CaughtFailureSchema, isCapabilityError } from '@vibesdotdev/kernel';
+import { ProjectedTouchSchema } from "../schemas/touch-projection.js";
+import { ambientProjectionOptedOut, requestAmbientJson, resolveAmbientBearer, resolveAmbientOrigin } from "./cloud-authenticated-json.js";
+/** Debounce window. Rapid editing produces ONE request, not one per keystroke. */
+const FLUSH_DEBOUNCE_MS = 2_000;
+/** Upper bound on how long a touch waits before being sent. */
+const MAX_BATCH_AGE_MS = 10_000;
+/** Never let an offline queue grow without bound; oldest are dropped. */
+const MAX_QUEUE = 200;
+/** The remote read is on the fs hot path. Give up fast and stay local. */
+const READ_TIMEOUT_MS = 400;
+/** The push is off the hot path but must not hang a process at exit. */
+const PUSH_TIMEOUT_MS = 5_000;
+const PROJECT_PATH = '/api/ambient/touches';
+const PEERS_PATH = '/api/ambient/peers';
+/** The peers envelope with entries still unvalidated: one corrupt row must not blind the reader. */
+const TouchPeersEnvelopeSchema = z.object({ peers: z.array(z.unknown()) });
+export class CloudTouchProjection {
+    runtime;
+    queue = [];
+    disposed = false;
+    /** The debounce timer, owned by the runtime's lifecycle (cleared on dispose). */
+    timer = null;
+    oldestQueuedAt = 0;
+    inFlight = null;
+    /** `runtime` is the one whose caller's bearer every request presents. */
+    constructor(runtime) {
+        this.runtime = runtime;
+    }
+    project(touches) {
+        if (this.disposed || touches.length === 0)
+            return;
+        // project() stays sync: queue and debounce. Opt-out, bearer, and origin
+        // are async and resolved at flush. A flush that sees `off` drops the
+        // batch without sending; a later `on` is picked up on the next flush.
+        if (this.queue.length === 0)
+            this.oldestQueuedAt = Date.now();
+        this.queue.push(...touches);
+        // Bounded queue. An agent editing offline for an hour must not grow a
+        // queue it will later dump in one enormous request.
+        if (this.queue.length > MAX_QUEUE) {
+            this.queue = this.queue.slice(-MAX_QUEUE);
+        }
+        const age = Date.now() - this.oldestQueuedAt;
+        if (age >= MAX_BATCH_AGE_MS) {
+            this.flushInBackground();
+            return;
+        }
+        this.timer?.();
+        this.timer = this.runtime.lifecycle.timeout(() => this.flushInBackground(), FLUSH_DEBOUNCE_MS);
+    }
+    /**
+     * A flush nobody awaits (debounce or age trigger). Its failure is reported
+     * with its reason, never dropped as an unhandled rejection; the batch stays
+     * local, as an unauthenticated flush's does.
+     */
+    flushInBackground() {
+        this.flush().catch((error) => {
+            const failure = CaughtFailureSchema.parse(error);
+            getLogger('external.ambient.projection', this.runtime).warn('touch projection flush failed', {
+                reason: isCapabilityError(failure) ? (failure.reason ?? 'unknown') : 'unknown',
+                error: failure instanceof Error ? failure.message : String(failure)
+            });
+            return failure;
+        });
+    }
+    dispose() {
+        this.disposed = true;
+        this.timer?.();
+        this.timer = null;
+        this.queue = [];
+        this.oldestQueuedAt = 0;
+    }
+    async flush() {
+        if (this.disposed)
+            return;
+        if (this.timer) {
+            this.timer();
+            this.timer = null;
+        }
+        if (await ambientProjectionOptedOut(this.runtime)) {
+            this.queue = [];
+            this.oldestQueuedAt = 0;
+            return;
+        }
+        if (this.inFlight)
+            return this.inFlight;
+        const batch = this.queue;
+        if (batch.length === 0)
+            return;
+        this.queue = [];
+        this.oldestQueuedAt = 0;
+        const origin = await resolveAmbientOrigin(this.runtime);
+        const token = await resolveAmbientBearer(this.runtime);
+        if (!origin || !token)
+            return;
+        this.inFlight = (async () => {
+            const result = await requestAmbientJson(this.runtime, PROJECT_PATH, {
+                method: 'POST',
+                body: { touches: batch },
+                timeoutMs: PUSH_TIMEOUT_MS
+            });
+            if (!result.ok) {
+                // Deliberately NOT re-queued. A retry storm after an outage is
+                // worse than a gap in an ephemeral, rolling window.
+                getLogger('external.ambient.projection', this.runtime).debug('touch projection dropped a batch (offline or rejected)', {
+                    count: batch.length,
+                    status: result.status,
+                    error: result.failure
+                });
+            }
+        })().finally(() => {
+            this.inFlight = null;
+        });
+        return this.inFlight;
+    }
+    async peersForPath(input) {
+        if (await ambientProjectionOptedOut(this.runtime))
+            return [];
+        const origin = await resolveAmbientOrigin(this.runtime);
+        const token = await resolveAmbientBearer(this.runtime);
+        if (!origin || !token)
+            return [];
+        const now = Date.now();
+        const response = await requestAmbientJson(this.runtime, PEERS_PATH, {
+            method: 'POST',
+            body: {
+                filePath: input.filePath,
+                workspaceRoot: input.workspaceRoot,
+                excludeSessionId: input.excludeSessionId,
+                sinceMs: Math.max(1, now - input.since.getTime()),
+                limit: input.limit ?? 8
+            },
+            timeoutMs: READ_TIMEOUT_MS
+        });
+        const body = response.ok ? response.body : null;
+        const envelope = TouchPeersEnvelopeSchema.safeParse(body);
+        const raw = envelope.success ? envelope.data.peers : [];
+        const peers = [];
+        for (const entry of raw) {
+            const parsed = ProjectedTouchSchema.safeParse(entry);
+            if (!parsed.success)
+                continue;
+            const touch = parsed.data;
+            // Trust nothing from the wire about identity we can check locally.
+            if (touch.sessionId === input.excludeSessionId)
+                continue;
+            peers.push({
+                sessionId: touch.sessionId,
+                machineId: touch.machineId,
+                machineName: touch.machineName,
+                participantId: touch.participantId,
+                participantSlug: touch.participantSlug,
+                workspaceRoot: touch.workspaceRoot,
+                gitBranch: touch.gitBranch,
+                workItemId: touch.workItemId,
+                workItemTitle: touch.workItemTitle,
+                operation: touch.operation,
+                filePath: touch.filePath,
+                timestamp: touch.timestamp,
+                ageMs: Math.max(0, now - touch.timestamp.getTime()),
+                origin: 'remote'
+            });
+        }
+        return peers;
+    }
+}
+/** Build the wire payload by PICKING fields — never by spreading a record. */
+export function toProjectedTouch(input) {
+    return ProjectedTouchSchema.parse({
+        sessionId: input.sessionId,
+        filePath: input.filePath,
+        operation: input.operation,
+        timestamp: input.timestamp,
+        machineId: input.machineId,
+        machineName: input.machineName,
+        participantId: input.participantId,
+        participantSlug: input.participantSlug,
+        workspaceRoot: input.workspaceRoot,
+        gitBranch: input.gitBranch,
+        workItemId: input.workItemId,
+        workItemTitle: input.workItemTitle
+    });
+}
+/** One projector owned by the activated runtime client, shared across tool calls. */
+export function getCloudTouchProjection(runtime) {
+    return activeExternalClient(runtime).getCloudTouchProjection();
+}
+/**
+ * Resolve the configured projection, falling back to the built-in cloud one
+ * when no provider is registered. A registered provider whose loader fails
+ * propagates: every caller reads through `attempt()`, so the edit stays local.
+ */
+export async function resolveTouchProjection(runtime) {
+    const provided = runtime.hasKind('external/touch-projection') &&
+        runtime.query('external/touch-projection').descriptors().length > 0;
+    if (!provided) {
+        getLogger('external.ambient.projection', runtime).debug('touch projection descriptor unresolved; using default');
+        return getCloudTouchProjection(runtime);
+    }
+    return runtime.query('external/touch-projection').resolve();
+}
+export default CloudTouchProjection;
+//# sourceMappingURL=cloud-touch-projection.impl.js.map

package/dist/ambient/cloud-touch-projection.impl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-touch-projection.impl.js","sourceRoot":"","sources":["../../src/ambient/cloud-touch-projection.impl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAA6C,MAAM,qBAAqB,CAAC;AAGxH,OAAO,EACN,oBAAoB,EAGpB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACN,yBAAyB,EACzB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EAEpB,MAAM,+BAA+B,CAAC;AAEvC,kFAAkF;AAClF,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAChC,+DAA+D;AAC/D,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAChC,yEAAyE;AACzE,MAAM,SAAS,GAAG,GAAG,CAAC;AACtB,0EAA0E;AAC1E,MAAM,eAAe,GAAG,GAAG,CAAC;AAC5B,wEAAwE;AACxE,MAAM,eAAe,GAAG,KAAK,CAAC;AAE9B,MAAM,YAAY,GAAG,sBAAsB,CAAC;AAC5C,MAAM,UAAU,GAAG,oBAAoB,CAAC;AAExC,oGAAoG;AACpG,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC;AAE3E,MAAM,OAAO,oBAAoB;IASH;IARrB,KAAK,GAAqB,EAAE,CAAC;IAC7B,QAAQ,GAAG,KAAK,CAAC;IACzB,iFAAiF;IACzE,KAAK,GAAwB,IAAI,CAAC;IAClC,cAAc,GAAG,CAAC,CAAC;IACnB,QAAQ,GAAyB,IAAI,CAAC;IAE9C,yEAAyE;IACzE,YAA6B,OAAuB;QAAvB,YAAO,GAAP,OAAO,CAAgB;IAAG,CAAC;IAExD,OAAO,CAAC,OAAyB;QAChC,IAAI,IAAI,CAAC,QAAQ,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAClD,wEAAwE;QACxE,qEAAqE;QACrE,sEAAsE;QAEtE,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC9D,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC;QAE5B,sEAAsE;QACtE,oDAAoD;QACpD,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC;YACnC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,CAAC;QAC3C,CAAC;QAED,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,cAAc,CAAC;QAC7C,IAAI,GAAG,IAAI,gBAAgB,EAAE,CAAC;YAC7B,IAAI,CAAC,iBAAiB,EAAE,CAAC;YACzB,OAAO;QACR,CAAC;QAED,IAAI,CAAC,KAAK,EAAE,EAAE,CAAC;QACf,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,iBAAiB,EAAE,EAAE,iBAAiB,CAAC,CAAC;IAChG,CAAC;IAED;;;;OAIG;IACK,iBAAiB;QACxB,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YACrC,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YACjD,SAAS,CAAC,6BAA6B,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,+BAA+B,EAAE;gBAC5F,MAAM,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS;gBAC9E,KAAK,EAAE,OAAO,YAAY,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;aACnE,CAAC,CAAC;YACH,OAAO,OAAO,CAAC;QAChB,CAAC,CAAC,CAAC;IACJ,CAAC;IAED,OAAO;QACN,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,IAAI,CAAC,KAAK,EAAE,EAAE,CAAC;QACf,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;QAChB,IAAI,CAAC,cAAc,GAAG,CAAC,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,KAAK;QACV,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO;QAC1B,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAChB,IAAI,CAAC,KAAK,EAAE,CAAC;YACb,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QACnB,CAAC;QACD,IAAI,MAAM,yBAAyB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YACnD,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;YAChB,IAAI,CAAC,cAAc,GAAG,CAAC,CAAC;YACxB,OAAO;QACR,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAC,QAAQ,CAAC;QACxC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACzB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAC/B,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;QAChB,IAAI,CAAC,cAAc,GAAG,CAAC,CAAC;QAExB,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACxD,MAAM,KAAK,GAAG,MAAM,oBAAoB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACvD,IAAI,CAAC,MAAM,IAAI,CAAC,KAAK;YAAE,OAAO;QAE9B,IAAI,CAAC,QAAQ,GAAG,CAAC,KAAK,IAAI,EAAE;YAC3B,MAAM,MAAM,GAAG,MAAM,kBAAkB,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE;gBACnE,MAAM,EAAE,MAAM;gBACd,IAAI,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE;gBACxB,SAAS,EAAE,eAAe;aAC1B,CAAC,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;gBAChB,+DAA+D;gBAC/D,oDAAoD;gBACpD,SAAS,CAAC,6BAA6B,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,wDAAwD,EAAE;oBACtH,KAAK,EAAE,KAAK,CAAC,MAAM;oBACnB,MAAM,EAAE,MAAM,CAAC,MAAM;oBACrB,KAAK,EAAE,MAAM,CAAC,OAAO;iBACrB,CAAC,CAAC;YACJ,CAAC;QACF,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;YACjB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACtB,CAAC,CAAC,CAAC;QAEH,OAAO,IAAI,CAAC,QAAQ,CAAC;IACtB,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,KAMlB;QACA,IAAI,MAAM,yBAAyB,CAAC,IAAI,CAAC,OAAO,CAAC;YAAE,OAAO,EAAE,CAAC;QAC7D,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACxD,MAAM,KAAK,GAAG,MAAM,oBAAoB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACvD,IAAI,CAAC,MAAM,IAAI,CAAC,KAAK;YAAE,OAAO,EAAE,CAAC;QAEjC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,QAAQ,GAAG,MAAM,kBAAkB,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE;YACnE,MAAM,EAAE,MAAM;YACd,IAAI,EAAE;gBACL,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,aAAa,EAAE,KAAK,CAAC,aAAa;gBAClC,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;gBACxC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;gBACjD,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,CAAC;aACvB;YACD,SAAS,EAAE,eAAe;SAC1B,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;QAChD,MAAM,QAAQ,GAAG,wBAAwB,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC1D,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QAExD,MAAM,KAAK,GAAgB,EAAE,CAAC;QAC9B,KAAK,MAAM,KAAK,IAAI,GAAG,EAAE,CAAC;YACzB,MAAM,MAAM,GAAG,oBAAoB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YACrD,IAAI,CAAC,MAAM,CAAC,OAAO;gBAAE,SAAS;YAC9B,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC;YAC1B,mEAAmE;YACnE,IAAI,KAAK,CAAC,SAAS,KAAK,KAAK,CAAC,gBAAgB;gBAAE,SAAS;YACzD,KAAK,CAAC,IAAI,CAAC;gBACV,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,WAAW,EAAE,KAAK,CAAC,WAAW;gBAC9B,aAAa,EAAE,KAAK,CAAC,aAAa;gBAClC,eAAe,EAAE,KAAK,CAAC,eAAe;gBACtC,aAAa,EAAE,KAAK,CAAC,aAAa;gBAClC,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,UAAU,EAAE,KAAK,CAAC,UAAU;gBAC5B,aAAa,EAAE,KAAK,CAAC,aAAa;gBAClC,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,GAAG,KAAK,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;gBACnD,MAAM,EAAE,QAAQ;aAChB,CAAC,CAAC;QACJ,CAAC;QACD,OAAO,KAAK,CAAC;IACd,CAAC;CACD;AAED,8EAA8E;AAC9E,MAAM,UAAU,gBAAgB,CAAC,KAahC;IACA,OAAO,oBAAoB,CAAC,KAAK,CAAC;QACjC,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,aAAa,EAAE,KAAK,CAAC,aAAa;QAClC,eAAe,EAAE,KAAK,CAAC,eAAe;QACtC,aAAa,EAAE,KAAK,CAAC,aAAa;QAClC,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,aAAa,EAAE,KAAK,CAAC,aAAa;KAClC,CAAC,CAAC;AACJ,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,uBAAuB,CAAC,OAAqB;IAC5D,OAAO,oBAAoB,CAAC,OAAO,CAAC,CAAC,uBAAuB,EAAE,CAAC;AAChE,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC3C,OAAqB;IAErB,MAAM,QAAQ,GACb,OAAO,CAAC,OAAO,CAAC,2BAA2B,CAAC;QAC5C,OAAO,CAAC,KAAK,CAAC,2BAA2B,CAAC,CAAC,WAAW,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;IACrE,IAAI,CAAC,QAAQ,EAAE,CAAC;QACf,SAAS,CAAC,6BAA6B,EAAE,OAAO,CAAC,CAAC,KAAK,CAAC,uDAAuD,CAAC,CAAC;QACjH,OAAO,uBAAuB,CAAC,OAAO,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,OAAO,CAAC,KAAK,CAAmD,2BAA2B,CAAC,CAAC,OAAO,EAAE,CAAC;AAC/G,CAAC;AAED,eAAe,oBAAoB,CAAC"}

package/dist/ambient/collaboration-settings.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Collaboration settings: how the hook bridge turns a harness's native work
+ * into shared state (locks, notices, messages) and how often it nudges a
+ * self-review. They live in the `external` config manifest under
+ * `collaboration`; every field has a default, so a project that sets nothing
+ * gets the whole behavior.
+ */
+import * as z from 'zod/v4';
+import type { RuntimeRef } from '@vibesdotdev/kernel';
+/** Native edit tools of the supported harnesses: Claude Code, then Codex. */
+export declare const DEFAULT_NATIVE_EDIT_TOOLS: readonly ["Edit", "Write", "MultiEdit", "NotebookEdit", "apply_patch"];
+/** The self-review prompt descriptor a nudge injects unless configured otherwise. */
+export declare const DEFAULT_SELF_REVIEW_PROMPT_ID = "guardrails.self-review";
+export declare const CollaborationSettingsSchema: z.ZodObject<{
+    nativeEditLocks: z.ZodDefault<z.ZodBoolean>;
+    nativeEditLockConflict: z.ZodDefault<z.ZodEnum<{
+        notice: "notice";
+        refuse: "refuse";
+    }>>;
+    editTools: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    lockTtlMs: z.ZodOptional<z.ZodNumber>;
+    ambientDelivery: z.ZodDefault<z.ZodBoolean>;
+    selfReviewEveryEdits: z.ZodDefault<z.ZodNumber>;
+    selfReviewAtStop: z.ZodDefault<z.ZodBoolean>;
+    selfReviewPromptId: z.ZodDefault<z.ZodString>;
+    toolTiers: z.ZodPrefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        tier: z.ZodDefault<z.ZodEnum<{
+            default: "default";
+            full: "full";
+            minimal: "minimal";
+            recommended: "recommended";
+        }>>;
+        ceiling: z.ZodOptional<z.ZodEnum<{
+            0: "0";
+            1: "1";
+            3: "3";
+            "2a": "2a";
+            "2b": "2b";
+        }>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type CollaborationSettings = z.infer<typeof CollaborationSettingsSchema>;
+/**
+ * The collaboration settings on `runtime`: the `external` manifest's
+ * `collaboration` value parsed with its defaults, or the defaults alone when
+ * the runtime composes no `external` manifest.
+ */
+export declare function readCollaborationSettings(runtime: RuntimeRef): Promise<CollaborationSettings>;
+//# sourceMappingURL=collaboration-settings.d.ts.map

package/dist/ambient/collaboration-settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collaboration-settings.d.ts","sourceRoot":"","sources":["../../src/ambient/collaboration-settings.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAE5B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAKtD,6EAA6E;AAC7E,eAAO,MAAM,yBAAyB,wEAAyE,CAAC;AAEhH,qFAAqF;AACrF,eAAO,MAAM,6BAA6B,2BAA2B,CAAC;AAEtE,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2BtC,CAAC;AAEH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAKhF;;;;GAIG;AACH,wBAAsB,yBAAyB,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAMnG"}

package/dist/ambient/collaboration-settings.js

@@ -0,0 +1,57 @@
+/**
+ * Collaboration settings: how the hook bridge turns a harness's native work
+ * into shared state (locks, notices, messages) and how often it nudges a
+ * self-review. They live in the `external` config manifest under
+ * `collaboration`; every field has a default, so a project that sets nothing
+ * gets the whole behavior.
+ */
+import * as z from 'zod/v4';
+import { ConfigManifest } from '@vibesdotdev/config/manifest/config-manifest';
+/** Longest lease a hook-taken lock asks for (the lock registry's own maximum). */
+const MAX_HOOK_LOCK_TTL_MS = 4 * 60 * 60_000;
+/** Native edit tools of the supported harnesses: Claude Code, then Codex. */
+export const DEFAULT_NATIVE_EDIT_TOOLS = ['Edit', 'Write', 'MultiEdit', 'NotebookEdit', 'apply_patch'];
+/** The self-review prompt descriptor a nudge injects unless configured otherwise. */
+export const DEFAULT_SELF_REVIEW_PROMPT_ID = 'guardrails.self-review';
+export const CollaborationSettingsSchema = z.object({
+    /** A native edit takes (or renews) a workspace lock on each path it writes. */
+    nativeEditLocks: z.boolean().default(true),
+    /** When another participant holds a path the edit writes: `notice` lets the edit run and tells both sides; `refuse` stops it. */
+    nativeEditLockConflict: z.enum(['notice', 'refuse']).default('notice'),
+    /** Host tool names that write files. A tool input carrying an `apply_patch` envelope counts as an edit whatever its name. */
+    editTools: z.array(z.string().min(1)).default([...DEFAULT_NATIVE_EDIT_TOOLS]),
+    /** Lease window for a hook-taken lock; the lock registry's default when unset. */
+    lockTtlMs: z.number().int().positive().max(MAX_HOOK_LOCK_TTL_MS).optional(),
+    /** Hook responses carry the participant's pending messages and edit notices. */
+    ambientDelivery: z.boolean().default(true),
+    /** Nudge a self-review after this many native edits since the last one; 0 turns the edit cadence off. */
+    selfReviewEveryEdits: z.number().int().min(0).default(10),
+    /** At Stop, nudge a self-review when edits happened since the last one. */
+    selfReviewAtStop: z.boolean().default(true),
+    /** `tools/prompt` descriptor whose content is the self-review prompt. */
+    selfReviewPromptId: z.string().min(1).default(DEFAULT_SELF_REVIEW_PROMPT_ID),
+    /**
+     * Tier enforcement on the harness's own tool calls: when `enabled`, PreToolUse and PostToolUse run the
+     * `tools/tool` tier subscribers against the Vibes tool a host tool name resolves to, under `tier` and
+     * `ceiling` (absent: the agent default ceiling). Off by default.
+     */
+    toolTiers: z.object({
+        enabled: z.boolean().default(false),
+        tier: z.enum(['minimal', 'default', 'recommended', 'full']).default('default'),
+        ceiling: z.enum(['0', '1', '2a', '2b', '3']).optional()
+    }).prefault({})
+});
+/** The `external` manifest slice this module reads. */
+const ExternalCollaborationSliceSchema = z.object({ collaboration: z.unknown().optional() });
+/**
+ * The collaboration settings on `runtime`: the `external` manifest's
+ * `collaboration` value parsed with its defaults, or the defaults alone when
+ * the runtime composes no `external` manifest.
+ */
+export async function readCollaborationSettings(runtime) {
+    if (!ConfigManifest.isRegistered(runtime, 'external'))
+        return CollaborationSettingsSchema.parse({});
+    const loaded = ExternalCollaborationSliceSchema.parse(await ConfigManifest.forRuntime(runtime, 'external').load());
+    return CollaborationSettingsSchema.parse(loaded.collaboration ?? {});
+}
+//# sourceMappingURL=collaboration-settings.js.map

package/dist/ambient/collaboration-settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collaboration-settings.js","sourceRoot":"","sources":["../../src/ambient/collaboration-settings.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,MAAM,8CAA8C,CAAC;AAG9E,kFAAkF;AAClF,MAAM,oBAAoB,GAAG,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC;AAE7C,6EAA6E;AAC7E,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,aAAa,CAAU,CAAC;AAEhH,qFAAqF;AACrF,MAAM,CAAC,MAAM,6BAA6B,GAAG,wBAAwB,CAAC;AAEtE,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IACnD,+EAA+E;IAC/E,eAAe,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IAC1C,iIAAiI;IACjI,sBAAsB,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IACtE,6HAA6H;IAC7H,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,yBAAyB,CAAC,CAAC;IAC7E,kFAAkF;IAClF,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC,QAAQ,EAAE;IAC3E,gFAAgF;IAChF,eAAe,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IAC1C,yGAAyG;IACzG,oBAAoB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACzD,2EAA2E;IAC3E,gBAAgB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3C,yEAAyE;IACzE,kBAAkB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,6BAA6B,CAAC;IAC5E;;;;OAIG;IACH,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC;QACnB,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;QACnC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;QAC9E,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE;KACvD,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;CACf,CAAC,CAAC;AAIH,uDAAuD;AACvD,MAAM,gCAAgC,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;AAE7F;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAAC,OAAmB;IAClE,IAAI,CAAC,cAAc,CAAC,YAAY,CAAC,OAAO,EAAE,UAAU,CAAC;QAAE,OAAO,2BAA2B,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACpG,MAAM,MAAM,GAAG,gCAAgC,CAAC,KAAK,CACpD,MAAM,cAAc,CAAC,UAAU,CAAmD,OAAO,EAAE,UAAU,CAAC,CAAC,IAAI,EAAE,CAC7G,CAAC;IACF,OAAO,2BAA2B,CAAC,KAAK,CAAC,MAAM,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC;AACtE,CAAC"}

package/dist/ambient/collision-notice.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The edit notice: who else recently changed the file this agent just changed.
+ *
+ * One reader for every surface that delivers it — the `workspace-fs` tool
+ * result (file-access-ambient.impl.ts) and the harness hook response
+ * (hook-delivery.ts) — so the peers, the filter, the duplicate-work line and
+ * the told-once dedupe cannot drift between them.
+ */
+import type { VibesRuntime } from '@vibesdotdev/kernel';
+import { type TouchPeer } from '../schemas/collision.ts';
+import { type AmbientFileAccessClient } from './file-access-shared.ts';
+/** Forget only this runtime's ephemeral collision delivery history. */
+export declare function resetAmbientDedupe(runtime: VibesRuntime): void;
+export declare function dedupeKey(sessionId: string, filePath: string, peerSessionId: string): string;
+/** What an edit of one path has to say, and how to record that it was said. */
+export interface CollisionNotice {
+    /** The peer line, with the duplicate-work line under it when there is one. */
+    readonly notice?: string;
+    /** Record the peers in `notice` as told; call only once the notice was delivered. */
+    markTold(): void;
+}
+/**
+ * The notice for this session's change of `filePath` (canonical): the fresh
+ * peers' line and the duplicate-work line. Empty when there is nothing new
+ * to say, which keeps a solo agent silent.
+ */
+export declare function collisionNotice(runtime: VibesRuntime, client: AmbientFileAccessClient, input: {
+    sessionId: string;
+    filePath: string;
+    workspaceRoot?: string;
+}): Promise<CollisionNotice>;
+/** Recent changers of a path, filtered for collisions, plus the unfiltered set. */
+export declare function collectPeers(runtime: VibesRuntime, client: AmbientFileAccessClient, input: {
+    sessionId: string;
+    filePath: string;
+    workspaceRoot?: string;
+}): Promise<{
+    peers: TouchPeer[];
+    candidates: TouchPeer[];
+}>;
+//# sourceMappingURL=collision-notice.d.ts.map

package/dist/ambient/collision-notice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collision-notice.d.ts","sourceRoot":"","sources":["../../src/ambient/collision-notice.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAKN,KAAK,SAAS,EACd,MAAM,yBAAyB,CAAC;AAKjC,OAAO,EAAsB,KAAK,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAG3F,uEAAuE;AACvE,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAE9D;AAED,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAE5F;AAED,+EAA+E;AAC/E,MAAM,WAAW,eAAe;IAC/B,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,qFAAqF;IACrF,QAAQ,IAAI,IAAI,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACpC,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,uBAAuB,EAC/B,KAAK,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GACpE,OAAO,CAAC,eAAe,CAAC,CA2B1B;AAED,mFAAmF;AACnF,wBAAsB,YAAY,CACjC,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,uBAAuB,EAC/B,KAAK,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GACpE,OAAO,CAAC;IAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IAAC,UAAU,EAAE,SAAS,EAAE,CAAA;CAAE,CAAC,CAoD1D"}

package/dist/ambient/collision-notice.js

@@ -0,0 +1,104 @@
+/**
+ * The edit notice: who else recently changed the file this agent just changed.
+ *
+ * One reader for every surface that delivers it — the `workspace-fs` tool
+ * result (file-access-ambient.impl.ts) and the harness hook response
+ * (hook-delivery.ts) — so the peers, the filter, the duplicate-work line and
+ * the told-once dedupe cannot drift between them.
+ */
+import { tryGetVibesClient } from '@vibesdotdev/kernel/client';
+import { activeExternalClient } from "./pending-notices.js";
+import { CollisionFilterSchema, DEFAULT_PEER_CAP, DEFAULT_RECENCY_WINDOW_MS, NoticeFormatterSchema } from "../schemas/collision.js";
+import { defaultCollisionFilter } from "./default-collision-filter.impl.js";
+import { defaultNoticeFormatter } from "./default-notice-formatter.impl.js";
+import { findSubsystemOverlaps, formatSubsystemOverlaps } from "./subsystem-overlap.impl.js";
+import { resolveTouchProjection } from "./cloud-touch-projection.impl.js";
+import { resolveAmbientImpl } from "./file-access-shared.js";
+import { attempt } from "./attempt.js";
+/** Forget only this runtime's ephemeral collision delivery history. */
+export function resetAmbientDedupe(runtime) {
+    tryGetVibesClient('external', runtime)?.collisionDedupe.clear();
+}
+export function dedupeKey(sessionId, filePath, peerSessionId) {
+    return `${sessionId}\u0000${filePath}\u0000${peerSessionId}`;
+}
+/**
+ * The notice for this session's change of `filePath` (canonical): the fresh
+ * peers' line and the duplicate-work line. Empty when there is nothing new
+ * to say, which keeps a solo agent silent.
+ */
+export async function collisionNotice(runtime, client, input) {
+    const { peers, candidates } = await collectPeers(runtime, client, input);
+    // Duplicate-work signal, computed from the peers the collision filter drops.
+    const overlapContext = { sessionId: input.sessionId };
+    if (input.workspaceRoot)
+        overlapContext.workspaceRoot = input.workspaceRoot;
+    const overlapLine = formatSubsystemOverlaps(findSubsystemOverlaps(candidates, [input.filePath], overlapContext));
+    const silent = overlapLine ? { notice: overlapLine, markTold() { } } : { markTold() { } };
+    const told = activeExternalClient(runtime).collisionDedupe;
+    const fresh = peers.filter((peer) => !told.has(dedupeKey(input.sessionId, input.filePath, peer.sessionId)));
+    if (fresh.length === 0)
+        return silent;
+    const formatter = await resolveAmbientImpl(runtime, 'external/notice-formatter', NoticeFormatterSchema, defaultNoticeFormatter);
+    const lineOutcome = await attempt(runtime, async () => formatter.format(fresh, { filePath: input.filePath, cap: DEFAULT_PEER_CAP, now: new Date() }));
+    const line = lineOutcome.ok ? lineOutcome.value : undefined;
+    // A formatter returning null means "say nothing" — honored, not overridden.
+    if (!line)
+        return silent;
+    return {
+        notice: overlapLine ? `${line}\n${overlapLine}` : line,
+        markTold() {
+            for (const peer of fresh)
+                told.add(dedupeKey(input.sessionId, input.filePath, peer.sessionId));
+        }
+    };
+}
+/** Recent changers of a path, filtered for collisions, plus the unfiltered set. */
+export async function collectPeers(runtime, client, input) {
+    const now = new Date();
+    const since = new Date(now.getTime() - DEFAULT_RECENCY_WINDOW_MS);
+    // Local and remote are read CONCURRENTLY. The remote leg is time-boxed
+    // inside the projection, so a slow or offline network costs the local
+    // answer nothing — the notice simply degrades to same-machine peers.
+    const [localOutcome, remoteOutcome] = await Promise.all([
+        attempt(runtime, () => client.whoElseTouched({
+            filePath: input.filePath,
+            workspaceRoot: input.workspaceRoot,
+            excludeSessionId: input.sessionId,
+            since,
+            limit: DEFAULT_PEER_CAP + 5
+        })),
+        attempt(runtime, async () => {
+            const projection = await resolveTouchProjection(runtime);
+            return projection.peersForPath({
+                filePath: input.filePath,
+                workspaceRoot: input.workspaceRoot,
+                excludeSessionId: input.sessionId,
+                since,
+                limit: DEFAULT_PEER_CAP + 5
+            });
+        })
+    ]);
+    // Merge, LOCAL WINS per session: the same session can appear in both legs
+    // (it projected what it also wrote locally), and the local row is the
+    // authoritative, freshest copy.
+    const local = localOutcome.ok ? localOutcome.value : [];
+    const remote = remoteOutcome.ok ? remoteOutcome.value : [];
+    const bySession = new Map();
+    for (const peer of remote)
+        bySession.set(peer.sessionId, peer);
+    for (const peer of local)
+        bySession.set(peer.sessionId, peer);
+    const candidates = Array.from(bySession.values());
+    if (candidates.length === 0)
+        return { peers: [], candidates: [] };
+    const filter = await resolveAmbientImpl(runtime, 'external/collision-filter', CollisionFilterSchema, defaultCollisionFilter);
+    const filterOutcome = await attempt(runtime, async () => filter.filter(candidates, { sessionId: input.sessionId, workspaceRoot: input.workspaceRoot, since, now }));
+    const peers = filterOutcome.ok ? filterOutcome.value : [];
+    // The unfiltered set comes back too. `defaultCollisionFilter` deliberately
+    // drops different-worktree peers — right for "are we clobbering each other",
+    // wrong for "are we building this twice" (#293). That dropped set is exactly
+    // the duplicate-work signal, so it must survive the call.
+    return { peers, candidates };
+}
+//# sourceMappingURL=collision-notice.js.map

package/dist/ambient/collision-notice.js.map

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

package/dist/ambient/default-collision-filter.impl.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Default `external/collision-filter`.
+ *
+ * Decides which peer touches are worth a line in the agent's context. Swap this
+ * descriptor to widen (directory-level), narrow (same-symbol), or apply a house
+ * policy — without forking the touch stream.
+ *
+ * The read (`ExternalClient.whoElseTouched`) has already applied the structural
+ * rules: other sessions only, same workspace, inside the window, one entry per
+ * peer. This filter is the LAST word before a notice is rendered, and its job
+ * is to be conservative.
+ *
+ * A filter may only REMOVE or REORDER. Fabricating a peer here would make the
+ * notice lie, and there is no enforcement anywhere in this design to catch it.
+ */
+import type { CollisionFilterImplementation } from '../schemas/collision.ts';
+export declare const defaultCollisionFilter: CollisionFilterImplementation;
+export default defaultCollisionFilter;
+//# sourceMappingURL=default-collision-filter.impl.d.ts.map

package/dist/ambient/default-collision-filter.impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-collision-filter.impl.d.ts","sourceRoot":"","sources":["../../src/ambient/default-collision-filter.impl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAEX,6BAA6B,EAE7B,MAAM,yBAAyB,CAAC;AAWjC,eAAO,MAAM,sBAAsB,EAAE,6BA8BpC,CAAC;AAEF,eAAe,sBAAsB,CAAC"}