agentstreamdeck 2.1.1__py3-none-any.whl

ocdeck/launcher.py

@@ -0,0 +1,203 @@
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import time
+import uuid
+from .common import home, atomic_json, read_json, identity, request
+
+
+def route(args):
+    """Global opencode shim: wrap interactive launches; pass CLI utilities through."""
+    commands = {
+        "run",
+        "serve",
+        "web",
+        "acp",
+        "auth",
+        "models",
+        "upgrade",
+        "uninstall",
+        "mcp",
+        "session",
+        "export",
+        "import",
+        "github",
+        "pr",
+        "stats",
+        "debug",
+        "agent",
+        "completion",
+        "db",
+        "plugin",
+    }
+    passthrough = any(a in ("--help", "-h", "--version", "-v") for a in args) or (args and args[0] in commands)
+    # A HomeAILab BAT may resolve the global shim again inside our worker.
+    # Keep its existing managed identity instead of spawning a second window.
+    passthrough = passthrough or bool(os.environ.get("OCDECK_BINDING"))
+    if not passthrough:
+        launch(args)
+        return 0
+    root = home()
+    install = read_json(root / "install.json")
+    if not isinstance(install, dict):
+        raise RuntimeError("Run scripts/Install.ps1 first")
+    spec = root / "launches" / (str(uuid.uuid4()) + ".json")
+    atomic_json(spec, {"cwd": os.getcwd(), "args": args, "executable": install["opencode"]})
+    try:
+        return subprocess.call(
+            [
+                "powershell.exe",
+                "-NoLogo",
+                "-NoProfile",
+                "-ExecutionPolicy",
+                "Bypass",
+                "-File",
+                str(Path(install["source"]) / "scripts" / "Run-OpenCode.ps1"),
+                "-LaunchFile",
+                str(spec),
+            ]
+        )
+    finally:
+        spec.unlink(missing_ok=True)
+
+
+def launch(args, cwd=None, executable=None):
+    if os.name != "nt":
+        raise RuntimeError("Managed launcher requires Windows; see docs/REMOTE-AND-WSL.md")
+    root = home()
+    install = read_json(root / "install.json")
+    if not isinstance(install, dict):
+        raise RuntimeError("Run scripts/Install.ps1 first")
+    if not install:
+        raise RuntimeError("Run scripts/Install.ps1 first")
+    executable = shutil.which(executable) if executable else install["opencode"]
+    if not executable:
+        raise RuntimeError("Launcher executable not found")
+    wt = shutil.which("wt.exe")
+    if not wt:
+        raise RuntimeError("Windows Terminal (wt.exe) is required for managed windows")
+    key = str(uuid.uuid4())
+    spec = root / "launches" / (key + ".json")
+    token = "OpenCode [" + key + "]"
+    atomic_json(
+        spec, {"id": key, "args": args, "cwd": cwd or os.getcwd(), "windowToken": token, "executable": executable}
+    )
+    subprocess.Popen(
+        [
+            wt,
+            "-w",
+            key,
+            "new-tab",
+            "--title",
+            token,
+            "--suppressApplicationTitle",
+            "--inheritEnvironment",
+            sys.executable,
+            "-m",
+            "ocdeck",
+            "worker",
+            str(spec),
+        ],
+        close_fds=True,
+    )
+
+
+def worker(spec_path):
+    root = home()
+    spec_path = Path(spec_path)
+    spec = read_json(spec_path)
+    if not isinstance(spec, dict):
+        raise ValueError("Invalid managed launch specification")
+    install = read_json(root / "install.json")
+    if not isinstance(install, dict):
+        raise RuntimeError("Run scripts/Install.ps1 first")
+    binding_path = spec_path.with_suffix(".binding.json")
+    reg = {
+        "id": spec["id"],
+        "process": identity(),
+        "windowToken": spec["windowToken"],
+        "label": Path(spec["cwd"]).name or "OpenCode",
+        "managed": True,
+    }
+    atomic_json(binding_path, reg)
+    env = dict(os.environ, OCDECK_HOME=str(root), OCDECK_BINDING=str(binding_path))
+    # Arguments are read from JSON by PowerShell, never interpolated into script text.
+    spec.setdefault("executable", install["opencode"])
+    atomic_json(spec_path, spec)
+    process = subprocess.Popen(
+        [
+            "powershell.exe",
+            "-NoLogo",
+            "-NoProfile",
+            "-ExecutionPolicy",
+            "Bypass",
+            "-File",
+            str(Path(install["source"]) / "scripts" / "Run-OpenCode.ps1"),
+            "-LaunchFile",
+            str(spec_path),
+        ],
+        cwd=spec["cwd"],
+        env=env,
+    )
+    try:
+        while process.poll() is None:
+            try:
+                request("POST", "/v1/register", reg)
+            except Exception:
+                pass  # OpenCode is independent of device availability.
+            time.sleep(0.5)
+        return process.returncode
+    finally:
+        try:
+            request("DELETE", "/v1/instances/" + reg["id"])
+        except Exception:
+            pass
+        for p in (spec_path, binding_path, Path(str(binding_path) + ".claim")):
+            p.unlink(missing_ok=True)
+
+
+def install_plugin(mode="server", config_dir=None):
+    root = home()
+    install = read_json(root / "install.json")
+    if not isinstance(install, dict):
+        raise RuntimeError("Run scripts/Install.ps1 first")
+    config = Path(
+        config_dir
+        or os.environ.get("OPENCODE_CONFIG_DIR")
+        or Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config")) / "opencode"
+    )
+    source = Path(install["source"]) / "plugins"
+    entry = config / "plugins" / "ocdeck.js"
+    marker = "// Managed by OpenCode Deck installer\n"
+    entry.parent.mkdir(parents=True, exist_ok=True)
+    if mode == "server":
+        if entry.exists() and not entry.read_text(encoding="utf-8").startswith(marker):
+            raise RuntimeError("Refusing to replace an unrelated ocdeck.js")
+        entry.write_text(
+            marker + "export { DeckBridge } from " + json.dumps((source / "server.mjs").as_uri()) + ";\n",
+            encoding="utf-8",
+        )
+    else:
+        # JSONC can contain comments; do not silently destroy a user's configuration.
+        if (config / "tui.jsonc").exists():
+            raise RuntimeError("tui.jsonc exists: follow docs to merge the TUI plugin entry manually")
+        tui = config / "tui.json"
+        try:
+            value = json.loads(tui.read_text(encoding="utf-8-sig")) if tui.exists() else {}
+        except ValueError:
+            raise RuntimeError("tui.json contains JSONC: merge the plugin entry manually")
+        uri = (source / "tui.mjs").as_uri()
+        plugins = value.setdefault("plugin", [])
+        if uri not in plugins:
+            plugins.append(uri)
+        if tui.exists():
+            shutil.copy2(tui, tui.with_suffix(".json.ocdeck-backup"))
+        atomic_json(tui, value)
+        if entry.exists() and entry.read_text(encoding="utf-8").startswith(marker):
+            entry.unlink()
+    install["pluginMode"], install["configDir"] = mode, str(config)
+    atomic_json(root / "install.json", install)
+    print(f"Installed {mode} adapter globally in {config}. Restart OpenCode instances.")

