@akanjs/cli 3.2.0-rc.9 → 3.2.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 (143) hide show
  1. package/.build-stamp +2 -2
  2. package/CodeAgent-fx6088tv.js +11 -0
  3. package/{CodeTui-qstk5vpj.js → CodeTui-zee8atsr.js} +822 -666
  4. package/README.ko.md +7 -0
  5. package/README.md +7 -0
  6. package/TunnelShare-9ry4vh0y.js +18 -0
  7. package/agent.command-x65f2ags.js +61 -0
  8. package/akanCode.js +12 -12
  9. package/appExecutor-79azsb2w.js +11 -0
  10. package/{application.command-m4rq4wc2.js → application.command-azbd1pb2.js} +83 -37
  11. package/{applicationBuildRunner-df7rx3ra.js → applicationBuildRunner-trfxv3pd.js} +49 -18
  12. package/buildBatch.proc.js +25 -11
  13. package/{cloud.command-a0gy0qq2.js → cloud.command-gapp4634.js} +33 -29
  14. package/cloud.script-3b401efv.js +35 -0
  15. package/{code.command-5rsdqw8s.js → code.command-5smx61yf.js} +13 -9
  16. package/context.command-ym5jbkny.js +64 -0
  17. package/context.runner-kctbfsde.js +34 -0
  18. package/{dependencyScanner-78sq8m4q.js → dependencyScanner-ge10gb52.js} +2 -2
  19. package/{devTui-h77zrjv5.js → devTui-rf374y2w.js} +1 -1
  20. package/{fileSys-zpvt5gtf.js → fileSys-q22646yc.js} +1 -1
  21. package/{guideline.command-mffxknbr.js → guideline.command-zwypaqsh.js} +9 -5
  22. package/guidelines/agentRule/agentRule.instruction.md +25 -9
  23. package/guidelines/akanApi/akanApi.instruction.md +6 -4
  24. package/guidelines/conventions/core.md +23 -5
  25. package/guidelines/conventions/rules/app.md +4 -1
  26. package/guidelines/conventions/rules/page.md +5 -4
  27. package/guidelines/conventions/rules/ts.md +3 -3
  28. package/guidelines/errorCodes/errorCodes.instruction.md +165 -0
  29. package/guidelines/fieldRule/fieldRule.instruction.md +2 -1
  30. package/guidelines/mcpRule/mcpRule.instruction.md +225 -5
  31. package/guidelines/pageRule/pageRule.instruction.md +10 -1
  32. package/guidelines/queryRule/queryRule.instruction.md +3 -1
  33. package/guidelines/runtimeRule/runtimeRule.instruction.md +14 -8
  34. package/guidelines/transportRule/transportRule.instruction.md +31 -1
  35. package/incrementalBuilder.proc.js +577 -411
  36. package/{index-w15mg3km.js → index-0dm25wvf.js} +1 -1
  37. package/{index-0gg15zwa.js → index-0s7w2085.js} +6 -6
  38. package/{index-hj6w4ka1.js → index-1p81ecbz.js} +1 -1
  39. package/{index-swwjakt0.js → index-275a4r3n.js} +11 -11
  40. package/{index-j6gc8n14.js → index-2jmvfa62.js} +11 -9
  41. package/{index-qd7xn2bk.js → index-2ny1e95c.js} +2 -2
  42. package/{index-exn38bzx.js → index-2yn3r67f.js} +116 -54
  43. package/{index-34792nh7.js → index-3txdtztz.js} +1 -1
  44. package/{index-28x1aszt.js → index-41a03gkj.js} +149 -53
  45. package/{index-2mf1aen9.js → index-4ss4gkv3.js} +2 -2
  46. package/{index-an76bdrv.js → index-612fdtbk.js} +1 -1
  47. package/{index-5radqwn2.js → index-67sd09ag.js} +12 -12
  48. package/{index-0hbtve0a.js → index-6dzjer7p.js} +32 -28
  49. package/{index-3ghdb7p5.js → index-71y6176j.js} +2777 -3676
  50. package/{index-xyn02k0w.js → index-78y75t0a.js} +662 -433
  51. package/index-7wf8snar.js +80 -0
  52. package/{index-skmtj8rm.js → index-8jtqfye2.js} +27 -10
  53. package/{index-2mrn1mrg.js → index-9f3reh2y.js} +1 -1
  54. package/{index-nmvhjn8c.js → index-9wh04mqy.js} +93 -82
  55. package/{index-xvk2a75m.js → index-a860mx0m.js} +3 -3
  56. package/{index-5zwr4n6k.js → index-baccvws5.js} +65 -8
  57. package/{index-yf9wc28h.js → index-bejy9zyc.js} +1 -1
  58. package/{index-bns3wcpc.js → index-by2tvsq6.js} +1 -1
  59. package/{index-r0a604h4.js → index-c669pbyb.js} +5 -4
  60. package/{index-x40bdsca.js → index-dadwp2aw.js} +33 -98
  61. package/{index-vm0dn0mt.js → index-dmcpetwe.js} +200 -138
  62. package/{index-43f4h4cm.js → index-ebn9kgea.js} +6 -6
  63. package/{index-hqv34wzq.js → index-gt8phqpt.js} +10 -10
  64. package/{index-yckz5t8b.js → index-h901f24n.js} +516 -434
  65. package/{index-j3v29pq7.js → index-j0wr4e32.js} +219 -175
  66. package/{index-gcx48get.js → index-j592zfqc.js} +2 -2
  67. package/{index-grxs6fts.js → index-j6jjmn2r.js} +57 -31
  68. package/{index-w8yasvpc.js → index-jek2re5k.js} +2136 -2175
  69. package/{index-ny2k80mv.js → index-jf4vk1s0.js} +9 -2
  70. package/{index-gxav1bjz.js → index-k6vwww45.js} +9 -9
  71. package/{index-99qvtff2.js → index-kfvjzk8r.js} +5 -5
  72. package/{index-j6eeh5d7.js → index-knpm8sdm.js} +5 -5
  73. package/{index-2r9ff9qm.js → index-nc3br31y.js} +2 -2
  74. package/{index-35j83zkd.js → index-p5zh7pmc.js} +2 -2
  75. package/{index-cmg5ngqa.js → index-p7beqww9.js} +2 -2
  76. package/{index-b4qq3rq0.js → index-rwgqba9p.js} +1 -1
  77. package/{index-rfzp4pqs.js → index-s885g0jj.js} +3 -3
  78. package/{index-9p260r4e.js → index-trffs83s.js} +538 -250
  79. package/{index-k92x3vne.js → index-v7ajmsh3.js} +1 -1
  80. package/index-w1zexzpx.js +127 -0
  81. package/{index-h7hehkw6.js → index-xczjdng6.js} +3 -1
  82. package/{index-39jz41jb.js → index-xs9a3ddt.js} +3 -3
  83. package/{index-rp4yf32g.js → index-xwwex8rf.js} +36 -29
  84. package/{index-ra9fvn7s.js → index-ybcb9wc8.js} +74 -38
  85. package/index-z92zm3wd.js +788 -0
  86. package/{index-j9790rhk.js → index-z96ks033.js} +1509 -1121
  87. package/index-zfnz878d.js +30 -0
  88. package/{index-2vgv7fs7.js → index-zmd9xxgd.js} +727 -693
  89. package/{index-ygdbn9jn.js → index-zyb0ebm4.js} +1 -1
  90. package/index.js +28 -24
  91. package/libExecutor-jc6f8hm6.js +10 -0
  92. package/{library.command-bmd7zc5m.js → library.command-nxvesvhb.js} +12 -5
  93. package/{localRegistry.command-y6en1599.js → localRegistry.command-xz62e4ng.js} +29 -24
  94. package/{module.command-7exfffqw.js → module.command-aaws9byg.js} +11 -7
  95. package/{package.command-adskw2rj.js → package.command-j7hv26p0.js} +14 -10
  96. package/package.json +8 -8
  97. package/{page.command-dw01272p.js → page.command-7yffs7n9.js} +8 -4
  98. package/{pipeline.command-0b1r3y5r.js → pipeline.command-7yk0zcng.js} +15 -9
  99. package/pkgExecutor-arxmvx4t.js +10 -0
  100. package/{primitive.command-byw6vc04.js → primitive.command-7a1pt715.js} +12 -8
  101. package/{projectTypecheck-kkrpq60a.js → projectTypecheck-f4qhbecd.js} +1 -1
  102. package/{prompter-qrwx1p17.js → prompter-qyggfhqd.js} +2 -2
  103. package/{quality.command-6rqnhzct.js → quality.command-c6mvrjh1.js} +25 -16
  104. package/{recipeScanner-4b69ybe0.js → recipeScanner-rrx69awy.js} +1 -1
  105. package/{repair.command-rw5zymak.js → repair.command-093adzt9.js} +12 -8
  106. package/{routeSourceValidator-4h947v7c.js → routeSourceValidator-8n6j1vn7.js} +4 -2
  107. package/{scalar.command-2dyp9nh9.js → scalar.command-2ex84spb.js} +10 -6
  108. package/skills/akan-debug/SKILL.md +8 -5
  109. package/skills/akan-err/SKILL.md +7 -0
  110. package/skills/akan-mcp/SKILL.md +19 -1
  111. package/skills/akan-scaffold/SKILL.md +1 -1
  112. package/skills/akan-validate/SKILL.md +3 -3
  113. package/{subspace.command-111ynwv1.js → subspace.command-4n4n4jpv.js} +32 -24
  114. package/templates/app/page/_layout.tsx +13 -0
  115. package/templates/app/page/styles.css.template +40 -0
  116. package/templates/appSample/page/_index.tsx +9 -9
  117. package/templates/appSample/page/_layout.tsx +1 -0
  118. package/templates/appSample/page/styles.css.template +40 -5
  119. package/templates/appSample/ui/Recipe/jellyButton.ts +1 -1
  120. package/templates/biomeForm.ts +1 -1
  121. package/templates/env/_env.server.type.ts +1 -1
  122. package/templates/facetIndex/index.ts +2 -37
  123. package/templates/lib/sig.ts +0 -4
  124. package/templates/lib/useClient.ts +1 -1
  125. package/templates/workspaceRoot/.devcontainer/devcontainer.json.template +1 -1
  126. package/templates/workspaceRoot/AGENTS.md.template +2 -1
  127. package/templates/workspaceRoot/README.ts +4 -2
  128. package/{tunnel.command-2gcpfbdj.js → tunnel.command-f7ep1qfa.js} +17 -13
  129. package/{typeChecker-s640r6c0.js → typeChecker-7jt6abrs.js} +1 -1
  130. package/typecheck.proc.js +3 -2
  131. package/{verify.command-djgs86ma.js → verify.command-zrkxnvct.js} +21 -17
  132. package/{workflow.command-n0k2mxr5.js → workflow.command-ks16jegk.js} +21 -14
  133. package/{workspace.command-fh1qwxfx.js → workspace.command-ahhfpaag.js} +60 -54
  134. package/CodeAgent-x2p3a3e0.js +0 -11
  135. package/TunnelShare-c4xsfzg5.js +0 -15
  136. package/agent.command-9et2e27p.js +0 -52
  137. package/cloud.script-xze4zh7n.js +0 -31
  138. package/context.command-rk1dwrg4.js +0 -57
  139. package/context.runner-83ky5m1b.js +0 -30
  140. /package/templates/{appSample → app}/public/fonts/Pretendard-Bold.woff2 +0 -0
  141. /package/templates/{appSample → app}/public/fonts/Pretendard-Medium.woff2 +0 -0
  142. /package/templates/{appSample → app}/public/fonts/Pretendard-Regular.woff2 +0 -0
  143. /package/templates/{appSample → app}/public/fonts/Pretendard-SemiBold.woff2 +0 -0
