@gatherthread/dsh-host 0.1.0-alpha.2 → 0.1.0-alpha.4

package/README.md

@@ -19,7 +19,7 @@ The package does not install a DSH runtime dependency.
 After `@gatherthread/dsh-host` is published, the ordinary three-step path is:
 
 ```text
-npx @deepseek-ai/dsh@0.1.2-rc.1 plugin --profile web add @gatherthread/dsh-host@0.1.0-alpha.2
+npx @deepseek-ai/dsh@0.1.2-rc.1 plugin --profile web add @gatherthread/dsh-host@0.1.0-alpha.4
 npx @deepseek-ai/dsh@0.1.2-rc.1 web
 # In DSH: Settings -> GatherThread / 共序 -> Sign in and pair
 ```
@@ -159,3 +159,10 @@ same runtime advance the projection cursor but are not appended back to DSH,
 while events written through another harness are imported normally. V1
 connector state deliberately restarts only the native projection cursor at zero
 once so history that the earlier poller observed but discarded is backfilled.
+
+Automatic upload is stored independently for every bound DSH conversation and
+defaults on. In **Settings -> GatherThread / 共序**, the user can switch it off
+without stopping cloud-to-local projection, or choose **Manual upload** to scan
+and send completed eligible local turns. The manual action is also the recovery
+path after a missed native event or transport interruption, uses the existing
+durable idempotent outbox, and never silently re-enables automatic upload.

package/bundle/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "name": "@gatherthread/dsh-host",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.4",
   "license": "Apache-2.0",
   "defaultEnabled": false,
   "hostEntry": "@gatherthread/dsh-host",

package/client/client.js

@@ -105,7 +105,9 @@ function GatherThreadStatusPanel({ connection, sessions }) {
       }
       onSuccess?.(next);
     } catch {
-      setNotice("操作未完成。请检查服务器地址、当前授权和模型配置。");
+      setNotice(endpoint.startsWith("sync/")
+        ? "上传操作未完成。请检查连接和会话权限后重试。"
+        : "操作未完成。请检查服务器地址、当前授权和模型配置。");
     } finally {
       setBusy(false);
     }
