@mostra/cli 0.10.0 → 0.12.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 (48) hide show
  1. package/dist/bin.js +2 -2
  2. package/dist/{bootstrap-_iCl_HaO.js → bootstrap-3_Tdfdg7.js} +3 -2
  3. package/dist/bootstrap-3_Tdfdg7.js.map +1 -0
  4. package/dist/bootstrap-C9a2gSWf.js +1 -0
  5. package/dist/{flush-znWmNZA1.js → flush-TPaIdwjy.js} +3 -1
  6. package/dist/flush-TPaIdwjy.js.map +1 -0
  7. package/dist/index.d.ts.map +1 -1
  8. package/dist/index.js +2 -2
  9. package/dist/reference/cli.md +178 -2
  10. package/dist/reference/diagnostics.json +108 -0
  11. package/dist/reference/errors/MOSTRA_ACTION_PAUSED.md +23 -0
  12. package/dist/reference/errors/MOSTRA_REMOTE_HOME_MOVING.md +23 -0
  13. package/dist/reference/errors/MOSTRA_REMOTE_HOME_SUSPENDED.md +23 -0
  14. package/dist/reference/errors/MOSTRA_REMOTE_LIMIT_REACHED.md +23 -0
  15. package/dist/reference/errors/MOSTRA_REMOTE_NO_INSTANCE.md +23 -0
  16. package/dist/reference/errors/MOSTRA_REMOTE_OPERATOR_UNAVAILABLE.md +23 -0
  17. package/dist/reference/errors/MOSTRA_REMOTE_PAUSED_BY_OPERATOR.md +23 -0
  18. package/dist/reference/errors/MOSTRA_REMOTE_UNDER_REVIEW.md +23 -0
  19. package/dist/reference/errors/MOSTRA_SUBMIT_PAUSED.md +23 -0
  20. package/dist/reference/errors/MOSTRA_TEAM_PRESENCE_RATE_LIMITED.md +23 -0
  21. package/dist/reference/errors/MOSTRA_TEAM_ROSTER_POLICY.md +23 -0
  22. package/dist/reference/errors/MOSTRA_TEAM_ROSTER_TOO_LARGE.md +23 -0
  23. package/dist/reference/self-hosting.md +130 -0
  24. package/dist/{run-Aq4HVIY0.js → run-CtR0PFMj.js} +349 -231
  25. package/dist/run-CtR0PFMj.js.map +1 -0
  26. package/dist/run-NWeQcyh9.js +1 -0
  27. package/dist/skill/SKILL.md +7 -3
  28. package/dist/skill/references/answers.md +3 -1
  29. package/dist/skill/references/mcp.md +8 -3
  30. package/dist/skill/references/sharing.md +1 -0
  31. package/dist/skill/references/teams.md +78 -0
  32. package/dist/telemetry/flush-main.js +1 -1
  33. package/package.json +5 -5
  34. package/src/commands/admin.ts +2 -2
  35. package/src/commands/index.ts +7 -1
  36. package/src/commands/interaction.ts +43 -2
  37. package/src/commands/remote.ts +99 -3
  38. package/src/commands/sharing.ts +19 -1
  39. package/src/commands/team.ts +191 -0
  40. package/src/detached.ts +2 -0
  41. package/src/docs.ts +12 -217
  42. package/src/exit.ts +2 -0
  43. package/src/mcp.ts +3 -21
  44. package/dist/bootstrap-BStzS_41.js +0 -1
  45. package/dist/bootstrap-_iCl_HaO.js.map +0 -1
  46. package/dist/flush-znWmNZA1.js.map +0 -1
  47. package/dist/run-Aq4HVIY0.js.map +0 -1
  48. package/dist/run-D1U_RFEP.js +0 -1
@@ -54,6 +54,15 @@
54
54
  "explanation": "The action run's worker crashed, ran out of memory, was stopped by the event-loop watchdog, or the instance stopped while the run was running. The run ends `failed` with the reason `interrupted`, and Mostra never retries it by itself (D24): an action that had already started a side effect, such as sending an email, may or may not have finished it.",
55
55
  "fix": "Look at the effect where it happens (the mail provider's sent folder, say) before running the action again. Pass the provider's own idempotency key from the action (for example, the run's key) so a repeated request can't act twice."
56
56
  },
