@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
@@ -0,0 +1,335 @@
1
+ import { CapabilityFailed, Mycelium, } from "@fungi.computer/mycelium";
2
+ import { VeilError } from "@fungi.computer/veil";
3
+ import { PublicFetchError, } from "@fungi.computer/veil/public-fetch";
4
+ import { decodeHTML } from "entities";
5
+ import { z } from "zod";
6
+ import { webSearchInputSchema, webSearchOutputSchema, } from "./search-contract.js";
7
+ /**
8
+ * The Agent's bounded web reader: `web.fetch` GETs one public URL from the
9
+ * Worker (no Computer needed) and returns readable text plus page metadata.
10
+ * Every hop, redirects included, goes through Veil's public-fetch door, which
11
+ * resolves once, refuses non-public addresses and connects to exactly the
12
+ * address it checked; this module opens no connection of its own. The read is
13
+ * bounded in bytes, characters and time. The owner grants it per binding as
14
+ * the `web` tool.
15
+ */
16
+ /** Bytes read from one response body before it is cut off. */
17
+ export const WEB_FETCH_MAX_BYTES = 1024 * 1024;
18
+ /** Default characters of extracted text returned to the model. */
19
+ const WEB_FETCH_DEFAULT_CHARS = 24_000;
20
+ const maxChars = 100_000;
21
+ /** Whole-call deadline, redirects and DNS included. */
22
+ const WEB_FETCH_TIMEOUT_MS = 10_000;
23
+ const maxRedirects = 5;
24
+ const accept = "text/markdown, text/plain;q=0.9, application/json;q=0.8, text/html;q=0.5, */*;q=0.1";
25
+ const userAgent = "FungiAgent/1.0 (+https://fungi.computer)";
26
+ /** A bounded, typed failure; its message is safe to show the model. */
27
+ class WebFetchError extends CapabilityFailed {
28
+ code;
29
+ constructor(code, message) {
30
+ super({
31
+ namespace: "web",
32
+ operation: "fetch",
33
+ cause: {
34
+ kind: "OperationFailed",
35
+ message: `web.fetch ${code}: ${message}`,
36
+ },
37
+ });
38
+ this.code = code;
39
+ this.name = "WebFetchError";
40
+ }
41
+ }
42
+ const inputSchema = z.strictObject({
43
+ url: z.string().min(1).max(2_048),
44
+ maxChars: z
45
+ .number()
46
+ .int()
47
+ .min(1)
48
+ .max(maxChars)
49
+ .default(WEB_FETCH_DEFAULT_CHARS),
50
+ });
51
+ const outputSchema = z.strictObject({
52
+ url: z.string(),
53
+ status: z.number().int(),
54
+ contentType: z.string(),
55
+ title: z.string().nullable(),
56
+ description: z.string().nullable(),
57
+ text: z.string(),
58
+ truncated: z.boolean(),
59
+ bytes: z.number().int().nonnegative(),
60
+ });
61
+ function parseTarget(raw) {
62
+ const url = URL.parse(raw);
63
+ if (url === null || (url.protocol !== "https:" && url.protocol !== "http:"))
64
+ throw new WebFetchError("disallowed_url", "only http(s) URLs are fetched");
65
+ if (url.username !== "" || url.password !== "")
66
+ throw new WebFetchError("disallowed_url", "URLs with credentials are refused");
67
+ url.hash = "";
68
+ return url;
69
+ }
70
+ /** Map a refusal from Veil's door to the typed failure the model sees. */
71
+ function doorFailure(refusal, url, signal) {
72
+ if (signal.aborted)
73
+ return deadline(signal);
74
+ if (refusal?.code === "denied")
75
+ return new WebFetchError("disallowed_url", `${url.hostname} is not a public address`);
76
+ if (refusal instanceof PublicFetchError && refusal.stage === "dns")
77
+ return new WebFetchError("dns_failed", `${url.hostname} did not resolve`);
78
+ return new WebFetchError("network", `${url.host} could not be reached`);
79
+ }
80
+ function deadline(signal) {
81
+ return signal.reason instanceof DOMException &&
82
+ signal.reason.name === "TimeoutError"
83
+ ? new WebFetchError("timeout", "the page did not answer in time")
84
+ : signal.reason instanceof Error
85
+ ? signal.reason
86
+ : new Error("web.fetch was cancelled");
87
+ }
88
+ /** Read at most the byte cap, cancelling the rest of the body. */
89
+ async function readBounded(response) {
90
+ if (response.body === null)
91
+ return { bytes: new Uint8Array(), truncated: false };
92
+ const reader = response.body.getReader();
93
+ const chunks = [];
94
+ let total = 0;
95
+ let truncated = false;
96
+ for (;;) {
97
+ const next = await reader.read();
98
+ if (next.done)
99
+ break;
100
+ // A Response body yields bytes; the Workers typing leaves the chunk open.
101
+ const value = next.value;
102
+ if (!(value instanceof Uint8Array))
103
+ throw new WebFetchError("network", "the page body was not bytes");
104
+ const room = WEB_FETCH_MAX_BYTES - total;
105
+ if (value.byteLength >= room) {
106
+ chunks.push(value.subarray(0, room));
107
+ total += room;
108
+ truncated = value.byteLength > room;
109
+ if (!truncated)
110
+ continue;
111
+ await reader.cancel();
112
+ break;
113
+ }
114
+ chunks.push(value);
115
+ total += value.byteLength;
116
+ }
117
+ const bytes = new Uint8Array(total);
118
+ let offset = 0;
119
+ for (const chunk of chunks) {
120
+ bytes.set(chunk, offset);
121
+ offset += chunk.byteLength;
122
+ }
123
+ return { bytes, truncated };
124
+ }
125
+ const mediaTypeSchema = z
126
+ .string()
127
+ .transform((value) => value.split(";")[0]?.trim().toLowerCase() ?? "");
128
+ const charsetPattern = /;\s*charset\s*=\s*"?([^";\s]+)"?/iu;
129
+ function decodeText(bytes, contentType) {
130
+ const label = charsetPattern.exec(contentType)?.[1] ?? "utf-8";
131
+ let decoder;
132
+ try {
133
+ decoder = new TextDecoder(label);
134
+ }
135
+ catch (cause) {
136
+ // An unknown charset label is the page's mistake; any other failure is ours.
137
+ if (!(cause instanceof RangeError))
138
+ throw cause;
139
+ decoder = new TextDecoder("utf-8");
140
+ }
141
+ return decoder.decode(bytes);
142
+ }
143
+ const textTypes = new Set([
144
+ "text/plain",
145
+ "text/markdown",
146
+ "text/x-markdown",
147
+ "text/csv",
148
+ "text/xml",
149
+ "application/json",
150
+ "application/ld+json",
151
+ "application/xml",
152
+ "application/rss+xml",
153
+ "application/atom+xml",
154
+ ]);
155
+ const htmlTypes = new Set(["text/html", "application/xhtml+xml"]);
156
+ /** Elements whose content is never readable page text. */
157
+ const hidden = "head, script, style, noscript, template, svg, iframe, canvas, object, select";
158
+ /** Elements that separate blocks of readable text. */
159
+ const blocks = "p, div, section, article, main, aside, header, footer, nav, li, ul, ol, dl, dt, dd, table, tr, blockquote, pre, figure, figcaption, form, h1, h2, h3, h4, h5, h6";
160
+ /** Void elements (no end tag) that still break a line. */
161
+ const breaks = "br, hr";
162
+ /** Extract title, description and readable text with the native HTML rewriter. */
163
+ async function readHtml(html) {
164
+ const parts = [];
165
+ const title = [];
166
+ let description = null;
167
+ let ogTitle = null;
168
+ let hiddenDepth = 0;
169
+ const rewriter = new HTMLRewriter()
170
+ .on("title", {
171
+ text: (chunk) => {
172
+ title.push(chunk.text);
173
+ },
174
+ })
175
+ .on("meta", {
176
+ element: (element) => {
177
+ const key = (element.getAttribute("name") ??
178
+ element.getAttribute("property") ??
179
+ "").toLowerCase();
180
+ const content = element.getAttribute("content");
181
+ if (content === null)
182
+ return;
183
+ if (description === null &&
184
+ (key === "description" || key === "og:description"))
185
+ description = decodeHTML(content);
186
+ if (ogTitle === null && key === "og:title")
187
+ ogTitle = decodeHTML(content);
188
+ },
189
+ })
190
+ .on(hidden, {
191
+ element: (element) => {
192
+ hiddenDepth += 1;
193
+ element.onEndTag(() => {
194
+ hiddenDepth -= 1;
195
+ });
196
+ },
197
+ })
198
+ .on(blocks, {
199
+ element: (element) => {
200
+ parts.push("\n");
201
+ element.onEndTag(() => {
202
+ parts.push("\n");
203
+ });
204
+ },
205
+ })
206
+ .on(breaks, {
207
+ element: () => {
208
+ parts.push("\n");
209
+ },
210
+ })
211
+ .onDocument({
212
+ text: (chunk) => {
213
+ if (hiddenDepth === 0)
214
+ parts.push(chunk.text);
215
+ },
216
+ });
217
+ await rewriter.transform(new Response(html)).arrayBuffer();
218
+ const text = decodeHTML(parts.join(""))
219
+ .replace(/[ \t\f\v\r\u00a0]+/gu, " ")
220
+ .replace(/ *\n */gu, "\n")
221
+ .replace(/\n{3,}/gu, "\n\n")
222
+ .trim();
223
+ const pageTitle = decodeHTML(title.join("")).trim();
224
+ return {
225
+ title: pageTitle === "" ? ogTitle : pageTitle,
226
+ description,
227
+ text,
228
+ };
229
+ }
230
+ /** Fetch one public page: GET only, redirects rechecked, bounded everywhere. */
231
+ export async function fetchWebPage(input, options) {
232
+ const request = inputSchema.parse(input);
233
+ const signal = AbortSignal.any([
234
+ options.signal,
235
+ AbortSignal.timeout(options.timeoutMs ?? WEB_FETCH_TIMEOUT_MS),
236
+ ]);
237
+ let target = parseTarget(request.url);
238
+ let response;
239
+ for (let hop = 0; hop <= maxRedirects; hop += 1) {
240
+ try {
241
+ response = await options.get({ url: target, accept, userAgent, signal });
242
+ }
243
+ catch (error) {
244
+ throw doorFailure(error instanceof VeilError ? error : undefined, target, signal);
245
+ }
246
+ const location = response.headers.get("Location");
247
+ if (response.status < 300 || response.status > 399 || location === null)
248
+ break;
249
+ await response.body?.cancel();
250
+ target = parseTarget(new URL(location, target).href);
251
+ response = undefined;
252
+ }
253
+ if (response === undefined)
254
+ throw new WebFetchError("too_many_redirects", `more than ${String(maxRedirects)} redirects`);
255
+ const contentType = response.headers.get("Content-Type") ?? "";
256
+ if (!response.ok) {
257
+ await response.body?.cancel();
258
+ throw new WebFetchError("non_2xx", `${target.href} answered HTTP ${String(response.status)}`);
259
+ }
260
+ const mediaType = mediaTypeSchema.parse(contentType);
261
+ const html = htmlTypes.has(mediaType);
262
+ if (!html && !textTypes.has(mediaType) && !mediaType.startsWith("text/")) {
263
+ await response.body?.cancel();
264
+ throw new WebFetchError("unsupported_content", `${mediaType || "an unlabelled body"} is not readable text`);
265
+ }
266
+ let body;
267
+ try {
268
+ body = await readBounded(response);
269
+ }
270
+ catch {
271
+ if (signal.aborted)
272
+ throw deadline(signal);
273
+ throw new WebFetchError("network", "the page body was interrupted");
274
+ }
275
+ const decoded = decodeText(body.bytes, contentType);
276
+ const page = html
277
+ ? await readHtml(decoded)
278
+ : { title: null, description: null, text: decoded };
279
+ const text = page.text.slice(0, request.maxChars);
280
+ return outputSchema.parse({
281
+ url: target.href,
282
+ status: response.status,
283
+ contentType: mediaType,
284
+ title: page.title,
285
+ description: page.description,
286
+ text,
287
+ truncated: body.truncated || text.length < page.text.length,
288
+ bytes: body.bytes.byteLength,
289
+ });
290
+ }
291
+ /**
292
+ * Compose the `web` module (`web.fetch`, `web.search`) for one run lease; the
293
+ * host grants both through the `web` tool.
294
+ */
295
+ export function createWebSource(options) {
296
+ const { get } = options;
297
+ return {
298
+ id: "hub-web",
299
+ acquire: ({ signal }) => {
300
+ signal.throwIfAborted();
301
+ return Promise.resolve({
302
+ snapshot: {
303
+ version: "hub-web-v2",
304
+ modules: [
305
+ Mycelium.module({
306
+ id: "hub-web",
307
+ name: "web",
308
+ description: "Search and read the public web.",
309
+ operations: {
310
+ fetch: Mycelium.operation({
311
+ replay: "unsafe",
312
+ description: `Fetch one public http(s) URL with GET and return its readable text, title and description. Redirects are followed (up to ${String(maxRedirects)}); private, local and internal addresses are refused. Reads at most 1 MiB in ${String(WEB_FETCH_TIMEOUT_MS / 1_000)} s and returns up to maxChars characters (default ${String(WEB_FETCH_DEFAULT_CHARS)}); check truncated.`,
313
+ input: inputSchema,
314
+ output: outputSchema,
315
+ execute: (input, context) => fetchWebPage(input, {
316
+ get,
317
+ signal: context.signal,
318
+ }),
319
+ }),
320
+ search: Mycelium.operation({
321
+ replay: "unsafe",
322
+ description: `Search the public web for an objective (optionally with up to 5 short keyword queries) and return ranked URLs with titles and text excerpts. Then read a result with web.fetch.`,
323
+ input: webSearchInputSchema,
324
+ output: webSearchOutputSchema,
325
+ execute: (input, context) => options.search.search(input, context.signal),
326
+ }),
327
+ },
328
+ }),
329
+ ],
330
+ },
331
+ release: () => Promise.resolve(),
332
+ });
333
+ },
334
+ };
335
+ }
@@ -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, } 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,8 @@ 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
+ ownerRoutes.include(modelKeyRoutes(agents));
1173
1174
  }
