@clowder-ai/personal-chrome-companion 0.0.0-stage → 0.1.0-alpha.4

package/README.en.md

@@ -0,0 +1,129 @@
+# Personal Chrome companion
+
+[Chinese](README.md) · English
+
+`@clowder-ai/personal-chrome-companion` connects explicitly authorized ChatGPT conversations through a Chrome MV3 extension and a local Native Messaging helper.
+
+The Host-loadable builtin runtime is implemented in this package:
+`runtime.transport: builtin` with entrypoint `dist/plugin-entrypoint.js`. The
+plugin declares `runtime.dataDirectory: personal-chrome-host`, so the Host
+provisions `<projectRoot>/.cat-cafe/plugin-host/personal-chrome-host` (0700)
+for this installation's private data.
+
+## Module plugin surface
+
+Conversation access requires your explicit authorization. Registering the extension with the operating
+system is a separate setup step; installing the plugin alone does neither.
+
+The generic installed setup and real-account journey require separate acceptance; a package archive test is not that evidence.
+
+The `personal-chrome-host` feature owns one `cloud-conversation-host`
+contribution (`provider: chatgpt`). Its three conversation methods use the
+package's native-host socket client and the helper's v2 protocol:
+
+- `personal-chrome-host.append-message` sends to an authorized conversation.
+- `personal-chrome-host.assistant-returns.list` fetches at most one pending reply.
+- `personal-chrome-host.assistant-returns.ack` acknowledges that reply; listing
+  alone never removes it.
+
+The `personalChromeAuthorizations` operation lists the authorized
+conversations as Host-rendered rows (one `revoke` row action each), revokes one
+authorization by `conversationId`, and reports authorization status. The
+underlying store holds at most 32 authorizations; the operation surfaces that
+ceiling through the status action.
+
+Use **Refresh titles** to ask the connected extension for readable titles of
+the currently authorized conversations. The result reports how many titles
+were updated, or why refreshing was unavailable; the conversation list then
+reloads. Refreshing never grants authorization or clears the extension reload
+reminder. Keep Chrome and the paired extension running for this action.
+
+Status also shows the **last observed** helper connection state. It never opens
+a socket: use **Test** for a live health probe. Authorization and helper
+reachability are reported separately; a connected helper does not by itself
+mean the extension is ready or a conversation is authorized.
+
+| Helper state | Meaning and next action |
+| --- | --- |
+| `unknown` | No connection observation since this start; run Test. |
+| `invalid_installation` | Pairing record validation failed; use **Chrome connection** in Settings to repair it, then run Test. Record contents are never shown. This state does not delay list attempts; the next successful connection restores `connected`. |
+| `not_installed` | No pairing record; use **Chrome connection** in Settings, then run Test. |
+| `unreachable` | Socket missing or connection refused; check Chrome and the extension, then run Test to retry now. Status includes the outage start, failure count and earliest next list attempt. |
+| `connected` | A socket connection was accepted; status includes the last contact time. Run Test to check current helper/extension health. |
+
+When the helper is unavailable, list returns `{ returns: [] }` and retries only
+on a later Host poll after 2, 4, 8, 16, 32, then at most every 60 seconds. There
+is no background retry timer. Append, acknowledge, Test and Refresh titles bypass this delay;
+any accepted connection resets it, even when the helper returns a business
+failure. Errors after a write are never treated as pre-send unavailability.
+Only connection-state changes produce logs. Stop clears these observations and
+cancels pending requests; it does not delete authorizations or pending replies.
+
+## Set up Chrome from Settings
+
+Open **Settings → Plugins → Personal Chrome → Chrome connection**. Choose the
+setup action and confirm registration of the local helper. The Host verifies
+the exact trusted release before invoking its fixed setup runner. Installation
+creates the pairing identity privately; you do not copy an extension ID, secret,
+or terminal command. Enabling a plugin alone never grants browser registration.
+
+The card gives you the stable extension folder. For the first installation,
+open Chrome's Extensions menu → Manage Extensions, enable Developer mode,
+and choose **Load unpacked**, selecting that folder. Chrome requires this
+browser-side action for an unpacked extension; an ordinary webpage cannot link
+to `chrome://extensions`. This release does not claim Chrome Web Store delivery
+or unattended extension installation.
+
+Return to the card and run **Test connection**. “Installed” only confirms the
+local registration and files. It does not mean Chrome is connected or that a
+conversation is authorized. Keep Chrome running; the extension reconnects to
+the helper. Test checks the real helper/extension revisions. Then open the exact
+ChatGPT conversation you want to authorize and click the extension's toolbar
+action. Its authorization will appear in Settings; use the row's revoke action
+to remove it, or Refresh titles to retrieve its readable title.
+
+The stable folder is `<projectRoot>/.cat-cafe/plugin-host/personal-chrome-host/extension/`.
+On updates or rollbacks the package refreshes these bytes; **Reload** the already
+loaded extension in Chrome, then run Test. If the helper has not been installed,
+use setup first: reloading Chrome cannot create its registration. The reload
+reminder clears only after a correlated reply proves the current revisions.
+
+Setup can be retried without rotating a valid pairing identity. A registration
+owned by another installation is a conflict, never silently overwritten. A broken
+pairing record is reported honestly; removing and setting up again creates a new
+identity. Setup removal refuses while the helper is active: close Chrome before
+retrying. It removes only this installation's registration, launcher and pairing,
+retaining authorizations, titles, extension files and delivery history. Revoke
+individual authorizations explicitly when desired, and remove the extension in
+Chrome if you no longer want it loaded.
+
+The fixed protocol and authority boundary for Host integrators are documented in
+[native-host/setup-protocol.md](native-host/setup-protocol.md). macOS and Linux
+helper installation are supported; Windows setup is explicitly unsupported.
+The initial Host product integration targets macOS.
+
+## Authority boundary
+
+Cat Café remains responsible for catalog/SRI/admission, pairing-secret
+issuance and rotation, lifecycle supervision, Settings/onboarding, and
+user-visible status. The installed helper receives a complete Host-supplied
+pairing record or environment configuration; it never generates a secret or
+chooses an install path.
+
+The extension may bind only an explicitly clicked exact
+`https://chatgpt.com/c/<id>` conversation. Normal dispatch finds that exact
+background tab and sends the append request without focusing, navigating,
+reloading, activating, selecting, moving, highlighting, reading cookies, or
+calling a private ChatGPT API.
+
+## Release status
+
+This package is a review candidate only. It does not publish to npm or the
+Chrome Web Store. Signed Chrome Web Store identity/admission and Windows support remain open; Windows is explicitly
+unsupported.
+
+Reading or revoking existing conversation authorizations is independent of runtime
+enablement and uses the same data directory. These settings operations do not
+install a helper, copy extension files or register a conversation runtime.
+
+The Host owns installation, grants, credentials and lifecycle; saving configuration preserves enable intent. The language link opens a separate document and does not imply automatic language selection.

