@akanjs/cli 3.2.0-rc.1 → 3.2.0-rc.11

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 (99) hide show
  1. package/.build-stamp +2 -1
  2. package/{CodeAgent-vmd9k4ak.js → CodeAgent-fk66n37w.js} +3 -3
  3. package/{CodeTui-zka44v52.js → CodeTui-4rf1mqmv.js} +1 -1
  4. package/README.ko.md +26 -1
  5. package/README.md +26 -1
  6. package/TunnelShare-44er4e29.js +15 -0
  7. package/{agent.command-2f657613.js → agent.command-7g9czkkd.js} +20 -19
  8. package/akanCode.js +3 -3
  9. package/{application.command-q6skd3am.js → application.command-00spg55s.js} +31 -24
  10. package/{applicationBuildRunner-sctcmkyx.js → applicationBuildRunner-f4yf0qyc.js} +9 -7
  11. package/buildBatch.proc.js +7 -6
  12. package/{cloud.command-7642pks6.js → cloud.command-ab704p0g.js} +24 -25
  13. package/cloud.script-4p4y0s7e.js +31 -0
  14. package/{code.command-7s4ndq2k.js → code.command-m6c9xk56.js} +7 -6
  15. package/{context.command-569z0rqf.js → context.command-hgcgxtdk.js} +20 -19
  16. package/context.runner-w071gmc3.js +30 -0
  17. package/{devTui-w38ch13a.js → devTui-h77zrjv5.js} +1 -1
  18. package/{guideline.command-gnv3e8p8.js → guideline.command-6yz6d4hf.js} +3 -2
  19. package/guidelines/agentRule/agentRule.instruction.md +4 -3
  20. package/guidelines/akanApi/akanApi.instruction.md +2 -0
  21. package/guidelines/conventions/core.md +1 -1
  22. package/guidelines/conventions/rules/app.md +3 -0
  23. package/guidelines/conventions/rules/page.md +5 -0
  24. package/guidelines/errorCodes/errorCodes.instruction.md +140 -0
  25. package/guidelines/fieldRule/fieldRule.instruction.md +2 -1
  26. package/guidelines/mcpRule/mcpRule.instruction.md +72 -2
  27. package/guidelines/pageRule/pageRule.instruction.md +5 -0
  28. package/guidelines/runtimeRule/runtimeRule.instruction.md +5 -1
  29. package/guidelines/transportRule/transportRule.instruction.md +5 -0
  30. package/incrementalBuilder.proc.js +8 -7
  31. package/{index-vkzfk7qt.js → index-097bjwvm.js} +40 -30
  32. package/{index-93ewzmp6.js → index-23d8gw08.js} +165 -102
  33. package/{index-p6hjwt2d.js → index-41mfhgq0.js} +72 -26
  34. package/{index-ktb3wcqz.js → index-4k9nv4m3.js} +71 -81
  35. package/{index-vr68mxj5.js → index-5jwx4bf2.js} +69 -33
  36. package/{index-5w9my9qe.js → index-6eptmk8z.js} +30 -20
  37. package/{index-d4n1wmrz.js → index-6fnrhpn1.js} +8 -4
  38. package/{index-kpdv34rq.js → index-6qtxs86x.js} +10 -7
  39. package/{index-ed6ea0qp.js → index-6z57w95f.js} +1 -1
  40. package/{index-drz9e84d.js → index-7ky4brfy.js} +2 -2
  41. package/{index-8g7tdsk4.js → index-849qvd7t.js} +58 -29
  42. package/{index-1q1cjn8s.js → index-9xh4zvw3.js} +94 -53
  43. package/{index-48d5qsj3.js → index-adj7qmz9.js} +23 -15
  44. package/{index-fjr4d6yd.js → index-apcr1qgk.js} +458 -304
  45. package/{index-8ts9774g.js → index-aybfcx58.js} +9 -4
  46. package/{index-8kczhnmv.js → index-b3pr4ee6.js} +1 -1
  47. package/{index-23860fej.js → index-b4qq3rq0.js} +23 -8
  48. package/{index-thckcabc.js → index-bper31wr.js} +24 -6
  49. package/{index-a8a9ede9.js → index-bxkx0x03.js} +14 -7
  50. package/{index-0fb3cpbt.js → index-c3r23w24.js} +9 -7
  51. package/{index-8pb9yvp8.js → index-dfsa009c.js} +148 -31
  52. package/{index-zpv14wpy.js → index-dsg50er9.js} +3 -3
  53. package/{index-hqrkqxx2.js → index-e5f6czck.js} +46 -7
  54. package/{index-sy481q2x.js → index-frvjq1rd.js} +1 -1
  55. package/{index-abgh0jve.js → index-grt0e6kk.js} +1 -1
  56. package/{index-e3vmjtph.js → index-hf9nvwam.js} +7 -2
  57. package/{index-v4p1zye8.js → index-hhagjhkh.js} +7 -7
  58. package/index-j4yvgfhr.js +70 -0
  59. package/{index-s2grpzef.js → index-k2r3hmbz.js} +6 -4
  60. package/{index-7y5yghjg.js → index-nd39rssn.js} +1162 -435
  61. package/{index-6wpaq392.js → index-p4htjyvk.js} +44 -5
  62. package/{index-aj3ehkcx.js → index-p54s83sz.js} +1 -1
  63. package/{index-7xdpww43.js → index-rdx8cyv2.js} +342 -134
  64. package/{index-sr5da35e.js → index-sq9d0jhj.js} +21 -18
  65. package/{index-eajbmk10.js → index-t4d0ckde.js} +2 -2
  66. package/{index-mqntfzv5.js → index-t8h09yjs.js} +7 -2
  67. package/index-va90m8nd.js +25 -0
  68. package/{index-rc5fvqj2.js → index-xfv2p7b5.js} +95 -58
  69. package/{index-w639tvkd.js → index-xgqz3kak.js} +29 -8
  70. package/{index-9tbgb4d8.js → index-xy70tcv4.js} +1 -1
  71. package/{index-mmym5xmb.js → index-z43wddce.js} +5 -3
  72. package/index.js +24 -23
  73. package/{library.command-1gp5qe3r.js → library.command-kc1zahcg.js} +5 -4
  74. package/{localRegistry.command-x7jptkd3.js → localRegistry.command-bz2df40m.js} +19 -18
  75. package/{module.command-4xz9he6h.js → module.command-cchwzz9r.js} +12 -7
  76. package/{package.command-s7qpnn1g.js → package.command-qcjajpv8.js} +8 -7
  77. package/package.json +2 -2
  78. package/{page.command-fan34c49.js → page.command-1t86dx8a.js} +4 -3
  79. package/{pipeline.command-ph4fnn9w.js → pipeline.command-2xx9z3d0.js} +3 -2
  80. package/{primitive.command-3fqh8emf.js → primitive.command-mc0x8txr.js} +8 -7
  81. package/{projectTypecheck-vkb40hjc.js → projectTypecheck-tz497yx7.js} +2 -1
  82. package/{quality.command-ecj6exsh.js → quality.command-11rayf5c.js} +7 -6
  83. package/{repair.command-fe9jw719.js → repair.command-8w41vy78.js} +7 -6
  84. package/{scalar.command-cnvfhk0n.js → scalar.command-rvwh98ny.js} +7 -6
  85. package/skills/akan-debug/SKILL.md +7 -3
  86. package/skills/akan-err/SKILL.md +7 -0
  87. package/skills/akan-mcp/SKILL.md +10 -1
  88. package/skills/akan-scaffold/SKILL.md +3 -2
  89. package/skills/akan-transport/SKILL.md +2 -0
  90. package/skills/akan-validate/SKILL.md +1 -0
  91. package/{subspace.command-qw5ddd6y.js → subspace.command-0970n7kd.js} +9 -8
  92. package/{tunnel.command-ggj38mqf.js → tunnel.command-bcy0rtmh.js} +8 -7
  93. package/typecheck.proc.js +5 -2
  94. package/{verify.command-w9ttxkdz.js → verify.command-ynaztxr2.js} +18 -16
  95. package/{workflow.command-ss8devj0.js → workflow.command-yp9ajthb.js} +45 -16
  96. package/{workspace.command-6z2rh8ze.js → workspace.command-e4wfxm86.js} +39 -34
  97. package/TunnelShare-k3ja4w9x.js +0 -14
  98. package/cloud.script-1sfseznn.js +0 -30
  99. package/context.runner-ms8v1rxy.js +0 -29
