@arnilo/prism 0.6.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (178) hide show
  1. package/CHANGELOG.md +79 -5
  2. package/README.md +12 -11
  3. package/dist/agent-approval.d.ts +4 -0
  4. package/dist/agent-approval.js +5 -1
  5. package/dist/agent-definitions.js +1 -0
  6. package/dist/agent-run-lifecycle.js +39 -4
  7. package/dist/agent-run-state.d.ts +18 -0
  8. package/dist/agent-run-state.js +39 -9
  9. package/dist/agent-session/helpers.js +6 -1
  10. package/dist/agent-session/session/assemble.js +159 -7
  11. package/dist/agent-session/session/persist.d.ts +16 -0
  12. package/dist/agent-session/session/persist.js +64 -4
  13. package/dist/agent-session/session/provider-round.d.ts +3 -3
  14. package/dist/agent-session/session/provider-round.js +12 -6
  15. package/dist/agent-session/session/tool-round.js +5 -1
  16. package/dist/agent-session/session/types.d.ts +22 -1
  17. package/dist/agent-session/session.d.ts +16 -0
  18. package/dist/agent-session/session.js +42 -3
  19. package/dist/artifacts.d.ts +39 -1
  20. package/dist/artifacts.js +73 -0
  21. package/dist/attention-compiler.d.ts +121 -0
  22. package/dist/attention-compiler.js +479 -0
  23. package/dist/checkpoints.js +7 -11
  24. package/dist/cli-init.js +20 -6
  25. package/dist/context-budget.d.ts +20 -1
  26. package/dist/context-budget.js +10 -1
  27. package/dist/contracts-core/agent.d.ts +7 -0
  28. package/dist/contracts-core/attention.d.ts +66 -0
  29. package/dist/contracts-core/attention.js +2 -0
  30. package/dist/contracts-core/compaction.d.ts +59 -0
  31. package/dist/contracts-core/compaction.js +77 -1
  32. package/dist/contracts-core/content.d.ts +5 -0
  33. package/dist/contracts-core/loop.d.ts +42 -0
  34. package/dist/contracts-core/provider.d.ts +4 -0
  35. package/dist/contracts-core/run-limits.d.ts +2 -0
  36. package/dist/contracts-core.d.ts +1 -0
  37. package/dist/contracts-core.js +1 -0
  38. package/dist/contracts-protocol.d.ts +44 -3
  39. package/dist/contracts-run-state.d.ts +32 -5
  40. package/dist/evidence-grounding.d.ts +29 -0
  41. package/dist/evidence-grounding.js +162 -0
  42. package/dist/host-composition.d.ts +91 -0
  43. package/dist/host-composition.js +279 -0
  44. package/dist/index.d.ts +13 -6
  45. package/dist/index.js +7 -4
  46. package/dist/input.d.ts +13 -1
  47. package/dist/input.js +40 -1
  48. package/dist/provider-events.d.ts +3 -1
  49. package/dist/provider-events.js +2 -2
  50. package/dist/providers/transport.d.ts +3 -1
  51. package/dist/providers/transport.js +36 -0
  52. package/dist/redaction.js +18 -2
  53. package/dist/run-bundle.d.ts +89 -0
  54. package/dist/run-bundle.js +149 -0
  55. package/dist/secure-agent.d.ts +2 -0
  56. package/dist/secure-agent.js +6 -1
  57. package/dist/testing/state-concurrency-conformance.js +5 -12
  58. package/dist/tool-result-fold.d.ts +12 -0
  59. package/dist/tool-result-fold.js +13 -6
  60. package/dist/tools.d.ts +10 -0
  61. package/dist/tools.js +41 -0
  62. package/docs/acp-agent.md +42 -11
  63. package/docs/acp.md +2 -1
  64. package/docs/ag-ui.md +10 -3
  65. package/docs/agent-definitions.md +9 -1
  66. package/docs/agent-events.md +4 -1
  67. package/docs/agent-loops.md +33 -0
  68. package/docs/agent-session-runtime.md +8 -7
  69. package/docs/attention-compiler.md +272 -0
  70. package/docs/cli-rpc.md +4 -2
  71. package/docs/coding-agent-tools.md +1 -1
  72. package/docs/coding-security.md +6 -3
  73. package/docs/coding-tools.md +0 -1
  74. package/docs/coding-workspaces.md +22 -0
  75. package/docs/compaction-and-retry.md +36 -4
  76. package/docs/compaction-observational-memory.md +63 -10
  77. package/docs/connected-apps.md +116 -0
  78. package/docs/context-and-skills.md +17 -2
  79. package/docs/conversations.md +1 -1
  80. package/docs/core.md +1 -1
  81. package/docs/dev-inspector.md +4 -0
  82. package/docs/device-adapters.md +1 -0
  83. package/docs/diagrams.md +6 -6
  84. package/docs/document-reader.md +18 -10
  85. package/docs/documents.md +40 -11
  86. package/docs/durable-runs.md +87 -0
  87. package/docs/enterprise-postgres-state.md +6 -2
  88. package/docs/evaluations.md +168 -4
  89. package/docs/execution-timeline.md +186 -0
  90. package/docs/guardrails.md +33 -0
  91. package/docs/history/0.7.0-primitive-review.md +254 -0
  92. package/docs/history/079-messaging-primitive-review.md +391 -0
  93. package/docs/history/080-messaging-followon-primitive-review.md +234 -0
  94. package/docs/history/081-connected-apps-primitive-review.md +74 -0
  95. package/docs/history/083-prism-work-primitive-review.md +84 -0
  96. package/docs/history/084-primitive-review.md +96 -0
  97. package/docs/history/085-honesty-and-cut-primitive-review.md +91 -0
  98. package/docs/history/README.md +5 -0
  99. package/docs/history/migration-0.0.md +2 -2
  100. package/docs/history/release-handoffs.md +75 -1
  101. package/docs/host-compositions.md +149 -0
  102. package/docs/host-security.md +2 -2
  103. package/docs/hosted-sandboxes.md +94 -0
  104. package/docs/index.md +82 -45
  105. package/docs/input-and-prompt-assembly.md +1 -0
  106. package/docs/knowledge-sync.md +84 -0
  107. package/docs/language-intelligence.md +1 -1
  108. package/docs/live-testing.md +8 -3
  109. package/docs/mcp-tools.md +3 -1
  110. package/docs/memory-fabric.md +416 -0
  111. package/docs/messaging-channel-operations.md +166 -0
  112. package/docs/messaging-channels.md +150 -0
  113. package/docs/migrate-to-0.5.md +1 -1
  114. package/docs/migrate-to-0.6.md +1 -0
  115. package/docs/migrate-to-0.7.md +345 -0
  116. package/docs/migrate-to-0.8.md +124 -0
  117. package/docs/migration.md +43 -1
  118. package/docs/model-registry.md +12 -2
  119. package/docs/model-routing.md +79 -4
  120. package/docs/multi-agent-patterns.md +20 -6
  121. package/docs/observability.md +52 -1
  122. package/docs/openapi-tools.md +1 -1
  123. package/docs/operations.md +14 -4
  124. package/docs/options-index.md +47 -3
  125. package/docs/peer-dependencies.md +12 -10
  126. package/docs/postgres-persistence.md +1 -1
  127. package/docs/process-sessions.md +3 -1
  128. package/docs/prompt-registry.md +1 -1
  129. package/docs/provider-caching.md +4 -2
  130. package/docs/provider-conformance.md +1 -1
  131. package/docs/provider-layer.md +2 -2
  132. package/docs/provider-packages.md +22 -22
  133. package/docs/providers/bedrock.md +71 -7
  134. package/docs/providers/neuralwatt.md +5 -1
  135. package/docs/providers/openai.md +1 -1
  136. package/docs/rag.md +24 -8
  137. package/docs/realtime-voice.md +87 -0
  138. package/docs/release-and-install.md +53 -45
  139. package/docs/run-bundle.md +92 -0
  140. package/docs/runs-and-usage.md +17 -2
  141. package/docs/server.md +7 -3
  142. package/docs/sheets.md +9 -9
  143. package/docs/signal-channel.md +112 -0
  144. package/docs/speech.md +7 -1
  145. package/docs/sqlite-persistence.md +1 -1
  146. package/docs/supervisors.md +33 -5
  147. package/docs/telegram-channel.md +157 -0
  148. package/docs/testing.md +2 -2
  149. package/docs/thinking-and-reasoning.md +3 -1
  150. package/docs/tools.md +6 -5
  151. package/docs/web-tools.md +2 -1
  152. package/docs/wiki.md +1 -1
  153. package/docs/work-artifacts-and-review.md +14 -4
  154. package/docs/work-connectors.md +12 -10
  155. package/docs/work-sandbox.md +115 -0
  156. package/docs/work-tools.md +50 -18
  157. package/docs/workflows.md +69 -1
  158. package/docs/working-and-semantic-memory.md +25 -14
  159. package/package.json +5 -3
  160. package/templates/README.md +2 -0
  161. package/templates/business-worker/README.md.tmpl +19 -0
  162. package/templates/business-worker/env.example.tmpl +1 -0
  163. package/templates/business-worker/gitignore.tmpl +11 -0
  164. package/templates/business-worker/manifest.json +12 -0
  165. package/templates/business-worker/package.json.tmpl +23 -0
  166. package/templates/business-worker/src/agent.ts.tmpl +92 -0
  167. package/templates/business-worker/src/index.ts.tmpl +13 -0
  168. package/templates/business-worker/src/tests/agent.test.ts.tmpl +77 -0
  169. package/templates/business-worker/tsconfig.json.tmpl +15 -0
  170. package/templates/personal-assistant/README.md.tmpl +18 -0
  171. package/templates/personal-assistant/env.example.tmpl +1 -0
  172. package/templates/personal-assistant/gitignore.tmpl +11 -0
  173. package/templates/personal-assistant/manifest.json +11 -0
  174. package/templates/personal-assistant/package.json.tmpl +23 -0
  175. package/templates/personal-assistant/src/agent.ts.tmpl +65 -0
  176. package/templates/personal-assistant/src/index.ts.tmpl +13 -0
  177. package/templates/personal-assistant/src/tests/agent.test.ts.tmpl +28 -0
  178. package/templates/personal-assistant/tsconfig.json.tmpl +15 -0