package/README.md

@@ -1,3 +1,34 @@
-# Temporary Holding Version
+# 个人 Chrome 伴侣
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+简体中文 · [English](README.en.md)
+
+将你明确授权的 ChatGPT 网页对话接入 Clowder AI。插件提供 Chrome 扩展和本机 Native Messaging 辅助程序；授权精确到单个对话。
+
+## 开始使用
+
+1. 打开“设置 → 插件 → Personal Chrome → Chrome connection”，选择安装操作并确认注册本机辅助程序。启用插件本身不会授予浏览器注册权限。
+2. 首次安装时，在 Chrome 扩展管理页开启开发者模式，选择“加载已解压的扩展”，使用设置卡片给出的固定扩展目录。无需复制扩展 ID、密钥或终端命令。
+3. 返回设置运行连接测试，保持 Chrome 和扩展运行。显示已安装只证明本地文件与注册存在，不代表连接正常或对话已授权。
+4. 打开你想授权的准确 ChatGPT 对话，点击扩展工具栏按钮。设置中会列出这条授权，可逐条撤销。
+
+此发布不提供 Chrome 应用商店交付或无人值守安装。辅助程序支持 macOS、Linux，不支持 Windows；初始宿主集成以 macOS 为目标。
+
+## 授权与状态
+
+最多保存 32 条授权。“刷新标题”从已连接扩展读取已授权对话的标题，不新增授权。授权列表、撤销和状态读取独立于运行启用状态，使用同一份私有数据。
+
+状态显示最近观察到的辅助程序连接，不会自动探测网络：用连接测试检查当前健康。`unknown` 表示尚未观察；`not_installed` 表示缺少配对；`invalid_installation` 表示配对记录无效；`unreachable` 表示连接不可达；`connected` 只表示曾成功接受连接。辅助程序可达不等于扩展或对话已就绪。
+
+辅助程序不可达时，后续宿主轮询采用 2、4、8、16、32、最多 60 秒的退避，不建立后台重试定时器。发送、确认、测试和刷新标题可立即尝试。回复列出后仍须确认才移除；停止不会删除授权或待确认回复。
+
+## 更新与卸除
+
+升级或回退会刷新固定扩展目录的文件。请在 Chrome 中重新加载已加载的扩展，再测试；只有对应版本的关联回复确认后才清除重新加载提示。未安装辅助程序时，单纯重新加载扩展不能完成注册。
+
+重试安装不轮换有效配对身份；属于其他安装的注册不会被静默覆盖。损坏配对需移除后重建。移除辅助程序前先关闭 Chrome；它只移除此安装的注册、启动器和配对，保留授权、标题、扩展文件及投递历史。需要时另行撤销授权并在 Chrome 移除扩展。
+
+## 隐私边界
+
+扩展只绑定明确点击的 `https://chatgpt.com/c/<id>` 对话。发送在准确的后台标签中完成，不主动切换、导航、刷新或读取 Cookie，也不调用私人 ChatGPT API。宿主发放配对身份和受限私有目录，包不会自行生成密钥或猜测安装位置。完整宿主安装和账号旅程需分别验收。
+
+宿主管理安装、授权、凭据和启停；配置保存不自动改变启用意图。英文文档是独立文件，互链不代表页面已支持自动语言切换。