@@ -0,0 +1,165 @@
1
+ # Akan.js error codes
2
+
3
+ Generated from the akanjs sources of this release: every code a framework error carries, so a caller branches on
4
+ `error.code`, or the `code` of the JSON it was answered with, rather than on the message.
5
+
6
+ - A **forwarded** error answers with its own JSON. Any other `AkanError` answers with its code and status, and in
7
+ production with the status's reason in place of its message, which can name a table, a file or what a provider
8
+ said (`akan start` and `AKAN_ERROR_DETAIL=1` keep the message).
9
+ - **Code on the wire** says whether that JSON carries `code`. A forwarded error whose JSON leaves it out is told
10
+ apart by its `error` key and status.
11
+ - An app's own failure is a dictionary `Err`, which carries its key in `error` instead of one of these codes.
12
+ - In code, `AkanError.is(error, "<code>")` tests any framework error for a code, and `<Class>.is(error)` one class.
13
+
14
+ ## Codes
15
+
16
+ | Code | Status | Error | Forwarded | Code on the wire | Source |
17
+ |---|---|---|---|---|---|
18
+ | `alreadyApplied` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
19
+ | `alreadyInitialized` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
20
+ | `artifactMissing` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
21
+ | `authRequired` | 401 | `McpAuthRequiredError` | no | yes | `server/mcp/McpDispatcher.ts` |
22
+ | `badGateway` | 502 | `ImageOptimizerError` | no | yes | `server/imageOptimizerError.ts` |
23
+ | `badRequest` | 400 | `Exception.BadRequest` | yes | no | `signal/exception.ts` |
24
+ | `badRequest` | 400 | `ImageOptimizerError` | no | yes | `server/imageOptimizerError.ts` |
25
+ | `baseMismatch` | 500 | `SignalDeclarationError` | no | yes | `signal/signalDeclarationError.ts` |
26
+ | `buildFailed` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
27
+ | `builderUnavailable` | 503 | `AkanError` | no | yes | `base/akanError.ts` |
28
+ | `bytesThroughAny` | 500 | `SignalContractError` | no | yes | `signal/signalContractError.ts` |
29
+ | `circularDependency` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
30
+ | `clientComponentOnServer` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
31
+ | `compressorNotInitialized` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
32
+ | `conflict` | 409 | `Exception.Conflict` | yes | no | `signal/exception.ts` |
33
+ | `consoleDisabled` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
34
+ | `databaseLocked` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
35
+ | `desktopAppRequired` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
36
+ | `documentNotFound` | 404 | `NoDocumentError` | yes | no | `document/noDocumentError.ts` |
37
+ | `duplicateRegistration` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
38
+ | `failed` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
39
+ | `fileGrantRefused` | 403 | `AkanError` | no | yes | `base/akanError.ts` |
40
+ | `fileGrantUnavailable` | 503 | `AkanError` | no | yes | `base/akanError.ts` |
41
+ | `forbidden` | 403 | `Exception.Forbidden` | yes | no | `signal/exception.ts` |
42
+ | `gatewayTimeout` | 504 | `Exception` | yes | no | `signal/exception.ts` |
43
+ | `handlerAlreadySet` | 500 | `SignalDeclarationError` | no | yes | `signal/signalDeclarationError.ts` |
44
+ | `inlineFailed` | 502 | `PromptError` | no | yes | `signal/mcp/promptError.ts` |
45
+ | `insightTimeout` | 504 | `InsightQueryError` | yes | yes | `service/insightQueryError.ts` |
46
+ | `insightUnavailable` | 500 | `InsightQueryError` | no | yes | `service/insightQueryError.ts` |
47
+ | `internalError` | 500 | `Exception.Error` | yes | no | `signal/exception.ts` |
48
+ | `invalidArgType` | 500 | `SignalDeclarationError` | no | yes | `signal/signalDeclarationError.ts` |
49
+ | `invalidArgument` | 400 | `McpArgumentError` | no | yes | `server/mcp/McpExecutionContext.ts` |
50
+ | `invalidArtifact` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
51
+ | `invalidCascade` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
52
+ | `invalidConfig` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
53
+ | `invalidDocument` | 500 | `DocumentStoreError` | no | yes | `service/documentStoreError.ts` |
54
+ | `invalidErrors` | 500 | `SignalDeclarationError` | no | yes | `signal/signalDeclarationError.ts` |
55
+ | `invalidFileGrant` | 400 | `AkanError` | no | yes | `base/akanError.ts` |
56
+ | `invalidFilter` | 400 | `FilterQueryError` | no | yes | `document/filterMeta.ts` |
57
+ | `invalidIdentity` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
58
+ | `invalidInject` | 500 | `InjectError` | no | yes | `service/injectError.ts` |
59
+ | `invalidInput` | 400 | `InvalidInputError` | no | yes | `constant/invalidInputError.ts` |
60
+ | `invalidInsightQuery` | 400 | `InsightQueryError` | yes | yes | `service/insightQueryError.ts` |
61
+ | `invalidKey` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
62
+ | `invalidMessage` | 400 | `AkanError` | no | yes | `base/akanError.ts` |
63
+ | `invalidParam` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
64
+ | `invalidPrompt` | 500 | `PromptError` | no | yes | `signal/mcp/promptError.ts` |
65
+ | `invalidQuery` | 500 | `DocumentStoreError` | no | yes | `service/documentStoreError.ts` |
66
+ | `invalidRoute` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
67
+ | `invalidRscResponse` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
68
+ | `invalidSchema` | 500 | `DocumentStoreError` | no | yes | `service/documentStoreError.ts` |
69
+ | `invalidSignal` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
70
+ | `invalidStorageKey` | 400 | `AkanError` | no | yes | `base/akanError.ts` |
71
+ | `ipcRequired` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
72
+ | `jobStalled` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
73
+ | `listFailed` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
74
+ | `liveAlreadySet` | 500 | `SignalDeclarationError` | no | yes | `signal/signalDeclarationError.ts` |
75
+ | `livePaused` | 409 | `AkanError` | no | yes | `base/akanError.ts` |
76
+ | `liveRoomLimit` | 429 | `LiveRoomLimitError` | yes | yes | `service/liveRoomLimitError.ts` |
77
+ | `liveRoomTaken` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
78
+ | `locked` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
79
+ | `logControlUnavailable` | 503 | `LogControlUnavailableError` | no | yes | `server/logging/logTailClient.ts` |
80
+ | `missingFilterQuery` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
81
+ | `missingInput` | 400 | `InvalidInputError` | no | yes | `constant/invalidInputError.ts` |
82
+ | `missingModel` | 500 | `SignalDeclarationError` | no | yes | `signal/signalDeclarationError.ts` |
83
+ | `missingSlice` | 500 | `SignalDeclarationError` | no | yes | `signal/signalDeclarationError.ts` |
84
+ | `noHandler` | 500 | `SignalContractError` | no | yes | `signal/signalContractError.ts` |
85
+ | `notApplied` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
86
+ | `notFound` | 404 | `Exception.NotFound` | yes | no | `signal/exception.ts` |
87
+ | `notFound` | 404 | `ImageOptimizerError` | no | yes | `server/imageOptimizerError.ts` |
88
+ | `notFound` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
89
+ | `notInitialized` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
90
+ | `notInitialized` | 500 | `InjectError` | no | yes | `service/injectError.ts` |
91
+ | `notRegistered` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
92
+ | `notRegistered` | 500 | `InjectError` | no | yes | `service/injectError.ts` |
93
+ | `notRegistered` | 500 | `SignalContractError` | no | yes | `signal/signalContractError.ts` |
94
+ | `nullableLastArg` | 500 | `SignalDeclarationError` | no | yes | `signal/signalDeclarationError.ts` |
95
+ | `payloadTooLarge` | 413 | `AkanError` | no | yes | `base/akanError.ts` |
96
+ | `payloadTooLarge` | 413 | `ImageOptimizerError` | no | yes | `server/imageOptimizerError.ts` |
97
+ | `planChanged` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
98
+ | `redisUriMissing` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
99
+ | `remoteOAuth` | 502 | `RemoteError` | no | yes | `server/remote/remoteError.ts` |
100
+ | `remoteProtocol` | 502 | `RemoteError` | no | yes | `server/remote/remoteError.ts` |
101
+ | `remoteTooLarge` | 502 | `RemoteError` | no | yes | `server/remote/remoteError.ts` |
102
+ | `remoteUnauthorized` | 401 | `RemoteError` | no | yes | `server/remote/remoteError.ts` |
103
+ | `remoteUnavailable` | 502 | `RemoteError` | no | yes | `server/remote/remoteError.ts` |
104
+ | `remoteUrlRejected` | 502 | `RemoteError` | no | yes | `server/remote/remoteError.ts` |
105
+ | `renderAborted` | 499 | `AkanError` | no | yes | `base/akanError.ts` |
106
+ | `routeConflict` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
107
+ | `routeNotFound` | 404 | `AkanError` | no | yes | `base/akanError.ts` |
108
+ | `routeNotFound` | 404 | `RscRouteNotFound` | no | yes | `server/rscClient.tsx` |
109
+ | `routerNotReady` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
110
+ | `rpcDisposed` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
111
+ | `rscFetchFailed` | 502 | `AkanError` | no | yes | `base/akanError.ts` |
112
+ | `rscQueueOverflow` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
113
+ | `rscRedirectStarted` | 303 | `RscRedirectNavigationStarted` | no | yes | `server/rscClient.tsx` |
114
+ | `rscWorkerFailed` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
115
+ | `rscWorkerStopped` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
116
+ | `searchMisconfigured` | 500 | `DocumentStoreError` | no | yes | `service/documentStoreError.ts` |
117
+ | `searchUnavailable` | 500 | `DocumentStoreError` | no | yes | `service/documentStoreError.ts` |
118
+ | `secretRefused` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
119
+ | `secretStoreUnavailable` | 503 | `AkanError` | no | yes | `base/akanError.ts` |
120
+ | `serviceUnavailable` | 503 | `ImageOptimizerError` | no | yes | `server/imageOptimizerError.ts` |
121
+ | `shutdownTimeout` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
122
+ | `stageFailed` | 500 | `StageFailedError` | no | yes | `server/di/stageFailedError.ts` |
123
+ | `storageNotShared` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
124
+ | `tableMissing` | 500 | `DocumentStoreError` | no | yes | `service/documentStoreError.ts` |
125
+ | `tooManyRequests` | 429 | `Exception` | yes | no | `signal/exception.ts` |
126
+ | `transferUnsupported` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
127
+ | `unauthorized` | 401 | `Exception.Unauthorized` | yes | no | `signal/exception.ts` |
128
+ | `undefinedReturn` | 500 | `SignalContractError` | no | yes | `signal/signalContractError.ts` |
129
+ | `unencodableValue` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
130
+ | `unguardedEndpoint` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
131
+ | `unmaskedResource` | 500 | `PromptError` | no | yes | `signal/mcp/promptError.ts` |
132
+ | `unroutableLiveQuery` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
133
+ | `unstorableValue` | 400 | `DocumentStoreError` | no | yes | `service/documentStoreError.ts` |
134
+ | `unsupportedMediaType` | 415 | `Exception.UnsupportedMediaType` | yes | no | `signal/exception.ts` |
135
+ | `usage` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
136
+ | `verifyFailed` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
137
+ | `wrongTransport` | 500 | `SignalContractError` | no | yes | `signal/signalContractError.ts` |
138
+ | set when thrown | set when thrown | `Err` | yes | yes | `common/err.ts` |
139
+ | set when thrown | set when thrown | `Err.BadRequest` | yes | yes | `common/err.ts` |
140
+ | set when thrown | set when thrown | `Err.Conflict` | yes | yes | `common/err.ts` |
141
+ | set when thrown | set when thrown | `Err.Forbidden` | yes | yes | `common/err.ts` |
142
+ | set when thrown | set when thrown | `Err.NotFound` | yes | yes | `common/err.ts` |
143
+ | set when thrown | set when thrown | `Err.Unauthorized` | yes | yes | `common/err.ts` |
144
+
145
+ ## Codes by status
146
+
147
+ An error coded by its status, such as an `Exception`, takes its code from `AkanError.codeOfStatus`:
148
+
149
+ | Status | Code | Reason |
150
+ |---|---|---|
151
+ | 400 | `badRequest` | Bad Request |
152
+ | 401 | `unauthorized` | Unauthorized |
153
+ | 403 | `forbidden` | Forbidden |
154
+ | 404 | `notFound` | Not Found |
155
+ | 409 | `conflict` | Conflict |
156
+ | 413 | `payloadTooLarge` | Payload Too Large |
157
+ | 415 | `unsupportedMediaType` | Unsupported Media Type |
158
+ | 429 | `tooManyRequests` | Too Many Requests |
159
+ | 500 | `internalError` | Internal Server Error |
160
+ | 502 | `badGateway` | Bad Gateway |
161
+ | 503 | `serviceUnavailable` | Service Unavailable |
162
+ | 504 | `gatewayTimeout` | Gateway Timeout |
163
+
164
+ Any other status is coded `http<status>`, with the reason `Internal Server Error` from 500 and `Request Failed`
165
+ below it.
@@ -63,7 +63,8 @@ Use this whenever generating constants or scalar constants. It defines the curre
63
63
  - **Do not declare `Upload` as a model field.** `Upload` is a signal-body-only primitive. Declare an image/file