1174
1175
  return ownerRoutes;
1175
1176
  }
@@ -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<{
135
- error: "not_found" | "duplicate_name" | "limit";
156
+ type ConnectionRefusal = Readonly<{
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
 
@@ -234,6 +266,7 @@ type OysterAgents = Readonly<{
234
266
  >
235
267
  >;
236
268
  };
269
+ keyId?: string;
237
270
  } | null>;
238
271
  decodeModelChoice: {
239
272
  keySource: "workers-ai" | "ai-gateway" | "byok";
@@ -246,6 +279,7 @@ type OysterAgents = Readonly<{
246
279
  >
247
280
  >;
248
281
  };
282
+ keyId?: string;
249
283
  } | null;
250
284
  setModelChoice: Promise<
251
285
  | {
@@ -259,6 +293,7 @@ type OysterAgents = Readonly<{
259
293
  >
260
294
  >;
261
295
  };
296
+ keyId?: string;
262
297
  }
263
298
  | Readonly<{
264
299
  error: "not_found" | "not_granted" | AgentModelRefusal;
@@ -288,27 +323,77 @@ type OysterAgents = Readonly<{
288
323
  error: "not_found" | "revision_conflict" | "not_granted";
289
324
  }>
290
325
  >;
291
- mcpServers: Promise<
292
- | readonly Readonly<{
293
- serverId: string;
294
- name: string;
295
- url: string;
296
- hasBearer: boolean;
297
- }>[]
298
- | null
326
+ modelKeys: Promise<
327
+ readonly Readonly<{
328
+ keyId: string;
329
+ provider: ModelKeyProvider;
330
+ label: string;
331
+ createdAt: number;
332
+ validatedAt: number;
333
+ }>[]
299
334
  >;
300
- addMcpServer: Promise<
335
+ sealModelKey: Promise<
301
336
  | Readonly<{
302
- serverId: string;
303
- name: string;
304
- url: string;
305
- hasBearer: boolean;
337
+ keyId: string;
338
+ provider: ModelKeyProvider;
339
+ label: string;
340
+ createdAt: number;
341
+ validatedAt: number;
342
+ }>
343
+ | Readonly<{
344
+ error: ModelKeyRefusal;
345
+ }>
346
+ >;
347
+ removeModelKey: Promise<"deleted" | "absent">;
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
+ }>[]
362
+ >;
363
+ addConnection: Promise<
364
+ | Readonly<{
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";
375
+ }>
376
+ | Readonly<{
377
+ ok: true;
378
+ }>
379
+ >;
380
+ ungrantConnection: Promise<boolean>;
381
+ removeConnection: Promise<boolean>;
382
+ connectionTools: Promise<
383
+ | readonly string[]
384
+ | Readonly<{
385
+ error: "not_found" | "duplicate_name" | "limit" | "invalid_endpoint";
306
386
  }>
387
+ >;
388
+ completeMcpConnection: Promise<
307
389
  | Readonly<{
308
- error: "not_found" | "duplicate_name" | "limit";
390
+ ok: true;
391
+ }>
392
+ | Readonly<{
393
+ error: string;
309
394
  }>
310
395
  >;
311
- removeMcpServer: Promise<boolean>;
396
+ mcpCallbackUrl: string;
312
397
  fetch: Promise<Response | null>;
313
398
  inbox: Promise<
314
399
  Readonly<{
@@ -348,35 +433,74 @@ type AgentModelRefusal =
348
433
  | "unsupported_key_source"
349
434
  | "key_source_mismatch"
350
435
  | "model_unavailable"
351
- | "key_not_connected";
436
+ | "key_not_connected"
437
+ | "key_removed";
352
438
  ```
353
439
 
354
440
  Stable reason for rejecting a model or credential source before a run.
355
441
 
442
+ ---
443
+
444
+ ### ModelKeyRefusal
445
+
446
+ ```ts
447
+ type ModelKeyRefusal =
448
+ | "invalid_key"
449
+ | "key_rejected"
450
+ | "provider_unavailable"
451
+ | "custody_unavailable"
452
+ | "key_removed"
453
+ | "target_denied"
454
+ | "limit";
455
+ ```
456
+
457
+ Why a key could not be stored or used; stable, secret-free.
458
+
459
+ ---
460
+
461
+ ### ModelKeySealInput
462
+
463
+ ```ts
464
+ type ModelKeySealInput = Readonly<{
465
+ provider: string;
466
+ label: string;
467
+ apiKey: string;
468
+ }>;
469
+ ```
470
+
471
+ What the owner submits to seal one provider key.
472
+
356
473
  ## Variables
357
474
 
358
- ### maxAgentMcpServers
475
+ ### maxAgentConnections
359
476
 
360
477
  ```ts
361
- const maxAgentMcpServers: 16 = 16;
478
+ const maxAgentConnections: 16 = 16;
362
479
  ```
363
480
 
364
- At most this many MCP servers per Agent.
481
+ At most this many connections per Agent.
365
482
 
366
483
  ---
367
484
 
368
- ### agentMcpServerInputSchema
485
+ ### connectionInputSchema
369
486
 
370
487
  ```ts
371
- const agentMcpServerInputSchema: Struct<{
488
+ const connectionInputSchema: Struct<{
372
489
  name: String;
373
490
  url: String;
374
491
  bearer: NullOr<String>;
492
+ oauth: optional<
493
+ Struct<{
494
+ clientId: optional<String>;
495
+ clientSecret: optional<String>;
496
+ scope: optional<String>;
497
+ }>
498
+ >;
375
499
  }>;
376
500
  ```
377
501
 
378
- Owner input for one MCP server: a guest identifier, an `https:` endpoint and an
379
- optional bearer.
502
+ Owner input for one MCP connection: a guest identifier, an `https:` endpoint and
503
+ an optional bearer.
380
504
 
381
505
  ## Functions
382
506
 
@@ -420,14 +544,35 @@ Host-owned direct approval under the admitted owner; never an App capability.
420
544
 
421
545
  ---
422
546
 
423
- ### agentMcpServerRoutes()
547
+ ### modelKeyRoutes()
548
+
549
+ ```ts
550
+ function modelKeyRoutes(agents): Routes<OysterEnv>;
551
+ ```
552
+
553
+ Host-owned model-key custody for the owner directly. A key goes in once and
554
+ never comes back out; listings carry provider, label and times only.
555
+
556
+ #### Parameters
557
+
558
+ | Parameter | Type |
559
+ | --------- | ------------------------------- |
560
+ | `agents` | [`OysterAgents`](#oysteragents) |
561
+
562
+ #### Returns
563
+
564
+ [`Routes`](authorization.md#routes)\<[`OysterEnv`](host.md#oysterenv)\>
565
+
566
+ ---
567
+
568
+ ### connectionRoutes()
424
569
 
425
570
  ```ts
426
- function agentMcpServerRoutes(agents): Routes<OysterEnv>;
571
+ function connectionRoutes(agents): Routes<OysterEnv>;
427
572
  ```
428
573
 
429
- Host-owned Agent MCP server custody for the owner directly; never an App
430
- 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.
431
576
 
432
577
  #### Parameters
433
578