@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/agents.d.ts +19 -0
- package/dist/agents.js +34 -0
- package/dist/embed-scripts.js +1 -1
- package/dist/mcp.d.ts +12 -1
- package/dist/mcp.js +130 -76
- package/dist/page-script.js +3 -3
- package/dist/standalone/agent-extension-attachments.d.ts +25 -0
- package/dist/standalone/agent-extension-attachments.js +35 -0
- package/dist/standalone/agents.d.ts +41 -0
- package/dist/standalone/agents.js +183 -1
- package/docs/api/README.md +13 -0
- package/docs/api/agents.md +19 -0
- package/docs/api/mcp.md +80 -0
- package/docs/api/workers-git.md +7 -7
- package/package.json +7 -7
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(
|
|
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,
|
|
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
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
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;
|