@fungi.computer/oyster 0.18.1 → 0.18.3

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.
@@ -21,13 +21,28 @@ export declare class AgentModelRefused extends Error {
21
21
  readonly reason: AgentModelRefusal;
22
22
  constructor(reason: AgentModelRefusal);
23
23
  }
24
+ /**
25
+ * An Agent with no saved choice runs on a model its host can reach, chosen when
26
+ * it runs: Workers AI where a Cloudflare account answers, then the Fungi
27
+ * gateway, then the first stored provider key's catalog default. A key added
28
+ * later just works; one removed moves the default on. Nothing is saved, so an
29
+ * Agent's own choice always wins.
30
+ */
31
+ export declare function resolveDefaultChoice(ready: Readonly<{
32
+ workersAi: boolean;
33
+ gateway: boolean;
34
+ keys: readonly Readonly<{
35
+ keyId: string;
36
+ provider: string;
37
+ }>[];
38
+ }>): Promise<AgentModelChoice>;
24
39
  /** Read the maintained Pi catalog; never accept a model from a different egress. */
25
40
  export declare function selectAgentModel(choice: AgentModelChoice): Promise<Model<Api>>;
26
41
  /** The Agent DO is the only durable owner. Absence is a new-format default, not an old-env reader. */
27
42
  export declare function agentModelChoice(storage: Readonly<{
28
43
  get<T = unknown>(key: string): Promise<T | undefined>;
29
44
  put(key: string, value: AgentModelChoice): Promise<void>;
30
- }>, admit: (choice: AgentModelChoice) => void | Promise<void>): {
45
+ }>, admit: (choice: AgentModelChoice) => void | Promise<void>, fallback?: () => Promise<AgentModelChoice>): {
31
46
  read(): Promise<AgentModelChoice>;
32
47
  set(input: AgentModelChoice): Promise<AgentModelChoice>;
33
48
  };
@@ -41,6 +41,38 @@ async function byokCatalog(provider) {
41
41
  .openrouterProvider()
42
42
  .getModels();
43
43
  }
44
+ /**
45
+ * An Agent with no saved choice runs on a model its host can reach, chosen when
46
+ * it runs: Workers AI where a Cloudflare account answers, then the Fungi
47
+ * gateway, then the first stored provider key's catalog default. A key added
48
+ * later just works; one removed moves the default on. Nothing is saved, so an
49
+ * Agent's own choice always wins.
50
+ */
51
+ export async function resolveDefaultChoice(ready) {
52
+ if (ready.workersAi)
53
+ return defaultChoice;
54
+ if (ready.gateway)
55
+ return {
56
+ keySource: "ai-gateway",
57
+ model: { providerId: "openai", modelId: "openai/gpt-6-luna" },
58
+ };
59
+ for (const { keyId, provider } of ready.keys) {
60
+ if (provider !== "anthropic" &&
61
+ provider !== "openai" &&
62
+ provider !== "openrouter")
63
+ continue;
64
+ const catalog = await byokCatalog(provider);
65
+ const model = catalog.find((entry) => "default" in entry && entry.default === true) ??
66
+ catalog[0];
67
+ if (model !== undefined)
68
+ return {
69
+ keySource: "byok",
70
+ keyId,
71
+ model: { providerId: provider, modelId: model.id },
72
+ };
73
+ }
74
+ return defaultChoice;
75
+ }
44
76
  /** Read the maintained Pi catalog; never accept a model from a different egress. */
