@akanjs/cli 3.3.0-rc.6 → 3.3.0-rc.8

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 (90) hide show
  1. package/.build-stamp +2 -2
  2. package/{CodeAgent-277k8f4q.js → CodeAgent-cqbf9gsv.js} +2 -2
  3. package/{CodeAgentRpcHost-6dzfkvsc.js → CodeAgentRpcHost-pwps2d67.js} +1 -1
  4. package/{CodeTui-rk7zw5mx.js → CodeTui-ehdr4hgw.js} +43 -3
  5. package/TunnelShare-0p4dy89e.js +16 -0
  6. package/{agent.command-m6scv9dh.js → agent.command-x55ncdjm.js} +17 -17
  7. package/akanCode.js +4 -4
  8. package/{appExecutor-qt1nm242.js → appExecutor-1ctzymwa.js} +3 -3
  9. package/{application.command-rdjx4678.js → application.command-xpntxnh8.js} +14 -14
  10. package/{applicationBuildRunner-6jkbfzmm.js → applicationBuildRunner-19c76791.js} +9 -9
  11. package/buildBatch.proc.js +10 -11
  12. package/{cloud.command-4kw1vbs0.js → cloud.command-p3ybjes7.js} +18 -18
  13. package/cloud.script-0dsyd10v.js +30 -0
  14. package/{code.command-87btt2a0.js → code.command-m6skj1kj.js} +31 -16
  15. package/{context.command-bbq2tdj4.js → context.command-3c3nv0d6.js} +18 -18
  16. package/context.runner-yyp7a112.js +32 -0
  17. package/{csrArtifactBuilder-wrqsfn1s.js → csrArtifactBuilder-mdh9ykn2.js} +2 -2
  18. package/{guideline.command-v2daz21k.js → guideline.command-725fq5p0.js} +6 -6
  19. package/guidelines/agentRule/agentRule.instruction.md +46 -7
  20. package/guidelines/conventions/rules/config.md +2 -1
  21. package/guidelines/errorCodes/errorCodes.instruction.md +4 -0
  22. package/guidelines/mcpRule/mcpRule.instruction.md +11 -4
  23. package/guidelines/runtimeRule/runtimeRule.instruction.md +68 -4
  24. package/incrementalBuilder.proc.js +8 -8
  25. package/{index-5ptvewmq.js → index-22bwg8hy.js} +1 -1
  26. package/{index-9f3reh2y.js → index-2v38x3ad.js} +12 -1
  27. package/{index-fqhr7j56.js → index-3a3vy2xy.js} +8 -8
  28. package/{index-eap5y4w5.js → index-3mj5trqc.js} +2 -2
  29. package/{index-zfmc4380.js → index-3r1crbct.js} +1 -1
  30. package/{index-sxnszzh7.js → index-3zkhg65e.js} +11 -11
  31. package/{index-m4s4tzjr.js → index-4r8dgm4x.js} +3 -3
  32. package/{index-94h6dxc3.js → index-4yvtqcme.js} +7 -7
  33. package/{index-vq0y1vr4.js → index-5ahe641t.js} +8 -8
  34. package/{index-w18qdjyf.js → index-8bta5pnr.js} +2 -2
  35. package/{index-cfzqdsam.js → index-9a9t77hz.js} +2 -2
  36. package/{index-bjg9thz8.js → index-9gjcbp2g.js} +1 -1
  37. package/{index-k29kg5c1.js → index-a4gcdffy.js} +485 -50
  38. package/{index-zas8gm0a.js → index-cbm9gzgx.js} +5 -5
  39. package/{index-bwhja4dj.js → index-ckcc9ab3.js} +8 -8
  40. package/{index-2t7jnfg5.js → index-crd99zqs.js} +1 -1
  41. package/{index-ewp82tjf.js → index-f4jydw2x.js} +1 -1
  42. package/{index-0vv0a5h8.js → index-fagjtk6m.js} +2 -2
  43. package/{index-8a4mnn65.js → index-fjqapyex.js} +31 -5
  44. package/{index-ghs8gtvp.js → index-h8w1n11r.js} +4 -4
  45. package/{index-999e5kp4.js → index-hxg6ctk2.js} +5 -5
  46. package/{index-0vtpxfx6.js → index-j2wq064m.js} +5 -5
  47. package/{index-2ktpwjgf.js → index-kbnvyhy4.js} +3 -3
  48. package/{index-jzwdwse0.js → index-m303nhv6.js} +6 -6
  49. package/{index-hfqc5n8e.js → index-nmdmkjt2.js} +4 -4
  50. package/{index-vznyyaf8.js → index-nnmw56fz.js} +5 -5
  51. package/{index-nd7tzzd9.js → index-pr9nypg7.js} +2 -2
  52. package/{index-4gxaerb7.js → index-pyjkbg8e.js} +2 -2
  53. package/{index-g7hm77j6.js → index-q63nbpv7.js} +3 -3
  54. package/{index-9jm7t0h5.js → index-qecrqpt6.js} +4 -21
  55. package/{index-6yefp97x.js → index-rdcgz02t.js} +4 -4
  56. package/{index-zx3bv21b.js → index-rt7q20sj.js} +1 -1
  57. package/{index-bsew0a12.js → index-se7n78fh.js} +1 -1
  58. package/{index-s4nvxpzm.js → index-sxbsrndq.js} +1 -1
  59. package/{index-nd69pk6t.js → index-t23dgyaf.js} +7 -7
  60. package/{index-609zbjve.js → index-v16gj2as.js} +83 -63
  61. package/{index-c1t41tk8.js → index-vnk1qwgr.js} +4 -4
  62. package/{index-8zxkjybr.js → index-wkwe91sn.js} +27 -17
  63. package/{index-3h0zqg41.js → index-wxqp1amd.js} +7 -7
  64. package/{index-c67vjafa.js → index-yey1envc.js} +1 -1
  65. package/index.js +27 -27
  66. package/{libExecutor-p21kkayq.js → libExecutor-n8hpm8s7.js} +2 -2
  67. package/{library.command-m4gw18qq.js → library.command-8abb26pg.js} +7 -7
  68. package/{localRegistry.command-edtbn4cy.js → localRegistry.command-sa211m1z.js} +17 -17
  69. package/{module.command-9vfdxapr.js → module.command-z3cwjf0p.js} +9 -9
  70. package/{package.command-rt4y8xaf.js → package.command-akynhtee.js} +8 -8
  71. package/package.json +2 -2
  72. package/{page.command-4zc20rnv.js → page.command-3fpdavk9.js} +7 -7
  73. package/{pipeline.command-4ekd9xgb.js → pipeline.command-ca95n8rd.js} +6 -6
  74. package/{pkgExecutor-mh903rz9.js → pkgExecutor-a73q41vx.js} +2 -2
  75. package/{primitive.command-5g3xe4mf.js → primitive.command-xwe9ggnf.js} +10 -10
  76. package/{projectTypecheck-bz6smek9.js → projectTypecheck-7g542ymk.js} +1 -1
  77. package/{quality.command-zf8dyc9w.js → quality.command-7wz7y8z1.js} +8 -8
  78. package/{repair.command-sx0eyq4w.js → repair.command-dej1qtfq.js} +9 -9
  79. package/{scalar.command-4bvzmbbh.js → scalar.command-z9qfxnvm.js} +8 -8
  80. package/skills/akan-agent/SKILL.md +8 -1
  81. package/skills/akan-code/SKILL.md +38 -3
  82. package/{subspace.command-tg85k9ry.js → subspace.command-9wekm4gn.js} +10 -10
  83. package/templates/localDev/docker-compose.yaml.template +2 -2
  84. package/{tunnel.command-t629kcm0.js → tunnel.command-cxc4h3j8.js} +9 -9
  85. package/{verify.command-837mthft.js → verify.command-j0w9dr5c.js} +14 -14
  86. package/{workflow.command-42p9g0w8.js → workflow.command-yt4sz04b.js} +14 -14
  87. package/{workspace.command-12egv8xq.js → workspace.command-8mp4mcp2.js} +31 -31
  88. package/TunnelShare-8pejh5jk.js +0 -16
  89. package/cloud.script-af2js02g.js +0 -30
  90. package/context.runner-ma47t32x.js +0 -32