ocdeck/model.py

@@ -0,0 +1,177 @@
+"""Serialized registry. Color is a projection; button presses never mutate it."""
+
+import copy
+import threading
+import time
+import uuid
+from .security import scrub_text
+
+
+class Registry:
+    def __init__(self, probe, clock=time.monotonic, stale_after=10, slots=6, secrets=()):
+        self.probe, self.clock, self.stale_after = probe, clock, stale_after
+        self.secrets = secrets
+        if slots not in (6, 15, 32):
+            raise ValueError("slots must be 6, 15 or 32")
+        self.lock = threading.RLock()
+        self.records = {}
+        self.slots: list[str | None] = [None] * slots
+        self.generations = [0] * slots
+        self.epoch = str(uuid.uuid4())
+
+    def resize(self, count):
+        if count not in (6, 15, 32):
+            raise ValueError("slots must be 6, 15 or 32")
+        with self.lock:
+            if count == len(self.slots):
+                return
+            old_generations = self.generations
+            self.slots = [None] * count
+            self.generations = [(old_generations[i] if i < len(old_generations) else 0) + 1 for i in range(count)]
+            for i, record in enumerate(self.records.values()):
+                record["slot"] = i if i < count else None
+                if i < count:
+                    self.slots[i] = record["id"]
+
+    def upsert(self, data):
+        key = data.get("id", "")
+        if not isinstance(key, str) or not 1 <= len(key) <= 128:
+            raise ValueError("id must be 1..128 characters")
+        with self.lock:
+            record = self.records.get(key)
+            if record is None:
+                process = data.get("process")
+                if not isinstance(process, dict) or self.probe(process) is not True:
+                    raise ValueError("process identity is not live on this host")
+                slot = next((i for i, value in enumerate(self.slots) if value is None), None)
+                if slot is not None:
+                    self.generations[slot] += 1
+                    self.slots[slot] = key
+                record = {
+                    "id": key,
+                    "process": process,
+                    "slot": slot,
+                    "label": scrub_text(str(data.get("label", "OpenCode")), self.secrets)[:100],
+                    "harness": scrub_text(str(data.get("harness", "")), self.secrets)[:40],
+                    "windowToken": str(data.get("windowToken", ""))[:128],
+                    "seq": -1,
+                    "producer": None,
+                    "retired": [],
+                    "status": "unknown",
+                    "pending": 0,
+                    "lastState": 0,
+                    "lastSeen": self.clock(),
+                    "detail": "Connecting",
+                }
+                self.records[key] = record
+            elif data.get("process") != record["process"]:
+                raise ValueError("instance process identity cannot change")
+            record["lastSeen"] = self.clock()
+            return copy.deepcopy(record)
+
+    def snapshot(self, key, data):
+        status = data.get("status")
+        if status not in ("idle", "busy", "retry", "unknown"):
+            raise ValueError("invalid status")
+        seq, producer = data.get("seq"), data.get("producer")
+        if not isinstance(seq, int) or seq < 0 or not isinstance(producer, str) or not producer or len(producer) > 128:
+            raise ValueError("invalid sequence/producer")
+        pending = data.get("pending", 0)
+        if type(pending) is not int or not 0 <= pending <= 10000:
+            raise ValueError("invalid pending count")
+        requests = data.get("requestIds", [])
+        if (
+            not isinstance(requests, list)
+            or len(requests) > 10000
+            or any(
+                not isinstance(x, str) or len(x) != 64 or any(c not in "0123456789abcdef" for c in x) for x in requests
+            )
+        ):
+            raise ValueError("requestIds must contain SHA256 metadata identities")
+        waiting = data.get("inputNeeded", False)
+        known = data.get("pendingKnown", True)
+        if type(waiting) is not bool or type(known) is not bool:
+            raise ValueError("inputNeeded/pendingKnown must be boolean")
+        with self.lock:
+            r = self.records[key]
+            if producer in r["retired"]:
+                return False
+            if r["producer"] != producer:
+                if r["producer"]:
+                    r["retired"].append(r["producer"])
+                r["producer"], r["seq"] = producer, -1
+            if seq <= r["seq"]:
+                return False
+            r.update(
+                seq=seq,
+                status=status,
+                pending=pending,
+                inputNeeded=waiting,
+                pendingKnown=known,
+                requestIds=list(set(requests)),
+                detail=scrub_text(str(data.get("detail", "")), self.secrets)[:200],
+                lastState=self.clock(),
+                lastSeen=self.clock(),
+            )
+            return True
+
+    def remove(self, key):
+        with self.lock:
+            r = self.records.pop(key, None)
+            if r and r["slot"] is not None:
+                slot = r["slot"]
+                self.slots[slot] = None
+                self.generations[slot] += 1
+            # Overflow agents take a freed slot in registration order.
+            for candidate in self.records.values():
+                if candidate["slot"] is None and None in self.slots:
+                    slot = self.slots.index(None)
+                    self.generations[slot] += 1
+                    self.slots[slot], candidate["slot"] = candidate["id"], slot
+
+    def sweep(self):
+        with self.lock:
+            for key, record in list(self.records.items()):
+                if self.probe(record["process"]) is False:
+                    self.remove(key)
+
+    def view(self):
+        with self.lock:
+            result = []
+            for slot, key in enumerate(self.slots):
+                r = self.records.get(key)
+                state = "off"
+                if r:
+                    if self.clock() - r["lastState"] > self.stale_after or r["status"] == "unknown":
+                        state = "unknown"
+                    elif r["pending"] or r.get("inputNeeded"):
+                        state = "input"
+                    elif r["status"] in ("busy", "retry"):
+                        state = "running"
+                    else:
+                        state = "idle"
+                result.append(
+                    {
+                        "slot": slot,
+                        "generation": self.generations[slot],
+                        "id": key,
+                        "state": state,
+                        "label": r["label"] if r else "",
+                        "detail": r["detail"] if r else "",
+                        "harness": r["harness"] if r else "",
+                        "pending": r["pending"] if r and r.get("pendingKnown", True) else None,
+                        "requestIds": r.get("requestIds", []) if r else [],
+                    }
+                )
+            return result
+
+    def resolve(self, slot, generation, key):
+        with self.lock:
+            if type(slot) is not int or not 0 <= slot < len(self.slots):
+                return None
+            if self.slots[slot] != key or self.generations[slot] != generation:
+                return None
+            r = self.records.get(key)
+            if not r or self.probe(r["process"]) is not True:
+                return None
+            return copy.deepcopy(r)

