@fungi.computer/oyster 0.23.0 → 0.25.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.
Files changed (41) hide show
  1. package/dist/agent-instructions.d.ts +35 -0
  2. package/dist/agent-instructions.js +42 -0
  3. package/dist/agents.d.ts +14 -0
  4. package/dist/agents.js +43 -1
  5. package/dist/apps/catalog.d.ts +11 -0
  6. package/dist/apps/catalog.js +1 -0
  7. package/dist/apps/gate.d.ts +2 -2
  8. package/dist/apps/installation.d.ts +7 -7
  9. package/dist/apps/permissions.d.ts +5 -5
  10. package/dist/boot-host-script.js +1 -1
  11. package/dist/browser/boot-once.d.ts +84 -0
  12. package/dist/browser/boot-once.js +48 -0
  13. package/dist/build/candidate-cli.mjs +6 -0
  14. package/dist/channels/discord-interactions.d.ts +15 -0
  15. package/dist/channels/discord-interactions.js +29 -0
  16. package/dist/channels/discord-replies.d.ts +9 -1
  17. package/dist/channels/discord-replies.js +34 -9
  18. package/dist/embed-metafiles.js +2 -2
  19. package/dist/embed-scripts.js +1 -1
  20. package/dist/installation-operations.d.ts +8 -8
  21. package/dist/machine-link/link.js +3 -1
  22. package/dist/page/computer-handles.d.ts +4 -0
  23. package/dist/page-script.js +2 -2
  24. package/dist/standalone/agents.d.ts +20 -0
  25. package/dist/standalone/agents.js +96 -13
  26. package/dist/standalone/computer.d.ts +3 -3
  27. package/dist/standalone/computer.js +37 -1
  28. package/dist/standalone/workflow-host.d.ts +5 -5
  29. package/dist/standalone/workflow-trigger-host.d.ts +1 -1
  30. package/docs/api/agents.md +18 -0
  31. package/docs/api/apps.md +148 -131
  32. package/docs/api/browser/boot-once.md +169 -0
  33. package/docs/api/build-contract.md +27 -21
  34. package/docs/api/build.md +70 -69
  35. package/docs/api/git.md +3 -3
  36. package/docs/api/host.md +91 -85
  37. package/docs/api/mcp.md +16 -16
  38. package/docs/api/modules.md +1 -0
  39. package/docs/api/workers-git.md +7 -7
  40. package/docs/api/workers.md +24 -21
  41. package/package.json +25 -17
