@jc_stack/ez-agents 0.1.0-beta.34 → 0.1.0-beta.36

package/.dockerignore

@@ -23,6 +23,7 @@
 !scripts/release-check.mjs
 !scripts/stage-qa.mjs
 !default-plugins.json
+!compose.yaml
 !scripts/trusted-beta.mjs
 !scripts/generate-publish-caller.mjs
 !scripts/smoke-busy-reply.ts

package/.env.example

@@ -32,26 +32,15 @@ EZ_EXECUTOR_CLI=agy
 # Does not grant GitHub access, merge or publication permissions.
 EZ_REPAIR_ENABLED=true
 
-# Optional PagerDuty incident paging for critical Stocks outages. Put the routing
-# key only in the private relay.env file when running Docker; place the other
-# settings in docker.env so Compose passes them to the relay.
-# PAGERDUTY_ROUTING_KEY=
-# EZ_PAGERDUTY_STOCKS_HEALTH_URL=http://10.97.0.1:3006/health/critical
-# EZ_PAGERDUTY_POLL_SECONDS=30
-# EZ_PAGERDUTY_FAILURE_THRESHOLD=3
-
-# Workforce Watch runs separately. Its enrollment secret and Telegram token are
-# monitor-only credentials; do not put them in an agent workspace.
-# EZ_WATCH_ENROLL_TOKEN=
-# EZ_WATCH_TELEGRAM_CHAT_ID=
-
-# Optional native application-only runtime: no Telegram bot or token.
-# Requires EZ_APPLICATION_PORT; administrator bootstrap uses the real operator ID.
-# EZ_TELEGRAM_ENABLED=false
+# An agent without TELEGRAM_BOT_TOKEN is application-only.
+# It requires EZ_APPLICATION_PORT; administrator bootstrap uses the real operator ID.
 # Isolation class from agent creation (default isolated).
 # EZ_ISOLATION=isolated
 # EZ_EXECUTOR_TRANSPORT=local
 # Host-capable: EZ_ISOLATION=host-capable and EZ_EXECUTOR_TRANSPORT=host
+# Host-capable agents get a generated ledger.compose.yaml that publishes this
+# loopback port so host CLIs can reach the relay ledger on macOS Docker.
+# EZ_DELIVERY_TCP_PORT=23456
 # Private application-only local container isolation (optional; default workspace-write).
 # EZ_CODEX_SANDBOX=external
 

package/AGENTS.md

@@ -14,13 +14,14 @@ Installed runtime operation uses Docker Compose. Read
 [Docker setup, state and QA](docs/docker-runtime.md). Docker owns relay/plugin services; the existing host CLI and login are shared
 through one generic transport, with separate agent workspaces and sessions.
 
-## General core instructions
+## Operating-agent instructions
 
-When the owner refers to "general core instructions", they mean
-`templates/agent-guidance.md`, loaded from the installed package into CLI and
-desktop agent runs, including background tasks. Update that file for defaults
-that must reach all agents after upgrade. Workspace `AGENTS.md` files and
-`templates/agent/` seeds alone do not propagate changes to existing agents.
+Do not inject a coding handbook into production agent minds. The package-owned
+workspace locator is the managed `<!-- ez tools -->` block: the bound `ez`
+launcher, `ez --help`, and `ez tools list --details`. Inventory is generated on
+read; do not hardcode command recipes. Purpose lives in that agent's own
+`AGENTS.md`. Coding defaults for this repository stay in this file and
+CONTRIBUTING.md.
 
 ## Installing this package
 
@@ -53,6 +54,7 @@ This package will be published as an open-source, lightweight Telegram-to-CLI re
 - Plugins are ordinary CLI tools with explicit inputs, outputs and errors. Packaging a tool does not justify another LLM worker or business workflow owner.
 - **SUBTRACT is as valid as ADD.** Question the requirement; delete unnecessary behavior; simplify; shorten feedback; automate last. Name and try the subtraction option before proposing additions. Removing a wrapper or correcting existing engine instructions/tool contracts can be the complete fix.
 - Add code only for a demonstrated missing transport or tool capability. Prompts, agents, retries and lifecycle owners also count as machinery; do not replace deleted code with a scripted prompt workflow. Prefer existing engine, CLI and Docker capabilities.
+- The spawn core (`src/executor.ts` `startExecutorJob`) is spawn + stream only: callers own admission/authority and pass the one trigger suffix; the core never reads the run ledger, history or the workspace.
 - `/goal do my daily routine` is literal task-prompt text for the engine. ez does not parse it, construct a native objective or own its workflow.
 - Keep changes focused. State what was removed, why anything added is necessary, and which observed outcome proves the simpler system works. Preserve authority and uncertain-delivery safeguards. Unchanged, non-actionable maintenance stops quietly; queued updates and passing tests alone do not prove an installed fix.
 
@@ -102,8 +104,8 @@ find flaws:
 If no answer identifies a material blocker, finish. Do not start another review
 round merely to seek more criticism, tests or hypothetical edge cases.
 
