@fungi.computer/oyster 0.10.0 → 0.12.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 (107) hide show
  1. package/README.md +103 -12
  2. package/dist/agents.d.ts +66 -22
  3. package/dist/agents.js +128 -38
  4. package/dist/app-builds.d.ts +2 -0
  5. package/dist/app-builds.js +17 -6
  6. package/dist/authorization.d.ts +25 -3
  7. package/dist/authorization.js +47 -14
  8. package/dist/browser/capability-source.d.ts +23 -5
  9. package/dist/browser/capability-source.js +19 -22
  10. package/dist/browser/index.d.ts +2 -1
  11. package/dist/browser/index.js +1 -0
  12. package/dist/browser/live-view.d.ts +38 -0
  13. package/dist/browser/live-view.js +179 -0
  14. package/dist/build/artifact-writer.d.ts +11 -2
  15. package/dist/build/artifact-writer.js +42 -24
  16. package/dist/build/candidate-cli.mjs +26 -18
  17. package/dist/build/content-objects.d.ts +29 -14
  18. package/dist/build/content-objects.js +57 -19
  19. package/dist/build/local-build.js +3 -0
  20. package/dist/build/submission-contract.d.ts +1 -1
  21. package/dist/build/submission-contract.js +5 -5
  22. package/dist/build-egress.d.ts +8 -7
  23. package/dist/build-egress.js +4 -3
  24. package/dist/build.d.ts +1 -1
  25. package/dist/channels/binding.d.ts +2 -0
  26. package/dist/channels/run-decision.d.ts +33 -0
  27. package/dist/channels/run-decision.js +25 -0
  28. package/dist/channels/visitor-channel.d.ts +84 -14
  29. package/dist/channels/visitor-channel.js +55 -32
  30. package/dist/channels/visitor-edge.d.ts +18 -2
  31. package/dist/channels/visitor-edge.js +67 -5
  32. package/dist/channels/visitors.d.ts +4 -0
  33. package/dist/channels/visitors.js +22 -1
  34. package/dist/channels/web-binding.d.ts +117 -0
  35. package/dist/channels/web-binding.js +227 -0
  36. package/dist/embed-metafiles.d.ts +8 -0
  37. package/dist/embed-metafiles.js +2 -0
  38. package/dist/embed-scripts.d.ts +8 -0
  39. package/dist/embed-scripts.js +3 -0
  40. package/dist/host.d.ts +3 -1
  41. package/dist/host.js +6 -1
  42. package/dist/install-release-cli.d.ts +2 -1
  43. package/dist/install-release-cli.js +18 -10
  44. package/dist/installation-client.d.ts +1 -0
  45. package/dist/installation-operations.d.ts +2 -0
  46. package/dist/installation-operations.js +1 -0
  47. package/dist/pack.d.ts +5 -2
  48. package/dist/pack.js +3 -1
  49. package/dist/page/embed-challenge.d.ts +19 -0
  50. package/dist/page/embed-challenge.js +45 -0
  51. package/dist/page/embed-error.d.ts +2 -0
  52. package/dist/page/embed-error.js +16 -0
  53. package/dist/page/embed-loader-protocol.d.ts +12 -0
  54. package/dist/page/embed-loader-protocol.js +29 -0
  55. package/dist/standalone/agent-connections.d.ts +22 -19
  56. package/dist/standalone/agent-connections.js +150 -106
  57. package/dist/standalone/agents.d.ts +174 -16
  58. package/dist/standalone/agents.js +331 -21
  59. package/dist/standalone/browser.d.ts +14 -2
  60. package/dist/standalone/browser.js +52 -4
  61. package/dist/standalone/channel-session-door.d.ts +4 -0
  62. package/dist/standalone/channel-session-door.js +72 -0
  63. package/dist/standalone/computer-egress.d.ts +5 -3
  64. package/dist/standalone/computer-egress.js +1 -1
  65. package/dist/standalone/hello-app.d.ts +9 -0
  66. package/dist/standalone/hello-app.js +78 -0
  67. package/dist/standalone/install-apps-cli.d.ts +2 -1
  68. package/dist/standalone/install-apps-cli.js +36 -14
  69. package/dist/standalone/instance.js +2 -2
  70. package/dist/standalone/local-desktop.d.ts +11 -0
  71. package/dist/standalone/local-desktop.js +75 -0
  72. package/dist/standalone/owner-routes.d.ts +4 -3
  73. package/dist/standalone/owner-routes.js +7 -1
  74. package/dist/standalone/registry.d.ts +2 -0
  75. package/dist/standalone/sign-in-link.d.ts +9 -0
  76. package/dist/standalone/sign-in-link.js +49 -0
  77. package/dist/standalone/try-cli.d.ts +52 -0
  78. package/dist/standalone/try-cli.js +404 -0
  79. package/dist/standalone/visitor-edge.d.ts +36 -0
  80. package/dist/standalone/visitor-edge.js +67 -0
  81. package/dist/standalone/visitor-proof.d.ts +23 -0
  82. package/dist/standalone/visitor-proof.js +67 -0
  83. package/dist/standalone/website-channels.d.ts +134 -0
  84. package/dist/standalone/website-channels.js +262 -0
  85. package/dist/standalone/worker-routes.d.ts +4 -1
  86. package/dist/standalone/worker-routes.js +3 -0
  87. package/dist/standalone/worker.d.ts +2 -1
  88. package/dist/standalone/worker.js +5 -1
  89. package/dist/testing/capabilities.d.ts +3 -0
  90. package/dist/testing/capabilities.js +1 -0
  91. package/dist/testing/installation.d.ts +4 -2
  92. package/dist/testing/installation.js +7 -2
  93. package/dist/webhook-abuse.d.ts +7 -1
  94. package/dist/webhook-abuse.js +8 -2
  95. package/dist/workers-git.js +2 -2
  96. package/dist/workers.d.ts +7 -2
  97. package/dist/workers.js +1 -1
  98. package/docs/api/agents.md +103 -36
  99. package/docs/api/authorization.md +56 -11
  100. package/docs/api/browser.md +115 -8
  101. package/docs/api/build-contract.md +52 -10
  102. package/docs/api/build.md +16 -2
  103. package/docs/api/host.md +1 -0
  104. package/docs/api/pack.md +179 -3
  105. package/docs/api/workers-git.md +6 -6
  106. package/docs/site/agent-quickstart.mdx +8 -0
  107. package/package.json +34 -8
