polygram 0.22.0 → 0.23.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "polygram",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Telegram integration for Claude Code that preserves the OpenClaw per-chat session model. Migration target for OpenClaw users. Multi-bot, multi-chat, per-topic isolation; SQLite transcripts; inline-keyboard approvals. Bundles /polygram:status|logs|pair-code|approvals admin commands plus history (transcript queries) and polygram-send (out-of-turn IPC sends with file-upload validation) skills.",
   "keywords": [
     "telegram",

package/README.md

@@ -45,8 +45,9 @@ ergonomics while running on top of `claude` CLI.
 - **Write-before-send atomicity.** Outbound messages hit the DB as
   `pending` before the Telegram call, flip to `sent` or `failed` after.
   Boot sweep resolves stale `pending` rows from the last crash.
-- **Unix-socket IPC per bot.** Cron jobs and Claude Code approval hooks
-  talk to the bot process over `/tmp/polygram-<bot>.sock`. The bot
+- **Unix-socket IPC per bot.** Cron jobs and external scripts talk to the
+  bot process over `<data-dir>/.ipc/polygram-<bot>.sock` inside an
+  owner-only runtime directory. The bot
   is the only writer to its own DB.
 - **Inline-keyboard approvals.** Destructive tool calls gate on operator
   click via Claude Code's `PreToolUse` hook; 5-minute auto-deny.
@@ -139,9 +140,10 @@ polygram --bot partner-bot        # another bot, another process
 - `config.json` → `$PWD/config.json` (override with `--config` or `POLYGRAM_CONFIG`)
 - `<bot>.db` → `$PWD/<bot>.db` (override with `--db` or `POLYGRAM_DB`)
 - `inbox/` → `$PWD/inbox/` (override with `POLYGRAM_INBOX`)
+- `.ipc/` → `$PWD/.ipc/` (override with canonical absolute `POLYGRAM_IPC_DIR`)
 
 Migrations are bundled in the package and apply automatically. The daemon
-opens a Unix socket at `/tmp/polygram-<bot>.sock`.
+opens a Unix socket at `$PWD/.ipc/polygram-<bot>.sock`.
 
 For production, LaunchAgent plists are in `ops/`. See `ops/README.md`.
 

package/config.example.json

@@ -63,6 +63,17 @@
     }
   },
 