ocdeck/observability.py

@@ -0,0 +1,57 @@
+"""Bounded JSON logs with request correlation and final-output redaction."""
+
+from contextvars import ContextVar
+import json
+import logging
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+from collections import deque
+from .security import scrub
+
+correlation = ContextVar("correlation", default="background")
+
+
+class JsonFormatter(logging.Formatter):
+    def __init__(self, secrets=()):
+        super().__init__()
+        self.secrets = secrets
+
+    def format(self, record):
+        value = {
+            "time": self.formatTime(record),
+            "level": record.levelname,
+            "logger": record.name,
+            "correlationId": correlation.get(),
+            "message": record.getMessage(),
+        }
+        if record.exc_info:
+            value["exception"] = self.formatException(record.exc_info)
+        return json.dumps(scrub(value, self.secrets), ensure_ascii=True)
+
+
+def configure(root):
+    root = Path(root)
+    try:
+        token = (root / "token").read_text().strip()
+    except OSError:
+        token = ""
+    handler = RotatingFileHandler(root / "broker.log", maxBytes=2_000_000, backupCount=3, encoding="utf-8")
+    handler.setFormatter(JsonFormatter((token,)))
+    logging.basicConfig(level=logging.INFO, handlers=[handler], force=True)
+
+
+def tail(root, count=100, errors_only=False):
+    count = max(0, min(2000, count))
+    rows = deque(maxlen=count)
+    try:
+        with (Path(root) / "broker.log").open(encoding="utf-8", errors="replace") as stream:
+            for line in stream:
+                if not errors_only or any(x in line for x in ('"WARNING"', '"ERROR"', '"CRITICAL"')):
+                    rows.append(line[:8192].rstrip())
+    except OSError:
+        pass
+    try:
+        token = (Path(root) / "token").read_text().strip()
+    except OSError:
+        token = ""
+    return scrub(list(rows), (token,))