64
64
  field as a relation to `File`: `image: field(File).optional()` for one, `images: field([File])` for many.
65
65
  - The store then auto-generates an `upload<Field>On<Model>(fileList)` action that calls the framework upload
66
- mutation and polls file status until it leaves `"uploading"` (`pkgs/akanjs/store/action.ts`).
66
+ mutation and polls file status until it leaves `"uploading"` (`uploadSetterOf` in
67
+ `pkgs/akanjs/store/formFieldSetters.ts`).
67
68
  - **An upload is scoped to the form that started it.** `Field.Img` / `Imgs` / `File` / `Files` handed the generated
68
69
  `set<Field>On<Model>` upload through `upload<Field>On<Model>` (any other `onChange` keeps the plain slice upload).
69
70
  While the request runs, `<model>FormUploading` holds a ticket under the field's name (`{}` when idle);
@@ -46,6 +46,12 @@ export class FileSlice extends slice(srv.file, {
46
46
  - **A view keeps reaching it.** To a host that renders MCP Apps views, an endpoint refused for `mcp: false` alone
47
47
  is published with `visibility: ["app"]`: an app's view may call it, the model is never shown it (below). Every
48
48
  other refusal still holds there.
49
+ - **`mcp: "agent"` keeps it off `/mcp` and on the in-process agent.** It goes wherever `mcp: false` goes, a slice
50
+ map key included. `/mcp` neither lists nor runs it and `listingCost` leaves it out, while `AgentToolsRole` and
51
+ `agentService.loop` list it under the same guards and exclusions. Use it when the listing's size, not the step,
52
+ keeps an entry off. A lib's slice and the app's keep the narrowest: `false`, then `"agent"`, then listed. Code
53
+ that reads `signalOption.mcp` to tell whether an entry is listed tests `(mcp ?? true) === true`, never
54
+ `mcp !== false`.
49
55
  - **`mcp: true` is the default and is a no-op**; write it only to say out loud that an entry is deliberately on
50
56
  the shelf. It does not override a shape refusal (an `Any` return stays refused) and it cannot publish something
51
57
  the guard rules keep out.
@@ -205,8 +211,11 @@ export default page()
205
211
  alike: the caller reads `You are not permitted to perform this action.`, because either sentence names your
206
212
  authorization structure to the one caller barred from it. A domain `Err` at any other status resolves through
207
213
  the dictionary and keeps its own words, placeholders filled.
208
- - The `readOnly` / `destructive` / `idempotent` hints a client renders are derived from the endpoint type and key
209
- and are not configurable. Clients are told to distrust hints; they are never a gate.
214
+ - The `readOnly` / `destructive` / `idempotent` hints a client renders are derived from the endpoint type and key.
215
+ A mutation named `remove`, `delete`, `purge`, `destroy`, `erase`, `wipe`, `drop`, `cancel`, `bulkRemove` or
216
+ `bulkDelete` is destructive; `destructive: true` or `false` on the endpoint overrides that, for an `archiveOrder`
217
+ no verb gives away. Clients are told to distrust hints; they are never a gate. `agentService.loop` does read this
218
+ one: it refuses a destructive tool unless `approve` allows it.
210
219
  - **`AKAN_MCP_READONLY=true` is the read-only-deployment valve, not the exposure switch.** It drops every mutation
211
220
  whatever it declared, and reports each one in the boot log like any other refusal. It also drops each `.prompt()`
212
221
  page's text tool, whose run renders the whole page; the prompts, the `.app()` tools and their views stay.
@@ -255,10 +264,12 @@ export default page()
255
264
  the tool's `outputSchema` even on a failure — and a JSON-RPC error holds `data.code`, which tells apart what
256
265
  `-32602` files together: `unknownTool`, `invalidArgument`, `unknownPrompt`, `unknownResource` and a screen's
257
266
  refusal, beside `tooManyRequests` and `internalError`. The code is the one an HTTP caller gets: a domain `Err`'s
258
- dictionary key (what `Err.is` matches), else the `AkanError`'s own code; a 401 or a 403 by its status alone
267
+ dictionary key (what `Err.is` matches), else the `AkanError`'s own code; a guard's 401 or 403 by its status alone
259
268
  (`unauthorized`, `forbidden`), since a guard's own code names its rule as its message does; a crash, or a 5xx whose
260
- code this server did not name, by its status (`internalError`). A code is a bounded key or camelCase token, never
261
- prose. No host hands `_meta` to the model, so what the model must act on belongs in the dictionary sentence.
269
+ answer names no bounded code, by its status (`internalError`). A 5xx's text is redacted but its code token is not,
270
+ and it comes from the error's own JSON when that carries one, which can be a third-party library's. A code is a
271
+ bounded key or camelCase token, never prose. No host hands `_meta` to the model, so what the model must act on
272
+ belongs in the dictionary sentence.
262
273
  - **Three revisions are spoken**: the modern `2026-07-28` and the legacy `2025-11-25` / `2025-06-18`, which are
263
274
  wire-identical over the POST-only surface this implements — a client whose proposal is not listed is told to
264
275
  disconnect. An unknown proposal is answered at whichever end of that list it is closer to, and an unimplemented
@@ -488,6 +499,19 @@ export default page()
488
499
  - `option.setMcp({ apps: false })` / `AKAN_MCP_APPS=false` publishes no page tools: no app is published and every
489
500
  prompt stays a prompt only. `web: { csr: false }` publishes the app tools with no view, and an API-only build
490
501
  (`web: false`) has no pages to publish.
502
+ - **`{ static: true }` sends the app as HTML to a host that runs no view.** `.app(name, description, load,
503
+ { static: true })` marks the tool `_meta["akanjs/static"]: true` wherever the server renders pages, view or not. A
504
+ `tools/call` whose `params._meta["akanjs/render"]` is `"html"` then gets, after the usual blocks, an embedded
505
+ `text/html` resource `ui://<app>/static/<name>`: one document drawn under the caller's credential after the route
506
+ guards, with the load under the same query-only rule — the element inside the root layout's `McpAppRoot` (no
507
+ `_overrides.tsx`), the layout's theme as `data-theme`, `<base href="<web origin>/" target="_blank">`, the stylesheet
508
+ as an absolute link, every Suspense boundary resolved in place, and no `<script>`: no view, no Flight payload,
509
+ nothing runs. Mark an app static only when its server render is the whole picture — nothing hydrates, so a client
510
+ component shows its first state and a button does nothing.
511
+ - **A static app sends no HTML, and the call answers as if none was asked** (with a server warning), when the guards
512
+ refuse, the drawing fails or passes 1 MB, the body is empty or a fallback stands in for content, or a component needs
513
+ a browser: `lazy(…, { ssr: false })` says so itself, and a component whose look only a browser finishes (a canvas, a
514
+ chart drawn in an effect, data read after mount) calls `needsBrowser()` from `akanjs/webkit` while it renders.
491
515
 
492
516
  ## Progress Reporting
493
517
  **`McpProgress.report(n, { total, message })`** reports progress from anywhere inside a call, a service or adapter
@@ -495,6 +519,202 @@ frames down included, and is a no-op when nobody is streaming — so the same co
495
519
  websocket, and in tests. `McpProgress.streaming` says whether anyone is reading, for a report whose message
496
520
  costs something to assemble.
497
521
 
522
+ ## Calling The Catalogue In-Process — `AgentToolsRole`
523
+
524
+ A server-side agent loop or a queue job reaches the same catalogue with no token and no loopback request:
525
+ `plug(AgentToolsRole)` in a service, then `listAs(account, { allow })` for the tools a model is offered and
526
+ `callAs(account, { id, name, args })` to run one. It adds every `mcp: "agent"` entry, and everything above still
527
+ holds — `mcp: false`, the exclusions, `readOnly`, `Person`, the account guards, masking and the refusal text — and
528
+ the call's `origin` is `"mcp"`, so `isAgentCall` and `.with(AgentCall)` treat it as an agent's. `allow` only
529
+ narrows. It is built from the DI registry, so a batch server, which mounts no `/mcp`, has it too; the per-caller
530
+ `/mcp` budget does not apply, an endpoint's own `rateLimit` does. A tool's failure never throws: it comes back as
531
+ the result's `error` and `code`. An adaptor may plug the role too. Neither method works before the server has built
532
+ its endpoints, so a call from an `onInit` throws `InjectError` `notInitialized`; call from a request, a job or a
533
+ schedule. A page's `page().app()` tools are left out: `/mcp` `tools/list` shows them, `listAs` does not, and `callAs` answers `Unknown tool`.
534
+
535
+ - **The account is trusted as given.** It is put on the call after the middleware chain, so pass one the server
536
+ resolved, never client input, and resolve a stored one again before reusing it: a revoked session is not noticed.
537
+ Its `machine` field is removed, since only a verified machine token may set one.
538
+ - **`headers` are forwarded without `authorization`, `cookie` and `origin`**; `ip` is what `getClientIp()` and an
539
+ ip-scoped `rateLimit` read, unknown by default.
540
+
541
+ ## A Server Agent Loop — `agentService.loop`
542
+
543
+ `this.agentService.loop(request)` runs a model over that catalogue until it answers, with no browser — a queued
544
+ task, a scheduled run, a reply to a mention. It is an async iterable of `text`, `toolCall`, `toolResult`, `usage`,
545
+ `compacted` and `awaiting` events that ends in exactly one `done { stop }` or `error`, and it waits for the consumer
546
+ at every event.
547
+
548
+ - **Who it acts as.** `account` is a snapshot the server resolved; `principal` is a stored id that
549
+ `option.setAgentAccountResolver((principal) => account | null)` resolves at the start and before every round, so
550
+ a revoked one ends the run as `"unauthorized"`, as does a missing or falsy `account`: there is no anonymous run.
551
+ Neither is ever client input. The model is offered `allow` ∩ what
552
+ the account sees on `/mcp`, and a call to a name that round did not list is answered as an unknown tool, neither
553
+ asked about nor run. A request with no `allow` array is an `error`.
554
+ - **Toolkits.** `toolkits: { calendar: { description, tools } }` groups names of `allow` so a round need not carry
555
+ every tool. A tool in no toolkit is listed every round, beside one more, `openToolkit({ name })`, whose description
556
+ lists the toolkits. An opened toolkit's tools are listed from the next round on; `openToolkit` never reaches
557
+ `approve` and counts as no tool call. A resume reopens what stored calls and a summary's `toolkits` opened.
558
+ - **The open screen's tools.** `clientTools` takes `new AgentClientTools().list()` from a page the member has open
559
+ (`akanjs/ui`), sent over your own transport. It is client input: a name an endpoint holds is dropped, every one
560
+ counts as a write whatever `readOnly` it was sent with, and past 128 tools, 200,000 characters of definitions or
561
+ 64 levels of nesting the run ends with `agent.error.clientToolsRefused` (413, `data.limit` `"tools"`, `"chars"` or
562
+ `"depth"`). Which of them may run after a read is the app's to say, in `approve`, by name. The run never runs one:
563
+ `approve` is asked, then the run ends `awaiting` with `client: true`. Have the page `run(call)` and resume with
564
+ what it returned as `answer` — or `answer: { id, error }` when no page answers. The page keeps its own rule beside
565
+ the run's: `run(call)` asks the member through `host.approve` when a call that changes something follows a `taint:
566
+ "source"` read. The run's rule below is the wider one, counting every result, the page's included, so with no
567
+ `approve` a client call is refused once the run has read anything; an `approve` that allows a client call leaves
568
+ that question to the page.
569
+ - **Asking the member.** `ask: true` lists `askUser({ question, choices?, multiple? })`, the in-page chat's own tool.
570
+ A call ends the run `awaiting` with `question: true`; put the question to the member and resume with
571
+ `answer: { id, result }` — or `{ id, error }` when they dismiss it. It never reaches `approve`, counts as no tool
572
+ call, and `untrusted` never sees the answer. A `clientTools` entry by that name is dropped.
573
+ - **Answering a parked call.** `answer` is the only way in for what a client sends, and `messages` holds only your
574
+ own user messages and what `onMessage` handed over: never append a client's result to them. Never take `messages`
575
+ from a request either: store what `onMessage` hands out, and pass from the client only `answer`, as a tool message
576
+ a client wrote reads exactly like one the run stored. Pass `answer` only after an `awaiting` event with `client`
577
+ or `question` named that call. `approve` is not asked about an answered call, as nothing runs on the server, so an
578
+ answer given for a call `approve` deferred, or for one a run died before parking on, is stored as it stands. A run
579
+ parks on one call, the first of its last batch that nothing answered, so `answer` is accepted for that call alone
580
+ and only when it is a client tool's or `askUser`'s. The run names the result after the call, whatever name was
581
+ sent, hands it to `onMessage`, emits it as a `toolResult` and runs the calls the batch has left. Every part of it
582
+ is bounded: `result`, `error` and `changes` as one value are clipped at 20,000 characters like a tool's result,
583
+ `code` is kept only when it is a failure code, and of its `attachments` the first four carrying `data` or `text`
584
+ are kept, never a `url`. An endpoint tool's call is answered only by running it: an `answer` naming one, a call
585
+ the run has not reached, or a call already answered ends the run with `agent.error.answerRefused` before anything
586
+ runs, and a resume without it carries on. Only `askUser`'s answer is the member's own word; a client tool's always
587
+ taints the run, by the rule below. A call parked with `connect` takes one answer only, the user's refusal as
588
+ `{ id, error }`; see "Calling Another Server".
589
+ - **Other servers.** `remotes` takes other MCP servers, each a toolkit named after it: none is listed or contacted
590
+ until the model opens it, and its tools then read `<name>.<tool>`. See "Calling Another Server" below.
591
+ - **Writes after a read.** What a tool returns may be text someone else wrote, so the run is tainted from the first
592
+ result of a call that ran — an endpoint tool's or a client tool's, an error included — and every later call
593
+ reaches `approve(call, { tainted, tool, client })` with `tainted` set, and `client: true` when the call is to a
594
+ page's tool. `askUser`'s answer, `openToolkit`'s and a call the run refused without running taint nothing. A
595
+ remote is the exception on each count: opening one taints the run, and so does any call into one, refused or not,
596
+ whatever `untrusted` returns and with none given. A batch is judged before it runs, since the model wrote it
597
+ before reading its results. Without `approve`, a `needsConfirm`
598
+ tool — on this catalogue, a mutation with the `destructive` hint above — is refused, and so is every write once
599
+ tainted: such a run writes only in the batch written before any result, and a later write is answered with the
600
+ code `writeAfterRead` and a sentence naming the two ways on. Pass `approve` to decide those calls, or pass
601
+ `untrusted(result)` to say which endpoint results carry another party's text: `(result) => !own.has(result.name)`
602
+ trusts the endpoints you name, and `() => false` trusts every endpoint result, which is right only when nothing
603
+ they return was written by anyone but the app and the member. No endpoint option says whose text a tool returns —
604
+ `readOnly` says only that it changes nothing — so the predicate is where that is declared. It is never asked about
605
+ a client tool's answer, which taints the run whatever it is named: a page may lend a tool under the name of an
606
+ endpoint this run does not list, and a predicate reading names would trust it. Only `approve` lets a write follow
607
+ a page's answer. `"defer"` holds the whole batch, emits `awaiting` and ends the run as `"awaiting"`.
608
+ - **Resuming.** Store each message `onMessage` hands over — it is awaited, and a retried run may hand one over twice
609
+ — and call `loop` again with them. A stored result is read as the answer to the call its id names, under that
610
+ call's name. It is judged as an endpoint's only when that call names an endpoint this run lists: any other, a
611
+ page's tool, a remote's, the open of a remote or a tool this run no longer has, taints the run without asking
612
+ `untrusted`, whatever mark it was stored with. The run's own answer to a tool name the model made up,
613
+ `Unknown tool: <name>.` with nothing beside it, taints nothing, and neither does its own sentence for a connection
614
+ the user refused. Keep `ask`, `toolkits` and `remotes` the same for
615
+ the life of a transcript: a stored `askUser` or `openToolkit` answer is the run's own only under the options it
616
+ was given with, and one whose name the page lends taints. Trailing calls nothing answered go to `approve` again before any model call, and the taint is rebuilt from
617
+ the `tainted` marks on stored messages and by re-applying `untrusted`, which sees a result whole during the run
618
+ and clipped on a resume; with no `untrusted` every stored tool result taints, a refusal included, as a resume
619
+ cannot tell one from a result. Store every message whole, marks included. `compacted` says the first `replaced`
620
+ messages are now `summary`; its `tainted` marker stands in for the results it replaced, and a summary with no
621
+ marker counts as tainted. A batch's results reach `onMessage` one tool message a call, as each call finishes, so a
622
+ resume runs only the calls that had not finished, even after a crash mid-batch. It cannot tell a call that was
623
+ running when the run died from one that never started: both go to `approve` again and run again, so a write that
624
+ must not land twice needs an idempotent endpoint or an `approve` that defers it. A stored result of that batch
625
+ which `untrusted` marks taints them too: a resume judges on everything stored, where an uninterrupted run judges a
626
+ batch before any of it runs.
627
+ - **Metering.** Each model call, compactions included, is its own turn for the request policy, the quota and the
628
+ usage hook. It gets a fresh `id`, `loop { id, round }`, a copy of the request's `meta` — server-set, so it may key
629
+ billing — empty headers and no ip. The relay's default size caps skip loop rounds, except in a run that lists
630
+ `clientTools` or names `remotes`: its turns carry `loop.client` or `loop.remote`, and one past
631
+ `AgentRelayPolicy.defaultLimits` ends the run with `agent.error.requestRefused`. A refused quota ends the run as
632
+ `"quota"`.
633
+ - **Limits.** `maxRounds` (12), `budget { tokens, toolCalls, wallMs }` (`"budget"`), `signal` (`"aborted"`) and a
634
+ provider cut (`"length"`). A limit that is not a valid number is an `error` before any model call. `wallMs` and
635
+ `signal` also end a run waiting on a tool or on `approve`. `callAs` cannot cancel a call, so the run stops waiting
636
+ and answers it with an error saying it may still finish; a resume does not run it again, and the endpoint runs on
637
+ with its outcome unreported. There is no preamble unless `preamble` gives one; with no `instructions` either, a
638
+ short neutral prompt stands in, as each adaptor's own fallback is about a screen. `compact { at, keep }` summarizes
639
+ the head, and a tool result is capped at 20,000 characters as the browser caps it. Its calls carry no ip, so an
640
+ ip-scoped `rateLimit` counts them under one unknown address.
641
+ - **A refusal for length.** With `compact` set, a round whose call fails as `agent.error.contextOverflow` compacts
642
+ regardless of `at` and asks once more, as one round; a second refusal, or nothing to cut, ends the run with the
643
+ error. An adaptor with its own size cap throws that error with `{ limit, requested }` in its own unit, bytes
644
+ included, and the run lowers `at` to where that request would have fit.
645
+
646
+ ## Calling Another Server — `remotes`
647
+
648
+ The other direction: an agent running here calls another server's `/mcp` as the signed-in user. The other server needs
649
+ no change; any akan app is one already, and so is any MCP server that speaks OAuth 2.1 with dynamic registration.
650
+
651
+ ```ts
652
+ // lib/option.ts — off by default, since it lets a signed-in user make this server call an address they name
653
+ export const option = new AkanOption<ModulesOptions>().transformEnv((env) => ({ ...env, remote: { enabled: true } }));
654
+
655
+ // a service that runs the loop
656
+ const remotes = this.remoteService.sources(account, [
657
+ { name: "shop", url: project.serverUrl, description: "Orders and refunds of the shop this project runs." },
658
+ ]);
659
+ for await (const event of this.agentService.loop({ account, allow, messages, remotes, approve, onMessage })) {
660
+ if (event.type === "awaiting" && event.connect) /* tell the page: this run waits for a connection to event.connect */;
661
+ }
662
+ ```
663
+
664
+ - **A connection is the user's own OAuth grant at the other server.** `libs/shared`'s `remote` service registers this
665
+ app there once, sends the user to that server's consent page, and keeps the tokens sealed on the server. The other
666
+ server judges every call by its own guards, as it judges any agent's, so `Person` endpoints stay closed. Accounts
667
+ are never matched across servers.
668
+ - **Connecting happens in the chat.** Opening a remote the account has no connection to ends the run `awaiting` with
669
+ `connect: "<name>"` and leaves the call unanswered. Render `<Remote.Util.Connect url={…} onConnected={resume} />`:
670
+ it opens the other server's sign-in in a window and calls back once `page/remote/callback` finished the exchange.
671
+ Resume with the stored messages and no `answer`, and the run opens the toolkit itself. When the user declines,
672
+ resume with `answer: { id, error }` for that call. The `error` only says that they refused: the run stores a
673
+ sentence of its own naming the remote, coded `remoteDeclined`, as the open's result and goes on, and none of your
674
+ text reaches the model or `onMessage`. That sentence taints neither this run nor a later resume, while the error
675
+ of an open that failed still does. The stored messages do not say why a run stopped at an open, so a refusal is
676
+ taken for any first unanswered open of a remote, one in a batch `approve` deferred included: all it does is keep
677
+ that open from running, and the rest of the batch is judged as usual. An `answer` carrying a `result` for an open
678
+ is refused with
679
+ `agent.error.answerRefused`, as only the server sees whether a connection exists.
680
+ - **What a remote lists and returns is another party's text.** Opening a remote taints the run, whatever `untrusted`
681
+ says and with none given: its tools' names, descriptions and schemas reach the model with the open, and so does
682
+ the error of an open that failed. A resume reads it off the stored call, mark or no mark: a stored result of a
683
+ `<name>.<tool>` call, or of an `openToolkit` call that names a remote, taints unasked. An open that only asks the
684
+ user to connect taints nothing. A call's arguments leave for that server,
685
+ and `readOnly` is the remote's own word for its tool, so a request with `remotes` and no `approve` is refused
686
+ before any model call, as `base.error.requiredArgument` naming `approve`: pass one with `remotes`. It is told the
687
+ target as `state.remote`, and hears a tool the remote does not call read-only as a `needsConfirm` one. Show the
688
+ user that server's name and the arguments before allowing a write: a record on one server can ask the model to
689
+ write to another.
690
+ - **Names.** A remote's `name` is `[a-z][A-Za-z0-9]{0,15}` and may not be a toolkit's. A tool name too long or with
691
+ characters a provider refuses is listed under a shortened alias and still called by its real name. A run takes
692
+ at most 120 tools from one remote, a description to 1,000 characters and a parameter schema to 8,000, and stops
693
+ listing at 120,000 characters in all; the open's result counts the tools left out as `omitted`. Pass `allow` in
694
+ the remote's entry to choose which tools those are. A run keeps at most four remotes open, as each listing rides
695
+ every later round: the open of a fifth is answered with an error and that server is not contacted. Of a call's
696
+ result the run keeps `result`, `error`, `code`, `changes` and `attachments`, each bounded as the parts of an
697
+ `answer` are, and nothing else the remote sent; the run's rounds meet the relay's size caps (see Metering).
698
+ - **Addresses.** `url` is the server's address or its MCP endpoint; a bare origin means `/mcp`. Every request goes
699
+ through `RemoteFetch`: https only, no private address, no redirect, the checked address pinned. A local run
700
+ (`operationMode: "local"`) reaches loopback over http, so two dev servers can connect; `remote.allowUrl` narrows
701
+ the addresses an app accepts.
702
+ - **A screen in the result.** When the called tool is a `page().app()`, the `toolResult` event carries `view`
703
+ (`{ remote, tool, args, href?, static?, resourceUri? }`) beside the result, without an `href` or `resourceUri`
704
+ longer than 2,048 characters. It never reaches the model or `onMessage`; store it yourself and draw `<Remote.Zone.Screen url tool={view.tool} args={view.args} href={view.href}
705
+ drawn={view.static} />`. For an app the other server declared `{ static: true }` the card asks `remoteScreen` for
706
+ that server's script-less HTML when it scrolls into view and shows it in a frame that runs no script; for any other
707
+ app, draw `<Remote.Zone.View url tool args uri={view.resourceUri} href />`: it frames that server's view (its
708
+ client bundle) with scripts on but no origin, under a policy that lets it load only from that server and connect
709
+ nowhere, and relays the view's own calls to that one server through `McpAppHost` (`akanjs/webkit`). A view cannot
710
+ write into the model's context, and a link it opens must stay on its server. Neither card stores what it drew: the
711
+ HTML and the view's data are fetched again on every draw, since what the user may see there can change. A view
712
+ weighs over a megabyte, so prefer `{ static: true }` on the other server for anything a person only reads.
713
+ - **Not published onward.** The connection endpoints take `Person` and are `mcp: false`, and remote tools exist only
714
+ inside the run: an outside agent connected to this app's `/mcp` never reaches a user's other servers through it.
715
+
716
+ Without `libs/shared`, build each entry from `RemoteSource` (`akanjs/server`) with your own `access { token, renew }`.
717
+
498
718
  ## Rolling MCP Out To An App
499
719
 
500
720
  The goal of exposing a service over MCP is that a person uses it through an agent instead of through the page:
@@ -60,7 +60,12 @@ body shape — this is the full contract behind them. Before changing route beha
60
60
  `.guard()` throws when the module loads. `fn` receives the route's typed arguments and `lang` (a layout's gets no
61
61
  `children`) and may be `async`. It refuses by moving the router — `router.redirect(href)`, `router.notFound()` — or
62
62
  with `getSelf({ unauthorize })`; `signedIn()` from `@libs/shared/webkit` is that last one, called inside an arrow
63
- (`.guard(() => signedIn())`), because `.guard(signedIn)` would hand the route's arguments to `unauthorize`.
63
+ (`.guard(() => signedIn())`), because `.guard(signedIn)` would take the route's arguments as its option.
64
+ - **A guard's second argument `{ path }` is where the visitor was going** — the in-app path with its search, as
65
+ `router.push` takes it (`undefined` while MCP lists the screen): `.guard((_, { path }) => signedIn({ path }))`
66
+ sends a refused visitor to `/signin?redirect=<path>`. Build a redirect target from it, never an admission rule —
67
+ CSR asks a guard again only when the route or an argument it declared moves. Hand it only to `router.push` or
68
+ `router.redirect`: it can be a raw `//host`, which `window.location` would follow off the site.
64
69
  - **On the server every guard of the chain runs before any layout body starts**, root layout first and before the
65
70
  route's arguments are checked, so a redirect is a real 307 even after an awaited query, and a not-found is a 404 —
66
71
  where a `getSelf({ unauthorize })` inside a layout body under a `.loading()` redirects late after I/O, inside the
@@ -119,6 +124,10 @@ body shape — this is the full contract behind them. Before changing route beha
119
124
  `property`, and a canonical / manifest / icon link, and keeps the rest — so a page states only what it changes.
120
125
  - A canonical link and `og:url` each name one URL, so a page carries them only from its own `.head()`, never from a
121
126
  layout's.
127
+ - A level that writes `og:image` or `twitter:image` drops the `og:image:*` / `twitter:image:*` tags it inherits, and a
128
+ `<meta name="theme-color">` a `.head()` writes replaces the root `.viewport({ themeColor })`'s. Only `.head()`
129
+ merges: a `<title>` or `<meta>` written inside a component renders beside the merged head, so a second `<title>`
130
+ can reach the document.
122
131
  - **A not-found or error view titles itself**: the `<title>` and `<meta>` at the top of what a layout's `.notFound()`
123
132
  / `.error()` returns replace the layouts' head, and the page's own head is dropped. Under a `.loading()` the head is
124
133
  already out, so they stay in the view.
@@ -129,7 +129,9 @@ this is the full contract behind them.
129
129
  server has one database, so it covers every model, hooks and query-level writes included; a nested call joins the
130
130
  outer one, with no savepoint. Cache, `memory` and outside calls are not in it — hand them to
131
131
  `this.afterCommit(fn)`, run once the commit lands, never after a rollback, at once outside one; one that throws is
132
- logged, never thrown, and the rest still run. On SQLite it holds the only write turn: keep it short.
132
+ logged, never thrown, and the rest still run. On SQLite it holds the only write turn: another request's write
133
+ waits until it ends, its read does not and sees the last commit. Keep it short, and never await inside it a write
134
+ started outside it.
133
135
  `@Transaction()` is deprecated.
134
136
 
135
137
  ## Text Search In A Filter — `q.search()`
@@ -200,7 +200,8 @@ normalized to `info` with one warning.
200
200
  - **The hub lives with whoever owns the surface**: the gateway when there is one, the replica itself under solo
201
201
  (`AKAN_REPLICA=0,0,1`), the same rule as the rotating log file and `/_akan/app/*`. It keeps a ring
202
202
  (`AKAN_LOG_BUFFER` records / `AKAN_LOG_BUFFER_MB`, default 2000 / 4), suppresses a line repeating more than 20
203
- times a second into one counted line, and serves `<runtimeDir>/akan-control.sock` (`0600`, NDJSON). A child
203
+ times a second into one counted line there, in live tails and in the log file (never a request line; the ndjson
204
+ stdout gets every record), and serves `<runtimeDir>/akan-control.sock` (`0600`, NDJSON). A child
204
205
  forwards records only while a subscriber wants that level (`log.level` IPC), so an unwatched process sends
205
206
  nothing; `AKAN_LOG_STREAM=1` keeps it on. The RSC worker forwards to its replica the same way.
206
207
  - **`akan logs <app>`** is the client: `--level --grep --endpoint --trace --child --role --origin --since`
@@ -216,9 +217,12 @@ normalized to `info` with one warning.
216
217
  solo replica) its only writer** — every other server process turns its console off and forwards from
