@jc_stack/ez-agents 0.1.0-beta.12

package/bin/ezenciel-agents-source.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const require = createRequire(import.meta.url)
+const tsx = require.resolve('tsx')
+const entry = join(here, '..', 'src', 'source-cli.ts')
+const forwarded = process.argv.slice(2).filter((arg) => arg !== '--')
+const child = spawn(process.execPath, ['--import', tsx, entry, ...forwarded], { stdio: 'inherit' })
+child.on('exit', (code, signal) => {
+  if (signal) process.kill(process.pid, signal)
+  process.exit(code ?? 1)
+})

package/bin/ezenciel-agents-tools.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from '../src/plugins/manager.mjs';
+main(process.argv.slice(2)).catch(error => { console.error(JSON.stringify({ok:false,error:error.message})); process.exitCode=1; });

package/bin/ezenciel-agents.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const require = createRequire(import.meta.url)
+const entry = join(here, '..', 'src', 'index.ts')
+const forwarded = process.argv.slice(2).filter((arg) => arg !== '--')
+if (forwarded.length === 1 && forwarded[0] === '--version') {
+  console.log(require('../package.json').version)
+  process.exit(0)
+}
+if (forwarded.length === 1 && ['--help', '-h'].includes(forwarded[0])) {
+  console.log('Usage: ezenciel-agents [start]\nStarts the Docker relay bound by EZ_DEPLOYMENT_DIR/docker.env.\nInitialize the mind: ezenciel-agents-setup init\nSetup instructions: docs/setup.md in the installed package.')
+  process.exit(0)
+}
+if (forwarded.length && (forwarded.length !== 1 || forwarded[0] !== 'start')) {
+  console.error('Usage: ezenciel-agents [start] (or --help)')
+  process.exit(1)
+}
+if (!existsSync('/.dockerenv') && process.env.EZ_DEVELOPMENT !== '1') {
+  const docker = spawn(join(here, 'ezenciel-agents-docker'), ['up', '-d', '--wait', 'relay'], { stdio: 'inherit' })
+  docker.on('error', () => { console.error('Docker launcher could not start'); process.exitCode = 1 })
+  docker.on('exit', code => { process.exitCode = code ?? 1 })
+} else {
+const tsx = require.resolve('tsx')
+const args = existsSync('.env') ? ['--env-file=.env', entry] : [entry]
+const child = spawn(process.execPath, ['--import', tsx, ...args, ...forwarded], { stdio: 'inherit' })
+child.on('exit', (code, signal) => {
+  if (signal) process.kill(process.pid, signal)
+  process.exit(code ?? 1)
+})
+
+}

package/compose.whatsapp.yaml

@@ -0,0 +1,12 @@
+services:
+  relay:
+    volumes:
+      - whatsapp-ipc:/plugins/whatsapp:ro
+      - whatsapp-client:/opt/plugins/whatsapp:ro
+volumes:
+  whatsapp-ipc:
+    external: true
+    name: ${EZ_WHATSAPP_IPC_VOLUME:?Set the registered WhatsApp IPC volume}
+  whatsapp-client:
+    external: true
+    name: ${EZ_WHATSAPP_CLIENT_VOLUME:?Set the registered WhatsApp client volume}

package/compose.yaml

