@fungi.computer/oyster 0.53.2 → 0.54.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/mcp.d.ts CHANGED
@@ -8,7 +8,7 @@ import { computerStateSchema } from "@fungi.computer/computer/fleet/wire";
8
8
  import type { InvocationContext } from "@fungi.computer/mycelium";
9
9
  import type { ComputerControlPort } from "./computer-control-port.js";
10
10
  export type { ComputerControlPort } from "./computer-control-port.js";
11
- import type { OysterHost } from "./host.js";
11
+ import type { OysterHost, OysterJson } from "./host.js";
12
12
  import type { TenantPrincipal } from "./tenant.js";
13
13
  import { type VerifiedRelease } from "./release.js";
14
14
  /** Captured capabilities and grants offered to one admitted MCP caller. */
@@ -422,6 +422,17 @@ export type ReleaseSurface = Readonly<{
422
422
  export type AppSurfaceCache = (release: Installation["release"]) => Promise<ReleaseSurface | null>;
423
423
  /** Make one {@link AppSurfaceCache} for a host whose artifact store and capabilities stay fixed. */
424
424
  export declare function appSurfaceCache(host: Pick<OysterHost, "artifacts" | "capabilities">): AppSurfaceCache;
425
+ /** The host parts the App door and its snapshot read. */
426
+ export type AppSnapshotHost = Pick<OysterHost, "tenantId" | "installations" | "instances" | "artifacts" | "guestLimits" | "backgroundOriginKey" | "computerId" | "capabilities" | "appToolPolicy" | "keys" | "approvals">;
427
+ /** One host-side call of a hosted extension's wire method. */
428
+ export type OysterExtensionCall = (name: string, input: OysterJson, signal?: AbortSignal) => Promise<OysterJson>;
429
+ /**
430
+ * The host-side door for an attached hosted extension: its wire methods go
431
+ * through the same App door as App tools (staleness, fresh policy, `admits`,
432
+ * the Instance call), and never appear as a model-facing operation. Null when
433
+ * the installation's current Release is not an Agent extension.
434
+ */
435
+ export declare function oysterExtensionDoor(host: AppSnapshotHost, surfaces: AppSurfaceCache, principal: TenantPrincipal, access: OysterCallerAccess, installation: Installation, sessionId: string | null): Promise<OysterExtensionCall | null>;
425
436
  /** Derive the current principal's admitted App modules and grants. */
426
437
  export declare function oysterAppSnapshot(host: Pick<OysterHost, "tenantId" | "installations" | "instances" | "artifacts" | "guestLimits" | "backgroundOriginKey" | "computerId" | "capabilities" | "appToolPolicy" | "keys" | "approvals">, surfaces: AppSurfaceCache, principal: TenantPrincipal, installations: readonly Installation[], access: OysterCallerAccess, sessionId: string | null, mode: "direct" | "approval"): Promise<Readonly<{
427
438
  modules: Readonly<Record<string, ModuleRegistration>>;
package/dist/mcp.js CHANGED
@@ -7,6 +7,7 @@ import { createMcpWorkflowControl, WORKFLOW_CONTROL_MODULE_ID, } from "./workflo
7
7
  import { causeClass } from "./cause-class.js";
8
8
  import { deriveDeclaredOperations } from "./apps/operations.js";
9
9
  import { appToolPolicySchema } from "./apps/tools.js";
10
+ import { isAgentExtensionApi, isAgentExtensionWireMethod, } from "@fungi.computer/agar/backend-definition";
10
11
  import { emptyAppDeclaration } from "@fungi.computer/puffball/app";
11
12
  import { admittedMethodCallerFacts, invocationCallerContext, } from "./invocation.js";
12
13
  import { guestLimits } from "./guest-policy.js";
@@ -275,7 +276,9 @@ export function appSurfaceCache(host) {
275
276
  release,
276
277
  api: release.api,
277
278
  declaredOperations: await deriveDeclaredOperations(installed, release.declaration ?? emptyAppDeclaration, host.capabilities ?? []),
278
- methods: Object.fromEntries(Object.entries(release.api.methods).filter(([, method]) => method.hidden !== true)),
279
+ methods: Object.fromEntries(
280
+ // Hidden methods and the Agent extension protocol are never tools.
281
+ Object.entries(release.api.methods).filter(([name, method]) => method.hidden !== true && !isAgentExtensionWireMethod(name))),
279
282
  };
280
283
  };
281
284
  return (installed) => {
@@ -291,6 +294,121 @@ export function appSurfaceCache(host) {
291
294
  return entry;
292
295
  };
293
296
  }
297
+ /**
298
+ * The one App door every operation of an installation shares (ordinary
299
+ * methods, a tool family's dynamic tools, and a hosted extension's wire
300
+ * methods): the same staleness check, the same owner-approved policy check,
301
+ * the same `admits` gate and the same Instance call.
302
+ */
303
+ const callAdmittedAppMethod = async (door, name, effect, input, signal) => {
304
+ const { host, installation, surface: { release, api, declaredOperations }, principal, captured, caller, limits, sessionId, } = door;
305
+ const { actor } = principal;
306
+ const instanceId = installation.instanceId;
307
+ if (instanceId === null)
308
+ throw new AppMethodRefused("stale_authority");
309
+ const declaration = release.declaration ?? emptyAppDeclaration;
310
+ signal?.throwIfAborted();
311
+ const currentInstallation = await host.installations.get(installation.installationId);
312
+ signal?.throwIfAborted();
313
+ if (currentInstallation?.status !== "enabled" ||
314
+ currentInstallation.instanceId !== instanceId ||
315
+ currentInstallation.authority.authorityVersion !==
316
+ installation.authority.authorityVersion ||
317
+ currentInstallation.release.releaseId !== installation.release.releaseId ||
318
+ currentInstallation.release.artifact.artifactDigest !==
319
+ installation.release.artifact.artifactDigest)
320
+ throw new AppMethodRefused("stale_authority");
321
+ if (actor.kind === "agent" || actor.kind === "team-key") {
322
+ const fresh = Schema.decodeUnknownOption(appToolPolicySchema, {
323
+ onExcessProperty: "error",
324
+ })(await freshAccessFor(host, actor, installation.installationId));
325
+ const capturedParsed = Schema.decodeUnknownOption(appToolPolicySchema, {
326
+ onExcessProperty: "error",
327
+ })(captured);
328
+ // A call never pre-approved in the first place (no captured
329
+ // policy) is `not_approved`; one that WAS approved but whose
330
+ // authority has since changed or vanished entirely -- a key
331
+ // revoked or expired after capture, say -- is `stale_authority`,
332
+ // just like the other authority drift below. Only the absence
333
+ // of a captured policy gets the former code.
334
+ if (capturedParsed._tag === "None")
335
+ throw new AppMethodRefused("not_approved");
336
+ if (fresh._tag === "None" ||
337
+ fresh.value.revision !== capturedParsed.value.revision ||
338
+ fresh.value.grantedBy !== capturedParsed.value.grantedBy ||
339
+ fresh.value.level !== capturedParsed.value.level)
340
+ throw new AppMethodRefused("stale_authority");
341
+ }
342
+ signal?.throwIfAborted();
343
+ const json = Schema.decodeUnknownSync(Schema.Json)(input);
344
+ const decision = admits({
345
+ installation: {
346
+ status: installation.status,
347
+ instanceId: installation.instanceId,
348
+ authority: installation.authority,
349
+ artifactDigest: installation.release.artifact.artifactDigest,
350
+ },
351
+ declaration,
352
+ declaredOperations,
353
+ api,
354
+ principal: {
355
+ actor,
356
+ role: "role" in principal ? principal.role : null,
357
+ },
358
+ access: captured === null
359
+ ? null
360
+ : {
361
+ level: captured.level,
362
+ revision: captured.revision,
363
+ grantedBy: captured.grantedBy,
364
+ bindingName: appBindingName(installation.installationId),
365
+ },
366
+ }, { kind: "method", name, input: json, via: "mcp" });
367
+ if (decision.kind === "refused")
368
+ throw new AppMethodRefused(decision.code);
369
+ const result = await host.instances.get(instanceId, limits).call(await admittedMethodCallerFacts(host, installation, release, caller, decision.grants, { name, effect }, [], sessionId ?? undefined, actor.kind === "agent" && captured !== null
370
+ ? {
371
+ policyRevision: captured.revision,
372
+ grantorMemberId: captured.grantedBy,
373
+ }
374
+ : undefined), api, name, json);
375
+ if (!result.ok)
376
+ throw new AppMethodRefused(result.code);
377
+ if (result.value.kind === "refused")
378
+ throw new AppMethodRefused(result.value.code, result.value.message);
379
+ return result.value.value;
380
+ };
381
+ /**
382
+ * The host-side door for an attached hosted extension: its wire methods go
383
+ * through the same App door as App tools (staleness, fresh policy, `admits`,
384
+ * the Instance call), and never appear as a model-facing operation. Null when
385
+ * the installation's current Release is not an Agent extension.
386
+ */
387
+ export async function oysterExtensionDoor(host, surfaces, principal, access, installation, sessionId) {
388
+ if (installation.status !== "enabled" || installation.instanceId === null)
389
+ return null;
390
+ const surface = await surfaces(installation.release);
391
+ if (surface === null || !isAgentExtensionApi(surface.api))
392
+ return null;
393
+ const door = {
394
+ host,
395
+ installation,
396
+ surface,
397
+ principal,
398
+ captured: capturedAccessFor(access, installation.installationId),
399
+ caller: invocationCallerContext(principal, host.computerId ?? null, host.tenantId),
400
+ limits: guestLimits(host.guestLimits),
401
+ sessionId,
402
+ };
403
+ return (name, input, signal) => {
404
+ const method = isAgentExtensionWireMethod(name)
405
+ ? surface.api.methods[name]
406
+ : undefined;
407
+ if (method === undefined)
408
+ return Promise.reject(new AppMethodRefused("not_declared"));
409
+ return callAdmittedAppMethod(door, name, method.effect, input, signal);
410
+ };
411
+ }
294
412
  /** Derive the current principal's admitted App modules and grants. */
295
413
  export async function oysterAppSnapshot(host, surfaces, principal, installations, access, sessionId, mode) {
296
414
  const limits = guestLimits(host.guestLimits);
@@ -314,9 +432,7 @@ export async function oysterAppSnapshot(host, surfaces, principal, installations
314
432
  const surface = await surfaces(installation.release);
315
433
  if (surface === null)
316
434
  continue;
317
- const { release, api, declaredOperations, methods } = surface;
318
- const instanceId = installation.instanceId;
319
- const declaration = release.declaration ?? emptyAppDeclaration;
435
+ const { release, api, methods } = surface;
320
436
  const id = `oyster-app:${installation.installationId}`;
321
437
  // A member/owner, or an Agent/key with no captured access, defaults to
322
438
  // "write" here exactly as every module always did before: the deeper gate
@@ -329,79 +445,17 @@ export async function oysterAppSnapshot(host, surfaces, principal, installations
329
445
  // check, the same owner-approved policy check, the same `admits` gate and
330
446
  // the same Instance call. A tool family tool is sugar over this same
331
447
  // admitted call to its declared `call` method; it gets no separate check.
332
- const callAppMethod = async (name, effect, input, signal) => {
333
- signal?.throwIfAborted();
334
- const currentInstallation = await host.installations.get(installation.installationId);
335
- signal?.throwIfAborted();
336
- if (currentInstallation?.status !== "enabled" ||
337
- currentInstallation.instanceId !== instanceId ||
338
- currentInstallation.authority.authorityVersion !==
339
- installation.authority.authorityVersion ||
340
- currentInstallation.release.releaseId !==
341
- installation.release.releaseId ||
342
- currentInstallation.release.artifact.artifactDigest !==
343
- installation.release.artifact.artifactDigest)
344
- throw new AppMethodRefused("stale_authority");
345
- if (actor.kind === "agent" || actor.kind === "team-key") {
346
- const fresh = Schema.decodeUnknownOption(appToolPolicySchema, {
347
- onExcessProperty: "error",
348
- })(await freshAccessFor(host, actor, installation.installationId));
349
- const capturedParsed = Schema.decodeUnknownOption(appToolPolicySchema, {
350
- onExcessProperty: "error",
351
- })(captured);
352
- // A call never pre-approved in the first place (no captured
353
- // policy) is `not_approved`; one that WAS approved but whose
354
- // authority has since changed or vanished entirely -- a key
355
- // revoked or expired after capture, say -- is `stale_authority`,
356
- // just like the other authority drift below. Only the absence
357
- // of a captured policy gets the former code.
358
- if (capturedParsed._tag === "None")
359
- throw new AppMethodRefused("not_approved");
360
- if (fresh._tag === "None" ||
361
- fresh.value.revision !== capturedParsed.value.revision ||
362
- fresh.value.grantedBy !== capturedParsed.value.grantedBy ||
363
- fresh.value.level !== capturedParsed.value.level)
364
- throw new AppMethodRefused("stale_authority");
365
- }
366
- signal?.throwIfAborted();
367
- const json = Schema.decodeUnknownSync(Schema.Json)(input);
368
- const decision = admits({
369
- installation: {
370
- status: installation.status,
371
- instanceId: installation.instanceId,
372
- authority: installation.authority,
373
- artifactDigest: installation.release.artifact.artifactDigest,
374
- },
375
- declaration,
376
- declaredOperations,
377
- api,
378
- principal: {
379
- actor,
380
- role: "role" in principal ? principal.role : null,
381
- },
382
- access: captured === null
383
- ? null
384
- : {
385
- level: captured.level,
386
- revision: captured.revision,
387
- grantedBy: captured.grantedBy,
388
- bindingName: appBindingName(installation.installationId),
389
- },
390
- }, { kind: "method", name, input: json, via: "mcp" });
391
- if (decision.kind === "refused")
392
- throw new AppMethodRefused(decision.code);
393
- const result = await host.instances.get(instanceId, limits).call(await admittedMethodCallerFacts(host, installation, release, caller, decision.grants, { name, effect }, [], sessionId ?? undefined, actor.kind === "agent" && captured !== null
394
- ? {
395
- policyRevision: captured.revision,
396
- grantorMemberId: captured.grantedBy,
397
- }
398
- : undefined), api, name, json);
399
- if (!result.ok)
400
- throw new AppMethodRefused(result.code);
401
- if (result.value.kind === "refused")
402
- throw new AppMethodRefused(result.value.code, result.value.message);
403
- return result.value.value;
448
+ const door = {
449
+ host,
450
+ installation,
451
+ surface,
452
+ principal,
453
+ captured,
454
+ caller,
455
+ limits,
456
+ sessionId,
404
457
  };
458
+ const callAppMethod = (name, effect, input, signal) => callAdmittedAppMethod(door, name, effect, input, signal);
405
459
  const operationEffects = {};
406
460
  effects[id] = operationEffects;
407
461
  let familyFacts = null;