@@ -0,0 +1,149 @@
1
+ # Host compositions
2
+
3
+ Prism agents are host-assembled: the host application owns credentials, providers, persistence, permissions, tool definitions, and connected-app transports. Prism provides two canonical, maintained host compositions and a zero-network inspection and readiness API to ensure host setups conform to their operational contracts:
4
+
5
+ - **`personal` (`personal-assistant`)**: Local-personal host composition for single-operator productivity, personal tools, local/memory persistence, and secret redaction.
6
+ - **`business` (`business-worker`)**: Multi-tenant enterprise worker host composition with verified tenant identity, mandatory durable storage, sandbox workspace containment, and strict governance enforcement.
7
+
8
+ ## Profiles
9
+
10
+ | Profile | Ownership | Identity | Persistence | Sandbox | Governance |
11
+ | --- | --- | --- | --- | --- | --- |
12
+ | `personal` | Single user (`userId`) | Optional unverified operator | Memory or durable storage | Local workspace | Optional |
13
+ | `business` | Tenant + user (`tenantId`, `userId`) | Mandatory verified identity (`verified: true`) matching tenant | Mandatory durable store (`durable: true`); memory rejected | Contained sandbox roots within workspace | Required supported governance |
14
+
15
+ ## Host composition API
16
+
17
+ Both helper functions and the error class are exported from `@arnilo/prism`:
18
+
19
+ ```ts
20
+ import {
21
+ inspectHostComposition,
22
+ assertHostCompositionReadiness,
23
+ HostCompositionError,
24
+ type HostCompositionProfile,
25
+ type HostCompositionOptions,
26
+ type HostCompositionReport,
27
+ } from "@arnilo/prism";
28
+ ```
29
+
30
+ ### `inspectHostComposition(options)`
31
+
32
+ Inspects an agent configuration and returns a typed `HostCompositionReport`. Inspection is **completely inert and performs zero network calls**. Canary secrets in credentials are never leaked.
33
+
34
+ ```ts
35
+ const report = inspectHostComposition({
36
+ profile: "personal",
37
+ agent: personalAgent,
38
+ store: memoryStore,
39
+ credentialRefs: ["OPENAI_API_KEY"],
40
+ connectedApps: { appIds: ["slack"], serverIds: ["slack"] },
41
+ });
42
+ ```
43
+
44
+ Report structure:
45
+
46
+ - `profile`: `"personal"` or `"business"`.
47
+ - `effectiveTools`: Readonly list of tool names registered on the agent.
48
+ - `credentialRefs`: Host credential references (sanitized, values never included).
49
+ - `connectedApps`: Optional copied `appIds` and `serverIds` (up to 32 identifiers per list); transports, environment, headers, and tokens are never accepted or reported. Business hosts require a verified identity when this field is present.
50
+ - `ownership`: Tenant and user ownership identifiers.
51
+ - `storage`: Storage summary with `kind` (`"memory"`, `"postgres"`, `"sqlite"`, etc.) and `durable` boolean. Memory stores are truthfully reported with `durable: false`. `snapshotRunBundle()` ([effective run bundle snapshots](run-bundle.md)) reuses this classification for the per-run store kinds.
52
+ - `sandbox`: Isolation status and resolved root paths.
53
+ - `governance`: Coverage flags (authorization, trust, and custom policies).
54
+ - `readiness`: Object with `ok: boolean` and list of `reasons` if not ready.
55
+
56
+ ### `assertHostCompositionReadiness(options)`
57
+
58
+ Validates that the host composition satisfies all profile constraints. Throws `HostCompositionError` on the first violated rule:
59
+
60
+ | Error Code | Violation |
61
+ | --- | --- |
62
+ | `ERR_PRISM_HOST_COMPOSITION_PROFILE` | Unknown or missing profile. |
63
+ | `ERR_PRISM_HOST_COMPOSITION_OWNERSHIP` | Missing `userId` (personal), missing `tenantId` (business), or identity/ownership mismatch. |
64
+ | `ERR_PRISM_HOST_COMPOSITION_STORAGE` | Non-durable or in-memory persistence passed to a business composition. |
65
+ | `ERR_PRISM_HOST_COMPOSITION_SECRETS` | Agent lacks a configured `SecretRedactor`. |
66
+ | `ERR_PRISM_HOST_COMPOSITION_PROVIDER` | Agent lacks an active `AIProvider` or model selection. |
67
+ | `ERR_PRISM_HOST_COMPOSITION_SANDBOX` | Sandbox roots escape the declared `workspaceRoot`. |
68
+ | `ERR_PRISM_HOST_COMPOSITION_GOVERNANCE` | Governance policy disabled or unsupported. |
69
+
70
+ ### Integration with `createSecureAgent`
71
+
72
+ `createSecureAgent` accepts an optional `composition` field. When provided, readiness is asserted immediately before the agent is returned:
73
+
74
+ ```ts
75
+ import { createSecureAgent } from "@arnilo/prism";
76
+
77
+ const agent = createSecureAgent({
78
+ id: "worker-1",
79
+ definitionRevision: "1",
80
+ ownership: { tenantId: "acme-corp", userId: "worker-prod" },
81
+ identity: {
82
+ tenantId: "acme-corp",
83
+ userId: "worker-prod",
84
+ principal: { kind: "user", id: "worker-prod" },
85
+ scopes: ["task:execute"],
86
+ verified: true,
87
+ issuedAt: new Date().toISOString(),
88
+ },
89
+ composition: {
90
+ profile: "business",
91
+ store: postgresStore,
92
+ workspaceRoot: "/data/acme",
93
+ sandboxRoots: ["/data/acme/scratch"],
94
+ },
95
+ // ... other required secure agent options
96
+ });
97
+ ```
98
+
99
+ ## Package install vs. import subpaths
100
+
101
+ Always install containing packages directly. **NPM install never accepts subpaths**:
102
+
103
+ ```bash
104
+ # Correct — install containing published packages:
105
+ npm install @arnilo/prism @arnilo/prism-core @arnilo/prism-providers @arnilo/prism-work
106
+
107
+ # Never install subpaths:
108
+ # npm install @arnilo/prism-work/connectors (WRONG: fails with 404 / E404)
109
+ ```
110
+
111
+ In your application code, import from documented subpaths:
112
+
113
+ ```ts
114
+ // Subpaths exported by @arnilo/prism-work:
115
+ import { createWorkTools } from "@arnilo/prism-work/connectors";
116
+ import { createJsonSchemaArgumentValidator } from "@arnilo/prism-core/validation/json-schema";
117
+
118
+ // Subpaths exported by @arnilo/prism-providers:
119
+ import { createOpenAIProvider } from "@arnilo/prism-providers/openai";
120
+ ```
121
+
122
+ ## Background workers
123
+
124
+ Business workers that share a durable checkpoint queue should pass `admission: { perTenant, drain }` into `createWorkflowCoordinator` and mount `createPrismOperatorHandler` beside health/drain. See [Operations runbook](operations.md) and [Workflows](workflows.md). Do not introduce a second scheduler.
125
+
126
+ ## Starter templates
127
+
128
+ Scaffold fresh host compositions using `prism init`:
129
+
130
+ ```bash
131
+ # Personal assistant composition
132
+ prism init my-assistant --template personal-assistant
133
+
134
+ # Business worker composition
135
+ prism init my-worker --template business-worker
136
+ ```
137
+
138
+ Each template produces a runnable agent, mock test fixtures, environment templates, and strict typing.
139
+
140
+ ## Dev inspector endpoint
141
+
142
+ When running `@arnilo/prism-coding-tools/dev`, host compositions can be inspected via HTTP:
143
+
144
+ ```bash
145
+ GET /inspect
146
+ # or GET {basePath}/inspect
147
+ ```
148
+
149
+ Returns the JSON serialized `HostCompositionReport` corresponding to the inspected agent and options.
@@ -190,7 +190,7 @@ PostgreSQL TLS/network policy, MCP endpoint trust/credentials and egress policy
190
190
  ## Web research boundaries