package/dist/host.d.ts CHANGED
@@ -16,7 +16,7 @@ export type { GuestLimits } from "./guest-policy.js";
16
16
  import { type TimingVariables } from "hono/timing";
17
17
  import * as Schema from "effect/Schema";
18
18
  import { type BackgroundSyncRefusal } from "@fungi.computer/puffball/background-replay";
19
- import { type Installation, type InstallationReader } from "./apps/installation.js";
19
+ import { type ApprovedGrant, type Installation, type InstallationReader } from "./apps/installation.js";
20
20
  import { type ResourceOption } from "./apps/permissions.js";
21
21
  import type { AppToolPolicy } from "./apps/tools.js";
22
22
  import type { LiveOysterKey } from "./keys.js";
@@ -144,6 +144,8 @@ export type CapabilityAdmission = Readonly<{
144
144
  principal: TenantPrincipal;
145
145
  /** The enabled installation the gate admitted for this capability. */
146
146
  installation: Installation;
147
+ /** The installation's approved grant for this capability: its operations and selected resources. */
148
+ grant: ApprovedGrant;
147
149
  }>;
148
150
  /** Capability routes read the host's admission from `c.env`; they never authenticate. */
149
151
  export type CapabilityEnv = {
package/dist/host.js CHANGED
@@ -492,8 +492,13 @@ export function oysterRouteTable(host) {
492
492
  : "write",
493
493
  }).kind === "refused")
494
494
  continue;
495
+ // The route names its exact resource; the table decides it within this
496
+ // grant's selection, never the principal's wider reach alone.
497
+ const grant = grantsFor(facts.installation, facts.declaration, facts.declaredOperations, capability.permission);
498
+ if (grant === null)
499
+ continue;
495
500
  url.pathname = `/${url.pathname.slice(capability.base.length)}`;
