@fungi.computer/oyster 0.10.0 → 0.11.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 (63) hide show
  1. package/README.md +33 -2
  2. package/dist/agents.d.ts +66 -22
  3. package/dist/agents.js +128 -38
  4. package/dist/authorization.d.ts +25 -3
  5. package/dist/authorization.js +47 -14
  6. package/dist/browser/capability-source.d.ts +23 -5
  7. package/dist/browser/capability-source.js +19 -22
  8. package/dist/browser/index.d.ts +2 -1
  9. package/dist/browser/index.js +1 -0
  10. package/dist/browser/live-view.d.ts +38 -0
  11. package/dist/browser/live-view.js +179 -0
  12. package/dist/channels/binding.d.ts +2 -0
  13. package/dist/channels/run-decision.d.ts +33 -0
  14. package/dist/channels/run-decision.js +25 -0
  15. package/dist/channels/visitor-channel.d.ts +84 -14
  16. package/dist/channels/visitor-channel.js +55 -32
  17. package/dist/channels/visitor-edge.d.ts +18 -2
  18. package/dist/channels/visitor-edge.js +67 -5
  19. package/dist/channels/visitors.d.ts +4 -0
  20. package/dist/channels/visitors.js +22 -1
  21. package/dist/channels/web-binding.d.ts +117 -0
  22. package/dist/channels/web-binding.js +227 -0
  23. package/dist/embed-metafiles.d.ts +8 -0
  24. package/dist/embed-metafiles.js +2 -0
  25. package/dist/embed-scripts.d.ts +8 -0
  26. package/dist/embed-scripts.js +3 -0
  27. package/dist/host.d.ts +3 -1
  28. package/dist/host.js +6 -1
  29. package/dist/page/embed-challenge.d.ts +19 -0
  30. package/dist/page/embed-challenge.js +45 -0
  31. package/dist/page/embed-error.d.ts +2 -0
  32. package/dist/page/embed-error.js +16 -0
  33. package/dist/page/embed-loader-protocol.d.ts +12 -0
  34. package/dist/page/embed-loader-protocol.js +29 -0
  35. package/dist/standalone/agent-connections.d.ts +22 -19
  36. package/dist/standalone/agent-connections.js +150 -106
  37. package/dist/standalone/agents.d.ts +168 -14
  38. package/dist/standalone/agents.js +310 -17
  39. package/dist/standalone/browser.d.ts +14 -2
  40. package/dist/standalone/browser.js +52 -4
  41. package/dist/standalone/channel-session-door.d.ts +4 -0
  42. package/dist/standalone/channel-session-door.js +72 -0
  43. package/dist/standalone/owner-routes.d.ts +4 -3
  44. package/dist/standalone/owner-routes.js +7 -1
  45. package/dist/standalone/visitor-edge.d.ts +36 -0
  46. package/dist/standalone/visitor-edge.js +67 -0
  47. package/dist/standalone/visitor-proof.d.ts +23 -0
  48. package/dist/standalone/visitor-proof.js +67 -0
  49. package/dist/standalone/website-channels.d.ts +134 -0
  50. package/dist/standalone/website-channels.js +262 -0
  51. package/dist/standalone/worker-routes.d.ts +4 -1
  52. package/dist/standalone/worker-routes.js +3 -0
  53. package/dist/standalone/worker.d.ts +2 -1
  54. package/dist/standalone/worker.js +4 -0
  55. package/dist/testing/capabilities.d.ts +3 -0
  56. package/dist/testing/capabilities.js +1 -0
  57. package/dist/testing/installation.d.ts +4 -2
  58. package/dist/testing/installation.js +7 -2
  59. package/dist/workers-git.js +2 -2
  60. package/docs/api/agents.md +103 -36
  61. package/docs/api/browser.md +115 -8
  62. package/docs/api/workers-git.md +6 -6
  63. package/package.json +31 -6
@@ -31,6 +31,7 @@ import { serveDoors } from "../authorization.js";
31
31
  import { standaloneWorkerRoutes } from "./worker-routes.js";
32
32
  import { HTTPException } from "hono/http-exception";
33
33
  import { standaloneOwnerRoutes } from "./owner-routes.js";
34
+ import { standaloneWebsiteApp, } from "./website-channels.js";
34
35
  import { standaloneComputerSelection } from "./computer-fleet.js";
35
36
  import { serveOysterComputerEgress, } from "./computer-egress.js";
36
37
  export { StandaloneGraphWorkflow } from "./workflows.js";
@@ -161,6 +162,8 @@ export class OysterComputerEgress extends WorkerEntrypoint {
161
162
  });
162
163
  }
163
164
  }
