@fungi.computer/oyster 0.44.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.
@@ -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