@fungi.computer/oyster 0.9.0 → 0.10.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 +13 -0
- package/dist/agents.d.ts +16 -1
- package/dist/agents.js +60 -3
- package/dist/computer-control-port.d.ts +20 -1
- package/dist/mcp.d.ts +128 -0
- package/dist/mcp.js +63 -1
- package/dist/standalone/agent-computers.d.ts +12 -1
- package/dist/standalone/agent-computers.js +35 -0
- package/dist/standalone/agent-connections.d.ts +47 -0
- package/dist/standalone/agent-connections.js +170 -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 +70 -9
- package/dist/standalone/agents.js +187 -110
- package/dist/standalone/browser.d.ts +4 -3
- package/dist/standalone/browser.js +4 -3
- 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/registry.d.ts +23 -0
- package/dist/standalone/registry.js +30 -0
- package/dist/standalone/web.d.ts +10 -0
- package/dist/standalone/web.js +34 -0
- package/dist/standalone/worker-routes.d.ts +3 -1
- package/dist/standalone/worker-routes.js +1 -0
- package/dist/standalone/worker.js +9 -1
- 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 +2 -1
- package/docs/api/agents.md +81 -3
- package/docs/api/apps.md +129 -111
- 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 +27 -22
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import { type CapabilitySource } from "@fungi.computer/mycelium";
|
|
2
|
+
import { type PublicGet } from "@fungi.computer/veil/public-fetch";
|
|
3
|
+
import { z } from "zod";
|
|
4
|
+
import { type WebSearch } from "./search-contract.js";
|
|
5
|
+
/**
|
|
6
|
+
* The Agent's bounded web reader: `web.fetch` GETs one public URL from the
|
|
7
|
+
* Worker (no Computer needed) and returns readable text plus page metadata.
|
|
8
|
+
* Every hop, redirects included, goes through Veil's public-fetch door, which
|
|
9
|
+
* resolves once, refuses non-public addresses and connects to exactly the
|
|
10
|
+
* address it checked; this module opens no connection of its own. The read is
|
|
11
|
+
* bounded in bytes, characters and time. The owner grants it per binding as
|
|
12
|
+
* the `web` tool.
|
|
13
|
+
*/
|
|
14
|
+
/** Bytes read from one response body before it is cut off. */
|
|
15
|
+
export declare const WEB_FETCH_MAX_BYTES: number;
|
|
16
|
+
declare const outputSchema: z.ZodObject<{
|
|
17
|
+
url: z.ZodString;
|
|
18
|
+
status: z.ZodNumber;
|
|
19
|
+
contentType: z.ZodString;
|
|
20
|
+
title: z.ZodNullable<z.ZodString>;
|
|
21
|
+
description: z.ZodNullable<z.ZodString>;
|
|
22
|
+
text: z.ZodString;
|
|
23
|
+
truncated: z.ZodBoolean;
|
|
24
|
+
bytes: z.ZodNumber;
|
|
25
|
+
}, z.core.$strict>;
|
|
26
|
+
export type WebFetchResult = z.output<typeof outputSchema>;
|
|
27
|
+
/** Fetch one public page: GET only, redirects rechecked, bounded everywhere. */
|
|
28
|
+
export declare function fetchWebPage(input: Readonly<{
|
|
29
|
+
url: string;
|
|
30
|
+
maxChars?: number;
|
|
31
|
+
}>, options: Readonly<{
|
|
32
|
+
get: PublicGet;
|
|
33
|
+
signal: AbortSignal;
|
|
34
|
+
timeoutMs?: number;
|
|
35
|
+
}>): Promise<WebFetchResult>;
|
|
36
|
+
/**
|
|
37
|
+
* Compose the `web` module (`web.fetch`, `web.search`) for one run lease; the
|
|
38
|
+
* host grants both through the `web` tool.
|
|
39
|
+
*/
|
|
40
|
+
export declare function createWebSource(options: Readonly<{
|
|
41
|
+
/** Veil's public-fetch door, the only way this module reaches the web. */
|
|
42
|
+
get: PublicGet;
|
|
43
|
+
/** Metered search, or the explicit unconfigured refusal. */
|
|
44
|
+
search: WebSearch;
|
|
45
|
+
}>): CapabilitySource;
|
|
46
|
+
export {};
|
|
@@ -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, agentMcpServerRoutes, } from "./agents.js";
|
|
24
|
+
import { agentCapabilities, agentApprovalRoutes, agentMcpServerRoutes, 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";
|
|
@@ -1170,6 +1170,7 @@ export function oysterGitOwnerRoutes(env, scope, hostOwnerRoutes, agents) {
|
|
|
1170
1170
|
if (agents !== undefined) {
|
|
1171
1171
|
ownerRoutes.include(agentApprovalRoutes(agents));
|
|
1172
1172
|
ownerRoutes.include(agentMcpServerRoutes(agents));
|
|
1173
|
+
ownerRoutes.include(modelKeyRoutes(agents));
|
|
1173
1174
|
}
|
|
1174
1175
|
return ownerRoutes;
|
|
1175
1176
|
}
|
package/docs/api/agents.md
CHANGED
|
@@ -132,7 +132,7 @@ An owner's request to connect one remote MCP server to an Agent.
|
|
|
132
132
|
|
|
133
133
|
```ts
|
|
134
134
|
type AgentMcpServerRefusal = Readonly<{
|
|
135
|
-
error: "not_found" | "duplicate_name" | "limit";
|
|
135
|
+
error: "not_found" | "duplicate_name" | "limit" | "invalid_endpoint";
|
|
136
136
|
}>;
|
|
137
137
|
```
|
|
138
138
|
|
|
@@ -234,6 +234,7 @@ type OysterAgents = Readonly<{
|
|
|
234
234
|
>
|
|
235
235
|
>;
|
|
236
236
|
};
|
|
237
|
+
keyId?: string;
|
|
237
238
|
} | null>;
|
|
238
239
|
decodeModelChoice: {
|
|
239
240
|
keySource: "workers-ai" | "ai-gateway" | "byok";
|
|
@@ -246,6 +247,7 @@ type OysterAgents = Readonly<{
|
|
|
246
247
|
>
|
|
247
248
|
>;
|
|
248
249
|
};
|
|
250
|
+
keyId?: string;
|
|
249
251
|
} | null;
|
|
250
252
|
setModelChoice: Promise<
|
|
251
253
|
| {
|
|
@@ -259,6 +261,7 @@ type OysterAgents = Readonly<{
|
|
|
259
261
|
>
|
|
260
262
|
>;
|
|
261
263
|
};
|
|
264
|
+
keyId?: string;
|
|
262
265
|
}
|
|
263
266
|
| Readonly<{
|
|
264
267
|
error: "not_found" | "not_granted" | AgentModelRefusal;
|
|
@@ -288,6 +291,28 @@ type OysterAgents = Readonly<{
|
|
|
288
291
|
error: "not_found" | "revision_conflict" | "not_granted";
|
|
289
292
|
}>
|
|
290
293
|
>;
|
|
294
|
+
modelKeys: Promise<
|
|
295
|
+
readonly Readonly<{
|
|
296
|
+
keyId: string;
|
|
297
|
+
provider: ModelKeyProvider;
|
|
298
|
+
label: string;
|
|
299
|
+
createdAt: number;
|
|
300
|
+
validatedAt: number;
|
|
301
|
+
}>[]
|
|
302
|
+
>;
|
|
303
|
+
sealModelKey: Promise<
|
|
304
|
+
| Readonly<{
|
|
305
|
+
keyId: string;
|
|
306
|
+
provider: ModelKeyProvider;
|
|
307
|
+
label: string;
|
|
308
|
+
createdAt: number;
|
|
309
|
+
validatedAt: number;
|
|
310
|
+
}>
|
|
311
|
+
| Readonly<{
|
|
312
|
+
error: ModelKeyRefusal;
|
|
313
|
+
}>
|
|
314
|
+
>;
|
|
315
|
+
removeModelKey: Promise<"deleted" | "absent">;
|
|
291
316
|
mcpServers: Promise<
|
|
292
317
|
| readonly Readonly<{
|
|
293
318
|
serverId: string;
|
|
@@ -305,7 +330,7 @@ type OysterAgents = Readonly<{
|
|
|
305
330
|
hasBearer: boolean;
|
|
306
331
|
}>
|
|
307
332
|
| Readonly<{
|
|
308
|
-
error: "not_found" | "duplicate_name" | "limit";
|
|
333
|
+
error: "not_found" | "duplicate_name" | "limit" | "invalid_endpoint";
|
|
309
334
|
}>
|
|
310
335
|
>;
|
|
311
336
|
removeMcpServer: Promise<boolean>;
|
|
@@ -348,11 +373,43 @@ type AgentModelRefusal =
|
|
|
348
373
|
| "unsupported_key_source"
|
|
349
374
|
| "key_source_mismatch"
|
|
350
375
|
| "model_unavailable"
|
|
351
|
-
| "key_not_connected"
|
|
376
|
+
| "key_not_connected"
|
|
377
|
+
| "key_removed";
|
|
352
378
|
```
|
|
353
379
|
|
|
354
380
|
Stable reason for rejecting a model or credential source before a run.
|
|
355
381
|
|
|
382
|
+
---
|
|
383
|
+
|
|
384
|
+
### ModelKeyRefusal
|
|
385
|
+
|
|
386
|
+
```ts
|
|
387
|
+
type ModelKeyRefusal =
|
|
388
|
+
| "invalid_key"
|
|
389
|
+
| "key_rejected"
|
|
390
|
+
| "provider_unavailable"
|
|
391
|
+
| "custody_unavailable"
|
|
392
|
+
| "key_removed"
|
|
393
|
+
| "target_denied"
|
|
394
|
+
| "limit";
|
|
395
|
+
```
|
|
396
|
+
|
|
397
|
+
Why a key could not be stored or used; stable, secret-free.
|
|
398
|
+
|
|
399
|
+
---
|
|
400
|
+
|
|
401
|
+
### ModelKeySealInput
|
|
402
|
+
|
|
403
|
+
```ts
|
|
404
|
+
type ModelKeySealInput = Readonly<{
|
|
405
|
+
provider: string;
|
|
406
|
+
label: string;
|
|
407
|
+
apiKey: string;
|
|
408
|
+
}>;
|
|
409
|
+
```
|
|
410
|
+
|
|
411
|
+
What the owner submits to seal one provider key.
|
|
412
|
+
|
|
356
413
|
## Variables
|
|
357
414
|
|
|
358
415
|
### maxAgentMcpServers
|
|
@@ -420,6 +477,27 @@ Host-owned direct approval under the admitted owner; never an App capability.
|
|
|
420
477
|
|
|
421
478
|
---
|
|
422
479
|
|
|
480
|
+
### modelKeyRoutes()
|
|
481
|
+
|
|
482
|
+
```ts
|
|
483
|
+
function modelKeyRoutes(agents): Routes<OysterEnv>;
|
|
484
|
+
```
|
|
485
|
+
|
|
486
|
+
Host-owned model-key custody for the owner directly. A key goes in once and
|
|
487
|
+
never comes back out; listings carry provider, label and times only.
|
|
488
|
+
|
|
489
|
+
#### Parameters
|
|
490
|
+
|
|
491
|
+
| Parameter | Type |
|
|
492
|
+
| --------- | ------------------------------- |
|
|
493
|
+
| `agents` | [`OysterAgents`](#oysteragents) |
|
|
494
|
+
|
|
495
|
+
#### Returns
|
|
496
|
+
|
|
497
|
+
[`Routes`](authorization.md#routes)\<[`OysterEnv`](host.md#oysterenv)\>
|
|
498
|
+
|
|
499
|
+
---
|
|
500
|
+
|
|
423
501
|
### agentMcpServerRoutes()
|
|
424
502
|
|
|
425
503
|
```ts
|