@jc_stack/ez-agents 0.1.0-beta.31 → 0.1.0-beta.32

package/AGENTS.md

@@ -94,7 +94,7 @@ Measure progress by usable outcomes and feedback, not code or test volume.
 
 ## 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.
-- Unapproved group messages from other senders and unknown DMs fail silently. Approved group text uses the existing conversation grant and restricted task runner. Paired-owner group text is discovery routed to the owner's private chat; it grants no group reply authority.
+- Unapproved group messages from other senders and unknown DMs fail silently unless an exact-contact or any-conversation owner-approved channel grant admits them. Both grant types use the restricted task runner. Paired-owner group text is discovery routed to the owner's private chat; it grants no group reply authority.
 - Stopping work (`/stop`) must terminate the active worker PID immediately (`SIGTERM`, escalating to `SIGKILL` if unclosed after 3s).
 
 ## 8. Mandatory Adversarial & Negative Tests

package/CHANGELOG.md

@@ -1,6 +1,31 @@
 # Changelog
 
-## Unreleased
+## 0.1.0-beta.32
+
+- Add shared authenticated inbound attachment staging for application and
+  Telegram channels, preserving literal comments and immutable retries.
+- Support separately scoped host-owned writable workspaces.
+- Reconcile reused host-lock PIDs using process birth identity while failing
+  closed on unknown or matching live-process identity.
+- Accept bounded scheduler recovery identifiers and preserve reviewed package
+  modes when extracting under a restrictive umask.
+- Allow concurrent plugin commands, scoped approved outgoing files, and the
+  host CLI configuration needed for restricted read-only plugin commands.
+- Clarify domain-agent positioning while preserving native engine ownership.
+
+- 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,
+  while audio, cross-turn, unrelated elicitations and approvals remain declined.
+- Restore `codex-gui` tasks when newer Codex Desktop builds do not create the
+  legacy control socket at app launch: invoke the native idempotent app-server
+  daemon start command and retry the desktop connection once, while retaining
+  fail-closed behavior and never falling back to headless execution.
+- Add owner-approved, provider-neutral public channel grants so restricted fresh
+  agent runs can answer any private chat or mentioned group on one enabled source.
+  Grants may expose only fixed, read-only query aliases such as Library search;
+  they retain no owner memory, recheck revocation around every operation, and
+  enforce persisted concurrency, traffic, receipt and evidence bounds.
 
 ## 0.1.0-beta.31
 

package/README.md

@@ -1,14 +1,20 @@
-# Ez — AI assistants for small businesses
+# Ez — Build domain-expert AI agents on the harnesses you already use
 
-**A lightweight, open-source foundation for persistent AI assistants, powered by
-existing AI harnesses.** Give an assistant a purpose, a workspace and tools for
-your business, then work with it through chat.
+**The open-source composition layer for turning Codex, Grok and other native
+agent harnesses into persistent, tool-using specialists.**
 
-Ez is for owners of shops, studios and small teams who want help doing everyday
-work: preparing quotes, maintaining business records, researching decisions or
-following up on an agreed task. Each assistant has its own working context and
-responsibilities. The tools and permissions you configure determine what it can
-do.
+Combine domain knowledge, portable plugins, messaging, scheduling and explicit
+authority around the AI tools you already have. Start with one useful agent and
+grow into a team whose responsibilities, accounts and access remain clear.
+
+Ez does not replace your agent engine or hide it behind another platform. The
+native harness keeps ownership of reasoning, sessions, tools and delegation. Ez
+connects that intelligence to a durable workspace, real applications, trusted
+people and the operational controls required to work reliably.
+
+Use Ez for a personal project, a specialist research system or an operating role
+inside a startup or small business. Each agent gets a defined domain, its own
+working context and only the tools and authority its job requires.
 
 ## Engine and application boundaries
 
