@akanjs/cli 3.2.0-rc.20 → 3.2.0-rc.21

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
- 92e320cf984d412345d4cc31a07e2bc154bfd1699638d3d03ef09847901a68d4
2
- f82d46ad-7815-4ab4-b3ff-49cc0923eb30
1
+ 0474fbf53ddbc090a2ab91eedf6a2fe0250a06594cdf5028738bf1b37222cbbc
2
+ 8f7a3e07-5e28-43d8-8272-9e6ef6864daf
@@ -235,8 +235,8 @@ globalPrefix?: false;
235
235
  /** HTTP verb of a `mutation`, `POST` unless named; every other endpoint type ignores it. */
236
236
  method?: HttpMutationMethod;
237
237
  fileUpload?: boolean;
238
- /** `false` keeps it out of the MCP catalogue (default `true`); curation, not authorization — HTTP still serves it. */
239
- mcp?: boolean;
238
+ /** `false` keeps it out of the MCP catalogue (default `true`), and `"agent"` keeps it off `/mcp` while the in-process agent (`AgentToolsRole`, `agentService.loop`) still lists it; curation, not authorization — HTTP still serves it. */
239
+ mcp?: McpShelf;
240
240
  /** Overrides what the key implies for a `mutation`'s MCP `destructiveHint`: `true` for one no verb gives away, such as `archiveOrder`, `false` for a `drop…` that loses nothing. */
241
241
  destructive?: boolean;
242
242
  /** The errors this endpoint throws on purpose, by status. */
@@ -46,6 +46,10 @@ 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.
49
53
  - **`mcp: true` is the default and is a no-op**; write it only to say out loud that an entry is deliberately on
50
54
  the shelf. It does not override a shape refusal (an `Any` return stays refused) and it cannot publish something
51
55
  the guard rules keep out.
@@ -504,14 +508,14 @@ costs something to assemble.
504
508
 
505
509
  A server-side agent loop or a queue job reaches the same catalogue with no token and no loopback request:
506
510
  `plug(AgentToolsRole)` in a service, then `listAs(account, { allow })` for the tools a model is offered and
507
- `callAs(account, { id, name, args })` to run one. Everything above still holds — `mcp: false`, the exclusions,
508
- `readOnly`, `Person`, the account guards, masking and the refusal text — and the call's `origin` is `"mcp"`, so
509
- `isAgentCall` and `.with(AgentCall)` treat it as an agent's. `allow` only narrows. It is built from the DI
510
- registry, so a batch server, which mounts no `/mcp`, has it too; the per-caller `/mcp` budget does not apply, an
511
- endpoint's own `rateLimit` does. A tool's failure never throws: it comes back as the result's `error` and `code`.
512
- An adaptor may plug the role too. Neither method works before the server has built its endpoints, so a call from an
513
- `onInit` throws `InjectError` `notInitialized`; call from a request, a job or a schedule. A page's `page().app()` tools
514
- are left out: `/mcp` `tools/list` shows them, `listAs` does not, and `callAs` answers `Unknown tool`.
511
+ `callAs(account, { id, name, args })` to run one. It adds every `mcp: "agent"` entry, and everything above still
512
+ holds — `mcp: false`, the exclusions, `readOnly`, `Person`, the account guards, masking and the refusal text — and
513
+ the call's `origin` is `"mcp"`, so `isAgentCall` and `.with(AgentCall)` treat it as an agent's. `allow` only
514
+ narrows. It is built from the DI registry, so a batch server, which mounts no `/mcp`, has it too; the per-caller
515
+ `/mcp` budget does not apply, an endpoint's own `rateLimit` does. A tool's failure never throws: it comes back as
516
+ the result's `error` and `code`. An adaptor may plug the role too. Neither method works before the server has built
517
+ its endpoints, so a call from an `onInit` throws `InjectError` `notInitialized`; call from a request, a job or a
518
+ schedule. A page's `page().app()` tools are left out: `/mcp` `tools/list` shows them, `listAs` does not, and `callAs` answers `Unknown tool`.
515
519
 