package/assets/icon.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="Personal Chrome companion">
+  <rect width="64" height="64" rx="14" fill="#1b72e8"/><circle cx="32" cy="32" r="18" fill="#fff"/><circle cx="32" cy="32" r="10" fill="#1b72e8"/><circle cx="32" cy="32" r="4" fill="#fff"/>
+</svg>

package/dist/assistant-return-cursor.d.ts

@@ -0,0 +1,13 @@
+export interface PersonalChromeAssistantReturnCursor {
+    readonly conversationId: string;
+    readonly sourceMessageId: string;
+    readonly assistantMessageId: string;
+}
+export interface PersonalChromeAssistantReturnCursorFields {
+    readonly afterConversationId?: string;
+    readonly afterSourceMessageId?: string;
+    readonly afterAssistantMessageId?: string;
+}
+export declare function assistantReturnCursorFields(cursor?: PersonalChromeAssistantReturnCursor): PersonalChromeAssistantReturnCursorFields;
+export declare function parseAssistantReturnCursorFields(record: Readonly<Record<string, unknown>>): PersonalChromeAssistantReturnCursorFields;
+//# sourceMappingURL=assistant-return-cursor.d.ts.map

package/dist/assistant-return-cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assistant-return-cursor.d.ts","sourceRoot":"","sources":["../src/assistant-return-cursor.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,mCAAmC;IAClD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AAED,MAAM,WAAW,yCAAyC;IACxD,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAC3C;AAED,wBAAgB,2BAA2B,CACzC,MAAM,CAAC,EAAE,mCAAmC,GAC3C,yCAAyC,CAQ3C;AAED,wBAAgB,gCAAgC,CAC9C,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,yCAAyC,CA0B3C"}

package/dist/assistant-return-cursor.js