ocdeck/runtime/plugins/core.mjs

@@ -0,0 +1,122 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export class Facts {
+  constructor() { this.sessions = new Map(); this.trusted = true; this.detail = ''; }
+  session(id) {
+    if (!this.sessions.has(id)) this.sessions.set(id, {status: 'idle', permissions: new Set(), questions: new Set()});
+    return this.sessions.get(id);
+  }
+  event(event) {
+    const p = event.properties || {};
+    const id = p.sessionID || p.info?.id;
+    if (!id) return;
+    const s = this.session(id);
+    switch (event.type) {
+      case 'session.status': s.status = p.status?.type || 'unknown'; break;
+      case 'session.idle': s.status = 'idle'; break;
+      case 'permission.asked': s.permissions.add(p.id); break;
+      case 'permission.replied': s.permissions.delete(p.requestID); break;
+      case 'question.asked': s.questions.add(p.id); break;
+      case 'question.replied': case 'question.rejected': s.questions.delete(p.requestID); break;
+      case 'session.deleted': this.sessions.delete(id); break;
+      case 'session.error': this.detail = 'Session error; inspect terminal'; break;
+    }
+  }
+  snapshot() {
+    let pending = 0, status = 'idle';
+    for (const s of this.sessions.values()) {
+      pending += s.permissions.size + s.questions.size;
+      if (s.status === 'unknown') status = 'unknown';
+      else if (status !== 'unknown' && ['busy', 'retry'].includes(s.status)) status = 'busy';
+    }
+    const requestIds = [];
+    for (const [session, s] of this.sessions) {
+      for (const kind of ['permissions','questions']) for (const id of s[kind]) {
+        if (typeof id === 'string') requestIds.push(crypto.createHash('sha256').update(JSON.stringify([session,kind,id])).digest('hex'));
+      }
+    }
+    return {status: this.trusted ? status : 'unknown', pending, detail: this.detail, pendingKnown:true, requestIds};
+  }
+}
+
+export class Bridge {
+  constructor({root, registration, readSnapshot, onError = () => {}}) {
+    this.root = root || process.env.OCDECK_HOME || path.join(os.homedir(), '.opencode-deck');
+    this.registration = registration;
+    this.readSnapshot = readSnapshot;
+    this.onError = onError;
+    this.producer = crypto.randomUUID(); this.seq = 0;
+    this.closed = false; this.busy = false; this.dirty = false; this.timer = null;
+  }
+  async call(method, route, body) {
+    const discovery = JSON.parse(await fs.readFile(path.join(this.root, 'discovery.json'), 'utf8'));
+    const token = (await fs.readFile(path.join(this.root, 'token'), 'utf8')).trim();
+    if (!Number.isInteger(discovery.port) || discovery.port < 1 || discovery.port > 65535) throw Error('Bad discovery port');
+    const response = await fetch(`http://127.0.0.1:${discovery.port}${route}`, {
+      method, headers: {Authorization: `Bearer ${token}`, 'Content-Type': 'application/json'},
+      body: body === undefined ? undefined : JSON.stringify(body), signal: AbortSignal.timeout(1200)
+    });
+    if (!response.ok) throw Error(`Broker HTTP ${response.status}`);
+    return response.json();
+  }
+  start() {
+    this.timer = setInterval(() => void this.flush(), 2000);
+    this.timer.unref?.();
+    void this.flush();
+  }
+  async flush() {
+    if (this.closed) return;
+    if (this.busy) { this.dirty = true; return; }
+    this.busy = true;
+    try {
+      await this.call('POST', '/v1/register', this.registration);
+      const value = await this.readSnapshot();
+      if (!this.closed) await this.call('PUT', `/v1/instances/${encodeURIComponent(this.registration.id)}`,
+        {...value, producer: this.producer, seq: ++this.seq});
+    } catch (e) { this.onError(String(e)); }
+    finally {
+      this.busy = false;
+      if (this.dirty && !this.closed) {
+        this.dirty = false;
+        setTimeout(() => void this.flush(), 0);
+      }
+    }
+  }
+  async close() {
+    this.closed = true; clearInterval(this.timer);
+    // For wrapper-managed instances the process supervisor owns removal.
+    if (!this.registration.managed) {
+      try { await this.call('DELETE', `/v1/instances/${encodeURIComponent(this.registration.id)}`); } catch {}
+    }
+  }
+}
+
+export async function registration() {
+  // Launcher writes identity using psutil's exact process creation timestamp.
+  const root = process.env.OCDECK_HOME || path.join(os.homedir(), '.opencode-deck');
+  if (process.env.OCDECK_BINDING) {
+    const r = JSON.parse(await fs.readFile(process.env.OCDECK_BINDING, 'utf8'));
+    // First OpenCode runtime claims this launch. Nested headless OpenCode jobs
+    // inherit environment variables but cannot claim the parent's button.
+    const claim = process.env.OCDECK_BINDING + '.claim';
+    try {
+      const f = await fs.open(claim, 'wx');
+      await f.writeFile(String(process.pid)); await f.close();
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      const owner = Number(await fs.readFile(claim, 'utf8'));
+      if (owner !== process.pid) return null;
+    }
+    return {...r, managed: true};
+  }
+  // Outside a managed launch, use the Python helper solely for exact PID identity.
+  const install = JSON.parse((await fs.readFile(path.join(root, 'install.json'), 'utf8')).replace(/^\uFEFF/, ''));
+  const {execFile} = await import('node:child_process');
+  const info = await new Promise((resolve, reject) => execFile(install.python,
+    ['-m', 'ocdeck', 'identity', String(process.pid)], {timeout: 2500, windowsHide: true},
+    (error, stdout) => error ? reject(error) : resolve(JSON.parse(stdout))));
+  return {id: crypto.randomUUID(), process: info, label: path.basename(process.cwd()) || 'OpenCode', windowToken: ''};
+}

