@fungi.computer/oyster 0.10.0 → 0.12.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 (107) hide show
  1. package/README.md +103 -12
  2. package/dist/agents.d.ts +66 -22
  3. package/dist/agents.js +128 -38
  4. package/dist/app-builds.d.ts +2 -0
  5. package/dist/app-builds.js +17 -6
  6. package/dist/authorization.d.ts +25 -3
  7. package/dist/authorization.js +47 -14
  8. package/dist/browser/capability-source.d.ts +23 -5
  9. package/dist/browser/capability-source.js +19 -22
  10. package/dist/browser/index.d.ts +2 -1
  11. package/dist/browser/index.js +1 -0
  12. package/dist/browser/live-view.d.ts +38 -0
  13. package/dist/browser/live-view.js +179 -0
  14. package/dist/build/artifact-writer.d.ts +11 -2
  15. package/dist/build/artifact-writer.js +42 -24
  16. package/dist/build/candidate-cli.mjs +26 -18
  17. package/dist/build/content-objects.d.ts +29 -14
  18. package/dist/build/content-objects.js +57 -19
  19. package/dist/build/local-build.js +3 -0
  20. package/dist/build/submission-contract.d.ts +1 -1
  21. package/dist/build/submission-contract.js +5 -5
  22. package/dist/build-egress.d.ts +8 -7
  23. package/dist/build-egress.js +4 -3
  24. package/dist/build.d.ts +1 -1
  25. package/dist/channels/binding.d.ts +2 -0
  26. package/dist/channels/run-decision.d.ts +33 -0
  27. package/dist/channels/run-decision.js +25 -0
  28. package/dist/channels/visitor-channel.d.ts +84 -14
  29. package/dist/channels/visitor-channel.js +55 -32
  30. package/dist/channels/visitor-edge.d.ts +18 -2
  31. package/dist/channels/visitor-edge.js +67 -5
  32. package/dist/channels/visitors.d.ts +4 -0
  33. package/dist/channels/visitors.js +22 -1
  34. package/dist/channels/web-binding.d.ts +117 -0
  35. package/dist/channels/web-binding.js +227 -0
  36. package/dist/embed-metafiles.d.ts +8 -0
  37. package/dist/embed-metafiles.js +2 -0
  38. package/dist/embed-scripts.d.ts +8 -0
  39. package/dist/embed-scripts.js +3 -0
  40. package/dist/host.d.ts +3 -1
  41. package/dist/host.js +6 -1
  42. package/dist/install-release-cli.d.ts +2 -1
  43. package/dist/install-release-cli.js +18 -10
  44. package/dist/installation-client.d.ts +1 -0
  45. package/dist/installation-operations.d.ts +2 -0
  46. package/dist/installation-operations.js +1 -0
  47. package/dist/pack.d.ts +5 -2
  48. package/dist/pack.js +3 -1
  49. package/dist/page/embed-challenge.d.ts +19 -0
  50. package/dist/page/embed-challenge.js +45 -0
  51. package/dist/page/embed-error.d.ts +2 -0
  52. package/dist/page/embed-error.js +16 -0
  53. package/dist/page/embed-loader-protocol.d.ts +12 -0
  54. package/dist/page/embed-loader-protocol.js +29 -0
  55. package/dist/standalone/agent-connections.d.ts +22 -19
  56. package/dist/standalone/agent-connections.js +150 -106
  57. package/dist/standalone/agents.d.ts +174 -16
  58. package/dist/standalone/agents.js +331 -21
  59. package/dist/standalone/browser.d.ts +14 -2
  60. package/dist/standalone/browser.js +52 -4
  61. package/dist/standalone/channel-session-door.d.ts +4 -0
  62. package/dist/standalone/channel-session-door.js +72 -0
  63. package/dist/standalone/computer-egress.d.ts +5 -3
  64. package/dist/standalone/computer-egress.js +1 -1
  65. package/dist/standalone/hello-app.d.ts +9 -0
  66. package/dist/standalone/hello-app.js +78 -0
  67. package/dist/standalone/install-apps-cli.d.ts +2 -1
  68. package/dist/standalone/install-apps-cli.js +36 -14
  69. package/dist/standalone/instance.js +2 -2
  70. package/dist/standalone/local-desktop.d.ts +11 -0
  71. package/dist/standalone/local-desktop.js +75 -0
  72. package/dist/standalone/owner-routes.d.ts +4 -3
  73. package/dist/standalone/owner-routes.js +7 -1
  74. package/dist/standalone/registry.d.ts +2 -0
  75. package/dist/standalone/sign-in-link.d.ts +9 -0
  76. package/dist/standalone/sign-in-link.js +49 -0
  77. package/dist/standalone/try-cli.d.ts +52 -0
  78. package/dist/standalone/try-cli.js +404 -0
  79. package/dist/standalone/visitor-edge.d.ts +36 -0
  80. package/dist/standalone/visitor-edge.js +67 -0
  81. package/dist/standalone/visitor-proof.d.ts +23 -0
  82. package/dist/standalone/visitor-proof.js +67 -0
  83. package/dist/standalone/website-channels.d.ts +134 -0
  84. package/dist/standalone/website-channels.js +262 -0
  85. package/dist/standalone/worker-routes.d.ts +4 -1
  86. package/dist/standalone/worker-routes.js +3 -0
  87. package/dist/standalone/worker.d.ts +2 -1
  88. package/dist/standalone/worker.js +5 -1
  89. package/dist/testing/capabilities.d.ts +3 -0
  90. package/dist/testing/capabilities.js +1 -0
  91. package/dist/testing/installation.d.ts +4 -2
  92. package/dist/testing/installation.js +7 -2
  93. package/dist/webhook-abuse.d.ts +7 -1
  94. package/dist/webhook-abuse.js +8 -2
  95. package/dist/workers-git.js +2 -2
  96. package/dist/workers.d.ts +7 -2
  97. package/dist/workers.js +1 -1
  98. package/docs/api/agents.md +103 -36
  99. package/docs/api/authorization.md +56 -11
  100. package/docs/api/browser.md +115 -8
  101. package/docs/api/build-contract.md +52 -10
  102. package/docs/api/build.md +16 -2
  103. package/docs/api/host.md +1 -0
  104. package/docs/api/pack.md +179 -3
  105. package/docs/api/workers-git.md +6 -6
  106. package/docs/site/agent-quickstart.mdx +8 -0
  107. package/package.json +34 -8