@@ -58,20 +64,20 @@ not implemented. The legacy channel-backend mode delegates execution and changes
 standard controls, so it does not meet this integration boundary. New integrations
 use the [native application channel](docs/application-channel.md).
 
-## What makes an Ez assistant
+## What makes an Ez domain agent
 
 | Part | What it contributes |
 |---|---|
-| **Workspace** | Markdown instructions, business context and working files that persist across conversations and changes of AI. |
+| **Workspace** | Markdown instructions, domain knowledge and working files that persist across conversations and changes of AI. |
 | **Native engine** | Inference, native sessions, context management and tool execution. See [AI selection](docs/architecture/ai-selection.md). |
 | **Authority** | A verified owner and explicit limits on delegated work. Receiving a message or installing a tool does not grant permission to act. |
 | **Plugins** | Documented CLI commands and agent instructions for application capabilities. Commands enforce authentication, authorization, validation and canonical persistence directly or through authoritative application services. |
 | **Ez transport and runtime** | Channel delivery, scheduling and standard runtime controls around the native engine. |
 
-The design starts with one assistant, one mind and clear responsibilities.
-Business instructions live in the workspace; reusable capabilities live in tools
-and plugins. The agent decides how to do the work using those instructions and
-the capabilities available to it.
+The design starts with one agent, one domain and clear responsibilities. Domain
+instructions live in the workspace; reusable capabilities live in tools and
+plugins. The agent decides how to do the work using those instructions and the
+capabilities available to it.
 
 Use the engine's native capabilities when they meet the need. Add a standalone
 plugin when a missing integration earns the maintenance. Ez keeps the surrounding
@@ -81,9 +87,9 @@ clients improve.
 ## Plugin catalog
 
 Browse the [available plugins](docs/plugin-catalog.md) for capabilities you can
-add to your assistant. The first released plugin is
+add to an agent. The first released plugin is
 [WhatsApp](https://github.com/jdorado/ez-whatsapp), which connects an existing
-WhatsApp account. Ask your working Ez assistant to set it up in Telegram.
+WhatsApp account. Ask your working Ez agent to set it up in Telegram.
 
 ## Start with one useful job
 
@@ -97,12 +103,12 @@ requested, keep each workspace's authority and registry explicit.
 Ask an AI agent with computer access to install Ez for a concrete purpose:
 
 > Install Ez from https://github.com/jdorado/ez-agents for my business.
-> I want an assistant that helps me prepare customer quotes from my own files.
+> I want a quoting specialist that works from my own files.
 > Set it up and verify that I can talk to it in Telegram.
 
 The installing agent follows [the setup guide](docs/setup.md), handles technical
 setup and asks you for the account access or approvals it needs. Once the
-assistant replies in Telegram, explain your business, give it the relevant
+agent replies in Telegram, explain the domain, give it the relevant
 materials and request any additional tools there. Integrations require their
 own setup and authorized accounts.
 
@@ -111,21 +117,26 @@ own setup and authorized accounts.
 The current source supports persistent agent workspaces, a choice of host AI
 executors, owner-gated Telegram messaging, native scheduling, plugin lifecycle
 management and bounded, owner-approved correspondence. A messaging task can
-contact one approved person using only its explicitly shared task context;
+serve one approved conversation or, after an explicit broad approval, anyone on
+one capable source. Restricted runs receive only their shared context and exact
+installed read-only query capabilities; they do not inherit the owner workspace
+or tools.
+The built-in Telegram source supports text in private chats and groups;
 restricted task execution currently requires the pinned Codex runtime. See
 [authority boundaries](docs/architecture/authority-boundaries.md) for the exact
 scope and [scheduling](docs/scheduling.md) for scheduled work.
 
-The broader direction is assistants working across business roles, with deliberate
+The broader direction is agents working across distinct domains, with deliberate
 workspace sharing and authority over who may direct work, see information and
-use accounts. General team delegation, family/group authority and enterprise
-reviewer roles remain future work. The current trusted-host beta is not an
+use accounts. General team delegation and enterprise reviewer roles remain
+future work. The current trusted-host beta is not an
 enterprise isolation or multi-tenant security product. See [security scope](SECURITY.md).
 
 ## For agents discovering this repository
 
-Ez may fit when a user needs a persistent business assistant reachable through
-chat, using an existing AI client and separately installed tools. Start here:
+Ez may fit when a user needs a persistent domain-specific AI agent reachable
+through chat, using an existing AI client and separately installed tools. Start
+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).

