@arnilo/prism 0.0.96 → 0.1.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 (203) hide show
  1. package/CHANGELOG.md +285 -2
  2. package/README.md +17 -3
  3. package/dist/agent-definitions.js +2 -3
  4. package/dist/agent-event-source.d.ts +11 -0
  5. package/dist/agent-event-source.js +512 -0
  6. package/dist/agent-loops.d.ts +5 -0
  7. package/dist/agent-loops.js +99 -14
  8. package/dist/agent-run-lifecycle.d.ts +5 -2
  9. package/dist/agent-run-lifecycle.js +18 -2
  10. package/dist/agent-run-state.d.ts +27 -1
  11. package/dist/agent-run-state.js +113 -7
  12. package/dist/agents.d.ts +3 -1
  13. package/dist/agents.js +1255 -129
  14. package/dist/artifacts.d.ts +132 -0
  15. package/dist/artifacts.js +44 -0
  16. package/dist/cache-helpers.js +18 -9
  17. package/dist/checkpoints.d.ts +4 -0
  18. package/dist/checkpoints.js +17 -9
  19. package/dist/cli-init.js +3 -7
  20. package/dist/cli-runner.d.ts +2 -6
  21. package/dist/cli-runner.js +71 -33
  22. package/dist/compaction.js +5 -4
  23. package/dist/config.js +7 -4
  24. package/dist/content.js +26 -24
  25. package/dist/context-budget.d.ts +67 -0
  26. package/dist/context-budget.js +288 -0
  27. package/dist/contracts.d.ts +590 -8
  28. package/dist/contracts.js +142 -1
  29. package/dist/contribution-parsing.js +6 -2
  30. package/dist/contributions.d.ts +2 -0
  31. package/dist/contributions.js +3 -0
  32. package/dist/conversations.d.ts +50 -0
  33. package/dist/conversations.js +98 -0
  34. package/dist/credentials.d.ts +22 -2
  35. package/dist/credentials.js +18 -3
  36. package/dist/devices.d.ts +94 -0
  37. package/dist/devices.js +138 -0
  38. package/dist/event-multiplexer.js +18 -4
  39. package/dist/extensions.d.ts +18 -1
  40. package/dist/extensions.js +79 -6
  41. package/dist/feedback.js +12 -10
  42. package/dist/guardrails.d.ts +1 -1
  43. package/dist/guardrails.js +26 -17
  44. package/dist/identity.d.ts +92 -0
  45. package/dist/identity.js +265 -0
  46. package/dist/index.d.ts +94 -72
  47. package/dist/index.js +48 -36
  48. package/dist/input.d.ts +10 -1
  49. package/dist/input.js +152 -52
  50. package/dist/instruction-injection.d.ts +1 -1
  51. package/dist/middleware.js +9 -1
  52. package/dist/models.d.ts +2 -0
  53. package/dist/models.js +3 -0
  54. package/dist/node/agent-definitions.js +16 -8
  55. package/dist/node/contribution-discovery.d.ts +1 -2
  56. package/dist/node/contribution-discovery.js +3 -3
  57. package/dist/node/session-store-jsonl.js +13 -7
  58. package/dist/node/settings.d.ts +1 -1
  59. package/dist/node/settings.js +1 -1
  60. package/dist/node/system-project-prompts.js +2 -4
  61. package/dist/node/trust.js +1 -1
  62. package/dist/persistence-lifecycle.d.ts +103 -0
  63. package/dist/persistence-lifecycle.js +202 -0
  64. package/dist/provider-events.d.ts +1 -0
  65. package/dist/provider-events.js +6 -1
  66. package/dist/provider-request-policy.js +3 -4
  67. package/dist/providers/media.d.ts +1 -1
  68. package/dist/providers/openai-compatible.d.ts +46 -1
  69. package/dist/providers/openai-compatible.js +123 -53
  70. package/dist/providers/openai-primitives.js +10 -7
  71. package/dist/providers/transport.d.ts +6 -0
  72. package/dist/providers/transport.js +21 -0
  73. package/dist/providers.d.ts +2 -0
  74. package/dist/providers.js +3 -0
  75. package/dist/redaction.d.ts +1 -0
  76. package/dist/redaction.js +26 -9
  77. package/dist/resources.d.ts +2 -2
  78. package/dist/resources.js +2 -2
  79. package/dist/retry.d.ts +5 -0
  80. package/dist/retry.js +8 -1
  81. package/dist/rpc.js +55 -11
  82. package/dist/run-ledger.d.ts +6 -0
  83. package/dist/run-ledger.js +16 -13
  84. package/dist/run-limits.js +49 -10
  85. package/dist/secure-agent.js +8 -2
  86. package/dist/security.js +7 -2
  87. package/dist/session-stores.d.ts +7 -2
  88. package/dist/session-stores.js +195 -21
  89. package/dist/skill-disclosure.d.ts +35 -0
  90. package/dist/skill-disclosure.js +101 -0
  91. package/dist/skill-load.d.ts +25 -0
  92. package/dist/skill-load.js +112 -0
  93. package/dist/structured-output.d.ts +5 -1
  94. package/dist/structured-output.js +20 -2
  95. package/dist/system-prompts.js +7 -2
  96. package/dist/testing/agent-event-source-conformance.d.ts +4 -0
  97. package/dist/testing/agent-event-source-conformance.js +54 -0
  98. package/dist/testing/compaction-conformance.js +5 -1
  99. package/dist/testing/extension-conformance.js +15 -3
  100. package/dist/testing/feedback.d.ts +1 -3
  101. package/dist/testing/feedback.js +1 -1
  102. package/dist/testing/persistence-schema.d.ts +2 -2
  103. package/dist/testing/persistence-schema.js +280 -35
  104. package/dist/testing/provider-conformance.js +3 -3
  105. package/dist/testing/run-ledger-conformance.js +1 -1
  106. package/dist/testing/session-store-conformance.d.ts +6 -0
  107. package/dist/testing/session-store-conformance.js +37 -2
  108. package/dist/testing/tool-conformance.js +30 -5
  109. package/dist/testing/tool-effect-store-conformance.d.ts +9 -0
  110. package/dist/testing/tool-effect-store-conformance.js +85 -0
  111. package/dist/thinking.js +4 -1
  112. package/dist/tool-effects.d.ts +15 -0
  113. package/dist/tool-effects.js +352 -0
  114. package/dist/tool-result-fold.d.ts +40 -0
  115. package/dist/tool-result-fold.js +176 -0
  116. package/dist/tools.d.ts +8 -3
  117. package/dist/tools.js +248 -13
  118. package/docs/0.1.0-readiness.md +202 -0
  119. package/docs/a2a.md +33 -2
  120. package/docs/acp.md +126 -0
  121. package/docs/ag-ui-adoption.md +77 -0
  122. package/docs/ag-ui.md +225 -0
  123. package/docs/agent-events.md +34 -3
  124. package/docs/agent-identity.md +144 -0
  125. package/docs/agent-loops.md +17 -2
  126. package/docs/agent-session-runtime.md +21 -4
  127. package/docs/browser-automation.md +5 -0
  128. package/docs/caveman.md +129 -0
  129. package/docs/cli-rpc.md +3 -6
  130. package/docs/coding-agent-tools.md +229 -25
  131. package/docs/coding-security.md +77 -11
  132. package/docs/compaction-and-retry.md +5 -2
  133. package/docs/compaction-llm.md +20 -1
  134. package/docs/compaction-observational-memory.md +52 -8
  135. package/docs/context-and-skills.md +94 -7
  136. package/docs/contribution-registries.md +1 -0
  137. package/docs/conversations.md +135 -0
  138. package/docs/credential-storage.md +34 -1
  139. package/docs/credentials-and-redaction.md +11 -1
  140. package/docs/database-persistence.md +27 -7
  141. package/docs/device-adapters.md +97 -0
  142. package/docs/enterprise-postgres-state.md +178 -0
  143. package/docs/evaluations.md +14 -1
  144. package/docs/extensions.md +4 -1
  145. package/docs/forge-integration.md +113 -0
  146. package/docs/guardrails.md +16 -2
  147. package/docs/host-security.md +35 -4
  148. package/docs/index.md +69 -37
  149. package/docs/input-and-prompt-assembly.md +8 -7
  150. package/docs/language-intelligence.md +162 -0
  151. package/docs/mcp-tools.md +62 -5
  152. package/docs/middleware-hooks.md +2 -2
  153. package/docs/migration.md +423 -2
  154. package/docs/model-routing.md +111 -0
  155. package/docs/multimodal-content.md +8 -5
  156. package/docs/node-jsonl-session-store.md +1 -1
  157. package/docs/observability.md +2 -0
  158. package/docs/openapi-tools.md +56 -0
  159. package/docs/performance.md +282 -0
  160. package/docs/policy-and-audit.md +171 -0
  161. package/docs/ponytail.md +127 -0
  162. package/docs/postgres-persistence.md +8 -4
  163. package/docs/process-sessions.md +147 -0
  164. package/docs/provider-caching.md +13 -1
  165. package/docs/provider-conformance.md +29 -5
  166. package/docs/provider-packages.md +43 -2
  167. package/docs/provider-request-policies.md +2 -0
  168. package/docs/providers/ai-sdk.md +24 -7
  169. package/docs/providers/alibaba.md +179 -0
  170. package/docs/providers/anthropic.md +93 -0
  171. package/docs/providers/azure.md +74 -0
  172. package/docs/providers/bedrock.md +72 -0
  173. package/docs/providers/google.md +89 -0
  174. package/docs/providers/ollama.md +166 -0
  175. package/docs/providers/openai-compatible.md +31 -2
  176. package/docs/providers/openai.md +24 -5
  177. package/docs/providers/openrouter.md +2 -0
  178. package/docs/providers/vertex.md +71 -0
  179. package/docs/public-contracts.md +61 -4
  180. package/docs/rag.md +41 -12
  181. package/docs/release-and-install.md +323 -206
  182. package/docs/resource-loading.md +3 -0
  183. package/docs/runs-and-usage.md +3 -0
  184. package/docs/server.md +44 -6
  185. package/docs/session-store-conformance.md +2 -0
  186. package/docs/session-stores.md +41 -2
  187. package/docs/sqlite-persistence.md +11 -3
  188. package/docs/structured-output.md +7 -1
  189. package/docs/supervisors.md +8 -0
  190. package/docs/tool-effects.md +95 -0
  191. package/docs/tools.md +5 -0
  192. package/docs/work-artifacts-and-review.md +102 -0
  193. package/docs/work-connectors.md +32 -0
  194. package/docs/work-tools.md +137 -0
  195. package/docs/workflows.md +6 -0
  196. package/docs/working-and-semantic-memory.md +40 -7
  197. package/package.json +30 -8
  198. package/templates/init/providers.json +22 -0
  199. package/docs/review-coverage-2026-07-14.md +0 -260
  200. package/docs/review-coverage-2026-07-15.md +0 -193
  201. package/docs/review-coverage-2026-07-17-provider-validation.md +0 -192
  202. package/docs/review-coverage-2026-07-19-phase-3.md +0 -174
  203. package/docs/review-coverage-2026-07-20-phase-4.md +0 -175