-## 3. Crash-Safe Atomic Disk State
-- All persistent stores (`ControlStore`, `RunStore`, outbox queue) must be disk-backed JSON files.
+## 3. Crash-Safe Disk State
+- Persistent authority state (`ControlStore` owner/pairing/sessions/presets, application bindings, schedule definitions) stays in disk-backed JSON files. Run/outbox/inbox bookkeeping is relay memory reached through the delivery socket (`src/delivery-socket.ts`): a restart drops in-flight runs and queued deliveries by design, uncertain sends report unknown rather than success, and Telegram redelivery is the replay mechanism. The live delivery socket also replaces the relay flock as the single-relay guard.
 - **Atomic write pattern:** Never write directly to a state file. Always write to a temporary file (`${target}.${process.pid}.tmp`) with mode `0o600`, then atomically `rename` it over the destination.
 - **Path sanitization:** Every ID parameter (`runId`, `outboxId`, `pairingId`) must be validated against `/^[a-zA-Z0-9_-]+$/` before being joined into paths. Never allow directory traversal (`..`).
 
@@ -119,7 +121,7 @@ round merely to seek more criticism, tests or hypothetical edge cases.
 
 ## 6. Concurrency & Workspace Invariants
 - **1 Writer Job per Workspace:** The agent's Markdown folder (`./agent/`) is its mind. Never run concurrent background processes writing to the same workspace simultaneously.
-- Main-conversation jobs queue sequentially in `RunStore`. Scheduled/background work uses separate task directories and native CLI sessions (up to four alongside chat). Never share a mutable task directory. Delegation decisions and goal persistence belong to the agent/executor; there is no automatic planner or canned chat ACK. Production executor runs have no wall-clock timeout; cancellation is explicit.
+- Main-conversation jobs queue sequentially in the relay's memory ledger; the delivery socket carries every cross-process enqueue/receipt, never control/ files. Scheduled/background work uses separate task directories under the control directory and native CLI sessions (up to four alongside chat). Never share a mutable task directory. Delegation decisions and goal persistence belong to the agent/executor; there is no automatic planner or canned chat ACK. Production executor runs have no wall-clock timeout; cancellation is explicit.
 
 ## 7. Fail-Closed Authority (Channel Access ≠ Execution)
 - Incoming messages outside the approved owner binding must **never** spawn the executor. A first DM or group message records a pending request only. Explicitly approved owner groups grant owner access to all human members in that exact chat; bots and anonymous posts are ignored.
@@ -146,3 +148,9 @@ fix and green tests do not justify a conflicting execution or context owner.
 Existing legacy channel-backend code is a documented limitation, not a pattern
 for new integrations. Keep internal plans and private evidence outside this
 repository.
+
+Source-checkout image builds are RCs: commit and open the PR first, then
+`ezenciel-agents-install build --label X.Y.Z-beta.N.rc.M` (increasing `.rc.N`)
+from the clean reviewed commit. The build refuses a dirty checkout or a package
+tree that is not the checkout root; `/status` must show the RC tag for source
+installs.

package/CHANGELOG.md

@@ -1,10 +1,77 @@
 # Changelog
 
+## 0.1.0-beta.36
+
+- Move relay run/outbox/inbox bookkeeping into relay memory behind the control
+  delivery socket. A restart drops in-flight runs and queued deliveries by
+  design; Telegram redelivery is the replay mechanism. The live socket replaces
+  the relay flock as the single-relay guard.
+- Slim the spawn core to spawn and stream only. Callers authorize admission and
+  pass the one trigger suffix; the core no longer reads the run ledger, history
+  or workspace.
+- Add a dedicated plugin-broker service (isolated profile) that owns Docker
+  access with no network access. Isolated plugin commands run over a Unix socket
+  with single-use capabilities, pinned revisions and per-invocation receipts.
+- Publish installed plugin versions through the broker and report the deployed
+  build identity; show the running RC tag, isolation/transport mode and host
+  platform in `/status`.
+- Add `ezenciel-agents-provision-telegram` to attach a Telegram channel to an
+  existing botless deployment using that deployment's installed image.
+- Add the Telegram `/tasks` list with numbered detail, attach Telegram identity
+  to an existing web owner, and infer Telegram transport from the token instead
+  of `EZ_TELEGRAM_ENABLED`.
+- Remove PagerDuty and Workforce Watch from core. Authorization, transport,
+  scheduling, safety gates and delivery receipts remain.
+- Stop waking the agent for software updates. The supervisor no longer writes an
+  attention notice and the relay no longer queues a wrapper-owned
+  `software_update_attention` run, so nothing outside the managed `ez tools`
+  locator is injected into an operating agent. `ez updates` stays owner-invoked.
+- Stop injecting a package-owned coding handbook into operating-agent
+  `AGENTS.md`. Upgrades strip the old `ez shared guidance` block. Seed only the
+  installer purpose. The managed `ez tools` locator binds the agent launcher
+  (`ez --help` and `ez tools list --details`); inventory is generated on read.
+  Do not create `inbox/`, `work/`, `SOUL.md`, or `USER.md`.
+- Generalize compatibility bridge upgrades so `.compat.N` builds hand off to
+  their canonical release, and allow reviewed legacy homes without `docker.env`.
+- List the agent-bound Codex catalog in `/ai` for local relays, make declared
+  provider models authoritative and migrate persisted provider selections.
+- Source-checkout RC builds require a clean reviewed commit and an increasing
+  `.rc.N` label; the label and commit SHA are baked into the image and shown
+  first in `/status`.
+- Existing host-capable deployments need one installer-owned migration before
+  this release: `ezenciel-agents-install migrate-ledger --deployment <dir>` adds
+  the authenticated loopback ledger endpoint. Pre-beta.36 deployments also need
+  the installer-owned bootstrap because the new `plugin-broker` service and
+  environment changes do not match the previous release's deployment gate.
+- Fix plugin application context delivery into the command container, plugin
+  status JSON parsing under Compose warnings, and EPERM lease liveness.
+
+## 0.1.0-beta.35
+
+- Harden the beta.34 compatibility upgrade path, including supervisor handoff
+  after a completed main upgrade and cleanup of obsolete terminal backups while
+  retaining active, queued and rollback state.
+
+- Publish one plugin author standard for local-only installation, exact public
+  releases, catalog registration, package boundaries, and executor verification.
+
 ## 0.1.0-beta.34
 
 - Correct setup guidance for host-capable custom Codex providers and replace
   stale pinned-beta installation guidance with current release records.
 
