@fungi.computer/oyster 0.43.0 → 0.45.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 CHANGED
@@ -3,6 +3,10 @@ import type { TenantPrincipal } from "./tenant.js";
3
3
  import type { ModelKeyRecord, ModelKeyRefusal, ModelKeySealInput } from "./standalone/model-key-vault.js";
4
4
  export type { ModelKeyRecord, ModelKeyRefusal, ModelKeySealInput, } from "./standalone/model-key-vault.js";
5
5
  export type { StandaloneModelKeyProvider } from "./standalone/model-key-providers.js";
6
+ import type { VaultCommand, VaultResult } from "./standalone/vault.js";
7
+ export type { VaultCommand, VaultCredential, VaultRefusal, VaultResult, VaultView, } from "./standalone/vault.js";
8
+ export type { ModelKeyUsage } from "./standalone/model-key-usage.js";
9
+ export type { CredentialRefusal } from "./standalone/agent-connections.js";
6
10
  import { type Routes } from "./authorization.js";
7
11
  import type { AppToolPolicy } from "./apps/tools.js";
8
12
  import * as Schema from "effect/Schema";
@@ -204,6 +208,8 @@ export type OysterAgents = Readonly<{
204
208
  }>>;
205
209
  /** Remove one key; Agents that chose it then fail with `key_removed`. */
206
210
  removeModelKey(keyId: string): Promise<"deleted" | "absent">;
211
+ /** The Vault page's one owner door: every stored credential, write-only. */
212
+ vault(command: VaultCommand): Promise<VaultResult>;
207
213
  /** Every connection with the Agents that may use it. */
208
214
  connections(): Promise<readonly OysterConnection[]>;
209
215
  /** Connect one remote MCP server; no Agent has it until the owner grants it. */
package/dist/agents.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { destinationsSchema, subjectSchema, } from "@fungi.computer/veil/connections";
1
2
  import { agent, agents as agentCollection, owner, routes, } from "./authorization.js";
2
3
  import * as Schema from "effect/Schema";
3
4
  import { agentNameSchema } from "@fungi.computer/agar/agents";
