@fungi.computer/oyster 0.47.1 → 0.47.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.
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)
package/dist/host.d.ts CHANGED
@@ -256,10 +256,12 @@ export type OysterHost = Readonly<{
256
256
  /** Read the owner's live installation directory. */
257
257
  directory(): Promise<OysterRootDirectory>;
258
258
  /** Open storage after fresh installation and owner admission. */
259
- storage(installationId: string, ownerId: string): Pick<AppStorageWire, "read" | "write" | "reset" | "claim"> & Readonly<{
260
- /** Stream changes for an admitted declared storage key. */
261
- events(key: string): Promise<Response>;
262
- }>;
259
+ storage(installationId: string, ownerId: string): Pick<AppStorageWire, "read" | "write" | "reset" | "claim">;
260
+ /**
261
+ * Watch many declared storage keys as one stream of server-sent frames,
262
+ * each key under fresh owner admission; cancelling it releases them all.
263
+ */
264
+ watchStorage(ownerId: string, watches: readonly (readonly [string, string])[]): Promise<ReadableStream<Uint8Array>>;
263
265
  }>;
264
266
  /** Root-selected home installation; the core never imports a specific home App. */
265
267
  homeInstallationId?: string;
package/dist/host.js CHANGED
@@ -33,6 +33,7 @@ export { capabilityDescriptorSchema, capabilityMethodKindSchema, capabilityMetho
33
33
  import { selectionOf, } from "./index.js";
34
34
  import { parseRelease, readCachedVerified, sha256, } from "./release.js";
35
35
  import { createGitDoor } from "./git.js";
36
+ import { maxStorageWatches, storageWatchSchema } from "./storage-watch-wire.js";
36
37
  import { getCookie } from "hono/cookie";
37
38
  import { returningCookieName } from "./auth.js";
38
39
  import { buildGitPassPrefix, presentedGitKey } from "./git-auth.js";
@@ -574,20 +575,40 @@ export function oysterRouteTable(host) {
574
575
  headers: { "Cache-Control": "no-store" },
575
576
  });
576
577
  });
