@mostra/runtime 0.12.0 → 0.14.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 (37) hide show
  1. package/dist/bin.js +2912 -2318
  2. package/dist/bin.js.map +1 -1
  3. package/dist/index.js +1 -1
  4. package/dist/{instance-CBUlOmzG.js → instance-CFTw3g-c.js} +227 -25
  5. package/dist/instance-CFTw3g-c.js.map +1 -0
  6. package/dist/reference/diagnostics.json +2 -2
  7. package/dist/reference/errors/MOSTRA_REMOTE_QUEUE_FULL.md +2 -2
  8. package/dist/reference/self-hosting.md +2 -1
  9. package/dist/skill/SKILL.md +2 -2
  10. package/dist/skill/assets/examples/dashboard/styles.css +27 -9
  11. package/dist/skill/assets/examples/decision/styles.css +27 -9
  12. package/dist/skill/assets/examples/inbox/styles.css +27 -9
  13. package/dist/skill/assets/studio.css +27 -9
  14. package/dist/skill/references/mcp.md +2 -2
  15. package/package.json +7 -6
  16. package/src/actions/index.ts +5 -2
  17. package/src/gateway/actions.ts +6 -1
  18. package/src/gateway/capabilities.ts +5 -1
  19. package/src/gateway/http.ts +15 -19
  20. package/src/gateway/index.ts +70 -1
  21. package/src/gateway/listener.ts +10 -5
  22. package/src/gateway/routes.ts +6 -1
  23. package/src/gateway/theme.ts +238 -0
  24. package/src/ledger/migrations.ts +9 -0
  25. package/src/server/api.ts +79 -87
  26. package/src/server/auth.ts +83 -16
  27. package/src/server/authorize.ts +74 -58
  28. package/src/server/config.ts +98 -0
  29. package/src/server/directory.ts +51 -0
  30. package/src/server/hosted-pages.ts +19 -6
  31. package/src/server/hosted.ts +59 -27
  32. package/src/server/index.ts +144 -17
  33. package/src/server/metering.ts +117 -12
  34. package/src/server/pages.ts +242 -0
  35. package/src/server/providers.ts +61 -9
  36. package/src/server/relay.ts +258 -107
  37. package/dist/instance-CBUlOmzG.js.map +0 -1
