@fungi.computer/oyster 0.33.0 → 0.35.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 (44) hide show
  1. package/README.md +62 -1
  2. package/dist/app-sandbox.d.ts +2 -2
  3. package/dist/app-sandbox.js +2 -2
  4. package/dist/approval-deadline.d.ts +2 -0
  5. package/dist/approval-deadline.js +7 -0
  6. package/dist/approval-home.d.ts +26 -3
  7. package/dist/approval-home.js +148 -18
  8. package/dist/apps/index.d.ts +1 -1
  9. package/dist/apps/index.js +1 -1
  10. package/dist/boot-host-script.js +1 -1
  11. package/dist/embed-metafiles.js +2 -2
  12. package/dist/embed-scripts.js +1 -1
  13. package/dist/hello-app-script.js +1 -1
  14. package/dist/host.d.ts +6 -4
  15. package/dist/host.js +8 -4
  16. package/dist/mcp.js +42 -13
  17. package/dist/page/app-permissions.js +8 -7
  18. package/dist/page/computer-handles.d.ts +0 -1
  19. package/dist/page/mount.js +1 -0
  20. package/dist/page-config.d.ts +1 -0
  21. package/dist/page-config.js +1 -0
  22. package/dist/page-script.js +2 -2
  23. package/dist/platform-skills.generated.d.ts +5 -2
  24. package/dist/platform-skills.generated.js +6 -2
  25. package/dist/standalone/agents.js +43 -7
  26. package/dist/standalone/computer-fleet.js +3 -0
  27. package/dist/standalone/computer.d.ts +6 -2
  28. package/dist/standalone/computer.js +27 -14
  29. package/dist/standalone/media.js +7 -2
  30. package/dist/standalone/preview.d.ts +21 -20
  31. package/dist/standalone/preview.js +147 -151
  32. package/dist/standalone/registry.d.ts +16 -21
  33. package/dist/standalone/registry.js +81 -28
  34. package/dist/standalone/worker.d.ts +1 -1
  35. package/dist/standalone/worker.js +23 -7
  36. package/dist/starter-agent.d.ts +6 -2
  37. package/dist/starter-agent.js +25 -4
  38. package/dist/workers.d.ts +31 -13
  39. package/dist/workers.js +86 -15
  40. package/docs/api/apps.md +21 -0
  41. package/docs/api/host.md +41 -11
  42. package/docs/api/page/mount.md +24 -22
  43. package/docs/api/workers.md +168 -81
  44. package/package.json +25 -24
package/dist/host.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import type { OysterApprovalCall } from "./approval-home.js";
2
- import type { PendingApproval, ApprovalApplyResult } from "@fungi.computer/approvals";
1
+ import type { OysterApprovalCall, OysterApprovalResult } from "./approval-home.js";
2
+ export type { OysterApprovalResult };
3
3
  import type { WorkflowControl } from "./workflows.js";
4
4
  import type { ComputerControlPort } from "./computer-control-port.js";
5
5
  import { type InstallationOperations } from "./installation-operations.js";
