@fungi.computer/oyster 0.44.0 → 0.46.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.
@@ -51,6 +51,7 @@ import { ShiitakeDO } from "@fungi.computer/shiitake/cloudflare";
51
51
  import { agentStoreKeeping } from "./agent-store.js";
52
52
  import { CredentialError, } from "@fungi.computer/veil/credential-store";
53
53
  import { createInstanceCredentialStore, createModelKeyVault, instanceCredentialKeyring, instanceSecretCustody, ModelKeyRefused, } from "./model-key-vault.js";
54
+ import { createModelKeyUsage } from "./model-key-usage.js";
54
55
  import { agentArchiveOwner } from "./agent-archive-owner.js";
55
56
  import { agentArchiveProjection } from "../agent-archive-projection.js";
56
57
  import { standaloneBrowserLiveView, standaloneBrowserSource, } from "./browser.js";
@@ -98,13 +99,15 @@ const logRedactedFailure = (label, cause) => {
98
99
  console.error(label, text);
99
100
  });
100
101
  };
101
- /** The starter has no Home yet: the owner has not attached a Computer. The seed waits for one. */
102
- class StarterHomePending extends Error {
103
- constructor() {
104
- super("The starter Agent has no Home Computer yet");
105
- this.name = "StarterHomePending";
106
- }
107
- }
102
+ /** The starter's Home attachment: one fixed id, so a replayed create attaches once. */
103
+ const starterHomeAttachment = "starter-home:v1";
104
+ /** The Agent's own storage key for the setup prompt it carries while it has no Home. */
105
+ const firstConversationKey = "first-conversation";
106
+ /** The kept prompt, and the owner whose grant writes it to a later Home. */
107
+ const firstConversationSchema = z.object({
108
+ content: z.string().min(1),
109
+ actor: z.string().min(1),
110
+ });
108
111
  const noHomeInstructions = {
109
112
  home: null,
110
113
  content: null,
@@ -1160,6 +1163,59 @@ export class StandaloneAgentBase extends ShiitakeDO {
1160
1163
  async readModelChoice() {
1161
1164
  return this.choice().read();
1162
1165
  }
1166
+ /**
1167
+ * Keep the starter's setup prompt on this Agent while it has no Home to hold
1168
+ * an AGENTS.md. Written once; Agents that never needed it have no such key.
1169
+ * `actor` is the owner whose grant later writes it into a Home.
1170
+ */
1171
+ async seedFirstConversation(content, actor) {
1172
+ if ((await this.ctx.storage.get(firstConversationKey)) === undefined)
1173
+ await this.ctx.storage.put(firstConversationKey, firstConversationSchema.parse({ content, actor }));
1174
+ }
1175
+ /** The instructions every run of this Agent starts from. */
1176
+ async agentInstructions() {
1177
+ const { appApprovalInstructions } = await import("../mcp.js");
1178
+ const first = await this.firstConversation();
1179
+ return {
1180
+ revision: first === null ? "oyster-7" : "oyster-7+first-conversation",
1181
+ text: instructions +
1182
+ "\n" +
1183
+ appApprovalInstructions +
1184
+ (first === null ? "" : "\n\n" + first),
1185
+ };
1186
+ }
1187
+ /**
1188
+ * The kept setup prompt, until a Home exists. Then it moves into that Home's
1189
+ * AGENTS.md when the Home has none (the starter seed's rule), so an
1190
+ * interview that gains a Home midway keeps its instructions, and the kept
1191
+ * copy is dropped. A Home that already has an AGENTS.md is left as it is.
1192
+ */
1193
+ async firstConversation() {
1194
+ const stored = await this.ctx.storage.get(firstConversationKey);
1195
+ if (stored === undefined)
1196
+ return null;
1197
+ const { content, actor } = firstConversationSchema.parse(stored);
1198
+ const attachments = (await this.preparedComputerSnapshot())?.projection.attachments ?? [];
1199
+ if (attachments.length === 0)
1200
+ return content;
1201
+ // Until the move lands (the Home went away, or its Computer could not
1202
+ // write), the prompt keeps riding in the instructions; a later run retries.
1203
+ let moved;
1204
+ try {
1205
+ moved = await this.replaceInstructions(actor, null, content);
1206
+ }
1207
+ catch (cause) {
1208
+ logRedactedFailure("starter setup prompt move failed", cause);
1209
+ return content;
1210
+ }
1211
+ if ("error" in moved && moved.error !== "conflict") {
1212
+ if (moved.error === "too_large")
1213
+ logRedactedFailure("starter setup prompt move failed", new Error("The setup prompt exceeds the AGENTS.md limit"));
1214
+ return content;
1215
+ }
1216
+ await this.ctx.storage.delete(firstConversationKey);
1217
+ return null;
1218
+ }
1163
1219
  async setModelChoice(input) {
1164
1220
  try {
1165
1221
  return await this.choice().set(input);
@@ -1215,7 +1271,7 @@ export class StandaloneAgentBase extends ShiitakeDO {
1215
1271
  method: request.method,
1216
1272
  headers: [...request.headers],
1217
1273
  body: request.body === null ? null : await request.text(),
1218
- });
1274
+ }, this.ctx.id.name ?? null);
1219
1275
  if (!(sent instanceof Response))
1220
1276
  throw new AgentModelRefused(sent.error === "key_removed"
1221
1277
  ? "key_removed"
@@ -1362,13 +1418,7 @@ export class StandaloneAgentBase extends ShiitakeDO {
1362
1418
  meta: { schema: FungiMessageMetaSchema },
1363
1419
  ...this.mail().host,
1364
1420
  instructions: this.channelInstructions({
1365
- load: async () => {
1366
- const { appApprovalInstructions } = await import("../mcp.js");
1367
- return {
1368
- revision: "oyster-7",
1369
- text: instructions + "\n" + appApprovalInstructions,
1370
- };
1371
- },
1421
+ load: () => this.agentInstructions(),
1372
1422
  }),
1373
1423
  tools: {
1374
1424
  // A run outlasts one ten-minute Computer command; waiting for a
@@ -1631,19 +1681,42 @@ export class AgentDirectory extends DurableObject {
1631
1681
  return this.modelKeys().remove(keyId);
1632
1682
  }
1633
1683
  /** Host-only: the one place a stored key meets a provider request. */
1634
- async sendModelKey(keyId, request) {
1684
+ async sendModelKey(keyId, request,
1685
+ /** The Agent the use is audited to; never its prompt or reply. */
1686
+ agentId = null) {
1687
+ let status = null;
1635
1688
  try {
1636
- return await this.modelKeys().send(keyId, new Request(request.url, {
1689
+ const response = await this.modelKeys().send(keyId, new Request(request.url, {
1637
1690
  method: request.method,
1638
1691
  headers: request.headers.map(([name, value]) => [name, value]),
1639
1692
  body: request.body,
1640
1693
  }));
1694
+ status = response.status;
1695
+ return response;
1641
1696
  }
1642
1697
  catch (error) {
1643
1698
  if (error instanceof ModelKeyRefused)
1644
1699
  return { error: error.reason };
1645
1700
  throw error;
1646
1701
  }
1702
+ finally {
1703
+ this.modelKeyUsage().record({ keyId, agentId, status });
1704
+ }
1705
+ }
1706
+ modelKeyUsageOwner;
1707
+ modelKeyUsage() {
1708
+ return (this.modelKeyUsageOwner ??= createModelKeyUsage({
1709
+ sql: this.ctx.storage.sql,
1710
+ }));
1711
+ }
1712
+ /** The Vault page's one owner door: every stored credential, write-only. */
1713
+ async vault(command) {
1714
+ const { createInstanceVault } = await import("./vault.js");
1715
+ return createInstanceVault({
1716
+ connections: await this.mcpConnections(),
1717
+ modelKeys: () => this.listModelKeys(),
1718
+ modelKeyUsage: (keyId) => this.modelKeyUsage().list(keyId),
1719
+ })(command);
1647
1720
  }
1648
1721
  redactionSet;
1649
1722
  /**
@@ -2678,6 +2751,11 @@ export function standaloneAgents(env, scope) {
2678
2751
  create: created,
2679
2752
  ensureStarter: (principal) => {
2680
2753
  const owner = directory();
2754
+ const reportStarterFailure = (cause) => {
2755
+ void redactedFailure(cause).then((text) => {
2756
+ console.warn(JSON.stringify({ event: "starter_agent_failed", cause: text }));
2757
+ });
2758
+ };
2681
2759
  return ensureStarterAgent({
2682
2760
  ledger: {
2683
2761
  read: () => owner.readStarter(),
@@ -2685,14 +2763,32 @@ export function standaloneAgents(env, scope) {
2685
2763
  },
2686
2764
  isOwner: () => oysterPrincipalIsOwner(principal),
2687
2765
  agentCount: () => owner.agentTotal(),
2688
- // The ordinary create: the same Computer-less Agent, policy and approval any owner create gets.
2766
+ // The ordinary create, then the ordinary owner attach of the host's own
2767
+ // configured Computer as its Home. A host with no such Computer, or one
2768
+ // the attach refuses, leaves the starter without a Home.
2689
2769
  create: async (request) => {
2690
2770
  const agent = await created(request.name, request.requestId, principal, "owner-direct");
2771
+ const computerId = env.OYSTER_COMPUTER_ID;
2772
+ // The Agent exists now; a failed Home attach must not fail the
2773
+ // create, or the starter ledger is never written. It is reported,
2774
+ // and the seed falls back to the Agent's own record.
2775
+ if (computerId !== undefined && computerId !== "")
2776
+ await directory()
2777
+ .attachComputer({
2778
+ agentId: agent.agentId,
2779
+ attachmentId: starterHomeAttachment,
2780
+ computerId,
2781
+ requestId: starterHomeAttachment,
2782
+ }, principal, scope?.tenantId ?? defaultTenant)
2783
+ .catch((cause) => {
2784
+ reportStarterFailure(cause);
2785
+ });
2691
2786
  return { status: "created", agentId: agent.agentId };
2692
2787
  },
2693
2788
  // No money step on Oyster: the owner brings their own model, so the
2694
2789
  // seed is only the first-run section, written to a Home that has no
2695
- // AGENTS.md. A Home the owner already wrote to is left as it is.
2790
+ // AGENTS.md. A Home the owner already wrote to is left as it is. With
2791
+ // no Home, the same section stays on the Agent until it has one.
2696
2792
  seedHome: async (agentId) => {
2697
2793
  await seedStarterHome(async (path, content) => {
2698
2794
  if (path !== "AGENTS.md")
@@ -2703,18 +2799,11 @@ export function standaloneAgents(env, scope) {
2703
2799
  if (result.error === "conflict")
2704
2800
  return;
2705
2801
  if (result.error === "no_home")
2706
- throw new StarterHomePending();
2802
+ return env.AGENTS.getByName(agentId).seedFirstConversation(content, JSON.stringify(principal));
2707
2803
  throw new Error(`Starter Home seed refused: ${result.error}`);
2708
2804
  });
2709
2805
  },
2710
- report: (cause) => {
2711
- // Waiting for the owner to attach a Computer is not a failure.
2712
- if (cause instanceof StarterHomePending)
2713
- return;
2714
- void redactedFailure(cause).then((text) => {
2715
- console.warn(JSON.stringify({ event: "starter_agent_failed", cause: text }));
2716
- });
2717
- },
2806
+ report: reportStarterFailure,
2718
2807
  });
2719
2808
  },
2720
2809
  rename: async (agentId, name, principal) => {
@@ -2773,6 +2862,7 @@ export function standaloneAgents(env, scope) {
2773
2862
  modelKeys: () => directory().listModelKeys(),
2774
2863
  sealModelKey: (input) => directory().sealModelKey(input),
2775
2864
  removeModelKey: (keyId) => directory().removeModelKey(keyId),
2865
+ vault: (command) => directory().vault(command),
2776
2866
  policyStatus: async (agentId) => directory().policyStatus(agentId),
2777
2867
  appToolPolicy: (actor) => directory().appToolPolicy(actor, scope?.tenantId ?? defaultTenant),
2778
2868
  policyRevision: (agentId) => directory().policyRevision(agentId),
@@ -0,0 +1,28 @@
1
+ type ModelKeyUse = Readonly<{
2
+ keyId: string;
3
+ agentId: string | null;
4
+ /** The provider's status, or null when nothing came back. */
5
+ status: number | null;
6
+ }>;
7
+ /** One recorded use, as the Vault lists it. */
8
+ export type ModelKeyUsage = Readonly<{
9
+ keyId: string;
10
+ subject: Readonly<{
11
+ kind: "agent";
12
+ id: string;
13
+ }> | null;
14
+ outcome: "upstream_status" | "failed";
15
+ status: number | null;
16
+ firstAt: number;
17
+ lastAt: number;
18
+ count: number;
19
+ }>;
20
+ export declare function createModelKeyUsage(options: {
21
+ sql: SqlStorage;
22
+ now?: () => number;
23
+ }): {
24
+ record(use: ModelKeyUse): void;
25
+ /** The newest uses of one key, oldest first. */
26
+ list(keyId: string): readonly ModelKeyUsage[];
27
+ };
28
+ export {};
@@ -0,0 +1,70 @@
1
+ import * as Schema from "effect/Schema";
2
+ /**
3
+ * Each use of a stored model key, for the Vault page: which Agent, when, and
4
+ * how the provider answered. Never the value, the prompt or the response.
5
+ * Identical uses within a minute share a row, as Veil's connection audit does;
6
+ * rows older than 90 days, and the oldest beyond the cap, are dropped.
7
+ */
8
+ const retentionMs = 90 * 24 * 60 * 60 * 1_000;
9
+ const coalesceMs = 60_000;
10
+ const rowLimit = 50_000;
11
+ const listLimit = 1_000;
12
+ const usageRow = Schema.Struct({
13
+ key_id: Schema.String,
14
+ agent_id: Schema.NullOr(Schema.String),
15
+ status: Schema.NullOr(Schema.Number),
16
+ first_at: Schema.Number,
17
+ last_at: Schema.Number,
18
+ uses: Schema.Number,
19
+ });
20
+ const decodeRows = Schema.decodeUnknownSync(Schema.Array(usageRow));
21
+ export function createModelKeyUsage(options) {
22
+ const { sql } = options;
23
+ const now = options.now ?? Date.now;
24
+ sql.exec(`CREATE TABLE IF NOT EXISTS oyster_model_key_usage (
25
+ sequence INTEGER PRIMARY KEY AUTOINCREMENT,
26
+ key_id TEXT NOT NULL,
27
+ agent_id TEXT,
28
+ status INTEGER,
29
+ first_at INTEGER NOT NULL,
30
+ last_at INTEGER NOT NULL,
31
+ uses INTEGER NOT NULL
32
+ )`);
33
+ sql.exec("CREATE INDEX IF NOT EXISTS oyster_model_key_usage_key ON oyster_model_key_usage (key_id, sequence)");
34
+ const expire = (at) => {
35
+ sql.exec("DELETE FROM oyster_model_key_usage WHERE last_at <= ?", at - retentionMs);
36
+ };
37
+ return {
38
+ record(use) {
39
+ const at = now();
40
+ expire(at);
41
+ const coalesced = sql
42
+ .exec(`UPDATE oyster_model_key_usage SET last_at = ?, uses = uses + 1
43
+ WHERE sequence = (
44
+ SELECT sequence FROM oyster_model_key_usage
45
+ WHERE key_id = ? AND agent_id IS ? AND status IS ? AND first_at > ?
46
+ ORDER BY sequence DESC LIMIT 1
47
+ ) RETURNING sequence`, at, use.keyId, use.agentId, use.status, at - coalesceMs)
48
+ .toArray();
49
+ if (coalesced.length > 0)
50
+ return;
51
+ sql.exec("DELETE FROM oyster_model_key_usage WHERE sequence IN (SELECT sequence FROM oyster_model_key_usage ORDER BY sequence LIMIT MAX(0, (SELECT COUNT(*) FROM oyster_model_key_usage) - ? + 1))", rowLimit);
52
+ sql.exec("INSERT INTO oyster_model_key_usage (key_id, agent_id, status, first_at, last_at, uses) VALUES (?, ?, ?, ?, ?, 1)", use.keyId, use.agentId, use.status, at, at);
53
+ },
54
+ /** The newest uses of one key, oldest first. */
55
+ list(keyId) {
56
+ expire(now());
57
+ return decodeRows(sql
58
+ .exec("SELECT key_id, agent_id, status, first_at, last_at, uses FROM (SELECT * FROM oyster_model_key_usage WHERE key_id = ? ORDER BY sequence DESC LIMIT ?) ORDER BY sequence", keyId, listLimit)
59
+ .toArray()).map((row) => ({
60
+ keyId: row.key_id,
61
+ subject: row.agent_id === null ? null : { kind: "agent", id: row.agent_id },
62
+ outcome: row.status === null ? "failed" : "upstream_status",
63
+ status: row.status,
64
+ firstAt: row.first_at,
65
+ lastAt: row.last_at,
66
+ count: row.uses,
67
+ }));
68
+ },
69
+ };
70
+ }
@@ -0,0 +1,84 @@
1
+ import type { ConnectionSubject, ConnectionUsage, ConnectionView, HttpDestinations, Placement } from "@fungi.computer/veil/connections";
2
+ import type { CredentialRefusal, createAgentMcpConnections } from "./agent-connections.js";
3
+ import type { ModelKeyRecord } from "./model-key-vault.js";
4
+ import type { ModelKeyUsage } from "./model-key-usage.js";
5
+ /** One stored credential as the Vault page lists it. No value, ever. */
6
+ export type VaultCredential = Readonly<{
7
+ connectionId: string;
8
+ name: string;
9
+ label: string;
10
+ kind: "secret" | "mcp" | "openapi";
11
+ origin: string;
12
+ destinations: HttpDestinations | null;
13
+ credential: "value" | "sign-in" | "none";
14
+ placement: Placement | null;
15
+ state: Exclude<ConnectionView["state"], "revoked">;
16
+ version: number;
17
+ subjects: readonly ConnectionSubject[];
18
+ }>;
19
+ /** One owner request to the instance Vault; values travel in, never out. */
20
+ export type VaultCommand = Readonly<{
21
+ op: "read";
22
+ }> | Readonly<{
23
+ op: "addSecret";
24
+ name: string;
25
+ label?: string | undefined;
26
+ destinations: HttpDestinations;
27
+ placement: Placement;
28
+ secret: string;
29
+ }> | Readonly<{
30
+ op: "updateCredential";
31
+ connectionId: string;
32
+ expectedVersion: number;
33
+ label?: string | undefined;
34
+ destinations?: HttpDestinations | undefined;
35
+ secret?: string | undefined;
36
+ }> | Readonly<{
37
+ op: "revokeCredential";
38
+ connectionId: string;
39
+ expectedVersion: number;
40
+ }> | Readonly<{
41
+ op: "grantSecret" | "ungrantSecret";
42
+ connectionId: string;
43
+ subject: ConnectionSubject;
44
+ }> | Readonly<{
45
+ op: "usage";
46
+ connectionId: string;
47
+ }> | Readonly<{
48
+ op: "modelKeyUsage";
49
+ keyId: string;
50
+ }>;
51
+ /** Why the Vault refused a command; never a stored value. */
52
+ export type VaultRefusal = Readonly<{
53
+ error: CredentialRefusal["error"] | "duplicate_name" | "limit" | "invalid_endpoint" | "unsupported_subject";
54
+ }>;
55
+ /** The Vault page listing: every stored credential and model key, with no value. */
56
+ export type VaultView = Readonly<{
57
+ /** The owner is the only actor on an Oyster: everything is theirs to manage. */
58
+ role: Readonly<{
59
+ manageTeam: true;
60
+ managePersonal: true;
61
+ }>;
62
+ modelKeys: readonly ModelKeyRecord[];
63
+ credentials: readonly VaultCredential[];
64
+ /** Oyster derives fingerprints from every stored value: always complete. */
65
+ coverage: Readonly<{
66
+ state: "complete";
67
+ }>;
68
+ }>;
69
+ /** What one Vault command answers: a listing, an id, a version, usage or a refusal. */
70
+ export type VaultResult = VaultView | Readonly<{
71
+ connectionId: string;
72
+ }> | Readonly<{
73
+ version: number;
74
+ }> | Readonly<{
75
+ ok: true;
76
+ }> | Readonly<{
77
+ usage: readonly ConnectionUsage[] | readonly ModelKeyUsage[];
78
+ }> | VaultRefusal;
79
+ /** The instance's Vault: its connections' credentials and model keys, write-only. */
80
+ export declare function createInstanceVault(owners: {
81
+ connections: ReturnType<typeof createAgentMcpConnections>;
82
+ modelKeys: () => Promise<readonly ModelKeyRecord[]>;
83
+ modelKeyUsage: (keyId: string) => readonly ModelKeyUsage[];
84
+ }): (command: VaultCommand) => Promise<VaultResult>;
@@ -0,0 +1,64 @@
1
+ const credentialOf = (view) => view.state === "revoked"
2
+ ? []
3
+ : [
4
+ {
5
+ connectionId: view.connectionId,
6
+ name: view.name,
7
+ label: view.label,
8
+ kind: view.surface.kind === "http" ? "secret" : view.surface.kind,
9
+ origin: view.surface.origin,
10
+ destinations: view.surface.destinations ?? null,
11
+ credential: view.credential.kind === "static"
12
+ ? "value"
13
+ : view.credential.kind === "oauth"
14
+ ? "sign-in"
15
+ : "none",
16
+ placement: view.credential.kind === "static"
17
+ ? view.credential.placement
18
+ : null,
19
+ state: view.state,
20
+ version: view.version,
21
+ subjects: view.grants.map((grant) => grant.subject),
22
+ },
23
+ ];
24
+ /** The instance's Vault: its connections' credentials and model keys, write-only. */
25
+ export function createInstanceVault(owners) {
26
+ const { connections } = owners;
27
+ return async (command) => {
28
+ switch (command.op) {
29
+ case "read":
30
+ return {
31
+ role: { manageTeam: true, managePersonal: true },
32
+ modelKeys: await owners.modelKeys(),
33
+ credentials: (await connections.credentials()).flatMap(credentialOf),
34
+ coverage: { state: "complete" },
35
+ };
36
+ case "addSecret":
37
+ return connections.addSecret(command);
38
+ case "updateCredential":
39
+ return connections.updateCredential(command);
40
+ case "revokeCredential": {
41
+ const held = (await connections.credentials()).find((view) => view.connectionId === command.connectionId);
42
+ if (held === undefined)
43
+ return { error: "not_found" };
44
+ if (held.version !== command.expectedVersion)
45
+ return { error: "conflict" };
46
+ // An HTTP secret is revoked whole; a Connection only loses its value.
47
+ if (held.surface.kind !== "http")
48
+ return connections.clearCredential(command);
49
+ return (await connections.remove(command.connectionId))
50
+ ? { ok: true }
51
+ : { error: "not_found" };
52
+ }
53
+ case "grantSecret":
54
+ return connections.grantSecret(command.connectionId, command.subject);
55
+ case "ungrantSecret":
56
+ await connections.ungrantSecret(command.connectionId, command.subject);
57
+ return { ok: true };
58
+ case "usage":
59
+ return { usage: await connections.secretUsage(command.connectionId) };
60
+ case "modelKeyUsage":
61
+ return { usage: owners.modelKeyUsage(command.keyId) };
62
+ }
63
+ };
64
+ }
@@ -368,6 +368,7 @@ type OysterAgents = Readonly<{
368
368
  error: ModelKeyRefusal;
369
369
  }>>;
370
370
  removeModelKey: Promise<"deleted" | "absent">;
371
+ vault: Promise<VaultResult>;
371
372
  connections: Promise<readonly Readonly<{
372
373
  connectionId: string;
373
374
  name: string;
@@ -383,11 +384,11 @@ type OysterAgents = Readonly<{
383
384
  }>[]>;
384
385
  addConnection: Promise<
385
386
  | Readonly<{
386
- connectionId: string;
387
- authorizeUrl: string | null;
387
+ error: "not_found" | "duplicate_name" | "limit" | "invalid_endpoint";
388
388
  }>
389
389
  | Readonly<{
390
- error: "not_found" | "duplicate_name" | "limit" | "invalid_endpoint";
390
+ connectionId: string;
391
+ authorizeUrl: string | null;
391
392
  }>>;
392
393
  grantConnection: Promise<
393
394
  | Readonly<{
@@ -430,6 +431,18 @@ restores only archive-paused schedules on unarchive.
430
431
 
431
432
  ---
432
433
 
434
+ ### CredentialRefusal
435
+
436
+ ```ts
437
+ type CredentialRefusal = Readonly<{
438
+ error: "not_found" | "conflict" | "denied" | "invalid_input";
439
+ }>;
440
+ ```
441
+
442
+ Why the Vault could not change a stored credential; never its value.
443
+
444
+ ---
445
+
433
446
  ### AgentModelChoice
434
447
 
435
448
  ```ts
@@ -468,6 +481,27 @@ Cloudflare account and token.
468
481
 
469
482
  ---
470
483
 
484
+ ### ModelKeyUsage
485
+
486
+ ```ts
487
+ type ModelKeyUsage = Readonly<{
488
+ keyId: string;
489
+ subject: Readonly<{
490
+ kind: "agent";
491
+ id: string;
492
+ }> | null;
493
+ outcome: "upstream_status" | "failed";
494
+ status: number | null;
495
+ firstAt: number;
496
+ lastAt: number;
497
+ count: number;
498
+ }>;
499
+ ```
500
+
501
+ One recorded use, as the Vault lists it.
502
+
503
+ ---
504
+
471
505
  ### ModelKeyRefusal
472
506
 
473
507
  ```ts
@@ -516,6 +550,136 @@ What the owner submits to seal one provider key.
516
550
 
517
551
  ---
518
552
 
553
+ ### VaultCredential
554
+
555
+ ```ts
556
+ type VaultCredential = Readonly<{
557
+ connectionId: string;
558
+ name: string;
559
+ label: string;
560
+ kind: "secret" | "mcp" | "openapi";
561
+ origin: string;
562
+ destinations: HttpDestinations | null;
563
+ credential: "value" | "sign-in" | "none";
564
+ placement: Placement | null;
565
+ state: Exclude<ConnectionView["state"], "revoked">;
566
+ version: number;
567
+ subjects: readonly ConnectionSubject[];
568
+ }>;
569
+ ```
570
+
571
+ One stored credential as the Vault page lists it. No value, ever.
572
+
573
+ ---
574
+
575
+ ### VaultCommand
576
+
577
+ ```ts
578
+ type VaultCommand =
579
+ | Readonly<{
580
+ op: "read";
581
+ }>
582
+ | Readonly<{
583
+ op: "addSecret";
584
+ name: string;
585
+ label?: string;
586
+ destinations: HttpDestinations;
587
+ placement: Placement;
588
+ secret: string;
589
+ }>
590
+ | Readonly<{
591
+ op: "updateCredential";
592
+ connectionId: string;
593
+ expectedVersion: number;
594
+ label?: string;
595
+ destinations?: HttpDestinations;
596
+ secret?: string;
597
+ }>
598
+ | Readonly<{
599
+ op: "revokeCredential";
600
+ connectionId: string;
601
+ expectedVersion: number;
602
+ }>
603
+ | Readonly<{
604
+ op: "grantSecret" | "ungrantSecret";
605
+ connectionId: string;
606
+ subject: ConnectionSubject;
607
+ }>
608
+ | Readonly<{
609
+ op: "usage";
610
+ connectionId: string;
611
+ }>
612
+ | Readonly<{
613
+ op: "modelKeyUsage";
614
+ keyId: string;
615
+ }>;
616
+ ```
617
+
618
+ One owner request to the instance Vault; values travel in, never out.
619
+
620
+ ---
621
+
622
+ ### VaultRefusal
623
+
624
+ ```ts
625
+ type VaultRefusal = Readonly<{
626
+ error:
627
+ | CredentialRefusal["error"]
628
+ | "duplicate_name"
629
+ | "limit"
630
+ | "invalid_endpoint"
631
+ | "unsupported_subject";
632
+ }>;
633
+ ```
634
+
635
+ Why the Vault refused a command; never a stored value.
636
+
637
+ ---
638
+
639
+ ### VaultView
640
+
641
+ ```ts
642
+ type VaultView = Readonly<{
643
+ role: Readonly<{
644
+ manageTeam: true;
645
+ managePersonal: true;
646
+ }>;
647
+ modelKeys: readonly ModelKeyRecord[];
648
+ credentials: readonly VaultCredential[];
649
+ coverage: Readonly<{
650
+ state: "complete";
651
+ }>;
652
+ }>;
653
+ ```
654
+
655
+ The Vault page listing: every stored credential and model key, with no value.
656
+
657
+ ---
658
+
659
+ ### VaultResult
660
+
661
+ ```ts
662
+ type VaultResult =
663
+ | VaultView
664
+ | Readonly<{
665
+ connectionId: string;
666
+ }>
667
+ | Readonly<{
668
+ version: number;
669
+ }>
670
+ | Readonly<{
671
+ ok: true;
672
+ }>
673
+ | Readonly<{
674
+ usage: readonly ConnectionUsage[] | readonly ModelKeyUsage[];
675
+ }>
676
+ | VaultRefusal;
677
+ ```
678
+
679
+ What one Vault command answers: a listing, an id, a version, usage or a refusal.
680
+
681
+ ---
682
+
519
683
  ### StarterOutcome
520
684
 
521
685
  ```ts