@clowder-ai/companion 0.1.0-alpha.24 → 0.1.0-alpha.26

package/README.md

@@ -26,9 +26,9 @@ borrowing today's selected companion.
 
 ## Host integration
 
-This surface requires the additive desktop bridge **1.4.0**. The Host computes
+This surface requires the additive desktop bridge **1.5.0**. The Host computes
 placement within the display work area, keeps the cat as its stable anchor, and
-owns bounded drag gestures and transparent-area hit testing. Hosts below 1.4
+owns bounded drag gestures and transparent-area hit testing. Hosts below 1.5
 reject this manifest before installation. Media admission and capture
 remain in the trusted Host; this package receives neither streams nor provider
 SDP. Hiding releases media; the existing Clowder **聊聊** entry restores the cat.
@@ -41,6 +41,19 @@ contract as the transcript surfaces that supply them. A Host
 another current reference may be observed without retrying the rejected one.
 Other failures retry after 1 and 2 seconds, then leave the call's
 first-visible result unknown; later text never backfills a manufactured success.
+Bridge 1.5 adds Host-bound conversation pages and versioned body continuations.
+The renderer can only return opaque cursors issued by the Host; it cannot select
+an owner, thread, message, call or byte offset. History progress, response phase
+and body completeness remain separate, so a processing draft or truncated body
+cannot masquerade as a completed reply.
+
+It also binds the one-line composer to the Host-owned durable draft. Versioned
+text submission carries the Host-issued conversation `scopeRef`, draft revision
+and caller message identity. An unknown settlement is read back but never
+automatically resent; an explicit retry keeps the original text, identity,
+revision and route. If the canonical thread changes, the old unconfirmed input
+stays visible as invalidated local text and is never replayed into the new scope.
+The legacy text and conversation methods remain unchanged for older pairs.
 
 Xianxian uses one layered sitting body or one VP9 clip at a time. Expiring Host
 facts with task, result and event identities select tool work, workspace fetch,

package/manifest.json

