@fungi.computer/oyster 0.9.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 (96) hide show
  1. package/README.md +46 -2
  2. package/dist/agents.d.ts +82 -23
  3. package/dist/agents.js +187 -40
  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/computer-control-port.d.ts +20 -1
  24. package/dist/embed-metafiles.d.ts +8 -0
  25. package/dist/embed-metafiles.js +2 -0
  26. package/dist/embed-scripts.d.ts +8 -0
  27. package/dist/embed-scripts.js +3 -0
  28. package/dist/host.d.ts +3 -1
  29. package/dist/host.js +6 -1
  30. package/dist/mcp.d.ts +128 -0
  31. package/dist/mcp.js +63 -1
  32. package/dist/page/embed-challenge.d.ts +19 -0
  33. package/dist/page/embed-challenge.js +45 -0
  34. package/dist/page/embed-error.d.ts +2 -0
  35. package/dist/page/embed-error.js +16 -0
  36. package/dist/page/embed-loader-protocol.d.ts +12 -0
  37. package/dist/page/embed-loader-protocol.js +29 -0
  38. package/dist/standalone/agent-computers.d.ts +12 -1
  39. package/dist/standalone/agent-computers.js +35 -0
  40. package/dist/standalone/agent-connections.d.ts +50 -0
  41. package/dist/standalone/agent-connections.js +214 -0
  42. package/dist/standalone/agent-model-choice.d.ts +7 -3
  43. package/dist/standalone/agent-model-choice.js +33 -4
  44. package/dist/standalone/agents.d.ts +224 -9
  45. package/dist/standalone/agents.js +485 -115
  46. package/dist/standalone/browser.d.ts +16 -3
  47. package/dist/standalone/browser.js +54 -5
  48. package/dist/standalone/channel-session-door.d.ts +4 -0
  49. package/dist/standalone/channel-session-door.js +72 -0
  50. package/dist/standalone/computer-control.js +55 -1
  51. package/dist/standalone/computer-fleet.d.ts +21 -0
  52. package/dist/standalone/computer-fleet.js +30 -6
  53. package/dist/standalone/computer.d.ts +20 -1
  54. package/dist/standalone/computer.js +63 -1
  55. package/dist/standalone/model-key-vault.d.ts +50 -0
  56. package/dist/standalone/model-key-vault.js +147 -0
  57. package/dist/standalone/owner-routes.d.ts +4 -3
  58. package/dist/standalone/owner-routes.js +7 -1
  59. package/dist/standalone/registry.d.ts +23 -0
  60. package/dist/standalone/registry.js +30 -0
  61. package/dist/standalone/visitor-edge.d.ts +36 -0
  62. package/dist/standalone/visitor-edge.js +67 -0
  63. package/dist/standalone/visitor-proof.d.ts +23 -0
  64. package/dist/standalone/visitor-proof.js +67 -0
  65. package/dist/standalone/web.d.ts +10 -0
  66. package/dist/standalone/web.js +34 -0
  67. package/dist/standalone/website-channels.d.ts +134 -0
  68. package/dist/standalone/website-channels.js +262 -0
  69. package/dist/standalone/worker-routes.d.ts +6 -1
  70. package/dist/standalone/worker-routes.js +4 -0
  71. package/dist/standalone/worker.d.ts +2 -1
  72. package/dist/standalone/worker.js +13 -1
  73. package/dist/testing/capabilities.d.ts +3 -0
  74. package/dist/testing/capabilities.js +1 -0
  75. package/dist/testing/installation.d.ts +4 -2
  76. package/dist/testing/installation.js +7 -2
  77. package/dist/web/index.d.ts +3 -0
  78. package/dist/web/index.js +3 -0
  79. package/dist/web/search-contract.d.ts +19 -0
  80. package/dist/web/search-contract.js +14 -0
  81. package/dist/web/search.d.ts +25 -0
  82. package/dist/web/search.js +123 -0
  83. package/dist/web/source.d.ts +46 -0
  84. package/dist/web/source.js +335 -0
  85. package/dist/workers-git.js +3 -2
  86. package/docs/api/agents.md +184 -39
  87. package/docs/api/apps.md +129 -111
  88. package/docs/api/browser.md +115 -8
  89. package/docs/api/build-contract.md +27 -21
  90. package/docs/api/build.md +55 -54
  91. package/docs/api/git.md +3 -3
  92. package/docs/api/host.md +69 -60
  93. package/docs/api/mcp.md +81 -44
  94. package/docs/api/workers-git.md +6 -6
  95. package/docs/api/workers.md +53 -47
  96. package/package.json +52 -22
@@ -145,6 +145,15 @@ export function allowsMachineEnrollment(key) {
145
145
  key.grants[0]?.capability === "machine.enroll" &&
146
146
  oysterKeyVocabulary.grantsAllow(key.grants, "machine.enroll"));
