@akanjs/cli 3.2.0-rc.3 → 3.2.0-rc.31
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.build-stamp +2 -1
- package/CodeAgent-c17abdbf.js +11 -0
- package/{CodeTui-wv9yf7eq.js → CodeTui-jed1nj82.js} +822 -666
- package/README.ko.md +26 -1
- package/README.md +26 -1
- package/TunnelShare-mbfcaqg0.js +18 -0
- package/agent.command-9whnc6vb.js +56 -0
- package/akanCode.js +12 -12
- package/appExecutor-020cyesq.js +11 -0
- package/{application.command-6515t682.js → application.command-4eqvyxkw.js} +77 -36
- package/{applicationBuildRunner-bqbyeg84.js → applicationBuildRunner-frtcrqfd.js} +18 -13
- package/buildBatch.proc.js +26 -11
- package/{cloud.command-32esk0v1.js → cloud.command-hbvmeezn.js} +31 -28
- package/cloud.script-9kmbr3d6.js +35 -0
- package/{code.command-xk7rwq2x.js → code.command-0ayrenk4.js} +14 -9
- package/{context.command-jwenkkf0.js → context.command-php852kf.js} +28 -23
- package/context.runner-nngmn7c0.js +34 -0
- package/{dependencyScanner-78sq8m4q.js → dependencyScanner-ge10gb52.js} +2 -2
- package/{devTui-cd03z4mx.js → devTui-rf374y2w.js} +1 -1
- package/{fileSys-zpvt5gtf.js → fileSys-q22646yc.js} +1 -1
- package/{guideline.command-w6yqpdec.js → guideline.command-w1grfwh7.js} +9 -4
- package/guidelines/agentRule/agentRule.instruction.md +29 -12
- package/guidelines/akanApi/akanApi.instruction.md +6 -4
- package/guidelines/conventions/core.md +23 -5
- package/guidelines/conventions/rules/app.md +4 -1
- package/guidelines/conventions/rules/page.md +5 -0
- package/guidelines/conventions/rules/ts.md +3 -3
- package/guidelines/errorCodes/errorCodes.instruction.md +164 -0
- package/guidelines/fieldRule/fieldRule.instruction.md +2 -1
- package/guidelines/mcpRule/mcpRule.instruction.md +171 -2
- package/guidelines/pageRule/pageRule.instruction.md +15 -1
- package/guidelines/runtimeRule/runtimeRule.instruction.md +12 -6
- package/guidelines/transportRule/transportRule.instruction.md +8 -1
- package/incrementalBuilder.proc.js +574 -410
- package/{index-w15mg3km.js → index-0dm25wvf.js} +1 -1
- package/{index-xrmrvafh.js → index-0gaj78wn.js} +808 -694
- package/{index-j1hjb477.js → index-11d7nh8a.js} +1 -1
- package/{index-hj6w4ka1.js → index-1p81ecbz.js} +1 -1
- package/{index-ygrdw6jw.js → index-1pjwsh2g.js} +65 -8
- package/{index-43acpsc7.js → index-28nk8w3j.js} +12 -12
- package/{index-qd7xn2bk.js → index-2ny1e95c.js} +2 -2
- package/{index-8gm4yag8.js → index-42jhx2ya.js} +6 -6
- package/{index-2rqyrvcy.js → index-4st0hq72.js} +62 -33
- package/{index-bak9f2br.js → index-5d57kx0s.js} +15 -11
- package/{index-bdmgqzb5.js → index-6469101k.js} +58 -29
- package/{index-7kmbqp0b.js → index-6pxmcaq8.js} +1 -1
- package/{index-54s6knqe.js → index-6zb17wcm.js} +12 -10
- package/{index-0ba8nj4d.js → index-7bs463x7.js} +50 -38
- package/{index-y725zb1a.js → index-7v7tvgt7.js} +196 -168
- package/{index-r0a604h4.js → index-99kjwyma.js} +1 -1
- package/{index-2mrn1mrg.js → index-9f3reh2y.js} +1 -1
- package/{index-386canwe.js → index-9rv2zt48.js} +186 -121
- package/{index-20wvskt8.js → index-9wab2ngg.js} +1 -1
- package/{index-2eym1yjb.js → index-9wjrwjgz.js} +288 -209
- package/{index-kcpk2d20.js → index-at6haq2x.js} +1474 -1139
- package/{index-6h775rv3.js → index-ba2xd32s.js} +53 -12
- package/{index-yf9wc28h.js → index-bejy9zyc.js} +1 -1
- package/{index-ngpt3zz3.js → index-bj8s07s7.js} +525 -440
- package/{index-bns3wcpc.js → index-by2tvsq6.js} +1 -1
- package/{index-vbhx60x5.js → index-cb91b6d8.js} +2140 -2165
- package/index-dss3ds74.js +127 -0
- package/{index-e22zedc2.js → index-f16kr6vj.js} +3 -3
- package/{index-ny2k80mv.js → index-ffa52fwf.js} +1 -1
- package/{index-djc5nxpy.js → index-fp5xf6ef.js} +6 -6
- package/{index-qrk06tfp.js → index-g45y5f3e.js} +2 -2
- package/{index-8jpc5fqv.js → index-g7jgd4xs.js} +2 -2
- package/index-j4yvgfhr.js +70 -0
- package/{index-ytpmk3pb.js → index-jgj31xvw.js} +18 -11
- package/{index-j6eeh5d7.js → index-knpm8sdm.js} +5 -5
- package/{index-s34v3y28.js → index-m3t28rt3.js} +11 -11
- package/{index-dpgywgeq.js → index-m5gg0wzv.js} +27 -16
- package/index-na8r4a27.js +30 -0
- package/{index-h0p6n4k1.js → index-nm7nt9vm.js} +3 -3
- package/{index-j4hkbzj6.js → index-p06kfhdf.js} +6 -6
- package/{index-35j83zkd.js → index-p5zh7pmc.js} +2 -2
- package/{index-cmg5ngqa.js → index-p7beqww9.js} +2 -2
- package/{index-zhkcab5a.js → index-prgvqqxe.js} +580 -364
- package/{index-wfmpxke3.js → index-qssq2d41.js} +2775 -3677
- package/{index-sc0g6zbm.js → index-rwgqba9p.js} +24 -11
- package/{index-zcdmnfrf.js → index-s3m89wt2.js} +9 -9
- package/{index-v50xjbbe.js → index-t4d0ckde.js} +1 -1
- package/{index-9p260r4e.js → index-trffs83s.js} +538 -250
- package/{index-ddk49ypz.js → index-v929w7j7.js} +133 -49
- package/index-va90m8nd.js +25 -0
- package/index-vjbne22r.js +80 -0
- package/{index-h7hehkw6.js → index-xczjdng6.js} +3 -1
- package/{index-39jz41jb.js → index-xs9a3ddt.js} +3 -3
- package/{index-84c2pgak.js → index-yvzm8mby.js} +94 -82
- package/{index-wr9magsr.js → index-yxkjsyx8.js} +3 -3
- package/index-ze48c0vd.js +788 -0
- package/{index-ygdbn9jn.js → index-zyb0ebm4.js} +1 -1
- package/index.js +29 -24
- package/libExecutor-tq994592.js +10 -0
- package/{library.command-qs8beggh.js → library.command-x219mhcx.js} +9 -4
- package/{localRegistry.command-hz4ged9n.js → localRegistry.command-zvdcejhn.js} +30 -24
- package/{module.command-z9js77m2.js → module.command-k6cwcm7g.js} +17 -8
- package/{package.command-zqenq8c0.js → package.command-vw7x09f8.js} +13 -8
- package/package.json +2 -2
- package/{page.command-t0nx1jat.js → page.command-gf06paq2.js} +9 -4
- package/{pipeline.command-2yjeas7m.js → pipeline.command-y07dgj9b.js} +14 -8
- package/pkgExecutor-stde3yc3.js +10 -0
- package/{primitive.command-v5kypwy4.js → primitive.command-edydvh07.js} +13 -8
- package/{projectTypecheck-s9hhe5sa.js → projectTypecheck-mk8wefvd.js} +2 -1
- package/{prompter-qrwx1p17.js → prompter-qyggfhqd.js} +2 -2
- package/{quality.command-q55j2htd.js → quality.command-mdb45vyr.js} +23 -16
- package/{recipeScanner-4b69ybe0.js → recipeScanner-rrx69awy.js} +1 -1
- package/{repair.command-7ssbbdq2.js → repair.command-kvtaeecy.js} +13 -8
- package/{routeSourceValidator-4h947v7c.js → routeSourceValidator-8n6j1vn7.js} +4 -2
- package/{scalar.command-p5jb7z57.js → scalar.command-sjt9p5e1.js} +11 -6
- package/skills/akan-debug/SKILL.md +10 -3
- package/skills/akan-err/SKILL.md +7 -0
- package/skills/akan-mcp/SKILL.md +17 -2
- package/skills/akan-scaffold/SKILL.md +2 -2
- package/skills/akan-transport/SKILL.md +2 -0
- package/skills/akan-validate/SKILL.md +1 -0
- package/{subspace.command-7wxy6ptj.js → subspace.command-mkkqync4.js} +29 -23
- package/templates/app/page/_layout.tsx +13 -0
- package/templates/app/page/styles.css.template +40 -0
- package/templates/appSample/page/_index.tsx +9 -9
- package/templates/appSample/page/_layout.tsx +1 -0
- package/templates/appSample/page/styles.css.template +40 -5
- package/templates/appSample/ui/Recipe/jellyButton.ts +1 -1
- package/templates/biomeForm.ts +1 -1
- package/templates/env/_env.server.type.ts +1 -1
- package/templates/facetIndex/index.ts +2 -37
- package/templates/lib/sig.ts +0 -4
- package/templates/lib/useClient.ts +1 -1
- package/templates/workspaceRoot/AGENTS.md.template +2 -1
- package/{tunnel.command-22g11n0x.js → tunnel.command-tr5b3030.js} +17 -12
- package/{typeChecker-s640r6c0.js → typeChecker-bfrd1n9n.js} +1 -1
- package/typecheck.proc.js +6 -3
- package/{verify.command-m0wnndd7.js → verify.command-0p9h8tpp.js} +26 -20
- package/{workflow.command-jx8dqs9n.js → workflow.command-9mfcwqzj.js} +37 -19
- package/{workspace.command-ca9kfyt3.js → workspace.command-5hjtmcfs.js} +61 -54
- package/CodeAgent-e9c712an.js +0 -11
- package/TunnelShare-zkfkrw8w.js +0 -14
- package/agent.command-9erafkcb.js +0 -51
- package/cloud.script-arsagnq6.js +0 -30
- package/context.runner-mqpp67br.js +0 -29
- package/index-x3x31df8.js +0 -14
- /package/templates/{appSample → app}/public/fonts/Pretendard-Bold.woff2 +0 -0
- /package/templates/{appSample → app}/public/fonts/Pretendard-Medium.woff2 +0 -0
- /package/templates/{appSample → app}/public/fonts/Pretendard-Regular.woff2 +0 -0
- /package/templates/{appSample → app}/public/fonts/Pretendard-SemiBold.woff2 +0 -0
|
@@ -0,0 +1,164 @@
|
|
|
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
|
+
| `liveRoomTaken` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
77
|
+
| `locked` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
|
|
78
|
+
| `logControlUnavailable` | 503 | `LogControlUnavailableError` | no | yes | `server/logging/logTailClient.ts` |
|
|
79
|
+
| `missingFilterQuery` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
80
|
+
| `missingInput` | 400 | `InvalidInputError` | no | yes | `constant/invalidInputError.ts` |
|
|
81
|
+
| `missingModel` | 500 | `SignalDeclarationError` | no | yes | `signal/signalDeclarationError.ts` |
|
|
82
|
+
| `missingSlice` | 500 | `SignalDeclarationError` | no | yes | `signal/signalDeclarationError.ts` |
|
|
83
|
+
| `noHandler` | 500 | `SignalContractError` | no | yes | `signal/signalContractError.ts` |
|
|
84
|
+
| `notApplied` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
|
|
85
|
+
| `notFound` | 404 | `Exception.NotFound` | yes | no | `signal/exception.ts` |
|
|
86
|
+
| `notFound` | 404 | `ImageOptimizerError` | no | yes | `server/imageOptimizerError.ts` |
|
|
87
|
+
| `notFound` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
|
|
88
|
+
| `notInitialized` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
89
|
+
| `notInitialized` | 500 | `InjectError` | no | yes | `service/injectError.ts` |
|
|
90
|
+
| `notRegistered` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
91
|
+
| `notRegistered` | 500 | `InjectError` | no | yes | `service/injectError.ts` |
|
|
92
|
+
| `notRegistered` | 500 | `SignalContractError` | no | yes | `signal/signalContractError.ts` |
|
|
93
|
+
| `nullableLastArg` | 500 | `SignalDeclarationError` | no | yes | `signal/signalDeclarationError.ts` |
|
|
94
|
+
| `payloadTooLarge` | 413 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
95
|
+
| `payloadTooLarge` | 413 | `ImageOptimizerError` | no | yes | `server/imageOptimizerError.ts` |
|
|
96
|
+
| `planChanged` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
|
|
97
|
+
| `redisUriMissing` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
98
|
+
| `remoteOAuth` | 502 | `RemoteError` | no | yes | `server/remote/remoteError.ts` |
|
|
99
|
+
| `remoteProtocol` | 502 | `RemoteError` | no | yes | `server/remote/remoteError.ts` |
|
|
100
|
+
| `remoteTooLarge` | 502 | `RemoteError` | no | yes | `server/remote/remoteError.ts` |
|
|
101
|
+
| `remoteUnauthorized` | 401 | `RemoteError` | no | yes | `server/remote/remoteError.ts` |
|
|
102
|
+
| `remoteUnavailable` | 502 | `RemoteError` | no | yes | `server/remote/remoteError.ts` |
|
|
103
|
+
| `remoteUrlRejected` | 502 | `RemoteError` | no | yes | `server/remote/remoteError.ts` |
|
|
104
|
+
| `renderAborted` | 499 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
105
|
+
| `routeConflict` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
106
|
+
| `routeNotFound` | 404 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
107
|
+
| `routeNotFound` | 404 | `RscRouteNotFound` | no | yes | `server/rscClient.tsx` |
|
|
108
|
+
| `routerNotReady` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
109
|
+
| `rpcDisposed` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
110
|
+
| `rscFetchFailed` | 502 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
111
|
+
| `rscQueueOverflow` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
112
|
+
| `rscRedirectStarted` | 303 | `RscRedirectNavigationStarted` | no | yes | `server/rscClient.tsx` |
|
|
113
|
+
| `rscWorkerFailed` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
114
|
+
| `rscWorkerStopped` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
115
|
+
| `searchMisconfigured` | 500 | `DocumentStoreError` | no | yes | `service/documentStoreError.ts` |
|
|
116
|
+
| `searchUnavailable` | 500 | `DocumentStoreError` | no | yes | `service/documentStoreError.ts` |
|
|
117
|
+
| `secretRefused` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
118
|
+
| `secretStoreUnavailable` | 503 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
119
|
+
| `serviceUnavailable` | 503 | `ImageOptimizerError` | no | yes | `server/imageOptimizerError.ts` |
|
|
120
|
+
| `shutdownTimeout` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
121
|
+
| `stageFailed` | 500 | `StageFailedError` | no | yes | `server/di/stageFailedError.ts` |
|
|
122
|
+
| `storageNotShared` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
123
|
+
| `tableMissing` | 500 | `DocumentStoreError` | no | yes | `service/documentStoreError.ts` |
|
|
124
|
+
| `tooManyRequests` | 429 | `Exception` | yes | no | `signal/exception.ts` |
|
|
125
|
+
| `transferUnsupported` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
126
|
+
| `unauthorized` | 401 | `Exception.Unauthorized` | yes | no | `signal/exception.ts` |
|
|
127
|
+
| `undefinedReturn` | 500 | `SignalContractError` | no | yes | `signal/signalContractError.ts` |
|
|
128
|
+
| `unencodableValue` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
129
|
+
| `unguardedEndpoint` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
130
|
+
| `unmaskedResource` | 500 | `PromptError` | no | yes | `signal/mcp/promptError.ts` |
|
|
131
|
+
| `unroutableLiveQuery` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
132
|
+
| `unstorableValue` | 400 | `DocumentStoreError` | no | yes | `service/documentStoreError.ts` |
|
|
133
|
+
| `unsupportedMediaType` | 415 | `Exception.UnsupportedMediaType` | yes | no | `signal/exception.ts` |
|
|
134
|
+
| `usage` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
|
|
135
|
+
| `verifyFailed` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
|
|
136
|
+
| `wrongTransport` | 500 | `SignalContractError` | no | yes | `signal/signalContractError.ts` |
|
|
137
|
+
| set when thrown | set when thrown | `Err` | yes | yes | `common/err.ts` |
|
|
138
|
+
| set when thrown | set when thrown | `Err.BadRequest` | yes | yes | `common/err.ts` |
|
|
139
|
+
| set when thrown | set when thrown | `Err.Conflict` | yes | yes | `common/err.ts` |
|
|
140
|
+
| set when thrown | set when thrown | `Err.Forbidden` | yes | yes | `common/err.ts` |
|
|
141
|
+
| set when thrown | set when thrown | `Err.NotFound` | yes | yes | `common/err.ts` |
|
|
142
|
+
| set when thrown | set when thrown | `Err.Unauthorized` | yes | yes | `common/err.ts` |
|
|
143
|
+
|
|
144
|
+
## Codes by status
|
|
145
|
+
|
|
146
|
+
An error coded by its status, such as an `Exception`, takes its code from `AkanError.codeOfStatus`:
|
|
147
|
+
|
|
148
|
+
| Status | Code | Reason |
|
|
149
|
+
|---|---|---|
|
|
150
|
+
| 400 | `badRequest` | Bad Request |
|
|
151
|
+
| 401 | `unauthorized` | Unauthorized |
|
|
152
|
+
| 403 | `forbidden` | Forbidden |
|
|
153
|
+
| 404 | `notFound` | Not Found |
|
|
154
|
+
| 409 | `conflict` | Conflict |
|
|
155
|
+
| 413 | `payloadTooLarge` | Payload Too Large |
|
|
156
|
+
| 415 | `unsupportedMediaType` | Unsupported Media Type |
|
|
157
|
+
| 429 | `tooManyRequests` | Too Many Requests |
|
|
158
|
+
| 500 | `internalError` | Internal Server Error |
|
|
159
|
+
| 502 | `badGateway` | Bad Gateway |
|
|
160
|
+
| 503 | `serviceUnavailable` | Service Unavailable |
|
|
161
|
+
| 504 | `gatewayTimeout` | Gateway Timeout |
|
|
162
|
+
|
|
163
|
+
Any other status is coded `http<status>`, with the reason `Internal Server Error` from 500 and `Request Failed`
|
|
164
|
+
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"` (`
|
|
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
|
-
|
|
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.
|
|
@@ -250,6 +259,17 @@ export default page()
|
|
|
250
259
|
`base.error.documentNotFound`, so a tool reads its dictionary sentence (`The requested item does not exist.`) and an
|
|
251
260
|
MCP App view receives that `Err`; a prompt whose page reads it is `No screen exists for these arguments.`
|
|
252
261
|
Only a real failure logs a stack; an agent can drive the rest at will.
|
|
262
|
+
- **Every failed call carries a code** beside the text, which reads as it always did. A tool error holds
|
|
263
|
+
`_meta["akanjs/failure"]: { code, statusCode }` — in `_meta`, because a client checks `structuredContent` against
|
|
264
|
+
the tool's `outputSchema` even on a failure — and a JSON-RPC error holds `data.code`, which tells apart what
|
|
265
|
+
`-32602` files together: `unknownTool`, `invalidArgument`, `unknownPrompt`, `unknownResource` and a screen's
|
|
266
|
+
refusal, beside `tooManyRequests` and `internalError`. The code is the one an HTTP caller gets: a domain `Err`'s
|
|
267
|
+
dictionary key (what `Err.is` matches), else the `AkanError`'s own code; a guard's 401 or 403 by its status alone
|
|
268
|
+
(`unauthorized`, `forbidden`), since a guard's own code names its rule as its message does; a crash, or a 5xx whose
|
|
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.
|
|
253
273
|
- **Three revisions are spoken**: the modern `2026-07-28` and the legacy `2025-11-25` / `2025-06-18`, which are
|
|
254
274
|
wire-identical over the POST-only surface this implements — a client whose proposal is not listed is told to
|
|
255
275
|
disconnect. An unknown proposal is answered at whichever end of that list it is closer to, and an unimplemented
|
|
@@ -479,6 +499,19 @@ export default page()
|
|
|
479
499
|
- `option.setMcp({ apps: false })` / `AKAN_MCP_APPS=false` publishes no page tools: no app is published and every
|
|
480
500
|
prompt stays a prompt only. `web: { csr: false }` publishes the app tools with no view, and an API-only build
|
|
481
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.
|
|
482
515
|
|
|
483
516
|
## Progress Reporting
|
|
484
517
|
**`McpProgress.report(n, { total, message })`** reports progress from anywhere inside a call, a service or adapter
|
|
@@ -486,6 +519,142 @@ frames down included, and is a no-op when nobody is streaming — so the same co
|
|
|
486
519
|
websocket, and in tests. `McpProgress.streaming` says whether anyone is reading, for a report whose message
|
|
487
520
|
costs something to assemble.
|
|
488
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, and a name an endpoint holds is dropped. The run
|
|
560
|
+
never runs one: `approve` is asked, then the run ends `awaiting` with `client: true`. Have the page `run(call)`,
|
|
561
|
+
append its result — or your own error when no page answers — and resume.
|
|
562
|
+
- **Asking the member.** `ask: true` lists `askUser({ question, choices?, multiple? })`, the in-page chat's own tool.
|
|
563
|
+
A call ends the run `awaiting` with `question: true`; put the question to the member, append
|
|
564
|
+
`{ id, name: "askUser", result }` — or an `error` when they dismiss it — and resume. It never reaches `approve`,
|
|
565
|
+
counts as no tool call, and `untrusted` never sees the answer. A `clientTools` entry by that name is dropped.
|
|
566
|
+
- **Other servers.** `remotes` takes other MCP servers, each a toolkit named after it: none is listed or contacted
|
|
567
|
+
until the model opens it, and its tools then read `<name>.<tool>`. See "Calling Another Server" below.
|
|
568
|
+
- **Writes after untrusted input.** `untrusted(result)` marks a result third parties wrote, and every later call
|
|
569
|
+
reaches `approve(call, { tainted, tool })` with `tainted` set. A batch is judged before it runs, since the model
|
|
570
|
+
wrote it before reading its results. Without `approve`, a `needsConfirm` tool — on this catalogue, a mutation
|
|
571
|
+
with the `destructive` hint above — is refused, and so is every write once tainted. `"defer"` holds the whole batch, emits
|
|
572
|
+
`awaiting` and ends the run as `"awaiting"`.
|
|
573
|
+
- **Resuming.** Store each message `onMessage` hands over — it is awaited, and a retried run may hand one over twice —
|
|
574
|
+
and call `loop` again with them. Trailing calls nothing answered go to `approve` again before any model call, and
|
|
575
|
+
the taint is rebuilt from the `tainted` marks on stored messages and by re-applying `untrusted`, which sees a result
|
|
576
|
+
whole during the run and clipped on a resume. Store every message whole, marks included. `compacted` says the first
|
|
577
|
+
`replaced` messages are now `summary`; its `tainted` marker stands in for the results it replaced, and a summary
|
|
578
|
+
with no marker counts as tainted to a run with `untrusted`. A batch's results
|
|
579
|
+
reach `onMessage` even when the consumer stops reading or a later call throws, so a resume runs only calls that
|
|
580
|
+
never started.
|
|
581
|
+
- **Metering.** Each model call, compactions included, is its own turn for the request policy, the quota and the
|
|
582
|
+
usage hook. It gets a fresh `id`, `loop { id, round }`, a copy of the request's `meta` — server-set, so it may key
|
|
583
|
+
billing — empty headers and no ip. The relay's default size caps skip loop rounds; a refused quota ends the run as
|
|
584
|
+
`"quota"`.
|
|
585
|
+
- **Limits.** `maxRounds` (12), `budget { tokens, toolCalls, wallMs }` (`"budget"`), `signal` (`"aborted"`) and a
|
|
586
|
+
provider cut (`"length"`). A limit that is not a valid number is an `error` before any model call. `wallMs` and
|
|
587
|
+
`signal` also end a run waiting on a tool or on `approve`. `callAs` cannot cancel a call, so the run stops waiting
|
|
588
|
+
and answers it with an error saying it may still finish; a resume does not run it again, and the endpoint runs on
|
|
589
|
+
with its outcome unreported. There is no preamble unless `preamble` gives one; with no `instructions` either, a
|
|
590
|
+
short neutral prompt stands in, as each adaptor's own fallback is about a screen. `compact { at, keep }` summarizes
|
|
591
|
+
the head, and a tool result is capped at 20,000 characters as the browser caps it. Its calls carry no ip, so an
|
|
592
|
+
ip-scoped `rateLimit` counts them under one unknown address.
|
|
593
|
+
- **A refusal for length.** With `compact` set, a round whose call fails as `agent.error.contextOverflow` compacts
|
|
594
|
+
regardless of `at` and asks once more, as one round; a second refusal, or nothing to cut, ends the run with the
|
|
595
|
+
error. An adaptor with its own size cap throws that error with `{ limit, requested }` in its own unit, bytes
|
|
596
|
+
included, and the run lowers `at` to where that request would have fit.
|
|
597
|
+
|
|
598
|
+
## Calling Another Server — `remotes`
|
|
599
|
+
|
|
600
|
+
The other direction: an agent running here calls another server's `/mcp` as the signed-in user. The other server needs
|
|
601
|
+
no change; any akan app is one already, and so is any MCP server that speaks OAuth 2.1 with dynamic registration.
|
|
602
|
+
|
|
603
|
+
```ts
|
|
604
|
+
// lib/option.ts — off by default, since it lets a signed-in user make this server call an address they name
|
|
605
|
+
export const option = new AkanOption<ModulesOptions>().transformEnv((env) => ({ ...env, remote: { enabled: true } }));
|
|
606
|
+
|
|
607
|
+
// a service that runs the loop
|
|
608
|
+
const remotes = this.remoteService.sources(account, [
|
|
609
|
+
{ name: "shop", url: project.serverUrl, description: "Orders and refunds of the shop this project runs." },
|
|
610
|
+
]);
|
|
611
|
+
for await (const event of this.agentService.loop({ account, allow, messages, remotes, approve, onMessage })) {
|
|
612
|
+
if (event.type === "awaiting" && event.connect) /* tell the page: this run waits for a connection to event.connect */;
|
|
613
|
+
}
|
|
614
|
+
```
|
|
615
|
+
|
|
616
|
+
- **A connection is the user's own OAuth grant at the other server.** `libs/shared`'s `remote` service registers this
|
|
617
|
+
app there once, sends the user to that server's consent page, and keeps the tokens sealed on the server. The other
|
|
618
|
+
server judges every call by its own guards, as it judges any agent's, so `Person` endpoints stay closed. Accounts
|
|
619
|
+
are never matched across servers.
|
|
620
|
+
- **Connecting happens in the chat.** Opening a remote the account has no connection to ends the run `awaiting` with
|
|
621
|
+
`connect: "<name>"` and leaves the call unanswered. Render `<Remote.Util.Connect url={…} onConnected={resume} />`:
|
|
622
|
+
it opens the other server's sign-in in a window and calls back once `page/remote/callback` finished the exchange.
|
|
623
|
+
Resume with the stored messages and the run opens the toolkit itself. When the user declines, append
|
|
624
|
+
`{ id, name: "openToolkit", error }` for that call and resume.
|
|
625
|
+
- **What a remote lists and returns is another party's text.** Opening a remote taints the run, whatever `untrusted`
|
|
626
|
+
says: its tools' names, descriptions and schemas reach the model with the open, and so does the error of an open
|
|
627
|
+
that failed. An open that only asks the user to connect taints nothing. A call's arguments leave for that server,
|
|
628
|
+
and `readOnly` is the remote's own word for its tool, so a request with `remotes` and no `approve` is refused
|
|
629
|
+
before any model call, as `base.error.requiredArgument` naming `approve`: pass one with `remotes`. It is told the
|
|
630
|
+
target as `state.remote`, and hears a tool the remote does not call read-only as a `needsConfirm` one. Show the
|
|
631
|
+
user that server's name and the arguments before allowing a write: a record on one server can ask the model to
|
|
632
|
+
write to another.
|
|
633
|
+
- **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
|
|
634
|
+
characters a provider refuses is listed under a shortened alias and still called by its real name. A run takes
|
|
635
|
+
at most 120 tools from one remote, a description to 1,000 characters and a parameter schema to 8,000, and stops
|
|
636
|
+
listing at 120,000 characters in all; the open's result counts the tools left out as `omitted`. Pass `allow` in
|
|
637
|
+
the remote's entry to choose which tools those are.
|
|
638
|
+
- **Addresses.** `url` is the server's address or its MCP endpoint; a bare origin means `/mcp`. Every request goes
|
|
639
|
+
through `RemoteFetch`: https only, no private address, no redirect, the checked address pinned. A local run
|
|
640
|
+
(`operationMode: "local"`) reaches loopback over http, so two dev servers can connect; `remote.allowUrl` narrows
|
|
641
|
+
the addresses an app accepts.
|
|
642
|
+
- **A screen in the result.** When the called tool is a `page().app()`, the `toolResult` event carries `view`
|
|
643
|
+
(`{ remote, tool, args, href?, static?, resourceUri? }`) beside the result. It never reaches the model or
|
|
644
|
+
`onMessage`; store it yourself and draw `<Remote.Zone.Screen url tool={view.tool} args={view.args} href={view.href}
|
|
645
|
+
drawn={view.static} />`. For an app the other server declared `{ static: true }` the card asks `remoteScreen` for
|
|
646
|
+
that server's script-less HTML when it scrolls into view and shows it in a frame that runs no script; for any other
|
|
647
|
+
app, draw `<Remote.Zone.View url tool args uri={view.resourceUri} href />`: it frames that server's view (its
|
|
648
|
+
client bundle) with scripts on but no origin, under a policy that lets it load only from that server and connect
|
|
649
|
+
nowhere, and relays the view's own calls to that one server through `McpAppHost` (`akanjs/webkit`). A view cannot
|
|
650
|
+
write into the model's context, and a link it opens must stay on its server. Neither card stores what it drew: the
|
|
651
|
+
HTML and the view's data are fetched again on every draw, since what the user may see there can change. A view
|
|
652
|
+
weighs over a megabyte, so prefer `{ static: true }` on the other server for anything a person only reads.
|
|
653
|
+
- **Not published onward.** The connection endpoints take `Person` and are `mcp: false`, and remote tools exist only
|
|
654
|
+
inside the run: an outside agent connected to this app's `/mcp` never reaches a user's other servers through it.
|
|
655
|
+
|
|
656
|
+
Without `libs/shared`, build each entry from `RemoteSource` (`akanjs/server`) with your own `access { token, renew }`.
|
|
657
|
+
|
|
489
658
|
## Rolling MCP Out To An App
|
|
490
659
|
|
|
491
660
|
The goal of exposing a service over MCP is that a person uses it through an agent instead of through the page:
|
|
@@ -48,6 +48,11 @@ body shape — this is the full contract behind them. Before changing route beha
|
|
|
48
48
|
that is harmless to repeat and safe for anyone to trigger (a warm-up) passes `{ duringRender: true }` as the option
|
|
49
49
|
after the endpoint's own arguments (`fetch.updateX(id, data, { duringRender: true })`). `akan quality` flags the call,
|
|
50
50
|
same-file helpers included, as `akan.ssr.render-mutation`.
|
|
51
|
+
- **A `Link` renders its page ahead of the click** — on hover, on keyboard focus, or as it shows with
|
|
52
|
+
`prefetch="viewport"` (production only). A page whose render has an effect one visit should cause once — a view
|
|
53
|
+
counted through `duringRender`, an expensive report — refuses with `.config({ prefetch: false })`; on a `_layout.tsx`
|
|
54
|
+
it covers every page below, and a page there opts back in with `prefetch: true`. Its guards still run for the
|
|
55
|
+
prefetch, so a redirect answers as one, and the click renders the page as usual.
|
|
51
56
|
|
|
52
57
|
## Route Guards — `.guard()`
|
|
53
58
|
|
|
@@ -55,7 +60,12 @@ body shape — this is the full contract behind them. Before changing route beha
|
|
|
55
60
|
`.guard()` throws when the module loads. `fn` receives the route's typed arguments and `lang` (a layout's gets no
|
|
56
61
|
`children`) and may be `async`. It refuses by moving the router — `router.redirect(href)`, `router.notFound()` — or
|
|
57
62
|
with `getSelf({ unauthorize })`; `signedIn()` from `@libs/shared/webkit` is that last one, called inside an arrow
|
|
58
|
-
(`.guard(() => signedIn())`), because `.guard(signedIn)` would
|
|
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.
|
|
59
69
|
- **On the server every guard of the chain runs before any layout body starts**, root layout first and before the
|
|
60
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 —
|
|
61
71
|
where a `getSelf({ unauthorize })` inside a layout body under a `.loading()` redirects late after I/O, inside the
|
|
@@ -114,6 +124,10 @@ body shape — this is the full contract behind them. Before changing route beha
|
|
|
114
124
|
`property`, and a canonical / manifest / icon link, and keeps the rest — so a page states only what it changes.
|
|
115
125
|
- A canonical link and `og:url` each name one URL, so a page carries them only from its own `.head()`, never from a
|
|
116
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.
|
|
117
131
|
- **A not-found or error view titles itself**: the `<title>` and `<meta>` at the top of what a layout's `.notFound()`
|
|
118
132
|
/ `.error()` returns replace the layouts' head, and the page's own head is dropped. Under a `.loading()` the head is
|
|
119
133
|
already out, so they stay in the view.
|
|
@@ -391,7 +391,8 @@ const config: AppConfig = {
|
|
|
391
391
|
was opened for while its frames load web content from anywhere, with an init script that runs in the top document
|
|
392
392
|
only, `evaluate`, a trusted `sendKey`, `capture`, and `loadFailed` / `gone` (it reloads, or is rebuilt, by itself;
|
|
393
393
|
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
|
|
394
|
+
again) / `consoleMessage` events. Every method on Windows and Linux, where a visible view also holds the keyboard
|
|
395
|
+
focus and no `consoleMessage` is sent; macOS 14+ lacks `sendKey`, `setMuted` and `capture`.
|
|
395
396
|
|
|
396
397
|
## A Desktop App's Server — `bin` And `trustedDependencies`
|
|
397
398
|
|
|
@@ -536,6 +537,10 @@ page API is
|
|
|
536
537
|
`akanjs/client/native/<id>` (`akanjs/client/native/window`, `…/screen`, `…/global-shortcut`), imported in a `webkit/`
|
|
537
538
|
hook; `volume` and `filePicker` also come from `akanjs/client/native` itself. A capability the shell
|
|
538
539
|
lacks is added there: an app's own plugin runs as Bun code in the plugin host and cannot add a native shell op.
|
|
540
|
+
`isNativeApp()`, `isNativeShell()`, `nativePlatform()` and `desktopPlatform()` come from `akanjs/client`, which starts
|
|
541
|
+
the native runtime only inside a shell. A static import of `akanjs/client/native` loads `@akanjs/native/core` on every
|
|
542
|
+
web page that reaches the file, so an app's store, or its own hook a web page also renders, loads the plugin on first
|
|
543
|
+
use behind the check: `if (isNativeApp()) await (await import("akanjs/client/native/push")).push.register()`.
|
|
539
544
|
|
|
540
545
|
**A plugin the app or lib owns lives in `native/<id>/`**, the folder named after the plugin id: `native-plugin.json`
|
|
541
546
|
beside its page API (`src/index.ts`, `definePlugin` from `akanjs/client/native`), its desktop part (`src/desktop.ts`,
|
|
@@ -555,7 +560,7 @@ uses `getCookie` / `setCookie` / `removeCookie`, `storage`, and `secretStorage`
|
|
|
555
560
|
names — pass `sameSite: "none"` only for a cookie a cross-site POST must carry back. `getCookie` reads a name sent
|
|
556
561
|
twice as unset, since a sibling subdomain can plant a second copy; server code reads `cookieJar()` from
|
|
557
562
|
`akanjs/fetch`, or `CookieJar.parse(req.headers.get("cookie"))`, never `req.cookies`. Browser APIs an app WebView lacks
|
|
558
|
-
stay in a `webkit/` hook that branches on `isNativeApp()` from `akanjs/client
|
|
563
|
+
stay in a `webkit/` hook that branches on `isNativeApp()` from `akanjs/client`, which is where the app side goes
|
|
559
564
|
too (`no-web-only-api-outside-webkit`, a warning): `navigator.share` / `canShare` (Android's WebView has none),
|
|
560
565
|
`navigator.serviceWorker` and `Notification.requestPermission` / `.permission` (no app page has them),
|
|
561
566
|
`navigator.geolocation` (use `useGeoLocation` from `akanjs/webkit`) and `navigator.vibrate` (iOS has none; use
|
|
@@ -625,10 +630,11 @@ serving without a key. Everything else is behind the ops channel.
|
|
|
625
630
|
get 30 a minute per process; every refusal is the same 401 and spends none of them, and an address refused 10
|
|
626
631
|
times in a minute gets 429 until it passes. A malformed key, or the machine token's own key
|
|
627
632
|
(`AKAN_MACHINE_PUBLIC_KEY`), logs an error and leaves the app serving with the channel off.
|
|
628
|
-
- **A migrate job runs for the token's `sub`**, which the run records as its actor: apply
|
|
629
|
-
token without one, and a body naming `actor` is refused. Each option reaches the command as
|
|
630
|
-
job runs at a time per process (409 meanwhile); the run's own lease keeps two hosts on one
|
|
631
|
-
live in memory, so after a restart read the outcome from `list`. Polls count toward the 30 a
|
|
633
|
+
- **A migrate job runs for the token's `sub`**, which the run records as its actor: apply, rollback and prune-indexes
|
|
634
|
+
refuse a token without one, and a body naming `actor` is refused. Each option reaches the command as
|
|
635
|
+
`--name=value`. One job runs at a time per process (409 meanwhile); the run's own lease keeps two hosts on one
|
|
636
|
+
database apart. Jobs live in memory, so after a restart read the outcome from `list`. Polls count toward the 30 a
|
|
637
|
+
minute.
|
|
632
638
|
- **The app holds no storage credential.** It PUTs to the presigned URLs it was handed (`application/octet-stream`,
|
|
633
639
|
the manifest `application/json`), plain http only to loopback. The manifest landing is the commit marker.
|
|
634
640
|
- **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
|
|
@@ -66,6 +68,11 @@ HTTP verb a mutation is mounted under. `conventions` carries the invariants —
|
|
|
66
68
|
- **A subscribe the client leaves before it finishes joins nothing.** When an `unsubscribe` for the room, or the
|
|
67
69
|
socket's close, arrives while the subscribe is still running, the subscribe answers `subscribe: false` and runs its
|
|
68
70
|
`unsubscribe` cleanup (and its `disconnect` one when the socket closed) instead of joining the room.
|
|
71
|
+
- **A send from the browser drops the reads it may have made stale.** A mutation, an upload or a `message` sent
|
|
72
|
+
through `fetch` ends the sharing of queries already in flight and drops the pages a `Link` prefetched, so the next
|
|
73
|
+
read asks again; only this tab's own sends count. A send that changes nothing anyone reads back — typing status, a
|
|
74
|
+
cursor move — passes `{ keepsReads: true }` after its arguments (`fetch.typing(chatId, { keepsReads: true })`), or
|
|
75
|
+
a chatty endpoint keeps every prefetch from surviving. A read receipt changes an unread count and passes nothing.
|
|
69
76
|
|
|
70
77
|
## Writing A Guard
|
|
71
78
|
|