217
218
  `AKAN_LOG_STDOUT_LEVEL` (default: the console level); a child's or the RSC worker's crash stack is wrapped as a
218
219
  `raw=true` record instead of breaking the stream. Text stays the default; turn it on in the deployment.
219
- - **`AKAN_LOG_STREAM_TOKEN` mounts `/_akan/app/logs`** (SSE, `Last-Event-ID` resume, explicit `gap` events);
220
+ - **`AKAN_LOG_STREAM_TOKEN` mounts `/_akan/app/logs`** (SSE, `Last-Event-ID` resume, explicit `gap` events;
221
+ a client that stops reading holds at most 4 MiB of live records beyond a resume's replay, hears `{type:"dropped",count}` when it reads again, and is cut off
222
+ past 10,000 dropped records);
220
223
  unset, the route does not exist. The same bearer also unlocks the health detail and metrics.
221
- - **`AKAN_LOG_CANONICAL=1|slow`** writes one `ok|error <endpoint> ms= status=` line per call; **`AKAN_LOG_FLIGHT=1`**
224
+ - **`AKAN_LOG_CANONICAL=1|slow`** writes one `ok|error <endpoint> ms= status=` line per call, at `info`, `warn` under
225
+ 500, or `error` with `type` and `stack` for a 5xx (then the only 5xx record); **`AKAN_LOG_FLIGHT=1`**
222
226
  keeps each call's last 64 sub-level records and promotes them (`flight=true`) only when it failed or ran past