@@ -0,0 +1,40 @@
+services:
+  relay:
+    image: ${EZ_RELAY_IMAGE:-ezenciel-agents:local}
+    build:
+      context: .
+      target: runtime
+    init: true
+    restart: unless-stopped
+    stop_grace_period: 30s
+    cap_drop: [ALL]
+    cap_add: [CHOWN, DAC_OVERRIDE, FOWNER, SETUID, SETGID, SETPCAP]
+    environment:
+      EZ_AGENT_PURPOSE_FILE: /run/agent-purpose.md
+      EZ_EXECUTOR_TRANSPORT: host
+      EZ_AGENT_WORKSPACE: ${EZ_AGENT_WORKSPACE:?Set this agent workspace}
+      EZ_CONTROL_DIR: ${EZ_CONTROL_DIR:?Set this agent control directory}
+      EZ_EXECUTOR_CLI: ${EZ_EXECUTOR_CLI:?Set the host installation CLI}
+      EZ_EXECUTOR_TIMEOUT_SECONDS: ${EZ_EXECUTOR_TIMEOUT_SECONDS:-300}
+    secrets: [relay_env]
+    configs:
+      - source: agent_purpose
+        target: /run/agent-purpose.md
+    volumes:
+      - ${EZ_AGENT_WORKSPACE}:/workspace
+      - ${EZ_AGENT_WORKSPACE}:${EZ_AGENT_WORKSPACE}
+      - ${EZ_CONTROL_DIR}:/state/control
+      - ${EZ_CONTROL_DIR}:${EZ_CONTROL_DIR}
+    tmpfs: [/tmp]
+    healthcheck:
+      test: [CMD, node, /app/docker/healthcheck.mjs]
+      interval: 10s
+      timeout: 5s
+      start_period: 30s
+      retries: 3
+configs:
+  agent_purpose:
+    file: ${EZ_AGENT_PURPOSE_FILE:-./templates/agent/SOUL.md}
+secrets:
+  relay_env:
+    file: ${EZ_RELAY_ENV_FILE:?Set EZ_RELAY_ENV_FILE to the private relay env file}

package/default-plugins.json

@@ -0,0 +1 @@
+{}

package/docker/entrypoint.sh

@@ -0,0 +1,15 @@
+#!/bin/sh -p
+set -eu
+umask 077
+if [ "$(id -u)" = 0 ]; then
+  mkdir -p /state/control /state/home /workspace /run/secrets
+  chmod 700 /run/secrets
+  chown 1000:1000 /state/control /state/home /workspace
+  if [ -f /run/secrets/relay_env ]; then exec 3</run/secrets/relay_env; else exec 3</dev/null; fi
+  exec setpriv --ruid=1001 --euid=1000 --regid=1000 --clear-groups --bounding-set=-all --no-new-privs /app/docker/entrypoint.sh "$@"
+fi
+case "${1:-start}" in
+  start|smoke|exec|setup)
+    exec flock --no-fork -n -E 73 /state/control/relay.lock node --import /app/node_modules/tsx/dist/loader.mjs /app/docker/run.ts "$@" ;;
+  *) exec node --import /app/node_modules/tsx/dist/loader.mjs /app/docker/run.ts "$@" ;;
+esac

package/docker/healthcheck.mjs

@@ -0,0 +1,8 @@
+import { readFileSync } from 'node:fs';
+const value = JSON.parse(readFileSync('/state/control/heartbeat.json', 'utf8'));
+if (!value.polling || Date.now() - value.at > 20000) process.exit(1);
+
+if (process.env.EZ_EXECUTOR_TRANSPORT === 'host') {
+  const host = JSON.parse(readFileSync(process.env.EZ_CONTROL_DIR + '/host-executor/heartbeat.json', 'utf8'));
+  if (Date.now() - host.at > 15000) process.exit(1);
+}

package/docker/plugin-smoke.mjs