@@ -0,0 +1,37 @@
+const SAFE_TOKEN = /^[A-Za-z0-9._:-]+$/;
+export function assistantReturnCursorFields(cursor) {
+    return cursor
+        ? {
+            afterConversationId: cursor.conversationId,
+            afterSourceMessageId: cursor.sourceMessageId,
+            afterAssistantMessageId: cursor.assistantMessageId,
+        }
+        : {};
+}
+export function parseAssistantReturnCursorFields(record) {
+    const hasConversation = Object.hasOwn(record, 'afterConversationId');
+    const hasSource = Object.hasOwn(record, 'afterSourceMessageId');
+    const hasAssistant = Object.hasOwn(record, 'afterAssistantMessageId');
+    if (hasConversation !== hasSource || hasSource !== hasAssistant) {
+        throw new Error('assistant return list cursor must contain conversation, source, and assistant message IDs');
+    }
+    if (!hasConversation)
+        return {};
+    if (typeof record.afterConversationId !== 'string' ||
+        record.afterConversationId.length > 200 ||
+        !SAFE_TOKEN.test(record.afterConversationId) ||
+        typeof record.afterSourceMessageId !== 'string' ||
+        record.afterSourceMessageId.length > 512 ||
+        !SAFE_TOKEN.test(record.afterSourceMessageId) ||
+        typeof record.afterAssistantMessageId !== 'string' ||
+        record.afterAssistantMessageId.length > 512 ||
+        !SAFE_TOKEN.test(record.afterAssistantMessageId)) {
+        throw new Error('assistant return list cursor contains an invalid identity token');
+    }
+    return {
+        afterConversationId: record.afterConversationId,
+        afterSourceMessageId: record.afterSourceMessageId,
+        afterAssistantMessageId: record.afterAssistantMessageId,
+    };
+}
+//# sourceMappingURL=assistant-return-cursor.js.map

package/dist/assistant-return-cursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assistant-return-cursor.js","sourceRoot":"","sources":["../src/assistant-return-cursor.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,GAAG,oBAAoB,CAAC;AAcxC,MAAM,UAAU,2BAA2B,CACzC,MAA4C;IAE5C,OAAO,MAAM;QACX,CAAC,CAAC;YACE,mBAAmB,EAAE,MAAM,CAAC,cAAc;YAC1C,oBAAoB,EAAE,MAAM,CAAC,eAAe;YAC5C,uBAAuB,EAAE,MAAM,CAAC,kBAAkB;SACnD;QACH,CAAC,CAAC,EAAE,CAAC;AACT,CAAC;AAED,MAAM,UAAU,gCAAgC,CAC9C,MAAyC;IAEzC,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;IACrE,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IAChE,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;IACtE,IAAI,eAAe,KAAK,SAAS,IAAI,SAAS,KAAK,YAAY,EAAE,CAAC;QAChE,MAAM,IAAI,KAAK,CAAC,2FAA2F,CAAC,CAAC;IAC/G,CAAC;IACD,IAAI,CAAC,eAAe;QAAE,OAAO,EAAE,CAAC;IAChC,IACE,OAAO,MAAM,CAAC,mBAAmB,KAAK,QAAQ;QAC9C,MAAM,CAAC,mBAAmB,CAAC,MAAM,GAAG,GAAG;QACvC,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,mBAAmB,CAAC;QAC5C,OAAO,MAAM,CAAC,oBAAoB,KAAK,QAAQ;QAC/C,MAAM,CAAC,oBAAoB,CAAC,MAAM,GAAG,GAAG;QACxC,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,oBAAoB,CAAC;QAC7C,OAAO,MAAM,CAAC,uBAAuB,KAAK,QAAQ;QAClD,MAAM,CAAC,uBAAuB,CAAC,MAAM,GAAG,GAAG;QAC3C,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,uBAAuB,CAAC,EAChD,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,iEAAiE,CAAC,CAAC;IACrF,CAAC;IACD,OAAO;QACL,mBAAmB,EAAE,MAAM,CAAC,mBAAmB;QAC/C,oBAAoB,EAAE,MAAM,CAAC,oBAAoB;QACjD,uBAAuB,EAAE,MAAM,CAAC,uBAAuB;KACxD,CAAC;AACJ,CAAC"}

package/dist/conversation-host.d.ts