ocdeck/runtime/plugins/harnesses/bridge.mjs

@@ -0,0 +1,52 @@
+// One persistent producer per managed launch, all descendant sessions share its slot.
+import fs from 'node:fs/promises';
+import http from 'node:http';
+import crypto from 'node:crypto';
+import {Bridge} from '../core.mjs';
+import {HookFacts, profiles} from './profiles.mjs';
+
+export async function serve({profile, registration, descriptor, root}) {
+  const facts = new HookFacts(profile);
+  const token = crypto.randomBytes(32).toString('hex');
+  const bridge = new Bridge({root, registration, readSnapshot:async () => {
+    try { await fs.access(descriptor + '.failed'); facts.broken = true; } catch {}
+    return facts.snapshot();
+  }});
+  const server = http.createServer(async (req, res) => {
+    const reply = code => { res.writeHead(code); res.end(); };
+    if (req.headers.origin || req.headers.authorization !== `Bearer ${token}`) return reply(403);
+    if (req.method !== 'POST' || req.url !== '/event') return reply(404);
+    try {
+      let raw = '', size = 0;
+      for await (const c of req) { size += c.length; if (size > 8192) return reply(413); raw += c; }
+      const e = JSON.parse(raw);
+      if (!e || Array.isArray(e) || typeof e.session !== 'string' || !e.session || e.session.length > 512 ||
+          !Object.hasOwn(profiles[profile].events, e.event)) return reply(400);
+      facts.event(e); reply(204); void bridge.flush();
+    } catch { reply(400); }
+  });
+  server.requestTimeout = 2000;
+  server.headersTimeout = 2000;
+  server.on('connection', socket => socket.setTimeout(2000, () => socket.destroy()));
+  await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve); });
+  try {
+    await fs.writeFile(descriptor + '.tmp', JSON.stringify({profile, port:server.address().port, token}), {mode:0o600});
+    await fs.rename(descriptor + '.tmp', descriptor);
+  } catch (error) { server.close(); throw error; }
+  bridge.start();
+  return {facts, bridge, close: async () => {
+    await bridge.close(); server.close(); server.closeAllConnections();
+    await fs.rm(descriptor, {force:true}); await fs.rm(descriptor + '.failed', {force:true});
+  }};
+}
+
+if (process.argv[2] === '--worker') {
+  const [profile, binding, descriptor] = process.argv.slice(3);
+  const registration = JSON.parse(await fs.readFile(binding, 'utf8'));
+  const service = await serve({profile, registration, descriptor});
+  let closing = false;
+  const close = async () => { if (closing) return; closing = true; await service.close(); process.exit(0); };
+  // Parent owns stdin. EOF also cleans up after an abrupt supervisor exit.
+  process.stdin.resume(); process.stdin.on('end', close);
+  process.on('SIGTERM', close); process.on('SIGINT', close);
+}