package/docs/application-channel.md

@@ -140,8 +140,12 @@ The existing `ezenciel-agents-schedule context` exposes it as
 `run.application.context` only to the current native run. Domain tools and their
 filesystem mounts are installed using ordinary Ez plugin/runtime setup. No API
 field selects a native session, working directory, process environment or owner.
-This first version transports text only, without file delivery, reactions or
-approval UI.
+This version transports text plus core approval requests, without file delivery
+or reactions. Run snapshots include `approvals: [{id,prompt,state}]`. Render the
+prompt verbatim and POST `{"decision":"approved"}` or
+`{"decision":"denied"}` to `/v1/approvals/TASK_ID` with the same bearer
+credential. Core binds the decision to the authenticated owner generation; the
+application must not infer or auto-submit consent.
 
 ## Conversation continuity and migration
 
@@ -364,3 +368,26 @@ secrets are present; do not put those secrets in a same-UID process environment
 or readable mount. This setting is rejected for host/backend execution and
 restricted delegated tasks, and cannot be selected by an application request.
 It is not forwarded to the host executor.
+
+## Generic inbound attachments
+
+`POST /v1/runs` (and `runApplication`) accepts one optional
+`attachment: {name, data}`, where `data` is canonical padded base64 of the file
+bytes. `text` remains the literal user comment and may be empty with an attachment.
+JPEG, PNG, WebP, PDF and UTF-8 TXT/Markdown (`.txt`, `.md`, `.markdown`) are supported,
+up to 10 MiB decoded; empty files and other types are rejected. Core detects file
+content rather than trusting a client MIME label. This same limit and staging
+contract apply to Telegram photo/document input.
+
+Authentication precedes staging. Core stages the file privately in the ordinary
+workspace inbox and uses the same attachment metadata and literal comment as
+Telegram. The existing run queue, native executor, selected AI and native session
+remain authoritative; applications must not extract, summarize, convert or build
+attachment prompts. Use `followOwner:true` for the shared owner conversation.
+Retry the same request ID, filename, bytes and literal comment; conflicts return
+409 and successful retries do not stage another file. A failed admission removes
+its staged file; a process crash may leave an unused inbox file, never a runnable
+partial request. Separate owner runtimes must retain separate workspace mounts.
+
+This is inbound file support. Application replies currently deliver text only;
+outgoing file downloads remain unsupported by this HTTP channel.

package/docs/architecture/ai-selection.md

@@ -14,7 +14,16 @@ Grok/Claude accept caller-selected native UUIDs. Codex/OpenCode generate IDs, so
 the adapter reads only their typed JSONL session metadata; stdout never becomes a
 Telegram reply. `codex-gui` is a separate desktop adapter: it submits a dedicated
 app-server thread/turn and waits for that turn to finish. It does not run
-`codex exec`. A missing or mismatched native session fails closed, not `--last`.
+`codex exec`. If the native control socket is absent, the adapter asks the
+installed Codex CLI to idempotently start its own app-server daemon, then retries
+the connection once. It does not implement another daemon or fall back to the
+headless CLI. A missing or mismatched native session fails closed, not `--last`.
+Native server requests use their method-specific response schema. Scheduled turns
+use on-request approval routing so browser elicitations reach the adapter, which
+accepts only the active turn's session-scoped HTTPS browser-origin and Computer
+Use Chrome app requests. Interactive turns remain non-interactive. Audio,
+cross-turn, command, file and unrelated requests are declined rather than being
+guessed or forwarded to a hidden task UI.
 Legacy unbound sessions require the owner's explicit `/new`.
 
 References used for the adapter contract:

package/docs/architecture/authority-boundaries.md

@@ -1,6 +1,7 @@
 # Authority boundaries
 
-The core pairs one Telegram owner and owns authority across providers. Plugins
+The core binds one owner identity, optionally linked to Telegram or an
+application channel, and owns authority across providers. Plugins
 provide transport, authentication, capture, and receipts. Their exposure metadata
 is discovery information, never a grant. A CRM can contain external text too;
 marking it internal does not confer owner authority.
@@ -17,7 +18,8 @@ owner does not edit JSON. The agent uses `list` and `revoke` when asked.
 After approval the relay starts a restricted task, including the initial outgoing
 message. Incoming-only tasks instead wait for new correspondence and never create
 an opening run. Their task records use version 2 so older task readers fail closed. Matching new correspondence resumes that task in a fresh native session.
-Other contacts remain blocked. Finite tasks have at most 30 distinct text sends;
+Other contacts remain blocked unless an owner-approved any-conversation grant is
+active for that source. Finite tasks have at most 30 distinct text sends;
 there are no payments, attachments, extra recipients, plugin installation,
 settings changes, or access to owner memory. A contact can have one active or
 pending task at a time. Completed, revoked, expired, replaced-source, and changed-
@@ -30,6 +32,46 @@ that each sentence serves the booking or that a correspondent is truthful. A
 prompt injection can still derail a task or elicit its shared context. It cannot
 use the provided tools to read owner files or select another destination.
 
+## Channel audiences and capabilities
+
+Version-4 grants may bind the audience to every conversation captured by one
+registered event source. The source must advertise `wildcardWatch` and implement
+`task-watch`/`task-unwatch` for conversation `*`. The grant is incoming-only and
+active until owner revocation. It does not grant other sources, owner controls,
+the owner session, owner files or conversation history. Each run contains events
+from exactly one provider conversation, replies only to that captured
+conversation and exposes no cross-conversation notes. Exact-contact grants remain
+the default.
+
+Public admission is capped at eight outstanding conversations, 60 conversations
+and 60 replies per hour, and 1,000 conversations or replies across the life of a
+grant. The cumulative limit revokes the grant and requires fresh owner review.
+Terminal public-run evidence retains the most recent 100 released runs per grant;
+unreleased runs remain durable for retry. Released provider events and accepted
+Telegram send receipts are also bounded.
+
+A channel grant may include up to eight owner-approved query capabilities. Each is an
+exact registered `ez` command plus fixed arguments ending in literal
+`-- {input}`. The restricted broker replaces only `{input}` with the
+correspondent's string; the model cannot select a command, prepend flags, choose
+a recipient, access a shell or change the fixed arguments. The full command
+vector and disclosure scope appear in the immutable owner approval. Core rechecks
+the grant immediately before and after invocation and before every reply. The
+installed alias must declare `channelQuery: true` and explicitly declare that it
+accepts external input without external sends, record changes, or interactive
+review; core revalidates this trusted installed manifest before execution. Output
+is bounded to 128 KiB and may be disclosed to the approved audience; stderr and
+process credentials are not exposed. Tool output and incoming messages remain
+untrusted source material.
+
+Capabilities are a core channel permission, not a plugin permission system.
+Domain tools remain ordinary reviewed CLIs and enforce their own authentication,
+resource authorization, validation, persistence and receipts. For example, an
+installed Library can supply a dedicated fixed read-only search alias. Do not
+grant lifecycle/admin commands or an operation with
+unbounded or uncertain external effects through this query-shaped interface.
+Those require a purpose-built tool contract with its own idempotency and receipts.
+
 ## Ongoing conversation permissions
 
 Incoming-only proposals may use `--until-revoked` for an ongoing conversation.