223
227
  `AKAN_LOG_FLIGHT_MS`; an `x-akan-debug` header lowers one request to `trace` — under the local dev runtime, or
224
228
  with the `AKAN_LOG_DEBUG_HEADER` secret.
@@ -391,7 +395,8 @@ const config: AppConfig = {
391
395
  was opened for while its frames load web content from anywhere, with an init script that runs in the top document
392
396
  only, `evaluate`, a trusted `sendKey`, `capture`, and `loadFailed` / `gone` (it reloads, or is rebuilt, by itself;
393
397
  the reason is `terminated` on macOS, and `rebuildFailed` when a rebuild failed and the view is closed, to be opened
394
- again) / `consoleMessage` events. Every method on Windows; macOS 14+ lacks `sendKey`, `setMuted` and `capture`.
398
+ again) / `consoleMessage` events. Every method on Windows and Linux, where a visible view also holds the keyboard
399
+ focus and no `consoleMessage` is sent; macOS 14+ lacks `sendKey`, `setMuted` and `capture`.
395
400
 
396
401
  ## A Desktop App's Server — `bin` And `trustedDependencies`
397
402
 
@@ -629,10 +634,11 @@ serving without a key. Everything else is behind the ops channel.
629
634
  get 30 a minute per process; every refusal is the same 401 and spends none of them, and an address refused 10