191
191
 
192
192
  - Construct `@arnilo/prism-web-tools` with one host-selected Brave or Exa adapter; never expose adapter/provider/credential/schema selection to model arguments.
193
- - Construct `@arnilo/prism-core/integrations/work` with host-pinned CLI binary + isolated `configDir` + verified `AgentIdentity` (M365 and/or GWS). Never pass model-built command strings, `login`/`setup`/`auth`/`schema`/`--debug`, or credentials in argv. Mutations require draft approval; external recipients and anonymous/`anyone` shares fail closed.
193
+ - Construct `@arnilo/prism-work/connectors` with host-pinned CLI binary + isolated `configDir` + verified `AgentIdentity` (M365 and/or GWS). Never pass model-built command strings, `login`/`setup`/`auth`/`schema`/`--debug`, or credentials in argv. Mutations require draft approval; external recipients and anonymous/`anyone` shares fail closed.
194
194
  - Provider API origins are fixed exact HTTPS origins and redirects fail. Credentials resolve immediately before I/O; remote bodies and secrets are excluded from errors/results/telemetry.
195
195
  - Firecrawl targets reject userinfo, non-HTTP(S), private literals, and policy-denied hosts. Supply `validateUrl` for host DNS/rebinding/egress checks. Firecrawl performs remote retrieval, so Prism cannot pin target DNS after handoff.
196
196
  - Treat every snippet, highlight, Markdown byte, metadata field, and extracted JSON value as prompt-injection-capable untrusted data. Never elevate it into system instructions or let it modify tools, permissions, trust, credentials, routing, or extraction schema.
@@ -201,7 +201,7 @@ PostgreSQL TLS/network policy, MCP endpoint trust/credentials and egress policy
201
201
  - Require `security / codeql`, `security / supply-chain`, PR dependency review, release readiness, and PostgreSQL integration in protected-branch rules. Enable GitHub secret scanning and push protection as repository settings; checked-in workflows cannot enable those service controls.
202
202
  - Actions are pinned to full commit revisions. Dependabot proposes weekly npm/action revision changes; review upstream release notes before merge rather than replacing pins with moving tags.
203
203
  - `scripts/verify-sbom.mjs` accepts only bounded SPDX 2.3 inventory with exact checked-in permissive licenses. Any missing/new expression fails until reviewed; do not widen policy merely to unblock CI.
204
- - `scripts/scan-secrets.mjs` checks tracked source and unpacked public tarballs for high-confidence credential/private-key forms without printing matched values. It complements GitHub secret scanning; it is not entropy scanning or DLP.
204
+ - `scripts/scan-secrets.mjs` checks tracked source and unpacked public tarballs for high-confidence credential/private-key forms without printing matched values. It complements GitHub secret scanning; it is not entropy scanning or DLP. Local credential files are the one carve-out: `scripts/live.env` and any `*.local.env` are skipped by name because `.gitignore` already excludes them, they hold real keys by design, and CI scans the tracked set where they cannot appear (`scripts/scan-secrets.test.mjs` asserts both names are still gitignored). Every other gitignored file is scanned.
205
205
  - Tag publication alone receives npm/OIDC/attestation permissions. Untrusted pull-request code receives no canary, npm, or OIDC secret and no workflow uses `pull_request_target`.
206
206
  - Scheduled/manual canaries run only in protected `live-canaries` environment. Use dedicated read-only/low-quota credentials and provider account spend limits. Runner performs four probes, at most one MCP cleanup, one provider output token, one Brave result, 64-KiB responses, and finite timeouts; report excludes endpoints, headers, bodies, credentials, and MCP session IDs.
207
207
  - Scheduled/manual coding/browser containment checks run in protected `sandbox-browser` environment (`.github/workflows/sandbox-browser.yml`). They receive no provider/npm/OIDC secrets; Docker/Playwright enablement is variable-gated with host-preloaded digest-pinned images/binaries; uploads are redacted aggregate status only.