57
+ {
58
+ "code": "MOSTRA_ACTION_PAUSED",
59
+ "severity": "error",
60
+ "phase": "host",
61
+ "title": "Artifact paused, no actions run",
62
+ "hint": "Wait until the page is resumed, then run the action again.",
63
+ "explanation": "The artifact is paused, so its actions don't run: the run or call was refused before anything was recorded or sent to the owner's machine.",
64
+ "fix": "The owner resumes it with `mostra resume <artifact>`; a pause by the server's operator is resumed only by the operator."
65
+ },
57
66
  {
58
67
  "code": "MOSTRA_ACTION_RUN_NOT_FOUND",
59
68
  "severity": "error",
@@ -1098,6 +1107,33 @@
1098
1107
  "explanation": "`mostra-runtime server` reads its configuration (the file `--config` names and `MOSTRA_SERVER_*` variables) before it serves anything, and stops when a key is missing, of the wrong type or out of range, naming the key. Nothing was served.",
1099
1108
  "fix": "Correct the key the message names: `apiOrigin` must be an `https:` origin (or `http:` on loopback), and `domains.active` a host name."
1100
1109
  },
1110
+ {
1111
+ "code": "MOSTRA_REMOTE_HOME_MOVING",
1112
+ "severity": "error",
1113
+ "phase": "host",
1114
+ "title": "This account's pages are moving",
1115
+ "hint": "Try again in a minute: this account's pages are moving between machines.",
1116
+ "explanation": "The server's operator is moving this account's hosted home to another data directory (`drainHome`), so the home is closed here until it serves again. Clients retry; nothing is lost.",
1117
+ "fix": "Retry shortly; the move ends when the operator releases the home on its new machine."
1118
+ },
1119
+ {
1120
+ "code": "MOSTRA_REMOTE_HOME_SUSPENDED",
1121
+ "severity": "error",
1122
+ "phase": "host",
1123
+ "title": "This account's pages are suspended",
1124
+ "hint": "Contact the server's operator: this account's pages are suspended.",
1125
+ "explanation": "The server's operator suspended this account's hosted home: its pages, its owner instances' bindings, pushes and links are refused until the operator resumes it. Nothing was deleted.",
1126
+ "fix": "Ask the server's operator to resume the account."
1127
+ },
1128
+ {
1129
+ "code": "MOSTRA_REMOTE_LIMIT_REACHED",
1130
+ "severity": "error",
1131
+ "phase": "host",
1132
+ "title": "The server's limit refused this",
1133
+ "hint": "Read the message for the server's limit, and try again once it allows the operation.",
1134
+ "explanation": "The server's operator refused the operation for this account (its `limits` port): a share, a version push, a link, a view, a submission, an action or an MCP call. The message is the operator's own. A refused submission keeps its draft.",
1135
+ "fix": "Follow the operator's message; its `Retry-After`, when present, says when to try again."
1136
+ },
1101
1137
  {
1102
1138
  "code": "MOSTRA_REMOTE_LOGIN_FAILED",
1103
1139
  "severity": "error",
@@ -1107,6 +1143,15 @@
1107
1143
  "explanation": "Signing this home in to a remote server didn't finish: the code expired, the person refused it, the server refused the client, or the binding's access token was refused (revoked, expired, or for another server). Nothing of the home changed; artifacts it owns on that server stay its own.",
1108
1144
  "fix": "Sign in to the server again and approve the code on the page it names. A refusal you didn't expect means the sign-in was revoked on the server."
1109
1145
  },
1146
+ {
1147
+ "code": "MOSTRA_REMOTE_NO_INSTANCE",
1148
+ "severity": "error",
1149
+ "phase": "host",
1150
+ "title": "No owner instance connected",
1151
+ "hint": "Start Mostra on the machine linked to this account (mostra daemon start), then try again.",
1152
+ "explanation": "Creating, verifying and publishing from a chat host run on the account's default owner instance, through the relay (D165 item 5), and no default instance is connected to the server now. Reading tools (list, wait, results, state, docs, open) keep working.",
1153
+ "fix": "Start Mostra on the linked machine (`mostra daemon start`, or `mostra daemon install` to keep it running); link a machine first with `mostra login <server> --default`."
1154
+ },
1110
1155
  {
1111
1156
  "code": "MOSTRA_REMOTE_NOT_OWNER_INSTANCE",
1112
1157
  "severity": "error",
@@ -1116,6 +1161,15 @@
1116
1161
  "explanation": "A hosted artifact has one owner instance: the one that shared it. It alone receives the artifact's submissions, relayed runs and authoring, and only it pushes versions of it (D165 item 1b). Another instance of the same account reads and waits through the hosted home.",
1117
1162
  "fix": "Run the command on the instance the message names. Moving an artifact to another owner instance isn't part of this release."
1118
1163
  },
