@relayfile/sdk 0.7.10 → 0.7.12

package/README.md

@@ -81,7 +81,11 @@ import { RelayFileClient } from "@relayfile/sdk";
 
 const client = new RelayFileClient({
   baseUrl: "https://api.relayfile.com",
-  token: process.env.RELAYFILE_TOKEN ?? ""
+  token: process.env.RELAYFILE_TOKEN ?? "",
+  changeLog: {
+    retentionMs: 7 * 24 * 60 * 60 * 1000,
+    maxEntries: 10_000
+  }
 });
 
 const workspaceId = "workspace_123";
@@ -108,6 +112,8 @@ await client.writeFile({
 
 Use a relayfile JWT whose claims include `workspace_id`, `agent_name`, and `aud: ["relayfile"]`. The SDK adds `X-Correlation-Id` automatically for API calls.
 
+The optional `changeLog` block configures the SDK's local per-workspace retained-change mirror used by `subscribe()`, `open({ replayOnStart })`, and `getResourceAtEvent(eventId)`. Durable retention still lives on the Relayfile backend.
+
 ## Full Docs
 
 Full documentation is available in the [relayfile docs](https://github.com/AgentWorkforce/relayfile/tree/main/docs).

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { type AdminIngressStatusResponse, type AdminSyncStatusResponse, type BulkWriteInput, type BulkWriteResponse, type BackendStatusResponse, type AckResponse, type CommitForkInput, type CommitForkResponse, type CreateForkInput, type DeleteFileInput, type DeadLetterItem, type DeadLetterFeedResponse, type DiscardForkInput, type EventFeedResponse, type ExportJsonResponse, type ExportOptions, type FileQueryResponse, type FileReadResponse, type FilesystemEvent, type GetEventsOptions, type GetAdminIngressStatusOptions, type GetAdminSyncStatusOptions, type GetOperationsOptions, type GetSyncDeadLettersOptions, type GetSyncIngressStatusOptions, type GetSyncStatusOptions, type ListTreeOptions, type OperationFeedResponse, type OperationStatusResponse, type QueuedResponse, type ReadFileInput, type QueryFilesOptions, type SyncIngressStatusResponse, type SyncStatusResponse, type TreeResponse, type WriteFileInput, type WriteQueuedResponse, type IngestWebhookInput, type WritebackItem, type AckWritebackInput, type AckWritebackResponse } from "./types.js";
+import { type AdminIngressStatusResponse, type AdminSyncStatusResponse, type BulkWriteInput, type BulkWriteResponse, type BackendStatusResponse, type AckResponse, type CommitForkInput, type CommitForkResponse, type CreateForkInput, type DeleteFileInput, type DeadLetterItem, type DeadLetterFeedResponse, type DiscardForkInput, type EventFeedResponse, type ExportJsonResponse, type ExportOptions, type FileQueryResponse, type FileReadResponse, type FilesystemEvent, type GetEventsOptions, type GetAdminIngressStatusOptions, type GetAdminSyncStatusOptions, type GetOperationsOptions, type GetSyncDeadLettersOptions, type GetSyncIngressStatusOptions, type GetSyncStatusOptions, type ListTreeOptions, type OperationFeedResponse, type OperationStatusResponse, type QueuedResponse, type ResourceAtEventResult, type ReadFileInput, type QueryFilesOptions, type Subscription, type SyncIngressStatusResponse, type SyncStatusResponse, type TreeResponse, type WriteFileInput, type WriteQueuedResponse, type IngestWebhookInput, type WritebackItem, type AckWritebackInput, type AckWritebackResponse, type ChangeEvent, type ChangeLogQueryResult, type ChangeStreamConnection, type ChangeStreamConnectionOptions, type SubscribeOptions } from "./types.js";
 import type { ForkHandle } from "@relayfile/core";
 /**
  * Bearer token or token factory used for Relayfile API requests.
@@ -13,6 +13,18 @@ export interface RelayFileRetryOptions {
     maxDelayMs?: number;
     jitterRatio?: number;
 }
+export interface RelayFileChangeLogOptions {
+    /**
+     * Local retained-change cache TTL in milliseconds.
+     *
+     * This mirrors the backend retention window opportunistically for delivered
+     * or replayed events; durable change-log retention remains a server-side
+     * responsibility.
+     */
+    retentionMs?: number;
+    /** Maximum number of retained change entries to keep per workspace locally. */
+    maxEntries?: number;
+}
 /** Default base URL for the hosted Relayfile API */
 export declare const DEFAULT_RELAYFILE_BASE_URL = "https://api.relayfile.dev";
 export interface RelayFileClientOptions {
@@ -28,6 +40,7 @@ export interface RelayFileClientOptions {
     fetchImpl?: typeof fetch;
     userAgent?: string;
     retry?: RelayFileRetryOptions;
+    changeLog?: RelayFileChangeLogOptions;
 }
 type WebSocketEventName = "event" | "error" | "open" | "close";
 type WebSocketHandlerMap = {
@@ -44,6 +57,10 @@ export interface ConnectWebSocketOptions {
     token?: string;
     onEvent?: (event: FilesystemEvent) => void;
 }
+interface ProactiveRequestContext {
+    workspaceId: string;
+    token?: string;
+}
 export declare class RelayFileClient {
     private readonly baseUrl;
     private readonly tokenProvider;
@@ -82,6 +99,11 @@ export declare class RelayFileClient {
     discardFork(input: DiscardForkInput): Promise<void>;
     commitFork(input: CommitForkInput): Promise<CommitForkResponse>;
     getEvents(workspaceId: string, options?: GetEventsOptions): Promise<EventFeedResponse>;
+    subscribe(globs: string[], onChange: (event: ChangeEvent) => void, options?: SubscribeOptions): Subscription;
+    open(options: ChangeStreamConnectionOptions): ChangeStreamConnection;
+    getResourceAtEvent(eventId: string, context?: ProactiveRequestContext): Promise<ResourceAtEventResult>;
+    listChangesSince(isoTimestamp: string, context?: ProactiveRequestContext): Promise<ChangeLogQueryResult>;
+    listLastNChanges(limit: number, context?: ProactiveRequestContext): Promise<ChangeLogQueryResult>;
     exportWorkspace(options: ExportOptions): Promise<ExportJsonResponse | Blob>;
     connectWebSocket(workspaceId: string, options?: ConnectWebSocketOptions): WebSocketConnection;
     getOp(workspaceId: string, opId: string, correlationId?: string, signal?: AbortSignal): Promise<OperationStatusResponse>;
@@ -102,6 +124,9 @@ export declare class RelayFileClient {
     ingestWebhook(input: IngestWebhookInput): Promise<QueuedResponse>;
     listPendingWritebacks(workspaceId: string, correlationId?: string, signal?: AbortSignal): Promise<WritebackItem[]>;
     ackWriteback(input: AckWritebackInput): Promise<AckWritebackResponse>;
+    private cacheWireChangeEvent;
+    private primeReplayCache;
+    private resolveWorkspaceId;
     private request;
     private performRequest;
     private shouldRetryStatus;

package/dist/client.js

@@ -1,3 +1,4 @@
+import { RelayFileSync } from "./sync.js";
 import { InvalidStateError, PayloadTooLargeError, QueueFullError, RelayFileApiError, RevisionConflictError } from "./errors.js";
 /** Default base URL for the hosted Relayfile API */
 export const DEFAULT_RELAYFILE_BASE_URL = "https://api.relayfile.dev";
@@ -7,6 +8,20 @@ const DEFAULT_RETRY_OPTIONS = {
     maxDelayMs: 2000,
     jitterRatio: 0.2
 };
+const DEFAULT_CHANGE_COALESCE_MS = 200;
+const DEFAULT_CHANGE_LOG_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+const DEFAULT_CHANGE_LOG_MAX_ENTRIES = 10_000;
+const CLIENT_TOKEN_STREAM_KEY = "__client__";
+const changeStreamManagers = new WeakMap();
+const changeLogCaches = new WeakMap();
+const changeLogSettings = new WeakMap();
+const pendingChangeHydrations = new WeakMap();
+function createM2NotImplementedError(feature) {
+    const error = new Error(`M2_NOT_IMPLEMENTED: ${feature} is reserved for proactive runtime M2.`);
+    error.name = "M2NotImplementedError";
+    error.code = "M2_NOT_IMPLEMENTED";
+    return error;
+}
 function normalizeRetryOptions(options) {
     const maxRetries = options?.maxRetries ?? DEFAULT_RETRY_OPTIONS.maxRetries;
     const baseDelayMs = options?.baseDelayMs ?? DEFAULT_RETRY_OPTIONS.baseDelayMs;
@@ -19,6 +34,18 @@ function normalizeRetryOptions(options) {
         jitterRatio: Math.max(0, Math.min(1, jitterRatio))
     };
 }
+function normalizeChangeLogOptions(options) {
+    const retentionMs = options?.retentionMs ?? DEFAULT_CHANGE_LOG_RETENTION_MS;
+    const maxEntries = options?.maxEntries ?? DEFAULT_CHANGE_LOG_MAX_ENTRIES;
+    return {
+        retentionMs: Number.isFinite(retentionMs) && retentionMs >= 0
+            ? Math.floor(retentionMs)
+            : DEFAULT_CHANGE_LOG_RETENTION_MS,
+        maxEntries: Number.isFinite(maxEntries) && maxEntries > 0
+            ? Math.floor(maxEntries)
+            : DEFAULT_CHANGE_LOG_MAX_ENTRIES
+    };
+}
 function buildQuery(params) {
     const query = new URLSearchParams();
     for (const [key, value] of Object.entries(params)) {
@@ -158,6 +185,749 @@ class RelayFileWebSocketConnection {
         };
     }
 }
+class WorkspaceChangeLogCache {
+    retentionMs;
+    maxEntries;
+    entries = [];
+    byId = new Map();
+    constructor(retentionMs = DEFAULT_CHANGE_LOG_RETENTION_MS, maxEntries = DEFAULT_CHANGE_LOG_MAX_ENTRIES) {
+        this.retentionMs = retentionMs;
+        this.maxEntries = maxEntries;
+    }
+    record(record) {
+        this.prune(Date.now());
+        const existing = this.byId.get(record.wire.id);
+        const merged = existing
+            ? {
+                wire: record.wire,
+                resource: record.resource.data !== null ? record.resource : existing.resource,
+                storedAt: record.storedAt,
+                context: record.context ?? existing.context
+            }
+            : record;
+        if (existing) {
+            const index = this.entries.findIndex((entry) => entry.wire.id === merged.wire.id);
+            if (index >= 0) {
+                this.entries.splice(index, 1);
+            }
+            this.entries.push(merged);
+            this.byId.set(merged.wire.id, merged);
+            return merged;
+        }
+        this.entries.push(merged);
+        this.byId.set(merged.wire.id, merged);
+        while (this.entries.length > this.maxEntries) {
+            const removed = this.entries.shift();
+            if (removed) {
+                this.byId.delete(removed.wire.id);
+            }
+        }
+        return merged;
+    }
+    get(eventId) {
+        this.prune(Date.now());
+        return this.byId.get(eventId);
+    }
+    listSince(isoTimestamp) {
+        this.prune(Date.now());
+        const threshold = Date.parse(isoTimestamp);
+        if (!Number.isFinite(threshold)) {
+            throw new Error(`Invalid ISO timestamp: ${isoTimestamp}`);
+        }
+        return this.entries.filter((entry) => Date.parse(entry.wire.occurredAt) >= threshold);
+    }
+    listLastN(limit) {
+        this.prune(Date.now());
+        const safeLimit = Math.max(0, Math.floor(limit));
+        if (safeLimit === 0) {
+            return [];
+        }
+        return this.entries.slice(-safeLimit);
+    }
+    prune(now) {
+        while (this.entries.length > 0) {
+            const first = this.entries[0];
+            if (!first) {
+                return;
+            }
+            if (now - first.storedAt < this.retentionMs) {
+                return;
+            }
+            this.entries.shift();
+            this.byId.delete(first.wire.id);
+        }
+    }
+}
+class RelayFileChangeSubscription {
+    manager;
+    onChange;
+    options;
+    active = true;
+    globPatterns;
+    pathScopes;
+    inFlight = new Set();
+    pendingByPath = new Map();
+    coalesceMs;
+    shouldCoalesce;
+    constructor(manager, globs, onChange, options) {
+        this.manager = manager;
+        this.onChange = onChange;
+        this.options = options;
+        this.globPatterns = globs.map((pattern) => normalizeChangePattern(pattern));
+        this.pathScopes = options?.pathScope?.length ? options.pathScope.map((pattern) => normalizeChangePattern(pattern)) : null;
+        this.shouldCoalesce = (options?.coalesce ?? "fire-once") !== "none";
+        this.coalesceMs = Math.max(0, Math.floor(options?.coalesceMs ?? DEFAULT_CHANGE_COALESCE_MS));
+    }
+    push(event) {
+        if (!this.active || !shouldPublishFilesystemEvent(event) || !this.matches(event.path)) {
+            return;
+        }
+        if (!this.shouldCoalesce) {
+            this.dispatch(event);
+            return;
+        }
+        const existing = this.pendingByPath.get(event.path);
+        if (existing) {
+            clearTimeout(existing.timer);
+        }
+        const timer = setTimeout(() => {
+            this.pendingByPath.delete(event.path);
+            if (!this.active) {
+                return;
+            }
+            this.dispatch(event);
+        }, this.coalesceMs);
+        this.pendingByPath.set(event.path, { event, timer });
+    }
+    async close() {
+        this.active = false;
+        for (const pending of this.pendingByPath.values()) {
+            clearTimeout(pending.timer);
+        }
+        this.pendingByPath.clear();
+        const drain = Promise.allSettled(Array.from(this.inFlight));
+        const drainMs = this.options?.drainMs;
+        if (typeof drainMs === "number" && Number.isFinite(drainMs) && drainMs >= 0) {
+            await Promise.race([
+                drain,
+                new Promise((resolve) => {
+                    setTimeout(resolve, drainMs);
+                })
+            ]);
+            return;
+        }
+        await drain;
+    }
+    matches(path) {
+        const pathSegments = normalizeChangePath(path);
+        const matchesGlob = this.globPatterns.some((pattern) => matchChangeSegments(pattern, pathSegments));
+        if (!matchesGlob) {
+            return false;
+        }
+        if (!this.pathScopes) {
+            return true;
+        }
+        return this.pathScopes.some((pattern) => matchChangeSegments(pattern, pathSegments));
+    }
+    dispatch(event) {
+        const task = this.manager.materialize(event)
+            .then((changeEvent) => {
+            if (!this.active || !changeEvent) {
+                return;
+            }
+            return Promise.resolve(this.onChange(changeEvent));
+        })
+            .catch((error) => {
+            if (typeof console !== "undefined" && typeof console.error === "function") {
+                console.error("RelayFile subscribe handler failed", error);
+            }
+        })
+            .finally(() => {
+            this.inFlight.delete(task);
+        });
+        this.inFlight.add(task);
+    }
+}
+class RelayFileChangeStreamManager {
+    client;
+    workspaceId;
+    token;
+    baseUrl;
+    subscriptions = new Set();
+    openHandleCount = 0;
+    sync;
+    readyResolved = false;
+    readyInternal;
+    resolveReady;
+    rejectReady;
+    constructor(client, workspaceId, token, baseUrl) {
+        this.client = client;
+        this.workspaceId = workspaceId;
+        this.token = token;
+        this.baseUrl = baseUrl;
+        this.readyInternal = new Promise((resolve, reject) => {
+            this.resolveReady = resolve;
+            this.rejectReady = reject;
+        });
+    }
+    get ready() {
+        return this.readyInternal;
+    }
+    addSubscription(globs, onChange, options) {
+        const subscription = new RelayFileChangeSubscription(this, globs, onChange, options);
+        this.subscriptions.add(subscription);
+        this.ensureStarted();
+        return {
+            unsubscribe: async () => {
+                this.subscriptions.delete(subscription);
+                await subscription.close();
+                await this.maybeStop();
+            }
+        };
+    }
+    open() {
+        this.openHandleCount += 1;
+        this.ensureStarted();
+        return {
+            ready: this.ready,
+            unsubscribe: async () => {
+                this.openHandleCount = Math.max(0, this.openHandleCount - 1);
+                await this.maybeStop();
+            }
+        };
+    }
+    async materialize(event) {
+        if (!shouldPublishFilesystemEvent(event)) {
+            return null;
+        }
+        const eventId = normalizeChangeEventId(event, this.workspaceId);
+        const cache = getChangeLogCache(this.client, this.workspaceId);
+        const cached = cache.get(eventId);
+        if (cached) {
+            return toChangeEvent(this.client, cached, { workspaceId: this.workspaceId, token: this.token });
+        }
+        const hydrations = getPendingChangeHydrations(this.client, this.workspaceId);
+        const pending = hydrations.get(eventId);
+        if (pending) {
+            const record = await pending;
+            return record ? toChangeEvent(this.client, record, { workspaceId: this.workspaceId, token: this.token }) : null;
+        }
+        const inFlight = materializeChangeRecord(this.client, this.workspaceId, event, this.token);
+        hydrations.set(eventId, inFlight);
+        let record;
+        try {
+            record = await inFlight;
+        }
+        finally {
+            if (hydrations.get(eventId) === inFlight) {
+                hydrations.delete(eventId);
+            }
+        }
+        return record ? toChangeEvent(this.client, record, { workspaceId: this.workspaceId, token: this.token }) : null;
+    }
+    ensureStarted() {
+        if (this.sync) {
+            return;
+        }
+        const sync = new RelayFileSync({
+            client: this.client,
+            workspaceId: this.workspaceId,
+            baseUrl: this.baseUrl,
+            token: this.token,
+            onPollingFallback: () => {
+                this.resolveReadyOnce();
+            }
+        });
+        sync.on("open", () => {
+            this.resolveReadyOnce();
+        });
+        sync.on("state", (state) => {
+            if (state === "polling") {
+                this.resolveReadyOnce();
+            }
+        });
+        sync.on("error", (error) => {
+            if (!this.readyResolved) {
+                this.rejectReady(error);
+            }
+        });
+        sync.on("event", (event) => {
+            for (const subscription of this.subscriptions) {
+                subscription.push(event);
+            }
+        });
+        this.sync = sync;
+        sync.start();
+        if (sync.getState() === "polling") {
+            this.resolveReadyOnce();
+        }
+    }
+    resolveReadyOnce() {
+        if (this.readyResolved) {
+            return;
+        }
+        this.readyResolved = true;
+        this.resolveReady();
+    }
+    async maybeStop() {
+        if (this.openHandleCount > 0 || this.subscriptions.size > 0) {
+            return;
+        }
+        if (this.sync) {
+            const sync = this.sync;
+            this.sync = undefined;
+            await sync.stop();
+        }
+        const managers = changeStreamManagers.get(this.client);
+        if (!managers) {
+            return;
+        }
+        for (const [key, manager] of managers.entries()) {
+            if (manager === this) {
+                managers.delete(key);
+            }
+        }
+    }
+}
+function getStreamManager(client, workspaceId, token, baseUrl) {
+    let managers = changeStreamManagers.get(client);
+    if (!managers) {
+        managers = new Map();
+        changeStreamManagers.set(client, managers);
+    }
+    const key = `${workspaceId}:${token ?? CLIENT_TOKEN_STREAM_KEY}`;
+    const existing = managers.get(key);
+    if (existing) {
+        return existing;
+    }
+    const manager = new RelayFileChangeStreamManager(client, workspaceId, token, baseUrl);
+    managers.set(key, manager);
+    return manager;
+}
+function getChangeLogCache(client, workspaceId) {
+    let workspaceCaches = changeLogCaches.get(client);
+    if (!workspaceCaches) {
+        workspaceCaches = new Map();
+        changeLogCaches.set(client, workspaceCaches);
+    }
+    const existing = workspaceCaches.get(workspaceId);
+    if (existing) {
+        return existing;
+    }
+    const settings = changeLogSettings.get(client) ?? normalizeChangeLogOptions();
+    const cache = new WorkspaceChangeLogCache(settings.retentionMs, settings.maxEntries);
+    workspaceCaches.set(workspaceId, cache);
+    return cache;
+}
+function getPendingChangeHydrations(client, workspaceId) {
+    let workspaceHydrations = pendingChangeHydrations.get(client);
+    if (!workspaceHydrations) {
+        workspaceHydrations = new Map();
+        pendingChangeHydrations.set(client, workspaceHydrations);
+    }
+    const existing = workspaceHydrations.get(workspaceId);
+    if (existing) {
+        return existing;
+    }
+    const hydrations = new Map();
+    workspaceHydrations.set(workspaceId, hydrations);
+    return hydrations;
+}
+function mergeChangeRecords(records) {
+    const deduped = new Map();
+    for (const record of records) {
+        deduped.set(record.wire.id, record);
+    }
+    return Array.from(deduped.values()).sort((left, right) => {
+        const leftOccurredAt = Date.parse(left.wire.occurredAt);
+        const rightOccurredAt = Date.parse(right.wire.occurredAt);
+        if (leftOccurredAt !== rightOccurredAt) {
+            return leftOccurredAt - rightOccurredAt;
+        }
+        return left.storedAt - right.storedAt;
+    });
+}
+function normalizeChangePattern(pattern) {
+    if (typeof pattern !== "string" || pattern.length === 0) {
+        throw new Error("subscribe globs must be non-empty strings.");
+    }
+    if (!pattern.startsWith("/")) {
+        throw new Error("subscribe globs must start with '/'.");
+    }
+    if (pattern.includes("//")) {
+        throw new Error("subscribe globs cannot contain empty path segments.");
+    }
+    const segments = normalizeChangePath(pattern);
+    const recursiveIndex = segments.indexOf("**");
+    if (recursiveIndex >= 0 && recursiveIndex !== segments.length - 1) {
+        throw new Error("subscribe globs only support '**' as the trailing segment.");
+    }
+    return segments;
+}
+function normalizeChangePath(path) {
+    const normalized = path.startsWith("/") ? path : `/${path}`;
+    const trimmed = normalized.replace(/\/+$/, "");
+    if (trimmed === "") {
+        return [];
+    }
+    return trimmed.split("/").filter(Boolean);
+}
+function matchChangeSegments(pattern, path) {
+    if (pattern.length > 0 && pattern[pattern.length - 1] === "**") {
+        const prefix = pattern.slice(0, -1);
+        return path.length >= prefix.length && prefix.every((segment, index) => segment === "*" || segment === path[index]);
+    }
+    if (pattern.length !== path.length) {
+        return false;
+    }
+    return pattern.every((segment, index) => segment === "*" || segment === path[index]);
+}
+function shouldPublishFilesystemEvent(event) {
+    return event.type === "file.created" || event.type === "file.updated" || event.type === "file.deleted";
+}
+function decodeBase64Url(value) {
+    const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, "=");
+    if (typeof atob === "function") {
+        const decoded = atob(padded);
+        return decodeURIComponent(Array.from(decoded).map((char) => `%${char.charCodeAt(0).toString(16).padStart(2, "0")}`).join(""));
+    }
+    const bufferCtor = globalThis.Buffer;
+    if (bufferCtor) {
+        return bufferCtor.from(padded, "base64").toString("utf8");
+    }
+    throw new Error("No base64 decoder is available in this environment.");
+}
+function getWorkspaceIdFromToken(token) {
+    const parts = token.split(".");
+    if (parts.length < 2) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(decodeBase64Url(parts[1] ?? ""));
+        return typeof parsed.workspace_id === "string" && parsed.workspace_id.length > 0 ? parsed.workspace_id : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function getAgentIdFromToken(token) {
+    const parts = token.split(".");
+    if (parts.length < 2) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(decodeBase64Url(parts[1] ?? ""));
+        return typeof parsed.agent_name === "string" && parsed.agent_name.length > 0 ? parsed.agent_name : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function getSingleKnownWorkspaceId(client) {
+    const workspaceIds = new Set();
+    for (const registry of [changeStreamManagers.get(client), changeLogCaches.get(client)]) {
+        if (!registry) {
+            continue;
+        }
+        for (const key of registry.keys()) {
+            workspaceIds.add(key.split(":")[0] ?? key);
+        }
+    }
+    return workspaceIds.size === 1 ? Array.from(workspaceIds)[0] : undefined;
+}
+function inferProviderFromPath(path) {
+    return normalizeChangePath(path)[0] ?? "relayfile";
+}
+function singularizeSegment(segment) {
+    return segment.endsWith("s") && segment.length > 1 ? segment.slice(0, -1) : segment;
+}
+function stripExtension(value) {
+    return value.replace(/\.[^/.]+$/, "");
+}
+function inferResourceMetadata(path, data) {
+    const segments = normalizeChangePath(path);
+    const provider = readStringField(data, ["provider"]) ?? inferProviderFromPath(path);
+    const kind = readStringField(data, ["kind", "resourceType"])
+        ?? readStringField(data, ["type"])
+        ?? `${provider}.${singularizeSegment(segments[1] ?? "resource")}`;
+    const id = readStringField(data, ["id", "resourceId", "key"])
+        ?? stripExtension(segments[segments.length - 1] ?? path);
+    return {
+        path,
+        kind,
+        id,
+        provider
+    };
+}
+function readStringField(data, keys) {
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+        return undefined;
+    }
+    const record = data;
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === "string" && value.trim().length > 0) {
+            return value.trim();
+        }
+    }
+    return undefined;
+}
+function readStringArrayField(data, keys) {
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+        return undefined;
+    }
+    const record = data;
+    for (const key of keys) {
+        const value = record[key];
+        if (Array.isArray(value)) {
+            const items = value.filter((entry) => typeof entry === "string" && entry.trim().length > 0).map((entry) => entry.trim());
+            if (items.length > 0) {
+                return items;
+            }
+        }
+    }
+    return undefined;
+}
+function readActorField(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+        return undefined;
+    }
+    const record = data;
+    const rawActor = record.actor ?? record.assignee ?? record.author;
+    if (typeof rawActor === "string" && rawActor.trim().length > 0) {
+        return { id: rawActor.trim() };
+    }
+    if (!rawActor || typeof rawActor !== "object" || Array.isArray(rawActor)) {
+        return undefined;
+    }
+    const actorRecord = rawActor;
+    const id = typeof actorRecord.id === "string" ? actorRecord.id.trim() : undefined;
+    if (!id) {
+        return undefined;
+    }
+    const displayName = typeof actorRecord.displayName === "string"
+        ? actorRecord.displayName.trim()
+        : typeof actorRecord.name === "string"
+            ? actorRecord.name.trim()
+            : undefined;
+    return { id, ...(displayName ? { displayName } : {}) };
+}
+function truncateString(value, maxLength) {
+    return value.length <= maxLength ? value : `${value.slice(0, Math.max(0, maxLength - 3))}...`;
+}
+function basename(path) {
+    const parts = normalizeChangePath(path);
+    return parts[parts.length - 1] ?? path;
+}
+function buildChangeSummary(path, data) {
+    const title = readStringField(data, ["title", "name", "summary", "subject"]) ?? stripExtension(basename(path));
+    const summary = {
+        title: truncateString(title, 120)
+    };
+    const status = readStringField(data, ["status", "state"]);
+    if (status) {
+        summary.status = status;
+    }
+    const priority = readStringField(data, ["priority"]);
+    if (priority) {
+        summary.priority = priority;
+    }
+    const labels = readStringArrayField(data, ["labels"]);
+    if (labels) {
+        summary.labels = labels.slice(0, 8);
+    }
+    const actor = readActorField(data);
+    if (actor) {
+        summary.actor = actor;
+    }
+    const fieldsChanged = readStringArrayField(data, ["fieldsChanged", "changedFields"]);
+    if (fieldsChanged) {
+        summary.fieldsChanged = fieldsChanged;
+    }
+    const tags = readStringArrayField(data, ["tags"]);
+    if (tags) {
+        summary.tags = tags.slice(0, 8);
+    }
+    return summary;
+}
+function decodeFilePayload(file) {
+    if (file.encoding === "base64") {
+        return {
+            contentBase64: file.content,
+            contentType: file.contentType,
+            encoding: "base64"
+        };
+    }
+    const looksJson = file.contentType.includes("json") || file.path.endsWith(".json");
+    if (looksJson) {
+        try {
+            return JSON.parse(file.content);
+        }
+        catch {
+            // Fall through to the raw string when payloads are malformed.
+        }
+    }
+    return file.content;
+}
+async function sha256Hex(value) {
+    let subtle = globalThis.crypto?.subtle;
+    if (!subtle) {
+        try {
+            const nodeCrypto = await import("node:crypto");
+            subtle = nodeCrypto.webcrypto?.subtle;
+            if (!subtle) {
+                return `sha256:${nodeCrypto.createHash("sha256").update(value).digest("hex")}`;
+            }
+        }
+        catch {
+            // Fall through to the non-content fallback below.
+        }
+    }
+    if (!subtle) {
+        const nonce = globalThis.crypto?.randomUUID?.() ?? `unavailable-${Date.now().toString(36)}`;
+        return `sha256:unavailable:${nonce}`;
+    }
+    const hash = await subtle.digest("SHA-256", new TextEncoder().encode(value));
+    const bytes = new Uint8Array(hash);
+    return `sha256:${Array.from(bytes).map((byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+}
+function normalizeChangeEventId(event, workspaceId) {
+    if (event.eventId && !event.eventId.startsWith("ws:")) {
+        return event.eventId;
+    }
+    return [
+        "relayfile",
+        workspaceId,
+        event.type,
+        event.path,
+        event.revision,
+        event.timestamp
+    ].join(":");
+}
+function toChangeEvent(client, record, contextOverride) {
+    const context = contextOverride ?? record.context ?? { workspaceId: record.wire.workspace };
+    return {
+        ...record.wire,
+        expand: async (level) => {
+            const normalizedLevel = (level ?? "summary");
+            if (normalizedLevel === "summary") {
+                return {
+                    level: normalizedLevel,
+                    path: record.wire.resource.path,
+                    summary: record.wire.summary
+                };
+            }
+            if (normalizedLevel === "full") {
+                const resource = await client.getResourceAtEvent(record.wire.id, context);
+                return {
+                    level: normalizedLevel,
+                    path: resource.path,
+                    data: resource.data
+                };
+            }
+            throw createM2NotImplementedError(`ChangeEvent.expand(${JSON.stringify(normalizedLevel)})`);
+        }
+    };
+}
+function normalizeWireChangeEvent(payload) {
+    const data = (payload ?? {});
+    const resource = (data.resource ?? {});
+    const summary = (data.summary ?? {});
+    return {
+        id: typeof data.id === "string" ? data.id : "",
+        workspace: typeof data.workspace === "string" ? data.workspace : "",
+        agentId: typeof data.agentId === "string" ? data.agentId : undefined,
+        type: "relayfile.changed",
+        occurredAt: typeof data.occurredAt === "string" ? data.occurredAt : new Date().toISOString(),
+        resource: {
+            path: typeof resource.path === "string" ? resource.path : "",
+            kind: typeof resource.kind === "string" ? resource.kind : "relayfile.resource",
+            id: typeof resource.id === "string" ? resource.id : "",
+            provider: typeof resource.provider === "string" ? resource.provider : "relayfile"
+        },
+        summary: {
+            ...(typeof summary.title === "string" ? { title: summary.title } : {}),
+            ...(typeof summary.status === "string" ? { status: summary.status } : {}),
+            ...(typeof summary.priority === "string" ? { priority: summary.priority } : {}),
+            ...(Array.isArray(summary.labels) ? { labels: summary.labels.filter((entry) => typeof entry === "string") } : {}),
+            ...(summary.actor && typeof summary.actor === "object"
+                ? {
+                    actor: {
+                        id: typeof summary.actor.id === "string" ? summary.actor.id : "",
+                        ...(typeof summary.actor.displayName === "string"
+                            ? { displayName: summary.actor.displayName }
+                            : {})
+                    }
+                }
+                : {}),
+            ...(Array.isArray(summary.fieldsChanged)
+                ? { fieldsChanged: summary.fieldsChanged.filter((entry) => typeof entry === "string") }
+                : {}),
+            ...(Array.isArray(summary.tags) ? { tags: summary.tags.filter((entry) => typeof entry === "string").slice(0, 8) } : {})
+        },
+        ...(typeof data.digest === "string" ? { digest: data.digest } : {})
+    };
+}
+async function materializeChangeRecord(client, workspaceId, event, token) {
+    const eventId = normalizeChangeEventId(event, workspaceId);
+    const occurredAt = event.timestamp || new Date().toISOString();
+    const fallbackDigest = event.revision ? `revision:${event.revision}` : `deleted:${occurredAt}`;
+    const fallbackResource = {
+        path: event.path,
+        data: { path: event.path, deleted: event.type === "file.deleted" },
+        digest: fallbackDigest
+    };
+    let tokenAgentId;
+    try {
+        tokenAgentId = getAgentIdFromToken(token ?? await client.getToken());
+    }
+    catch {
+        tokenAgentId = undefined;
+    }
+    let resource = fallbackResource;
+    let wire = {
+        id: eventId,
+        workspace: workspaceId,
+        ...(tokenAgentId ? { agentId: tokenAgentId } : {}),
+        type: "relayfile.changed",
+        occurredAt,
+        resource: inferResourceMetadata(event.path, resource.data),
+        summary: buildChangeSummary(event.path, resource.data),
+        digest: resource.digest
+    };
+    if (event.type !== "file.deleted") {
+        try {
+            const file = await client.readFile({ workspaceId, path: event.path, token });
+            const data = decodeFilePayload(file);
+            const digest = await sha256Hex(file.content);
+            resource = {
+                path: event.path,
+                data,
+                digest
+            };
+            wire = {
+                ...wire,
+                resource: inferResourceMetadata(event.path, data),
+                summary: buildChangeSummary(event.path, data),
+                digest
+            };
+        }
+        catch (error) {
+            if (typeof console !== "undefined" && typeof console.warn === "function") {
+                console.warn(`[relayfile-sdk] Failed to materialize change event for ${event.path}; falling back to path-only summary.`, error);
+            }
+        }
+    }
+    const record = {
+        wire,
+        resource,
+        storedAt: Date.now(),
+        context: { workspaceId, token }
+    };
+    getChangeLogCache(client, workspaceId).record(record);
+    return record;
+}
 export class RelayFileClient {
     baseUrl;
     tokenProvider;
@@ -170,6 +940,7 @@ export class RelayFileClient {
         this.fetchImpl = options.fetchImpl ?? fetch.bind(globalThis);
         this.userAgent = options.userAgent;
         this.retryOptions = normalizeRetryOptions(options.retry);
+        changeLogSettings.set(this, normalizeChangeLogOptions(options.changeLog));
     }
     /**
      * Resolve the current access token via the configured token provider.
@@ -223,7 +994,8 @@ export class RelayFileClient {
             method: "GET",
             path: `/v1/workspaces/${encodeURIComponent(input.workspaceId)}/fs/file${query}`,
             correlationId: input.correlationId,
-            signal: input.signal
+            signal: input.signal,
+            tokenOverride: input.token
         });
     }
     async queryFiles(workspaceId, options = {}) {
@@ -350,6 +1122,115 @@ export class RelayFileClient {
             signal: options.signal
         });
     }
+    subscribe(globs, onChange, options) {
+        const setup = this.resolveWorkspaceId(options?.aclToken)
+            .then((workspaceId) => {
+            const manager = getStreamManager(this, workspaceId, options?.aclToken, this.baseUrl);
+            return manager.addSubscription(globs, onChange, options);
+        });
+        return {
+            async unsubscribe() {
+                const subscription = await setup;
+                await subscription.unsubscribe();
+            },
+        };
+    }
+    open(options) {
+        const manager = getStreamManager(this, options.workspaceId, options.aclToken, this.baseUrl);
+        const connection = manager.open();
+        const replay = this.primeReplayCache(options).catch((error) => {
+            if (typeof console !== "undefined" && typeof console.error === "function") {
+                console.error("RelayFile change-stream replay initialization failed", error);
+            }
+        });
+        return {
+            ready: Promise.all([connection.ready, replay]).then(() => undefined),
+            unsubscribe: () => connection.unsubscribe()
+        };
+    }
+    async getResourceAtEvent(eventId, context) {
+        const workspaceId = context?.workspaceId ?? await this.resolveWorkspaceId(context?.token);
+        const effectiveContext = context ?? { workspaceId };
+        const cache = getChangeLogCache(this, workspaceId);
+        const cached = cache.get(eventId);
+        if (cached && cached.resource.data !== null) {
+            return cached.resource;
+        }
+        const pending = getPendingChangeHydrations(this, workspaceId).get(eventId);
+        if (pending) {
+            try {
+                await pending;
+            }
+            catch {
+                // Fall through to the retained lookup endpoint if live hydration fails.
+            }
+            const hydrated = cache.get(eventId);
+            if (hydrated && hydrated.resource.data !== null) {
+                return hydrated.resource;
+            }
+        }
+        return this.request({
+            method: "GET",
+            path: `/v1/workspaces/${encodeURIComponent(workspaceId)}/fs/changes/resource${buildQuery({ eventId })}`,
+            tokenOverride: effectiveContext.token
+        });
+    }
+    async listChangesSince(isoTimestamp, context) {
+        const workspaceId = context?.workspaceId ?? await this.resolveWorkspaceId(context?.token);
+        const effectiveContext = context ?? { workspaceId };
+        const cache = getChangeLogCache(this, workspaceId);
+        const cached = cache.listSince(isoTimestamp);
+        let records = cached;
+        try {
+            const payload = await this.request({
+                method: "GET",
+                path: `/v1/workspaces/${encodeURIComponent(workspaceId)}/fs/changes${buildQuery({ since: isoTimestamp })}`,
+                tokenOverride: effectiveContext.token
+            });
+            records = mergeChangeRecords([
+                ...cached,
+                ...(payload.events ?? []).map((event) => this.cacheWireChangeEvent(workspaceId, normalizeWireChangeEvent(event), effectiveContext))
+            ]);
+        }
+        catch (error) {
+            if (cached.length === 0) {
+                throw error;
+            }
+        }
+        return {
+            events: records.map((record) => toChangeEvent(this, record, context))
+        };
+    }
+    async listLastNChanges(limit, context) {
+        const safeLimit = Math.max(0, Math.floor(limit));
+        if (safeLimit === 0) {
+            return { events: [] };
+        }
+        const workspaceId = context?.workspaceId ?? await this.resolveWorkspaceId(context?.token);
+        const effectiveContext = context ?? { workspaceId };
+        const cache = getChangeLogCache(this, workspaceId);
+        const cached = cache.listLastN(safeLimit);
+        let records = cached;
+        try {
+            const payload = await this.request({
+                method: "GET",
+                path: `/v1/workspaces/${encodeURIComponent(workspaceId)}/fs/changes${buildQuery({ last: safeLimit })}`,
+                tokenOverride: effectiveContext.token
+            });
+            records = mergeChangeRecords([
+                ...cached,
+                ...(payload.events ?? []).map((event) => this.cacheWireChangeEvent(workspaceId, normalizeWireChangeEvent(event), effectiveContext))
+            ]).slice(-safeLimit);
+        }
+        catch (error) {
+            if (cached.length === 0) {
+                throw error;
+            }
+        }
+        return {
+            events: records.map((record) => toChangeEvent(this, record, context))
+        };
+    }
     async exportWorkspace(options) {
         const format = options.format ?? "json";
         const query = buildQuery({ format });
@@ -586,6 +1467,44 @@ export class RelayFileClient {
             signal: input.signal
         });
     }
+    cacheWireChangeEvent(workspaceId, wire, context) {
+        const record = {
+            wire,
+            resource: {
+                path: wire.resource.path,
+                data: null,
+                digest: wire.digest ?? `event:${wire.id}`
+            },
+            storedAt: Date.now(),
+            context: context ?? { workspaceId }
+        };
+        return getChangeLogCache(this, workspaceId).record(record);
+    }
+    async primeReplayCache(options) {
+        if (!options.replayOnStart || options.replayOnStart === "none") {
+            return;
+        }
+        if (options.replayOnStart.startsWith("since:")) {
+            await this.listChangesSince(options.replayOnStart.slice("since:".length), { workspaceId: options.workspaceId, token: options.aclToken });
+            return;
+        }
+        if (options.replayOnStart.startsWith("last:")) {
+            const limit = Number.parseInt(options.replayOnStart.slice("last:".length), 10);
+            await this.listLastNChanges(limit, { workspaceId: options.workspaceId, token: options.aclToken });
+        }
+    }
+    async resolveWorkspaceId(tokenOverride) {
+        const knownWorkspaceId = getSingleKnownWorkspaceId(this);
+        if (knownWorkspaceId) {
+            return knownWorkspaceId;
+        }
+        const token = tokenOverride ?? await this.getToken();
+        const workspaceId = getWorkspaceIdFromToken(token);
+        if (workspaceId) {
+            return workspaceId;
+        }
+        throw new Error("RelayFile proactive-runtime APIs require a workspace-scoped JWT with a workspace_id claim.");
+    }
     async request(params) {
         const response = await this.performRequest(params);
         const payload = await this.readPayload(response);
@@ -612,7 +1531,7 @@ export class RelayFileClient {
         let retries = 0;
         const url = `${this.baseUrl}${params.path}`;
         for (;;) {
-            const token = await resolveToken(this.tokenProvider);
+            const token = params.tokenOverride ?? await resolveToken(this.tokenProvider);
             const headers = {
                 Authorization: `Bearer ${token}`,
                 ...baseHeaders

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { RelayFileClient, DEFAULT_RELAYFILE_BASE_URL, type AccessTokenProvider, type ConnectWebSocketOptions, type RelayFileClientOptions, type RelayFileRetryOptions, type WebSocketConnection } from "./client.js";
+export { RelayFileClient, DEFAULT_RELAYFILE_BASE_URL, type AccessTokenProvider, type RelayFileChangeLogOptions, type ConnectWebSocketOptions, type RelayFileClientOptions, type RelayFileRetryOptions, type WebSocketConnection } from "./client.js";
 export { RelayfileSetup, RELAYFILE_SDK_VERSION, WorkspaceHandle } from "./setup.js";
 export { type RelayfileCloudLoginOptions, type RelayfileCloudTokenSet, type RelayfileCloudTokenSetupOptions } from "./cloud-login.js";
 export { CloudAbortError, CloudApiError, CloudTimeoutError, InvalidLocalDirError, InvalidMountModeError, InvalidRemotePathError, IntegrationConnectionTimeoutError, MalformedCloudResponseError, MissingConnectionIdError, MountModeUnavailableError, MountReadyTimeoutError, MountSessionInputError, ProviderNotConnectedError, ProviderNotReadyError, RelayfileSetupError, UnknownProviderError } from "./setup-errors.js";
@@ -10,7 +10,7 @@ export { InvalidStateError, PayloadTooLargeError, QueueFullError, RelayFileApiEr
 export { IntegrationProvider, computeCanonicalPath } from "./provider.js";
 export type { WebhookInput, ListProviderFilesOptions, WatchProviderEventsOptions } from "./provider.js";
 export type { ConnectionProvider, NormalizedWebhook, ProxyHeaders, ProxyMethod, ProxyQuery, ProxyRequest, ProxyResponse, } from "./connection.js";
-export type { AckResponse, AckWritebackInput, AckWritebackResponse, AdminIngressAlert, AdminIngressAlertProfile, AdminIngressEffectiveAlertProfile, AdminIngressAlertSeverity, AdminIngressAlertThresholds, AdminIngressAlertTotals, AdminIngressAlertType, AdminIngressStatusResponse, AdminSyncAlert, AdminSyncAlertSeverity, AdminSyncAlertThresholds, AdminSyncAlertTotals, AdminSyncAlertType, AdminSyncStatusResponse, BackendStatusResponse, BulkWriteFile, BulkWriteInput, BulkWriteResponse, CommitForkInput, CommitForkResponse, ConflictErrorResponse, CreateForkInput, ContentIdentity, DeleteFileInput, DeadLetterFeedResponse, DeadLetterItem, DiscardForkInput, ErrorResponse, EventFeedResponse, ExportFormat, ExportJsonResponse, ExportOptions, FileQueryItem, FileQueryResponse, FileReadResponse, FileSemantics, FileWriteRequest, FilesystemEvent, FilesystemEventType, EventOrigin, GetEventsOptions, GetAdminSyncStatusOptions, GetAdminIngressStatusOptions, GetOperationsOptions, GetSyncDeadLettersOptions, GetSyncIngressStatusOptions, GetSyncStatusOptions, IngestWebhookInput, ListTreeOptions, OperationFeedResponse, OperationStatus, OperationStatusResponse, QueuedResponse, QueryFilesOptions, ReadFileInput, RelayFileJwtClaims, SyncIngressStatusResponse, SyncProviderStatus, SyncProviderStatusState, SyncRefreshRequest, SyncStatusResponse, TreeEntry, TreeResponse, WritebackActionType, WritebackState, WritebackItem, WriteFileInput, WriteQueuedResponse } from "./types.js";
+export type { AckResponse, AckWritebackInput, AckWritebackResponse, AdminIngressAlert, AdminIngressAlertProfile, AdminIngressEffectiveAlertProfile, AdminIngressAlertSeverity, AdminIngressAlertThresholds, AdminIngressAlertTotals, AdminIngressAlertType, AdminIngressStatusResponse, AdminSyncAlert, AdminSyncAlertSeverity, AdminSyncAlertThresholds, AdminSyncAlertTotals, AdminSyncAlertType, AdminSyncStatusResponse, BackendStatusResponse, BulkWriteFile, BulkWriteInput, BulkWriteResponse, ChangeLogQueryResult, ChangeEvent, ChangeEventActor, ChangeEventResource, ChangeEventSummary, ChangeStreamConnection, ChangeStreamConnectionOptions, CommitForkInput, CommitForkResponse, ConflictErrorResponse, CreateForkInput, ContentIdentity, DeleteFileInput, DeadLetterFeedResponse, DeadLetterItem, DiscardForkInput, ErrorResponse, EventSummary, EventFeedResponse, ExportFormat, ExportJsonResponse, ExportOptions, FileQueryItem, FileQueryResponse, FileReadResponse, FileSemantics, FileWriteRequest, FilesystemEvent, FilesystemEventType, EventOrigin, Expansion, ExpansionLevel, GetEventsOptions, GetAdminSyncStatusOptions, GetAdminIngressStatusOptions, GetOperationsOptions, GetSyncDeadLettersOptions, GetSyncIngressStatusOptions, GetSyncStatusOptions, IngestWebhookInput, ListTreeOptions, OperationFeedResponse, OperationStatus, OperationStatusResponse, QueuedResponse, QueryFilesOptions, ReadFileInput, ReplayOptions, ResourceAtEventResult, SummaryExpansion, FullExpansion, DiffExpansion, ThreadExpansion, RelayFileJwtClaims, SubscribeOptions, Subscription, SyncIngressStatusResponse, SyncProviderStatus, SyncProviderStatusState, SyncRefreshRequest, SyncStatusResponse, TreeEntry, TreeResponse, WritebackActionType, WritebackState, WritebackItem, WriteFileInput, WriteQueuedResponse } from "./types.js";
 export type { ForkHandle, ForkOptions } from "@relayfile/core";
 export type { WriteEvent, WriteEventActor, WriteEventOperation, WriteEventSource } from "@relayfile/core";
 export { WritebackConsumer } from "./writeback-consumer.js";

package/dist/types.d.ts

@@ -136,6 +136,106 @@ export interface FilesystemEvent {
     correlationId?: string;
     timestamp: string;
 }
+export interface ChangeEventResource {
+    path: string;
+    kind: string;
+    id: string;
+    provider: string;
+}
+export interface ChangeEventActor {
+    id: string;
+    displayName?: string;
+}
+export interface ChangeEventSummary {
+    title?: string;
+    status?: string;
+    priority?: string;
+    labels?: string[];
+    actor?: ChangeEventActor;
+    fieldsChanged?: string[];
+    /** Optional compact tag list. Producers must cap this at 8 entries. */
+    tags?: string[];
+}
+/**
+ * Canonical lightweight event summary shape exported for proactive-runtime
+ * adapters. `buildSummary(payload)` should return this exact structure.
+ */
+export type EventSummary = ChangeEventSummary;
+export type ExpansionLevel = "summary" | "full" | "diff" | "thread";
+export interface SummaryExpansion {
+    level: "summary";
+    path: string;
+    summary: ChangeEventSummary;
+}
+export interface FullExpansion<TData = unknown> {
+    level: "full";
+    path: string;
+    data: TData;
+}
+export interface DiffExpansion {
+    level: "diff";
+    path: string;
+    diff: Record<string, unknown>;
+}
+export interface ThreadExpansion {
+    level: "thread";
+    path: string;
+    thread: Record<string, unknown>;
+}
+export type Expansion<L extends ExpansionLevel = ExpansionLevel> = L extends "summary" ? SummaryExpansion : L extends "full" ? FullExpansion : L extends "diff" ? DiffExpansion : ThreadExpansion;
+/**
+ * Proactive runtime relayfile notification envelope.
+ *
+ * This differs from the lower-level FilesystemEvent feed above. The proactive
+ * runtime consumes a small, stable notification that points at the canonical
+ * payload in VFS instead of inlining provider payloads directly.
+ *
+ * M1 exposes the type so downstream packages can compile against the final
+ * shape before M2 wires live delivery.
+ */
+export interface ChangeEvent {
+    id: string;
+    workspace: string;
+    agentId?: string;
+    type: "relayfile.changed";
+    occurredAt: string;
+    resource: ChangeEventResource;
+    summary: ChangeEventSummary;
+    expand<L extends ExpansionLevel = "summary">(level?: L): Promise<Expansion<L>>;
+    digest?: string;
+}
+export interface SubscribeOptions {
+    coalesce?: "none" | "fire-once";
+    coalesceMs?: number;
+    pathScope?: string[];
+    aclToken?: string;
+    drainMs?: number;
+}
+export interface Subscription {
+    unsubscribe(): Promise<void>;
+}
+export type ReplayOptions = {
+    replayOnStart?: "none";
+} | {
+    replayOnStart: `since:${string}`;
+} | {
+    replayOnStart: `last:${number}`;
+};
+export type ChangeStreamConnectionOptions = ReplayOptions & {
+    workspaceId: string;
+    aclToken?: string;
+};
+export interface ChangeStreamConnection extends Subscription {
+    readonly ready: Promise<void>;
+}
+export interface ResourceAtEventResult {
+    path: string;
+    data: unknown;
+    digest: string;
+}
+export interface ChangeLogQueryResult {
+    events: ChangeEvent[];
+}
 export interface EventFeedResponse {
     events: FilesystemEvent[];
     nextCursor: string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/sdk",
-  "version": "0.7.10",
+  "version": "0.7.12",
   "description": "TypeScript SDK for relayfile — real-time filesystem for humans and agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -22,7 +22,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@relayfile/core": "0.7.10"
+    "@relayfile/core": "0.7.12"
   },
   "devDependencies": {
     "typescript": "^5.7.3",