@@ -0,0 +1,94 @@
1
+ # Hosted sandboxes
2
+
3
+ ## What it does
4
+
5
+ `createE2BSandbox` / `connectE2BSandbox` map one hosted vendor (E2B) onto the existing `DisposableSandbox` contract: `execFile`, optional `startProcess` / `attachProcess`, `pause` / `resume`, and explicit `kill`. Prism does not run hosted compute. The host owns the E2B account, template, API key, and lifecycle. Pause is the snapshot. `keepMemory: false` is filesystem-only: resume reboots and running processes are gone. `Sandbox.connect` auto-resumes a paused sandbox; this adapter never calls it unless the host calls `resume()` or passes `resume: true`.
6
+
7
+ ## When to use it
8
+
9
+ Use this adapter when coding or process work should run in an E2B cloud sandbox rather than Docker. Use `createDockerSandbox` when you need a local digest-pinned container with `network: none`. Do not assume E2B isolation matches Docker: default capabilities report `networkIsolated` and `egressRestricted` false (E2B sandboxes have internet).
10
+
11
+ ## Inputs / request
12
+
13
+ | Field | Required | Notes |
14
+ | --- | --- | --- |
15
+ | `apiKey` | unless `client` | Resolved at the SDK edge only. Never logged. |
16
+ | `client` | unless `apiKey` | Host-injected `e2b` `Sandbox` surface for tests or a pinned SDK. |
17
+ | `template` | no | Default `base`. Host-owned image/template. |
18
+ | `workdir` | no | Default `/workspace`. |
19
+ | `timeoutMs` / `limits.wallTimeMs` | no | Passed to E2B as sandbox timeout (idle/cost budget). |
20
+ | `onTimeout` | no | `kill` (default) or `pause`. `autoResume` is always false. |
21
+ | `labels` | no | Stored as E2B metadata for reconnect attestation. No secrets. |
22
+ | `expectedLabels` (connect) | no | Fail-closed mismatch → wrong owner. |
23
+ | `resume` (connect) | no | Default false. Paused sandboxes stay paused until `resume()`. |
24
+ | `capabilities` | no | Full host attestation; omitted fields resolve false. |
25
+
26
+ Optional peer: `e2b@2.49.1` (MIT). Install it or pass `client`.
27
+
28
+ ## Outputs / response / events
29
+
30
+ `createE2BSandbox` returns a `DisposableSandbox`:
31
+
32
+ - `id` is the E2B sandbox id (non-secret reconnect identity).
33
+ - `pause({ keepMemory })` → `{ kind: "memory" \| "filesystem", state: "paused" }`. HTTP 503 (`ServiceBusyError`) leaves the sandbox **running**.
34
+ - `resume()` calls `Sandbox.connect` (explicit).
35
+ - `startProcess` refs are `prism-e2b-proc:<base64url>`. Filesystem-only pause makes `attachProcess` return null.
36
+ - `stop()` pauses with memory. `kill()` / `close()` destroy the sandbox. `close({ export })` is unsupported (pause is the snapshot).
37
+ - Default capabilities: workspace coherent, filesystem isolated from the host, process isolated; **not** network/egress/privilege isolated.
38
+
39
+ ## Request/response example
40
+
41
+ ```json
42
+ {
43
+ "template": "base",
44
+ "timeoutMs": 600000,
45
+ "onTimeout": "kill",
46
+ "labels": { "app.owner": "alice" },
47
+ "pause": { "keepMemory": false }
48
+ }
49
+ ```
50
+
51
+ ## Implementation example
52
+
53
+ ```ts
54
+ import { connectE2BSandbox, createE2BSandbox } from "@arnilo/prism-coding-tools/security";
55
+
56
+ const sandbox = await createE2BSandbox({
57
+ apiKey: process.env.E2B_API_KEY,
58
+ labels: { "app.owner": "alice" },
59
+ timeoutMs: 10 * 60_000,
60
+ });
61
+ await sandbox.execFile({ file: "/bin/echo", args: ["ok"], cwd: "/workspace" });
62
+ await sandbox.pause!({ keepMemory: false });
63
+
64
+ const again = await connectE2BSandbox({
65
+ apiKey: process.env.E2B_API_KEY,
66
+ sandboxId: sandbox.id,
67
+ expectedLabels: { "app.owner": "alice" },
68
+ });
69
+ await again.resume!();
70
+ await again.kill();
71
+ ```
72
+
73
+ ## Extension and configuration notes
74
+
75
+ - Detect `pause` / `startProcess` like Docker: `typeof sandbox.pause === "function"`. Absence is not an error on other backends.
76
+ - `createE2BProcessRecoveryBackend(sandbox, { expectedSandboxId, expectedWorkspace, expectedLabels })` is the attested `ProcessRecoveryBackend`. `createProcessSessions({ sandbox })` still auto-wires `attachProcess` when present.
77
+ - `lifecycle.autoResume` is forced false. Activity (exec, file, HTTP) must not resume paused work.
78
+ - Paused E2B sandboxes persist until `kill()`. There is no vendor TTL; the host must delete.
79
+
80
+ ## Security and performance notes
81
+
82
+ - Attest vendor isolation; do not copy Docker `network: none` claims. Override `capabilities` only when the host actually restricted the template/network.
83
+ - API keys belong in `apiKey` or the injected client, never metadata, refs, labels, argv, or logs. Errors pass through `createSecretRedactor`.
84
+ - Process refs carry sandbox id, pid, command fingerprint, and workspace — no secrets.
85
+ - Pause duration is vendor-bound (about 4s per GiB RAM). Command output, env, and concurrent execs use the same sandbox limit caps as Docker (`maxOutputBytes`, `maxCommands`, `maxConcurrentExecs`).
86
+ - A 503 pause refusal is not success: status stays `running`.
87
+ - Filesystem-only resume is a reboot: in-memory state and processes are gone; do not auto-restart them.
88
+
89
+ ## Related APIs
90
+
91
+ - [Coding execution approval and sandboxing](coding-security.md)
92
+ - [Process sessions](process-sessions.md)
93
+ - [Optional peer dependencies](peer-dependencies.md)
94
+ - [Live testing](live-testing.md)
package/docs/index.md CHANGED
@@ -2,9 +2,29 @@
2
2
 
3
3
  Prism is a TypeScript/Node.js agent harness. Hosts own providers, tools, credentials, storage, and behavior; Prism supplies contracts, registries, events, and replaceable runtime primitives.
4
4
 
5
- ## Current line (0.6.0)
5
+ ## Current line (0.8.0)
6
6
 
7
- - **Node 22 floor**: `engines.node` is `>=22` in all ten publishable packages, the `node20-compat` CI leg becomes `node22-compat`, and `@types/node` moves to `^22.20.0` (plan 071; Node 20 is upstream EOL since 2026-04-30).
7
+ - **Messaging channels**: `@arnilo/prism-channels` transport-neutral runtime with deny-by-default authorization, owned bindings, one-use durable approvals, official Telegram (private DMs, opt-in granted groups/topics, drafts, bounded media/voice, opt-in notices) and experimental pinned signal-cli Signal.
8
+ - **Connected apps**: identity-bound MCP server sessions admit host-selected transports and register prefixed tools; Google Workspace and Microsoft 365 HTTP adapters live under `@arnilo/prism-work/connectors`.
9
+ - **Work family**: `@arnilo/prism-work` replaces `@arnilo/prism-office` — connectors, documents, sheets, diagrams, document-reader, sandbox, and vendored office skills. No pre-1.0 shim.
10
+ - **Durable long runs**: turn-boundary checkpoints with host-only `decision: "continue"`, turn-stop policy, frozen run-bundle snapshots, claim-grounding guardrail, and typed provider failure classes.
11
+ - **Honesty surfaces**: Postgres release evidence is this-commit, channel lease release stays held until the store acknowledges, and observational-memory workers ignore non-tool events on purpose.
12
+ - **11 publishable packages** at current **0.8.0** lockstep, with the migration guide reachable from the release section below — inventory below.
13
+
14
+ ### Carried from the 0.7.0 line
15
+
16
+ - **Traps closed**: ACP MCP destination matching uses WHATWG origin plus path-segment subtree rules, the ACP launcher requires a real provider (mock mode is explicit), and the model-router facade refuses governance it cannot enforce (`ERR_PRISM_MODEL_ROUTER_ASYNC_REQUIRED` / `_ASYNC_STATE`).
17
+ - **Governed host surfaces**: validated personal/business compositions, governed provider invocation with aggregate task/tenant accounting, durable business-action drafts with editable approvals, Docker process sessions and coherent workspace recovery, Drive knowledge synchronization, snapshot/reconnect with one hosted sandbox, fair worker admission, cross-layer memory lineage with correction/revocation, evidence-backed citations with import-fidelity/OCR reports, and monotonic per-run tool narrowing.
18
+ - **Evidence cockpit**: execution timeline, workflow graph, trajectory/outcome evals (scenarios, trials, manifests), cockpit aggregations, and workflow OpenTelemetry spans — with the cross-package journey matrix behind them.
19
+ - **Attention Compiler**: opt-in per-turn gate that mutates the transcript only after a ratio of the model input cap, with sticky thinking/tool stubs and a host-programmable compaction trigger.
20
+ - **Memory Fabric**: opt-in typed notes (fact/procedure/file/working/episode) with links, validity windows, and time/tool recall over the working, semantic, and observational-memory engines.
21
+ - **Work-scope memory index**: host-named work scopes (`open`/`bind`/`project`/`enter`) project the observational outline; unscoped attach keeps the 0.6.0 dropper.
22
+ - **Host-owned subagent spawn**: `spawn_agent` over the host supervisor (allow-listed children, narrowed identity, redacted results), bounded async spawn with `wait_agent`/`cancel_agent`, opt-in per-child worktree isolation, and redacted `subagent_started`/`subagent_stopped` lifecycle events.
23
+ - **Native Bedrock Converse and governed realtime voice**: `createBedrockConverseProvider` adds a native `Converse`/`ConverseStream` route next to the OpenAI-compatible one, with no AWS SDK dependency; realtime voice sessions stay host-governed.
24
+
25
+ ### Carried from the 0.6.0 line
26
+
27
+ - **Node 22 floor**: `engines.node` is `>=22` in all eleven publishable packages, the `node20-compat` CI leg becomes `node22-compat`, and `@types/node` moves to `^22.20.0` (plan 071; Node 20 is upstream EOL since 2026-04-30).
8
28
  - **Folded 0.5.7 content**: the 0.5.7 cut was never published — its durable-tool-round and strict-tool-result fixes, host knobs, peer/options truth, and dependency floors ship in 0.6.0 (migration guide below).