630
635
  times in a minute gets 429 until it passes. A malformed key, or the machine token's own key
631
636
  (`AKAN_MACHINE_PUBLIC_KEY`), logs an error and leaves the app serving with the channel off.
632
- - **A migrate job runs for the token's `sub`**, which the run records as its actor: apply and rollback refuse a
633
- token without one, and a body naming `actor` is refused. Each option reaches the command as `--name=value`. One
634
- job runs at a time per process (409 meanwhile); the run's own lease keeps two hosts on one database apart. Jobs
635
- live in memory, so after a restart read the outcome from `list`. Polls count toward the 30 a minute.
637
+ - **A migrate job runs for the token's `sub`**, which the run records as its actor: apply, rollback and prune-indexes
638
+ refuse a token without one, and a body naming `actor` is refused. Each option reaches the command as
639
+ `--name=value`. One job runs at a time per process (409 meanwhile); the run's own lease keeps two hosts on one
640
+ database apart. Jobs live in memory, so after a restart read the outcome from `list`. Polls count toward the 30 a
641
+ minute.
636
642
  - **The app holds no storage credential.** It PUTs to the presigned URLs it was handed (`application/octet-stream`,
637
643
  the manifest `application/json`), plain http only to loopback. The manifest landing is the commit marker.
638
644
  - **Snapshots cover the SQLite modes only.** `single` copies the main file and, with `includeSolid`, the Solid file;