@@ -53,6 +53,7 @@ import {
53
53
  import type { Ledger, LedgerDb } from "../ledger/index.ts";
54
54
  import type { Log } from "../log.ts";
55
55
  import { handler, type MethodHandler, type Session } from "../protocol-server/index.ts";
56
+ import type { LimitVerdict } from "./operator.ts";
56
57
 
57
58
  /** How long a relay port call may take: the owner answers once it recorded the run. */
58
59
  const PORT_CALL_MS = 30_000;
@@ -103,6 +104,15 @@ export interface HostedRelayOptions {
103
104
  * refused before anything is recorded or relayed.
104
105
  */
105
106
  readonly perLink?: { readonly count: number; readonly perMs: number } | undefined;
107
+ /**
108
+ * The operator's `limits` for one artifact's relayed actions (INTERFACES §18.6, D165 item 9):
109
+ * `run` before a run is recorded, `run.wait` when it would wait for an absent owner, `call`
110
+ * before a plain call is relayed, each with quantity 1. Absent: nothing is asked.
111
+ */
112
+ readonly limit?: (
113
+ artifactId: string,
114
+ operation: "run" | "run.wait" | "call",
115
+ ) => Promise<LimitVerdict>;
106
116
  /** How often waiting and unacknowledged runs are checked against their limits; default 1 s. */
107
117
  readonly sweepMs?: number;
108
118
  /** An artifact's latest version here, whose producers its viewers want. */
@@ -119,7 +129,12 @@ export interface HostedRelayOptions {
119
129
  }
120
130
 
121
131
  /** The relay: the gateway's actions on a hosted home, and the owner's methods. */
122
- export interface HostedRelay extends Pick<Actions, "call" | "startRun" | "attach" | "cancel"> {
132
+ export interface HostedRelay extends Pick<Actions, "call" | "attach" | "cancel"> {
133
+ /**
134
+ * Starts or joins a relayed run (`Actions.startRun`): asynchronous here, since the operator's
135
+ * `limits` is asked before a new run is recorded.
136
+ */
137
+ startRun(...args: Parameters<Actions["startRun"]>): Promise<RunState>;
123
138
  /** `relay/run.update` and `relay/call.batch`, for the hosted home's protocol server. */
124
139
  methods(): MethodHandler[];
125
140
  /** An owner session opened: reconcile its accepted runs, then resend and drain (§18.3). */
@@ -245,35 +260,32 @@ export function createHostedRelay(options: HostedRelayOptions): HostedRelay {
245
260
 
246
261
  /** Each link's recent relayed runs and calls, for the per-link limit. */
247
262
  const linkUses = new Map<string, number[]>();
263
+ /**
264
+ * Whether a run request joins a run already recorded (its client key, or its key): it starts
265
+ * nothing, so it is neither counted against its link nor asked of the operator.
266
+ */
267
+ const joinsRun = (
268
+ artifactId: string,
269
+ input: { readonly clientKey: string; readonly key?: string | undefined; readonly fnId: string },
270
+ ): boolean =>
271
+ ledger.read(
272
+ (db) =>
273
+ db.get(
274
+ "SELECT 1 FROM action_run WHERE artifact_id = ? AND (client_key = ? OR (key IS NOT NULL AND key = ? AND action = ?))",
275
+ artifactId,
276
+ input.clientKey,
277
+ input.key ?? null,
278
+ input.fnId,
279
+ ) !== undefined,
280
+ );
248
281
  /**
249
282
  * Counts a relayed run or call against its link (D159), refusing it past the limit with
250
- * `MOSTRA_REMOTE_RATE_LIMITED` and when to try again. A request that joins a run already
251
- * recorded (its client key, or its key) starts nothing, so it is never counted.
283
+ * `MOSTRA_REMOTE_RATE_LIMITED` and when to try again. Answers how to give the use back, for a
284
+ * request the operator then refuses (as a refused submit gets its tokens back, D167 item 24).
252
285
  */
253
- const limitLink = (
254
- tokenId: string | undefined,
255
- artifactId?: string,
256
- input?: {
257
- readonly clientKey: string;
258
- readonly key?: string | undefined;
259
- readonly fnId: string;
260
- },
261
- ): void => {
286
+ const limitLink = (tokenId: string | undefined): (() => void) => {
262
287
  const limit = options.perLink;
263
- if (!limit || tokenId === undefined) return;
264
- if (artifactId !== undefined && input !== undefined) {
265
- const joins = ledger.read(
266
- (db) =>
267
- db.get(
268
- "SELECT 1 FROM action_run WHERE artifact_id = ? AND (client_key = ? OR (key IS NOT NULL AND key = ? AND action = ?))",
269
- artifactId,
270
- input.clientKey,
271
- input.key ?? null,
272
- input.fnId,
273
- ) !== undefined,
274
- );
275
- if (joins) return;
276
- }
288
+ if (!limit || tokenId === undefined) return () => {};
277
289
  const at = now();
278
290
  const recent = (linkUses.get(tokenId) ?? []).filter((used) => at - used < limit.perMs);
279
291
  if (recent.length >= limit.count) {
@@ -288,8 +300,87 @@ export function createHostedRelay(options: HostedRelayOptions): HostedRelay {
288
300
  }
289
301
  recent.push(at);
290
302
  linkUses.set(tokenId, recent);
303
+ let given = false;
304
+ return () => {
305
+ if (given) return;
306
+ given = true;
307
+ const uses = linkUses.get(tokenId);
308
+ const index = uses?.indexOf(at) ?? -1;
309
+ if (uses && index >= 0) uses.splice(index, 1);
310
+ };
311
+ };
312
+
313
+ /**
314
+ * Asks the operator's `limits` for a relayed action (D165 item 9). A refusal of `run` or `call`
315
+ * answers 403 `MOSTRA_REMOTE_LIMIT_REACHED` and one of `run.wait` 503 `MOSTRA_REMOTE_QUEUE_FULL`,
316
+ * each with the operator's message (and `Retry-After` when it gives one); no answer lets the
317
+ * action through, since it is viewer input (INTERFACES §18.6).
318
+ */
319
+ const admit = async (
320
+ artifactId: string,
321
+ operation: "run" | "run.wait" | "call",
322
+ ): Promise<void> => {
323
+ if (!options.limit) return;
324
+ const verdict = await options.limit(artifactId, operation);
325
+ if (verdict.allowed !== false) return;
326
+ const error = failed(
327
+ operation === "run.wait" ? "MOSTRA_REMOTE_QUEUE_FULL" : "MOSTRA_REMOTE_LIMIT_REACHED",
328
+ verdict.message,
329
+ ) as RpcError & { retryAfter?: number };
330
+ if (verdict.retryAfterMs !== undefined) {
331
+ error.retryAfter = Math.max(1, Math.ceil(verdict.retryAfterMs / 1000));
332
+ }
333
+ throw error;
291
334
  };
292
335
 
336
+ /**
337
+ * What may have changed while the operator answered (MT-03, the Opus review): a page paused, or
338
+ * its link revoked or expired, runs nothing it asked for before, so both are judged again after
339
+ * every wait, in the same synchronous stretch as the record (D165 item 14, D97 item 5).
340
+ */
341
+ const stillAdmitted = (page: {
342
+ readonly artifactId: string;
343
+ readonly tokenId?: string;
344
+ }): void => {
345
+ const pause = interaction.pauseOf(page.artifactId);
346
+ if (pause) {
347
+ throw failed(
348
+ "MOSTRA_ACTION_PAUSED",
349
+ `This page is paused${pause.by === "operator" ? " by its server's operator" : ""}: its actions don't run until it is resumed.`,
350
+ );
351
+ }
352
+ const tokenId = page.tokenId;
353
+ if (tokenId === undefined) return;
354
+ const token = ledger.read((db) =>
355
+ db.get<{ revoked_at: string | null; expires_at: string | null }>(
356
+ "SELECT revoked_at, expires_at FROM token WHERE id = ?",
357
+ tokenId,
358
+ ),
359
+ );
360
+ if (!token || token.revoked_at !== null) {
361
+ throw failed("MOSTRA_HYGIENE_TOKEN_REVOKED", "This link was revoked.");
362
+ }
363
+ if (token.expires_at !== null && Date.parse(token.expires_at) <= now()) {
364
+ throw failed("MOSTRA_HYGIENE_TOKEN_REVOKED", "This link has expired.");
365
+ }
366
+ };
367
+
368
+ /**
369
+ * Run requests still on their way to a record, by the client key and the key they would join:
370
+ * a duplicate sent meanwhile waits for the first one's outcome, then joins what it recorded
371
+ * (asking nothing) or, if it recorded nothing, goes on as itself (MT-03, the Opus review).
372
+ */
373
+ const inflight = new Map<string, Promise<unknown>>();
374
+ const inflightKeys = (
375
+ artifactId: string,
376
+ input: { readonly clientKey: string; readonly key?: string | undefined; readonly fnId: string },
377
+ ): string[] => [
378
+ `${artifactId}\u0000c\u0000${input.clientKey}`,
379
+ ...(input.key !== undefined
380
+ ? [`${artifactId}\u0000k\u0000${input.fnId}\u0000${input.key}`]
381
+ : []),
382
+ ];
383
+
293
384
  const checkArgs = (args: Batches): void => {
294
385
  if (JSON.stringify(args).length > ACTION_ARGS_MAX) {
295
386
  throw failed(
@@ -817,19 +908,141 @@ export function createHostedRelay(options: HostedRelayOptions): HostedRelay {
817
908
  : { ...state, ownerUnreachable: true };
818
909
  };
819
910
 
911
+ /** Starts or joins a relayed run: `startRun` without its guard against concurrent duplicates. */
912
+ const beginRun = async (
913
+ page: Parameters<HostedRelay["startRun"]>[0],
914
+ input: Parameters<HostedRelay["startRun"]>[1],
915
+ ): Promise<RunState> => {
916
+ checkArgs(input.args);
917
+ const versionId = interaction.viewVersion(page, input.viewId);
918
+ const version = functionOf(versionId, input.fnId);
919
+ mayTrigger(page.viewerId, version);
920
+ // A request that joins a run already recorded starts nothing: it isn't counted against its
921
+ // link, nor asked of the operator, as a repeated submit isn't (D166 item 19).
922
+ const joins = joinsRun(page.artifactId, input);
923
+ const giveBack = joins ? () => {} : limitLink(page.tokenId);
924
+ const owner = options.ownerOf(page.artifactId);
925
+ /**
926
+ * Past the cap a run is refused before anything is recorded (D165 item 4). A request that
927
+ * joins a run already recorded is never refused.
928
+ */
929
+ const capped = (link: string): void => {
930
+ if (sessionFor(link) !== undefined || version.policy !== "queue") return;
931
+ const waiting = ledger.read(
932
+ (db) =>
933
+ db.get<{ n: number }>(
934
+ "SELECT COUNT(*) AS n FROM action_run WHERE artifact_id = ? AND status = 'waiting'",
935
+ page.artifactId,
936
+ )?.n ?? 0,
937
+ );
938
+ if (waiting >= cap && !joinsRun(page.artifactId, input)) {
939
+ throw failed(
940
+ "MOSTRA_REMOTE_QUEUE_FULL",
941
+ "Too many actions are waiting for this page's owner; try again once it is back.",
942
+ );
943
+ }
944
+ };
945
+ // Every refusal from here to the record gives the link's use back, since nothing ran.
946
+ try {
947
+ if (owner === undefined) {
948
+ throw failed("MOSTRA_REMOTE_OWNER_OFFLINE", "This page has no owner instance to run it.");
949
+ }
950
+ capped(owner);
951
+ if (!joins) {
952
+ // The operator's `limits` before anything is recorded (D165 item 9): `run`, then
953
+ // `run.wait` when the run would wait for its absent owner, judged once `run` is
954
+ // answered, so an owner who left meanwhile is seen.
955
+ await admit(page.artifactId, "run");
956
+ if (sessionFor(owner) === undefined && version.policy === "queue") {
957
+ await admit(page.artifactId, "run.wait");
958
+ }
959
+ // The queue may have filled while the operator answered.
960
+ capped(owner);
961
+ }
962
+ // A pause, or a revoked or expired link, while this request waited stops it here, in the
963
+ // same synchronous stretch as the record below.
964
+ stillAdmitted(page);
965
+ } catch (error) {
966
+ giveBack();
967
+ throw error;
968
+ }
969
+ const connected = sessionFor(owner) !== undefined;
970
+ const { state, row, started } = interaction.startRun(page, input);
971
+ bus.attachRuns(page.artifactId, input.viewId, [state.runId]);
972
+ if (!started) {
973
+ // Another request recorded this run while the operator answered: it joins, uncounted.
974
+ giveBack();
975
+ return decorate(state, page.artifactId);
976
+ }
977
+ // The relay's record, in the order runs were made: its sequence is unique per owner link and
978
+ // continues above the owner's mark after a restore (§18.2).
979
+ const recorded = Date.parse(row.started_at);
980
+ const waitingState = ledger.write((db) => {
981
+ const seq =
982
+ (db.get<{ high: number | null }>(
983
+ "SELECT MAX(relay_seq) AS high FROM relay_run WHERE owner_link_id = ?",
984
+ owner,
985
+ )?.high ?? 0) + 1;
986
+ const floor = Math.max(
987
+ marks.get(owner) ?? 0,
988
+ db.get<{ floor: number }>("SELECT floor FROM relay_floor WHERE link_id = ?", owner)
989
+ ?.floor ?? 0,
990
+ );
991
+ db.run(
992
+ "INSERT INTO relay_run (run_id, owner_link_id, relay_seq, offline_limit_at) VALUES (?, ?, ?, ?)",
993
+ row.id,
994
+ owner,
995
+ Math.max(seq, floor + 1),
996
+ iso(recorded + version.limitMs),
997
+ );
998
+ if (connected) return undefined;
999
+ markWaiting(db, row.id);
1000
+ const after = runRow(db, row.id);
1001
+ return after ? runState(db, after) : undefined;
1002
+ });
1003
+ if (connected) {
1004
+ const session = sessionFor(owner);
1005
+ if (session !== undefined) void send(row.id, session);
1006
+ return state;
1007
+ }
1008
+ if (version.policy === "fail") {
1009
+ endOffline(row.id);
1010
+ return interaction.runState(row.id) ?? state;
1011
+ }
1012
+ if (waitingState) publish(waitingState, page.artifactId);
1013
+ return waitingState ?? state;
1014
+ };
1015
+
820
1016
  return {
821
1017
  async call(page, input, signal) {
822
1018
  checkArgs(input.args);
823
1019
  const versionId = interaction.viewVersion(page, input.viewId);
824
1020
  mayTrigger(page.viewerId, functionOf(versionId, input.fnId));
825
- limitLink(page.tokenId);
826
- const owner = options.ownerOf(page.artifactId);
827
- const session = owner === undefined ? undefined : sessionFor(owner);
828
- if (session === undefined) {
829
- throw failed(
1021
+ const giveBack = limitLink(page.tokenId);
1022
+ const offline = (): RpcError =>
1023
+ failed(
830
1024
  "MOSTRA_REMOTE_OWNER_OFFLINE",
831
1025
  "The page's owner is offline, so its server code can't answer now; try again later.",
832
1026
  );
1027
+ // Every refusal from here to the relay gives the link's use back, since nothing ran.
1028
+ let session: number;
1029
+ try {
1030
+ const owner = options.ownerOf(page.artifactId);
1031
+ if (owner === undefined || sessionFor(owner) === undefined) throw offline();
1032
+ // The operator's `limits` before anything is relayed (D165 item 9).
1033
+ await admit(page.artifactId, "call");
1034
+ // While the operator answered: the viewer may have gone (nobody would get the answer),
1035
+ // the page may have been paused or its link revoked, and the owner may have left.
1036
+ if (signal.aborted) {
1037
+ throw failed("MOSTRA_ACTION_CANCELLED", "The page stopped waiting for this call.");
1038
+ }
1039
+ stillAdmitted(page);
1040
+ const current = sessionFor(owner);
1041
+ if (current === undefined) throw offline();
1042
+ session = current;
1043
+ } catch (error) {
1044
+ giveBack();
1045
+ throw error;
833
1046
  }
834
1047
  const callId = `call_${crypto.randomUUID()}`;
835
1048
  const pending: PendingCall = { session, lines: [], ended: false, lastSeq: 0 };
@@ -880,84 +1093,22 @@ export function createHostedRelay(options: HostedRelayOptions): HostedRelay {
880
1093
  return lines();
881
1094
  },
882
1095
 
883
- startRun(page, input) {
884
- checkArgs(input.args);
885
- const versionId = interaction.viewVersion(page, input.viewId);
886
- const version = functionOf(versionId, input.fnId);
887
- mayTrigger(page.viewerId, version);
888
- limitLink(page.tokenId, page.artifactId, input);
889
- const owner = options.ownerOf(page.artifactId);
890
- if (owner === undefined) {
891
- throw failed("MOSTRA_REMOTE_OWNER_OFFLINE", "This page has no owner instance to run it.");
892
- }
893
- const connected = sessionFor(owner) !== undefined;
894
- // Past the cap a run is refused before anything is recorded (D165 item 4). A request that
895
- // joins a run already recorded is never refused.
896
- if (!connected && version.policy === "queue") {
897
- const waiting = ledger.read(
898
- (db) =>
899
- db.get<{ n: number }>(
900
- "SELECT COUNT(*) AS n FROM action_run WHERE artifact_id = ? AND status = 'waiting'",
901
- page.artifactId,
902
- )?.n ?? 0,
903
- );
904
- const joins = ledger.read(
905
- (db) =>
906
- db.get<{ id: string }>(
907
- `SELECT id FROM action_run WHERE artifact_id = ? AND (client_key = ? OR (key IS NOT NULL AND key = ? AND action = ?))`,
908
- page.artifactId,
909
- input.clientKey,
910
- input.key ?? null,
911
- input.fnId,
912
- ) !== undefined,
913
- );
914
- if (waiting >= cap && !joins) {
915
- throw failed(
916
- "MOSTRA_REMOTE_QUEUE_FULL",
917
- "Too many actions are waiting for this page's owner; try again once it is back.",
918
- );
919
- }
920
- }
921
- const { state, row, started } = interaction.startRun(page, input);
922
- bus.attachRuns(page.artifactId, input.viewId, [state.runId]);
923
- if (!started) return decorate(state, page.artifactId);
924
- // The relay's record, in the order runs were made: its sequence is unique per owner link and
925
- // continues above the owner's mark after a restore (§18.2).
926
- const recorded = Date.parse(row.started_at);
927
- const waitingState = ledger.write((db) => {
928
- const seq =
929
- (db.get<{ high: number | null }>(
930
- "SELECT MAX(relay_seq) AS high FROM relay_run WHERE owner_link_id = ?",
931
- owner,
932
- )?.high ?? 0) + 1;
933
- const floor = Math.max(
934
- marks.get(owner) ?? 0,
935
- db.get<{ floor: number }>("SELECT floor FROM relay_floor WHERE link_id = ?", owner)
936
- ?.floor ?? 0,
937
- );
938
- db.run(
939
- "INSERT INTO relay_run (run_id, owner_link_id, relay_seq, offline_limit_at) VALUES (?, ?, ?, ?)",
940
- row.id,
941
- owner,
942
- Math.max(seq, floor + 1),
943
- iso(recorded + version.limitMs),
944
- );
945
- if (connected) return undefined;
946
- markWaiting(db, row.id);
947
- const after = runRow(db, row.id);
948
- return after ? runState(db, after) : undefined;
949
- });
950
- if (connected) {
951
- const session = sessionFor(owner);
952
- if (session !== undefined) void send(row.id, session);
953
- return state;
1096
+ async startRun(page, input) {
1097
+ // A duplicate of a request still on its way to its record waits for it first, so the
1098
+ // operator is asked once for one run and the duplicate joins what it recorded.
1099
+ const keys = inflightKeys(page.artifactId, input);
1100
+ for (;;) {
1101
+ const prior = keys.map((key) => inflight.get(key)).find((found) => found !== undefined);
1102
+ if (prior === undefined) break;
1103
+ await prior.catch(() => undefined);
954
1104
  }
955
- if (version.policy === "fail") {
956
- endOffline(row.id);
957
- return interaction.runState(row.id) ?? state;
1105
+ const started = beginRun(page, input);
1106
+ for (const key of keys) inflight.set(key, started);
1107
+ try {
1108
+ return await started;
1109
+ } finally {
1110
+ for (const key of keys) if (inflight.get(key) === started) inflight.delete(key);
958
1111
  }
959
- if (waitingState) publish(waitingState, page.artifactId);
960
- return waitingState ?? state;
961
1112
  },
962
1113
 
963
1114
  attach(page, input) {