@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.
- package/README.md +46 -2
- package/dist/agents.d.ts +82 -23
- package/dist/agents.js +187 -40
- package/dist/authorization.d.ts +25 -3
- package/dist/authorization.js +47 -14
- package/dist/browser/capability-source.d.ts +23 -5
- package/dist/browser/capability-source.js +19 -22
- package/dist/browser/index.d.ts +2 -1
- package/dist/browser/index.js +1 -0
- package/dist/browser/live-view.d.ts +38 -0
- package/dist/browser/live-view.js +179 -0
- package/dist/channels/binding.d.ts +2 -0
- package/dist/channels/run-decision.d.ts +33 -0
- package/dist/channels/run-decision.js +25 -0
- package/dist/channels/visitor-channel.d.ts +84 -14
- package/dist/channels/visitor-channel.js +55 -32
- package/dist/channels/visitor-edge.d.ts +18 -2
- package/dist/channels/visitor-edge.js +67 -5
- package/dist/channels/visitors.d.ts +4 -0
- package/dist/channels/visitors.js +22 -1
- package/dist/channels/web-binding.d.ts +117 -0
- package/dist/channels/web-binding.js +227 -0
- package/dist/computer-control-port.d.ts +20 -1
- package/dist/embed-metafiles.d.ts +8 -0
- package/dist/embed-metafiles.js +2 -0
- package/dist/embed-scripts.d.ts +8 -0
- package/dist/embed-scripts.js +3 -0
- package/dist/host.d.ts +3 -1
- package/dist/host.js +6 -1
- package/dist/mcp.d.ts +128 -0
- package/dist/mcp.js +63 -1
- package/dist/page/embed-challenge.d.ts +19 -0
- package/dist/page/embed-challenge.js +45 -0
- package/dist/page/embed-error.d.ts +2 -0
- package/dist/page/embed-error.js +16 -0
- package/dist/page/embed-loader-protocol.d.ts +12 -0
- package/dist/page/embed-loader-protocol.js +29 -0
- package/dist/standalone/agent-computers.d.ts +12 -1
- package/dist/standalone/agent-computers.js +35 -0
- package/dist/standalone/agent-connections.d.ts +50 -0
- package/dist/standalone/agent-connections.js +214 -0
- package/dist/standalone/agent-model-choice.d.ts +7 -3
- package/dist/standalone/agent-model-choice.js +33 -4
- package/dist/standalone/agents.d.ts +224 -9
- package/dist/standalone/agents.js +485 -115
- package/dist/standalone/browser.d.ts +16 -3
- package/dist/standalone/browser.js +54 -5
- package/dist/standalone/channel-session-door.d.ts +4 -0
- package/dist/standalone/channel-session-door.js +72 -0
- package/dist/standalone/computer-control.js +55 -1
- package/dist/standalone/computer-fleet.d.ts +21 -0
- package/dist/standalone/computer-fleet.js +30 -6
- package/dist/standalone/computer.d.ts +20 -1
- package/dist/standalone/computer.js +63 -1
- package/dist/standalone/model-key-vault.d.ts +50 -0
- package/dist/standalone/model-key-vault.js +147 -0
- package/dist/standalone/owner-routes.d.ts +4 -3
- package/dist/standalone/owner-routes.js +7 -1
- package/dist/standalone/registry.d.ts +23 -0
- package/dist/standalone/registry.js +30 -0
- package/dist/standalone/visitor-edge.d.ts +36 -0
- package/dist/standalone/visitor-edge.js +67 -0
- package/dist/standalone/visitor-proof.d.ts +23 -0
- package/dist/standalone/visitor-proof.js +67 -0
- package/dist/standalone/web.d.ts +10 -0
- package/dist/standalone/web.js +34 -0
- package/dist/standalone/website-channels.d.ts +134 -0
- package/dist/standalone/website-channels.js +262 -0
- package/dist/standalone/worker-routes.d.ts +6 -1
- package/dist/standalone/worker-routes.js +4 -0
- package/dist/standalone/worker.d.ts +2 -1
- package/dist/standalone/worker.js +13 -1
- package/dist/testing/capabilities.d.ts +3 -0
- package/dist/testing/capabilities.js +1 -0
- package/dist/testing/installation.d.ts +4 -2
- package/dist/testing/installation.js +7 -2
- package/dist/web/index.d.ts +3 -0
- package/dist/web/index.js +3 -0
- package/dist/web/search-contract.d.ts +19 -0
- package/dist/web/search-contract.js +14 -0
- package/dist/web/search.d.ts +25 -0
- package/dist/web/search.js +123 -0
- package/dist/web/source.d.ts +46 -0
- package/dist/web/source.js +335 -0
- package/dist/workers-git.js +3 -2
- package/docs/api/agents.md +184 -39
- package/docs/api/apps.md +129 -111
- package/docs/api/browser.md +115 -8
- package/docs/api/build-contract.md +27 -21
- package/docs/api/build.md +55 -54
- package/docs/api/git.md +3 -3
- package/docs/api/host.md +69 -60
- package/docs/api/mcp.md +81 -44
- package/docs/api/workers-git.md +6 -6
- package/docs/api/workers.md +53 -47
- 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
|
+
}
|
package/dist/workers-git.js
CHANGED
|
@@ -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,
|
|
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(
|
|
1172
|
+
ownerRoutes.include(connectionRoutes(agents));
|
|
1173
|
+
ownerRoutes.include(modelKeyRoutes(agents));
|
|
1173
1174
|
}
|
|
1174
1175
|
return ownerRoutes;
|
|
1175
1176
|
}
|
package/docs/api/agents.md
CHANGED
|
@@ -103,40 +103,72 @@ An App's requested tools await the owner's direct approval.
|
|
|
103
103
|
|
|
104
104
|
---
|
|
105
105
|
|
|
106
|
-
###
|
|
106
|
+
### ConnectionAccess
|
|
107
107
|
|
|
108
108
|
```ts
|
|
109
|
-
type
|
|
110
|
-
|
|
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
|
-
|
|
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
|
|
135
|
+
One connection as its owner sees it; no secret, locator or token ever appears.
|
|
118
136
|
|
|
119
137
|
---
|
|
120
138
|
|
|
121
|
-
###
|
|
139
|
+
### ConnectionAdded
|
|
122
140
|
|
|
123
141
|
```ts
|
|
124
|
-
type
|
|
142
|
+
type ConnectionAdded = Readonly<{
|
|
143
|
+
connectionId: string;
|
|
144
|
+
authorizeUrl: string | null;
|
|
145
|
+
}>;
|
|
125
146
|
```
|
|
126
147
|
|
|
127
|
-
|
|
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
|
-
###
|
|
153
|
+
### ConnectionRefusal
|
|
132
154
|
|
|
133
155
|
```ts
|
|
134
|
-
type
|
|
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
|
|
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
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
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
|
-
|
|
335
|
+
sealModelKey: Promise<
|
|
301
336
|
| Readonly<{
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
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
|
-
|
|
390
|
+
ok: true;
|
|
391
|
+
}>
|
|
392
|
+
| Readonly<{
|
|
393
|
+
error: string;
|
|
309
394
|
}>
|
|
310
395
|
>;
|
|
311
|
-
|
|
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
|
-
###
|
|
475
|
+
### maxAgentConnections
|
|
359
476
|
|
|
360
477
|
```ts
|
|
361
|
-
const
|
|
478
|
+
const maxAgentConnections: 16 = 16;
|
|
362
479
|
```
|
|
363
480
|
|
|
364
|
-
At most this many
|
|
481
|
+
At most this many connections per Agent.
|
|
365
482
|
|
|
366
483
|
---
|
|
367
484
|
|
|
368
|
-
###
|
|
485
|
+
### connectionInputSchema
|
|
369
486
|
|
|
370
487
|
```ts
|
|
371
|
-
const
|
|
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
|
|
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
|
-
###
|
|
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
|
|
571
|
+
function connectionRoutes(agents): Routes<OysterEnv>;
|
|
427
572
|
```
|
|
428
573
|
|
|
429
|
-
Host-owned
|
|
430
|
-
|
|
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
|
|