@@ -57,7 +57,9 @@ HTTP verb a mutation is mounted under. `conventions` carries the invariants —
57
57
  each room delivers (`seq`); a client drops a repeat, and a hole — a frame dropped under backpressure — calls the
58
58
  room's `onResync`. A resubscribe names its last frame (`since`): a server that saw every publish (a solo process)
59
59
  replays what followed it ahead of the ack, and otherwise answers a gap, which calls `onResync` as before. Binary
60
- rooms are not numbered.
60
+ rooms are not numbered. A server on Redis whose link to the app's other servers drops and returns sends each room a
61
+ `resync` frame once Redis hands it the room's events again, which calls `onResync` too (a live room refetches
62
+ instead), since what other servers published meanwhile never reached it.
61
63
  - **A cleanup registered with `ws.on("disconnect" | "unsubscribe", fn)` is scoped to the call that registered it.**
62
64
  From a `pubsub` subscribe it belongs to that room — `unsubscribe` runs when the client leaves it or a credential
63
65
  change revokes it, `disconnect` when the socket closes while still subscribed — so a room already left runs
@@ -231,6 +233,34 @@ HTTP verb a mutation is mounted under. `conventions` carries the invariants —
231
233
  ``await this.rateLimit.consume(`otp:${phone}`, { calls: 5, windowMs: 3_600_000 })``, which answers
