@akanjs/cli 3.2.0-rc.10 → 3.2.0-rc.11

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
- ed1a6034368b9b93d8a0752b2a6e180f3b595501bede5d0f3a9c914c47ced5b4
2
- 5eed55b1-b5b5-4198-84af-6e928a89dc1a
1
+ a94d99eccb3bb4d4970ad614e92679e27275a624eb2bd66ad85987aa9867e817
2
+ 97453604-5b94-4b93-a557-33d9131fb1cf
@@ -237,6 +237,8 @@ method?: HttpMutationMethod;
237
237
  fileUpload?: boolean;
238
238
  /** `false` keeps it out of the MCP catalogue (default `true`); curation, not authorization — HTTP still serves it. */
239
239
  mcp?: boolean;
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
+ destructive?: boolean;
240
242
  /** The errors this endpoint throws on purpose, by status. */
241
243
  errors?: EndpointErrors;
242
244
  /** A slow subscriber of a `pubsub(Binary)`: `"coalesce"` (default) keeps only the newest frame per room, `"queue"` delivers every frame and grows the send buffer with the slowest subscriber. */
@@ -205,8 +205,11 @@ export default page()
205
205
  alike: the caller reads `You are not permitted to perform this action.`, because either sentence names your
206
206
  authorization structure to the one caller barred from it. A domain `Err` at any other status resolves through
207
207
  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
- and are not configurable. Clients are told to distrust hints; they are never a gate.
208
+ - The `readOnly` / `destructive` / `idempotent` hints a client renders are derived from the endpoint type and key.
209
+ A mutation named `remove`, `delete`, `purge`, `destroy`, `erase`, `wipe`, `drop`, `cancel`, `bulkRemove` or
210
+ `bulkDelete` is destructive; `destructive: true` or `false` on the endpoint overrides that, for an `archiveOrder`
211
+ no verb gives away. Clients are told to distrust hints; they are never a gate. `agentService.loop` does read this
212
+ one: it refuses a destructive tool unless `approve` allows it.
210
213
  - **`AKAN_MCP_READONLY=true` is the read-only-deployment valve, not the exposure switch.** It drops every mutation
211
214
  whatever it declared, and reports each one in the boot log like any other refusal. It also drops each `.prompt()`
212
215
  page's text tool, whose run renders the whole page; the prompts, the `.app()` tools and their views stay.
@@ -514,6 +517,45 @@ are left out: `/mcp` `tools/list` shows them, `listAs` does not, and `callAs` an
514
517
  - **`headers` are forwarded without `authorization`, `cookie` and `origin`**; `ip` is what `getClientIp()` and an
515
518
  ip-scoped `rateLimit` read, unknown by default.
516
519
 
520
+ ## A Server Agent Loop — `agentService.loop`
521
+
522
+ `this.agentService.loop(request)` runs a model over that catalogue until it answers, with no browser — a queued
523
+ task, a scheduled run, a reply to a mention. It is an async iterable of `text`, `toolCall`, `toolResult`, `usage`,
524
+ `compacted` and `awaiting` events that ends in exactly one `done { stop }` or `error`, and it waits for the consumer
525
+ at every event.
526
+
527
+ - **Who it acts as.** `account` is a snapshot the server resolved; `principal` is a stored id that
528
+ `option.setAgentAccountResolver((principal) => account | null)` resolves at the start and before every round, so
529
+ a revoked one ends the run as `"unauthorized"`, as does a missing or falsy `account`: there is no anonymous run.
530
+ Neither is ever client input. The model is offered `allow` ∩ what
531
+ the account sees on `/mcp`, and a call to a name that round did not list is answered as an unknown tool, neither
532
+ asked about nor run. A request with no `allow` array is an `error`.
533
+ - **Writes after untrusted input.** `untrusted(result)` marks a result third parties wrote, and every later call
534
+ reaches `approve(call, { tainted, tool })` with `tainted` set. A batch is judged before it runs, since the model
535
+ wrote it before reading its results. Without `approve`, a `needsConfirm` tool — on this catalogue, a mutation
536
+ with the `destructive` hint above — is refused, and so is every write once tainted. `"defer"` holds the whole batch, emits
537
+ `awaiting` and ends the run as `"awaiting"`.
538
+ - **Resuming.** Store each message `onMessage` hands over — it is awaited, and a retried run may hand one over twice —
539
+ and call `loop` again with them. Trailing calls nothing answered go to `approve` again before any model call, and
540
+ the taint is rebuilt from the `tainted` marks on stored messages and by re-applying `untrusted`, which sees a result
541
+ whole during the run and clipped on a resume. Store every message whole, marks included. `compacted` says the first
542
+ `replaced` messages are now `summary`; its `tainted` marker stands in for the results it replaced, and a summary
543
+ with no marker counts as tainted to a run with `untrusted`. A batch's results
544
+ reach `onMessage` even when the consumer stops reading or a later call throws, so a resume runs only calls that
545
+ never started.
546
+ - **Metering.** Each model call, compactions included, is its own turn for the request policy, the quota and the
547
+ usage hook. It gets a fresh `id`, `loop { id, round }`, a copy of the request's `meta` — server-set, so it may key
548
+ billing — empty headers and no ip. The relay's default size caps skip loop rounds; a refused quota ends the run as
549
+ `"quota"`.
550
+ - **Limits.** `maxRounds` (12), `budget { tokens, toolCalls, wallMs }` (`"budget"`), `signal` (`"aborted"`) and a
551
+ provider cut (`"length"`). A limit that is not a valid number is an `error` before any model call. `wallMs` and
552
+ `signal` also end a run waiting on a tool or on `approve`. `callAs` cannot cancel a call, so the run stops waiting
553
+ and answers it with an error saying it may still finish; a resume does not run it again, and the endpoint runs on
554
+ with its outcome unreported. There is no preamble unless `preamble` gives one; with no `instructions` either, a
555
+ short neutral prompt stands in, as each adaptor's own fallback is about a screen. `compact { at, keep }` summarizes
556
+ the head, and a tool result is capped at 20,000 characters as the browser caps it. Its calls carry no ip, so an
557
+ ip-scoped `rateLimit` counts them under one unknown address.
558
+
517
559
  ## Rolling MCP Out To An App
518
560
 
519
561
  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.10",
3
+ "version": "3.2.0-rc.11",
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.10",
42
+ "akanjs": "3.2.0-rc.11",
43
43
  "chalk": "^6.0.1",
44
44
  "commander": "^15.0.0",
45
45
  "dayjs": "^1.11.23",
@@ -36,6 +36,9 @@ an endpoint with a real guard is published, one with none is refused, and so is
36
36
 
37
37
  - `plug(AgentToolsRole)` gives a service `listAs(account, { allow })` / `callAs(account, call)`: the same catalogue
38
38
  and refusals in-process, batch servers included. Pass only an account the server resolved, never client input.
39
+ - `this.agentService.loop({ account | principal, allow, messages, approve, untrusted, onMessage, meta, budget })`
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`.
39
42
 
40
43
  ## Verify
41
44