@arnilo/prism 0.7.0 → 0.8.0

package/docs/sheets.md

@@ -1,8 +1,8 @@
-# Spreadsheets, CSV parsing, and typed schema inference (`@arnilo/prism-office/sheets`)
+# Spreadsheets, CSV parsing, and typed schema inference (`@arnilo/prism-work/sheets`)
 
 ## What it does
 
-The `@arnilo/prism-office/sheets` package provides fail-closed, high-fidelity spreadsheet (XLSX) and delimiter-separated (CSV/TSV/PSV) data ingestion with automatic dialect sniffing, typed column schema inference, and **strict financial decimal safety**.
+The `@arnilo/prism-work/sheets` package provides fail-closed, high-fidelity spreadsheet (XLSX) and delimiter-separated (CSV/TSV/PSV) data ingestion with automatic dialect sniffing, typed column schema inference, and **strict financial decimal safety**.
 
 ### Headline Guarantee: Strict Financial Decimal Safety
 
@@ -10,7 +10,7 @@ The `@arnilo/prism-office/sheets` package provides fail-closed, high-fidelity sp
 > **Zero Float Coercion on Decimal Paths**:
 > In financial and enterprise data processing, floating-point rounding errors (IEEE-754 `double`) silently distort monetary totals, balance ledgers, and transaction reconciliations.
 >
-> In `@arnilo/prism-office/sheets`:
+> In `@arnilo/prism-work/sheets`:
 > - Money-like and decimal values are **never converted to JavaScript numbers (`Number()`, `parseFloat()`, or unary `+`)**.
 > - All decimal and currency values are parsed, normalized, and emitted as exact canonical decimal strings: `{ type: "decimal", value: "1234.56" }`.
 > - Currency markers (`$`, `€`, `£`, `¥`, `₹`, `CHF`, `USD`, `EUR`, etc.) and accounting parentheses `($1,234.56)` are normalized safely into canonical strings (`"-1234.56"`).
@@ -29,7 +29,7 @@ The `@arnilo/prism-office/sheets` package provides fail-closed, high-fidelity sp
 
 ## When to use it
 
-Use `@arnilo/prism-office/sheets` when autonomous agents, data pipelines, or enterprise workflows need to:
+Use `@arnilo/prism-work/sheets` when autonomous agents, data pipelines, or enterprise workflows need to:
 1. Ingest untrusted customer XLSX or CSV files with strict, unbypassable byte, row, column, and sheet caps.
 2. Parse tabular financial records, invoices, ledgers, or pricing sheets with mathematical decimal precision guarantees.
 3. Automatically determine CSV delimiters, quotes, and headers without manual dialect configuration.
@@ -151,7 +151,7 @@ TXN-1003,"Hardware Device","£ 2,500.00",2500.00,"$ 0.00"
 ## Implementation example
 
 ```ts
-import { parseWorkbook, parseCsv, type SheetsTelemetry } from "@arnilo/prism-office/sheets";
+import { parseWorkbook, parseCsv, type SheetsTelemetry } from "@arnilo/prism-work/sheets";
 
 // 1. Parse XLSX workbook with custom caps
 const xlsxBytes = new Uint8Array([...]); // Untrusted file bytes
@@ -194,7 +194,7 @@ console.log(`Revenue value:`, csvResult.rows[1][2]);
 ## Extension and configuration notes
 
 ### Sub-package Pinning
-To avoid pulling in CLI frameworks or extraneous dependencies, `@arnilo/prism-office/sheets` directly pins the exact underlying modular packages:
+To avoid pulling in CLI frameworks or extraneous dependencies, `@arnilo/prism-work/sheets` directly pins the exact underlying modular packages:
 - `@office-open/xlsx@0.12.3`
 - `@office-open/xml@0.12.3`
 
@@ -211,7 +211,7 @@ const telemetry: SheetsTelemetry = {
 ```
 
 ### Self-Hosting & Operational Notes
-- **Zero Network & Storage Dependencies**: `@arnilo/prism-office/sheets` does not write files or contact network services. Host engines own persistence, storage buckets, and lake datasets.
+- **Zero Network & Storage Dependencies**: `@arnilo/prism-work/sheets` does not write files or contact network services. Host engines own persistence, storage buckets, and lake datasets.
 - **Fail-Closed Container Gating**: Malicious or non-standard files are rejected before allocation or XML decompression occurs.
 
 ## Security and performance notes