@@ -0,0 +1,48 @@
+// Explicit opt-in: node docker/plugin-smoke.mjs. Only synthetic provider data.
+import assert from 'node:assert/strict';
+import * as fs from 'node:fs/promises';
+import {tmpdir} from 'node:os';
+import path from 'node:path';
+import {execFile,spawn} from 'node:child_process';
+import {promisify} from 'node:util';
+import {snapshot,init} from '../src/plugins/manager.mjs';
+const exec=promisify(execFile),bin=new URL('../bin/ezenciel-agents-tools.mjs',import.meta.url).pathname;
+const root=await fs.mkdtemp(path.join(tmpdir(),'ez-plugin-docker-'));
+const source=path.join(root,'source'),home=path.join(root,'tools'),mind=path.join(root,'mind');
+const whatsappSource=path.resolve(process.env.EZ_WHATSAPP_SOURCE || new URL('../../ez_whatsapp',import.meta.url).pathname);
+let record;
+const call=async(...args)=>(await exec(process.execPath,[bin,'--home',home,...args],{maxBuffer:4*1024*1024})).stdout;
+try {
+ await fs.mkdir(source);await fs.mkdir(mind);
+ const original=await snapshot(whatsappSource);
+ for(const [name,f]of original.files) {await fs.mkdir(path.dirname(path.join(source,name)),{recursive:true});await fs.writeFile(path.join(source,name),f.data,{mode:f.mode});}
+ await fs.copyFile(path.join(whatsappSource,'docker/fixture.mjs'),path.join(source,'src/transport.mjs'));
+ const m=JSON.parse(await fs.readFile(path.join(source,'ez-plugin.json')));m.commands.probe={executable:'bin/ez-whatsapp.mjs',args:[]};await fs.writeFile(path.join(source,'ez-plugin.json'),JSON.stringify(m));
+ const d=JSON.parse(await fs.readFile(path.join(source,'ez-deployment.json')));d.commands.probe={service:'whatsapp',argv:['node','-e',"console.log('ready');setInterval(()=>{},1000)"]};await fs.writeFile(path.join(source,'ez-deployment.json'),JSON.stringify(d));
+ const p=await snapshot(source);await init(home,mind);
+ console.log('Installing isolated WhatsApp snapshot with synthetic transport…');
+ const installed=JSON.parse(await call('plugins','install','whatsapp','--source',source,'--revision',p.revision));assert.equal(installed.started,false);
+ record=JSON.parse(await fs.readFile(path.join(home,'registry.json'))).plugins.whatsapp;
+ await call('plugins','start','whatsapp');
+ assert.equal(JSON.parse(await call('whatsapp','doctor','--json')).data.connected,true);
+ const first=JSON.parse(await call('whatsapp','inbox')).data;
+ assert.equal(first.messages.length,1);
+ const text=path.join(await fs.realpath(mind),'literal $(no execution) message.txt');await fs.writeFile(text,'Synthetic registry test');
+ const send=JSON.parse(await call('whatsapp','send','--to','+15551230000','--text-file',text,'--idempotency-key','registry:qa')).data;
+ assert.equal(send.state,'accepted');
+ const duplicate=JSON.parse(await call('whatsapp','send','--to','+15551230000','--text-file',text,'--idempotency-key','registry:qa')).data;assert.equal(duplicate.providerMessageId,send.providerMessageId);
+ await call('plugins','stop','whatsapp');await call('plugins','start','whatsapp');
+ assert.equal(JSON.parse(await call('whatsapp','operation','--idempotency-key','registry:qa')).data.providerMessageId,send.providerMessageId);
+ assert.equal(JSON.parse(await call('whatsapp','inbox')).data.nextCursor,first.nextCursor);
+ const probe=spawn(process.execPath,[bin,'--home',home,'probe'],{stdio:['ignore','pipe','pipe']});
+ await new Promise((resolve,reject)=>{const timeout=setTimeout(()=>reject(Error('Probe never started')),20000);probe.stdout.once('data',()=>{clearTimeout(timeout);resolve();});});
+ const closed=new Promise(resolve=>probe.once('close',resolve));probe.kill('SIGTERM');assert.equal(await closed,130);
+ const clients=(await exec('docker',['ps','-a','--filter',`name=${record.project}-call-`,'--format','{{.Names}}'])).stdout.trim();assert.equal(clients,'');
+ assert.equal(JSON.parse(await call('whatsapp','doctor')).data.connected,true);
+ await call('plugins','uninstall','whatsapp');
+ const volumes=(await exec('docker',['volume','ls','--filter',`label=com.docker.compose.project=${record.project}`,'--format','{{.Name}}'])).stdout.trim();assert(volumes);
+ console.log('PASS: install without startup; registered CLI; synthetic account/read/send; literal file path; idempotency; stop/start persistence; data-preserving uninstall. No real provider calls.');
+} catch(error) { if(record)console.error((await exec('docker',['compose','-p',record.project,'-f',record.compose,'logs','--tail','30']).catch(()=>({stdout:''}))).stdout);throw error; } finally {
+ if(record){await exec('docker',['compose','-p',record.project,'-f',record.compose,'down','--volumes']).catch(()=>{});await exec('docker',['image','rm',`${record.project}-whatsapp:${record.revision.slice(7,23)}`]).catch(()=>{});}
+ await fs.rm(root,{recursive:true,force:true});
+}

package/docker/pnpm-lock.yaml