@@ -103,40 +103,72 @@ An App's requested tools await the owner's direct approval.
103
103
 
104
104
  ---
105
105
 
106
- ### AgentMcpServer
106
+ ### ConnectionAccess
107
107
 
108
108
  ```ts
109
- type AgentMcpServer = Readonly<{
110
- serverId: string;
109
+ type ConnectionAccess = "all" | "read" | readonly string[];
110
+ ```
111
+
112
+ What an Agent may do with one connection: everything, only reads, or named
113
+ tools.
114
+
115
+ ---
116
+
117
+ ### OysterConnection
118
+
119
+ ```ts
120
+ type OysterConnection = Readonly<{
121
+ connectionId: string;
111
122
  name: string;
123
+ label: string;
124
+ kind: "mcp" | "openapi";
112
125
  url: string;
113
- hasBearer: boolean;
126
+ auth: "none" | "token" | "oauth";
127
+ state: "connected" | "pending" | "reconnect_required";
128
+ grants: readonly Readonly<{
129
+ agentId: string;
130
+ access: ConnectionAccess;
131
+ }>[];
114
132
  }>;
115
133
  ```
116
134
 
117
- One remote MCP server connected to an Agent; its bearer token is never returned.
135
+ One connection as its owner sees it; no secret, locator or token ever appears.
118
136
 
119
137
  ---
120
138
 
121
- ### AgentMcpServerInput
139
+ ### ConnectionAdded
122
140
 
123
141
  ```ts
124
- type AgentMcpServerInput = typeof agentMcpServerInputSchema.Type;
142
+ type ConnectionAdded = Readonly<{
143
+ connectionId: string;
144
+ authorizeUrl: string | null;
145
+ }>;
125
146
  ```
126
147
 
127
- An owner's request to connect one remote MCP server to an Agent.
148
+ A newly added connection; `authorizeUrl` is where the owner signs in, when the
149
+ server uses OAuth.
128
150
 
129
151
  ---
130
152
 
131
- ### AgentMcpServerRefusal
153
+ ### ConnectionRefusal
132
154
 
133
155
  ```ts
134
- type AgentMcpServerRefusal = Readonly<{
156
+ type ConnectionRefusal = Readonly<{
135
157
  error: "not_found" | "duplicate_name" | "limit" | "invalid_endpoint";
136
158
  }>;
137
159
  ```
