@hellolynk-ai/codex-plugin 0.0.0-stage → 0.2.100

package/plugins/hellolynk-codex/runtime/core/hellolynk-local-peer-transport.mjs

@@ -0,0 +1,103 @@
+import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { validateLocalIdentityProofRequest } from "./hellolynk-local-identity-trust.mjs";
+
+export const LOCAL_PEER_EXCHANGE_PATH = "/host/v1/local-peer-exchange";
+const CONTRACT = "hellolynk-local-peer-exchange-v1";
+const fail = (code = "local_peer_exchange_invalid") => Object.assign(new Error(code), { code });
+function exact(value, fields) {
+  if (!value || typeof value !== "object" || Array.isArray(value)
+    || Object.keys(value).sort().join(",") !== [...fields].sort().join(",")) throw fail();
+}
+function id(value) {
+  if (typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_.:-]{0,199}$/.test(value)) throw fail();
+  return value;
+}
+const digest = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+
+export function validateLocalPeerRequest(value) {
+  exact(value, ["challenge", "owner", "target", "source", "action", "payload"]);
+  const base = validateLocalIdentityProofRequest({ challenge: value.challenge, owner: value.owner, target: value.target });
+  const source = validateLocalIdentityProofRequest({ ...base, target: value.source }).target;
+  if (source.hostInstallationId === base.target.hostInstallationId || source.delegateId === base.target.delegateId) throw fail();
+  if (value.action === "claim") {
+    exact(value.payload, ["routeKind", "clientMessageId", "recipientDeviceId",
+      ...(value.payload?.nativeContentVersion == null ? [] : ["nativeContentVersion"])]);
+    if (value.payload.nativeContentVersion != null && value.payload.nativeContentVersion !== 1) throw fail();
+    if (!["owned_delegate", "instance_direct"].includes(value.payload.routeKind)) throw fail();
+    id(value.payload.clientMessageId);
+    if (value.payload.recipientDeviceId !== null) id(value.payload.recipientDeviceId);
+  } else if (value.action === "deliver") {
+    exact(value.payload, ["event", ...(value.payload?.nativeContentVersion == null ? [] : ["nativeContentVersion"])]);
+    if (value.payload.nativeContentVersion != null && value.payload.nativeContentVersion !== 1) throw fail();
+    const event = value.payload.event;
+    if (!event || event.schemaVersion !== 2 || !event.e2eeEnvelope || typeof event.envelopeDigest !== "string") throw fail();
+    if (event.eventId !== `same_host_${createHash("sha256").update(`${event.clientMessageId}\0${event.envelopeDigest}`).digest("hex").slice(0, 32)}`) throw fail();
+    // The full envelope/signature and all outer bindings are validated by the
+    // ordinary E2EE receiver; this boundary only fixes the selected local pair.
+    if (event.senderPrincipalId !== base.owner.principalId || event.recipientPrincipalId !== base.owner.principalId
+      || event.senderHelloLynkId !== base.owner.hellolynkId || event.recipientHelloLynkId !== base.owner.hellolynkId
+      || event.senderHostId !== source.hostInstallationId || event.senderDelegateId !== source.delegateId
+      || event.senderDelegateAuthorizationVersion !== source.authorizationVersion
+      || event.recipientHostId !== base.target.hostInstallationId || event.recipientDelegateId !== base.target.delegateId
+      || event.recipientDelegateAuthorizationVersion !== base.target.authorizationVersion
+      || !["owned_delegate", "instance_direct"].includes(event.routeKind)) throw fail();
+  } else throw fail();
+  return { ...base, source, action: value.action, payload: value.payload };
+}
+
+function signedPayload({ request, hostGeneration, capabilityId, result }) {
+  return { contract: CONTRACT, requestDigest: digest(validateLocalPeerRequest(request)),
+    hostGeneration: id(hostGeneration), capabilityId: id(capabilityId), result };
+}
+function mac(value, secret) {
+  if (!Buffer.isBuffer(secret) || secret.length < 32) throw fail();
+  return createHmac("sha256", secret).update(`${CONTRACT}\n${JSON.stringify(value)}`).digest("hex");
+}
+export function signLocalPeerResult(input) {
+  const value = signedPayload(input);
+  return { ...value, proof: mac(value, input.secretBuffer) };
+}
+export function verifyLocalPeerResult(input) {
+  exact(input.response, ["contract", "requestDigest", "hostGeneration", "capabilityId", "result", "proof"]);
+  const expected = signedPayload({ ...input, result: input.response.result });
+  const { proof, ...actual } = input.response;
+  if (JSON.stringify(expected) !== JSON.stringify(actual) || !/^[a-f0-9]{64}$/.test(proof)
+    || !timingSafeEqual(Buffer.from(proof, "hex"), Buffer.from(mac(expected, input.secretBuffer), "hex"))) throw fail();
+  return actual.result;
+}
+
+export function createLocalPeerTransport({ profile, access }) {
+  const source = { hostInstallationId: profile.hostId, delegateId: profile.delegateId,
+    authorizationVersion: profile.authorizationVersion };
+  async function exchange(target, action, payload, { required, signal } = {}) {
+    return access(target, async (peer) => {
+      if (!peer.binding.capability.scopes.includes("app-data:authorized-messaging")) throw fail("local_peer_messaging_unavailable");
+      const request = validateLocalPeerRequest({ challenge: randomBytes(32).toString("hex"), owner: peer.owner,
+        target: { hostInstallationId: peer.binding.hostInstallationId, delegateId: peer.binding.delegateId,
+          authorizationVersion: peer.target.authorizationVersion }, source, action, payload });
+      const response = await peer.request(LOCAL_PEER_EXCHANGE_PATH, request);
+      // No transport switch after this call, including timeout/invalid ACK.
+      // The messenger retains its existing outcome-unknown and retry rules.
+      if (response.status !== 200) throw fail("local_peer_exchange_unconfirmed");
+      return verifyLocalPeerResult({ response: response.body, request, hostGeneration: peer.discovery.hostGeneration,
+        capabilityId: peer.binding.capability.capabilityId, secretBuffer: peer.binding.capability.secretBuffer });
+    }, { required, signal, proveIdentity: false, timeoutMs: 30_000 });
+  }
+  return Object.freeze({
+    claim(input, { signal } = {}) {
+      return exchange({ peerHelloLynkId: profile.hellolynkId, peerDelegateId: input.recipientDelegateId,
+        peerHostId: input.recipientHostId }, "claim", { routeKind: input.routeKind, clientMessageId: input.clientMessageId,
+        recipientDeviceId: input.recipientDeviceId ?? null,
+        ...(input.nativeContentVersion ? { nativeContentVersion: input.nativeContentVersion } : {}) }, { signal });
+    },
+    async deliver(event, nativeContentVersion = null) {
+      const result = await exchange({ peerHelloLynkId: event.recipientHelloLynkId, peerDelegateId: event.recipientDelegateId,
+        peerHostId: event.recipientHostId, peerAuthorizationVersion: event.recipientDelegateAuthorizationVersion },
+      "deliver", { event, ...(nativeContentVersion == null ? {} : { nativeContentVersion }) }, { required: true });
+      exact(result, ["acknowledged", "duplicate", "replyTargetDeleted", "eventId", "envelopeDigest"]);
+      if (result.acknowledged !== true || typeof result.duplicate !== "boolean" || typeof result.replyTargetDeleted !== "boolean"
+        || result.eventId !== event.eventId || result.envelopeDigest !== event.envelopeDigest) throw fail("local_peer_ack_invalid");
+      return result;
+    },
+  });
+}

