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

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
+ 0018601bd7b80c0a8f0b71960a59cf4fc033f87b77335b612f0d4f351f543d35
2
+ b32cfaf2-7c00-4a10-a90a-784494553fc4
@@ -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,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.
@@ -504,14 +510,14 @@ costs something to assemble.
504
510
 
505
511
  A server-side agent loop or a queue job reaches the same catalogue with no token and no loopback request:
506
512
  `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`.
513
+ `callAs(account, { id, name, args })` to run one. It adds every `mcp: "agent"` entry, and everything above still
514
+ holds — `mcp: false`, the exclusions, `readOnly`, `Person`, the account guards, masking and the refusal text — and
515
+ the call's `origin` is `"mcp"`, so `isAgentCall` and `.with(AgentCall)` treat it as an agent's. `allow` only
516
+ narrows. It is built from the DI registry, so a batch server, which mounts no `/mcp`, has it too; the per-caller
517
+ `/mcp` budget does not apply, an endpoint's own `rateLimit` does. A tool's failure never throws: it comes back as
518
+ the result's `error` and `code`. An adaptor may plug the role too. Neither method works before the server has built
519
+ its endpoints, so a call from an `onInit` throws `InjectError` `notInitialized`; call from a request, a job or a
520
+ schedule. A page's `page().app()` tools are left out: `/mcp` `tools/list` shows them, `listAs` does not, and `callAs` answers `Unknown tool`.
515
521
 
516
522
  - **The account is trusted as given.** It is put on the call after the middleware chain, so pass one the server
517
523
  resolved, never client input, and resolve a stored one again before reusing it: a revoked session is not noticed.
@@ -532,6 +538,14 @@ at every event.
532
538
  Neither is ever client input. The model is offered `allow` ∩ what
533
539
  the account sees on `/mcp`, and a call to a name that round did not list is answered as an unknown tool, neither
534
540
  asked about nor run. A request with no `allow` array is an `error`.
541
+ - **Toolkits.** `toolkits: { calendar: { description, tools } }` groups names of `allow` so a round need not carry
542
+ every tool. A tool in no toolkit is listed every round, beside one more, `openToolkit({ name })`, whose description
543
+ lists the toolkits. An opened toolkit's tools are listed from the next round on; `openToolkit` never reaches
544
+ `approve` and counts as no tool call. A resume reopens what stored calls and a summary's `toolkits` opened.
545
+ - **The open screen's tools.** `clientTools` takes `new AgentClientTools().list()` from a page the member has open
546
+ (`akanjs/ui`), sent over your own transport. It is client input, and a name an endpoint holds is dropped. The run
547
+ never runs one: `approve` is asked, then the run ends `awaiting` with `client: true`. Have the page `run(call)`,
548
+ append its result — or your own error when no page answers — and resume.
535
549
  - **Writes after untrusted input.** `untrusted(result)` marks a result third parties wrote, and every later call
536
550
  reaches `approve(call, { tainted, tool })` with `tainted` set. A batch is judged before it runs, since the model
537
551
  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.22",
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.22",
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