@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.
@@ -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),
@@ -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
@@ -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