package/plugins/hellolynk-codex/runtime/core/hellolynk-local-process-lock.mjs

@@ -0,0 +1,157 @@
+import crypto from "node:crypto";
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import net from "node:net";
+import path from "node:path";
+import { performance } from "node:perf_hooks";
+
+// Serialize lock-file changes with an OS-owned resource. A check followed by
+// rename/unlink is not a compare-and-swap, even when the file is checked twice.
+// The OS releases this guard if its process exits; there is no second stale
+// lock file to reclaim. Nothing is read from or written to connected clients.
+export async function withLocalProcessLock(target, operation, { timeoutMs = 10_000 } = {}) {
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || typeof operation !== "function") {
+    throw lockError("hellolynk_local_process_lock_invalid");
+  }
+  const started = performance.now();
+  const parent = await fs.realpath(path.dirname(target));
+  const canonical = path.join(parent, path.basename(target));
+  const scope = process.platform === "win32" || process.platform === "darwin"
+    ? canonical.toLowerCase() : canonical;
+  const digest = crypto.createHash("sha256").update(scope).digest("hex");
+  const address = process.platform === "win32"
+    ? { path: `\\\\.\\pipe\\hellolynk-file-lock-${digest}` }
+    : process.platform === "linux"
+      ? { path: `\0hellolynk-file-lock-${digest}` }
+      // macOS has no abstract Unix sockets. A deterministic loopback port is
+      // also released on crash. A collision fails closed; never select another
+      // port, which would let contenders for the same file use different locks.
+      : { host: "127.0.0.1", port: 16_384 + (Number.parseInt(digest.slice(0, 8), 16) % 49_152) };
+  let server;
+  for (;;) {
+    if (performance.now() - started >= timeoutMs) throw lockError("hellolynk_local_process_lock_busy");
+    server = net.createServer((socket) => { socket.on("error", () => {}); socket.destroy(); });
+    try {
+      await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen({ ...address, exclusive: true }, resolve);
+      });
+      break;
+    } catch (error) {
+      server.close();
+      if (error?.code !== "EADDRINUSE") throw lockError("hellolynk_local_process_lock_unavailable", error);
+      await new Promise((resolve) => setTimeout(resolve, Math.min(25, Math.max(1, timeoutMs - (performance.now() - started)))));
+    }
+  }
+  try { return await operation(); }
+  finally { await new Promise((resolve) => server.close(resolve)); }
+}
+
+function lockError(code, cause) { return Object.assign(new Error(code, cause ? { cause } : undefined), { code }); }
+
+// Process birth identity distinguishes an active lock owner from a reused PID.
+const SELF_PROCESS_STARTED_AT_MS = Date.now() - (process.uptime() * 1_000);
+let selfProcessIdentityPromise = null;
+
+export async function inspectProcessIdentity(pid) {
+  if (!Number.isSafeInteger(pid) || pid < 1) return null;
+  if (pid === process.pid) {
+    selfProcessIdentityPromise ||= inspectPlatformProcessIdentity(pid).then((value) => value || Object.freeze({
+      identity: `portable:${process.platform}:${Math.round(SELF_PROCESS_STARTED_AT_MS)}`,
+      startedAtMs: SELF_PROCESS_STARTED_AT_MS,
+    }));
+    return selfProcessIdentityPromise;
+  }
+  return inspectPlatformProcessIdentity(pid);
+}
+
+async function inspectPlatformProcessIdentity(pid) {
+  if (process.platform === "linux") return inspectLinuxProcessIdentity(pid);
+  if (process.platform === "win32") return inspectWindowsProcessIdentity(pid);
+  if (process.platform === "darwin") return inspectDarwinProcessIdentity(pid);
+  return null;
+}
+
+async function inspectLinuxProcessIdentity(pid) {
+  try {
+    const [statText, bootId, processMetadata] = await Promise.all([
+      fs.readFile(`/proc/${pid}/stat`, "utf8"),
+      fs.readFile("/proc/sys/kernel/random/boot_id", "utf8"),
+      fs.stat(`/proc/${pid}`),
+    ]);
+    const close = statText.lastIndexOf(")");
+    if (close < 1) return null;
+    const fields = statText.slice(close + 2).trim().split(/\s+/);
+    const startTicks = fields[19];
+    const normalizedBootId = bootId.trim().toLowerCase();
+    if (!/^\d+$/.test(String(startTicks || ""))
+      || !/^[a-f0-9-]{32,40}$/.test(normalizedBootId)) return null;
+    return Object.freeze({
+      identity: `linux:${normalizedBootId}:${startTicks}`,
+      startedAtMs: Number.isFinite(processMetadata.ctimeMs) ? processMetadata.ctimeMs : null,
+    });
+  } catch { return null; }
+}
+
+async function inspectWindowsProcessIdentity(pid) {
+  const systemRoot = String(process.env.SystemRoot || "C:\\Windows");
+  if (!path.isAbsolute(systemRoot)) return null;
+  const powershell = path.join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+  const script = `$p=Get-Process -Id ${pid} -ErrorAction Stop;[Console]::Out.Write($p.StartTime.ToUniversalTime().Ticks.ToString())`;
+  const output = await runIdentityProbe(powershell, [
+    "-NoLogo", "-NoProfile", "-NonInteractive", "-Command", script,
+  ]);
+  if (!/^\d{12,20}$/.test(String(output || ""))) return null;
+  const ticks = Number(output);
+  const startedAtMs = (ticks / 10_000) - 62_135_596_800_000;
+  if (!Number.isFinite(startedAtMs) || startedAtMs < 0) return null;
+  return Object.freeze({ identity: `win32:${output}`, startedAtMs });
+}
+
+async function inspectDarwinProcessIdentity(pid) {
+  const output = await runIdentityProbe("/bin/ps", ["-o", "lstart=", "-p", String(pid)]);
+  const startedAtMs = Date.parse(String(output || "").trim());
+  if (!Number.isFinite(startedAtMs)) return null;
+  return Object.freeze({
+    identity: `darwin:${crypto.createHash("sha256").update(output.trim()).digest("hex")}`,
+    startedAtMs,
+  });
+}
+
+async function runIdentityProbe(executable, args) {
+  return new Promise((resolve) => {
+    let output = "";
+    let overflow = false;
+    let settled = false;
+    let child;
+    const settle = (value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(value);
+    };
+    const timer = setTimeout(() => {
+      child?.kill();
+      settle(null);
+    }, 2_000);
+    try {
+      child = spawn(executable, args, {
+        windowsHide: true,
+        stdio: ["ignore", "pipe", "ignore"],
+      });
+    } catch {
+      settle(null);
+      return;
+    }
+    child.stdout.on("data", (chunk) => {
+      if (overflow) return;
+      output += chunk.toString("utf8");
+      if (Buffer.byteLength(output, "utf8") > 256) {
+        output = "";
+        overflow = true;
+      }
+    });
+    child.once("error", () => settle(null));
+    child.once("close", (code) => settle(code === 0 && !overflow ? output.trim() : null));
+  });
+}