165
+ /** The public website channel: one edge, authenticated per request. */
166
+ const website = standaloneWebsiteApp();
164
167
  const standaloneWorkerErrorHandler = (error, context) => {
165
168
  if (error instanceof StandaloneSeedConfigurationChanged) {
166
169
  const { refusal } = error;
@@ -189,6 +192,7 @@ export default {
189
192
  // tenant host's own declared table.
190
193
  return serveDoors(standaloneWorkerRoutes({
191
194
  machineLink: (incoming) => serveDoors(standaloneMachineLinkRoutes(env).onError(standaloneWorkerErrorHandler)).fetch(incoming, env, context),
195
+ website: (incoming) => Promise.resolve(website.fetch(incoming, env, context)),
192
196
  localBackendDial: async (incoming) => {
193
197
  const dial = ownerLocalBackendDialPath.exec(new URL(incoming.url).pathname);
194
198
  // Only a Computer this Oyster owns is addressed; no stray object is made.
@@ -1,6 +1,7 @@
1
1
  import { type AppCapabilityId } from "@fungi.computer/puffball/app";
2
2
  import { type OysterAgents } from "../agents.js";
3
3
  import type { LiveOysterKey } from "../keys.js";
4
+ import type { ResourceRef } from "../apps/index.js";
4
5
  import { type FileSource } from "../files.js";
5
6
  import { type OysterAuthResult, type OysterCapability } from "../host.js";
6
7
  /** How one capability fixture host admits its single installation. */
@@ -13,6 +14,8 @@ export type CapabilityFixtureOptions = Readonly<{
13
14
  adapters?: readonly OysterCapability[];
14
15
  /** Grant the file adapters over this source instead of the probe. */
15
16
  fileSource?: FileSource;
17
+ /** Capabilities the owner narrowed to exactly these resources. */
18
+ selected?: Partial<Record<AppCapabilityId, readonly ResourceRef[]>>;
16
19
  /** `false` clears the owner's approval after install. */
17
20
  admitted?: boolean;
18
21
  authenticate?: (request: Request) => Promise<OysterAuthResult>;
@@ -70,6 +70,7 @@ export async function capabilityFixture(options = {}) {
70
70
  release: declaredRelease,
71
71
  declaration: declaration ?? emptyAppDeclaration,
72
72
  descriptors: capabilities,
73
+ selected: options.selected ?? {},
73
74
  });
74
75
  if (options.admitted === false)
75
76
  installation = {
@@ -1,5 +1,5 @@
1
- import type { AppDeclaration } from "@fungi.computer/puffball/app";
2
- import { type CapabilityOperationDescriptor, type Installation } from "../apps/index.js";
1
+ import type { AppCapabilityId, AppDeclaration } from "@fungi.computer/puffball/app";
2
+ import { type CapabilityOperationDescriptor, type Installation, type ResourceRef } from "../apps/index.js";
3
3
  /** Build fixture state through the same approval owner used by installation routes. */
4
4
  export declare function approvedInstallation(input: Readonly<{
5
5
  release: Installation["release"];
@@ -7,4 +7,6 @@ export declare function approvedInstallation(input: Readonly<{
7
7
  installationId: string;
8
8
  instanceId: Installation["instanceId"];
9
9
  descriptors?: readonly CapabilityOperationDescriptor[];
10
+ /** Narrow these capabilities to exactly these resources, as the owner's picker does. */
11
+ selected?: Partial<Record<AppCapabilityId, readonly ResourceRef[]>>;
10
12
  }>): Promise<Installation>;
@@ -23,11 +23,16 @@ export async function approvedInstallation(input) {
23
23
  throw new Error(result.failure.code);
24
24
  const installed = result.success.next;
25
25
  const declaredOperations = await deriveDeclaredOperations(input.release, input.declaration, input.descriptors ?? []);
26
+ const selected = input.selected ?? {};
26
27
  const changes = declaredOperations.capabilities
27
- .filter(({ capability }) => permissionCatalog[capability].consent === "ask")
28
+ .filter(({ capability }) => permissionCatalog[capability].consent === "ask" ||
29
+ selected[capability] !== undefined)
28
30
  .map(({ capability, operations }) => ({
29
31
  capability,
30
- grant: { operations, resources: "tenant-scope" },
32
+ grant: {
33
+ operations,
34
+ resources: selected[capability] ?? "tenant-scope",
35
+ },
31
36
  }));
32
37
  if (changes.length === 0)
33
38
  return installed;
@@ -21,7 +21,7 @@ import { parseAppMethodCallContext, workflowAttestationSchema, } from "@fungi.co
21
21
  import { lsRefsRequest, parseLsRefs, } from "./git.js";
22
22
  import { createKeyStore, keyWire, } from "@fungi.computer/ear-tag/keys";
23
23
  import { oysterKeyVocabulary, } from "./keys.js";
24
- import { agentCapabilities, agentApprovalRoutes, agentMcpServerRoutes, modelKeyRoutes, } from "./agents.js";
24
+ import { agentCapabilities, agentApprovalRoutes, connectionRoutes, modelKeyRoutes, } from "./agents.js";
25
25
  import { createArtifactsRestNamespace, } from "@fungi.computer/burrow";
26
26
  import { attemptWebhook } from "./webhook-delivery.js";
27
27
  import { createRecipientDeliveries, } from "./event-recipients.js";
@@ -1169,7 +1169,7 @@ export function oysterGitOwnerRoutes(env, scope, hostOwnerRoutes, agents) {
1169
1169
  ownerRoutes.include(hostOwnerRoutes);
1170
1170
  if (agents !== undefined) {
1171
1171
  ownerRoutes.include(agentApprovalRoutes(agents));
1172
- ownerRoutes.include(agentMcpServerRoutes(agents));
1172
+ ownerRoutes.include(connectionRoutes(agents));
1173
1173
  ownerRoutes.include(modelKeyRoutes(agents));
1174
1174
  }
1175
1175
  return ownerRoutes;
@@ -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
 
@@ -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