@jc_stack/ez-agents 0.1.0-beta.27 → 0.1.0-beta.28

package/docs/application-channel.md

@@ -0,0 +1,366 @@
+# Application input to the standard agent
+
+An installed application can submit work to the ordinary Ez agent. Ez uses its
+existing run queue, native executor, session store, cancellation and message
+outbox. The application supplies domain tools and keeps its UI/content API; it
+can remove its own model runner, continuation loop and engine authentication.
+This is separate from the older outbound channel-backend integration.
+
+## Shared runtime controls
+
+Register with `--share-owner` (the existing `--share-telegram` spelling is an
+alias) to grant access to the runtime's active conversation and standard AI
+settings. This explicit grant works with or without a Telegram bot. It grants
+control of the same active state Telegram uses when enabled; it is not a
+scope-only permission. Ordinary application bindings cannot read or change it.
+
+`GET /v1/control` returns the existing Ez AI presets, installed native model
+catalog, active control-session ID and conversations visible through `/chats`.
+Native engine session IDs and private application scopes are omitted. The token
+stays in the authenticated application backend, never in browser code.
+
+`POST /v1/control` accepts one action and the `expectedSession` returned by the
+last read (null before a conversation exists):
+
+| Action | Additional fields | Existing Ez operation |
+| --- | --- | --- |
+| `new` | None | `/new`, using the default AI |
+| `switch` | `sessionId` from the visible conversation list | `/chats` selection |
+| `select` | `presetId` from `ai.presets` | Select a saved AI |
+| `model` | `cli`, optional `model` and `effort`, from `models` | Save/select the same native choice as `/ai` |
+
+Engine changes start a fresh conversation through the same selection operation
+as Telegram. A changed active conversation rejects a stale mutation; refresh
+controls before another attempt. Model changes within one conversation retain
+the ordinary last-selection-wins behavior. Already-admitted runs keep their
+captured conversation and AI. Uncertain control responses require a fresh read,
+not blind repetition of `/new`.
+
+For private application conversations, `GET /v1/scope-control?scope=<encoded-scope>` returns
+the same catalog and the current scope's public control ID and preset. The scope
+is the application's original admission scope, resolved under its authenticated
+binding. `POST` accepts `new`, `select` and `model` with that scope's
+`expectedSession`. It does not require shared-control permission. Shared scopes
+must use `/v1/control` instead.
+
+A scope reset uses the configured default AI. A client change starts a fresh
+private conversation; a model change within the same client retains it. Retired
+private conversations stay hidden from `/chats`; admitted work can finish in its
+original native session. Neither operation changes the shared active selection.
+Control mutations are never marked retryable by the public client: read back
+after uncertainty before deciding on another change.
+
+Current HTTP gaps: rename/archive, scheduling
+administration and shared-chat stop-all are not exposed here. Per-run application
+cancellation remains available. The native agent can use the standard scheduler
+from an application turn; its replies retain that channel binding.
+
+## Install and authorize
+
+An installation has one owner, independent of its channels. As the installing
+administrator, outside an agent turn, generate a random 32-byte base64url token
+into a private file and register the first channel with a verified opaque owner ID:
+
+```sh
+ezenciel-agents-application --owner-id verified-account --id web --token-file /private/web-token --share-owner
+ezenciel-agents-application --id phone --token-file /private/phone-token --share-owner
+```
+
+The application backend receives that token through its secret store. Core stores
+only its SHA-256 digest, bound to the installation owner. Channel IDs are arbitrary
+labels, not a predefined provider list. The trusted adapter verifies its provider's
+identity (for example Privy); a browser-supplied owner ID is never authentication.
+For an existing Telegram owner, omit `--owner-id`: the new channel attaches to that
+same owner. `GET /v1/registration` returns the owner ID and binding ID.
+Revoke a channel with `--id web --revoke`. Rotate with `--id web --token-file
+/private/new-token --rotate`: the binding ID, retries and native sessions remain
+unchanged. Revoking the installation owner invalidates every channel.
+Revocation blocks admission, results and delivery and stops an active app run on
+the existing queue tick. `--list` exposes IDs, never tokens or hashes.
+
+This grant lets a **trusted application backend act for the paired owner**. It is
+not a multi-tenant filesystem sandbox. The application authenticates its users,
+derives their allowed scope, and enforces domain tool permissions. Independent
+owners or untrusted applications need separate agents/workspaces. Scoped sessions
+separate conversation history; they share the ordinary agent's filesystem and
+tool authority. Do not give this bearer token to browser JavaScript or models.
+
+Enable the optional listener in the relay environment:
+
+```dotenv
+EZ_APPLICATION_PORT=8787
+EZ_APPLICATION_HOST=0.0.0.0
+```
+
+The default bind address is loopback. In Docker, put the relay and backend on a
+private shared network and use `http://<relay-service>:8787`; do not publish a host
+port. Cross-host use requires HTTPS or an authenticated private tunnel. There is
+no listener unless a port is configured. This mode cannot be combined with the
+older channel-backend URL. Install core normally: its bin manifest makes the
+application administration command available through the standard tools setup.
+
+## Request and result
+
+All endpoints require `Authorization: Bearer <token>`.
+
+```text
+POST /v1/runs
+{"requestId":"job-123","scope":"principal:program","text":"Prepare our next lesson","context":{"reference":"lesson-1"}}
+
+GET /v1/runs/<id>
+GET /v1/runs
+GET /v1/registration
+POST /v1/runs/<id>/cancel
+```
+
+Submission returns HTTP 202; reads/cancellation return 200. Each response is:
+
+```json
+{"id":"r_app_...","scope":"principal:program","status":"queued","messages":[]}
+```
+
+Status is `queued`, `running`, `completed`, `failed` or `cancelled`. Messages are
+`{id,text}` records sent by the native agent through the existing message CLI.
+The backend polls and renders them; no raw native JSONL or Telegram messages are
+exposed. A delivery receipt means durable availability in the application inbox,
+not that a human read it. Failure adds a generic `error`; detailed logs remain
+local to core. Cancellation uses the existing child termination boundary and may
+return `running` until the process exits.
+
+`requestId` and `scope` accept 1–200 ASCII letters, digits, `_:.-`. Text is at most
+16,000 characters. Context is an optional JSON object (48 KiB); the complete HTTP
+body is bounded to 64 KiB. Unknown input fields are rejected. Use a stable job ID:
+retries with the same ID, scope and text return the original run and original
+context, even if the caller supplies refreshed context. Changed scope/text is a
+409 conflict. Persist the submitted context/capability for recovery, or poll the
+original run; retries never grant replacement authority to an admitted run.
+
+Context is opaque domain-tool data, not prompt text or an environment override.
+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.
+
+## Conversation continuity and migration
+
+Each application binding plus scope gets an existing core session. Its first run
+captures the selected engine/preset; later runs resume that same native session.
+Application sessions are excluded from the Telegram session selector. Engines
+that only resume an implicit latest session (`agy`) cannot serve isolated scopes.
+
+Before cutting over an existing application, stop its old runner, copy its native
+transcripts into the ordinary engine's private state, and import each authoritative
+scope pointer as the administrator:
+
+```sh
+ezenciel-agents-application --id myapp --import-scope principal:program \
+  --native-session NATIVE_SESSION_ID --cli codex
+```
+
+Do this before submitting work for that scope. Import does not copy transcripts,
+change the model preset, or merge histories. Verify the next real native turn
+recalls the intended history and the app renders its reply before removing the
+old deployment. Keep exactly one executor owner throughout the cutover.
+For an owner-chat channel registered with `--share-owner`, add `--share-owner`
+to the import command to select that imported conversation as the owner's current
+chat. Without it, the import remains scoped and does not switch owner chat.
+
+## Reviewed deployment migration
+
+The first upgrade adding the two optional application listener environment lines
+changes `compose.yaml`. The existing updater deliberately rejects that runtime
+shape change with “Runtime deployment changed; a separately reviewed migration is
+required.” Keep this guard. Installation requires a separately reviewed deployment
+migration before subsequent ordinary updates can use the new baseline.
+
+The operator verifies the immutable archive's SHA-256, extracts it into a new
+versioned package directory, copies `docker/pnpm-lock.yaml` to `pnpm-lock.yaml`,
+and installs frozen dependencies **inside that package root**. Verify the new
+application CLI and root-local `tsx` resolve. Build its runtime image without
+stopping or changing the existing agent. Then the authorized deployment owner
+switches the saved package/image binding using the standard host/update setup,
+preserving the agent's existing workspace, control, native engine state, owner
+pairing and plugin registry. Do not copy another agent's state or disable the
+updater's deployment compatibility check.
+
+For Docker applications, a deployment-owned overlay can attach the ordinary relay
+to an explicitly created private network shared with the application backend:
+
+```yaml
+services:
+  relay:
+    environment:
+      EZ_APPLICATION_PORT: "8787"
+      EZ_APPLICATION_HOST: "0.0.0.0"
+    networks:
+      default: {}
+      application:
+        aliases: [standard-agent]
+networks:
+  application:
+    external: true
+    name: ${EZ_APPLICATION_NETWORK:?Set the deployment-owned application network}
+```
+
+Create that network once through normal Docker administration; attach the backend
+to the same external network in its own deployment overlay. Preserve the default
+network. The backend connects to `http://standard-agent:8787`; no `ports` entry or
+host listener is required. Keep the overlay outside the package, owned by the
+deployment, and include it in that deployment's saved Compose invocation. This is
+an explicit network configuration, not a second runtime or automatic discovery
+service. Read back the loaded package/image and verify a real authenticated app
+request after switching; preparation and image build alone are not rollout.
+
+## Shared backend client and private principals
+
+Node backends can import `applicationBinding`, `applicationCall`, and
+`runApplication` from `@jc_stack/ez-agents/application-client`. This is a small
+HTTP client; core remains the sole owner of agent execution. Pin the package
+revision in the application's lockfile. Do not copy this client into each app.
+
+`applicationBinding(file, principalId)` reads a backend-private registry:
+
+```json
+{"version":1,"bindings":[
+  {"principalId":"verified-person-one","url":"http://person-one-agent:8787","tokenFile":"/run/secrets/person-one"},
+  {"principalId":"verified-person-two","url":"http://person-two-agent:8787","tokenFile":"/run/secrets/person-two"}
+]}
+```
+
+Resolve identity in the app before lookup. Unknown and revoked principals fail
+closed. Set `revoked:true` to remove a mapping from new lookup and revoke its
+core application grant to stop admitted work. Do not use a default owner's
+connection. Each endpoint must be a separate ordinary Ez deployment with private
+workspace, native CLI state, OS/container access and tools. The client rejects
+reused endpoint origins, but cannot prove that two DNS aliases name different
+containers. Provision isolation explicitly; this registry does not create it.
+The backend's registry and service credentials must not be mounted in an agent.
+
+The app keeps its existing user and coach/tutor grants. A delegated principal
+must be distinct from the learner's personal principal, and every domain tool
+must recheck the current grant. A coach can edit permitted learner records
+without inheriting the learner's private agent conversation. No new role system
+is required in Ez.
+
+Use `runApplication({requestId,scope,text,context}, connection)`. It returns the
+completed snapshot plus `reply`, the last nonempty message. An interrupted or
+invalid HTTP response reports a retryable transport error; the caller reconnects
+using the same persisted job ID and authority. The client does not resubmit by
+itself. `applicationCall('/v1/runs/<id>/cancel', {}, connection)` uses normal
+core cancellation. Aborting a local poll does not cancel admitted work.
+
+Snapshots also expose `sessionId`, `nativeSessionId` when known, and `cli`.
+An optional `expectedNativeSessionId` on submission is an assertion, never a
+session selector. It rejects a missing or different imported history before
+execution. Import old histories administratively before cutover. An optional
+`ai:{cli,model,effort}` uses the existing preset/effort contract; a scope keeps its
+CLI, while model/effort can change for later turns. Use distinct scopes for
+separate CLI histories. A retry cannot change an admitted turn's AI choice.
+
+## One owner across channels
+
+Register owner-chat channels with `--share-owner` and submit `followOwner:true`.
+Web, phone and Telegram then use the same selected native conversation and AI.
+This works without Telegram and requires no transcript replay or new runner.
+Scoped application conversations remain separate when the flag is omitted.
+Owner identity does not automatically merge histories or grant learner access.
+
+To link Telegram, enable its ordinary bot configuration, send a real DM, then
+approve the observed pending identity using `ezenciel-agents-owner approve ID`.
+`ezenciel-agents-owner unlink-telegram` removes that channel without removing the
+owner, application bindings or native sessions. Relinking does not authorize old
+Telegram deliveries. Linking other providers requires an authenticated adapter;
+registering the label `phone` does not install a phone service.
+
+The legacy `--share-telegram`, `--share-active` and `followTelegram:true` spellings remain supported.
+
+### Existing scoped Telegram sharing
+
+For an application using the ordinary agent's Telegram channel, the administrator
+may register its grant with `--share-telegram`. An ordinary application turn can
+then send `activateTelegram:true`: its scoped session becomes the owner's current
+Telegram conversation. Both inputs resume the same native history. Shared scopes
+appear in the existing `/chats` selector. Omit activation for temporary selection,
+extraction, and delegated work; those must not switch the personal conversation.
+Without the administrator's flag, application requests cannot switch Telegram.
+
+For a main chat that should follow the owner's current Telegram conversation,
+submit `followTelegram:true` under the same administrator-approved sharing grant.
+This uses the normal selected conversation and AI at admission, including after
+`/new`, `/chats`, or `/ai`. Do not also send `activateTelegram`, `ai`, or a native
+session assertion. Retries remain pinned to their originally admitted run even
+if the owner has since switched conversations. Keep exercise/detail scopes on
+the ordinary scoped path by omitting this flag.
+
+This shares native context, not an application's transcript database. Existing
+Telegram-to-backend integrations are a legacy limitation. Drain/reconcile their
+actual admitted runs before moving Telegram onto ordinary Ez transport and app
+admission onto this path. Do not introduce an application execution queue or
+route a channel-backend job into its own occupied execution queue.
+
+For backends holding a data lock across a native turn, `reconnect:true` keeps
+retrying transient transport failures with the same admitted request/GET until
+core reports the outcome. It never changes a job or capability. Do not apply a
+wall-clock abort that releases the data lock while remote execution continues.
+Persist a restart barrier before admission if backend restart could otherwise
+allow conflicting domain writes. Core remains the execution owner.
+
+A rejected submission includes `admitted:false` only when core can verify that
+no run exists for that binding/request ID. An existing conflicting run produces
+`admitted:true` and `runId`. Authentication or unreadable state may leave admission
+unknown. Backends may release a pending data barrier on explicit non-admission;
+a generic HTTP error or revoked credential alone is not proof of termination.
+
+## Application-only deployment (no Telegram bot)
+
+For a private per-user native runtime, set `EZ_TELEGRAM_ENABLED=false` and
+`EZ_APPLICATION_PORT` (plus `EZ_APPLICATION_HOST` when other containers connect).
+No bot token is required or used. This mode runs the existing native executor,
+application queue and application outbox without creating a Telegram client,
+starting Telegram sources/polling, or registering bot commands. Default deployments
+still enable Telegram and require its token.
+
+The installing administrator can initialize empty control authority and register
+an application in one local command:
+
+```sh
+ezenciel-agents-application --id web --token-file /run/private/application-token --owner-id VERIFIED_ACCOUNT_ID --share-owner
+```
+
+No Telegram ID is required or fabricated. Account identity remains server-resolved
+by the app and bound to its isolated runtime. Registration is unavailable inside
+agent turns and cannot replace an existing owner or adopt orphaned session state.
+Existing owners require no bootstrap. Tokens remain private; normal binding and
+run authorization checks still apply. The old numeric `--owner` option is retained
+only for compatibility, not recommended for new installations.
+
+Each learner/coach principal requires its own workspace, CLI state and isolated
+runtime. No separate bot is required. A channel is an authenticated route to its
+existing owner, not a new owner, scheduler or native execution engine.
+
+The standard scheduler, task controls and native delegation remain available.
+Schedules created during an application turn retain its binding and reply scope;
+scheduled replies use the normal outbox and appear in `GET /v1/runs` (100 channel
+runs per page), with their `originRunId`. Follow `nextCursor` through
+`GET /v1/runs?before=RUN_ID` until null to catch up after a disconnect; receipts
+from older origins must not be limited to the UI's current page. The backend projects these receipts into
+its UI; it does not schedule or execute work. Revoked channels cannot launch or
+receive scheduled work. Token rotation retains delivery. Telegram-specific intake
+and delivery require Telegram; pending Telegram work is never rerouted to web.
+
+When a private container supplies the isolation boundary and
+Codex cannot create its nested sandbox, its installing administrator may set
+`EZ_CODEX_SANDBOX=external` together with `EZ_EXECUTOR_TRANSPORT=local`.
+Local owner-authorized Codex app and Telegram turns use
+`--sandbox danger-full-access`. Native scheduled owner sessions use Codex's
+`externalSandbox` turn policy, with network access supplied by the container.
+The default remains `workspace-write`.
+Keep the container's private mounts, non-root UID, dropped capabilities and
+no-new-privileges policy; the agent can access everything mounted into it.
+Use standard root-start relay privilege separation when Telegram/provider
+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.

