@fungi.computer/oyster 0.14.1 → 0.16.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 (61) hide show
  1. package/README.md +178 -1552
  2. package/dist/agents.d.ts +8 -0
  3. package/dist/agents.js +6 -0
  4. package/dist/app-builds.d.ts +5 -6
  5. package/dist/app-builds.js +3 -10
  6. package/dist/apps/permissions.js +8 -1
  7. package/dist/auth.d.ts +2 -0
  8. package/dist/auth.js +9 -8
  9. package/dist/boot-host-script.js +1 -1
  10. package/dist/build/candidate-cli.mjs +4 -0
  11. package/dist/catalog-frame.d.ts +0 -1
  12. package/dist/computer.d.ts +5 -0
  13. package/dist/computer.js +1 -0
  14. package/dist/embed-metafiles.js +2 -2
  15. package/dist/embed-scripts.js +3 -3
  16. package/dist/hello-app-script.js +1 -1
  17. package/dist/host-page-assets.js +1 -1
  18. package/dist/host-page.d.ts +5 -1
  19. package/dist/host-page.js +23 -23
  20. package/dist/host.js +6 -1
  21. package/dist/page/app-access.js +23 -1
  22. package/dist/page/app-permissions.js +165 -50
  23. package/dist/page/app-rights.d.ts +8 -0
  24. package/dist/page/app-rights.js +13 -0
  25. package/dist/page/computer-handles.d.ts +15 -0
  26. package/dist/page/computer-handles.js +4 -1
  27. package/dist/page/mount.d.ts +5 -0
  28. package/dist/page/mount.js +4 -0
  29. package/dist/page-script.js +3 -3
  30. package/dist/standalone/agents.js +10 -0
  31. package/dist/standalone/app-set.d.ts +9 -0
  32. package/dist/standalone/app-set.js +43 -0
  33. package/dist/standalone/app-source.js +16 -1
  34. package/dist/standalone/builds.d.ts +2 -2
  35. package/dist/standalone/builds.js +4 -0
  36. package/dist/standalone/cloudflare-account.d.ts +10 -0
  37. package/dist/standalone/cloudflare-account.js +17 -0
  38. package/dist/standalone/computer.d.ts +8 -3
  39. package/dist/standalone/computer.js +26 -3
  40. package/dist/standalone/install-apps-cli.js +1 -1
  41. package/dist/standalone/local-desktop.d.ts +19 -2
  42. package/dist/standalone/local-desktop.js +38 -15
  43. package/dist/standalone/media.d.ts +2 -0
  44. package/dist/standalone/media.js +17 -1
  45. package/dist/standalone/registry.d.ts +4 -1
  46. package/dist/standalone/registry.js +6 -0
  47. package/dist/standalone/sign-in-link.d.ts +1 -1
  48. package/dist/standalone/sign-in-link.js +9 -18
  49. package/dist/standalone/try-cli.d.ts +7 -0
  50. package/dist/standalone/try-cli.js +88 -8
  51. package/dist/starter-agent.d.ts +59 -0
  52. package/dist/starter-agent.js +85 -0
  53. package/docs/api/README.md +744 -88
  54. package/docs/api/agents.md +6 -0
  55. package/docs/api/auth.md +10 -0
  56. package/docs/api/computer.md +4 -0
  57. package/docs/api/page/mount.md +2 -0
  58. package/docs/api/workers-git.md +14 -9
  59. package/docs/api/workers.md +8 -3
  60. package/docs/site/agent-quickstart.mdx +1 -1
  61. package/package.json +34 -50
@@ -1,6 +1,7 @@
1
1
  // A one-time sign-in link for `oyster try`. The owner key never goes in a URL:
2
2
  // the link opens a page served by this process that posts the key to the local
3
- // Oyster's own /login form, then the server forgets the link.
3
+ // Oyster's own /login form, then the server forgets the key. The listener stays
4
+ // up for the whole try session, so a reused link lands on /login with a note.
4
5
  import { awaitCleanup } from "../build/process-group.js";
5
6
  import { createHash, randomBytes } from "node:crypto";
6
7
  import { addAbortListener } from "node:events";
@@ -9,8 +10,7 @@ import * as z from "zod";
9
10
  import { hostPage } from "../host-page.js";
10
11
  import { loadPageAssets } from "../page-assets.js";
11
12
  const addressSchema = z.object({ port: z.number() });