package/plugins/hellolynk-codex/runtime/core/hellolynk-model-inbox.mjs

@@ -0,0 +1,230 @@
+import { readNativeReplyRoute } from "./hellolynk-native-reply-routes.mjs";
+import { setTimeout as delay } from "node:timers/promises";
+import { readNativeInboxBatchDispatch } from "./hellolynk-native-inbox-runtime.mjs";
+
+const ID = /^[A-Za-z0-9][A-Za-z0-9_.:-]{2,240}$/;
+const READS = new Set(["list", "read", "pending", "count"]);
+const fail = code => { throw Object.assign(new Error(code), { code }); };
+export function modelInboxCaller(value) {
+  if (!value || typeof value !== "object" || !ID.test(value.threadId || "")) fail("model_inbox_context_unavailable");
+  // Aliases are supplied by a verified native bridge, never by tool arguments.
+  if (value.aliases != null && (!Array.isArray(value.aliases) || value.aliases.length > 2
+    || value.aliases.some(id => !ID.test(id)))) fail("model_inbox_context_unavailable");
+  return { threadId: value.threadId, ...(value.aliases?.length ? { aliases: [...new Set(value.aliases)] } : {}) };
+}
+
+// Request-local only. The dispatcher keeps its original, unscoped operations.
+export async function runModelInbox(request, io) {
+  const { operation, query = {}, scope = "current" } = request;
+  if (![...READS, "claim", "assertReply"].includes(operation)
+    || scope !== "current") fail("model_inbox_scope_invalid");
+  const caller = modelInboxCaller(request.caller);
+  const nativeIds = new Set([caller.threadId, ...(caller.aliases || [])]);
+  const assignmentCache = new Map(), messageAssignments = new Map();
+  async function preparePage(messages) {
+    if (!messages.length) return;
+    const rows = await io.assignments(messages.map(message => message.localMessageId));
+    for (const message of messages) messageAssignments.set(message.localMessageId, rows[message.localMessageId] ?? null);
+  }
+  const nativeThread = async assignment => {
+    if (!assignment) return null;
+    if (assignment.nativeThreadId) return assignment.nativeThreadId;
+    if (!assignmentCache.has(assignment.batchId)) {
+      assignmentCache.set(assignment.batchId, (await readNativeInboxBatchDispatch(io.nativeScope, assignment.batchId))?.threadId || null);
+    }
+    return assignmentCache.get(assignment.batchId);
+  };
+  const targetThread = target => {
+    const prefix = io.nativeScope.adapterId === "claude-code" ? "claude-original:" : io.nativeScope.adapterId + "-origin:";
+    return typeof target === "string" && target.startsWith(prefix) ? target.slice(prefix.length) : null;
+  };
+  async function assertAssignment(assignment) {
+    if (!assignment) fail("model_inbox_unassigned");
+    const deadline = Date.now() + 5_000;
+    while (true) {
+      const owner = assignment.nativeThreadId || targetThread(assignment.target);
+      if (owner) {
+        if (!nativeIds.has(owner)) fail("model_inbox_other_conversation");
+        return;
+      }
+      const dispatch = await readNativeInboxBatchDispatch(io.nativeScope, assignment.batchId);
+      if (dispatch?.threadId) {
+        if (!nativeIds.has(dispatch.threadId)) fail("model_inbox_other_conversation");
+        return;
+      }
+      // Codex creates and prompts atomically: its first claim can precede the
+      // create response. Wait only for the authoritative owner, never guess it.
+      if (!dispatch?.pending) {
+        // Confirm can pin the owner and remove runtime state between our reads.
+        const latest = await io.assignment({ batchId: assignment.batchId });
+        if (latest?.nativeThreadId) { assignment = latest; continue; }
+        fail("model_inbox_unassigned");
+      }
+      if (Date.now() >= deadline) fail("model_inbox_owner_pending");
+      await delay(100);
+      assignment = await io.assignment({ batchId: assignment.batchId });
+      if (!assignment) fail("model_inbox_unassigned");
+    }
+  }
+  async function owns(message, assert = false) {
+    const assignment = messageAssignments.has(message.localMessageId) ? messageAssignments.get(message.localMessageId)
+      : await io.assignment({ localMessageId: message.localMessageId });
+    if (assignment) {
+      if (assert) { await assertAssignment(assignment); return true; }
+      const owner = await nativeThread(assignment);
+      if (owner) return nativeIds.has(owner);
+      // A known original target is immutable. Never infer historical ownership
+      // from a carrier that may since have been closed and recreated.
+      return nativeIds.has(targetThread(assignment.target));
+    }
+    if (message.targetConversationId && message.replyToClientMessageId) fail("model_inbox_route_invalid");
+    if (message.targetConversationId) return nativeIds.has(message.targetConversationId);
+    if (message.replyToClientMessageId) {
+      return nativeIds.has((await readNativeReplyRoute(io.nativeScope, message))?.threadId);
+    }
+    if (assert) fail("model_inbox_unassigned");
+    return false; // New, unassigned mail belongs to the backend dispatcher.
+  }
+  async function assertMessage() {
+    const message = await io.metadata(query);
+    if (!await owns(message, true)) fail("model_inbox_other_conversation");
+    return message;
+  }
+  async function history({ count = false } = {}) {
+    const selected = []; let unread = 0, before = query.before;
+    while (true) {
+      const page = await io.list(before == null ? {} : { before });
+      if (!Array.isArray(page.messages)) fail("model_inbox_response_invalid");
+      await preparePage(page.messages);
+      for (const message of page.messages) {
+        if (await owns(message)) {
+          if (count) unread += Number(message.unread === true);
+          else selected.push(message);
+        }
+        if (!count && selected.length === 10) return { messages: selected };
+      }
+      if (!page.messages.length) return count ? unread : { messages: selected };
+      const next = page.messages.at(-1).localMessageId;
+      if (!next || next === before) fail("model_inbox_cursor_invalid");
+      before = next;
+    }
+  }
+  async function pending({ count = false } = {}) {
+    const selected = []; let total = 0, cursor = query.cursor ?? 0;
+    while (true) {
+      const page = await io.pending({ cursor });
+      if (!Array.isArray(page.messages)) fail("model_inbox_response_invalid");
+      await preparePage(page.messages);
+      for (const message of page.messages) if (await owns(message)) {
+        if (count) total++;
+        else {
+          selected.push(message);
+          if (selected.length === 1000) return { messages: selected, nextCursor: message.receiptSeq };
+        }
+      }
+      if (page.nextCursor == null) return count ? total : { messages: selected, nextCursor: null };
+      if (!Number.isSafeInteger(page.nextCursor) || page.nextCursor <= cursor) fail("model_inbox_cursor_invalid");
+      cursor = page.nextCursor;
+    }
+  }
+  if (operation === "list") return history();
+  if (operation === "pending") return pending();
+  if (operation === "count") {
+    const humanUnreadCount = await history({ count: true });
+    const aiPendingCount = await pending({ count: true });
+    return { unreadCount: humanUnreadCount, humanUnreadCount, aiPendingCount, scope };
+  }
+  if (operation === "read") {
+    await assertMessage();
+    return io.read(query);
+  }
+  if (operation === "claim") {
+    if (query.batchId) {
+      const assignment = await io.assignment({ batchId: query.batchId });
+      await assertAssignment(assignment);
+    } else await assertMessage();
+    return io.claim(query);
+  }
+  await assertMessage(); // Before reply-origin registration as well as send.
+  return { allowed: true };
+}
+
+const MODEL_TOOLS = Object.freeze({
+  hellolynk_get_unread_count: "count", hellolynk_list_authorized_inbox_messages: "list",
+  hellolynk_read_authorized_inbox_message: "read", hellolynk_list_pending_messages: "pending",
+  hellolynk_claim_message: "claim", hellolynk_reply_authorized_message: "reply",
+});
+export const isModelInboxTool = name => Object.hasOwn(MODEL_TOOLS, name);
+export async function prepareModelInboxInvocation(adapter, { name, args = {}, caller, readEnvelope = false, detailTarget = null }) {
+  const operation = MODEL_TOOLS[name];
+  if (!operation) return { adapter, args, finish: value => value };
+  if (!args || typeof args !== "object" || Array.isArray(args)) fail("model_inbox_scope_invalid");
+  if (Object.hasOwn(args, "scope")) fail("model_inbox_scope_invalid");
+  const checkedCaller = modelInboxCaller(caller);
+  if (typeof adapter?.modelInbox !== "function") fail("model_inbox_unavailable");
+  const clean = { ...args };
+  const cursor = operation === "pending" ? clean.cursor : undefined;
+  if (operation === "pending") {
+    if (cursor != null && (!Number.isSafeInteger(cursor) || cursor < 0)) fail("model_inbox_scope_invalid");
+    delete clean.cursor;
+  }
+  let last;
+  const call = async (op, query = {}) => {
+    last = await adapter.modelInbox({ operation: op, scope: "current", caller: checkedCaller, query });
+    return last;
+  };
+  let assertedReply = null;
+  async function assertReply(query) {
+    const key = JSON.stringify([query.localMessageId, query.conversationKey]);
+    if (assertedReply === key) return;
+    await call('assertReply', { localMessageId: query.localMessageId, conversationKey: query.conversationKey });
+    assertedReply = key;
+  }
+  const scoped = { ...adapter,
+    assertModelInboxReply: assertReply,
+    replyAuthorizedMessage: async query => { await assertReply(query); return adapter.replyAuthorizedMessage(query); },
+    readUnreadCount: () => call("count"),
+    listAuthorizedInboxMessages: (query = {}) => call("list", query),
+    readAuthorizedInboxMessage: async (localMessageId, conversationKey) => {
+      const result = await call("read", { localMessageId, conversationKey });
+      return readEnvelope ? result : result.message;
+    },
+    listPendingMessages: (query = {}) => call("pending", { ...(query || {}), ...(cursor == null ? {} : { cursor }) }),
+    listPendingAuthorizedInboxMessages: () => call("pending", cursor == null ? {} : { cursor }),
+    claimMessage: (localMessageId, conversationKey) => call("claim", { localMessageId, conversationKey }),
+    claimAuthorizedInboxMessage: (localMessageId, conversationKey) => call("claim", { localMessageId, conversationKey }),
+    claimBatch: batchId => call("claim", { batchId }),
+    claimInboxBatch: batchId => call("claim", { batchId }),
+  };
+  function finish(value) {
+    if (!READS.has(operation)) return value;
+    if (!value || value.isError || value.ok === false || value.structuredContent?.ok === false) return value;
+    const detail = { scope: "current",
+      ...(last?.nextCursor != null ? { nextCursor: last.nextCursor } : {}) };
+    if (operation === "count" && last) Object.assign(detail, {
+      humanUnreadCount: last.humanUnreadCount, aiPendingCount: last.aiPendingCount,
+    });
+    if (value.structuredContent) {
+      const structuredContent = detailTarget && value.structuredContent[detailTarget]
+        ? { ...value.structuredContent, [detailTarget]: { ...value.structuredContent[detailTarget], ...detail } }
+        : { ...value.structuredContent, ...detail };
+      const originalJson = JSON.stringify(value.structuredContent), projected = JSON.stringify(structuredContent);
+      let hasProjection = false;
+      const content = (value.content || []).map(item => {
+        if (item.type !== 'text') return item;
+        try {
+          if (JSON.stringify(JSON.parse(item.text)) === originalJson) { hasProjection = true; return { ...item, text: projected }; }
+        } catch { /* Ordinary result text. */ }
+        return item;
+      });
+      if (operation === 'count') return { ...value, structuredContent, content: [
+        { type: 'text', text: '当前对话：人类未读 ' + last.humanUnreadCount + ' 条；AI 待处理 ' + last.aiPendingCount + ' 条。' },
+        { type: 'text', text: projected },
+      ] };
+      if (!hasProjection) content.push({ type: 'text', text: projected });
+      return { ...value, structuredContent, content };
+    }
+    return { ...value, ...detail };
+  }
+  return { adapter: scoped, args: clean, finish };
+}