@@ -0,0 +1,84 @@
1
+ import type { UiBootCheckOutcome } from "../boot-gate.js";
2
+ /** One Release and the version of the check that judges it. */
3
+ export type BootRunKey = Readonly<{
4
+ releaseId: string;
5
+ checkVersion: string;
6
+ }>;
7
+ /** Why a check could not judge the page. */
8
+ export type NotCheckedCode = Extract<UiBootCheckOutcome, {
9
+ kind: "not_checked";
10
+ }>["code"];
11
+ /** What an ask for the key's run slot learns. */
12
+ export type BootRunClaim = Readonly<{
13
+ kind: "acquired";
14
+ }>
15
+ /** Another asker is running the check right now. */
16
+ | Readonly<{
17
+ kind: "held";
18
+ }>
19
+ /** The last run was inconclusive a moment ago; it is reused, not retried. */
20
+ | Readonly<{
21
+ kind: "cooling";
22
+ code: NotCheckedCode;
23
+ }>;
24
+ /**
25
+ * The run slot for one key, in a store every isolate shares (the Hub's
26
+ * catalog D1). `acquire` is one atomic step: it hands the slot to exactly one
27
+ * asker unless a live claim exists, and a claim past its lease is free, so a
28
+ * crashed holder never blocks the Release.
29
+ */
30
+ export type BootRunClaims = Readonly<{
31
+ /** Take the key's slot, or learn who holds it or why it is cooling. */
32
+ acquire: (input: BootRunKey & Readonly<{
33
+ claimId: string;
34
+ now: number;
35
+ leaseMs: number;
36
+ }>) => Promise<BootRunClaim>;
37
+ /**
38
+ * End the holder's claim. With `cooling`, keep the slot closed for `coolMs`
39
+ * so waiters and new asks share the inconclusive reason; without it the slot
40
+ * is free at once. A claim another asker holds is left alone.
41
+ */
42
+ finish: (input: BootRunKey & Readonly<{
43
+ claimId: string;
44
+ now: number;
45
+ cooling: Readonly<{
46
+ code: NotCheckedCode;
47
+ coolMs: number;
48
+ }> | null;
49
+ }>) => Promise<void>;
50
+ }>;
51
+ /** Everything one single-flight boot ask needs. */
52
+ export type SingleFlightBootInput = BootRunKey & Readonly<{
53
+ claims: BootRunClaims;
54
+ /** The recorded definitive outcome for the key, or null. */
55
+ recorded: () => Promise<UiBootCheckOutcome | null>;
56
+ /** One check; may open a browser session. */
57
+ run: () => Promise<UiBootCheckOutcome>;
58
+ /** Record a definitive outcome; the stored one wins. */
59
+ record: (outcome: Exclude<UiBootCheckOutcome, {
60
+ kind: "not_checked";
61
+ }>) => Promise<UiBootCheckOutcome>;
62
+ /** The clock, epoch ms. */
63
+ now: () => number;
64
+ /** Wait between polls of a held slot. */
65
+ sleep: (ms: number) => Promise<void>;
66
+ /** A host-minted identity for one attempt to take the slot. */
67
+ newClaimId: () => string;
68
+ /** Longer than one `run`, cleanup included. */
69
+ leaseMs: number;
70
+ pollMs: number;
71
+ /** How long an inconclusive reason is shared. */
72
+ coolMs: number;
73
+ /** The longest a waiter holds on before giving up as `boot_timeout`. */
74
+ maxWaitMs: number;
75
+ }>;
76
+ /**
77
+ * At most one boot check per Release and check version is in flight across
78
+ * every caller sharing `claims`. A definitive outcome is recorded and read by
79
+ * everyone after. A waiter reuses whatever the holder produced: the recorded
80
+ * verdict, or its inconclusive reason for `coolMs`. An inconclusive outcome is
81
+ * never a verdict and never reported as a pass; once the cooldown ends the
82
+ * next ask checks again.
83
+ */
84
+ export declare function singleFlightBoot(input: SingleFlightBootInput): Promise<UiBootCheckOutcome>;
@@ -0,0 +1,48 @@
1
+ /**
2
+ * At most one boot check per Release and check version is in flight across
3
+ * every caller sharing `claims`. A definitive outcome is recorded and read by
4
+ * everyone after. A waiter reuses whatever the holder produced: the recorded
5
+ * verdict, or its inconclusive reason for `coolMs`. An inconclusive outcome is
6
+ * never a verdict and never reported as a pass; once the cooldown ends the
7
+ * next ask checks again.
8
+ */
9
+ export async function singleFlightBoot(input) {
10
+ const key = { releaseId: input.releaseId, checkVersion: input.checkVersion };
11
+ const startedAt = input.now();
12
+ for (;;) {
13
+ const stored = await input.recorded();
14
+ if (stored !== null)
15
+ return stored;
16
+ const claimId = input.newClaimId();
17
+ const claim = await input.claims.acquire({
18
+ ...key,
19
+ claimId,
20
+ now: input.now(),
21
+ leaseMs: input.leaseMs,
22
+ });
23
+ if (claim.kind === "cooling")
24
+ return { kind: "not_checked", code: claim.code };
25
+ if (claim.kind === "acquired")
26
+ return await held(input, key, claimId);
27
+ if (input.now() - startedAt >= input.maxWaitMs)
28
+ return { kind: "not_checked", code: "boot_timeout" };
29
+ await input.sleep(input.pollMs);
30
+ }
31
+ }
32
+ async function held(input, key, claimId) {
33
+ let cooling = null;
34
+ try {
35
+ // A verdict recorded between the read and the claim needs no run.
36
+ const stored = await input.recorded();
37
+ if (stored !== null)
38
+ return stored;
39
+ const outcome = await input.run();
40
+ if (outcome.kind !== "not_checked")
41
+ return await input.record(outcome);
42
+ cooling = { code: outcome.code, coolMs: input.coolMs };
43
+ return outcome;
44
+ }
45
+ finally {
46
+ await input.claims.finish({ ...key, claimId, now: input.now(), cooling });
47
+ }
48
+ }
@@ -19604,6 +19604,11 @@ var appBackendBindingKinds = {
19604
19604
  requires: ["computer.writeFile"],
19605
19605
  effect: "write"
19606
19606
  },