@@ -42,14 +84,15 @@ later replies. The runner gets current-run receipts and rolling group-only notes
 receive the largest supported timestamp for the watch; the core still checks
 revocation before every operation. Older versions reject version-3 grants.
 
-The native Telegram source implements the existing provider protocol for exact
-group IDs. It records selected text messages and sender identity, and sends only
-to the bound group with durable uncertain/accepted receipts. Bot messages and
+The native Telegram source implements the provider protocol for exact private or
+group IDs and wildcard audiences. It records selected text messages and sender
+identity, and sends only to the concrete captured chat with durable
+uncertain/accepted receipts. Bot messages and
 anonymous-admin posts are excluded by intake. Unselected owner group text remains
 private discovery; other unselected group messages cannot launch work. Source
 registration enables discovery, never reply permission. Voice and attachments are
 not handled by this group adapter. WhatsApp continues using its existing adapter;
-group and ongoing watch support requires the companion provider update. Older
+group, ongoing and wildcard watch support depends on the companion provider. Older
 adapters reject ongoing grants at proposal time. Pending watch removals retry
 after service outages; core revocation blocks sends immediately.
 
@@ -69,9 +112,11 @@ tool discovery. Model metadata can override feature flags, so flags alone are
 insufficient. The native inventory test uses a real bundled model entry and must
 prove the five bounded task tools work without additional action tools.
 
-A core stdio MCP broker exposes `context`, `send`, `note`, `report`, and `complete`.
+A core stdio MCP broker exposes `context`, `send`, `note`, `report`, and `complete`,
+plus only the exact capabilities recorded in the grant. Any-conversation runs omit
+cross-conversation note/report/complete tools.
 The native client also lists resource helpers, but the broker serves no resources.
-Only these five tools have native approval bypass configured: the core rechecks
+Only these tools have native approval bypass configured: the core rechecks
 the grant on each call. Broker requests cross host/relay through private atomic
 control files; only the relay dispatches provider writes. Model tool arguments
 never choose a recipient, account, control path, shell command, or permission.
