@jc_stack/ez-agents 0.1.0-beta.12

package/.dockerignore

@@ -0,0 +1,24 @@
+*
+!package.json
+!pnpm-lock.yaml
+!src/**
+!bin/**
+!docker/**
+!templates/**
+!skills/**
+!test/**
+!tsconfig.json
+!scripts/smoke.ts
+!README.md
+!AGENTS.md
+!ez-plugin.json
+!LICENSE
+!SECURITY.md
+!docs/**
+!scripts/assert-local-registry.mjs
+
+!THIRD_PARTY_NOTICES.md
+!CONTRIBUTING.md
+!CHANGELOG.md
+!scripts/release-check.mjs
+!default-plugins.json

package/.env.example

@@ -0,0 +1,26 @@
+# The only credential required for the first smoke test. Keep the real value in .env.
+TELEGRAM_BOT_TOKEN=
+
+# Persistent mind, seeded by setup init or first relay start; existing files survive.
+EZ_AGENT_WORKSPACE=./agent
+
+# Local, protected authority state. Keep it outside the agent Markdown workspace.
+# EZ_CONTROL_DIR=/absolute/path/outside/agent-workspace
+
+# Owner-pairing request lifetime. Default is 900 seconds.
+# EZ_PAIRING_TTL_SECONDS=900
+
+# Optional. Default is 300.
+# EZ_EXECUTOR_TIMEOUT_SECONDS=300
+
+# CLI Executor adapter. Supported: agy (default), claude, grok, opencode
+# Switch easily with: pnpm run setup <executor-name>
+EZ_EXECUTOR_CLI=agy
+
+# Optional: Audio transcription (STT) and voice synthesis (TTS)
+# GEMINI_API_KEY=
+# OPENAI_API_KEY=
+
+# Optional: OpenRouter API key for OpenCode CLI (Nemotron 3.5 Lightning)
+# OPENROUTER_API_KEY=
+# OPENCODE_MODEL=openrouter/nvidia/nemotron-3.5-lightning

package/AGENTS.md

@@ -0,0 +1,84 @@
+# ezenciel-agents — Coding Standards & Architectural Invariants
+
+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.
+
+## Installing this package
+
+When the user asks to set up or install this repository or package, follow
+[the agent-led setup instructions](docs/setup.md). Handle the technical work
+and ask only for missing information. The user does not need to name or read
+the documentation. Install means onboarding through a real Telegram reply,
+unless the user explicitly asks for package files only. Do not finish with
+developer commands or an uninitialized bot. At a required user step, give one
+concrete action with its exact link; continue after their answer. The coding
+standards below apply when developing the relay.
+
+Main-first onboarding is mandatory: initialize an empty registry, complete owner
+pairing and verify an agent-produced Telegram reply before plugin preparation or
+QR onboarding. A supplied plugin archive is deferred input. After main setup,
+plugin requests and onboarding run through the installed agent's Telegram chat,
+not the original installer CLI. Read docs/setup.md for the handoff and diagnostics.
+
+This package will be published as an open-source, lightweight Telegram-to-CLI relay. All code added to this package must adhere to these strict invariants to prevent bloat, credential leaks, and rewrites.
+
+---
+
+## 1. Radical Lean Footprint (Zero DB Dependencies)
+- **Runtime dependencies:** Restricted to `grammy` and TypeScript tooling (`tsx`). Do not add databases (no MongoDB, SQLite, Redis, or ORMs) or web frameworks (no Express/Fastify).
+- **Native Node 22+ APIs only:** Use `node:fs/promises`, `node:child_process`, `node:crypto`, `node:path`, and native global `fetch`, `FormData`, and `Blob`.
+- Keep `node_modules` minimal and installable in seconds.
+
+## 2. Zero Deterministic Coding Across the Board (Tools, Flows & Dialog)
+- **The relay is dumb plumbing:** The relay only ingests messages, batches them into runs, spawns the CLI executor, and drains outbox items. It is strictly minimal.
+- **Nothing deterministic—not just dialog:** Do not hardcode multi-step tool pipelines, fallback state machines, parameter translation shims, procedural dialog flows, or canned conversational receipts ("Started run...", "I'll message as I go...").
+- **The debugging reflex trap:** When an integration, tool, or flow doesn't work as expected, developers and LLMs have an overwhelming reflex to patch it by writing deterministic procedural code (`if error X -> hardcode Y -> do Z`). **Resist this completely.**
+- **The real engineering work:** Our job is solely to:
+  1. Build clean, standalone tools that work reliably with clear Unix interfaces (clear args, predictable stdout/stderr, clean exit codes).
+  2. Ensure tools have simple setup and are clearly explained in the agent's workspace so the **agent understands them**.
+  3. Let the agent own all flow orchestration, tool chaining, decision making, and error recovery. Question every line of code—if it can be agentic, keep code out of it.
+
+## 3. Crash-Safe Atomic Disk State
+- All persistent stores (`ControlStore`, `RunStore`, outbox queue) must be disk-backed JSON files.
+- **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 (`..`).
+
+## 4. Strict Subprocess Isolation & Secret Whitelisting
+- **Environment leak prevention:** `TELEGRAM_BOT_TOKEN`, relay internals, and parent daemon secrets must **never** leak into the executor subprocess.
+- The executor environment is built from an explicit whitelist plus bound runtime identifiers. Inspect `src/executor.ts` for the current list; never spread the daemon environment into a child.
+- Executor stdout is ignored for chat delivery. To send updates, the agent must invoke the native binary: `ezenciel-agents-message`.
+
+## 5. Telegram Formatting & Rate Limit Safety
+- **Safe HTML formatting:** Never pass raw markdown directly into Telegram with `parse_mode: 'HTML'` or `'MarkdownV2'` without escaping. Use a dedicated sanitizer (`markdownToTelegramHtml`) that escapes `<, >, &` before wrapping tags.
+- **Message chunking:** Chunk all outgoing messages to $\le 4,000$ characters on paragraph (`\n\n`), line (`\n`), or word boundaries.
+- **Rate limits:** Avoid spamming bubbles to respect Telegram’s 1 message/sec per-chat rate limit.
+
+## 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.
+- Executor jobs queue sequentially in `RunStore`; the poller remains available for cancellation and incoming messages. There is no separate planner or automatic chat ACK lane.
+
+## 7. Fail-Closed Authority (Channel Access ≠ Execution)
+- Incoming messages from unapproved senders must **never** spawn the executor. First DM registers an unapproved pairing request, then stops.
+- Group messages or unknown DMs fail silently.
+- Stopping work (`/stop`) must terminate the active worker PID immediately (`SIGTERM`, escalating to `SIGKILL` if unclosed after 3s).
+
+## 8. Mandatory Adversarial & Negative Tests
+Every pull request modifying authority, execution, or routing must include negative tests:
+1. Unapproved Telegram ID $\rightarrow$ no process spawned.
+2. Group message $\rightarrow$ silent ignore.
+3. Executor environment check $\rightarrow$ asserts `TELEGRAM_BOT_TOKEN` is `undefined`.
+4. Corrupt JSON in store $\rightarrow$ handled gracefully without process crash.
+5. Injected path traversal in IDs $\rightarrow$ rejected.
+
+## Public contribution workflow
+
+Read CONTRIBUTING.md before edits and docs/releasing.md before a release.
+Maintainers and external agents use the same PR, tests and documentation standard.
+Keep internal plans and private evidence outside this repository.
+
+Before edits, follow CONTRIBUTING.md's isolated-work rules: one task per dedicated
+worktree/branch/PR, starting from fetched origin/main. Do not switch or mix work in
+another task's checkout. Stage only this task's changes. Keep its worktree through
+review and QA; independent review and green CI precede an authorized merge.
+Never treat task completion as permission to merge or publish.

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+## 0.1.0-beta.12 — self-upgrade beta
+
+- Agent-owned main/plugin upgrades with stable-default policy, queued maintenance,
+  pinned package-manager preflight, private backups and code/config rollback.
+- Main Telegram onboarding before plugin installation, reusable build/preflight tools,
+  executor and private-pause fixes, and installed/running version diagnostics.
+- Isolated worktree/PR contribution process and explicit independent review.
+- User-reported VM QA passed main beta.3 to beta.4 upgrade and deliberate beta.11
+  activation failure with rollback to beta.4 and a post-recovery Telegram reply.
+- That VM evidence covers earlier candidates. Final beta.12 fresh-host/reboot and
+  live WhatsApp upgrade acceptance remain pending; this is a testing beta.
+
+Private QA versions beta.3 through beta.11 were not public releases; some were
+deliberately broken rollback fixtures and must never be published.
+
+## 0.1.0-beta.2 — distribution preparation (not published)
+
+- Publish under `@jc_stack/ez-agents`; GitHub remains `jdorado/ez-agents`.
+- Document pinned npm downloads and retain the beta-only distribution channel.
+- Runtime behavior and dependencies are unchanged from beta.1. Live account and
+  reboot acceptance remain deferred.
+
+## 0.1.0-beta.1 — initial public beta
+
+- Owner-paired Telegram relay using an existing host AI CLI and persistent
+  Markdown workspace, with queued execution and explicit messaging tools.
+- Docker runtime, private deployment creation and a local hash-pinned plugin
+  manager with explicit installation/start/stop and provider-owned onboarding.
+- Empty default catalog: no unpublished sibling package required.
+- Public contribution, security, packaging and release instructions.
+
+Limits: trusted host administration, not hostile-agent isolation. No hosted
+service or remote plugin marketplace. Desktop executor acceptance and optional
+voice providers need separate verification; CLI success is not GUI evidence.
+
+Beta acceptance: automated tests, packed installs and Docker fixtures only. Live
+provider onboarding and reboot verification are deferred, not marked passed.

package/CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# Contributing
+
+Humans, LLM agents and maintainers use the same small-PR process. Read AGENTS.md
+and the relevant CLI help first. Open an issue for substantial scope changes;
+small fixes need no proposal. Internal plans and private QA belong outside this
+repository. Public docs describe shipped behavior and explicit limitations.
+
+1. Fork/branch from main and make one coherent change. Preserve unrelated work.
+2. Install Node 22+ and pnpm 10.30.3. Run `pnpm install --frozen-lockfile`.
+3. Change the code, user instructions and focused tests together. Authority,
+   paths, credentials, cancellation and uncertain writes need negative tests.
+4. Run `pnpm verify`, `npm run release:check` and `git diff --check`.
+   Packaging/runtime changes also need the Docker checks in docs/releasing.md.
+5. Open a PR explaining the problem, resulting behavior, verification and limits.
+   Include a short sanitized reproduction. State which tests were not run.
+6. A maintainer reviews and merges after CI. Maintainers use PRs too. No CLA,
+   ticket requirement, custom commit format or additional approval committee.
+
+You are responsible for understanding submitted code, including AI-generated
+code, and having the right to contribute it under this repository's license.
+Do not upload conversation dumps, credentials, QR codes or customer records.
+Installation authority alone does not authorize messaging another person.
+Use synthetic providers for routine tests; live tests need a dedicated account
+and explicit recipient authority. A process exit is not provider delivery proof.
+
+Report bugs through a GitHub issue with version, OS, Node/Docker versions,
+minimal steps, expected/actual behavior and sanitized output. Feature requests
+should explain the user problem and a small acceptance example. Security reports
+follow SECURITY.md. Release and new-plugin requirements: docs/releasing.md and
+docs/plugin-contributions.md.
+
+## Isolated work and review
+
+- One coherent change, one branch, one dedicated Git worktree, one PR per
+  repository. Create the worktree from freshly fetched origin/main before edits.
+  Never develop on main or switch branches in another task's checkout.
+- Inspect git status and git worktree list first. Reuse a worktree only for the
+  same task. Preserve other work; never stash, reset or commit another task's
+  files. Stage explicit paths or hunks and review the staged diff before committing.
+- Keep worktrees outside the published package. Each task installs its own
+  dependencies and uses separate test state, ports and Docker project names.
+  Never share live bot tokens or provider profiles between test instances.
+- Keep unrelated fixes/features in separate PRs. For work spanning repositories,
+  create one worktree/PR per repository and link dependencies and merge order.
+  Branch from an unmerged feature only when the dependency is intentional and
+  documented; do not quietly include it in an unrelated PR.
+- Open a draft PR when the change is reviewable. Report its scope, exact commit,
+  validation and remaining QA. A completed coding task can remain a draft;
+  implementation completion does not authorize merge or npm publication.
+- Before merge, obtain an independent human or agent review of the final diff.
+  The implementer's self-check and passing CI are not independent review.
+  Reviewers inspect correctness, architecture, state/permissions and negative
+  cases. Record reviewer identity/session, reviewed commit, findings and resolution
+  in the PR. If review is unavailable, leave it explicitly pending.
+- New substantive commits or conflict resolutions invalidate the affected review
+  and test evidence. Refresh against current main, review the resulting diff and
+  run the applicable checks. Do not bypass protected-branch requirements.
+- Merge only after review, required CI, applicable QA and maintainer authorization.
+  Publish only under the separate release process; commits and merges are not
+  releases. Record which source commit and artifact hash were tested.
+- Keep the worktree while its PR or QA is open. After merge or explicit abandonment,
+  inspect it for uncommitted/untracked files and local-only commits. Remove only
+  the clean task worktree after valuable work is preserved; never force cleanup.
+  Delete its branch only after confirming merge or authorized abandonment.
+
+Example, substituting a unique task name and an absolute external directory:
+
+```sh
+git status --short
+git worktree list
+git fetch origin
+git worktree add -b feat/task-name /absolute/worktrees/task-name origin/main
+```

package/Dockerfile

@@ -0,0 +1,16 @@
+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 corepack enable && corepack prepare pnpm@10.30.3 --activate
+COPY package.json ./
+COPY docker/pnpm-lock.yaml ./pnpm-lock.yaml
+RUN pnpm install --frozen-lockfile --ignore-scripts
+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
+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"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ezenciel-agents contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+# ezenciel-agents
+
+Telegram `/status` shows the running relay and host
+versions plus installed plugin versions. The agent's `ez status` adds verified
+plugin runtime states and upgrade job receipts. See [status and upgrades](docs/upgrades.md).
+
+**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 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).
+GitHub remains under `jdorado`; npm uses `jc_stack`. Do not install the unrelated
+unscoped `ez-whatsapp` package.
+
+
+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.
+
+A minimal Telegram-to-AI-CLI relay. One owner, one persistent Markdown mind.
+
+## You are the installing agent
+
+If the user says **install** or **set up** this repository/package, complete
+[docs/setup.md](docs/setup.md) yourself. The instructions and commands in this
+repository are addressed to you, the LLM with computer access, not the human.
+
+**Your finish line is a working Telegram reply and automatic startup.** Adding
+npm dependencies, printing `--help`, or creating files is not completion.
+Install the main runtime alone first, with an empty plugin catalog. Even when
+WhatsApp is supplied or requested alongside it, defer plugin setup and QR scanning
+until owner pairing and a real agent reply are verified. Then the owner requests
+the plugin in Telegram and the installed agent handles onboarding there. The
+initial host CLI must not install the plugin on that agent's behalf.
+Do not hand the human terminal commands, ask them to start the relay, leave a
+terminal open, read logs, find their numeric Telegram ID, or approve pairing
+from another terminal. You own those steps and their verification.
+
+Only involve the human for missing account access, a bot token you cannot
+obtain through authorized tools, confirmation of which Telegram account is
+theirs, or an OS-level authorization prompt you cannot approve yourself. Give
+one concrete action at a time, with the exact link. Resume setup when they
+answer. Explain actual blockers in plain language.
+
+### Docker is installer work
+
+Docker and Compose are required, but they are **not a prerequisite the human
+must install**. First inspect the host. If Docker is absent, stopped, or lacks
+Compose, install the official supported Docker distribution for that operating
+system yourself, start it, and arrange the normal user access it requires.
+Then verify the engine and Compose with a harmless real container before
+building this package. Do not respond with “install Docker and retry,” a list
+of commands for the human, or a request to open a terminal.
+
+An administrator password, native system approval, or Docker Desktop sign-in
+dialog is a human-only boundary. When one appears, explain the single action
+needed and continue immediately after it. Everything else—package install,
+image build, host transport, Compose startup, pairing, and a real Telegram
+reply—is the installing LLM's job.
+
+### Recognize this artifact immediately
+
+This is a **Node.js npm package**, not a Python package or a Codex skill.
+For a supplied tarball, read `package/README.md` and `package/docs/setup.md`
+from that archive. Install that artifact; do not search npm, PyPI, or skill
+catalogs for its name. Build/run its Docker image; Docker and Compose are
+required on the host and the installing LLM makes them ready if needed. The
+image supplies relay dependencies; the existing host CLI supplies execution.
+
+Use the exact scoped npm name and version above, or the supplied tarball/path.
+A bare product name is not a package identity. Inspect the artifact before setup;
+do not substitute a similarly named package.
+
+### Installer tools
+
+Run these yourself from the installation directory. Read the setup guide for
+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 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-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 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 |
+
+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.
+
+## 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`, `USER.md`, and `TOOLS.md` are seeded; `MEMORY.md` is
+optional. 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.
+
+Telegram intake is owner-gated. The executor sends replies with the messaging
+CLI; stdout is not a reply. A process exit code is not delivery proof.
+Voice/media needs its additional providers and tools; defer optional setup
+until the owner asks. Do not advertise unverified integrations.
+
+For code development only: `pnpm install`, then `pnpm verify` for offline tests
+and TypeScript. `pnpm smoke` uses real providers and a paired owner; it verifies
+outbound delivery, not the full incoming Telegram path. Never publish publicly
+without authorization. Local registry rehearsal uses `pnpm publish:local`.
+
+- [Setup and troubleshooting](docs/setup.md)
+- [Architecture and run semantics](docs/architecture/telegram-intake.md)
+- [Saved AI choices](docs/architecture/ai-selection.md)
+- [Development and verification](docs/development-and-testing.md)
+- [Authority boundaries](docs/architecture/authority-boundaries.md)
+- [Security scope](SECURITY.md)
+
+- [Contributing](CONTRIBUTING.md) and [releasing](docs/releasing.md)
+- [First plugin and extension contract](docs/plugins.md)
+- [License and dependency notices](THIRD_PARTY_NOTICES.md)
+
+## Agent-owned upgrades
+
+This beta includes owner-policy release checks and durable
+main/plugin replacement. See [upgrade setup, tools and recovery](docs/upgrades.md). Earlier main upgrade/rollback VM QA passed; final-release fresh-host/reboot and live plugin upgrade acceptance remain pending.

package/SECURITY.md

@@ -0,0 +1,26 @@
+# Security
+
+Supported scope: the latest release, one paired Telegram owner per agent on a
+trusted host. Unknown senders/groups cannot acquire execution authority.
+The host CLI and plugin manager run with the host user's authority, including
+Docker administration. Environment filtering and container profile separation
+reduce accidental exposure; they do not isolate a hostile process from its own
+host user. Markdown roles and approvals are instructions, not an OS sandbox.
+Do not expose this as a public multi-tenant execution service.
+
+Keep Telegram tokens, device profiles, QR images, control state and native CLI
+sessions outside source and mind files. Treat incoming provider content as
+untrusted data. Do not bypass owner checks or silently retry uncertain writes.
+
+## Reporting
+
+On the public GitHub repository use Security → Report a vulnerability (private
+vulnerability reporting). Before publication the maintainer must enable and
+verify that channel. If it is unavailable, open an issue asking only for a private
+contact route; do not include exploit details or sensitive attachments publicly.
+Include affected version, sanitized reproduction, impact and suggested fix.
+There is no paid response SLA. Only the latest release receives fixes; report
+older-version findings with a reproduction on the latest version when possible.
+
+Current support target: the latest beta on a trusted single-user host. Report
+privately at https://github.com/jdorado/ez-agents/security/advisories/new.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,14 @@
+# Third-party software
+
+This repository's original source is MIT (LICENSE). Dependencies retain their
+own copyright and licenses; our LICENSE does not relicense them. Preserve the
+license files installed with every dependency and the frozen pnpm-lock.yaml.
+Node/Debian container layers and optional external CLIs have separate terms.
+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.

package/bin/ezenciel-agents

@@ -0,0 +1,2 @@
+#!/bin/sh
+exec node "$(dirname "$0")/ezenciel-agents.mjs" "$@"

package/bin/ezenciel-agents-ai

@@ -0,0 +1,2 @@
+#!/bin/sh
+exec node "$(dirname -- "$0")/ezenciel-agents-ai.mjs" "$@"

package/bin/ezenciel-agents-ai.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+const child=spawn(process.execPath,['--import',fileURLToPath(new URL('../node_modules/tsx/dist/loader.mjs',import.meta.url)),fileURLToPath(new URL('../src/ai-cli.ts',import.meta.url)),...process.argv.slice(2)],{stdio:'inherit'})
+child.on('exit',code=>{process.exitCode=code??1})

package/bin/ezenciel-agents-approval

@@ -0,0 +1,2 @@
+#!/bin/sh
+exec node "$(dirname "$0")/ezenciel-agents-approval.mjs" "$@"

package/bin/ezenciel-agents-approval.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', 'approval-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-create

@@ -0,0 +1,12 @@
+#!/bin/sh
+set -eu
+umask 077
+root=$(node -e 'const fs=require("node:fs"),path=require("node:path");process.stdout.write(path.dirname(path.dirname(fs.realpathSync(process.argv[1]))))' "$0")
+: "${EZ_AGENTS_HOME:?Set EZ_AGENTS_HOME to the absolute private installation registry}"
+case "$EZ_AGENTS_HOME" in /*) ;; *) echo 'EZ_AGENTS_HOME must be absolute' >&2; exit 1;; esac
+mkdir -p "$EZ_AGENTS_HOME"
+exec docker run --rm -i --user "$(id -u):$(id -g)" --cap-drop ALL --security-opt no-new-privileges \
+  --mount "type=bind,src=$EZ_AGENTS_HOME,dst=/installations" \
+  --entrypoint node "${EZ_RELAY_IMAGE:-ezenciel-agents:local}" \
+  --import /app/node_modules/tsx/dist/loader.mjs /app/src/agent-install.ts \
+  --host-root "$EZ_AGENTS_HOME" --compose-file "$root/compose.yaml" --relay-image "${EZ_RELAY_IMAGE:-ezenciel-agents:local}" "$@"

package/bin/ezenciel-agents-docker

@@ -0,0 +1,6 @@
+#!/bin/sh
+set -eu
+root=$(node -e 'const fs=require("node:fs"),path=require("node:path");process.stdout.write(path.dirname(path.dirname(fs.realpathSync(process.argv[1]))))' "$0")
+: "${EZ_DEPLOYMENT_DIR:?Set EZ_DEPLOYMENT_DIR to the absolute deployment directory containing docker.env}"
+case "$EZ_DEPLOYMENT_DIR" in /*) ;; *) echo 'EZ_DEPLOYMENT_DIR must be absolute' >&2; exit 1;; esac
+exec docker compose --project-directory "$root" --env-file "$EZ_DEPLOYMENT_DIR/docker.env" "$@"

package/bin/ezenciel-agents-host

@@ -0,0 +1,5 @@
+#!/bin/sh
+set -eu
+root=$(node -e 'const fs=require("node:fs"),path=require("node:path");process.stdout.write(path.dirname(path.dirname(fs.realpathSync(process.argv[1]))))' "$0")
+: "${EZ_DEPLOYMENT_DIR:?Set EZ_DEPLOYMENT_DIR to this agent deployment}"
+exec node "$root/src/updates/launch.mjs" "$EZ_DEPLOYMENT_DIR"

package/bin/ezenciel-agents-install

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

package/bin/ezenciel-agents-message

@@ -0,0 +1,2 @@
+#!/bin/sh
+exec node "$(dirname "$0")/ezenciel-agents-message.mjs" "$@"

package/bin/ezenciel-agents-message.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', 'message.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-owner

@@ -0,0 +1,2 @@
+#!/bin/sh
+exec node "$(dirname "$0")/ezenciel-agents-owner.mjs" "$@"

package/bin/ezenciel-agents-owner.mjs

@@ -0,0 +1,18 @@
+#!/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 tsx = require.resolve('tsx')
+const entry = join(here, '..', 'src', 'owner.ts')
+const forwarded = process.argv.slice(2).filter((arg) => arg !== '--')
+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/bin/ezenciel-agents-react

@@ -0,0 +1,2 @@
+#!/bin/sh
+exec node "$(dirname "$0")/ezenciel-agents-react.mjs" "$@"

package/bin/ezenciel-agents-react.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', 'react.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-setup.mjs

@@ -0,0 +1,18 @@
+#!/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 tsx = require.resolve('tsx')
+const entry = join(here, '..', 'src', 'setup.ts')
+const forwarded = process.argv.slice(2).filter((arg) => arg !== '--')
+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/bin/ezenciel-agents-source

@@ -0,0 +1,2 @@
+#!/bin/sh
+exec node "$(dirname "$0")/ezenciel-agents-source.mjs" "$@"