package/docs/docker-runtime.md

@@ -4,6 +4,11 @@ Docker Compose owns each relay and executable plugin. The CLI the user installs
 Ez from stays on the host, with its existing authentication. All agents in that
 installation use that CLI; there is no second CLI installation or agent-specific
 CLI login. The relay image contains Node, relay dependencies and ffmpeg.
+The runtime image exposes Ez commands through the wrappers in `/app/bin`, including
+`ezenciel-agents-application`; application images do not need to link Ez themselves.
+The image also installs package-manifest commands in `/usr/local/bin`, so native
+engine login shells can resolve them after resetting PATH. Command installation
+belongs to Ez packaging, not an application image or an engine-specific prompt.
 
 ## Agent binding
 
@@ -46,6 +51,21 @@ between jobs after adding a registry binding.
 
 ## Operate and verify
 
+Root-started containers default to executor UID/GID `1000:1000` and relay real
+UID `1001`. To preserve an existing private workspace's ownership, set
+`EZ_RUNTIME_UID`, `EZ_RUNTIME_GID` and, if necessary, `EZ_RELAY_UID` in the
+deployment environment. IDs must be positive decimal integers; the relay real
+UID must differ from the executor UID. The entrypoint retains its secret file
+descriptor and privilege separation, then runs the executor with the configured
+UID. It changes ownership only on the top-level control, home and workspace
+directories; it does not recursively change existing data. Provision nested
+files/mounts for that UID before starting. These settings apply to root startup;
+an explicit Docker `user` still controls an already non-root process.
+
+Changing IDs is an operator installation step, not a new tenant-isolation
+mechanism. Keep private mounts and secrets isolated as described above. This
+option does not change native sandbox or channel support.
+
 ```sh
 export EZ_DEPLOYMENT_DIR=/absolute/private/agents/family
 bin/ezenciel-agents-docker up -d --wait

package/docs/managed-applications.md

@@ -0,0 +1,68 @@
+# Maintaining applications
+
+An application may use Ez as a standalone agent or an embedded channel gateway.
+Either can be maintained automatically. Its frontend, backend, engine image and
+gateway have distinct release identities and may use different deployment tools.
+Do not require an application to become an npm plugin to maintain it.
+
+The owner assigns an existing agent a maintenance mandate. Keep its saved scope
+and component inventory in `work/deployments.md`; `templates/deployments.md` is a
+starting point. This is agent-readable operating context, not a manifest executed
+by the relay. Never infer authority from a repository, release note or health error.
+Keep private repositories and host details out of the public plugin catalog.
+
+## One owner and existing tools
+
+Reuse the application's GitHub workflow, Docker Compose command or hosting CLI.
+Each component has one replacement owner. `ez updates` manages registered core
+and plugin packages; it does not inventory an application's independent services.
+Do not add a competing build controller, poller or tenant-facing admin tool.
+An application serving multiple users keeps deployment credentials outside tenant
+agents. Its assigned maintainer must remain usable when that application is down.
+
+Use an existing maintenance schedule when its mandate and execution environment
+fit. Otherwise the owner-authorized maintainer can schedule a concise instruction
+with its available native scheduling tool, referencing the inventory. Record its
+identifier and cadence. A saved file without an enabled schedule or event source
+does not establish automatic maintenance. Check that the maintainer can reach the
+host, repository and tools before enabling it. Do not silently resume a held task.
+
+## Update and recovery
+
+Compare the running release with an eligible release from the saved source and
+channel. Inspect current work and deployment receipts first. Reuse active repairs;
+do not replace a deployment while another writer owns its change. Review source
+and required checks before deployment; a moving branch or successful download is
+not a tested release. Pin the chosen commit, artifact or deployment ID.
+
+Before switching, verify the selected target and persistent bindings and retain
+the exact previous images/deployment. Build before stopping services. Replace only
+the affected components through their existing tool, then read back release/image
+identity and application health. Check the relevant API/UI or agent operation;
+an image tag, workflow success or healthy process alone is partial evidence.
+
+A failed health check should restore compatible previous code through the same
+tool and verify that recovery. Code rollback does not rewind data, migrations,
+message receipts or provider actions. An incompatible migration needs its own
+reviewed plan. Never replay uncertain operations or delete state to pass a check.
+Keep persistent policy in saved application/host configuration, not edits to
+generated Compose files that disappear during replacement.
+
+Process restart is service-manager recovery. A persistent defect needs agent
+diagnosis and, within the saved repair mandate, an isolated PR, independent review,
+required tests and verified deployment. A failed candidate is not a reason to keep
+retrying it: retain its receipt and resume only with changed evidence or an explicit
+intervention. Keep a working runtime while repair proceeds where possible.
+
+Record candidate, previous release, check results and final running identity in a
+private receipt. Keep maintenance quiet when unchanged. Report a verified change,
+failed recovery or actionable blocker once; retain the next trigger for blocked
+work. Do not manufacture releases just to exercise the maintenance loop.
+
+## Acceptance
+
+Before calling a deployment self-maintaining, verify the enabled schedule/event,
+maintainer access, exact-version deployment and readback, configuration retention,
+and failed-health rollback in an isolated environment. Reconcile the live target
+after rollout. State separately which live API/UI or delivery paths were exercised
+and which still need evidence. Never test rollback by breaking a user's live app.

package/docs/plugin-catalog.md

@@ -12,6 +12,7 @@ has been published. Install only released plugins needed for the owner's request
 | [GitHub](https://github.com/jdorado/ez_github) | Create repositories, commit and push through native Git/gh with a private per-agent profile. Requires GitHub browser consent and Ez 0.1.0-beta.13 or newer. | `@jc_stack/ez-github` | [npm versions](https://www.npmjs.com/package/@jc_stack/ez-github?activeTab=versions) · [GitHub releases](https://github.com/jdorado/ez_github/releases) |
 | [Library](https://github.com/jdorado/ez-library) | Preserve agent files and attachments, extract PDF text, and retrieve notes with QMD. Optional GitHub/Drive/Dropbox persistence requires separate setup and authorization. | `@jc_stack/ez-library` | [npm versions](https://www.npmjs.com/package/@jc_stack/ez-library?activeTab=versions) · [GitHub releases](https://github.com/jdorado/ez-library/releases) |
 | [Resend](https://github.com/jdorado/ez-resend) | Receive Resend email into private idempotent receipts for agent-owned routing. Requires a Resend API key and an already-configured receiving domain. | `@jc_stack/ez-resend` | [npm versions](https://www.npmjs.com/package/@jc_stack/ez-resend?activeTab=versions) · [GitHub releases](https://github.com/jdorado/ez-resend/releases) |
+| [Voice](https://github.com/jdorado/ez-voice) | Talk with the agent through an authenticated realtime voice web client, with direct access to installed Ez tools. Requires an OpenAI API key, microphone access and Ez 0.1.0-beta.28 or newer. | `@jc_stack/ez-voice` | [npm versions](https://www.npmjs.com/package/@jc_stack/ez-voice?activeTab=versions) · [GitHub releases](https://github.com/jdorado/ez-voice/releases) |
 
 Release links are live records, not a guarantee that every registered package
 has a published version. Before installing, read npm metadata and the matching

package/docs/plugin-connection.md

@@ -0,0 +1,76 @@
+# Persistent plugin connection
+
+`ez tools connect <installed-alias> <literal arguments...>` attaches one Compose
+command container for a local, agent-bound client. It releases the registry lock
+after admission. Ordinary JSON objects travel as JSONL between client and plugin;
+this transport owns no inference, conversation history or plugin-specific tools.
+The local owning connection uses the agent's installed plugin permissions, just
+like its bound CLI. A remote or web adapter must authenticate its owner before
+connecting and protect its stdin. Plugin commands retain their own authorization;
+the connection adds no per-command permission prompt.
+
+Plugin requests use `{"coreRequest":{"id":"r1","method":"tools.list","params":{}}}`.
+Core answers `{"coreResponse":{"id":"r1","result":...}}` or `error` (a string).
+
+| Method | Parameters | Result |
+| --- | --- | --- |
+| `tools.list` | none | Array of alias, plugin, description, skillCount, revision |
+| `tools.help` | alias | CLI `--help` result: code, stdout, stderr |
+| `tools.skill` | alias, index, optional line | Declared skill text and nextLine; index starts at zero, line at one |
+| `tools.invoke` | alias, args (literal string array), optional stdin and output filename | CLI result: code, stdout, stderr; optional artifact path, bytes, sha256 |
+| `tools.native.list` | none | Core command descriptions and availability |
+| `tools.native` | command, args (literal argument array) | Native CLI result: code, stdout, stderr |
+
+`tools.native` invokes only the shipped `schedule` or `message` CLI, using the
+owning host's verified workspace/control binding and a whitelisted environment.
+Read `--help` for its command contract; this connection requires inline `--text`
+and rejects `--text-file` so it cannot read arbitrary host files. `create --now` submits standard
+asynchronous native work; it does not launch a second runner or hold the workspace
+lease while waiting. The native agent may retrieve a Library original, inspect it
+with its existing image/PDF tools, and save source-linked searchable text.
+Scheduler owner checks, selected engine, cancellation and receipts remain native.
+No synthetic run context is injected. Standalone bindings cannot use this method;
+task creation without a Telegram owner or authenticated originating channel still
+fails under the scheduler's existing delivery rule. Results can be inspected with
+`runs` and `run RUN_ID`; a completed run alone is not proof of indexed content.
+
+Message delivery captures the paired owner and pairing epoch when the connection
+opens. Core injects that context; tool arguments cannot select a recipient or
+replace it. The message CLI enqueues the existing outbox without creating an agent
+run, and the relay rechecks the owner before sending. Revocation or re-pairing
+invalidates the connection. Inline text and workspace documents use the same
+Telegram delivery and receipt path as native runs. Text-file input is unavailable.
+History still requires a native run; `message receipt OUTBOX_ID` reconciles a
+channel send against the current owner's outbox. Sends return a queued ID then
+wait up to 20 seconds for delivery; queued or unknown never means sent, and must
+not be retried without receipt readback. An accepted send may finish after the
+voice connection closes. Omitting command retains schedule compatibility.
+
+For binary plugin output, supply a simple `output` filename. Core saves at most
+20 MiB of stdout in a unique private workspace artifact and returns its relative
+path, byte count and SHA-256 instead of binary model text. Only successful command
+output is saved. The message CLI can send that path with `--document`; both host
+admission and relay delivery enforce workspace containment.
+
+The registry is read on each request. The connected plugin is excluded, including
+its other aliases. Skill reads stay within its declared source directory and
+return at most 100 lines. Invocations execute once through the registered binding;
+a changed plugin revision requires rediscovery. Client stdin cannot forge core
+requests or responses. The plugin may send `coreCancel: {id}` to cancel its own
+pending request. Request IDs cannot be reused within a connection.
+
+Commands use the existing bound Compose dispatcher, literal argv and whitelisted
+environment. Calls have a 30-second timeout and 256 KiB combined output limit;
+connection frames are limited to 1 MiB. Connection closure aborts pending calls
+and removes their exact command containers. There is no automatic retry.
+
+Arbitrary calls take the same fail-fast workspace lease as non-scheduled native
+jobs. Native work stays pending while a call runs; calls refuse pending/running
+native work. Ordinary CLI calls inside an admitted native job do not reacquire
+the lease. Isolated scheduled work keeps its existing workspace behavior. A stale
+native `workspace-writer.lock` is recovered at host startup only after its host
+owner is dead and startup has checked previous native processes. A stale plugin
+lease stops admission with an explicit error: an operator must verify its command
+containers stopped before removing the lock. A dead bridge alone is insufficient.
+This guard requires the updated host worker. Direct external writers are outside
+the managed admission boundary.

package/docs/plugins.md

@@ -263,10 +263,10 @@ Shared workers have a hard Docker CPU quota of half a core by default, across al
 
 ## Existing local folders
 
-Use operator-owned read-only folder bindings when a plugin needs files that
+Use operator-owned folder bindings when a plugin needs files that
 already exist on the host. Keep indexes and writable metadata in the plugin's
 normal volume. This uses Docker bind mounts; it copies no source bytes and
-starts no provider sync. File edits remain with the host's existing tools.
+starts no provider sync. Read-only is the default.
 
 Stop the plugin before changing a binding:
 
@@ -288,8 +288,8 @@ volume contents; inspect those before restarting to avoid using stale files.
 Never enable another sync writer for an already synchronized host folder.
 
 For Library, create/select the library name first and retain its QMD state while
-binding the host tree at that library's `files` directory. Keep provider bindings
-disabled for that source. Enable the normal shared embedding worker through
+binding the host tree at that library's `files` directory. Enable provider bindings
+only when that plugin supports the selected host folder and owns its sync. Enable the normal shared embedding worker through
 `plugins shared-enable library embeddings`. Verify `library sources`, real search,
 and original readback from the actual executor. Document any differences between
 indexed snapshots and current originals; do not replace Library with private
@@ -307,3 +307,39 @@ on the next read, without hooks, LLM calls or a cached inventory file.
 contains only the agent-bound discovery shortcut. New workspaces do not seed
 TOOLS.md; upgrades preserve legacy notes without rewriting them. Keep owner/account
 policies in agent instructions or linked policy files, separate from plugin metadata.
+
+Folder bindings default to read-only. For an explicitly authorized plugin that
+updates the existing source, add `--writable` to `folder-bind` while the plugin
+is stopped. The grant applies only to that folder and survives compatible
+upgrades. Rebind without `--writable` to return it to read-only. Package
+descriptors cannot request this grant. Keep one synchronization owner for each
+source; a writable mount alone does not configure synchronization.
+
+## Browser endpoints for connected plugins
+
+`ez tools serve HOST_PORT:CONTAINER_PORT ALIAS ARGS...` runs a plugin's web command
+inside its command container while core handles the existing persistent tool
+protocol. Both ports must be 1024–65535. Publication is always on host 127.0.0.1;
+no plugin manifest can request public ingress. Run the foreground command under
+the host's normal service supervisor if it must survive terminal closure. SIGINT
+or SIGTERM cancels the connection and removes its command container.
+
+The plugin owns HTTP, browser authentication, sessions and static assets. HTTPS
+termination, DNS and forwarding are explicit operator configuration. Plugins may
+use the read-only `tools.owner` core request to check the current paired private
+Telegram user and opaque pairing epoch. This is identity data, not an access grant;
+the plugin must authenticate the requester and recheck identity on protected requests.
+No owner returns null, and no bot token is exposed. Standard plugin CLI operations
+still enforce their normal permissions. See the Voice plugin's README for a client.
+
+To add an optional launcher without replacing Telegram's command menu, set the
+relay Compose environment or `.env` (then recreate the relay container):
+
+```dotenv
+EZ_TELEGRAM_WEB_APP={"command":"voice","label":"Voice","url":"https://voice.example.com/"}
+```
+
+The command returns a Mini App button to the authenticated owner in private chat;
+`/menu` includes the same button. Reserved commands cannot be replaced. The HTTPS
+URL must not contain credentials, query parameters or a fragment. This setting
+only registers a launcher; it does not expose a port or authenticate web requests.

package/docs/upgrades.md

@@ -1,5 +1,10 @@
 # Agent-owned software upgrades
 
+For an application's independently deployed frontend, backend or embedded gateway,
+see [managed applications](managed-applications.md). They use their existing
+deployment tools and a saved maintenance mandate; this package updater inventories
+only core and registered plugins.
+
 Available in this beta. Earlier main upgrade/rollback VM QA passed; final-release
 fresh-host/reboot and live plugin upgrade acceptance remain pending. npm
 publication is not required to test this feature. The beta channel is the default
@@ -14,7 +19,12 @@ runs the normal CLI transport. It checks npm every six hours while running and
 queues an owner-bound maintenance turn only when an automatic channel changes.
 No owner means no maintenance executor. Normal user work and maintenance share
 one serial queue. Checks use the installed scoped npm identity; failures are
-visible in `updates check` and private `tools/updates/available.json`.
+visible in `updates check` and private `tools/updates/available.json`. Plugins marked
+`private: true` in their package metadata are reported as local-source updates
+only, without querying public npm; this does not mean they are up to date.
+Explicit local-file updates retain the existing release-contract checks; plugins
+without that contract use their reviewed local-source installation procedure.
+Public packages still receive discovery checks under a manual policy.
 
 ## Installation and scope