@fungi.computer/oyster 0.8.2 → 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.
Files changed (72) hide show
  1. package/README.md +34 -17
  2. package/dist/agents.d.ts +16 -1
  3. package/dist/agents.js +63 -3
  4. package/dist/apps/catalog.d.ts +11 -0
  5. package/dist/apps/catalog.js +1 -0
  6. package/dist/apps/gate.d.ts +2 -2
  7. package/dist/apps/installation.d.ts +7 -7
  8. package/dist/apps/permissions.d.ts +5 -5
  9. package/dist/boot-host-script.js +1 -1
  10. package/dist/build/candidate-cli.mjs +1 -0
  11. package/dist/computer-control-port.d.ts +20 -1
  12. package/dist/host.js +11 -4
  13. package/dist/installation-client.d.ts +6 -5
  14. package/dist/installation-client.js +21 -17
  15. package/dist/installation-execution.js +41 -8
  16. package/dist/installation-operations.d.ts +30 -8
  17. package/dist/installation-operations.js +122 -24
  18. package/dist/instance-refusal.d.ts +4 -2
  19. package/dist/instance-refusal.js +5 -1
  20. package/dist/mcp.d.ts +132 -2
  21. package/dist/mcp.js +63 -1
  22. package/dist/page/mount.d.ts +8 -1
  23. package/dist/page/mount.js +72 -6
  24. package/dist/page-script.js +3 -3
  25. package/dist/standalone/agent-computers.d.ts +12 -1
  26. package/dist/standalone/agent-computers.js +35 -0
  27. package/dist/standalone/agent-connections.d.ts +47 -0
  28. package/dist/standalone/agent-connections.js +170 -0
  29. package/dist/standalone/agent-model-choice.d.ts +7 -3
  30. package/dist/standalone/agent-model-choice.js +33 -4
  31. package/dist/standalone/agents.d.ts +70 -9
  32. package/dist/standalone/agents.js +187 -110
  33. package/dist/standalone/app-set.js +6 -7
  34. package/dist/standalone/browser.d.ts +4 -3
  35. package/dist/standalone/browser.js +4 -3
  36. package/dist/standalone/computer-control.js +55 -1
  37. package/dist/standalone/computer-fleet.d.ts +29 -2
  38. package/dist/standalone/computer-fleet.js +51 -23
  39. package/dist/standalone/computer.d.ts +20 -1
  40. package/dist/standalone/computer.js +63 -1
  41. package/dist/standalone/model-key-vault.d.ts +50 -0
  42. package/dist/standalone/model-key-vault.js +147 -0
  43. package/dist/standalone/registry.d.ts +23 -0
  44. package/dist/standalone/registry.js +39 -0
  45. package/dist/standalone/web.d.ts +10 -0
  46. package/dist/standalone/web.js +34 -0
  47. package/dist/standalone/worker-routes.d.ts +3 -1
  48. package/dist/standalone/worker-routes.js +1 -0
  49. package/dist/standalone/worker.js +9 -1
  50. package/dist/standalone/workflow-host.d.ts +5 -5
  51. package/dist/standalone/workflow-trigger-host.d.ts +1 -1
  52. package/dist/web/index.d.ts +3 -0
  53. package/dist/web/index.js +3 -0
  54. package/dist/web/search-contract.d.ts +19 -0
  55. package/dist/web/search-contract.js +14 -0
  56. package/dist/web/search.d.ts +25 -0
  57. package/dist/web/search.js +123 -0
  58. package/dist/web/source.d.ts +46 -0
  59. package/dist/web/source.js +335 -0
  60. package/dist/workers-git.js +2 -1
  61. package/docs/api/agents.md +81 -3
  62. package/docs/api/apps.md +160 -142
  63. package/docs/api/build-contract.md +27 -21
  64. package/docs/api/build.md +55 -54
  65. package/docs/api/git.md +3 -3
  66. package/docs/api/host.md +226 -60
  67. package/docs/api/mcp.md +83 -44
  68. package/docs/api/page/mount.md +6 -1
  69. package/docs/api/workers-git.md +6 -6
  70. package/docs/api/workers.md +53 -47
  71. package/docs/site/agent-quickstart.mdx +4 -2
  72. package/package.json +27 -22