1164
+ {
1165
+ "code": "MOSTRA_REMOTE_OPERATOR_UNAVAILABLE",
1166
+ "severity": "error",
1167
+ "phase": "host",
1168
+ "title": "The server's operator didn't answer",
1169
+ "hint": "Try again in a moment; the server's operator didn't answer in time.",
1170
+ "explanation": "The server's operator module didn't answer in time (2 s for limits, 5 s for sign-in), so an operation that creates something (a share, a push, a link, authoring, a sign-in) was refused rather than allowed blind. Views, drafts and submissions never wait for it, and existing sessions keep working.",
1171
+ "fix": "Try again; if it lasts, the server's operator has to fix its operator module."
1172
+ },
1119
1173
  {
1120
1174
  "code": "MOSTRA_REMOTE_OWNER_OFFLINE",
1121
1175
  "severity": "error",
@@ -1125,6 +1179,15 @@
1125
1179
  "explanation": "A hosted page called server code its owner instance runs, and the owner instance isn't connected. A plain call isn't kept, so it is refused at once; an action run waits or fails as the artifact's `hosted.offline` says.",
1126
1180
  "fix": "Start Mostra on the owner's machine (`mostra daemon start`, or `mostra daemon install` for always-on). An action that must work while the owner is away should be an action run with `hosted.offline.actions: \"queue\"`."
1127
1181
  },
1182
+ {
1183
+ "code": "MOSTRA_REMOTE_PAUSED_BY_OPERATOR",
1184
+ "severity": "error",
1185
+ "phase": "host",
1186
+ "title": "Paused by the server's operator",
1187
+ "hint": "Contact the server's operator: only the operator resumes a pause it made.",
1188
+ "explanation": "The server's operator paused this hosted artifact, and an owner can't undo an operator's pause (D165 item 14). Views keep working and the links stay valid.",
1189
+ "fix": "Ask the server's operator why it was paused and to resume it."
1190
+ },
1128
1191
  {
1129
1192
  "code": "MOSTRA_REMOTE_QUEUE_FULL",
1130
1193
  "severity": "error",
@@ -1152,6 +1215,15 @@
1152
1215
  "explanation": "On a hosted link, an action that runs on the owner's machine, or a submission when the artifact asks for it, needs a viewer signed in (D159, D165 item 13). Nothing was recorded.",
1153
1216
  "fix": "Sign in with the page's Sign in. An owner who wants anyone with the link to run actions sets `hosted: { actions: \"link\" }` in the manifest (and `submissions: \"link\"` for answers)."
1154
1217
  },
1218
+ {
1219
+ "code": "MOSTRA_REMOTE_UNDER_REVIEW",
1220
+ "severity": "error",
1221
+ "phase": "host",
1222
+ "title": "This page is under review",
1223
+ "hint": "Nothing to do here: the server's operator is reviewing this page.",
1224
+ "explanation": "The server's operator quarantined this hosted page, or this version of it, while it reviews it. Its data is kept; the page shows a neutral notice instead of its content until the operator releases it.",
1225
+ "fix": "The owner can ask the server's operator about the review."
1226
+ },
1155
1227
  {
1156
1228
  "code": "MOSTRA_REMOTE_UNREACHABLE",
1157
1229
  "severity": "error",
@@ -1332,6 +1404,15 @@
1332
1404
  "explanation": "The artifact has no submission yet, or none with the ID asked for. Submissions are durable once made, so this means none was made (or the ID belongs to another artifact or home). An artifact whose submission policy is `none` never has one, and the message says so: its viewers' work is in its shared state, its signals and its action runs.",
1333
1405
  "fix": "Run `mostra wait <artifact> --until submitted` to block until the viewer submits, then read the results. List the artifact's submissions through `submission.created` events. Under policy `none`, read the shared state with `mostra state get <artifact>`, or wait for a signal the page raises with `mostra wait <artifact> --until signal:<name>`: its event carries the signal's payload."
1334
1406
  },