138
160
 
139
- Why connecting an MCP server was refused.
161
+ Why a connection change was refused.
162
+
163
+ ---
164
+
165
+ ### ConnectionInput
166
+
167
+ ```ts
168
+ type ConnectionInput = typeof connectionInputSchema.Type;
169
+ ```
170
+
171
+ An owner's request to connect one remote MCP server.
140
172
 
141
173
  ---
142
174
 
@@ -313,27 +345,55 @@ type OysterAgents = Readonly<{
313
345
  }>
314
346
  >;
315
347
  removeModelKey: Promise<"deleted" | "absent">;
316
- mcpServers: Promise<
317
- | readonly Readonly<{
318
- serverId: string;
319
- name: string;
320
- url: string;
321
- hasBearer: boolean;
322
- }>[]
323
- | null
348
+ connections: Promise<
349
+ readonly Readonly<{
350
+ connectionId: string;
351
+ name: string;
352
+ label: string;
353
+ kind: "mcp" | "openapi";
354
+ url: string;
355
+ auth: "none" | "token" | "oauth";
356
+ state: "connected" | "pending" | "reconnect_required";
357
+ grants: readonly Readonly<{
358
+ agentId: string;
359
+ access: ConnectionAccess;
360
+ }>[];
361
+ }>[]
324
362
  >;
325
- addMcpServer: Promise<
363
+ addConnection: Promise<
326
364
  | Readonly<{
327
- serverId: string;
328
- name: string;
329
- url: string;
330
- hasBearer: boolean;
365
+ connectionId: string;
366
+ authorizeUrl: string | null;
367
+ }>
368
+ | Readonly<{
369
+ error: "not_found" | "duplicate_name" | "limit" | "invalid_endpoint";
370
+ }>
371
+ >;
372
+ grantConnection: Promise<
373
+ | Readonly<{
374
+ error: "not_found" | "duplicate_name" | "limit" | "invalid_endpoint";
331
375
  }>
376
+ | Readonly<{
377
+ ok: true;
378
+ }>
379
+ >;
380
+ ungrantConnection: Promise<boolean>;
381
+ removeConnection: Promise<boolean>;
382
+ connectionTools: Promise<
383
+ | readonly string[]
332
384
  | Readonly<{
333
385
  error: "not_found" | "duplicate_name" | "limit" | "invalid_endpoint";
334
386
  }>
335
387
  >;
336
- removeMcpServer: Promise<boolean>;
388
+ completeMcpConnection: Promise<
389
+ | Readonly<{
390
+ ok: true;
391
+ }>
392
+ | Readonly<{
393
+ error: string;
394
+ }>
395
+ >;
396
+ mcpCallbackUrl: string;
337
397
  fetch: Promise<Response | null>;
338
398
  inbox: Promise<