516
520
  - **The account is trusted as given.** It is put on the call after the middleware chain, so pass one the server
517
521
  resolved, never client input, and resolve a stored one again before reusing it: a revoked session is not noticed.
@@ -532,6 +536,14 @@ at every event.
532
536
  Neither is ever client input. The model is offered `allow` ∩ what
533
537
  the account sees on `/mcp`, and a call to a name that round did not list is answered as an unknown tool, neither
534
538
  asked about nor run. A request with no `allow` array is an `error`.
539
+ - **Toolkits.** `toolkits: { calendar: { description, tools } }` groups names of `allow` so a round need not carry
540
+ every tool. A tool in no toolkit is listed every round, beside one more, `openToolkit({ name })`, whose description
541
+ lists the toolkits. An opened toolkit's tools are listed from the next round on; `openToolkit` never reaches
542
+ `approve` and counts as no tool call. A resume reopens what stored calls and a summary's `toolkits` opened.
543
+ - **The open screen's tools.** `clientTools` takes `new AgentClientTools().list()` from a page the member has open
544
+ (`akanjs/ui`), sent over your own transport. It is client input, and a name an endpoint holds is dropped. The run
545
+ never runs one: `approve` is asked, then the run ends `awaiting` with `client: true`. Have the page `run(call)`,
546
+ append its result — or your own error when no page answers — and resume.
535
547
  - **Writes after untrusted input.** `untrusted(result)` marks a result third parties wrote, and every later call
536
548
  reaches `approve(call, { tainted, tool })` with `tainted` set. A batch is judged before it runs, since the model
537
549
  wrote it before reading its results. Without `approve`, a `needsConfirm` tool — on this catalogue, a mutation
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@akanjs/cli",
3
- "version": "3.2.0-rc.20",
3
+ "version": "3.2.0-rc.21",
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.20",
42
+ "akanjs": "3.2.0-rc.21",
43
43
  "chalk": "^6.0.1",
44
44
  "commander": "^15.0.0",
45
45
  "dayjs": "^1.11.23",
@@ -13,7 +13,7 @@ an endpoint with a real guard is published, one with none is refused, and so is
13
13
 
14
14
  - `mcp: false` on an endpoint, or a `slice()` `mcp` map mirroring `guards`, keeps a perfectly guarded step (a UI
15
15
  state-machine step a model would only call by mistake) off the shelf. It is an opt-out; everything else still
16
- publishes.
16
+ publishes. `mcp: "agent"` keeps an entry off `/mcp` but listed to `AgentToolsRole` and `agentService.loop`.
17
17
  - `guards: [Every, Person]` reserves an act for a person; `.with(AgentCall)` narrows what an agent's call may do.
18
18
  - A guard's `static scope` decides whether a listing can hide the entry: `"account"` guards are evaluated per
19
19
  caller, `"resource"` guards stay visible and stop the call.
@@ -35,10 +35,12 @@ an endpoint with a real guard is published, one with none is refused, and so is
35
35
  ## Calling it from the server
36
36
 
37
37
  - `plug(AgentToolsRole)` gives a service `listAs(account, { allow })` / `callAs(account, call)`: the same catalogue
38
- and refusals in-process, batch servers included. Pass only an account the server resolved, never client input.
38
+ and refusals in-process plus the `mcp: "agent"` entries, batch servers included. Pass only an account the server resolved, never client input.
39
39
  - `this.agentService.loop({ account | principal, allow, messages, approve, untrusted, onMessage, meta, budget })`
40
40
  runs a model over those tools until it answers; `option.setAgentAccountResolver` resolves a stored `principal`
41
- before every round. Each round is metered as its own turn with `turn.loop` and `turn.meta`.
41
+ before every round. Each round is metered as its own turn with `turn.loop` and `turn.meta`. `toolkits` holds named
42
+ groups of `allow` back until the model calls `openToolkit`; `clientTools` (from `AgentClientTools` on an open page)
43
+ parks a call as `awaiting { client: true }` for the page to run.
42
44
 
43
45
  ## Verify
44
46