@botiverse/porthole 0.15.3 → 0.16.1
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.
- package/CHANGELOG.md +70 -0
- package/dist/annotate/types.d.ts +15 -1
- package/dist/annotate/validate.js +19 -1
- package/dist/bridge/bridge.d.ts +1 -8
- package/dist/bridge/bridge.js +0 -7
- package/dist/bridge/types.d.ts +1 -1
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +1 -1
- package/dist/compile/policy.d.ts +0 -7
- package/dist/compile/policy.js +1 -10
- package/dist/config/capabilities.d.ts +8 -14
- package/dist/config/capabilities.js +4 -5
- package/dist/config/schema.d.ts +2 -13
- package/dist/config/validate.js +0 -24
- package/dist/conformance/behavior.js +26 -37
- package/dist/conformance/clipboard.js +47 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/displays/displays.js +1 -3
- package/dist/guide/limits.js +1 -1
- package/dist/guide/runtime.js +1 -1
- package/dist/host/create-host.d.ts +1 -1
- package/dist/host/create-host.js +8 -52
- package/dist/host/door.d.ts +1 -1
- package/dist/host/locate.d.ts +1 -1
- package/dist/host/locate.js +2 -2
- package/dist/host/outcome.d.ts +5 -12
- package/dist/host/outcome.js +8 -16
- package/dist/host/types.d.ts +6 -22
- package/dist/index.d.ts +2 -4
- package/dist/index.js +2 -4
- package/dist/isolation/served.d.ts +4 -14
- package/dist/isolation/served.js +7 -28
- package/dist/isolation/types.d.ts +2 -25
- package/dist/isolation/types.js +0 -23
- package/dist/platform/focus-field.d.ts +11 -0
- package/dist/platform/focus-field.js +18 -0
- package/dist/platform/types.d.ts +7 -23
- package/dist/platform/web.js +8 -106
- package/dist/presets/presets.d.ts +0 -2
- package/dist/presets/presets.js +0 -1
- package/dist/react/frame.d.ts +0 -8
- package/dist/react/frame.js +0 -4
- package/dist/runtime/contract.d.ts +2 -2
- package/dist/runtime/contract.js +2 -2
- package/dist/runtime/types.generated.js +6 -6
- package/dist/server/files.js +7 -23
- package/dist/server/host.d.ts +1 -1
- package/dist/server/index.d.ts +1 -1
- package/dist/server/index.js +4 -6
- package/dist/server/naming.js +1 -1
- package/dist/server/server.js +28 -166
- package/dist/server/types.d.ts +7 -7
- package/dist/shell/annotate.d.ts +3 -0
- package/dist/shell/annotate.js +15 -5
- package/dist/shell/plan.d.ts +0 -5
- package/dist/shell/plan.js +2 -4
- package/dist/shell/runtime.js +1 -268
- package/docs/ADOPTING.md +398 -1081
- package/docs/DECISIONS.md +172 -10
- package/docs/DESIGN.md +1114 -1388
- package/docs/PRINCIPLES.md +85 -1
- package/docs/THREAT_MODEL.md +658 -1127
- package/package.json +1 -1
- package/src/annotate/types.ts +12 -1
- package/src/annotate/validate.ts +23 -1
- package/src/bridge/bridge.ts +1 -17
- package/src/bridge/types.ts +1 -1
- package/src/check/page.ts +1 -1
- package/src/compile/policy.ts +1 -11
- package/src/config/capabilities.ts +8 -14
- package/src/config/schema.ts +2 -13
- package/src/config/validate.ts +0 -28
- package/src/conformance/behavior.ts +50 -52
- package/src/conformance/clipboard.ts +56 -1
- package/src/displays/displays.ts +1 -3
- package/src/guide/limits.ts +1 -1
- package/src/guide/runtime.ts +1 -1
- package/src/host/create-host.ts +8 -53
- package/src/host/door.ts +1 -1
- package/src/host/locate.ts +2 -2
- package/src/host/outcome.ts +8 -21
- package/src/host/types.ts +6 -20
- package/src/index.ts +2 -4
- package/src/isolation/served.ts +6 -34
- package/src/isolation/types.ts +2 -31
- package/src/platform/focus-field.ts +18 -0
- package/src/platform/types.ts +7 -22
- package/src/platform/web.ts +8 -129
- package/src/presets/presets.ts +0 -3
- package/src/react/frame.tsx +0 -10
- package/src/runtime/contract.ts +4 -4
- package/src/runtime/types.generated.ts +6 -6
- package/src/server/files.ts +4 -19
- package/src/server/host.ts +1 -1
- package/src/server/index.ts +4 -16
- package/src/server/naming.ts +1 -1
- package/src/server/server.ts +29 -189
- package/src/server/types.ts +7 -7
- package/src/shell/annotate.ts +15 -5
- package/src/shell/plan.ts +2 -9
- package/src/shell/runtime.ts +1 -268
- package/types/runtime/v1/artifact.d.ts +2 -3
- package/types/runtime/v1/assets.d.ts +1 -1
- package/types/runtime/v1/chat.d.ts +2 -2
- package/types/runtime/v1/comments.d.ts +1 -1
- package/types/runtime/v1/downloads.d.ts +2 -2
- package/types/runtime/v1/links.d.ts +2 -2
- package/dist/platform/focus-guard.d.ts +0 -288
- package/dist/platform/focus-guard.js +0 -838
- package/dist/server/nested.d.ts +0 -66
- package/dist/server/nested.js +0 -121
- package/dist/shell/frame.d.ts +0 -28
- package/dist/shell/frame.js +0 -407
- package/docs/ARCHITECTURE.md +0 -359
- package/docs/OBJECTIVES.md +0 -116
- package/src/platform/focus-guard.ts +0 -1114
- package/src/server/nested.ts +0 -157
- package/src/shell/frame.ts +0 -444
package/docs/PRINCIPLES.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# Principles
|
|
1
|
+
# Principles and objectives
|
|
2
2
|
|
|
3
3
|
These are the rules we use to make decisions quickly. When a choice is unclear,
|
|
4
4
|
pick the option that best satisfies these, write it down in
|
|
@@ -153,3 +153,87 @@ same config as the sandbox and the shell.
|
|
|
153
153
|
- **Rules out.** Shipping a shell and leaving the manual to each host; a manual
|
|
154
154
|
that lists variables or limits the shell does not actually enforce; prose
|
|
155
155
|
guidance that no test checks against real renders.
|
|
156
|
+
|
|
157
|
+
## Objectives
|
|
158
|
+
|
|
159
|
+
What Porthole is for and how we know it does it. OBJECTIVE n is cited by its number.
|
|
160
|
+
|
|
161
|
+
### What Porthole is for
|
|
162
|
+
|
|
163
|
+
Any app that wants the "show content made by an agent" ability — like the inline
|
|
164
|
+
visuals and standalone pages in ChatGPT and the Claude app — should be able to
|
|
165
|
+
embed Porthole and get a working, safe display out of the box, plus the manual
|
|
166
|
+
that teaches the agent to write for it.
|
|
167
|
+
|
|
168
|
+
The subject, stated generally, is **HTML drawn by an agent that may optionally
|
|
169
|
+
interact with the agent** — and that interaction is just one host function among
|
|
170
|
+
several. "Out of the box" means: a host picks a preset, passes theme tokens and
|
|
171
|
+
callbacks, and receives a safe display plus a generated agent manual.
|
|
172
|
+
|
|
173
|
+
### Objectives and success criteria
|
|
174
|
+
|
|
175
|
+
1. **Show untrusted agent HTML without putting the host at risk.**
|
|
176
|
+
- *Success:* the conformance/leak suite passes on Chromium, WebKit and
|
|
177
|
+
Firefox — every egress and escape probe attempts its channel and observes
|
|
178
|
+
nothing; the content cannot reach the host origin, its storage, its DOM, or
|
|
179
|
+
its credentials.
|
|
180
|
+
|
|
181
|
+
2. **One config generates the sandbox, the shell, and the manual, in agreement.**
|
|
182
|
+
- *Success:* for every preset, a test derives the CSP, the shell's wired host
|
|
183
|
+
functions, and the generated guide from the same config and asserts they
|
|
184
|
+
match — the guide names only variables the shell injects and only
|
|
185
|
+
capabilities the CSP and bridge allow; changing the config changes all
|
|
186
|
+
three together.
|
|
187
|
+
|
|
188
|
+
3. **Speak the MCP Apps standard, proven against the reference implementation.**
|
|
189
|
+
- *Success:* the MCP Apps preset renders and interacts with the official
|
|
190
|
+
ext-apps example servers **unmodified** (initialize handshake, tool input
|
|
191
|
+
and result, size and theme changes, open-link and message), driven in the
|
|
192
|
+
leak suite.
|
|
193
|
+
|
|
194
|
+
4. **Embed with near-zero config across the modes.**
|
|
195
|
+
- *Success:* a host mounts an inline widget, an artifact page, an MCP Apps
|
|
196
|
+
view and a URL frame each in a few lines using only a preset, theme tokens
|
|
197
|
+
and callbacks; the framework-agnostic core and the React binding both do
|
|
198
|
+
this; no host-specific code lives in the core.
|
|
199
|
+
|
|
200
|
+
5. **Ship the agent manual as a first-class output.**
|
|
201
|
+
- *Success:* each preset produces an agent-facing guide and tool description
|
|
202
|
+
from its config; a real agent that reads the guide produces content that
|
|
203
|
+
renders within the sandbox and reads correctly at the target widths in light
|
|
204
|
+
and dark, checked by rendering the guide's own examples in the leak suite.
|
|
205
|
+
|
|
206
|
+
### Non-goals
|
|
207
|
+
|
|
208
|
+
- **Host-drawn DSL rendering.** Rendering a JSON/JSX/remote-DOM UI description
|
|
209
|
+
with the host's own native components (A2UI, json-render, remote-dom, JSX
|
|
210
|
+
preview) is a separate concern and a different project. Porthole is the HTML
|
|
211
|
+
sandbox only.
|
|
212
|
+
- **A component vocabulary inside the sandbox.** Content is plain HTML and SVG,
|
|
213
|
+
taught by the generated manual; a consistent look comes from the injected theme
|
|
214
|
+
variables and, at most, plain base CSS for native elements, never from tags and
|
|
215
|
+
props an agent must learn (P015). Nor is Porthole a design-system library.
|
|
216
|
+
- **A new widget-side protocol.** The contract is MCP Apps; we do not define an
|
|
217
|
+
alternative (PRINCIPLE 2).
|
|
218
|
+
- **A shell or egress control for URL mode.** A URL frame is someone else's
|
|
219
|
+
running app: Porthole gives it isolation and access auth, nothing more (P020).
|
|
220
|
+
- **Operating infrastructure.** The serving part (`/server`) is a request handler a
|
|
221
|
+
host mounts in its own backend; Porthole runs no service, domain or certificate
|
|
222
|
+
of its own.
|
|
223
|
+
- **Being an agent framework or an MCP server.** Porthole is host-side rendering
|
|
224
|
+
and isolation. It does not run models, implement an MCP server, or decide
|
|
225
|
+
product policy (PRINCIPLE 8).
|
|
226
|
+
|
|
227
|
+
### Who the users are
|
|
228
|
+
|
|
229
|
+
- **Host app developers** who want to show agent-made HTML in a chat or canvas UI
|
|
230
|
+
and do not want to build or audit an isolation layer themselves. They are the
|
|
231
|
+
primary users: they embed the library and pick a preset.
|
|
232
|
+
- **Agents (and the people prompting them)** who write the HTML. They are served
|
|
233
|
+
indirectly: the generated manual is written for them, and the sandbox is the
|
|
234
|
+
environment their code runs in.
|
|
235
|
+
- **MCP App authors** who build standard MCP Apps and want them to render in any
|
|
236
|
+
Porthole-based host unmodified.
|
|
237
|
+
|
|
238
|
+
The first adopter is a normal user of the public API, with no privileged path
|
|
239
|
+
(PRINCIPLE 9).
|