@relayfile/sdk 0.8.10 → 0.8.12

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 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 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 SweepWritebackDraftsInput, type SweepWritebackDraftsResponse, 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.
@@ -127,6 +127,11 @@ export declare class RelayFileClient {
     ingestWebhook(input: IngestWebhookInput): Promise<QueuedResponse>;
     listPendingWritebacks(workspaceId: string, correlationId?: string, signal?: AbortSignal): Promise<WritebackItem[]>;
     ackWriteback(input: AckWritebackInput): Promise<AckWritebackResponse>;
+    /**
+     * One-time residue sweep for accumulated writeback drafts (issue #242).
+     * Dry run unless `apply` is true; classification-exempt service-side.
+     */
+    sweepWritebackDrafts(input: SweepWritebackDraftsInput): Promise<SweepWritebackDraftsResponse>;
     private cacheWireChangeEvent;
     private primeReplayCache;
     private resolveWorkspaceId;

package/dist/client.js

@@ -1523,7 +1523,26 @@ export class RelayFileClient {
             correlationId: input.correlationId,
             body: {
                 success: input.success,
-                error: input.error
+                error: input.error,
+                externalId: input.externalId,
+                canonicalPath: input.canonicalPath
+            },
+            signal: input.signal
+        });
+    }
+    /**
+     * One-time residue sweep for accumulated writeback drafts (issue #242).
+     * Dry run unless `apply` is true; classification-exempt service-side.
+     */
+    async sweepWritebackDrafts(input) {
+        return this.request({
+            method: "POST",
+            path: `/v1/workspaces/${encodeURIComponent(input.workspaceId)}/writeback/sweep-drafts`,
+            correlationId: input.correlationId,
+            body: {
+                pathPrefix: input.pathPrefix,
+                patterns: input.patterns,
+                apply: input.apply === true
             },
             signal: input.signal
         });

package/dist/index.d.ts

@@ -2,14 +2,14 @@ export { RelayFileClient, DEFAULT_RELAYFILE_BASE_URL, type AccessTokenProvider,
 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";
-export { type EnsureMountedWorkspaceInput, WORKSPACE_INTEGRATION_PROVIDERS, type AgentWorkspaceInvite, type AgentWorkspaceInviteOptions, type AgentWorkspaceScopedInviteOptions, type ConnectIntegrationOptions, type ConnectIntegrationResult, type CreateWorkspaceOptions, type JoinWorkspaceOptions, type MountLauncher, type MountLauncherEvent, type MountLauncherInstance, type MountLauncherStart, type MountMode, type MountSessionRequest, type MountSessionResponse, type MountSessionResult, type MountedWorkspaceHandle, type MountedWorkspaceStatus, type MountWorkspaceInput, type ReadMountedWorkspaceStatusInput, type RelayfileSetupOptions, type RelayfileSetupRetryOptions, type WaitForConnectionOptions, type WorkspaceInfo, type WorkspaceIntegrationProvider, type WorkspaceMountEnv, type WorkspaceMountEnvOptions, type WorkspacePermissions } from "./setup-types.js";
+export { type EnsureMountedWorkspaceInput, WORKSPACE_INTEGRATION_PROVIDERS, type AgentWorkspaceInvite, type AgentWorkspaceInviteOptions, type AgentWorkspaceScopedInviteOptions, type ConnectIntegrationOptions, type ConnectIntegrationResult, type CreateWorkspaceOptions, type JoinWorkspaceOptions, type MountLauncher, type MountLauncherEvent, type MountLauncherInstance, type MountLauncherStart, type MountLocalLayout, type MountMode, type MountSessionRequest, type MountSessionResponse, type MountSessionResult, type MountSyncMode, type MountedWorkspaceHandle, type MountedWorkspaceStatus, type MountWorkspaceInput, type ReadMountedWorkspaceStatusInput, type RelayfileSetupOptions, type RelayfileSetupRetryOptions, type WaitForConnectionOptions, type WorkspaceInfo, type WorkspaceIntegrationProvider, type WorkspaceMountEnv, type WorkspaceMountEnvOptions, type WorkspacePermissions } from "./setup-types.js";
 export { RelayFileSync, type RelayFileSyncOptions, type RelayFileSyncPong, type RelayFileSyncReconnectOptions, type RelayFileSyncSocket, type RelayFileSyncStart, type RelayFileSyncState, type RelayFileSyncTokenProvider } from "./sync.js";
 export { onWrite, pathMatches, type OnWriteClient, type OnWriteHandler, type OnWriteHandlerError, type OnWriteOptions } from "./onWrite.js";
 export { InvalidStateError, PayloadTooLargeError, QueueFullError, RelayFileApiError, RevisionConflictError } from "./errors.js";
 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, ChangeLogQueryResult, ChangeEvent, ChangeEventActor, ChangeEventResource, ChangeEventSummary, ChangeStreamConnection, ChangeStreamConnectionOptions, CommitForkInput, CommitForkResponse, ConflictErrorResponse, CreateForkInput, ContentIdentity, DeleteFileInput, DeadLetterFeedResponse, DeadLetterItem, DigestBullet, DigestContext, DigestHandler, DigestSection, DigestWindow, 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, LayoutManifest, LayoutManifestAlias, LayoutManifestResource, ListTreeOptions, OperationFeedResponse, OperationStatus, OperationStatusResponse, QueuedResponse, QueryFilesOptions, ReadFileInput, ReplayOptions, ResourceAtEventResult, SummaryExpansion, FullExpansion, DiffExpansion, ThreadExpansion, RelayFileJwtClaims, SubscribeOptions, Subscription, SyncIngressStatusResponse, SyncProviderStatus, SyncProviderStatusState, SyncRefreshRequest, SyncStatusResponse, TreeEntry, TreeResponse, WritebackActionType, WritebackDeadLetterError, WritebackDeadLetterErrorCode, WritebackListState, WritebackState, WritebackItem, WritebackItemDetail, WritebackSchemaRef, WriteFileInput, WriteQueuedResponse } from "./types.js";
+export type { AckResponse, AckWritebackInput, AckWritebackDraftDisposition, 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, DigestBullet, DigestContext, DigestHandler, DigestSection, DigestWindow, 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, LayoutManifest, LayoutManifestAlias, LayoutManifestResource, ListTreeOptions, OperationFeedResponse, OperationStatus, OperationStatusResponse, QueuedResponse, QueryFilesOptions, ReadFileInput, ReplayOptions, ResourceAtEventResult, SummaryExpansion, FullExpansion, DiffExpansion, ThreadExpansion, RelayFileJwtClaims, SubscribeOptions, Subscription, SyncIngressStatusResponse, SyncProviderStatus, SyncProviderStatusState, SyncRefreshRequest, SyncStatusResponse, SweepWritebackDraftsInput, SweepWritebackDraftsResponse, TreeEntry, TreeResponse, WritebackActionType, WritebackDeadLetterError, WritebackDeadLetterErrorCode, WritebackListState, WritebackState, WritebackItem, WritebackItemDetail, WritebackSchemaRef, 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/mount-launcher.js

@@ -20,7 +20,7 @@ export function createDefaultMountLauncher(options = {}) {
     };
 }
 export async function readMountedWorkspaceStatus(input) {
-    const state = await readMountStateFile(input.localDir);
+    const state = await readMountStateFile(resolveMountLocalDir(input.localDir, input.remotePath, input.localLayout));
     if (state && !isMountStateStale(state)) {
         return {
             ready: isMountStateReady(state),
@@ -46,7 +46,8 @@ export async function readMountedWorkspaceStatus(input) {
 }
 async function startRelayfileMount(input, options) {
     const localDir = path.resolve(input.env.RELAYFILE_LOCAL_DIR ?? process.cwd());
-    const relayDir = path.join(localDir, ".relay");
+    const mountLocalDir = resolveMountLocalDir(localDir, input.env.RELAYFILE_REMOTE_PATH, input.env.RELAYFILE_MOUNT_LOCAL_LAYOUT);
+    const relayDir = path.join(mountLocalDir, ".relay");
     const logPath = path.join(relayDir, "mount.log");
     const pidPath = path.join(relayDir, "mount.pid");
     await mkdir(relayDir, { recursive: true });
@@ -54,7 +55,7 @@ async function startRelayfileMount(input, options) {
     const command = await resolveRelayfileMountCommand();
     const args = input.background === false ? ["--once"] : [];
     const child = (options.spawnImpl ?? spawn)(command, args, {
-        cwd: input.cwd ?? localDir,
+        cwd: input.cwd ?? mountLocalDir,
         env: {
             ...process.env,
             ...input.env
@@ -73,7 +74,7 @@ async function startRelayfileMount(input, options) {
         pidPath,
         outputBuffer,
         input,
-        localDir,
+        localDir: mountLocalDir,
         now: options.now ?? Date.now,
         readyPollIntervalMs: options.readyPollIntervalMs ?? DEFAULT_READY_POLL_INTERVAL_MS
     });
@@ -113,6 +114,8 @@ class RelayfileMountProcessInstance {
             workspaceId: this.input.env.RELAYFILE_WORKSPACE ?? "",
             remotePath: this.input.env.RELAYFILE_REMOTE_PATH ?? "/",
             mode: normalizeMountMode(this.input.env.RELAYFILE_MOUNT_MODE) ?? "poll",
+            localLayout: normalizeMountLocalLayout(this.input.env.RELAYFILE_MOUNT_LOCAL_LAYOUT),
+            syncMode: normalizeMountSyncMode(this.input.env.RELAYFILE_MOUNT_SYNC_MODE),
             relayfileBaseUrl: this.input.env.RELAYFILE_BASE_URL ?? "",
             relayfileToken: this.input.env.RELAYFILE_TOKEN ?? "",
             expiresAt: null,
@@ -251,6 +254,32 @@ function isMountStateStale(state) {
 function normalizeMountMode(mode) {
     return mode === "fuse" ? "fuse" : mode === "poll" ? "poll" : undefined;
 }
+function normalizeMountLocalLayout(layout) {
+    return layout === "scoped" ? "scoped" : "exact";
+}
+function normalizeMountSyncMode(mode) {
+    return mode === "write-only" ? "write-only" : "mirror";
+}
+function resolveMountLocalDir(localDir, remotePath, localLayout) {
+    const root = path.resolve(localDir);
+    if (normalizeMountLocalLayout(localLayout) !== "scoped") {
+        return root;
+    }
+    const normalizedRemote = normalizeRemotePath(remotePath);
+    if (normalizedRemote === "/") {
+        return root;
+    }
+    return path.join(root, ...normalizedRemote.split("/").filter(Boolean));
+}
+function normalizeRemotePath(remotePath) {
+    const trimmed = typeof remotePath === "string" ? remotePath.trim() : "";
+    if (!trimmed || trimmed === "/") {
+        return "/";
+    }
+    const slashNormalized = trimmed.replace(/\\/g, "/");
+    const normalized = path.posix.normalize(slashNormalized.startsWith("/") ? slashNormalized : `/${slashNormalized}`);
+    return normalized === "/" ? "/" : normalized.replace(/\/+$/, "");
+}
 function normalizeIsoString(value) {
     if (typeof value !== "string" || value.trim() === "") {
         return undefined;

package/dist/setup-types.d.ts

@@ -67,6 +67,8 @@ export interface WorkspaceMountEnvOptions {
 }
 export type WorkspaceMountEnv = Record<string, string>;
 export type MountMode = "poll" | "fuse";
+export type MountLocalLayout = "exact" | "scoped";
+export type MountSyncMode = "mirror" | "write-only";
 export interface MountSessionRequest {
     localDir: string;
     remotePath?: string;
@@ -98,6 +100,8 @@ export interface MountSessionResult {
     remotePath: string;
     localDir: string;
     mode: MountMode;
+    localLayout: MountLocalLayout;
+    syncMode: MountSyncMode;
     scopes: string[];
     tokenIssuedAt: string | null;
     expiresAt: string | null;
@@ -122,6 +126,8 @@ export interface ReadMountedWorkspaceStatusInput {
     workspaceId: string;
     remotePath: string;
     mode: MountMode;
+    localLayout?: MountLocalLayout;
+    syncMode?: MountSyncMode;
     relayfileBaseUrl: string;
     relayfileToken: string;
     expiresAt: string | null;
@@ -167,6 +173,8 @@ export interface MountWorkspaceInput {
     localDir: string;
     remotePath?: string;
     mode?: MountMode;
+    localLayout?: MountLocalLayout;
+    syncMode?: MountSyncMode;
     background?: boolean;
     agentName?: string;
     scopes?: string[];

package/dist/setup.js

@@ -16,6 +16,8 @@ const DEFAULT_WAIT_INTERVAL_MS = 2_000;
 const DEFAULT_WAIT_TIMEOUT_MS = 300_000;
 const DEFAULT_MOUNT_READY_TIMEOUT_MS = 60_000;
 const DEFAULT_MOUNT_AGENT_NAME = "relayfile-mount";
+const DEFAULT_MOUNT_LOCAL_LAYOUT = "exact";
+const DEFAULT_MOUNT_SYNC_MODE = "mirror";
 const TOKEN_REFRESH_AGE_MS = 55 * 60 * 1000;
 const nodeOnlyMountLauncher = {
     async start() {
@@ -142,6 +144,8 @@ export class RelayfileSetup {
             localDir: normalized.localDir,
             remotePath: normalized.remotePath,
             mode: normalized.mode,
+            localLayout: normalized.localLayout,
+            syncMode: normalized.syncMode,
             background: normalized.background,
             agentName: normalized.agentName,
             scopes: normalized.scopes,
@@ -246,13 +250,18 @@ export class RelayfileSetup {
                 : undefined
         });
         try {
-            return validateMountSessionResponse(await workspace.requestJson({
+            const session = validateMountSessionResponse(await workspace.requestJson({
                 operation: "mountWorkspace",
                 method: "POST",
                 path: `api/v1/workspaces/${encodeURIComponent(workspace.workspaceId)}/relayfile/mount-session`,
                 body: request,
                 signal: input.signal
             }), input.localDir);
+            return {
+                ...session,
+                localLayout: input.localLayout,
+                syncMode: input.syncMode
+            };
         }
         catch (error) {
             throw mapMountSessionError(error, request);
@@ -731,6 +740,8 @@ class MountedWorkspaceHandleImpl {
             workspaceId: this.workspaceId,
             remotePath: this.remotePath,
             mode: this.mode,
+            localLayout: this.mountSession.localLayout,
+            syncMode: this.mountSession.syncMode,
             relayfileBaseUrl: this.mountSession.relayfileBaseUrl,
             relayfileToken: this.mountSession.relayfileToken,
             expiresAt: this.expiresAt,
@@ -837,6 +848,8 @@ function validateMountSessionResponse(payload, localDir) {
         remotePath: requireStringField(payload, "remotePath"),
         localDir,
         mode: requireMountModeField(payload, "mode"),
+        localLayout: DEFAULT_MOUNT_LOCAL_LAYOUT,
+        syncMode: DEFAULT_MOUNT_SYNC_MODE,
         scopes: requireStringArrayField(payload, "scopes"),
         tokenIssuedAt: readNullableStringField(payload, "tokenIssuedAt"),
         expiresAt: readNullableStringField(payload, "expiresAt"),
@@ -930,6 +943,8 @@ function normalizeMountWorkspaceInput(input) {
         localDir: resolveLocalDir(localDir),
         remotePath: normalizeMountRemotePath(input.remotePath),
         mode: normalizeMountModeInput(input.mode),
+        localLayout: normalizeMountLocalLayoutInput(input.localLayout),
+        syncMode: normalizeMountSyncModeInput(input.syncMode),
         background: input.background !== false,
         agentName: normalizeNonEmptyString(input.agentName),
         scopes: input.scopes && input.scopes.length > 0 ? [...input.scopes] : undefined,
@@ -954,6 +969,20 @@ function normalizeMountModeInput(mode) {
     }
     return normalized;
 }
+function normalizeMountLocalLayoutInput(layout) {
+    const normalized = normalizeNonEmptyString(layout) ?? DEFAULT_MOUNT_LOCAL_LAYOUT;
+    if (normalized !== "exact" && normalized !== "scoped") {
+        throw new MountSessionInputError(`Invalid localLayout "${normalized}" for mount session.`);
+    }
+    return normalized;
+}
+function normalizeMountSyncModeInput(mode) {
+    const normalized = normalizeNonEmptyString(mode) ?? DEFAULT_MOUNT_SYNC_MODE;
+    if (normalized !== "mirror" && normalized !== "write-only") {
+        throw new MountSessionInputError(`Invalid syncMode "${normalized}" for mount session.`);
+    }
+    return normalized;
+}
 function normalizeMountRemotePath(remotePath) {
     const normalized = normalizeNonEmptyString(remotePath) ?? "/";
     if (normalized.includes("\u0000")) {
@@ -1052,6 +1081,8 @@ function buildMountedWorkspaceEnv(mountSession) {
         RELAYFILE_REMOTE_PATH: mountSession.remotePath,
         RELAYFILE_LOCAL_DIR: mountSession.localDir,
         RELAYFILE_MOUNT_MODE: mountSession.mode,
+        RELAYFILE_MOUNT_LOCAL_LAYOUT: mountSession.localLayout,
+        RELAYFILE_MOUNT_SYNC_MODE: mountSession.syncMode,
         RELAYCAST_API_KEY: mountSession.relaycastApiKey,
         RELAY_API_KEY: mountSession.relaycastApiKey,
         RELAYCAST_BASE_URL: relaycastBaseUrl,

package/dist/types.d.ts

@@ -700,12 +700,58 @@ export interface AckWritebackInput {
     itemId: string;
     success: boolean;
     error?: string;
+    /**
+     * Provider-assigned id of the created/updated object (e.g. the Slack
+     * message ts). When present on a successful ack, the service reconciles
+     * the agent-authored draft file per the draftFile() rename contract
+     * (issue #242): the draft is renamed to the canonical id, or removed when
+     * the canonical record already materialized. The mutation is
+     * classification-exempt — it can never enqueue a new writeback.
+     */
+    externalId?: string;
+    /**
+     * Optional canonical projection path for the draft rename. Must stay under
+     * the same provider root as the draft; otherwise the service falls back to
+     * the externalId-derived name next to the draft.
+     */
+    canonicalPath?: string;
     correlationId?: string;
     signal?: AbortSignal;
 }
+/** Disposition of the agent-authored draft file after a successful ack. */
+export interface AckWritebackDraftDisposition {
+    action: "renamed" | "removed" | "none";
+    from?: string;
+    to?: string;
+}
 export interface AckWritebackResponse {
     status: "acknowledged";
     id: string;
     correlationId?: string;
     success: boolean;
+    /** Present only when the ack was successful and carried an externalId. */
+    draft?: AckWritebackDraftDisposition;
+}
+export interface SweepWritebackDraftsInput {
+    workspaceId: string;
+    /** Restrict the sweep to a subtree. */
+    pathPrefix?: string;
+    /** Basename globs for hand-named drafts, e.g. "wb-*.json". */
+    patterns?: string[];
+    /** Execute removals; when false the sweep is a dry run. */
+    apply?: boolean;
+    correlationId?: string;
+    signal?: AbortSignal;
+}
+export interface SweepWritebackDraftsResponse {
+    dryRun: boolean;
+    scanned: number;
+    removed: Array<{
+        path: string;
+        reason: "space-uuid-draft" | "pattern";
+    }>;
+    skipped: Array<{
+        path: string;
+        reason: "pending-writeback" | "provider-linked";
+    }>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/sdk",
-  "version": "0.8.10",
+  "version": "0.8.12",
   "description": "TypeScript SDK for relayfile — real-time filesystem for humans and agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -55,7 +55,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@relayfile/core": "0.8.10",
+    "@relayfile/core": "0.8.12",
     "ignore": "^7.0.5",
     "tar": "^7.5.10"
   },