19607
+ move: {
19608
+ cap: "app.computer.write",
19609
+ requires: ["computer.writeFile"],
19610
+ effect: "write"
19611
+ },
19607
19612
  preview: {
19608
19613
  cap: "app.computer.exec",
19609
19614
  requires: ["computer.execute"],
@@ -19677,6 +19682,7 @@ var appCapabilityIds = [
19677
19682
  "agent.manage",
19678
19683
  "agent.rename",
19679
19684
  "agent.avatar",
19685
+ "agent.instructions",
19680
19686
  "agent.toolPolicy",
19681
19687
  "agent.read",
19682
19688
  "agent.send",
@@ -232,6 +232,21 @@ export declare function postFollowUp(send: typeof fetch, input: Readonly<{
232
232
  content: string;
233
233
  withReply: boolean;
234
234
  }>): Promise<"delivered" | "gone" | "retry">;
235
+ /** What a member is told on the original message when an answer will take longer. */
236
+ export declare const STILL_WORKING_TEXT = "Still working on this. I will post the answer in this channel when it is ready.";
237
+ /**
238
+ * Post a normal channel message as the owner's bot, for an answer that
239
+ * outlived its interaction token. The bot token is the credential and never
240
+ * leaves the host call; the member is mentioned so they are told it arrived.
241
+ */
242
+ export declare function postChannelMessage(send: typeof fetch, input: Readonly<{
243
+ channelId: string;
244
+ botToken: string;
245
+ content: string;
246
+ withReply: boolean;
247
+ /** Mention this member, and only them. */
248
+ mentionUserId: string | null;
249
+ }>): Promise<"delivered" | "gone" | "retry">;
235
250
  /**
236
251
  * Tell the member why an answer did not come, in plain words and with what to
237
252
  * do next. The host's own failure diagnostic names the cause; provider prose
@@ -259,6 +259,35 @@ export async function postFollowUp(send, input) {
259
259
  return "delivered";
260
260
  return [401, 403, 404].includes(response.status) ? "gone" : "retry";
261
261
  }
262
+ /** What a member is told on the original message when an answer will take longer. */
263
+ export const STILL_WORKING_TEXT = "Still working on this. I will post the answer in this channel when it is ready.";
264
+ /**
265
+ * Post a normal channel message as the owner's bot, for an answer that
266
+ * outlived its interaction token. The bot token is the credential and never
267
+ * leaves the host call; the member is mentioned so they are told it arrived.
268
+ */
269
+ export async function postChannelMessage(send, input) {
270
+ const response = await send(`${DISCORD_API}/channels/${input.channelId}/messages`, {
271
+ method: "POST",
272
+ headers: {
273
+ authorization: `Bot ${input.botToken}`,
274
+ "content-type": "application/json",
275
+ },
276
+ body: JSON.stringify({
277
+ ...followUpBody(input.content, input.withReply),
278
+ allowed_mentions: {
279
+ parse: [],
280
+ users: input.mentionUserId === null ? [] : [input.mentionUserId],
281
+ },
282
+ }),
283
+ signal: AbortSignal.timeout(15_000),
284
+ });
285
+ await response.body?.cancel();
286
+ // 401, 403 and 404: the bot is not allowed in that channel, or it is gone.
287
+ if (response.ok)
288
+ return "delivered";
289
+ return [401, 403, 404].includes(response.status) ? "gone" : "retry";
290
+ }
262
291
  const failureCode = /^Model request failed \(([\w-]+)\)/u;
263
292
  /**
264
293
  * Tell the member why an answer did not come, in plain words and with what to
@@ -6,7 +6,7 @@ export type DiscordDelivery =
6
6
  "delivered"
7
7
  /** The run has not settled yet; look again soon. */
8
8
  | "waiting"
9
- /** Discord no longer knows the token; nothing more can be sent. */
9
+ /** Discord refuses every way of reaching the member; nothing more can be sent. */
10
10
  | "gone"
11
11
  /** A transient failure; try again with backoff. */
12
12
  | "retry";
@@ -22,6 +22,10 @@ export type DiscordPendingReply = Readonly<{
22
22
  attempts: number;
23
23
  /** Messages of the answer Discord already has; a retry resumes after them. */
24
24
  deliveredParts: number;
25
+ /** Whether the interaction token still works; past it, only the channel does. */
26
+ tokenLive: boolean;
27
+ /** The token is about to lapse and the member has not been told it is still working. */
28
+ stillWorkingDue: boolean;
25
29
  }>;
26
30
  /** One reply that never reached Discord, as the owner's list shows it. */
27
31
  export type DiscordClosedReply = Readonly<{
@@ -43,6 +47,10 @@ export declare function createDiscordReplies(options: Readonly<{
43
47
  }>): {
44
48
  /** Owe one reply. A second record of the same interaction is the first. */
45
49
  record: (bindingId: string, ask: DiscordAsk) => void;
50
+ /** The member has been told the run is still going. */
51
+ markStillWorking: (interactionId: string) => void;
52
+ /** Discord no longer knows the token: only the channel reaches the member now. */
53
+ tokenGone: (interactionId: string) => void;
46
54
  /** Remember how many messages of the answer Discord has. */
47
55
  progress: (interactionId: string, parts: number) => void;
48
56
  /** Replies of one binding that never reached Discord, newest first. */
@@ -1,14 +1,22 @@
1
1
  import { z } from "zod";
2
2
  /**
3
3
  * The Discord replies an Agent still owes. An interaction token is valid for
4
- * about 15 minutes; until the answer is delivered or the token lapses, one row
5
- * per interaction keeps the debt in the Agent's own store, so an evicted run
6
- * still answers after the Agent wakes. A row names no secret once it is
7
- * closed, and a closed row says honestly why: `expired` (the token lapsed or
8
- * Discord no longer knew it) or `failed` (delivery kept failing).
4
+ * about 15 minutes: until then the answer fills the original message. A run
5
+ * that needs longer says it is still working before the token lapses, and its
6
+ * answer then arrives as a normal channel message. One row per interaction
7
+ * keeps the debt in the Agent's own store, so an evicted run still answers
8
+ * after the Agent wakes. A row names no secret once it is closed, and a closed
9
+ * row says honestly why: `expired` (no answer within two hours) or `failed`
10
+ * (delivery kept failing).
9
11
  */
10
- /** The token window we honour, a little under Discord's own 15 minutes. */
12
+ /** The interaction token window we honour, a little under Discord's 15 minutes. */
11
13
  const DISCORD_REPLY_WINDOW_MS = 14 * 60_000;
14
+ /** When a run still going tells the member so, safely inside the token window. */
15
+ const STILL_WORKING_AFTER_MS = 12 * 60_000;
16
+ /** How long an answer may take before the reply is given up as expired. */
17
+ const CHANNEL_WINDOW_MS = 2 * 3_600_000;
18
+ /** How soon a run past the token window is looked at again. */
19
+ const SLOW_POLL_MS = 10_000;
12
20
  /** How long a closed row stays readable before it is pruned. */
13
21
  const CLOSED_RETENTION_MS = 7 * 86_400_000;
14
22
  /** Delivery attempts after which a reply is given up as failed. */
@@ -32,6 +40,8 @@ const pendingRow = z.strictObject({
32
40
  command_id: z.string().nullable(),
33
41
  attempts: z.number().int().nonnegative(),
34
42
  delivered_parts: z.number().int().nonnegative(),
43
+ still_working: z.union([z.literal(0), z.literal(1)]),
44
+ created_at: z.number().int(),
35
45
  expires_at: z.number().int(),
36
46
  });
37
47
  const closedRow = z.strictObject({
@@ -57,6 +67,7 @@ export function createDiscordReplies(options) {
57
67
  echo TEXT,
58
68
  display_name TEXT,
59
69
  delivered_parts INTEGER NOT NULL DEFAULT 0,
70
+ still_working INTEGER NOT NULL DEFAULT 0,
60
71
  session_id TEXT,
61
72
  command_id TEXT,
62
73
  state TEXT NOT NULL CHECK (state IN ('waiting','expired','failed')),
@@ -79,15 +90,17 @@ export function createDiscordReplies(options) {
79
90
  const now = options.now();
80
91
  sql.exec("DELETE FROM oyster_discord_replies WHERE state!='waiting' AND closed_at<?", now - CLOSED_RETENTION_MS);
81
92
  const rows = sql
82
- .exec("SELECT interaction_id,binding_id,application_id,token,guild_id,channel_id,user_id,text,echo,display_name,session_id,command_id,attempts,delivered_parts,expires_at FROM oyster_discord_replies WHERE state='waiting' AND next_at<=? ORDER BY next_at LIMIT ?", now, PASS_LIMIT)
93
+ .exec("SELECT interaction_id,binding_id,application_id,token,guild_id,channel_id,user_id,text,echo,display_name,session_id,command_id,attempts,delivered_parts,still_working,created_at,expires_at FROM oyster_discord_replies WHERE state='waiting' AND next_at<=? ORDER BY next_at LIMIT ?", now, PASS_LIMIT)
83
94
  .toArray()
84
95
  .map((raw) => pendingRow.parse(raw));
85
96
  for (const row of rows) {
86
- if (options.now() >= row.expires_at) {
97
+ const at = options.now();
98
+ if (at >= row.created_at + CHANNEL_WINDOW_MS) {
87
99
  close(row.interaction_id, "expired");
88
100
  options.onExpired(row.interaction_id);
89
101
  continue;
90
102
  }
103
+ const tokenLive = at < row.expires_at;
91
104
  const delivery = await options.deliver({
92
105
  interactionId: row.interaction_id,
93
106
  bindingId: row.binding_id,
@@ -107,13 +120,17 @@ export function createDiscordReplies(options) {
107
120
  : null,
108
121
  attempts: row.attempts,
109
122
  deliveredParts: row.delivered_parts,
123
+ tokenLive,
124
+ stillWorkingDue: tokenLive &&
125
+ row.still_working === 0 &&
126
+ at >= row.created_at + STILL_WORKING_AFTER_MS,
110
127
  });
111
128
  switch (delivery) {
112
129
  case "delivered":
113
130
  sql.exec("DELETE FROM oyster_discord_replies WHERE interaction_id=?", row.interaction_id);
114
131
  break;
115
132
  case "waiting":
116
- reschedule(row.interaction_id, options.now() + POLL_MS, row.attempts);
133
+ reschedule(row.interaction_id, options.now() + (tokenLive ? POLL_MS : SLOW_POLL_MS), row.attempts);
117
134
  break;
118
135
  case "gone":
119
136
  close(row.interaction_id, "expired");
@@ -135,6 +152,14 @@ export function createDiscordReplies(options) {
135
152
  const now = options.now();
136
153
  sql.exec("INSERT OR IGNORE INTO oyster_discord_replies (interaction_id,binding_id,application_id,token,guild_id,channel_id,user_id,text,echo,display_name,state,attempts,created_at,expires_at,next_at) VALUES (?,?,?,?,?,?,?,?,?,?,'waiting',0,?,?,?)", ask.interactionId, bindingId, ask.applicationId, ask.interactionToken, ask.guildId, ask.channelId, ask.userId, ask.text, ask.echo ?? null, ask.displayName ?? null, now, now + DISCORD_REPLY_WINDOW_MS, now);
137
154
  },
155
+ /** The member has been told the run is still going. */
156
+ markStillWorking: (interactionId) => {
157
+ sql.exec("UPDATE oyster_discord_replies SET still_working=1 WHERE interaction_id=?", interactionId);
158
+ },
159
+ /** Discord no longer knows the token: only the channel reaches the member now. */
160
+ tokenGone: (interactionId) => {
161
+ sql.exec("UPDATE oyster_discord_replies SET expires_at=? WHERE interaction_id=?", options.now(), interactionId);
162
+ },
138
163
  /** Remember how many messages of the answer Discord has. */
139
164
  progress: (interactionId, parts) => {
140
165
  sql.exec("UPDATE oyster_discord_replies SET delivered_parts=? WHERE interaction_id=?", parts, interactionId);