45
77
  export async function selectAgentModel(choice) {
46
78
  const { providerId, modelId, reasoning } = choice.model;
@@ -72,12 +104,12 @@ export async function selectAgentModel(choice) {
72
104
  return model;
73
105
  }
74
106
  /** The Agent DO is the only durable owner. Absence is a new-format default, not an old-env reader. */
75
- export function agentModelChoice(storage, admit) {
107
+ export function agentModelChoice(storage, admit, fallback = () => Promise.resolve(defaultChoice)) {
76
108
  return {
77
109
  async read() {
78
110
  const stored = await storage.get(key);
79
111
  return stored === undefined
80
- ? defaultChoice
112
+ ? fallback()
81
113
  : Schema.decodeUnknownSync(agentModelChoiceSchema, {
82
114
  onExcessProperty: "error",
83
115
  })(stored);
@@ -43,7 +43,7 @@ import { standaloneBrowserLiveView, standaloneBrowserSource, } from "./browser.j
43
43
  import { standaloneWebSource } from "./web.js";
44
44
  import { configuredProviderEgress, providerFetch, } from "@fungi.computer/veil/gatekeeper";
45
45
  import { createAssistantMessageEventStream } from "@earendil-works/pi-ai/utils/event-stream";
46
- import { agentModelChoice, agentModelChoiceSchema, AgentModelRefused, selectAgentModel, } from "./agent-model-choice.js";
46
+ import { agentModelChoice, agentModelChoiceSchema, AgentModelRefused, resolveDefaultChoice, selectAgentModel, } from "./agent-model-choice.js";
47
47
  import { CLOUDFLARE_GATEWAY_BINDING_AUTH_SENTINEL, createAiBindingFetch, } from "@earendil-works/pi-ai/api/cloudflare-ai-binding";
48
48
  import { cloudflareAccountReady } from "./cloudflare-account.js";
49
49
  import { cloudflareWorkersAIProvider } from "@earendil-works/pi-ai/providers/cloudflare-workers-ai";
@@ -170,6 +170,56 @@ function observedModels(model, defaults) {
170
170
  },
171
171
  };
172
172
  }
173
+ /** The refusal a run ends with when no model provider is connected, in the host's own failure wording. */
174
+ const setupRequiredFailure = "Model request failed (setup_required). Connect a model first.";
175
+ /**
176
+ * A run with no connected model provider: end it at once with the typed setup
177
+ * failure. A transport error would read as an outage and be retried.
178
+ */
179
+ function unconfiguredModels(model) {
180
+ return {
181
+ acquire: () => {
182
+ const failed = new WeakSet();
183
+ return Promise.resolve({
184
+ model,
185
+ retryable: () => false,
186
+ failureReason: (message) => failed.has(message) ? setupRequiredFailure : undefined,
187
+ stream: () => {
188
+ const events = createAssistantMessageEventStream();
189
+ const terminal = {
190
+ role: "assistant",
191
+ content: [],
192
+ api: model.api,
193
+ provider: model.provider,
194
+ model: model.id,
195
+ usage: {
196
+ input: 0,
197
+ output: 0,
198
+ cacheRead: 0,
199
+ cacheWrite: 0,
200
+ totalTokens: 0,
201
+ cost: {
202
+ input: 0,
203
+ output: 0,
204
+ cacheRead: 0,
205
+ cacheWrite: 0,
206
+ total: 0,
207
+ },
208
+ },
209
+ stopReason: "error",
210
+ errorMessage: setupRequiredFailure,
211
+ timestamp: Date.now(),
212
+ };
213
+ failed.add(terminal);
214
+ events.push({ type: "error", reason: "error", error: terminal });
215
+ events.end(terminal);
216
+ return events;
217
+ },
218
+ release: () => Promise.resolve(),
219
+ });
220
+ },
221
+ };
222
+ }
173
223
  /**
174
224
  * Workers AI over the AI binding. Requests go through AI Gateway's
175
225
  * `workers-ai` passthrough on the binding, so no API token is needed.
@@ -573,6 +623,9 @@ export class StandaloneAgentBase extends ShiitakeDO {
573
623
  !(await this.env.AGENT_DIRECTORY.getByName(pin.directoryName).has(agentId)))
574
624
  return new Response("Agent scope is unavailable", { status: 403 });
575
625
  const choice = await this.readModelChoice();
626
+ // Offer only what can run: a model whose provider is not connected is not a choice.
627
+ if (choice.keySource === "workers-ai" && !cloudflareAccountReady(this.env))
628
+ return Response.json(agentModelListSchema.parse([]));
576
629
  // The same owner checks the chosen source before reporting it as available.
577
630
  await this.sourceFor(choice);
578
631
  const model = await selectAgentModel(choice);
@@ -824,6 +877,15 @@ export class StandaloneAgentBase extends ShiitakeDO {
824
877
  throw new AgentModelRefused("key_not_connected");
825
878
  if (choice.keySource === "workers-ai" && this.env.AI === undefined)
826
879
  throw new AgentModelRefused("key_not_connected");
880
+ }, async () => {
881
+ const pin = await this.policyDirectory();
882
+ return resolveDefaultChoice({
883
+ workersAi: this.env.AI !== undefined && cloudflareAccountReady(this.env),
884
+ gateway: configuredProviderEgress(this.env).baseUrl("ai-gateway") !== null,
885
+ keys: pin === null
886
+ ? []
887
+ : await this.env.AGENT_DIRECTORY.getByName(pin.directoryName).listModelKeys(),
888
+ });
827
889
  });
828
890
  }
829
891
  /** Secret-free default of this Agent; stored separately from Session history. */
@@ -913,6 +975,9 @@ export class StandaloneAgentBase extends ShiitakeDO {
913
975
  }
914
976
  if (this.env.AI === undefined)
915
977
  throw new AgentModelRefused("key_not_connected");
978
+ // The AI binding is declared everywhere; only a Cloudflare account answers it.
979
+ if (!cloudflareAccountReady(this.env))
980
+ return unconfiguredModels(normalizeModel(modelChoice));
916
981
  let options = { model: modelChoice.id };
917
982
  if (this.env.OYSTER_AI_GATEWAY !== undefined)
918
983
  options = { ...options, gateway: this.env.OYSTER_AI_GATEWAY };
@@ -1,4 +1,12 @@
1
1
  import { type StarterApp } from "./app-set.js";
2
+ /**
3
+ * The release tag the App repositories carry for this Oyster: `v<version>`.
4
+ * An Oyster at X gets the App versions that were released with X, never the
5
+ * repository's newest commit.
6
+ */
7
+ export declare function starterReleaseTag(): Promise<string>;
8
+ /** The git arguments that fetch one starter App at its release tag. */
9
+ export declare function starterCloneArguments(app: StarterApp, tag: string, destination: string): readonly string[];
2
10
  /** The Tourtois desktop, which `oyster try` installs before anything else. */
3
11
  export declare const desktopApp: Readonly<{
4
12
  dashboard?: true;
@@ -9,6 +17,12 @@ export declare const desktopApp: Readonly<{
9
17
  trial: "local" | "needs-runtime";
10
18
  }>;
11
19
  export type DesktopReadiness = "ready" | "approval-required" | "disabled" | "deleted" | "unavailable";
20
+ /** Whether the Oyster has a model its Agents can answer with (`GET /api/setup`). Read-only. */
21
+ export declare function localModelSetup(input: Readonly<{
22
+ url: string;
23
+ key: string;
24
+ signal?: AbortSignal;
25
+ }>): Promise<"ready" | "missing" | "unknown">;
12
26
  /** Whether an installation of this id is saved on the Oyster. Read-only. */
13
27
  export declare function localStarterInstalled(input: Readonly<{
14
28
  url: string;
@@ -5,7 +5,7 @@ import { CleanupError } from "../build/process-group.js";
5
5
  // and installs it; the Tourtois desktop is the home installation, and its shell
6
6
  // is approved the same way `install-apps` does.
7
7
  import { runGit } from "../build/local-build.js";
8
- import { mkdtemp, realpath, rm } from "node:fs/promises";
8
+ import { mkdtemp, readFile, realpath, rm } from "node:fs/promises";
9
9
  import { tmpdir } from "node:os";
10
10
  import { join } from "node:path";
11
11
  import * as Schema from "effect/Schema";
@@ -16,6 +16,27 @@ import { installationSchema } from "../apps/installation.js";
16
16
  import { approveChosenDashboard } from "./dashboard-approval.js";
17
17
  import { standaloneAppSet } from "./app-set.js";
18
18
  const repositoryUrl = (app) => `https://github.com/fungi-computer/${app.repository}.git`;
19
+ const versionManifest = z.object({ version: z.string().min(1) });
20
+ /**
21
+ * The release tag the App repositories carry for this Oyster: `v<version>`.
22
+ * An Oyster at X gets the App versions that were released with X, never the
23
+ * repository's newest commit.
24
+ */
25
+ export async function starterReleaseTag() {
26
+ const { version } = versionManifest.parse(JSON.parse(await readFile(join(import.meta.dirname, "../../package.json"), "utf8")));
27
+ return `v${version}`;
28
+ }
29
+ /** The git arguments that fetch one starter App at its release tag. */
30
+ export function starterCloneArguments(app, tag, destination) {
31
+ return [
32
+ "clone",
33
+ "--quiet",
34
+ "--depth=1",
35
+ `--branch=${tag}`,
36
+ repositoryUrl(app),
37
+ destination,
38
+ ];
39
+ }
19
40
  /** The Tourtois desktop, which `oyster try` installs before anything else. */
20
41
  export const desktopApp = requireStarter("tourtois");
21
42
  function requireStarter(installationId) {
@@ -26,6 +47,29 @@ function requireStarter(installationId) {
26
47
  }
27
48
  const installationRowsSchema = z.array(installationSchema);
28
49
  const git = async (cwd, args, signal) => new TextDecoder().decode(await runGit(args, cwd, signal, process.env)).trim();
50
+ const setupFactsSchema = z.object({ models: z.enum(["ready", "missing"]) });
51
+ /** Whether the Oyster has a model its Agents can answer with (`GET /api/setup`). Read-only. */
52
+ export async function localModelSetup(input) {
53
+ const request = {
54
+ headers: { Authorization: `Bearer ${input.key}` },
55
+ };
56
+ if (input.signal !== undefined)
57
+ request.signal = input.signal;
58
+ let response;
59
+ try {
60
+ response = await fetch(new URL("/api/setup", input.url), request);
61
+ }
62
+ catch (cause) {
63
+ // A stop is not "unknown"; any other read failure only means no message.
64
+ input.signal?.throwIfAborted();
65
+ console.error("The Oyster's setup could not be read", cause);
66
+ return "unknown";
67
+ }
68
+ if (!response.ok)
69
+ return "unknown";
70
+ const parsed = setupFactsSchema.safeParse(await response.json());
71
+ return parsed.success ? parsed.data.models : "unknown";
72
+ }
29
73
  /** Whether an installation of this id is saved on the Oyster. Read-only. */
30
74
  export async function localStarterInstalled(input) {
31
75
  const request = {
@@ -72,7 +116,10 @@ export async function installLocalStarter(app, input) {
72
116
  const canonical = await realpath(scratch);
73
117
  signal.throwIfAborted();
74
118
  const source = join(canonical, app.repository);
75
- await git(canonical, ["clone", "--quiet", "--depth=1", repositoryUrl(app), source], signal);
119
+ const tag = await starterReleaseTag();
120
+ await git(canonical, starterCloneArguments(app, tag, source), signal).catch((cause) => {
121
+ throw new Error(`${app.installationId} has no release ${tag} to install; it is published with each Oyster release.`, { cause });
122
+ });
76
123
  const commit = await git(source, ["rev-parse", "HEAD"], signal);
77
124
  const release = join(scratch, "release");
78
125
  await packRelease({
@@ -45,6 +45,12 @@ export type TryEffects = Readonly<{
45
45
  key: string;
46
46
  signal: AbortSignal;
47
47
  }) => Promise<"installed" | "already-installed">;
48
+ /** Whether a model is connected, so the start message can say what to do. */
49
+ modelSetup: (input: {
50
+ url: string;
51
+ key: string;
52
+ signal: AbortSignal;
53
+ }) => Promise<"ready" | "missing" | "unknown">;
48
54
  /** A one-time page that signs the owner in without the key in a URL. */
49
55
  signInLink: (input: {
50
56
  oysterUrl: string;
@@ -27,7 +27,7 @@ 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 { desktopApp, installLocalStarter, localDesktopState, localStarterInstalled, } from "./local-desktop.js";
30
+ import { desktopApp, installLocalStarter, localDesktopState, localStarterInstalled, localModelSetup, } from "./local-desktop.js";
31
31
  import { standaloneAppSet, trialStarterOrder, } from "./app-set.js";
32
32
  import { startSignInLink } from "./sign-in-link.js";
33
33
  export const tryUsage = "Usage: oyster try [directory] [--port 8787] [--no-open] [--verbose] [--package <npm spec>]";
@@ -55,6 +55,8 @@ const ownerKeyFile = ".oyster-owner";
55
55
  const logFile = join(".oyster", "wrangler.log");
56
56
  const installLogFile = join(".oyster", "install.log");
57
57
  const command = "npx @fungi.computer/oyster try";
58
+ /** Where a stranger learns to add a model key. */
59
+ const modelKeyGuideUrl = "https://docs.fungi.computer/models/your-own-key/";
58
60
  const pendingInstall = join(".oyster", "install.pending");
59
61
  const quote = (value) => "'" + value.replaceAll("'", "'\"'\"'") + "'";
60
62
  const retryCommand = (directory, port) => `${command} ${quote(directory)} --port ${String(port)}`;
@@ -521,6 +523,7 @@ const realEffects = {
521
523
  await installLocalStarter(app, input);
522
524
  return "installed";
523
525
  },
526
+ modelSetup: localModelSetup,
524
527
  signInLink: startSignInLink,
525
528
  open: openBrowser,
526
529
  portFree,
@@ -776,6 +779,9 @@ export async function tryOyster(args, effects = realEffects, ui = createTryCli(a
776
779
  `Sign in later by pasting that key at ${url}/login.`,
777
780
  "Press Ctrl-C to stop.",
778
781
  ]);
782
+ // Agents answer with a model; say up front, once, what to do when none is.
783
+ if ((await effects.modelSetup({ url, key, signal })) === "missing")
784
+ ui.warn("No model is connected yet, so Agents can't answer.", `Open Oyster, choose Keys, then Model keys, and add a key. Guide: ${modelKeyGuideUrl}`);
779
785
  // The rest of the starter Apps build here, one at a time, while the desktop
780
786
  // is already usable. Each reports one line; a failure never stops the rest.
781
787
  const starters = trialStarterOrder.map((id) => {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fungi.computer/oyster",
3
- "version": "0.18.1",
3
+ "version": "0.18.3",
4
4
  "author": "Levi <levi@technomancy.dev>",
5
5
  "description": "Run your own Apps on Cloudflare Workers or celld: installable App Releases, each with its own Durable Object, SQLite database and declared bindings",
6
6
  "type": "module",
@@ -346,7 +346,7 @@
346
346
  "@fungi.computer/lantern": "0.4.2",
347
347
  "@fungi.computer/mycelium": "0.3.8",
348
348
  "@fungi.computer/nacre": "0.4.1",
349
- "@fungi.computer/parakeet": "0.11.1",
349
+ "@fungi.computer/parakeet": "0.11.2",
350
350
  "@fungi.computer/puffball": "0.5.5",
351
351
  "@fungi.computer/seam": "0.2.5",
352
352
  "@fungi.computer/shiitake": "0.12.3",