@@ -103,7 +103,7 @@ export declare function createStandaloneWorkflowHost(owner: WatchdogSqliteOwner,
103
103
  authorityVersion: number;
104
104
  declaredOperationsDigest: import("@fungi.computer/puffball").Sha256Digest;
105
105
  approvedGrants: readonly Readonly<{
106
- capability: "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "approvals" | "agent.list" | "agent.manage" | "agent.rename" | "agent.avatar" | "agent.toolPolicy" | "agent.read" | "agent.send" | "llm.generation" | "media.generation" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage";
106
+ capability: "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "approvals" | "agent.list" | "agent.manage" | "agent.rename" | "agent.avatar" | "agent.toolPolicy" | "agent.read" | "agent.send" | "llm.generation" | "media.generation" | "media.share" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage";
107
107
  capabilityApproved: true;
108
108
  operations: readonly string[];
109
109
  resources: "tenant-scope" | readonly Readonly<{
@@ -220,7 +220,7 @@ export declare function createStandaloneWorkflowHost(owner: WatchdogSqliteOwner,
220
220
  authorityVersion: number;
221
221
  declaredOperationsDigest: import("@fungi.computer/puffball").Sha256Digest;
222
222
  approvedGrants: readonly Readonly<{
223
- capability: "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "approvals" | "agent.list" | "agent.manage" | "agent.rename" | "agent.avatar" | "agent.toolPolicy" | "agent.read" | "agent.send" | "llm.generation" | "media.generation" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage";
223
+ capability: "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "approvals" | "agent.list" | "agent.manage" | "agent.rename" | "agent.avatar" | "agent.toolPolicy" | "agent.read" | "agent.send" | "llm.generation" | "media.generation" | "media.share" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage";
224
224
  capabilityApproved: true;
225
225
  operations: readonly string[];
226
226
  resources: "tenant-scope" | readonly Readonly<{
@@ -287,7 +287,7 @@ export declare function createStandaloneWorkflowHost(owner: WatchdogSqliteOwner,
287
287
  authorityVersion: number;
288
288
  declaredOperationsDigest: import("@fungi.computer/puffball").Sha256Digest;
289
289
  approvedGrants: readonly Readonly<{
290
- capability: "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "approvals" | "agent.list" | "agent.manage" | "agent.rename" | "agent.avatar" | "agent.toolPolicy" | "agent.read" | "agent.send" | "llm.generation" | "media.generation" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage";
290
+ capability: "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "approvals" | "agent.list" | "agent.manage" | "agent.rename" | "agent.avatar" | "agent.toolPolicy" | "agent.read" | "agent.send" | "llm.generation" | "media.generation" | "media.share" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage";
291
291
  capabilityApproved: true;
292
292
  operations: readonly string[];
293
293
  resources: "tenant-scope" | readonly Readonly<{
@@ -387,7 +387,7 @@ export declare function createStandaloneWorkflowHost(owner: WatchdogSqliteOwner,
387
387
  authorityVersion: number;
388
388
  declaredOperationsDigest: import("@fungi.computer/puffball").Sha256Digest;
389
389
  approvedGrants: readonly Readonly<{
390
- capability: "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "approvals" | "agent.list" | "agent.manage" | "agent.rename" | "agent.avatar" | "agent.toolPolicy" | "agent.read" | "agent.send" | "llm.generation" | "media.generation" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage";
390
+ capability: "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "approvals" | "agent.list" | "agent.manage" | "agent.rename" | "agent.avatar" | "agent.toolPolicy" | "agent.read" | "agent.send" | "llm.generation" | "media.generation" | "media.share" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage";
391
391
  capabilityApproved: true;
392
392
  operations: readonly string[];
393
393
  resources: "tenant-scope" | readonly Readonly<{
@@ -468,7 +468,7 @@ export declare function createStandaloneWorkflowHost(owner: WatchdogSqliteOwner,
468
468
  authorityVersion: number;
469
469
  declaredOperationsDigest: import("@fungi.computer/puffball").Sha256Digest;
470
470
  approvedGrants: readonly Readonly<{
471
- capability: "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "approvals" | "agent.list" | "agent.manage" | "agent.rename" | "agent.avatar" | "agent.toolPolicy" | "agent.read" | "agent.send" | "llm.generation" | "media.generation" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage";
471
+ capability: "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "approvals" | "agent.list" | "agent.manage" | "agent.rename" | "agent.avatar" | "agent.toolPolicy" | "agent.read" | "agent.send" | "llm.generation" | "media.generation" | "media.share" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage";
472
472
  capabilityApproved: true;
473
473
  operations: readonly string[];
474
474
  resources: "tenant-scope" | readonly Readonly<{
@@ -344,7 +344,7 @@ export declare function createStandaloneWorkflowTriggerHost(options: {
344
344
  readonly operations: readonly string[];
345
345
  }[];
346
346
  readonly nodeId: string;
347
- readonly capabilities: readonly ("approvals" | "agent.list" | "agent.manage" | "agent.rename" | "agent.avatar" | "agent.toolPolicy" | "agent.read" | "agent.send" | "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "llm.generation" | "media.generation" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage")[];
347
+ readonly capabilities: readonly ("approvals" | "agent.list" | "agent.manage" | "agent.rename" | "agent.avatar" | "agent.toolPolicy" | "agent.read" | "agent.send" | "computer.list" | "computer.readFile" | "computer.writeFile" | "computer.execute" | "llm.generation" | "media.generation" | "media.share" | "games:servers" | "git.repository" | "apps.open" | "apps.call" | "app.storage" | "app.events.emit" | "team.workbenchHost" | "marketplace.browse" | "marketplace.purchase" | "workflow.run" | "workflow.publish" | "workflow.arm" | "world" | "channels.read" | "channels.personal.manage")[];
348
348
  readonly graphId?: string;
349
349
  }[];
350
350
  readonly nodeGitAccess: readonly {
@@ -0,0 +1,3 @@
1
+ export { createWebSource, fetchWebPage, WEB_FETCH_MAX_BYTES, type WebFetchResult, } from "./source.js";
2
+ export { parallelWebSearch, unconfiguredWebSearch, WebSearchError, type WebSearchReport, } from "./search.js";
3
+ export { webSearchInputSchema, webSearchOutputSchema, type WebSearch, type WebSearchInput, type WebSearchOutput, } from "./search-contract.js";
@@ -0,0 +1,3 @@
1
+ export { createWebSource, fetchWebPage, WEB_FETCH_MAX_BYTES, } from "./source.js";
2
+ export { parallelWebSearch, unconfiguredWebSearch, WebSearchError, } from "./search.js";
3
+ export { webSearchInputSchema, webSearchOutputSchema, } from "./search-contract.js";
@@ -0,0 +1,19 @@
1
+ import { z } from "zod";
2
+ export declare const webSearchInputSchema: z.ZodObject<{
3
+ objective: z.ZodString;
4
+ queries: z.ZodDefault<z.ZodArray<z.ZodString>>;
5
+ maxResults: z.ZodDefault<z.ZodNumber>;
6
+ }, z.core.$strict>;
7
+ export declare const webSearchOutputSchema: z.ZodObject<{
8
+ results: z.ZodArray<z.ZodObject<{
9
+ url: z.ZodString;
10
+ title: z.ZodNullable<z.ZodString>;
11
+ publishDate: z.ZodNullable<z.ZodString>;
12
+ excerpts: z.ZodArray<z.ZodString>;
13
+ }, z.core.$strict>>;
14
+ }, z.core.$strict>;
15
+ export type WebSearchInput = z.output<typeof webSearchInputSchema>;
16
+ export type WebSearchOutput = z.output<typeof webSearchOutputSchema>;
17
+ export type WebSearch = Readonly<{
18
+ search: (input: WebSearchInput, signal: AbortSignal) => Promise<WebSearchOutput>;
19
+ }>;
@@ -0,0 +1,14 @@
1
+ import { z } from "zod";
2
+ export const webSearchInputSchema = z.strictObject({
3
+ objective: z.string().trim().min(1).max(2_000),
4
+ queries: z.array(z.string().trim().min(1).max(200)).max(5).default([]),
5
+ maxResults: z.number().int().min(1).max(10).default(5),
6
+ });
7
+ export const webSearchOutputSchema = z.strictObject({
8
+ results: z.array(z.strictObject({
9
+ url: z.string(),
10
+ title: z.string().nullable(),
11
+ publishDate: z.string().nullable(),
12
+ excerpts: z.array(z.string()),
13
+ })),
14
+ });
@@ -0,0 +1,25 @@
1
+ import { type VeilBindings } from "@fungi.computer/veil/gatekeeper";
2
+ import type { WebSearch } from "./search-contract.js";
3
+ export type WebSearchErrorCode = "unavailable" | "insufficient_credits" | "denied" | "provider";
4
+ /** A typed search failure whose message is safe to show the model. */
5
+ export declare class WebSearchError extends Error {
6
+ readonly code: WebSearchErrorCode;
7
+ constructor(code: WebSearchErrorCode, message: string);
8
+ }
9
+ /** A diagnostic a host decides how to record; it never carries a body or key. */
10
+ export type WebSearchReport = Readonly<{
11
+ kind: "response_body_unavailable";
12
+ status: number;
13
+ cause: unknown;
14
+ }>;
15
+ /** The operation's behavior when no search provider is configured. */
16
+ export declare const unconfiguredWebSearch: WebSearch;
17
+ /**
18
+ * Parallel Search for a host's Worker environment: unconfigured without
19
+ * Veil's Parallel credential, otherwise Parallel through the AI Gateway when
20
+ * the host names one, else directly.
21
+ */
22
+ export declare function parallelWebSearch(env: VeilBindings, options: Readonly<{
23
+ fetch: typeof globalThis.fetch;
24
+ report: (event: WebSearchReport) => void;
25
+ }>): WebSearch;
@@ -0,0 +1,123 @@
1
+ import { z } from "zod";
2
+ import { configuredProviderEgress, providerFetch, } from "@fungi.computer/veil/gatekeeper";
3
+ /**
4
+ * `web.search` through Parallel's Search API (routed through the AI Gateway
5
+ * when the host names one). Veil owns the key and the route: this module never
6
+ * sees the credential. Without a Parallel key the operation says so and
7
+ * fetches nothing; it never invents results. Funding is the host's decision:
8
+ * the Hub wraps this search in Team credits, a standalone Oyster's owner pays
9
+ * Parallel directly.
10
+ */
11
+ /** Excerpt characters returned to the model across all results. */
12
+ const maxChars = 12_000;
13
+ /** A typed search failure whose message is safe to show the model. */
14
+ export class WebSearchError extends Error {
15
+ code;
16
+ constructor(code, message) {
17
+ super(`web.search ${code}: ${message}`);
18
+ this.code = code;
19
+ this.name = "WebSearchError";
20
+ }
21
+ }
22
+ /** Parallel's `/v1/search` answer; unknown fields are ignored. */
23
+ const parallelResponseSchema = z.looseObject({
24
+ results: z.array(z.looseObject({
25
+ url: z.url(),
26
+ title: z.string().nullish(),
27
+ publish_date: z.string().nullish(),
28
+ excerpts: z.array(z.string()).default([]),
29
+ })),
30
+ });
31
+ /**
32
+ * Parallel Search over `baseUrl`, which is Parallel or the gateway route.
33
+ * `fetch` is Veil's `parallel` route: it carries the key, never this module.
34
+ */
35
+ function createParallelSearch(options) {
36
+ return {
37
+ search: async (input, signal) => {
38
+ let response;
39
+ try {
40
+ response = await options.fetch(`${options.baseUrl}/v1/search`, {
41
+ method: "POST",
42
+ headers: {
43
+ "Content-Type": "application/json",
44
+ },
45
+ body: JSON.stringify({
46
+ objective: input.objective,
47
+ search_queries: input.queries.length > 0
48
+ ? input.queries
49
+ : [input.objective.slice(0, 200)],
50
+ mode: "basic",
51
+ max_chars_total: maxChars,
52
+ advanced_settings: { max_results: input.maxResults },
53
+ }),
54
+ signal,
55
+ });
56
+ }
57
+ catch {
58
+ signal.throwIfAborted();
59
+ throw new WebSearchError("provider", "the search service is unreachable");
60
+ }
61
+ if (!response.ok) {
62
+ await response.body?.cancel();
63
+ throw new WebSearchError("provider", `the search service answered HTTP ${String(response.status)}`);
64
+ }
65
+ let body;
66
+ try {
67
+ body = await response.json();
68
+ }
69
+ catch (cause) {
70
+ signal.throwIfAborted();
71
+ options.report({
72
+ kind: "response_body_unavailable",
73
+ status: response.status,
74
+ cause,
75
+ });
76
+ throw new WebSearchError("provider", "the search answer could not be read");
77
+ }
78
+ const parsed = parallelResponseSchema.safeParse(body);
79
+ if (!parsed.success)
80
+ throw new WebSearchError("provider", "the search answer was malformed");
81
+ let budget = maxChars;
82
+ return {
83
+ results: parsed.data.results
84
+ .slice(0, input.maxResults)
85
+ .map((result) => {
86
+ const excerpts = [];
87
+ for (const excerpt of result.excerpts) {
88
+ if (budget <= 0)
89
+ break;
90
+ excerpts.push(excerpt.slice(0, budget));
91
+ budget -= excerpt.length;
92
+ }
93
+ return {
94
+ url: result.url,
95
+ title: result.title ?? null,
96
+ publishDate: result.publish_date ?? null,
97
+ excerpts,
98
+ };
99
+ }),
100
+ };
101
+ },
102
+ };
103
+ }
104
+ /** The operation's behavior when no search provider is configured. */
105
+ export const unconfiguredWebSearch = {
106
+ search: () => Promise.reject(new WebSearchError("unavailable", "web search is not configured on this platform; no search was run")),
107
+ };
108
+ /**
109
+ * Parallel Search for a host's Worker environment: unconfigured without
110
+ * Veil's Parallel credential, otherwise Parallel through the AI Gateway when
111
+ * the host names one, else directly.
112
+ */
113
+ export function parallelWebSearch(env, options) {
114
+ const egress = configuredProviderEgress(env, { fetch: options.fetch });
115
+ const baseUrl = egress.baseUrl("parallel");
116
+ if (baseUrl === null)
117
+ return unconfiguredWebSearch;
118
+ return createParallelSearch({
119
+ baseUrl,
120
+ fetch: providerFetch(egress, "parallel"),
121
+ report: options.report,
122
+ });
123
+ }
@@ -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
+ }
@@ -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
  }