@@ -80,8 +125,9 @@ containment, not isolation from a malicious native executable or local host user
 Native configuration reference: [Codex configuration](https://learn.chatgpt.com/docs/config-file/config-reference).
 
 Task notes live under protected `control/tasks/`, separate from the owner mind.
-Reports go to the owner's Telegram outbox, visibly labelled as task reports;
-they are not inserted as owner instructions or trusted memory. The owner mind
+Exact-contact task reports currently use the linked Telegram owner outbox and
+are visibly labelled; any-conversation runs have no report tool. Reports are not
+inserted as owner instructions or trusted memory. The owner mind
 keeps its existing `inbox/` and `work/` organization. No database or general memory
 index is introduced.
 
@@ -92,6 +138,8 @@ stable string `accountId` in `events-head`. The core calls `task-watch` with tha
 account, exact `conversationId`, and expiry to request bounded capture attention.
 The existing events/events-check protocol supplies incoming messages. This
 subscription grants attention only; execution still requires the core grant.
+Sources that support an any-conversation grant additionally advertise
+`wildcardWatch: true` and accept `*` only for watch/unwatch, never as a send target.
 
 For sends the core supplies `task-send` with those same bound IDs, text, and a
 core-prefixed idempotency key. The adapter checks account consistency immediately
@@ -116,7 +164,9 @@ records, but cannot launch task work.
 Unmatched events retain terminal `cancelled` plus
 `external-execution-unavailable`. Task runs use record version 2; older readers
 reject/skip them instead of executing them with owner access. Existing version-1
-owner runs remain readable. Package state schema stays 1, but rollback suspends
+owner runs remain readable. Older task readers reject version-4 wildcard grants;
+approval prompt changes also fail closed if a capability-bearing older record is
+read after rollback. Package state schema stays 1, but rollback suspends
 task processing until a task-aware version returns; rollback does not replay
 messages or erase task receipts. Update host and relay together. A missing or
 outdated host fails task launch closed.
@@ -124,9 +174,9 @@ outdated host fails task launch closed.
 The installing host user remains trusted and can modify local control state.
 Owner runs can use the plugin manager and Docker administration; content read
 inside owner work still depends on native protections and agent judgment. This
-is not a public multi-tenant execution service. Family delegation, payments,
-enterprise reviewer agents, arbitrary file sharing, and other restricted native
-executors are deferred.
+is an owner-configured channel service, not a general multi-tenant execution
+platform. Payments, enterprise reviewer agents, arbitrary file sharing and
+unrestricted delegated executors are deferred.
 
 Verify with `pnpm verify`, Docker test/runtime targets and smoke fixtures.
 `EZ_TEST_NATIVE_TASKS=1 pnpm exec tsx --test test/task-native.test.ts` checks the

package/docs/architecture/event-sources.md

@@ -31,9 +31,16 @@ creation; it does not promise exactly-once external actions after executor failu
 
 Before starting queued work, recheck binding, owner and provider eligibility.
 Unavailable sources keep work queued; removed subscriptions cancel empty runs.
-No check can retract work already started. Eligible external runs are now recorded
-as blocked (`external-execution-unavailable`), with no executor launch. They do
-not borrow the owner workspace, session or tools. The existing source cursor and
-deduplication remain intact; blocked work does not retry automatically. Work status
-shows the blocked count. No provider SDK or provider-specific authority is imported.
+Events matching exactly one active core task launch its restricted fresh-session
+runner; unmatched events are recorded as blocked (`external-execution-unavailable`)
+with no executor launch. Neither borrows the owner workspace, session or tools.
+Any-conversation tasks admit at most one outstanding run per conversation and
+eight across the public source queue, with persisted limits of 60 conversations
+and 60 replies per hour and 1,000 across a grant. The cumulative limit revokes
+the grant. Owner work is preferred and preempts an active public run. Terminal
+history retains the latest 100 released runs per public grant; providers supporting
+`releaseEvents` are told to discard terminal source events. Release completion is
+persisted, and a failed release is retried before that run can be pruned. The source cursor and
+deterministic run IDs preserve replay. No provider SDK or provider-specific
+authority is imported into core.
 See [authority boundaries](authority-boundaries.md).

package/docs/architecture/telegram-intake.md

@@ -2,7 +2,7 @@
 
 One owner, one bot, one relay writer per control directory. No database, extra agent, or executor loop.
 
-1. Gate the sender and private chat before accepting work. Text from the paired owner in a group is recorded only for discovery and routed to the owner's private chat; other group senders are ignored. Group controls, anonymous administrators and group replies are unsupported.
+1. Gate the sender and chat before accepting work. Text from the paired owner in an unbound group is recorded only for discovery and routed to the owner's private chat. Other private/group senders are ignored unless the built-in source has an active exact or wildcard core grant. Group controls and anonymous administrators remain unsupported.
 2. Atomically save the raw update and deduplicate its Telegram update ID in `EZ_CONTROL_DIR/inbox.json`.
 3. Collect a short burst before downloading/transcribing. Seal batch membership on disk, then normalize in receive order. Captions, album IDs and quoted context travel with the media.
 4. Create one durable run using the batch's stable ID. A restart between run creation and intake completion finds that same run; it does not create a second job.

package/docs/host-service.md

@@ -89,6 +89,9 @@ preserving it rather than reverting to a different or expired host login.
 An agent binding may set `sharedWorkspace` to an absolute canonical application
 repository. The host resolves its canonical path, adds that directory to Codex
 write permissions for chat and scheduled jobs, including symlink aliases.
+If the agent needs more than one separately scoped writable directory, keep the
+canonical application in `sharedWorkspace` and list the others as absolute paths
+in `additionalWorkspaces`; do not grant a broader common parent.
 The host claims requests independently; a running job does not block another
 request sharing its workspace. The selected engine owns execution concurrency.
 Task sessions and artifacts remain isolated. The binding is host-owned and cannot

package/docs/plugin-contributions.md

@@ -18,6 +18,8 @@ Before the first PR, provide:
 - Per-command exposure declarations for external reads, external sends, record
   changes and requested review; see [plugin metadata](plugins.md#exposure-declarations).
   These are self-reported capabilities, never permission grants or safety certificates.
+  A dedicated query-only alias may opt into restricted channel use with
+  `channelQuery: true` and the required explicit non-writing exposure fields.
 - Private state locations, start/stop/status, backup, migration/rollback limits,
   data-preserving uninstall and separate account revocation instructions.
 - Offline contract/negative tests and CI. Verify snapshot installation and CLI

package/docs/plugins.md

@@ -168,6 +168,29 @@ attention during setup/use; it does not enable an automated reviewer. Declaring
 false never grants permissions, disables core checks or certifies a plugin safe.
 The core owns authority; plugins own provider transport/authentication/receipts.
 
+A command may additionally set `"channelQuery": true` only when all four
+exposure fields are explicit and describe external input with no external send,
+record change, or interactive review. This is narrow eligibility for inclusion
+in an owner-approved restricted channel grant, not an activated permission or a
+safety label for the rest of the plugin. Mixed read/write aliases are ineligible;
+publish a dedicated query-only alias.
+
+For original file bytes, declare `"channelFile": true` instead, with the same
+read-only exposure fields. The approved task capability must specify
+`"output": "file"`. Its command accepts one literal input and writes only the
+file bytes to stdout (maximum 20 MiB across a run). Core returns an attachment ID and filename
+to the agent; binary content stays in private task staging. The input basename
+supplies the download filename.
+
+The task's existing `send` tool accepts `attachmentId` plus text and an
+idempotency key. Only a completed file capability from that run can supply it.
+The destination remains the authorized conversation. Providers opt in through
+`events-head.taskAttachments: true`, optionally declaring `attachmentCaptionLimit`,
+and accept the attachment metadata in `task-send`. Telegram delivers a document
+with a caption of at most 1024 characters; channels without this contract fail
+explicitly before dispatch. Staged bytes are removed when the external run is
+released. File capability access must be included in the owner's grant.
+
 Owner adapters retain owner access. External correspondence can run only in an
 approved core messaging task through the restricted task runner. Declarations
 and monitoring subscriptions alone never grant task execution. See

package/docs/responsive-channels.md

@@ -12,4 +12,7 @@ the message CLI. Native final text is not automatically delivered to Telegram.
 
 Restricted correspondence receives a typed activation event and scoped tools.
 Authorization, sandboxing and tool handlers enforce contact and lifecycle limits.
+An owner-approved channel capability adds only a fixed installed alias declared
+as a read-only channel query; it does not expose the workspace, shell, owner
+session or other installed tools.
 Maintenance and group notifications carry event data; CLI help owns operations.

package/docs/selective-monitoring.md

@@ -12,8 +12,9 @@ is a reminder, never an activated source, watch or reply permission.
 Keep mode names internal. Linking/syncing an account defaults to quiet capture;
 finish connection verification, then at most one short optional prompt such as
 “WhatsApp is connected. Want me to follow up with anyone?” Do not present a
-technical three-mode menu or suggest blanket autonomous replies that v1 cannot
-safely authorize. If the owner already gave a job, continue it without this prompt.
+technical three-mode menu. Suggest an any-conversation reply grant only when the
+owner has actually asked to serve everyone on that source. If the owner already
+gave a job, continue it without this prompt.
 
 Infer the complete job from ordinary language:
 
@@ -42,7 +43,8 @@ when it matters to that proposed job; never silently expand or renew permission.
 - Selected: wake for named contacts only. Never turn on all-inbox mode to satisfy
   a one-contact request.
 - All: attention for all eligible incoming contacts; requires that broader
-  owner request. Attention alone never grants autonomous reply permission.
+  owner request. Attention alone never grants autonomous reply permission; a
+  separate approved any-conversation task does.
 
 For an approved core reply task, the provider's task-watch supplies expiring
 selected attention even if its general policy remains manual. That is expected:
@@ -95,6 +97,56 @@ members of that approved group may converse; this does not grant owner tools.
 The group runs with the existing restricted messaging runner, and its notes are
 separate from private PA memory. Group text is supported; media is not yet.
 
+## Everyone on an enabled channel
+
+When the owner explicitly asks to answer anyone on one channel, propose one
+incoming-only `--any-conversation` grant for that registered source. The flag
+also selects `--until-revoked` and contact `*`. Do not widen “this group,” “this
+person,” or “customers in this list” into everyone. The source must support a
+wildcard watch; otherwise report that adapter gap without inventing a parallel
+poller. Telegram's built-in source supports private chats and groups. Other
+channels use the same core grant when their adapter advertises the same event-
+source contract. Authenticated owner application channels remain owner routes;
+an untrusted web, voice or phone audience needs an event-source adapter and this
+grant.
+
+Capabilities are optional and provider-neutral. Put an array in a private
+capability file; each entry has `id`, `description`, registered `command`, and a
+fixed `args` array ending in `"--", "{input}"`. Example for an already installed
+Library source:
+
+```json
+[
+  {
+    "id": "knowledge",
+    "description": "Search the approved public Library source",
+    "command": "library-query",
+    "args": ["--library", "public", "--limit", "5", "--", "{input}"]
+  }
+]
+```
+
+The registered alias must declare `channelQuery: true` with explicit exposure
+metadata showing that it accepts external input but cannot send, change records,
+or require interactive review. Core verifies that installed declaration on every
+invocation. Verify the selected source and query alias first, then propose:
+
+```sh
+ezenciel-agents-task propose --source telegram --any-conversation \
+  --purpose "Answer questions using approved public knowledge" \
+  --context-file work/public-answer-policy.txt \
+  --capability-file work/public-answer-capabilities.json
+```
+
+The approval names the audience, disclosure context and exact command vectors.
+Command output may be shown to anyone in that audience. External writes need
+their own bounded tool contract and receipts. Revocation stops new capture,
+cancels queued replies and rechecks every tool/send. Public Telegram groups must
+mention or reply to the bot; one conversation can have only one outstanding run
+and the source-wide public backlog is bounded. Core admits at most 60 public
+conversations and 60 replies per hour. A grant revokes after 1,000 conversations
+or replies so the owner must review continued broad access.
+
 The core presents the exact proposal for owner confirmation. Ordinary messages
 inside that grant need no repeated confirmations. Incoming-only grants create
 no initial run or opening message. They remain active across replies until expiry

package/docs/setup.md

@@ -19,7 +19,8 @@ Make the bot a group admin so Telegram delivers ordinary member messages and
 allows membership verification for approval and control buttons. Group ownership only authorizes
 the exact approved chat, not other groups or members' private DMs. Telegram group
 migration to a new chat ID requires a new explicit binding. Verify a real group
-reply before considering setup complete. All other groups retain their existing
+reply before considering setup complete. Unless an explicit any-conversation
+grant is active, all other groups retain their existing
 restricted conversation-grant behavior.
 
 Ez supports two independent, composable uses: an autonomous Telegram agent and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jc_stack/ez-agents",
-  "version": "0.1.0-beta.31",
+  "version": "0.1.0-beta.32",
   "private": false,
   "type": "module",
   "description": "A lightweight foundation for persistent business AI assistants using existing AI harnesses, workspaces and plugins.",