@@ -0,0 +1,415 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .:
+    dependencies:
+      grammy:
+        specifier: ^1.39.3
+        version: 1.46.0
+      tsx:
+        specifier: ^4.21.0
+        version: 4.23.13
+    devDependencies:
+      '@types/node':
+        specifier: ^24.10.1
+        version: 24.13.3
+      typescript:
+        specifier: ^5.9.3
+        version: 5.9.3
+
+packages:
+
+  '@esbuild/aix-ppc64@0.28.2':
+    resolution: {integrity: sha512-XExcO+dvLKvVtNTibSTBej1NCAbaGhWn9Ww1ZPx80qsahhPFe/8jgWP0IchNe0F3HwkU7n8ejhH8bjonqht8mQ==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [aix]
+
+  '@esbuild/android-arm64@0.28.2':
+    resolution: {integrity: sha512-5YfKeeI8qWfBZIX+u2xZC3Zlb3Os/gLS2sbEKM+I4ZOcsWmHS2WLysCcQZDAFRslDUU5Oiq44gf6PYN1vGwG5A==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [android]
+
+  '@esbuild/android-arm@0.28.2':
+    resolution: {integrity: sha512-kXXoiPVVGQcnIYGOeaovwOURpniDBpSq4A03qkQ+BMQqtGG6HYap3xne9C1O1yo4TR3qxlCX5IqqmX6fFo2Lqg==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [android]
+
+  '@esbuild/android-x64@0.28.2':
+    resolution: {integrity: sha512-O387ite7SzUyCcy3JQX4P4bLtEA7bLLkx+esve5JHnyYfNTxcVpXZo9jhdB0lTKN44gztELTdU7nS8Nr16Fs1Q==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [android]
+
+  '@esbuild/darwin-arm64@0.28.2':
+    resolution: {integrity: sha512-n4KqkOQrraxHJcgjM1RvwbigfQKIKJVpM7xp+KsxiyUSrRdIXnt73VhrPAx0fV44hgfmIVKjxMN9J1t5jySVkw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@esbuild/darwin-x64@0.28.2':
+    resolution: {integrity: sha512-uq6suIWYP37qzGddBKPw5QEQPi6HiLGsO7UmkpfyaYNQ3D+rN6w6WfwH+nuqcGXWvawGwxOEroO4YGnFh95azw==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@esbuild/freebsd-arm64@0.28.2':
+    resolution: {integrity: sha512-n+I0BTSRIoy+d6RPKnEVwql5UwBJolytvY4mAOIEJorKlqgPII8ix6slVVrfZ5Tnj7glIZvloylbB/EJPMWEXw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@esbuild/freebsd-x64@0.28.2':
+    resolution: {integrity: sha512-78XJTJkvPs0kz2w61301PJjXl4g7q3JqiYMZ/M/yVI73EHBrCRTgkhu9oqG7vPqq+a/yadEW8aD+agKlk5xrmg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@esbuild/linux-arm64@0.28.2':
+    resolution: {integrity: sha512-pW4AC0P3it8c7do9MVM4p51FzHzdM/TZrerurgRcHJ2WTa1VQ1CIq18xncfpBJw4ojkiZZrKW2yIBWBP92j6Ug==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@esbuild/linux-arm@0.28.2':
+    resolution: {integrity: sha512-XlDnu2q5yoqems+xay6wSAcg9DDD7K9RLKZEBOMZm3ckNpJBvOX20tSfby8KfrrhINDyv9V2YVZKY/SpoGJI8w==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [linux]
+
+  '@esbuild/linux-ia32@0.28.2':
+    resolution: {integrity: sha512-CYbnj78HsIeA+DhgUKgFCfvNsTHFhMMrinUrMZpDXJXKN8T3XViTZ/+wtHeVxEWY8ewSzTFN+nRmSwO2tZaLUQ==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [linux]
+
+  '@esbuild/linux-loong64@0.28.2':
+    resolution: {integrity: sha512-buwkd8nsph4R+ajRvw0qM5Hja/TXQow3ptzWO2EbG/cqcIkHloRrdlBtQlshyYGTNFvfkfJ5tpPLVkY4DtsPfQ==}
+    engines: {node: '>=18'}
+    cpu: [loong64]
+    os: [linux]
+
+  '@esbuild/linux-mips64el@0.28.2':
+    resolution: {integrity: sha512-ZVykbDyk7519VwiNb9Lcj9m8XM6v5V9uKPvrEMkkEedVewf+0itkhahp4HDpgERXhwLRpWFypsGbG/J8s0QjJA==}
+    engines: {node: '>=18'}
+    cpu: [mips64el]
+    os: [linux]
+
+  '@esbuild/linux-ppc64@0.28.2':
+    resolution: {integrity: sha512-CAXl+Dtd9UUuJd8pKKdwh6MLm3MUMiqMPmhZ3tTSXPqfyQ3vDl6R5hZdZ/kYojK4ofXtdfSv1tFq8XzWx3heNQ==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@esbuild/linux-riscv64@0.28.2':
+    resolution: {integrity: sha512-GeXCej4IQtU1B+QlDV8W/RRvbzI3O/Stss+/bCXv4lZls5WGRtu2a+3JkA3i4qIUlMXpcHebWpF8AkJhATowuA==}
+    engines: {node: '>=18'}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@esbuild/linux-s390x@0.28.2':
+    resolution: {integrity: sha512-3H1weTYZPxt/WOhByszQZybS9w5lKzUn1FDMsgEChbHWQwHYQQRfBxgCcZvPhjHfKyJjIievvMmEUawJrdY9Dg==}
+    engines: {node: '>=18'}
+    cpu: [s390x]
+    os: [linux]
+
+  '@esbuild/linux-x64@0.28.2':
+    resolution: {integrity: sha512-4xTZr1FUmSoQW4XIWmit3tzQrUTZM+N3P0XV8xROKYF50XfI7xeO90+1bZvNwxIufQ9hDQVRJH5YhgPVF8A/HQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [linux]
+
+  '@esbuild/netbsd-arm64@0.28.2':
+    resolution: {integrity: sha512-sSATRjPeDBg3pdgHoQfoYBob11Kk1FGa9lui5RIHZCoCkJa9QKlvl3/vKz2usCmYYjs7ymJR/2Nnsqe+Hjt5nw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [netbsd]
+
+  '@esbuild/netbsd-x64@0.28.2':
+    resolution: {integrity: sha512-lqnzCV+mM0gIADaKihiCg6ifgfU2L3h5E33rNQBN1Y4MaVGnzryzmvvf7UHxprpQdE8hpqLolJ9Rl+SkIRDpyw==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [netbsd]
+
+  '@esbuild/openbsd-arm64@0.28.2':
+    resolution: {integrity: sha512-AL2qJILH7lNjrDmCQDvdxMfAUIv8KMNZOvrwAQ8i8//ntL9FflhOyMJ8OZSMBb8/AWXe3/5v5S20y3zCoZWKoQ==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openbsd]
+
+  '@esbuild/openbsd-x64@0.28.2':
+    resolution: {integrity: sha512-QtiuPytchRyC4rwUKhexJdQKvDuZ6hWloi3igqPQNUJCS1/v9EiO3UTOXR6A3FoMo4fnAKbWJdqaIwhOzh8qEw==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@esbuild/openharmony-arm64@0.28.2':
+    resolution: {integrity: sha512-WkhYDmpTjLvGlScA1rwjRUmhl4k8oXR3cIbtqWmELgU/dFeHHlEllxDvdWcNJV9rbzCexB5vz8gtNewWLgCT7Q==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@esbuild/sunos-x64@0.28.2':
+    resolution: {integrity: sha512-GPMSkTOtMnv2U2F8gxe4Io6qmVs+YKyp832Etqqxr0hFngmXQ3rzwytelm3GIn7T4VviRUlf3sOgBOiTdvaf7g==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [sunos]
+
+  '@esbuild/win32-arm64@0.28.2':
+    resolution: {integrity: sha512-PIhhEkE9uPBleRBrQEJpUn7MBnibZzbGzYWPmY3x+YoVg/95zbjB4CxPPOQ8l5tYYM4mMaCthF8/1DIfBQQyWQ==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@esbuild/win32-ia32@0.28.2':
+    resolution: {integrity: sha512-YmJbfTlvU7Sdn9BB+4PRES4oB6pxgS37MAONj+hBr/cpXS1aBPKXxNnDbu+QCWPj0o9dgyxeq79g6c5P8KeuYA==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [win32]
+
+  '@esbuild/win32-x64@0.28.2':
+    resolution: {integrity: sha512-5ebpxr3nWMzrL/rnUI755Jkuee0bHL/Gq0WTF9lvcpv73wAp5eu8MfBUgWK9bhWvZjj7yX8etf/8tI8Ney695g==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [win32]
+
+  '@grammyjs/types@5.0.0':
+    resolution: {integrity: sha512-iq1Qrq1iPKkB8yAa0qSuIURMZOCuqTY5pWy5gHpCeL1oQ+GPadGhw/cDTVE8waJwuCzacUzuIjRv1sESvk7u7A==}
+
+  '@types/node@24.13.3':
+    resolution: {integrity: sha512-Dh8vAsV36ig5wa9OX4pXvMc9D3Veibfw2wix0CUwYODLD8nkj9UsLjASr49nPg+2eKzxhBV+v7L8pXvT4e639Q==}
+
+  abort-controller@3.0.0:
+    resolution: {integrity: sha512-h8lQ8tacZYnR3vNQTgibj+tODHI5/+l06Au2Pcriv/Gmet0eaj4TwWH41sO9wnHDiQsEj19q0drzdWdeAHtweg==}
+    engines: {node: '>=6.5'}
+
+  debug@4.4.3:
+    resolution: {integrity: sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==}
+    engines: {node: '>=6.0'}
+    peerDependencies:
+      supports-color: '*'
+    peerDependenciesMeta:
+      supports-color:
+        optional: true
+
+  esbuild@0.28.2:
+    resolution: {integrity: sha512-HKVLS8dvII+xoKW9kmqxbRKrnWEXfJJr/FZhhJmiqIB0e053QNYFqOBouTMO/k5sID4MvCiUCvv8b9M4h32wIA==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  event-target-shim@5.0.1:
+    resolution: {integrity: sha512-i/2XbnSz/uxRCU6+NdVJgKWDTM427+MqYbkQzD321DuCQJUqOuJKIA0IM2+W2xtYHdKOmZ4dR6fExsd4SXL+WQ==}
+    engines: {node: '>=6'}
+
+  fsevents@2.3.3:
+    resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
+  grammy@1.46.0:
+    resolution: {integrity: sha512-/8Qw+iisrUdOMk+p2mjEHouMm/BBdBEN1DHh16wiTpRUZkxDG3PxexdjCvR+wvK3LWPdrEvnQbdrwpU954sPhg==}
+    engines: {node: ^12.20.0 || >=14.13.1}
+
+  ms@2.1.3:
+    resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==}
+
+  node-fetch@2.7.0:
+    resolution: {integrity: sha512-c4FRfUm/dbcWZ7U+1Wq0AwCyFL+3nt2bEw05wfxSz+DWpWsitgmSgYmy2dQdWyKC1694ELPqMs/YzUSNozLt8A==}
+    engines: {node: 4.x || >=6.0.0}
+    peerDependencies:
+      encoding: ^0.1.0
+    peerDependenciesMeta:
+      encoding:
+        optional: true
+
+  tr46@0.0.3:
+    resolution: {integrity: sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==}
+
+  tsx@4.23.13:
+    resolution: {integrity: sha512-BL5MGkRln6aDYhb0xbQlEAGw743BaZYWdbWtdJOBriYJboKgUUYCadFp2/FpBBZquBC/ezNBn7wMMPx7FDZUDw==}
+    engines: {node: '>=18.0.0'}
+    hasBin: true
+
+  typescript@5.9.3:
+    resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==}
+    engines: {node: '>=14.17'}
+    hasBin: true
+
+  undici-types@7.18.2:
+    resolution: {integrity: sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w==}
+
+  webidl-conversions@3.0.1:
+    resolution: {integrity: sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ==}
+
+  whatwg-url@5.0.0:
+    resolution: {integrity: sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==}
+
+snapshots:
+
+  '@esbuild/aix-ppc64@0.28.2':
+    optional: true
+
+  '@esbuild/android-arm64@0.28.2':
+    optional: true
+
+  '@esbuild/android-arm@0.28.2':
+    optional: true
+
+  '@esbuild/android-x64@0.28.2':
+    optional: true
+
+  '@esbuild/darwin-arm64@0.28.2':
+    optional: true
+
+  '@esbuild/darwin-x64@0.28.2':
+    optional: true
+
+  '@esbuild/freebsd-arm64@0.28.2':
+    optional: true
+
+  '@esbuild/freebsd-x64@0.28.2':
+    optional: true
+
+  '@esbuild/linux-arm64@0.28.2':
+    optional: true
+
+  '@esbuild/linux-arm@0.28.2':
+    optional: true
+
+  '@esbuild/linux-ia32@0.28.2':
+    optional: true
+
+  '@esbuild/linux-loong64@0.28.2':
+    optional: true
+
+  '@esbuild/linux-mips64el@0.28.2':
+    optional: true
+
+  '@esbuild/linux-ppc64@0.28.2':
+    optional: true
+
+  '@esbuild/linux-riscv64@0.28.2':
+    optional: true
+
+  '@esbuild/linux-s390x@0.28.2':
+    optional: true
+
+  '@esbuild/linux-x64@0.28.2':
+    optional: true
+
+  '@esbuild/netbsd-arm64@0.28.2':
+    optional: true
+
+  '@esbuild/netbsd-x64@0.28.2':
+    optional: true
+
+  '@esbuild/openbsd-arm64@0.28.2':
+    optional: true
+
+  '@esbuild/openbsd-x64@0.28.2':
+    optional: true
+
+  '@esbuild/openharmony-arm64@0.28.2':
+    optional: true
+
+  '@esbuild/sunos-x64@0.28.2':
+    optional: true
+
+  '@esbuild/win32-arm64@0.28.2':
+    optional: true
+
+  '@esbuild/win32-ia32@0.28.2':
+    optional: true
+
+  '@esbuild/win32-x64@0.28.2':
+    optional: true
+
+  '@grammyjs/types@5.0.0': {}
+
+  '@types/node@24.13.3':
+    dependencies:
+      undici-types: 7.18.2
+
+  abort-controller@3.0.0:
+    dependencies:
+      event-target-shim: 5.0.1
+
+  debug@4.4.3:
+    dependencies:
+      ms: 2.1.3
+
+  esbuild@0.28.2:
+    optionalDependencies:
+      '@esbuild/aix-ppc64': 0.28.2
+      '@esbuild/android-arm': 0.28.2
+      '@esbuild/android-arm64': 0.28.2
+      '@esbuild/android-x64': 0.28.2
+      '@esbuild/darwin-arm64': 0.28.2
+      '@esbuild/darwin-x64': 0.28.2
+      '@esbuild/freebsd-arm64': 0.28.2
+      '@esbuild/freebsd-x64': 0.28.2
+      '@esbuild/linux-arm': 0.28.2
+      '@esbuild/linux-arm64': 0.28.2
+      '@esbuild/linux-ia32': 0.28.2
+      '@esbuild/linux-loong64': 0.28.2
+      '@esbuild/linux-mips64el': 0.28.2
+      '@esbuild/linux-ppc64': 0.28.2
+      '@esbuild/linux-riscv64': 0.28.2
+      '@esbuild/linux-s390x': 0.28.2
+      '@esbuild/linux-x64': 0.28.2
+      '@esbuild/netbsd-arm64': 0.28.2
+      '@esbuild/netbsd-x64': 0.28.2
+      '@esbuild/openbsd-arm64': 0.28.2
+      '@esbuild/openbsd-x64': 0.28.2
+      '@esbuild/openharmony-arm64': 0.28.2
+      '@esbuild/sunos-x64': 0.28.2
+      '@esbuild/win32-arm64': 0.28.2
+      '@esbuild/win32-ia32': 0.28.2
+      '@esbuild/win32-x64': 0.28.2
+
+  event-target-shim@5.0.1: {}
+
+  fsevents@2.3.3:
+    optional: true
+
+  grammy@1.46.0:
+    dependencies:
+      '@grammyjs/types': 5.0.0
+      abort-controller: 3.0.0
+      debug: 4.4.3
+      node-fetch: 2.7.0
+    transitivePeerDependencies:
+      - encoding
+      - supports-color
+
+  ms@2.1.3: {}
+
+  node-fetch@2.7.0:
+    dependencies:
+      whatwg-url: 5.0.0
+
+  tr46@0.0.3: {}
+
+  tsx@4.23.13:
+    dependencies:
+      esbuild: 0.28.2
+    optionalDependencies:
+      fsevents: 2.3.3
+
+  typescript@5.9.3: {}
+
+  undici-types@7.18.2: {}
+
+  webidl-conversions@3.0.1: {}
+
+  whatwg-url@5.0.0:
+    dependencies:
+      tr46: 0.0.3
+      webidl-conversions: 3.0.1

package/docker/recovery.ts

@@ -0,0 +1,11 @@
+import { RunStore } from '../src/runs.js'
+
+// Called only after the deployment's kernel writer lock is held. No worker
+// from a previous container can still own this deployment; PIDs may be reused.
+export const recoverInterruptedRuns = async (controlDir: string) => {
+  const store = new RunStore(controlDir)
+  for (const run of await store.list()) {
+    if (run.status === 'running')
+      await store.patch(run.id, { status: 'failed', endedAt: new Date().toISOString() })
+  }
+}

package/docker/run.ts

@@ -0,0 +1,52 @@
+import { readFileSync, closeSync } from 'node:fs'
+import { spawn } from 'node:child_process'
+import { executorEnvironment, executorInvocation } from '../src/executor.js'
+import { parseEnv } from 'node:util'
+import { writeFile, rm } from 'node:fs/promises'
+import { loadConfig } from '../src/config.js'
+import { recoverInterruptedRuns } from './recovery.js'
+import { createRelay } from '../src/index.js'
+import { packageVersion } from '../src/version.js'
+
+// Provider errors can contain credential-bearing URLs; never dump error causes.
+process.on('uncaughtException', (error) => {
+  console.error(error.name + ': ' + error.message.replace(/bot\d+:[A-Za-z0-9_-]+/g, 'bot[redacted]'))
+  process.exit(1)
+})
+
+// Read and close the root-opened descriptor before any executor can start.
+// Secrets never enter the initial process environment or a readable mount.
+let privateEnv: NodeJS.ProcessEnv = {}
+try { privateEnv = parseEnv(readFileSync(3, 'utf8')) } catch (error) {
+  if ((error as NodeJS.ErrnoException).code !== 'EINVAL' && (error as NodeJS.ErrnoException).code !== 'EBADF') throw error
+} finally { try { closeSync(3) } catch {} }
+for (const [key, value] of Object.entries(privateEnv)) {
+  if (value !== undefined && ['TELEGRAM_BOT_TOKEN', 'GEMINI_API_KEY', 'OPENAI_API_KEY'].includes(key)) process.env[key] = value
+}
+privateEnv = {}
+const [command = 'start', ...args] = process.argv.slice(2)
+process.argv = [process.argv[0], '', ...args]
+if (['start', 'smoke'].includes(command)) await recoverInterruptedRuns(loadConfig().controlDir)
+if (command === 'start') {
+  const relay = createRelay(loadConfig())
+  const heartbeat = '/state/control/heartbeat.json'
+  await rm(heartbeat, { force: true })
+  const timer = setInterval(() => {
+    if (relay.bot.isRunning()) void writeFile(heartbeat, JSON.stringify({ at: Date.now(), polling: true, version: packageVersion }), { mode: 0o600 })
+  }, 5000)
+  for (const signal of ['SIGINT', 'SIGTERM'] as const) process.once(signal, () => { clearInterval(timer); void relay.stop() })
+  try { await relay.start() } finally { clearInterval(timer); await rm(heartbeat, { force: true }) }
+} else if (command === 'smoke') {
+  await import('../scripts/smoke.js')
+} else if (command === 'exec') {
+  if (!args.length) throw new Error('exec requires a command')
+  const invocation = executorInvocation(args[0], args.slice(1))
+  const child = spawn(invocation.command, invocation.args, { stdio: 'inherit', env: executorEnvironment() })
+  child.on('error', () => { console.error('Command could not start'); process.exitCode = 1 })
+  for (const signal of ['SIGINT', 'SIGTERM'] as const) process.once(signal, () => child.kill(signal))
+  child.on('exit', (code) => { process.exitCode = code ?? 1 })
+} else if (command === 'setup') {
+  await (await import('../src/setup.js')).runCli()
+} else if (['owner', 'source', 'message', 'react'].includes(command)) {
+  await import(`../src/${command === 'source' ? 'source-cli' : command}.js`)
+} else throw new Error('Use start, smoke, exec, setup, owner, source, message or react')