@akanjs/cli 3.2.0-rc.9 → 3.2.1-rc.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.build-stamp +2 -2
- package/CodeAgent-xdw73nbz.js +11 -0
- package/{CodeTui-qstk5vpj.js → CodeTui-0gewm71c.js} +822 -666
- package/README.ko.md +7 -0
- package/README.md +7 -0
- package/TunnelShare-cccfdgbm.js +16 -0
- package/agent.command-g1mj34wz.js +59 -0
- package/akanCode.js +12 -12
- package/appExecutor-rrx10jya.js +11 -0
- package/{application.command-m4rq4wc2.js → application.command-3w4v7t40.js} +84 -40
- package/{applicationBuildRunner-df7rx3ra.js → applicationBuildRunner-y5xbetyz.js} +51 -20
- package/buildBatch.proc.js +31 -16
- package/{cloud.command-a0gy0qq2.js → cloud.command-ph0rz6sw.js} +28 -29
- package/cloud.script-8bs9tp4j.js +30 -0
- package/{code.command-5rsdqw8s.js → code.command-9b967qpg.js} +13 -9
- package/context.command-ndzs5rbf.js +62 -0
- package/context.runner-bmstpng2.js +32 -0
- package/csrArtifactBuilder-gtvff6k7.js +10 -0
- package/{index-qd7xn2bk.js → dependencyScanner-93g8tk0r.js} +7 -6
- package/{devTui-h77zrjv5.js → devTui-rf374y2w.js} +1 -1
- package/{fileSys-zpvt5gtf.js → fileSys-e5mwt73x.js} +1 -1
- package/frameworkGraph-aneq2nwy.js +8 -0
- package/{guideline.command-mffxknbr.js → guideline.command-y8qz9kxy.js} +9 -5
- package/guidelines/agentRule/agentRule.instruction.md +25 -9
- 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 -4
- package/guidelines/conventions/rules/ts.md +3 -3
- package/guidelines/errorCodes/errorCodes.instruction.md +165 -0
- package/guidelines/fieldRule/fieldRule.instruction.md +2 -1
- package/guidelines/mcpRule/mcpRule.instruction.md +225 -5
- package/guidelines/pageRule/pageRule.instruction.md +10 -1
- package/guidelines/queryRule/queryRule.instruction.md +3 -1
- package/guidelines/runtimeRule/runtimeRule.instruction.md +14 -8
- package/guidelines/transportRule/transportRule.instruction.md +31 -1
- package/incrementalBuilder.proc.js +609 -437
- package/{index-skmtj8rm.js → index-02v45hh9.js} +27 -10
- package/{index-j6gc8n14.js → index-0csk6jqm.js} +11 -9
- package/{index-2r9ff9qm.js → index-0wa5z6rm.js} +2 -2
- package/{index-nmvhjn8c.js → index-0z8sbdme.js} +93 -82
- package/{index-2vgv7fs7.js → index-1c2807kg.js} +727 -693
- package/{index-hj6w4ka1.js → index-1p81ecbz.js} +1 -1
- package/{index-2mf1aen9.js → index-1p9bxjmt.js} +2 -2
- package/{index-an76bdrv.js → index-2kh4xj3m.js} +1 -1
- package/{index-99qvtff2.js → index-2vn0m9z5.js} +5 -5
- package/{index-rp4yf32g.js → index-3569fr49.js} +36 -29
- package/{index-xvk2a75m.js → index-38x8ynrx.js} +25 -25
- package/{index-cmg5ngqa.js → index-3fmzz9sf.js} +20 -20
- package/{index-rfzp4pqs.js → index-45aprybg.js} +3 -3
- package/{index-k92x3vne.js → index-4a1n0nym.js} +1 -1
- package/{index-ra9fvn7s.js → index-4zgm54wf.js} +76 -40
- package/{index-exn38bzx.js → index-652f3bs8.js} +116 -54
- package/{index-grxs6fts.js → index-6gepp8yn.js} +57 -31
- package/{index-vm0dn0mt.js → index-6j351de4.js} +294 -157
- package/{index-w15mg3km.js → index-7ssr7wq4.js} +1 -1
- package/{index-gxav1bjz.js → index-82cmbpxc.js} +9 -9
- package/{index-2mrn1mrg.js → index-9f3reh2y.js} +1 -1
- package/{index-gcx48get.js → index-9rymt8d6.js} +2 -2
- package/{index-swwjakt0.js → index-ankyx6dj.js} +14 -18
- package/{index-28x1aszt.js → index-b0t92k71.js} +154 -58
- package/index-b372rck5.js +799 -0
- package/{index-yf9wc28h.js → index-bejy9zyc.js} +1 -1
- package/{index-r0a604h4.js → index-c669pbyb.js} +5 -4
- package/{index-xyn02k0w.js → index-cm9rb480.js} +662 -433
- package/{index-j9790rhk.js → index-d0n78fzc.js} +1635 -1139
- package/{index-hqv34wzq.js → index-dr1carpr.js} +10 -10
- package/index-f2arv0mv.js +30 -0
- package/{index-5radqwn2.js → index-gtydr9qc.js} +12 -12
- package/{index-j6eeh5d7.js → index-j3fqs8rc.js} +5 -5
- package/{index-yckz5t8b.js → index-jdw9m5c4.js} +516 -434
- package/{index-ny2k80mv.js → index-jf4vk1s0.js} +9 -2
- package/{index-x40bdsca.js → index-jg5rwrf7.js} +77 -115
- package/{index-5zwr4n6k.js → index-ktxdfqg5.js} +65 -8
- package/index-mnhrqjjq.js +127 -0
- package/{index-3ghdb7p5.js → index-pc42gxa5.js} +2777 -3676
- package/{index-0hbtve0a.js → index-q8h4eg5y.js} +32 -28
- package/{index-j3v29pq7.js → index-qh81drde.js} +219 -175
- package/{index-b4qq3rq0.js → index-rwgqba9p.js} +1 -1
- package/{index-w8yasvpc.js → index-scfsqen7.js} +2136 -2175
- package/{index-9p260r4e.js → index-trffs83s.js} +538 -250
- package/{index-0gg15zwa.js → index-twjgmryg.js} +6 -6
- package/index-whvhsb5f.js +80 -0
- package/{index-h7hehkw6.js → index-xczjdng6.js} +3 -1
- package/{index-39jz41jb.js → index-xs9a3ddt.js} +3 -3
- package/{index-35j83zkd.js → index-xv3pvdw4.js} +2 -2
- package/{index-34792nh7.js → index-y2g0s9tn.js} +1 -1
- package/{index-43f4h4cm.js → index-ymgsvhc5.js} +7 -8
- package/{index-ygdbn9jn.js → index-zyb0ebm4.js} +1 -1
- package/{index-bns3wcpc.js → index-zyjztrvc.js} +2 -2
- package/index.js +30 -24
- package/libExecutor-nstr00s7.js +10 -0
- package/{library.command-bmd7zc5m.js → library.command-b02aw1hm.js} +12 -5
- package/{localRegistry.command-y6en1599.js → localRegistry.command-3hg1p4aj.js} +24 -24
- package/{module.command-7exfffqw.js → module.command-bd9gz6cv.js} +11 -7
- package/{package.command-adskw2rj.js → package.command-xmr0mxze.js} +11 -10
- package/package.json +8 -8
- package/{page.command-dw01272p.js → page.command-x94qf58g.js} +8 -4
- package/{pipeline.command-0b1r3y5r.js → pipeline.command-n2843k6t.js} +15 -9
- package/pkgExecutor-cka27e3c.js +10 -0
- package/{primitive.command-byw6vc04.js → primitive.command-cs7v376h.js} +12 -8
- package/{projectTypecheck-kkrpq60a.js → projectTypecheck-za2n3nbr.js} +1 -1
- package/{prompter-qrwx1p17.js → prompter-d33wmdpa.js} +2 -2
- package/{quality.command-6rqnhzct.js → quality.command-nqngh1jd.js} +25 -16
- package/{recipeScanner-4b69ybe0.js → recipeScanner-rrx69awy.js} +1 -1
- package/{repair.command-rw5zymak.js → repair.command-v2medwsm.js} +12 -8
- package/{routeSourceValidator-4h947v7c.js → routeSourceValidator-8n6j1vn7.js} +4 -2
- package/{scalar.command-2dyp9nh9.js → scalar.command-61cjmxn1.js} +10 -6
- package/skills/akan-debug/SKILL.md +8 -5
- package/skills/akan-err/SKILL.md +7 -0
- package/skills/akan-mcp/SKILL.md +19 -1
- package/skills/akan-scaffold/SKILL.md +1 -1
- package/skills/akan-validate/SKILL.md +3 -3
- package/{subspace.command-111ynwv1.js → subspace.command-dtv8nfh7.js} +30 -24
- 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/.devcontainer/devcontainer.json.template +1 -1
- package/templates/workspaceRoot/AGENTS.md.template +2 -1
- package/templates/workspaceRoot/README.ts +4 -2
- package/{tunnel.command-2gcpfbdj.js → tunnel.command-fmwm5fgb.js} +15 -13
- package/{typeChecker-s640r6c0.js → typeChecker-7jt6abrs.js} +1 -1
- package/typecheck.proc.js +3 -2
- package/{verify.command-djgs86ma.js → verify.command-4f260t53.js} +19 -17
- package/{workflow.command-n0k2mxr5.js → workflow.command-tm5q9xsm.js} +21 -14
- package/{workspace.command-fh1qwxfx.js → workspace.command-75gc280j.js} +56 -54
- package/CodeAgent-x2p3a3e0.js +0 -11
- package/TunnelShare-c4xsfzg5.js +0 -15
- package/agent.command-9et2e27p.js +0 -52
- package/cloud.script-xze4zh7n.js +0 -31
- package/context.command-rk1dwrg4.js +0 -57
- package/context.runner-83ky5m1b.js +0 -30
- package/dependencyScanner-78sq8m4q.js +0 -8
- /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
|
@@ -30,6 +30,24 @@ and infrastructure. A workspace is Bun-first: `apps/<app>` holds pages, domain m
|
|
|
30
30
|
- Follow the nearest established pattern; when two shapes disagree, follow the newer neighbour. A new abstraction must
|
|
31
31
|
remove real duplication — near-identical sibling modules are copied with changed literals, not parameterised.
|
|
32
32
|
|
|
33
|
+
## Finishing Work
|
|
34
|
+
|
|
35
|
+
- Carry the task through to `verify ok`. A failing check, a stale generated file, a stopped dev server or a tool
|
|
36
|
+
error is an ordinary obstacle: diagnose it and work through it (`akan sync`, `akan repair generated`, a retry,
|
|
37
|
+
another command) rather than stopping to report it or offering to continue. Silencing a check is not a way through.
|
|
38
|
+
- Routine steps need no confirmation: reading code, `akan sync`, `akan verify`, `akan test`, `akan preview`, and the
|
|
39
|
+
workflow plan and apply the task calls for. Ask only when the work cannot go on without the answer, and keep doing
|
|
40
|
+
the parts that do not depend on it.
|
|
41
|
+
- A deliberate blocker stays put — another person's change in a dirty tree, an `akan.baseline.json` entry, a secret
|
|
42
|
+
you cannot read, a failure outside what you changed: leave it, say what you found, and finish the rest. Confirm
|
|
43
|
+
before a step that is hard to undo or leaves this machine, such as a push, a deploy or a write to a shared database.
|
|
44
|
+
|
|
45
|
+
## Reporting
|
|
46
|
+
|
|
47
|
+
Write the final message for a reader who did not watch your tool calls. Lead with the outcome, name every file you
|
|
48
|
+
changed (small edits too), give each check's own result line, and say what you left undone or could not check, and
|
|
49
|
+
why. Use plain words, not labels you coined during the work.
|
|
50
|
+
|
|
33
51
|
## Looks Wrong, Is Right — Do Not "Fix"
|
|
34
52
|
|
|
35
53
|
- Tailwind class order (`font-bold text-2xl text-foreground`) — Biome sorts it, `cn()` arguments included.
|
|
@@ -47,7 +65,7 @@ and infrastructure. A workspace is Bun-first: `apps/<app>` holds pages, domain m
|
|
|
47
65
|
contract. Path rules name their checks the same way.
|
|
48
66
|
|
|
49
67
|
- 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].
|
|
68
|
+
(`no-throw-raw-error`) and never the untyped `Err` of `akanjs/common` (`no-import-common-err`) [app].
|
|
51
69
|
- A third-party package reaches `page/**`, a barrel or a module file only through a lib re-export
|
|
52
70
|
(`no-import-external-library`) [app].
|
|
53
71
|
- Colors only from the semantic vocabulary (`bg-primary`, `text-foreground/70`) — no palette, arbitrary, daisyUI or
|
|
@@ -77,10 +95,10 @@ contract. Path rules name their checks the same way.
|
|
|
77
95
|
- One class per file, named after it; TypeScript files are camelCase, component and convention files excepted.
|
|
78
96
|
- Identifiers, endpoint names and logs are English; everything a user reads goes through `l("model.field")` or
|
|
79
97
|
`l.trans({ en, ko })`, and dictionary entries are `[en, ko]` pairs.
|
|
80
|
-
- Comment only what the code cannot say (`akan verify` flags each new one as `akan.comment.added
|
|
81
|
-
an infrastructure constraint, security reasoning, a domain field's
|
|
82
|
-
alternative. Never restate code, label a section or add JSDoc; retire a
|
|
83
|
-
`/** @deprecated <what instead> */`.
|
|
98
|
+
- Comment only what the code cannot say (`akan verify` flags each new one as `akan.comment.added`, a
|
|
99
|
+
`// TODO: <issue url>` aside) — a vendor quirk, an infrastructure constraint, security reasoning, a domain field's
|
|
100
|
+
meaning, a state transition, a rejected alternative. Never restate code, label a section or add JSDoc; retire a
|
|
101
|
+
symbol with `/** @deprecated <what instead> */`.
|
|
84
102
|
- Server rendering is the default: `"use client"` only for a hook, an event handler, the store, a browser global or
|
|
85
103
|
a client-only package.
|
|
86
104
|
|
|
@@ -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/`,
|
|
@@ -49,7 +52,7 @@ each plugin's header and diagnostic carry its full reasoning.
|
|
|
49
52
|
- Lib root files: `AGENTS.md`, `CLAUDE.md`, `README.md`, `akan.baseline.json`, `akan.config.ts`, `akan.lib.json`,
|
|
50
53
|
`client.ts`, `index.ts`, `package.json`, `server.ts`, `tsconfig.json`, `tsconfig.spec.json`, `tsconfig.tsbuildinfo`;
|
|
51
54
|
folders: the app's minus `.akan`, `script`, `secrets` (no `main.ts` either — a lib is never booted).
|
|
52
|
-
- The allowlists' one source is `pkgs/@akanjs/devkit/workspaceLayout.ts`, read by `akan sync` (error), `akan doctor`
|
|
55
|
+
- The allowlists' one source is `pkgs/@akanjs/devkit/workspace/workspaceLayout.ts`, read by `akan sync` (error), `akan doctor`
|
|
53
56
|
and `akan quality scan` — add an entry there and mirror it here.
|
|
54
57
|
- `apps/<app>/AGENTS.md` / `libs/<lib>/AGENTS.md` carry a generated `## Recipes In Scope` block between the
|
|
55
58
|
`akan:agent` markers — never hand-edit it (outside the markers is yours); `akan lint` fails when it is stale.
|
|
@@ -43,10 +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 while the page answers 200. So a
|
|
47
|
-
only a `Load.*`, directly or through a Zone.
|
|
48
|
-
`use()`-
|
|
49
|
-
|
|
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()`.
|
|
50
51
|
- **A route never writes while it renders**: a `fetch.<mutation>()` in a stage or a component it renders throws
|
|
51
52
|
`base.error.mutationInRender`, since opening a link would perform it. Send it from a user action;
|
|
52
53
|
`{ duringRender: true }` only for a write harmless to repeat and safe for anyone to trigger (`ssrRule`).
|
|
@@ -89,8 +89,8 @@ Do not narrate code. Do document the thing the code cannot say. Both halves are
|
|
|
89
89
|
- Warranted for: a vendor or protocol quirk; an infrastructure constraint; a library gotcha; security reasoning; why
|
|
90
90
|
an arbitrary-looking rule is correct; a math derivation; a domain field's business meaning; a state transition above
|
|
91
91
|
a document chain method; why an obvious alternative was rejected.
|
|
92
|
-
- Markers: `TODO
|
|
93
|
-
(disabled or must-fix — server, `srvkit/`, CLI only), `//?` (an aside), `//*` (a design note), and a
|
|
94
|
-
caution saying why removing a line would break something non-obvious.
|
|
92
|
+
- Markers: `TODO: <issue url>` (tracked unfinished work), `FIXME` (known broken), `XXX` (a hazard a reader must not
|
|
93
|
+
miss), `//!` (disabled or must-fix — server, `srvkit/`, CLI only), `//?` (an aside), `//*` (a design note), and a
|
|
94
|
+
deletion caution saying why removing a line would break something non-obvious.
|
|
95
95
|
- One short line each. Every suppression carries a reason (`// biome-ignore lint/<rule>: <why>`), never a bare
|
|
96
96
|
disable block. Match the nearby density.
|
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
# Akan.js error codes
|
|
2
|
+
|
|
3
|
+
Generated from the akanjs sources of this release: every code a framework error carries, so a caller branches on
|
|
4
|
+
`error.code`, or the `code` of the JSON it was answered with, rather than on the message.
|
|
5
|
+
|
|
6
|
+
- A **forwarded** error answers with its own JSON. Any other `AkanError` answers with its code and status, and in
|
|
7
|
+
production with the status's reason in place of its message, which can name a table, a file or what a provider
|
|
8
|
+
said (`akan start` and `AKAN_ERROR_DETAIL=1` keep the message).
|
|
9
|
+
- **Code on the wire** says whether that JSON carries `code`. A forwarded error whose JSON leaves it out is told
|
|
10
|
+
apart by its `error` key and status.
|
|
11
|
+
- An app's own failure is a dictionary `Err`, which carries its key in `error` instead of one of these codes.
|
|
12
|
+
- In code, `AkanError.is(error, "<code>")` tests any framework error for a code, and `<Class>.is(error)` one class.
|
|
13
|
+
|
|
14
|
+
## Codes
|
|
15
|
+
|
|
16
|
+
| Code | Status | Error | Forwarded | Code on the wire | Source |
|
|
17
|
+
|---|---|---|---|---|---|
|
|
18
|
+
| `alreadyApplied` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
|
|
19
|
+
| `alreadyInitialized` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
20
|
+
| `artifactMissing` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
21
|
+
| `authRequired` | 401 | `McpAuthRequiredError` | no | yes | `server/mcp/McpDispatcher.ts` |
|
|
22
|
+
| `badGateway` | 502 | `ImageOptimizerError` | no | yes | `server/imageOptimizerError.ts` |
|
|
23
|
+
| `badRequest` | 400 | `Exception.BadRequest` | yes | no | `signal/exception.ts` |
|
|
24
|
+
| `badRequest` | 400 | `ImageOptimizerError` | no | yes | `server/imageOptimizerError.ts` |
|
|
25
|
+
| `baseMismatch` | 500 | `SignalDeclarationError` | no | yes | `signal/signalDeclarationError.ts` |
|
|
26
|
+
| `buildFailed` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
27
|
+
| `builderUnavailable` | 503 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
28
|
+
| `bytesThroughAny` | 500 | `SignalContractError` | no | yes | `signal/signalContractError.ts` |
|
|
29
|
+
| `circularDependency` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
30
|
+
| `clientComponentOnServer` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
31
|
+
| `compressorNotInitialized` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
32
|
+
| `conflict` | 409 | `Exception.Conflict` | yes | no | `signal/exception.ts` |
|
|
33
|
+
| `consoleDisabled` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
34
|
+
| `databaseLocked` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
35
|
+
| `desktopAppRequired` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
36
|
+
| `documentNotFound` | 404 | `NoDocumentError` | yes | no | `document/noDocumentError.ts` |
|
|
37
|
+
| `duplicateRegistration` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
38
|
+
| `failed` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
|
|
39
|
+
| `fileGrantRefused` | 403 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
40
|
+
| `fileGrantUnavailable` | 503 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
41
|
+
| `forbidden` | 403 | `Exception.Forbidden` | yes | no | `signal/exception.ts` |
|
|
42
|
+
| `gatewayTimeout` | 504 | `Exception` | yes | no | `signal/exception.ts` |
|
|
43
|
+
| `handlerAlreadySet` | 500 | `SignalDeclarationError` | no | yes | `signal/signalDeclarationError.ts` |
|
|
44
|
+
| `inlineFailed` | 502 | `PromptError` | no | yes | `signal/mcp/promptError.ts` |
|
|
45
|
+
| `insightTimeout` | 504 | `InsightQueryError` | yes | yes | `service/insightQueryError.ts` |
|
|
46
|
+
| `insightUnavailable` | 500 | `InsightQueryError` | no | yes | `service/insightQueryError.ts` |
|
|
47
|
+
| `internalError` | 500 | `Exception.Error` | yes | no | `signal/exception.ts` |
|
|
48
|
+
| `invalidArgType` | 500 | `SignalDeclarationError` | no | yes | `signal/signalDeclarationError.ts` |
|
|
49
|
+
| `invalidArgument` | 400 | `McpArgumentError` | no | yes | `server/mcp/McpExecutionContext.ts` |
|
|
50
|
+
| `invalidArtifact` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
51
|
+
| `invalidCascade` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
52
|
+
| `invalidConfig` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
53
|
+
| `invalidDocument` | 500 | `DocumentStoreError` | no | yes | `service/documentStoreError.ts` |
|
|
54
|
+
| `invalidErrors` | 500 | `SignalDeclarationError` | no | yes | `signal/signalDeclarationError.ts` |
|
|
55
|
+
| `invalidFileGrant` | 400 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
56
|
+
| `invalidFilter` | 400 | `FilterQueryError` | no | yes | `document/filterMeta.ts` |
|
|
57
|
+
| `invalidIdentity` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
58
|
+
| `invalidInject` | 500 | `InjectError` | no | yes | `service/injectError.ts` |
|
|
59
|
+
| `invalidInput` | 400 | `InvalidInputError` | no | yes | `constant/invalidInputError.ts` |
|
|
60
|
+
| `invalidInsightQuery` | 400 | `InsightQueryError` | yes | yes | `service/insightQueryError.ts` |
|
|
61
|
+
| `invalidKey` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
62
|
+
| `invalidMessage` | 400 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
63
|
+
| `invalidParam` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
|
|
64
|
+
| `invalidPrompt` | 500 | `PromptError` | no | yes | `signal/mcp/promptError.ts` |
|
|
65
|
+
| `invalidQuery` | 500 | `DocumentStoreError` | no | yes | `service/documentStoreError.ts` |
|
|
66
|
+
| `invalidRoute` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
67
|
+
| `invalidRscResponse` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
68
|
+
| `invalidSchema` | 500 | `DocumentStoreError` | no | yes | `service/documentStoreError.ts` |
|
|
69
|
+
| `invalidSignal` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
70
|
+
| `invalidStorageKey` | 400 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
71
|
+
| `ipcRequired` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
72
|
+
| `jobStalled` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
73
|
+
| `listFailed` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
74
|
+
| `liveAlreadySet` | 500 | `SignalDeclarationError` | no | yes | `signal/signalDeclarationError.ts` |
|
|
75
|
+
| `livePaused` | 409 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
76
|
+
| `liveRoomLimit` | 429 | `LiveRoomLimitError` | yes | yes | `service/liveRoomLimitError.ts` |
|
|
77
|
+
| `liveRoomTaken` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
78
|
+
| `locked` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
|
|
79
|
+
| `logControlUnavailable` | 503 | `LogControlUnavailableError` | no | yes | `server/logging/logTailClient.ts` |
|
|
80
|
+
| `missingFilterQuery` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
81
|
+
| `missingInput` | 400 | `InvalidInputError` | no | yes | `constant/invalidInputError.ts` |
|
|
82
|
+
| `missingModel` | 500 | `SignalDeclarationError` | no | yes | `signal/signalDeclarationError.ts` |
|
|
83
|
+
| `missingSlice` | 500 | `SignalDeclarationError` | no | yes | `signal/signalDeclarationError.ts` |
|
|
84
|
+
| `noHandler` | 500 | `SignalContractError` | no | yes | `signal/signalContractError.ts` |
|
|
85
|
+
| `notApplied` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
|
|
86
|
+
| `notFound` | 404 | `Exception.NotFound` | yes | no | `signal/exception.ts` |
|
|
87
|
+
| `notFound` | 404 | `ImageOptimizerError` | no | yes | `server/imageOptimizerError.ts` |
|
|
88
|
+
| `notFound` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
|
|
89
|
+
| `notInitialized` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
90
|
+
| `notInitialized` | 500 | `InjectError` | no | yes | `service/injectError.ts` |
|
|
91
|
+
| `notRegistered` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
92
|
+
| `notRegistered` | 500 | `InjectError` | no | yes | `service/injectError.ts` |
|
|
93
|
+
| `notRegistered` | 500 | `SignalContractError` | no | yes | `signal/signalContractError.ts` |
|
|
94
|
+
| `nullableLastArg` | 500 | `SignalDeclarationError` | no | yes | `signal/signalDeclarationError.ts` |
|
|
95
|
+
| `payloadTooLarge` | 413 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
96
|
+
| `payloadTooLarge` | 413 | `ImageOptimizerError` | no | yes | `server/imageOptimizerError.ts` |
|
|
97
|
+
| `planChanged` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
|
|
98
|
+
| `redisUriMissing` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
99
|
+
| `remoteOAuth` | 502 | `RemoteError` | no | yes | `server/remote/remoteError.ts` |
|
|
100
|
+
| `remoteProtocol` | 502 | `RemoteError` | no | yes | `server/remote/remoteError.ts` |
|
|
101
|
+
| `remoteTooLarge` | 502 | `RemoteError` | no | yes | `server/remote/remoteError.ts` |
|
|
102
|
+
| `remoteUnauthorized` | 401 | `RemoteError` | no | yes | `server/remote/remoteError.ts` |
|
|
103
|
+
| `remoteUnavailable` | 502 | `RemoteError` | no | yes | `server/remote/remoteError.ts` |
|
|
104
|
+
| `remoteUrlRejected` | 502 | `RemoteError` | no | yes | `server/remote/remoteError.ts` |
|
|
105
|
+
| `renderAborted` | 499 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
106
|
+
| `routeConflict` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
107
|
+
| `routeNotFound` | 404 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
108
|
+
| `routeNotFound` | 404 | `RscRouteNotFound` | no | yes | `server/rscClient.tsx` |
|
|
109
|
+
| `routerNotReady` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
110
|
+
| `rpcDisposed` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
111
|
+
| `rscFetchFailed` | 502 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
112
|
+
| `rscQueueOverflow` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
113
|
+
| `rscRedirectStarted` | 303 | `RscRedirectNavigationStarted` | no | yes | `server/rscClient.tsx` |
|
|
114
|
+
| `rscWorkerFailed` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
115
|
+
| `rscWorkerStopped` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
116
|
+
| `searchMisconfigured` | 500 | `DocumentStoreError` | no | yes | `service/documentStoreError.ts` |
|
|
117
|
+
| `searchUnavailable` | 500 | `DocumentStoreError` | no | yes | `service/documentStoreError.ts` |
|
|
118
|
+
| `secretRefused` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
119
|
+
| `secretStoreUnavailable` | 503 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
120
|
+
| `serviceUnavailable` | 503 | `ImageOptimizerError` | no | yes | `server/imageOptimizerError.ts` |
|
|
121
|
+
| `shutdownTimeout` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
122
|
+
| `stageFailed` | 500 | `StageFailedError` | no | yes | `server/di/stageFailedError.ts` |
|
|
123
|
+
| `storageNotShared` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
124
|
+
| `tableMissing` | 500 | `DocumentStoreError` | no | yes | `service/documentStoreError.ts` |
|
|
125
|
+
| `tooManyRequests` | 429 | `Exception` | yes | no | `signal/exception.ts` |
|
|
126
|
+
| `transferUnsupported` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
127
|
+
| `unauthorized` | 401 | `Exception.Unauthorized` | yes | no | `signal/exception.ts` |
|
|
128
|
+
| `undefinedReturn` | 500 | `SignalContractError` | no | yes | `signal/signalContractError.ts` |
|
|
129
|
+
| `unencodableValue` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
130
|
+
| `unguardedEndpoint` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
131
|
+
| `unmaskedResource` | 500 | `PromptError` | no | yes | `signal/mcp/promptError.ts` |
|
|
132
|
+
| `unroutableLiveQuery` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
133
|
+
| `unstorableValue` | 400 | `DocumentStoreError` | no | yes | `service/documentStoreError.ts` |
|
|
134
|
+
| `unsupportedMediaType` | 415 | `Exception.UnsupportedMediaType` | yes | no | `signal/exception.ts` |
|
|
135
|
+
| `usage` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
|
|
136
|
+
| `verifyFailed` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
|
|
137
|
+
| `wrongTransport` | 500 | `SignalContractError` | no | yes | `signal/signalContractError.ts` |
|
|
138
|
+
| set when thrown | set when thrown | `Err` | yes | yes | `common/err.ts` |
|
|
139
|
+
| set when thrown | set when thrown | `Err.BadRequest` | yes | yes | `common/err.ts` |
|
|
140
|
+
| set when thrown | set when thrown | `Err.Conflict` | yes | yes | `common/err.ts` |
|
|
141
|
+
| set when thrown | set when thrown | `Err.Forbidden` | yes | yes | `common/err.ts` |
|
|
142
|
+
| set when thrown | set when thrown | `Err.NotFound` | yes | yes | `common/err.ts` |
|
|
143
|
+
| set when thrown | set when thrown | `Err.Unauthorized` | yes | yes | `common/err.ts` |
|
|
144
|
+
|
|
145
|
+
## Codes by status
|
|
146
|
+
|
|
147
|
+
An error coded by its status, such as an `Exception`, takes its code from `AkanError.codeOfStatus`:
|
|
148
|
+
|
|
149
|
+
| Status | Code | Reason |
|
|
150
|
+
|---|---|---|
|
|
151
|
+
| 400 | `badRequest` | Bad Request |
|
|
152
|
+
| 401 | `unauthorized` | Unauthorized |
|
|
153
|
+
| 403 | `forbidden` | Forbidden |
|
|
154
|
+
| 404 | `notFound` | Not Found |
|
|
155
|
+
| 409 | `conflict` | Conflict |
|
|
156
|
+
| 413 | `payloadTooLarge` | Payload Too Large |
|
|
157
|
+
| 415 | `unsupportedMediaType` | Unsupported Media Type |
|
|
158
|
+
| 429 | `tooManyRequests` | Too Many Requests |
|
|
159
|
+
| 500 | `internalError` | Internal Server Error |
|
|
160
|
+
| 502 | `badGateway` | Bad Gateway |
|
|
161
|
+
| 503 | `serviceUnavailable` | Service Unavailable |
|
|
162
|
+
| 504 | `gatewayTimeout` | Gateway Timeout |
|
|
163
|
+
|
|
164
|
+
Any other status is coded `http<status>`, with the reason `Internal Server Error` from 500 and `Request Failed`
|
|
165
|
+
below it.
|
|
@@ -63,7 +63,8 @@ Use this whenever generating constants or scalar constants. It defines the curre
|
|
|
63
63
|
- **Do not declare `Upload` as a model field.** `Upload` is a signal-body-only primitive. Declare an image/file
|
|
64
64
|
field as a relation to `File`: `image: field(File).optional()` for one, `images: field([File])` for many.
|
|
65
65
|
- The store then auto-generates an `upload<Field>On<Model>(fileList)` action that calls the framework upload
|
|
66
|
-
mutation and polls file status until it leaves `"uploading"` (`
|
|
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.
|
|
@@ -255,10 +264,12 @@ export default page()
|
|
|
255
264
|
the tool's `outputSchema` even on a failure — and a JSON-RPC error holds `data.code`, which tells apart what
|
|
256
265
|
`-32602` files together: `unknownTool`, `invalidArgument`, `unknownPrompt`, `unknownResource` and a screen's
|
|
257
266
|
refusal, beside `tooManyRequests` and `internalError`. The code is the one an HTTP caller gets: a domain `Err`'s
|
|
258
|
-
dictionary key (what `Err.is` matches), else the `AkanError`'s own code; a 401 or
|
|
267
|
+
dictionary key (what `Err.is` matches), else the `AkanError`'s own code; a guard's 401 or 403 by its status alone
|
|
259
268
|
(`unauthorized`, `forbidden`), since a guard's own code names its rule as its message does; a crash, or a 5xx whose
|
|
260
|
-
|
|
261
|
-
|
|
269
|
+
answer names no bounded code, by its status (`internalError`). A 5xx's text is redacted but its code token is not,
|
|
270
|
+
and it comes from the error's own JSON when that carries one, which can be a third-party library's. A code is a
|
|
271
|
+
bounded key or camelCase token, never prose. No host hands `_meta` to the model, so what the model must act on
|
|
272
|
+
belongs in the dictionary sentence.
|
|
262
273
|
- **Three revisions are spoken**: the modern `2026-07-28` and the legacy `2025-11-25` / `2025-06-18`, which are
|
|
263
274
|
wire-identical over the POST-only surface this implements — a client whose proposal is not listed is told to
|
|
264
275
|
disconnect. An unknown proposal is answered at whichever end of that list it is closer to, and an unimplemented
|
|
@@ -488,6 +499,19 @@ export default page()
|
|
|
488
499
|
- `option.setMcp({ apps: false })` / `AKAN_MCP_APPS=false` publishes no page tools: no app is published and every
|
|
489
500
|
prompt stays a prompt only. `web: { csr: false }` publishes the app tools with no view, and an API-only build
|
|
490
501
|
(`web: false`) has no pages to publish.
|
|
502
|
+
- **`{ static: true }` sends the app as HTML to a host that runs no view.** `.app(name, description, load,
|
|
503
|
+
{ static: true })` marks the tool `_meta["akanjs/static"]: true` wherever the server renders pages, view or not. A
|
|
504
|
+
`tools/call` whose `params._meta["akanjs/render"]` is `"html"` then gets, after the usual blocks, an embedded
|
|
505
|
+
`text/html` resource `ui://<app>/static/<name>`: one document drawn under the caller's credential after the route
|
|
506
|
+
guards, with the load under the same query-only rule — the element inside the root layout's `McpAppRoot` (no
|
|
507
|
+
`_overrides.tsx`), the layout's theme as `data-theme`, `<base href="<web origin>/" target="_blank">`, the stylesheet
|
|
508
|
+
as an absolute link, every Suspense boundary resolved in place, and no `<script>`: no view, no Flight payload,
|
|
509
|
+
nothing runs. Mark an app static only when its server render is the whole picture — nothing hydrates, so a client
|
|
510
|
+
component shows its first state and a button does nothing.
|
|
511
|
+
- **A static app sends no HTML, and the call answers as if none was asked** (with a server warning), when the guards
|
|
512
|
+
refuse, the drawing fails or passes 1 MB, the body is empty or a fallback stands in for content, or a component needs
|
|
513
|
+
a browser: `lazy(…, { ssr: false })` says so itself, and a component whose look only a browser finishes (a canvas, a
|
|
514
|
+
chart drawn in an effect, data read after mount) calls `needsBrowser()` from `akanjs/webkit` while it renders.
|
|
491
515
|
|
|
492
516
|
## Progress Reporting
|
|
493
517
|
**`McpProgress.report(n, { total, message })`** reports progress from anywhere inside a call, a service or adapter
|
|
@@ -495,6 +519,202 @@ frames down included, and is a no-op when nobody is streaming — so the same co
|
|
|
495
519
|
websocket, and in tests. `McpProgress.streaming` says whether anyone is reading, for a report whose message
|
|
496
520
|
costs something to assemble.
|
|
497
521
|
|
|
522
|
+
## Calling The Catalogue In-Process — `AgentToolsRole`
|
|
523
|
+
|
|
524
|
+
A server-side agent loop or a queue job reaches the same catalogue with no token and no loopback request:
|
|
525
|
+
`plug(AgentToolsRole)` in a service, then `listAs(account, { allow })` for the tools a model is offered and
|
|
526
|
+
`callAs(account, { id, name, args })` to run one. It adds every `mcp: "agent"` entry, and everything above still
|
|
527
|
+
holds — `mcp: false`, the exclusions, `readOnly`, `Person`, the account guards, masking and the refusal text — and
|
|
528
|
+
the call's `origin` is `"mcp"`, so `isAgentCall` and `.with(AgentCall)` treat it as an agent's. `allow` only
|
|
529
|
+
narrows. It is built from the DI registry, so a batch server, which mounts no `/mcp`, has it too; the per-caller
|
|
530
|
+
`/mcp` budget does not apply, an endpoint's own `rateLimit` does. A tool's failure never throws: it comes back as
|
|
531
|
+
the result's `error` and `code`. An adaptor may plug the role too. Neither method works before the server has built
|
|
532
|
+
its endpoints, so a call from an `onInit` throws `InjectError` `notInitialized`; call from a request, a job or a
|
|
533
|
+
schedule. A page's `page().app()` tools are left out: `/mcp` `tools/list` shows them, `listAs` does not, and `callAs` answers `Unknown tool`.
|
|
534
|
+
|
|
535
|
+
- **The account is trusted as given.** It is put on the call after the middleware chain, so pass one the server
|
|
536
|
+
resolved, never client input, and resolve a stored one again before reusing it: a revoked session is not noticed.
|
|
537
|
+
Its `machine` field is removed, since only a verified machine token may set one.
|
|
538
|
+
- **`headers` are forwarded without `authorization`, `cookie` and `origin`**; `ip` is what `getClientIp()` and an
|
|
539
|
+
ip-scoped `rateLimit` read, unknown by default.
|
|
540
|
+
|
|
541
|
+
## A Server Agent Loop — `agentService.loop`
|
|
542
|
+
|
|
543
|
+
`this.agentService.loop(request)` runs a model over that catalogue until it answers, with no browser — a queued
|
|
544
|
+
task, a scheduled run, a reply to a mention. It is an async iterable of `text`, `toolCall`, `toolResult`, `usage`,
|
|
545
|
+
`compacted` and `awaiting` events that ends in exactly one `done { stop }` or `error`, and it waits for the consumer
|
|
546
|
+
at every event.
|
|
547
|
+
|
|
548
|
+
- **Who it acts as.** `account` is a snapshot the server resolved; `principal` is a stored id that
|
|
549
|
+
`option.setAgentAccountResolver((principal) => account | null)` resolves at the start and before every round, so
|
|
550
|
+
a revoked one ends the run as `"unauthorized"`, as does a missing or falsy `account`: there is no anonymous run.
|
|
551
|
+
Neither is ever client input. The model is offered `allow` ∩ what
|
|
552
|
+
the account sees on `/mcp`, and a call to a name that round did not list is answered as an unknown tool, neither
|
|
553
|
+
asked about nor run. A request with no `allow` array is an `error`.
|
|
554
|
+
- **Toolkits.** `toolkits: { calendar: { description, tools } }` groups names of `allow` so a round need not carry
|
|
555
|
+
every tool. A tool in no toolkit is listed every round, beside one more, `openToolkit({ name })`, whose description
|
|
556
|
+
lists the toolkits. An opened toolkit's tools are listed from the next round on; `openToolkit` never reaches
|
|
557
|
+
`approve` and counts as no tool call. A resume reopens what stored calls and a summary's `toolkits` opened.
|
|
558
|
+
- **The open screen's tools.** `clientTools` takes `new AgentClientTools().list()` from a page the member has open
|
|
559
|
+
(`akanjs/ui`), sent over your own transport. It is client input: a name an endpoint holds is dropped, every one
|
|
560
|
+
counts as a write whatever `readOnly` it was sent with, and past 128 tools, 200,000 characters of definitions or
|
|
561
|
+
64 levels of nesting the run ends with `agent.error.clientToolsRefused` (413, `data.limit` `"tools"`, `"chars"` or
|
|
562
|
+
`"depth"`). Which of them may run after a read is the app's to say, in `approve`, by name. The run never runs one:
|
|
563
|
+
`approve` is asked, then the run ends `awaiting` with `client: true`. Have the page `run(call)` and resume with
|
|
564
|
+
what it returned as `answer` — or `answer: { id, error }` when no page answers. The page keeps its own rule beside
|
|
565
|
+
the run's: `run(call)` asks the member through `host.approve` when a call that changes something follows a `taint:
|
|
566
|
+
"source"` read. The run's rule below is the wider one, counting every result, the page's included, so with no
|
|
567
|
+
`approve` a client call is refused once the run has read anything; an `approve` that allows a client call leaves
|
|
568
|
+
that question to the page.
|
|
569
|
+
- **Asking the member.** `ask: true` lists `askUser({ question, choices?, multiple? })`, the in-page chat's own tool.
|
|
570
|
+
A call ends the run `awaiting` with `question: true`; put the question to the member and resume with
|
|
571
|
+
`answer: { id, result }` — or `{ id, error }` when they dismiss it. It never reaches `approve`, counts as no tool
|
|
572
|
+
call, and `untrusted` never sees the answer. A `clientTools` entry by that name is dropped.
|
|
573
|
+
- **Answering a parked call.** `answer` is the only way in for what a client sends, and `messages` holds only your
|
|
574
|
+
own user messages and what `onMessage` handed over: never append a client's result to them. Never take `messages`
|
|
575
|
+
from a request either: store what `onMessage` hands out, and pass from the client only `answer`, as a tool message
|
|
576
|
+
a client wrote reads exactly like one the run stored. Pass `answer` only after an `awaiting` event with `client`
|
|
577
|
+
or `question` named that call. `approve` is not asked about an answered call, as nothing runs on the server, so an
|
|
578
|
+
answer given for a call `approve` deferred, or for one a run died before parking on, is stored as it stands. A run
|
|
579
|
+
parks on one call, the first of its last batch that nothing answered, so `answer` is accepted for that call alone
|
|
580
|
+
and only when it is a client tool's or `askUser`'s. The run names the result after the call, whatever name was
|
|
581
|
+
sent, hands it to `onMessage`, emits it as a `toolResult` and runs the calls the batch has left. Every part of it
|
|
582
|
+
is bounded: `result`, `error` and `changes` as one value are clipped at 20,000 characters like a tool's result,
|
|
583
|
+
`code` is kept only when it is a failure code, and of its `attachments` the first four carrying `data` or `text`
|
|
584
|
+
are kept, never a `url`. An endpoint tool's call is answered only by running it: an `answer` naming one, a call
|
|
585
|
+
the run has not reached, or a call already answered ends the run with `agent.error.answerRefused` before anything
|
|
586
|
+
runs, and a resume without it carries on. Only `askUser`'s answer is the member's own word; a client tool's always
|
|
587
|
+
taints the run, by the rule below. A call parked with `connect` takes one answer only, the user's refusal as
|
|
588
|
+
`{ id, error }`; see "Calling Another Server".
|
|
589
|
+
- **Other servers.** `remotes` takes other MCP servers, each a toolkit named after it: none is listed or contacted
|
|
590
|
+
until the model opens it, and its tools then read `<name>.<tool>`. See "Calling Another Server" below.
|
|
591
|
+
- **Writes after a read.** What a tool returns may be text someone else wrote, so the run is tainted from the first
|
|
592
|
+
result of a call that ran — an endpoint tool's or a client tool's, an error included — and every later call
|
|
593
|
+
reaches `approve(call, { tainted, tool, client })` with `tainted` set, and `client: true` when the call is to a
|
|
594
|
+
page's tool. `askUser`'s answer, `openToolkit`'s and a call the run refused without running taint nothing. A
|
|
595
|
+
remote is the exception on each count: opening one taints the run, and so does any call into one, refused or not,
|
|
596
|
+
whatever `untrusted` returns and with none given. A batch is judged before it runs, since the model wrote it
|
|
597
|
+
before reading its results. Without `approve`, a `needsConfirm`
|
|
598
|
+
tool — on this catalogue, a mutation with the `destructive` hint above — is refused, and so is every write once
|
|
599
|
+
tainted: such a run writes only in the batch written before any result, and a later write is answered with the
|
|
600
|
+
code `writeAfterRead` and a sentence naming the two ways on. Pass `approve` to decide those calls, or pass
|
|
601
|
+
`untrusted(result)` to say which endpoint results carry another party's text: `(result) => !own.has(result.name)`
|
|
602
|
+
trusts the endpoints you name, and `() => false` trusts every endpoint result, which is right only when nothing
|
|
603
|
+
they return was written by anyone but the app and the member. No endpoint option says whose text a tool returns —
|
|
604
|
+
`readOnly` says only that it changes nothing — so the predicate is where that is declared. It is never asked about
|
|
605
|
+
a client tool's answer, which taints the run whatever it is named: a page may lend a tool under the name of an
|
|
606
|
+
endpoint this run does not list, and a predicate reading names would trust it. Only `approve` lets a write follow
|
|
607
|
+
a page's answer. `"defer"` holds the whole batch, emits `awaiting` and ends the run as `"awaiting"`.
|
|
608
|
+
- **Resuming.** Store each message `onMessage` hands over — it is awaited, and a retried run may hand one over twice
|
|
609
|
+
— and call `loop` again with them. A stored result is read as the answer to the call its id names, under that
|
|
610
|
+
call's name. It is judged as an endpoint's only when that call names an endpoint this run lists: any other, a
|
|
611
|
+
page's tool, a remote's, the open of a remote or a tool this run no longer has, taints the run without asking
|
|
612
|
+
`untrusted`, whatever mark it was stored with. The run's own answer to a tool name the model made up,
|
|
613
|
+
`Unknown tool: <name>.` with nothing beside it, taints nothing, and neither does its own sentence for a connection
|
|
614
|
+
the user refused. Keep `ask`, `toolkits` and `remotes` the same for
|
|
615
|
+
the life of a transcript: a stored `askUser` or `openToolkit` answer is the run's own only under the options it
|
|
616
|
+
was given with, and one whose name the page lends taints. Trailing calls nothing answered go to `approve` again before any model call, and the taint is rebuilt from
|
|
617
|
+
the `tainted` marks on stored messages and by re-applying `untrusted`, which sees a result whole during the run
|
|
618
|
+
and clipped on a resume; with no `untrusted` every stored tool result taints, a refusal included, as a resume
|
|
619
|
+
cannot tell one from a result. Store every message whole, marks included. `compacted` says the first `replaced`
|
|
620
|
+
messages are now `summary`; its `tainted` marker stands in for the results it replaced, and a summary with no
|
|
621
|
+
marker counts as tainted. A batch's results reach `onMessage` one tool message a call, as each call finishes, so a
|
|
622
|
+
resume runs only the calls that had not finished, even after a crash mid-batch. It cannot tell a call that was
|
|
623
|
+
running when the run died from one that never started: both go to `approve` again and run again, so a write that
|
|
624
|
+
must not land twice needs an idempotent endpoint or an `approve` that defers it. A stored result of that batch
|
|
625
|
+
which `untrusted` marks taints them too: a resume judges on everything stored, where an uninterrupted run judges a
|
|
626
|
+
batch before any of it runs.
|
|
627
|
+
- **Metering.** Each model call, compactions included, is its own turn for the request policy, the quota and the
|
|
628
|
+
usage hook. It gets a fresh `id`, `loop { id, round }`, a copy of the request's `meta` — server-set, so it may key
|
|
629
|
+
billing — empty headers and no ip. The relay's default size caps skip loop rounds, except in a run that lists
|
|
630
|
+
`clientTools` or names `remotes`: its turns carry `loop.client` or `loop.remote`, and one past
|
|
631
|
+
`AgentRelayPolicy.defaultLimits` ends the run with `agent.error.requestRefused`. A refused quota ends the run as
|
|
632
|
+
`"quota"`.
|
|
633
|
+
- **Limits.** `maxRounds` (12), `budget { tokens, toolCalls, wallMs }` (`"budget"`), `signal` (`"aborted"`) and a
|
|
634
|
+
provider cut (`"length"`). A limit that is not a valid number is an `error` before any model call. `wallMs` and
|
|
635
|
+
`signal` also end a run waiting on a tool or on `approve`. `callAs` cannot cancel a call, so the run stops waiting
|
|
636
|
+
and answers it with an error saying it may still finish; a resume does not run it again, and the endpoint runs on
|
|
637
|
+
with its outcome unreported. There is no preamble unless `preamble` gives one; with no `instructions` either, a
|
|
638
|
+
short neutral prompt stands in, as each adaptor's own fallback is about a screen. `compact { at, keep }` summarizes
|
|
639
|
+
the head, and a tool result is capped at 20,000 characters as the browser caps it. Its calls carry no ip, so an
|
|
640
|
+
ip-scoped `rateLimit` counts them under one unknown address.
|
|
641
|
+
- **A refusal for length.** With `compact` set, a round whose call fails as `agent.error.contextOverflow` compacts
|
|
642
|
+
regardless of `at` and asks once more, as one round; a second refusal, or nothing to cut, ends the run with the
|
|
643
|
+
error. An adaptor with its own size cap throws that error with `{ limit, requested }` in its own unit, bytes
|
|
644
|
+
included, and the run lowers `at` to where that request would have fit.
|
|
645
|
+
|
|
646
|
+
## Calling Another Server — `remotes`
|
|
647
|
+
|
|
648
|
+
The other direction: an agent running here calls another server's `/mcp` as the signed-in user. The other server needs
|
|
649
|
+
no change; any akan app is one already, and so is any MCP server that speaks OAuth 2.1 with dynamic registration.
|
|
650
|
+
|
|
651
|
+
```ts
|
|
652
|
+
// lib/option.ts — off by default, since it lets a signed-in user make this server call an address they name
|
|
653
|
+
export const option = new AkanOption<ModulesOptions>().transformEnv((env) => ({ ...env, remote: { enabled: true } }));
|
|
654
|
+
|
|
655
|
+
// a service that runs the loop
|
|
656
|
+
const remotes = this.remoteService.sources(account, [
|
|
657
|
+
{ name: "shop", url: project.serverUrl, description: "Orders and refunds of the shop this project runs." },
|
|
658
|
+
]);
|
|
659
|
+
for await (const event of this.agentService.loop({ account, allow, messages, remotes, approve, onMessage })) {
|
|
660
|
+
if (event.type === "awaiting" && event.connect) /* tell the page: this run waits for a connection to event.connect */;
|
|
661
|
+
}
|
|
662
|
+
```
|
|
663
|
+
|
|
664
|
+
- **A connection is the user's own OAuth grant at the other server.** `libs/shared`'s `remote` service registers this
|
|
665
|
+
app there once, sends the user to that server's consent page, and keeps the tokens sealed on the server. The other
|
|
666
|
+
server judges every call by its own guards, as it judges any agent's, so `Person` endpoints stay closed. Accounts
|
|
667
|
+
are never matched across servers.
|
|
668
|
+
- **Connecting happens in the chat.** Opening a remote the account has no connection to ends the run `awaiting` with
|
|
669
|
+
`connect: "<name>"` and leaves the call unanswered. Render `<Remote.Util.Connect url={…} onConnected={resume} />`:
|
|
670
|
+
it opens the other server's sign-in in a window and calls back once `page/remote/callback` finished the exchange.
|
|
671
|
+
Resume with the stored messages and no `answer`, and the run opens the toolkit itself. When the user declines,
|
|
672
|
+
resume with `answer: { id, error }` for that call. The `error` only says that they refused: the run stores a
|
|
673
|
+
sentence of its own naming the remote, coded `remoteDeclined`, as the open's result and goes on, and none of your
|
|
674
|
+
text reaches the model or `onMessage`. That sentence taints neither this run nor a later resume, while the error
|
|
675
|
+
of an open that failed still does. The stored messages do not say why a run stopped at an open, so a refusal is
|
|
676
|
+
taken for any first unanswered open of a remote, one in a batch `approve` deferred included: all it does is keep
|
|
677
|
+
that open from running, and the rest of the batch is judged as usual. An `answer` carrying a `result` for an open
|
|
678
|
+
is refused with
|
|
679
|
+
`agent.error.answerRefused`, as only the server sees whether a connection exists.
|
|
680
|
+
- **What a remote lists and returns is another party's text.** Opening a remote taints the run, whatever `untrusted`
|
|
681
|
+
says and with none given: its tools' names, descriptions and schemas reach the model with the open, and so does
|
|
682
|
+
the error of an open that failed. A resume reads it off the stored call, mark or no mark: a stored result of a
|
|
683
|
+
`<name>.<tool>` call, or of an `openToolkit` call that names a remote, taints unasked. An open that only asks the
|
|
684
|
+
user to connect taints nothing. A call's arguments leave for that server,
|
|
685
|
+
and `readOnly` is the remote's own word for its tool, so a request with `remotes` and no `approve` is refused
|
|
686
|
+
before any model call, as `base.error.requiredArgument` naming `approve`: pass one with `remotes`. It is told the
|
|
687
|
+
target as `state.remote`, and hears a tool the remote does not call read-only as a `needsConfirm` one. Show the
|
|
688
|
+
user that server's name and the arguments before allowing a write: a record on one server can ask the model to
|
|
689
|
+
write to another.
|
|
690
|
+
- **Names.** A remote's `name` is `[a-z][A-Za-z0-9]{0,15}` and may not be a toolkit's. A tool name too long or with
|
|
691
|
+
characters a provider refuses is listed under a shortened alias and still called by its real name. A run takes
|
|
692
|
+
at most 120 tools from one remote, a description to 1,000 characters and a parameter schema to 8,000, and stops
|
|
693
|
+
listing at 120,000 characters in all; the open's result counts the tools left out as `omitted`. Pass `allow` in
|
|
694
|
+
the remote's entry to choose which tools those are. A run keeps at most four remotes open, as each listing rides
|
|
695
|
+
every later round: the open of a fifth is answered with an error and that server is not contacted. Of a call's
|
|
696
|
+
result the run keeps `result`, `error`, `code`, `changes` and `attachments`, each bounded as the parts of an
|
|
697
|
+
`answer` are, and nothing else the remote sent; the run's rounds meet the relay's size caps (see Metering).
|
|
698
|
+
- **Addresses.** `url` is the server's address or its MCP endpoint; a bare origin means `/mcp`. Every request goes
|
|
699
|
+
through `RemoteFetch`: https only, no private address, no redirect, the checked address pinned. A local run
|
|
700
|
+
(`operationMode: "local"`) reaches loopback over http, so two dev servers can connect; `remote.allowUrl` narrows
|
|
701
|
+
the addresses an app accepts.
|
|
702
|
+
- **A screen in the result.** When the called tool is a `page().app()`, the `toolResult` event carries `view`
|
|
703
|
+
(`{ remote, tool, args, href?, static?, resourceUri? }`) beside the result, without an `href` or `resourceUri`
|
|
704
|
+
longer than 2,048 characters. It never reaches the model or `onMessage`; store it yourself and draw `<Remote.Zone.Screen url tool={view.tool} args={view.args} href={view.href}
|
|
705
|
+
drawn={view.static} />`. For an app the other server declared `{ static: true }` the card asks `remoteScreen` for
|
|
706
|
+
that server's script-less HTML when it scrolls into view and shows it in a frame that runs no script; for any other
|
|
707
|
+
app, draw `<Remote.Zone.View url tool args uri={view.resourceUri} href />`: it frames that server's view (its
|
|
708
|
+
client bundle) with scripts on but no origin, under a policy that lets it load only from that server and connect
|
|
709
|
+
nowhere, and relays the view's own calls to that one server through `McpAppHost` (`akanjs/webkit`). A view cannot
|
|
710
|
+
write into the model's context, and a link it opens must stay on its server. Neither card stores what it drew: the
|
|
711
|
+
HTML and the view's data are fetched again on every draw, since what the user may see there can change. A view
|
|
712
|
+
weighs over a megabyte, so prefer `{ static: true }` on the other server for anything a person only reads.
|
|
713
|
+
- **Not published onward.** The connection endpoints take `Person` and are `mcp: false`, and remote tools exist only
|
|
714
|
+
inside the run: an outside agent connected to this app's `/mcp` never reaches a user's other servers through it.
|
|
715
|
+
|
|
716
|
+
Without `libs/shared`, build each entry from `RemoteSource` (`akanjs/server`) with your own `access { token, renew }`.
|
|
717
|
+
|
|
498
718
|
## Rolling MCP Out To An App
|
|
499
719
|
|
|
500
720
|
The goal of exposing a service over MCP is that a person uses it through an agent instead of through the page:
|
|
@@ -60,7 +60,12 @@ body shape — this is the full contract behind them. Before changing route beha
|
|
|
60
60
|
`.guard()` throws when the module loads. `fn` receives the route's typed arguments and `lang` (a layout's gets no
|
|
61
61
|
`children`) and may be `async`. It refuses by moving the router — `router.redirect(href)`, `router.notFound()` — or
|
|
62
62
|
with `getSelf({ unauthorize })`; `signedIn()` from `@libs/shared/webkit` is that last one, called inside an arrow
|
|
63
|
-
(`.guard(() => signedIn())`), because `.guard(signedIn)` would
|
|
63
|
+
(`.guard(() => signedIn())`), because `.guard(signedIn)` would take the route's arguments as its option.
|
|
64
|
+
- **A guard's second argument `{ path }` is where the visitor was going** — the in-app path with its search, as
|
|
65
|
+
`router.push` takes it (`undefined` while MCP lists the screen): `.guard((_, { path }) => signedIn({ path }))`
|
|
66
|
+
sends a refused visitor to `/signin?redirect=<path>`. Build a redirect target from it, never an admission rule —
|
|
67
|
+
CSR asks a guard again only when the route or an argument it declared moves. Hand it only to `router.push` or
|
|
68
|
+
`router.redirect`: it can be a raw `//host`, which `window.location` would follow off the site.
|
|
64
69
|
- **On the server every guard of the chain runs before any layout body starts**, root layout first and before the
|
|
65
70
|
route's arguments are checked, so a redirect is a real 307 even after an awaited query, and a not-found is a 404 —
|
|
66
71
|
where a `getSelf({ unauthorize })` inside a layout body under a `.loading()` redirects late after I/O, inside the
|
|
@@ -119,6 +124,10 @@ body shape — this is the full contract behind them. Before changing route beha
|
|
|
119
124
|
`property`, and a canonical / manifest / icon link, and keeps the rest — so a page states only what it changes.
|
|
120
125
|
- A canonical link and `og:url` each name one URL, so a page carries them only from its own `.head()`, never from a
|
|
121
126
|
layout's.
|
|
127
|
+
- A level that writes `og:image` or `twitter:image` drops the `og:image:*` / `twitter:image:*` tags it inherits, and a
|
|
128
|
+
`<meta name="theme-color">` a `.head()` writes replaces the root `.viewport({ themeColor })`'s. Only `.head()`
|
|
129
|
+
merges: a `<title>` or `<meta>` written inside a component renders beside the merged head, so a second `<title>`
|
|
130
|
+
can reach the document.
|
|
122
131
|
- **A not-found or error view titles itself**: the `<title>` and `<meta>` at the top of what a layout's `.notFound()`
|
|
123
132
|
/ `.error()` returns replace the layouts' head, and the page's own head is dropped. Under a `.loading()` the head is
|
|
124
133
|
already out, so they stay in the view.
|
|
@@ -129,7 +129,9 @@ this is the full contract behind them.
|
|
|
129
129
|
server has one database, so it covers every model, hooks and query-level writes included; a nested call joins the
|
|
130
130
|
outer one, with no savepoint. Cache, `memory` and outside calls are not in it — hand them to
|
|
131
131
|
`this.afterCommit(fn)`, run once the commit lands, never after a rollback, at once outside one; one that throws is
|
|
132
|
-
logged, never thrown, and the rest still run. On SQLite it holds the only write turn:
|
|
132
|
+
logged, never thrown, and the rest still run. On SQLite it holds the only write turn: another request's write
|
|
133
|
+
waits until it ends, its read does not and sees the last commit. Keep it short, and never await inside it a write
|
|
134
|
+
started outside it.
|
|
133
135
|
`@Transaction()` is deprecated.
|
|
134
136
|
|
|
135
137
|
## Text Search In A Filter — `q.search()`
|