232
234
  `{ ok: true } | { ok: false, retryAfterMs }` and is never switched off — throw the module's own `Err` with the
233
235
  wait when it refuses.
236
+ - **Rooms per socket are capped at 256, live or not** (`option.setLiveRoomLimit({ roomsPerSocket })`, merged in
237
+ mount order with the app last; `AKAN_LIVE_ROOMS_PER_SOCKET=<count>|off` wins over it). A subscribe past the cap is
238
+ refused with 429 `base.error.liveRoomLimit`, `data: { limit, per: "socket" }`; the rooms already held keep their events,
239
+ subscribing a held room again does not count twice, and leaving a room or closing the socket frees its place.
240
+ - **Rooms per caller are capped at 2,000 per server process**, across its sockets (`roomsPerCaller`,
241
+ `AKAN_LIVE_ROOMS_PER_CALLER`). The caller is `accountKey(account)`, else the address (`addressBlockOf`: an IPv4
242
+ address, mapped or not, as itself, an IPv6 one by its /64); one whose address is unknown is bounded per socket
243
+ only. A subscribe past it is refused the same way with `per: "caller"`, and the count drops as its sockets leave
244
+ rooms or close. Sockets per address stay unlimited: this count bounds the rooms whatever their number.
245
+ - **Live rooms per model are capped at 50,000 per server process** (`roomsPerModel` in the same setting,
246
+ `AKAN_LIVE_ROOMS_PER_MODEL`), counting only the rooms every write evaluates: those no equality index files and the
247
+ invalidating ones. An indexed room is reached through its key and never counts. A new counted room past it is
248
+ refused the same way with `per: "model"`, existing rooms keep working, and the refusal is warned at most once a
249
+ minute per model. It is a backstop behind the per-caller cap, which about 25 distinct callers at 2,000 rooms each
250
+ can reach; both count per server process, not across replicas.
251
+ - **A subscribe refused with 429 names its room** (`requestRoomId` on the error frame) and echoes the subscribe
252
+ frame's `token`, so the client ignores a refusal that answers an earlier subscribe of the room. Refused with
253
+ `liveRoomLimit`, the client drops that room, so a reconnect does not send it again, and calls the subscriber's
254
+ `onRefused(error)` fetch policy once. Refused for a budget (`tooManyRequests`), it sends the subscribe again after
255
+ the frame's `data.seconds` (1 to 60) plus up to a second of jitter per attempt, resyncs the room on the retry's
256
+ ack as a reconnect does, and drops the room the same way after five tries without an ack. A live slice whose room is dropped shows the error as a message, marks its list
257
+ stale, and subscribes again only on its next watch, such as the next mount — never in a loop.
258
+ - **Subscribe frames have a budget of their own**, over every pubsub endpoint: 1,000 a minute per websocket, counted
259
+ before the arguments are read, and 10,000 a minute per caller (the same caller as the room cap; one whose address
260
+ is unknown is counted per socket only), shared through the cache. A reconnect resubscribing every held room fits
261
+ either. `option.setRateLimit({ subscribe: { perSocket, perCaller } })` changes them (`{ calls,
262
+ windowMs? }`, or `false` to lift one; `subscribe: false` lifts both), and `AKAN_RATE_LIMIT=off` and a `local`
263
+ environment turn them off with every other budget. A refusal is the same 429 `base.error.tooManyRequests`.
234
264
 
235
265
  ## Calling Another Server
236
266