9
29
  - **Release-truth gates**: one forward-claim version-literal gate (manifests, internal ranges, lockfile, version constant, index banner, workflow tags), a workflow-liveness gate (every script target and action reference resolves, actions SHA-pinned), and a load-tolerant startup budget ratio (plan 071).
10
30
  - **Self-describing coverage failures**: a failing coverage child prints its redacted output tail and records `status`/`exitCode`/`tail` on its artifact row (plan 071).
@@ -19,13 +39,12 @@ Prism is a TypeScript/Node.js agent harness. Hosts own providers, tools, credent
19
39
  - **Tool-result fold**: content-only `ToolResult`s fold into `tool_result.result` (0.5.3).
20
40
  - **Stream token coalesce**: adjacent text/thinking deltas merge on persist (0.5.2).
21
41
  - **Provider request construction**: kernel session/cache/thinking defaults; hosts overlay (0.5.1).
22
- - **10 publishable packages** at current **0.6.0** lockstep — inventory below.
23
42
 
24
43
  ## Public contracts
25
44
 
26
45
  - [Public contracts](public-contracts.md): canonical message, agent, tool, store, resource, credential, and event shapes.
27
- - [Coding tools, sandboxing, and personas](coding-tools.md): `@arnilo/prism-coding-tools` family subpaths — agent, security, document-reader, openapi, computer-use-linux, dev, personas.
28
- - [Core runtime, sessions, and governance](core.md): `@arnilo/prism-core` family subpaths — runtime, sessions, governance, credentials, enterprise, work, validation.
46
+ - [Coding tools, sandboxing, and personas](coding-tools.md): `@arnilo/prism-coding-tools` family subpaths — agent, security, openapi, computer-use-linux, dev, personas.
47
+ - [Core runtime, sessions, and governance](core.md): `@arnilo/prism-core` family subpaths — runtime, sessions, governance, credentials, enterprise, validation.
29
48
  - [Configuration options index](options-index.md): every public `*Options`/`*Limits`/`*Config` surface mapped to the doc page that owns its fields.
30
49
 
31
50
  ## Identity and governance
@@ -33,21 +52,23 @@ Prism is a TypeScript/Node.js agent harness. Hosts own providers, tools, credent
33
52
  - [Agent identity](agent-identity.md): host-verified `Principal`/`AgentIdentity`, delegation narrowing, redacted telemetry refs, optional OIDC verifier.
34
53
  - [Policy and audit](policy-and-audit.md): allow/deny/modify/approval decision ledger, multi-party approvals, OPA evaluator — evidence refs only.
35
54
  - [Signed, hash-chained audit export](audit-export.md): tenant-scoped signed, hash-chained audit batches with independent verification; no key storage.
36
- - [Model routing](model-routing.md): allow-list/residency/budget/rate/circuit/fallback governance with atomic budget reservation.
55
+ - [Model routing](model-routing.md): allow-list/residency/budget/rate/circuit/fallback governance with atomic budget reservation, aggregate task/tenant accounting across all paid work, and fail-closed synchronous invocation boundaries.
37
56
 
38
57
  ## Agent/session runtime
39
58
 
40
- - [Agent/session runtime](agent-session-runtime.md): create agents/sessions, `run`/`prompt`/`steer`/`stream`, durable resume, batch approvals.
59
+ - [Agent/session runtime](agent-session-runtime.md): create agents/sessions, `run`/`prompt`/`steer`/`stream`, durable resume, batch approvals, per-run `toolNames` narrowing.
60
+ - [Durable runs](durable-runs.md): turn-boundary `checkpointPolicy: "every-turn"` checkpoints and `decision: "continue"` crash recovery for long runs.
41
61
  - [Agent definitions](agent-definitions.md): declarative `AgentDefinition` resolution and `AGENT.md` bundle discovery, fail-closed activation.
42
62
  - [Agent loops](agent-loops.md): replaceable loops with `limits.maxToolRounds` budgets and durable revision/restore hooks.
43
63
  - [Guardrails](guardrails.md): typed fail-closed input/output/tool checks with redacted decision records.
44
64
  - [Agent events](agent-events.md): `turn_started`/`tool_call_delta` stream plus durable page/resume sources for reconnect.
45
- - [Observability](observability.md): OTel GenAI span hierarchy, RAG span tree, bounded trace linkage, exporter isolation.
46
- - [Operations runbook](operations.md): high-availability fencing model, failover drill, replay rules; never unlock leases manually.
65
+ - [Observability](observability.md): OTel GenAI span hierarchy, workflow spans, cockpit aggregations, RAG span tree, bounded trace linkage, exporter isolation.
66
+ - [Execution timeline](execution-timeline.md): execution timeline projection and cockpit summaries for host dashboards and trajectory evals.
67
+ - [Operations runbook](operations.md): high-availability fencing, fair worker admission, operator queue/cancel/reconcile; never unlock leases manually.
47
68
  - [Disaster recovery and backup operations](disaster-recovery.md): backup/restore/PITR/DR-drill runbook with guarded commands and RPO/RTO.
48
69
  - [Data classification and field-level redaction](data-classification.md): `applyFieldPolicy` allow/redact/tokenize/deny walks with fail-closed protected default.
49
- - [Evaluations](evaluations.md): deterministic bounded trace/model-judge/pairwise scoring with CI thresholds and trace linkage.
50
- - [Runs and usage ledger](runs-and-usage.md): durable run/event/usage persistence, host-raisable `RunLimits`, `CostCatalog` pricing.
70
+ - [Evaluations](evaluations.md): trajectory/outcome scorers over execution timelines, citation-integrity invariant, workflow experiments, scenarios, repeated trials that re-run items with sample standard error, failure injection, two-field and release manifests, deterministic bounded trace/model-judge scoring.
71
+ - [Runs and usage ledger](runs-and-usage.md): durable run/event/usage persistence, aggregate task accounting across paid work, host-raisable `RunLimits`, `CostCatalog` pricing.
51
72
  - [Performance limits](performance.md): frozen 0.1.0 capacity envelopes and network-free benchmark evidence — the performance contract.
52
73
  - [Structured output](structured-output.md): `Artifact*` seam plus provider-native `StructuredOutputOptions` for capable models.
53
74
 
@@ -55,11 +76,12 @@ Prism is a TypeScript/Node.js agent harness. Hosts own providers, tools, credent
55
76
 
56
77
  - [Compaction and retry policies](compaction-and-retry.md): host-replaceable summarize/retry policies with deprecated-option removals fail closed.
57
78
  - [LLM compaction subpath](compaction-llm.md): provider-backed summarization with finite `model.parameters.maxTokens` and coding handoff strategy.
58
- - [Observational memory compaction subpath](compaction-observational-memory.md): observations/reflections with `appendEntry`, exact-id recall, nested-only settings.
59
- - [Working and semantic memory](working-and-semantic-memory.md): working-memory store, semantic recall, pgvector path, consent lifecycle.
79
+ - [Observational memory compaction subpath](compaction-observational-memory.md): source-backed observations/reflections, an optional work-scope index for the current working set, and exact-id recall; `invalidatedIds` withhold derived injection.
80
+ - [Working and semantic memory](working-and-semantic-memory.md): working-memory store, semantic recall, pgvector path, consent lifecycle, lineage invalidation, parent-child share grants.
81
+ - [Memory fabric](memory-fabric.md): opt-in typed notes (fact/procedure/file/working/episode) with validity windows over the existing vector and working stores.
60
82
  - [Session stores](session-stores.md): `SessionStore` contract, append options, branches, bounded search — start here for persistence.
61
83
  - [Conversations](conversations.md): durable user-scoped threads with versioned metadata and legal-hold-aware deletion.
62
- - [Work artifacts and review](work-artifacts-and-review.md): artifact attach, revision compare, approve/reject, expiring delivery links.
84
+ - [Work artifacts and review](work-artifacts-and-review.md): artifact attach, revision compare, evidence-bound citations, approve/reject, expiring delivery links.
63
85
  - [Session stores and branching](session-stores-and-branching.md): branch-semantics helper reference (compatibility stub for session-stores.md).
64
86
  - [Database persistence](database-persistence.md): production persistence contracts, migrations, retention, and adapter conformance harnesses.