package/plugins/hellolynk-codex/runtime/core/hellolynk-model-notices.cjs

@@ -0,0 +1,60 @@
+"use strict";
+
+const { AsyncLocalStorage } = require("node:async_hooks");
+// Only collect responses belonging to this model tool invocation. Card refreshes,
+// background polling and another account's concurrent call cannot supply notices.
+const calls = new AsyncLocalStorage();
+
+function captureHelloLynkModelNotices(response) {
+  const call = calls.getStore();
+  const state = response?.body?.modelNotices;
+  if (call && state && typeof state === "object") {
+    call.notices = [];
+    if (Number.isSafeInteger(state.pendingContactRequests) && state.pendingContactRequests > 0) {
+      call.notices.push(`有 ${state.pendingContactRequests} 个联系申请等你确认。`);
+    }
+    if (state.localStorageFull === true) call.notices.push("本机存储已满，已暂停接收新消息。");
+  }
+  return response;
+}
+
+function captureHelloLynkNativeDeliveryStatus(state) {
+  const call = calls.getStore();
+  if (!call) return;
+  call.nativeNotices = [];
+  if (state?.failure && /^[A-Za-z0-9_:-]{1,100}$/.test(state.failure.code)) {
+    call.nativeNotices.push(`本机 AI 收信提醒检查失败（${state.failure.code}），与本次发信结果无关。`);
+  }
+  if (Number.isSafeInteger(state?.unknownCount) && state.unknownCount > 0) {
+    call.nativeNotices.push(`本机 AI 收信提醒：${state.unknownCount} 条近期提醒结果未知；与本次发信结果、对方未读无关，请勿据此重发。`);
+  }
+}
+
+function appendNotices(result, notices) {
+  if (!notices?.length) return result;
+  const text = `HelloLynk：${notices.join(" ")}`;
+  if (typeof result === "string") {
+    try {
+      const value = JSON.parse(result);
+      return JSON.stringify({ ...value, notices });
+    } catch { return `${result}\n${text}`; }
+  }
+  if (result?.result) return { ...result, result: appendNotices(result.result, notices) };
+  if (!Array.isArray(result?.content)) return result;
+  return { ...result, content: [...result.content, { type: "text", text }],
+    ...(result.structuredContent ? { structuredContent: { ...result.structuredContent, notices } } : {}),
+    ...(result.details ? { details: { ...result.details, notices } } : {}) };
+}
+
+async function withHelloLynkModelNotices(operation) {
+  const call = {};
+  return calls.run(call, async () => {
+    const result = await operation();
+    // A notice can never turn a successful send into an error or cause a resend.
+    try { return appendNotices(result, [...(call.notices || []), ...(call.nativeNotices || [])]); } catch { return result; }
+  });
+}
+
+exports.captureHelloLynkModelNotices = captureHelloLynkModelNotices;
+exports.captureHelloLynkNativeDeliveryStatus = captureHelloLynkNativeDeliveryStatus;
+exports.withHelloLynkModelNotices = withHelloLynkModelNotices;