@@ -1,175 +0,0 @@
1
- # Review coverage — 2026-07-20 Phase 4
2
-
3
- Working evidence for Plan 072 Task 0. This page freezes revised Phase 4 scope, source/external revisions, primitive ownership, finite-limit targets, threats, tests, docs, and release gates before implementation.
4
-
5
- **Evidence frozen:** 2026-07-20. **Prism source:** `0d109989b4892e3fe4378ab782044ceadc460277` (`Release 0.0.8`). **Release target:** 0.0.9. **Default test rule:** local fakes and fixtures only; Docker/Playwright execution is a separate protected gate.
6
-
7
- ## Revised product decision
8
-
9
- 0.0.9 contains production coding and browser execution only. Office document execution is host-selected skill/instruction work outside Prism packaging. Prism will not ship `@arnilo/prism-work-tools/officecli`, an OfficeCLI binary/SDK/wrapper, Office-specific runtime contracts, generic Office MCP/CLI passthrough, Office tests/docs, or an Office release gate. This is a removed product criterion, not deferred 0.0.9 implementation.
10
-
11
- Cloud Microsoft 365 and Google Workspace connectors remain a separate later roadmap decision. They cannot depend on or imply local OfficeCLI execution.
12
-
13
- ## Status legend
14
-
15
- | Status | Meaning |
16
- | --- | --- |
17
- | `existing` | Current public contract covers the requirement. |
18
- | `extend` | Owning task extends an existing optional package/contract. |
19
- | `new-package` | New optional package; core remains dependency-free. |
20
- | `compose` | Existing public primitives are sufficient; only example/docs or package-local glue may be needed. |
21
- | `removed` | Deliberately outside Prism product/release scope. |
22
-
23
- ## Frozen external revisions
24
-
25
- | Surface | Frozen reference | Compatibility decision |
26
- | --- | --- | --- |
27
- | Prism | [`0d109989b4892e3fe4378ab782044ceadc460277`](../plans/072-release-0-0-9-production-coding-and-browser-execution.md) | All primitive/caller claims below were checked against the 0.0.8 release tree. |
28
- | Node.js | Local reference `v24.18.0`; Prism release support remains Node 20 and current | Use `node:child_process`, `node:fs`, streams, `AbortSignal`, `URL`, crypto hashes, and path APIs only. Node 20/current tests own compatibility. |
29
- | Playwright | [`playwright-core@1.61.0`](https://github.com/microsoft/playwright/tree/v1.61.0), npm integrity `sha512-caX7TrY3Ml6egyDX0WUcTHDxodl/b51y5wJOdCEA36QviK/s2g081hvmGs8eaE3DWb6NYZQ6BjO/QkNRPenoPA==` | Task 5 tests this exact compatibility line. Browser binary remains host supplied; package install performs no browser download. Only documented Browser/BrowserContext/Page/Locator/Download APIs are allowed. |
30
- | Playwright context/locator/snapshot/network docs | [BrowserContext](https://playwright.dev/docs/api/class-browsercontext), [Locator](https://playwright.dev/docs/api/class-locator), [locators](https://playwright.dev/docs/locators), [ARIA snapshots](https://playwright.dev/docs/aria-snapshots), [network](https://playwright.dev/docs/network), retrieved 2026-07-20 | Non-persistent contexts; role/label/test-id and snapshot refs before CSS; `ariaSnapshot({ mode: "ai" })`; service workers blocked when routing must observe requests. Request routing is defense in depth, not DNS containment. |
31
- | Docker CLI/Engine | Local reference client/server `29.6.1`; [container run](https://docs.docker.com/reference/cli/docker/container/run/), [resource constraints](https://docs.docker.com/engine/containers/run/), [default seccomp](https://docs.docker.com/engine/security/seccomp/), retrieved 2026-07-20 | Task 1 uses an absolute host-selected Docker executable, digest-pinned preloaded image, `--pull=never`, typed arguments, read-only root/source, finite tmpfs workspace, non-root user, dropped capabilities, default seccomp, no-new-privileges, and network none. Exact supported-version floor follows tested flag preflight; 29.6.1 is reference evidence. |
32
- | Git | Local reference `git version 2.55.0`; [official manuals](https://git-scm.com/docs), retrieved 2026-07-20 | Task 3 uses porcelain/plumbing argument arrays: `status --porcelain=v2 -z`, `diff --no-ext-diff --no-textconv`, `check-ref-format`, `worktree`, `apply --check`, `commit`, and `bundle`. Exact supported-version floor follows fixture/live conformance; 2.55.0 is reference evidence. |
33
-
34
- No Office executable, SDK, repository, schema, or version is pinned because Office execution is outside the release boundary.
35
-
36
- ## Capability traceability matrix
37
-
38
- | Revised roadmap criterion | Current surface | Minimum 0.0.9 gap | Status / owner | Required proof | Docs | Release gate |
39
- | --- | --- | --- | --- | --- | --- | --- |
40
- | Disposable read-only-base sandbox; writable bounded workspace; deny-default network; CPU/memory/PID/disk/time/secret/termination controls | `SandboxAdapter.exec(command)` maps only shell operations; coding tools have local operation seams | Typed process/lifecycle/import/export Docker reference with real limits and cleanup | `extend` / Task 1 | fake CLI matrix plus protected filesystem/network/process/resource escape tests | `coding-security.md`, `host-security.md`, `performance.md` | protected Docker gate + offline adapter tests |
41
- | Native bounded repository list/search | `createReadOnlyTools()` contains only `read`; read already has path, byte, line, image, abort bounds | Streaming stdlib list/search and sandbox operation wiring | `extend` / Task 2 | traversal/search ordering, symlink, binary, regex, byte/time/abort tests | `coding-agent-tools.md`, `performance.md` | offline coding conformance |
42
- | Structured Git status/diff/branch/worktree/patch/commit | Shell can invoke Git but has coarse operation policy | Typed arguments, bounded parsers/results, safe repo config, rollback, artifacts | `extend` / Task 3 | hostile path/ref/config/hook, dirty-tree, rollback, worktree tests | `coding-agent-tools.md`, `coding-security.md` | offline Git conformance + protected sandbox |
43
- | Named test/lint/typecheck/security commands and diagnostics | Shell operation backend, output accumulator, execution policy, progress events | Host-declared name → fixed executable/args map; bounded summaries/artifacts | `extend` / Task 3 | unknown name, fixed args/env, timeout/output/secret tests | `coding-agent-tools.md`, `performance.md` | offline command conformance |
44
- | Durable plans/todos/checkpoints/approvals/background branches/restart | Workspace files; `CheckpointStore`; workflow state/suspend/resume/coordinator/leases/events | Reference composition and immutable workspace artifact metadata; no second runtime | `compose` / Task 4 | restart/revision/owner/hash/lease/cancel/stale-worker matrix | `workflows.md`, `coding-agent-tools.md` | offline durable workflow journey |
45
- | Host-owned PR creation | No repository host API; workflow results can return bounded data | PR handoff metadata + patch/bundle reference only | `extend` / Task 3, composed by Task 4 | deterministic bounded handoff; prove no push/network/credential use | `coding-agent-tools.md`, `workflows.md` | offline handoff conformance |
46
- | Four Playwright browser tools with one run-owned isolated context and ordered actions | Core tool dispatch/exclusive flag, execution policy, guardrails, run identity; no browser package | Optional package and finite context/page/snapshot/action manager | `new-package` / Task 5 | fake API lifecycle, isolation, stale-ref, ordered-action, cleanup tests | `browser-automation.md`, `tools.md` | package/pack/install + protected Playwright |
47
- | Browser egress/side-effect/artifact policy | Execution/permission policy, guardrails, path containment, `ImageContent`, redaction | Context routing + host firewall/proxy requirement; upload/download/screenshot quarantine | `new-package` / Task 6 | redirects/private/DNS/service-worker, approval, artifact, secret tests | `browser-automation.md`, `host-security.md` | protected egress/browser gate |
48
- | Adversarial coding/browser evals and reproducible benchmarks | `@arnilo/prism-evals`, network-free fixtures, current benchmark/live workflow patterns | Package datasets, one 0.0.9 benchmark, protected real gate | `extend` / Task 7 | deterministic score thresholds and benchmark schema/cleanup | `evaluations.md`, `performance.md` | default eval gate + protected live gate |
49
- | 0.0.9 package/docs/release evidence | 31-package 0.0.8 graph and deterministic release pipeline | Add at most browser package; version/docs/pack/install/audit evidence | `extend` / Task 8 | `sdk:ready`, Node 20/current, pack/install, supply chain, release dry-run | `release-and-install.md`, `migration.md` | complete 0.0.9 release gate |
50
- | OfficeCLI/Office package/runtime/tests/docs/release criterion | Roadmap-only proposal; no current package | None | `removed` / product decision | docs assertion: absent from Phase 4/package graph/release checklist | this page, `roadmap.md` | explicit absence check |
51
-
52
- ## Primitive and caller inventory
53
-
54
- | Primitive | Existing contract/callers at frozen revision | Phase 4 disposition |
55
- | --- | --- | --- |
56
- | `ToolDefinition` / tool dispatch | `src/contracts.ts` defines name/schema/static `exclusive`/execute; `src/tools.ts` applies registry filter, trust, permission, validation, `beforeExecute`, guardrails, run-limit charge, events, ledger, and redaction. Coding, web, MCP, workflows, providers, examples, and tests consume it. | Reuse for list/search/Git/check/browser tools. Browser tools set static `exclusive: true` and also queue per run. No browser-specific dispatch runtime. |
57
- | `ExecutionPolicy` | String-extensible `ExecutionAction.kind`, operation/paths/command/risk/metadata and allow/modify/deny check in `src/execution-policy.ts`; coding tools enforce immediately before operations; workflow tool nodes can define actions and durable approval. | Reuse. Add package-local `git`, `check`, and `browser` action kinds/metadata; no core enum or approval engine. Policy is authorization, not containment. |
58
- | `PermissionPolicy` / trust | `src/security.ts`; `dispatchToolCall` and resource loading check host policies before execution/load. MCP/supervisor/extensions also consume permission/trust contracts. | Reuse at dispatch/resource boundaries. Do not duplicate permission logic in sandbox/browser managers. |
59
- | Guardrails / redaction | `src/tools.ts` runs tool-input/output guardrails and redacts results/events/ledger; `src/agents.ts` handles agent/provider stages. | Reuse for untrusted repository/browser content. Secrets remain host-known redactor inputs; sandbox/browser internals must redact before errors/artifact metadata too. |
60
- | `RunLimits` / `RunLimitTracker` | Defaults/hard caps in `src/run-limits.ts`; runtime charges turns, provider attempts, tool rounds/calls, wall time, request/response bytes, tokens, cost. MCP/workflow types accept limits. | Reuse for total agent work. Package-local external-resource limits below charge before work/retention; no expansion of `RunLimits` until another domain needs identical counters. |
61
- | `CheckpointStore` / leases | Generic owner-scoped versioned CAS/fencing contract; memory, SQLite, PostgreSQL, agent lifecycle/state, workflows, and schedules consume it. | Reuse for durable workflow metadata. Store artifact URI/hash/bytes and summaries, never repository/browser state blobs or credentials. |
62
- | Workflow state/suspend/coordinator | Workflow revision hash, bounded state/history/checkpoints, tool approval suspension, background enqueue, lease renewal/fencing/cancel, finite coordinator concurrency/pages. | Compose coding plan/todo files and branch artifact references. No `CodingRun`, todo DB, scheduler, or second workflow engine. |
63
- | Coding operation backends | `ReadOperations`, `WriteOperations`, `EditOperations`, `BashOperations`; local defaults; `SandboxAdapter` currently maps shell only. | Task 1 extends coding-security with typed `execFile`/lifecycle; Task 2 wires bounded repository operations. Preserve current custom/local contracts unless tests prove one shared addition is required. |
64
- | `withFileMutationQueue` | Process-wide map keyed by resolved realpath; used by write/edit; serializes same real path and releases on error. | Reuse for local same-path mutation. Git disposable worktree/patch transaction owns multi-file rollback; do not turn queue into transaction manager. |
65
- | `ResourceLoader` | Optional load/list with abort, trust, permission; bounded binary helper exists; inputs/contributions/extensions consume it. | May rehydrate a host-owned immutable artifact reference. It is not an artifact store, workspace transport, browser downloader, or network-containment bypass. Task 1/3 use narrow host callbacks for export. |
66
- | `ImageContent` / media bounds | Core content contract; coding read returns bounded images and can require host transform. | Reuse for bounded screenshots. Browser package enforces pixel/encoded-byte caps before returning content; no new image type. |
67
- | Agent/workflow events | Tool progress/start/finish/error/block, guardrail/limit events, workflow ordered events and finite buffers. | Reuse for diagnostics/progress/cleanup evidence. No coding/browser event bus or hook registry. |
68
- | `@arnilo/prism-evals` | Immutable datasets, bounded experiments/concurrency, function scorers, trace/judge/comparison/report limits. | Extend with package-local coding/browser datasets/scorers only; no mandatory model/network/service. |
69
- | `SandboxAdapter` | One `exec({ command, cwd, env, onData, signal, timeout })` contract and `createSandboxBashOperations`; no lifecycle, typed arguments, transfer, status, or containment implementation. | Extend in coding-security Task 1. Generic core sandbox contract is not authorized. |
70
-
71
- ### Primitive decision
72
-
73
- No new core primitive is authorized by Task 0.
74
-
75
- Authorized package-local work:
76
-
77
- 1. `@arnilo/prism-coding-security`: minimal typed executable, disposable lifecycle, import/export, status, and cleanup contracts implemented by the real Docker reference. Preserve current `SandboxAdapter.exec` compatibility.
78
- 2. `@arnilo/prism-coding-agent`: repository/Git/check/artifact types and operation overrides only where local and sandbox implementations both consume them.
79
- 3. `@arnilo/prism-browser`: run/context/action/artifact manager and Playwright types stay entirely optional-package local.
80
-
81
- A shared primitive can be promoted later only with two concrete non-test consumers and migration/conformance evidence. One-consumer interfaces, artifact databases, browser planners, Git libraries, proxy/firewall implementations, Office types, and remote worker/control-plane contracts are rejected.
82
-
83
- ## Frozen capability boundary
84
-
85
- | Surface | Supported in 0.0.9 | Explicitly unsupported |
86
- | --- | --- | --- |
87
- | Sandbox | Host-invoked Docker CLI reference; digest-pinned preloaded image; disposable container; finite tmpfs workspace; typed execution; bounded import/export; deterministic cleanup; default network none | Docker daemon provisioning, image build/pull/update, Kubernetes/remote scheduler, bundled image/proxy, host Docker-socket exposure, claim that command policy equals containment |
88
- | Coding | Native list/literal-or-bounded-regex search; structured Git/status/diff/branch/worktree/patch/commit; named fixed checks; workspace plan/todos; rollback/discard; background workflow composition; PR handoff | Language server/index/watch service, arbitrary model-created commands, implicit repo hook execution, GitHub/GitLab authentication/push/PR client, second coding runtime |
89
- | Browser | Four model tools; host-supplied Playwright 1.61-compatible browser; non-persistent context; ARIA snapshot/refs and user-facing locators; bounded screenshots/uploads/downloads/popups/dialogs | `evaluate`, arbitrary JavaScript/CSS/XPath, CDP/devtools, extensions, persistent/local profiles, browser binary download, generic MCP proxy, visual/coordinate planner |
90
- | Network | Network none by default; real browsing only behind host-contained proxy/firewall plus Playwright route checks | DNS rebinding protection by URL regex/routing alone; in-package firewall/proxy; public-network default tests |
91
- | Artifacts | Bounded host callbacks/references/hashes; download quarantine; screenshot `ImageContent`; patch/bundle/PR handoff | Artifact SaaS/database, unrestricted host paths, checkpointing credentials/storage state/full workspace, automatic upload/push |
92
- | Office | Host-selected skills/instructions may guide external user-owned work | Any Prism Office executable, SDK, wrapper, package, protocol, tool, test, doc page, binary, or release gate |
93
-
94
- ## Frozen finite limits and charging points
95
-
96
- Values are target defaults / hard caps for Tasks 1–7, not active 0.0.8 APIs. Existing stricter limits remain authoritative. Validate host configuration before starting work; charge count/declared bytes before each operation and stream-count actual bytes before retention/export.
97
-
98
- ### Sandbox and workspace
99
-
100
- | Resource | Default / hard cap | Charge/check point | Failure and cleanup owner |
101
- | --- | --- | --- | --- |
102
- | Startup / run wall / idle | 30 s / 120 s; 20 min / 30 min; 5 min / 15 min | Before create; absolute deadline starts before Docker invocation; idle resets only on accepted operation | Task 1 stops, then kills and removes recorded container |
103
- | CPU / memory+swap / PIDs | 2 / 8 CPUs; 2 GiB / 16 GiB; swap equal to memory; 256 / 1,024 PIDs | Validated before `docker run`; enforced by container/cgroup flags | Task 1 aborts run on limit exit and cleans container |
104
- | File descriptors | 1,024 / 8,192 | Validated before `docker run`; `nofile` ulimit | Task 1 |
105
- | Workspace / temp / download tmpfs | 1 GiB / 8 GiB; 256 MiB / 2 GiB; 64 MiB / 512 MiB | Size option validated before create; kernel tmpfs cap enforces writes | Task 1/6 discard on overflow |
106
- | Commands / concurrent exec | 100 / 256; 1 / 8 | Before queue/start; total also remains under run tool-call/wall limits | Task 1 rejects/aborts; close drains finite queue then kills |
107
- | Command output | existing 64 MiB / 1 GiB total; model result spill remains separately bounded | Stream byte count before append/write | Coding output accumulator + Task 1 termination |
108
- | Environment/secrets | 64 names / 256; 64 KiB / 256 KiB aggregate values | Validate exact host allow-list before create/exec; inherit none | Task 1 redacts errors and never exports environment |
109
- | Import/export | 50,000 / 250,000 entries; 256 MiB / 2 GiB bytes; 16 / 64 retained artifacts | Count headers/entries and stream bytes before write/retain; verify real path/type/hash | Task 1 aborts export, removes partial host artifact, source remains unchanged |
110
- | Stop grace / forced cleanup | 5 s / 30 s; one stop then one kill; cleanup deadline 30 s / 120 s | Terminal/abort/timeout/lease loss/browser crash | Task 1 records unresolved cleanup as release-blocking error |
111
-
112
- ### Repository, Git, checks, and durable work
113
-
114
- | Resource | Default / hard cap | Charge/check point | Owner |
115
- | --- | --- | --- | --- |
116
- | Repository depth / entries / files | 32 / 128; 10,000 / 100,000; 10,000 / 100,000 | Before descending/retaining next entry/file | Task 2 |
117
- | Search scan/file/matches | 64 MiB / 1 GiB aggregate; 8 MiB / 64 MiB per file; 1,000 / 10,000 matches | Prefix/binary check then stream bytes; check aggregate before next file/match | Task 2 |
118
- | Search pattern/line/context/time | 512 / 4,096 UTF-8 bytes; 50 KiB / 1 MiB line; 5 / 20 context lines; 30 s / 300 s | Before regex compile; before line/context retention; absolute deadline | Task 2 |
119
- | Repository concurrency | 8 / 32 open/read workers | Before opening next directory/file | Task 2 |
120
- | Git paths/refs/message | 1,000 / 10,000 paths; 1 KiB / 4 KiB ref; 64 KiB / 256 KiB commit message | Validate before process/temp-file creation | Task 3 |
121
- | Git output/diff/patch | 4 MiB / 64 MiB inline output; 10,000 / 100,000 diff lines; 1,000 / 10,000 changed files; 16 MiB / 64 MiB patch input | Stream before retain; spill only through bounded artifact callback | Task 3 |
122
- | Worktrees/background runs | 4 / 16 per parent run; coordinator default remains 4 and hard cap 256 | Before create/lease claim; exact branch/root ownership recorded | Task 3/4 |
123
- | Named checks | 8 / 32 names per host config; 1 / 4 concurrent; 10 min / 60 min each; 2,000 / 100,000 diagnostic lines; 4 MiB / 64 MiB inline output | Validate config at construction; charge before start/line retention | Task 3 |
124
- | Workflow state/checkpoint/history | Existing 64 KiB / 512 KiB state; 1 MiB / 8 MiB checkpoint; 32 / 128 history revisions | Existing workflow adapter checks before save | Task 4 |
125
- | Workspace checkpoint artifacts | 16 / 64 references; 256 MiB / 2 GiB each, also sandbox export aggregate | Hash/size verify before checkpoint metadata/import | Task 4 with host artifact owner |
126
- | Plan/todo and PR handoff | 256 KiB / 1 MiB plan; 1,000 / 10,000 todos; 256 KiB / 1 MiB handoff JSON | Before write/checkpoint/result exposure | Task 4 / Task 3 handoff |
127
-
128
- ### Browser
129
-
130
- | Resource | Default / hard cap | Charge/check point | Owner |
131
- | --- | --- | --- | --- |
132
- | Contexts/pages/actions/queued actions | exactly 1 context per run; 4 / 16 pages; 100 / 256 actions; 16 / 64 queued | Before context/page/action/queue creation; invalidate refs on mutation | Task 5 |
133
- | Snapshot refs/depth/bytes | 2,000 / 10,000 refs; depth 30 / 100; 256 KiB / 2 MiB encoded YAML | Before retaining each ref/node and before result exposure | Task 5 |
134
- | Navigation/action/wait/run time | 30 s / 120 s navigation; 10 s / 60 s action; 30 s / 120 s explicit wait; sandbox 20 min / 30 min run | Absolute deadline before Playwright call; no timeout retries unless action budget charged | Task 5 |
135
- | Popups/dialogs/listeners | 4 / 16 popups; 16 / 64 dialogs; 64 / 256 registered listeners | Before accepting/retaining; deterministic deny/dismiss after cap | Task 5/6 |
136
- | Network requests/redirects/WebSockets | 1,000 / 10,000 requests; 10 / 32 redirects/request; 8 / 32 WebSockets | Before route continuation/redirect/socket acceptance | Task 6; host firewall/proxy owns actual egress |
137
- | Screenshots | 16 / 64 megapixels; existing 10 MB / 32 MiB encoded image cap; 16 / 64 per run | Validate clip/viewport before capture and bytes before result/artifact | Task 6 |
138
- | Uploads | 8 / 32 files; 16 MiB / 64 MiB each; 64 MiB / 256 MiB aggregate | Realpath/type/size/approval before Playwright receives path | Task 6 |
139
- | Downloads | 8 / 32 files; 32 MiB / 256 MiB each; 64 MiB / 512 MiB aggregate | Stream to quarantine with count/hash; approval before export | Task 6 |
140
- | Browser cleanup | 5 s / 30 s close grace, then sandbox kill; 0 retained context/storage-state objects | Abort, terminal run, explicit close, browser crash, lease loss | Task 5 manager and Task 1 sandbox |
141
-
142
- ## Threat and authority matrix
143
-
144
- | Boundary | Trusted authority | Untrusted input | Mandatory control | Default/unsupported behavior |
145
- | --- | --- | --- | --- | --- |
146
- | Docker daemon/executable/image | Host operator supplies absolute CLI, daemon, digest, non-root image UID and policy | Model/repository/container output | Typed args; preflight; `--pull=never`; no socket/device/privileged/host namespaces; labels/recorded IDs | Missing/mutable/untrusted input fails before create; daemon compromise is outside Prism containment |
147
- | Source/workspace import/export | Host selects source and artifact callback | Paths, links, repository entries, archive headers/content | Read-only source; finite tmpfs; realpath/type checks; no devices; stream bounds; hash; atomic partial cleanup | No direct write-back; failed run discards workspace |
148
- | Process/environment/secrets | Host declares named checks and exact env allow-list | Model command text, repo scripts/config/hooks, process output | Typed exec for first-party tools; shell explicit; inherited env empty; noninteractive Git; redaction; limits | Unknown command/check/env denied; no implicit hooks/credentials |
149
- | Network/DNS | Host firewall/proxy/network policy | URLs, redirects, DNS, page scripts/service workers/WebSockets | Network none default; isolated proxy/firewall for browse; route validation and service-worker block in depth | No proxy attestation means no external browser network; private/local/file/devtools denied |
150
- | Playwright/browser endpoint | Host owns pinned browser launch/control endpoint | Pages, DOM/a11y text, refs, popups, downloads | One non-persistent context/run; short-lived host-only endpoint; ordered actions; no evaluate/CDP/profile | Endpoint/browser mismatch fails construction; import is inert |
151
- | Side effects/approval | Host `PermissionPolicy`, `ExecutionPolicy`, workflow approval | Model/page instructions and action metadata | Dispatch permission/guardrails then immediate operation policy; high-impact durable approval | Page text cannot authorize; denial produces bounded stable result |
152
- | Browser storage/secrets | Host injects at context/request edge | Cookies/storage state/page content/errors | Never return/persist/log storage state; redact known secret canaries; close context | No local profile; no checkpointed browser internals |
153
- | Upload/download/screenshot | Host roots, artifact callback, approval | Filenames, MIME, bytes, page pixels, symlinks | Realpath containment; quarantine; stream/pixel/byte caps; hashes; explicit release | Overflow/unknown type stays quarantined then deleted |
154
- | Durable checkpoint/resume | Host-owned checkpoint/lease/artifact stores and ownership scope | Persisted metadata, stale workers, artifact URI/content | CAS/fencing; workflow revision; image/tool/policy fingerprints; artifact hash/size; current approval | Wrong owner/revision/hash/fence fails before import/action |
155
- | Office work | User/host-selected external skill/tool | Office files/commands | Outside Prism runtime | No package, executable, schema, docs, test, or release claim |
156
-
157
- ## Validation matrix for Task 0
158
-
159
- | Check | Frozen assertion |
160
- | --- | --- |
161
- | Traceability | Every retained Phase 4 criterion above has one primary owner Task 1–8; cross-task composition is explicit. Removed Office criterion has product-decision owner and no implementation task. |
162
- | Primitive reuse | No new core primitive. Package-local additions have concrete local+sandbox or coding+browser consumers where shared; otherwise remain in owning package. |
163
- | Finite resources | Every external start/read/write/retain/queue/export path above has default/hard caps, pre-charge point, abort behavior, and cleanup owner. |
164
- | Security claims | Sandbox containment is Docker/host policy, not regex; browser DNS containment is host proxy/firewall, not Playwright routing; daemon, image, credentials, network, artifacts, and approvals stay host-owned. |
165
- | Scope absence | Revised roadmap Phase 4, package ledger, persona outcomes, and release checklist contain no OfficeCLI/Office runtime/package gate. |
166
-
167
- ## Documentation and release ownership
168
-
169
- - Task 1: `docs/coding-security.md`, `docs/host-security.md`, `docs/performance.md`, protected Docker gate.
170
- - Tasks 2–4: `docs/coding-agent-tools.md`, `docs/workflows.md`, `docs/evaluations.md`, offline coding/Git/durable-workflow gates.
171
- - Tasks 5–6: new `docs/browser-automation.md`, plus tools/guardrails/security/performance docs, package/install and protected Playwright gate.
172
- - Task 7: eval, benchmark, and protected-gate evidence — completed network-free coding/browser adversarial fixtures (`eval-fixtures.test.ts`), `scripts/benchmark-0.0.9.mjs` (+ schema test), protected Playwright live matrix, expanded Docker protected matrix, and `.github/workflows/sandbox-browser.yml`.
173
- - Task 8: migration/release docs, package graph, Node/pack/install/supply-chain/release dry-run evidence — completed 32-package exact `0.0.9` graph (`@arnilo/prism-browser` in `prism-all` only), finalized docs/changelogs/migration/release handoff, dated `benchmark-0.0.9` evidence, and release-candidate gates recorded in Plan 072.
174
-
175
- No public implementation API changed in Task 0. This page and `roadmap.md` are the authoritative pre-implementation boundary; later tasks may tighten defaults but cannot raise hard caps or broaden authority without updating tests, docs, and this evidence.