339
399
  Readonly<{
@@ -412,28 +472,35 @@ What the owner submits to seal one provider key.
412
472
 
413
473
  ## Variables
414
474
 
415
- ### maxAgentMcpServers
475
+ ### maxAgentConnections
416
476
 
417
477
  ```ts
418
- const maxAgentMcpServers: 16 = 16;
478
+ const maxAgentConnections: 16 = 16;
419
479
  ```
420
480
 
421
- At most this many MCP servers per Agent.
481
+ At most this many connections per Agent.
422
482
 
423
483
  ---
424
484
 
425
- ### agentMcpServerInputSchema
485
+ ### connectionInputSchema
426
486
 
427
487
  ```ts
428
- const agentMcpServerInputSchema: Struct<{
488
+ const connectionInputSchema: Struct<{
429
489
  name: String;
430
490
  url: String;
431
491
  bearer: NullOr<String>;
492
+ oauth: optional<
493
+ Struct<{
494
+ clientId: optional<String>;
495
+ clientSecret: optional<String>;
496
+ scope: optional<String>;
497
+ }>
498
+ >;
432
499
  }>;
433
500
  ```
434
501
 
435
- Owner input for one MCP server: a guest identifier, an `https:` endpoint and an
436
- optional bearer.
502
+ Owner input for one MCP connection: a guest identifier, an `https:` endpoint and
503
+ an optional bearer.
437
504
 
438
505
  ## Functions
439
506
 
@@ -498,14 +565,14 @@ never comes back out; listings carry provider, label and times only.
498
565
 
499
566
  ---
500
567
 
501
- ### agentMcpServerRoutes()
568
+ ### connectionRoutes()
502
569
 
503
570
  ```ts
504
- function agentMcpServerRoutes(agents): Routes<OysterEnv>;
571
+ function connectionRoutes(agents): Routes<OysterEnv>;
505
572
  ```
506
573
 
507
- Host-owned Agent MCP server custody for the owner directly; never an App
508
- capability. Bearer tokens go in and never come back out.
574
+ Host-owned connection custody for the owner directly; never an App capability.
575
+ Tokens go in and never come back out.
509
576
 
510
577
  #### Parameters
511
578
 
@@ -458,6 +458,7 @@ type RequestFacts = Readonly<{
458
458
  body: <T>(schema) => Promise<T | null>;
459
459
  principal: () => Promise<OysterAuthResult>;
460
460
  mediated: boolean;
461
+ agents: AgentCeiling;
461
462
  ports: AuthorityPorts;
462
463
  }>;
463
464
  ```
@@ -466,6 +467,18 @@ The request facts a requirement reads.
466
467
 
467
468
  ---
468
469
 
470
+ ### AgentCeiling
471
+
472
+ ```ts
473
+ type AgentCeiling = "all" | ReadonlySet<string>;
474
+ ```
475
+
476
+ The Agents an App's admitted capability grant reaches: every Agent its principal
477
+ reaches, or exactly the selected ones. A request no App capability narrowed
478
+ carries `"all"`; principal reach still decides.
479
+
480
+ ---
481
+
469
482
  ### RequirementKind
470
483
 
471
484
  ```ts
@@ -516,6 +529,7 @@ the shell.
516
529
  type OwnerAdmission = Readonly<{
517
530
  principal: OwnerPrincipal;
518
531
  origin: OwnerOrigin;
532
+ delegatesAgent: (agentId) => boolean;
519
533
  }>;
520
534
  ```
521
535
 
@@ -556,6 +570,19 @@ What an Agent route receives.
556
570
 
557
571
  ---
558
572
 
573
+ ### AgentCollectionAdmission
574
+
575
+ ```ts
576
+ type AgentCollectionAdmission = CollectionAdmission<string> &
577
+ Readonly<{
578
+ everyAgent: boolean;
579
+ }>;
580
+ ```
581
+
582
+ What an Agent collection route receives.
583
+
584
+ ---
585
+
559
586
  ### Method
560
587
 
561
588
  ```ts
@@ -969,6 +996,27 @@ Whether a live key's grants permit a one-use device enrollment.
969
996
 
970
997
  ---
971
998
 
999
+ ### agentCeiling()
1000
+
1001
+ ```ts
1002
+ function agentCeiling(resources): AgentCeiling;
1003
+ ```
1004
+
1005
+ An admitted grant's resources as an Agent ceiling; a non-Agent selection reaches
1006
+ no Agent.
1007
+
1008
+ #### Parameters
1009
+
1010
+ | Parameter | Type |
1011
+ | ----------- | --------------------------------------------------------------------------------------- |
1012
+ | `resources` | \| `"tenant-scope"` \| readonly `Readonly`\<\{ `kind`: `string`; `id`: `string`; \}\>[] |
1013
+
1014
+ #### Returns
1015
+
1016
+ [`AgentCeiling`](#agentceiling)
1017
+
1018
+ ---
1019
+
972
1020
  ### unauthenticated()
973
1021
 
974
1022
  ```ts
@@ -1039,6 +1087,7 @@ function owner(via): Requirement<
1039
1087
  Readonly<{
1040
1088
  principal: OwnerPrincipal;
1041
1089
  origin: OwnerOrigin;
1090
+ delegatesAgent: (agentId) => boolean;
1042
1091
  }>
1043
1092
  >;
1044
1093
  ```
@@ -1057,7 +1106,7 @@ serves): consent and secrets never ride an App.
1057
1106
 
1058
1107
  [`Requirement`](#requirement)\<`Readonly`\<\{ `principal`:
1059
1108
  [`OwnerPrincipal`](#ownerprincipal); `origin`: [`OwnerOrigin`](#ownerorigin);
1060
- \}\>\>
1109
+ `delegatesAgent`: (`agentId`) => `boolean`; \}\>\>
1061
1110
 
1062
1111
  ---
1063
1112
 
@@ -1160,20 +1209,15 @@ owner, or a key granted `agents.use` for that Agent id.
1160
1209
  ### agents()
1161
1210
 
1162
1211
  ```ts
1163
- function agents(): Requirement<
1164
- Readonly<{
1165
- authority: Authority;
1166
- reaches: (item) => Promise<boolean>;
1167
- }>
1168
- >;
1212
+ function agents(): Requirement<AgentCollectionAdmission>;
1169
1213
  ```
1170
1214
 
1171
- Agents (and their inbox rows): the owner sees all, a key its granted Agents.
1215
+ Agents (and their inbox rows): the owner sees all, a key its granted Agents, and
1216
+ either only within the App grant that carried the request.
1172
1217
 
1173
1218
  #### Returns
1174
1219
 
1175
- [`Requirement`](#requirement)\<`Readonly`\<\{ `authority`:
1176
- [`Authority`](#authority); `reaches`: (`item`) => `Promise`\<`boolean`\>; \}\>\>
1220
+ [`Requirement`](#requirement)\<[`AgentCollectionAdmission`](#agentcollectionadmission)\>
1177
1221
 
1178
1222
  ---
1179
1223
 
@@ -1286,7 +1330,8 @@ Serve one capability's declared table under the host dispatcher's admission,
1286
1330
  read from `c.env`: the App already holds the capability, and each route still
1287
1331
  decides its own resource. Every request here is App-mediated, however it was
1288
1332
  admitted (a header or a browser socket's query), so `owner("direct")` always
1289
- refuses inside a capability.
1333
+ refuses inside a capability, and every Agent decision stays within the admitted
1334
+ grant's selection.
1290
1335
 
1291
1336
  #### Parameters
1292
1337
 
@@ -693,6 +693,21 @@ The agent-facing slice of `Browser`, possibly behind a host RPC hop.
693
693
 
694
694
  ---
695
695
 
696
+ ### BrowserHandoffPorts
697
+
698
+ ```ts
699
+ type BrowserHandoffPorts = Readonly<{
700
+ channel: ((sessionId, reason) => boolean) | null;
701
+ viewPath: (owner, leaseId) => string;
702
+ }>;
703
+ ```
704
+
705
+ How a host hands a paused lease to a person. A channel Session (a website
706
+ visitor) takes the conversation handoff; every other Session gets the live view
707
+ and asks the person itself.
708
+
709
+ ---
710
+
696
711
  ### CdpSocket
697
712
 
698
713
  ```ts
@@ -768,6 +783,55 @@ long-term.
768
783
 
769
784
  ---
770
785
 
786
+ ### LiveViewDoor
787
+
788
+ ```ts
789
+ type LiveViewDoor = (action, signal) => Promise<BinaryResult | null>;
790
+ ```
791
+
792
+ One admitted viewer's door into one lease: `Browser.member` already bound to it.
793
+
794
+ #### Parameters
795
+
796
+ | Parameter | Type |
797
+ | --------- | --------------------------------------------- |
798
+ | `action` | [`BrowserMemberAction`](#browsermemberaction) |
799
+ | `signal` | `AbortSignal` |
800
+
801
+ #### Returns
802
+
803
+ `Promise`\<[`BinaryResult`](#binaryresult) \| `null`\>
804
+
805
+ ---
806
+
807
+ ### LiveViewPaths
808
+
809
+ ```ts
810
+ type LiveViewPaths = Readonly<{
811
+ view: string;
812
+ frame: string;
813
+ input: string;
814
+ }>;
815
+ ```
816
+
817
+ The three paths a host serves for one lease, relative to its own origin.
818
+
819
+ ---
820
+
821
+ ### LiveView
822
+
823
+ ```ts
824
+ type LiveView = Readonly<{
825
+ page: () => Response;
826
+ frame: (signal) => Promise<Response>;
827
+ input: (request, signal) => Promise<Response>;
828
+ }>;
829
+ ```
830
+
831
+ The handlers for one lease's view, frame and input routes.
832
+
833
+ ---
834
+
771
835
  ### MarkdownInput
772
836
 
773
837
  ```ts
@@ -1118,7 +1182,7 @@ const CLOUD_BROWSER_DESCRIPTIONS: Readonly<{
1118
1182
  scroll: "Scroll an open session's page by a pixel delta.";
1119
1183
  screenshot: "Capture a PNG screenshot of an open session's page and save it to a Computer path; returns the saved byte count, never the bytes.";
1120
1184
  pdf: "Render an open session's page to PDF and save it to a Computer path; returns the saved byte count, never the bytes.";
1121
- handoff: "Ask a Team member to take over an open session for a login or captcha; a card appears in the conversation and the run continues once they finish.";
1185
+ handoff: "Pause an open session so the person can take over for a login or captcha. In a channel conversation the owner is notified and takes over. Otherwise the result is {paused: true, view}: ask the person with the question tool, include the view link, and wait for their answer. They press Done in the view to resume; drive again only after that.";
1122
1186
  close: "End a driven session and release its lease.";
1123
1187
  }>;
1124
1188
  ```
@@ -1367,16 +1431,16 @@ function browserCapabilitySource(deps): CapabilitySource;
1367
1431
 
1368
1432
  Compose the `cloudBrowser` source for one Session, on either host. `browser` is
1369
1433
  the module's lease door (in-process, or the Hub's egress RPC); `saveFile` is the
1370
- host's Computer bytes writer and `requestHandoff` its "needs you" card. A host
1371
- without one passes `null` and the matching operations are not offered. A lease
1372
- needs a Session identity, so a session-free host (e.g. the MCP execute path)
1373
- gets no module at all.
1434
+ host's Computer bytes writer and `handoff` its "needs you" ports. A host without
1435
+ a Computer passes `null` for `saveFile` and that operation is not offered. A
1436
+ lease needs a Session identity, so a session-free host (e.g. the MCP execute
1437
+ path) gets no module at all.
1374
1438
 
1375
1439
  #### Parameters
1376
1440
 
1377
- | Parameter | Type |
1378
- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1379
- | `deps` | `Readonly`\<\{ `identity`: () => \| `Readonly`\<\{ `teamId`: `string`; `agentId`: `string`; \}\> \| `null`; `browser`: [`AgentBrowserDoor`](#agentbrowserdoor); `quickReads`: `boolean`; `saveFile`: [`SaveBrowserFile`](#savebrowserfile) \| `null`; `requestHandoff`: ((`sessionId`, `reason`) => `void`) \| `null`; \}\> |
1441
+ | Parameter | Type |
1442
+ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1443
+ | `deps` | `Readonly`\<\{ `identity`: () => \| `Readonly`\<\{ `teamId`: `string`; `agentId`: `string`; \}\> \| `null`; `browser`: [`AgentBrowserDoor`](#agentbrowserdoor); `quickReads`: `boolean`; `saveFile`: [`SaveBrowserFile`](#savebrowserfile) \| `null`; `handoff`: [`BrowserHandoffPorts`](#browserhandoffports); \}\> |
1380
1444
 
1381
1445
  #### Returns
1382
1446
 
@@ -1384,6 +1448,49 @@ gets no module at all.
1384
1448
 
1385
1449
  ---
1386
1450
 
1451
+ ### liveViewPaths()
1452
+
1453
+ ```ts
1454
+ function liveViewPaths(base): LiveViewPaths;
1455
+ ```
1456
+
1457
+ The host-relative paths for a lease whose live view is served under `base`.
1458
+
1459
+ #### Parameters
1460
+
1461
+ | Parameter | Type |
1462
+ | --------- | -------- |
1463
+ | `base` | `string` |
1464
+
1465
+ #### Returns
1466
+
1467
+ [`LiveViewPaths`](#liveviewpaths)
1468
+
1469
+ ---
1470
+
1471
+ ### liveView()
1472
+
1473
+ ```ts
1474
+ function liveView(door, paths, report): LiveView;
1475
+ ```
1476
+
1477
+ Build the handlers for one admitted viewer and lease. `report` receives a
1478
+ request body that did not decode, so the host can log it with its own sink.
1479
+
1480
+ #### Parameters
1481
+
1482
+ | Parameter | Type |
1483
+ | --------- | --------------------------------- |
1484
+ | `door` | [`LiveViewDoor`](#liveviewdoor) |
1485
+ | `paths` | [`LiveViewPaths`](#liveviewpaths) |
1486
+ | `report` | (`event`, `cause`) => `void` |
1487
+
1488
+ #### Returns
1489
+
1490
+ [`LiveView`](#liveview)
1491
+
1492
+ ---
1493
+
1387
1494
  ### browserRunQuickReads()
1388
1495
 
1389
1496
  ```ts
@@ -28,6 +28,18 @@ The parts of an R2 bucket a content-object store uses.
28
28
 
29
29
  ---
30
30
 
31
+ ### ContentObjectOwner
32
+
33
+ ```ts
34
+ type ContentObjectOwner = Readonly<{
35
+ namespace: string;
36
+ }>;
37
+ ```
38
+
39
+ The one Team or tenant whose uploads share a key namespace.
40
+
41
+ ---
42
+
31
43
  ### CandidateObject
32
44
 
33
45
  ```ts
@@ -916,19 +928,42 @@ asset's type is its manifest's, so it is an octet stream.
916
928
 
917
929
  ## Functions
918
930
 
931
+ ### contentObjectOwner()
932
+
933
+ ```ts
934
+ function contentObjectOwner(id): ContentObjectOwner;
935
+ ```
936
+
937
+ Name the upload namespace of a Team or tenant id. Ids are opaque to the store,
938
+ so the namespace is a fixed-length digest of the id.
939
+
940
+ #### Parameters
941
+
942
+ | Parameter | Type |
943
+ | --------- | -------- |
944
+ | `id` | `string` |
945
+
946
+ #### Returns
947
+
948
+ [`ContentObjectOwner`](#contentobjectowner)
949
+
950
+ ---
951
+
919
952
  ### contentObjectRef()
920
953
 
921
954
  ```ts
922
- function contentObjectRef(digest): ArtifactRef;
955
+ function contentObjectRef(owner, digest, mediaType): ArtifactRef;
923
956
  ```
924
957
 
925
- The store key of one content-addressed object.
958
+ The store key of one uploaded object: its owner, digest and stored media type.
926
959
 
927
960
  #### Parameters
928
961
 
929
- | Parameter | Type |
930
- | --------- | -------------- |
931
- | `digest` | `Sha256Digest` |
962
+ | Parameter | Type |
963
+ | ----------- | ------------------------------------------------------------------------------------------------------------- |
964
+ | `owner` | [`ContentObjectOwner`](#contentobjectowner) |
965
+ | `digest` | `Sha256Digest` |
966
+ | `mediaType` | \| `"text/html; charset=utf-8"` \| `"application/vnd.fungi.app-backend+json"` \| `"application/octet-stream"` |
932
967
 
933
968
  #### Returns
934
969
 
@@ -969,22 +1004,28 @@ Describe a stored object by its size and the SHA-256 the store verified.
969
1004
  ```ts
970
1005
  function putContentObject(
971
1006
  bucket,
1007
+ owner,
972
1008
  object,
973
1009
  body,
974
1010
  mediaType,
975
1011
  ): Promise<"stored" | "refused">;
976
1012
  ```
977
1013
 
978
- Stream one object into the store under its digest. The store refuses a body
979
- whose SHA-256 differs; an object already stored with the same verified digest
980
- and size is kept (write-once: a stored version may be pinned by a Release) and
981
- the body is discarded, never stored.
1014
+ Stream one object into the store under its owner, digest and media type. The
1015
+ store refuses a body whose SHA-256 differs. The key is write-once (a stored
1016
+ version may be pinned by a Release): the put is conditional on the key being
1017
+ absent, and an existing object is never replaced. When the key already holds an
1018
+ object of the named size whose store-verified digest is the named one, or that
1019
+ the store never checksummed (a packed upload's plain bytes, which the candidate
1020
+ check reads and hashes), the body is discarded and the object kept; any other
1021
+ existing object refuses the upload.
982
1022
 
983
1023
  #### Parameters
984
1024
 
985
1025
  | Parameter | Type |
986
1026
  | ------------------- | ------------------------------------------------------------------------------------------------------------- |
987
1027
  | `bucket` | [`ContentObjectBucket`](#contentobjectbucket) |
1028
+ | `owner` | [`ContentObjectOwner`](#contentobjectowner) |
988
1029
  | `object` | \{ `digest`: `Sha256Digest`; `byteLength`: `number`; \} |
989
1030
  | `object.digest` | `Sha256Digest` |
990
1031
  | `object.byteLength` | `number` |
@@ -1082,7 +1123,8 @@ The stored media type a request names, if it is one an object may carry.
1082
1123
  function candidateManifestObjects(output): readonly CandidateUpload[];
1083
1124
  ```
1084
1125
 
1085
- Every distinct object a manifest names, each once, in manifest order.
1126
+ Every distinct object (digest and stored type) a manifest names, each once, in
1127
+ manifest order.
1086
1128
 
1087
1129
  #### Parameters
1088
1130