@akanjs/cli 3.2.0-rc.30 → 3.2.0-rc.31
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/.build-stamp
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
1
|
+
7e96f6e93d6860f1c8b06526922e78b36e623dd40f403807b3ed13251b2e9965
|
|
2
|
+
ba19f3f2-8ac0-4f9c-93cf-eed60de5e15e
|
|
@@ -120,7 +120,7 @@ Only on `page()`:
|
|
|
120
120
|
|
|
121
121
|
```ts
|
|
122
122
|
.prompt(name: string, description: string)
|
|
123
|
-
.app<Name extends string>(name: Name & FreeName<Name, Record<never, never>>, description: string, load: (args: RouteBaseArgs) => PromiseOrObject<ReactNode
|
|
123
|
+
.app<Name extends string>(name: Name & FreeName<Name, Record<never, never>>, description: string, load: (args: RouteBaseArgs) => PromiseOrObject<ReactNode>, option?: { static?: boolean; })
|
|
124
124
|
```
|
|
125
125
|
|
|
126
126
|
On `layout()` and `rootLayout()`, where a line replaces its shared form above:
|
|
@@ -95,6 +95,12 @@ Generated from the akanjs sources of this release: every code a framework error
|
|
|
95
95
|
| `payloadTooLarge` | 413 | `ImageOptimizerError` | no | yes | `server/imageOptimizerError.ts` |
|
|
96
96
|
| `planChanged` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
|
|
97
97
|
| `redisUriMissing` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
98
|
+
| `remoteOAuth` | 502 | `RemoteError` | no | yes | `server/remote/remoteError.ts` |
|
|
99
|
+
| `remoteProtocol` | 502 | `RemoteError` | no | yes | `server/remote/remoteError.ts` |
|
|
100
|
+
| `remoteTooLarge` | 502 | `RemoteError` | no | yes | `server/remote/remoteError.ts` |
|
|
101
|
+
| `remoteUnauthorized` | 401 | `RemoteError` | no | yes | `server/remote/remoteError.ts` |
|
|
102
|
+
| `remoteUnavailable` | 502 | `RemoteError` | no | yes | `server/remote/remoteError.ts` |
|
|
103
|
+
| `remoteUrlRejected` | 502 | `RemoteError` | no | yes | `server/remote/remoteError.ts` |
|
|
98
104
|
| `renderAborted` | 499 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
99
105
|
| `routeConflict` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
100
106
|
| `routeNotFound` | 404 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
@@ -499,6 +499,19 @@ export default page()
|
|
|
499
499
|
- `option.setMcp({ apps: false })` / `AKAN_MCP_APPS=false` publishes no page tools: no app is published and every
|
|
500
500
|
prompt stays a prompt only. `web: { csr: false }` publishes the app tools with no view, and an API-only build
|
|
501
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.
|
|
502
515
|
|
|
503
516
|
## Progress Reporting
|
|
504
517
|
**`McpProgress.report(n, { total, message })`** reports progress from anywhere inside a call, a service or adapter
|
|
@@ -550,6 +563,8 @@ at every event.
|
|
|
550
563
|
A call ends the run `awaiting` with `question: true`; put the question to the member, append
|
|
551
564
|
`{ id, name: "askUser", result }` — or an `error` when they dismiss it — and resume. It never reaches `approve`,
|
|
552
565
|
counts as no tool call, and `untrusted` never sees the answer. A `clientTools` entry by that name is dropped.
|
|
566
|
+
- **Other servers.** `remotes` takes other MCP servers, each a toolkit named after it: none is listed or contacted
|
|
567
|
+
until the model opens it, and its tools then read `<name>.<tool>`. See "Calling Another Server" below.
|
|
553
568
|
- **Writes after untrusted input.** `untrusted(result)` marks a result third parties wrote, and every later call
|
|
554
569
|
reaches `approve(call, { tainted, tool })` with `tainted` set. A batch is judged before it runs, since the model
|
|
555
570
|
wrote it before reading its results. Without `approve`, a `needsConfirm` tool — on this catalogue, a mutation
|
|
@@ -580,6 +595,66 @@ at every event.
|
|
|
580
595
|
error. An adaptor with its own size cap throws that error with `{ limit, requested }` in its own unit, bytes
|
|
581
596
|
included, and the run lowers `at` to where that request would have fit.
|
|
582
597
|
|
|
598
|
+
## Calling Another Server — `remotes`
|
|
599
|
+
|
|
600
|
+
The other direction: an agent running here calls another server's `/mcp` as the signed-in user. The other server needs
|
|
601
|
+
no change; any akan app is one already, and so is any MCP server that speaks OAuth 2.1 with dynamic registration.
|
|
602
|
+
|
|
603
|
+
```ts
|
|
604
|
+
// lib/option.ts — off by default, since it lets a signed-in user make this server call an address they name
|
|
605
|
+
export const option = new AkanOption<ModulesOptions>().transformEnv((env) => ({ ...env, remote: { enabled: true } }));
|
|
606
|
+
|
|
607
|
+
// a service that runs the loop
|
|
608
|
+
const remotes = this.remoteService.sources(account, [
|
|
609
|
+
{ name: "shop", url: project.serverUrl, description: "Orders and refunds of the shop this project runs." },
|
|
610
|
+
]);
|
|
611
|
+
for await (const event of this.agentService.loop({ account, allow, messages, remotes, approve, onMessage })) {
|
|
612
|
+
if (event.type === "awaiting" && event.connect) /* tell the page: this run waits for a connection to event.connect */;
|
|
613
|
+
}
|
|
614
|
+
```
|
|
615
|
+
|
|
616
|
+
- **A connection is the user's own OAuth grant at the other server.** `libs/shared`'s `remote` service registers this
|
|
617
|
+
app there once, sends the user to that server's consent page, and keeps the tokens sealed on the server. The other
|
|
618
|
+
server judges every call by its own guards, as it judges any agent's, so `Person` endpoints stay closed. Accounts
|
|
619
|
+
are never matched across servers.
|
|
620
|
+
- **Connecting happens in the chat.** Opening a remote the account has no connection to ends the run `awaiting` with
|
|
621
|
+
`connect: "<name>"` and leaves the call unanswered. Render `<Remote.Util.Connect url={…} onConnected={resume} />`:
|
|
622
|
+
it opens the other server's sign-in in a window and calls back once `page/remote/callback` finished the exchange.
|
|
623
|
+
Resume with the stored messages and the run opens the toolkit itself. When the user declines, append
|
|
624
|
+
`{ id, name: "openToolkit", error }` for that call and resume.
|
|
625
|
+
- **What a remote lists and returns is another party's text.** Opening a remote taints the run, whatever `untrusted`
|
|
626
|
+
says: its tools' names, descriptions and schemas reach the model with the open, and so does the error of an open
|
|
627
|
+
that failed. An open that only asks the user to connect taints nothing. A call's arguments leave for that server,
|
|
628
|
+
and `readOnly` is the remote's own word for its tool, so a request with `remotes` and no `approve` is refused
|
|
629
|
+
before any model call, as `base.error.requiredArgument` naming `approve`: pass one with `remotes`. It is told the
|
|
630
|
+
target as `state.remote`, and hears a tool the remote does not call read-only as a `needsConfirm` one. Show the
|
|
631
|
+
user that server's name and the arguments before allowing a write: a record on one server can ask the model to
|
|
632
|
+
write to another.
|
|
633
|
+
- **Names.** A remote's `name` is `[a-z][A-Za-z0-9]{0,15}` and may not be a toolkit's. A tool name too long or with
|
|
634
|
+
characters a provider refuses is listed under a shortened alias and still called by its real name. A run takes
|
|
635
|
+
at most 120 tools from one remote, a description to 1,000 characters and a parameter schema to 8,000, and stops
|
|
636
|
+
listing at 120,000 characters in all; the open's result counts the tools left out as `omitted`. Pass `allow` in
|
|
637
|
+
the remote's entry to choose which tools those are.
|
|
638
|
+
- **Addresses.** `url` is the server's address or its MCP endpoint; a bare origin means `/mcp`. Every request goes
|
|
639
|
+
through `RemoteFetch`: https only, no private address, no redirect, the checked address pinned. A local run
|
|
640
|
+
(`operationMode: "local"`) reaches loopback over http, so two dev servers can connect; `remote.allowUrl` narrows
|
|
641
|
+
the addresses an app accepts.
|
|
642
|
+
- **A screen in the result.** When the called tool is a `page().app()`, the `toolResult` event carries `view`
|
|
643
|
+
(`{ remote, tool, args, href?, static?, resourceUri? }`) beside the result. It never reaches the model or
|
|
644
|
+
`onMessage`; store it yourself and draw `<Remote.Zone.Screen url tool={view.tool} args={view.args} href={view.href}
|
|
645
|
+
drawn={view.static} />`. For an app the other server declared `{ static: true }` the card asks `remoteScreen` for
|
|
646
|
+
that server's script-less HTML when it scrolls into view and shows it in a frame that runs no script; for any other
|
|
647
|
+
app, draw `<Remote.Zone.View url tool args uri={view.resourceUri} href />`: it frames that server's view (its
|
|
648
|
+
client bundle) with scripts on but no origin, under a policy that lets it load only from that server and connect
|
|
649
|
+
nowhere, and relays the view's own calls to that one server through `McpAppHost` (`akanjs/webkit`). A view cannot
|
|
650
|
+
write into the model's context, and a link it opens must stay on its server. Neither card stores what it drew: the
|
|
651
|
+
HTML and the view's data are fetched again on every draw, since what the user may see there can change. A view
|
|
652
|
+
weighs over a megabyte, so prefer `{ static: true }` on the other server for anything a person only reads.
|
|
653
|
+
- **Not published onward.** The connection endpoints take `Person` and are `mcp: false`, and remote tools exist only
|
|
654
|
+
inside the run: an outside agent connected to this app's `/mcp` never reaches a user's other servers through it.
|
|
655
|
+
|
|
656
|
+
Without `libs/shared`, build each entry from `RemoteSource` (`akanjs/server`) with your own `access { token, renew }`.
|
|
657
|
+
|
|
583
658
|
## Rolling MCP Out To An App
|
|
584
659
|
|
|
585
660
|
The goal of exposing a service over MCP is that a person uses it through an agent instead of through the page:
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@akanjs/cli",
|
|
3
|
-
"version": "3.2.0-rc.
|
|
3
|
+
"version": "3.2.0-rc.31",
|
|
4
4
|
"sourceType": "module",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"publishConfig": {
|
|
@@ -39,7 +39,7 @@
|
|
|
39
39
|
"@earendil-works/pi-tui": "1.3.0",
|
|
40
40
|
"@inquirer/prompts": "^8.7.3",
|
|
41
41
|
"@tailwindcss/node": "^4.3.3",
|
|
42
|
-
"akanjs": "3.2.0-rc.
|
|
42
|
+
"akanjs": "3.2.0-rc.31",
|
|
43
43
|
"chalk": "^6.0.1",
|
|
44
44
|
"commander": "^15.0.0",
|
|
45
45
|
"dayjs": "^1.11.23",
|
package/skills/akan-mcp/SKILL.md
CHANGED
|
@@ -42,6 +42,9 @@ an endpoint with a real guard is published, one with none is refused, and so is
|
|
|
42
42
|
groups of `allow` back until the model calls `openToolkit`; `clientTools` (from `AgentClientTools` on an open page)
|
|
43
43
|
parks a call as `awaiting { client: true }` for the page to run; `ask: true` lists `askUser`, which parks as
|
|
44
44
|
`awaiting { question: true }` until you append the member's answer.
|
|
45
|
+
- `remotes: this.remoteService.sources(account, [{ name, url, description }])` (`libs/shared`, `remote.enabled`) lets
|
|
46
|
+
the loop call another server's `/mcp` as the user: each is a toolkit, tools read `<name>.<tool>`, a missing
|
|
47
|
+
connection parks as `awaiting { connect: name }` for `<Remote.Util.Connect>`, and every remote result taints the run.
|
|
45
48
|
|
|
46
49
|
## Verify
|
|
47
50
|
|