ocdeck/runtime/plugins/harnesses/hook.mjs

@@ -0,0 +1,38 @@
+// Short-lived observer: no approval decisions, no diagnostics on stdout, always exit 0.
+import fs from 'node:fs/promises';
+import {writeFileSync} from 'node:fs';
+import {normalize} from './profiles.mjs';
+const [profile, event] = process.argv.slice(2);
+const descriptor = process.env.AGENTDECK_HOOK_BINDING;
+const timer = setTimeout(() => {
+  if (descriptor) { try { writeFileSync(descriptor + '.failed', '1', {mode:0o600}); } catch {} }
+  if (profile === 'gemini') process.stdout.write('{}\n');
+  process.exit(0);
+}, 1800);
+try {
+  if (descriptor) {
+    const d = JSON.parse(await fs.readFile(descriptor, 'utf8'));
+    if (d.profile === profile && Number.isInteger(d.port) && d.port > 0 && d.port <= 65535) {
+      process.stdin.setEncoding('utf8');
+      let input = '', size = 0;
+      for await (const chunk of process.stdin) {
+        size += Buffer.byteLength(chunk);
+        if (size > 4 * 1024 * 1024) throw Error('Oversized hook input');
+        input += chunk;
+      }
+      const value = normalize(profile, event, JSON.parse(input));
+      if (!value) throw Error('Invalid hook input');
+      const response = await fetch(`http://127.0.0.1:${d.port}/event`, {method:'POST',
+        headers:{Authorization:`Bearer ${d.token}`, 'Content-Type':'application/json'},
+        body:JSON.stringify(value), signal:AbortSignal.timeout(800)});
+      if (!response.ok) throw Error('Delivery failed');
+    }
+  }
+} catch {
+  // Persist only a failure marker. A later heartbeat must not make lost events look reliable.
+  if (descriptor) { try { await fs.writeFile(descriptor + '.failed', '1', {mode:0o600}); } catch {} }
+} finally {
+  clearTimeout(timer);
+  if (profile === 'gemini') process.stdout.write('{}\n');
+  process.exit(0);
+}