1407
+ {
1408
+ "code": "MOSTRA_SUBMIT_PAUSED",
1409
+ "severity": "error",
1410
+ "phase": "host",
1411
+ "title": "Artifact paused, no answers taken",
1412
+ "hint": "Wait until the page is resumed, then submit again; the draft is kept.",
1413
+ "explanation": "The artifact is paused (`mostra pause`, or its server's operator paused it). A paused artifact stays viewable and its links stay valid, but it takes no submissions until it is resumed. Nothing was recorded, and the draft stays as it was.",
1414
+ "fix": "The owner resumes it with `mostra resume <artifact>`; a pause by the server's operator is resumed only by the operator."
1415
+ },
1335
1416
  {
1336
1417
  "code": "MOSTRA_SUBMIT_POLICY_NONE",
1337
1418
  "severity": "error",
@@ -1377,6 +1458,33 @@
1377
1458
  "explanation": "The page called something that needs Mostra's server, such as a server function, and this delivery target doesn't provide it: a static export, a file opened from disk, or a runtime without server support. The page keeps working without it.",
1378
1459
  "fix": "Open the artifact through its Mostra link, where server functions, submissions and live data are available. In a static export, handle the error so the page explains what isn't available."
1379
1460
  },
1461
+ {
1462
+ "code": "MOSTRA_TEAM_PRESENCE_RATE_LIMITED",
1463
+ "severity": "error",
1464
+ "phase": "hygiene",
1465
+ "title": "Presence updates too fast",
1466
+ "hint": "Send presence at most 10 times a second; usePresence does this for you.",
1467
+ "explanation": "A page shares its viewer's cursor and selection through `POST /_mostra/v/<rev>/presence`. Each view may send 20 updates a second; past that the gateway answers 429 with `Retry-After`. Presence is never stored, so nothing is lost: the next update replaces the last one.",
1468
+ "fix": "Use `usePresence` from `@mostra/react`, which sends at most 10 updates a second, or throttle your own calls to the route."
1469
+ },
1470
+ {
1471
+ "code": "MOSTRA_TEAM_ROSTER_POLICY",
1472
+ "severity": "error",
1473
+ "phase": "host",
1474
+ "title": "This artifact's policy can't wait for every respondent",
1475
+ "hint": "Publish with the submission policy once per-viewer or epochs, then wait again; or wait for submitted.",
1476
+ "explanation": "`submitted:all` waits until every expected respondent has submitted, and `submitted:<N>` for N submissions. Both need a policy that takes a submission from each person: `once` with scope `per-viewer`, or `epochs`. Under `once` per-artifact the artifact takes one submission in all, so neither can be met beyond the first, and Mostra refuses the wait instead of letting it run forever.",
1477
+ "fix": "Publish again with `mostra publish <path> --policy once-per-viewer` (or `--policy epochs`), or wait for `submitted`."
1478
+ },
1479
+ {
1480
+ "code": "MOSTRA_TEAM_ROSTER_TOO_LARGE",
1481
+ "severity": "error",
1482
+ "phase": "host",
1483
+ "title": "Roster larger than 1,000 respondents",
1484
+ "hint": "Name at most 1,000 expected respondents; share one link for everyone else instead.",
1485
+ "explanation": "A roster lists the people an artifact expects answers from, each with a personal link and a status. It holds at most 1,000 of them. Nothing was added: the roster is as it was.",
1486
+ "fix": "Remove respondents you no longer expect (`mostra roster remove`), or, for a page many people answer, share one link and wait for `submitted:<N>` instead."
1487
+ },
1380
1488
  {
1381
1489
  "code": "MOSTRA_TYPE_ERROR",
1382
1490
  "severity": "error",
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_ACTION_PAUSED
3
+ severity: error
4
+ phase: host
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_ACTION_PAUSED
10
+
11
+ Artifact paused, no actions run. Severity: error. Phase: host.
12
+
13
+ ## What it means
14
+
15
+ The artifact is paused, so its actions don't run: the run or call was refused before anything was recorded or sent to the owner's machine.
16
+
17
+ ## How to fix it
18
+
19
+ The owner resumes it with `mostra resume <artifact>`; a pause by the server's operator is resumed only by the operator.
20
+
21
+ ## Hint
22
+
23
+ Wait until the page is resumed, then run the action again.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_REMOTE_HOME_MOVING
3
+ severity: error
4
+ phase: host
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_REMOTE_HOME_MOVING
10
+
11
+ This account's pages are moving. Severity: error. Phase: host.
12
+
13
+ ## What it means
14
+
15
+ The server's operator is moving this account's hosted home to another data directory (`drainHome`), so the home is closed here until it serves again. Clients retry; nothing is lost.
16
+
17
+ ## How to fix it
18
+
19
+ Retry shortly; the move ends when the operator releases the home on its new machine.
20
+
21
+ ## Hint
22
+
23
+ Try again in a minute: this account's pages are moving between machines.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_REMOTE_HOME_SUSPENDED
3
+ severity: error
4
+ phase: host
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_REMOTE_HOME_SUSPENDED
10
+
11
+ This account's pages are suspended. Severity: error. Phase: host.
12
+
13
+ ## What it means
14
+
15
+ The server's operator suspended this account's hosted home: its pages, its owner instances' bindings, pushes and links are refused until the operator resumes it. Nothing was deleted.
16
+
17
+ ## How to fix it
18
+
19
+ Ask the server's operator to resume the account.
20
+
21
+ ## Hint
22
+
23
+ Contact the server's operator: this account's pages are suspended.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_REMOTE_LIMIT_REACHED
3
+ severity: error
4
+ phase: host
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_REMOTE_LIMIT_REACHED
10
+
11
+ The server's limit refused this. Severity: error. Phase: host.
12
+
13
+ ## What it means
14
+
15
+ The server's operator refused the operation for this account (its `limits` port): a share, a version push, a link, a view, a submission, an action or an MCP call. The message is the operator's own. A refused submission keeps its draft.
16
+
17
+ ## How to fix it
18
+
19
+ Follow the operator's message; its `Retry-After`, when present, says when to try again.
20
+
21
+ ## Hint
22
+
23
+ Read the message for the server's limit, and try again once it allows the operation.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_REMOTE_NO_INSTANCE
3
+ severity: error
4
+ phase: host
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_REMOTE_NO_INSTANCE
10
+
11
+ No owner instance connected. Severity: error. Phase: host.
12
+
13
+ ## What it means
14
+
15
+ Creating, verifying and publishing from a chat host run on the account's default owner instance, through the relay (D165 item 5), and no default instance is connected to the server now. Reading tools (list, wait, results, state, docs, open) keep working.
16
+
17
+ ## How to fix it
18
+
19
+ Start Mostra on the linked machine (`mostra daemon start`, or `mostra daemon install` to keep it running); link a machine first with `mostra login <server> --default`.
20
+
21
+ ## Hint
22
+
23
+ Start Mostra on the machine linked to this account (mostra daemon start), then try again.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_REMOTE_OPERATOR_UNAVAILABLE
3
+ severity: error
4
+ phase: host
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_REMOTE_OPERATOR_UNAVAILABLE
10
+
11
+ The server's operator didn't answer. Severity: error. Phase: host.
12
+
13
+ ## What it means
14
+
15
+ The server's operator module didn't answer in time (2 s for limits, 5 s for sign-in), so an operation that creates something (a share, a push, a link, authoring, a sign-in) was refused rather than allowed blind. Views, drafts and submissions never wait for it, and existing sessions keep working.
16
+
17
+ ## How to fix it
18
+
19
+ Try again; if it lasts, the server's operator has to fix its operator module.
20
+
21
+ ## Hint
22
+
23
+ Try again in a moment; the server's operator didn't answer in time.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_REMOTE_PAUSED_BY_OPERATOR
3
+ severity: error
4
+ phase: host
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_REMOTE_PAUSED_BY_OPERATOR
10
+
11
+ Paused by the server's operator. Severity: error. Phase: host.
12
+
13
+ ## What it means
14
+
15
+ The server's operator paused this hosted artifact, and an owner can't undo an operator's pause (D165 item 14). Views keep working and the links stay valid.
16
+
17
+ ## How to fix it
18
+
19
+ Ask the server's operator why it was paused and to resume it.
20
+
21
+ ## Hint
22
+
23
+ Contact the server's operator: only the operator resumes a pause it made.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_REMOTE_UNDER_REVIEW
3
+ severity: error
4
+ phase: host
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_REMOTE_UNDER_REVIEW
10
+
11
+ This page is under review. Severity: error. Phase: host.
12
+
13
+ ## What it means
14
+
15
+ The server's operator quarantined this hosted page, or this version of it, while it reviews it. Its data is kept; the page shows a neutral notice instead of its content until the operator releases it.
16
+
17
+ ## How to fix it
18
+
19
+ The owner can ask the server's operator about the review.
20
+
21
+ ## Hint
22
+
23
+ Nothing to do here: the server's operator is reviewing this page.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_SUBMIT_PAUSED
3
+ severity: error
4
+ phase: host
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_SUBMIT_PAUSED
10
+
11
+ Artifact paused, no answers taken. Severity: error. Phase: host.
12
+
13
+ ## What it means
14
+
15
+ The artifact is paused (`mostra pause`, or its server's operator paused it). A paused artifact stays viewable and its links stay valid, but it takes no submissions until it is resumed. Nothing was recorded, and the draft stays as it was.
16
+
17
+ ## How to fix it
18
+
19
+ The owner resumes it with `mostra resume <artifact>`; a pause by the server's operator is resumed only by the operator.
20
+
21
+ ## Hint
22
+
23
+ Wait until the page is resumed, then submit again; the draft is kept.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_TEAM_PRESENCE_RATE_LIMITED
3
+ severity: error
4
+ phase: hygiene
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_TEAM_PRESENCE_RATE_LIMITED
10
+
11
+ Presence updates too fast. Severity: error. Phase: hygiene.
12
+
13
+ ## What it means
14
+
15
+ A page shares its viewer's cursor and selection through `POST /_mostra/v/<rev>/presence`. Each view may send 20 updates a second; past that the gateway answers 429 with `Retry-After`. Presence is never stored, so nothing is lost: the next update replaces the last one.
16
+
17
+ ## How to fix it
18
+
19
+ Use `usePresence` from `@mostra/react`, which sends at most 10 updates a second, or throttle your own calls to the route.
20
+
21
+ ## Hint
22
+
23
+ Send presence at most 10 times a second; usePresence does this for you.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_TEAM_ROSTER_POLICY
3
+ severity: error
4
+ phase: host
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_TEAM_ROSTER_POLICY
10
+
11
+ This artifact's policy can't wait for every respondent. Severity: error. Phase: host.
12
+
13
+ ## What it means
14
+
15
+ `submitted:all` waits until every expected respondent has submitted, and `submitted:<N>` for N submissions. Both need a policy that takes a submission from each person: `once` with scope `per-viewer`, or `epochs`. Under `once` per-artifact the artifact takes one submission in all, so neither can be met beyond the first, and Mostra refuses the wait instead of letting it run forever.
16
+
17
+ ## How to fix it
18
+
19
+ Publish again with `mostra publish <path> --policy once-per-viewer` (or `--policy epochs`), or wait for `submitted`.
20
+
21
+ ## Hint
22
+
23
+ Publish with the submission policy once per-viewer or epochs, then wait again; or wait for submitted.
@@ -0,0 +1,23 @@
1
+ ---
2
+ code: MOSTRA_TEAM_ROSTER_TOO_LARGE
3
+ severity: error
4
+ phase: host
5
+ ---
6
+
7
+ <!-- Generated from packages/protocol/src/diagnostics/codes by `node tools/docs/diagnostics.ts write`. Edit the area file, not this page. -->
8
+
9
+ # MOSTRA_TEAM_ROSTER_TOO_LARGE
10
+
11
+ Roster larger than 1,000 respondents. Severity: error. Phase: host.
12
+
13
+ ## What it means
14
+
15
+ A roster lists the people an artifact expects answers from, each with a personal link and a status. It holds at most 1,000 of them. Nothing was added: the roster is as it was.
16
+
17
+ ## How to fix it
18
+
19
+ Remove respondents you no longer expect (`mostra roster remove`), or, for a page many people answer, share one link and wait for `submitted:<N>` instead.
20
+
21
+ ## Hint
22
+
23
+ Name at most 1,000 expected respondents; share one link for everyone else instead.
@@ -0,0 +1,130 @@
1
+ # Self-hosting the remote server
2
+
3
+ The remote server hosts shared pages so their links keep working while the machine that shared them sleeps. It also hosts the remote MCP endpoint for chat apps. You run it as one container behind a TLS front. This page shows the shape with Caddy. Any TLS terminator that keeps the request's `Host` and adds `X-Forwarded-For` works the same way.
4
+
5
+ ## What you need
6
+
7
+ - **A host name for the API origin**, such as `api.example.com`. Owners sign in and connect there, chat apps reach `/mcp` there, and version files upload there.
8
+ - **A user-content domain of its own**, such as `example-usercontent.com`. Its apex serves the hosted shell, and each shared page gets a random label under it (`<label>.example-usercontent.com`). Use a registrable domain that serves nothing else, and keep the API origin off it. A page on it can set cookies for the whole domain, so nothing else should live there.
9
+ - **DNS** for the API host, the user-content apex and the wildcard `*.example-usercontent.com`, all pointing at your front. Labels are one level deep, so one wildcard certificate covers every page.
10
+ - **One machine** with Docker and a local disk. The data directory can't be on a network filesystem: the server refuses NFS, SMB and network FUSE mounts at start.
11
+
12
+ ## Configuration
13
+
14
+ The server reads a JSON file (`--config`) and `MOSTRA_SERVER_<KEY>` variables. A variable overrides the file's key. It holds JSON, or a plain string for `apiOrigin`, `operator` and `scheme`. If the server can't use a key, it stops before serving anything and names the key (`MOSTRA_REMOTE_CONFIG_INVALID`).
15
+
16
+ ```json
17
+ {
18
+ "apiOrigin": "https://api.example.com",
19
+ "domains": { "active": "example-usercontent.com" },
20
+ "trustedProxies": ["172.31.230.0/24"],
21
+ "identityProviders": [
22
+ {
23
+ "id": "github",
24
+ "kind": "github",
25
+ "label": "GitHub",
26
+ "clientId": "<the OAuth app's client ID>",
27
+ "clientSecretFile": "/run/secrets/github"
28
+ }
29
+ ],
30
+ "rateLimits": {
31
+ "perIp": { "submissions": { "count": 120, "per": "1m" } },
32
+ "perLink": { "submissions": { "count": 600, "per": "1m" } }
33
+ }
34
+ }
35
+ ```
36
+
37
+ | Key | What it does |
38
+ |---|---|
39
+ | `apiOrigin` | The API origin, `https:` |
40
+ | `domains.active`, `domains.spares` | The user-content domain new links use, and older ones that issued links keep working on. To move off a domain, make a spare active and restart the server |
41
+ | `trustedProxies` | Addresses or CIDR ranges whose `X-Forwarded-For` the server believes. It reads the header from the right and takes the first address that isn't a trusted proxy. Rate limits count IPv6 clients per /64 (`rateLimits.ipv6Prefix`) |
42
+ | `identityProviders` | How people sign in: `github` (an OAuth app), `oidc` (any OpenID Connect provider: `issuer`, `clientId`, `clientSecretFile`) or `development` (trusts any typed name; for tests only, never on a public server) |
43
+ | `rateLimits` | Rates as `{ "count", "per" }`: `perIp.submissions` and `perLink.submissions` for answers, `perLink.relayedRuns` for actions, and `perIp.requests` for every request an address sends (a health check aside). Past a rate the answer is 429 with `Retry-After`; a page says to try again shortly and keeps the draft. A key left out is no limit |
44
+ | `relay`, `homes`, `ledger` | The relay's waiting-run cap and drain rate, how long an idle hosted home stays open, and the ledger's WAL checkpoint (`0` for a backup replicator) |
45
+ | `operator` | The path of an operator module, which adds limits, metering, accounts and abuse handling through the operator ports (`@mostra/protocol/operator`). Without one, every port keeps its no-op default |
46
+
47
+ For GitHub sign-in, create an OAuth app with the callback `https://api.example.com/signin/github/callback`. For OpenID Connect, register the redirect URI `https://api.example.com/signin/<id>/callback`. Keep each client secret in a file that only the container's user (UID 10001) can read.
48
+
49
+ ## Running it with Caddy
50
+
51
+ The image is `ghcr.io/mostra-dev/mostra-server`, tagged with each release's version, for `linux/amd64` and `linux/arm64`. It runs `mostra-runtime server` as a non-root user. It listens on port 8080 and keeps everything in `/data`: hosted homes, version files and the server's keys. Append `--config <file>` to its command, or set the `MOSTRA_SERVER_*` variables.
52
+
53
+ `compose.yaml`:
54
+
55
+ ```yaml
56
+ networks:
57
+ front:
58
+ ipam:
59
+ config:
60
+ - subnet: 172.31.230.0/24
61
+ volumes:
62
+ data: {}
63
+ caddy-data: {}
64
+ services:
65
+ mostra-server:
66
+ image: ghcr.io/mostra-dev/mostra-server:<version>
67
+ command: ["--config", "/config/server.json"]
68
+ restart: unless-stopped
69
+ networks: [front]
70
+ read_only: true
71
+ tmpfs: [/tmp]
72
+ volumes:
73
+ - data:/data
74
+ - ./server.json:/config/server.json:ro
75
+ - ./github-secret:/run/secrets/github:ro
76
+ caddy:
77
+ image: <caddy built with the caddy-dns module for your DNS provider>
78
+ restart: unless-stopped
79
+ networks: [front]
80
+ ports: ["80:80", "443:443", "443:443/udp"]
81
+ volumes:
82
+ - ./Caddyfile:/etc/caddy/Caddyfile:ro
83
+ - ./dns-token:/run/secrets/dns-token:ro
84
+ - caddy-data:/data
85
+ ```
86
+
87
+ `Caddyfile`:
88
+
89
+ ```caddyfile
90
+ {
91
+ servers {
92
+ # A sibling page can fill the domain's cookie jar: pass up to 1 MiB of headers.
93
+ max_header_size 1MiB
94
+ }
95
+ }
96
+
97
+ api.example.com {
98
+ reverse_proxy mostra-server:8080
99
+ }
100
+
101
+ example-usercontent.com, *.example-usercontent.com {
102
+ tls {
103
+ dns cloudflare {file./run/secrets/dns-token}
104
+ }
105
+ reverse_proxy mostra-server:8080
106
+ }
107
+ ```
108
+
109
+ The wildcard certificate needs the DNS-01 challenge, so Caddy needs a build with your DNS provider's module (`xcaddy build --with github.com/caddy-dns/<provider>`) and a token that may edit the zone's records, kept in the file `dns-token` beside the `Caddyfile` (readable by the user Caddy runs as, and by nobody else) and read by `{file.…}`, so it is in no environment a process listing or a log can show. Caddy keeps the request's `Host` and adds `X-Forwarded-For`, and the server believes that header only from the network `trustedProxies` names.
110
+
111
+ Check the server once it runs:
112
+
113
+ ```sh
114
+ curl https://api.example.com/health # {"status":"ok",…}
115
+ curl https://api.example.com/.well-known/oauth-authorization-server # the sign-in metadata
116
+ ```
117
+
118
+ An owner then links a machine with `mostra login https://api.example.com` and shares a page with `mostra share <dir> --cloud`. A chat app connects to `https://api.example.com/mcp`.
119
+
120
+ ## Fronts and request headers
121
+
122
+ Hosted pages use no cookies, and the server drops every `Cookie` header unread. A tenant's page can still fill the user-content domain's cookie jar, and browsers then send up to about 720 KiB of cookies with each request. The server accepts headers up to 1 MiB, so such a jar never costs another page its session. Your front has to pass them too. Caddy's default is 16 KiB, so the Caddyfile above raises it with `max_header_size 1MiB`. A CDN or proxy whose limit is smaller fails every page on the domain for a browser whose jar a sibling page filled.
123
+
124
+ ## Backups and restores
125
+
126
+ Each hosted home's ledger is SQLite in WAL mode with normal locking, so a WAL replicator such as Litestream can read it live from its own process. Back up the whole data directory. After restoring a home, or the whole directory, by hand, start the server with `--restored <homeId>` or `--restored all`. The restored homes then rotate their incarnations before they serve anything, so owners never mistake reused cursors for ones they already copied. Each owner's machine also notices a home that holds less than it copied, and records the gap as `remote.regressed`.
127
+
128
+ ## What the open server doesn't do
129
+
130
+ It imposes no quota, link expiry or automatic pause, deletes nothing on its own, and sends no email or webhook. Plans, quotas, billing, abuse scoring, placing homes across machines, backup automation and outside domains come from an operator module through the operator ports. An operator pauses, quarantines, suspends and removes through the server handle the module receives.