@@ -2,32 +2,33 @@
2
2
  import {
3
3
  Workspace,
4
4
  command
5
- } from "./index-93ewzmp6.js";
5
+ } from "./index-23d8gw08.js";
6
+ import"./index-j4yvgfhr.js";
6
7
  import"./index-bns3wcpc.js";
7
- import"./index-sr5da35e.js";
8
+ import"./index-sq9d0jhj.js";
9
+ import"./index-bper31wr.js";
8
10
  import"./index-hj6w4ka1.js";
9
- import"./index-8pb9yvp8.js";
10
- import"./index-7y5yghjg.js";
11
- import"./index-thckcabc.js";
12
- import"./index-rc5fvqj2.js";
13
- import"./index-zpv14wpy.js";
14
- import"./index-ed6ea0qp.js";
11
+ import"./index-dfsa009c.js";
12
+ import"./index-nd39rssn.js";
13
+ import"./index-xfv2p7b5.js";
14
+ import"./index-dsg50er9.js";
15
+ import"./index-6z57w95f.js";
15
16
  import"./index-m9jj544v.js";
16
- import"./index-1q1cjn8s.js";
17
- import"./index-mmym5xmb.js";
17
+ import"./index-9xh4zvw3.js";
18
+ import"./index-z43wddce.js";
18
19
  import"./index-j6eeh5d7.js";
19
20
  import"./index-ygdbn9jn.js";
20
- import"./index-w639tvkd.js";
21
- import"./index-0fb3cpbt.js";
22
- import"./index-aj3ehkcx.js";
23
- import"./index-8ts9774g.js";
24
- import"./index-48d5qsj3.js";
25
- import"./index-e3vmjtph.js";
26
- import"./index-eajbmk10.js";
27
- import"./index-vkzfk7qt.js";
21
+ import"./index-xgqz3kak.js";
22
+ import"./index-c3r23w24.js";
23
+ import"./index-p54s83sz.js";
24
+ import"./index-aybfcx58.js";
25
+ import"./index-adj7qmz9.js";
26
+ import"./index-hf9nvwam.js";
27
+ import"./index-t4d0ckde.js";
28
+ import"./index-097bjwvm.js";
28
29
  import {
29
30
  ContextScript
30
- } from "./index-kpdv34rq.js";
31
+ } from "./index-6qtxs86x.js";
31
32
 
