@fungi.computer/oyster 0.47.1 → 0.47.2
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 +3 -1
- package/dist/agents.js +3 -1
- package/dist/standalone/agents.d.ts +1 -0
- package/dist/standalone/agents.js +13 -5
- package/dist/starter-agent.d.ts +94 -6
- package/dist/starter-agent.js +229 -41
- package/docs/api/agents.md +5 -1
- package/package.json +1 -1
package/dist/agents.d.ts
CHANGED
|
@@ -126,8 +126,10 @@ export type OysterAgents = Readonly<{
|
|
|
126
126
|
/**
|
|
127
127
|
* Offer the owner their starter Agent on an empty Team's first owner read;
|
|
128
128
|
* it creates through this host's ordinary `create` and never fails the read.
|
|
129
|
+
* Work the read does not wait for is handed to `keepAlive` (the Worker's
|
|
130
|
+
* `waitUntil`), so it outlives the response.
|
|
129
131
|
*/
|
|
130
|
-
ensureStarter(principal: TenantPrincipal): Promise<StarterOutcome>;
|
|
132
|
+
ensureStarter(principal: TenantPrincipal, keepAlive?: (work: Promise<unknown>) => void): Promise<StarterOutcome>;
|
|
131
133
|
/** Owner-only HTTP transition; creator Agents use their own control tool. */
|
|
132
134
|
setArchived(agentId: string, archived: boolean, principal: TenantPrincipal): Promise<Readonly<{
|
|
133
135
|
archived: boolean;
|
package/dist/agents.js
CHANGED
|
@@ -222,7 +222,9 @@ function createAgentRoutes(agents) {
|
|
|
222
222
|
return refusal(400, "Choose a valid archive view");
|
|
223
223
|
// The owner's own directory read is the starter Agent's one trigger.
|
|
224
224
|
if (everyAgent && authority.kind === "owner" && selected !== "true")
|
|
225
|
-
await agents.ensureStarter(authority.principal)
|
|
225
|
+
await agents.ensureStarter(authority.principal, (work) => {
|
|
226
|
+
context.executionCtx.waitUntil(work);
|
|
227
|
+
});
|
|
226
228
|
const listed = await agents.list({ archived: selected === "true" });
|
|
227
229
|
const reached = [];
|
|
228
230
|
for (const item of listed)
|
|
@@ -623,6 +623,7 @@ export declare class AgentDirectory extends DurableObject<StandaloneAgentEnv> {
|
|
|
623
623
|
/** The starter Agent's one-row ledger and the Agent total it reads, for the owner's ensure. */
|
|
624
624
|
readStarter(): StarterLedgerRow | undefined;
|
|
625
625
|
recordStarter(row: StarterLedgerRow): void;
|
|
626
|
+
forgetStarter(): void;
|
|
626
627
|
/** Every Agent in the directory, archived ones included. */
|
|
627
628
|
agentTotal(): number;
|
|
628
629
|
/** Resolve the existing recorded creator for host-side owner admission. */
|
|
@@ -2400,6 +2400,9 @@ export class AgentDirectory extends DurableObject {
|
|
|
2400
2400
|
recordStarter(row) {
|
|
2401
2401
|
this.starterLedger.record(row);
|
|
2402
2402
|
}
|
|
2403
|
+
forgetStarter() {
|
|
2404
|
+
this.starterLedger.forget();
|
|
2405
|
+
}
|
|
2403
2406
|
/** Every Agent in the directory, archived ones included. */
|
|
2404
2407
|
agentTotal() {
|
|
2405
2408
|
return this.directory.list(this.grant()).length;
|
|
@@ -2714,6 +2717,13 @@ export function standaloneAgents(env, scope) {
|
|
|
2714
2717
|
const directory = () => scope === undefined
|
|
2715
2718
|
? env.AGENT_DIRECTORY.getByName(directoryName)
|
|
2716
2719
|
: agentDirectoryForScope(env, scope);
|
|
2720
|
+
// The starter's state lives in the directory's storage: this adapter is
|
|
2721
|
+
// rebuilt for every Worker request, so it remembers nothing itself.
|
|
2722
|
+
const starterLedger = {
|
|
2723
|
+
read: () => directory().readStarter(),
|
|
2724
|
+
record: (row) => directory().recordStarter(row),
|
|
2725
|
+
forget: () => directory().forgetStarter(),
|
|
2726
|
+
};
|
|
2717
2727
|
const toAgent = (entry) => ({
|
|
2718
2728
|
agentId: entry.agentId,
|
|
2719
2729
|
name: entry.name,
|
|
@@ -2749,7 +2759,7 @@ export function standaloneAgents(env, scope) {
|
|
|
2749
2759
|
return agent.setArchived(archived);
|
|
2750
2760
|
},
|
|
2751
2761
|
create: created,
|
|
2752
|
-
ensureStarter: (principal) => {
|
|
2762
|
+
ensureStarter: (principal, keepAlive) => {
|
|
2753
2763
|
const owner = directory();
|
|
2754
2764
|
const reportStarterFailure = (cause) => {
|
|
2755
2765
|
void redactedFailure(cause).then((text) => {
|
|
@@ -2757,10 +2767,8 @@ export function standaloneAgents(env, scope) {
|
|
|
2757
2767
|
});
|
|
2758
2768
|
};
|
|
2759
2769
|
return ensureStarterAgent({
|
|
2760
|
-
ledger:
|
|
2761
|
-
|
|
2762
|
-
record: (row) => owner.recordStarter(row),
|
|
2763
|
-
},
|
|
2770
|
+
ledger: starterLedger,
|
|
2771
|
+
keepAlive,
|
|
2764
2772
|
isOwner: () => oysterPrincipalIsOwner(principal),
|
|
2765
2773
|
agentCount: () => owner.agentTotal(),
|
|
2766
2774
|
// The ordinary create, then the ordinary owner attach of the host's own
|
package/dist/starter-agent.d.ts
CHANGED
|
@@ -17,23 +17,45 @@ export declare const starterAgent: {
|
|
|
17
17
|
export declare function seedStarterHome(
|
|
18
18
|
/** Where this host keeps Home's AGENTS.md. */
|
|
19
19
|
instructionsPath: string, writeIfMissing: (path: string, content: string) => Promise<void>): Promise<void>;
|
|
20
|
-
/**
|
|
20
|
+
/** Why the last create or Home seed attempt failed, in plain words. */
|
|
21
|
+
export type StarterFailure = Readonly<{
|
|
22
|
+
reason: string;
|
|
23
|
+
at: number;
|
|
24
|
+
}>;
|
|
25
|
+
/**
|
|
26
|
+
* What the ledger remembers, durably, so a restart or a fresh Worker request
|
|
27
|
+
* resumes the starter instead of forgetting it. `creating` is recorded before
|
|
28
|
+
* the create starts, so a create cut off after reserving the Agent is replayed
|
|
29
|
+
* by its `requestId`, never read as a Team that already had Agents.
|
|
30
|
+
* `seed-pending` means the starter exists but its Home is not seeded yet.
|
|
31
|
+
* `attemptAt` is when the running attempt started: within the bound it is
|
|
32
|
+
* still running somewhere; past it, with no `failure`, it was cut off.
|
|
33
|
+
*/
|
|
21
34
|
export type StarterLedgerRow = Readonly<{
|
|
22
35
|
version: number;
|
|
23
|
-
outcome: "seed-pending" | "created" | "team-not-empty";
|
|
36
|
+
outcome: "creating" | "seed-pending" | "created" | "team-not-empty";
|
|
24
37
|
agentId: string | null;
|
|
25
38
|
at: number;
|
|
39
|
+
attemptAt: number | null;
|
|
40
|
+
failure: StarterFailure | null;
|
|
26
41
|
}>;
|
|
27
42
|
/** One row per Team in the host's own SQLite. */
|
|
28
43
|
export type StarterLedgerStore = Readonly<{
|
|
29
44
|
read(): StarterLedgerRow | undefined;
|
|
30
|
-
/**
|
|
45
|
+
/**
|
|
46
|
+
* First write wins. Afterwards only an unsettled starter moves on: a
|
|
47
|
+
* `creating` row to its next attempt, `seed-pending` or `created`; a
|
|
48
|
+
* `seed-pending` row to its next attempt or `created`, for the same Agent.
|
|
49
|
+
*/
|
|
31
50
|
record(row: StarterLedgerRow): void;
|
|
51
|
+
/** Drop a `creating` row whose create was refused for funding. */
|
|
52
|
+
forget(): void;
|
|
32
53
|
}>;
|
|
33
54
|
/** The ledger as the policy reads it; a host across an RPC awaits its store. */
|
|
34
55
|
export type StarterLedger = Readonly<{
|
|
35
56
|
read(): StarterLedgerRow | undefined | Promise<StarterLedgerRow | undefined>;
|
|
36
57
|
record(row: StarterLedgerRow): void | Promise<void>;
|
|
58
|
+
forget(): void | Promise<void>;
|
|
37
59
|
}>;
|
|
38
60
|
/** The host's ordinary create, as the starter sees it. */
|
|
39
61
|
export type StarterCreateResult = Readonly<{
|
|
@@ -53,19 +75,85 @@ export type StarterAgentHost = Readonly<{
|
|
|
53
75
|
name: string;
|
|
54
76
|
requestId: string;
|
|
55
77
|
}): Promise<StarterCreateResult>;
|
|
56
|
-
/**
|
|
78
|
+
/**
|
|
79
|
+
* Hosts with a Home seed it atomically. The seed runs in the background,
|
|
80
|
+
* bounded by `timeoutMs`; a failure leaves a retryable ledger row.
|
|
81
|
+
*/
|
|
57
82
|
seedHome?(agentId: string): Promise<void>;
|
|
83
|
+
/**
|
|
84
|
+
* Keep background work alive after the read answers: a stateless Worker
|
|
85
|
+
* passes its `waitUntil`. A host whose process outlives the read omits it;
|
|
86
|
+
* work cut off anyway is resumed from the ledger by a later offer.
|
|
87
|
+
*/
|
|
88
|
+
keepAlive?: ((work: Promise<unknown>) => void) | undefined;
|
|
89
|
+
/** How long the create or one Home seed may take before it counts as failed; default 60 s. */
|
|
90
|
+
timeoutMs?: number;
|
|
91
|
+
/** How long a read waits for the create before answering `starting`; default 5 s. */
|
|
92
|
+
readWaitMs?: number;
|
|
93
|
+
/**
|
|
94
|
+
* Whether this offer starts a create or seed that last failed again (the
|
|
95
|
+
* default). A status read passes false, so a failure stays visible until a
|
|
96
|
+
* retry. An attempt that was cut off is always resumed.
|
|
97
|
+
*/
|
|
98
|
+
retryFailedSeed?: boolean;
|
|
99
|
+
/**
|
|
100
|
+
* Why the create or seed failed, in plain words for the owner, completing
|
|
101
|
+
* "Your Computer didn't start: ...". One that ran out of time arrives as a
|
|
102
|
+
* `StarterTimeout`.
|
|
103
|
+
*/
|
|
104
|
+
describeSeedFailure?(cause: unknown): string;
|
|
58
105
|
/** Where a failed attempt is reported; the caller's read never fails. */
|
|
59
106
|
report?(cause: unknown): void;
|
|
60
107
|
now?(): number;
|
|
61
108
|
}>;
|
|
62
|
-
/**
|
|
63
|
-
export
|
|
109
|
+
/** The default bound on the starter's create and on one Home seed. */
|
|
110
|
+
export declare const starterTimeoutMs = 60000;
|
|
111
|
+
/** The default time a read waits for the starter's create. */
|
|
112
|
+
export declare const starterReadWaitMs = 5000;
|
|
113
|
+
/** A create or Home seed that did not finish within its bound. */
|
|
114
|
+
export declare class StarterTimeout extends Error {
|
|
115
|
+
readonly timeoutMs: number;
|
|
116
|
+
constructor(timeoutMs: number);
|
|
117
|
+
}
|
|
118
|
+
/**
|
|
119
|
+
* Where the starter stands, for the owner's first run: `starting` while its
|
|
120
|
+
* create runs (or is owed), `seeding` while its Home seed runs (or is owed),
|
|
121
|
+
* `failed` with the plain reason of the last attempt (`agentId` null when the
|
|
122
|
+
* create itself failed), `ready` once seeded, `none` when there is no starter.
|
|
123
|
+
*/
|
|
124
|
+
export type StarterSeedStatus = Readonly<{
|
|
125
|
+
state: "none";
|
|
126
|
+
}> | Readonly<{
|
|
127
|
+
state: "starting";
|
|
128
|
+
}> | Readonly<{
|
|
129
|
+
state: "seeding";
|
|
130
|
+
agentId: string;
|
|
131
|
+
}> | Readonly<{
|
|
132
|
+
state: "ready";
|
|
133
|
+
agentId: string;
|
|
134
|
+
}> | Readonly<{
|
|
135
|
+
state: "failed";
|
|
136
|
+
agentId: string | null;
|
|
137
|
+
reason: string;
|
|
138
|
+
at: number;
|
|
139
|
+
}>;
|
|
140
|
+
/**
|
|
141
|
+
* How one offer of the starter Agent settled. `created` and `seeding` both
|
|
142
|
+
* mean the Agent exists; `seeding` means its Home seed is still running;
|
|
143
|
+
* `starting` means its create is still running.
|
|
144
|
+
*/
|
|
145
|
+
export type StarterOutcome = "created" | "seeding" | "starting" | "already-offered" | "team-not-empty" | "unfunded" | "not-owner" | "failed";
|
|
64
146
|
/** Open the one-row ledger in the host's own SQLite. */
|
|
65
147
|
export declare function createStarterLedger(sql: WatchdogSqliteOwner["sql"]): StarterLedgerStore;
|
|
66
148
|
/**
|
|
67
149
|
* Offer the starter Agent if this Team never had its chance. Safe to call on
|
|
68
150
|
* every owner directory read: concurrent calls share one attempt, and the
|
|
69
151
|
* host's `requestId` replay makes a second attempt return the same Agent.
|
|
152
|
+
* It waits at most `readWaitMs` for the create and never for the Home seed:
|
|
153
|
+
* both run on in the background, bounded, and `starterSeedStatus` says how
|
|
154
|
+
* they went. Everything it knows is in the ledger, so an attempt cut off by
|
|
155
|
+
* a restart is resumed by the next offer once its bound has passed.
|
|
70
156
|
*/
|
|
71
157
|
export declare function ensureStarterAgent(host: StarterAgentHost): Promise<StarterOutcome>;
|
|
158
|
+
/** Where the starter stands, read from the ledger alone. */
|
|
159
|
+
export declare function starterSeedStatus(ledger: StarterLedger): Promise<StarterSeedStatus>;
|
package/dist/starter-agent.js
CHANGED
|
@@ -45,19 +45,48 @@ work and where it lives on my Computer, how they like updates.)
|
|
|
45
45
|
- Never save secrets, keys, passwords or payment details here.
|
|
46
46
|
- Keep this file under 200 lines; tidy it when it grows.
|
|
47
47
|
`;
|
|
48
|
+
/** The default bound on the starter's create and on one Home seed. */
|
|
49
|
+
export const starterTimeoutMs = 60_000;
|
|
50
|
+
/** The default time a read waits for the starter's create. */
|
|
51
|
+
export const starterReadWaitMs = 5_000;
|
|
52
|
+
/** A create or Home seed that did not finish within its bound. */
|
|
53
|
+
export class StarterTimeout extends Error {
|
|
54
|
+
timeoutMs;
|
|
55
|
+
constructor(timeoutMs) {
|
|
56
|
+
const seconds = Math.max(1, Math.round(timeoutMs / 1000));
|
|
57
|
+
super(`it did not answer within ${String(seconds)} second${seconds === 1 ? "" : "s"}`);
|
|
58
|
+
this.timeoutMs = timeoutMs;
|
|
59
|
+
this.name = "StarterTimeout";
|
|
60
|
+
}
|
|
61
|
+
}
|
|
48
62
|
const ledgerRowSchema = z.strictObject({
|
|
49
63
|
version: z.number().int(),
|
|
50
|
-
outcome: z.enum(["seed-pending", "created", "team-not-empty"]),
|
|
64
|
+
outcome: z.enum(["creating", "seed-pending", "created", "team-not-empty"]),
|
|
51
65
|
agent_id: z.string().nullable(),
|
|
52
66
|
at: z.number(),
|
|
67
|
+
attempt_at: z.number().nullable(),
|
|
68
|
+
failure_reason: z.string().nullable(),
|
|
69
|
+
failure_at: z.number().nullable(),
|
|
53
70
|
});
|
|
71
|
+
const ledgerColumnsSchema = z.array(z.object({ name: z.string() }));
|
|
54
72
|
/** Open the one-row ledger in the host's own SQLite. */
|
|
55
73
|
export function createStarterLedger(sql) {
|
|
56
|
-
sql.exec("CREATE TABLE IF NOT EXISTS starter_agent (id INTEGER PRIMARY KEY CHECK (id = 1), version INTEGER NOT NULL, outcome TEXT NOT NULL, agent_id TEXT, at INTEGER NOT NULL) STRICT");
|
|
74
|
+
sql.exec("CREATE TABLE IF NOT EXISTS starter_agent (id INTEGER PRIMARY KEY CHECK (id = 1), version INTEGER NOT NULL, outcome TEXT NOT NULL, agent_id TEXT, at INTEGER NOT NULL, attempt_at INTEGER, failure_reason TEXT, failure_at INTEGER) STRICT");
|
|
75
|
+
// A ledger stored before attempts were durable has none of their columns.
|
|
76
|
+
const columns = new Set(ledgerColumnsSchema
|
|
77
|
+
.parse(sql.exec("PRAGMA table_info(starter_agent)").toArray())
|
|
78
|
+
.map(({ name }) => name));
|
|
79
|
+
for (const [column, type] of [
|
|
80
|
+
["attempt_at", "INTEGER"],
|
|
81
|
+
["failure_reason", "TEXT"],
|
|
82
|
+
["failure_at", "INTEGER"],
|
|
83
|
+
])
|
|
84
|
+
if (!columns.has(column))
|
|
85
|
+
sql.exec(`ALTER TABLE starter_agent ADD COLUMN ${column} ${type}`);
|
|
57
86
|
return {
|
|
58
87
|
read() {
|
|
59
88
|
const row = sql
|
|
60
|
-
.exec("SELECT version, outcome, agent_id, at FROM starter_agent WHERE id = 1")
|
|
89
|
+
.exec("SELECT version, outcome, agent_id, at, attempt_at, failure_reason, failure_at FROM starter_agent WHERE id = 1")
|
|
61
90
|
.toArray()[0];
|
|
62
91
|
if (row === undefined)
|
|
63
92
|
return undefined;
|
|
@@ -67,10 +96,17 @@ export function createStarterLedger(sql) {
|
|
|
67
96
|
outcome: stored.outcome,
|
|
68
97
|
agentId: stored.agent_id,
|
|
69
98
|
at: stored.at,
|
|
99
|
+
attemptAt: stored.attempt_at,
|
|
100
|
+
failure: stored.failure_reason === null || stored.failure_at === null
|
|
101
|
+
? null
|
|
102
|
+
: { reason: stored.failure_reason, at: stored.failure_at },
|
|
70
103
|
};
|
|
71
104
|
},
|
|
72
105
|
record(row) {
|
|
73
|
-
sql.exec("INSERT INTO starter_agent(id, version, outcome, agent_id, at) VALUES(1, ?, ?, ?, ?) ON CONFLICT(id) DO UPDATE SET outcome = excluded.outcome WHERE starter_agent.outcome = 'seed-pending' AND excluded.outcome
|
|
106
|
+
sql.exec("INSERT INTO starter_agent(id, version, outcome, agent_id, at, attempt_at, failure_reason, failure_at) VALUES(1, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT(id) DO UPDATE SET outcome = excluded.outcome, agent_id = excluded.agent_id, attempt_at = excluded.attempt_at, failure_reason = excluded.failure_reason, failure_at = excluded.failure_at WHERE (starter_agent.outcome = 'creating' AND excluded.outcome IN ('creating', 'seed-pending', 'created')) OR (starter_agent.outcome = 'seed-pending' AND excluded.outcome IN ('seed-pending', 'created') AND starter_agent.agent_id = excluded.agent_id)", row.version, row.outcome, row.agentId, row.at, row.attemptAt, row.failure?.reason ?? null, row.failure?.at ?? null);
|
|
107
|
+
},
|
|
108
|
+
forget() {
|
|
109
|
+
sql.exec("DELETE FROM starter_agent WHERE outcome = 'creating'");
|
|
74
110
|
},
|
|
75
111
|
};
|
|
76
112
|
}
|
|
@@ -79,6 +115,10 @@ const inFlight = new WeakMap();
|
|
|
79
115
|
* Offer the starter Agent if this Team never had its chance. Safe to call on
|
|
80
116
|
* every owner directory read: concurrent calls share one attempt, and the
|
|
81
117
|
* host's `requestId` replay makes a second attempt return the same Agent.
|
|
118
|
+
* It waits at most `readWaitMs` for the create and never for the Home seed:
|
|
119
|
+
* both run on in the background, bounded, and `starterSeedStatus` says how
|
|
120
|
+
* they went. Everything it knows is in the ledger, so an attempt cut off by
|
|
121
|
+
* a restart is resumed by the next offer once its bound has passed.
|
|
82
122
|
*/
|
|
83
123
|
export function ensureStarterAgent(host) {
|
|
84
124
|
const running = inFlight.get(host.ledger);
|
|
@@ -88,55 +128,203 @@ export function ensureStarterAgent(host) {
|
|
|
88
128
|
inFlight.set(host.ledger, attempt);
|
|
89
129
|
return attempt;
|
|
90
130
|
}
|
|
131
|
+
/** Where the starter stands, read from the ledger alone. */
|
|
132
|
+
export async function starterSeedStatus(ledger) {
|
|
133
|
+
const row = await ledger.read();
|
|
134
|
+
if (row === undefined || row.outcome === "team-not-empty")
|
|
135
|
+
return { state: "none" };
|
|
136
|
+
const { agentId, failure } = row;
|
|
137
|
+
if (row.outcome === "creating")
|
|
138
|
+
return failure === null
|
|
139
|
+
? { state: "starting" }
|
|
140
|
+
: { state: "failed", agentId: null, ...failure };
|
|
141
|
+
if (agentId === null)
|
|
142
|
+
return { state: "none" };
|
|
143
|
+
if (row.outcome === "created")
|
|
144
|
+
return { state: "ready", agentId };
|
|
145
|
+
return failure === null
|
|
146
|
+
? { state: "seeding", agentId }
|
|
147
|
+
: { state: "failed", agentId, ...failure };
|
|
148
|
+
}
|
|
149
|
+
function withDeadline(work, timeoutMs) {
|
|
150
|
+
let timer;
|
|
151
|
+
let expired = false;
|
|
152
|
+
const deadline = new Promise((_, reject) => {
|
|
153
|
+
timer = setTimeout(() => {
|
|
154
|
+
expired = true;
|
|
155
|
+
reject(new StarterTimeout(timeoutMs));
|
|
156
|
+
}, timeoutMs);
|
|
157
|
+
});
|
|
158
|
+
const bounded = Promise.race([work, deadline]).finally(() => {
|
|
159
|
+
clearTimeout(timer);
|
|
160
|
+
});
|
|
161
|
+
return { bounded, timedOut: () => expired };
|
|
162
|
+
}
|
|
163
|
+
function describe(host, cause) {
|
|
164
|
+
if (host.describeSeedFailure !== undefined)
|
|
165
|
+
return host.describeSeedFailure(cause);
|
|
166
|
+
return cause instanceof Error
|
|
167
|
+
? cause.message
|
|
168
|
+
: "the Computer did not say why";
|
|
169
|
+
}
|
|
170
|
+
/** Record why `attempt` failed; a row that has moved on since keeps its state. */
|
|
171
|
+
async function fail(host, attempt, cause) {
|
|
172
|
+
host.report?.(cause);
|
|
173
|
+
await host.ledger.record({
|
|
174
|
+
...attempt,
|
|
175
|
+
failure: { reason: describe(host, cause), at: (host.now ?? Date.now)() },
|
|
176
|
+
});
|
|
177
|
+
}
|
|
178
|
+
/** Whether `row`'s attempt may still be running somewhere. */
|
|
179
|
+
function attemptLive(host, row) {
|
|
180
|
+
return (row.failure === null &&
|
|
181
|
+
row.attemptAt !== null &&
|
|
182
|
+
(host.now ?? Date.now)() <
|
|
183
|
+
row.attemptAt + (host.timeoutMs ?? starterTimeoutMs));
|
|
184
|
+
}
|
|
185
|
+
/**
|
|
186
|
+
* Run `work` within the bound: on success `done` records the result; on
|
|
187
|
+
* failure the attempt's row records why. The read never awaits it.
|
|
188
|
+
*/
|
|
189
|
+
function runBounded(host, attempt, work) {
|
|
190
|
+
const { bounded, timedOut } = withDeadline(work, host.timeoutMs ?? starterTimeoutMs);
|
|
191
|
+
const settled = bounded.then((value) => value, async (cause) => {
|
|
192
|
+
try {
|
|
193
|
+
await fail(host, attempt, cause);
|
|
194
|
+
}
|
|
195
|
+
catch (recordCause) {
|
|
196
|
+
// Reported; the attempt's row stays live until its bound passes.
|
|
197
|
+
host.report?.(recordCause);
|
|
198
|
+
}
|
|
199
|
+
return "failed";
|
|
200
|
+
});
|
|
201
|
+
// Work that outlives its bound may still finish and record its result; one
|
|
202
|
+
// that fails after its timeout was recorded is reported too.
|
|
203
|
+
const late = work.catch((cause) => {
|
|
204
|
+
if (timedOut())
|
|
205
|
+
host.report?.(cause);
|
|
206
|
+
});
|
|
207
|
+
host.keepAlive?.(Promise.all([settled, late]));
|
|
208
|
+
return settled;
|
|
209
|
+
}
|
|
210
|
+
/** Start the Home seed for an existing starter, recording the attempt first. */
|
|
211
|
+
async function startSeed(host, seedHome, row, agentId) {
|
|
212
|
+
const attempt = {
|
|
213
|
+
...row,
|
|
214
|
+
outcome: "seed-pending",
|
|
215
|
+
agentId,
|
|
216
|
+
attemptAt: (host.now ?? Date.now)(),
|
|
217
|
+
failure: null,
|
|
218
|
+
};
|
|
219
|
+
await host.ledger.record(attempt);
|
|
220
|
+
const seeded = Promise.resolve()
|
|
221
|
+
.then(() => seedHome(agentId))
|
|
222
|
+
.then(() => host.ledger.record({ ...attempt, outcome: "created" }));
|
|
223
|
+
void runBounded(host, attempt, seeded);
|
|
224
|
+
}
|
|
225
|
+
/**
|
|
226
|
+
* Record the `creating` attempt, then run the host's create with its
|
|
227
|
+
* continuation attached, so a create that lands after a read stopped waiting
|
|
228
|
+
* still records the starter and seeds it.
|
|
229
|
+
*/
|
|
230
|
+
async function startCreate(host, row) {
|
|
231
|
+
const attempt = {
|
|
232
|
+
...row,
|
|
233
|
+
outcome: "creating",
|
|
234
|
+
agentId: null,
|
|
235
|
+
attemptAt: (host.now ?? Date.now)(),
|
|
236
|
+
failure: null,
|
|
237
|
+
};
|
|
238
|
+
await host.ledger.record(attempt);
|
|
239
|
+
const landed = Promise.resolve()
|
|
240
|
+
.then(() => host.create({
|
|
241
|
+
name: starterAgent.name,
|
|
242
|
+
requestId: starterAgent.requestId,
|
|
243
|
+
}))
|
|
244
|
+
.then(async (result) => {
|
|
245
|
+
if (result.status === "unfunded") {
|
|
246
|
+
await host.ledger.forget();
|
|
247
|
+
return "unfunded";
|
|
248
|
+
}
|
|
249
|
+
if (host.seedHome === undefined) {
|
|
250
|
+
await host.ledger.record({
|
|
251
|
+
...attempt,
|
|
252
|
+
outcome: "created",
|
|
253
|
+
agentId: result.agentId,
|
|
254
|
+
attemptAt: null,
|
|
255
|
+
});
|
|
256
|
+
return "created";
|
|
257
|
+
}
|
|
258
|
+
await startSeed(host, host.seedHome, attempt, result.agentId);
|
|
259
|
+
return "seeding";
|
|
260
|
+
});
|
|
261
|
+
return runBounded(host, attempt, landed);
|
|
262
|
+
}
|
|
91
263
|
async function settle(host) {
|
|
92
264
|
try {
|
|
93
265
|
if (!host.isOwner())
|
|
94
266
|
return "not-owner";
|
|
95
|
-
const
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
if (
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
267
|
+
const row = await host.ledger.read();
|
|
268
|
+
const retry = host.retryFailedSeed !== false;
|
|
269
|
+
if (row === undefined) {
|
|
270
|
+
const at = (host.now ?? Date.now)();
|
|
271
|
+
if ((await host.agentCount()) > 0) {
|
|
272
|
+
await host.ledger.record({
|
|
273
|
+
version: starterAgent.version,
|
|
274
|
+
outcome: "team-not-empty",
|
|
275
|
+
agentId: null,
|
|
276
|
+
at,
|
|
277
|
+
attemptAt: null,
|
|
278
|
+
failure: null,
|
|
279
|
+
});
|
|
280
|
+
return "team-not-empty";
|
|
281
|
+
}
|
|
282
|
+
return await waitForCreate(host, startCreate(host, {
|
|
108
283
|
version: starterAgent.version,
|
|
109
|
-
outcome: "
|
|
284
|
+
outcome: "creating",
|
|
110
285
|
agentId: null,
|
|
111
286
|
at,
|
|
112
|
-
|
|
113
|
-
|
|
287
|
+
attemptAt: null,
|
|
288
|
+
failure: null,
|
|
289
|
+
}));
|
|
114
290
|
}
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
outcome: "seed-pending",
|
|
125
|
-
agentId: result.agentId,
|
|
126
|
-
at,
|
|
127
|
-
});
|
|
128
|
-
await host.seedHome(result.agentId);
|
|
291
|
+
if (row.outcome === "created" || row.outcome === "team-not-empty")
|
|
292
|
+
return "already-offered";
|
|
293
|
+
const live = attemptLive(host, row);
|
|
294
|
+
if (row.outcome === "creating") {
|
|
295
|
+
if (live)
|
|
296
|
+
return "starting";
|
|
297
|
+
if (row.failure !== null && !retry)
|
|
298
|
+
return "failed";
|
|
299
|
+
return await waitForCreate(host, startCreate(host, row));
|
|
129
300
|
}
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
301
|
+
const { agentId } = row;
|
|
302
|
+
if (agentId === null || host.seedHome === undefined)
|
|
303
|
+
throw new Error("Pending starter has no Home seed owner");
|
|
304
|
+
if (live)
|
|
305
|
+
return "seeding";
|
|
306
|
+
if (row.failure !== null && !retry)
|
|
307
|
+
return "failed";
|
|
308
|
+
await startSeed(host, host.seedHome, row, agentId);
|
|
309
|
+
return "seeding";
|
|
137
310
|
}
|
|
138
311
|
catch (cause) {
|
|
139
312
|
host.report?.(cause);
|
|
140
313
|
return "failed";
|
|
141
314
|
}
|
|
142
315
|
}
|
|
316
|
+
/** Wait at most `readWaitMs` for the create; past that the read answers `starting`. */
|
|
317
|
+
async function waitForCreate(host, outcome) {
|
|
318
|
+
let waited;
|
|
319
|
+
const readWait = new Promise((resolve) => {
|
|
320
|
+
waited = setTimeout(() => {
|
|
321
|
+
resolve("starting");
|
|
322
|
+
}, host.readWaitMs ?? starterReadWaitMs);
|
|
323
|
+
});
|
|
324
|
+
try {
|
|
325
|
+
return await Promise.race([outcome, readWait]);
|
|
326
|
+
}
|
|
327
|
+
finally {
|
|
328
|
+
clearTimeout(waited);
|
|
329
|
+
}
|
|
330
|
+
}
|
package/docs/api/agents.md
CHANGED
|
@@ -685,6 +685,8 @@ What one Vault command answers: a listing, an id, a version, usage or a refusal.
|
|
|
685
685
|
```ts
|
|
686
686
|
type StarterOutcome =
|
|
687
687
|
| "created"
|
|
688
|
+
| "seeding"
|
|
689
|
+
| "starting"
|
|
688
690
|
| "already-offered"
|
|
689
691
|
| "team-not-empty"
|
|
690
692
|
| "unfunded"
|
|
@@ -692,7 +694,9 @@ type StarterOutcome =
|
|
|
692
694
|
| "failed";
|
|
693
695
|
```
|
|
694
696
|
|
|
695
|
-
How one offer of the starter Agent settled
|
|
697
|
+
How one offer of the starter Agent settled. `created` and `seeding` both mean
|
|
698
|
+
the Agent exists; `seeding` means its Home seed is still running; `starting`
|
|
699
|
+
means its create is still running.
|
|
696
700
|
|
|
697
701
|
## Variables
|
|
698
702
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fungi.computer/oyster",
|
|
3
|
-
"version": "0.47.
|
|
3
|
+
"version": "0.47.2",
|
|
4
4
|
"author": "Levi <levi@technomancy.dev>",
|
|
5
5
|
"description": "Oyster by Fungi: open-source Apps for people and AI agents. Try with one command or run on your own Cloudflare account.",
|
|
6
6
|
"homepage": "https://docs.fungi.computer/oyster",
|