@@ -0,0 +1,33 @@
+import { type CloudConversationAckResult, type CloudConversationAppendMessageResult, type CloudConversationListResult } from '@clowder-ai/plugin-contract';
+import { type PersonalChromeHostAdapterOptions } from './personal-chrome-host-transport.js';
+import { type HelperConnectionLog, type HelperConnectionStatus } from './helper-reachability.js';
+import type { PersonalChromeTitleSync } from './title-refresh-protocol.js';
+export interface PersonalChromeConversationHostOperations {
+    readonly refreshTitles: () => Promise<PersonalChromeTitleSync>;
+    readonly appendMessage: (input: unknown) => Promise<CloudConversationAppendMessageResult>;
+    readonly list: (input: unknown) => Promise<CloudConversationListResult>;
+    readonly ack: (input: unknown) => Promise<CloudConversationAckResult>;
+    /** Honest reachability probe for the `test` action: never claims ok without a real probe. */
+    readonly probe: () => Promise<{
+        readonly ok: boolean;
+        readonly message: string;
+    }>;
+    /** Last-known connection state; never opens a socket or reads the pairing record. */
+    readonly status: () => HelperConnectionStatus;
+    readonly dispose: () => Promise<void>;
+}
+/**
+ * The three cloud-conversation-host methods (contract beta.24 h3) backed by the
+ * package's own native-host socket client. None of these throw: the Host treats
+ * any throw after the call as AMBIGUOUS_EFFECT, so every failure is returned as
+ * data per the (d) error-code table and every result passes the contract
+ * validators with no extra fields.
+ */
+export declare function createConversationHostOperations(options: {
+    readonly dataDirectory: string;
+    readonly timeoutMs?: number;
+    readonly now?: () => number;
+    readonly log?: HelperConnectionLog;
+    readonly onRevisionContact?: PersonalChromeHostAdapterOptions['onRevisionContact'];
+}): PersonalChromeConversationHostOperations;
+//# sourceMappingURL=conversation-host.d.ts.map

package/dist/conversation-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-host.d.ts","sourceRoot":"","sources":["../src/conversation-host.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,0BAA0B,EAC/B,KAAK,oCAAoC,EACzC,KAAK,2BAA2B,EAIjC,MAAM,6BAA6B,CAAC;AAOrC,OAAO,EAA6D,KAAK,gCAAgC,EAAE,MAAM,qCAAqC,CAAC;AAEvJ,OAAO,EAAsB,KAAK,mBAAmB,EAAE,KAAK,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AACrH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAE3E,MAAM,WAAW,wCAAwC;IACvD,QAAQ,CAAC,aAAa,EAAE,MAAM,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAC/D,QAAQ,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,oCAAoC,CAAC,CAAC;IAC1F,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,2BAA2B,CAAC,CAAC;IACxE,QAAQ,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,0BAA0B,CAAC,CAAC;IACtE,6FAA6F;IAC7F,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC;QAAE,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClF,qFAAqF;IACrF,QAAQ,CAAC,MAAM,EAAE,MAAM,sBAAsB,CAAC;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AA0DD;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAAC,OAAO,EAAE;IACxD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,QAAQ,CAAC,GAAG,CAAC,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,gCAAgC,CAAC,mBAAmB,CAAC,CAAC;CACpF,GAAG,wCAAwC,CA8K3C"}

package/dist/conversation-host.js