496
- return capabilityTable(capability).fetch(new Request(url, context.req.raw), { principal, installation });
501
+ return capabilityTable(capability).fetch(new Request(url, context.req.raw), { principal, installation, grant });
497
502
  }
498
503
  return refusal(403, "Capability permission denied");
499
504
  };
@@ -1,2 +1,3 @@
1
+ import { Cli } from "@fungi.computer/lantern";
1
2
  export declare const installReleaseUsage = "Usage: oyster install <directory|release.json> [--installation-id <name>]";
2
- export declare function installReleaseCommand(args: readonly string[]): Promise<void>;
3
+ export declare function installReleaseCommand(args: readonly string[], ui?: Cli): Promise<void>;
@@ -3,9 +3,12 @@ import { stat } from "node:fs/promises";
3
3
  import { basename, dirname, resolve } from "node:path";
4
4
  import process from "node:process";
5
5
  import { parseArgs } from "node:util";
6
+ import { Cli } from "@fungi.computer/lantern";
6
7
  import { installRelease } from "./pack.js";
7
8
  export const installReleaseUsage = "Usage: oyster install <directory|release.json> [--installation-id <name>]";
8
- export async function installReleaseCommand(args) {
9
+ export async function installReleaseCommand(args,
10
+ // Progress goes to stderr so stdout stays the installation result.
11
+ ui = new Cli({ brand: "fungi", output: process.stderr })) {
9
12
  const { values, positionals } = parseArgs({
10
13
  args: [...args],
11
14
  allowPositionals: true,
@@ -33,14 +36,19 @@ export async function installReleaseCommand(args) {
33
36
  if (!info.isDirectory() &&
34
37
  (!info.isFile() || basename(path) !== "release.json"))
35
38
  throw new Error("Expected a Release directory or release.json");
36
- const response = await installRelease({
37
- directory: info.isDirectory() ? path : dirname(path),
38
- url,
39
- key,
40
- installationId: values["installation-id"],
39
+ ui.welcome("Oyster: install a Release");
40
+ const body = await ui.task(`Installing ${basename(path)}`, async () => {
41
+ const response = await installRelease({
42
+ directory: info.isDirectory() ? path : dirname(path),
43
+ url,
44
+ key,
45
+ installationId: values["installation-id"],
46
+ });
47
+ const text = await response.text();
48
+ if (!response.ok)
49
+ throw new Error("Installation failed (" + String(response.status) + "): " + text);
50
+ return text;
41
51
  });
42
- const body = await response.text();
43
- if (!response.ok)
44
- throw new Error("Installation failed (" + String(response.status) + "): " + body);
45
- process.stdout.write(body + "\n");
52
+ process.stdout.write(body.trim() + "\n");
53
+ ui.outro(`Open ${url}/ to use it.`);
46
54
  }
@@ -1,5 +1,6 @@
1
1
  import type { Release } from "@fungi.computer/puffball";
2
2
  import { type InstallationOperation } from "./installation-operations.js";
3
+ /** An installation operation that has finished: it is no longer pending. */
3
4
  export type InstallationCompletion = Exclude<InstallationOperation, {
4
5
  state: "pending";
5
6
  }>;
@@ -127,6 +127,7 @@ declare const installationOutcomeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
127
127
  }, z.core.$strict>], "state">;
128
128
  export type InstallationOutcome = z.output<typeof installationOutcomeSchema>;
129
129
  /** One wire contract for admission and subsequent authoritative observation. */
130
+ /** Parses the owner's answer about one installation request: pending, installed, refused or unconfirmed. */
130
131
  export declare const installationOperationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
131
132
  state: z.ZodLiteral<"pending">;
132
133
  requestId: z.ZodString;
@@ -323,6 +324,7 @@ export declare const installationOperationSchema: z.ZodDiscriminatedUnion<[z.Zod
323
324
  };
324
325
  }, unknown>>;
325
326
  }, z.core.$strict>], "state">;
327
+ /** The owner's answer about one installation request. */
326
328
  export type InstallationOperation = z.output<typeof installationOperationSchema>;
327
329
  declare const installationAdmissionSchema: z.ZodObject<{
328
330
  requestId: z.ZodString;
@@ -76,6 +76,7 @@ const terminalOperationSchema = z.discriminatedUnion("state", [
76
76
  unconfirmedSchema.extend(identity),
77
77
  ]);
78
78
  /** One wire contract for admission and subsequent authoritative observation. */
79
+ /** Parses the owner's answer about one installation request: pending, installed, refused or unconfirmed. */
79
80
  export const installationOperationSchema = z.discriminatedUnion("state", [
80
81
  pendingOperationSchema,
81
82
  successReferenceSchema
package/dist/pack.d.ts CHANGED
@@ -1,8 +1,9 @@
1
- import { type InstallationObservationBudget } from "./installation-client.js";
1
+ import { type InstallationCompletion, type InstallationObservationBudget } from "./installation-client.js";
2
2
  import { type ArtifactRef, type Release } from "@fungi.computer/puffball";
3
3
  import { type AppPublisherCoreConfigInput } from "./build.js";
4
4
  import type { InstallationOperation } from "./installation-operations.js";
5
- export { InstallationObservationError } from "./installation-client.js";
5
+ export { InstallationObservationError, type InstallationCompletion, } from "./installation-client.js";
6
+ export { installationOperationSchema, type InstallationOperation, } from "./installation-operations.js";
6
7
  /** One committed repository and its canonical App build recipe. */
7
8
  export type PackOptions = Readonly<{
8
9
  /** The App's ID, `app_<name>`. */
@@ -72,6 +73,8 @@ export declare function installRelease(input: Readonly<{
72
73
  installationId?: string;
73
74
  /** Report owner-correlated admission without shortening the completion wait. */
74
75
  onAdmitted?: (operation: InstallationOperation) => void;
76
+ /** Runs once with the completed operation, before the response is made. */
77
+ onCompleted?: (operation: InstallationCompletion) => Promise<void>;
75
78
  }> & InstallationObservationBudget): Promise<Response>;
76
79
  /** Project one exact first-party commit's editable source, `git push` it to
77
80
  * an Oyster's own template for that App, and claim the pushed head, so
package/dist/pack.js CHANGED
@@ -10,7 +10,8 @@ import { commitPreparedCandidate, createAppCandidatePreparer, createArtifactsSou
10
10
  import { templateSeedClaimSchema, } from "./source/template-seed.js";
11
11
  import { pushTemplateSource } from "./source/template-push.js";
12
12
  import { sha256 } from "./release.js";
13
- export { InstallationObservationError } from "./installation-client.js";
13
+ export { InstallationObservationError, } from "./installation-client.js";
14
+ export { installationOperationSchema, } from "./installation-operations.js";
14
15
  async function filesUnder(directory) {
15
16
  const entries = await readdir(directory, {
16
17
  recursive: true,
@@ -127,6 +128,7 @@ export async function installRelease(input) {
127
128
  if (input.onAdmitted !== undefined)
128
129
  installation = { ...installation, onAdmitted: input.onAdmitted };
129
130
  const operation = await installOnOyster(installation);
131
+ await input.onCompleted?.(operation);
130
132
  return completedInstallationResponse(operation);
131
133
  }
132
134
  /** Project one exact first-party commit's editable source, `git push` it to
@@ -0,0 +1,19 @@
1
+ /**
2
+ * The Turnstile check a site can require before it mints a visitor. The
3
+ * embed document carries the public site key only when the owner asked for the
4
+ * check and the host holds its keys; the token goes back with the first mint.
5
+ */
6
+ type Turnstile = {
7
+ render(container: HTMLElement, options: {
8
+ sitekey: string;
9
+ callback: (token: string) => void;
10
+ "error-callback": () => void;
11
+ }): string;
12
+ remove(widgetId: string): void;
13
+ };
14
+ declare global {
15
+ var turnstile: Turnstile | undefined;
16
+ }
17
+ /** Show the check over the chat until it passes, then hand back its token. */
18
+ export declare function requestChallenge(siteKey: string): Promise<string>;
19
+ export {};
@@ -0,0 +1,45 @@
1
+ const scriptUrl = "https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit";
2
+ function loadTurnstile() {
3
+ const loaded = globalThis.turnstile;
4
+ if (loaded !== undefined)
5
+ return Promise.resolve(loaded);
6
+ return new Promise((resolve, reject) => {
7
+ const script = document.createElement("script");
8
+ script.src = scriptUrl;
9
+ script.async = true;
10
+ script.addEventListener("load", () => {
11
+ const api = globalThis.turnstile;
12
+ if (api === undefined)
13
+ reject(new Error("turnstile_unavailable"));
14
+ else
15
+ resolve(api);
16
+ });
17
+ script.addEventListener("error", () => {
18
+ reject(new Error("turnstile_unavailable"));
19
+ });
20
+ document.head.append(script);
21
+ });
22
+ }
23
+ /** Show the check over the chat until it passes, then hand back its token. */
24
+ export async function requestChallenge(siteKey) {
25
+ const api = await loadTurnstile();
26
+ const surface = document.createElement("div");
27
+ surface.setAttribute("aria-label", "Security check");
28
+ surface.className =
29
+ "fixed inset-0 z-10 flex items-center justify-center bg-base-100";
30
+ document.body.append(surface);
31
+ try {
32
+ return await new Promise((resolve, reject) => {
33
+ api.render(surface, {
34
+ sitekey: siteKey,
35
+ callback: resolve,
36
+ "error-callback": () => {
37
+ reject(new Error("turnstile_failed"));
38
+ },
39
+ });
40
+ });
41
+ }
42
+ finally {
43
+ surface.remove();
44
+ }
45
+ }
@@ -0,0 +1,2 @@
1
+ /** Report a widget failure without writing exception messages or visitor data. */
2
+ export declare function reportEmbedCatchFailure(operation: string, cause: unknown): void;
@@ -0,0 +1,16 @@
1
+ function describeCause(cause, depth = 0) {
2
+ if (!(cause instanceof Error))
3
+ return { kind: "non-error" };
4
+ const description = { kind: "error" };
5
+ if (cause.cause !== undefined && depth < 3)
6
+ description.cause = describeCause(cause.cause, depth + 1);
7
+ return description;
8
+ }
9
+ /** Report a widget failure without writing exception messages or visitor data. */
10
+ export function reportEmbedCatchFailure(operation, cause) {
11
+ console.error(JSON.stringify({
12
+ event: "hub_catch_failure",
13
+ operation,
14
+ cause: describeCause(cause),
15
+ }));
16
+ }
@@ -0,0 +1,12 @@
1
+ import * as z from "zod";
2
+ /** The parent accepts this constant only from its own iframe and serving origin. */
3
+ export declare const CLOSE_MESSAGE = "fungi-embed:close";
4
+ /** Decode the snippet's presentation choice; absent means the visitor's OS. */
5
+ export declare function parseEmbedTheme(value: string | undefined): "auto" | "light" | "dark" | null;
6
+ declare const siteThemeSchema: z.ZodObject<{
7
+ accent: z.ZodNullable<z.ZodString>;
8
+ originAllowed: z.ZodBoolean;
9
+ }, z.core.$strict>;
10
+ /** Decode the bounded public accent, without taking host-page CSS or fonts. */
11
+ export declare function parseSiteTheme(body: string): z.infer<typeof siteThemeSchema> | null;
12
+ export {};
@@ -0,0 +1,29 @@
1
+ import * as Schema from "effect/Schema";
2
+ import * as Option from "effect/Option";
3
+ import * as z from "zod";
4
+ /** The parent accepts this constant only from its own iframe and serving origin. */
5
+ export const CLOSE_MESSAGE = "fungi-embed:close";
6
+ const embedThemeSchema = z.enum(["light", "dark", "auto"]).default("auto");
7
+ /** Decode the snippet's presentation choice; absent means the visitor's OS. */
8
+ export function parseEmbedTheme(value) {
9
+ const parsed = embedThemeSchema.safeParse(value);
10
+ return parsed.success ? parsed.data : null;
11
+ }
12
+ const decodeJson = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Json));
13
+ const siteThemeSchema = z.strictObject({
14
+ accent: z
15
+ .string()
16
+ .regex(/^#[0-9a-f]{6}$/iu)
17
+ .nullable(),
18
+ originAllowed: z.boolean(),
19
+ });
20
+ /** Decode the bounded public accent, without taking host-page CSS or fonts. */
21
+ export function parseSiteTheme(body) {
22
+ if (body.length > 128)
23
+ return null;
24
+ const decoded = decodeJson(body);
25
+ if (Option.isNone(decoded))
26
+ return null;
27
+ const parsed = siteThemeSchema.safeParse(decoded.value);
28
+ return parsed.success ? parsed.data : null;
29
+ }
@@ -1,18 +1,6 @@
1
1
  import type { McpServersConnectionOptions } from "@fungi.computer/knapsack";
2
- import { createSealedCustody, type ConnectionProjection, type EgressRef, type SqlStore } from "@fungi.computer/veil/connections";
3
- import { type AgentMcpServer, type AgentMcpServerInput, type AgentMcpServerRefusal } from "../agents.js";
4
- /** One Agent MCP request as plain data, so it can cross the Durable Object RPC boundary. */
5
- export type McpRequestData = Readonly<{
6
- url: string;
7
- method: string;
8
- headers: readonly (readonly [string, string])[];
9
- body: ArrayBuffer | null;
10
- }>;
11
- /** A refusal crosses RPC as data: a stable code, never a message. */
12
- type McpFetchRefusal = Readonly<{
13
- error: string;
14
- }>;
15
- export declare function mcpRequestData(request: Request): Promise<McpRequestData>;
2
+ import { createSealedCustody, type ConnectionProjection, type EgressRef, type McpRefusal, type McpRequestData, type SqlStore } from "@fungi.computer/veil/connections";
3
+ import { type ConnectionAccess, type ConnectionAdded, type ConnectionInput, type ConnectionRefusal, type OysterConnection } from "../agents.js";
16
4
  /**
17
5
  * This instance's Agent MCP connections over Veil's connections core. The
18
6
  * owner holds every credential; an Agent receives a secret-free projection and
@@ -27,12 +15,28 @@ export declare function createAgentMcpConnections(options: {
27
15
  /** Told after a change so the Agent drops captured tools. */
28
16
  notify: (agentId: string) => Promise<void>;
29
17
  ownerId: string;
18
+ /** Where an authorization server returns the owner; shown to them to register their own app. */
19
+ callbackUrl: string;
30
20
  }): {
31
- servers: (agentId: string) => Promise<readonly AgentMcpServer[] | null>;
32
- add: (agentId: string, input: AgentMcpServerInput) => Promise<AgentMcpServer | AgentMcpServerRefusal>;
33
- remove: (agentId: string, serverId: string) => Promise<boolean>;
21
+ list: () => Promise<readonly OysterConnection[]>;
22
+ add: (input: ConnectionInput) => Promise<ConnectionAdded | ConnectionRefusal>;
23
+ grant: (connectionId: string, agentId: string, access: ConnectionAccess) => Promise<Readonly<{
24
+ ok: true;
25
+ }> | ConnectionRefusal>;
26
+ ungrant: (connectionId: string, agentId: string) => Promise<boolean>;
27
+ remove: (connectionId: string) => Promise<boolean>;
28
+ tools: (connectionId: string) => Promise<readonly string[] | ConnectionRefusal>;
29
+ complete: (query: {
30
+ state: string;
31
+ code: string;
32
+ iss: string | undefined;
33
+ }) => Promise<Readonly<{
34
+ ok: true;
35
+ }> | McpRefusal>;
34
36
  projection: (agentId: string) => Promise<ConnectionProjection>;
35
- fetch: (agentId: string, ref: EgressRef, data: McpRequestData) => Promise<Response | McpFetchRefusal>;
37
+ fetch: (agentId: string, ref: EgressRef, data: McpRequestData) => Promise<Response | Readonly<{
38
+ error: string;
39
+ }>>;
36
40
  };
37
41
  /**
38
42
  * The Agent half: Knapsack connects to each granted server through a fetch that
@@ -44,4 +48,3 @@ export declare function agentMcpSourceOptions(input: {
44
48
  onUnavailable: McpServersConnectionOptions["onUnavailable"];
45
49
  fetch: (ref: EgressRef, request: Request) => Promise<Response>;
46
50
  }): McpServersConnectionOptions;
47
- export {};