@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
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which hosted extensions the owner attached to each Agent. The row is the
|
|
3
|
+
* extension consent: an Agent's blanket App-tool approval never asks an
|
|
4
|
+
* extension by itself. Each row pins the installation's Instance, so a
|
|
5
|
+
* removed or replaced installation reads as unattached, and its grantor's
|
|
6
|
+
* membership version, so a membership change revokes it. A store opened
|
|
7
|
+
* from before this table existed simply has no attachments.
|
|
8
|
+
*/
|
|
9
|
+
import type { WatchdogSqliteOwner } from "@fungi.computer/watchdog";
|
|
10
|
+
/** One owner-attached hosted extension of an Agent, as stored. */
|
|
11
|
+
export type AgentExtensionAttachment = Readonly<{
|
|
12
|
+
installationId: string;
|
|
13
|
+
instanceId: string;
|
|
14
|
+
attachedBy: string;
|
|
15
|
+
membershipVersion: number;
|
|
16
|
+
}>;
|
|
17
|
+
export type AgentExtensionAttachments = Readonly<{
|
|
18
|
+
/** Attach or re-attach; the latest owner and Instance replace the row. */
|
|
19
|
+
attach: (agentId: string, attachment: AgentExtensionAttachment) => void;
|
|
20
|
+
/** Whether a row was removed. */
|
|
21
|
+
detach: (agentId: string, installationId: string) => boolean;
|
|
22
|
+
list: (agentId: string) => readonly AgentExtensionAttachment[];
|
|
23
|
+
}>;
|
|
24
|
+
/** Open the attachment table in the Agent directory's own SQLite. */
|
|
25
|
+
export declare function createAgentExtensionAttachments(sql: WatchdogSqliteOwner["sql"]): AgentExtensionAttachments;
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
const storedAttachmentSchema = z.strictObject({
|
|
3
|
+
installation_id: z.string().min(1),
|
|
4
|
+
instance_id: z.string().min(1),
|
|
5
|
+
attached_by: z.string().min(1),
|
|
6
|
+
membership_version: z.number().int().positive(),
|
|
7
|
+
});
|
|
8
|
+
/** Open the attachment table in the Agent directory's own SQLite. */
|
|
9
|
+
export function createAgentExtensionAttachments(sql) {
|
|
10
|
+
sql.exec("CREATE TABLE IF NOT EXISTS agent_extension_attachments (agent_id TEXT NOT NULL, installation_id TEXT NOT NULL, instance_id TEXT NOT NULL, attached_by TEXT NOT NULL, membership_version INTEGER NOT NULL, PRIMARY KEY (agent_id, installation_id)) STRICT");
|
|
11
|
+
return {
|
|
12
|
+
attach(agentId, attachment) {
|
|
13
|
+
sql.exec("INSERT INTO agent_extension_attachments(agent_id, installation_id, instance_id, attached_by, membership_version) VALUES(?, ?, ?, ?, ?) ON CONFLICT(agent_id, installation_id) DO UPDATE SET instance_id = excluded.instance_id, attached_by = excluded.attached_by, membership_version = excluded.membership_version", agentId, attachment.installationId, attachment.instanceId, attachment.attachedBy, attachment.membershipVersion);
|
|
14
|
+
},
|
|
15
|
+
detach(agentId, installationId) {
|
|
16
|
+
return (sql
|
|
17
|
+
.exec("DELETE FROM agent_extension_attachments WHERE agent_id = ? AND installation_id = ? RETURNING installation_id", agentId, installationId)
|
|
18
|
+
.toArray().length > 0);
|
|
19
|
+
},
|
|
20
|
+
list(agentId) {
|
|
21
|
+
return sql
|
|
22
|
+
.exec("SELECT installation_id, instance_id, attached_by, membership_version FROM agent_extension_attachments WHERE agent_id = ? ORDER BY installation_id", agentId)
|
|
23
|
+
.toArray()
|
|
24
|
+
.map((row) => {
|
|
25
|
+
const stored = storedAttachmentSchema.parse(row);
|
|
26
|
+
return {
|
|
27
|
+
installationId: stored.installation_id,
|
|
28
|
+
instanceId: stored.instance_id,
|
|
29
|
+
attachedBy: stored.attached_by,
|
|
30
|
+
membershipVersion: stored.membership_version,
|
|
31
|
+
};
|
|
32
|
+
});
|
|
33
|
+
},
|
|
34
|
+
};
|
|
35
|
+
}
|
|
@@ -295,6 +295,15 @@ export declare abstract class StandaloneAgentBase<Env extends StandaloneAgentEnv
|
|
|
295
295
|
settlement(principal: MachineAgentSettlementPrincipal, sessionId: string, commandId: string): Promise<string | undefined>;
|
|
296
296
|
/** The root host for this Agent's pinned policy directory; unpinned Agents have no App tools. */
|
|
297
297
|
private appHost;
|
|
298
|
+
/**
|
|
299
|
+
* The installation an owner may attach as this Agent's hosted extension:
|
|
300
|
+
* enabled, running, and its current Release declares the whole method
|
|
301
|
+
* family. Its Instance pins the attachment.
|
|
302
|
+
*/
|
|
303
|
+
extensionInstallation(installationId: string): Promise<Readonly<{
|
|
304
|
+
installationId: string;
|
|
305
|
+
instanceId: string;
|
|
306
|
+
}> | null>;
|
|
298
307
|
/** The instance directory that owns this Agent's sealed model keys. */
|
|
299
308
|
private keyDirectory;
|
|
300
309
|
/** The instance directory that owns this Agent's MCP connections and their credentials. */
|
|
@@ -360,6 +369,14 @@ export declare abstract class StandaloneAgentBase<Env extends StandaloneAgentEnv
|
|
|
360
369
|
private readonly mcpInvalidations;
|
|
361
370
|
/** Host-only: the directory told us this Agent's connections changed. */
|
|
362
371
|
invalidateMcpConnections(): void;
|
|
372
|
+
/**
|
|
373
|
+
* The hosted extensions the owner attached to this Agent, under the shared
|
|
374
|
+
* composer. Both consents are required: the owner's attachment and the
|
|
375
|
+
* Agent's current App-tool approval, whose level also decides whether the
|
|
376
|
+
* extension's tools reach the run. A denied visitor Session asks nothing.
|
|
377
|
+
* Every guest call goes through the same App door as App tools.
|
|
378
|
+
*/
|
|
379
|
+
private hostedExtensions;
|
|
363
380
|
/**
|
|
364
381
|
* A full override must retain channelSource and channelInstructions:
|
|
365
382
|
* dropping them removes a suspended website's run refusal and turn capture,
|
|
@@ -530,6 +547,7 @@ export declare class AgentDirectory extends DurableObject<StandaloneAgentEnv> {
|
|
|
530
547
|
private readonly computerNames;
|
|
531
548
|
private readonly directory;
|
|
532
549
|
private readonly avatars;
|
|
550
|
+
private readonly extensionAttachments;
|
|
533
551
|
private composedTenancy;
|
|
534
552
|
private machineEnrollmentOwner;
|
|
535
553
|
private machineFencesOwner;
|
|
@@ -683,6 +701,29 @@ export declare class AgentDirectory extends DurableObject<StandaloneAgentEnv> {
|
|
|
683
701
|
}>, tenantId?: TenantId): Promise<AppToolPolicy | null>;
|
|
684
702
|
/** Only direct human approval records an authenticated canonical grantor. */
|
|
685
703
|
approveAppToolPolicy(agentId: string, principal: TenantPrincipal, level: AppToolPolicy["level"], expectedRevision: string | null, actor: AgentPolicyActor, tenantId: TenantId): Promise<Awaited<ReturnType<OysterAgents["approveAppToolPolicy"]>>>;
|
|
704
|
+
/**
|
|
705
|
+
* Attach one hosted extension to an Agent. Only a current owner attaches;
|
|
706
|
+
* the row records that owner and membership version, and the Instance the
|
|
707
|
+
* caller found for an enabled extension installation.
|
|
708
|
+
*/
|
|
709
|
+
attachExtension(agentId: string, target: Readonly<{
|
|
710
|
+
installationId: string;
|
|
711
|
+
instanceId: string;
|
|
712
|
+
}>, principal: TenantPrincipal, tenantId: TenantId): Promise<Readonly<{
|
|
713
|
+
installationId: string;
|
|
714
|
+
attachedBy: string;
|
|
715
|
+
}> | Readonly<{
|
|
716
|
+
error: "not_found" | "not_granted";
|
|
717
|
+
}>>;
|
|
718
|
+
/** Detach one hosted extension; detaching only ever removes authority. */
|
|
719
|
+
detachExtension(agentId: string, installationId: string, principal: TenantPrincipal): "detached" | "absent" | Readonly<{
|
|
720
|
+
error: "not_found" | "not_granted";
|
|
721
|
+
}>;
|
|
722
|
+
/** The Agent's attachments whose grantor is still the same current owner. */
|
|
723
|
+
extensionAttachmentsFor(agentId: string, tenantId?: TenantId): Promise<readonly Readonly<{
|
|
724
|
+
installationId: string;
|
|
725
|
+
instanceId: string;
|
|
726
|
+
}>[]>;
|
|
686
727
|
visit(agentId: string, sessionId: string): void;
|
|
687
728
|
visits(): readonly Readonly<{
|
|
688
729
|
agentId: string;
|
|
@@ -48,7 +48,10 @@ import { resolveHome } from "@fungi.computer/shiitake-extensions/home/host";
|
|
|
48
48
|
import { DurableObject } from "cloudflare:workers";
|
|
49
49
|
import { standaloneHomeInstructionsFile, } from "./computer.js";
|
|
50
50
|
import { shiitakeEngine } from "./agent-engine.js";
|
|
51
|
+
import { hostedAgentExtensionsGrant, hostedAppExtensions, } from "@fungi.computer/shiitake/hosted";
|
|
52
|
+
import { isAgentExtensionApi } from "@fungi.computer/agar/backend-definition";
|
|
51
53
|
import { agentStoreKeeping } from "./agent-store.js";
|
|
54
|
+
import { createAgentExtensionAttachments, } from "./agent-extension-attachments.js";
|
|
52
55
|
import { CredentialError, } from "@fungi.computer/veil/credential-store";
|
|
53
56
|
import { createInstanceCredentialStore, createModelKeyVault, instanceCredentialKeyring, instanceSecretCustody, ModelKeyRefused, } from "./model-key-vault.js";
|
|
54
57
|
import { createModelKeyUsage } from "./model-key-usage.js";
|
|
@@ -99,6 +102,8 @@ const logRedactedFailure = (label, cause) => {
|
|
|
99
102
|
console.error(label, text);
|
|
100
103
|
});
|
|
101
104
|
};
|
|
105
|
+
/** Wall budget for one hosted-extension prompt or tools call, as on the Hub. */
|
|
106
|
+
const hostedExtensionBudgetMs = 3000;
|
|
102
107
|
/** The starter's Home attachment: one fixed id, so a replayed create attaches once. */
|
|
103
108
|
const starterHomeAttachment = "starter-home:v1";
|
|
104
109
|
/** The Agent's own storage key for the setup prompt it carries while it has no Home. */
|
|
@@ -1111,6 +1116,25 @@ export class StandaloneAgentBase extends DurableObject {
|
|
|
1111
1116
|
? this.hostFor(scope)
|
|
1112
1117
|
: null;
|
|
1113
1118
|
}
|
|
1119
|
+
/**
|
|
1120
|
+
* The installation an owner may attach as this Agent's hosted extension:
|
|
1121
|
+
* enabled, running, and its current Release declares the whole method
|
|
1122
|
+
* family. Its Instance pins the attachment.
|
|
1123
|
+
*/
|
|
1124
|
+
async extensionInstallation(installationId) {
|
|
1125
|
+
const host = await this.appHost();
|
|
1126
|
+
if (host === null)
|
|
1127
|
+
return null;
|
|
1128
|
+
const installation = await host.installations.get(installationId);
|
|
1129
|
+
if (installation?.status !== "enabled" || installation.instanceId === null)
|
|
1130
|
+
return null;
|
|
1131
|
+
const { appSurfaceCache } = await import("../mcp.js");
|
|
1132
|
+
this.#appSurfaces ??= appSurfaceCache(host);
|
|
1133
|
+
const surface = await this.#appSurfaces(installation.release);
|
|
1134
|
+
return surface !== null && isAgentExtensionApi(surface.api)
|
|
1135
|
+
? { installationId, instanceId: installation.instanceId }
|
|
1136
|
+
: null;
|
|
1137
|
+
}
|
|
1114
1138
|
/** The instance directory that owns this Agent's sealed model keys. */
|
|
1115
1139
|
async keyDirectory() {
|
|
1116
1140
|
const pin = await this.policyDirectory();
|
|
@@ -1405,6 +1429,76 @@ export class StandaloneAgentBase extends DurableObject {
|
|
|
1405
1429
|
for (const invalidate of this.mcpInvalidations)
|
|
1406
1430
|
invalidate();
|
|
1407
1431
|
}
|
|
1432
|
+
/**
|
|
1433
|
+
* The hosted extensions the owner attached to this Agent, under the shared
|
|
1434
|
+
* composer. Both consents are required: the owner's attachment and the
|
|
1435
|
+
* Agent's current App-tool approval, whose level also decides whether the
|
|
1436
|
+
* extension's tools reach the run. A denied visitor Session asks nothing.
|
|
1437
|
+
* Every guest call goes through the same App door as App tools.
|
|
1438
|
+
*/
|
|
1439
|
+
async hostedExtensions(principal) {
|
|
1440
|
+
const { oysterExtensionDoor, appSurfaceCache, appBindingName, AppMethodRefused, } = await import("../mcp.js");
|
|
1441
|
+
return hostedAppExtensions({
|
|
1442
|
+
guestBudgetMs: hostedExtensionBudgetMs,
|
|
1443
|
+
attachments: async (sessionId) => {
|
|
1444
|
+
if ((await this.channelRun(sessionId)).kind === "denied")
|
|
1445
|
+
return null;
|
|
1446
|
+
const pin = await this.policyDirectory();
|
|
1447
|
+
const host = await this.appHost();
|
|
1448
|
+
if (pin === null || host === null)
|
|
1449
|
+
return null;
|
|
1450
|
+
const policy = (await host.appToolPolicy?.(principal.actor)) ?? null;
|
|
1451
|
+
if (policy === null)
|
|
1452
|
+
return null;
|
|
1453
|
+
const attached = await this.env.AGENT_DIRECTORY.getByName(pin.directoryName).extensionAttachmentsFor(this.agentName(), pin.tenantId);
|
|
1454
|
+
this.#appSurfaces ??= appSurfaceCache(host);
|
|
1455
|
+
const surfaces = this.#appSurfaces;
|
|
1456
|
+
const current = await Promise.all(attached.map(async ({ installationId, instanceId }) => {
|
|
1457
|
+
const installation = await host.installations.get(installationId);
|
|
1458
|
+
if (installation?.instanceId !== instanceId)
|
|
1459
|
+
return [];
|
|
1460
|
+
const call = await oysterExtensionDoor(host, surfaces, principal, { kind: "agent", policy }, installation, sessionId);
|
|
1461
|
+
if (call === null)
|
|
1462
|
+
return [];
|
|
1463
|
+
return [
|
|
1464
|
+
{
|
|
1465
|
+
bindingName: appBindingName(installationId),
|
|
1466
|
+
installationId,
|
|
1467
|
+
level: policy.level,
|
|
1468
|
+
cacheKey: JSON.stringify([
|
|
1469
|
+
installationId,
|
|
1470
|
+
instanceId,
|
|
1471
|
+
installation.release.releaseId,
|
|
1472
|
+
installation.release.artifact.artifactDigest,
|
|
1473
|
+
installation.authority.authorityVersion,
|
|
1474
|
+
policy.revision,
|
|
1475
|
+
]),
|
|
1476
|
+
call,
|
|
1477
|
+
},
|
|
1478
|
+
];
|
|
1479
|
+
}));
|
|
1480
|
+
return current.flat();
|
|
1481
|
+
},
|
|
1482
|
+
call: async (attachment, method, input, deadlineAt) => {
|
|
1483
|
+
try {
|
|
1484
|
+
return {
|
|
1485
|
+
kind: "ok",
|
|
1486
|
+
value: await attachment.call(method, input, deadlineAt === null
|
|
1487
|
+
? undefined
|
|
1488
|
+
: AbortSignal.timeout(Math.max(0, deadlineAt - Date.now()))),
|
|
1489
|
+
};
|
|
1490
|
+
}
|
|
1491
|
+
catch (cause) {
|
|
1492
|
+
if (cause instanceof AppMethodRefused)
|
|
1493
|
+
return { kind: "refused", reason: cause.code };
|
|
1494
|
+
throw cause;
|
|
1495
|
+
}
|
|
1496
|
+
},
|
|
1497
|
+
report: (report) => {
|
|
1498
|
+
logRedactedFailure(`hosted extension ${report.kind}`, report.kind === "tools_skipped" ? report.outcome : report.cause);
|
|
1499
|
+
},
|
|
1500
|
+
});
|
|
1501
|
+
}
|
|
1408
1502
|
/**
|
|
1409
1503
|
* A full override must retain channelSource and channelInstructions:
|
|
1410
1504
|
* dropping them removes a suspended website's run refusal and turn capture,
|
|
@@ -1554,8 +1648,9 @@ export class StandaloneAgentBase extends DurableObject {
|
|
|
1554
1648
|
})),
|
|
1555
1649
|
},
|
|
1556
1650
|
}),
|
|
1651
|
+
await this.hostedExtensions(principal),
|
|
1557
1652
|
],
|
|
1558
|
-
grants: [...extensions.grants, homeGrant],
|
|
1653
|
+
grants: [...extensions.grants, homeGrant, hostedAgentExtensionsGrant],
|
|
1559
1654
|
},
|
|
1560
1655
|
...keeping,
|
|
1561
1656
|
admission: {
|
|
@@ -1896,6 +1991,7 @@ export class AgentDirectory extends DurableObject {
|
|
|
1896
1991
|
computerNames = new Map();
|
|
1897
1992
|
directory;
|
|
1898
1993
|
avatars;
|
|
1994
|
+
extensionAttachments;
|
|
1899
1995
|
composedTenancy;
|
|
1900
1996
|
machineEnrollmentOwner;
|
|
1901
1997
|
machineFencesOwner;
|
|
@@ -2044,6 +2140,7 @@ export class AgentDirectory extends DurableObject {
|
|
|
2044
2140
|
ctx.storage.sql.exec("DROP TABLE IF EXISTS agent_instructions");
|
|
2045
2141
|
this.directory = createAgentDirectory(ctx.storage.sql);
|
|
2046
2142
|
this.avatars = createAgentAvatarStore(ctx.storage.sql);
|
|
2143
|
+
this.extensionAttachments = createAgentExtensionAttachments(ctx.storage.sql);
|
|
2047
2144
|
this.computers = createAgentComputers({
|
|
2048
2145
|
sql: ctx.storage.sql,
|
|
2049
2146
|
transactionSync: (body) => ctx.storage.transactionSync(body),
|
|
@@ -2685,6 +2782,70 @@ export class AgentDirectory extends DurableObject {
|
|
|
2685
2782
|
return policy;
|
|
2686
2783
|
});
|
|
2687
2784
|
}
|
|
2785
|
+
/**
|
|
2786
|
+
* Attach one hosted extension to an Agent. Only a current owner attaches;
|
|
2787
|
+
* the row records that owner and membership version, and the Instance the
|
|
2788
|
+
* caller found for an enabled extension installation.
|
|
2789
|
+
*/
|
|
2790
|
+
async attachExtension(agentId, target, principal, tenantId) {
|
|
2791
|
+
if (!oysterPrincipalIsOwner(principal))
|
|
2792
|
+
return { error: "not_granted" };
|
|
2793
|
+
if (!this.has(agentId))
|
|
2794
|
+
return { error: "not_found" };
|
|
2795
|
+
const member = await this.currentMember(tenantId, oysterPrincipalId(principal));
|
|
2796
|
+
if (member === null ||
|
|
2797
|
+
!oysterPrincipalIsOwner(member) ||
|
|
2798
|
+
!Schema.is(approverVersionSchema)(member.membershipVersion) ||
|
|
2799
|
+
oysterPrincipalId(member) !== oysterPrincipalId(principal))
|
|
2800
|
+
return { error: "not_granted" };
|
|
2801
|
+
const attachedBy = oysterPrincipalId(member);
|
|
2802
|
+
const membershipVersion = member.membershipVersion;
|
|
2803
|
+
this.ctx.storage.transactionSync(() => {
|
|
2804
|
+
this.extensionAttachments.attach(agentId, {
|
|
2805
|
+
...target,
|
|
2806
|
+
attachedBy,
|
|
2807
|
+
membershipVersion,
|
|
2808
|
+
});
|
|
2809
|
+
this.bump();
|
|
2810
|
+
});
|
|
2811
|
+
return { installationId: target.installationId, attachedBy };
|
|
2812
|
+
}
|
|
2813
|
+
/** Detach one hosted extension; detaching only ever removes authority. */
|
|
2814
|
+
detachExtension(agentId, installationId, principal) {
|
|
2815
|
+
if (!oysterPrincipalIsOwner(principal))
|
|
2816
|
+
return { error: "not_granted" };
|
|
2817
|
+
if (!this.has(agentId))
|
|
2818
|
+
return { error: "not_found" };
|
|
2819
|
+
return this.ctx.storage.transactionSync(() => {
|
|
2820
|
+
if (!this.extensionAttachments.detach(agentId, installationId))
|
|
2821
|
+
return "absent";
|
|
2822
|
+
this.bump();
|
|
2823
|
+
return "detached";
|
|
2824
|
+
});
|
|
2825
|
+
}
|
|
2826
|
+
/** The Agent's attachments whose grantor is still the same current owner. */
|
|
2827
|
+
async extensionAttachmentsFor(agentId, tenantId = defaultTenant) {
|
|
2828
|
+
if (!this.has(agentId))
|
|
2829
|
+
return [];
|
|
2830
|
+
const current = new Map();
|
|
2831
|
+
const attached = [];
|
|
2832
|
+
for (const row of this.extensionAttachments.list(agentId)) {
|
|
2833
|
+
if (!current.has(row.attachedBy)) {
|
|
2834
|
+
const member = await this.currentMember(tenantId, row.attachedBy);
|
|
2835
|
+
current.set(row.attachedBy, member !== null &&
|
|
2836
|
+
oysterPrincipalIsOwner(member) &&
|
|
2837
|
+
oysterPrincipalId(member) === row.attachedBy
|
|
2838
|
+
? member.membershipVersion
|
|
2839
|
+
: null);
|
|
2840
|
+
}
|
|
2841
|
+
if (current.get(row.attachedBy) === row.membershipVersion)
|
|
2842
|
+
attached.push({
|
|
2843
|
+
installationId: row.installationId,
|
|
2844
|
+
instanceId: row.instanceId,
|
|
2845
|
+
});
|
|
2846
|
+
}
|
|
2847
|
+
return attached;
|
|
2848
|
+
}
|
|
2688
2849
|
visit(agentId, sessionId) {
|
|
2689
2850
|
this.ctx.storage.sql.exec("INSERT INTO visits(agent_id, session_id, visited_at) VALUES(?,?,?) ON CONFLICT(agent_id, session_id) DO UPDATE SET visited_at=excluded.visited_at", agentId, sessionId, Date.now());
|
|
2690
2851
|
this.bump();
|
|
@@ -2925,6 +3086,27 @@ export function standaloneAgents(env, scope) {
|
|
|
2925
3086
|
return { error: "not_found" };
|
|
2926
3087
|
return directory().approveAppToolPolicy(agentId, principal, level, expectedRevision, actor, scope?.tenantId ?? defaultTenant);
|
|
2927
3088
|
},
|
|
3089
|
+
extensionAttachments: async (agentId) => {
|
|
3090
|
+
if (!(await directory().has(agentId)))
|
|
3091
|
+
return null;
|
|
3092
|
+
return (await directory().extensionAttachmentsFor(agentId, scope?.tenantId ?? defaultTenant)).map(({ installationId }) => ({ installationId }));
|
|
3093
|
+
},
|
|
3094
|
+
attachExtension: async (agentId, installationId, principal) => {
|
|
3095
|
+
if (!oysterPrincipalIsOwner(principal))
|
|
3096
|
+
return { error: "not_granted" };
|
|
3097
|
+
if (!(await directory().has(agentId)))
|
|
3098
|
+
return { error: "not_found" };
|
|
3099
|
+
const agent = env.AGENTS.getByName(agentId);
|
|
3100
|
+
const pinned = await agent.policyDirectory();
|
|
3101
|
+
if (pinned?.directoryName !== directoryName ||
|
|
3102
|
+
pinned.tenantId !== (scope?.tenantId ?? defaultTenant))
|
|
3103
|
+
return { error: "not_found" };
|
|
3104
|
+
const target = await agent.extensionInstallation(installationId);
|
|
3105
|
+
if (target === null)
|
|
3106
|
+
return { error: "not_extension" };
|
|
3107
|
+
return directory().attachExtension(agentId, target, principal, scope?.tenantId ?? defaultTenant);
|
|
3108
|
+
},
|
|
3109
|
+
detachExtension: (agentId, installationId, principal) => directory().detachExtension(agentId, installationId, principal),
|
|
2928
3110
|
connections: () => directory().connections(),
|
|
2929
3111
|
addConnection: (input) => directory().addConnection(input),
|
|
2930
3112
|
grantConnection: (connectionId, agentId, access) => directory().grantConnection(connectionId, agentId, access),
|
package/docs/api/README.md
CHANGED
|
@@ -222,6 +222,19 @@ no policy exists). A stale revision returns 409, an unknown Agent 404 and
|
|
|
222
222
|
malformed input 400. The stored approval pins the owner's `membershipVersion`,
|
|
223
223
|
so demotion, removal or suspension requires new approval.
|
|
224
224
|
|
|
225
|
+
**Hosted extensions.** An App whose backend declares the Agent extension methods
|
|
226
|
+
(`agentExtensionPrompt`, `agentExtensionTools`, `agentExtensionCall`) can add
|
|
227
|
+
prompt sections and tools to an Agent's runs. Those methods are never listed as
|
|
228
|
+
App tools. The Agent's App-tool approval alone attaches nothing:
|
|
229
|
+
`PUT /api/agent-extensions/:agentId/:installationId` attaches one enabled
|
|
230
|
+
extension installation (409 `not_extension` when its current Release is not
|
|
231
|
+
one), `DELETE` the same path detaches it, and
|
|
232
|
+
`GET /api/agent-extensions/:agentId` lists the attachments. The Agent's approval
|
|
233
|
+
level still applies: `read` gives the extension's prompt sections, `write` also
|
|
234
|
+
its tools. An attachment lapses when the installation is removed or replaced, or
|
|
235
|
+
when the attaching owner's membership changes. A visitor Session whose website
|
|
236
|
+
or Discord binding is not active asks no extension.
|
|
237
|
+
|
|
225
238
|
**Remote MCP servers.** Connect a Streamable HTTP MCP server once, then choose
|
|
226
239
|
which Agents use it; each sees its granted tools as `env.mcp.<name>.<tool>()`.
|
|
227
240
|
`GET /api/connections` returns the connections, their grants, the Agents and the
|
package/docs/api/agents.md
CHANGED
|
@@ -345,6 +345,25 @@ type OysterAgents = Readonly<{
|
|
|
345
345
|
| Readonly<{
|
|
346
346
|
error: "not_found" | "revision_conflict" | "not_granted";
|
|
347
347
|
}>>;
|
|
348
|
+
extensionAttachments: Promise<
|
|
349
|
+
| readonly Readonly<{
|
|
350
|
+
installationId: string;
|
|
351
|
+
}>[]
|
|
352
|
+
| null>;
|
|
353
|
+
attachExtension: Promise<
|
|
354
|
+
| Readonly<{
|
|
355
|
+
installationId: string;
|
|
356
|
+
attachedBy: string;
|
|
357
|
+
}>
|
|
358
|
+
| Readonly<{
|
|
359
|
+
error: "not_found" | "not_granted" | "not_extension";
|
|
360
|
+
}>>;
|
|
361
|
+
detachExtension: Promise<
|
|
362
|
+
| "absent"
|
|
363
|
+
| "detached"
|
|
364
|
+
| Readonly<{
|
|
365
|
+
error: "not_found" | "not_granted";
|
|
366
|
+
}>>;
|
|
348
367
|
setup: Promise<Readonly<{
|
|
349
368
|
models: "ready" | "missing";
|
|
350
369
|
media: "ready" | "missing";
|
package/docs/api/mcp.md
CHANGED
|
@@ -260,6 +260,51 @@ verification is not cached.
|
|
|
260
260
|
|
|
261
261
|
`Promise`\<[`ReleaseSurface`](#releasesurface) \| `null`\>
|
|
262
262
|
|
|
263
|
+
---
|
|
264
|
+
|
|
265
|
+
### AppSnapshotHost
|
|
266
|
+
|
|
267
|
+
```ts
|
|
268
|
+
type AppSnapshotHost = Pick<
|
|
269
|
+
OysterHost,
|
|
270
|
+
| "tenantId"
|
|
271
|
+
| "installations"
|
|
272
|
+
| "instances"
|
|
273
|
+
| "artifacts"
|
|
274
|
+
| "guestLimits"
|
|
275
|
+
| "backgroundOriginKey"
|
|
276
|
+
| "computerId"
|
|
277
|
+
| "capabilities"
|
|
278
|
+
| "appToolPolicy"
|
|
279
|
+
| "keys"
|
|
280
|
+
| "approvals"
|
|
281
|
+
>;
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
The host parts the App door and its snapshot read.
|
|
285
|
+
|
|
286
|
+
---
|
|
287
|
+
|
|
288
|
+
### OysterExtensionCall
|
|
289
|
+
|
|
290
|
+
```ts
|
|
291
|
+
type OysterExtensionCall = (name, input, signal?) => Promise<OysterJson>;
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
One host-side call of a hosted extension's wire method.
|
|
295
|
+
|
|
296
|
+
#### Parameters
|
|
297
|
+
|
|
298
|
+
| Parameter | Type |
|
|
299
|
+
| --------- | ---------------------------------- |
|
|
300
|
+
| `name` | `string` |
|
|
301
|
+
| `input` | [`OysterJson`](host.md#oysterjson) |
|
|
302
|
+
| `signal?` | `AbortSignal` |
|
|
303
|
+
|
|
304
|
+
#### Returns
|
|
305
|
+
|
|
306
|
+
`Promise`\<[`OysterJson`](host.md#oysterjson)\>
|
|
307
|
+
|
|
263
308
|
## Variables
|
|
264
309
|
|
|
265
310
|
### appApprovalInstructions
|
|
@@ -392,6 +437,41 @@ capabilities stay fixed.
|
|
|
392
437
|
|
|
393
438
|
---
|
|
394
439
|
|
|
440
|
+
### oysterExtensionDoor()
|
|
441
|
+
|
|
442
|
+
```ts
|
|
443
|
+
function oysterExtensionDoor(
|
|
444
|
+
host,
|
|
445
|
+
surfaces,
|
|
446
|
+
principal,
|
|
447
|
+
access,
|
|
448
|
+
installation,
|
|
449
|
+
sessionId,
|
|
450
|
+
): Promise<OysterExtensionCall | null>;
|
|
451
|
+
```
|
|
452
|
+
|
|
453
|
+
The host-side door for an attached hosted extension: its wire methods go through
|
|
454
|
+
the same App door as App tools (staleness, fresh policy, `admits`, the Instance
|
|
455
|
+
call), and never appear as a model-facing operation. Null when the
|
|
456
|
+
installation's current Release is not an Agent extension.
|
|
457
|
+
|
|
458
|
+
#### Parameters
|
|
459
|
+
|
|
460
|
+
| Parameter | Type |
|
|
461
|
+
| -------------- | ---------------------------------------------- |
|
|
462
|
+
| `host` | [`AppSnapshotHost`](#appsnapshothost) |
|
|
463
|
+
| `surfaces` | [`AppSurfaceCache`](#appsurfacecache) |
|
|
464
|
+
| `principal` | [`TenantPrincipal`](tenant.md#tenantprincipal) |
|
|
465
|
+
| `access` | [`OysterCallerAccess`](#oystercalleraccess) |
|
|
466
|
+
| `installation` | [`Installation`](apps.md#installation) |
|
|
467
|
+
| `sessionId` | `string` \| `null` |
|
|
468
|
+
|
|
469
|
+
#### Returns
|
|
470
|
+
|
|
471
|
+
`Promise`\<[`OysterExtensionCall`](#oysterextensioncall) \| `null`\>
|
|
472
|
+
|
|
473
|
+
---
|
|
474
|
+
|
|
395
475
|
### oysterAppSnapshot()
|
|
396
476
|
|
|
397
477
|
```ts
|