@@ -224,6 +224,6 @@ const telemetry: SheetsTelemetry = {
 
 ## Related APIs
 
-- [`@arnilo/prism-office/documents`](./documents.md): Specification-compliant OpenXML document generation, parsing, patching, and preview rendering for DOCX, XLSX, and PPTX.
-- [`@arnilo/prism-coding-tools/document-reader`](./document-reader.md): Bounded literal text extraction from PDF and DOCX documents for coding agent tools.
+- [`@arnilo/prism-work/documents`](./documents.md): Specification-compliant OpenXML document generation, parsing, patching, and preview rendering for DOCX, XLSX, and PPTX.
+- [`@arnilo/prism-work/document-reader`](./document-reader.md): Bounded literal text extraction from PDF and DOCX documents for coding agent tools.
 - [`@arnilo/prism-core/governance/observability`](./observability.md): OpenTelemetry instrumentation and trace adapters.

package/docs/signal-channel.md

@@ -0,0 +1,112 @@
+# Signal channel (experimental)
+
+## What it does
+
+`@arnilo/prism-channels/signal` is a Node-only, experimental adapter for an **externally supervised** [signal-cli v0.14.8](https://github.com/AsamK/signal-cli/tree/v0.14.8) Unix-socket daemon. It is not an official Signal bot API, does not make a bot official, and must be enabled only after an operator records the acceptable-use and GPL distribution decisions required for its deployment.
+
+Importing or constructing the adapter does nothing: it never downloads, spawns, registers, links, relinks, configures, or health-checks `signal-cli`; opens no network connection; and has no environment or credential lookup. Host owns that lifecycle, account, state directory, encryption, backup/retention and process supervisor.
+
+## When to use it
+
+Use only after an operator records acceptable-use and GPL distribution decisions for an already-operated Signal account. Not an official bot API; not for groups, topics, attachments, identity linking, bulk messaging (including `MessagingRuntime.notify`, which is unicast to one existing DM binding only), automated account creation, or streaming previews (Signal has no Bot API draft equivalent, so this adapter ignores `MessagingRuntimeOptions.onAssistantDelta`).
+
+```bash
+npm install @arnilo/prism @arnilo/prism-channels
+```
+
+## Inputs / request
+
+`SignalAdapterOptions`: host `connectionId`, absolute private `socketPath`, daemon `account`, `signalCliVersion` (must equal `SIGNAL_CLI_VERSION`), `policy` attestation, and service-owned `checkpoints`/`leases`/`cursorOwnership`. `signal-cli` is a host-operated binary, not an npm peer.
+
+## Host setup
+
+Use only a private, host-selected Unix socket on the same Node/Linux host. Do not expose a TCP or HTTP bridge. Protect socket parent/state directories with service-only permissions (for example `0700`) and protect backups. Signal transport decrypts at `signal-cli`; Prism stores and model providers receive plaintext according to host policy.
+
+The supported daemon shape is manual receive mode, selected by the host for the pinned CLI version:
+
+```sh
+signal-cli --data-dir /private/prism-signal -a +15550001111 \
+  daemon --socket=/private/run/prism-signal.sock --receive-mode=manual
+```
+
+`signal-cli` is GPLv3 and its upstream compatibility can change after Signal service changes. It requires the pinned release's documented JRE/native dependencies (v0.14.8 documents JRE 25). Account registration/relinking may disrupt existing clients; never automate it from Prism or chat input. Consult current Signal terms and operator policy before enabling automated replies; terms/policy can prohibit an intended deployment.
+
+## Request/response example
+
+```ts
+import { createMessagingRuntime } from "@arnilo/prism-channels";
+import { createSignalAdapter, SIGNAL_CLI_VERSION } from "@arnilo/prism-channels/signal";
+
+const adapter = createSignalAdapter({
+  connectionId: "support-signal",
+  socketPath: "/private/run/prism-signal.sock",
+  account: "+15550001111",       // host daemon account, never taken from a message
+  signalCliVersion: SIGNAL_CLI_VERSION,
+  policy: {
+    acceptableUse: "operator_approved",
+    gplDistribution: "operator_approved",
+    termsVersion: "2026-09-review", // host's recorded policy review, not a Signal approval
+  },
+  checkpoints: serviceCheckpoints,
+  leases: serviceLeases,
+  cursorOwnership: { tenantId: "signal-service" },
+  // multiAccount: true, // only for a daemon where account is supplied on RPC requests
+});
+
+const runtime = createMessagingRuntime({
+  authorize: hostAuthorizeSignalSender, // verify observed Signal UUID -> Prism identity/grant
+  resolveAgent: hostResolveAgent,
+  deliver: (reply) => adapter.send(reply),
+  checkpoints: userCheckpoints,
+  leases: userLeases,
+});
+
+await adapter.start((event) => runtime.admit(event));
+// Shutdown: await adapter.stop(); await runtime.stop();
+```
+
+## Implementation example
+
+[`examples/signal-agent.ts`](../examples/signal-agent.ts) contains the same host composition helper.
+
+`start()` acquires `prism.channels.v1.signal.receiver`, probes its checkpoint writer, connects the persistent Unix socket, then calls only `subscribeReceive`. It renews its receiver lease; loss fails closed by pausing intake. `stop()` unsubscribes when possible, closes its socket, aborts reconnection and releases only its lease. A second receiver under the same service ownership cannot subscribe.
+
+The adapter accepts manual `params.result.envelope` notifications only when they name the selected account and contain a direct text `dataMessage` from a valid Signal UUID. It ignores receipts, sync echoes, reactions, stories, edits, groups (including group topics, which have no supported thread mapping) and attachments before `admit`. UUID (not display name or phone number) becomes the external actor/conversation ID; the runtime must still authorize it. An account mismatch pauses the adapter before admission. `health()` reports independent bounded `bridge`, `subscription`, and `account` states for host monitoring without message text, phone numbers, socket path or key material.
+
+## Outputs / response / events
+
+`send()` accepts only replies for its configured `connectionId` and a UUID destination fixed by the runtime's authorized binding. It calls only `send`; chat text cannot choose an RPC method, account, socket, recipient or identity action. Replies are plain text and chunked at 2,000 UTF-16 code units without splitting surrogate pairs.
+
+A server-issued approval control is rendered as plain reply text:
+
+```text
+Reply /approve <opaque-token> to allow once.
+Reply /deny <opaque-token> to deny.
+```
+
+Only the shared runtime validates and consumes that opaque token. Free-form text remains untrusted input; no Signal reaction, attachment, identity-trust or linking action is exposed.
+
+Known daemon errors map to a bounded reason (`signal_rate_limited`, `signal_captcha_required`, `signal_relink_required`, `signal_identity_changed`, or `signal_rpc_error`). A changed/untrusted identity stops normal sends until an operator verifies it and current authorization is re-established. Timeout/socket loss after a write — or a failure after an earlier chunk — throws an ambiguous-delivery error; the durable reply journal records `delivery_unknown` and must not automatically resend it.
+
+## Extension and configuration notes
+
+| Setting | Default | Range |
+| --- | ---: | ---: |
+| JSON-RPC line/frame | 128 KiB | 1 KiB–512 KiB |
+| Pending RPC requests | 16 | 1–64 |
+| Pending admitted notifications | 32 | 1–128 |
+| RPC timeout | 10 s | 100 ms–60 s |
+| Reconnect delay | 1 s | 1 ms–60 s (exponential, 30 s default max) |
+| Receiver lease | 90 s | 5 s–5 min |
+| Outbound chunk | 2,000 UTF-16 units | fixed |
+
+The adapter pauses/unsubscribes on journal admission capacity/storage failure, malformed/oversized frames, account mismatch, or lease loss. It reconnects with bounded backoff after an established bridge loss and rechecks writer readiness before subscribing. It has **no documented application acknowledgment or replay log**: a daemon notification received before a crash and before durable commit can be lost. This adapter does not claim lossless intake, exactly-once execution, message read status, or end-to-end encryption through a model/provider.
+
+## Security and performance notes
+
+Construction is inert: no spawn, TCP/HTTP, environment lookup, or credential read. Chat text cannot choose RPC method, account, socket, recipient, or identity action. UUID (not phone or display name) is the only observed actor id. A changed identity stops sends until an operator verifies it. Receive-to-commit can lose a notification; treat that as a documented loss window, not a retry.
+
+## Related APIs
+
+- [Messaging channels](messaging-channels.md): authorization and durable replies.
+- [Messaging channel operations](messaging-channel-operations.md): recovery and operator review.

package/docs/speech.md

@@ -14,7 +14,11 @@ and `runTranscriptionConformance` from `@arnilo/prism/testing/provider-conforman
 ## When to use it
 
 Use it for one-shot voice output and batch/stream transcription where the host
-owns playback, capture, and audio storage. Do not use it for interactive
+owns playback, capture, and audio storage. Messaging hosts wrap these providers
+and hand the wrappers to a channel adapter — Telegram `transcribe` turns an
+inbound voice note into turn text and `synthesize` adds a voice note next to a
+final reply ([telegram-channel.md](telegram-channel.md)); `@arnilo/prism-channels`
+never imports this package and never stores audio. Do not use it for interactive
 bidirectional voice — that is the Realtime session contract
 ([`RealtimeSession`](public-contracts.md)), which keeps its own
 `audio_delta`/`transcript_delta` events. Streaming here is one-directional:

package/docs/sqlite-persistence.md

@@ -54,7 +54,7 @@ import { createSqlitePersistence } from "@arnilo/prism-core/sessions/sqlite";
 | `SessionStore.readBranchPath` | Recursive ancestor query from `leafId` (or latest leaf) in root→leaf order. |
 | `RunLedger.append*` | Inserts run/event/tool/usage rows; events receive monotonic per-run `sequence` values. |
 | `ProductionPersistenceStore.query*` | Parameterized cursor pagination on indexed columns. |
-| `checkpoints` | Generic versioned `CheckpointStore` backed by `prism_checkpoints`; ownership, CAS/fencing checks, bounded pagination, and workflow suspended/denied/schedule/state/replay values without a schema migration. |
+| `checkpoints` | Generic versioned `CheckpointStore` backed by `prism_checkpoints`; ownership, CAS/fencing checks, bounded pagination, and workflow suspended/denied/schedule/state/replay values without a schema migration. A load or delete under a non-matching ownership scope reads as absent and a cross-scope write fails as a generic `ERR_PRISM_CHECKPOINT_CONFLICT` (plan 080 Task 3) — no ownership-shaped existence oracle. |
 | `leases` | Atomic `LeaseStore` backed by `prism_leases`; database-clock expiry, opaque renew/release token, monotonic takeover fence. |
 | `close()` | Closes the underlying database when the adapter opened it. |
 

package/docs/telegram-channel.md

@@ -0,0 +1,157 @@
+# Telegram channel
+
+## What it does
+
+`@arnilo/prism-channels/telegram` is framework-free Telegram Bot API transport for text, with bounded attachment handling. It uses native `fetch`; importing it or creating a factory starts no listener, poller, credential lookup, environment lookup, or network request.
+
+## When to use it
+
+Use for official Telegram Bot API text and bounded media. Private DMs are the default; group/supergroup text (including forum topics) is opt-in per adapter with `allowGroups: true` and stays subject to host `authorize`. Optional ephemeral streaming previews (`sendDrafts`) are private-chat only. Opt-in host hooks add voice transcription, document extraction and speech synthesis; images reach a model only when it declares image input. Not for Secret Chats, unbounded or stored media, or model-selected destinations.
+
+Install peer and channel package:
+
+```bash
+npm install @arnilo/prism @arnilo/prism-channels
+```
+
+## Inputs / request
+
+`TelegramAdapterOptions` (polling): host `connectionId`, `botToken` (`CredentialValueSource`), service-owned `checkpoints`/`leases`/`cursorOwnership`, optional `allowGroups`, `sendDrafts`, `maxAttachmentBytes`, `transcribe`, `synthesize` and `extractDocumentText`. `TelegramWebhookHandlerOptions` add independent `webhookSecret` and the `admit` callback (intake only — outbound sends, drafts and `fetchAttachment` use an adapter instance, which works without `start()`). Importing or constructing starts no network.
+
+## Request/response example
+
+Polling is explicit and restart-safe only with a service-owned `CheckpointStore` cursor and `LeaseStore` receiver lease. `start()` verifies the token with `getMe`, refuses to poll if `getWebhookInfo` reports an existing webhook, then runs 30-second `getUpdates` requests. It accepts private `message.text`/`caption` updates from non-bot senders, plus `group`/`supergroup` text and media when `allowGroups: true`. `photo`, `voice` and `document` become bounded attachment *refs* — see [Attachments and voice](#attachments-and-voice). Service, edit and bot-echo updates are acknowledged without agent execution, as are channel/anonymous-admin `sender_chat` messages and forum topics that fail the host grant.
+
+A parsed group message keeps the admission keys transport-exact: `externalConversationId` is the chat id (negative for groups), `externalActorId` is `from.id`, and `message_thread_id` becomes `threadId`. Only `claims` carry untrusted context (`chatType`, `isForum`, `forwarded`), and `authorize` receives them so a host can refuse forwarded messages or non-forum groups. Threads and senders are separate sessions and separate grants: a grant for `(chat A, topic 7, user X)` admits neither user Y, chat B, nor topic 8.
+
+```ts
+import { createMessagingRuntime } from "@arnilo/prism-channels";
+import { createTelegramAdapter } from "@arnilo/prism-channels/telegram";
+
+const adapter = createTelegramAdapter({
+  connectionId: "support-telegram",
+  botToken: hostCredentials.telegramBotToken, // string, function, or CredentialValueSource
+  checkpoints: serviceCheckpoints,
+  leases: serviceLeases,
+  cursorOwnership: { tenantId: "service" }, // service scope, not a Telegram claim
+  allowGroups: true, // opt-in groups/topics; still deny-by-default at authorize()
+  maxAttachmentBytes: 1024 * 1024, // per `getFile` download; hard ceiling 4 MiB
+  transcribe: (audio, format) => transcription.transcribe({ model: "whisper-1", audio, format }), // voice -> turn text
+  synthesize: (text) => speech.synthesize({ model: "tts-1", input: text }), // text -> voice note, final replies only
+  extractDocumentText: (bytes, mimeType) => hostExtractor(bytes, mimeType), // documents are inert without this
+});
+
+const runtime = createMessagingRuntime({
+  // Exact observed tuple: chat id, optional topic id, sender id. Display names are never keys.
+  authorize: ({ externalConversationId, threadId, externalActorId, claims }) =>
+    claims?.forwarded === true
+      ? false
+      : (hostGrants.get(externalConversationId, threadId, externalActorId) ?? false),
+  resolveAgent: hostResolveAgent,
+  deliver: (reply) => adapter.send(reply),
+  onAssistantDelta: (delta) => adapter.sendDraft(delta), // opt-in previews; needs sendDrafts: true
+  fetchAttachment: (ref) => adapter.fetchAttachment(ref), // lets a model that declares image input receive the image
+  checkpoints: userCheckpoints,
+  leases: userLeases,
+});
+
+await adapter.start((event) => runtime.admit(event));
+// shutdown: await adapter.stop(); await runtime.stop();
+```
+
+[`examples/telegram-agent.ts`](../examples/telegram-agent.ts) exposes same composition as a host-supplied helper.
+
+The adapter awaits `runtime.admit()` before advancing `offset`. Return the admission result from the callback: `capacity`, `unavailable`, and `stopped` keep Telegram's update unacknowledged; all other settled dispositions advance the durable cursor. The operation journal then deduplicates any replay before model or tool work.
+
+A connection receiver lease (`prism.channels.v1.telegram.receiver`) is held for the poll loop. A second poller or a webhook worker using the same `connectionId`, service ownership and `LeaseStore` receives no work. This fences stored intake state; it cannot retract an already accepted platform request from a paused process.
+
+## Implementation example
+
+Mount `createTelegramWebhookHandler` on a host HTTPS route. It is a Web-standard `(Request) => Promise<Response>` handler; Prism does not create a listener, configure DNS/TLS, or call `setWebhook` for you.
+
+```ts
+import { createTelegramWebhookHandler } from "@arnilo/prism-channels/telegram";
+
+const telegramWebhook = createTelegramWebhookHandler({
+  connectionId: "support-telegram",
+  botToken: hostCredentials.telegramBotToken,
+  webhookSecret: hostSecrets.telegramWebhookSecret, // 1–256 URL-safe characters
+  admit: (event) => runtime.admit(event),
+  leases: serviceLeases,
+  cursorOwnership: { tenantId: "service" },
+  allowGroups: true, // must match the poller you are replacing
+});
+
+// Example host adapter: route only this fixed HTTPS path to telegramWebhook(request).
+```
+
+Configure Telegram deliberately after the route, TLS and independent secret exist. Do not set `drop_pending_updates` and do not remove an active webhook merely to switch modes.
+
+```sh
+curl --fail-with-body \
+  -H 'content-type: application/json' \
+  -d '{"url":"https://bot.example/telegram","secret_token":"<independent-secret>","allowed_updates":["message","callback_query"]}' \
+  "https://api.telegram.org/bot<BOT_TOKEN>/setWebhook"
+```
+
+The handler requires `POST` + JSON, verifies `X-Telegram-Bot-Api-Secret-Token` with a fixed-length hash comparison before body parsing, bounds body bytes, acquires the same receiver lease, and calls `admit` before returning `204`. Bad secret/body returns `401`/`400`/`413`; lease, capacity, stopped runtime, or journal unavailability returns `503` so Telegram retries. Untrusted but final inputs (bot/media/unknown sender/anonymous admin, or group updates when `allowGroups` is off) return `204` without an agent call. `allowGroups` is parsed identically in both modes; set it the same on the webhook worker and the poller you replaced.
+
+`callback_query` is promptly acknowledged with `answerCallbackQuery` and only accepts the runtime's `p:a:<opaque-token>` / `p:d:<opaque-token>` callback shape from a non-bot sender in an admitted private, group, or topic conversation (a topic callback keeps its `message_thread_id` as `threadId`). The adapter maps it to an `approval` event; callback data never becomes model input. The runtime validates its short-lived server-side binding before core resume.
+
+## Outputs / response / events
+
+`send()` accepts only replies addressed to its own `connectionId`; the runtime fixes `externalConversationId` and the reply `threadId` from the authorized binding, so a topic answer posts to that topic's `message_thread_id` and the model cannot choose either. It sends plain text, chunks at 3,500 UTF-16 code units without splitting surrogate pairs, and retries documented `retry_after` delays up to five attempts. A bounded server-issued control set renders as an inline keyboard on the final chunk; arbitrary model text cannot create buttons. There is no Markdown parse mode.
+
+Known API failures return `{ delivered: false, reason }`. A network/timeout outcome, or a later failure after a prior chunk was accepted, rejects with a bounded ambiguous-delivery error. The common durable reply journal records thrown delivery as `delivery_unknown`; do not automatically resend it. Bot token URLs are never included in adapter errors and redirects are forbidden.
+
+Telegram's `getUpdates` and webhooks are mutually exclusive. Updates remain available for at most 24 hours; the cursor is an ordering/acknowledgment record, not an exactly-once agent execution guarantee. Bots are not Secret Chats.
+
+### Streaming previews (drafts)
+
+With `sendDrafts: true` and `MessagingRuntimeOptions.onAssistantDelta: (delta) => adapter.sendDraft(delta)`, the adapter renders the answer while it is produced through Bot API `sendMessageDraft`: same chat and `message_thread_id` as the bound turn, `draft_id` fixed at one preview slot per chat, text capped to the last 3,500 UTF-16 code units. Previews are coalesced — one request in flight, the latest partial wins — so a token stream never floods the API, and failures are ignored because a draft is only a preview. Cancel, `stop()` and run end stop further previews. Drafts are private-chat only: group and supergroup chats are skipped even when `allowGroups` and `sendDrafts` are both on. No draft is ever a `ChannelReply`: nothing is journaled, no controls or attachments can ride along, and the terminal `sendMessage` remains the only message the user keeps.
+
+### Attachments and voice
+
+A `photo`, `voice` or `document` message is parsed into at most eight `ChannelAttachmentRef` values on the event: `kind`, `transportFileId` (Telegram `file_id`), optional `mimeType`, `byteLength` and `fileName`. A photo collapses to its largest size. The event never carries bytes, a URL, a caption-as-identity, or a model-chosen id, and nothing here can be addressed by model output.
+
+Before `admit`, the adapter runs the one bounded fetch the host opted into (Bot API `getFile` plus a capped download):
+
+- `voice` + host `transcribe` → the transcript becomes ordinary turn text (`caption`, then transcript). The audio is discarded after the call.
+- `document` + host `extractDocumentText` → the extracted text becomes turn text. Without the hook the document stays inert: the message admits with an attachment ref and no text, and the runtime answers with a bounded "cannot be processed" notice instead of a model call.
+- `photo` is never fetched by the adapter. The runtime fetches it (through `fetchAttachment`) only when the resolved agent's model declares `image` input, then sends it as one image content block next to the caption; otherwise the turn is refused with the same notice and no model call. `image` is the only attachment kind that becomes model input — audio/documents are text-only because Prism receives their host-produced text.
+
+Oversize fails closed twice: the runtime denies an event whose *declared* sizes exceed `maxAttachmentBytes` (`denied: oversized`, no fetch, no model call), and the adapter refuses to buffer a body whose `Content-Length` or streamed size exceeds the same cap. Failures (network, credential, API, malformed `file_path`) yield no bytes, so the turn is refused rather than run without the attachment.
+
+Outbound, `synthesize` adds a Bot API `sendVoice` next to the text for `final` replies: same bound chat and `message_thread_id`, OGG/OPUS, MP3 or M4A formats only, best-effort — a synthesis or upload failure never fails or re-sends the delivered text reply. Notices stay text-only. Nothing hangs a voice note on model-selected destinations.
+
+## Extension and configuration notes
+
+| Setting | Default | Range |
+| --- | ---: | ---: |
+| Poll timeout | 30 s | 1–50 s |
+| Poll batch | 100 | 1–100 |
+| Receiver lease | 90 s | poll timeout + 10 s–5 min |
+| Webhook/API body | 128 KiB | 1 KiB–1 MiB |
+| Outbound chunk | 3,500 UTF-16 units | fixed (under Telegram's 4,096 limit) |
+| Known-send attempts | 5 | fixed |
+| Group/topic text (`allowGroups`) | off | boolean |
+| Streaming previews (`sendDrafts`) | off | boolean (private chats only) |
+| Attachment bytes (`maxAttachmentBytes`) | 1 MiB | 1 B–4 MiB |
+| Voice transcription (`transcribe`) | off | host `TranscriptionProvider` wrapper |
+| Speech synthesis (`synthesize`) | off | host `SpeechProvider` wrapper (final replies) |
+| Document text (`extractDocumentText`) | off | host extractor |
+
+## Security and performance notes
+
+The webhook secret is independent of the bot token and compared with a fixed-length hash before body parsing. Redirects are forbidden; bot-token URLs never appear in adapter errors. Polling and webhooks are mutually exclusive. Model text cannot create inline buttons.
+
+Groups and topics are off by default and never self-authorize: the adapter only parses an observed `(chat id, topic id?, user id)` and the host grant decides, so a group membership claim is not an identity. Chat titles, usernames and display names are never actor ids. Bots, `sender_chat` (channel posts and anonymous admins), and non-text updates are dropped before admission; forwarded messages are admitted but flagged in `claims` so the grant can refuse them. In groups Telegram privacy mode limits what a bot receives (commands and replies to it) unless an operator disables it in BotFather; Prism does not work around that platform behavior. Signal stays DM-only.
+
+Drafts are display-only and cannot become input: they carry no controls or attachments, the destination chat/thread always comes from the bound event (never from model output or from the delta), text is redacted with the same redactor as finals, and the 3,500-unit cap keeps the request inside Bot API limits. Since `sendDraft` is fire-and-forget and failures are swallowed, a draft can never fail a turn, mask a delivery failure, or replace the journaled final reply.
+
+Media is bounded on every axis. Only the current event's refs are ever fetched (`fetchAttachment` takes a ref, and the runtime only passes refs of the event it is running), the cap is enforced twice (declared size and streamed body), and downloads use the same fixed origin with redirects forbidden. Bytes live only for the fetch call: they are never journaled (`ChannelOperationRecord` and `ChannelReplyRecord` store text only), never logged, and never written to disk. A `file_id` is not a capability — the bot proves nothing to Telegram by holding one, and a caller-supplied or model-invented id yields at most one bounded request inside the cap. Hosts wire `transcribe`/`synthesize`/`extractDocumentText` to their own provider wrappers; `@arnilo/prism-channels` never depends on `@arnilo/prism-providers`.
+
+## Related APIs
+
+- [Messaging channels](messaging-channels.md): authorization, durable operations and reply recovery.
+- [Web-standard server handler](server.md): mounting a `Request`/`Response` handler in a Node or framework host.

package/docs/testing.md

@@ -21,14 +21,14 @@ Documents how the hermetic suite runs, which stage a new suite belongs to, and t
 | build race | `scripts/phase23-build-race.test.mjs` |
 | workspace suites | `npm run test --workspaces --if-present` |
 
-Protected-environment legs (Postgres, PTY, NATS, live credentials) are not part of `npm test`; they fail closed with one canonical `BLOCKED GATE <id> requires=<names> evidence=<surface> hint=<how to unblock>` record and a non-zero exit when their infrastructure is absent (registry and audit: `node scripts/blocked-gate.mjs`). Retired phase freeze/release gates live in `scripts/` for audit but are deliberately kept out of the chain. 0.7.0 host-completeness packed proof is `scripts/fixtures/e2e-070-host-completeness-journey.mjs` (same packed consumer as the full-surface journey) plus `scripts/host-completeness-evidence.test.mjs`; live legs stay skip-not-fail. R16/R17 stay blocked until plans 077/074 ship.
+Protected-environment legs (Postgres, PTY, NATS, live credentials) are not part of `npm test`; they fail closed with one canonical `BLOCKED GATE <id> requires=<names> evidence=<surface> hint=<how to unblock>` record and a non-zero exit when their infrastructure is absent (registry and audit: `node scripts/blocked-gate.mjs`). A successful `PRISM_TEST_POSTGRES_URL=… npm run test:postgres` first removes stale evidence, then writes gitignored `scripts/postgres-evidence.json` with only current `gitHead`, capture time, and TAP counts; release evidence accepts it only at the same `HEAD`. Retired phase freeze/release gates live in `scripts/` for audit but are deliberately kept out of the chain. 0.7.0 host-completeness packed proof is `scripts/fixtures/e2e-070-host-completeness-journey.mjs` (same packed consumer as the full-surface journey) plus `scripts/host-completeness-evidence.test.mjs`; live legs stay skip-not-fail. R16/R17 stay blocked until plans 077/074 ship.
 
 ## Isolation rules
 
 - **Scratch roots come from the OS.** A suite that writes anything creates its root with `mkdtempSync(join(tmpdir(), "prism-…"))` and removes it in `after()`. Never rely on `process.cwd()` for write targets: the same suite runs with different working directories (workspace stage vs. root stage), so a cwd-relative root silently writes into the repository.
 - **Pass explicit roots.** Wiki, memory, and store helpers default `workspaceRoot` to `process.cwd()`; suites pass their scratch root (and a `wikiRoot` relative to it) instead of accepting the default.
 - **Tracked fixtures stay byte-identical.** `packages/memory/.wiki/` is a tracked wiki fixture and `docs/` is a tracked corpus. `scripts/wiki-scratch-isolation.test.mjs` runs the wiki suites from the package and from the repository root and fails if the tracked fixture hashes change, if a new file appears inside the fixture, if `<repo>/.wiki/` is scaffolded, or if the old cwd-relative scratch directories reappear.
-- **Gates never write inside the repository.** A gate asserts against tracked content and spawns suites in temporary directories only. A gate that spawns `node --test` must strip `NODE_TEST_CONTEXT`/`NODE_TEST_WORKER_ID` from the child environment (an inherited value makes the nested runner skip every file and still exit 0) and assert the child reported a non-zero pass count.
+- **Gates never write inside the repository.** A gate asserts against tracked content and spawns suites in temporary directories only. A gate that spawns `node --test` must strip `NODE_TEST_CONTEXT`/`NODE_TEST_WORKER_ID` from the child environment (an inherited value makes the nested runner skip every file and still exit 0) and assert the child reported a non-zero pass count. The wiki gate additionally uses `--test-isolation=none`: all nested files run in its one runner process, avoiding process-worker IPC deserialization without retrying failures.
 - **Wait by polling, not by sleeping.** Async browser state (download quarantine, idle reaping) is not awaitable from the outside — `manager.ts` settles it on a fire-and-forget listener promise — so a fixed sleep is a race that loses under CPU load and fails the assertion for a reason unrelated to the behavior under test. Suites poll observable state through `waitFor(read, ok, label, { timeoutMs, intervalMs })` in `packages/web-tools/src/browser/__tests__/wait-for.ts`, which returns as soon as the state appears and otherwise throws naming the label and the last observed value. Fixed sleeps remain only where real elapsed time is the subject of the test (idle TTLs).
 
 ## Related APIs

package/docs/wiki.md

@@ -85,7 +85,7 @@ The staging primitive behind `/wiki-ingest`, `wiki_ingest`, and the CLI. Accepts
 | :--- | :--- |
 | Text-like files and `text` | Decoded as UTF-8 (RAG text/markdown/html parsers) |
 | Uncompressed PDF | Parsed by the RAG PDF parser (bounded pages/bytes) |
-| Compressed PDF / DOCX | Throws a named error unless the host supplies `options.extractDocument` (e.g. wire `createDocumentReader()` from `@arnilo/prism-coding-tools/document-reader`) |
+| Compressed PDF / DOCX | Throws a named error unless the host supplies `options.extractDocument` (e.g. wire `createDocumentReader()` from `@arnilo/prism-work/document-reader`) |
 | `url` | `assertSsrfAllowedUrl` runs first (private/link-local hosts rejected before any fetch); then the host `fetchUrl` hook supplies the bytes/text — missing or empty hook output fails closed. Staged filename comes from the hook, the URL extension (`doc.pdf`), or `source.md` |
 | Images | Staged as-is; stub extract points at the staged `source.*` — no OCR; view the file |
 | Unknown binary | Fails closed unless `extractDocument` claims it |

package/docs/work-artifacts-and-review.md

@@ -97,7 +97,7 @@ export const handler = createArtifactHandler({ service: artifacts, authorize: ho
 
 ## Business action drafts and editable approvals (0.7.0)
 
-Business tools (e.g. mail, calendar, documents in `@arnilo/prism-core/integrations/work`) record mutations through durable `WorkDraftStore` drafts before execution. Human reviewers can approve, deny, or edit draft payloads directly:
+Business tools (e.g. mail, calendar, documents in `@arnilo/prism-work/connectors`) record mutations through durable `WorkDraftStore` drafts before execution. Human reviewers can approve, deny, or edit draft payloads directly:
 - AG-UI clients advertise and send `approveWithEdits` with revised arguments (`editedArgs`/`modifiedArguments`).
 - The server resume endpoint accepts `{ decision: "approve", modifiedArguments: { ... } }` under CAS `expectedVersion`.
 - If arguments are modified, a new draft revision is created with bumped revision number and payload digest. The previous revision's approval is invalidated and the mutation requires approval for the revised content.

package/docs/work-connectors.md

@@ -1,33 +1,33 @@
 # Work connectors
 
-Least-privilege Microsoft 365 and Google Workspace connectors live in `@arnilo/prism-core/integrations/work`.
+Least-privilege Microsoft 365 and Google Workspace connectors live in `@arnilo/prism-work/connectors`.
 
 ## Principles
 
-1. **Host-pinned binary** — Prism never downloads or shells an untrusted CLI path.
-2. **Hard-coded argv templates** — models choose typed tool args; they never supply command strings.
+1. **Host-pinned binary or HTTP adapter** — Prism never downloads or shells an untrusted CLI path; HTTP adapters use fixed origins and pinned fetch.
+2. **Hard-coded operation maps** — models choose typed tool args; they never supply command strings or request URLs.
 3. **Draft-then-approve & durable resumption** — mutations create a draft with tracked revisions and payload digests; side effects run only after host approval binds to that exact revision; durable checkpoint persistence survives process restart.
 4. **Idempotent retries** — `IdempotencyStore` keyed by identity + operation key.
 5. **Isolated config** — per-identity `configDir` (CLI `HOME`); no credential argv.
-6. **Shared result shapes** — mail/calendar/file/task list/get tools normalize onto `WorkMailMessage` / `WorkCalendarEvent` / `WorkFileItem` / `WorkTaskItem` without hiding provider-specific ops.
+6. **Shared result shapes** — mail/calendar/file/task list/get tools normalize onto `WorkMailMessage` / `WorkCalendarEvent` / `WorkFileItem` / `WorkTaskItem` without hiding provider-specific ops. Binary file gets return only untrusted artifact/path metadata plus hash and byte length.
 
 ## Microsoft 365
 
-See [Work tools](work-tools.md). Adapter: `createMicrosoft365CliAdapter` / subpath `@arnilo/prism-core/integrations/work/microsoft365`.
+See [Work tools](work-tools.md). Adapters: `createMicrosoft365CliAdapter` or `createMicrosoft365HttpAdapter` from `@arnilo/prism-work/connectors`.
 
-Uses [@pnp/cli-microsoft365](https://pnp.github.io/cli-microsoft365/) commands such as `outlook message list|get`, `outlook mail send`, `outlook event list|add`, `file list|add`, `spo file sharinglink add`. To Do / Planner / Teams remain capability-gated.
+The CLI adapter uses [@pnp/cli-microsoft365](https://pnp.github.io/cli-microsoft365/) commands such as `outlook message list|get`, `outlook mail send`, `outlook event list|add`, `file list|add|copy`, `spo file sharinglink add`. The HTTP adapter maps its fixed operation set to `graph.microsoft.com` through pinned fetch; tokens reach it only in `Authorization`. `m365_file_get` accepts only an item ID and downloads via fixed `/me/drive/items/{id}/content` into a scanned artifact and/or contained sandbox path; it never emits bytes to model context. Upload drafts accept a host path, artifact ref, or contained sandbox path and bind the content hash before approval. It requires direct Graph Drive-item URLs for one-request file list/upload/copy and rejects arbitrary SharePoint links. To Do / Planner / Teams remain capability-gated.
 
 ## Google Workspace
 
-See [Work tools](work-tools.md). Adapter: `createGoogleWorkspaceCliAdapter` / subpath `@arnilo/prism-core/integrations/work/google-workspace`.
+See [Work tools](work-tools.md). Adapters: `createGoogleWorkspaceCliAdapter` or `createGoogleWorkspaceHttpAdapter` from `@arnilo/prism-work/connectors`.
 
-Uses [`@googleworkspace/cli` (`gws`)](https://github.com/googleworkspace/cli): `gmail users messages list|get`, `gmail +send`, `calendar events list|insert`, `drive files list|create`, `drive permissions create`, `tasks tasks *`. Docs/Sheets/Slides create remain capability-gated. Discovery `schema` and `auth`/`login`/`setup` are forbidden from Prism argv.
+The CLI adapter uses [`@googleworkspace/cli` (`gws`)](https://github.com/googleworkspace/cli): `gmail users messages list|get`, `gmail +send`, `calendar events list|insert`, `drive files list|create`, `drive permissions create`, `tasks tasks *`, and capability-gated Docs/Sheets/Slides create and fixed update commands. The HTTP adapter maps the same typed operations to Gmail, Calendar, Drive, Tasks, Docs, Sheets, and Slides REST origins with `pinnedFetch`; `gws_file_get` accepts only an item ID and uses fixed `Drive files.get?alt=media`, returning only scanned artifact/path metadata. Its fixed allowlist excludes model-supplied URLs. Docs/Sheets/Slides updates accept only replace/insert text or string-matrix values, never a model-provided batch request array. Discovery `schema` and `auth`/`login`/`setup` are forbidden from Prism argv.
 
 Drive **knowledge synchronization** (RAG import of file text + host-mapped ACL via `changes.list`) is not this CLI adapter. Use `createGoogleDriveConnector` / `syncKnowledge` from `@arnilo/prism-memory/rag` — see [Knowledge synchronization](knowledge-sync.md).
 
 ## Scoped OAuth establishment (0.0.14)
 
-Hosts establish, refresh, and revoke scoped OAuth credentials for these workloads through the existing `OAuthProvider` / credential-store seams (`@arnilo/prism-core/credentials/node`): `createMicrosoft365OAuthProvider` / `createGoogleWorkspaceOAuthProvider` (PKCE + device code), least-privilege scope bundles per capability (`resolveMicrosoft365Scopes` / `resolveGoogleWorkspaceScopes`, read vs mutation). Connectors consume a per-identity token via a late-bound `tokenProvider` injected as an env var — never argv, never model context; revocation fails closed. See [Credential storage](credential-storage.md) and [Work tools](work-tools.md).
+Hosts establish, refresh, and revoke scoped OAuth credentials for these workloads through the existing `OAuthProvider` / credential-store seams (`@arnilo/prism-core/credentials/node`): `createMicrosoft365OAuthProvider` / `createGoogleWorkspaceOAuthProvider` (PKCE + device code), least-privilege scope bundles per capability (`resolveMicrosoft365Scopes` / `resolveGoogleWorkspaceScopes`, read vs mutation). Connectors consume a per-identity token via a late-bound `tokenProvider`: CLI adapters inject it into env and HTTP adapters send it only as `Authorization` — never argv or model context; revocation fails closed. See [Credential storage](credential-storage.md) and [Work tools](work-tools.md).
 
 ## Out of scope
 

package/docs/work-sandbox.md

@@ -0,0 +1,115 @@
+# Work sandbox (`@arnilo/prism-work/sandbox`)
+
+## What it does
+
+Host-built Docker image and in-process composition for document work. `WORK_SANDBOX_IMAGE` is a digest-pinned fixture (`name@sha256:<64-hex>`); hosts replace the zero digest after `docker build`. `createWorkComposition({ sandbox })` takes an injected `DisposableSandbox` (from `createDockerSandbox`, never forked here), copies its capability attestation, wires `createOfficeTools` filesystem mode plus `work_exec`, and optionally host-side `createWorkTools`. Connectors stay on the host. Default env has no `M365_*` / `GOOGLE_*` keys.
+
+## When to use it
+
+Use when Office parse/generate and Python/LibreOffice/poppler scripts must run inside a network-none container. Do **not** put Graph/Gmail tokens in the sandbox. Do not import `@arnilo/prism-coding-tools` from this package — the host constructs `createDockerSandbox({ image: WORK_SANDBOX_IMAGE, user: "65532:65532", network: { mode: "none" } })` and injects the session.
+
+## Inputs / request
+
+`createWorkComposition(options)`:
+
+| Field | Meaning |
+| --- | --- |
+| `sandbox` | Injected adapter with `execFile` and optional `readFile`/`writeFile`/`root`. Required. |
+| `connectors?` | `WorkToolsOptions` for host-side M365/GWS tools. |
+| `office?` | Extra `createOfficeTools` options (caps, artifacts, redactor). |
+| `reader?` | Host-built `DocumentReader`; exposed on the composition, not turned into tools. |
+| `filesystem?` | `WorkSandboxFilesystem` when the sandbox has no `readFile`/`writeFile`. |
+| `env?` | Extra container env. `M365_*` and `GOOGLE_*` names throw. |
+
+Image build context: `packages/prism-work` (`sandbox/Dockerfile` + `sandbox/soffice.sh` + `vendor/hermes-agent`). Vendored Hermes scripts land at `/opt/prism-work/skills`.
+
+## Outputs / response / events
+
+`{ tools, composition }`. `tools` always include `office_*` and `work_exec`. `composition.capabilities` is a frozen copy of the sandbox attestation (malformed metadata → every field `false`). `networkIsolated` is true only when the sandbox attests it — Docker reports that solely for `network: { mode: "none" }`. `composition.execFile` strips token env names and forces LibreOffice `-env:UserInstallation=file:///tmp/lo-profile` without `--accept` / macro flags.
+
+## Request/response example
+
+```ts
+import { createDockerSandbox } from "@arnilo/prism-coding-tools/security";
+import { createWorkComposition, WORK_SANDBOX_IMAGE } from "@arnilo/prism-work/sandbox";
+
+const sandbox = await createDockerSandbox({
+  docker: "/usr/bin/docker",
+  image: WORK_SANDBOX_IMAGE, // replace zeros with the host-built digest
+  sourceRoot: workdir,
+  user: "65532:65532",
+  network: { mode: "none" },
+});
+const { tools, composition } = createWorkComposition({ sandbox, connectors });
+```
+
+## Implementation example
+
+```ts
+import { createWorkComposition, WORK_SANDBOX_IMAGE } from "@arnilo/prism-work/sandbox";
+
+const { tools, composition } = createWorkComposition({
+  sandbox: fakeDisposableSandbox, // tests inject this; no Docker
+});
+composition.capabilities.networkIsolated; // copied, never invented
+```
+
+Build:
+
+```bash
+docker build -f packages/prism-work/sandbox/Dockerfile -t prism-work-sandbox packages/prism-work
+docker image inspect --format '{{index .RepoDigests 0}}' prism-work-sandbox
+```
+
+## Extension and configuration notes
+
+- Do not fork `createDockerSandbox`. Image pull/build stays outside Prism (`--pull=never`).
+- Connectors optional and host-side. Bytes move via sandbox import/export and office filesystem tools.
+- `work_exec` is argv-only (`file` + `args`); no model-supplied shell string.
+- Protected image check: `PRISM_TEST_WORK_SANDBOX=1` runs `scripts/work-sandbox-image.test.mjs` and sandbox recalc/render/legacy-convert tests. Default `npm test` does not spawn `soffice`.
+
+## Recalc and visual QA
+
+In-process `SheetModel` does not evaluate formulas. Cached values are filled only by LibreOffice in this image (`network: none`, isolated `/tmp/lo-profile`, deleted with the container). Vendored scripts:
+
+```bash
+python3 /opt/prism-work/skills/skills/productivity/xlsx/scripts/xlsx_recalc.py /workspace/out.xlsx --timeout 60
+python3 /opt/prism-work/skills/skills/productivity/powerpoint/scripts/pptx_render.py /workspace/deck.pptx --outdir /workspace/render
+```
+
+Equivalent argv (wrapper already injects `-env:UserInstallation=file:///tmp/lo-profile --headless`):
+
+```bash
+soffice --headless -env:UserInstallation=file:///tmp/lo-profile --convert-to pdf --outdir /tmp/out /workspace/out.xlsx
+pdftoppm -png -r 100 /tmp/out/out.pdf /tmp/out/page
+```
+
+External workbook links cannot be fetched. Recalc then fails closed: formula stays, cached value missing or error — Prism does not invent a number. `soffice` timeout ≤ 60 s.
+
+## Legacy convert
+
+Prism AST still refuses non-ZIP packages. Convert OLE `.doc` / `.xls` / `.ppt` inside this image (`network: none`, isolated `/tmp/lo-profile`, macros refused), then `office_parse`:
+
+```bash
+soffice --headless -env:UserInstallation=file:///tmp/lo-profile --convert-to docx --outdir /workspace /workspace/legacy.doc
+soffice --headless -env:UserInstallation=file:///tmp/lo-profile --convert-to xlsx --outdir /workspace /workspace/legacy.xls
+soffice --headless -env:UserInstallation=file:///tmp/lo-profile --convert-to pptx --outdir /workspace /workspace/legacy.ppt
+```
+
+Do not enable macros. Encrypted OOXML stays dropped. No in-process OLE parser.
+
+## Security and performance notes
+
+- Default network none. Composition does not claim isolation the sandbox did not attest.
+- Token env keys denied by name (`M365_*`, `GOOGLE_*`) at composition construct and `execFile`.
+- LibreOffice wrapper: private `/tmp/lo-profile`, `--headless`, no macro enable, `--accept` refused. No listening socket. Legacy convert uses the same wrapper.
+- Zip bombs: existing office parse caps; sandbox export uses existing export caps.
+- Image build is CI/protected, not default unit tests. Composition construct is in-process with a fake sandbox.
+
+## Related APIs
+
+- [Coding security](coding-security.md) — `createDockerSandbox` digest pin, user, network none
+- [Work tools](work-tools.md) — host-side connectors
+- [Documents](documents.md) — `createOfficeTools`
+- [Document reader](document-reader.md) — optional `reader` injection
+- [Context and skills](context-and-skills.md) — `loadWorkSkills()` (`docx`, `xlsx`, `powerpoint`, `pdf`)