@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.
- package/dist/agents.d.ts +6 -0
- package/dist/agents.js +122 -0
- package/dist/standalone/agent-connections.d.ts +21 -1
- package/dist/standalone/agent-connections.js +85 -1
- package/dist/standalone/agents.d.ts +30 -3
- package/dist/standalone/agents.js +118 -28
- package/dist/standalone/model-key-usage.d.ts +28 -0
- package/dist/standalone/model-key-usage.js +70 -0
- package/dist/standalone/vault.d.ts +84 -0
- package/dist/standalone/vault.js +64 -0
- package/docs/api/agents.md +167 -3
- package/docs/api/workers-git.md +7 -7
- package/package.json +6 -6
|
@@ -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
|
+
}
|
package/docs/api/agents.md
CHANGED
|
@@ -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
|
-
|
|
387
|
-
authorizeUrl: string | null;
|
|
387
|
+
error: "not_found" | "duplicate_name" | "limit" | "invalid_endpoint";
|
|
388
388
|
}>
|
|
389
389
|
| Readonly<{
|
|
390
|
-
|
|
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
|