@@ -0,0 +1,237 @@
+import { isCloudBridgeFailureDiagnosticV1, isCloudConversationAckInput, isCloudConversationAppendMessageInput, } from '@clowder-ai/plugin-contract';
+import { createPersonalChromeHostAdapter, isPersonalChromeNotInstalled, readPersonalChromeAdapterOptions, } from './pairing-record.js';
+import { PersonalChromeHostError, PersonalChromeHostRequestTracker } from './personal-chrome-host-transport.js';
+import { HelperReachability } from './helper-reachability.js';
+function isObjectRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function asContractDiagnostic(diagnostic) {
+    return isCloudBridgeFailureDiagnosticV1(diagnostic) ? { diagnostic } : {};
+}
+function appendFailure(errorCode, extras = {}) {
+    return { status: 'failed', errorCode, ...extras };
+}
+function ackFailure(errorCode, extras = {}) {
+    return { status: 'failed', errorCode, ...extras };
+}
+/**
+ * Resolves the pairing record from the granted data directory. A missing record
+ * is one of the three (e) cases and maps to HOST_UNAVAILABLE; a corrupt record is
+ * INVALID_CONFIGURATION. Both are PersonalChromeHostError codes passed through.
+ */
+async function resolveAdapterOptions(dataDirectory, onNotInstalled, onInvalidConfiguration) {
+    try {
+        return await readPersonalChromeAdapterOptions(dataDirectory);
+    }
+    catch (error) {
+        if (isPersonalChromeNotInstalled(error)) {
+            onNotInstalled();
+            throw new PersonalChromeHostError('HOST_UNAVAILABLE', 'personal Chrome host is not installed');
+        }
+        if (error instanceof PersonalChromeHostError && error.code === 'INVALID_CONFIGURATION') {
+            onInvalidConfiguration();
+        }
+        throw error;
+    }
+}
+function toCursor(value) {
+    if (!isObjectRecord(value))
+        return undefined;
+    const { conversationId, sourceMessageId, assistantMessageId } = value;
+    if (typeof conversationId !== 'string' ||
+        typeof sourceMessageId !== 'string' ||
+        typeof assistantMessageId !== 'string') {
+        return undefined;
+    }
+    return { conversationId, sourceMessageId, assistantMessageId };
+}
+/**
+ * The three cloud-conversation-host methods (contract beta.24 h3) backed by the
+ * package's own native-host socket client. None of these throw: the Host treats
+ * any throw after the call as AMBIGUOUS_EFFECT, so every failure is returned as
+ * data per the (d) error-code table and every result passes the contract
+ * validators with no extra fields.
+ */
+export function createConversationHostOperations(options) {
+    const { dataDirectory } = options;
+    let disposed = false;
+    // Cancels every in-flight helper request on stop: dispose destroys their
+    // sockets and settles the pending promises (written ones as AMBIGUOUS_EFFECT)
+    // instead of leaking them until their timeouts (ledger h3 (e)).
+    const requestTracker = new PersonalChromeHostRequestTracker();
+    const reachability = new HelperReachability(options.now ?? Date.now, options.log);
+    const unavailable = (state) => {
+        if (!disposed)
+            reachability.unavailable(state);
+    };
+    const adapterOptionsForRequest = async () => ({
+        ...(await resolveAdapterOptions(dataDirectory, () => unavailable('not_installed'), () => { if (!disposed)
+            reachability.invalidInstallation(); })),
+        timeoutMs: options.timeoutMs,
+        requestTracker,
+        onConnected: () => { if (!disposed)
+            reachability.connected(); },
+        onUnavailable: () => unavailable('unreachable'),
+        onRevisionContact: async (revisions, errorCode) => {
+            if (!disposed)
+                await options.onRevisionContact?.(revisions, errorCode);
+        },
+    });
+    const appendMessage = async (input) => {
+        if (disposed)
+            return appendFailure('HOST_UNAVAILABLE');
+        if (!isCloudConversationAppendMessageInput(input)) {
+            return appendFailure('INVALID_REQUEST');
+        }
+        let adapterOptions;
+        try {
+            adapterOptions = await adapterOptionsForRequest();
+        }
+        catch (error) {
+            if (error instanceof PersonalChromeHostError)
+                return appendFailure(error.code);
+            return appendFailure('AMBIGUOUS_EFFECT');
+        }
+        // Stop may have run while the pairing record was being read: no socket has
+        // been created yet, so nothing was sent and HOST_UNAVAILABLE stays truthful
+        // (cancelAll alone cannot cover requests that register after it returns).
+        if (disposed)
+            return appendFailure('HOST_UNAVAILABLE');
+        try {
+            const receipt = await createPersonalChromeHostAdapter(adapterOptions).append_message(input.conversationId, input.text, input.idempotencyKey);
+            return {
+                status: 'appended',
+                providerMessageId: receipt.hostMessageId,
+                ...(receipt.idempotentReplay === undefined ? {} : { idempotentReplay: receipt.idempotentReplay }),
+            };
+        }
+        catch (error) {
+            if (error instanceof PersonalChromeHostError) {
+                return appendFailure(error.code, {
+                    ...asContractDiagnostic(error.diagnostic),
+                    ...(error.idempotentReplay === undefined ? {} : { idempotentReplay: error.idempotentReplay }),
+                });
+            }
+            // The request may have reached the helper; without a typed code the only
+            // truthful answer is "effect unknown" (ledger h3 (e)).
+            return appendFailure('AMBIGUOUS_EFFECT');
+        }
+    };
+    const list = async (input) => {
+        if (disposed || !reachability.canList())
+            return { returns: [] };
+        let adapterOptions;
+        try {
+            adapterOptions = await adapterOptionsForRequest();
+        }
+        catch {
+            // Invalid installation is visible in status but does not start backoff.
+            // Only missing installation or a pre-send socket failure gates list.
+            return { returns: [] };
+        }
+        // Stop during pairing resolution: nothing sent yet, report an empty round.
+        if (disposed)
+            return { returns: [] };
+        try {
+            const after = toCursor(isObjectRecord(input) ? input.after : undefined);
+            const returns = await createPersonalChromeHostAdapter(adapterOptions).list_assistant_returns(after);
+            return { returns: [...returns] };
+        }
+        catch {
+            return { returns: [] };
+        }
+    };
+    const ack = async (input) => {
+        if (disposed)
+            return ackFailure('HOST_UNAVAILABLE');
+        if (!isCloudConversationAckInput(input)) {
+            return ackFailure('INVALID_REQUEST');
+        }
+        let adapterOptions;
+        try {
+            adapterOptions = await adapterOptionsForRequest();
+        }
+        catch (error) {
+            if (error instanceof PersonalChromeHostError)
+                return ackFailure(error.code);
+            return ackFailure('AMBIGUOUS_EFFECT');
+        }
+        // Stop during pairing resolution: no socket created, nothing was sent.
+        if (disposed)
+            return ackFailure('HOST_UNAVAILABLE');
+        try {
+            await createPersonalChromeHostAdapter(adapterOptions).ack_assistant_return(input.conversationId, input.sourceMessageId, input.assistantMessageId);
+            return { status: 'acknowledged' };
+        }
+        catch (error) {
+            if (error instanceof PersonalChromeHostError) {
+                // ASSISTANT_RETURN_NOT_FOUND means the return is already settled; pass it
+                // through so the Host stops retrying that entry.
+                return ackFailure(error.code, asContractDiagnostic(error.diagnostic));
+            }
+            return ackFailure('AMBIGUOUS_EFFECT');
+        }
+    };
+    const probe = async () => {
+        if (disposed)
+            return { ok: false, message: 'personal Chrome host module is stopped' };
+        let adapterOptions;
+        try {
+            adapterOptions = await adapterOptionsForRequest();
+        }
+        catch (error) {
+            if (error instanceof PersonalChromeHostError && error.code === 'HOST_UNAVAILABLE') {
+                return { ok: false, message: 'personal Chrome host is not installed (no pairing record)' };
+            }
+            if (error instanceof PersonalChromeHostError) {
+                return { ok: false, message: `personal Chrome pairing record rejected: ${error.code}` };
+            }
+            return { ok: false, message: 'personal Chrome pairing record is unreadable' };
+        }
+        // Stop during pairing resolution: never probe after stop returned.
+        if (disposed)
+            return { ok: false, message: 'personal Chrome host module is stopped' };
+        try {
+            const health = await createPersonalChromeHostAdapter(adapterOptions).check_health();
+            if (health.status === 'ready') {
+                return { ok: true, message: 'personal Chrome host helper answered the health probe' };
+            }
+            const reason = health.errorCode ?? health.status;
+            return { ok: false, message: `personal Chrome host health probe reported ${reason}` };
+        }
+        catch (error) {
+            if (error instanceof PersonalChromeHostError) {
+                return { ok: false, message: `personal Chrome host is not reachable: ${error.code}` };
+            }
+            return { ok: false, message: 'personal Chrome host health probe failed unexpectedly' };
+        }
+    };
+    // Owner-triggered, like probe: deliberately bypasses the background list gate.
+    const refreshTitles = async () => {
+        if (disposed)
+            return { status: 'unavailable', errorCode: 'HOST_UNAVAILABLE' };
+        try {
+            const adapterOptions = await adapterOptionsForRequest();
+            if (disposed)
+                return { status: 'unavailable', errorCode: 'HOST_UNAVAILABLE' };
+            return await createPersonalChromeHostAdapter(adapterOptions).refresh_conversation_titles();
+        }
+        catch (error) {
+            return { status: 'unavailable', errorCode: error instanceof PersonalChromeHostError ? error.code : 'AMBIGUOUS_EFFECT' };
+        }
+    };
+    return {
+        refreshTitles,
+        appendMessage,
+        list,
+        ack,
+        probe,
+        status: () => reachability.snapshot(),
+        dispose: async () => {
+            disposed = true;
+            reachability.reset();
+            requestTracker.cancelAll();
+        },
+    };
+}
+//# sourceMappingURL=conversation-host.js.map

