@jc_stack/ez-agents 0.1.0-beta.33 → 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,22 +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,5 +1,94 @@
 # 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.
+  Mismatched class and transport fail closed. Isolated Codex sets
+  `EZ_CODEX_SANDBOX=external`. Host transport is not started for isolated
+  agents. Unlabeled existing host transports stay host-capable.
+- Install pinned Codex CLI `0.153.4` in the relay runtime image so isolated
+  agents resolve `codex` on PATH. Isolated jobs keep auth in
+  `control/cli/codex` and do not link the operator `~/.codex`.
+
+- Confine macOS host jobs to their bound workspace and prevent cross-agent
+  plugin registry access.
+- Support agent-scoped OpenRouter models through the native Codex engine and
+  start a new native session when the provider or model changes.
+- Resolve native CLIs from the host PATH, expose captured presets in application
+  run receipts, and seed one purpose-scoped AGENTS.md for new agents.
+
 ## 0.1.0-beta.33
 
 - Allow compatible plugin updates to add commands to existing services, registering
@@ -21,6 +110,9 @@
   host CLI configuration needed for restricted read-only plugin commands.
 - Clarify domain-agent positioning while preserving native engine ownership.
 
+- Prevent accidental cross-agent plugin access by rejecting relay-bound registry
+  calls outside the owning workspace, and restrict its host-folder bindings to
+  workspace roots explicitly granted by the host.
 - Answer native app-server requests with their current protocol shapes. Scheduled
   `codex-gui` browser work now surfaces approval requests and grants only its
   active turn session-scoped HTTPS browser-origin and Chrome app elicitations,

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
@@ -9,15 +9,17 @@ COPY . .
 FROM dependencies AS test
 RUN pnpm verify
 FROM dependencies AS runtime
-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)'
+# Keep this pin aligned with TASK_CODEX_VERSION. Isolated agents run this CLI
+# 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/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
@@ -148,15 +149,19 @@ the user's request and preserve its scope.
 
 ## Package and runtime
 
-**Beta 0.1.0-beta.12 — for testing on a trusted machine.** Offline and Docker
-fixtures are verified. Live account onboarding and reboot acceptance for this
-release are deferred; this is not a production-readiness claim. The source branch
-may contain changes newer than the published beta; inspect the supplied artifact's
-documentation when installing a pinned release.
-
-The npm package is `@jc_stack/ez-agents` (channel `beta`). Download a pinned
-release with `npm pack @jc_stack/ez-agents@0.1.0-beta.12`, or get the tarball and SHA256SUMS from
-[GitHub prereleases](https://github.com/jdorado/ez-agents/releases/tag/v0.1.0-beta.12).
+**Published beta releases are for testing on a trusted machine.** Offline and
+Docker fixtures are verified for the selected release. Live account onboarding
+and reboot acceptance remain beta gates; this is not a production-readiness
+claim. The source branch may contain changes newer than the published beta, so
+inspect the supplied artifact's documentation when installing a pinned release.
+
+The npm package is `@jc_stack/ez-agents`. Approved beta publications use npm's
+`latest` distribution tag while their versions and GitHub releases remain
+prereleases. For a reproducible download, choose an exact version from
+[GitHub prereleases](https://github.com/jdorado/ez-agents/releases) and substitute
+it for `VERSION` in `npm pack @jc_stack/ez-agents@VERSION`.
+You can also download the release's candidate tarball and verify its SHA-256
+against the attached release receipt or release notes.
 GitHub remains under `jdorado`; npm uses `jc_stack`. Do not install the unrelated
 unscoped `ez-whatsapp` package.
 
@@ -165,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,
@@ -239,31 +237,37 @@ 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 <purpose>` | Create an agent inheriting the installation CLI; token via stdin |
+| `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 |
+| `ezenciel-agents-create --name <name> --purpose <agent-brief> --isolation host-capable` | Explicitly reuse the host CLI and installer UID |
 | `ezenciel-agents-host` | Invoke the existing shared host CLI for this deployment |
-| `ezenciel-agents-setup configure <executor>` | Private configuration and missing starter files; preserves personal files |
-| `ezenciel-agents-setup configure <executor> --token-stdin` | Same, with the BotFather token supplied privately through stdin |
+| `ezenciel-agents-setup configure <executor> --purpose-file <path>` | Private configuration and missing starter files; fresh workspaces require installer-scoped purpose; preserves personal files |
+| `ezenciel-agents-setup configure <executor> --purpose-file <path> --token-stdin` | Same, with the BotFather token supplied privately through stdin |
 | `ezenciel-agents-setup service` | Start only the Docker relay bound by `docker.env` in the current directory; register the [host service](docs/host-service.md) separately |
 | `ezenciel-agents-owner status` | Inspect the owner and pending pairing requests |
 | `ezenciel-agents-owner approve <telegram-user-id>` | Approve the verified owner; never an arbitrary first sender |
 | `ezenciel-agents-setup status` | Inspect installed executor choices |
-| `ezenciel-agents-setup init` | Seed only missing workspace guidance |
+| `ezenciel-agents-setup init --purpose-file <path>` | Seed missing workspace guidance; purpose is optional only when AGENTS.md already exists |
 
 Run runtime tools through `ezenciel-agents-docker run --rm relay <command>`
 as shown in the Docker guide. Keep the Docker engine available; Compose owns
-restart and shutdown. The installing agent registers the small host CLI transport with the native service manager.
+restart and shutdown. Host-capable agents register the small host CLI transport with the native service manager. Isolated agents do not.
 
 ## Runtime and development reference
 
 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.
-`AGENTS.md`, `SOUL.md`, and `USER.md` are seeded; `MEMORY.md` is
-optional. 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/`.
-Credentials and control state stay outside the mind. File separation is not
-OS isolation against a process running as the same user.
+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.
 
 In Telegram, **Conversations** (or `/chats`) lists this agent's saved Ez
 conversations by name. Tap a name to continue its native engine session and
@@ -311,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/THIRD_PARTY_NOTICES.md

@@ -8,7 +8,7 @@ The container is built locally; no bundled third-party binary image is promised.
 
 Direct runtime dependencies: grammy (MIT), tsx (MIT). Development dependencies
 include TypeScript (Apache-2.0) and Node type definitions (MIT). The runtime
-image installs ffmpeg and Debian packages: redistributing that image requires
-review of its exact package build, notices and corresponding-source obligations.
-Docker and the selected host AI CLI are separately installed products, not covered
-by this repository's MIT license.
+image installs ffmpeg, Debian packages, and pinned `@openai/codex` (Apache-2.0):
+redistributing that image requires review of its exact package build, notices and
+corresponding-source obligations. Docker and a host-capable AI CLI remain
+separately installed products, not covered by this repository's MIT license.

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

@@ -17,10 +17,11 @@ services:
       EZ_RELAY_UID: ${EZ_RELAY_UID:-1001}
       EZ_REPAIR_ENABLED: ${EZ_REPAIR_ENABLED:-true}
       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}
@@ -29,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
@@ -48,9 +46,48 @@ 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/SOUL.md}
+    file: ${EZ_AGENT_PURPOSE_FILE:-./templates/agent-purpose.md}
 secrets:
   relay_env:
     file: ${EZ_RELAY_ENV_FILE:?Set EZ_RELAY_ENV_FILE to the private relay env file}

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'); }
+}