@@ -129,7 +131,9 @@ function GatherThreadStatusPanel({ connection, sessions }) {
   React.createElement("p", { style: styles.summary },
     `活跃会话 ${String(snapshot?.activeSessionCount ?? 0)} / ${String(sessionRows.length)}`),
   React.createElement("div", { style: styles.list },
-    ...sessionRows.map((session) => React.createElement("div", {
+    ...sessionRows.map((session) => {
+      const sync = nativeState?.localSync?.find((item) => item.sessionId === session.sessionId);
+      return React.createElement("div", {
       key: session.sessionId,
       style: styles.row,
     },
@@ -137,7 +141,30 @@ function GatherThreadStatusPanel({ connection, sessions }) {
       React.createElement("strong", { style: styles.sessionTitle }, session.title),
       React.createElement("span", { style: styles.sessionMeta },
         session.lastSyncedAt === undefined ? "尚未同步" : `最近同步 ${formatTime(session.lastSyncedAt)}`)),
-    React.createElement("span", { style: badgeStyle(session.state) }, statusLabel(session.state))))),
+    sync === undefined ? React.createElement("span", { style: badgeStyle(session.state) }, statusLabel(session.state))
+      : React.createElement("div", { style: styles.syncActions },
+        React.createElement("label", { style: styles.syncToggle },
+          React.createElement("input", {
+            type: "checkbox",
+            checked: sync.automaticUpload,
+            disabled: busy,
+            onChange: (event) => void runAction("sync/set-auto-upload", {
+              projectId: sync.projectId,
+              sessionId: sync.sessionId,
+              enabled: event.target.checked,
+            }),
+          }),
+          "自动上传"),
+        React.createElement("button", {
+          type: "button",
+          disabled: busy || sync.uploadableLocalTurns < 1,
+          style: styles.compactButton,
+          onClick: () => void runAction("sync/upload", {
+            projectId: sync.projectId,
+            sessionId: sync.sessionId,
+          }),
+        }, sync.uploadableLocalTurns > 0 ? `手动上传 ${String(sync.uploadableLocalTurns)}` : "已上传")));
+    })),
   nativeState === undefined || unavailable
     ? null
     : renderNativeControls({
@@ -386,7 +413,7 @@ function detail(label, value) {
 function parseNativeState(value) {
   exactObject(value, [
     "schemaVersion", "integration", "authorization", "compatibility", "runtime",
-    "officialServerUrl", "serverUrl", "deviceName", "route", "projectCount", "bindings", "pairing", "recoverableError",
+    "officialServerUrl", "serverUrl", "deviceName", "route", "projectCount", "bindings", "localSync", "pairing", "recoverableError",
   ]);
   if (value.schemaVersion !== 2 || value.integration !== "gatherthread") throw new Error("invalid native status identity");
   if (!AUTHORIZATION_STATES.has(value.authorization)) throw new Error("invalid native authorization state");
@@ -409,6 +436,7 @@ function parseNativeState(value) {
   if (value.deviceName !== undefined) boundedText(value.deviceName, 120);
   let route;
   let bindings;
+  let localSync;
   if (value.route !== undefined || value.bindings !== undefined || value.projectCount !== undefined) {
     if (value.route === undefined || !Number.isSafeInteger(value.projectCount) || value.projectCount < 0
       || !Array.isArray(value.bindings) || value.bindings.length > 100
@@ -430,6 +458,25 @@ function parseNativeState(value) {
       }
       return { ...binding };
     });
+    const localSyncValue = value.localSync ?? [];
+    if (!Array.isArray(localSyncValue) || localSyncValue.length > 100) throw new Error("invalid local sync status");
+    localSync = localSyncValue.map((sync) => {
+      exactObject(sync, [
+        "projectId", "projectName", "sessionId", "localSessionId", "title", "automaticUpload",
+        "pendingLocalTurns", "uploadableLocalTurns",
+      ]);
+      boundedText(sync.projectId, 128);
+      boundedText(sync.projectName, 160);
+      boundedText(sync.sessionId, 128);
+      boundedText(sync.localSessionId, 200);
+      boundedText(sync.title, 160);
+      if (typeof sync.automaticUpload !== "boolean"
+        || !Number.isSafeInteger(sync.pendingLocalTurns) || sync.pendingLocalTurns < 0
+        || !Number.isSafeInteger(sync.uploadableLocalTurns) || sync.uploadableLocalTurns < 0) {
+        throw new Error("invalid local sync status");
+      }
+      return { ...sync };
+    });
   }
   let pairing;
   if (value.pairing !== undefined) {
@@ -465,7 +512,7 @@ function parseNativeState(value) {
     ...(officialServerUrl === undefined ? {} : { officialServerUrl }),
     ...(serverUrl === undefined ? {} : { serverUrl }),
     ...(value.deviceName === undefined ? {} : { deviceName: value.deviceName }),
-    ...(route === undefined ? {} : { route, projectCount: value.projectCount, bindings }),
+    ...(route === undefined ? {} : { route, projectCount: value.projectCount, bindings, localSync }),
     ...(pairing === undefined ? {} : { pairing }),
     ...(value.recoverableError === undefined ? {} : { recoverableError: value.recoverableError }),
   };
@@ -592,6 +639,9 @@ const styles = {
   sessionText: { minWidth: 0, display: "grid", gap: 3 },
   sessionTitle: { overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap", fontSize: 14 },
   sessionMeta: { opacity: 0.62, fontSize: 12 },
+  syncActions: { flex: "none", display: "grid", justifyItems: "end", gap: 6 },
+  syncToggle: { display: "inline-flex", alignItems: "center", gap: 5, fontSize: 12, cursor: "pointer" },
+  compactButton: { minHeight: 28, padding: "4px 8px", borderRadius: 8, border: "1px solid rgba(127,127,127,.3)", background: "transparent", color: "inherit", font: "inherit", fontSize: 12, cursor: "pointer" },
   badge: { flex: "none", padding: "4px 8px", borderRadius: 999, fontSize: 12, fontWeight: 600, background: "rgba(127,127,127,.12)", color: "inherit", border: "1px solid rgba(127,127,127,.2)" },
   connectionCard: { display: "grid", gap: 12, padding: "14px", border: "1px solid rgba(127,127,127,.2)", borderRadius: 14, background: "rgba(127,127,127,.06)" },
   subheading: { display: "grid", gap: 4 },

package/dist/bundle/native-plugin.js

@@ -191,10 +191,10 @@ var HttpCollaborationClient = class {
     const body = requiredObject(await this.#request(`/snapshot-requests/${encodeURIComponent(requestId)}`));
     return fromWireSnapshotRequest(body.snapshot_request ?? body);
   }
-  async createSnapshotRequest(sessionId) {
+  async createSnapshotRequest(sessionId, kind = "immutable") {
     const body = requiredObject(await this.#request(`/sessions/${encodeURIComponent(sessionId)}/snapshot-requests`, {
       method: "POST",
-      body: "{}"
+      body: JSON.stringify({ kind })
     }));
     return fromWireSnapshotRequest(body.snapshot_request ?? body);
   }
@@ -315,6 +315,7 @@ function fromWireSnapshotRequest(value) {
   return {
     id: requiredString(input.id, "snapshot_request.id"),
     sessionId: requiredString(input.session_id, "snapshot_request.session_id"),
+    kind: input.kind === "visible_history_replace" ? "visible_history_replace" : "immutable",
     throughSequence: requiredNumber(input.through_sequence, "snapshot_request.through_sequence"),
     status,
     ...createdAt === void 0 ? {} : { createdAt },
@@ -1398,6 +1399,7 @@ var DshHostConnector = class {
   #timer;
   #heartbeatTimer;
   #pollPromise;
+  #localSyncControlPromise;
   #heartbeatPromise;
   #stopPromise;
   #backgroundFatalError;
@@ -1429,6 +1431,47 @@ var DshHostConnector = class {
   get stopped() {
     return this.#stopped;
   }
+  localSyncStatus() {
+    const state = this.#requireState();
+    const pendingOperations = state.outbox.filter((operation) => operation.kind === "local_turn");
+    const pending = pendingOperations.length;
+    const discoverFrom = pendingOperations.reduce((sequence, operation) => Math.max(sequence, operation.dshToSequence), state.publishedDshSequence);
+    const discoverable = state.activeRequest === void 0 ? captureCompletedLocalTurns(this.#host.snapshotFrom(discoverFrom), discoverFrom, this.#config.dshSessionId).turns.length : 0;
+    return {
+      sessionId: this.#config.sessionId,
+      localSessionId: this.#config.dshSessionId,
+      automaticUpload: state.automaticUpload,
+      pendingLocalTurns: pending,
+      uploadableLocalTurns: pending + discoverable
+    };
+  }
+  async setLocalAutoUpload(enabled) {
+    const status = await this.#withLocalSyncControl(async () => {
+      const state = this.#requireState();
+      state.automaticUpload = enabled;
+      await this.#stateStore.save(state);
+      return this.localSyncStatus();
+    });
+    if (enabled)
+      await this.pollOnce();
+    return enabled ? this.localSyncStatus() : status;
+  }
+  uploadLocalTurns() {
+    return this.#withLocalSyncControl(async () => {
+      const before = this.localSyncStatus();
+      await this.#flushOutbox(true);
+      await this.#captureLocalTurns(0);
+      const discoveredLocalTurns = this.localSyncStatus().pendingLocalTurns;
+      const pendingBefore = this.localSyncStatus().pendingLocalTurns;
+      await this.#flushOutbox(true);
+      const after = this.localSyncStatus();
+      return {
+        ...after,
+        discoveredLocalTurns,
+        uploadedLocalTurns: Math.max(0, before.pendingLocalTurns + pendingBefore - after.pendingLocalTurns)
+      };
+    });
+  }
   async start(options = {}) {
     if (this.#started)
       throw new Error("DSH connector is already started");
@@ -1493,7 +1536,7 @@ var DshHostConnector = class {
       this.#notifyLifecycle("idle");
       if (options.schedule !== false)
         this.#scheduleHeartbeat();
-      await this.#flushOutbox();
+      await this.#flushOutbox(this.#requireState().automaticUpload);
       await this.#finalizeDeliveredRequest();
       if (this.#state.activeRequest !== void 0) {
         await this.#withExecutionPermit(() => this.#recoverActiveRequest());
@@ -1514,6 +1557,10 @@ var DshHostConnector = class {
     if (!this.#started || this.#stopped) {
       return Promise.reject(new Error("DSH connector is not running"));
     }
+    const localSyncControl = this.#localSyncControlPromise;
+    if (localSyncControl !== void 0) {
+      return localSyncControl.then(() => this.pollOnce());
+    }
     if (this.#pollPromise !== void 0)
       return this.#pollPromise;
     this.#pollPromise = this.#poll().then((result) => {
@@ -1528,6 +1575,28 @@ var DshHostConnector = class {
     });
     return this.#pollPromise;
   }
+  async #withLocalSyncControl(operation) {
+    const previous = this.#localSyncControlPromise;
+    let release;
+    const barrier = new Promise((resolve) => {
+      release = resolve;
+    });
+    const current = (previous ?? Promise.resolve()).then(() => barrier);
+    this.#localSyncControlPromise = current;
+    try {
+      await previous;
+      const poll = this.#pollPromise;
+      if (poll !== void 0)
+        await poll;
+      if (!this.#started || this.#stopped)
+        throw new Error("DSH connector is not running");
+      return await operation();
+    } finally {
+      release();
+      if (this.#localSyncControlPromise === current)
+        this.#localSyncControlPromise = void 0;
+    }
+  }
   stop() {
     this.#stopPromise ??= (async () => {
       this.#stopped = true;
@@ -1557,14 +1626,17 @@ var DshHostConnector = class {
   }
   async #poll() {
     const state = this.#requireState();
-    await this.#flushOutbox();
+    await this.#flushOutbox(state.automaticUpload);
     await this.#finalizeDeliveredRequest();
     if (state.activeRequest !== void 0) {
       await this.#withExecutionPermit(() => this.#recoverActiveRequest());
       return { scanned: 0, claimed: 0, completed: 1 };
     }
-    await this.#captureLocalTurns();
-    await this.#flushOutbox();
+    if (state.automaticUpload) {
+      await this.#captureLocalTurns();
+      await this.#flushOutbox(true);
+    }
+    const manualUploadRequired = !state.automaticUpload && this.localSyncStatus().uploadableLocalTurns > 0;
     let scanCursor = state.projectionCursor;
     let scanned = 0;
     while (!this.#stopped) {
@@ -1580,6 +1652,9 @@ var DshHostConnector = class {
           continue;
         }
         await this.#projectCanonicalBatch(passive, passive.at(-1)?.sequence ?? state.projectionCursor);
+        if (manualUploadRequired) {
+          return { scanned, claimed: 0, completed: 0 };
+        }
         if (profile.provider !== void 0 && profile.provider !== this.#config.provider) {
           throw new Error("DeepSeek Harness Agent request provider does not match the configured Host binding");
         }
@@ -1757,7 +1832,7 @@ var DshHostConnector = class {
     state.serverCursor = Math.max(state.serverCursor, throughSequence);
     await this.#stateStore.save(state);
   }
-  async #captureLocalTurns() {
+  async #captureLocalTurns(basedOnSequence) {
     const state = this.#requireState();
     if (state.activeRequest !== void 0 || state.outbox.length > 0)
       return;
@@ -1775,7 +1850,7 @@ var DshHostConnector = class {
       input: {
         localTurnId: turn.localTurnId,
         runtimeId: runtime.id,
-        basedOnSequence: state.serverCursor,
+        basedOnSequence: basedOnSequence ?? state.serverCursor,
         occurredAt: turn.occurredAt,
         observedModel: this.#config.model,
         requestPayload: {
@@ -1877,13 +1952,15 @@ var DshHostConnector = class {
     });
     return operations;
   }
-  async #flushOutbox() {
+  async #flushOutbox(includeLocalTurns = true) {
     const state = this.#requireState();
     const runtime = this.#requireRuntime();
     while (state.outbox.length > 0) {
       const operation = state.outbox[0];
       if (operation === void 0)
         break;
+      if (operation.kind === "local_turn" && !includeLocalTurns)
+        break;
       if (operation.input.runtimeId !== runtime.id) {
         throw new Error("DSH connector outbox belongs to a different runtime");
       }
@@ -1965,7 +2042,7 @@ var DshHostConnector = class {
         throw new Error("Persisted DSH Session exists without connector state; refusing ambiguous resume");
       }
       return {
-        version: 2,
+        version: 3,
         binding: {
           projectId: this.#config.projectId,
           sessionId: this.#config.sessionId,
@@ -1974,6 +2051,7 @@ var DshHostConnector = class {
         serverCursor: 0,
         projectionCursor: 0,
         publishedDshSequence: 0,
+        automaticUpload: true,
         outbox: []
       };
     }
@@ -3273,6 +3351,21 @@ var DshProjectManager = class {
   activeSessionIds() {
     return [...this.#managed].filter(([, binding]) => binding.phase === "active" && !binding.connector.stopped).map(([sessionId]) => sessionId).sort();
   }
+  localSyncStatuses() {
+    return [...this.#managed.entries()].filter(([, binding]) => binding.phase === "active" && !binding.connector.stopped).flatMap(([, binding]) => binding.connector.localSyncStatus?.() ?? []).sort((left, right) => left.sessionId.localeCompare(right.sessionId));
+  }
+  async setLocalAutoUpload(sessionId, enabled) {
+    const connector = this.#requireManagedConnector(sessionId);
+    if (!connector.setLocalAutoUpload)
+      throw new Error("This DSH conversation does not support upload controls");
+    return connector.setLocalAutoUpload(enabled);
+  }
+  async uploadLocalTurns(sessionId) {
+    const connector = this.#requireManagedConnector(sessionId);
+    if (!connector.uploadLocalTurns)
+      throw new Error("This DSH conversation does not support manual upload");
+    return connector.uploadLocalTurns();
+  }
   async start() {
     if (this.#started)
       throw new Error("DSH project manager is already started");
@@ -3512,6 +3605,13 @@ var DshProjectManager = class {
       throw new Error("Authenticated GatherThread actor is unavailable");
     return this.#actor;
   }
+  #requireManagedConnector(sessionId) {
+    const binding = this.#managed.get(sessionId);
+    if (!binding || binding.phase !== "active" || binding.connector.stopped) {
+      throw new Error("The selected DSH conversation is not active");
+    }
+    return binding.connector;
+  }
   #reportError(error) {
     this.#onBackgroundError?.(error);
   }
@@ -3660,17 +3760,20 @@ var FileConnectorStateStore = class {
 function validateConnectorState(value) {
   const state = requiredObject4(value, "state");
   const legacy = state.version === 1;
+  const legacyUploadPolicy = state.version === 1 || state.version === 2;
   exactKeys(state, /* @__PURE__ */ new Set([
     "version",
     "binding",
     "serverCursor",
     ...legacy ? [] : ["projectionCursor"],
     "publishedDshSequence",
+    ...legacyUploadPolicy ? [] : ["automaticUpload"],
     "activeRequest",
     "outbox"
   ]), "state");
-  if (!legacy && state.version !== 2)
+  if (state.version !== 1 && state.version !== 2 && state.version !== 3) {
     throw new Error("Unsupported DSH connector state version");
+  }
   const binding = requiredObject4(state.binding, "state.binding");
   exactKeys(binding, /* @__PURE__ */ new Set(["projectId", "sessionId", "dshSessionId"]), "state.binding");
   const serverCursor = nonNegativeInteger(state.serverCursor, "state.serverCursor");
@@ -3681,7 +3784,7 @@ function validateConnectorState(value) {
     throw new Error("state.outbox must be an array");
   const outbox = state.outbox.map(parseOutboxOperation);
   const validated = {
-    version: 2,
+    version: 3,
     binding: {
       projectId: safeString(binding.projectId, "state.binding.projectId", 128),
       sessionId: safeString(binding.sessionId, "state.binding.sessionId", 128),
@@ -3690,6 +3793,7 @@ function validateConnectorState(value) {
     serverCursor,
     projectionCursor,
     publishedDshSequence,
+    automaticUpload: legacyUploadPolicy ? true : requiredBoolean(state.automaticUpload, "state.automaticUpload"),
     ...activeRequest === void 0 ? {} : { activeRequest },
     outbox
   };
@@ -3869,6 +3973,11 @@ function nonNegativeInteger(value, label) {
   }
   return Number(value);
 }
+function requiredBoolean(value, label) {
+  if (typeof value !== "boolean")
+    throw new Error(`${label} must be a boolean`);
+  return value;
+}
 function positiveInteger(value, label) {
   const parsed = nonNegativeInteger(value, label);
   if (parsed === 0)
@@ -4133,7 +4242,9 @@ var RPC_ENDPOINTS = /* @__PURE__ */ new Set([
   "pairing/cancel",
   "catalog/get",
   "connection/configure",
-  "connection/disconnect"
+  "connection/disconnect",
+  "sync/set-auto-upload",
+  "sync/upload"
 ]);
 var MAX_CATALOG_PROVIDERS = 64;
 var MAX_CATALOG_MODELS = 256;
@@ -4202,7 +4313,8 @@ var DshNativeHostController = class {
         ...this.#grant.route === void 0 ? {} : {
           route: { ...this.#grant.route },
           projectCount: this.#projects.size,
-          bindings: this.#currentBindings(this.#grant.route).slice(0, 100)
+          bindings: this.#currentBindings(this.#grant.route).slice(0, 100),
+          localSync: this.#currentLocalSync().slice(0, 100)
         }
       },
       ...this.#pairing === void 0 ? {} : {
@@ -4371,6 +4483,34 @@ var DshNativeHostController = class {
     this.#options.status.setConnection("stopped");
     return this.publicState();
   }
+  async setLocalAutoUpload(inputValue) {
+    this.#assertAvailable();
+    const input = exactInput(inputValue, /* @__PURE__ */ new Set(["projectId", "sessionId", "enabled"]));
+    const projectId = safeInputIdentifier(input.projectId, "projectId");
+    const sessionId = safeInputIdentifier(input.sessionId, "sessionId");
+    if (typeof input.enabled !== "boolean")
+      throw new Error("enabled must be true or false");
+    const owner = this.#owners.get(projectId);
+    if (!owner)
+      throw new Error("The selected GatherThread Project is not active");
+    if (!owner.setLocalAutoUpload)
+      throw new Error("This DSH Project does not expose upload controls");
+    await owner.setLocalAutoUpload(sessionId, input.enabled);
+    return this.publicState();
+  }
+  async uploadLocalTurns(inputValue) {
+    this.#assertAvailable();
+    const input = exactInput(inputValue, /* @__PURE__ */ new Set(["projectId", "sessionId"]));
+    const projectId = safeInputIdentifier(input.projectId, "projectId");
+    const sessionId = safeInputIdentifier(input.sessionId, "sessionId");
+    const owner = this.#owners.get(projectId);
+    if (!owner)
+      throw new Error("The selected GatherThread Project is not active");
+    if (!owner.uploadLocalTurns)
+      throw new Error("This DSH Project does not expose manual upload");
+    await owner.uploadLocalTurns(sessionId);
+    return this.publicState();
+  }
   dispose() {
     this.#disposePromise ??= (async () => {
       this.#disposed = true;
@@ -4507,6 +4647,20 @@ var DshNativeHostController = class {
       model: route.model
     })).sort((left, right) => left.projectName.localeCompare(right.projectName) || left.projectId.localeCompare(right.projectId));
   }
+  #currentLocalSync() {
+    const titles = new Map(this.#options.status.snapshot().sessions.map((session) => [session.sessionId, session.title]));
+    return [...this.#owners.entries()].flatMap(([projectId, owner]) => {
+      const project = this.#projects.get(projectId);
+      if (!project)
+        return [];
+      return (owner.localSyncStatuses?.() ?? []).map((sync) => ({
+        ...sync,
+        projectId,
+        projectName: boundedPublicText2(project.name, "project name", 160),
+        title: titles.get(sync.sessionId) ?? sync.sessionId
+      }));
+    }).sort((left, right) => left.projectName.localeCompare(right.projectName) || left.title.localeCompare(right.title) || left.sessionId.localeCompare(right.sessionId));
+  }
   #updateProjectStatus(projectId, update) {
     if (!this.#projects.has(projectId) || this.#disposed)
       return;
@@ -4628,6 +4782,10 @@ function registerNativeDshRpc(contextValue, controller) {
         case "connection/disconnect":
           exactInput(payload, /* @__PURE__ */ new Set());
           return rpcSuccess(await controller.disconnect());
+        case "sync/set-auto-upload":
+          return rpcSuccess(await controller.setLocalAutoUpload(payload));
+        case "sync/upload":
+          return rpcSuccess(await controller.uploadLocalTurns(payload));
         default:
           return rpcFailure("gatherthread/not-found", "GatherThread DSH action is unavailable");
       }
@@ -4709,6 +4867,9 @@ async function createProductionOwner(options) {
   }
   let stopPromise;
   return {
+    localSyncStatuses: () => manager.localSyncStatuses(),
+    setLocalAutoUpload: (sessionId, enabled) => manager.setLocalAutoUpload(sessionId, enabled),
+    uploadLocalTurns: (sessionId) => manager.uploadLocalTurns(sessionId),
     stop() {
       stopPromise ??= (async () => {
         options.signal.removeEventListener("abort", abortFromRoot);
@@ -4773,6 +4934,9 @@ function createNativeManagedConnector(options) {
     async start() {
       await connector.start();
     },
+    localSyncStatus: () => connector.localSyncStatus(),
+    setLocalAutoUpload: (enabled) => connector.setLocalAutoUpload(enabled),
+    uploadLocalTurns: () => connector.uploadLocalTurns(),
     stop() {
       stopPromise ??= (async () => {
         options.rootSignal.removeEventListener("abort", abortFromRoot);

package/dist/bundle/plugin.js

@@ -512,10 +512,10 @@ var HttpCollaborationClient = class {
     const body = requiredObject2(await this.#request(`/snapshot-requests/${encodeURIComponent(requestId)}`));
     return fromWireSnapshotRequest(body.snapshot_request ?? body);
   }
-  async createSnapshotRequest(sessionId) {
+  async createSnapshotRequest(sessionId, kind = "immutable") {
     const body = requiredObject2(await this.#request(`/sessions/${encodeURIComponent(sessionId)}/snapshot-requests`, {
       method: "POST",
-      body: "{}"
+      body: JSON.stringify({ kind })
     }));
     return fromWireSnapshotRequest(body.snapshot_request ?? body);
   }
@@ -636,6 +636,7 @@ function fromWireSnapshotRequest(value) {
   return {
     id: requiredString2(input.id, "snapshot_request.id"),
     sessionId: requiredString2(input.session_id, "snapshot_request.session_id"),
+    kind: input.kind === "visible_history_replace" ? "visible_history_replace" : "immutable",
     throughSequence: requiredNumber(input.through_sequence, "snapshot_request.through_sequence"),
     status,
     ...createdAt === void 0 ? {} : { createdAt },
@@ -1309,6 +1310,7 @@ var DshHostConnector = class {
   #timer;
   #heartbeatTimer;
   #pollPromise;
+  #localSyncControlPromise;
   #heartbeatPromise;
   #stopPromise;
   #backgroundFatalError;
@@ -1340,6 +1342,47 @@ var DshHostConnector = class {
   get stopped() {
     return this.#stopped;
   }
+  localSyncStatus() {
+    const state = this.#requireState();
+    const pendingOperations = state.outbox.filter((operation) => operation.kind === "local_turn");
+    const pending = pendingOperations.length;
+    const discoverFrom = pendingOperations.reduce((sequence, operation) => Math.max(sequence, operation.dshToSequence), state.publishedDshSequence);
+    const discoverable = state.activeRequest === void 0 ? captureCompletedLocalTurns(this.#host.snapshotFrom(discoverFrom), discoverFrom, this.#config.dshSessionId).turns.length : 0;
+    return {
+      sessionId: this.#config.sessionId,
+      localSessionId: this.#config.dshSessionId,
+      automaticUpload: state.automaticUpload,
+      pendingLocalTurns: pending,
+      uploadableLocalTurns: pending + discoverable
+    };
+  }
+  async setLocalAutoUpload(enabled) {
+    const status = await this.#withLocalSyncControl(async () => {
+      const state = this.#requireState();
+      state.automaticUpload = enabled;
+      await this.#stateStore.save(state);
+      return this.localSyncStatus();
+    });
+    if (enabled)
+      await this.pollOnce();
+    return enabled ? this.localSyncStatus() : status;
+  }
+  uploadLocalTurns() {
+    return this.#withLocalSyncControl(async () => {
+      const before = this.localSyncStatus();
+      await this.#flushOutbox(true);
+      await this.#captureLocalTurns(0);
+      const discoveredLocalTurns = this.localSyncStatus().pendingLocalTurns;
+      const pendingBefore = this.localSyncStatus().pendingLocalTurns;
+      await this.#flushOutbox(true);
+      const after = this.localSyncStatus();
+      return {
+        ...after,
+        discoveredLocalTurns,
+        uploadedLocalTurns: Math.max(0, before.pendingLocalTurns + pendingBefore - after.pendingLocalTurns)
+      };
+    });
+  }
   async start(options = {}) {
     if (this.#started)
       throw new Error("DSH connector is already started");
@@ -1404,7 +1447,7 @@ var DshHostConnector = class {
       this.#notifyLifecycle("idle");
       if (options.schedule !== false)
         this.#scheduleHeartbeat();
-      await this.#flushOutbox();
+      await this.#flushOutbox(this.#requireState().automaticUpload);
       await this.#finalizeDeliveredRequest();
       if (this.#state.activeRequest !== void 0) {
         await this.#withExecutionPermit(() => this.#recoverActiveRequest());
@@ -1425,6 +1468,10 @@ var DshHostConnector = class {
     if (!this.#started || this.#stopped) {
       return Promise.reject(new Error("DSH connector is not running"));
     }
+    const localSyncControl = this.#localSyncControlPromise;
+    if (localSyncControl !== void 0) {
+      return localSyncControl.then(() => this.pollOnce());
+    }
     if (this.#pollPromise !== void 0)
       return this.#pollPromise;
     this.#pollPromise = this.#poll().then((result) => {
@@ -1439,6 +1486,28 @@ var DshHostConnector = class {
     });
     return this.#pollPromise;
   }
+  async #withLocalSyncControl(operation) {
+    const previous = this.#localSyncControlPromise;
+    let release;
+    const barrier = new Promise((resolve) => {
+      release = resolve;
+    });
+    const current = (previous ?? Promise.resolve()).then(() => barrier);
+    this.#localSyncControlPromise = current;
+    try {
+      await previous;
+      const poll = this.#pollPromise;
+      if (poll !== void 0)
+        await poll;
+      if (!this.#started || this.#stopped)
+        throw new Error("DSH connector is not running");
+      return await operation();
+    } finally {
+      release();
+      if (this.#localSyncControlPromise === current)
+        this.#localSyncControlPromise = void 0;
+    }
+  }
   stop() {
     this.#stopPromise ??= (async () => {
       this.#stopped = true;
@@ -1468,14 +1537,17 @@ var DshHostConnector = class {
   }
   async #poll() {
     const state = this.#requireState();
-    await this.#flushOutbox();
+    await this.#flushOutbox(state.automaticUpload);
     await this.#finalizeDeliveredRequest();
     if (state.activeRequest !== void 0) {
       await this.#withExecutionPermit(() => this.#recoverActiveRequest());
       return { scanned: 0, claimed: 0, completed: 1 };
     }
-    await this.#captureLocalTurns();
-    await this.#flushOutbox();
+    if (state.automaticUpload) {
+      await this.#captureLocalTurns();
+      await this.#flushOutbox(true);
+    }
+    const manualUploadRequired = !state.automaticUpload && this.localSyncStatus().uploadableLocalTurns > 0;
     let scanCursor = state.projectionCursor;
     let scanned = 0;
     while (!this.#stopped) {
@@ -1491,6 +1563,9 @@ var DshHostConnector = class {
           continue;
         }
         await this.#projectCanonicalBatch(passive, passive.at(-1)?.sequence ?? state.projectionCursor);
+        if (manualUploadRequired) {
+          return { scanned, claimed: 0, completed: 0 };
+        }
         if (profile.provider !== void 0 && profile.provider !== this.#config.provider) {
           throw new Error("DeepSeek Harness Agent request provider does not match the configured Host binding");
         }
@@ -1668,7 +1743,7 @@ var DshHostConnector = class {
     state.serverCursor = Math.max(state.serverCursor, throughSequence);
     await this.#stateStore.save(state);
   }
-  async #captureLocalTurns() {
+  async #captureLocalTurns(basedOnSequence) {
     const state = this.#requireState();
     if (state.activeRequest !== void 0 || state.outbox.length > 0)
       return;
@@ -1686,7 +1761,7 @@ var DshHostConnector = class {
       input: {
         localTurnId: turn.localTurnId,
         runtimeId: runtime.id,
-        basedOnSequence: state.serverCursor,
+        basedOnSequence: basedOnSequence ?? state.serverCursor,
         occurredAt: turn.occurredAt,
         observedModel: this.#config.model,
         requestPayload: {
@@ -1788,13 +1863,15 @@ var DshHostConnector = class {
     });
     return operations;
   }
-  async #flushOutbox() {
+  async #flushOutbox(includeLocalTurns = true) {
     const state = this.#requireState();
     const runtime = this.#requireRuntime();
     while (state.outbox.length > 0) {
       const operation = state.outbox[0];
       if (operation === void 0)
         break;
+      if (operation.kind === "local_turn" && !includeLocalTurns)
+        break;
       if (operation.input.runtimeId !== runtime.id) {
         throw new Error("DSH connector outbox belongs to a different runtime");
       }
@@ -1876,7 +1953,7 @@ var DshHostConnector = class {
         throw new Error("Persisted DSH Session exists without connector state; refusing ambiguous resume");
       }
       return {
-        version: 2,
+        version: 3,
         binding: {
           projectId: this.#config.projectId,
           sessionId: this.#config.sessionId,
@@ -1885,6 +1962,7 @@ var DshHostConnector = class {
         serverCursor: 0,
         projectionCursor: 0,
         publishedDshSequence: 0,
+        automaticUpload: true,
         outbox: []
       };
     }
@@ -2648,17 +2726,20 @@ var FileConnectorStateStore = class {
 function validateConnectorState(value) {
   const state = requiredObject3(value, "state");
   const legacy = state.version === 1;
+  const legacyUploadPolicy = state.version === 1 || state.version === 2;
   exactKeys(state, /* @__PURE__ */ new Set([
     "version",
     "binding",
     "serverCursor",
     ...legacy ? [] : ["projectionCursor"],
     "publishedDshSequence",
+    ...legacyUploadPolicy ? [] : ["automaticUpload"],
     "activeRequest",
     "outbox"
   ]), "state");
-  if (!legacy && state.version !== 2)
+  if (state.version !== 1 && state.version !== 2 && state.version !== 3) {
     throw new Error("Unsupported DSH connector state version");
+  }
   const binding = requiredObject3(state.binding, "state.binding");
   exactKeys(binding, /* @__PURE__ */ new Set(["projectId", "sessionId", "dshSessionId"]), "state.binding");
   const serverCursor = nonNegativeInteger(state.serverCursor, "state.serverCursor");
@@ -2669,7 +2750,7 @@ function validateConnectorState(value) {
     throw new Error("state.outbox must be an array");
   const outbox = state.outbox.map(parseOutboxOperation);
   const validated = {
-    version: 2,
+    version: 3,
     binding: {
       projectId: safeString(binding.projectId, "state.binding.projectId", 128),
       sessionId: safeString(binding.sessionId, "state.binding.sessionId", 128),
@@ -2678,6 +2759,7 @@ function validateConnectorState(value) {
     serverCursor,
     projectionCursor,
     publishedDshSequence,
+    automaticUpload: legacyUploadPolicy ? true : requiredBoolean(state.automaticUpload, "state.automaticUpload"),
     ...activeRequest === void 0 ? {} : { activeRequest },
     outbox
   };
@@ -2857,6 +2939,11 @@ function nonNegativeInteger(value, label) {
   }
   return Number(value);
 }
+function requiredBoolean(value, label) {
+  if (typeof value !== "boolean")
+    throw new Error(`${label} must be a boolean`);
+  return value;
+}
 function positiveInteger(value, label) {
   const parsed = nonNegativeInteger(value, label);
   if (parsed === 0)
@@ -3020,6 +3107,21 @@ var DshProjectManager = class {
   activeSessionIds() {
     return [...this.#managed].filter(([, binding]) => binding.phase === "active" && !binding.connector.stopped).map(([sessionId]) => sessionId).sort();
   }
+  localSyncStatuses() {
+    return [...this.#managed.entries()].filter(([, binding]) => binding.phase === "active" && !binding.connector.stopped).flatMap(([, binding]) => binding.connector.localSyncStatus?.() ?? []).sort((left, right) => left.sessionId.localeCompare(right.sessionId));
+  }
+  async setLocalAutoUpload(sessionId, enabled) {
+    const connector = this.#requireManagedConnector(sessionId);
+    if (!connector.setLocalAutoUpload)
+      throw new Error("This DSH conversation does not support upload controls");
+    return connector.setLocalAutoUpload(enabled);
+  }
+  async uploadLocalTurns(sessionId) {
+    const connector = this.#requireManagedConnector(sessionId);
+    if (!connector.uploadLocalTurns)
+      throw new Error("This DSH conversation does not support manual upload");
+    return connector.uploadLocalTurns();
+  }
   async start() {
     if (this.#started)
       throw new Error("DSH project manager is already started");
@@ -3259,6 +3361,13 @@ var DshProjectManager = class {
       throw new Error("Authenticated GatherThread actor is unavailable");
     return this.#actor;
   }
+  #requireManagedConnector(sessionId) {
+    const binding = this.#managed.get(sessionId);
+    if (!binding || binding.phase !== "active" || binding.connector.stopped) {
+      throw new Error("The selected DSH conversation is not active");
+    }
+    return binding.connector;
+  }
   #reportError(error) {
     this.#onBackgroundError?.(error);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gatherthread/dsh-host",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.4",
   "description": "Opt-in GatherThread integration for the DeepSeek Harness Web profile",
   "license": "Apache-2.0",
   "publishConfig": {