@@ -186,8 +186,8 @@ export type OysterEnv = {
186
186
  export type OysterHost = Readonly<{
187
187
  /** Native approval home. A host without one cannot execute App tool writes. */
188
188
  approvals?: Readonly<{
189
- /** Stage an admitted operation; only the native home may apply it. */
190
- submit(call: OysterApprovalCall): Promise<PendingApproval | ApprovalApplyResult>;
189
+ /** Wait for a decision and return the native home's in-call result. */
190
+ submit(call: OysterApprovalCall, signal: AbortSignal): Promise<OysterApprovalResult>;
191
191
  }>;
192
192
  /**
193
193
  * Host-bound Workflow control; absence exposes no Workflow authority.
@@ -212,6 +212,8 @@ export type OysterHost = Readonly<{
212
212
  bootUi: (release: Release) => Promise<UiBootCheckOutcome>;
213
213
  /** Fixed Computer selected by the host; request input never selects it. */
214
214
  computerId?: string;
215
+ /** The selected Computer's name from its owner; never derived from its ID. */
216
+ computerName?: string | null;
215
217
  /** The fixed Computer's advertised calls for one admitted caller, or null
216
218
  * when the caller holds no Computer access (for a key, without its own
217
219
  * `computer.use` grant). The Computer owner accepts each call against the
package/dist/host.js CHANGED
@@ -1188,7 +1188,10 @@ export function oysterRouteTable(host) {
1188
1188
  installation.installationId === host.homeInstallationId &&
1189
1189
  declaration?.capabilities.includes("team.workbenchHost") === true &&
1190
1190
  grantsFor(facts.installation, facts.declaration, facts.declaredOperations, "team.workbenchHost") !== null;
1191
- const uiUrl = `/ui/${installation.installationId}/${installation.release.releaseId}/`;
1191
+ const uiPath = `/ui/${installation.installationId}/${installation.release.releaseId}/`;
1192
+ // Immutable App documents also carry the host's sandbox policy.
1193
+ const uiUrl = `${uiPath}?${new URLSearchParams({ sandbox: appSandbox }).toString()}`;
1194
+ const computerId = invocationCallerContext(principal, host.computerId ?? null).computerId;
1192
1195
  const config = {
1193
1196
  workbench,
1194
1197
  // The home shell's own code: the module its Release ships beside
@@ -1202,8 +1205,8 @@ export function oysterRouteTable(host) {
1202
1205
  host.workbench !== undefined &&
1203
1206
  (declaration?.storage?.length ?? 0) > 0,
1204
1207
  appsOpen: declaration?.capabilities.includes("apps.open") === true,
1205
- computerId: invocationCallerContext(principal, host.computerId ?? null)
1206
- .computerId,
1208
+ computerId,
1209
+ computerName: computerId === null ? null : (host.computerName ?? null),
1207
1210
  authorityVersion: installation.authority.authorityVersion,
1208
1211
  capabilities,
1209
1212
  commands: declaration?.commands ?? [],
@@ -1226,7 +1229,7 @@ export function oysterRouteTable(host) {
1226
1229
  ? release.ui.build.assets
1227
1230
  .filter((asset) => asset.contentType.startsWith("text/javascript") &&
1228
1231
  asset.path !== shellModuleAssetPath)
1229
- .map((asset) => `<link rel="modulepreload" href="${escapeHtml(`${uiUrl.slice(0, -1)}${asset.path}`)}">`)
1232
+ .map((asset) => `<link rel="modulepreload" href="${escapeHtml(`${uiPath.slice(0, -1)}${asset.path}`)}">`)
1230
1233
  .join("")
1231
1234
  : "";
1232
1235
  const head = `<!doctype html><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>${escapeHtml(installation.installationId)} · ${escapeHtml(title)}</title>${tabIcon}<link rel="stylesheet" href="${(await assets()).fonts.path}">${shellPreloads}`;
@@ -1350,6 +1353,7 @@ export function oysterRouteTable(host) {
1350
1353
  rows: [],
1351
1354
  reason: "params_required",
1352
1355
  error: `Choose a ${missing.kind}`,
1356
+ recovery: { kind: "configure", param: missing.key },
1353
1357
  });
1354
1358
  const authority = invocationAuthorityOf(installation, release);
1355
1359
  const grants = scopedBindings(authority.grants, method, "read");
package/dist/mcp.js CHANGED
@@ -1,6 +1,7 @@
1
1
  import { z } from "zod";
2
2
  import { computerSizeSchema } from "@fungi.computer/computer/backing";
3
- import { PendingApprovalSchema, ApprovalRefusalSchema, } from "@fungi.computer/approvals";
3
+ import { ApprovalRefusalSchema } from "@fungi.computer/approvals";
4
+ import { oysterApprovalDeadlineAt } from "./approval-deadline.js";
4
5
  import { admits } from "./apps/gate.js";
5
6
  import { createMcpWorkflowControl, WORKFLOW_CONTROL_MODULE_ID, } from "./workflows.js";
6
7
  import { causeClass } from "./cause-class.js";
@@ -9,7 +10,7 @@ import { appToolPolicySchema } from "./apps/tools.js";
9
10
  import { emptyAppDeclaration } from "@fungi.computer/puffball/app";
10
11
  import { admittedMethodCallerFacts, invocationCallerContext, } from "./invocation.js";
11
12
  import { guestLimits } from "./guest-policy.js";
12
- import { Mycelium, } from "@fungi.computer/mycelium";
13
+ import { BadResponse, Mycelium, } from "@fungi.computer/mycelium";
13
14
  import { appJsonSchema, appToolFamilySchemas } from "@fungi.computer/forage";
14
15
  import { forageDiscoveryInstructions } from "@fungi.computer/mycelium/effect";
15
16
  import { Knapsack } from "@fungi.computer/knapsack";
@@ -25,9 +26,9 @@ import { defaultAssetPolicy, sha256, verifyRelease, } from "./release.js";
25
26
  export const appApprovalInstructions = [
26
27
  "A write (including Effect: external) may instead return AppApprovalResult:",
27
28
  "type AppApprovalResult =",
28
- ' | { kind: "pending_approval"; recordId: string; description: { title: string; inputBytes: number; inputSha256: string } }',
29
+ ' | { kind: "denied"; by: string; note?: string; message: string }',
29
30
  ' | { kind: "refused"; reason: string; denialNote?: string };',
30
- "On pending_approval, tell the person it is waiting for their approval; do not retry.",
31
+ "A write needing approval waits in this call. Approval returns its output; denial or expiry returns here, never as a Session message.",
31
32
  ].join("\n");
32
33
  const fleetIds = defineIdFamily({
33
34
  family: "mcp-computer-control",
@@ -348,7 +349,7 @@ export async function oysterAppSnapshot(host, surfaces, principal, installations
348
349
  const outputFor = (declared, effect) => mode === "approval" && effect !== "read"
349
350
  ? approvalOutput(declared)
350
351
  : declared;
351
- const runOperation = async (name, effect, input, context, direct) => {
352
+ const runOperation = async (name, effect, input, context, declaredOutput, direct) => {
352
353
  if (mode === "direct" || effect === "read")
353
354
  return direct();
354
355
  if (host.approvals === undefined)
@@ -369,18 +370,35 @@ export async function oysterAppSnapshot(host, surfaces, principal, installations
369
370
  context.operationOrdinal ?? 0,
370
371
  ]))),
371
372
  input,
372
- });
373
- return result.kind === "applied" ? result.output : result;
373
+ deadlineAt: oysterApprovalDeadlineAt(context.deadlineAt),
374
+ }, context.signal);
375
+ if (result.kind !== "applied")
376
+ return result;
377
+ // App data must not take the host-only approval branch of the public
378
+ // output union, even when the App declares a permissive object schema.
379
+ if (isApprovalResult(result.output))
380
+ throw new BadResponse({
381
+ reason: "App output cannot impersonate an approval decision",
382
+ rawCause: undefined,
383
+ });
384
+ const output = declaredOutput.safeParse(result.output);
385
+ if (!output.success)
386
+ throw new BadResponse({
387
+ reason: "Capability output failed its declared schema",
388
+ rawCause: output.error,
389
+ });
390
+ return output.data;
374
391
  };
375
392
  const toolOperations = Object.entries(methods).map(([name, method]) => {
376
393
  operationEffects[name] = method.effect;
394
+ const declaredOutput = appJsonSchema(method.output);
377
395
  const appMethod = Mycelium.operation({
378
396
  replay: "unsafe",
379
397
  access: method.effect === "read" ? "read" : "write",
380
398
  description: `${method.description}\nEffect: ${method.effect}.`,
381
399
  input: appJsonSchema(method.input),
382
- output: outputFor(appJsonSchema(method.output), method.effect),
383
- execute: (input, context) => runOperation(name, method.effect, input, context, () => callAppMethod(name, method.effect, input, context.signal)),
400
+ output: outputFor(declaredOutput, method.effect),
401
+ execute: (input, context) => runOperation(name, method.effect, input, context, declaredOutput, () => callAppMethod(name, method.effect, input, context.signal)),
384
402
  });
385
403
  return [name, appMethod];
386
404
  });
@@ -410,7 +428,7 @@ export async function oysterAppSnapshot(host, surfaces, principal, installations
410
428
  description: `${tool.description}\nEffect: ${compiled.effect}.`,
411
429
  input: tool.input,
412
430
  output: outputFor(tool.output, compiled.effect),
413
- execute: (input, context) => runOperation(`${compiled.name}.${tool.row.tool}`, compiled.effect, input, context, () => {
431
+ execute: (input, context) => runOperation(`${compiled.name}.${tool.row.tool}`, compiled.effect, input, context, tool.output, () => {
414
432
  // The declaring App owns every field below except
415
433
  // `requestId` (this call's own identity) and `input`
416
434
  // (the caller's tool-shaped payload): `tool.row.call` is
@@ -675,14 +693,25 @@ export function oysterMcpCatalogLoad(host) {
675
693
  };
676
694
  };
677
695
  }
678
- const isPendingApproval = Schema.is(PendingApprovalSchema);
679
- const isApprovalRefusal = Schema.is(ApprovalRefusalSchema);
696
+ const isApprovalResult = Schema.is(Schema.Union([
697
+ ApprovalRefusalSchema.check(Schema.makeFilter((value) => value.reason !== "expired")),
698
+ Schema.Struct({
699
+ kind: Schema.Literal("refused"),
700
+ reason: Schema.Literals(["cancelled", "approval_expired"]),
701
+ }),
702
+ Schema.Struct({
703
+ kind: Schema.Literal("denied"),
704
+ by: Schema.String,
705
+ note: Schema.optionalKey(Schema.String),
706
+ message: Schema.String,
707
+ }),
708
+ ]));
680
709
  /** Approval results are a host contract, not part of each App's declaration. */
681
710
  function approvalOutput(declared) {
682
711
  return {
683
712
  "~standard": {
684
713
  ...declared["~standard"],
685
- validate: (value) => isPendingApproval(value) || isApprovalRefusal(value)
714
+ validate: (value) => isApprovalResult(value)
686
715
  ? { value }
687
716
  : declared["~standard"].validate(value),
688
717
  },
@@ -159,6 +159,8 @@ function PermissionEditor({ port, appKey, onAccepted, onStateChange, }) {
159
159
  const asked = useRef(null);
160
160
  const describeId = useId();
161
161
  const mounted = useRef(true);
162
+ /** Failures and flow notices are toasts, never text that reflows the form. */
163
+ const toastError = (text) => toast.error(text, { toasterId: describeId, closeButton: true });
162
164
  const retire = useCallback(() => {
163
165
  setRetired(true);
164
166
  setUncertain(false);
@@ -211,7 +213,7 @@ function PermissionEditor({ port, appKey, onAccepted, onStateChange, }) {
211
213
  if (!mounted.current)
212
214
  return;
213
215
  setRefreshNeeded(true);
214
- setMessage("Permissions saved. The surrounding screen could not refresh.");
216
+ toastError("Permissions saved. The surrounding screen could not refresh.");
215
217
  }
216
218
  }
217
219
  async function retryRefresh() {
@@ -248,11 +250,11 @@ function PermissionEditor({ port, appKey, onAccepted, onStateChange, }) {
248
250
  }
249
251
  if (result === "unconfirmed") {
250
252
  setUncertain(true);
251
- setMessage("The change could not be confirmed. Review current permissions before trying again.");
253
+ toastError("The change could not be confirmed. Review current permissions before trying again.");
252
254
  return;
253
255
  }
254
256
  if (result === "refused") {
255
- setMessage("This permission change was refused. No approval was confirmed.");
257
+ toastError("This permission change was refused. No approval was confirmed.");
256
258
  return;
257
259
  }
258
260
  if (result === "accepted") {
@@ -284,13 +286,13 @@ function PermissionEditor({ port, appKey, onAccepted, onStateChange, }) {
284
286
  setView(next);
285
287
  setDraft(rebaseDraft(nextDraft, view.permissions.authority, next.permissions.authority));
286
288
  setUncertain(false);
287
- setMessage("Current permissions loaded. Review your edits before saving again.");
289
+ toast.warning("Current permissions loaded. Review your edits before saving again.", { toasterId: describeId, closeButton: true });
288
290
  }
289
291
  catch (cause) {
290
292
  console.error("App permissions could not be confirmed", cause);
291
293
  if (isMounted()) {
292
294
  setUncertain(true);
293
- setMessage("The change could not be confirmed. Review current permissions before trying again.");
295
+ toastError("The change could not be confirmed. Review current permissions before trying again.");
294
296
  }
295
297
  }
296
298
  finally {
@@ -384,8 +386,7 @@ function PermissionEditor({ port, appKey, onAccepted, onStateChange, }) {
384
386
  ? `${view.appName} asks for`
385
387
  : `${view.appName} permissions`, headings: gridHeadings, rows: first })), later.length > 0 && (_jsx(Disclosure, { open: otherOpen, onOpenChange: setOtherOpen, summary: `Other permissions · ${String(later.length)}`, children: _jsx(PermissionGrid, { caption: "Already decided", headings: gridHeadings, rows: later }) })), _jsx("div", { className: "sr-only", children: groups
386
388
  .flatMap((group) => [...group.columns, ...group.switches])
387
- .map((column) => (_jsxs("p", { id: `${describeId}-${column.capability}`, children: [column.description, column.warning === null ? "" : ` ${column.warning}`] }, column.capability))) }), screen.groups.length === 0 && _jsx("p", { children: "This App requests no permissions." }), message !== null && !showFooter && (_jsx("p", { role: "status", "aria-live": "polite", children: message })), showFooter && (_jsxs(FormFooter, { divider: false, children: [message !== null &&
388
- (saved && !uncertain && !refreshNeeded ? (_jsx(Status, { role: "status", size: "compact", glyph: "dot", tone: "success", label: message })) : (_jsx("span", { role: "status", children: message }))), refreshNeeded && (_jsx(Button, { type: "button", size: "xs", variant: "outline", disabled: saving, onClick: () => void retryRefresh(), children: "Retry screen refresh" })), (changes.length > 0 || saving || uncertain) && (_jsx(Button, { type: "submit", variant: "primary", disabled: saving || retired || !screen.canEdit, children: saving
389
+ .map((column) => (_jsxs("p", { id: `${describeId}-${column.capability}`, children: [column.description, column.warning === null ? "" : ` ${column.warning}`] }, column.capability))) }), screen.groups.length === 0 && _jsx("p", { children: "This App requests no permissions." }), message !== null && !showFooter && (_jsx("p", { role: "status", "aria-live": "polite", children: message })), showFooter && (_jsxs(FormFooter, { divider: false, children: [message !== null && saved && !uncertain && !refreshNeeded && (_jsx(Status, { role: "status", size: "compact", glyph: "dot", tone: "success", label: message })), refreshNeeded && (_jsx(Button, { type: "button", size: "xs", variant: "outline", disabled: saving, onClick: () => void retryRefresh(), children: "Retry screen refresh" })), (changes.length > 0 || saving || uncertain) && (_jsx(Button, { type: "submit", variant: "primary", disabled: saving || retired || !screen.canEdit, children: saving
389
390
  ? "Saving…"
390
391
  : uncertain
391
392
  ? "Review current permissions"
@@ -17,7 +17,6 @@ export declare class ComputerPortsHandle extends RpcTarget implements HandleOf<t
17
17
  readonly port: number;
18
18
  readonly previewUrl: string;
19
19
  readonly openMode: "inline" | "external-only";
20
- readonly expiresAt: number;
21
20
  }[];
22
21
  } | {
23
22
  readonly error: "port_previews_not_configured";
@@ -338,6 +338,7 @@ async function openOysterApp(options, appWindow, opening, navigate) {
338
338
  version: 1,
339
339
  value: {
340
340
  computerId: config.computerId,
341
+ computerName: config.computerName,
341
342
  focus: { editing: false, surface: null },
342
343
  openRequest: options.openRequest ?? null,
343
344
  visibility: "visible",
@@ -8,6 +8,7 @@ export declare const oysterAppConfigSchema: Schema.Struct<{
8
8
  /** The Release declares `apps.open`; only an embedding shell can serve it. */
9
9
  readonly appsOpen: Schema.Boolean;
10
10
  readonly computerId: Schema.NullOr<Schema.String>;
11
+ readonly computerName: Schema.optional<Schema.NullOr<Schema.String>>;
11
12
  readonly authorityVersion: Schema.Int;
12
13
  readonly commands: Schema.$Array<Schema.Codec<Readonly<{
13
14
  id: string;
@@ -10,6 +10,7 @@ export const oysterAppConfigSchema = Schema.Struct({
10
10
  /** The Release declares `apps.open`; only an embedding shell can serve it. */
11
11
  appsOpen: Schema.Boolean,
12
12
  computerId: Schema.NullOr(Schema.String),
13
+ computerName: Schema.optional(Schema.NullOr(Schema.String)),
13
14
  authorityVersion: Schema.Int,
14
15
  commands: Schema.Array(appDeclaredCommandSchema),
15
16
  icon: Schema.NullOr(Schema.String),