65
87
  - [SQLite persistence](sqlite-persistence.md): optional `better-sqlite3` adapter with FTS search and verified migrations.
@@ -72,6 +94,7 @@ Prism is a TypeScript/Node.js agent harness. Hosts own providers, tools, credent
72
94
 
73
95
  - [Embeddings](embeddings.md): provider-neutral batch `embedMany` contract with OpenAI-compatible and DashScope adapters.
74
96
  - [Speech and transcription](speech.md): provider-neutral synthesis and transcription contracts with streaming variants.
97
+ - [Realtime voice](realtime-voice.md): governed OpenAI Realtime bridge into host tool dispatch, barge-in, reconnect, and transcript privacy.
75
98
  - [Image generation and editing](image-generation.md): provider-neutral generate/edit contract with OpenAI and DashScope adapters.
76
99
  - [Moderation](moderation.md): provider-neutral classification under a neutral vocabulary; scores are provider output.
77
100
  - [Batch jobs](batch-jobs.md): provider-neutral submit/status/cancel/results contract with OpenAI Files-API adapter.
@@ -84,7 +107,7 @@ Prism is a TypeScript/Node.js agent harness. Hosts own providers, tools, credent
84
107
  - [Provider request policies](provider-request-policies.md): kernel request-option defaults with host `ProviderRequestPolicy` overlays.
85
108
  - [Provider packages](provider-packages.md): all adapters as `@arnilo/prism-providers/<adapter>` subpaths; tool_result and event wire shapes stay provider-neutral.
86
109
  - First-party adapters: [`openai`](providers/openai.md), [`anthropic`](providers/anthropic.md), [`google`](providers/google.md), [`opencode-go`](providers/opencode-go.md), [`openrouter`](providers/openrouter.md), [`zai`](providers/zai.md), [`deepseek`](providers/deepseek.md), [`xai`](providers/xai.md), [`clinepass`](providers/clinepass.md), [`hyper`](providers/hyper.md), [`commandcode`](providers/commandcode.md), [`kimi`](providers/kimi.md), [`alibaba`](providers/alibaba.md), [`ollama`](providers/ollama.md), [`neuralwatt`](providers/neuralwatt.md), plus the cross-vendor `model-discovery` listing adapters on the same page.
87
- - Enterprise cloud (workload identity): [`azure`](providers/azure.md) (Entra/Foundry), [`bedrock`](providers/bedrock.md) (IAM/SigV4), [`vertex`](providers/vertex.md) (ADC/Vertex).
110
+ - Enterprise cloud (workload identity): [`azure`](providers/azure.md) (Entra/Foundry), [`bedrock`](providers/bedrock.md) (IAM/SigV4; OpenAI-compatible or native Converse route), [`vertex`](providers/vertex.md) (ADC/Vertex).
88
111
  - Optional AI SDK adapter: [`ai-sdk`](providers/ai-sdk.md) maps host-owned pinned `LanguageModelV4` models onto Prism streams.
89
112
  - [OpenAI-compatible provider](providers/openai-compatible.md): base Chat Completions subpath with strict-completion default and vendor hooks.
90
113
 
@@ -92,42 +115,47 @@ Prism is a TypeScript/Node.js agent harness. Hosts own providers, tools, credent
92
115
 
93
116
  - [SDK customization guide](customization.md): map every replaceable seam — providers, middleware, loops, stores — to explicit host wiring.
94
117
  - [Input and prompt assembly](input-and-prompt-assembly.md): input-to-message builders, cache-aware ordering, optional context-budget eviction.
118
+ - [Attention compiler](attention-compiler.md): opt-in per-turn gate that mutates only after a ratio of the model input cap.
95
119
  - [Multimodal content](multimodal-content.md): media resolution, SSRF/MIME policy, capability tags, video generation contract.
96
120
  - [System prompts](system-prompts.md): layered system prompts plus trust-gated `AGENTS.md`/`SYSTEM.md` file auto-load.
97
121
  - [Versioned prompt registry](prompt-registry.md): immutable content-hashed prompt assets with durable stores and bounded diff.
98
122
  - [Instruction injection](instruction-injection.md): package injectors layer redacted instructions without granting capabilities.
99
- - [Context and skills](context-and-skills.md): ordered context providers, progressive skill disclosure, fail-closed activation.
123
+ - [Context and skills](context-and-skills.md): ordered context providers, progressive skill disclosure, fail-closed activation. `@arnilo/prism-work` ships `docx`, `xlsx`, `powerpoint`, `pdf`.
100
124
  - [LLM Wiki](wiki.md): optional knowledge compiler emitting OKF bundles, with `/wiki-ingest` raw staging (text, file, image, or URL via a host `fetchUrl` hook) and on-device hybrid search.
101
- - [Retrieval-augmented generation](rag.md): bounded source lifecycle, hybrid retrieval, reranking, citations, inert injection.
125
+ - [Retrieval-augmented generation](rag.md): bounded source lifecycle, hybrid retrieval, permission-trimmed query legs, reranking, evidence-backed citations, inert injection.
126
+ - [Knowledge synchronization](knowledge-sync.md): paged enterprise-source import with a Drive connector, checkpointed change cursors, and host-owned ACL mapping.
102
127
 
103
128
  ## Tools
104
129
 
105
130
  - [Recoverable tool effects](tool-effects.md): effect declarations, claim/CAS store, unknown reconciliation classifications.
106
- - [Tools](tools.md): host-owned tool registration, allow/deny filtering, bounded artifact-loop dispatch, progressive loading.
131
+ - [Tools](tools.md): host-owned tool registration, allow/deny filtering, per-run `toolNames` narrowing, bounded artifact-loop dispatch, progressive loading.
107
132
  - [OpenAPI tools adapter](openapi-tools.md): compile allow-listed OpenAPI 3.1 operations into bounded, approval-gated tools.
108
133
  - [Tool execution primitives](tool-execution-primitives.md): bounded JSON Schema validation, parallel dispatch, MCP bridge mapping.
109
134
  - [Tool validator JSON Schema package](../packages/prism-core/README.md): optional `@arnilo/prism-core/validation/json-schema` adapter.
110
135
  - [MCP client bridge and server exposure](mcp-tools.md): SDK v2 bridge and serving with OAuth transports and DNS-pinned transport.
111
- - [Web search, fetch, and extraction](web-tools.md): Brave/Exa/Firecrawl tools with finite limits and untrusted-content boundaries.
112
- - [Work tools](work-tools.md): identity-scoped M365/GWS connectors — draft-then-approve, isolated subprocess environments.
136
+ - [Connected apps](connected-apps.md): identity-bound MCP server sessions that admit host-selected transports and register prefixed tools.
137
+ - [Web search, fetch, and extraction](web-tools.md): Brave/Exa/Firecrawl tools with finite limits, hashed web evidence snapshots, and untrusted-content boundaries.
138
+ - [Work tools](work-tools.md): identity-scoped M365/GWS connectors — scanned file get, hash-bound uploads/copies, fixed Docs/Sheets/Slides updates, approvals, isolated subprocess environments.
113
139
  - [Work connectors](work-connectors.md): connector principles, capability gates, scoped OAuth establishment, out-of-scope boundaries.
140
+ - [Work sandbox](work-sandbox.md): host-pinned document image and `createWorkComposition` — office/exec in an injected Docker sandbox, connectors stay on the host.
114
141
  - [Browser automation](browser-automation.md): Playwright-backed browser tools with egress policy, caps, and verified checkpoints.
115
142
  - [Device adapters](device-adapters.md): deny-by-default realtime voice/desktop-control contract with consent and sandbox gating.
116
143
  - [Linux desktop control](computer-use-linux.md): optional `computer-use-linux` MCP wrapper — doctor-first, approval-gated mutators.
117
144
  - [Obscura browser engine](obscura.md): optional host-binary browser engine adapter with fail-closed lifecycle and CDP composition.
118
145
  - [Coding agent tools](coding-agent-tools.md): shell/read/write/edit/search toolset with caps, document reader, and optional Git awareness.
119
- - [Document reader](document-reader.md): bounded PDF/DOCX text extraction behind `createReadTool({ documentReader })`.
146
+ - [Document reader](document-reader.md): bounded PDF/DOCX/XLSX/PPTX text extraction behind `createReadTool({ documentReader })`; optional host-selected Mistral OCR parser (not default).
120
147
  - [Indexed code search](indexed-code-search.md): host-owned incremental index seam; results labeled `untrusted_index`.