@@ -2,35 +2,35 @@
2
2
  import {
3
3
  Workspace,
4
4
  command
5
- } from "./index-vznyyaf8.js";
5
+ } from "./index-nnmw56fz.js";
6
6
  import"./index-j4yvgfhr.js";
7
- import"./index-609zbjve.js";
7
+ import"./index-v16gj2as.js";
8
8
  import"./index-zyjztrvc.js";
9
- import"./index-cfzqdsam.js";
10
- import"./index-c67vjafa.js";
11
- import"./index-2t7jnfg5.js";
12
- import"./index-g7hm77j6.js";
9
+ import"./index-9a9t77hz.js";
10
+ import"./index-yey1envc.js";
11
+ import"./index-crd99zqs.js";
12
+ import"./index-q63nbpv7.js";
13
13
  import"./index-trffs83s.js";
14
- import"./index-ghs8gtvp.js";
14
+ import"./index-h8w1n11r.js";
15
15
  import"./index-1p81ecbz.js";
16
- import"./index-vq0y1vr4.js";
16
+ import"./index-5ahe641t.js";
17
17
  import"./index-j3fqs8rc.js";
18
- import"./index-8a4mnn65.js";
19
- import"./index-ewp82tjf.js";
18
+ import"./index-fjqapyex.js";
19
+ import"./index-f4jydw2x.js";
20
20
  import"./index-m9jj544v.js";
21
21
  import"./index-zyb0ebm4.js";
22
22
  import"./index-xs9a3ddt.js";
23
- import"./index-2ktpwjgf.js";
24
- import"./index-bjg9thz8.js";
25
- import"./index-6yefp97x.js";
26
- import"./index-jzwdwse0.js";
27
- import"./index-0vv0a5h8.js";
23
+ import"./index-kbnvyhy4.js";
24
+ import"./index-9gjcbp2g.js";
25
+ import"./index-rdcgz02t.js";
26
+ import"./index-m303nhv6.js";
27
+ import"./index-fagjtk6m.js";
28
28
  import"./index-t4d0ckde.js";
29
- import"./index-fqhr7j56.js";
29
+ import"./index-3a3vy2xy.js";
30
30
  import {
31
31
  ContextScript
32
- } from "./index-c1t41tk8.js";
33
- import"./index-zfmc4380.js";
32
+ } from "./index-vnk1qwgr.js";
33
+ import"./index-3r1crbct.js";
34
34
 
35
35
  // pkgs/@akanjs/cli/context/context.command.ts