578
+ // One shared stream for every storage key a page watches, so a page with
579
+ // many open Apps stays under an HTTP/1.1 host's six-connection limit.
580
+ table.get("/api/workbench/storage-events", owner("direct-or-app"), async (context, { principal }) => {
581
+ const workbench = host.workbench;
582
+ if (workbench === undefined)
583
+ return refusal(404, "Not found");
584
+ const decoded = (context.req.queries("watch") ?? []).map((raw) => Schema.decodeUnknownOption(Schema.fromJsonString(storageWatchSchema))(raw));
585
+ const watches = decoded.flatMap((watch) => watch._tag === "Some" &&
586
+ Schema.decodeUnknownOption(appStorageKeyNameSchema)(watch.value[1])
587
+ ._tag === "Some"
588
+ ? [watch.value]
589
+ : []);
590
+ if (watches.length === 0 ||
591
+ watches.length !== decoded.length ||
592
+ watches.length > maxStorageWatches)
593
+ return refusal(400, "Invalid storage watches");
594
+ return new Response(await workbench.watchStorage(oysterPrincipalId(principal), watches), {
595
+ headers: {
596
+ "Content-Type": "text/event-stream",
597
+ "Cache-Control": "no-store",
598
+ },
599
+ });
600
+ });
577
601
  table.all("/api/workbench/storage/:installationId/:operation", owner("direct-or-app"), async (context, { principal }) => {
578
602
  const workbench = host.workbench;
579
603
  if (workbench === undefined)
580
604
  return refusal(404, "Not found");
581
605
  const view = workbench.storage(context.req.param("installationId"), oysterPrincipalId(principal));
582
606
  const operation = context.req.param("operation");
583
- if ((operation === "read" || operation === "events") &&
584
- context.req.method === "GET") {
607
+ if (operation === "read" && context.req.method === "GET") {
585
608
  const key = Schema.decodeUnknownOption(appStorageKeyNameSchema)(context.req.query("key"));
586
609
  if (key._tag === "None")
587
610
  return refusal(400, "Invalid storage key");
588
- return operation === "read"
589
- ? Response.json(await view.read(key.value))
590
- : view.events(key.value);
611
+ return Response.json(await view.read(key.value));
591
612
  }
592
613
  if (operation === "claim" && context.req.method === "POST") {
593
614
  const input = Schema.decodeUnknownOption(appStorageClaimSchema, {
@@ -0,0 +1,41 @@
1
+ import type { appStorageErrorCodes, AppStorageEvent } from "@fungi.computer/agar/storage";
2
+ /** The part of an EventSource the shared stream needs. */
3
+ export type WatchSource = {
4
+ addEventListener(type: "watch", listener: (message: {
5
+ data: string;
6
+ }) => void): void;
7
+ close(): void;
8
+ };
9
+ /** What one watched key's stream said: its signals, or why the owner refused it. */
10
+ export type StorageWatchMessage = Readonly<{
11
+ kind: "ready";
12
+ }> | Readonly<{
13
+ kind: "changed";
14
+ event: AppStorageEvent;
15
+ }> | Readonly<{
16
+ kind: "rejected";
17
+ code: (typeof appStorageErrorCodes)[number];
18
+ }>;
19
+ /**
20
+ * Every storage key this page watches rides one shared event stream. A browser
21
+ * allows six connections per HTTP/1.1 host, so one stream per open App would
22
+ * starve every later request. The stream reopens when the watched set changes.
23
+ */
24
+ export declare class SharedStorageEvents {
25
+ #private;
26
+ constructor(open?: (url: string) => WatchSource);
27
+ /**
28
+ * Watch one key until the returned function is called. Past the page's watch
29
+ * limit the watcher is refused with `quota_exceeded`, like any other refusal.
30
+ */
31
+ subscribe(installationId: string, key: string, listener: (message: StorageWatchMessage) => void): () => void;
32
+ }
33
+ /** The page's one shared watcher. */
34
+ export declare const storageEvents: SharedStorageEvents;
35
+ /**
36
+ * An EventSource-shaped watch of one key, for the Desktop's observation.
37
+ * A refusal is reported once to `refused`; the watch then stays quiet.
38
+ */
39
+ export declare function watchStorageKey(installationId: string, key: string, refused: (code: (typeof appStorageErrorCodes)[number]) => void, events?: SharedStorageEvents): Pick<EventTarget, "addEventListener"> & {
40
+ close(): void;
41
+ };
@@ -0,0 +1,102 @@
1
+ import * as Schema from "effect/Schema";
2
+ import { maxStorageWatches, storageWatchFrameSchema, } from "../storage-watch-wire.js";
3
+ /**
4
+ * Every storage key this page watches rides one shared event stream. A browser
5
+ * allows six connections per HTTP/1.1 host, so one stream per open App would
6
+ * starve every later request. The stream reopens when the watched set changes.
7
+ */
8
+ export class SharedStorageEvents {
9
+ #subscribers = new Map();
10
+ #open;
11
+ #source = null;
12
+ #next = 0;
13
+ #pending = false;
14
+ constructor(open = (url) => new EventSource(url, { withCredentials: true })) {
15
+ this.#open = open;
16
+ }
17
+ /**
18
+ * Watch one key until the returned function is called. Past the page's watch
19
+ * limit the watcher is refused with `quota_exceeded`, like any other refusal.
20
+ */
21
+ subscribe(installationId, key, listener) {
22
+ const id = this.#next++;
23
+ if (this.#subscribers.size >= maxStorageWatches) {
24
+ queueMicrotask(() => {
25
+ listener({ kind: "rejected", code: "quota_exceeded" });
26
+ });
27
+ return () => undefined;
28
+ }
29
+ this.#subscribers.set(id, {
30
+ installationId,
31
+ key,
32
+ listener,
33
+ refused: false,
34
+ });
35
+ this.#reopen();
36
+ return () => {
37
+ if (this.#subscribers.delete(id))
38
+ this.#reopen();
39
+ };
40
+ }
41
+ #reopen() {
42
+ if (this.#pending)
43
+ return;
44
+ this.#pending = true;
45
+ queueMicrotask(() => {
46
+ this.#pending = false;
47
+ const previous = this.#source;
48
+ const live = [...this.#subscribers].filter(([, { refused }]) => !refused);
49
+ if (live.length === 0) {
50
+ this.#source = null;
51
+ }
52
+ else {
53
+ const query = new URLSearchParams();
54
+ for (const [, { installationId, key }] of live)
55
+ query.append("watch", JSON.stringify([installationId, key]));
56
+ const source = this.#open(`/api/workbench/storage-events?${query}`);
57
+ source.addEventListener("watch", (message) => {
58
+ const frame = Schema.decodeUnknownOption(Schema.fromJsonString(storageWatchFrameSchema))(message.data);
59
+ if (frame._tag === "None")
60
+ return;
61
+ const entry = live[frame.value.watch];
62
+ if (entry === undefined)
63
+ return;
64
+ const subscriber = entry[1];
65
+ if (frame.value.kind === "rejected") {
66
+ if (subscriber.refused)
67
+ return;
68
+ subscriber.refused = true;
69
+ subscriber.listener({ kind: "rejected", code: frame.value.code });
70
+ return;
71
+ }
72
+ subscriber.listener(frame.value.kind === "ready"
73
+ ? { kind: "ready" }
74
+ : { kind: "changed", event: frame.value.event });
75
+ });
76
+ this.#source = source;
77
+ }
78
+ previous?.close();
79
+ });
80
+ }
81
+ }
82
+ /** The page's one shared watcher. */
83
+ export const storageEvents = new SharedStorageEvents();
84
+ /**
85
+ * An EventSource-shaped watch of one key, for the Desktop's observation.
86
+ * A refusal is reported once to `refused`; the watch then stays quiet.
87
+ */
88
+ export function watchStorageKey(installationId, key, refused, events = storageEvents) {
89
+ const target = new EventTarget();
90
+ const stop = events.subscribe(installationId, key, (message) => {
91
+ if (message.kind === "rejected")
92
+ refused(message.code);
93
+ else
94
+ target.dispatchEvent(new Event(message.kind));
95
+ });
96
+ return {
97
+ addEventListener: (type, listener, options) => {
98
+ target.addEventListener(type, listener, options);
99
+ },
100
+ close: stop,
101
+ };
102
+ }
@@ -0,0 +1,3 @@
1
+ import type { appStorageErrorCodes } from "@fungi.computer/agar/storage";
2
+ /** Tell the person, once per refusal, why a Desktop App will not update live. */
3
+ export declare function showStorageRefusal(installationId: string, code: (typeof appStorageErrorCodes)[number]): void;
@@ -0,0 +1,28 @@
1
+ import { createElement } from "react";
2
+ import { createRoot } from "react-dom/client";
3
+ import { Toaster, showNotice } from "@fungi.computer/caps/components/toaster";
4
+ const toasterId = "oyster-storage-notices";
5
+ const reasons = {
6
+ invalid: "it asked to watch storage with a request the host could not read",
7
+ undeclared_key: "it watches a storage key it never declared",
8
+ scope_not_declared: "it watches storage in a scope it never declared",
9
+ owner_required: "only the owner can watch its storage",
10
+ too_large: "its storage change was too large to send",
11
+ quota_exceeded: "this page is already watching the most storage keys it can",
12
+ conflict: "its storage changed in a conflicting way",
13
+ unavailable: "its storage is not available right now",
14
+ };
15
+ let mounted = false;
16
+ /** Tell the person, once per refusal, why a Desktop App will not update live. */
17
+ export function showStorageRefusal(installationId, code) {
18
+ if (!mounted) {
19
+ mounted = true;
20
+ const root = document.createElement("div");
21
+ document.body.append(root);
22
+ createRoot(root).render(createElement(Toaster, { id: toasterId }));
23
+ }
24
+ showNotice({
25
+ tone: "error",
26
+ message: `${installationId} will not update live: ${reasons[code]}.`,
27
+ }, toasterId);
28
+ }
@@ -2,6 +2,7 @@ import { RpcTarget } from "@fungi.computer/capnweb";
2
2
  import * as Schema from "effect/Schema";
3
3
  import { AppError } from "@fungi.computer/agar";
4
4
  import { appStorageKeyNameSchema, appStorageWriteSchema, appStorageResetSchema, appStorageClaimSchema, appStorageReadResultSchema, appStorageMutationResultSchema, appStorageClaimResultSchema, } from "@fungi.computer/agar/storage";
5
+ import { storageEvents } from "./storage-events.js";
5
6
  const NativeTarget = RpcTarget;
6
7
  function path(installationId, operation) {
7
8
  return `/api/workbench/storage/${encodeURIComponent(installationId)}/${operation}`;
@@ -17,18 +18,61 @@ async function reply(response) {
17
18
  return Schema.decodeUnknownSync(Schema.Json)(await response.json());
18
19
  }
19
20
  class StorageEvents extends NativeTarget {
20
- url;
21
+ installationId;
22
+ key;
21
23
  #abort = new AbortController();
22
- constructor(url) {
24
+ constructor(installationId, key) {
23
25
  super();
24
- this.url = url;
26
+ this.installationId = installationId;
27
+ this.key = key;
25
28
  }
29
+ /**
30
+ * The App's own event stream, carried by the page's one shared stream. A
31
+ * refused watch answers like a refused read, with the owner's code.
32
+ */
26
33
  fetch(request) {
27
- return fetch(this.url, {
28
- credentials: "same-origin",
29
- cache: "no-store",
30
- redirect: "error",
31
- signal: AbortSignal.any([request.signal, this.#abort.signal]),
34
+ const signal = AbortSignal.any([request.signal, this.#abort.signal]);
35
+ const encoder = new TextEncoder();
36
+ return new Promise((answer) => {
37
+ let controller;
38
+ let answered = false;
39
+ let stop = () => undefined;
40
+ const body = new ReadableStream({
41
+ start: (opened) => {
42
+ controller = opened;
43
+ },
44
+ cancel: () => {
45
+ stop();
46
+ },
47
+ });
48
+ const reply = (response) => {
49
+ answered = true;
50
+ answer(response);
51
+ };
52
+ stop = storageEvents.subscribe(this.installationId, this.key, (message) => {
53
+ if (message.kind === "rejected") {
54
+ stop();
55
+ if (answered)
56
+ controller?.error(new Error(message.code));
57
+ else
58
+ reply(Response.json({ kind: "rejected", code: message.code }, { status: 403 }));
59
+ return;
60
+ }
61
+ controller?.enqueue(encoder.encode(message.kind === "ready"
62
+ ? "event: ready\ndata: {}\n\n"
63
+ : `event: changed\ndata: ${JSON.stringify(message.event)}\n\n`));
64
+ if (!answered)
65
+ reply(new Response(body, {
66
+ headers: { "Content-Type": "text/event-stream" },
67
+ }));
68
+ });
69
+ signal.addEventListener("abort", () => {
70
+ stop();
71
+ if (answered)
72
+ controller?.close();
73
+ else
74
+ reply(new Response(null, { status: 499 }));
75
+ }, { once: true });
32
76
  });
33
77
  }
34
78
  close() {
@@ -79,7 +123,7 @@ class Storage extends NativeTarget {
79
123
  }
80
124
  openEvents(raw) {
81
125
  const key = Schema.decodeUnknownSync(appStorageKeyNameSchema)(raw);
82
- return Promise.resolve(new StorageEvents(`${path(this.installationId, "events")}?${new URLSearchParams({ key })}`));
126
+ return Promise.resolve(new StorageEvents(this.installationId, key));
83
127
  }
84
128
  }
85
129
  /** The existing Agar storage wire, scoped to an admitted installation and owner. */