@@ -525,6 +526,127 @@ export function modelKeyRoutes(agents, computerSetup) {
525
526
  return (await agents.removeModelKey(keyId)) === "deleted"
526
527
  ? new Response(null, { status: 204 })
527
528
  : refusal(404, "No such key");
529
+ })
530
+ .include(vaultRoutes(agents));
531
+ }
532
+ /** Printable ASCII, as Veil seals it; never echoed back. */
533
+ const vaultValue = Schema.String.check(Schema.isPattern(/^[\x21-\x7e]{1,16384}$/u));
534
+ const vaultLabel = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(128));
535
+ const expectedVersion = Schema.Number.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(1));
536
+ const addSecretSchema = Schema.Struct({
537
+ name: Schema.String.check(Schema.isPattern(/^[a-z][a-z0-9_]{0,31}$/u)),
538
+ label: Schema.optional(vaultLabel),
539
+ destinations: destinationsSchema,
540
+ placement: Schema.Union([
541
+ Schema.Literal("bearer"),
542
+ Schema.Literal("basic"),
543
+ Schema.Struct({
544
+ header: Schema.String.check(Schema.isPattern(/^[A-Za-z0-9-]{1,64}$/u)),
545
+ }),
546
+ Schema.Struct({
547
+ query: Schema.String.check(Schema.isPattern(/^[A-Za-z0-9_.-]{1,64}$/u)),
548
+ }),
549
+ ]),
550
+ secret: vaultValue,
551
+ });
552
+ const updateCredentialSchema = Schema.Struct({
553
+ expectedVersion,
554
+ label: Schema.optional(vaultLabel),
555
+ destinations: Schema.optional(destinationsSchema),
556
+ secret: Schema.optional(vaultValue),
557
+ });
558
+ const revokeCredentialSchema = Schema.Struct({ expectedVersion });
559
+ /** Apps hold no Vault power: the subject kinds the page offers. */
560
+ const vaultSubjectKinds = new Set(["agent", "computer", "team-key"]);
561
+ const vaultRefusalStatus = {
562
+ not_found: 404,
563
+ conflict: 409,
564
+ denied: 403,
565
+ invalid_input: 400,
566
+ duplicate_name: 409,
567
+ limit: 409,
568
+ invalid_endpoint: 400,
569
+ unsupported_subject: 400,
570
+ };
571
+ /**
572
+ * The Vault page's owner routes. A value is posted straight here and nothing
573
+ * ever reads one back; listings and usage carry no value.
574
+ */
575
+ function vaultRoutes(agents) {
576
+ const answer = async (command, status = 200) => {
577
+ const result = await agents.vault(command);
578
+ return "error" in result
579
+ ? refusal(vaultRefusalStatus[result.error], result.error)
580
+ : Response.json(result, {
581
+ status,
582
+ headers: { "cache-control": "private, no-store" },
583
+ });
584
+ };
585
+ const body = async (request, schema) => {
586
+ if (Number(request.headers.get("content-length") ?? "0") > 64 * 1024)
587
+ return null;
588
+ const decoded = Schema.decodeUnknownOption(Schema.fromJsonString(schema), {
589
+ onExcessProperty: "error",
590
+ })(await request.text());
591
+ return decoded._tag === "None" ? null : decoded.value;
592
+ };
593
+ const subjectOf = (kind, id) => {
594
+ if (!vaultSubjectKinds.has(kind))
595
+ return null;
596
+ const subject = Schema.decodeUnknownOption(subjectSchema)({ kind, id });
597
+ return subject._tag === "None" ? null : subject.value;
598
+ };
599
+ return routes()
600
+ .get("/api/vault", owner("direct"), () => answer({ op: "read" }))
601
+ .post("/api/vault/secrets", owner("direct"), async (context) => {
602
+ const input = await body(context.req.raw, addSecretSchema);
603
+ return input === null
604
+ ? refusal(400, "Name the secret, bind it to hosts and paste its value")
605
+ : answer({ op: "addSecret", ...input }, 201);
606
+ })
607
+ .put("/api/vault/credentials/:connectionId", owner("direct"), async (context) => {
608
+ const connectionId = context.req.param("connectionId");
609
+ const input = await body(context.req.raw, updateCredentialSchema);
610
+ if (!connectionIdPattern.test(connectionId))
611
+ return refusal(404, "No such credential");
612
+ return input === null
613
+ ? refusal(400, "invalid_input")
614
+ : answer({ op: "updateCredential", connectionId, ...input });
615
+ })
616
+ .delete("/api/vault/credentials/:connectionId", owner("direct"), async (context) => {
617
+ const connectionId = context.req.param("connectionId");
618
+ const input = await body(context.req.raw, revokeCredentialSchema);
619
+ if (!connectionIdPattern.test(connectionId))
620
+ return refusal(404, "No such credential");
621
+ return input === null
622
+ ? refusal(400, "invalid_input")
623
+ : answer({ op: "revokeCredential", connectionId, ...input });
624
+ })
625
+ .put("/api/vault/credentials/:connectionId/subjects/:kind/:subjectId", owner("direct"), (context) => {
626
+ const connectionId = context.req.param("connectionId");
627
+ const subject = subjectOf(context.req.param("kind"), context.req.param("subjectId"));
628
+ return !connectionIdPattern.test(connectionId) || subject === null
629
+ ? refusal(400, "invalid_input")
630
+ : answer({ op: "grantSecret", connectionId, subject });
631
+ })
632
+ .delete("/api/vault/credentials/:connectionId/subjects/:kind/:subjectId", owner("direct"), (context) => {
633
+ const connectionId = context.req.param("connectionId");
634
+ const subject = subjectOf(context.req.param("kind"), context.req.param("subjectId"));
635
+ return !connectionIdPattern.test(connectionId) || subject === null
636
+ ? refusal(400, "invalid_input")
637
+ : answer({ op: "ungrantSecret", connectionId, subject });
638
+ })
639
+ .get("/api/vault/credentials/:connectionId/usage", owner("direct"), (context) => {
640
+ const connectionId = context.req.param("connectionId");
641
+ return connectionIdPattern.test(connectionId)
642
+ ? answer({ op: "usage", connectionId })
643
+ : refusal(404, "No such credential");
644
+ })
645
+ .get("/api/vault/model-keys/:keyId/usage", owner("direct"), (context) => {
646
+ const keyId = context.req.param("keyId");
647
+ return keyIdPattern.test(keyId)
648
+ ? answer({ op: "modelKeyUsage", keyId })
649
+ : refusal(404, "No such key");
528
650
  });
529
651
  }