@@ -1,6 +1,6 @@
 {
   "pluginId": "official.companion",
-  "version": "0.1.0-alpha.24",
+  "version": "0.1.0-alpha.26",
   "contractVersion": "0.1.0",
   "name": "猫猫球",
   "icon": {
@@ -37,10 +37,10 @@
       "type": "desktop-window",
       "id": "companion",
       "role": "companion",
-      "bridgeVersion": "1.4.0",
+      "bridgeVersion": "1.5.0",
       "surface": {
         "entrypoint": "renderer/index.html",
-        "integrity": "sha256-EFERDKvXnOw6Mbk1Kq7ZyX7w4FdswfX5W/B0w/KTLE8="
+        "integrity": "sha256-Q5N69iKFCZpX1mGm9KJWOvJaU3xd5mdGbojDBRZUTx4="
       },
       "presentation": {
         "width": 300,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clowder-ai/companion",
-  "version": "0.1.0-alpha.24",
+  "version": "0.1.0-alpha.26",
   "description": "The desktop voice body for your Clowder companion",
   "license": "MIT",
   "type": "module",
@@ -27,8 +27,8 @@
     "prepack": "pnpm build"
   },
   "devDependencies": {
-    "@clowder-ai/plugin-contract": "0.1.0-beta.27",
-    "@clowder-ai/plugin-sdk": "0.1.0-beta.23",
+    "@clowder-ai/plugin-contract": "0.1.0-beta.28",
+    "@clowder-ai/plugin-sdk": "0.1.0-beta.24",
     "playwright": "1.61.1"
   },
   "repository": {

package/plugin.yaml

@@ -1,6 +1,6 @@
 {
   "pluginId": "official.companion",
-  "version": "0.1.0-alpha.24",
+  "version": "0.1.0-alpha.26",
   "contractVersion": "0.1.0",
   "name": "猫猫球",
   "icon": {
@@ -37,10 +37,10 @@
       "type": "desktop-window",
       "id": "companion",
       "role": "companion",
-      "bridgeVersion": "1.4.0",
+      "bridgeVersion": "1.5.0",
       "surface": {
         "entrypoint": "renderer/index.html",
-        "integrity": "sha256-EFERDKvXnOw6Mbk1Kq7ZyX7w4FdswfX5W/B0w/KTLE8="
+        "integrity": "sha256-Q5N69iKFCZpX1mGm9KJWOvJaU3xd5mdGbojDBRZUTx4="
       },
       "presentation": {
         "width": 300,

package/renderer/client.mjs

@@ -16,6 +16,50 @@ export function createCompanionClient(bridge) {
             throw new CompanionRequestError('unavailable');
         return reply;
     }
+    async function readConversation() {
+        const response = await invoke({ kind: 'conversation.read' }, 'conversation');
+        if ('v' in response)
+            throw new CompanionRequestError('unavailable');
+        return response;
+    }
+    async function readConversationPage(options = {}) {
+        const command = options.before === undefined
+            ? options.limit === undefined
+                ? { kind: 'conversation.read', v: 2 }
+                : { kind: 'conversation.read', v: 2, limit: options.limit }
+            : options.limit === undefined
+                ? { kind: 'conversation.read', v: 2, before: options.before }
+                : { kind: 'conversation.read', v: 2, before: options.before, limit: options.limit };
+        const response = await invoke(command, 'conversation');
+        if (!('v' in response) || response.v !== 2)
+            throw new CompanionRequestError('unavailable');
+        return response;
+    }
+    async function readConversationBody(continuation) {
+        return invoke({ kind: 'conversation.body.read', v: 2, continuation }, 'conversation-body');
+    }
+    async function readConversationDraft() {
+        return invoke({ kind: 'conversation.draft.read', v: 1 }, 'conversation-draft');
+    }
+    async function saveConversationDraft(expectedRevision, text, scopeRef) {
+        return invoke({
+            kind: 'conversation.draft.save', v: 1, scopeRef, expectedRevision, text,
+        }, 'conversation-draft');
+    }
+    async function invokeDeliveryV2(command) {
+        const response = await invoke(command, 'delivery');
+        if (!('v' in response) || response.v !== 2)
+            throw new CompanionRequestError('unavailable');
+        return response;
+    }
+    async function submitConversationText(text, clientMessageId, submissionRevision, scopeRef) {
+        return invokeDeliveryV2({
+            kind: 'text', v: 2, scopeRef, text, clientMessageId, submissionRevision,
+        });
+    }
+    async function readConversationDelivery(clientMessageId, scopeRef) {
+        return invokeDeliveryV2({ kind: 'conversation.delivery.read', v: 1, scopeRef, clientMessageId });
+    }
     return {
         state: () => invoke({ kind: 'state' }, 'state'),
         prepare: () => invoke({ kind: 'prepare' }, 'state'),
@@ -26,6 +70,8 @@ export function createCompanionClient(bridge) {
         stop: () => invoke({ kind: 'stop' }, 'ok'),
         text: async (text, clientMessageId) => {
             const receipt = await invoke({ kind: 'text', text, clientMessageId }, 'delivery');
+            if ('v' in receipt)
+                throw new CompanionRequestError('unavailable');
             if (receipt.delivery !== 'accepted')
                 throw new CompanionRequestError('unconfirmed');
             return receipt;
@@ -56,7 +102,13 @@ export function createCompanionClient(bridge) {
         readSettings: () => invoke({ kind: 'settings.read' }, 'settings'),
         updateSetting: (field, value) => invoke({ kind: 'settings.update', field, value }, 'settings-update'),
         disableCompanion: () => invoke({ kind: 'companion.disable' }, 'companion-lifecycle'),
-        readConversation: () => invoke({ kind: 'conversation.read' }, 'conversation'),
+        readConversation,
+        readConversationPage,
+        readConversationBody,
+        readConversationDraft,
+        saveConversationDraft,
+        submitConversationText,
+        readConversationDelivery,
         readTranscript: () => invoke({ kind: 'transcript.read' }, 'transcript'),
         subscribe: (listener) => bridge.subscribe(listener),
     };

package/renderer/conversation-draft.mjs

@@ -0,0 +1,304 @@
+const receiptFingerprint = receipt => [
+  receipt.delivery,
+  receipt.messageId ?? '',
+  receipt.reason ?? '',
+  receipt.draftRevision ?? '',
+].join('\u0000');
+
+const copySubmission = submission => ({
+  clientMessageId: submission.clientMessageId,
+  text: submission.text,
+  submissionRevision: submission.submissionRevision,
+  receipt: { ...submission.receipt },
+});
+
+/**
+ * Renderer coordinator for the Host-owned composer draft.
+ *
+ * It keeps the current local edit separate from the last canonical Host text.
+ * Reads may reconcile receipts, but only submit() and retry() can send text.
+ */
+export class HostConversationDraft {
+  constructor({ client, changed = () => {}, delivery = () => {}, invalidated = () => {},
+    uuid = () => crypto.randomUUID(), schedule = setTimeout, cancel = clearTimeout,
+    debounceMs = 180 }) {
+    Object.assign(this, { client, changed, delivery, invalidated, uuid, debounceMs });
+    this.schedule = (...args) => Reflect.apply(schedule, globalThis, args);
+    this.cancel = (...args) => Reflect.apply(cancel, globalThis, args);
+    this.scopeRef = null;
+    this.revision = null;
+    this.canonicalText = '';
+    this.localText = '';
+    this.localVersion = 0;
+    this.localEdited = false;
+    this.writable = false;
+    this.status = 'loading';
+    this.submissions = new Map();
+    this.reportedReceipts = new Map();
+  }
+
+  snapshot() {
+    return {
+      scopeRef: this.scopeRef,
+      revision: this.revision,
+      canonicalText: this.canonicalText,
+      localText: this.localText,
+      writable: this.writable,
+      status: this.status,
+      submissions: [...this.submissions.values()].map(copySubmission),
+    };
+  }
+
+  canonicalReply() {
+    if (this.scopeRef === null || this.revision === null) return null;
+    return {
+      kind: 'conversation-draft', v: 1, status: 'available', scopeRef: this.scopeRef,
+      revision: this.revision, text: this.canonicalText, writable: this.writable,
+      submissions: [...this.submissions.values()].map(copySubmission),
+    };
+  }
+
+  emit() { this.changed(this.snapshot()); }
+
+  update(text) {
+    this.localText = text;
+    this.localEdited = true;
+    ++this.localVersion;
+    if (!['scope_changed', 'readonly'].includes(this.status)) this.status = 'editing';
+    this.emit();
+    if (this.saveTimer !== undefined) this.cancel(this.saveTimer);
+    this.saveTimer = this.schedule(() => {
+      this.saveTimer = undefined;
+      void this.save();
+    }, this.debounceMs);
+    this.saveTimer?.unref?.();
+  }
+
+  async load(options = {}) {
+    if (this.loading) return this.loading;
+    const operation = this.loadOnce(options);
+    this.loading = operation;
+    try { return await operation; }
+    finally { if (this.loading === operation) this.loading = undefined; }
+  }
+
+  async loadOnce({ preserveStatus = null } = {}) {
+    try {
+      const response = await this.client.readConversationDraft();
+      if (response.status !== 'available') {
+        this.revision = response.revision;
+        this.writable = false;
+        this.status = response.status;
+        this.emit();
+        return response;
+      }
+      if (response.scopeRef === this.scopeRef && this.revision !== null
+        && response.revision < this.revision) return response;
+      const scopeChanged = this.scopeRef !== null && this.scopeRef !== response.scopeRef;
+      const previousCanonical = this.canonicalText;
+      const previousSubmissions = [...this.submissions.values()];
+      if (scopeChanged) {
+        const unconfirmed = previousSubmissions.filter(value => value.receipt.delivery === 'unconfirmed');
+        const latest = unconfirmed.at(-1);
+        if (latest && (!this.localEdited || this.localText === previousCanonical)) {
+          this.localText = latest.text;
+          this.localEdited = true;
+          ++this.localVersion;
+        }
+        for (const submission of unconfirmed) this.invalidated({
+          ...copySubmission(submission), scopeRef: this.scopeRef, reason: 'scope_changed',
+        });
+        this.reportedReceipts.clear();
+      } else if (!this.localEdited || this.localText === previousCanonical) {
+        this.localText = response.text;
+        this.localEdited = false;
+      }
+      this.scopeRef = response.scopeRef;
+      this.revision = response.revision;
+      this.canonicalText = response.text;
+      this.writable = response.writable;
+      this.submissions = new Map(response.submissions.map(value => [value.clientMessageId, copySubmission(value)]));
+      this.status = scopeChanged ? 'scope_changed'
+        : preserveStatus ?? (response.writable ? 'ready' : 'readonly');
+      for (const submission of this.submissions.values()) this.report(submission);
+      this.emit();
+      if (!scopeChanged) await this.reconcileUnconfirmed();
+      return response;
+    } catch (error) {
+      this.status = error?.code ?? 'unavailable';
+      this.emit();
+      return null;
+    }
+  }
+
+  report(submission, restored = true) {
+    const key = `${this.scopeRef}\u0000${submission.clientMessageId}`;
+    const fingerprint = receiptFingerprint(submission.receipt);
+    if (this.reportedReceipts.get(key) === fingerprint) return;
+    this.reportedReceipts.set(key, fingerprint);
+    this.delivery({ ...copySubmission(submission), scopeRef: this.scopeRef, restored });
+  }
+
+  async reconcileUnconfirmed() {
+    const scopeRef = this.scopeRef;
+    for (const submission of [...this.submissions.values()]) {
+      if (submission.receipt.delivery !== 'unconfirmed' || scopeRef !== this.scopeRef) continue;
+      try {
+        const receipt = await this.client.readConversationDelivery(submission.clientMessageId, scopeRef);
+        if (scopeRef !== this.scopeRef) return;
+        const updated = { ...submission, receipt };
+        if (receipt.delivery !== 'rejected') this.submissions.set(submission.clientMessageId, updated);
+        this.report(updated);
+      } catch (error) {
+        if (error?.code === 'invalid_request' && scopeRef !== this.scopeRef) return;
+        this.status = error?.code ?? 'unavailable';
+      }
+    }
+    this.emit();
+  }
+
+  async save() {
+    if (this.saving) {
+      this.saveAgain = true;
+      return this.saving;
+    }
+    const operation = (async () => {
+      let result;
+      do {
+        this.saveAgain = false;
+        result = await this.saveOnce();
+      } while (this.saveAgain);
+      return result;
+    })();
+    this.saving = operation;
+    try { return await operation; }
+    finally { if (this.saving === operation) this.saving = undefined; }
+  }
+
+  async saveOnce() {
+    if (this.scopeRef === null) await this.load();
+    const text = this.localText;
+    const version = this.localVersion;
+    if (this.scopeRef === null || this.revision === null) return null;
+    if (!this.writable || text.length > 8000) {
+      this.status = 'readonly';
+      this.emit();
+      return null;
+    }
+    if (text === this.canonicalText) return this.canonicalReply();
+    const expectedRevision = this.revision;
+    const scopeRef = this.scopeRef;
+    this.status = 'saving';
+    this.emit();
+    try {
+      const response = await this.client.saveConversationDraft(expectedRevision, text, scopeRef);
+      if (response.status !== 'available') {
+        this.revision = response.revision;
+        this.status = response.status;
+        this.emit();
+        await this.load({ preserveStatus: response.status });
+        return response;
+      }
+      if (response.scopeRef !== scopeRef) {
+        await this.load({ preserveStatus: 'scope_changed' });
+        return null;
+      }
+      if (this.revision !== null && response.revision < this.revision) return this.canonicalReply();
+      const preserveStatus = version === this.localVersion ? 'ready' : 'editing';
+      this.applySaved(response, preserveStatus);
+      return response;
+    } catch (error) {
+      this.status = error?.code ?? 'unavailable';
+      this.emit();
+      return null;
+    }
+  }
+
+  applySaved(response, status) {
+    this.scopeRef = response.scopeRef;
+    this.revision = response.revision;
+    this.canonicalText = response.text;
+    this.writable = response.writable;
+    this.submissions = new Map(response.submissions.map(value => [value.clientMessageId, copySubmission(value)]));
+    this.status = response.writable ? status : 'readonly';
+    for (const submission of this.submissions.values()) this.report(submission);
+    this.emit();
+  }
+
+  async flush() {
+    if (this.saveTimer !== undefined) {
+      this.cancel(this.saveTimer);
+      this.saveTimer = undefined;
+    }
+    return this.save();
+  }
+
+  async submit() {
+    const text = this.localText.trim();
+    if (!text) return null;
+    if (text !== this.localText) {
+      this.localText = text;
+      this.localEdited = true;
+      ++this.localVersion;
+      this.emit();
+    }
+    const submittedVersion = this.localVersion;
+    const saved = await this.flush();
+    if (!saved || saved.status !== 'available' || saved.text !== text || !saved.writable) return null;
+    const submission = {
+      clientMessageId: this.uuid(), text, submissionRevision: saved.revision,
+      receipt: null,
+    };
+    return this.send(submission, submittedVersion);
+  }
+
+  async retry(submission) {
+    const current = this.submissions.get(submission.clientMessageId);
+    if (!current || current.receipt.delivery !== 'unconfirmed'
+      || current.text !== submission.text
+      || current.submissionRevision !== submission.submissionRevision) return null;
+    return this.send(current, null);
+  }
+
+  async send(submission, submittedVersion) {
+    const scopeRef = this.scopeRef;
+    if (scopeRef === null) return null;
+    try {
+      const receipt = await this.client.submitConversationText(
+        submission.text, submission.clientMessageId, submission.submissionRevision, scopeRef,
+      );
+      if (scopeRef !== this.scopeRef) return null;
+      const updated = { ...submission, receipt };
+      if (receipt.delivery !== 'rejected') this.submissions.set(submission.clientMessageId, updated);
+      this.reportedReceipts.delete(`${scopeRef}\u0000${submission.clientMessageId}`);
+      this.report(updated, false);
+      if (receipt.delivery === 'accepted') {
+        if (submittedVersion !== null && submittedVersion === this.localVersion
+          && this.localText === submission.text) {
+          this.localText = '';
+          this.localEdited = false;
+          ++this.localVersion;
+        }
+        this.status = 'accepted';
+        this.emit();
+        await this.load();
+      } else if (receipt.delivery === 'unconfirmed') {
+        this.status = 'unconfirmed';
+        this.emit();
+      } else {
+        this.status = receipt.reason;
+        this.emit();
+      }
+      return receipt;
+    } catch (error) {
+      this.status = error?.code ?? 'unavailable';
+      this.emit();
+      return null;
+    }
+  }
+
+  close() {
+    if (this.saveTimer !== undefined) this.cancel(this.saveTimer);
+    this.saveTimer = undefined;
+  }
+}

package/renderer/conversation-history.mjs

@@ -0,0 +1,176 @@
+const copyRow = row => ({
+  ...row,
+  body: { ...row.body },
+  inputMessageIds: [...row.inputMessageIds],
+});
+
+/** In-memory presentation cache for the Host-owned v2 conversation projection. */
+export class ConversationHistory {
+  constructor({ changed = () => {} } = {}) {
+    this.changed = changed;
+    this.rows = new Map();
+    this.order = [];
+    this.latestIds = new Set();
+    this.tokens = new Map();
+    this.consumed = new Map();
+    this.threadTitle = '';
+    this.hasMoreOlder = false;
+    this.olderCursor = null;
+    this.pageStatus = 'idle';
+    this.loadedOlder = false;
+  }
+
+  loadPage(page, { older = false } = {}) {
+    if (page.status !== 'available') {
+      this.pageStatus = 'stale';
+      this.emit();
+      return false;
+    }
+    this.pageStatus = 'available';
+    this.threadTitle = page.threadTitle;
+    const pageIds = [];
+    for (const value of page.messages) {
+      pageIds.push(value.id);
+      this.mergeRow(value);
+    }
+    const inPage = new Set(pageIds);
+    if (older) {
+      this.order = [...pageIds, ...this.order.filter(id => !inPage.has(id))];
+    } else {
+      const overlapsLatest = pageIds.some(id => this.latestIds.has(id));
+      const keepEarlier = this.latestIds.size === 0 || overlapsLatest || this.loadedOlder;
+      this.order = [...(keepEarlier ? this.order.filter(id => !inPage.has(id)) : []), ...pageIds];
+      this.latestIds = inPage;
+      for (const id of [...this.rows.keys()]) {
+        if (!this.order.includes(id)) this.remove(id);
+      }
+    }
+    if (older || !this.loadedOlder) {
+      this.hasMoreOlder = page.hasMoreOlder;
+      this.olderCursor = page.olderCursor;
+    }
+    if (older) this.loadedOlder = true;
+    this.emit();
+    return true;
+  }
+
+  mergeRow(value) {
+    const previous = this.rows.get(value.id);
+    const next = {
+      ...value,
+      body: { ...value.body },
+      inputMessageIds: [...value.inputMessageIds],
+      bodyStatus: value.body.complete ? 'complete' : 'loading',
+    };
+    if (!previous || previous.body.revision !== value.body.revision) {
+      this.forgetMessageTokens(value.id);
+      this.consumed.set(value.id, new Set());
+      this.rows.set(value.id, next);
+      this.registerContinuation(next);
+      return;
+    }
+
+    if (previous.text.startsWith(value.text)) {
+      next.text = previous.text;
+      next.body = previous.body;
+      next.bodyStatus = previous.bodyStatus;
+    } else if (!value.text.startsWith(previous.text)) {
+      next.text = previous.text;
+      next.body = previous.body;
+      next.bodyStatus = 'stale';
+    }
+    this.rows.set(value.id, next);
+    this.registerContinuation(next);
+  }
+
+  bodyContinuation(messageId) {
+    const value = this.rows.get(messageId);
+    return value?.bodyStatus === 'loading' ? value.body.continuation : null;
+  }
+
+  applyBody(continuation, reply) {
+    const binding = this.tokens.get(continuation);
+    if (!binding) return false;
+    const value = this.rows.get(binding.messageId);
+    if (!value || value.body.revision !== binding.revision) return false;
+    if (reply.status === 'withdrawn') {
+      this.remove(binding.messageId);
+      this.emit();
+      return true;
+    }
+    if (reply.status === 'stale') {
+      value.bodyStatus = 'stale';
+      this.emit();
+      return true;
+    }
+    const used = this.consumed.get(binding.messageId) ?? new Set();
+    if (used.has(continuation)) return true;
+    if (reply.messageId !== binding.messageId || reply.body.revision !== binding.revision
+      || value.body.continuation !== continuation) {
+      value.bodyStatus = 'stale';
+      this.emit();
+      return false;
+    }
+    used.add(continuation);
+    this.consumed.set(binding.messageId, used);
+    value.text += reply.text;
+    value.body = { ...reply.body };
+    value.bodyStatus = reply.body.complete ? 'complete' : 'loading';
+    if (!reply.body.complete && used.has(reply.body.continuation)) value.bodyStatus = 'stale';
+    this.registerContinuation(value);
+    this.emit();
+    return value.bodyStatus !== 'stale';
+  }
+
+  registerContinuation(value) {
+    const continuation = value.body.continuation;
+    if (!continuation || value.bodyStatus !== 'loading') return;
+    this.tokens.set(continuation, { messageId: value.id, revision: value.body.revision });
+  }
+
+  forgetMessageTokens(messageId) {
+    for (const [token, binding] of this.tokens) {
+      if (binding.messageId === messageId) this.tokens.delete(token);
+    }
+  }
+
+  remove(messageId) {
+    this.rows.delete(messageId);
+    this.order = this.order.filter(id => id !== messageId);
+    this.forgetMessageTokens(messageId);
+    this.consumed.delete(messageId);
+  }
+
+  clearProtected(reason) {
+    this.rows.clear();
+    this.order = [];
+    this.latestIds.clear();
+    this.tokens.clear();
+    this.consumed.clear();
+    this.threadTitle = '';
+    this.hasMoreOlder = false;
+    this.olderCursor = null;
+    this.pageStatus = reason;
+    this.emit();
+  }
+
+  message(messageId) {
+    const value = this.rows.get(messageId);
+    return value ? copyRow(value) : undefined;
+  }
+
+  snapshot() {
+    return {
+      threadTitle: this.threadTitle,
+      messages: this.order.flatMap(id => {
+        const value = this.rows.get(id);
+        return value ? [copyRow(value)] : [];
+      }),
+      hasMoreOlder: this.hasMoreOlder,
+      olderCursor: this.olderCursor,
+      pageStatus: this.pageStatus,
+    };
+  }
+
+  emit() { this.changed(this.snapshot()); }
+}