+- Retain only the newest completed updater backup per target and reconcile older
+  terminal backups after updates and supervisor restarts, without touching
+  active, queued or rollback state.
+
+- Let existing agents self-upgrade across the beta.34 runtime compatibility
+  migration while retaining fail-closed rejection of structural deployment
+  changes.
+
+- Record the reviewed Library beta14 command-contract migration and hand a
+  completed main upgrade back to the retained bootstrap so the new updater code
+  is loaded without a manual supervisor restart.
+
 - Record an isolation class at agent creation. The default is `isolated`: the
   native CLI runs in the relay (`EZ_EXECUTOR_TRANSPORT=local`). Pass
   `--isolation host-capable` to reuse the installer UID and host CLI login.

package/Dockerfile

@@ -1,6 +1,6 @@
 FROM node:22.22.0-bookworm-slim@sha256:dd9d21971ec4395903fa6143c2b9267d048ae01ca6d3ea96f16cb30df6187d94 AS dependencies
 WORKDIR /app
-RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates git util-linux ffmpeg && rm -rf /var/lib/apt/lists/*
+RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates git util-linux ffmpeg docker.io docker-compose && rm -rf /var/lib/apt/lists/*
 RUN corepack enable && corepack prepare pnpm@10.30.3 --activate
 COPY package.json ./
 COPY docker/pnpm-lock.yaml ./pnpm-lock.yaml
@@ -13,15 +13,13 @@ FROM dependencies AS runtime
 # in the relay; do not bind-mount the operator's ~/.codex.
 ARG CODEX_CLI_VERSION=0.153.4
 RUN npm install -g @openai/codex@${CODEX_CLI_VERSION} && command -v codex
-RUN chmod +x docker/entrypoint.sh bin/ezenciel-agents* && mkdir -p /state/control /state/home /workspace && chown node:node /state/control /state/home /workspace
-RUN node -e 'for (const [name, target] of Object.entries(require("./package.json").bin)) require("node:fs").symlinkSync("/app/" + target, "/usr/local/bin/" + name)'
+RUN chmod +x docker/entrypoint.sh bin/ez bin/ezenciel-agents* && mkdir -p /state/control /state/home /workspace && chown node:node /state/control /state/home /workspace
+RUN node -e 'for (const [name, target] of Object.entries(require("./package.json").bin)) require("node:fs").symlinkSync("/app/" + target, "/usr/local/bin/" + name); require("node:fs").symlinkSync("/app/bin/ez", "/usr/local/bin/ez")'
+# Build identity for relay status (package version stays release-owned).
+ARG BUILD_TAG=""
+ARG BUILD_SHA=""
+RUN node -e 'require("node:fs").writeFileSync("/app/build.json",JSON.stringify({tag:process.env.BUILD_TAG||"",sha:process.env.BUILD_SHA||""})+"\n")'
 ENV HOME=/state/home EZ_AGENT_WORKSPACE=/workspace EZ_CONTROL_DIR=/state/control EZ_EXECUTOR_CLI=grok PATH=/app/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
 WORKDIR /workspace
 ENTRYPOINT ["/app/docker/entrypoint.sh"]
 CMD ["start"]
-
-FROM dependencies AS workforce-watch
-RUN chmod +x bin/ezenciel-agents-watch.mjs && mkdir /state
-ENV EZ_WATCH_STATE_DIR=/state
-WORKDIR /app
-CMD ["node", "--import", "tsx", "src/workforce-watch-cli.ts"]

package/README.md

@@ -140,7 +140,8 @@ here:
 
 - **Install for a user:** [setup and verified onboarding](docs/setup.md), then the installer instructions below.
 - **Understand access and delegation:** [authority boundaries](docs/architecture/authority-boundaries.md) and [security scope](SECURITY.md).
-- **Discover or add capabilities:** [plugin contract](docs/plugins.md). Check the actual executor's native tools before adding an integration.
+- **Build or share a plugin:** [plugin guide](docs/plugin-guide.md). It covers local unpublished installs, public releases, and catalog registration.
+- **Discover or add capabilities:** [plugin manager contract](docs/plugins.md). Check the actual executor's native tools before adding an integration.
 - **Contribute:** [AGENTS.md](AGENTS.md) and [CONTRIBUTING.md](CONTRIBUTING.md).
 
 Repository discovery is not an instruction to install or contact anyone. Act on
@@ -169,13 +170,6 @@ services; the existing host CLI and login are shared through one generic
 transport, with separate agent workspaces and sessions. See
 [Docker setup, state and QA](docs/docker-runtime.md).
 
-For optional PagerDuty paging of a critical Stocks outage, see
-[PagerDuty critical-outage paging](docs/pagerduty.md).
-
-For independent agent check-ins and concise incident context, see
-[Workforce Watch](docs/workforce-watch.md). It runs separately from relays and
-does not receive their executor or provider credentials.
-
 Telegram `/status` shows the running relay and host versions plus installed
 plugin versions. Its read-only **Scheduled tasks** control lists the paired
 owner's active schedules in alphabetical order, with their engine/model/effort,
@@ -243,7 +237,8 @@ credentials, startup, and verified pairing; never present this as human homework
 | Tool | Purpose |
 |---|---|
 | `ezenciel-agents-install preflight --executor <path-or-name>` | Check prerequisites, disk and executor identity hints before setup |
-| `ezenciel-agents-install build` | Build once per artifact, with a private log and duplicate-build detection |
+| `ezenciel-agents-install build [--label <X.Y.Z-beta.N.rc.M>]` | Build once per artifact, with a private log and duplicate-build detection; a source checkout requires the RC label and a clean reviewed commit |
+| `ezenciel-agents-install migrate-ledger --deployment <path>` | Add the loopback host ledger endpoint to an existing host-capable deployment (idempotent; no restart) |
 | `ezenciel-agents-install status --deployment <path>` | Distinguish runtime/configuration, pairing and Telegram reply evidence |
 | `ezenciel-agents-create --register-cli <current-cli>` | Record the CLI that installs the initial package |
 | `ezenciel-agents-create --name <name> --purpose <agent-brief>` | Create an agent from the installing LLM's compact brief; packaged Codex defaults isolated, other CLIs stay host-capable; token via stdin |
@@ -265,10 +260,11 @@ restart and shutdown. Host-capable agents register the small host CLI transport
 
 The selected host CLI runs in this agent's persistent workspace and owns its
 Markdown/work files. New conversations and AI changes preserve those files.
-One compact, purpose-scoped `AGENTS.md` is seeded; `MEMORY.md` is optional.
-The installing LLM authors the initial brief from the owner's request and known
-application context; Ez stores it without trying to infer the product itself.
-Installed plugin snippets and skill paths come from `ez tools list --details`; no tool inventory file needs maintenance. Received files go in `inbox/`, tasks and deliverables in `work/`.
+One compact `AGENTS.md` is seeded with the installer purpose; `MEMORY.md` is
+optional. The installing LLM authors the initial brief from the owner's request
+and known application context; Ez stores it without trying to infer the product
+itself. Installed plugin snippets and skill paths come from the bound
+`ez tools list --details` locator; no tool inventory file needs maintenance.
 Credentials and control state stay outside the mind. Isolated agents use relay
 mounts as the filesystem boundary. Host-capable file separation is not OS
 isolation against a process running as the same user.
@@ -319,6 +315,7 @@ without authorization. Local registry rehearsal uses `pnpm publish:local`.
 - [Security scope](SECURITY.md)
 
 - [Contributing](CONTRIBUTING.md) and [releasing](docs/releasing.md)
+- [Plugin author guide](docs/plugin-guide.md)
 - [First plugin and extension contract](docs/plugins.md)
 - [License and dependency notices](THIRD_PARTY_NOTICES.md)
 

package/bin/ez

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import { createConnection } from 'node:net';
+import { randomUUID } from 'node:crypto';
+
+const MAX_STDIN_BYTES = 1024 * 1024;
+const RUN_ID = /^[A-Za-z0-9_-]{1,160}$/;
+const socketPath = process.env.EZ_PLUGIN_BROKER_SOCKET?.trim();
+const runId = process.env.EZ_RUN_ID?.trim();
+
+const fail = message => {
+  process.stderr.write(`ez plugin broker: ${message}\n`);
+  process.exitCode = 1;
+};
+
+const request = (payload, signal = undefined) => new Promise((resolve, reject) => {
+  if (!socketPath || !socketPath.startsWith('/') || socketPath.length > 100) return reject(Error('isolated plugin broker is not configured'));
+  const timeoutMs = Number(process.env.EZ_PLUGIN_BROKER_CLIENT_TIMEOUT_MS ?? 600000)
+  const socket = createConnection(socketPath);
+  let buffer = '';
+  let settled = false;
+  const finish = (error, value) => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(timer);
+    signal?.removeEventListener('abort', cancel);
+    socket.destroy();
+    if (error) reject(error); else resolve(value);
+  };
+  const cancel = () => {
+    socket.destroy();
+    finish(Error('plugin command cancelled'));
+  };
+  const timer = setTimeout(() => {
+    socket.destroy();
+    finish(Error('plugin broker request timed out'));
+  }, Number.isSafeInteger(timeoutMs) && timeoutMs > 0 ? timeoutMs : 600000);
+  signal?.addEventListener('abort', cancel, { once: true });
+  socket.on('error', error => finish(error));
+  socket.on('close', () => finish(Error('plugin broker closed the connection')));
+  socket.on('data', chunk => {
+    buffer += chunk.toString();
+    const end = buffer.indexOf('\n');
+    if (end < 0) return;
+    let value;
+    try { value = JSON.parse(buffer.slice(0, end)); } catch { return finish(Error('invalid plugin broker response')); }
+    finish(undefined, value);
+  });
+  socket.on('connect', () => socket.write(JSON.stringify(payload) + '\n'));
+});
+
+const readStdin = async () => {
+  if (process.stdin.isTTY) return '';
+  const chunks = [];
+  let bytes = 0;
+  for await (const chunk of process.stdin) {
+    const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    bytes += value.length;
+    if (bytes > MAX_STDIN_BYTES) throw Error('plugin stdin exceeds the broker limit');
+    chunks.push(value);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+};
+
+const invoke = async (args, stdin) => {
+  if (!runId || !RUN_ID.test(runId)) throw Error('EZ_RUN_ID is required for an isolated plugin command');
+  const alias = args.shift();
+  if (!alias || !/^[a-z][a-z0-9-]{0,39}$/.test(alias) || ['plugins', 'tools', 'status', 'updates', 'message', 'owner', 'approval', 'react', 'setup', 'help', 'version'].includes(alias)) throw Error('Use a declared plugin alias');
+  const resolved = await request({ version: 1, id: randomUUID(), operation: 'resolve', runId, alias });
+  if (!resolved?.ok) throw Error(resolved?.error || 'Plugin alias resolution failed');
+  const result = await request({ version: 1, id: randomUUID(), operation: 'invoke', runId, alias, revision: resolved.revision, capability: resolved.capability, args, ...(stdin ? { stdin } : {}) });
+  if (!result?.ok) throw Error(result?.error || 'Plugin invocation failed');
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  process.exitCode = Number.isInteger(result.code) ? result.code : 1;
+};
+
+const manager = async args => {
+  if (!runId || !RUN_ID.test(runId)) throw Error('EZ_RUN_ID is required for isolated plugin management');
+  const result = await request({ version: 1, id: randomUUID(), operation: 'manager', runId, args });
+  if (!result?.ok) throw Error(result?.error || 'Plugin broker management failed');
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  process.exitCode = Number.isInteger(result.code) ? result.code : 0;
+};
+
+const main = async () => {
+  const args = process.argv.slice(2);
+  if (!args.length || args[0] === '--help' || args[0] === '-h') {
+    process.stdout.write('Use `ez tools list` to discover installed plugins, then `ez <alias> ...` for a declared command.\n');
+    return;
+  }
+  const stdin = ['plugins', 'tools', 'updates', 'status'].includes(args[0]) ? '' : await readStdin();
+  if (['plugins', 'tools', 'updates', 'status'].includes(args[0])) await manager(args);
+  else await invoke(args, stdin);
+};
+
+main().catch(error => fail(error instanceof Error ? error.message : 'Plugin broker client failed'));

package/bin/ezenciel-agents-plugin-broker.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', 'plugin-broker.mjs');
+const child = spawn(process.execPath, ['--import', tsx, entry, ...process.argv.slice(2)], { stdio: 'inherit' });
+child.on('error', error => { console.error(error.message); process.exitCode = 1; });
+child.on('exit', (code, signal) => {
+  if (signal) process.kill(process.pid, signal);
+  process.exit(code ?? 1);
+});

package/bin/ezenciel-agents-provision-telegram.mjs

@@ -0,0 +1,13 @@
+#!/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 child = spawn(process.execPath, ['--import', require.resolve('tsx'), join(here, '..', 'src', 'telegram-provisioning-cli.ts'), ...process.argv.slice(2)], { stdio: 'inherit' })
+child.on('exit', (code, signal) => {
+  if (signal) process.kill(process.pid, signal)
+  process.exit(code ?? 1)
+})

package/bin/ezenciel-agents.mjs

@@ -22,7 +22,7 @@ if (forwarded.length && (forwarded.length !== 1 || forwarded[0] !== 'start')) {
   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' })
+  const docker = spawn(join(here, 'ezenciel-agents-docker'), ['up', '-d', '--wait'], { stdio: 'inherit' })
   docker.on('error', () => { console.error('Docker launcher could not start'); process.exitCode = 1 })
   docker.on('exit', code => { process.exitCode = code ?? 1 })
 } else {

package/compose.yaml

@@ -19,9 +19,9 @@ services:
       EZ_AGENT_PURPOSE_FILE: /run/agent-purpose.md
       EZ_ISOLATION: ${EZ_ISOLATION:-}
       EZ_EXECUTOR_TRANSPORT: ${EZ_EXECUTOR_TRANSPORT:-host}
+      EZ_PLUGIN_BROKER_SOCKET: ${EZ_PLUGIN_BROKER_SOCKET:-}
       EZ_CHANNEL_BACKEND_URL: ${EZ_CHANNEL_BACKEND_URL:-}
       EZ_TELEGRAM_WEB_APP: ${EZ_TELEGRAM_WEB_APP:-}
-      EZ_TELEGRAM_ENABLED: ${EZ_TELEGRAM_ENABLED:-true}
       EZ_APPLICATION_PORT: ${EZ_APPLICATION_PORT:-}
       EZ_APPLICATION_HOST: ${EZ_APPLICATION_HOST:-127.0.0.1}
       EZ_AGENT_WORKSPACE: ${EZ_AGENT_WORKSPACE:?Set this agent workspace}
@@ -30,9 +30,6 @@ services:
       EZ_CODEX_SANDBOX: ${EZ_CODEX_SANDBOX:-}
       EZ_CODEX_AUTO_COMPACT_TOKENS: ${EZ_CODEX_AUTO_COMPACT_TOKENS:-64000}
       EZ_EXECUTOR_TIMEOUT_SECONDS: ${EZ_EXECUTOR_TIMEOUT_SECONDS:-300}
-      EZ_PAGERDUTY_STOCKS_HEALTH_URL: ${EZ_PAGERDUTY_STOCKS_HEALTH_URL:-}
-      EZ_PAGERDUTY_POLL_SECONDS: ${EZ_PAGERDUTY_POLL_SECONDS:-30}
-      EZ_PAGERDUTY_FAILURE_THRESHOLD: ${EZ_PAGERDUTY_FAILURE_THRESHOLD:-3}
     secrets: [relay_env]
     configs:
       - source: agent_purpose
@@ -49,6 +46,45 @@ services:
       timeout: 5s
       start_period: 30s
       retries: 3
+  plugin-broker:
+    profiles: [isolated]
+    image: ${EZ_RELAY_IMAGE:-ezenciel-agents:local}
+    build:
+      context: .
+      target: runtime
+    init: true
+    restart: unless-stopped
+    stop_grace_period: 10s
+    user: "0:0"
+    cap_drop: [ALL]
+    security_opt: [no-new-privileges:true]
+    network_mode: none
+    environment:
+      # Defaults keep Compose interpolation valid for host-capable deployments;
+      # the broker itself rejects these placeholders if its isolated profile is enabled.
+      EZ_PLUGIN_BROKER_HOME: ${EZ_TOOLS_HOME:-/nonexistent/ez-tools}
+      EZ_PLUGIN_BROKER_WORKSPACE: ${EZ_AGENT_WORKSPACE:-/nonexistent/ez-workspace}
+      EZ_PLUGIN_BROKER_CONTROL_DIR: ${EZ_CONTROL_DIR:-/nonexistent/ez-control}
+      EZ_PLUGIN_BROKER_SOCKET: ${EZ_PLUGIN_BROKER_SOCKET:-/nonexistent/ez-control/plugin-broker.sock}
+      EZ_PLUGIN_BROKER_HOST_CONFIG: ${EZ_PLUGIN_BROKER_HOST_CONFIG:-/nonexistent/host-executor.json}
+      EZ_PLUGIN_BROKER_TIMEOUT_MS: ${EZ_PLUGIN_BROKER_TIMEOUT_MS:-300000}
+      EZ_DOCKER_COMPOSE: standalone
+      HOME: /tmp
+      DOCKER_CONFIG: /tmp/docker-config
+    volumes:
+      - ${EZ_TOOLS_HOME:-/nonexistent/ez-tools}:${EZ_TOOLS_HOME:-/nonexistent/ez-tools}
+      - ${EZ_AGENT_WORKSPACE:-/nonexistent/ez-workspace}:${EZ_AGENT_WORKSPACE:-/nonexistent/ez-workspace}:ro
+      - ${EZ_CONTROL_DIR:-/nonexistent/ez-control}:${EZ_CONTROL_DIR:-/nonexistent/ez-control}
+      - ${EZ_PLUGIN_BROKER_HOST_CONFIG:-/nonexistent/host-executor.json}:${EZ_PLUGIN_BROKER_HOST_CONFIG:-/nonexistent/host-executor.json}:ro
+      - /var/run/docker.sock:/var/run/docker.sock
+    tmpfs: [/tmp]
+    entrypoint: [node, --import, /app/node_modules/tsx/dist/loader.mjs, /app/src/plugin-broker.mjs]
+    healthcheck:
+      test: [CMD, node, -e, "const fs=require('node:fs'); try { process.exit(fs.statSync(process.env.EZ_PLUGIN_BROKER_SOCKET).isSocket() ? 0 : 1) } catch { process.exit(1) }"]
+      interval: 2s
+      timeout: 5s
+      start_period: 5s
+      retries: 30
 configs:
   agent_purpose:
     file: ${EZ_AGENT_PURPOSE_FILE:-./templates/agent-purpose.md}

package/docker/entrypoint.sh

@@ -28,6 +28,6 @@ fi
 ( : <&3 ) 2>/dev/null || exec 3</dev/null
 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 "$@" ;;
   *) exec node --import /app/node_modules/tsx/dist/loader.mjs /app/docker/run.ts "$@" ;;
 esac

package/docker/healthcheck.mjs

@@ -1,10 +1,14 @@
-import { readFileSync } from 'node:fs';
+import { readFileSync, statSync } from 'node:fs';
+const heartbeatFile = process.env.EZ_HEARTBEAT_FILE || '/tmp/ez-relay-heartbeat.json';
 const relayControl = process.env.EZ_HEALTH_RELAY_CONTROL_DIR || '/state/control';
 const fail = code => { process.stderr.write(`EZ_HEALTH_${code}\n`); process.exit(1); };
 let value;
-try { value = JSON.parse(readFileSync(relayControl + '/heartbeat.json', 'utf8')); }
-catch { fail('RELAY_UNREADABLE'); }
-if (!value.polling && !(process.env.EZ_TELEGRAM_ENABLED === 'false' && value.applicationOnly === true)) fail('RELAY_NOT_POLLING');
+try { value = JSON.parse(readFileSync(heartbeatFile, 'utf8')); }
+catch {
+  try { value = JSON.parse(readFileSync(relayControl + '/heartbeat.json', 'utf8')); }
+  catch { fail('RELAY_UNREADABLE'); }
+}
+if (!value.polling && (value.applicationOnly !== true || value.telegramConfigured !== false)) fail('RELAY_NOT_POLLING');
 if (!Number.isFinite(value.at) || Date.now() - value.at > 20000) fail('RELAY_STALE');
 
 if (process.env.EZ_EXECUTOR_TRANSPORT === 'host') {
@@ -13,3 +17,7 @@ if (process.env.EZ_EXECUTOR_TRANSPORT === 'host') {
   catch { fail('HOST_UNREADABLE'); }
   if (!Number.isFinite(host.at) || Date.now() - host.at > 15000) fail('HOST_STALE');
 }
+if (process.env.EZ_PLUGIN_BROKER_SOCKET?.trim()) {
+  try { if (!statSync(process.env.EZ_PLUGIN_BROKER_SOCKET).isSocket()) fail('PLUGIN_BROKER_UNREADABLE'); }
+  catch { fail('PLUGIN_BROKER_UNREADABLE'); }
+}

package/docker/run.ts

@@ -4,7 +4,6 @@ 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'
 
@@ -21,18 +20,18 @@ 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', 'EZ_CHANNEL_BACKEND_TOKEN', 'PAGERDUTY_ROUTING_KEY'].includes(key)) process.env[key] = value
+  if (value !== undefined && ['TELEGRAM_BOT_TOKEN', 'GEMINI_API_KEY', 'OPENAI_API_KEY', 'EZ_CHANNEL_BACKEND_TOKEN'].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, Boolean(loadConfig().channelBackendUrl))
 if (command === 'start') {
-  const relay = createRelay(loadConfig())
-  const heartbeat = '/state/control/heartbeat.json'
+  const config = loadConfig()
+  const relay = createRelay(config)
+  const heartbeat = process.env.EZ_HEARTBEAT_FILE || '/tmp/ez-relay-heartbeat.json'
   await rm(heartbeat, { force: true })
   const timer = setInterval(() => {
-    if (relay.isRunning()) void writeFile(heartbeat, JSON.stringify({ at: Date.now(), polling: Boolean(relay.bot?.isRunning()), applicationOnly: process.env.EZ_TELEGRAM_ENABLED === 'false', version: packageVersion }), { mode: 0o600 })
+    if (relay.isRunning()) void writeFile(heartbeat, JSON.stringify({ at: Date.now(), polling: Boolean(relay.bot?.isRunning()), applicationOnly: !relay.telegramEnabled, telegramConfigured: config.telegramBotToken !== '', 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 }) }

package/docker/smoke.mjs

@@ -21,7 +21,7 @@ try {
     '--mount',`type=bind,src=${join(dir,'purpose.md')},dst=/run/agent-purpose.md,readonly`,'-e','EZ_AGENT_PURPOSE_FILE=/run/agent-purpose.md',
     '--tmpfs','/tmp:mode=1777','--tmpfs','/state/control:uid=20000,gid=20000,mode=700',
     '--tmpfs','/state/home:uid=20000,gid=20000,mode=700','--tmpfs','/workspace:uid=20000,gid=20000,mode=700',
-    '-e','EZ_TELEGRAM_ENABLED=false','-e','EZ_APPLICATION_PORT=8110','-e','EZ_ISOLATION=isolated','-e','EZ_EXECUTOR_TRANSPORT=local','-e','EZ_EXECUTOR_CLI=codex'];
+    '-e','EZ_APPLICATION_PORT=8110','-e','EZ_ISOLATION=isolated','-e','EZ_EXECUTOR_TRANSPORT=local','-e','EZ_EXECUTOR_CLI=codex'];
   const help = run(['run','--rm',...nonroot,image,'application','--help']);
   assert.equal(help.status,0,help.stderr);
   assert.match(help.stdout,/ezenciel-agents-application/);
@@ -72,7 +72,23 @@ try {
   assert.equal(JSON.parse(custom.stdout).uid,20001);
   const failed = run(['run','--rm',image,'exec','node','-e','process.exit(23)']);
   assert.equal(failed.status, 23, failed.stderr);
-  const held = run(['run','-d','--name',holder,'-v',`${volume}:/state/control`,image,'exec','node','-e',"require('fs').writeFileSync('/state/control/ready','yes');setInterval(()=>{},1000)"]);
+  // The live delivery socket is the single-relay guard (it replaced the kernel
+  // flock). This mirrors the relay's own start check: an answering address
+  // refuses the second owner; a stale file is removed before binding.
+  const guardScript = `
+    const net=require('net'),fs=require('fs'),stay=process.argv[1]==='hold',path='/state/control/delivery.sock';
+    const probe=net.createConnection(path);
+    const bind=()=>{
+      fs.rmSync(path,{force:true});
+      const s=net.createServer(()=>{});
+      s.on('error',()=>process.exit(1));
+      s.listen(path,()=>{if(stay){fs.writeFileSync('/state/control/ready','yes');setInterval(()=>{},1000)}else s.close(()=>process.exit(0))});
+    };
+    probe.on('connect',()=>{probe.destroy();process.exit(73)});
+    probe.on('error',bind);
+    probe.setTimeout(3000,()=>{probe.destroy();process.exit(1)});
+  `;
+  const held = run(['run','-d','--name',holder,'-v',`${volume}:/state/control`,image,'exec','node','-e',guardScript,'hold']);
   assert.equal(held.status,0,held.stderr);
   for (let n=0;n<30;n++) {
     const probe=run(['exec',holder,'test','-f','/state/control/ready']);
@@ -80,10 +96,16 @@ try {
     await new Promise(resolve=>setTimeout(resolve,100));
   }
   assert.equal(run(['exec',holder,'test','-f','/state/control/ready']).status,0);
-  const duplicate=run(['run','--rm','-v',`${volume}:/state/control`,image,'exec','node','-e','process.exit(0)']);
+  const duplicate=run(['run','--rm','-v',`${volume}:/state/control`,image,'exec','node','-e',guardScript]);
   assert.equal(duplicate.status,73,duplicate.stderr);
   assert.equal(run(['kill',holder]).status,0);
-  const recovered=run(['run','--rm','-v',`${volume}:/state/control`,image,'exec','node','-e','process.exit(0)']);
-  assert.equal(recovered.status,0,recovered.stderr);
-  console.log('Docker smoke passed: direct non-root application help/start/health/stop, inherited private descriptor, non-root executor, isolated Codex on PATH, private secret isolation, literal argv, exit code, no Docker socket, duplicate writer rejection and crash lock release.');
+  let released=1;
+  for (let n=0;n<50;n++) {
+    const recovered=run(['run','--rm','-v',`${volume}:/state/control`,image,'exec','node','-e',guardScript]);
+    released=recovered.status;
+    if(released===0)break;
+    await new Promise(resolve=>setTimeout(resolve,100));
+  }
+  assert.equal(released,0,'a dead relay must release the delivery socket');
+  console.log('Docker smoke passed: direct non-root application help/start/health/stop, inherited private descriptor, non-root executor, isolated Codex on PATH, private secret isolation, literal argv, exit code, no Docker socket, live delivery-socket guard and crash release.');
 } finally { run(['rm','-f',holder,application]); run(['volume','rm',volume]); rmSync(dir, {recursive:true, force:true}); }