147
147
  }
148
+ /** An admitted grant's resources as an Agent ceiling; a non-Agent selection reaches no Agent. */
149
+ export function agentCeiling(resources) {
150
+ return resources === "tenant-scope"
151
+ ? "all"
152
+ : new Set(resources.flatMap((resource) => resource.kind === "agent" ? [resource.id] : []));
153
+ }
154
+ function withinCeiling(ceiling, agentId) {
155
+ return ceiling === "all" || ceiling.has(agentId);
156
+ }
148
157
  /** A refusal this module returns before any handler runs. */
149
158
  function refused(status, error) {
150
159
  return Response.json({ error }, { status });
@@ -224,7 +233,11 @@ export function owner(via) {
224
233
  const origin = facts.mediated ? "app" : "owner-direct";
225
234
  if (via === "direct" && origin === "app")
226
235
  return refused(403, "Owner direct only");
227
- return { principal, origin };
236
+ return {
237
+ principal,
238
+ origin,
239
+ delegatesAgent: (agentId) => withinCeiling(facts.agents, agentId),
240
+ };
228
241
  });
229
242
  }
230
243
  /**
@@ -280,12 +293,16 @@ export function agent(id = (facts) => Promise.resolve(facts.param("agentId") ??
280
293
  const agentId = await id(facts);
281
294
  if (agentId === null)
282
295
  return refused(400, "Name the Agent");
283
- if (!reachesAgent(authority, agentId))
296
+ if (!reachesAgent(authority, agentId) ||
297
+ !withinCeiling(facts.agents, agentId))
284
298
  return refused(403, "Agent access denied");
285
299
  return { authority, principal: authority.principal, agentId };
286
300
  });
287
301
  }
288
- /** Agents (and their inbox rows): the owner sees all, a key its granted Agents. */
302
+ /**
303
+ * Agents (and their inbox rows): the owner sees all, a key its granted
304
+ * Agents, and either only within the App grant that carried the request.
305
+ */
289
306
  export function agents() {
290
307
  return requirement({ kind: "agents" }, async (facts) => {
291
308
  const authority = await signedInAuthority(facts);
@@ -293,7 +310,9 @@ export function agents() {
293
310
  return authority;
294
311
  return {
295
312
  authority,
296
- reaches: (agentId) => Promise.resolve(reachesAgent(authority, agentId)),
313
+ everyAgent: authority.kind === "owner" && facts.agents === "all",
314
+ reaches: (agentId) => Promise.resolve(reachesAgent(authority, agentId) &&
315
+ withinCeiling(facts.agents, agentId)),
297
316
  };
298
317
  });
299
318
  }
@@ -390,7 +409,7 @@ export class Routes {
390
409
  this.#entries.push({
391
410
  kind: "route",
392
411
  declaration: { methods, path, requirement: record.declared },
393
- mount: (hono, principal, ports, mediated) => {
412
+ mount: (hono, principal, ports, delegation) => {
394
413
  // One admission per request, shared down the middleware chain.
395
414
  const admittedFor = new WeakMap();
396
415
  const gate = async (context, next) => {
@@ -402,7 +421,7 @@ export class Routes {
402
421
  return decoded._tag === "Some" ? decoded.value : null;
403
422
  },
404
423
  principal: () => principal(context),
405
- mediated: mediated(context.req.raw),
424
+ ...delegation(context),
406
425
  ports,
407
426
  });
408
427
  if (admitted instanceof Response)
@@ -441,8 +460,14 @@ export function routes() {
441
460
  function declarationsOf(table) {
442
461
  return recordOf(table).entries.flatMap((entry) => entry.kind === "route" ? [entry.declaration] : declarationsOf(entry.table));
443
462
  }
444
- /** The page bridge names the installation an App call comes from. */
445
- const bridged = (request) => request.headers.has("X-Oyster-Installation");
463
+ /**
464
+ * The page bridge names the installation an App call comes from. A host
465
+ * route it reaches is no capability, so no capability grant narrows it.
466
+ */
467
+ const bridged = (context) => ({
468
+ mediated: context.req.raw.headers.has("X-Oyster-Installation"),
469
+ agents: "all",
470
+ });
446
471
  /**
447
472
  * Serve one table: the only `Hono` the Oyster host builds. Each route runs
448
473
  * its requirement first, then its middleware, then its handler. Nothing a
@@ -488,10 +513,10 @@ function serveTable(table, principal, ports, rules) {
488
513
  hono.route("/", serveTable(entry.table, principal, ports, {
489
514
  headers: [],
490
515
  serverTiming: null,
491
- mediated: rules.mediated,
516
+ delegation: rules.delegation,
492
517
  }));
493
518
  else
494
- entry.mount(hono, principal, ports, rules.mediated);
519
+ entry.mount(hono, principal, ports, rules.delegation);
495
520
  const handler = errorHandler();
496
521
  if (handler !== undefined)
497
522
  hono.onError(handler);
@@ -519,7 +544,7 @@ export function serveHost(table, authenticate, ports, options = {}) {
519
544
  serverTiming: Object.hasOwn(options, "serverTiming")
520
545
  ? (options.serverTiming ?? null)
521
546
  : null,
522
- mediated: bridged,
547
+ delegation: bridged,
523
548
  }));
524
549
  }
525
550
  /**
@@ -528,15 +553,23 @@ export function serveHost(table, authenticate, ports, options = {}) {
528
553
  * principal is refused, never admitted.
529
554
  */
530
555
  export function serveDoors(table) {
531
- return servedView(serveTable(table, () => Promise.resolve({ kind: "refused", status: 401 }), { liveKey: () => Promise.resolve(null), appToolPolicy: () => null }, { headers: [], serverTiming: null, mediated: bridged }));
556
+ return servedView(serveTable(table, () => Promise.resolve({ kind: "refused", status: 401 }), { liveKey: () => Promise.resolve(null), appToolPolicy: () => null }, { headers: [], serverTiming: null, delegation: bridged }));
532
557
  }
533
558
  /**
534
559
  * Serve one capability's declared table under the host dispatcher's
535
560
  * admission, read from `c.env`: the App already holds the capability, and
536
561
  * each route still decides its own resource. Every request here is
537
562
  * App-mediated, however it was admitted (a header or a browser socket's
538
- * query), so `owner("direct")` always refuses inside a capability.
563
+ * query), so `owner("direct")` always refuses inside a capability, and
564
+ * every Agent decision stays within the admitted grant's selection.
539
565
  */
540
566
  export function serveCapability(table, ports) {
541
- return servedView(serveTable(table, (context) => Promise.resolve({ kind: "admitted", principal: context.env.principal }), ports, { headers: [], serverTiming: null, mediated: () => true }));
567
+ return servedView(serveTable(table, (context) => Promise.resolve({ kind: "admitted", principal: context.env.principal }), ports, {
568
+ headers: [],
569
+ serverTiming: null,
570
+ delegation: (context) => ({
571
+ mediated: true,
572
+ agents: agentCeiling(context.env.grant.resources),
573
+ }),
574
+ }));
542
575
  }
@@ -32,7 +32,7 @@ export declare const CLOUD_BROWSER_DESCRIPTIONS: Readonly<{
32
32
  readonly scroll: "Scroll an open session's page by a pixel delta.";
33
33
  readonly 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.";
34
34
  readonly pdf: "Render an open session's page to PDF and save it to a Computer path; returns the saved byte count, never the bytes.";
35
- readonly 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.";
35
+ readonly 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.";
36
36
  readonly close: "End a driven session and release its lease.";
37
37
  }>;
38
38
  /**
@@ -56,12 +56,30 @@ export type AgentBrowserDoor = Readonly<{
56
56
  /** Pause the owner's lease for a Team member. */
57
57
  handoff: (owner: LeaseOwner, leaseId: string) => Promise<void>;
58
58
  }>;
59
+ /**
60
+ * How a host hands a paused lease to a person. A channel Session (a website
61
+ * visitor) takes the conversation handoff; every other Session gets the live
62
+ * view and asks the person itself.
63
+ */
64
+ export type BrowserHandoffPorts = Readonly<{
65
+ /**
66
+ * Request the channel conversation handoff for this Session. True when the
67
+ * Session is a channel conversation and was handed off; false for any other
68
+ * Session. `null` when the host has no conversations owner.
69
+ */
70
+ channel: ((sessionId: string, reason: string) => boolean) | null;
71
+ /** The host-relative live-view path for one lease of this Session's owner. */
72
+ viewPath: (owner: Readonly<{
73
+ teamId: string;
74
+ agentId: string;
75
+ }>, leaseId: string) => string;
76
+ }>;
59
77
  /**
60
78
  * Compose the `cloudBrowser` source for one Session, on either host. `browser`
61
79
  * is the module's lease door (in-process, or the Hub's egress RPC); `saveFile`
62
- * is the host's Computer bytes writer and `requestHandoff` its "needs you"
63
- * card. A host without one passes `null` and the matching operations are not
64
- * offered. A lease needs a Session identity, so a session-free host (e.g. the
80
+ * is the host's Computer bytes writer and `handoff` its "needs you" ports. A
81
+ * host without a Computer passes `null` for `saveFile` and that operation is
82
+ * not offered. A lease needs a Session identity, so a session-free host (e.g. the
65
83
  * MCP execute path) gets no module at all.
66
84
  */
67
85
  export declare function browserCapabilitySource(deps: Readonly<{
@@ -72,5 +90,5 @@ export declare function browserCapabilitySource(deps: Readonly<{
72
90
  browser: AgentBrowserDoor;
73
91
  quickReads: boolean;
74
92
  saveFile: SaveBrowserFile | null;
75
- requestHandoff: ((sessionId: string, reason: string) => void) | null;
93
+ handoff: BrowserHandoffPorts;
76
94
  }>): CapabilitySource;
@@ -22,7 +22,7 @@ export const CLOUD_BROWSER_DESCRIPTIONS = Object.freeze({
22
22
  module: "A work browser for reading and driving public pages. markdown/links/scrape/extract " +
23
23
  "need no session. open/navigate/snapshot/click/type/press/scroll drive one session by " +
24
24
  "leaseId; screenshot/pdf save to a Computer path (bytes never enter this transcript). " +
25
- "handoff asks a Team member to take over for a login or captcha; close ends the lease. " +
25
+ "handoff pauses the session for the person to take over for a login or captcha; close ends the lease. " +
26
26
  "To show the member something yourself, use the Session browser tools, not this.",
27
27
  markdown: "Render a JavaScript page and return it as markdown, truncated to maxChars (default 20000).",
28
28
  links: "Render a page and return up to 500 links found on it.",
@@ -37,7 +37,7 @@ export const CLOUD_BROWSER_DESCRIPTIONS = Object.freeze({
37
37
  scroll: "Scroll an open session's page by a pixel delta.",
38
38
  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.",
39
39
  pdf: "Render an open session's page to PDF and save it to a Computer path; returns the saved byte count, never the bytes.",
40
- 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.",
40
+ 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.",
41
41
  close: "End a driven session and release its lease.",
42
42
  });
43
43
  for (const [name, text] of Object.entries(CLOUD_BROWSER_DESCRIPTIONS))
@@ -65,7 +65,7 @@ function cloudBrowserFailureMessage(error) {
65
65
  case "CloudBrowserLeaseNotFound":
66
66
  return "that leaseId is not open for this session; call open first";
67
67
  case "CloudBrowserLeasePaused":
68
- return "a Team member is driving this lease; wait for them to finish";
68
+ return "a person has this lease; ask them to press Done in the browser view, then try again";
69
69
  case "CloudBrowserCapacityExceeded":
70
70
  return "this Team has too many cloud browsers open at once; close one first";
71
71
  case "CloudBrowserCreditDenied":
@@ -111,9 +111,11 @@ const destinationResultSchema = z.strictObject({
111
111
  path: z.string(),
112
112
  bytes: z.number().int().nonnegative(),
113
113
  });
114
- const handoffResultSchema = z.strictObject({
115
- status: z.literal("handed_off"),
116
- });
114
+ /** A channel Session's owner was notified, or the person is given a live view. */
115
+ const handoffResultSchema = z.union([
116
+ z.strictObject({ status: z.literal("handed_off") }),
117
+ z.strictObject({ paused: z.literal(true), view: z.string().min(1) }),
118
+ ]);
117
119
  /** Build the `cloudBrowser` module once a Session identity is known. */
118
120
  function buildCloudBrowserModule(options) {
119
121
  /** Run one call, mapping any thrown failure and parsing the result through `schema`. */
@@ -176,10 +178,7 @@ function buildCloudBrowserModule(options) {
176
178
  reason: z.string().min(1).max(500),
177
179
  }),
178
180
  output: handoffResultSchema,
179
- execute: (input) => run("handoff", handoffResultSchema, async () => {
180
- await handoff(input.leaseId, input.reason);
181
- return { status: "handed_off" };
182
- }),
181
+ execute: (input) => run("handoff", handoffResultSchema, () => handoff(input.leaseId, input.reason)),
183
182
  }),
184
183
  };
185
184
  }
@@ -283,8 +282,7 @@ function buildCloudBrowserModule(options) {
283
282
  Object.assign(operations, quickReads);
284
283
  if (options.saveFile !== null)
285
284
  Object.assign(operations, saveOperations(options.saveFile));
286
- if (options.handoff !== null)
287
- Object.assign(operations, handoffOperation(options.handoff));
285
+ Object.assign(operations, handoffOperation(options.handoff));
288
286
  return Mycelium.module({
289
287
  id: "cloud-browser",
290
288
  name: "cloudBrowser",
@@ -295,9 +293,9 @@ function buildCloudBrowserModule(options) {
295
293
  /**
296
294
  * Compose the `cloudBrowser` source for one Session, on either host. `browser`
297
295
  * is the module's lease door (in-process, or the Hub's egress RPC); `saveFile`
298
- * is the host's Computer bytes writer and `requestHandoff` its "needs you"
299
- * card. A host without one passes `null` and the matching operations are not
300
- * offered. A lease needs a Session identity, so a session-free host (e.g. the
296
+ * is the host's Computer bytes writer and `handoff` its "needs you" ports. A
297
+ * host without a Computer passes `null` for `saveFile` and that operation is
298
+ * not offered. A lease needs a Session identity, so a session-free host (e.g. the
301
299
  * MCP execute path) gets no module at all.
302
300
  */
303
301
  export function browserCapabilitySource(deps) {
@@ -317,17 +315,16 @@ export function browserCapabilitySource(deps) {
317
315
  agentId: identity.agentId,
318
316
  sessionId,
319
317
  };
320
- const requestHandoff = deps.requestHandoff;
321
318
  const registration = buildCloudBrowserModule({
322
319
  call: (op, opSignal) => deps.browser.call(owner, op, opSignal),
323
320
  quickReads: deps.quickReads,
324
321
  saveFile: deps.saveFile,
325
- handoff: requestHandoff === null
326
- ? null
327
- : async (leaseId, reason) => {
328
- await deps.browser.handoff(owner, leaseId);
329
- requestHandoff(sessionId, `cloud browser: ${reason}`);
330
- },
322
+ handoff: async (leaseId, reason) => {
323
+ await deps.browser.handoff(owner, leaseId);
324
+ if (deps.handoff.channel?.(sessionId, `cloud browser: ${reason}`))
325
+ return { status: "handed_off" };
326
+ return { paused: true, view: deps.handoff.viewPath(owner, leaseId) };
327
+ },
331
328
  });
332
329
  return Promise.resolve({
333
330
  snapshot: { version: "cloud-browser-v1", modules: [registration] },
@@ -8,7 +8,8 @@
8
8
  * the agent's `cloudBrowser` tool. Raw CDP stays internal to this directory.
9
9
  */
10
10
  export { createBrowser, type Browser, type BrowserEvent, type BrowserHost, type BrowserLimits, type BrowserMemberAction, type BrowserMeter, } from "./browser.js";
11
- export { browserCapabilitySource, CLOUD_BROWSER_DESCRIPTIONS, type AgentBrowserDoor, type SaveBrowserFile, } from "./capability-source.js";
11
+ export { browserCapabilitySource, CLOUD_BROWSER_DESCRIPTIONS, type AgentBrowserDoor, type BrowserHandoffPorts, type SaveBrowserFile, } from "./capability-source.js";
12
+ export { liveView, liveViewPaths, type LiveView, type LiveViewDoor, type LiveViewPaths, } from "./live-view.js";
12
13
  export { CloudBrowserCapacityExceeded, CloudBrowserCreditDenied, CloudBrowserLeaseNotFound, CloudBrowserLeasePaused, CloudBrowserTimeout, CloudBrowserUnavailable, CloudBrowserUpstreamError, CloudBrowserUrlDenied, type CloudBrowserFailure, } from "./errors.js";
13
14
  export type { LeaseOwner } from "./lease-registry.js";
14
15
  export { cloudBrowserBounds, extractInputSchema, extractResultSchema, linksResultSchema, markdownInputSchema, markdownResultSchema, navigateResultSchema, openResultSchema, scrapeInputSchema, scrapeResultSchema, snapshotResultSchema, type BinaryResult, type CloudBrowserAck, type CloudBrowserClosed, type CloudBrowserOperation, type CloudBrowserOperationResult, type ExtractInput, type ExtractResult, type LinksResult, type MarkdownInput, type MarkdownResult, type NavigateResult, type OpenResult, type ScrapeInput, type ScrapeResult, type SnapshotResult, } from "./operations.js";
@@ -9,6 +9,7 @@
9
9
  */
10
10
  export { createBrowser, } from "./browser.js";
11
11
  export { browserCapabilitySource, CLOUD_BROWSER_DESCRIPTIONS, } from "./capability-source.js";
12
+ export { liveView, liveViewPaths, } from "./live-view.js";
12
13
  export { CloudBrowserCapacityExceeded, CloudBrowserCreditDenied, CloudBrowserLeaseNotFound, CloudBrowserLeasePaused, CloudBrowserTimeout, CloudBrowserUnavailable, CloudBrowserUpstreamError, CloudBrowserUrlDenied, } from "./errors.js";
13
14
  export { cloudBrowserBounds, extractInputSchema, extractResultSchema, linksResultSchema, markdownInputSchema, markdownResultSchema, navigateResultSchema, openResultSchema, scrapeInputSchema, scrapeResultSchema, snapshotResultSchema, } from "./operations.js";
14
15
  export { browserRunQuickReads, } from "./quick-reads.js";
@@ -0,0 +1,38 @@
1
+ import type { BrowserMemberAction } from "./browser.js";
2
+ import type { BinaryResult } from "./operations.js";
3
+ /**
4
+ * The person's live view of a paused cloud-browser lease, shared by both
5
+ * hosts. It is request/response handlers, not a router: each host registers
6
+ * three routes under its own admission (the Hub's Team chain, a standalone
7
+ * Oyster's owner requirement in `authorization.ts`) and passes the door
8
+ * that admission produced. The page never carries a bearer or a CDP URL;
9
+ * every fetch is same-origin and rides the viewer's own session. It forwards
10
+ * only the closed {@link BrowserMemberAction} set, and never reaches the model.
11
+ */
12
+ /** One admitted viewer's door into one lease: `Browser.member` already bound to it. */
13
+ export type LiveViewDoor = (action: BrowserMemberAction, signal: AbortSignal) => Promise<BinaryResult | null>;
14
+ /** The three paths a host serves for one lease, relative to its own origin. */
15
+ export type LiveViewPaths = Readonly<{
16
+ /** The page a member opens to watch and steer the lease. */
17
+ view: string;
18
+ /** The current screenshot of the lease's page. */
19
+ frame: string;
20
+ /** Where the page posts the member's clicks and typing. */
21
+ input: string;
22
+ }>;
23
+ /** The host-relative paths for a lease whose live view is served under `base`. */
24
+ export declare function liveViewPaths(base: string): LiveViewPaths;
25
+ /** The handlers for one lease's view, frame and input routes. */
26
+ export type LiveView = Readonly<{
27
+ /** The HTML page a member opens to watch and steer the lease. */
28
+ page: () => Response;
29
+ /** The current screenshot of the lease's page. */
30
+ frame: (signal: AbortSignal) => Promise<Response>;
31
+ /** Applies the member's click or typing and answers whether it was accepted. */
32
+ input: (request: Request, signal: AbortSignal) => Promise<Response>;
33
+ }>;
34
+ /**
35
+ * Build the handlers for one admitted viewer and lease. `report` receives a
36
+ * request body that did not decode, so the host can log it with its own sink.
37
+ */
38
+ export declare function liveView(door: LiveViewDoor, paths: LiveViewPaths, report: (event: "input_body_unavailable", cause: unknown) => void): LiveView;
@@ -0,0 +1,179 @@
1
+ import { z } from "zod";
2
+ import { CloudBrowserLeaseNotFound, CloudBrowserUnavailable, } from "./errors.js";
3
+ /** The host-relative paths for a lease whose live view is served under `base`. */
4
+ export function liveViewPaths(base) {
5
+ return {
6
+ view: `${base}/view`,
7
+ frame: `${base}/frame`,
8
+ input: `${base}/input`,
9
+ };
10
+ }
11
+ const actionSchema = z.discriminatedUnion("kind", [
12
+ z.strictObject({ kind: z.literal("screenshot") }),
13
+ z.strictObject({
14
+ kind: z.literal("click"),
15
+ x: z.number().int().min(0).max(20_000),
16
+ y: z.number().int().min(0).max(20_000),
17
+ }),
18
+ z.strictObject({ kind: z.literal("type"), text: z.string().max(10_000) }),
19
+ z.strictObject({
20
+ kind: z.literal("scroll"),
21
+ deltaX: z.number().int().min(-100_000).max(100_000).default(0),
22
+ deltaY: z.number().int().min(-100_000).max(100_000).default(0),
23
+ }),
24
+ z.strictObject({ kind: z.literal("resume") }),
25
+ ]);
26
+ function failureStatus(cause) {
27
+ if (cause instanceof CloudBrowserLeaseNotFound)
28
+ return 404;
29
+ if (cause instanceof CloudBrowserUnavailable)
30
+ return 503;
31
+ return 502;
32
+ }
33
+ function json(body, status) {
34
+ return Response.json(body, { status });
35
+ }
36
+ /**
37
+ * Build the handlers for one admitted viewer and lease. `report` receives a
38
+ * request body that did not decode, so the host can log it with its own sink.
39
+ */
40
+ export function liveView(door, paths, report) {
41
+ return {
42
+ page: () => new Response(viewPage(paths), {
43
+ headers: {
44
+ "content-type": "text/html; charset=utf-8",
45
+ "cache-control": "no-store",
46
+ },
47
+ }),
48
+ frame: async (signal) => {
49
+ try {
50
+ const frame = await door({ kind: "screenshot" }, signal);
51
+ if (frame === null)
52
+ return json({ error: "no_frame" }, 502);
53
+ return new Response(new Blob([frame.bytes.slice().buffer]), {
54
+ status: 200,
55
+ headers: {
56
+ "content-type": frame.contentType,
57
+ "cache-control": "no-store",
58
+ },
59
+ });
60
+ }
61
+ catch (error) {
62
+ return json({ error: "frame_unavailable" }, failureStatus(error));
63
+ }
64
+ },
65
+ input: async (request, signal) => {
66
+ let body;
67
+ try {
68
+ body = await request.json();
69
+ }
70
+ catch (cause) {
71
+ report("input_body_unavailable", cause);
72
+ return json({ error: "invalid_action" }, 400);
73
+ }
74
+ const parsed = actionSchema.safeParse(body);
75
+ if (!parsed.success)
76
+ return json({ error: "invalid_action" }, 400);
77
+ try {
78
+ await door(parsed.data, signal);
79
+ return json({ ok: true }, 200);
80
+ }
81
+ catch (error) {
82
+ return json({ error: "input_failed" }, failureStatus(error));
83
+ }
84
+ },
85
+ };
86
+ }
87
+ function viewPage(paths) {
88
+ return `<!doctype html>
89
+ <html lang="en">
90
+ <head>
91
+ <meta charset="utf-8" />
92
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
93
+ <meta name="color-scheme" content="light dark" />
94
+ <title>Cloud browser</title>
95
+ <style>
96
+ :root { --bg: #f6f5f2; --panel: #ffffff; --ink: #1c1b19; --muted: #6a6761; --line: #d9d6cf; --accent: #2f6f4e; --accent-ink: #ffffff; --live: #2f9e63; }
97
+ @media (prefers-color-scheme: dark) {
98
+ :root { --bg: #161513; --panel: #201f1c; --ink: #ece9e2; --muted: #9a968d; --line: #36342f; --accent: #5cb987; --accent-ink: #10231a; --live: #5cd08f; }
99
+ }
100
+ * { box-sizing: border-box; }
101
+ body { margin: 0; min-height: 100vh; font: 15px/1.4 system-ui, sans-serif; background: var(--bg); color: var(--ink); }
102
+ main { max-width: 1200px; margin: 0 auto; padding: 16px; display: grid; gap: 12px; }
103
+ header { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; }
104
+ header h1 { font-size: 16px; margin: 0; font-weight: 600; flex: 1; min-width: 12ch; }
105
+ .dot { width: 8px; height: 8px; border-radius: 50%; background: var(--live); flex: none; }
106
+ .dot[data-state="idle"] { background: var(--muted); }
107
+ .hint { color: var(--muted); margin: 0; }
108
+ .controls { display: flex; gap: 8px; flex-wrap: wrap; }
109
+ .controls input { flex: 1; min-width: 12ch; padding: 8px 10px; border: 1px solid var(--line); border-radius: 6px; background: var(--panel); color: inherit; font: inherit; }
110
+ button { padding: 8px 14px; border: 1px solid var(--line); border-radius: 6px; background: var(--panel); color: inherit; font: inherit; cursor: pointer; }
111
+ button.primary { background: var(--accent); border-color: var(--accent); color: var(--accent-ink); }
112
+ #stage { border: 1px solid var(--line); border-radius: 8px; background: var(--panel); overflow: hidden; }
113
+ #frame { display: block; width: 100%; height: auto; cursor: crosshair; }
114
+ #done { padding: 16px; margin: 0; }
115
+ </style>
116
+ </head>
117
+ <body>
118
+ <main>
119
+ <header>
120
+ <span class="dot" id="dot" data-state="live"></span>
121
+ <h1>The Agent needs you in this browser</h1>
122
+ <div class="controls"><button class="primary" id="done-button" type="button">Done</button></div>
123
+ </header>
124
+ <p class="hint" id="hint">Click the page to interact, type below, then press Done so the Agent can continue.</p>
125
+ <div class="controls">
126
+ <input id="text" type="text" autocomplete="off" placeholder="Text to type into the focused field" />
127
+ <button id="send" type="button">Send text</button>
128
+ </div>
129
+ <div id="stage"><img id="frame" alt="Live cloud browser" /></div>
130
+ </main>
131
+ <script>
132
+ const paths = ${JSON.stringify(paths)};
133
+ const img = document.getElementById("frame");
134
+ const dot = document.getElementById("dot");
135
+ let finished = false;
136
+ async function act(action) {
137
+ const response = await fetch(paths.input, {
138
+ method: "POST",
139
+ headers: { "content-type": "application/json" },
140
+ body: JSON.stringify(action),
141
+ });
142
+ return response.ok;
143
+ }
144
+ async function refresh() {
145
+ if (finished) return;
146
+ const response = await fetch(paths.frame, { cache: "no-store" });
147
+ dot.dataset.state = response.ok ? "live" : "idle";
148
+ if (!response.ok) return;
149
+ const previous = img.src;
150
+ img.src = URL.createObjectURL(await response.blob());
151
+ if (previous.startsWith("blob:")) URL.revokeObjectURL(previous);
152
+ }
153
+ img.addEventListener("click", async (event) => {
154
+ const rect = img.getBoundingClientRect();
155
+ await act({
156
+ kind: "click",
157
+ x: Math.round((event.clientX - rect.left) * (img.naturalWidth / rect.width)),
158
+ y: Math.round((event.clientY - rect.top) * (img.naturalHeight / rect.height)),
159
+ });
160
+ await refresh();
161
+ });
162
+ document.getElementById("send").addEventListener("click", async () => {
163
+ const field = document.getElementById("text");
164
+ if (field.value) await act({ kind: "type", text: field.value });
165
+ field.value = "";
166
+ await refresh();
167
+ });
168
+ document.getElementById("done-button").addEventListener("click", async () => {
169
+ if (!(await act({ kind: "resume" }))) return;
170
+ finished = true;
171
+ dot.dataset.state = "idle";
172
+ document.querySelector("main").innerHTML = '<p id="done">Done. The Agent can drive the browser again.</p>';
173
+ });
174
+ refresh();
175
+ setInterval(refresh, 1000);
176
+ </script>
177
+ </body>
178
+ </html>`;
179
+ }
@@ -13,6 +13,8 @@ export type ConversationBinding = Readonly<{
13
13
  siteKey: string;
14
14
  origins: readonly string[];
15
15
  accent?: string | undefined;
16
+ /** Visitors must pass Turnstile before a mint. */
17
+ turnstile?: boolean | undefined;
16
18
  }> | Readonly<{
17
19
  provider: "discord" | "email" | "game";
18
20
  }>;
@@ -0,0 +1,33 @@
1
+ import type { ConversationBinding } from "./binding.js";
2
+ /**
3
+ * Whether one Session of an Agent may run, and under which channel binding.
4
+ * A channel never narrows or widens the Agent's own tools and permissions; it
5
+ * only admits or refuses the run. A missing, suspended or unreadable binding
6
+ * denies the run.
7
+ */
8
+ export type ChannelRunDecision<B extends ConversationBinding> = Readonly<{
9
+ kind: "private";
10
+ }> | Readonly<{
11
+ kind: "channel";
12
+ binding: B;
13
+ }> | Readonly<{
14
+ kind: "denied";
15
+ bindingId: string;
16
+ reason: ChannelDenial;
17
+ }>;
18
+ /** Why a channel Session may not run. */
19
+ export type ChannelDenial = "binding_missing" | "binding_suspended" | "lookup_failed";
20
+ /**
21
+ * Decide one Session. `conversationBindingId` is the binding the Session was
22
+ * opened under (null for an owner Session); `binding` is that binding as the
23
+ * Agent currently knows it, or null when it knows none.
24
+ */
25
+ export declare function decideChannelRun<B extends ConversationBinding>(input: Readonly<{
26
+ conversationBindingId: string | null;
27
+ binding: B | null;
28
+ }>): ChannelRunDecision<B>;
29
+ /** Run the lookup and decision together; a throwing lookup denies. */
30
+ export declare function decideChannelRunSafely<B extends ConversationBinding>(lookup: () => Readonly<{
31
+ conversationBindingId: string | null;
32
+ binding: B | null;
33
+ }>, sessionId: string, onFailure: (cause: unknown) => void): ChannelRunDecision<B>;
@@ -0,0 +1,25 @@
1
+ /**
2
+ * Decide one Session. `conversationBindingId` is the binding the Session was
3
+ * opened under (null for an owner Session); `binding` is that binding as the
4
+ * Agent currently knows it, or null when it knows none.
5
+ */
6
+ export function decideChannelRun(input) {
7
+ const { conversationBindingId: bindingId, binding } = input;
8
+ if (bindingId === null)
9
+ return { kind: "private" };
10
+ if (binding?.bindingId !== bindingId)
11
+ return { kind: "denied", bindingId, reason: "binding_missing" };
12
+ if (binding.lifecycle !== "active")
13
+ return { kind: "denied", bindingId, reason: "binding_suspended" };
14
+ return { kind: "channel", binding };
15
+ }
16
+ /** Run the lookup and decision together; a throwing lookup denies. */
17
+ export function decideChannelRunSafely(lookup, sessionId, onFailure) {
18
+ try {
19
+ return decideChannelRun(lookup());
20
+ }
21
+ catch (cause) {
22
+ onFailure(cause);
23
+ return { kind: "denied", bindingId: sessionId, reason: "lookup_failed" };
24
+ }
25
+ }