121
- - [Coding workspaces](coding-workspaces.md): worktree lifecycle with CheckpointStore CAS records and LeaseStore fencing.
148
+ - [Coding workspaces](coding-workspaces.md): worktree lifecycle with CheckpointStore CAS records, LeaseStore fencing, and opt-in per-child spawn isolation.
122
149
  - [Coding review and diagnostics](coding-review-and-diagnostics.md): bounded patch-review manifests and normalized LSP diagnostics.
123
150
  - [Language intelligence](language-intelligence.md): bounded LSP client with lazy spawn, URI confinement, policy-gated rename.
124
- - [Process sessions](process-sessions.md): long-running process registry with durable recovery and fail-closed ownership.
151
+ - [Process sessions](process-sessions.md): long-running process registry with durable recovery, Docker/E2B container sessions, and fail-closed ownership.
125
152
  - [Forge integration](forge-integration.md): reference GitHub adapter — every mutation policy-gated and effect-recorded.
126
- - [Coding execution approval and sandboxing](coding-security.md): path/command approval, workspace modes, Docker/native sandboxes, egress allow-listing.
153
+ - [Coding execution approval and sandboxing](coding-security.md): path/command approval, workspace modes, Docker/native/E2B sandboxes with long-running process handles, egress allow-listing.
154
+ - [Hosted sandboxes](hosted-sandboxes.md): E2B `DisposableSandbox` adapter with pause/resume, filesystem-only snapshots, and reconnect by non-secret sandbox id.
127
155
 
128
156
  ## Documents, sheets, and diagrams
129
157
 
130
- - [Documents, spreadsheets, and presentations](documents.md): OOXML generation, parsing, patching, and bounded preview for Office formats.
158
+ - [Documents, spreadsheets, and presentations](documents.md): OOXML generation, parsing, import fidelity reports, patching, structural diffs, and bounded preview for Office formats.
131
159
  - [Spreadsheets and CSV data](sheets.md): fail-closed XLSX/CSV ingestion with decimal-safety guarantees.
132
160
  - [Diagrams and mxGraph embed](diagrams.md): origin-enforced draw.io embed client with XXE-safe XML validation.
133
161
 
@@ -142,29 +170,31 @@ Prism is a TypeScript/Node.js agent harness. Hosts own providers, tools, credent
142
170
  ## Configuration/manifests
143
171
 
144
172
  - [Configuration and manifests](configuration-and-manifests.md): layered JSON config merge with data-only manifest validation.
173
+ - [Effective run bundle snapshots](run-bundle.md): frozen JSON projection of the effective run bundle — prompt/skill/tool/guardrail digests, resolved limits, storage kinds, one pinning digest, zero network or store reads.
174
+ - [Host compositions](host-compositions.md): personal and business worker host compositions, inspection reports, storage durability truth, sandbox isolation, and fail-closed readiness enforcement.
145
175
  - [Node filesystem config loader](node-filesystem-config.md): explicitly read caller-named JSON config files in Node.
146
176
  - [Resource loading](resource-loading.md): decode text/JSON/binary through caller-provided loaders; RAG bridge.
147
177
  - [Optional peer dependencies](peer-dependencies.md): every third-party peer a package declares, the subpath it unlocks, its install line, pin rationale, and which peers touch the network.
148
178
 
149
179
  ## Server/API
150
180
 
151
- - [Web-standard server handler](server.md): framework-free authorized agent/SSE handler with durable reconnect and webhook seams.
181
+ - [Web-standard server handler](server.md): framework-free authorized agent/SSE handler with durable reconnect, editable approvals, and webhook seams.
152
182
 
153
183
  ## Multi-agent and interoperability
154
184
 
155
- - [Multi-agent patterns (handoff/crew/supervisor/A2A)](multi-agent-patterns.md): decision table for handoff, crew, supervisor, and A2A.
156
- - [Supervisor delegation](supervisors.md): child allow-lists, narrowed permissions, finite budgets, nested delegation.
185
+ - [Multi-agent patterns (handoff/crew/supervisor/spawn/A2A)](multi-agent-patterns.md): decision table for handoff, crew, supervisor, in-process spawn, and A2A.
186
+ - [Supervisor delegation](supervisors.md): child allow-lists, model-facing sync/async spawn, wait/cancel, narrowed permissions, finite budgets, nested delegation.
157
187
  - [A2A interoperability](a2a.md): A2A 1.0 cards, durable task seams, verified client, AG-UI fronting.
158
- - [Frontend interoperability (AG-UI and ACP)](ag-ui.md): AG-UI event mapping, A2UI middleware, hardened MCP/A2A adapters, ACP sibling.
188
+ - [Frontend interoperability (AG-UI and ACP)](ag-ui.md): AG-UI event mapping with editable durable approvals, A2UI middleware, hardened MCP/A2A adapters, ACP sibling.
159
189
  - [ACP coding-host interop](acp.md): stable ACP v1 agent with capability advertisement, approvals, durability, and projections.
160
- - [Spawnable ACP agent](acp-agent.md): stdio bin serving `createPrismAcpAgent` from a validated config file.
190
+ - [Spawnable ACP agent](acp-agent.md): stdio bin serving `createPrismAcpAgent` with lazy real providers, credential references, explicit offline mock mode, durable SQLite recovery, and origin- and path-safe MCP allow-listing.
161
191
  - [AG-UI adoption evaluation](ag-ui-adoption.md): official AG-UI matrix and shipped handshake boundaries.
162
192
 
163
193
  ## CLI/RPC
164
194
 
165
- - [Dev inspector](dev-inspector.md): loopback-only local playground over a configured agent; `prism dev` composition.
166
- - [CLI/RPC](cli-rpc.md): print/json modes, LF-delimited RPC, `prism init` scaffold, provider scaffolding, allow-listed `--extension` activation.
167
- - [Workflows](workflows.md): typed bounded DAG orchestration with durable suspend/resume, schedules, sagas.
195
+ - [Dev inspector](dev-inspector.md): loopback-only local playground over a configured agent; composition inspection via `GET /inspect`; quality/cost/latency compare from timeline summaries; `prism dev` composition.
196
+ - [CLI/RPC](cli-rpc.md): print/json modes, LF-delimited RPC, `prism init` scaffold (`personal-assistant`, `business-worker`, `deep-research` templates), provider scaffolding, allow-listed `--extension` activation.
197
+ - [Workflows](workflows.md): typed DAG orchestration plus serializable graph/Mermaid overlay for host UIs.
168
198
 
169
199
  ## Security and credentials
170
200
 
@@ -185,7 +215,7 @@ Prism is a TypeScript/Node.js agent harness. Hosts own providers, tools, credent
185
215
  - [Compaction conformance](compaction-conformance.md): assert redacted non-empty summaries and abort observation.
186
216
  - [Tool conformance](tool-conformance.md): assert blocked-reason matrix and success-path dispatch behavior.
187
217
  - [Extension conformance](extension-conformance.md): assert inert contributions and redacted setup errors.
188
- - `examples/`: compile-checked typed examples ([`conversation-durable-replay.ts`](../examples/conversation-durable-replay.ts), [`artifact-review-delivery.ts`](../examples/artifact-review-delivery.ts), [`enterprise-identity.ts`](../examples/enterprise-identity.ts), [`enterprise-policy-audit.ts`](../examples/enterprise-policy-audit.ts), [`enterprise-work-connectors.ts`](../examples/enterprise-work-connectors.ts), [`server-deployment-seams.ts`](../examples/server-deployment-seams.ts), [`neuralwatt-agent-run.ts`](../examples/neuralwatt-agent-run.ts), [`cache-aware-prompt-assembly.ts`](../examples/cache-aware-prompt-assembly.ts), [`ag-ui-server.ts`](../examples/ag-ui-server.ts), [`acp-coding-host.ts`](../examples/acp-coding-host.ts), and more), plus runnable mock demos.
218
+ - `examples/`: compile-checked typed examples ([`conversation-durable-replay.ts`](../examples/conversation-durable-replay.ts), [`artifact-review-delivery.ts`](../examples/artifact-review-delivery.ts), [`enterprise-identity.ts`](../examples/enterprise-identity.ts), [`enterprise-policy-audit.ts`](../examples/enterprise-policy-audit.ts), [`enterprise-work-connectors.ts`](../examples/enterprise-work-connectors.ts), [`connected-slack-mcp.ts`](../examples/connected-slack-mcp.ts), [`server-deployment-seams.ts`](../examples/server-deployment-seams.ts), [`neuralwatt-agent-run.ts`](../examples/neuralwatt-agent-run.ts), [`cache-aware-prompt-assembly.ts`](../examples/cache-aware-prompt-assembly.ts), [`ag-ui-server.ts`](../examples/ag-ui-server.ts), [`acp-coding-host.ts`](../examples/acp-coding-host.ts), [`telegram-agent.ts`](../examples/telegram-agent.ts), [`signal-agent.ts`](../examples/signal-agent.ts), [`messaging-agent.ts`](../examples/messaging-agent.ts), and more), plus runnable mock demos.
189
219
 