36
36
  class ContextCommand extends command("context", [ContextScript], ({ public: target }) => ({
@@ -0,0 +1,32 @@
1
+ // @bun
2
+ import {
3
+ ContextRunner2
4
+ } from "./index-5ahe641t.js";
5
+ import"./index-3a3vy2xy.js";
6
+ import"./index-fagjtk6m.js";
7
+ import"./index-m303nhv6.js";
8
+ import"./index-kbnvyhy4.js";
9
+ import"./index-rdcgz02t.js";
10
+ import"./index-9gjcbp2g.js";
11
+ import"./index-t4d0ckde.js";
12
+ import"./index-h8w1n11r.js";
13
+ import"./index-q63nbpv7.js";
14
+ import"./index-j3fqs8rc.js";
15
+ import"./index-f4jydw2x.js";
16
+ import"./index-fjqapyex.js";
17
+ import"./index-m9jj544v.js";
18
+ import"./index-nnmw56fz.js";
19
+ import"./index-xs9a3ddt.js";
20
+ import"./index-zyb0ebm4.js";
21
+ import"./index-trffs83s.js";
22
+ import"./index-3r1crbct.js";
23
+ import"./index-9a9t77hz.js";
24
+ import"./index-yey1envc.js";
25
+ import"./index-crd99zqs.js";
26
+ import"./index-v16gj2as.js";
27
+ import"./index-j4yvgfhr.js";
28
+ import"./index-1p81ecbz.js";
29
+ import"./index-zyjztrvc.js";
30
+ export {
31
+ ContextRunner2 as ContextRunner
32
+ };
@@ -1,8 +1,8 @@
1
1
  // @bun
2
2
  import {
3
3
  CsrArtifactBuilder2
4
- } from "./index-nd7tzzd9.js";
5
- import"./index-eap5y4w5.js";
4
+ } from "./index-pr9nypg7.js";
5
+ import"./index-3mj5trqc.js";
6
6
  import"./index-zyjztrvc.js";
7
7
  export {
8
8
  CsrArtifactBuilder2 as CsrArtifactBuilder
@@ -2,17 +2,17 @@
2
2
  import {
3
3
  script,
4
4
  command
5
- } from "./index-vznyyaf8.js";
5
+ } from "./index-nnmw56fz.js";
6
6
  import"./index-j4yvgfhr.js";
7
- import"./index-609zbjve.js";
7
+ import"./index-v16gj2as.js";
8
8
  import"./index-zyjztrvc.js";
9
- import"./index-cfzqdsam.js";
10
- import"./index-c67vjafa.js";
11
- import"./index-2t7jnfg5.js";
9
+ import"./index-9a9t77hz.js";
10
+ import"./index-yey1envc.js";
11
+ import"./index-crd99zqs.js";
12
12
  import {
13
13
  Prompter2
14
14
  } from "./index-j3fqs8rc.js";
15
- import"./index-zfmc4380.js";
15
+ import"./index-3r1crbct.js";
16
16
 
17
17
  // pkgs/@akanjs/cli/guideline/guideline.script.ts
18
18
  import { Logger } from "akanjs/common";
@@ -116,6 +116,19 @@ pages declaring one name never clash, and a registry kept outside the surface re
116
116
  blocks, the results ride in a *user* turn, roles must alternate — so two wire turns that map to one role are
117
117
  merged — and `max_tokens` is required. **Both require `model`**: a default would age into a 404, and worse, it
118
118
  would decide the vision claim for the app.
119
+ - **A turn's context is data in a user turn, never part of the system prompt.** Both adaptors send
120
+ `request.context` as a `<turn-context …>` block that ends the turn's last user-role content, after that turn's
121
+ tool results, so the system prompt is the instructions alone and stays the same text from turn to turn. The
122
+ block closes on a delimiter chosen so its content cannot contain it. A block marked `untrusted: true` holds text
123
+ someone other than the developer or the user may have written; it goes in a `<page-content …>` block of its own,
124
+ the one a `readScreen` result arrives in, and the turn counts as an untrusted read. A compaction summary is
125
+ history the model wrote, so it too rides a user turn, in a `<conversation-summary …>` block, never the system
126
+ role. `LlmContext.of(context)` and `LlmContext.summary(text)` (`akanjs/service`) build them. An adaptor of the
127
+ app's own that does not go through `OpenaiDialect.requestBody` appends the context text to its last user-role
128
+ content, maps a `summary` message to a user turn, and writes neither into its system prompt — `systemPrompt`
129
+ returns the instructions alone, so pairing it with hand-built messages sends no context. A dialect added to the
130
+ framework is a class with a static `requestBody`; `llmDialect.conformance.test.ts` finds it by that and fails
131
+ until it passes the same checks.
119
132
  - **`OpenaiLlm` claims vision for its default host and for nothing else.** OpenAI's own endpoint takes image
120
133
  parts, so that is what it answers with no `host` set. A `host` the app named is a gateway the class knows
121
134
  nothing about, and it stays text-only until `option.setLlm({ accepts })` says otherwise — handing bytes to a
@@ -233,7 +246,13 @@ pages declaring one name never clash, and a registry kept outside the surface re
233
246
  pointed at — leaving a live reference showing the result with no record of what it was changed from.
234
247
  `refName`/`refId`/`path` travel so a tool can read the current value when the answer needs it, and
235
248
  `AgentService.referenced` folds the whole lot into the message text in one place, so every provider carries a
236
- reference without either adaptor knowing the word. **The value is masked on the way in and nowhere else**: masking
249
+ reference without either adaptor knowing the word. **A reference is the record's own text, not the user's**: its
250
+ pointer, label, value and note reach the model together in one `<page-content …>` block under a heading, the
251
+ token in the user's words is sent as `@[pointer](mention:pointer)` so the title is in that block only — or as
252
+ `@[ref-1a2b3c4d](mention:ref-1a2b3c4d)`, with the pointer spelled in the block, when the id or path is not a
253
+ token, as a slug is not — and a
254
+ message that carries one counts as a page read, so the first change after a mention asks the user first, as after
255
+ `readScreen`. **The value is masked on the way in and nowhere else**: masking
237
256
  needs the model class, which no wire carries, so the model a host names when it stages the reference is the whole
238
257
  of the decision about what leaves the browser — name the class that actually holds the field, because a `Light`
239
258
  one usually does not. **The ceiling is 20,000 characters per reference**, applied as it is staged and again on
@@ -342,7 +361,8 @@ pages declaring one name never clash, and a registry kept outside the surface re
342
361
  `AgentConfirm.set({ byName })` moves that default app-wide. After a tool marked `taint: "source"` (`readScreen`,
343
362
  `readState`, `viewImage`) returns text the user did not write, the next call that changes something asks once,
344
363
  whatever its own `confirm` says, until the user approves a call; `taint: "exempt"` marks a tool that only moves the
345
- view, and `AgentConfirm.set({ afterScreenRead: false })` turns the rule off. `st.tool("x", { label:
364
+ view, and `AgentConfirm.set({ afterScreenRead: false })` turns the rule off. A message that points at a record
365
+ with an `@` mention counts as such a read, and so does a turn whose context holds a block marked `untrusted`. `st.tool("x", { label:
346
366
  l("ticket.archive") })` gives the action a name a person reads — `Agent.useScreenActions()` hands it to a command
347
367
  palette, and the model never sees it. Reach a store action
348
368
  from the body — `.exec((id) => st.do.removeX(id))` — which is how an agent gets CRUD; `st.do` on its own
@@ -552,7 +572,25 @@ pages declaring one name never clash, and a registry kept outside the surface re
552
572
  `st.useState(name, Type, { set: true }).desc("…").init(initial)` local state, read-only without `set`. Both
553
573
  end in a hook, so a conditional surface withholds the name rather than skipping the chain. A subscribed store key is listed in
554
574
  the state context block by name and pulled with `readState(key)`, masked by the model that key declares — while
555
- a key the screen does not read stays unreadable even when a sibling key of the same store is live. **There is no
575
+ a key the screen does not read stays unreadable even when a sibling key of the same store is live. **The block
576
+ carries a value only when it is an id, an enum member, a number or a boolean**: a string rides inline when it is
577
+ one token of up to 40 letters, digits, `.`, `_` or `-`, of at most three words — a word ends at a separator or
578
+ at a lower-to-upper case change, so `created-at-desc` and `createdAtDesc` pass and four joined words are a
579
+ sentence; more parts pass only as an id's, each hex with a digit or eight characters long, as in a UUID; a run of
580
+ over sixteen letters with no digit never passes — and any other string is listed by key and type alone, because
581
+ free text is whatever the record's author wrote and the model reads that through `readState`, where it arrives as
582
+ page content. The route block follows the same rule for each path segment and path param, up to twelve words of
583
+ each. **A search param rides inline when a store declares its key with `search("key", …)`** and its value is a
584
+ token; of the others at most four ride, key and value both tokens, and the rest are left out, key and value, with
585
+ their count in `searchParamsWithheld`. A page's own typed `search` is read on the server and does not count, so
586
+ declare the params an agent should see in a store. What is left out is named in `withheld` as `pathname`,
587
+ `params` or `searchParams`, and `readState` answers those three whether or not a component subscribes them. The
588
+ screen block applies the rule to a `Load` scope's label, which is its record's title, and to the ids and labels
589
+ of a list scope's `items` — a row whose id is not a token, a slug or a mixed-case random id, is left out — and
590
+ then says to read the scope with `readScreen`. So instructions never say "the query is in the route context";
591
+ they say to read `searchParams`. **Three things still ride whole, because no read returns them**: an
592
+ `Agent.Zone`'s `label` and a value published with `st.expose`, `st.useState` or `useAgentResource`. Publish an
593
+ id, a count or an enum member there, never text a user wrote. **There is no
556
594
  store-level exposure declaration**: a store class says nothing about agents, and `st.use.x({ agent: false })` is
557
595
  how the component that subscribes a value keeps it off the surface. Base-store plumbing does the same at the
558
596
  call site — `st.use.path({ agent: false })`, `st.use.tryJwt({ agent: false })` — so routing and the caller's
@@ -624,8 +662,8 @@ pages declaring one name never clash, and a registry kept outside the surface re
624
662
  have, and the next one asks again — a summarizer that was momentarily unreachable says nothing about whether
625
663
  this transcript can shrink. One that *landed* and shrank nothing does, so that one is not retried until another
626
664
  threshold's worth has been added. On the
627
- wire a summary wears the user's role because the wire has no other, so a provider mapping frames it as a system
628
- message and `/retry` steps over it — replaying it would send the notes back as a question. **While a summary is
665
+ wire a summary wears the user's role because the wire has no other, so a provider mapping frames it as fenced
666
+ history in a user turn and `/retry` steps over it — replaying it would send the notes back as a question. **While a summary is
629
667
  being written the transcript says so** (`session.isCompacting`, distinct from `isRunning`, which an
630
668
  auto-compaction runs inside): that turn takes as long as any other and answers nothing the user asked, so a chat
631
669
  that only shows the running dot reads as a question being ignored.
@@ -664,7 +702,8 @@ pages declaring one name never clash, and a registry kept outside the surface re
664
702
  not with prose), `readScreen` (the rendered DOM as compact text — headings, links, control values, and `(disabled)`
665
703
  on a control or button that has it; the chat's own UI is skipped via `data-agent-ui`, and a password value is never
666
704
  read), `readState(key)` (one masked store key — a key that is unknown or that this screen does not read is refused
667
- *with the keys it can* read, the way `readScreen` names its sections), `highlight(target)`, and `viewImage(src)` (one
705
+ *with the keys it can* read, the way `readScreen` names its sections; the route's own `pathname`, `params` and
706
+ `searchParams` are always readable), `highlight(target)`, and `viewImage(src)` (one
668
707
  `<img>` on screen, redrawn as a JPEG at most 1568px long and attached to the result — `src` must be one this view
669
708
  shows, as `readScreen({ images: true })` printed it, so the agent cannot have the browser fetch an address of its
670
709
  own, and a `data:` one is refused). Declaring a hook tool under one of those names shadows the built-in, so reuse
@@ -760,7 +799,7 @@ pages declaring one name never clash, and a registry kept outside the surface re
760
799
  above the cut and a result this large arrives below it. Clipped rather than dropped, because a model handed a
761
800
  value it cannot see the end of asks a narrower question, where one handed nothing answers from the field names.
762
801
  The cap is a safety rail, not the design: a tool should return what answers the question — an id, a count, the
763
- three fields the agent asked about — and `AgentContext` inlines only small primitives for the same reason.
802
+ three fields the agent asked about — and `AgentContext` inlines only numbers, booleans and one-token strings.
764
803
  - **A slow tool reports its own progress with `AgentProgress.report(message, { done, total })`** from wherever the
765
804
  work is — a store action, an upload loop, an adapter — reached through a module slot rather than a parameter, and
766
805
  a no-op when nobody is rendering it. The chat shows it on that call's row until the row resolves. It is the
@@ -19,7 +19,8 @@ contract: `runtimeRule`.
19
19
  `getWsPrefix()` (`akanjs/base`); never write `/api` or `/ws`, never pass one as a prop.
20
20
  - A single-language app, or URLs fixed from outside (OAuth callbacks, QR codes, mail links, a migrated site), gets
21
21
  unprefixed paths from `i18n: { localePrefix: "as-needed" }` and `<Link>`, never from a raw `<a>`.
22
- - The generated Docker image installs only `ca-certificates` and `tzdata`; add the rest in `docker.preRuns`.
22
+ - The generated Docker image installs only `ca-certificates` and `tzdata` (add the rest in `docker.preRuns`) and
23
+ runs the server as uid 1000 (`bun`) after its root build steps.
23
24
  - An app running in two database modes avoids `q.raw`.
24
25
  - Give every log sink a floor (`Logger.addSink(sink, { minLevel })`), and never log per delivered record in anything
25
26
  that delivers records.
@@ -33,6 +33,7 @@ Generated from the akanjs sources of this release: every code a framework error
33
33
  | `consoleDisabled` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
34
34
  | `databaseLocked` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
35
35
  | `desktopAppRequired` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
36
+ | `directoryNotWritable` | 500 | `DirectoryNotWritableError` | no | yes | `service/predefinedAdaptor/directoryNotWritableError.ts` |
36
37
  | `documentNotFound` | 404 | `NoDocumentError` | yes | no | `document/noDocumentError.ts` |
37
38
  | `duplicateRegistration` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
38
39
  | `failed` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
@@ -60,6 +61,7 @@ Generated from the akanjs sources of this release: every code a framework error
60
61
  | `invalidInsightQuery` | 400 | `InsightQueryError` | yes | yes | `service/insightQueryError.ts` |
61
62
  | `invalidKey` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
62
63
  | `invalidMessage` | 400 | `AkanError` | no | yes | `base/akanError.ts` |
64
+ | `invalidMetric` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
63
65
  | `invalidParam` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
64
66
  | `invalidPrompt` | 500 | `PromptError` | no | yes | `signal/mcp/promptError.ts` |
65
67
  | `invalidQuery` | 500 | `DocumentStoreError` | no | yes | `service/documentStoreError.ts` |
@@ -103,6 +105,8 @@ Generated from the akanjs sources of this release: every code a framework error
103
105
  | `remoteUnavailable` | 502 | `RemoteError` | no | yes | `server/remote/remoteError.ts` |
104
106
  | `remoteUrlRejected` | 502 | `RemoteError` | no | yes | `server/remote/remoteError.ts` |
105
107
  | `renderAborted` | 499 | `AkanError` | no | yes | `base/akanError.ts` |
108
+ | `renderQueueFull` | 503 | `RscRenderRefusal` | no | yes | `server/rscRenderRefusal.ts` |
109
+ | `renderQueueTimeout` | 503 | `RscRenderRefusal` | no | yes | `server/rscRenderRefusal.ts` |
106
110
  | `routeConflict` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
107
111
  | `routeNotFound` | 404 | `AkanError` | no | yes | `base/akanError.ts` |
108
112
  | `routeNotFound` | 404 | `RscRouteNotFound` | no | yes | `server/rscClient.tsx` |
@@ -552,9 +552,10 @@ at every event.
552
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
553
  asked about nor run. A request with no `allow` array is an `error`.
554
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.
555
+ every tool. A tool in no toolkit is listed every round, beside `openToolkit({ name })`, whose description lists the
556
+ toolkits. An opened toolkit's tools are listed from the next round on, until a compaction keeps no message using
557
+ it; `openToolkit` never reaches `approve` and counts as no tool call. A resume reopens what stored calls and a
558
+ summary opened.
558
559
  - **The open screen's tools.** `clientTools` takes `new AgentClientTools().list()` from a page the member has open
559
560
  (`akanjs/ui`), sent over your own transport. It is client input: a name an endpoint holds is dropped, every one
560
561
  counts as a write whatever `readOnly` it was sent with, and past 128 tools, 200,000 characters of definitions or
@@ -593,7 +594,13 @@ at every event.
593
594
  reaches `approve(call, { tainted, tool, client })` with `tainted` set, and `client: true` when the call is to a
594
595
  page's tool. `askUser`'s answer, `openToolkit`'s and a call the run refused without running taint nothing. A
595
596
  remote is the exception on each count: opening one taints the run, and so does any call into one, refused or not,
596
- whatever `untrusted` returns and with none given. A batch is judged before it runs, since the model wrote it
597
+ whatever `untrusted` returns and with none given. Text the request itself carries from another party taints the
598
+ run before any tool has run: a `context` block marked `untrusted: true`, and a user message's `references`, the
599
+ records it points at. With no `approve`, a write in such a run is answered with the code `writeAfterPageText`
600
+ for the rest of the conversation, as the stored messages keep the reference: only `approve` decides it.
601
+ `context` reaches the model as data in a user turn, never in the system prompt, and a marked block is fenced as
602
+ page content. The run stores `tainted: true` on each assistant message it writes while tainted, so a resume and
603
+ the next ask in that conversation keep the taint without the block being passed again. A batch is judged before it runs, since the model wrote it
597
604
  before reading its results. Without `approve`, a `needsConfirm`
598
605
  tool — on this catalogue, a mutation with the `destructive` hint above — is refused, and so is every write once
599
606
  tainted: such a run writes only in the batch written before any result, and a later write is answered with the
@@ -98,6 +98,23 @@ worker per web-serving replica.
98
98
  is then the only thing bound to answer `/_akan/app/health`.
99
99
  - **The RSC worker is never folded in.** It runs under `--conditions react-server`, which resolves the same
100
100
  module graph differently, so it cannot share a process with the server that renders client components.
101
+ - **A render worker starts every render it is sent, unless `AKAN_RSC_WORKER_MAX_CONCURRENCY` caps it.** With a
102
+ cap, that many renders run in one worker (so per replica) and the rest wait first come, first served: documents,
103
+ `/__rsc` navigations and prefetches, and a failed render's error page. A stored page is replayed without a slot,
104
+ after a wait too; an aborted request leaves the queue, and a slot comes back when its render ends, throws, is
105
+ cancelled, or has held it as long as `AKAN_IDLE_TIMEOUT` (120 s, also where that is `0`); MCP page prompts are not
106
+ queued. `AKAN_RSC_WORKER_MAX_QUEUE` bounds the queue (default: the cap times that timeout's seconds, `0` for
107
+ none): a render past it, or one that waited that timeout, is answered `503` with `Retry-After: 1` and `no-store`
108
+ before it renders (`renderQueueFull`, `renderQueueTimeout`; a browser gets a page that reloads once, backing
109
+ off), counted as its route's `5xx` and in `akan_rsc_render_refusals_total{reason}`, which counts a slot taken
110
+ back as `hold-timeout`. `akan_rsc_renders_in_flight`, `akan_rsc_render_queue_depth` and
111
+ `akan_rsc_render_queue_wait_seconds` report the queue; a page that waited carries `queueMs` on its request line.
112
+ The cap bounds admitted renders, not abandoned ones: a page whose slot came back runs on until its own `await`
113
+ settles, counted in `akan_rsc_renders_abandoned`.
114
+ Off by default, because a page that awaits data holds its slot: on `apps/akan` at 32 requests at once, pages
115
+ waiting 20–200 ms on data served 151 requests a second uncapped and 32 at a cap of 4, while CPU-bound pages
116
+ served about 105 at any cap with the same median latency. It bounds a burst, not latency: set it to the requests
117
+ one replica is sized for; the table is in `pkgs/akanjs/server/SSR_MEMORY_DIAGNOSIS.md`.
101
118
  - **A solo process answers `/_akan/app/health`, `/_akan/app/metrics` and `/_akan/bench/ping` itself**, in the
102
119
  gateway's own shape — a `children` array with one entry — so a probe reads one contract either way. It owns the
103
120
  rotating log file the gateway would otherwise write, in the same `runtime/logs` directory.
@@ -107,6 +124,19 @@ worker per web-serving replica.
107
124
  alone (still 200) and `/_akan/app/metrics` is 401. An address that sends 10 wrong bearers in a minute is refused
108
125
  the right one too until the minute passes. A probe that reads only the status code needs nothing; give a scraper or
109
126
  monitor `AKAN_STATUS_TOKEN` (32 characters or more, or it warns), which reads nothing else.
127
+ - **`/_akan/app/metrics` answers a Prometheus scrape as text**, behind the same token: `Accept:
128
+ application/openmetrics-text` gets OpenMetrics 1.0 and `text/plain` the 0.0.4 text, while `*/*`,
129
+ `application/json` or no Accept keeps the JSON, whose `metricFamilies` carries the same series. Every endpoint and
130
+ page call is counted and timed with tracing off — `akan_endpoint_requests_total{endpoint, status_class}`,
131
+ `akan_page_requests_total{route, status_class}` and their `_duration_seconds` histograms (12 buckets, 1 ms to
132
+ 10 s) — labelled `<type>:<key>` or the route id and the process `role`, never a URL, user or query; a path no
133
+ route matches is `unmatched`, and a label past 2,000 values is `other`. Behind a gateway each replica reports its
134
+ own and the gateway adds them, as fresh as `AKAN_MEMORY_LOG_INTERVAL_MS`. A new series is one line,
135
+ `metricRegistry.counter|gauge|histogram(name, help, labels)` from `server/metrics/metricRegistry`, in the server
136
+ or in its RSC worker, whose series reach the same scrape as fresh as that interval and survive a worker restart. The
137
+ `infra/app` chart adds the `prometheus.io/*` scrape annotations with `<branch>.metrics.scrape: true` and reads the
138
+ token from the Secret `<branch>.metrics.tokenSecret` names, and refuses to render `scrape` without it;
139
+ `infra/monitoring` holds a Grafana dashboard and the alert rules.
110
140
  - **Nothing supervises a solo process but the orchestrator**, since the gateway's crash-restart-with-backoff went
111
141
  with it. `infra/app/templates/app.yaml` carries the liveness, readiness and startup probes that replace it.
112
142
  - **`PORT` is the whole tree's port, and a server-side self-call follows it.** `AkanApp` resolves it once
@@ -191,9 +221,20 @@ normalized to `info` with one warning.
191
221
  `traceId`. Internal triggers get `internal:<key>`, the RSC worker gets `page:<route>`, MCP calls are the
192
222
  endpoint's own type with `origin: "mcp"`. `AKAN_LOG_CONTEXT=0` is the escape hatch; `AKAN_TRACE=1` is a
193
223
  different switch that adds span and query aggregation. Measured cost: ~25ns per call.
224
+ - **One id per request, across processes.** The `traceId` is 32 hex digits (a W3C trace id), written on the response
225
+ as `x-request-id` and in a failed call's body as `traceId`. The server always mints it: an inbound `traceparent`,
226
+ or else an `x-request-id` that is a UUID or 32 hex digits, is kept as `link` on every record of the request, and
227
+ `akan logs --trace` matches `link` too and takes the id as the caller sent it. Only the gateway's unix-socket hop
228
+ to its replica carries an id over. `AKAN_TRACE_ADOPT=trusted-proxies` lets a peer `AKAN_TRUSTED_PROXIES` names
229
+ (an address, a CIDR, or `private`; never the unset default, `*`, or loopback unlisted) choose the id, which is
230
+ safe only when that proxy overwrites or strips both headers. The replica hands its id to the RSC worker in the
231
+ render message, a server-side `fetch` sends `traceparent` to the app's own server and to a `clone({ origin })`,
232
+ every websocket frame is a span under its handshake's id, and a queued job is a trace of its own that links the
233
+ enqueuing one.
194
234
  - **Not everything carries context, by design.** The primitive query fast path (an unauthenticated GET of a
195
235
  primitive with no args, guards or middlewares) skips it; the schedule adaptor's own `started/finished/error`
196
- lines wrap the traced handler from outside; gateway-internal lines have none. `akan logs --endpoint` says so.
236
+ lines wrap the traced handler from outside; gateway lines written outside a request have none. `akan logs
237
+ --endpoint` says so.
197
238
  - **`Logger.addSink(sink, { minLevel })` — give a sink its floor.** A sink with none follows `AKAN_LOG_FILE_LEVEL`
198
239
  (default `trace`), which is why a registered sink used to make every `verbose` call render (1,294ns against an
199
240
  11ns reject). The IPC forwarder and any sink that never reads the text pass a floor and cost a record literal.
@@ -224,8 +265,17 @@ normalized to `info` with one warning.
224
265
  - **`AKAN_LOG_CANONICAL=1|slow`** writes one `ok|error <endpoint> ms= status=` line per call, at `info`, `warn` under
225
266
  500, or `error` with `type` and `stack` for a 5xx (then the only 5xx record); **`AKAN_LOG_FLIGHT=1`**
226
267
  keeps each call's last 64 sub-level records and promotes them (`flight=true`) only when it failed or ran past
227
- `AKAN_LOG_FLIGHT_MS`; an `x-akan-debug` header lowers one request to `trace` — under the local dev runtime, or
228
- with the `AKAN_LOG_DEBUG_HEADER` secret.
268
+ `AKAN_LOG_FLIGHT_MS`; an `x-akan-debug` header lowers one request to `trace`, records its spans and answers with
269
+ `Server-Timing` — under the local dev runtime, or with the `AKAN_LOG_DEBUG_HEADER` secret. A local runtime sends
270
+ `Server-Timing` on every signal response. Spans carry ids, parents and start offsets; under `AKAN_TRACE=1` each
271
+ database call is a `db:<model>.<op>` span, never its statement or values.
272
+ - **Every dev route is listed once, in `akanjs/server/routing/devSurfaces`** — devtools, Studio, `/_akan/hmr`,
273
+ the ssr-dev and csr-dev module registries, `/__rsc/manifest` — and is mounted through `DevRoutes.mount`, which
274
+ refuses a path the list lacks. Each answers only localhost, an IP address, the app's own hosts and
275
+ `AKAN_ALLOWED_HOSTS` names, even on a server that answers every Host; `--share` serves only the two module
276
+ registries. Devtools opens in the local dev runtime; elsewhere `AKAN_DEVTOOLS=true` opens it only with
277
+ `AKAN_LOG_DEBUG_HEADER` set to at least 32 characters, to `x-akan-debug: <secret>` or a browser that posted the
278
+ secret to the form it is shown (a 15-minute cookie); without one that long it stays closed and the log says why.
229
279
  - **Structured values go in `LogRecord.attrs` via `Logger.emit(...)`**; a key naming a secret is `[redacted]`
230
280
  before the record exists.
231
281
  - **Never log per delivered record in anything that delivers records.** The control socket and the hub do not,
@@ -247,6 +297,16 @@ const config: AppConfig = { docker: "FROM oven/bun:1.4.4-slim\n…" }; // verbat
247
297
  `RUN if [ "$TARGETARCH" = "<arch>" ]` guard, so a multi-arch build runs it on one leg only. `preRuns` land
248
298
  before `bun install --production` (where a native dependency's build tools have to be), `postRuns` after it
249
299
  and before the app files are copied.
300
+ - **The server runs as `USER 1000:1000`, oven/bun's `bun` user, and owns only the directories it writes.** The
301
+ build steps (`apt-get`, `preRuns`, `bun install`, `postRuns`) run as root and the app files stay root's, so
302
+ `main.js`, `server.js`, `public/` and `node_modules` are read-only to the server. After the copy, uid 1000 gets
303
+ `/workspace/sqlite`, `/workspace/local`, `/workspace/runtime` (the control socket), `/workspace/data` and
304
+ `/workspace/.akan/artifact/image-cache`; `/tmp` and `/home/bun` are writable too. A directory a `postRuns` step
305
+ makes for the server to write needs `chown 1000:1000`. An empty named volume takes the owner of the directory it
306
+ mounts over; one a root image already wrote is owned by root, so the server stops at boot with
307
+ `directoryNotWritable`, naming the directory and the `chown -R 1000:1000` that fixes it.
308
+ - **The base image is pinned by digest**, `oven/bun:<bun>-slim@sha256:…`, the multi-arch index's, so amd64 and
309
+ arm64 build from the same release; a test holds the tag to the Bun version the workspace's `package.json` pins.
250
310
  - **The image installs the versions the workspace locked.** `akan build` writes a `bun.lock` beside the image's
251
311
  `package.json`, cut down from the workspace's to what the server needs, and the image installs it
252
312
  `--frozen-lockfile`. A workspace without a root `bun.lock` gets a warning and an unlocked install; a Dockerfile
@@ -396,7 +456,11 @@ const config: AppConfig = {
396
456
  only, `evaluate`, a trusted `sendKey`, `capture`, and `loadFailed` / `gone` (it reloads, or is rebuilt, by itself;
397
457
  the reason is `terminated` on macOS, and `rebuildFailed` when a rebuild failed and the view is closed, to be opened
398
458
  again) / `consoleMessage` events. Every method on Windows and Linux, where a visible view also holds the keyboard
399
- focus and no `consoleMessage` is sent; macOS 14+ lacks `sendKey`, `setMuted` and `capture`.
459
+ focus and no `consoleMessage` is sent; macOS 14+ lacks `sendKey`, `setMuted` and `capture`. A view opens only the
460
+ exact origins `native.desktop.externalView.allowOrigins` lists (none without it), over the calling page's own window:
461
+ its own `allowOrigins` narrow within them, and opening it again while it is open never adds one. Closed, its id opens
462
+ again for any listed origins with the same profile, which belongs to the id. `evaluate` and `initScript` need
463
+ `desktop.externalView.evaluate: true`, `sendKey` needs `desktop.externalView.sendKey: true`.
400
464
 
401
465
  ## A Desktop App's Server — `bin` And `trustedDependencies`
402
466
 
@@ -3,21 +3,21 @@ import"./index-zyjztrvc.js";
3
3
  import {
4
4
  CodegenLock,
5
5
  WorkspaceExecutor
6
- } from "./index-609zbjve.js";
6
+ } from "./index-v16gj2as.js";
7
7
  import"./index-j4yvgfhr.js";
8
8
  import {
9
9
  HmrWatcher,
10
10
  WatchRootResolver,
11
11
  ApplicationBuildReporter
12
- } from "./index-w18qdjyf.js";
12
+ } from "./index-8bta5pnr.js";
13
13
  import {
14
14
  AppExecutor2
15
- } from "./index-cfzqdsam.js";
16
- import"./index-c67vjafa.js";
17
- import"./index-2t7jnfg5.js";
15
+ } from "./index-9a9t77hz.js";
16
+ import"./index-yey1envc.js";
17
+ import"./index-crd99zqs.js";
18
18
  import {
19
19
  ServerGraphFile
20
- } from "./index-eap5y4w5.js";
20
+ } from "./index-3mj5trqc.js";
21
21
  import {
22
22
  GraphClientEntryDiscovery,
23
23
  RouteClientBuilder,
@@ -27,7 +27,7 @@ import {
27
27
  DevChangePlanner,
28
28
  DevGeneratedIndexSync,
29
29
  SsrDevBundler
30
- } from "./index-94h6dxc3.js";
30
+ } from "./index-4yvtqcme.js";
31
31
  import"./index-trffs83s.js";
32
32
  import {
33
33
  FrameworkGraph2
@@ -41,7 +41,7 @@ import {
41
41
  import {
42
42
  prepareDevWatchBatch
43
43
  } from "./index-a5vmm6x4.js";
44
- import"./index-zfmc4380.js";
44
+ import"./index-3r1crbct.js";
45
45
 
46
46
  // pkgs/@akanjs/devkit/incrementalBuilder/incrementalBuilder.proc.ts
47
47
  import path6 from "path";
@@ -157,7 +157,7 @@ class SubagentPool2 {
157
157
  }
158
158
  }
159
159
  async#run(id, kind, prompt, signal) {
160
- const { CodeAgent } = await import("./CodeAgent-277k8f4q.js");
160
+ const { CodeAgent } = await import("./CodeAgent-cqbf9gsv.js");
161
161
  const budget = this.#options.parent.tools.subagent;
162
162
  const child = SubagentPool2.childOf(this.#options.parent, kind);
163
163
  const model = this.#options.model?.();
@@ -257,6 +257,7 @@ class CodeTuiCommands2 {
257
257
  { name: "fork", desc: "continue this conversation twice; the copy takes over here", arg: "[name]" },
258
258
  { name: "agents", desc: "what a sub-agent may be, and what one may spend" },
259
259
  { name: "mcp", desc: "the MCP servers this session reached", arg: "[add|remove|login|reload]" },
260
+ { name: "allowed", desc: "the commands this session runs without asking", arg: "[clear]" },
260
261
  { name: "peers", desc: "the other akan code sessions running here" },
261
262
  { name: "msg", desc: "hand a message to another session", arg: "<peer> <text>" },
262
263
  { name: "quit", desc: "leave the session" }
@@ -662,7 +663,12 @@ class CodeTuiParts2 {
662
663
  case "approval":
663
664
  return [
664
665
  { prefix: { text: "? ", color: "yellow" }, spans: [{ text: part.request.summary, color: "yellow" }] },
665
- ...part.approved === undefined ? [] : [{ prefix: { text: " " }, spans: [{ text: part.approved ? "approved" : "denied", dim: true }] }]
666
+ ...part.approved === undefined ? [] : [
667
+ {
668
+ prefix: { text: " " },
669
+ spans: [{ text: CodeTuiParts2.#verdict(part.approved, part.remembered), dim: true }]
670
+ }
671
+ ]
666
672
  ];
667
673
  case "host":
668
674
  return [{ prefix: { text: " ", dim: true }, spans: [{ text: `${part.hostKind} ${part.text}`, dim: true }] }];
@@ -749,6 +755,11 @@ class CodeTuiParts2 {
749
755
  ...part.rendered === undefined ? [] : [{ prefix: { text: " = ", color: "green" }, spans: [{ text: part.rendered, color: "green" }] }]
750
756
  ];
751
757
  }
758
+ static #verdict(approved, remembered) {
759
+ if (!approved)
760
+ return "denied";
761
+ return remembered?.length ? `approved \xB7 ${remembered.join(", ")} runs unasked until this session ends` : "approved";
762
+ }
752
763
  static #noticeStyle(level) {
753
764
  if (level === "error")
754
765
  return { color: "red" };
@@ -2,10 +2,10 @@
2
2
  import {
3
3
  CommandContainer,
4
4
  runner
5
- } from "./index-vznyyaf8.js";
5
+ } from "./index-nnmw56fz.js";
6
6
  import {
7
7
  WorkspaceExecutor
8
- } from "./index-609zbjve.js";
8
+ } from "./index-v16gj2as.js";
9
9
  import {
10
10
  jsonText,
11
11
  workflowPlanApproval,
@@ -31,23 +31,23 @@ import {
31
31
  renderWorkflowApply,
32
32
  renderWorkflowValidation,
33
33
  renderWorkflowRunArtifact
34
- } from "./index-g7hm77j6.js";
34
+ } from "./index-q63nbpv7.js";
35
35
  import {
36
36
  AkanContextAnalyzer
37
- } from "./index-ghs8gtvp.js";
37
+ } from "./index-h8w1n11r.js";
38
38
  import {
39
39
  ModuleScript
40
- } from "./index-6yefp97x.js";
40
+ } from "./index-rdcgz02t.js";
41
41
  import {
42
42
  PrimitiveScript
43
- } from "./index-jzwdwse0.js";
43
+ } from "./index-m303nhv6.js";
44
44
  import {
45
45
  spawnAkan,
46
46
  isWorkspaceTarget
47
- } from "./index-2ktpwjgf.js";
47
+ } from "./index-kbnvyhy4.js";
48
48
  import {
49
49
  ScalarScript
50
- } from "./index-0vv0a5h8.js";
50
+ } from "./index-fagjtk6m.js";
51
51
  import {
52
52
  workflowSpecs
53
53
  } from "./index-t4d0ckde.js";
@@ -3,7 +3,7 @@ import {
3
3
  AsyncDefaultExportDetector,
4
4
  StoreBootstrap,
5
5
  resolveSsrPageEntriesForApp
6
- } from "./index-cfzqdsam.js";
6
+ } from "./index-9a9t77hz.js";
7
7
  import {
8
8
  FileSys2
9
9
  } from "./index-zyjztrvc.js";
@@ -207,7 +207,7 @@ class BarrelAnalyzer {
207
207
  if (!rel || rel.startsWith("..") || path.isAbsolute(rel))
208
208
  return null;
209
209
  if (pkg.preserveFilePath)
210
- return `${pkg.pkgName}/${rel.split(path.sep).join("/")}`;
210
+ return absFile.split(path.sep).join("/");
211
211
  const ext = CANDIDATE_EXTS.find((candidate) => rel.endsWith(candidate));
212
212
  const parts = (ext ? rel.slice(0, -ext.length) : rel).split(path.sep);
213
213
  if (parts[parts.length - 1] === "index")
@@ -2,7 +2,7 @@
2
2
  import {
3
3
  execEmoji,
4
4
  Executor
5
- } from "./index-609zbjve.js";
5
+ } from "./index-v16gj2as.js";
6
6
  // pkgs/@akanjs/devkit/executors/moduleExecutor.ts
7
7
  class ModuleExecutor extends Executor {
8
8
  sys;