530
652
  const connectionIdPattern = /^[A-Za-z0-9_.:-]{1,128}$/u;
@@ -5,6 +5,10 @@ import { type ConnectionAccess, type ConnectionAdded, type ConnectionInput, type
5
5
  type SecretGrantRefusal = ConnectionRefusal | Readonly<{
6
6
  error: "unsupported_subject";
7
7
  }>;
8
+ /** Why the Vault could not change a stored credential; never its value. */
9
+ export type CredentialRefusal = Readonly<{
10
+ error: "not_found" | "conflict" | "denied" | "invalid_input";
11
+ }>;
8
12
  /**
9
13
  * This instance's Agent MCP connections over Veil's connections core. The
10
14
  * owner holds every credential; an Agent receives a secret-free projection and
@@ -39,11 +43,27 @@ export declare function createAgentMcpConnections(options: {
39
43
  connectionId: string;
40
44
  }> | ConnectionRefusal>;
41
45
  secrets: () => Promise<readonly ConnectionView[]>;
46
+ credentials: () => Promise<readonly ConnectionView[]>;
47
+ updateCredential: (input: Readonly<{
48
+ connectionId: string;
49
+ expectedVersion: number;
50
+ label?: string | undefined;
51
+ destinations?: HttpDestinations | undefined;
52
+ secret?: string | undefined;
53
+ }>) => Promise<Readonly<{
54
+ version: number;
55
+ }> | CredentialRefusal>;
56
+ clearCredential: (input: Readonly<{
57
+ connectionId: string;
58
+ expectedVersion: number;
59
+ }>) => Promise<Readonly<{
60
+ version: number;
61
+ }> | CredentialRefusal>;
42
62
  grantSecret: (connectionId: string, subject: ConnectionSubject) => Promise<Readonly<{
43
63
  ok: true;
44
64
  }> | SecretGrantRefusal>;
45
65
  ungrantSecret: (connectionId: string, subject: ConnectionSubject) => Promise<void>;
46
- /** Every recorded use and refusal of one secret, without its value. */
66
+ /** Every recorded use and refusal of one credential, without its value. */
47
67
  secretUsage: (connectionId: string) => Promise<{
48
68
  readonly firstAt: number;
49
69
  readonly lastAt: number;
@@ -59,7 +79,7 @@ export declare function createAgentMcpConnections(options: {
59
79
  readonly pathTemplate: "/" | "/:segment" | "/:segment/\u2026";
60
80
  readonly pathLength: "short" | "medium" | "long";
61
81
  readonly method: "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "OTHER";
62
- readonly outcome: "placed" | "refused_destination" | "refused_grant" | "upstream_status";
82
+ readonly outcome: "placed" | "refused_destination" | "refused_grant" | "echo_redacted" | "upstream_status";
63
83
  readonly status: number | null;
64
84
  }[]>;
65
85
  /** Complete one request with a secret on the owner side; the caller names its subject. */
@@ -9,6 +9,24 @@ const ids = defineIdFamily({
9
9
  });
10
10
  /** The Oyster owner is the only actor that manages connections. */
11
11
  const owner = "owner";
12
+ const credentialRefusal = (cause) => {
13
+ if (cause instanceof ConnectionsError)
14
+ switch (cause.code) {
15
+ case "conflict":
16
+ return { error: "conflict" };
17
+ case "denied":
18
+ return { error: "denied" };
19
+ case "revoked":
20
+ case "pending":
21
+ return { error: "not_found" };
22
+ case "invalid_input":
23
+ case "unsupported":
24
+ return { error: "invalid_input" };
25
+ default:
26
+ break;
27
+ }
28
+ throw cause;
29
+ };
12
30
  /**
13
31
  * This instance's Agent MCP connections over Veil's connections core. The
14
32
  * owner holds every credential; an Agent receives a secret-free projection and
@@ -269,13 +287,79 @@ export function createAgentMcpConnections(options) {
269
287
  if (subject.kind === "agent")
270
288
  await options.notify(subject.id);
271
289
  }
290
+ /** Every live credential this instance holds, of every kind; never a value. */
291
+ async function credentials() {
292
+ return (await run(connections.list(owner))).filter((row) => row.state !== "revoked");
293
+ }
294
+ const live = async (connectionId) => (await credentials()).find((row) => row.connectionId === connectionId);
295
+ /**
296
+ * The Vault's one write path for a stored credential, write-only: rotate its
297
+ * value, rename it, rescope an HTTP secret, or give a Connection without one
298
+ * a bearer value. Grants stay; a widened secret needs its value re-entered.
299
+ */
300
+ async function updateCredential(input) {
301
+ const view = await live(input.connectionId);
302
+ if (view === undefined)
303
+ return { error: "not_found" };
304
+ // A signed-in Connection's tokens come from its sign-in, never a paste.
305
+ if (input.secret !== undefined && view.credential.kind === "oauth")
306
+ return { error: "invalid_input" };
307
+ try {
308
+ const done = await run(connections.update(owner, {
309
+ requestId: ids.connection.generate(),
310
+ connectionId: input.connectionId,
311
+ expectedVersion: input.expectedVersion,
312
+ label: input.label,
313
+ destinations: input.destinations,
314
+ // A rotation keeps the placement; a first value rides as a bearer.
315
+ credential: input.secret === undefined
316
+ ? undefined
317
+ : view.credential.kind === "static"
318
+ ? view.credential
319
+ : { kind: "static", placement: "bearer" },
320
+ secret: input.secret,
321
+ }));
322
+ await notifyHolders(view);
323
+ return { version: done.version };
324
+ }
325
+ catch (cause) {
326
+ return credentialRefusal(cause);
327
+ }
328
+ }
329
+ /** Take a Connection's pasted value out of custody; an HTTP secret is revoked whole instead. */
330
+ async function clearCredential(input) {
331
+ const view = await live(input.connectionId);
332
+ if (view === undefined)
333
+ return { error: "not_found" };
334
+ if (view.surface.kind === "http" || view.credential.kind !== "static")
335
+ return { error: "invalid_input" };
336
+ try {
337
+ const done = await run(connections.update(owner, {
338
+ requestId: ids.connection.generate(),
339
+ connectionId: input.connectionId,
340
+ expectedVersion: input.expectedVersion,
341
+ credential: { kind: "none" },
342
+ }));
343
+ await notifyHolders(view);
344
+ return { version: done.version };
345
+ }
346
+ catch (cause) {
347
+ return credentialRefusal(cause);
348
+ }
349
+ }
350
+ const notifyHolders = (view) => Promise.all(view.grants
351
+ .filter((grant) => grant.subject.kind === "agent")
352
+ .map((grant) => options.notify(grant.subject.id)));
272
353
  return {
273
354
  list,
274
355
  addSecret,
275
356
  secrets,
357
+ credentials,
358
+ updateCredential,
359
+ clearCredential,
276
360
  grantSecret,
277
361
  ungrantSecret,
278
- /** Every recorded use and refusal of one secret, without its value. */
362
+ /** Every recorded use and refusal of one credential, without its value. */
279
363
  secretUsage: (connectionId) => run(connections.audit(owner, connectionId)),
280
364
  /** Complete one request with a secret on the owner side; the caller names its subject. */
281
365
  fetchSecret: (subject, ref, data) => answerEgressRequest(connections.egress, subject, ref, data),
@@ -20,11 +20,15 @@ export type AiBinding = {
20
20
  import { type ComputerAttachmentInput } from "../agent-computers.js";
21
21
  import { type AgentComputerSnapshot, type AgentComputerConnection } from "../agent-computer-source.js";
22
22
  import { type StandaloneAgentComputerReply } from "./agent-computers.js";
23
- import { type ComputerGrant } from "@fungi.computer/computer/fleet";
23
+ import { type ComputerAction, type ComputerGrant } from "@fungi.computer/computer/fleet";
24
+ import { type VaultReferenceAdmission, type VaultSecretGrant } from "@fungi.computer/computer";
25
+ import type { VaultRequestData } from "@fungi.computer/computer/egress";
26
+ import type { ConnectionSubject, ConnectionUsage, HttpDestinations, Placement } from "@fungi.computer/veil/connections";
24
27
  import { DurableObject } from "cloudflare:workers";
25
28
  import { type StandaloneComputerEnv } from "./computer.js";
26
29
  import { ShiitakeDO } from "@fungi.computer/shiitake/cloudflare";
27
30
  import { type ModelKeyRecord, type ModelKeyRefusal, type ModelKeySealInput } from "./model-key-vault.js";
31
+ import type { VaultCommand, VaultResult } from "./vault.js";
28
32
  import type { CloudflareShiitakeOptions } from "@fungi.computer/shiitake/cloudflare";
29
33
  import { type AgentModelChoice, type AgentModelRefusal } from "./agent-model-choice.js";
30
34
  import * as Schema from "effect/Schema";
@@ -64,6 +68,8 @@ export type StandaloneAgentsEnv = Readonly<{
64
68
  OYSTER_WEBSITE_PROOF_KEY?: string;
65
69
  /** Configured standalone-owner identity subject; never a stored member ID. */
66
70
  OYSTER_OWNER_NAME?: string;
71
+ /** The host's own configured Computer; the starter's Home when it is there. */
72
+ OYSTER_COMPUTER_ID?: string;
67
73
  /** Gateway custody remains in Veil; only the host receives these bindings. */
68
74
  AI_GATEWAY_AUTH_TOKEN?: string;
69
75
  AI_GATEWAY_ACCOUNT_ID?: string;
@@ -288,6 +294,24 @@ export declare abstract class StandaloneAgentBase<Env extends StandaloneAgentEnv
288
294
  }>>;
289
295
  /** Secret-free default of this Agent; stored separately from Session history. */
290
296
  readModelChoice(): Promise<AgentModelChoice>;
297
+ /**
298
+ * Keep the starter's setup prompt on this Agent while it has no Home to hold
299
+ * an AGENTS.md. Written once; Agents that never needed it have no such key.
300
+ * `actor` is the owner whose grant later writes it into a Home.
301
+ */
302
+ seedFirstConversation(content: string, actor: string): Promise<void>;
303
+ /** The instructions every run of this Agent starts from. */
304
+ protected agentInstructions(): Promise<{
305
+ revision: string;
306
+ text: string;
307
+ }>;
308
+ /**
309
+ * The kept setup prompt, until a Home exists. Then it moves into that Home's
310
+ * AGENTS.md when the Home has none (the starter seed's rule), so an
311
+ * interview that gains a Home midway keeps its instructions, and the kept
312
+ * copy is dropped. A Home that already has an AGENTS.md is left as it is.
313
+ */
314
+ private firstConversation;
291
315
  setModelChoice(input: AgentModelChoice): Promise<AgentModelChoice | Readonly<{
292
316
  error: AgentModelRefusal;
293
317
  }>>;
@@ -336,6 +360,17 @@ export declare abstract class StandaloneAgentBase<Env extends StandaloneAgentEnv
336
360
  inboxRows(): Promise<AgentInboxRows>;
337
361
  }
338
362
  /** Names this Oyster's agents and remembers which Sessions the member opened. */
363
+ /**
364
+ * An admitted Agent Computer call as it crosses the directory's RPC boundary:
365
+ * plain data, which the Agent turns into its fleet grant with the Vault
366
+ * context of the directory that admitted it.
367
+ */
368
+ export type AdmittedAgentComputer = Readonly<{
369
+ computerId: string;
370
+ actions: readonly ComputerAction[];
371
+ expiresAt: number;
372
+ provenance: ComputerGrant["provenance"];
373
+ }>;
339
374
  export declare class AgentDirectory extends DurableObject<StandaloneAgentEnv> {
340
375
  private archiveProjectionOwner;
341
376
  private archiveProjection;
@@ -363,9 +398,15 @@ export declare class AgentDirectory extends DurableObject<StandaloneAgentEnv> {
363
398
  method: string;
364
399
  headers: readonly (readonly [string, string])[];
365
400
  body: string | null;
366
- }>): Promise<Response | Readonly<{
401
+ }>,
402
+ /** The Agent the use is audited to; never its prompt or reply. */
403
+ agentId?: string | null): Promise<Response | Readonly<{
367
404
  error: ModelKeyRefusal;
368
405
  }>>;
406
+ private modelKeyUsageOwner;
407
+ private modelKeyUsage;
408
+ /** The Vault page's one owner door: every stored credential, write-only. */
409
+ vault(command: VaultCommand): Promise<VaultResult>;
369
410
  private redactionSet;
370
411
  /**
371
412
  * Host-only: fingerprints of every credential this directory stores (model
@@ -395,10 +436,10 @@ export declare class AgentDirectory extends DurableObject<StandaloneAgentEnv> {
395
436
  }>[];
396
437
  }>[]>;
397
438
  addConnection(input: ConnectionInput): Promise<Readonly<{
439
+ error: "not_found" | "duplicate_name" | "limit" | "invalid_endpoint";
440
+ }> | Readonly<{
398
441
  connectionId: string;
399
442
  authorizeUrl: string | null;
400
- }> | Readonly<{
401
- error: "not_found" | "duplicate_name" | "limit" | "invalid_endpoint";
402
443
  }>>;
403
444
  grantConnection(connectionId: string, agentId: string, access: ConnectionAccess): Promise<Readonly<{
404
445
  error: "not_found" | "duplicate_name" | "limit" | "invalid_endpoint";
@@ -407,6 +448,30 @@ export declare class AgentDirectory extends DurableObject<StandaloneAgentEnv> {
407
448
  }>>;
408
449
  ungrantConnection(connectionId: string, agentId: string): Promise<boolean>;
409
450
  removeConnection(connectionId: string): Promise<boolean>;
451
+ /** Host-only: save one Vault secret bound to exact destinations. */
452
+ addSecret(input: Readonly<{
453
+ name: string;
454
+ destinations: HttpDestinations;
455
+ placement: Placement;
456
+ secret: string;
457
+ }>): Promise<Readonly<{
458
+ connectionId: string;
459
+ }> | Readonly<{
460
+ error: string;
461
+ }>>;
462
+ grantSecret(connectionId: string, subject: ConnectionSubject): Promise<Readonly<{
463
+ ok: true;
464
+ }> | Readonly<{
465
+ error: string;
466
+ }>>;
467
+ ungrantSecret(connectionId: string, subject: ConnectionSubject): Promise<void>;
468
+ secretUsage(connectionId: string): Promise<readonly ConnectionUsage[]>;
469
+ /** A Computer opening one Agent command: which secrets it holds now; never a value. */
470
+ computerVaultGrants(agentId: string): Promise<readonly VaultSecretGrant[]>;
471
+ /** The Computer gateway's Vault lane: one resolved reference's request, sent here. */
472
+ sendComputerVault(admission: VaultReferenceAdmission, data: VaultRequestData): Promise<Response | Readonly<{
473
+ error: string;
474
+ }>>;
410
475
  connectionTools(connectionId: string): Promise<readonly string[] | Readonly<{
411
476
  error: "not_found" | "duplicate_name" | "limit" | "invalid_endpoint";
412
477
  }>>;
@@ -494,7 +559,7 @@ export declare class AgentDirectory extends DurableObject<StandaloneAgentEnv> {
494
559
  /** The owner HTTP read uses the same projection as direct discovery. */
495
560
  readAgentComputers(agentId: string, principal: TenantPrincipal, tenantId?: TenantId): Promise<StandaloneAgentComputerReply>;
496
561
  /** Every captured native call rechecks the exact live attachment and credential owner. */
497
- admitAgentComputer(captured: Pick<AgentComputerConnection, "scopeId" | "agentId" | "attachment">, tenantId: TenantId): Promise<Omit<ComputerGrant, "egress">>;
562
+ admitAgentComputer(captured: Pick<AgentComputerConnection, "scopeId" | "agentId" | "attachment">, tenantId: TenantId): Promise<AdmittedAgentComputer>;
498
563
  private websiteChannelsOwner;
499
564
  private websites;
500
565
  /** Owner read of every website bound to one of this tenant's Agents. */