190
220
  ## Third-party integrations
191
221
 
@@ -193,10 +223,16 @@ Prism is a TypeScript/Node.js agent harness. Hosts own providers, tools, credent
193
223
  - [Ponytail behavior integration](ponytail.md): upstream Ponytail skills with injector and peer resolution; opt-in.
194
224
  - [Graft context-graph integration](graft.md): graft CLI pull tools, retrieval-pack context provider, blast-radius middleware, and `/graft-init` / `/graft-build` / `/graft-build-deep` commands (host-configured `deepModel`).
195
225
  - [Impeccable behavior integration](impeccable.md): upstream Impeccable skill behind `load_skill`; host supplies the compiled `SKILL.md`.
226
+ - [Messaging channels](messaging-channels.md): `@arnilo/prism-channels` transport-neutral runtime — deny-by-default sender authorization, owned session binding, serialized turns, current-run replies, one-use durable approvals, bounded attachment refs (images reach the model only when it declares image input), and opt-in host notices to one already-bound pair.
227
+ - [Telegram channel](telegram-channel.md): official `@arnilo/prism-channels/telegram` long polling and mountable webhook ingress with durable offset/lease handling, approval callbacks, opt-in granted group/topic text, bounded media with optional voice transcription/synthesis, and opt-in streaming drafts.
228
+ - [Signal channel (experimental)](signal-channel.md): `@arnilo/prism-channels/signal` pinned signal-cli v0.14.8 private-socket manual receive, explicit policy gate, UUID DM filtering and bounded ambiguous delivery.
229
+ - [Messaging channel operations](messaging-channel-operations.md): durable journal, restart and reconciliation contract, lease fencing, retention and the operator runbook.
196
230
 
197
231
  ## Release and install
198
232
 
199
233
  - [Release and install](release-and-install.md): install rules, package graph, and deterministic resumable publication.
234
+ - [Migrate 0.7 → 0.8](migrate-to-0.8.md): work-family import map, messaging channels, connected apps, durable runs, and 0.8.0 host migration steps.
235
+ - [Migrate 0.6 → 0.7](migrate-to-0.7.md): ACP MCP allow-list URL normalization, model router facade fail-closed governance, and 0.7.0 host migration steps.
200
236
  - [Migrate 0.5 → 0.6](migrate-to-0.6.md): Node 22 floor, folded 0.5.7 host delta, third-party floors, and upgrade/rollback steps.
201
237
  - [Migrate 0.5](migrate-to-0.5.md): 0.4 → 0.5 migration guide with per-release sections and rollback.
202
238
  - [Documentation archive](history/README.md): frozen migration/history records — not read on the hot path.
@@ -207,18 +243,19 @@ Prism is a TypeScript/Node.js agent harness. Hosts own providers, tools, credent
207
243
  The generated inventory below derives from [`scripts/package-truth.json`](../scripts/package-truth.json) — regenerate with `node scripts/package-truth.mjs --emit-docs`, never hand-edit.
208
244
 
209
245
  <!-- generated:package-truth:inventory begin -->
210
- **10 publishable manifests** — root `@arnilo/prism` plus 9 workspace packages (3 `prism-*` family packages, 6 capability packages). Generated by `node scripts/package-truth.mjs --emit-docs` — do not hand-edit.
246
+ **11 publishable manifests** — root `@arnilo/prism` plus 10 workspace packages (4 `prism-*` family packages, 6 capability packages). Generated by `node scripts/package-truth.mjs --emit-docs` — do not hand-edit.
211
247
 
212
248
  | package | version | notes |
213
249
  | --- | --- | --- |
214
- | `@arnilo/prism` | 0.6.0 | core — runtime, CLI/RPC, templates, docs |
215
- | `@arnilo/prism-coding-tools` | 0.6.0 | family — /agent, /security, /document-reader, /openapi, /computer-use-linux, /dev, /caveman, /ponytail, /impeccable subpaths |
216
- | `@arnilo/prism-core` | 0.6.0 | family — /runtime, /sessions, /governance, /credentials, /enterprise, /work, /validation subpaths |
217
- | `@arnilo/prism-providers` | 0.6.0 | family — all provider adapters as `/<adapter>` subpaths |
218
- | `@arnilo/prism-acp-agent` | 0.6.0 | capability — ACP adapter |
219
- | `@arnilo/prism-ag-ui` | 0.6.0 | capability — AG-UI/A2A/A2UI adapter |
220
- | `@arnilo/prism-mcp` | 0.6.0 | capability — MCP client/server/OAuth interop |
221
- | `@arnilo/prism-memory` | 0.6.0 | capability — memory plus /rag, /compaction/*, /graft, /wiki subpaths |
222
- | `@arnilo/prism-office` | 0.6.0 | capability — /documents, /sheets, /diagrams subpaths |
223
- | `@arnilo/prism-web-tools` | 0.6.0 | capability — Brave/Exa/Firecrawl plus peer-gated /browser and /obscura subpaths |
250
+ | `@arnilo/prism` | 0.8.0 | core — runtime, CLI/RPC, templates, docs |
251
+ | `@arnilo/prism-channels` | 0.8.0 | family — transport-neutral messaging runtime, durable journal, pairing and one-use approvals; official /telegram (private DMs, opt-in granted groups/topics) and experimental pinned signal-cli /signal |
252
+ | `@arnilo/prism-coding-tools` | 0.8.0 | family — /agent, /security, /openapi, /computer-use-linux, /dev, /caveman, /ponytail, /impeccable subpaths |
253
+ | `@arnilo/prism-core` | 0.8.0 | family — /runtime, /sessions, /governance, /credentials, /enterprise, /validation subpaths |
254
+ | `@arnilo/prism-providers` | 0.8.0 | family — all provider adapters as `/<adapter>` subpaths |
255
+ | `@arnilo/prism-acp-agent` | 0.8.0 | capability — ACP adapter |
256
+ | `@arnilo/prism-ag-ui` | 0.8.0 | capability — AG-UI/A2A/A2UI adapter |
257
+ | `@arnilo/prism-mcp` | 0.8.0 | capability — MCP client/server/OAuth interop |
258
+ | `@arnilo/prism-memory` | 0.8.0 | capability — memory plus /rag, /compaction/*, /fabric, /graft, /wiki subpaths |
259
+ | `@arnilo/prism-web-tools` | 0.8.0 | capability — Brave/Exa/Firecrawl plus peer-gated /browser and /obscura subpaths |
260
+ | `@arnilo/prism-work` | 0.8.0 | capability — /connectors, /documents, /sheets, /diagrams, /document-reader, /sandbox, /skills, /tools subpaths |
224
261
  <!-- generated:package-truth:inventory end -->
@@ -189,3 +189,4 @@ const request = await assembleProviderInput({
189
189
  - [Agent/session runtime](agent-session-runtime.md): calls assembly each turn and supplies runtime tool results to the next provider request.
190
190
  - [Tools](tools.md): host-owned tool registry and tool result boundary.
191
191
  - [Compaction and retry policies](compaction-and-retry.md): default compaction strategy that feeds summaries into input assembly.
192
+ - [Attention compiler](attention-compiler.md): opt-in per-turn ratio gate that strips old thinking and stubs old tool results on the assembled groups before they reach the prompt builder.