12
- const lifetimeMs = 10 * 60_000;
13
- /** Serve one single-use page that signs the owner in to `oysterUrl`. */
13
+ /** Serve one single-use page that signs the owner in to `oysterUrl`, until closed. */
14
14
  export async function startSignInLink(input) {
15
15
  const signal = input.signal ?? new AbortController().signal;
16
16
  signal.throwIfAborted();
@@ -32,10 +32,8 @@ export async function startSignInLink(input) {
32
32
  key: input.key,
33
33
  },
34
34
  })).text();
35
- const expired = await (await hostPage({ ...pageOptions, state: "link-expired", status: 404 })).text();
36
35
  const notFound = await (await hostPage({ ...pageOptions, state: "not-found", status: 404 })).text();
37
36
  signal.throwIfAborted();
38
- const timers = new Set();
39
37
  const server = createServer((request, response) => {
40
38
  const headers = {
41
39
  "Content-Type": "text/html; charset=utf-8",
@@ -49,21 +47,22 @@ export async function startSignInLink(input) {
49
47
  return;
50
48
  }
51
49
  if (used) {
52
- response.writeHead(404, headers).end(expired);
50
+ response
51
+ .writeHead(302, {
52
+ ...headers,
53
+ Location: new URL("/login?link=used", input.oysterUrl).href,
54
+ })
55
+ .end();
53
56
  return;
54
57
  }
55
58
  used = true;
56
59
  response.writeHead(200, headers).end(page);
57
60
  page = "";
58
- scheduleClose(1_000);
59
61
  });
60
62
  let closing;
61
63
  let abortListener;
62
64
  const beginClose = () => (closing ??= Promise.allSettled([
63
65
  (async () => {
64
- for (const timer of timers)
65
- clearTimeout(timer);
66
- timers.clear();
67
66
  page = "";
68
67
  abortListener?.[Symbol.dispose]();
69
68
  await new Promise((resolve, reject) => {
@@ -79,13 +78,6 @@ export async function startSignInLink(input) {
79
78
  })(),
80
79
  ]));
81
80
  const close = () => awaitCleanup(beginClose());
82
- function scheduleClose(ms) {
83
- const timer = setTimeout(() => {
84
- void beginClose();
85
- }, ms);
86
- timer.unref();
87
- timers.add(timer);
88
- }
89
81
  try {
90
82
  await new Promise((done, fail) => {
91
83
  server.once("error", fail);
@@ -100,7 +92,6 @@ export async function startSignInLink(input) {
100
92
  abortListener = addAbortListener(signal, () => {
101
93
  void beginClose();
102
94
  });
103
- scheduleClose(lifetimeMs);
104
95
  const { port } = addressSchema.parse(server.address());
105
96
  return { url: `http://127.0.0.1:${String(port)}/${nonce}`, close };
106
97
  }
@@ -1,5 +1,6 @@
1
1
  import { Cli } from "@fungi.computer/lantern";
2
2
  import { type DesktopReadiness } from "./local-desktop.js";
3
+ import { type StarterApp } from "./app-set.js";
3
4
  import { type SignInLink } from "./sign-in-link.js";
4
5
  export declare const tryUsage = "Usage: oyster try [directory] [--port 8787] [--no-open] [--verbose] [--package <npm spec>]";
5
6
  /**
@@ -38,6 +39,12 @@ export type TryEffects = Readonly<{
38
39
  key: string;
39
40
  signal: AbortSignal;
40
41
  }) => Promise<DesktopReadiness>;
42
+ /** Build and install one more starter App; resolves once it is installed. */
43
+ installStarter: (app: StarterApp, input: {
44
+ url: string;
45
+ key: string;
46
+ signal: AbortSignal;
47
+ }) => Promise<"installed" | "already-installed">;
41
48
  /** A one-time page that signs the owner in without the key in a URL. */
42
49
  signInLink: (input: {
43
50
  oysterUrl: string;
@@ -23,11 +23,12 @@ import { copyFile, mkdir, mkdtemp, rename, readdir, rm, readFile, stat, writeFil
23
23
  import { createServer } from "node:net";
24
24
  import { basename, dirname, delimiter, join, resolve } from "node:path";
25
25
  import process from "node:process";
26
- import { parseArgs } from "node:util";
26
+ import { parseArgs, stripVTControlCharacters } from "node:util";
27
27
  import { Cli } from "@fungi.computer/lantern";
28
28
  import * as z from "zod";
29
29
  import { installHelloApp } from "./hello-app.js";
30
- import { installLocalDesktop, localDesktopState, } from "./local-desktop.js";
30
+ import { desktopApp, installLocalStarter, localDesktopState, localStarterInstalled, } from "./local-desktop.js";
31
+ import { standaloneAppSet, trialStarterOrder, } from "./app-set.js";
31
32
  import { startSignInLink } from "./sign-in-link.js";
32
33
  export const tryUsage = "Usage: oyster try [directory] [--port 8787] [--no-open] [--verbose] [--package <npm spec>]";
33
34
  const tryHelp = `${tryUsage}
@@ -225,6 +226,30 @@ function captureOutput(child, log, verbose) {
225
226
  stream?.pipe(process.stderr, { end: false });
226
227
  }
227
228
  }
229
+ /**
230
+ * Wrangler keeps running after a failed build, so a startup that will never
231
+ * answer is only visible in its output. Resolves with its first error line.
232
+ */
233
+ class StartupFailure {
234
+ line;
235
+ constructor(line) {
236
+ this.line = line;
237
+ }
238
+ }
239
+ function firstWranglerError(child) {
240
+ return new Promise((found) => {
241
+ let seen = "";
242
+ for (const stream of [child.stdout, child.stderr])
243
+ stream?.setEncoding("utf8").on("data", (chunk) => {
244
+ seen = (seen + chunk).slice(-4096);
245
+ const line = stripVTControlCharacters(seen)
246
+ .split("\n")
247
+ .find((candidate) => candidate.includes("[ERROR]"));
248
+ if (line !== undefined)
249
+ found(line.slice(line.indexOf("[ERROR]") + "[ERROR]".length).trim());
250
+ });
251
+ });
252
+ }
228
253
  const npmFailureSchema = z.object({ error: z.object({ code: z.string() }) });
229
254
  function npmFailureCode(output) {
230
255
  try {
@@ -372,6 +397,7 @@ function startWrangler(input) {
372
397
  env: { ...process.env, WRANGLER_SEND_METRICS: "false" },
373
398
  });
374
399
  captureOutput(child, logStream, input.verbose);
400
+ const startupError = firstWranglerError(child);
375
401
  const lifetime = new AbortController();
376
402
  const spawnError = new Promise((done) => {
377
403
  child.once("error", () => {
@@ -405,16 +431,19 @@ function startWrangler(input) {
405
431
  });
406
432
  try {
407
433
  const readiness = await Promise.race([
434
+ startupError.then((line) => new StartupFailure(line)),
408
435
  waitUntilReady(url, child, 120_000, AbortSignal.any([lifetime.signal, input.signal])),
409
436
  spawnError,
410
437
  ]);
411
438
  input.signal.throwIfAborted();
412
439
  if (readiness !== "ready") {
413
- const diagnostic = readiness === "spawn-error"
414
- ? "Oyster could not launch its server process."
415
- : readiness === "exited"
416
- ? `Oyster stopped before readiness (${child.signalCode === null ? `exit ${String(child.exitCode)}` : `signal ${child.signalCode}`}).`
417
- : "Oyster did not answer within 120 seconds.";
440
+ const diagnostic = readiness instanceof StartupFailure
441
+ ? `Oyster could not start: ${readiness.line}`
442
+ : readiness === "spawn-error"
443
+ ? "Oyster could not launch its server process."
444
+ : readiness === "exited"
445
+ ? `Oyster stopped before readiness (${child.signalCode === null ? `exit ${String(child.exitCode)}` : `signal ${child.signalCode}`}).`
446
+ : "Oyster did not answer within 120 seconds.";
418
447
  await stop();
419
448
  throw new TryError(diagnostic, `Read ${log} for the server output.`);
420
449
  }
@@ -462,10 +491,19 @@ const realEffects = {
462
491
  const saved = await localDesktopState(input);
463
492
  if (saved !== "missing")
464
493
  return saved;
465
- await installLocalDesktop(input);
494
+ await installLocalStarter(desktopApp, input);
466
495
  const installed = await localDesktopState(input);
467
496
  return installed === "missing" ? "unavailable" : installed;
468
497
  },
498
+ installStarter: async (app, input) => {
499
+ if (await localStarterInstalled({
500
+ ...input,
501
+ installationId: app.installationId,
502
+ }))
503
+ return "already-installed";
504
+ await installLocalStarter(app, input);
505
+ return "installed";
506
+ },
469
507
  signInLink: startSignInLink,
470
508
  open: openBrowser,
471
509
  portFree,
@@ -718,6 +756,46 @@ export async function tryOyster(args, effects = realEffects, ui = createTryCli(a
718
756
  `Sign in later by pasting that key at ${url}/login.`,
719
757
  "Press Ctrl-C to stop.",
720
758
  ]);
759
+ // The rest of the starter Apps build here, one at a time, while the desktop
760
+ // is already usable. Each reports one line; a failure never stops the rest.
761
+ const starters = trialStarterOrder.map((id) => {
762
+ const app = standaloneAppSet.find((item) => item.installationId === id);
763
+ if (app === undefined)
764
+ throw new Error(`${id} is not a starter App`);
765
+ return app;
766
+ });
767
+ const trialAbort = new AbortController();
768
+ const trialSignal = AbortSignal.any([signal, trialAbort.signal]);
769
+ void watchedExit.then(() => {
770
+ trialAbort.abort();
771
+ });
772
+ const stopped = () => trialSignal.aborted;
773
+ // A stop interrupts the build in flight; that is not a failure to report.
774
+ const reportStarterFailure = (name, cause) => {
775
+ if (!stopped())
776
+ ui.warn(`${name} couldn't be installed: ${innermostError(cause).message}`, `Run \`${retry}\` again to retry it.`);
777
+ };
778
+ const background = desktopReady
779
+ ? (async () => {
780
+ ui.info(`Getting ${String(starters.length)} more Apps ready in the background.`);
781
+ for (const app of starters) {
782
+ if (stopped())
783
+ return;
784
+ const name = app.installationId;
785
+ const settled = await effects
786
+ .installStarter(app, { url, key, signal: trialSignal })
787
+ .then((result) => ({ kind: "done", result }), (cause) => ({ kind: "failed", cause }));
788
+ if (settled.kind === "failed")
789
+ reportStarterFailure(name, settled.cause);
790
+ else
791
+ ui.info(app.trial === "needs-runtime"
792
+ ? `${name} installed: needs a Computer runtime (see ${name})`
793
+ : settled.result === "already-installed"
794
+ ? `${name} already installed`
795
+ : `${name} ready`);
796
+ }
797
+ })()
798
+ : Promise.resolve();
721
799
  let stopListener;
722
800
  try {
723
801
  const requested = new Promise((done) => {
@@ -734,6 +812,8 @@ export async function tryOyster(args, effects = realEffects, ui = createTryCli(a
734
812
  }
735
813
  finally {
736
814
  stopListener?.[Symbol.dispose]();
815
+ trialAbort.abort();
816
+ await background;
737
817
  }
738
818
  }
739
819
  catch (cause) {
@@ -0,0 +1,59 @@
1
+ /**
2
+ * The starter Agent policy: an owner with an empty Team gets one Agent named
3
+ * "Shiitake", once, ever. This module owns only that rule and its one-row
4
+ * ledger. It never creates anything itself: the host supplies its ordinary,
5
+ * idempotent Agent create, so the starter has exactly the identity, Computer,
6
+ * App tools and funding checks of any other Agent. It stores no model, prompt,
7
+ * session or tool grant.
8
+ */
9
+ import type { WatchdogSqliteOwner } from "@fungi.computer/watchdog";
10
+ /** The declaration. Changing it affects only Teams with no ledger row. */
11
+ export declare const starterAgent: {
12
+ readonly version: 1;
13
+ readonly name: "Shiitake";
14
+ readonly requestId: "starter-agent:v1";
15
+ };
16
+ /** What the ledger remembers: that the starter was settled, never to be offered again. */
17
+ export type StarterLedgerRow = Readonly<{
18
+ version: number;
19
+ outcome: "created" | "team-not-empty";
20
+ agentId: string | null;
21
+ at: number;
22
+ }>;
23
+ /** One row per Team, in the host's own SQLite. */
24
+ export type StarterLedger = Readonly<{
25
+ read(): StarterLedgerRow | undefined;
26
+ /** First write wins; a later one is ignored. */
27
+ record(row: StarterLedgerRow): void;
28
+ }>;
29
+ /** The host's ordinary create, as the starter sees it. */
30
+ export type StarterCreateResult = Readonly<{
31
+ status: "created";
32
+ agentId: string;
33
+ }> | Readonly<{
34
+ status: "unfunded";
35
+ }>;
36
+ export type StarterAgentHost = Readonly<{
37
+ ledger: StarterLedger;
38
+ /** Only the Team owner's read may trigger the starter. */
39
+ isOwner(): boolean;
40
+ /** Agents in the Team, archived ones included. */
41
+ agentCount(): number;
42
+ /** The host's normal create, replayed by `requestId`; funding refusal is `unfunded`. */
43
+ create(request: {
44
+ name: string;
45
+ requestId: string;
46
+ }): Promise<StarterCreateResult>;
47
+ /** Where a failed attempt is reported; the caller's read never fails. */
48
+ report?(cause: unknown): void;
49
+ now?(): number;
50
+ }>;
51
+ export type StarterOutcome = "created" | "already-offered" | "team-not-empty" | "unfunded" | "not-owner" | "failed";
52
+ /** Open the one-row ledger in the host's own SQLite. */
53
+ export declare function createStarterLedger(sql: WatchdogSqliteOwner["sql"]): StarterLedger;
54
+ /**
55
+ * Offer the starter Agent if this Team never had its chance. Safe to call on
56
+ * every owner directory read: concurrent calls share one attempt, and the
57
+ * host's `requestId` replay makes a second attempt return the same Agent.
58
+ */
59
+ export declare function ensureStarterAgent(host: StarterAgentHost): Promise<StarterOutcome>;
@@ -0,0 +1,85 @@
1
+ import { z } from "zod";
2
+ /** The declaration. Changing it affects only Teams with no ledger row. */
3
+ export const starterAgent = {
4
+ version: 1,
5
+ name: "Shiitake",
6
+ requestId: "starter-agent:v1",
7
+ };
8
+ const ledgerRowSchema = z.strictObject({
9
+ version: z.number().int(),
10
+ outcome: z.enum(["created", "team-not-empty"]),
11
+ agent_id: z.string().nullable(),
12
+ at: z.number(),
13
+ });
14
+ /** Open the one-row ledger in the host's own SQLite. */
15
+ export function createStarterLedger(sql) {
16
+ 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");
17
+ return {
18
+ read() {
19
+ const row = sql
20
+ .exec("SELECT version, outcome, agent_id, at FROM starter_agent WHERE id = 1")
21
+ .toArray()[0];
22
+ if (row === undefined)
23
+ return undefined;
24
+ const stored = ledgerRowSchema.parse(row);
25
+ return {
26
+ version: stored.version,
27
+ outcome: stored.outcome,
28
+ agentId: stored.agent_id,
29
+ at: stored.at,
30
+ };
31
+ },
32
+ record(row) {
33
+ sql.exec("INSERT INTO starter_agent(id, version, outcome, agent_id, at) VALUES(1, ?, ?, ?, ?) ON CONFLICT(id) DO NOTHING", row.version, row.outcome, row.agentId, row.at);
34
+ },
35
+ };
36
+ }
37
+ const inFlight = new WeakMap();
38
+ /**
39
+ * Offer the starter Agent if this Team never had its chance. Safe to call on
40
+ * every owner directory read: concurrent calls share one attempt, and the
41
+ * host's `requestId` replay makes a second attempt return the same Agent.
42
+ */
43
+ export function ensureStarterAgent(host) {
44
+ const running = inFlight.get(host.ledger);
45
+ if (running !== undefined)
46
+ return running;
47
+ const attempt = settle(host).finally(() => inFlight.delete(host.ledger));
48
+ inFlight.set(host.ledger, attempt);
49
+ return attempt;
50
+ }
51
+ async function settle(host) {
52
+ try {
53
+ if (!host.isOwner())
54
+ return "not-owner";
55
+ if (host.ledger.read() !== undefined)
56
+ return "already-offered";
57
+ const at = (host.now ?? Date.now)();
58
+ if (host.agentCount() > 0) {
59
+ host.ledger.record({
60
+ version: starterAgent.version,
61
+ outcome: "team-not-empty",
62
+ agentId: null,
63
+ at,
64
+ });
65
+ return "team-not-empty";
66
+ }
67
+ const result = await host.create({
68
+ name: starterAgent.name,
69
+ requestId: starterAgent.requestId,
70
+ });
71
+ if (result.status === "unfunded")
72
+ return "unfunded";
73
+ host.ledger.record({
74
+ version: starterAgent.version,
75
+ outcome: "created",
76
+ agentId: result.agentId,
77
+ at,
78
+ });
79
+ return "created";
80
+ }
81
+ catch (cause) {
82
+ host.report?.(cause);
83
+ return "failed";
84
+ }
85
+ }