@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
@@ -7,6 +7,7 @@ import { hostActorSchema } from "@fungi.computer/puffball/app-method-runtime";
7
7
  import { installationIdSchema, installationSchema, isCommittedInstallation, ownerCodec, } from "./apps/installation.js";
8
8
  import { instanceIds, instanceIdSchema } from "./instance-id.js";
9
9
  import { tenantIdSchema, tenantScope } from "./tenant.js";
10
+ import { failureDiagnostic } from "./cause-class.js";
10
11
  import { uiBootCheckOutcomeSchema, } from "./boot-gate.js";
11
12
  // Request identity has Watchdog's public job-key bound; it is not a retry cap.
12
13
  export const installationRequestIdSchema = z.string().min(1).max(256);
@@ -132,6 +133,18 @@ const storedCommandSchema = z.union([
132
133
  const inputDigest = (input) => createHash("sha256")
133
134
  .update(JSON.stringify(installationAdmissionSchema.parse(input)))
134
135
  .digest("hex");
136
+ /**
137
+ * One owner wait's bound, under ordinary HTTP idle timeouts; an observer that
138
+ * needs longer simply waits again.
139
+ */
140
+ export const maxSettlementWaitMs = 25_000;
141
+ /** The status door's optional `waitMs` query: whole milliseconds, bounded. */
142
+ export const installationWaitQuerySchema = z
143
+ .string()
144
+ .regex(/^\d{1,5}$/u)
145
+ .transform(Number)
146
+ .pipe(z.number().int().max(maxSettlementWaitMs))
147
+ .optional();
135
148
  const installationOperationRequestSchema = z.discriminatedUnion("action", [
136
149
  z.strictObject({
137
150
  action: z.literal("admit"),
@@ -144,6 +157,13 @@ const installationOperationRequestSchema = z.discriminatedUnion("action", [
144
157
  requestId: installationRequestIdSchema,
145
158
  installationId: installationIdSchema,
146
159
  }),
160
+ z.strictObject({
161
+ action: z.literal("await"),
162
+ scope: scopeSchema,
163
+ requestId: installationRequestIdSchema,
164
+ installationId: installationIdSchema,
165
+ waitMs: z.number().int().min(0).max(maxSettlementWaitMs),
166
+ }),
147
167
  z.strictObject({
148
168
  action: z.literal("load"),
149
169
  scope: scopeSchema,
@@ -228,6 +248,18 @@ export function installationOperationsPort(send, scope) {
228
248
  throw new InstallationOperationError("unavailable");
229
249
  return reply.operation;
230
250
  },
251
+ async awaitSettled(requestId, installationId, waitMs) {
252
+ const reply = await call({
253
+ action: "await",
254
+ scope,
255
+ requestId,
256
+ installationId,
257
+ waitMs,
258
+ });
259
+ if (reply.kind !== "operation")
260
+ throw new InstallationOperationError("unavailable");
261
+ return reply.operation;
262
+ },
231
263
  async load(requestId) {
232
264
  const reply = await call({ action: "load", scope, requestId });
233
265
  if (reply.kind !== "command")
@@ -403,6 +435,19 @@ export async function createInstallationOperations(ports) {
403
435
  ? null
404
436
  : readStored(installationOutcomeSchema, encoded);
405
437
  };
438
+ // Callers waiting for one command to leave pending (or to be admitted). The
439
+ // settlement is projected inside Watchdog's transaction, so waiters are woken
440
+ // only after the tick that ran it has returned, and re-read committed state.
441
+ const waiters = new Map();
442
+ const settledInTick = new Set();
443
+ const wake = (requestId) => {
444
+ const waiting = waiters.get(requestId);
445
+ if (waiting === undefined)
446
+ return;
447
+ waiters.delete(requestId);
448
+ for (const resume of waiting)
449
+ resume();
450
+ };
406
451
  const watchdog = await Watchdog.make({
407
452
  owner,
408
453
  isAlive: () => Promise.resolve(false),
@@ -420,15 +465,23 @@ export async function createInstallationOperations(ports) {
420
465
  ports.generation() === command.generation &&
421
466
  same(ports.get(command.installationId), proposed.installation)) ||
422
467
  (proposed?.state === "refused" && settled.outcome === "failed");
468
+ const stopped = settled.outcome === "interrupted" || settled.outcome === "cancelled";
469
+ // The commit marks the plan prepared in this owner before its
470
+ // compare-and-put, and a settled command can never commit later. An
471
+ // unprepared plan whose target is not the current row therefore proves
472
+ // this request changed nothing: the previous release is still selected.
473
+ const neverCommitted = !stopped &&
474
+ command.plan?.prepared !== true &&
475
+ (command.plan === null ||
476
+ !same(ports.get(command.installationId), command.plan.installation));
423
477
  const result = definitive
424
478
  ? proposed
425
- : {
426
- state: "unconfirmed",
427
- outcome: settled.outcome === "interrupted" ||
428
- settled.outcome === "cancelled"
429
- ? settled.outcome
430
- : "outcome_unknown",
431
- };
479
+ : neverCommitted
480
+ ? { state: "refused", status: 503, code: "installation_not_applied" }
481
+ : {
482
+ state: "unconfirmed",
483
+ outcome: stopped ? settled.outcome : "outcome_unknown",
484
+ };
432
485
  const operation = terminalOperationSchema.parse(result.state === "succeeded"
433
486
  ? {
434
487
  ...command.operation,
@@ -453,6 +506,7 @@ export async function createInstallationOperations(ports) {
453
506
  operation,
454
507
  });
455
508
  owner.sql.exec("UPDATE installation_commands SET provisional_outcome=NULL WHERE request_id=?", payload);
509
+ settledInTick.add(payload);
456
510
  },
457
511
  execute: async (job) => {
458
512
  const command = load(installationRequestIdSchema.parse(job.payload));
@@ -460,7 +514,19 @@ export async function createInstallationOperations(ports) {
460
514
  return { kind: "outcome_unknown" };
461
515
  // Persist the wake handoff before awaiting work in another execution context.
462
516
  await ports.scheduleWake(Date.now());
463
- const result = installationOutcomeSchema.parse(await ports.execute(command));
517
+ let executed;
518
+ try {
519
+ executed = await ports.execute(command);
520
+ }
521
+ catch (cause) {
522
+ // Watchdog keeps only a closed failure reason; keep the cause here.
523
+ console.error("Installation execution failed", {
524
+ requestId: command.admission.requestId,
525
+ ...failureDiagnostic(cause),
526
+ });
527
+ throw cause;
528
+ }
529
+ const result = installationOutcomeSchema.parse(executed);
464
530
  const latest = load(command.admission.requestId);
465
531
  if (latest === null || !("admission" in latest))
466
532
  throw new InstallationOperationError("stale_authority");
@@ -489,6 +555,16 @@ export async function createInstallationOperations(ports) {
489
555
  throw new InstallationOperationError("stale_authority");
490
556
  return command;
491
557
  };
558
+ /** The caller's operation, when it names this installation in its scope. */
559
+ const observed = (request) => {
560
+ const command = load(request.requestId);
561
+ return command !== null &&
562
+ same(command.scope, request.scope) &&
563
+ (command.operation.installationId === request.installationId ||
564
+ command.operation.requestedInstallationId === request.installationId)
565
+ ? operationOf(command)
566
+ : null;
567
+ };
492
568
  const dispatch = async (raw) => {
493
569
  const request = installationOperationRequestSchema.parse(raw);
494
570
  const scope = tenantScope(request.scope.tenantId, request.scope.origin);
@@ -501,7 +577,7 @@ export async function createInstallationOperations(ports) {
501
577
  // An orphan wake is harmless; an accepted row with no wake is not.
502
578
  // No external await separates this persisted wake from atomic admission.
503
579
  await ports.scheduleWake(Date.now());
504
- return owner.transactionSync(() => {
580
+ const admitted = owner.transactionSync(() => {
505
581
  const prior = load(request.input.requestId);
506
582
  if (prior !== null) {
507
583
  if (("admission" in prior
@@ -560,24 +636,41 @@ export async function createInstallationOperations(ports) {
560
636
  });
561
637
  return { kind: "operation", operation };
562
638
  });
639
+ // A waiter whose admission acknowledgement was lost learns of it now.
640
+ wake(request.input.requestId);
641
+ return admitted;
563
642
  }
564
- if (request.action === "read" || request.action === "load") {
643
+ if (request.action === "load") {
565
644
  const command = load(request.requestId);
566
- const admitted = command !== null && same(command.scope, request.scope) ? command : null;
567
- return request.action === "load"
568
- ? {
569
- kind: "command",
570
- command: admitted !== null && "admission" in admitted ? admitted : null,
571
- }
572
- : {
573
- kind: "operation",
574
- operation: admitted !== null &&
575
- (admitted.operation.installationId === request.installationId ||
576
- admitted.operation.requestedInstallationId ===
577
- request.installationId)
578
- ? operationOf(admitted)
579
- : null,
645
+ return {
646
+ kind: "command",
647
+ command: command !== null &&
648
+ same(command.scope, request.scope) &&
649
+ "admission" in command
650
+ ? command
651
+ : null,
652
+ };
653
+ }
654
+ if (request.action === "read")
655
+ return { kind: "operation", operation: observed(request) };
656
+ if (request.action === "await") {
657
+ const current = observed(request);
658
+ if (current !== null && current.state !== "pending")
659
+ return { kind: "operation", operation: current };
660
+ await new Promise((resolve) => {
661
+ const waiting = waiters.get(request.requestId) ?? new Set();
662
+ const resume = () => {
663
+ clearTimeout(timer);
664
+ waiting.delete(resume);
665
+ if (waiting.size === 0 && waiters.get(request.requestId) === waiting)
666
+ waiters.delete(request.requestId);
667
+ resolve();
580
668
  };
669
+ const timer = setTimeout(resume, request.waitMs);
670
+ waiting.add(resume);
671
+ waiters.set(request.requestId, waiting);
672
+ });
673
+ return { kind: "operation", operation: observed(request) };
581
674
  }
582
675
  const command = requireCommand(request.requestId, request.scope);
583
676
  if (request.action === "plan") {
@@ -647,6 +740,11 @@ export async function createInstallationOperations(ports) {
647
740
  return await watchdog.tick();
648
741
  }
649
742
  finally {
743
+ // After the tick, never inside its transaction. A rolled-back
744
+ // settlement wakes a waiter that re-reads pending and waits again.
745
+ for (const requestId of settledInTick)
746
+ wake(requestId);
747
+ settledInTick.clear();
650
748
  if (await watchdog.hasPendingWork())
651
749
  await ports.scheduleWake(Date.now());
652
750
  else {
@@ -1,9 +1,11 @@
1
1
  import type { AppInstanceErrorCode } from "./index.js";
2
2
  /** The retained HTTP meaning of a known Instance refusal, never generic failed. */
3
3
  export declare function instanceRefusalStatus(code: AppInstanceErrorCode): number;
4
- /** Only closed host-authored boot reasons produce a caller-facing message. */
4
+ /** The host-authored settlement for an installation that changed nothing. */
5
+ export declare const installationNotAppliedMessage = "The new release was not applied: Oyster could not prepare it. The previous release is still installed; install again to retry.";
6
+ /** Only closed host-authored reasons produce a caller-facing message. */
5
7
  export declare function instanceRefusalBody(code: string): {
6
- error: "backend_load_failed" | "backend_construction_failed" | "ui_mount_failed" | "boot_runner_unavailable" | "boot_browser_binding_missing" | "boot_clone_unavailable" | "boot_timeout" | "boot_cleanup_failed";
8
+ error: string;
7
9
  message: string;
8
10
  } | {
9
11
  error: string;
@@ -12,8 +12,12 @@ export function instanceRefusalStatus(code) {
12
12
  return 422;
13
13
  return conflicts.has(code) ? 409 : 403;
14
14
  }
15
- /** Only closed host-authored boot reasons produce a caller-facing message. */
15
+ /** The host-authored settlement for an installation that changed nothing. */
16
+ export const installationNotAppliedMessage = "The new release was not applied: Oyster could not prepare it. The previous release is still installed; install again to retry.";
17
+ /** Only closed host-authored reasons produce a caller-facing message. */
16
18
  export function instanceRefusalBody(code) {
19
+ if (code === "installation_not_applied")
20
+ return { error: code, message: installationNotAppliedMessage };
17
21
  const boot = bootFailureSchema.safeParse(code);
18
22
  return boot.success
19
23
  ? { error: boot.data, message: new BootGateError(boot.data).message }
package/dist/mcp.d.ts CHANGED
@@ -3,6 +3,7 @@ import { type AppToolPolicy } from "./apps/tools.js";
3
3
  import type { DeclaredOperations, Installation } from "./apps/installation.js";
4
4
  import { type CapabilitySource, type Grants, type ModuleRegistration } from "@fungi.computer/mycelium";
5
5
  import { computerPageSchema } from "@fungi.computer/computer/fleet/inventory-wire";
6
+ import { localBackendDetachSchema } from "@fungi.computer/computer/fleet/wire";
6
7
  import type { InvocationContext } from "@fungi.computer/mycelium";
7
8
  import type { ComputerControlPort } from "./computer-control-port.js";
8
9
  export type { ComputerControlPort } from "./computer-control-port.js";
@@ -25,6 +26,57 @@ declare const fleetCreate: z.ZodObject<{
25
26
  name: z.ZodDefault<z.ZodNullable<z.ZodString>>;
26
27
  requestId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
27
28
  }, z.core.$strict>;
29
+ declare const fleetBackends: z.ZodObject<{
30
+ backends: z.ZodArray<z.ZodObject<{
31
+ id: z.ZodString;
32
+ kind: z.ZodEnum<{
33
+ "platform-container": "platform-container";
34
+ "on-box-vm": "on-box-vm";
35
+ local: "local";
36
+ }>;
37
+ status: z.ZodEnum<{
38
+ ready: "ready";
39
+ online: "online";
40
+ offline: "offline";
41
+ queued: "queued";
42
+ }>;
43
+ queuePosition: z.ZodNullable<z.ZodNumber>;
44
+ hostId: z.ZodNullable<z.ZodString>;
45
+ hostLabel: z.ZodNullable<z.ZodString>;
46
+ folderLabel: z.ZodNullable<z.ZodString>;
47
+ detachable: z.ZodBoolean;
48
+ }, z.core.$strict>>;
49
+ }, z.core.$strict>;
50
+ declare const fleetAttachInput: z.ZodObject<{
51
+ computerId: z.ZodString;
52
+ publicKey: z.ZodBase64;
53
+ hostLabel: z.ZodLazy<z.ZodString>;
54
+ folderLabel: z.ZodLazy<z.ZodString>;
55
+ requestId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
56
+ }, z.core.$strict>;
57
+ declare const fleetAttachment: z.ZodDiscriminatedUnion<[z.ZodObject<{
58
+ kind: z.ZodLiteral<"attached">;
59
+ requestId: z.ZodString;
60
+ backendId: z.ZodString;
61
+ }, z.core.$strict>, z.ZodObject<{
62
+ kind: z.ZodEnum<{
63
+ invalid: "invalid";
64
+ denied: "denied";
65
+ uncertain: "uncertain";
66
+ conflict: "conflict";
67
+ }>;
68
+ requestId: z.ZodString;
69
+ }, z.core.$strict>], "kind">;
70
+ declare const fleetDetachment: z.ZodDiscriminatedUnion<[z.ZodObject<{
71
+ kind: z.ZodLiteral<"detached">;
72
+ detached: z.ZodBoolean;
73
+ }, z.core.$strict>, z.ZodObject<{
74
+ kind: z.ZodEnum<{
75
+ invalid: "invalid";
76
+ denied: "denied";
77
+ uncertain: "uncertain";
78
+ }>;
79
+ }, z.core.$strict>], "kind">;
28
80
  declare const fleetCreation: z.ZodDiscriminatedUnion<[z.ZodObject<{
29
81
  kind: z.ZodLiteral<"created">;
30
82
  requestId: z.ZodString;
@@ -83,6 +135,7 @@ export declare function computerControlSpecs(port: ComputerControlPort): {
83
135
  running: "running";
84
136
  sleeping: "sleeping";
85
137
  starting: "starting";
138
+ start_failed: "start_failed";
86
139
  }>;
87
140
  }, z.core.$strict>, z.ZodObject<{
88
141
  state: z.ZodLiteral<"queued">;
@@ -90,7 +143,7 @@ export declare function computerControlSpecs(port: ComputerControlPort): {
90
143
  }, z.core.$strict>], "state">;
91
144
  /** Return liveness without waking the runtime. */
92
145
  execute: (input: z.output<typeof fleetComputerId>, context: InvocationContext) => Promise<{
93
- state: "running" | "sleeping" | "starting";
146
+ state: "running" | "sleeping" | "starting" | "start_failed";
94
147
  } | {
95
148
  state: "queued";
96
149
  position: number;
@@ -107,6 +160,7 @@ export declare function computerControlSpecs(port: ComputerControlPort): {
107
160
  running: "running";
108
161
  sleeping: "sleeping";
109
162
  starting: "starting";
163
+ start_failed: "start_failed";
110
164
  }>;
111
165
  }, z.core.$strict>, z.ZodObject<{
112
166
  state: z.ZodLiteral<"queued">;
@@ -114,7 +168,7 @@ export declare function computerControlSpecs(port: ComputerControlPort): {
114
168
  }, z.core.$strict>], "state">;
115
169
  /** Admit and start this Computer. */
116
170
  execute: (input: z.output<typeof fleetComputerId>, context: InvocationContext) => Promise<{
117
- state: "running" | "sleeping" | "starting";
171
+ state: "running" | "sleeping" | "starting" | "start_failed";
118
172
  } | {
119
173
  state: "queued";
120
174
  position: number;
@@ -146,6 +200,82 @@ export declare function computerControlSpecs(port: ComputerControlPort): {
146
200
  /** Mint one identity or preserve the requestId for an uncertain retry. */
147
201
  execute: (input: z.output<typeof fleetCreate>, context: InvocationContext) => Promise<z.output<typeof fleetCreation>>;
148
202
  };
203
+ backends: {
204
+ replay: "safe";
205
+ description: string;
206
+ input: z.ZodObject<{
207
+ computerId: z.ZodString;
208
+ }, z.core.$strict>;
209
+ output: z.ZodObject<{
210
+ backends: z.ZodArray<z.ZodObject<{
211
+ id: z.ZodString;
212
+ kind: z.ZodEnum<{
213
+ "platform-container": "platform-container";
214
+ "on-box-vm": "on-box-vm";
215
+ local: "local";
216
+ }>;
217
+ status: z.ZodEnum<{
218
+ ready: "ready";
219
+ online: "online";
220
+ offline: "offline";
221
+ queued: "queued";
222
+ }>;
223
+ queuePosition: z.ZodNullable<z.ZodNumber>;
224
+ hostId: z.ZodNullable<z.ZodString>;
225
+ hostLabel: z.ZodNullable<z.ZodString>;
226
+ folderLabel: z.ZodNullable<z.ZodString>;
227
+ detachable: z.ZodBoolean;
228
+ }, z.core.$strict>>;
229
+ }, z.core.$strict>;
230
+ /** Return the attached list without waking any backend. */
231
+ execute: (input: z.output<typeof fleetComputerId>, context: InvocationContext) => Promise<z.output<typeof fleetBackends>>;
232
+ };
233
+ attachLocal: {
234
+ replay: "unsafe";
235
+ description: string;
236
+ input: z.ZodObject<{
237
+ computerId: z.ZodString;
238
+ publicKey: z.ZodBase64;
239
+ hostLabel: z.ZodLazy<z.ZodString>;
240
+ folderLabel: z.ZodLazy<z.ZodString>;
241
+ requestId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
242
+ }, z.core.$strict>;
243
+ output: z.ZodDiscriminatedUnion<[z.ZodObject<{
244
+ kind: z.ZodLiteral<"attached">;
245
+ requestId: z.ZodString;
246
+ backendId: z.ZodString;
247
+ }, z.core.$strict>, z.ZodObject<{
248
+ kind: z.ZodEnum<{
249
+ invalid: "invalid";
250
+ denied: "denied";
251
+ uncertain: "uncertain";
252
+ conflict: "conflict";
253
+ }>;
254
+ requestId: z.ZodString;
255
+ }, z.core.$strict>], "kind">;
256
+ /** Mint one identity or preserve the requestId for an uncertain retry. */
257
+ execute: (input: z.output<typeof fleetAttachInput>, context: InvocationContext) => Promise<z.output<typeof fleetAttachment>>;
258
+ };
259
+ detachLocal: {
260
+ replay: "unsafe";
261
+ description: string;
262
+ input: z.ZodLazy<z.ZodObject<{
263
+ computerId: z.ZodString;
264
+ backendId: z.ZodString;
265
+ }, z.core.$strict>>;
266
+ output: z.ZodDiscriminatedUnion<[z.ZodObject<{
267
+ kind: z.ZodLiteral<"detached">;
268
+ detached: z.ZodBoolean;
269
+ }, z.core.$strict>, z.ZodObject<{
270
+ kind: z.ZodEnum<{
271
+ invalid: "invalid";
272
+ denied: "denied";
273
+ uncertain: "uncertain";
274
+ }>;
275
+ }, z.core.$strict>], "kind">;
276
+ /** Close the attachment and its live connection; a gone one settles. */
277
+ execute: (input: z.output<typeof localBackendDetachSchema>, context: InvocationContext) => Promise<z.output<typeof fleetDetachment>>;
278
+ };
149
279
  };
150
280
  /** An installation ID as a guest binding name: `spawn-git` becomes `SPAWN_GIT`. */
151
281
  export declare function appBindingName(installationId: string): string;
package/dist/mcp.js CHANGED
@@ -15,6 +15,7 @@ import { Knapsack } from "@fungi.computer/knapsack";
15
15
  import * as Schema from "effect/Schema";
16
16
  import { defineIdFamily } from "@fungi.computer/cairn/id";
17
17
  import { computerCreateRequestSchema, computerPageSchema, } from "@fungi.computer/computer/fleet/inventory-wire";
18
+ import { computerBackendViewSchema, localBackendAttachSchema, localBackendDetachSchema, } from "@fungi.computer/computer/fleet/wire";
18
19
  import { computerStateSchema } from "@fungi.computer/computer/fleet/wire";
19
20
  import { teamComputerDirectorySchema } from "@fungi.computer/nacre/workbench";
20
21
  import { appToolAccess, authorityOf, hostAuthorityPorts, } from "./authorization.js";
@@ -48,6 +49,31 @@ const fleetComputer = z.strictObject({
48
49
  computerId: z.string(),
49
50
  name: z.string(),
50
51
  });
52
+ const fleetBackends = z.strictObject({
53
+ backends: z.array(computerBackendViewSchema),
54
+ });
55
+ const fleetAttachInput = z.strictObject({
56
+ computerId: localBackendAttachSchema.shape.computerId,
57
+ publicKey: localBackendAttachSchema.shape.publicKey,
58
+ hostLabel: localBackendAttachSchema.shape.hostLabel,
59
+ folderLabel: localBackendAttachSchema.shape.folderLabel,
60
+ requestId: localBackendAttachSchema.shape.requestId.nullable().default(null),
61
+ });
62
+ const fleetAttachment = z.discriminatedUnion("kind", [
63
+ z.strictObject({
64
+ kind: z.literal("attached"),
65
+ requestId: z.string(),
66
+ backendId: z.string(),
67
+ }),
68
+ z.strictObject({
69
+ kind: z.enum(["uncertain", "denied", "conflict", "invalid"]),
70
+ requestId: z.string(),
71
+ }),
72
+ ]);
73
+ const fleetDetachment = z.discriminatedUnion("kind", [
74
+ z.strictObject({ kind: z.literal("detached"), detached: z.boolean() }),
75
+ z.strictObject({ kind: z.enum(["denied", "uncertain", "invalid"]) }),
76
+ ]);
51
77
  const fleetCreation = z.discriminatedUnion("kind", [
52
78
  z.strictObject({
53
79
  kind: z.literal("created"),
@@ -100,6 +126,36 @@ export function computerControlSpecs(port) {
100
126
  return { ...result, requestId };
101
127
  },
102
128
  },
129
+ backends: {
130
+ replay: "safe",
131
+ description: "List one Computer's attached execution backends (platform container, on-box VM, members' machines) with live status.",
132
+ input: fleetComputerId,
133
+ output: fleetBackends,
134
+ /** Return the attached list without waking any backend. */
135
+ execute: async (input, context) => ({
136
+ backends: await port.backends(input.computerId, context),
137
+ }),
138
+ },
139
+ attachLocal: {
140
+ replay: "unsafe",
141
+ description: "Attach this authenticated member's machine to a Computer as an execution backend. Send only the device public key and labels; the folder path and private key stay on the machine. Retry an uncertain outcome with its returned requestId.",
142
+ input: fleetAttachInput,
143
+ output: fleetAttachment,
144
+ /** Mint one identity or preserve the requestId for an uncertain retry. */
145
+ execute: async (input, context) => {
146
+ const requestId = input.requestId ?? fleetIds.request.generate();
147
+ const result = await port.attachLocal({ ...input, requestId }, context);
148
+ return { ...result, requestId };
149
+ },
150
+ },
151
+ detachLocal: {
152
+ replay: "unsafe",
153
+ description: "Detach a machine this member attached from a Computer. Its live connection closes and the Computer keeps its files. Safe to retry.",
154
+ input: localBackendDetachSchema,
155
+ output: fleetDetachment,
156
+ /** Close the attachment and its live connection; a gone one settles. */
157
+ execute: (input, context) => port.detachLocal(input, context),
158
+ },
103
159
  };
104
160
  }
105
161
  /** Mints the requestId a tool family tool sends on the caller's behalf to its
@@ -388,7 +444,10 @@ export async function oysterAppSnapshot(host, surfaces, principal, installations
388
444
  fences[id] = await sha256(new TextEncoder().encode(JSON.stringify({
389
445
  installation,
390
446
  generation,
391
- principal,
447
+ // The canonical caller facts, never the raw principal: a resolver may
448
+ // carry extra registry fields (membershipVersion) that the submit-time
449
+ // principal lacks, which would fence a legitimate approval.
450
+ caller,
392
451
  access: captured,
393
452
  api,
394
453
  family: familyFacts,
@@ -552,6 +611,9 @@ export function oysterMcpCatalogLoad(host) {
552
611
  ...fleetSpecs.create,
553
612
  confirm: true,
554
613
  }),
614
+ backends: Mycelium.operation(fleetSpecs.backends),
615
+ attachLocal: Mycelium.operation(fleetSpecs.attachLocal),
616
+ detachLocal: Mycelium.operation(fleetSpecs.detachLocal),
555
617
  },
556
618
  }),
557
619
  ],
@@ -160,7 +160,14 @@ export type OysterAppConnectionOptions = Readonly<{
160
160
  reservedChords: readonly import("@fungi.computer/agar/host").AppHostReservedChord[];
161
161
  theme: string;
162
162
  }>;
163
- /** Connect a child or home App using the same admitted Oyster slot handles. */
163
+ /**
164
+ * Connect a child or home App using the same admitted Oyster slot handles.
165
+ * The host navigates the App's frame (`config.uiUrl`) only once it listens for
166
+ * the App's ready signal, so slow capability resolution on a cold Oyster can
167
+ * never outlast that signal. Opening is bounded: the capabilities and the
168
+ * document get the shared cold-document budget, and the handshake after the
169
+ * document loads gets the App's own ready window.
170
+ */
164
171
  export declare function connectOysterApp(options: OysterAppConnectionOptions): Promise<AppHost>;
165
172
  export { oysterStorageHandle } from "./storage.js";
166
173
  export { appSandbox } from "../app-sandbox.js";
@@ -2,6 +2,7 @@ import { appOpenInputSchema, appsCall, appsOpen, } from "@fungi.computer/agar/ap
2
2
  import { appApiMethodNameSchema } from "@fungi.computer/puffball/app";
3
3
  import { appIdSchema } from "@fungi.computer/puffball/effect";
4
4
  import { createBrowserActionHandler } from "@fungi.computer/nacre";
5
+ import { APP_SURFACE_DOCUMENT_TIMEOUT_MS } from "@fungi.computer/nacre/window-manager";
5
6
  import { createAppSurfaceCommandHost } from "@fungi.computer/nacre/command-host";
6
7
  // App page: mounts one installed App's sandboxed frame and gives it the
7
8
  // capabilities this Oyster host provides. Bundled into `shellScript`.
@@ -251,20 +252,83 @@ export async function mountOysterPage() {
251
252
  },
252
253
  });
253
254
  }
254
- /** Connect a child or home App using the same admitted Oyster slot handles. */
255
+ /** The App's own ready window: once its document loads, it announces itself for 10 s. */
256
+ const APP_CONNECT_TIMEOUT_MS = 10_000;
257
+ /** Resolve `work`, or reject with the signal's reason once it aborts. */
258
+ function untilAborted(work, signal) {
259
+ const stopped = () => signal.reason instanceof Error
260
+ ? signal.reason
261
+ : new Error("App open was stopped", { cause: signal.reason });
262
+ if (signal.aborted)
263
+ return Promise.reject(stopped());
264
+ return new Promise((resolve, reject) => {
265
+ const stop = () => {
266
+ reject(stopped());
267
+ };
268
+ signal.addEventListener("abort", stop, { once: true });
269
+ work.then((value) => {
270
+ signal.removeEventListener("abort", stop);
271
+ resolve(value);
272
+ }, (cause) => {
273
+ signal.removeEventListener("abort", stop);
274
+ reject(cause instanceof Error
275
+ ? cause
276
+ : new Error("App open failed", { cause }));
277
+ });
278
+ });
279
+ }
280
+ /**
281
+ * Connect a child or home App using the same admitted Oyster slot handles.
282
+ * The host navigates the App's frame (`config.uiUrl`) only once it listens for
283
+ * the App's ready signal, so slow capability resolution on a cold Oyster can
284
+ * never outlast that signal. Opening is bounded: the capabilities and the
285
+ * document get the shared cold-document budget, and the handshake after the
286
+ * document loads gets the App's own ready window.
287
+ */
255
288
  export async function connectOysterApp(options) {
256
289
  const { config, frame } = options;
257
290
  if (frame.contentWindow === null)
258
291
  throw new Error("App frame is unavailable");
259
- const capabilities = await oysterAppCapabilities(options);
292
+ const deadline = new AbortController();
293
+ const expire = () => {
294
+ deadline.abort();
295
+ };
296
+ let timer = setTimeout(expire, APP_SURFACE_DOCUMENT_TIMEOUT_MS);
297
+ const opening = AbortSignal.any([options.signal, deadline.signal]);
298
+ const documentLoaded = () => {
299
+ clearTimeout(timer);
300
+ timer = setTimeout(expire, APP_CONNECT_TIMEOUT_MS);
301
+ };
302
+ try {
303
+ return await openOysterApp(options, frame.contentWindow, opening, () => {
304
+ frame.addEventListener("load", documentLoaded, { once: true });
305
+ frame.src = config.uiUrl;
306
+ });
307
+ }
308
+ catch (cause) {
309
+ if (deadline.signal.aborted && !options.signal.aborted)
310
+ throw new AppError("App did not open in time", {
311
+ code: "TIMEOUT",
312
+ retryable: true,
313
+ });
314
+ throw cause;
315
+ }
316
+ finally {
317
+ clearTimeout(timer);
318
+ frame.removeEventListener("load", documentLoaded);
319
+ }
320
+ }
321
+ async function openOysterApp(options, appWindow, opening, navigate) {
322
+ const { config, frame } = options;
323
+ const capabilities = await untilAborted(oysterAppCapabilities(options), opening);
260
324
  const agents = agentDirectory(capabilities);
261
325
  const releaseBrowser = options.agentBrowser.mount(frame, options.agentCommands);
262
326
  options.signal.addEventListener("abort", releaseBrowser, { once: true });
263
- const host = await connectAppHost({
264
- appWindow: frame.contentWindow,
327
+ const connecting = connectAppHost({
328
+ appWindow,
265
329
  expectedAppOrigin: "null",
266
330
  hostWindow: window,
267
- signal: options.signal,
331
+ signal: opening,
268
332
  launch: {
269
333
  identity: {
270
334
  appId: config.appId,
@@ -301,7 +365,9 @@ export async function connectOysterApp(options) {
301
365
  signal: options.signal,
302
366
  }),
303
367
  },
304
- }).catch((cause) => {
368
+ });
369
+ navigate();
370
+ const host = await connecting.catch((cause) => {
305
371
  releaseBrowser();
306
372
  throw cause;
307
373
  });