+  "codex": {
+    "_comment": "Optional native macOS Codex app-server beta. Codex stays disabled unless a chat/topic explicitly sets pm:'codex' and exact startup preflight succeeds. Linux and Windows are rejected in this milestone. `home` must be a dedicated non-temporary 0700 CODEX_HOME already authenticated with ChatGPT; polygram never copies or reads credential contents. `binary` must be the canonical immutable path to the reviewed pinned Codex CLI, not a PATH symlink. Every directory containing daemon credentials or control data must be listed in daemonSecretRoots and must not overlap a Codex workspace or CODEX_HOME. Command network and model-native web search are disabled; product MCP tools and interactive approvals are unavailable. Keep long-running commands in the foreground. Detached/background servers are unsupported and may survive hard runtime loss.",
+    "home": "/Users/you/.codex-polygram",
+    "binary": "/Users/you/.local/share/codex/versions/0.145.0/codex",
+    "daemonSecretRoots": [
+      "/Users/you/.polygram",
+      "/Users/you/.claude",
+      "/Users/you/.codex"
+    ]
+  },
+
   "chats": {
     "123456789": {
       "name": "Admin DM",
@@ -77,6 +88,17 @@
       "compactionWarnings": true
     },
 
+    "987654321": {
+      "name": "Codex beta DM",
+      "bot": "admin-bot",
+      "_comment_pm": "Codex uses the pinned app-server SDK surface directly (no tmux). Native macOS beta only: command network and model-native web search are disabled; product MCP tools and interactive approvals are unavailable; long-running commands must stay in the foreground; detached/background servers are unsupported and may survive hard runtime loss. The model and effort are accepted only when returned by this deployment's authenticated ChatGPT-backed model catalog.",
+      "pm": "codex",
+      "codexModel": "gpt-5.6-sol",
+      "codexEffort": "xhigh",
+      "cwd": "/Users/you/codex-workspace",
+      "timeout": 600
+    },
+
     "-1000000000001": {
       "name": "Ops Group",
       "bot": "admin-bot",
@@ -104,7 +126,7 @@
       "isolateTopics": true,
       "_comment_topics": "rc.48: each topic entry is EITHER a string (legacy: just a label) OR an object with optional fields {name, agent, cwd, model, effort, permissionMode, isolateUserConfig}. Object form lets a topic override chat-level config. Per-topic permissionMode overrides chat-level — typical use: scope one topic to permissionMode:'default' (so settings.json gates apply) while the rest of the chat stays on bypassPermissions. Object form requires isolateTopics: true (each topic gets its own SDK Query); polygram emits a startup warning otherwise.",
       "_comment_isolateUserConfig": "0.10.0, tmux backend only: isolateUserConfig:true spawns the topic's claude TUI cut off from the user-level ~/.claude config — passes --strict-mcp-config (zero MCP servers load) and --setting-sources project,local (drops ~/.claude/settings.json; the spawn cwd's own .claude/settings.json still loads). Use it when a topic's agent would otherwise inherit slow user-global MCP servers whose cold-start (tens of seconds) wedges the TUI before it can accept a prompt. Settable at chat OR topic level (topic wins). Default false.",
-      "_comment_pm": "0.12.0: 'pm' selects the Process backend. Two canonical values: 'sdk' (default; per-token Console API billing; full SDK features) and 'cli' (subscription-priced claude CLI in tmux + Channels MCP bridge + hooks ndjson observability — see docs/0.12.0-cli-driver-plan.md). Settable at bot, chat, OR topic level (topic > chat > bot). Aliases preserved for back-compat with 0.10/0.11 configs: 'channels' and 'tmux' both resolve to 'cli' with a once-at-boot deprecation warn. CLI requires Pro/Max subscription, Claude Code v2.1.80+, and uses --dangerously-load-development-channels (research preview flag).",
+      "_comment_pm": "'pm' selects the session runtime. Canonical values: 'sdk' (default Claude API SDK), 'cli' (subscription-priced Claude CLI in tmux + Channels bridge), and 'codex' (subscription-backed pinned Codex app-server, no tmux). Settable at bot, chat, or topic scope (topic > chat > bot). Claude aliases 'channels' and 'tmux' still resolve to 'cli'. Codex uses separate codexModel/codexEffort fields and never consumes Claude model/effort values.",
       "topics": {
         "100": "Customer A",
         "200": {

package/lib/codex/binary.js

@@ -0,0 +1,287 @@
+'use strict';
+
+const { execFile } = require('node:child_process');
+const { createHash } = require('node:crypto');
+const {
+  createReadStream,
+  lstatSync,
+  realpathSync,
+  statSync,
+} = require('node:fs');
+const path = require('node:path');
+const { promisify } = require('node:util');
+
+const CODEX_CLI_PINNED_VERSION = 'codex-cli 0.145.0';
+const CODEX_BINARY_SHA256 =
+  '1da3f4e0e96028b8a771814293c3033dafd1971f943f6c7e79b0897fe705f590';
+const CONTROLLED_PATH = '/usr/bin:/bin';
+const SHA256_RE = /^[a-f0-9]{64}$/;
+const VERSION_PROBE_TIMEOUT_MS = 10_000;
+const VERSION_PROBE_MAX_BYTES = 4 * 1024;
+
+class CodexBinaryError extends Error {
+  constructor(message, code, action, options) {
+    super(message, options);
+    this.name = 'CodexBinaryError';
+    this.code = code;
+    this.action = action;
+  }
+}
+
+function deepFreeze(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) {
+    return value;
+  }
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.freeze(value);
+}
+
+function binaryAction(version = CODEX_CLI_PINNED_VERSION) {
+  return (
+    `Install ${version} as an immutable versioned executable and set `
+    + 'POLYGRAM_CODEX_BIN to its canonical absolute path.'
+  );
+}
+
+function fail(message, code, version, cause) {
+  return new CodexBinaryError(
+    message,
+    code,
+    binaryAction(version),
+    cause ? { cause } : undefined,
+  );
+}
+
+function fingerprint(binary) {
+  const stat = statSync(binary, { bigint: true });
+  if (!stat.isFile()) {
+    throw fail(
+      'Pinned Codex binary is not a regular file.',
+      'CODEX_BINARY_MISMATCH',
+    );
+  }
+  return {
+    dev: stat.dev.toString(),
+    ino: stat.ino.toString(),
+    size: stat.size.toString(),
+    mtimeNs: stat.mtimeNs.toString(),
+    ctimeNs: stat.ctimeNs.toString(),
+    mode: Number(stat.mode),
+    uid: Number(stat.uid),
+    nlink: Number(stat.nlink),
+  };
+}
+
+function sameFingerprint(left, right) {
+  return Object.keys(left).every((key) => left[key] === right[key]);
+}
+
+async function hashFile(binary) {
+  const hash = createHash('sha256');
+  await new Promise((resolve, reject) => {
+    const stream = createReadStream(binary);
+    stream.on('data', (chunk) => hash.update(chunk));
+    stream.once('error', reject);
+    stream.once('end', resolve);
+  });
+  return hash.digest('hex');
+}
+
+function validatePin(cliVersion, binarySha256) {
+  if (
+    typeof cliVersion !== 'string'
+    || cliVersion.length === 0
+    || !SHA256_RE.test(binarySha256)
+  ) {
+    throw new TypeError(
+      'Pinned Codex resolver requires an exact version and lowercase SHA-256.',
+    );
+  }
+}
+
+function createPinnedCodexBinaryResolver({
+  cliVersion,
+  binarySha256,
+  execFileFn = promisify(execFile),
+  platform = process.platform,
+  getuid = process.getuid?.bind(process),
+} = {}) {
+  validatePin(cliVersion, binarySha256);
+  if (typeof execFileFn !== 'function') {
+    throw new TypeError('Pinned Codex resolver requires execFileFn.');
+  }
+
+  return async function resolve({
+    binaryPath,
+    env = process.env,
+  } = {}) {
+    if (platform !== 'darwin') {
+      throw new CodexBinaryError(
+        'The native Codex beta currently supports only macOS hosts.',
+        'CODEX_BINARY_PLATFORM_UNSUPPORTED',
+        'Use macOS; Linux and Windows support are outside this rollout.',
+      );
+    }
+
+    const configured = binaryPath ?? env?.POLYGRAM_CODEX_BIN;
+    if (typeof configured !== 'string' || configured.length === 0) {
+      throw new CodexBinaryError(
+        'Pinned Codex binary is not configured.',
+        'CODEX_BINARY_NOT_CONFIGURED',
+        binaryAction(cliVersion),
+      );
+    }
+    if (!path.isAbsolute(configured)) {
+      throw fail(
+        'Pinned Codex binary must be an absolute path; PATH lookup is disabled.',
+        'CODEX_BINARY_NOT_ABSOLUTE',
+        cliVersion,
+      );
+    }
+
+    let canonical;
+    try {
+      canonical = realpathSync(configured);
+    } catch (error) {
+      if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') {
+        throw fail(
+          'Pinned Codex binary is missing.',
+          'CODEX_BINARY_MISSING',
+          cliVersion,
+          error,
+        );
+      }
+      throw fail(
+        'Pinned Codex binary could not be resolved safely.',
+        'CODEX_BINARY_MISMATCH',
+        cliVersion,
+        error,
+      );
+    }
+    if (canonical !== configured) {
+      throw fail(
+        'Pinned Codex binary path must be canonical and must not be a symlink.',
+        'CODEX_BINARY_MISMATCH',
+        cliVersion,
+      );
+    }
+
+    try {
+      const allowedOwners = new Set([0]);
+      if (typeof getuid === 'function') allowedOwners.add(getuid());
+      const root = path.parse(canonical).root;
+      let component = root;
+      for (const part of canonical.slice(root.length).split('/').filter(Boolean)) {
+        component = path.join(component, part);
+        const stat = lstatSync(component);
+        if (
+          stat.isSymbolicLink()
+          || !allowedOwners.has(stat.uid)
+          || (stat.mode & 0o022) !== 0
+        ) {
+          throw fail(
+            'Pinned Codex binary path ownership or mode is unsafe.',
+            'CODEX_BINARY_MISMATCH',
+            cliVersion,
+          );
+        }
+      }
+
+      const before = fingerprint(canonical);
+      if (
+        (before.mode & 0o022) !== 0
+        || (before.mode & 0o111) === 0
+        || !allowedOwners.has(before.uid)
+        || before.nlink !== 1
+      ) {
+        throw fail(
+          'Pinned Codex binary ownership or mode is unsafe.',
+          'CODEX_BINARY_MISMATCH',
+          cliVersion,
+        );
+      }
+
+      const actualSha256 = await hashFile(canonical);
+      if (actualSha256 !== binarySha256) {
+        throw fail(
+          'Pinned Codex binary checksum does not match the reviewed runtime.',
+          'CODEX_BINARY_MISMATCH',
+          cliVersion,
+        );
+      }
+
+      let stdout;
+      try {
+        ({ stdout } = await execFileFn(canonical, ['--version'], {
+          encoding: 'utf8',
+          timeout: VERSION_PROBE_TIMEOUT_MS,
+          maxBuffer: VERSION_PROBE_MAX_BYTES,
+          env: { PATH: CONTROLLED_PATH },
+        }));
+      } catch (error) {
+        throw fail(
+          'Pinned Codex binary version probe failed.',
+          'CODEX_BINARY_MISMATCH',
+          cliVersion,
+          error,
+        );
+      }
+      if (typeof stdout !== 'string' || stdout.trim() !== cliVersion) {
+        throw fail(
+          'Pinned Codex binary version does not match the reviewed runtime.',
+          'CODEX_BINARY_MISMATCH',
+          cliVersion,
+        );
+      }
+
+      if (
+        realpathSync(canonical) !== canonical
+        || !sameFingerprint(before, fingerprint(canonical))
+      ) {
+        throw fail(
+          'Pinned Codex binary changed during verification.',
+          'CODEX_BINARY_MISMATCH',
+          cliVersion,
+        );
+      }
+
+      return deepFreeze({
+        path: canonical,
+        version: cliVersion,
+        sha256: actualSha256,
+        fingerprint: before,
+      });
+    } catch (error) {
+      if (error instanceof CodexBinaryError) throw error;
+      if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') {
+        throw fail(
+          'Pinned Codex binary disappeared during verification.',
+          'CODEX_BINARY_MISSING',
+          cliVersion,
+          error,
+        );
+      }
+      throw fail(
+        'Pinned Codex binary failed ownership and integrity verification.',
+        'CODEX_BINARY_MISMATCH',
+        cliVersion,
+        error,
+      );
+    }
+  };
+}
+
+// Application code uses this fixed resolver. The factory exists so a pin
+// upgrade can verify its candidate fixture before changing the production pin.
+const resolvePinnedCodexBinary = createPinnedCodexBinaryResolver({
+  cliVersion: CODEX_CLI_PINNED_VERSION,
+  binarySha256: CODEX_BINARY_SHA256,
+});
+
+module.exports = {
+  CODEX_BINARY_SHA256,
+  CODEX_CLI_PINNED_VERSION,
+  CodexBinaryError,
+  createPinnedCodexBinaryResolver,
+  resolvePinnedCodexBinary,
+};

package/lib/codex/delivery-finalizer.js

@@ -0,0 +1,97 @@
+'use strict';
+
+function claimsCodexRuntime(result) {
+  return result?.runtime === 'codex' || result?.backend === 'codex';
+}
+
+function missingControllerError() {
+  const error = new Error(
+    'A Codex result cannot be finalized without its runtime controller',
+  );
+  error.code = 'CODEX_DELIVERY_CONTROLLER_MISSING';
+  return error;
+}
+
+async function finalizeTelegramDelivery({
+  controller,
+  sessionKey,
+  result,
+  deliveryComplete = true,
+  queuedDispatch = null,
+  markHandlerStatus,
+} = {}) {
+  if (typeof markHandlerStatus !== 'function') {
+    throw new TypeError('markHandlerStatus function required');
+  }
+
+  if (!claimsCodexRuntime(result)) {
+    await markHandlerStatus('replied');
+    return Object.freeze({
+      runtime: 'claude',
+      disposition: 'delivered',
+      handlerStatus: 'replied',
+    });
+  }
+  if (!controller) throw missingControllerError();
+
+  const disposition = (
+    result?.error == null
+    && deliveryComplete === true
+  )
+    ? 'delivered'
+    : 'failed';
+  await controller.settleTelegramDelivery(
+    sessionKey,
+    result,
+    { disposition },
+  );
+
+  if (disposition === 'delivered' && queuedDispatch?.reservationId) {
+    controller.settleQueuedDispatch({
+      sessionKey,
+      generationId: result.generationId,
+      reservationId: queuedDispatch.reservationId,
+      attemptId: result.attemptId,
+      botName: queuedDispatch.botName,
+      telegramChatId: queuedDispatch.telegramChatId,
+      telegramMessageId: queuedDispatch.telegramMessageId,
+    });
+  }
+
+  const handlerStatus = disposition === 'delivered' ? 'replied' : 'failed';
+  await markHandlerStatus(handlerStatus);
+  return Object.freeze({
+    runtime: 'codex',
+    disposition,
+    handlerStatus,
+  });
+}
+
+function createTelegramDeliveryFinalizer(options = {}) {
+  let outcome = null;
+
+  async function finalize(deliveryComplete = true) {
+    if (outcome) return outcome;
+    outcome = await finalizeTelegramDelivery({
+      ...options,
+      deliveryComplete,
+    });
+    return outcome;
+  }
+
+  async function failIfPending() {
+    if (outcome || !claimsCodexRuntime(options.result)) return outcome;
+    return finalize(false);
+  }
+
+  return Object.freeze({
+    finalize,
+    failIfPending,
+  });
+}
+
+module.exports = {
+  claimsCodexRuntime,
+  createTelegramDeliveryFinalizer,
+  finalizeTelegramDelivery,
+};