package/dist/conversation-host.js.map

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

package/dist/extension-delivery.d.ts

@@ -0,0 +1,6 @@
+/** No symlinks: copying a package must not expand its read/write authority. */
+export declare function extensionFiles(directory: string): Promise<Map<string, Buffer>>;
+export declare function extensionDigest(files: ReadonlyMap<string, Buffer>): string;
+/** Caller holds the install lease. The previous complete directory is recoverable until activation. */
+export declare function replaceExtension<T>(dataDirectory: string, files: ReadonlyMap<string, Buffer>, activate: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=extension-delivery.d.ts.map

package/dist/extension-delivery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension-delivery.d.ts","sourceRoot":"","sources":["../src/extension-delivery.ts"],"names":[],"mappings":"AAIA,+EAA+E;AAC/E,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAcpF;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAI1E;AAED,uGAAuG;AACvG,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACjG,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAgCxC"}

package/dist/extension-delivery.js

@@ -0,0 +1,71 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { lstat, mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+/** No symlinks: copying a package must not expand its read/write authority. */
+export async function extensionFiles(directory) {
+    const files = new Map();
+    const visit = async (relative) => {
+        const path = join(directory, relative);
+        const metadata = await lstat(path);
+        if (metadata.isSymbolicLink())
+            throw new Error('extension symlinks are not supported');
+        if (metadata.isDirectory()) {
+            for (const child of (await readdir(path)).sort())
+                await visit(join(relative, child));
+        }
+        else if (metadata.isFile()) {
+            files.set(relative, await readFile(path));
+        }
+        else
+            throw new Error('extension entry must be a regular file or directory');
+    };
+    await visit('');
+    return files;
+}
+export function extensionDigest(files) {
+    const hash = createHash('sha256');
+    for (const [name, bytes] of files)
+        hash.update(name).update('\0').update(bytes).update('\0');
+    return hash.digest('hex');
+}
+/** Caller holds the install lease. The previous complete directory is recoverable until activation. */
+export async function replaceExtension(dataDirectory, files, activate) {
+    const destination = join(dataDirectory, 'extension');
+    const staging = join(dataDirectory, `.extension-${randomUUID()}`);
+    const backup = join(dataDirectory, `.extension-previous-${randomUUID()}`);
+    let backedUp = false;
+    let activated = false;
+    await mkdir(staging, { mode: 0o700 });
+    try {
+        for (const [name, bytes] of files) {
+            await mkdir(dirname(join(staging, name)), { recursive: true, mode: 0o700 });
+            await writeFile(join(staging, name), bytes, { mode: 0o600, flag: 'wx' });
+        }
+        try {
+            await rename(destination, backup);
+            backedUp = true;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        try {
+            await rename(staging, destination);
+            const result = await activate();
+            activated = true;
+            return result;
+        }
+        catch (error) {
+            await rm(destination, { recursive: true, force: true });
+            if (backedUp)
+                await rename(backup, destination);
+            throw error;
+        }
+    }
+    finally {
+        await rm(staging, { recursive: true, force: true });
+        if (activated && backedUp)
+            await rm(backup, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=extension-delivery.js.map

package/dist/extension-delivery.js.map

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