32
33
  // pkgs/@akanjs/cli/context/context.command.ts
33
34
  class ContextCommand extends command("context", [ContextScript], ({ public: target }) => ({
@@ -0,0 +1,30 @@
1
+ // @bun
2
+ import {
3
+ ContextRunner2
4
+ } from "./index-xfv2p7b5.js";
5
+ import"./index-097bjwvm.js";
6
+ import"./index-hf9nvwam.js";
7
+ import"./index-adj7qmz9.js";
8
+ import"./index-c3r23w24.js";
9
+ import"./index-aybfcx58.js";
10
+ import"./index-p54s83sz.js";
11
+ import"./index-t4d0ckde.js";
12
+ import"./index-bper31wr.js";
13
+ import"./index-dfsa009c.js";
14
+ import"./index-6z57w95f.js";
15
+ import"./index-j6eeh5d7.js";
16
+ import"./index-dsg50er9.js";
17
+ import"./index-m9jj544v.js";
18
+ import"./index-23d8gw08.js";
19
+ import"./index-xgqz3kak.js";
20
+ import"./index-ygdbn9jn.js";
21
+ import"./index-nd39rssn.js";
22
+ import"./index-z43wddce.js";
23
+ import"./index-9xh4zvw3.js";
24
+ import"./index-sq9d0jhj.js";
25
+ import"./index-j4yvgfhr.js";
26
+ import"./index-hj6w4ka1.js";
27
+ import"./index-bns3wcpc.js";
28
+ export {
29
+ ContextRunner2 as ContextRunner
30
+ };
@@ -1,7 +1,7 @@
1
1
  // @bun
2
2
  import {
3
3
  stripAnsi
4
- } from "./index-23860fej.js";
4
+ } from "./index-b4qq3rq0.js";
5
5
  import {
6
6
  writeClipboard
7
7
  } from "./index-p6pbz9n5.js";
@@ -2,9 +2,10 @@
2
2
  import {
3
3
  script,
4
4
  command
5
- } from "./index-93ewzmp6.js";
5
+ } from "./index-23d8gw08.js";
6
+ import"./index-j4yvgfhr.js";
6
7
  import"./index-bns3wcpc.js";
7
- import"./index-sr5da35e.js";
8
+ import"./index-sq9d0jhj.js";
8
9
  import {
9
10
  Prompter2
10
11
  } from "./index-j6eeh5d7.js";
@@ -32,9 +32,10 @@ pages declaring one name never clash, and a registry kept outside the surface re
32
32
  warning. A product with accounts names it in its `option.ts`, `option.setAgentAccess(SignedIn)`, taking the same
33
33
  guard classes every endpoint takes (an array is ANDed, `null` clears what a library set); without one the chat
34
34
  cannot spend the LLM key. **The guard decides who, not what** — the browser writes the instructions, tools and
35
- transcript — so `option.setAgentRequestPolicy((request, { account, ip }) => request)` sees each turn after the
36
- guard, before the quota and the model (tool names as the page published them), and returns what is sent, or
37
- throws an `Err` (`agent.error.requestRefused`) to refuse it. With no policy set, a turn past
35
+ transcript — so `option.setAgentRequestPolicy((request, { id, headers, account, ip }) => request)` sees each turn
36
+ after the guard, before the quota and the model (tool names as the page published them), and returns what is
37
+ sent, or throws an `Err` (`agent.error.requestRefused`) to refuse it. `setAgentQuota` and `setAgentUsage` get that
38
+ same `turn`, and usage comes once per turn the quota passed, `failed` and `aborted` ones too. With no policy set, a turn past
38
39
  `AgentRelayPolicy.defaultLimits` (5,000 messages, 512 tools, 256 context entries, 8M characters, 64 MiB of
39
40
  attachments) is refused with 413; a policy of the app's own keeps them by returning
40
41
  `AgentRelayPolicy.capped(request, limits)`, and `(request) => request` lifts them. An error that is not an `Err`
@@ -237,6 +237,8 @@ method?: HttpMutationMethod;
237
237
  fileUpload?: boolean;
238
238
  /** `false` keeps it out of the MCP catalogue (default `true`); curation, not authorization — HTTP still serves it. */
239
239
  mcp?: boolean;
240
+ /** Overrides what the key implies for a `mutation`'s MCP `destructiveHint`: `true` for one no verb gives away, such as `archiveOrder`, `false` for a `drop…` that loses nothing. */
241
+ destructive?: boolean;
240
242
  /** The errors this endpoint throws on purpose, by status. */
241
243
  errors?: EndpointErrors;
242
244
  /** A slow subscriber of a `pubsub(Binary)`: `"coalesce"` (default) keeps only the newest frame per room, `"queue"` delivers every frame and grows the send buffer with the slowest subscriber. */
@@ -47,7 +47,7 @@ and infrastructure. A workspace is Bun-first: `apps/<app>` holds pages, domain m
47
47
  contract. Path rules name their checks the same way.
48
48
 
49
49
  - Throw `new Err("<module>.error.<key>")` with the key in the module dictionary's `.error({})`; never a raw `Error`
50
- (`no-throw-raw-error`) [app].
50
+ (`no-throw-raw-error`) and never the untyped `Err` of `akanjs/common` (`no-import-common-err`) [app].
51
51
  - A third-party package reaches `page/**`, a barrel or a module file only through a lib re-export
52
52
  (`no-import-external-library`) [app].
53
53
  - Colors only from the semantic vocabulary (`bg-primary`, `text-foreground/70`) — no palette, arbitrary, daisyUI or
@@ -17,6 +17,9 @@ each plugin's header and diagnostic carry its full reasoning.
17
17
  stored loses the key and status too (a warning for now). Exempt: tests, `*.constant.ts`, a root `native/` folder
18
18
  (plugins throw `AkanNativeError`), `script/migration/**` (an operator reads its message), and `common/**` / `env/**`,
19
19
  which have no legal `Err` import — keep throwing code out of them.
20
+ - **Never import `Err` from `akanjs/common`** or `akanjs/common/err` (`no-import-common-err`). That class takes any
21
+ string, so a mistyped key compiles; the `Err` from `"../dict"` or a client entrypoint is the same class, typed with
22
+ the dictionary's keys. `import type` stays legal, to annotate a caught `Err`. Exempt: tests.
20
23
  - **Never import a third-party package** (`no-import-external-library`) from `page/**`, any barrel, a module logic file
21
24
  (`*.{constant,dictionary,document,service,signal,store}.ts`) or module component
22
25
  (`*.{Template,Unit,Util,View,Zone}.tsx`) — re-export it through a lib first (one-line shims in a lib's `common/`,
@@ -43,6 +43,11 @@ export default page()
43
43
  - `.render()` gets the declared args flat and typed (no `PageProps`, no `loader=` prop). Order: `usePage()`, fetch,
44
44
  return; auth is the chain's `.guard()`, which runs before anything renders. Hand `fetch.init*` / `view*` / `edit*` fields to sections unawaited; await only what the shell reads
45
45
  (title, redirect, link id) in one `Promise.all`.
46
+ - **A field's refusal belongs to its `Load.*`**, which draws a notice in its place while the page answers 200. So a
47
+ field reaches only a `Load.*`, directly or through a Zone. Awaited in a component below the page, rendered as a
48
+ child or `use()`-d outside `Load.*`, a refused field takes its whole route level, which draws a retryable notice
49
+ under the layouts above it, as any server error after the first byte does. Await the handle
50
+ (`await fetch.initX()`) instead, so a refusal takes the layout's `.error()`.
46
51
  - **A route never writes while it renders**: a `fetch.<mutation>()` in a stage or a component it renders throws
47
52
  `base.error.mutationInRender`, since opening a link would perform it. Send it from a user action;
48
53
  `{ duringRender: true }` only for a write harmless to repeat and safe for anyone to trigger (`ssrRule`).
@@ -0,0 +1,140 @@
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
+ | `artifactMissing` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
20
+ | `authRequired` | 401 | `McpAuthRequiredError` | no | yes | `server/mcp/McpDispatcher.ts` |
21
+ | `badGateway` | 502 | `ImageOptimizerError` | no | yes | `server/imageOptimizerError.ts` |
22
+ | `badRequest` | 400 | `Exception.BadRequest` | yes | no | `signal/exception.ts` |
23
+ | `badRequest` | 400 | `ImageOptimizerError` | no | yes | `server/imageOptimizerError.ts` |
24
+ | `baseMismatch` | 500 | `SignalDeclarationError` | no | yes | `signal/signalDeclarationError.ts` |
25
+ | `bytesThroughAny` | 500 | `SignalContractError` | no | yes | `signal/signalContractError.ts` |
26
+ | `clientComponentOnServer` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
27
+ | `compressorNotInitialized` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
28
+ | `conflict` | 409 | `Exception.Conflict` | yes | no | `signal/exception.ts` |
29
+ | `consoleDisabled` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
30
+ | `desktopAppRequired` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
31
+ | `documentNotFound` | 404 | `NoDocumentError` | yes | no | `document/noDocumentError.ts` |
32
+ | `failed` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
33
+ | `fileGrantRefused` | 403 | `AkanError` | no | yes | `base/akanError.ts` |
34
+ | `fileGrantUnavailable` | 503 | `AkanError` | no | yes | `base/akanError.ts` |
35
+ | `forbidden` | 403 | `Exception.Forbidden` | yes | no | `signal/exception.ts` |
36
+ | `gatewayTimeout` | 504 | `Exception` | yes | no | `signal/exception.ts` |
37
+ | `handlerAlreadySet` | 500 | `SignalDeclarationError` | no | yes | `signal/signalDeclarationError.ts` |
38
+ | `inlineFailed` | 502 | `PromptError` | no | yes | `signal/mcp/promptError.ts` |
39
+ | `insightTimeout` | 504 | `InsightQueryError` | yes | yes | `service/insightQueryError.ts` |
40
+ | `insightUnavailable` | 500 | `InsightQueryError` | no | yes | `service/insightQueryError.ts` |
41
+ | `internalError` | 500 | `Exception.Error` | yes | no | `signal/exception.ts` |
42
+ | `invalidArgType` | 500 | `SignalDeclarationError` | no | yes | `signal/signalDeclarationError.ts` |
43
+ | `invalidArgument` | 400 | `McpArgumentError` | no | yes | `server/mcp/McpExecutionContext.ts` |
44
+ | `invalidArtifact` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
45
+ | `invalidCascade` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
46
+ | `invalidConfig` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
47
+ | `invalidDocument` | 500 | `DocumentStoreError` | no | yes | `service/documentStoreError.ts` |
48
+ | `invalidErrors` | 500 | `SignalDeclarationError` | no | yes | `signal/signalDeclarationError.ts` |
49
+ | `invalidFileGrant` | 400 | `AkanError` | no | yes | `base/akanError.ts` |
50
+ | `invalidFilter` | 400 | `FilterQueryError` | no | yes | `document/filterMeta.ts` |
51
+ | `invalidIdentity` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
52
+ | `invalidInject` | 500 | `InjectError` | no | yes | `service/injectError.ts` |
53
+ | `invalidInput` | 400 | `InvalidInputError` | no | yes | `constant/invalidInputError.ts` |
54
+ | `invalidInsightQuery` | 400 | `InsightQueryError` | yes | yes | `service/insightQueryError.ts` |
55
+ | `invalidKey` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
56
+ | `invalidMessage` | 400 | `AkanError` | no | yes | `base/akanError.ts` |
57
+ | `invalidParam` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
58
+ | `invalidPrompt` | 500 | `PromptError` | no | yes | `signal/mcp/promptError.ts` |
59
+ | `invalidQuery` | 500 | `DocumentStoreError` | no | yes | `service/documentStoreError.ts` |
60
+ | `invalidRoute` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
61
+ | `invalidRscResponse` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
62
+ | `invalidSchema` | 500 | `DocumentStoreError` | no | yes | `service/documentStoreError.ts` |
63
+ | `invalidSignal` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
64
+ | `invalidStorageKey` | 400 | `AkanError` | no | yes | `base/akanError.ts` |
65
+ | `ipcRequired` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
66
+ | `liveAlreadySet` | 500 | `SignalDeclarationError` | no | yes | `signal/signalDeclarationError.ts` |
67
+ | `livePaused` | 409 | `AkanError` | no | yes | `base/akanError.ts` |
68
+ | `liveRoomTaken` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
69
+ | `locked` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
70
+ | `logControlUnavailable` | 503 | `LogControlUnavailableError` | no | yes | `server/logging/logTailClient.ts` |
71
+ | `missingFilterQuery` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
72
+ | `missingInput` | 400 | `InvalidInputError` | no | yes | `constant/invalidInputError.ts` |
73
+ | `missingModel` | 500 | `SignalDeclarationError` | no | yes | `signal/signalDeclarationError.ts` |
74
+ | `missingSlice` | 500 | `SignalDeclarationError` | no | yes | `signal/signalDeclarationError.ts` |
75
+ | `noHandler` | 500 | `SignalContractError` | no | yes | `signal/signalContractError.ts` |
76
+ | `notApplied` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
77
+ | `notFound` | 404 | `Exception.NotFound` | yes | no | `signal/exception.ts` |
78
+ | `notFound` | 404 | `ImageOptimizerError` | no | yes | `server/imageOptimizerError.ts` |
79
+ | `notFound` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
80
+ | `notInitialized` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
81
+ | `notInitialized` | 500 | `InjectError` | no | yes | `service/injectError.ts` |
82
+ | `notRegistered` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
83
+ | `notRegistered` | 500 | `InjectError` | no | yes | `service/injectError.ts` |
84
+ | `notRegistered` | 500 | `SignalContractError` | no | yes | `signal/signalContractError.ts` |
85
+ | `nullableLastArg` | 500 | `SignalDeclarationError` | no | yes | `signal/signalDeclarationError.ts` |
86
+ | `payloadTooLarge` | 413 | `AkanError` | no | yes | `base/akanError.ts` |
87
+ | `payloadTooLarge` | 413 | `ImageOptimizerError` | no | yes | `server/imageOptimizerError.ts` |
88
+ | `planChanged` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
89
+ | `redisUriMissing` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
90
+ | `routeConflict` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
91
+ | `routeNotFound` | 404 | `AkanError` | no | yes | `base/akanError.ts` |
92
+ | `routerNotReady` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
93
+ | `rpcDisposed` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
94
+ | `searchMisconfigured` | 500 | `DocumentStoreError` | no | yes | `service/documentStoreError.ts` |
95
+ | `searchUnavailable` | 500 | `DocumentStoreError` | no | yes | `service/documentStoreError.ts` |
96
+ | `secretRefused` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
97
+ | `secretStoreUnavailable` | 503 | `AkanError` | no | yes | `base/akanError.ts` |
98
+ | `serviceUnavailable` | 503 | `ImageOptimizerError` | no | yes | `server/imageOptimizerError.ts` |
99
+ | `storageNotShared` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
100
+ | `tableMissing` | 500 | `DocumentStoreError` | no | yes | `service/documentStoreError.ts` |
101
+ | `tooManyRequests` | 429 | `Exception` | yes | no | `signal/exception.ts` |
102
+ | `transferUnsupported` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
103
+ | `unauthorized` | 401 | `Exception.Unauthorized` | yes | no | `signal/exception.ts` |
104
+ | `undefinedReturn` | 500 | `SignalContractError` | no | yes | `signal/signalContractError.ts` |
105
+ | `unguardedEndpoint` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
106
+ | `unmaskedResource` | 500 | `PromptError` | no | yes | `signal/mcp/promptError.ts` |
107
+ | `unroutableLiveQuery` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
108
+ | `unstorableValue` | 400 | `DocumentStoreError` | no | yes | `service/documentStoreError.ts` |
109
+ | `unsupportedMediaType` | 415 | `Exception.UnsupportedMediaType` | yes | no | `signal/exception.ts` |
110
+ | `usage` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
111
+ | `verifyFailed` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
112
+ | `wrongTransport` | 500 | `SignalContractError` | no | yes | `signal/signalContractError.ts` |
113
+ | set when thrown | set when thrown | `Err` | yes | yes | `common/err.ts` |
114
+ | set when thrown | set when thrown | `Err.BadRequest` | yes | yes | `common/err.ts` |
115
+ | set when thrown | set when thrown | `Err.Conflict` | yes | yes | `common/err.ts` |
116
+ | set when thrown | set when thrown | `Err.Forbidden` | yes | yes | `common/err.ts` |
117
+ | set when thrown | set when thrown | `Err.NotFound` | yes | yes | `common/err.ts` |
118
+ | set when thrown | set when thrown | `Err.Unauthorized` | yes | yes | `common/err.ts` |
119
+
120
+ ## Codes by status
121
+
122
+ An error coded by its status, such as an `Exception`, takes its code from `AkanError.codeOfStatus`:
123
+
124
+ | Status | Code | Reason |
125
+ |---|---|---|
126
+ | 400 | `badRequest` | Bad Request |
127
+ | 401 | `unauthorized` | Unauthorized |
128
+ | 403 | `forbidden` | Forbidden |
129
+ | 404 | `notFound` | Not Found |
130
+ | 409 | `conflict` | Conflict |
131
+ | 413 | `payloadTooLarge` | Payload Too Large |
132
+ | 415 | `unsupportedMediaType` | Unsupported Media Type |
133
+ | 429 | `tooManyRequests` | Too Many Requests |
134
+ | 500 | `internalError` | Internal Server Error |
135
+ | 502 | `badGateway` | Bad Gateway |
136
+ | 503 | `serviceUnavailable` | Service Unavailable |
137
+ | 504 | `gatewayTimeout` | Gateway Timeout |
138
+
139
+ Any other status is coded `http<status>`, with the reason `Internal Server Error` from 500 and `Request Failed`
140
+ 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);
@@ -205,8 +205,11 @@ export default page()
205
205
  alike: the caller reads `You are not permitted to perform this action.`, because either sentence names your
206
206
  authorization structure to the one caller barred from it. A domain `Err` at any other status resolves through
207
207
  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.
208
+ - The `readOnly` / `destructive` / `idempotent` hints a client renders are derived from the endpoint type and key.
209
+ A mutation named `remove`, `delete`, `purge`, `destroy`, `erase`, `wipe`, `drop`, `cancel`, `bulkRemove` or
210
+ `bulkDelete` is destructive; `destructive: true` or `false` on the endpoint overrides that, for an `archiveOrder`
211
+ no verb gives away. Clients are told to distrust hints; they are never a gate. `agentService.loop` does read this
212
+ one: it refuses a destructive tool unless `approve` allows it.
210
213
  - **`AKAN_MCP_READONLY=true` is the read-only-deployment valve, not the exposure switch.** It drops every mutation
211
214
  whatever it declared, and reports each one in the boot log like any other refusal. It also drops each `.prompt()`
212
215
  page's text tool, whose run renders the whole page; the prompts, the `.app()` tools and their views stay.
@@ -250,6 +253,15 @@ export default page()
250
253
  `base.error.documentNotFound`, so a tool reads its dictionary sentence (`The requested item does not exist.`) and an
251
254
  MCP App view receives that `Err`; a prompt whose page reads it is `No screen exists for these arguments.`
252
255
  Only a real failure logs a stack; an agent can drive the rest at will.
256
+ - **Every failed call carries a code** beside the text, which reads as it always did. A tool error holds
257
+ `_meta["akanjs/failure"]: { code, statusCode }` — in `_meta`, because a client checks `structuredContent` against
258
+ the tool's `outputSchema` even on a failure — and a JSON-RPC error holds `data.code`, which tells apart what
259
+ `-32602` files together: `unknownTool`, `invalidArgument`, `unknownPrompt`, `unknownResource` and a screen's
260
+ refusal, beside `tooManyRequests` and `internalError`. The code is the one an HTTP caller gets: a domain `Err`'s
261
+ dictionary key (what `Err.is` matches), else the `AkanError`'s own code; a guard's 401 or 403 by its status alone
262
+ (`unauthorized`, `forbidden`), since a guard's own code names its rule as its message does; a crash, or a 5xx whose
263
+ code this server did not name, by its status (`internalError`). A code is a bounded key or camelCase token, never
264
+ prose. No host hands `_meta` to the model, so what the model must act on belongs in the dictionary sentence.
253
265
  - **Three revisions are spoken**: the modern `2026-07-28` and the legacy `2025-11-25` / `2025-06-18`, which are
254
266
  wire-identical over the POST-only surface this implements — a client whose proposal is not listed is told to
255
267
  disconnect. An unknown proposal is answered at whichever end of that list it is closer to, and an unimplemented
@@ -486,6 +498,64 @@ frames down included, and is a no-op when nobody is streaming — so the same co
486
498
  websocket, and in tests. `McpProgress.streaming` says whether anyone is reading, for a report whose message
487
499
  costs something to assemble.
488
500
 
501
+ ## Calling The Catalogue In-Process — `AgentToolsRole`
502
+
503
+ A server-side agent loop or a queue job reaches the same catalogue with no token and no loopback request:
504
+ `plug(AgentToolsRole)` in a service, then `listAs(account, { allow })` for the tools a model is offered and
505
+ `callAs(account, { id, name, args })` to run one. Everything above still holds — `mcp: false`, the exclusions,
506
+ `readOnly`, `Person`, the account guards, masking and the refusal text — and the call's `origin` is `"mcp"`, so
507
+ `isAgentCall` and `.with(AgentCall)` treat it as an agent's. `allow` only narrows. It is built from the DI
508
+ registry, so a batch server, which mounts no `/mcp`, has it too; the per-caller `/mcp` budget does not apply, an
509
+ endpoint's own `rateLimit` does. A tool's failure never throws: it comes back as the result's `error` and `code`.
510
+ An adaptor may plug the role too. Neither method works before the server has built its endpoints, so a call from an
511
+ `onInit` throws `InjectError` `notInitialized`; call from a request, a job or a schedule. A page's `page().app()` tools
512
+ are left out: `/mcp` `tools/list` shows them, `listAs` does not, and `callAs` answers `Unknown tool`.
513
+
514
+ - **The account is trusted as given.** It is put on the call after the middleware chain, so pass one the server
515
+ resolved, never client input, and resolve a stored one again before reusing it: a revoked session is not noticed.
516
+ Its `machine` field is removed, since only a verified machine token may set one.
517
+ - **`headers` are forwarded without `authorization`, `cookie` and `origin`**; `ip` is what `getClientIp()` and an
518
+ ip-scoped `rateLimit` read, unknown by default.
519
+
520
+ ## A Server Agent Loop — `agentService.loop`
521
+
522
+ `this.agentService.loop(request)` runs a model over that catalogue until it answers, with no browser — a queued
523
+ task, a scheduled run, a reply to a mention. It is an async iterable of `text`, `toolCall`, `toolResult`, `usage`,
524
+ `compacted` and `awaiting` events that ends in exactly one `done { stop }` or `error`, and it waits for the consumer
525
+ at every event.
526
+
527
+ - **Who it acts as.** `account` is a snapshot the server resolved; `principal` is a stored id that
528
+ `option.setAgentAccountResolver((principal) => account | null)` resolves at the start and before every round, so
529
+ a revoked one ends the run as `"unauthorized"`, as does a missing or falsy `account`: there is no anonymous run.
530
+ Neither is ever client input. The model is offered `allow` ∩ what
531
+ the account sees on `/mcp`, and a call to a name that round did not list is answered as an unknown tool, neither
532
+ asked about nor run. A request with no `allow` array is an `error`.
533
+ - **Writes after untrusted input.** `untrusted(result)` marks a result third parties wrote, and every later call
534
+ reaches `approve(call, { tainted, tool })` with `tainted` set. A batch is judged before it runs, since the model
535
+ wrote it before reading its results. Without `approve`, a `needsConfirm` tool — on this catalogue, a mutation
536
+ with the `destructive` hint above — is refused, and so is every write once tainted. `"defer"` holds the whole batch, emits
537
+ `awaiting` and ends the run as `"awaiting"`.
538
+ - **Resuming.** Store each message `onMessage` hands over — it is awaited, and a retried run may hand one over twice —
539
+ and call `loop` again with them. Trailing calls nothing answered go to `approve` again before any model call, and
540
+ the taint is rebuilt from the `tainted` marks on stored messages and by re-applying `untrusted`, which sees a result
541
+ whole during the run and clipped on a resume. Store every message whole, marks included. `compacted` says the first
542
+ `replaced` messages are now `summary`; its `tainted` marker stands in for the results it replaced, and a summary
543
+ with no marker counts as tainted to a run with `untrusted`. A batch's results
544
+ reach `onMessage` even when the consumer stops reading or a later call throws, so a resume runs only calls that
545
+ never started.
546
+ - **Metering.** Each model call, compactions included, is its own turn for the request policy, the quota and the
547
+ usage hook. It gets a fresh `id`, `loop { id, round }`, a copy of the request's `meta` — server-set, so it may key
548
+ billing — empty headers and no ip. The relay's default size caps skip loop rounds; a refused quota ends the run as
549
+ `"quota"`.
550
+ - **Limits.** `maxRounds` (12), `budget { tokens, toolCalls, wallMs }` (`"budget"`), `signal` (`"aborted"`) and a
551
+ provider cut (`"length"`). A limit that is not a valid number is an `error` before any model call. `wallMs` and
552
+ `signal` also end a run waiting on a tool or on `approve`. `callAs` cannot cancel a call, so the run stops waiting
553
+ and answers it with an error saying it may still finish; a resume does not run it again, and the endpoint runs on
554
+ with its outcome unreported. There is no preamble unless `preamble` gives one; with no `instructions` either, a
555
+ short neutral prompt stands in, as each adaptor's own fallback is about a screen. `compact { at, keep }` summarizes
556
+ the head, and a tool result is capped at 20,000 characters as the browser caps it. Its calls carry no ip, so an
557
+ ip-scoped `rateLimit` counts them under one unknown address.
558
+
489
559
  ## Rolling MCP Out To An App
490
560
 
491
561
  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
 
@@ -536,6 +536,10 @@ page API is
536
536
  `akanjs/client/native/<id>` (`akanjs/client/native/window`, `…/screen`, `…/global-shortcut`), imported in a `webkit/`
537
537
  hook; `volume` and `filePicker` also come from `akanjs/client/native` itself. A capability the shell
538
538
  lacks is added there: an app's own plugin runs as Bun code in the plugin host and cannot add a native shell op.
539
+ `isNativeApp()`, `isNativeShell()`, `nativePlatform()` and `desktopPlatform()` come from `akanjs/client`, which starts
540
+ the native runtime only inside a shell. A static import of `akanjs/client/native` loads `@akanjs/native/core` on every
541
+ 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
542
+ use behind the check: `if (isNativeApp()) await (await import("akanjs/client/native/push")).push.register()`.
539
543
 
540
544
  **A plugin the app or lib owns lives in `native/<id>/`**, the folder named after the plugin id: `native-plugin.json`
541
545
  beside its page API (`src/index.ts`, `definePlugin` from `akanjs/client/native`), its desktop part (`src/desktop.ts`,
@@ -555,7 +559,7 @@ uses `getCookie` / `setCookie` / `removeCookie`, `storage`, and `secretStorage`
555
559
  names — pass `sameSite: "none"` only for a cookie a cross-site POST must carry back. `getCookie` reads a name sent
556
560
  twice as unset, since a sibling subdomain can plant a second copy; server code reads `cookieJar()` from
557
561
  `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/native`, which is where the app side goes
562
+ stay in a `webkit/` hook that branches on `isNativeApp()` from `akanjs/client`, which is where the app side goes
559
563
  too (`no-web-only-api-outside-webkit`, a warning): `navigator.share` / `canShare` (Android's WebView has none),
560
564
  `navigator.serviceWorker` and `Notification.requestPermission` / `.permission` (no app page has them),
561
565
  `navigator.geolocation` (use `useGeoLocation` from `akanjs/webkit`) and `navigator.vibrate` (iOS has none; use
@@ -66,6 +66,11 @@ HTTP verb a mutation is mounted under. `conventions` carries the invariants —
66
66
  - **A subscribe the client leaves before it finishes joins nothing.** When an `unsubscribe` for the room, or the
67
67
  socket's close, arrives while the subscribe is still running, the subscribe answers `subscribe: false` and runs its
68
68
  `unsubscribe` cleanup (and its `disconnect` one when the socket closed) instead of joining the room.
69
+ - **A send from the browser drops the reads it may have made stale.** A mutation, an upload or a `message` sent
70
+ through `fetch` ends the sharing of queries already in flight and drops the pages a `Link` prefetched, so the next
71
+ read asks again; only this tab's own sends count. A send that changes nothing anyone reads back — typing status, a
72
+ cursor move — passes `{ keepsReads: true }` after its arguments (`fetch.typing(chatId, { keepsReads: true })`), or
73
+ a chatty endpoint keeps every prefetch from surviving. A read receipt changes an unread count and passes nothing.
69
74
 
70
75
  ## Writing A Guard
71
76
 
@@ -3,13 +3,14 @@ import {
3
3
  HmrWatcher,
4
4
  WatchRootResolver,
5
5
  ApplicationBuildReporter
6
- } from "./index-p6hjwt2d.js";
6
+ } from "./index-41mfhgq0.js";
7
7
  import {
8
8
  CodegenLock,
9
9
  WorkspaceExecutor,
10
10
  AppExecutor
11
- } from "./index-sr5da35e.js";
11
+ } from "./index-sq9d0jhj.js";
12
12
  import"./index-bns3wcpc.js";
13
+ import"./index-j4yvgfhr.js";
13
14
  import {
14
15
  GraphClientEntryDiscovery,
15
16
  RouteClientBuilder,
@@ -19,20 +20,20 @@ import {
19
20
  DevChangePlanner,
20
21
  DevGeneratedIndexSync,
21
22
  SsrDevBundler
22
- } from "./index-7xdpww43.js";
23
+ } from "./index-rdx8cyv2.js";
23
24
  import {
24
25
  ServerGraphFile
25
- } from "./index-1q1cjn8s.js";
26
- import"./index-7y5yghjg.js";
26
+ } from "./index-9xh4zvw3.js";
27
+ import"./index-nd39rssn.js";
27
28
  import {
28
29
  FrameworkGraph
29
- } from "./index-abgh0jve.js";
30
+ } from "./index-grt0e6kk.js";
30
31
  import {
31
32
  GitRevision
32
33
  } from "./index-ygdbn9jn.js";
33
34
  import {
34
35
  WorkspaceGraph
35
- } from "./index-w639tvkd.js";
36
+ } from "./index-xgqz3kak.js";
36
37
  import {
37
38
  prepareDevWatchBatch
38
39
  } from "./index-a5vmm6x4.js";