@oneie/sdk 0.17.4 → 0.17.6

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.
Files changed (118) hide show
  1. package/README.md +4 -0
  2. package/dist/.build-fingerprint +1 -0
  3. package/dist/age.d.ts +96 -0
  4. package/dist/age.d.ts.map +1 -0
  5. package/dist/age.js +487 -0
  6. package/dist/age.js.map +1 -0
  7. package/dist/billing.d.ts +244 -14
  8. package/dist/billing.d.ts.map +1 -1
  9. package/dist/billing.js +374 -55
  10. package/dist/billing.js.map +1 -1
  11. package/dist/blocks.d.ts +8 -4
  12. package/dist/blocks.d.ts.map +1 -1
  13. package/dist/blocks.js +17 -5
  14. package/dist/blocks.js.map +1 -1
  15. package/dist/client.d.ts.map +1 -1
  16. package/dist/client.js +8 -1
  17. package/dist/client.js.map +1 -1
  18. package/dist/edge/solve.d.ts +38 -0
  19. package/dist/edge/solve.d.ts.map +1 -0
  20. package/dist/edge/solve.js +334 -0
  21. package/dist/edge/solve.js.map +1 -0
  22. package/dist/edge/types.d.ts +216 -0
  23. package/dist/edge/types.d.ts.map +1 -0
  24. package/dist/edge/types.js +21 -0
  25. package/dist/edge/types.js.map +1 -0
  26. package/dist/edge/validate.d.ts +19 -0
  27. package/dist/edge/validate.d.ts.map +1 -0
  28. package/dist/edge/validate.js +89 -0
  29. package/dist/edge/validate.js.map +1 -0
  30. package/dist/edge.d.ts +9 -0
  31. package/dist/edge.d.ts.map +1 -0
  32. package/dist/edge.js +8 -0
  33. package/dist/edge.js.map +1 -0
  34. package/dist/fn-allowlist.d.ts +1 -1
  35. package/dist/fn-allowlist.d.ts.map +1 -1
  36. package/dist/fn-allowlist.js +14 -0
  37. package/dist/fn-allowlist.js.map +1 -1
  38. package/dist/gateway.d.ts +18 -1
  39. package/dist/gateway.d.ts.map +1 -1
  40. package/dist/gateway.js +77 -3
  41. package/dist/gateway.js.map +1 -1
  42. package/dist/generated/fn-map.d.ts +2 -2
  43. package/dist/generated/fn-map.d.ts.map +1 -1
  44. package/dist/generated/fn-map.js +114 -13
  45. package/dist/generated/fn-map.js.map +1 -1
  46. package/dist/generated/schemas/index.d.ts +2 -2
  47. package/dist/generated/schemas.d.ts +65 -23
  48. package/dist/generated/schemas.d.ts.map +1 -1
  49. package/dist/generated/schemas.js +32 -1
  50. package/dist/generated/schemas.js.map +1 -1
  51. package/dist/index.d.ts +1 -1
  52. package/dist/index.d.ts.map +1 -1
  53. package/dist/index.js +1 -1
  54. package/dist/index.js.map +1 -1
  55. package/dist/market.d.ts.map +1 -1
  56. package/dist/market.js +6 -0
  57. package/dist/market.js.map +1 -1
  58. package/dist/message-key.d.ts +20 -0
  59. package/dist/message-key.d.ts.map +1 -0
  60. package/dist/message-key.js +46 -0
  61. package/dist/message-key.js.map +1 -0
  62. package/dist/message-lock.d.ts +56 -0
  63. package/dist/message-lock.d.ts.map +1 -0
  64. package/dist/message-lock.js +157 -0
  65. package/dist/message-lock.js.map +1 -0
  66. package/dist/meta.d.ts +13 -0
  67. package/dist/meta.d.ts.map +1 -1
  68. package/dist/meta.js +11 -0
  69. package/dist/meta.js.map +1 -1
  70. package/dist/prices/vendors.d.ts +7 -0
  71. package/dist/prices/vendors.d.ts.map +1 -0
  72. package/dist/prices/vendors.js +229 -0
  73. package/dist/prices/vendors.js.map +1 -0
  74. package/dist/prices.d.ts +41 -0
  75. package/dist/prices.d.ts.map +1 -0
  76. package/dist/prices.js +79 -0
  77. package/dist/prices.js.map +1 -0
  78. package/dist/receiver-layers.d.ts +27 -1
  79. package/dist/receiver-layers.d.ts.map +1 -1
  80. package/dist/receiver-layers.js +85 -5
  81. package/dist/receiver-layers.js.map +1 -1
  82. package/dist/receivers.d.ts +1773 -103
  83. package/dist/receivers.d.ts.map +1 -1
  84. package/dist/receivers.js +1910 -179
  85. package/dist/receivers.js.map +1 -1
  86. package/dist/secrets-give.d.ts +120 -0
  87. package/dist/secrets-give.d.ts.map +1 -0
  88. package/dist/secrets-give.js +160 -0
  89. package/dist/secrets-give.js.map +1 -0
  90. package/dist/secrets-grant.d.ts +52 -0
  91. package/dist/secrets-grant.d.ts.map +1 -0
  92. package/dist/secrets-grant.js +55 -0
  93. package/dist/secrets-grant.js.map +1 -0
  94. package/dist/secrets-key.d.ts +20 -0
  95. package/dist/secrets-key.d.ts.map +1 -0
  96. package/dist/secrets-key.js +47 -0
  97. package/dist/secrets-key.js.map +1 -0
  98. package/dist/secrets-list.d.ts +169 -0
  99. package/dist/secrets-list.d.ts.map +1 -0
  100. package/dist/secrets-list.js +13 -0
  101. package/dist/secrets-list.js.map +1 -0
  102. package/dist/secrets-one-vault.d.ts +53 -0
  103. package/dist/secrets-one-vault.d.ts.map +1 -0
  104. package/dist/secrets-one-vault.js +78 -0
  105. package/dist/secrets-one-vault.js.map +1 -0
  106. package/dist/secrets.d.ts +204 -0
  107. package/dist/secrets.d.ts.map +1 -0
  108. package/dist/secrets.js +389 -0
  109. package/dist/secrets.js.map +1 -0
  110. package/dist/templates.js +6 -6
  111. package/dist/templates.js.map +1 -1
  112. package/dist/work-contract-grammar.json +77 -5
  113. package/dist/work-contract.d.ts +24 -0
  114. package/dist/work-contract.d.ts.map +1 -1
  115. package/dist/work-contract.js +55 -0
  116. package/dist/work-contract.js.map +1 -1
  117. package/package.json +42 -3
  118. package/src/generated/funs.json +1 -0
package/dist/receivers.js CHANGED
@@ -2,6 +2,48 @@ import { z } from "zod";
2
2
  import { AgentActionResponseSchema, AgentStatusResponseSchema, CapabilityItemSchema, PayResponseSchema, RegisterResponseSchema, StatsSchema, StepKind, WorkflowDiffSchema, } from "./schemas.js";
3
3
  import { FieldSchema, ResourceTypeSchema } from "./types.js";
4
4
  import { GroupEntitySchema } from "./generated/schemas/index.js";
5
+ import { PROVIDER_NAMES, REFUSALS, USED_REFUSALS } from "./secrets.js";
6
+ /**
7
+ * The work-contract pair, declared on every VALUE-MOVING receiver's request.
8
+ *
9
+ * `/api/ask` dispatches zod's PARSED body (receiver-envelope.ts validateReceiver),
10
+ * so a field a request schema does not name is stripped before the universal gate
11
+ * (one.ie/web resolvers/_shared.ts validateContractGate) ever runs. That gate
12
+ * REQUIRES a contract from an agent key on `VALUE_MOVING_RECEIVERS` — so a
13
+ * value-moving receiver that omits this pair demands a field it can never receive.
14
+ * Measured on production 2026-11-07 (text/agent-path.md walk 7): `market:escrow`
15
+ * and `checkout:create` answered `contract_required` with the contract in the body.
16
+ *
17
+ * `contractScope` is the namespaced name on purpose: five receivers already use a
18
+ * bare `scope` for a board filter / visibility / key scope. For a BARE KEY (a
19
+ * Bearer with no browser session — human- or agent-typed) the gate binds `agent`
20
+ * and `workspace` to the attested key (ctx.actorId / ctx.keyGroup) and resolves
21
+ * `granted` as the request INTERSECTED with (the bare-key ceiling ∪ the key's
22
+ * attested grant rows) — a caller names a scope, it never grants one. A
23
+ * value-moving capability (`signal:<receiver>` for a receiver declared
24
+ * `moves: "value"`) comes only from a `work_contract_grants` row the
25
+ * workspace owner wrote through `agents:approve`; without one the refusal is
26
+ * `grant_required`, naming the capability and that door. And the contract must
27
+ * NAME the receiver being called — `(signal (to "<receiver>"))` — or it is a decoy.
28
+ * Parity with the `moves: "value"` set: tests/unit/agents/value-moving-parity.test.ts.
29
+ */
30
+ const WORK_CONTRACT_FIELDS = {
31
+ contract: z.unknown().optional().describe("WORK-AST s-expression (JSON arrays) — `[\"contract\", [\"workflow\", name, [\"signal\", [\"to\", \"<this receiver>\"]], …]]`. Required from an agent key on a value-moving receiver, and it must name THIS receiver in a `signal` node; validated against the schema-generated grammar before the resolver runs (@oneie/sdk/work-contract)."),
32
+ contractScope: z.object({
33
+ agent: z.string().describe("Overridden server-side by the attested actor (ctx.actorId) for a bare key."),
34
+ workspace: z.string().describe("Overridden server-side for a bare key: at a value-moving receiver, the workspace the call moves value in (its declared movesIn field, else the caller's attested ownerSlug — exactly what the resolver debits); elsewhere the key's attested home."),
35
+ granted: z.array(z.string()).describe("Capabilities the contract may use (workflow:define · step:<kind> · track:mark · signal:<receiver> …). For a bare key this is a REQUEST: it is intersected with the bare-key ceiling plus the key's attested grant rows. A value-moving capability (signal:<receiver> for a `moves: \"value\"` receiver) is held only through an `agents:approve` row the workspace owner wrote — it cannot be self-granted here. step:sell is a step kind in the ceiling: a sell step only mints a checkout."),
36
+ }).optional().describe("The scope the contract is validated against. Must travel with `contract` (half a declaration is refused)."),
37
+ };
38
+ /**
39
+ * The workspace a SERVICE caller (the channels worker, shared gateway key) acts in.
40
+ * `/api/ask` reads it off the zod-PARSED payload, so a receiver that does not name it
41
+ * strips it, `ctx.ownerSlug` arrives undefined, and every chat workflow tool past
42
+ * workflow_list answered "workflow not found" (production chat, 2026-09-17). A session
43
+ * or world-key caller's own attested workspace always wins; the field is ignored there.
44
+ * Guard: packages/sdk/test/service-lane-slug.test.ts.
45
+ */
46
+ const SERVICE_SLUG = z.string().optional().describe("Workspace a service caller acts in. Ignored for a session or key caller — their attested workspace is used.");
5
47
  /**
6
48
  * Declare a receiver contract. Identity at runtime — its only job is to pin the
7
49
  * `Req`/`Res` generics so the catalog infers payload + outcome types.
@@ -60,6 +102,39 @@ const CARD_STEP_RESPONSE = z.object({
60
102
  step: z.string().optional(),
61
103
  error: z.string().optional(),
62
104
  });
105
+ /**
106
+ * The fields tasks:mine and tasks:everywhere answer beside `tasks` since they read the
107
+ * queue from RAM (tql-edge C10, text/tql-edge-todo.md § C10). Declared here because a
108
+ * receiver that pages, caps or reads a snapshot names its window in the response, every
109
+ * time — and `reason` had three readers branching on it while the contract denied it.
110
+ */
111
+ /**
112
+ * One row of the swap alias table (one.ie/web/src/lib/swap/assets.ts, text/swap-plan.md
113
+ * § The asset table) — what swap:quote resolved an alias to, and what can sign it.
114
+ */
115
+ const SWAP_ASSET = z.object({
116
+ alias: z.string().describe("Canonical alias, e.g. USDC@base"),
117
+ chain: z.string().describe("ethereum | base | arbitrum | solana | sui | bitcoin | hyperliquid"),
118
+ symbol: z.string().describe("Ticker"),
119
+ assetId: z.string().describe("1Click asset id this alias resolves to"),
120
+ decimals: z.number().describe("Base-unit decimals"),
121
+ contract: z.string().nullable().describe("EVM contract or Sui coin type; null for a native coin"),
122
+ signer: z.string().describe("browser = ONE's in-browser key can send it · external = send from any wallet to the deposit address · none = quote only"),
123
+ origin: z.boolean().describe("Can be swapped FROM (live)"),
124
+ destination: z.boolean().describe("Can be swapped TO"),
125
+ });
126
+ const SWAP_TX = z.object({ hash: z.string().describe("Tx hash"), explorerUrl: z.string().describe("Explorer link") });
127
+ const QUEUE_READ_FIELDS = {
128
+ total: z.number().optional().describe("Rows matching BEFORE `limit`. A FLOOR, not a count, whenever `truncatedTypes` is present"),
129
+ truncated: z.boolean().optional().describe("true = the answer is short: more rows than returned (raise limit, or use tasks:board) OR graph.json marks a type this read touched as cut (`truncatedTypes`)"),
130
+ truncatedTypes: z.array(z.string()).optional().describe("Graph types the RAM snapshot marks cut that this read touched (contract #13: the snapshot's `truncated` ∩ the funs' types). Absent = nothing was cut"),
131
+ asOf: z.string().optional().describe("When the task scan this answer reads was taken from TypeDB (ISO) — shared by every caller for up to 60 s (KV), so up to a minute behind a write. Never read-modify-write a row through this receiver: read it with tasks:board {tid, fresh:true}. `claimable` is a prediction as of this instant; tasks:claim decides"),
132
+ prose: z.literal("unavailable").optional().describe("notes/contextDocs could not be hydrated for this page (they are not in the RAM graph — one keyed read fetches them). Present = every `notes`/`contextDocs` here is MISSING, not empty"),
133
+ reason: z.enum(["no_subscriptions", "no_workspace_membership"]).optional().describe("Why an ok:true queue may be empty: `no_subscriptions` (tasks:mine — subscribe, or read the board directly) · `no_workspace_membership` (tasks:everywhere — the caller belongs to no workspace)"),
134
+ error: z.string().optional().describe("On ok:false: `upstream_unavailable` (no graph — `detail` says why) · `edge_fun_missing` (funs.json lacks a queue fun — `missing` names each) · `edge_ir_mismatch` · `budget` · `edge_solve_failed`. Never an empty queue in place of a reason"),
135
+ detail: z.string().optional(),
136
+ missing: z.array(z.object({ fun: z.string(), reason: z.string() })).optional().describe("edge_fun_missing: each fun the edge cannot solve and codegen's reason (e.g. not on prod)"),
137
+ };
63
138
  /**
64
139
  * The receiver catalog — one source of truth for capability. Object-literal keys
65
140
  * are always literal, so `keyof typeof RECEIVERS` yields the declared receiver
@@ -68,6 +143,45 @@ const CARD_STEP_RESPONSE = z.object({
68
143
  * Populated incrementally: C2 = spine + 21 `world:*` + `grant-capability`;
69
144
  * C4 = remaining families with metadata; C5 = the `meta:` family.
70
145
  */
146
+ /** The page settings `pages:edit` may write into `data.root.props` — the same
147
+ * keys Puck's root panel edits (one.ie/web/src/lib/puck/config.tsx ROOT_FIELDS).
148
+ * `""` clears a key. Closed on purpose: root also carries `theme`, which has
149
+ * its own door. */
150
+ // What `pages:create` / `pages:edit` say about the page they just wrote: the
151
+ // template-strength checks (lib/puck/template-strength.ts), so a meh page comes
152
+ // back with the fixes named in the same turn instead of looking like success.
153
+ const PAGE_QUALITY = z.object({
154
+ score: z.number(), max: z.number(),
155
+ missing: z.array(z.string()).describe("Checks the page fails — each has a line in `fix`"),
156
+ fix: z.record(z.string(), z.string()).describe("check → how to fix it"),
157
+ why: z.record(z.string(), z.array(z.string())).describe("check → the offending block ids and values (at most 5 per check)"),
158
+ factTokens: z.array(z.string()).optional().describe("`{{ns.key}}` / `[Fact]` tokens still in the copy. Each fills from the workspace's business facts at render; one with no fact DROPS its sentence. Write the real value where you know it."),
159
+ }).describe("Template-strength verdict on the stored page. Fix what `missing` names before calling it done.");
160
+ const PAGE_ROOT_PATCH = z.object({
161
+ description: z.string().max(500),
162
+ socialTitle: z.string().max(200),
163
+ ogImage: z.string().max(2000),
164
+ canonical: z.string().max(2000),
165
+ search: z.enum(["listed", "hidden", ""]),
166
+ chat: z.enum(["auto", "show", "panel", "hide", ""]),
167
+ dock: z.enum(["auto", "show", "hide", ""]),
168
+ siteHeader: z.enum(["auto", "hide", ""]),
169
+ siteFooter: z.enum(["auto", "hide", ""]),
170
+ }).partial().strict();
171
+ // One storefront price as products:create and products:update accept it. Every field
172
+ // the studio's ProductBuilder sends is declared, because the edge returns zod's PARSED
173
+ // output and strips the rest. `interval` is nullable: the editor loads a one-time price
174
+ // as `interval: null` and sends it back. `compare_at_amount` is the was-price (0255);
175
+ // commerce.ts compareAtColumn refuses one that is not above unit_amount.
176
+ const productPriceInput = z.object({
177
+ unit_amount: z.number(),
178
+ currency: z.string().optional(),
179
+ price_type: z.string().optional(),
180
+ interval: z.string().nullable().optional(),
181
+ nickname: z.string().optional(),
182
+ is_default: z.boolean().optional(),
183
+ compare_at_amount: z.number().nullable().optional(),
184
+ });
71
185
  export const RECEIVERS = {
72
186
  // ── Spine (non-world) — contracts only this cycle; route-wiring lands in C4 ──
73
187
  "agent:enroll": receiver({
@@ -122,25 +236,51 @@ export const RECEIVERS = {
122
236
  effect: "ask", cost: "free", reversible: false, idempotent: true, settles: "none", auth: "manage_workspace",
123
237
  examples: [{ agentId: "acme--research-agent", objectId: "0x5f3a" }],
124
238
  }),
125
- "agent:provision": receiver({
126
- receiver: "agent:provision",
127
- canonical: "agent:enroll",
128
- summary: "Zero-to-live in one unauthenticated call — register + workspace + publish agent + import skills + invite owner",
239
+ // ── agents:approve / agents:update — the attested grant store the work-contract gate reads ──
240
+ // A bare key (agent- or human-typed, no browser session) that calls a receiver
241
+ // declared `moves: "value"` must carry a contract naming `signal:<receiver>`, and
242
+ // that capability is held ONLY through a `work_contract_grants` row (migration
243
+ // 0370) keyed (workspace, actor, capability). This is the door that writes the
244
+ // row: a person's own session, controlling the workspace, never a bare key
245
+ // (requireHumanPresence) and never a workflow step. The gate reads the row
246
+ // (one.ie/web lib/contract-grants.ts) and refuses `grant_required` without it.
247
+ "agents:approve": receiver({
248
+ receiver: "agents:approve",
249
+ summary: "Workspace owner, in a signed-in session: grant a key's actor one value-moving capability for work contracts — `signal:<receiver>` for a receiver declared `moves: \"value\"` (market:escrow, wallet:transfer, wallet:send …). Written to work_contract_grants keyed (workspace, actor, capability); the universal gate reads the row and answers `grant_required` without it. Never a bare key, never a workflow step",
129
250
  request: () => z.object({
130
- name: z.string().optional(),
131
- agentName: z.string().optional(),
132
- content: z.string().optional(),
133
- skills: z.array(z.string()).optional(),
134
- invite: z.object({ email: z.string().email().optional(), role: z.string().optional() }).optional(),
135
- live: z.boolean().optional(),
251
+ actor: z.string().min(1).max(128).describe("The key's actor id — what `grant_required` names as `actor`, the same string verifyWorldKey attests as ctx.actorId"),
252
+ capability: z.string().min(1).max(128).describe("`signal:<receiver>` for a `moves: \"value\"` receiver. A capability that is not value-moving — a step kind, step:sell included (a sell step only mints a checkout), a plain signal — is refused `not_a_value_capability`: the bare-key ceiling already holds it"),
253
+ workspace: z.string().optional().describe("The workspace the grant lives under — `grant_required` prints it as `workspace`: for a call that names its target (wallet:transfer {workspace|from: X}, payout:set {workspace: X}) it is X, granted by X's owner; for a call from the key's OWN purse (market:escrow, a transfer with no field) it is the key's HOME — the group that homes the agent — granted by the home's owner. Defaults to the caller's own workspace. The caller must control it"),
136
254
  }),
137
255
  response: () => z.object({
138
- uid: z.string(),
139
- workspace: z.string(),
140
- apiKey: z.string(),
141
- inviteUrl: z.string().optional(),
256
+ ok: z.boolean(),
257
+ workspace: z.string().optional(),
258
+ actor: z.string().optional(),
259
+ capability: z.string().optional(),
260
+ grantedBy: z.string().optional().describe("The session's attested slug that wrote the row"),
261
+ error: z.string().optional().describe("unauthorized | approval_required (a bare key) | not_in_workflow | forbidden (the caller does not control `workspace`) | not_a_value_capability | no_db"),
262
+ }),
263
+ effect: "ask", auth: "manage_workspace", cost: "free", reversible: true, idempotent: true,
264
+ examples: [{ actor: "01a1b2b393c785de0503803b", capability: "signal:market:escrow" }],
265
+ }),
266
+ "agents:update": receiver({
267
+ receiver: "agents:update",
268
+ summary: "Workspace owner, in a signed-in session: archive a work-contract grant written by agents:approve — `status: \"revoked\"` sets revoked_at on the (workspace, actor, capability) row, the row is kept, and the gate stops honouring it on the next call. The verb is `update` because archiving is an update with a status; granting is agents:approve",
269
+ request: () => z.object({
270
+ actor: z.string().min(1).max(128).describe("The key's actor id the grant names"),
271
+ capability: z.string().min(1).max(128).describe("The capability to revoke, exactly as granted"),
272
+ status: z.literal("revoked").describe("The only status this door writes — a grant is re-armed by agents:approve, never here"),
273
+ workspace: z.string().optional().describe("The workspace the grant is scoped to; defaults to the caller's own. The caller must control it"),
274
+ }),
275
+ response: () => z.object({
276
+ ok: z.boolean(),
277
+ revoked: z.boolean().optional().describe("false when no live row matched — already revoked or never granted"),
278
+ workspace: z.string().optional(),
279
+ actor: z.string().optional(),
280
+ capability: z.string().optional(),
281
+ error: z.string().optional().describe("unauthorized | approval_required | not_in_workflow | forbidden | no_db"),
142
282
  }),
143
- effect: "ask", auth: "none", reversible: false, idempotent: false,
283
+ effect: "ask", auth: "manage_workspace", cost: "free", reversible: true, idempotent: true,
144
284
  }),
145
285
  "agent:bootstrap": receiver({
146
286
  receiver: "agent:bootstrap",
@@ -163,6 +303,8 @@ export const RECEIVERS = {
163
303
  }),
164
304
  "auth:agent": receiver({
165
305
  receiver: "auth:agent",
306
+ // auth (public) — task:01a128d6108e551f5966106b: the open agent sign-up door by design — handler reads only ctx.ip for its rate limit (resolvers/auth.ts:65-74); the pay/tools demos call it with no key.
307
+ auth: "public",
166
308
  canonical: "agent:enroll",
167
309
  // `wallet` is a PUBLIC receiving address the caller derived in its own process.
168
310
  // Nothing here generates keys. The address is stored on the TypeDB actor but NOT
@@ -180,6 +322,8 @@ export const RECEIVERS = {
180
322
  }),
181
323
  "agents:sync": receiver({
182
324
  receiver: "agents:sync",
325
+ // auth (member) — task:01a128d6108e551f5966106b: no handler (parity-baseline declaredNoHandler); syncs the CALLER's agent definitions — RECIPES.spine reaches it holding the key auth:agent minted.
326
+ auth: "member",
183
327
  surfaces: { mcp: { name: "sync_agent" } },
184
328
  summary: "Declare capability — sync agent definitions, skills, and memberships",
185
329
  // Accepts a single markdown body or a structured multi-agent world payload.
@@ -248,6 +392,8 @@ export const RECEIVERS = {
248
392
  }),
249
393
  "world:accept-client-invite": receiver({
250
394
  receiver: "world:accept-client-invite",
395
+ // auth (public) — task:01a128d6108e551f5966106b: the TOKEN is the credential: verifyInviteToken + single-use UPDATE (world-receivers.ts:1266-1278), ctx is ignored; the invitee is logged out by design (auth-plugins/invite-redeem.ts:371).
396
+ auth: "public",
251
397
  summary: "Redeem a client invite — creates the workspace owned by the invitee (single-use, replay-protected)",
252
398
  request: () => z.object({ token: z.string(), email: z.string().email().optional(), name: z.string().optional() }),
253
399
  response: () => z.object({ wsid: z.string(), slug: z.string(), owner: z.string(), parent: z.string() }),
@@ -463,7 +609,10 @@ export const RECEIVERS = {
463
609
  "visitor:promote": receiver({
464
610
  receiver: "visitor:promote",
465
611
  summary: "Promote a tracked anonymous visitor to a TypeDB actor (anon:<hash12>) so it surfaces in People; binds rung-1 visitor_hash→aid. Idempotent.",
466
- request: () => z.object({ visitorHash: z.string() }),
612
+ request: () => z.object({
613
+ visitorHash: z.string(),
614
+ workspace: z.string().optional().describe("The workspace the visitor visited — files them in THAT workspace's People instead of the caller's. Honoured only when the caller's authority reaches it (platform staff, or an owner above it), else reason 'forbidden'; 'no_activity' if the hash never visited it."),
615
+ }),
467
616
  response: () => z.object({
468
617
  ok: z.boolean(),
469
618
  aid: z.string().optional(),
@@ -480,6 +629,13 @@ export const RECEIVERS = {
480
629
  receiver: "visitor:identify",
481
630
  summary: "Every surface's front door to identify a visitor — mines free text, enriches by email, climbs the ladder, merges tenant-walled candidates, upserts the vCard.",
482
631
  request: () => z.object({
632
+ // The workspace the visitor arrived at. Channels (a service caller) names
633
+ // it here, and the ask route reads the service principal's workspace from
634
+ // the PARSED payload — undeclared, it was stripped, the caller had no
635
+ // workspace, and every email typed into a chat was refused before the
636
+ // resolver ran. A session caller's own slug still wins over this field.
637
+ slug: z.string().optional(),
638
+ group: z.string().optional(),
483
639
  email: z.string().optional(),
484
640
  phone: z.string().optional(),
485
641
  name: z.string().optional(),
@@ -487,6 +643,11 @@ export const RECEIVERS = {
487
643
  channel: z.string().optional(),
488
644
  sender: z.string().optional(),
489
645
  visitorHash: z.string().optional(),
646
+ // web's signature over exactly (visitorHash, slug) — one.ie/web
647
+ // lib/visitor-attest.ts. On the gateway lane and in a workflow step the
648
+ // workspace is a nominated value, so a visitorHash binds only behind this;
649
+ // undeclared, the edge would strip it and no chat browser would ever bind.
650
+ visitorAttest: z.string().optional(),
490
651
  freeText: z.string().optional(),
491
652
  source: z.enum(["door", "chat", "asked", "event"]),
492
653
  }),
@@ -1093,7 +1254,13 @@ export const RECEIVERS = {
1093
1254
  receiver: "tools:composio",
1094
1255
  summary: "Execute one connected Composio tool from a workflow `tool` step (config.composio)",
1095
1256
  request: () => z.object({ workspace: z.string().optional().describe("Workspace slug; defaults to the attested caller's"), tool: z.string().describe("Composio tool slug to execute"), args: z.record(z.string(), z.unknown()).optional().describe("Arguments passed to the tool") }),
1096
- response: () => z.object({ ok: z.boolean(), tool: z.string().optional(), result: z.unknown().optional(), error: z.string().optional() }),
1257
+ response: () => z.object({
1258
+ ok: z.boolean(), tool: z.string().optional(), result: z.unknown().optional(), error: z.string().optional(),
1259
+ reason: z.string().optional().describe("Why a call was refused: approval_required, over_limit, meter_unavailable"),
1260
+ write: z.boolean().optional().describe("The tool was classed a write (fail closed: anything not a clear read verb); from an API key a write answers approval_required"),
1261
+ withheld: z.array(z.string()).optional().describe("Paths of credential fields (access_token, refresh_token, client_secret, …) replaced with \"[withheld]\" before the result left the worker"),
1262
+ used: z.object({ today: z.number().optional(), perDay: z.number().optional() }).passthrough().optional().describe("The workspace's interim daily execute meter, UTC"),
1263
+ }),
1097
1264
  effect: "ask", auth: "manage_integrations", reversible: false, idempotent: false,
1098
1265
  examples: [{ workspace: "acme", tool: "GMAIL_SEND_EMAIL", args: { to: "x@y.com" } }],
1099
1266
  }),
@@ -1116,14 +1283,14 @@ export const RECEIVERS = {
1116
1283
  "endpoint:register": receiver({
1117
1284
  receiver: "endpoint:register",
1118
1285
  surfaces: { mcp: true },
1119
- summary: "Register (or update) one of the workspace's own https endpoints under a handle a workflow step can name. The url is SSRF-checked here and again on every call; a secret is sealed under the worker's envelope key and never returned.",
1286
+ summary: "Register (or update) one of the workspace's own https endpoints under a handle a workflow step can name. The url is SSRF-checked here and again on every call; a secret goes to THE OPENER (secrets/), which seals it to ONE's lock bound to this workspace, name and url — the web app keeps only a ref, never returns it, and cannot open it. A new url needs the secret again. Until the opener is deployed (no OPENER binding), a secret is sealed under the worker's envelope key exactly as before.",
1120
1287
  request: () => z.object({
1121
1288
  workspace: z.string().optional().describe("Group slug. Omit for your own. A scope REQUEST — refused when the authority walk says no, never swapped for your own."),
1122
1289
  name: z.string().describe("The handle a workflow step names. Lowercase letters, digits, `-` and `_`, 1–48 chars. Unique per workspace; re-registering the same name updates it in place so a live workflow keeps working."),
1123
1290
  url: z.string().describe("A public https address. Refused BY NAME — https_required · ip_literal · private_hostname · dns_unresolved · blocked_address — so a retry is informed."),
1124
1291
  method: z.enum(["GET", "POST", "PUT", "PATCH"]).optional().describe("Default POST. GET folds `input` into the query string; the others send it as a JSON body."),
1125
- authHeader: z.string().optional().describe("The header NAME the secret travels in, e.g. `Authorization` or `X-Api-Key`. The VALUE is `secret` and is stored sealed."),
1126
- secret: z.string().optional().describe("Your endpoint's own credential. Sealed AES-256-GCM under the worker's PII_ENVELOPE_KEY, opened into memory for one outbound header, never logged, never returned. Requires `authHeader`. Omitting it on a re-register KEEPS the existing secret rather than disarming it."),
1292
+ authHeader: z.string().optional().describe("The header NAME the secret travels in, e.g. `Authorization` or `X-Api-Key`. The VALUE is `secret`, held by the opener. Changing it on a re-register needs the secret again."),
1293
+ secret: z.string().optional().describe("Your endpoint's own credential. Handed to the opener, which seals it to ONE's lock bound to this workspace, name and url, opens it only to send a call to THAT url, and scrubs it from the answer; never logged, never returned. Requires `authHeader`. Omitting it on a re-register KEEPS the existing secret when the url and authHeader are unchanged; a new url (or authHeader) without it is refused `bad_request: a new url needs the secret again` — the opener never re-points a key."),
1127
1294
  returnMode: z.enum(["json", "url", "bytes"]).optional().describe("What the endpoint answers. `json` = the answer itself. `url` = a small JSON body naming a url, which is fetched under the SAME guard and filed to the media library. `bytes` = the asset itself, filed the same way. Default json."),
1128
1295
  timeoutMs: z.number().optional().describe("Per-call AbortSignal timeout. Default 20000, clamped to 1000–120000."),
1129
1296
  maxBytes: z.number().optional().describe("Response byte ceiling, enforced while reading — `content-length` is a claim and is not read. Default 5 MiB, clamped to 10 MiB."),
@@ -1637,6 +1804,8 @@ export const RECEIVERS = {
1637
1804
  // ── identity ──
1638
1805
  "identity:address": receiver({
1639
1806
  receiver: "identity:address",
1807
+ // auth (member) — task:01a128d6108e551f5966106b: handler reads no ctx (resolvers/billing.ts:115) but no anonymous caller exists: the SDK walletFor and the MCP tool both carry a key.
1808
+ auth: "member",
1640
1809
  surfaces: { mcp: true },
1641
1810
  summary: "Resolve an actor's wallet address",
1642
1811
  request: () => z.object({ uid: z.string() }),
@@ -1730,21 +1899,14 @@ export const RECEIVERS = {
1730
1899
  }),
1731
1900
  effect: "ask", auth: "public", cost: "free", idempotent: true,
1732
1901
  }),
1733
- // ── auth (human session) ──
1734
- // auth:sign-in killed (C7): Better Auth handles all human auth; signal/ask pipeline returns dissolved
1735
- "auth:sign-out": receiver({
1736
- receiver: "auth:sign-out",
1737
- summary: "End the current session",
1738
- request: () => z.object({}),
1739
- response: () => ok,
1740
- effect: "signal", idempotent: true,
1741
- }),
1742
1902
  // board:join killed (C7): no resolver, no route, no caller
1743
1903
  // agency:push:complete killed (C7): no resolver, no route, no caller
1744
1904
  // agency:friction killed (C7): no resolver, no route, no caller
1745
1905
  // ── groups ──
1746
1906
  "groups:join": receiver({
1747
1907
  receiver: "groups:join",
1908
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!gid || !uid) return { ok: false }` on ctx.ownerSlug (resolvers/groups.ts:125-126), then the discover walk for a non-public group.
1909
+ auth: "member",
1748
1910
  canonical: "world:request-access",
1749
1911
  surfaces: { mcp: true },
1750
1912
  summary: "Join a group",
@@ -1754,6 +1916,8 @@ export const RECEIVERS = {
1754
1916
  }),
1755
1917
  "groups:leave": receiver({
1756
1918
  receiver: "groups:leave",
1919
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!gid || !uid) return { ok: false }` on ctx.ownerSlug (resolvers/groups.ts:155-156).
1920
+ auth: "member",
1757
1921
  canonical: "world:remove-member",
1758
1922
  surfaces: { mcp: true },
1759
1923
  summary: "Leave a group",
@@ -1806,6 +1970,8 @@ export const RECEIVERS = {
1806
1970
  }),
1807
1971
  "groups:members": receiver({
1808
1972
  receiver: "groups:members",
1973
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!ctx.ownerSlug) throw forbidden` (resolvers/groups.ts:108).
1974
+ auth: "member",
1809
1975
  canonical: "world:list-actors",
1810
1976
  surfaces: { mcp: true },
1811
1977
  summary: "List a group's members",
@@ -1862,6 +2028,7 @@ export const RECEIVERS = {
1862
2028
  summary: "Funder only: approve a credits:request token — sets the requester's monthly budget to what it was when asked plus the amount, never past your own plan grant; replaying the same token changes nothing. The requester can never approve its own",
1863
2029
  request: () => z.object({
1864
2030
  token: z.string().min(10).max(4000).describe("The token credits:request returned (also in the inbox notice)."),
2031
+ ...WORK_CONTRACT_FIELDS,
1865
2032
  }),
1866
2033
  response: () => z.object({
1867
2034
  ok: z.boolean(),
@@ -1870,7 +2037,7 @@ export const RECEIVERS = {
1870
2037
  clamped: z.boolean().optional().describe("true when the approval was cut to the funder's own plan grant."),
1871
2038
  error: z.string().optional().describe("unauthorized | invalid_token | expired | not_the_funder | self_approval | recipient_moved | request_unavailable"),
1872
2039
  }),
1873
- effect: "ask", auth: "manage_clients", cost: "free", idempotent: true,
2040
+ effect: "ask", auth: "manage_clients", cost: "free", idempotent: true, moves: "value",
1874
2041
  }),
1875
2042
  "billing:clients": receiver({
1876
2043
  receiver: "billing:clients",
@@ -1896,6 +2063,8 @@ export const RECEIVERS = {
1896
2063
  // ── subscriptions ──
1897
2064
  "subscriptions:register": receiver({
1898
2065
  receiver: "subscriptions:register",
2066
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!actor) return forbidden` on ctx.ownerSlug (resolvers/subscriptions.ts:1092-1093).
2067
+ auth: "member",
1899
2068
  canonical: "world:subscribe",
1900
2069
  summary: "Subscribe to a receiver's events by tag",
1901
2070
  request: () => z.object({
@@ -1929,6 +2098,8 @@ export const RECEIVERS = {
1929
2098
  }),
1930
2099
  "world:announce": receiver({
1931
2100
  receiver: "world:announce",
2101
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!sender) return forbidden` (resolvers/subscriptions.ts:1143).
2102
+ auth: "member",
1932
2103
  summary: "Broadcast a tagged signal; the world fans it to every subscriber whose follow-tags intersect. reply:true also invokes up to 5 of the matched actors and returns their answers inline (repliesTruncated:true if more matched)",
1933
2104
  request: () => z.object({
1934
2105
  tags: z.array(z.string()),
@@ -1952,6 +2123,8 @@ export const RECEIVERS = {
1952
2123
  }),
1953
2124
  "world": receiver({
1954
2125
  receiver: "world",
2126
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!sender) return forbidden` (resolvers/subscriptions.ts:1078).
2127
+ auth: "member",
1955
2128
  summary: "THE door — say it once, the world decides. Routes a tagged signal via the ladder (learned path → staked subscribers → CEO); fan:'all' broadcasts to every matching subscriber instead. Address form world:<tag-expr> carries tags in the receiver. reply:true also invokes the resolved actor and returns its answer inline (single-actor routes only, not fan:'all')",
1956
2129
  request: () => z.object({
1957
2130
  tags: z.array(z.string()).optional(),
@@ -1975,6 +2148,8 @@ export const RECEIVERS = {
1975
2148
  }),
1976
2149
  "world:outcome": receiver({
1977
2150
  receiver: "world:outcome",
2151
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!sender) return forbidden` (resolvers/subscriptions.ts:1469).
2152
+ auth: "member",
1978
2153
  summary: "Close the routing loop with the RESULT: whoever consumed a route reports success/failure, moving the same tag→receiver paths the router reads — success marks, failure warns. Pass the actor id the route returned",
1979
2154
  request: () => z.object({
1980
2155
  tags: z.array(z.string()),
@@ -1995,6 +2170,8 @@ export const RECEIVERS = {
1995
2170
  }),
1996
2171
  "world:route": receiver({
1997
2172
  receiver: "world:route",
2173
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!sender) return forbidden` (resolvers/subscriptions.ts:1211).
2174
+ auth: "member",
1998
2175
  summary: "Route a tagged signal to THE handler via the ladder: learned tag-node path (follow_route) → staked subscribers (reputation-ranked) → CEO standing workflow; marks the delivery path so the next route is smarter. reply:true also invokes the resolved actor and returns its answer inline. decide:true instead answers the deterministic verdict { receiver, rung, reason } (reason: highway|classified|ceo) from the learned lane — a pure read, zero side effects, zero tokens; TypeQL twin: route_verdict (migration 0043)",
1999
2176
  request: () => z.object({
2000
2177
  tags: z.array(z.string()).optional(),
@@ -2021,6 +2198,8 @@ export const RECEIVERS = {
2021
2198
  }),
2022
2199
  "world:suggest-workflow": receiver({
2023
2200
  receiver: "world:suggest-workflow",
2201
+ // auth (member) — task:01a128d6108e551f5966106b: handler takes data.workspace when ctx.ownerSlug is absent and then skips its mismatch check (resolvers/subscriptions.ts:1382-1386) — an anonymous cross-workspace read; the door now refuses that caller.
2202
+ auth: "member",
2024
2203
  summary: "Rank staked workflows by tag match + earned track record (claw_paths), read-only — no delivery, no run, no auto-trigger. Requires >=3 successful runs before a workflow is surfaced; caps at 3 suggestions",
2025
2204
  request: () => z.object({
2026
2205
  tags: z.array(z.string()),
@@ -2041,6 +2220,8 @@ export const RECEIVERS = {
2041
2220
  }),
2042
2221
  "tasks:announce": receiver({
2043
2222
  receiver: "tasks:announce",
2223
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!sender) return forbidden` (resolvers/subscriptions.ts:1518).
2224
+ auth: "member",
2044
2225
  surfaces: { mcp: true },
2045
2226
  summary: "Announce a task into the world by its tags — the first caller of world:announce",
2046
2227
  request: () => z.object({
@@ -2070,8 +2251,10 @@ export const RECEIVERS = {
2070
2251
  }),
2071
2252
  "tasks:mine": receiver({
2072
2253
  receiver: "tasks:mine",
2254
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!actor) return forbidden` (resolvers/subscriptions.ts:1544).
2255
+ auth: "member",
2073
2256
  surfaces: { mcp: true },
2074
- summary: "My work queue: the open tasks whose words match what I subscribed to, ranked by learned weight (context-strength), not static priority",
2257
+ summary: "My work queue: the open tasks whose words match what I subscribed to, ranked by learned weight (the tag-node lane), not static priority. Read from RAM as of `asOf`",
2075
2258
  // `workspace` is not decoration — /api/ask reads a SERVICE caller's nominated slug off
2076
2259
  // validation.payload.slug|workspace, and zod .object() STRIPS unknown keys. Omitting the
2077
2260
  // field here meant a service call could never name a workspace: ctx.ownerSlug stayed
@@ -2095,12 +2278,16 @@ export const RECEIVERS = {
2095
2278
  // before running /do <slug>. Empty until the task is enriched (seed/backfill).
2096
2279
  notes: z.string().optional(),
2097
2280
  contextDocs: z.array(z.string()).optional(),
2281
+ priority: z.number().optional().describe("Task priority; the fallback behind `weight` when no followed word carries learned strength"),
2098
2282
  })),
2283
+ ...QUEUE_READ_FIELDS,
2099
2284
  }),
2100
2285
  effect: "ask", idempotent: true,
2101
2286
  }),
2102
2287
  "tasks:everywhere": receiver({
2103
2288
  receiver: "tasks:everywhere",
2289
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!actor) return forbidden` (resolvers/subscriptions.ts:1655).
2290
+ auth: "member",
2104
2291
  surfaces: { mcp: true },
2105
2292
  summary: "Every workspace I belong to, one queue: open+picked tasks visible by assignment/follow/ownership, with claimable + mine + offeredByMe flags; closed:true returns the logbook (done/verified, newest first)",
2106
2293
  // See tasks:mine — a service caller nominates its workspace here, and zod strips any
@@ -2133,16 +2320,19 @@ export const RECEIVERS = {
2133
2320
  claimable: z.boolean(),
2134
2321
  offeredByMe: z.boolean(),
2135
2322
  closedAt: z.string().optional(),
2323
+ // Shipped since 2026-09-17 and undeclared until tql-edge C10.
2324
+ blockedBy: z.array(z.string()).optional().describe("Tids blocking this row (the `blocks` edges). Absent = no blockers at all — absent is not `false`"),
2325
+ openBlockers: z.number().optional().describe("How many of `blockedBy` the CLAIM DOOR would still count (done/verified clear; an unknown blocker counts — fail closed). Present only with `blockedBy`"),
2136
2326
  })),
2137
- // A cap that reports itself (the /api/things standard). The old 200 clamp
2138
- // was silent: a 595-row queue came back as 200 rows and read as complete.
2139
- total: z.number().optional().describe("Visible rows before the limit was applied"),
2140
- truncated: z.boolean().optional().describe("true = more rows exist than were returned; raise limit or use tasks:board"),
2327
+ ...QUEUE_READ_FIELDS,
2328
+ edgesTruncated: z.literal(true).optional().describe("The `blocks` edge sweep was cut or failed: every `claimable:true` in this body is a best effort, not a promise"),
2141
2329
  }),
2142
2330
  effect: "ask", idempotent: true,
2143
2331
  }),
2144
2332
  "factory:elaborate": receiver({
2145
2333
  receiver: "factory:elaborate",
2334
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!actor) return forbidden` + inWorkspace(parent) (resolvers/factory.ts:285,307-309).
2335
+ auth: "member",
2146
2336
  summary: "Create one rung of the derivation ladder (objective | deliverable | task) and hang it under its parent with containment — the ELABORATE move. The rung id is derived from slug + ordinal, so a retry dedupes instead of duplicating",
2147
2337
  request: () => z.object({
2148
2338
  type: z.enum(["objective", "deliverable", "task"]),
@@ -2176,6 +2366,8 @@ export const RECEIVERS = {
2176
2366
  }),
2177
2367
  "factory:size": receiver({
2178
2368
  receiver: "factory:size",
2369
+ // auth (public) — task:01a128d6108e551f5966106b: pure function, no ctx (resolvers/factory.ts:243-250); the public /factory page's signal-gates probe reads it logged out (lib/factory/signal-gates.ts:73).
2370
+ auth: "public",
2179
2371
  summary: "How big is this change — the tier `.claude/scripts/do-tier.sh` returns for the same paths, answered where a Worker can ask (a Worker cannot run a shell script, which is the only reason the Size card at factory flow.ts:306 is a gap). Zero real paths is REFUSED as `unsized`, mirroring the script's exit 3: absence of recon must not read as simplicity. The pin ladder in the response is a pure function of the tier; the surfaces are additive obligation, never a second gate selector",
2180
2372
  request: () => z.object({
2181
2373
  // The changed paths, repo-relative. do-tier sizes a DIFF, never a sentence,
@@ -2207,6 +2399,8 @@ export const RECEIVERS = {
2207
2399
  }),
2208
2400
  "factory:recon": receiver({
2209
2401
  receiver: "factory:recon",
2402
+ // auth (public) — task:01a128d6108e551f5966106b: pure function over build-time PAGE_FILES, no ctx (resolvers/factory.ts:218) — the read-only sibling of factory:size.
2403
+ auth: "public",
2210
2404
  summary: "What does this sentence touch — the paths, the route and the verdict `.claude/scripts/do-triage.sh` returns for the same text, answered where a Worker can ask (a Worker cannot exec a shell script, which is the only reason the recon card at factory flow.ts:480 was a gap). Runs UPSTREAM of factory:size: prose in, repo paths out, and the sizer's own contract unchanged. No model call. It ALWAYS answers with a verdict and never refuses — it runs as a workflow tool step (one.ie/ai/workflows/eng-intake.tql:33), where a failed step poisons every step downstream of it; factory:size's `unsized` stays the one refusal on this lane",
2211
2405
  request: () => z.object({
2212
2406
  // The captured sentence. do-triage reads what the text LITERALLY names —
@@ -2240,6 +2434,8 @@ export const RECEIVERS = {
2240
2434
  }),
2241
2435
  "factory:attempt": receiver({
2242
2436
  receiver: "factory:attempt",
2437
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!actor) return forbidden` + inWorkspace(task) (resolvers/factory.ts:356,371-373).
2438
+ auth: "member",
2243
2439
  summary: "Open an attempt contained by its task, or close it with the production edge to what it produced plus the rubric. A do-cycle IS an attempt (factory-plan.md §3.1) — do:cycle-close arms as a caller of the close phase, never as a second writer",
2244
2440
  request: () => z.object({
2245
2441
  phase: z.enum(["open", "close"]),
@@ -2537,6 +2733,7 @@ export const RECEIVERS = {
2537
2733
  receiver: "ehc:evidence-remove",
2538
2734
  summary: "Remove one artefact from an EHC case's evidence locker, or restore it (removed:false). Owner-only: authority is the caller's control of the case's group, read off the attested caller and never the payload. Writes one row to an append-only log — nothing is deleted, and every page says how many items the owner removed. Takes an exact evidence id from ehc:evidence; never matches a caption",
2539
2735
  request: () => z.object({
2736
+ slug: SERVICE_SLUG,
2540
2737
  cyp: z.string(), // case id or slug
2541
2738
  evidenceId: z.string(), // exact id from ehc:evidence, e.g. 'ev-a7-railay'
2542
2739
  removed: z.boolean().optional(), // default true; false restores
@@ -2726,6 +2923,8 @@ export const RECEIVERS = {
2726
2923
  }),
2727
2924
  "do:halt": receiver({
2728
2925
  receiver: "do:halt",
2926
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!actor) return forbidden` + inWorkspace(plan) (resolvers/factory.ts:576,592-594).
2927
+ auth: "member",
2729
2928
  summary: "Stop a factory run, or release the stop. Sets a halt latch on the plan thing that `factory:attempt` phase \"open\" refuses against, so no new attempt can be claimed; with `attempt`, also closes that in-flight attempt as dissolved. It does NOT kill an OS process — a cycle already executing stops at its next substrate write",
2730
2929
  request: () => z.object({
2731
2930
  // The plan slug the operator sees ("factory"). The plan tid is resolved server-side;
@@ -2753,6 +2952,8 @@ export const RECEIVERS = {
2753
2952
  }),
2754
2953
  "tasks:create": receiver({
2755
2954
  receiver: "tasks:create",
2955
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!actor) return { error: 'workspace required' }` (resolvers/tasks.ts:415); operate on the parent (:459).
2956
+ auth: "member",
2756
2957
  surfaces: { mcp: true },
2757
2958
  summary: "Write one open task to the substrate and announce it by its tags in the same act — the quick-add entry point",
2758
2959
  request: () => z.object({
@@ -2783,6 +2984,8 @@ export const RECEIVERS = {
2783
2984
  }),
2784
2985
  "tasks:claim": receiver({
2785
2986
  receiver: "tasks:claim",
2987
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!claimant) return { error: 'workspace required' }` + taskAccess === 'operate' (resolvers/tasks.ts:1319,1336-1337).
2988
+ auth: "member",
2786
2989
  surfaces: { mcp: true },
2787
2990
  summary: "Take a task off the queue: blocker-gate → status picked → tag the claimant @<slug>. Address it by tid, or by the /do slug the task was created under. The claimant is the attested caller, never a body field",
2788
2991
  // Addressable two ways, and BOTH must be optional here. The resolver has always
@@ -2811,6 +3014,8 @@ export const RECEIVERS = {
2811
3014
  }),
2812
3015
  "tasks:reap": receiver({
2813
3016
  receiver: "tasks:reap",
3017
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!ctx.ownerSlug) return { error: 'workspace required' }` (resolvers/tasks.ts:1273).
3018
+ auth: "member",
2814
3019
  surfaces: { mcp: true },
2815
3020
  summary: "Sweep stranded claim leases in a workspace: every `picked` task whose newest updated-at-ms is older than the 45-minute TTL goes back to `open`, its @claimant tags are stripped, and the abandoned path is warned",
2816
3021
  // The other half of the claim seam. tasks:claim is atomic, so two workers can
@@ -2945,7 +3150,11 @@ export const RECEIVERS = {
2945
3150
  surfaces: { mcp: true },
2946
3151
  summary: "Every task carrying a tag, with its task-status — the read that lets a plan's checkboxes be a PROJECTION of task state instead of a second copy. Scoped to the caller's workspace on the server",
2947
3152
  request: () => z.object({
2948
- tag: z.string(),
3153
+ // Optional: without a tag the handler lists the caller's workspace's ACTIVE rows
3154
+ // (open|blocked|picked) from the board snapshot — a page of `limit`, with `total` +
3155
+ // `truncated`. A tag narrows to one plan's rows, unbounded as before.
3156
+ tag: z.string().optional(),
3157
+ limit: z.number().int().positive().optional().describe("Tag-less page size (default 50, cap 1000); ignored when a tag is given."),
2949
3158
  // Optional task-status filter (open|blocked|picked|done|verified|failed|dissolved).
2950
3159
  // Declared here because the HTTP edge dispatches zod's PARSED output — an
2951
3160
  // undeclared field is silently stripped before the resolver reads it, and the
@@ -2962,6 +3171,11 @@ export const RECEIVERS = {
2962
3171
  status: z.string(),
2963
3172
  name: z.string().optional(),
2964
3173
  })).optional(),
3174
+ total: z.number().optional().describe("Tag-less list only: rows matched before the page cut."),
3175
+ truncated: z.boolean().optional().describe("Tag-less list only: true when `limit` (or the board snapshot's own row cap) cut rows — `total` is the count matched, a floor when the snapshot was cut."),
3176
+ asOf: z.string().optional().describe("Tag-less list only: when the board snapshot it was read from was built."),
3177
+ stale: z.boolean().optional().describe("Tag-less list only: the snapshot rebuild failed and this is the last board that was built."),
3178
+ status: z.string().optional().describe("Echo of the status filter, when one was given."),
2965
3179
  error: z.string().optional(),
2966
3180
  }),
2967
3181
  effect: "ask", idempotent: true, auth: "member",
@@ -3445,6 +3659,8 @@ export const RECEIVERS = {
3445
3659
  }),
3446
3660
  "tasks:undepend": receiver({
3447
3661
  receiver: "tasks:undepend",
3662
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!actor) return { error: 'workspace required' }` + gateTask on both rows (resolvers/tasks.ts:1768,1773-1774).
3663
+ auth: "member",
3448
3664
  surfaces: { mcp: true },
3449
3665
  summary: "Remove one blocks edge — the inverse of tasks:depend. Deletes exactly the (blockedBy → tid) pair; does not touch task status. Auth: attested caller only, both ends in the caller's workspace",
3450
3666
  request: () => z.object({
@@ -3462,6 +3678,8 @@ export const RECEIVERS = {
3462
3678
  }),
3463
3679
  "tasks:launch": receiver({
3464
3680
  receiver: "tasks:launch",
3681
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!owner) return { error: 'workspace required' }` + operate per tid (resolvers/tasks.ts:2100,2118-2121).
3682
+ auth: "member",
3465
3683
  summary: "Batch-launch ready agent-assigned tasks: per task re-check blockers, resolve the @assignee, set picked, fire agent:run, mark owner→assignee on success or revert to open + warn on failure. Per-task receipts — a batch is never all-or-nothing. Caps at 20 tids; skips human assignees",
3466
3684
  request: () => z.object({
3467
3685
  tids: z.array(z.string()),
@@ -3487,6 +3705,8 @@ export const RECEIVERS = {
3487
3705
  }),
3488
3706
  "tasks:link": receiver({
3489
3707
  receiver: "tasks:link",
3708
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!actor) return { error: 'workspace required' }` + gateTask (resolvers/tasks.ts:1451,1467).
3709
+ auth: "member",
3490
3710
  surfaces: { mcp: true },
3491
3711
  summary: "Close the handoff: record that a claimed task was built via /do <slug> — append a provenance line to the task's notes (the id back-ref + doc stems) and move it to done. Auth: attested caller only",
3492
3712
  // The slug IS the handle here — the resolver requires it and resolves the origin tid
@@ -3541,6 +3761,8 @@ export const RECEIVERS = {
3541
3761
  }),
3542
3762
  "agents:commend": receiver({
3543
3763
  receiver: "agents:commend",
3764
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!voter) throw forbidden` (resolvers/market.ts:1865-1866).
3765
+ auth: "member",
3544
3766
  summary: "Commend an agent — strengthen its reputation path",
3545
3767
  request: () => z.object({ uid: z.string() }),
3546
3768
  response: () => AgentActionResponseSchema,
@@ -3548,6 +3770,8 @@ export const RECEIVERS = {
3548
3770
  }),
3549
3771
  "agents:flag": receiver({
3550
3772
  receiver: "agents:flag",
3773
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!voter) throw forbidden` (resolvers/market.ts:1878-1879).
3774
+ auth: "member",
3551
3775
  summary: "Flag an agent — add resistance to its reputation path",
3552
3776
  request: () => z.object({ uid: z.string() }),
3553
3777
  response: () => AgentActionResponseSchema,
@@ -3555,6 +3779,8 @@ export const RECEIVERS = {
3555
3779
  }),
3556
3780
  "agents:status": receiver({
3557
3781
  receiver: "agents:status",
3782
+ // auth (owner) — task:01a128d6108e551f5966106b: handler requires uid === caller or callerControlsWorkspace(caller, uid) (resolvers/market.ts:1892-1896); not a manage_actors label, which would bar an agent key setting its own status.
3783
+ auth: "owner",
3558
3784
  canonical: "world:update-actor",
3559
3785
  summary: "Set an agent active or inactive",
3560
3786
  request: () => z.object({ uid: z.string(), status: z.string() }),
@@ -3563,6 +3789,8 @@ export const RECEIVERS = {
3563
3789
  }),
3564
3790
  "agents:capabilities": receiver({
3565
3791
  receiver: "agents:capabilities",
3792
+ // auth (public) — task:01a128d6108e551f5966106b: named by the anonymous /.well-known agent door (well-known-door.ts:42,131). The handler reads no ctx and shows only what market:list would: active, visibility='open', no scope, no bounty:* row, and no TypeDB fallback (resolvers/market.ts agents:capabilities).
3793
+ auth: "public",
3566
3794
  summary: "List an agent's published capabilities",
3567
3795
  request: () => z.object({ uid: z.string() }),
3568
3796
  response: () => z.array(CapabilityItemSchema),
@@ -3572,6 +3800,8 @@ export const RECEIVERS = {
3572
3800
  // ── pay (TRANSACT — onchain settlement) ──
3573
3801
  "pay:weight": receiver({
3574
3802
  receiver: "pay:weight",
3803
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!callerSlug) throw forbidden` (resolvers/market.ts:1561).
3804
+ auth: "member",
3575
3805
  surfaces: { mcp: { name: "pay" } },
3576
3806
  summary: "Pay for a task by weighting the path between two actors",
3577
3807
  request: () => z.object({
@@ -3580,9 +3810,10 @@ export const RECEIVERS = {
3580
3810
  // before the handler could derive it — and before its own auth check ran.
3581
3811
  from: z.string().optional(),
3582
3812
  to: z.string(), task: z.string(), amount: z.number(),
3813
+ ...WORK_CONTRACT_FIELDS,
3583
3814
  }),
3584
3815
  response: () => PayResponseSchema,
3585
- effect: "ask", cost: "variable", settles: "onchain", reversible: false, simulatable: true,
3816
+ effect: "ask", cost: "variable", settles: "onchain", reversible: false, simulatable: true, moves: "value",
3586
3817
  }),
3587
3818
  "tasks:stake": receiver({
3588
3819
  receiver: "tasks:stake",
@@ -3607,6 +3838,7 @@ export const RECEIVERS = {
3607
3838
  receiver: "market:offer",
3608
3839
  summary: "Buyer creates a Deal at OFFER stage — initiates A2A negotiation",
3609
3840
  request: () => z.object({
3841
+ slug: SERVICE_SLUG,
3610
3842
  id: z.string().uuid().optional(),
3611
3843
  seller: z.string().min(1),
3612
3844
  skill: z.string().min(1),
@@ -3640,7 +3872,7 @@ export const RECEIVERS = {
3640
3872
  "market:accept": receiver({
3641
3873
  receiver: "market:accept",
3642
3874
  summary: "Buyer accepts deal — OFFER → ESCROW",
3643
- request: () => z.object({ dealId: z.string().min(1) }),
3875
+ request: () => z.object({ slug: SERVICE_SLUG, dealId: z.string().min(1) }),
3644
3876
  response: () => z.union([
3645
3877
  z.object({ ok: z.literal(true), deal: z.object({ id: z.string(), stage: z.string(), version: z.number() }) }),
3646
3878
  z.object({ ok: z.literal(false), error: z.string() }),
@@ -3686,12 +3918,12 @@ export const RECEIVERS = {
3686
3918
  "market:settle": receiver({
3687
3919
  receiver: "market:settle",
3688
3920
  summary: "Release escrow payment — SETTLE → RECEIPT",
3689
- request: () => z.object({ dealId: z.string().min(1) }),
3921
+ request: () => z.object({ slug: SERVICE_SLUG, dealId: z.string().min(1), ...WORK_CONTRACT_FIELDS }),
3690
3922
  response: () => z.union([
3691
3923
  z.object({ ok: z.literal(true), deal: z.object({ id: z.string(), stage: z.string(), version: z.number() }) }),
3692
3924
  z.object({ ok: z.literal(false), error: z.string() }),
3693
3925
  ]),
3694
- effect: "ask", auth: "required", reversible: false, idempotent: false,
3926
+ effect: "ask", auth: "required", reversible: false, idempotent: false, moves: "value",
3695
3927
  }),
3696
3928
  "market:dispute": receiver({
3697
3929
  receiver: "market:dispute",
@@ -3706,17 +3938,17 @@ export const RECEIVERS = {
3706
3938
  "market:escrow": receiver({
3707
3939
  receiver: "market:escrow",
3708
3940
  summary: "Buyer locks payment via pay.one.ie — ESCROW → EXECUTE on confirmed tx",
3709
- request: () => z.object({ dealId: z.string().min(1) }),
3941
+ request: () => z.object({ dealId: z.string().min(1), ...WORK_CONTRACT_FIELDS }),
3710
3942
  response: () => z.union([
3711
3943
  z.object({ ok: z.literal(true), deal: z.object({ id: z.string(), stage: z.string(), version: z.number() }), escrowRef: z.string() }),
3712
3944
  z.object({ ok: z.literal(false), error: z.string(), deal: z.object({ id: z.string(), stage: z.string() }).optional() }),
3713
3945
  ]),
3714
- effect: "ask", auth: "required", reversible: false, idempotent: false,
3946
+ effect: "ask", auth: "required", reversible: false, idempotent: false, moves: "value",
3715
3947
  }),
3716
3948
  "market:offers": receiver({
3717
3949
  receiver: "market:offers",
3718
3950
  summary: "List the caller's own deals (as buyer or seller), optionally filtered by stage",
3719
- request: () => z.object({ stage: z.string().optional() }),
3951
+ request: () => z.object({ slug: SERVICE_SLUG, stage: z.string().optional() }),
3720
3952
  response: () => z.union([
3721
3953
  z.object({ ok: z.literal(true), deals: z.array(z.object({
3722
3954
  id: z.string(), buyer: z.string(), seller: z.string(), skill: z.string(),
@@ -3730,6 +3962,8 @@ export const RECEIVERS = {
3730
3962
  // ── market (TRADE) ──
3731
3963
  "market:hire": receiver({
3732
3964
  receiver: "market:hire",
3965
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!callerSlug) throw forbidden` (resolvers/market.ts:1493).
3966
+ auth: "member",
3733
3967
  summary: "Hire an agent for a skill — opens a chat or returns an escrow template",
3734
3968
  request: () => z.object({ providerUid: z.string(), skillId: z.string(), initialMessage: z.string().optional() }),
3735
3969
  response: () => z.union([
@@ -3743,6 +3977,8 @@ export const RECEIVERS = {
3743
3977
  }),
3744
3978
  "market:bounty": receiver({
3745
3979
  receiver: "market:bounty",
3980
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!callerSlug) throw forbidden` (resolvers/market.ts:1616).
3981
+ auth: "member",
3746
3982
  summary: "Post a bounty for a skill, backed by an escrow",
3747
3983
  request: () => z.object({
3748
3984
  skillId: z.string(), sellerUid: z.string(),
@@ -3766,6 +4002,8 @@ export const RECEIVERS = {
3766
4002
  }),
3767
4003
  "market:bounties": receiver({
3768
4004
  receiver: "market:bounties",
4005
+ // auth (public) — task:01a128d6108e551f5966106b: the prerendered public /marketplace reads it logged out (MarketplaceApp.tsx:278); handler reads no ctx (resolvers/market.ts:1649).
4006
+ auth: "public",
3769
4007
  summary: "List bounties, optionally filtered by seller or poster",
3770
4008
  request: () => z.object({ seller: z.string().optional(), poster: z.string().optional() }),
3771
4009
  response: () => z.array(z.object({
@@ -3776,6 +4014,8 @@ export const RECEIVERS = {
3776
4014
  }),
3777
4015
  "market:claim": receiver({
3778
4016
  receiver: "market:claim",
4017
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!claimantUid) throw forbidden` (resolvers/market.ts:1689-1690).
4018
+ auth: "member",
3779
4019
  summary: "Claim an open bounty — atomically marks it picked and binds the claimant",
3780
4020
  request: () => z.object({ bountyId: z.string() }),
3781
4021
  response: () => z.union([
@@ -3812,6 +4052,8 @@ export const RECEIVERS = {
3812
4052
  }),
3813
4053
  "market:list": receiver({
3814
4054
  receiver: "market:list",
4055
+ // auth (public) — task:01a128d6108e551f5966106b: the /.well-known door (well-known-door.ts:43) and the prerendered public /marketplace (MarketplaceApp.tsx:277) read it logged out; handler reads no ctx (resolvers/market.ts:571).
4056
+ auth: "public",
3815
4057
  summary: "List the capability market",
3816
4058
  request: () => z.object({ tag: z.string().optional(), maxPrice: z.number().optional() }),
3817
4059
  response: () => z.object({ capabilities: z.array(z.unknown()) }),
@@ -3820,6 +4062,8 @@ export const RECEIVERS = {
3820
4062
  // ── capabilities ──
3821
4063
  "capabilities:publish": receiver({
3822
4064
  receiver: "capabilities:publish",
4065
+ // auth (owner) — task:01a128d6108e551f5966106b: handler requires sellerUid === caller or callerControlsWorkspace (resolvers/market.ts:1908-1916).
4066
+ auth: "owner",
3823
4067
  summary: "Publish a capability (skill listing) to the market",
3824
4068
  request: () => z.object({
3825
4069
  skillId: z.string(), name: z.string(),
@@ -3843,8 +4087,14 @@ export const RECEIVERS = {
3843
4087
  // ── reads (free · idempotent) ──
3844
4088
  "signals:list": receiver({
3845
4089
  receiver: "signals:list",
4090
+ // auth (member) — task:01a128d6108e551f5966106b: handler reads the CALLER's events; with no ctx.ownerSlug it reads the 'none' bucket (resolvers/billing.ts:81-85) — nothing an anonymous caller is meant to have.
4091
+ auth: "member",
3846
4092
  summary: "List recent signals",
3847
4093
  request: () => z.object({
4094
+ // The service lane (channels' analytics tools) names the workspace it asks for; the ask
4095
+ // door reads only a service caller's nomination, from the PARSED payload — undeclared,
4096
+ // zod strips it and the member label refuses the call.
4097
+ slug: z.string().optional(),
3848
4098
  limit: z.number().optional(), since: z.number().optional(),
3849
4099
  from: z.number().optional(), to: z.number().optional(),
3850
4100
  intent: z.string().optional(),
@@ -3858,16 +4108,26 @@ export const RECEIVERS = {
3858
4108
  }),
3859
4109
  "stats:current": receiver({
3860
4110
  receiver: "stats:current",
4111
+ // auth (member) — task:01a128d6108e551f5966106b: handler reads no ctx (resolvers/billing.ts:8); every caller found carries a key (SDK, MCP stats, channels service lane).
4112
+ auth: "member",
3861
4113
  surfaces: { mcp: { name: "stats" } },
3862
4114
  summary: "Current world stats — units, skills, highways, revenue, signals",
3863
- request: () => z.object({}),
4115
+ request: () => z.object({
4116
+ // The service lane names the workspace it asks for (see signals:list).
4117
+ slug: z.string().optional(),
4118
+ }),
3864
4119
  response: () => StatsSchema,
3865
4120
  effect: "ask", cost: "free", idempotent: true,
3866
4121
  }),
3867
4122
  "dashboard:usage": receiver({
3868
4123
  receiver: "dashboard:usage",
4124
+ // auth (member) — task:01a128d6108e551f5966106b: the CALLER's usage; with no ctx.ownerSlug the handler returns a canned free tier (resolvers/billing.ts:96) — nothing an anonymous caller is meant to have.
4125
+ auth: "member",
3869
4126
  summary: "Caller's plan usage — calls, agents, limits",
3870
- request: () => z.object({}),
4127
+ request: () => z.object({
4128
+ // The service lane names the workspace it asks for (see signals:list).
4129
+ slug: z.string().optional(),
4130
+ }),
3871
4131
  response: () => z.object({
3872
4132
  tier: z.string(), calls_this_month: z.number(), agents_count: z.number(),
3873
4133
  api_limit: z.number(), agent_limit: z.number(), loops: z.array(z.string()),
@@ -3877,6 +4137,8 @@ export const RECEIVERS = {
3877
4137
  }),
3878
4138
  "world:state": receiver({
3879
4139
  receiver: "world:state",
4140
+ // auth (member) — task:01a128d6108e551f5966106b: handler reads no ctx (resolvers/groups.ts:340); the only caller is the SDK state(), which carries the client's key.
4141
+ auth: "member",
3880
4142
  summary: "Full world snapshot — units, edges, highways, tags, stats",
3881
4143
  request: () => z.object({}),
3882
4144
  response: () => z.object({}).passthrough(),
@@ -3889,9 +4151,11 @@ export const RECEIVERS = {
3889
4151
  // ════════════════════════════════════════════════════════════════════════
3890
4152
  "meta:catalog": receiver({
3891
4153
  receiver: "meta:catalog",
4154
+ // auth (public) — task:01a128d6108e551f5966106b: the /.well-known door advertises it to agents that hold no key yet (well-known-door.ts:44,141); an anonymous caller gets the owner-filtered projection (meta-receivers.ts:119-120).
4155
+ auth: "public",
3892
4156
  surfaces: { mcp: true },
3893
4157
  summary: "List every receiver the caller can use (with cost/reversibility/settlement), or a goal's recipe",
3894
- request: () => z.object({ goal: z.enum(["spine", "build", "trade", "transact"]).optional() }),
4158
+ request: () => z.object({ goal: z.enum(["spine", "build", "trade", "transact"]).optional(), tag: z.string().optional() }),
3895
4159
  response: () => z.union([
3896
4160
  z.array(z.object({
3897
4161
  receiver: z.string(), summary: z.string(), effect: z.enum(["signal", "ask"]),
@@ -3904,6 +4168,8 @@ export const RECEIVERS = {
3904
4168
  }),
3905
4169
  "meta:schema": receiver({
3906
4170
  receiver: "meta:schema",
4171
+ // auth (public) — task:01a128d6108e551f5966106b: the /.well-known door advertises it to agents that hold no key yet (well-known-door.ts:45,140); named paths are read only for an attested slug (meta-receivers.ts:147).
4172
+ auth: "public",
3907
4173
  surfaces: { mcp: true },
3908
4174
  summary: "JSON Schema for one receiver's request + response — read it before you call",
3909
4175
  request: () => z.object({ receiver: z.string() }),
@@ -3915,6 +4181,8 @@ export const RECEIVERS = {
3915
4181
  }),
3916
4182
  "meta:recall": receiver({
3917
4183
  receiver: "meta:recall",
4184
+ // auth (member) — task:01a128d6108e551f5966106b: the CALLER's hypotheses — the handler requires ctx.ownerSlug (or staff) and scopes the read to group_id = group:<ownerSlug>; staff read all (meta-receivers.ts recall). No anonymous caller depends on it (CLI/MCP carry keys).
4185
+ auth: "member",
3918
4186
  surfaces: { mcp: true },
3919
4187
  summary: "Recall the caller's hypotheses (memory), optionally filtered by a search term",
3920
4188
  request: () => z.object({ match: z.string().optional(), limit: z.number().optional() }),
@@ -3927,22 +4195,36 @@ export const RECEIVERS = {
3927
4195
  }),
3928
4196
  "meta:reputation": receiver({
3929
4197
  receiver: "meta:reputation",
3930
- summary: "Read an actor's reputation score — weighted commend/flag balance from claw_paths + vote counts from reputation_votes",
4198
+ // auth (public) — task:01a128d6108e551f5966106b: reputation is a public score: an anonymous caller gets disclosure 'public' (score + counts, no payer rows) — meta-receivers.ts:198-201.
4199
+ auth: "public",
4200
+ summary: "Read an actor's reputation score — the net of the claw_paths rows routing ranks by, plus vote counts from reputation_votes. The score and the counts go to every caller. Each row's payer identity, strength and resistance are disclosed by the workspace the payment was SETTLED TO, written on the row at payment time by wallet:send (never looked up by the uid, which any registry can be squatted under): a controller of that workspace reads the row (the spend walk from the attested caller), and so does a member of it when that workspace's C10 visibility is Members (the membership snapshot). Every other row is counted and withheld; `withheld` says how many, and `disclosure` names the highest rung that opened one. A row with no recorded workspace — written before the field existed, paid into two workspaces, or paid to a slug nobody owned yet — opens to nobody, ever. A walk or snapshot that cannot answer opens nothing",
3931
4201
  request: () => z.object({ uid: z.string().describe("The actor's slug or aid to look up") }),
3932
4202
  response: () => z.object({
3933
4203
  uid: z.string(),
3934
- score: z.number().describe("Normalised 0–1 float: strength / (strength + resistance)"),
3935
- commend_count: z.number(),
3936
- flag_count: z.number(),
3937
- strength: z.number(),
3938
- resistance: z.number(),
3939
- why: z.array(z.string()).describe("Plain-English summary of the score"),
3940
- howToRaise: z.array(z.string()).describe("Actionable hints for improving score"),
4204
+ disclosure: z.enum(["public", "members", "controller"]).optional().describe("The highest rung by which a row opened to this caller: controller (the spend walk admits the caller over a row's settled-to workspace), members (a confirmed member of a Members workspace a row settled to), public (no row opened — counts only). Absent only beside `error`"),
4205
+ error: z.string().optional().describe("uid_required only. A payee the caller may not read answers counts, never a 404 and never a hint either way"),
4206
+ score: z.number().optional().describe("Net strength - resistance over the claw_paths rows routing ranks by (readActorReputation) - the same number for every caller"),
4207
+ ratio: z.number().optional().describe("Normalised 0–1 float: strength / (strength + resistance)"),
4208
+ evidence: z.object({
4209
+ payers: z.number().describe("How many payers' settled money is in the score — every row, open or withheld"),
4210
+ stakes: z.number().describe("How many burned stakes are in the score — every row, open or withheld"),
4211
+ sources: z.array(z.string()).optional().describe("Payer slugs of the rows that opened to this caller. Absent when none did"),
4212
+ rows: z.array(z.object({ source: z.string(), strength: z.number(), resistance: z.number(), settledTo: z.string().nullable() })).optional().describe("The rows that opened to this caller, each with the workspace its payments settled to. Absent when none did"),
4213
+ }).optional().describe("The counts behind the score, and of the rows exactly those this caller may read"),
4214
+ withheld: z.number().optional().describe("How many of the payer and stake rows behind the score this caller may NOT read — the short answer says it is short. 0 when every row opened, or there are none"),
4215
+ commend_count: z.number().optional(),
4216
+ flag_count: z.number().optional(),
4217
+ strength: z.number().optional(),
4218
+ resistance: z.number().optional(),
4219
+ why: z.array(z.string()).optional().describe("Plain-English summary of the score"),
4220
+ howToRaise: z.array(z.string()).optional().describe("Actionable hints for improving score"),
3941
4221
  }),
3942
4222
  effect: "ask", cost: "free", idempotent: true,
3943
4223
  }),
3944
4224
  "meta:types": receiver({
3945
4225
  receiver: "meta:types",
4226
+ // auth (public) — task:01a128d6108e551f5966106b: an anonymous caller gets the empty manifest + first-party templates (meta-receivers.ts:160); the role-scoped read needs ctx.ownerSlug.
4227
+ auth: "public",
3946
4228
  surfaces: { mcp: true },
3947
4229
  summary: "Read the resource-type manifest for the caller's workspace, plus the built-in industry templates",
3948
4230
  request: () => z.object({}),
@@ -3954,6 +4236,8 @@ export const RECEIVERS = {
3954
4236
  }),
3955
4237
  "meta:entitlements": receiver({
3956
4238
  receiver: "meta:entitlements",
4239
+ // auth (member) — task:01a128d6108e551f5966106b: the CALLER's entitlement; with no ctx.ownerSlug the handler answers allowed:false (meta-receivers.ts:173) — no anonymous caller found.
4240
+ auth: "member",
3957
4241
  summary: "Check the caller workspace's entitlement for one feature — the authoritative paid-plugin gate; absent/over-limit claim → not allowed (backend returns 402)",
3958
4242
  request: () => z.object({ feature: z.string() }),
3959
4243
  response: () => z.object({
@@ -4041,6 +4325,8 @@ export const RECEIVERS = {
4041
4325
  }),
4042
4326
  "plugins:list": receiver({
4043
4327
  receiver: "plugins:list",
4328
+ // auth (public) — task:01a128d6108e551f5966106b: the static plugin catalog, no ctx (resolvers/plugins.ts:71); the chat PluginPanel reads it logged out (PluginPanel.tsx:236).
4329
+ auth: "public",
4044
4330
  summary: "List all available ONE plugins with their feature key, price, and description",
4045
4331
  request: () => z.object({}),
4046
4332
  response: () => z.object({
@@ -4065,6 +4351,7 @@ export const RECEIVERS = {
4065
4351
  kind: z.enum(["plugin", "agent", "skill"]).optional(),
4066
4352
  uses: z.number().optional(),
4067
4353
  idem: z.string().optional(),
4354
+ ...WORK_CONTRACT_FIELDS,
4068
4355
  }),
4069
4356
  response: () => z.object({
4070
4357
  method: z.enum(["stripe", "credits"]),
@@ -4084,7 +4371,7 @@ export const RECEIVERS = {
4084
4371
  plugin: z.string(),
4085
4372
  feature: z.string(),
4086
4373
  }),
4087
- effect: "ask", auth: "owner", cost: "variable", idempotent: false,
4374
+ effect: "ask", auth: "owner", cost: "variable", idempotent: false, moves: "value",
4088
4375
  examples: [{ name: "shop" }, { name: "shop", method: "credits" }],
4089
4376
  }),
4090
4377
  "plugins:grant": receiver({
@@ -4107,6 +4394,8 @@ export const RECEIVERS = {
4107
4394
  }),
4108
4395
  "plugins:source": receiver({
4109
4396
  receiver: "plugins:source",
4397
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!ws) return { error: 'unauthenticated' }` + checkEntitlement (resolvers/plugins.ts:288-292).
4398
+ auth: "member",
4110
4399
  summary: "Get the install reference for a plugin — 402 when the workspace is not entitled. Use meta:entitlements to check first; this doubles as the delivery gate.",
4111
4400
  request: () => z.object({ feature: z.string() }),
4112
4401
  response: () => z.object({
@@ -4121,6 +4410,8 @@ export const RECEIVERS = {
4121
4410
  // ── actor discovery + messaging ──────────────────────────────────────────
4122
4411
  "actors:find": receiver({
4123
4412
  receiver: "actors:find",
4413
+ // auth (public) — task:01a128d6108e551f5966106b: the agent directory: keyless `one market --query` against api.one.ie reads it (packages/cli/src/trade.ts:41); handler reads no ctx and refuses type 'human' (resolvers/groups.ts:313-315).
4414
+ auth: "public",
4124
4415
  summary: "Find agents on the marketplace by name fragment or skill — marketplace discovery only",
4125
4416
  request: () => z.object({
4126
4417
  // human is excluded: personal names/emails are PII, not marketplace data.
@@ -4137,6 +4428,8 @@ export const RECEIVERS = {
4137
4428
  }),
4138
4429
  "peer:message": receiver({
4139
4430
  receiver: "peer:message",
4431
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!from) throw forbidden` (resolvers/messaging.ts:699-700).
4432
+ auth: "member",
4140
4433
  summary: "Send an async message to another agent's inbox — instant store, no LLM, no streaming",
4141
4434
  request: () => z.object({ to: z.string(), content: z.string(), from: z.string().optional() }),
4142
4435
  response: () => z.object({ ok: z.boolean(), id: z.string().optional(), ts: z.number().optional(), to: z.string().optional(), from: z.string().optional(), error: z.string().optional() }),
@@ -4144,6 +4437,8 @@ export const RECEIVERS = {
4144
4437
  }),
4145
4438
  "notify": receiver({
4146
4439
  receiver: "notify",
4440
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!from) throw forbidden` (resolvers/messaging.ts:789-790).
4441
+ auth: "member",
4147
4442
  // NOT surfaces.mcp — the curated `message` tool in packages/mcp/src/tools/
4148
4443
  // messaging.ts already fronts this receiver and carries shaping the registry
4149
4444
  // cannot infer: it defaults `kind: "message"` and names the argument
@@ -4173,6 +4468,8 @@ export const RECEIVERS = {
4173
4468
  }),
4174
4469
  "notify:count": receiver({
4175
4470
  receiver: "notify:count",
4471
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!slug) throw forbidden` (resolvers/messaging.ts:819-820).
4472
+ auth: "member",
4176
4473
  summary: "Unread thread count for the caller's inbox (a thread is unread when its last message is newer than the caller's read marker).",
4177
4474
  request: () => z.object({}),
4178
4475
  response: () => z.object({ unread: z.number() }),
@@ -4180,6 +4477,8 @@ export const RECEIVERS = {
4180
4477
  }),
4181
4478
  "notify:list": receiver({
4182
4479
  receiver: "notify:list",
4480
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!slug) throw forbidden` (resolvers/messaging.ts:839-840).
4481
+ auth: "member",
4183
4482
  summary: "The caller's unread threads, newest first, each with a short preview.",
4184
4483
  request: () => z.object({ limit: z.number().optional() }),
4185
4484
  response: () => z.object({ unread: z.array(z.object({ id: z.string(), ts: z.number(), preview: z.string() })) }),
@@ -4187,6 +4486,8 @@ export const RECEIVERS = {
4187
4486
  }),
4188
4487
  "notify:read": receiver({
4189
4488
  receiver: "notify:read",
4489
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!slug) throw forbidden` (resolvers/messaging.ts:875-876).
4490
+ auth: "member",
4190
4491
  summary: "Mark one thread (threadId) or all of the caller's threads (all:true) as read; nudges the inbox live.",
4191
4492
  request: () => z.object({ threadId: z.string().optional(), id: z.string().optional(), all: z.boolean().optional() }),
4192
4493
  response: () => z.object({ ok: z.boolean(), ts: z.number().optional(), error: z.string().optional() }),
@@ -4194,6 +4495,8 @@ export const RECEIVERS = {
4194
4495
  }),
4195
4496
  "push:subscribe": receiver({
4196
4497
  receiver: "push:subscribe",
4498
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!caller) throw forbidden` (resolvers/messaging.ts:914-915).
4499
+ auth: "member",
4197
4500
  summary: "Store a browser's Web Push subscription so notify() can reach the caller off-screen — the send side behind the shipped inbox service worker. Optional slug keys the row to a workspace the caller controls (else their own slug).",
4198
4501
  request: () => z.object({
4199
4502
  endpoint: z.string(),
@@ -4205,6 +4508,8 @@ export const RECEIVERS = {
4205
4508
  }),
4206
4509
  "thread:append": receiver({
4207
4510
  receiver: "thread:append",
4511
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!slug) return forbidden` (resolvers/messaging.ts:945-946); the keyless /api/write sealed note calls it IN-PROCESS with an attested ownerSlug (lib/key/sealed-append.ts:24-38), never through this door.
4512
+ auth: "member",
4208
4513
  summary: "Gateway-callable write into web threads — carries tags into entity_tags so slug/in renders every channel by tag. Called by the channels bridge after every inbound signal.",
4209
4514
  request: () => z.object({
4210
4515
  slug: z.string(),
@@ -4240,6 +4545,8 @@ export const RECEIVERS = {
4240
4545
  }),
4241
4546
  "space:post": receiver({
4242
4547
  receiver: "space:post",
4548
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!from) return forbidden` + callerMayPostToSpace (resolvers/messaging.ts:1081-1090).
4549
+ auth: "member",
4243
4550
  summary: "Post a message to a Space — authenticated member or public Space; stamps space:<slug> tag so the message appears in the Space's thread on slug/in alongside every channel's conversation",
4244
4551
  request: () => z.object({
4245
4552
  space: z.string(),
@@ -4258,6 +4565,8 @@ export const RECEIVERS = {
4258
4565
  }),
4259
4566
  "space:create": receiver({
4260
4567
  receiver: "space:create",
4568
+ // auth (owner) — task:01a128d6108e551f5966106b: handler requires callerControlsWorkspace(from, slug) (resolvers/space.ts:14-22).
4569
+ auth: "owner",
4261
4570
  summary: "Create a new Space — registers the channel_link inbox door in channels so every inbound signal is mirrored to the workspace thread read model; private flag restricts posting to members",
4262
4571
  request: () => z.object({
4263
4572
  slug: z.string(),
@@ -4274,6 +4583,8 @@ export const RECEIVERS = {
4274
4583
  }),
4275
4584
  "space:join": receiver({
4276
4585
  receiver: "space:join",
4586
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!from) return forbidden` (resolvers/space.ts:53-54).
4587
+ auth: "member",
4277
4588
  canonical: "world:request-access",
4278
4589
  summary: "Join a public Space — caller begins receiving its signals and their posts are stamped with the space tag",
4279
4590
  request: () => z.object({ space: z.string() }),
@@ -4286,6 +4597,8 @@ export const RECEIVERS = {
4286
4597
  }),
4287
4598
  "space:invite": receiver({
4288
4599
  receiver: "space:invite",
4600
+ // auth (owner) — task:01a128d6108e551f5966106b: handler requires callerControlsWorkspace(from, space) (resolvers/space.ts:76-83).
4601
+ auth: "owner",
4289
4602
  canonical: "world:invite-member",
4290
4603
  summary: "Invite an actor to a private Space — grants membership so they can read and post; requires the caller to be a member or admin of the Space",
4291
4604
  request: () => z.object({
@@ -4436,6 +4749,7 @@ export const RECEIVERS = {
4436
4749
  receiver: "entity:reply",
4437
4750
  summary: "Reply to a conversation — persists the message, delivers to the customer's channel (telegram/discord) when not web, clears the pending draft; kind:'note' stays internal",
4438
4751
  request: () => z.object({
4752
+ slug: SERVICE_SLUG,
4439
4753
  entityId: z.string(), // conv/session/thread id (alias: id)
4440
4754
  content: z.string(),
4441
4755
  kind: z.enum(["send", "note"]).optional(), // 'send' (default, egresses) | 'note' (internal)
@@ -4458,6 +4772,7 @@ export const RECEIVERS = {
4458
4772
  receiver: "entity:tag",
4459
4773
  summary: "Tag a conversation/entity (add/remove) or move it between lifecycle stages — the sole stage_transition writer",
4460
4774
  request: () => z.object({
4775
+ slug: SERVICE_SLUG,
4461
4776
  id: z.string(),
4462
4777
  add: z.array(z.string()).optional(),
4463
4778
  remove: z.array(z.string()).optional(),
@@ -4672,7 +4987,6 @@ export const RECEIVERS = {
4672
4987
  // conversation:autonomy — read by the channels worker per inbound turn (send vs
4673
4988
  // draft), not an operator/agent verb.
4674
4989
  // member:invited — an internal event hook, not a callable capability.
4675
- // ui:campaigns:compile · ui:campaigns:approve — UI build-pipeline steps.
4676
4990
  // These have live resolvers but no RECEIVERS entry by design — keep it that way.
4677
4991
  // ── commerce (storefront products) — handlers in resolvers/commerce.ts ─────────
4678
4992
  "products:create": receiver({
@@ -4681,16 +4995,14 @@ export const RECEIVERS = {
4681
4995
  request: () => z.object({
4682
4996
  slug: z.string(),
4683
4997
  name: z.string(),
4684
- prices: z.array(z.object({
4685
- unit_amount: z.number(),
4686
- currency: z.string().optional(),
4687
- price_type: z.string().optional(),
4688
- interval: z.string().optional(),
4689
- })),
4998
+ prices: z.array(productPriceInput),
4690
4999
  description: z.string().optional(),
4691
5000
  images: z.array(z.string()).optional(),
4692
5001
  product_type: z.string().optional(), // default 'one_time'
4693
5002
  collection: z.string().optional(),
5003
+ // Search tags, stored in the product's metadata JSON (no column). Lower-cased, de-duplicated and
5004
+ // capped at eight by the resolver; undeclared here, zod would strip them at the HTTP edge.
5005
+ tags: z.array(z.string()).optional(),
4694
5006
  // Same stripped-at-the-edge trap as the two artifact fields below, and it
4695
5007
  // cost more: resolvers/commerce.ts has read `data.status` since it shipped,
4696
5008
  // but the key was never declared here, so zod dropped it and EVERY product
@@ -4716,16 +5028,50 @@ export const RECEIVERS = {
4716
5028
  // `status` carries the same history as on products:create — the resolver has
4717
5029
  // always read it, the declaration never listed it, so zod stripped it and a
4718
5030
  // draft product could not be published through this receiver either.
4719
- request: () => z.object({ slug: z.string(), pid: z.string(), name: z.string().optional(), description: z.string().optional(), images: z.array(z.string()).optional(), collection: z.string().optional(), status: z.enum(["draft", "active", "archived"]).optional(), product_kind: z.enum(["artifact", "physical", "one_time"]).optional(), delivery_r2_key: z.string().optional() }),
5031
+ // `prices` was undeclared, so zod stripped it at the edge and a price edit in the
5032
+ // studio's ProductBuilder saved everything except the price. A submitted price
5033
+ // whose charged terms match a live row keeps its ppid (commerce.ts planPriceUpdate).
5034
+ request: () => z.object({ slug: z.string(), pid: z.string(), name: z.string().optional(), description: z.string().optional(), images: z.array(z.string()).optional(), collection: z.string().optional(), tags: z.array(z.string()).optional(), status: z.enum(["draft", "active", "archived"]).optional(), product_kind: z.enum(["artifact", "physical", "one_time"]).optional(), delivery_r2_key: z.string().optional(), prices: z.array(productPriceInput).optional() }),
4720
5035
  response: () => z.object({ pid: z.string().optional(), workspace: z.string().optional(), error: z.string().optional() }),
4721
5036
  effect: "ask", cost: "free", reversible: false, idempotent: true, auth: "member",
4722
5037
  }),
5038
+ "products:generate": receiver({
5039
+ receiver: "products:generate",
5040
+ summary: "Draft a product listing from what the seller has so far — description, tags, a collection (an existing one or a new name) and variant titles. Returns a PATCH for the editor and writes nothing; the pressed `focus` field is rewritten and every other field only filled when empty",
5041
+ request: () => z.object({
5042
+ slug: z.string().describe("The workspace whose shop this is — its collections are read and its credits pay for the one model turn"),
5043
+ name: z.string().describe("The product name — required, every other field is optional context"),
5044
+ focus: z.enum(["description", "tags", "collection", "variants", "all"]).optional().describe("Which Generate button was pressed; that field is rewritten, the others are only filled when empty. Default all"),
5045
+ description: z.string().optional().describe("What the seller has written so far; improved, never contradicted"),
5046
+ tags: z.array(z.string()).optional(),
5047
+ collection: z.string().optional(),
5048
+ price: z.number().optional().describe("Major units (dollars). Used to price generated variants"),
5049
+ ships: z.boolean().optional().describe("True for a physical parcel; false for a download, course or service"),
5050
+ variants: z.array(z.object({ title: z.string(), sku: z.string().optional(), price: z.string().optional(), stock: z.string().optional() })).optional(),
5051
+ }),
5052
+ response: () => z.object({
5053
+ patch: z.object({
5054
+ description: z.string().optional(),
5055
+ tags: z.array(z.string()).optional(),
5056
+ collection: z.string().optional(),
5057
+ variants: z.array(z.object({ title: z.string(), sku: z.string(), price: z.string(), stock: z.string() })).optional(),
5058
+ }).optional(),
5059
+ collections: z.array(z.string()).optional().describe("The shop's existing collections, for the editor's drop-down"),
5060
+ error: z.string().optional(),
5061
+ balance: z.number().optional(),
5062
+ needed: z.number().optional(),
5063
+ topupUrl: z.string().optional(),
5064
+ }),
5065
+ effect: "ask", cost: "variable", reversible: true, idempotent: false, auth: "member",
5066
+ }),
4723
5067
  "products:list": receiver({
4724
5068
  receiver: "products:list",
4725
5069
  surfaces: { mcp: true },
4726
5070
  summary: "List a workspace's storefront products with their prices (public). To buy as an agent: open an ACP session with POST /api/checkout_sessions, or pay the item's x402 link.",
4727
5071
  request: () => z.object({
4728
- slug: z.string().optional(),
5072
+ // Required: a public storefront read names its storefront. No default to the caller's own
5073
+ // group — an anonymous caller has none — so a missing slug is 400 validation field slug.
5074
+ slug: z.string(),
4729
5075
  collection: z.string().optional().describe("Narrow the catalogue to one collection, matched TRIMMED on both sides (the facet label is derived as `(collection ?? '').trim()`, so an untrimmed predicate would match zero rows and filter everything). Empty or unknown returns the whole catalogue, never an error. Public: it can only narrow rows an anonymous caller could already see — unlike includeDrafts, which is honoured only for the attested owner (ctx.ownerSlug), never a body claim."),
4730
5076
  includeDrafts: z.boolean().optional().describe("Owner-only: true returns draft products and every active price row. Honoured only when the attested caller owns slug (ctx.ownerSlug === slug); for anyone else it is ignored, never an error."),
4731
5077
  sort: z.string().optional().describe("featured | newest | price-asc | price-desc, trimmed and lower-cased by the resolver; anything else orders as featured (updated_at desc)."),
@@ -5192,6 +5538,79 @@ export const RECEIVERS = {
5192
5538
  effect: "ask", cost: "free", reversible: false, idempotent: false, settles: "none", auth: "manage_things",
5193
5539
  examples: [{ oid: "ord_1", session_id: "cs_test_1" }, { oid: "ord_1", workspace: "elitemoversca" }],
5194
5540
  }),
5541
+ // ── book:chapter / book:edit-passage — the writing room's chat (handler: resolvers/books.ts) ──
5542
+ // A PERSON edits a book: the viewer channels vouched for (X-One-Actor), a world key's actor, or
5543
+ // staff on a session — never the service key's nominated workspace alone — and only an author of
5544
+ // the book's workspace. Writes go to a DRAFT (the editor's own door, lib/books/chapter-store.ts),
5545
+ // one passage at a time, never the published book and never a whole chapter.
5546
+ "book:chapter": receiver({
5547
+ receiver: "book:chapter",
5548
+ summary: "Read one chapter of a book as its author has it now (the draft if there is one) — markdown, for the writing room's chat",
5549
+ request: () => z.object({
5550
+ book: z.string().min(1).describe("The book's slug, e.g. 100-million-years-ahead."),
5551
+ chapter: z.string().min(1).describe("The chapter: its number (\"3\"), slug, file or title."),
5552
+ slug: z.string().optional().describe("The workspace the call is made in (channels nominates it; it is not who may edit)."),
5553
+ }),
5554
+ response: () => z.object({
5555
+ ok: z.boolean(),
5556
+ book: z.string().optional(),
5557
+ chapter: z.object({ file: z.string(), slug: z.string(), number: z.number().nullable(), title: z.string() }).optional(),
5558
+ draft: z.object({ savedAt: z.string() }).nullable().optional(),
5559
+ words: z.number().optional(),
5560
+ body: z.string().optional().describe("The chapter's markdown (its title block is not part of it). At most 60,000 characters; `truncated` says when it was cut."),
5561
+ truncated: z.boolean().optional(),
5562
+ error: z.string().optional().describe("Named refusal: not_found · forbidden (no person, or not an author) · unavailable (roles or storage could not answer; retry)."),
5563
+ }),
5564
+ effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "none", auth: "manage_things",
5565
+ }),
5566
+ "book:edit-passage": receiver({
5567
+ receiver: "book:edit-passage",
5568
+ summary: "Change ONE passage of a book chapter's draft — replace it, or insert a new paragraph after/before the paragraph holding it",
5569
+ request: () => z.object({
5570
+ book: z.string().min(1).describe("The book's slug."),
5571
+ chapter: z.string().min(1).describe("The chapter: its number, slug, file or title."),
5572
+ find: z.string().min(1).max(4000).describe("An exact passage from the chapter as book:chapter returned it — it must occur exactly once. Quotes, dashes and spacing are matched loosely."),
5573
+ text: z.string().describe("The new text (markdown). For replace: what replaces `find` (empty deletes it). For insert_*: the paragraph(s) to add."),
5574
+ mode: z.enum(["replace", "insert_after", "insert_before"]).optional().describe("replace (default) · insert_after / insert_before the paragraph that holds `find`."),
5575
+ slug: z.string().optional().describe("The workspace the call is made in (channels nominates it; it is not who may edit)."),
5576
+ }),
5577
+ response: () => z.object({
5578
+ ok: z.boolean(),
5579
+ book: z.string().optional(),
5580
+ chapter: z.object({ file: z.string(), slug: z.string(), number: z.number().nullable(), title: z.string() }).optional(),
5581
+ mode: z.string().optional(),
5582
+ savedAt: z.string().nullable().optional().describe("The draft's new savedAt; null when the edit made the chapter its published text again (the draft is cleared)."),
5583
+ words: z.number().optional(),
5584
+ removed: z.string().optional(),
5585
+ added: z.string().optional(),
5586
+ url: z.string().optional().describe("The writing room, open on this chapter."),
5587
+ error: z.string().optional().describe("Named refusal: not_found · forbidden · unavailable · bad_request · not_applied (the passage is not in the chapter, or occurs more than once — read it again) · conflict (the author saved meanwhile — read it again) · cannot_typeset (the press could not print the result)."),
5588
+ }),
5589
+ effect: "ask", cost: "free", reversible: true, idempotent: false, settles: "none", auth: "manage_things",
5590
+ }),
5591
+ // ── book:claim — "Save to my library" (handler: resolvers/book-claim.ts) ──
5592
+ // The sibling of order:claim for a BOOK: same bearer proof (the Stripe
5593
+ // Checkout session_id the success page holds), but the result is a durable
5594
+ // entitlement `book:<slug>` in the CALLER's own workspace, so it is tenant-
5595
+ // class: the library it writes is ctx.ownerSlug's, never a body field. Card
5596
+ // rail only — a crypto order's session_id is a public tx hash, and a durable
5597
+ // grant keyed on a public value could be front-run. One session is spent once.
5598
+ "book:claim": receiver({
5599
+ receiver: "book:claim",
5600
+ summary: "Save a paid book to the signed-in caller's library — proves the purchase with the Stripe Checkout session_id and grants book:<slug>",
5601
+ request: () => z.object({
5602
+ session_id: z.string().min(1).describe("The Stripe Checkout session id from the success page URL (?session_id=cs_…) — the same receipt order:claim accepts. Card rail only; a crypto tx hash is refused as rail_not_claimable."),
5603
+ }),
5604
+ response: () => z.object({
5605
+ ok: z.boolean(),
5606
+ books: z.array(z.string()).optional().describe("Book slugs now in the caller's library (feature book:<slug>)."),
5607
+ already: z.boolean().optional().describe("True when the caller already held every book in this order; the session is spent either way."),
5608
+ error: z.string().optional().describe("Named refusal: session_id_required · forbidden · agent_not_claimable (an agent world key; a library is a signed-in reader's) · not_found (no order sold by one under this session — the webhook may not have landed yet; retry) · not_a_book (no line on the order is a book) · not_paid · refunded · test_mode · rail_not_claimable · already_claimed (another library already holds this session) · unavailable (D1 failed; retry) · no_db."),
5609
+ httpStatus: z.literal(503).optional().describe("Present only with unavailable / no_db: the door answers HTTP 503 so the refusal is retried, never cached as a 200 idempotent result."),
5610
+ }),
5611
+ effect: "ask", cost: "free", reversible: false, idempotent: true, settles: "none", auth: "manage_things",
5612
+ examples: [{ session_id: "cs_live_a1b2c3" }],
5613
+ }),
5195
5614
  // ── wallet:create — register RECEIVING ADDRESSES only (handler: resolvers/wallet.ts) ──
5196
5615
  // Custody invariant: `addresses` carries public addresses and nothing else. No
5197
5616
  // field here accepts a private key or a mnemonic, and none is emitted back.
@@ -5215,7 +5634,10 @@ export const RECEIVERS = {
5215
5634
  }).optional(),
5216
5635
  // An AGENT's addresses are written only with proof of control: the token
5217
5636
  // wallet:challenge issued, and one signature per address over
5218
- // addressProofMessage (@oneie/sdk/address-proof). Public bytes only.
5637
+ // addressProofMessage (@oneie/sdk/address-proof). Public bytes only. A HUMAN
5638
+ // row may carry the same proof (C11): a verified one is recorded in
5639
+ // wallet_address_proofs, which is what lets wallet:send prove who paid and
5640
+ // who was paid; without it the row is the body's word and proves nothing.
5219
5641
  challenge: z.string().optional(),
5220
5642
  proofs: z.object({
5221
5643
  sui: z.object({ publicKey: z.string().optional(), signature: z.string() }).optional(),
@@ -5237,12 +5659,88 @@ export const RECEIVERS = {
5237
5659
  btc: z.string().nullable().optional(),
5238
5660
  asi: z.string().nullable().optional(),
5239
5661
  }).optional(),
5662
+ proven: z.array(z.string()).optional().describe("Human row only: the chains whose address arrived with a verified proof and were recorded in wallet_address_proofs. Absent when no proof was offered"),
5240
5663
  error: z.string().optional(),
5241
5664
  field: z.string().optional(),
5242
5665
  }),
5243
5666
  effect: "ask", cost: "free", reversible: false, idempotent: true, settles: "none", auth: "member",
5244
5667
  examples: [{ workspace: "acme", kind: "human", addresses: { sui: "0xabc", evm: "0xdef" } }],
5245
5668
  }),
5669
+ "wallet:lock-publish": receiver({
5670
+ receiver: "wallet:lock-publish",
5671
+ summary: "Publish the caller's message lock (age1…) under their own name, proven by a Sui signature. The holder signs the exact text \"ONE message lock v1\\n<slug>\\n<lock>\" with the Sui key their account registered; the server rebuilds that text, checks the signature and that the signer IS the registered Sui address, then stores lock + signer + signature. The name is the attested session's, never the body's. An AGENT publishes its own lock with `agent` set to its id (the Bearer key's attested actor — a person, even the owner, is refused `not_the_agent`): the text is \"ONE message lock v1\\n<workspace>/<agent>\\n<lock>\" and the signer must be the Sui address on the agent's own wallet row. Refusals: unauthorized · forbidden · bad_slug · bad_lock · bad_agent · not_the_agent · no_sui_address · bad_signature · wrong_signer",
5672
+ request: () => z.object({
5673
+ lock: z.string().describe("The lock: age1 followed by 58 bech32 characters, as shown on /keys"),
5674
+ signature: z.string().describe("Sui personal-message signature (base64) over lockMessage(slug, lock), or agentLockMessage(workspace, agent, lock) for an agent — see lib/key/lock-lookup.ts"),
5675
+ agent: z.string().optional().describe("Agent form only: the agent's own id. Must equal the attested caller (ctx.actorId); never chooses whose lock is written"),
5676
+ workspace: z.string().optional().describe("Agent form: the workspace of the agent's wallet row (defaults to the agent's id; selects a row, grants nothing). Workspace form (no `agent`, C16): the workspace whose TREASURY lock and card to publish, as the (ws, ws) row — refused `forbidden` unless the caller controls it, and `wrong_signer` unless the workspace key's registered Sui account signed"),
5677
+ card: z.string().optional().describe("The pay card (text/wallets.md § 3), as text: \"ONE pay card v1\" + name · lock · id · ecdh · scan · spend — PUBLIC keys only. Stored beside the lock (0332 + 0333); refused `bad_card` unless it verifies for this name and this lock under the identity key it names AND is bound by the registered Sui key (`cardBind`). All three card fields or none. Sent without any card field, a publish KEEPS the card already stored for an unchanged lock"),
5678
+ cardSignature: z.string().optional().describe("The identity child's Sui personal-message signature (base64) over the exact card text — never the funded wallet key (D8)"),
5679
+ cardBind: z.string().optional().describe("The REGISTERED Sui key's personal-message signature (base64) over the exact card text — the same key that signed the lock. This is what binds the card to the page: without it any writer of the row could replay the public lock signature beside a card of their own"),
5680
+ }),
5681
+ response: () => z.object({
5682
+ ok: z.boolean(),
5683
+ lock: z.string().optional(),
5684
+ suiAddress: z.string().optional(),
5685
+ publishedAt: z.string().optional(),
5686
+ error: z.string().optional(),
5687
+ }),
5688
+ effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "none", auth: "member",
5689
+ examples: [{ lock: "age1…", signature: "AB…" }],
5690
+ }),
5691
+ "wallet:lock-get": receiver({
5692
+ receiver: "wallet:lock-get",
5693
+ summary: "Public read: the lock a name has published, with everything needed to re-verify it offline (lock, Sui signer, signature, the exact signed text, publishedAt). `published:false` when none, or when the signer is no longer the account's registered Sui address (after wallet:rotate). Also served as GET /api/lock/<slug>, and /api/lock/<slug>/<agent-id> for an agent's own lock",
5694
+ request: () => z.object({
5695
+ slug: z.string().describe("The name (workspace slug) whose lock to look up"),
5696
+ agent: z.string().optional().describe("An agent id in that workspace: answers the agent's own lock, never the workspace's person lock"),
5697
+ // F8 — the pay card is practice money (testnet): served only to a request that names the practice network
5698
+ // (GET /api/lock/<slug>?net=testnet) or an agent caller; otherwise `withheld: 'practice_net_only'`. Narrows only.
5699
+ net: z.string().optional().describe("Practice network ask ('testnet'): without it the pay card is withheld"),
5700
+ }),
5701
+ response: () => z.object({
5702
+ ok: z.boolean(),
5703
+ published: z.boolean().optional(),
5704
+ lock: z.string().optional(),
5705
+ suiAddress: z.string().optional(),
5706
+ signature: z.string().optional(),
5707
+ message: z.string().optional(),
5708
+ publishedAt: z.string().optional(),
5709
+ card: z.string().optional().describe("The pay card text, when the page published one bound (all three card fields are present together or absent together)"),
5710
+ cardSignature: z.string().optional().describe("The identity child's signature over the card text"),
5711
+ cardBind: z.string().optional().describe("The registered Sui key's signature over the card text — a reader checks it against the lock's verified signer"),
5712
+ withheld: z.string().optional().describe("Why the card is not here: 'practice_net_only' (no practice ask, F8) or 'agent_has_vault' (paid into its vault, C18d)"),
5713
+ error: z.string().optional(),
5714
+ }),
5715
+ effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "none", auth: "public",
5716
+ examples: [{ slug: "tony" }],
5717
+ }),
5718
+ "wallet:rotate": receiver({
5719
+ receiver: "wallet:rotate",
5720
+ summary: "Give up a HUMAN wallet row's registered addresses so a NEW key can register its own — the old set is written to the event log first, then every address column is cleared. Refuses an agent row (its addresses are proven, never typed) and a caller the authority walk does not place over the workspace",
5721
+ request: () => z.object({
5722
+ workspace: z.string().optional().describe("The workspace whose row rotates. Defaults to the attested caller"),
5723
+ actor: z.string().optional().describe("The row's actor. Defaults to the workspace — the human's own row"),
5724
+ reason: z.string().max(200).optional().describe("Why — kept in the audit event beside the cleared addresses"),
5725
+ }),
5726
+ response: () => z.object({
5727
+ ok: z.boolean().optional(),
5728
+ workspace: z.string().optional(),
5729
+ actor: z.string().optional(),
5730
+ cleared: z.object({
5731
+ sui: z.string().nullable().optional(),
5732
+ evm: z.string().nullable().optional(),
5733
+ solana: z.string().nullable().optional(),
5734
+ btc: z.string().nullable().optional(),
5735
+ asi: z.string().nullable().optional(),
5736
+ }).optional().describe("The addresses the rotate cleared, read inside the clearing batch — every one is also kept in wallet_rotated_addresses"),
5737
+ closed: z.enum(["mark", "warn"]).optional(),
5738
+ error: z.string().optional().describe("unauthorized · approval_required (a bare API key — needs a human session or a verified service caller) · forbidden · no_row · agent_row · no_db · history_unwritten (the cleared addresses could not be recorded in wallet_rotated_addresses, so nothing was cleared)"),
5739
+ detail: z.string().optional(),
5740
+ }),
5741
+ effect: "ask", cost: "free", reversible: false, idempotent: false, settles: "none", auth: "owner",
5742
+ examples: [{ workspace: "acme", reason: "new key" }],
5743
+ }),
5246
5744
  "wallet:challenge": receiver({
5247
5745
  receiver: "wallet:challenge",
5248
5746
  summary: "Issue a fresh, single-use challenge an agent signs to prove it holds the keys behind the addresses it registers with wallet:create",
@@ -5328,6 +5826,10 @@ export const RECEIVERS = {
5328
5826
  request: () => z.object({
5329
5827
  workspace: z.string().optional().describe("Defaults to the attested caller's workspace"),
5330
5828
  actor: z.string().optional().describe("Actor whose spend ceiling is read; defaults to the workspace"),
5829
+ // C13 repair 2 — the network the VAULT PROJECTION is read on (the /w `?net=` door);
5830
+ // defaults to the deploy's NETWORK. It moves the D1 read only: chain balances stay
5831
+ // on the deploy's endpoints. Each row's `vault.net` says which network it answered.
5832
+ net: z.enum(["mainnet", "testnet"]).optional().describe("Network whose vault projection the wallet rows read; defaults to the deploy's"),
5331
5833
  }),
5332
5834
  response: () => z.object({
5333
5835
  workspace: z.string().optional(),
@@ -5350,6 +5852,34 @@ export const RECEIVERS = {
5350
5852
  effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "none", auth: "member",
5351
5853
  examples: [{}, { workspace: "acme" }, { workspace: "acme", actor: "agent:scout" }],
5352
5854
  }),
5855
+ // wallet:update — the owner's one number: how many credits an agent may spend a month.
5856
+ // Lowering (and pausing at 0) is open to the workspace's controllers and to the agent for
5857
+ // itself, never a sibling; raising needs a person's hand (a session, or the owner's own human key).
5858
+ "wallet:update": receiver({
5859
+ receiver: "wallet:update",
5860
+ surfaces: { mcp: { name: "wallet_limit" } },
5861
+ summary: "Set an agent's spending limit in credits a month (0 pauses it). Lowering is open to the people who control the workspace and to the agent for itself (never a sibling); raising needs a person — a signed-in session or the owner's own key, never an agent key",
5862
+ request: () => z.object({
5863
+ actor: z.string().min(1).max(200).describe("The agent whose limit is set — its wallets row (kind 'agent') in `workspace`"),
5864
+ limit: z.number().int().min(0).max(10_000_000).describe("The spending limit in credits per month. 0 pauses the agent (every spend refused, liftable by the owner). 1000 credits = $1"),
5865
+ workspace: z.string().optional().describe("The workspace that holds the agent's wallet; defaults to the attested caller"),
5866
+ }),
5867
+ response: () => z.object({
5868
+ ok: z.boolean(),
5869
+ workspace: z.string().optional(),
5870
+ actor: z.string().optional(),
5871
+ monthlyCredits: z.number().optional(),
5872
+ spentCredits: z.number().optional().describe("What this period has used against the limit"),
5873
+ paused: z.boolean().optional(),
5874
+ changed: z.boolean().optional(),
5875
+ raised: z.boolean().optional(),
5876
+ closed: z.enum(["mark", "warn", "dissolve"]).optional(),
5877
+ detail: z.string().optional(),
5878
+ error: z.string().optional().describe("unauthorized | actor_required | no_db | bad_limit | forbidden | not_an_agent_wallet | zeroed_on_chain (the on-chain Zero is final) | human_presence_required (a raise from an agent or a bare key) | write_unconfirmed"),
5879
+ }),
5880
+ effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "none", auth: "member",
5881
+ examples: [{ actor: "scout", limit: 5000 }, { actor: "scout", limit: 0 }],
5882
+ }),
5353
5883
  "wallet:transactions": receiver({
5354
5884
  receiver: "wallet:transactions",
5355
5885
  surfaces: { mcp: true },
@@ -5357,12 +5887,14 @@ export const RECEIVERS = {
5357
5887
  request: () => z.object({
5358
5888
  workspace: z.string().optional().describe("Defaults to the attested caller's workspace"),
5359
5889
  limit: z.number().optional().describe("Rows to return; the handler caps at 500"),
5890
+ actor: z.string().optional().describe("One person's money in the workspace (the CRM Orders tab): settlements and orders keyed on the aid, the hash or address of their VERIFIED account email, or their rung-1 browser hashes. Only when the caller may read that contact; else 'forbidden'"),
5360
5891
  }),
5361
5892
  response: () => z.object({
5362
5893
  transactions: z.array(z.object({
5363
5894
  ts: z.number(), rail: z.string(), direction: z.enum(["in", "out"]), counterparty: z.string(),
5364
5895
  amountCents: z.number(), currency: z.string(), ref: z.string(), status: z.string(),
5365
5896
  })).optional(),
5897
+ truncated: z.boolean().optional().describe("With `actor`: true when more rows exist than `limit` returned"),
5366
5898
  error: z.string().optional(),
5367
5899
  }),
5368
5900
  effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "none", auth: "member",
@@ -5385,6 +5917,7 @@ export const RECEIVERS = {
5385
5917
  from: z.string().optional().describe("Alias for `workspace` — the source the authority walk runs against"),
5386
5918
  transferId: z.string().optional().describe("Idempotency key; both legs share it as rail_ref"),
5387
5919
  memo: z.string().optional(),
5920
+ ...WORK_CONTRACT_FIELDS,
5388
5921
  }),
5389
5922
  response: () => z.object({
5390
5923
  ok: z.boolean(),
@@ -5396,7 +5929,7 @@ export const RECEIVERS = {
5396
5929
  }),
5397
5930
  // Zero-sum inside the credit ledger — real value, settled OFFCHAIN (never on
5398
5931
  // chain), reversible by a compensating transfer. Idempotent on `transferId`.
5399
- effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "offchain", auth: "manage_workspace",
5932
+ effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "offchain", auth: "manage_workspace", moves: "value", movesIn: ["workspace", "from"],
5400
5933
  examples: [{ to: "acme", amount: 500 }],
5401
5934
  }),
5402
5935
  // The caller signs and broadcasts the transfer CLIENT-SIDE and passes the
@@ -5420,6 +5953,7 @@ export const RECEIVERS = {
5420
5953
  userAddress: z.string().optional().describe("Sender address; defaults to `to`"),
5421
5954
  memo: z.string().optional(),
5422
5955
  product: z.string().optional().describe("Falls back to `memo`, then a generated transfer label"),
5956
+ ...WORK_CONTRACT_FIELDS,
5423
5957
  }),
5424
5958
  response: () => z.object({
5425
5959
  ok: z.boolean(),
@@ -5449,9 +5983,19 @@ export const RECEIVERS = {
5449
5983
  verdict: z.string().optional().describe("On a stage 'authority' refusal: mismatch | unknown. 'unknown' FAILS CLOSED — an unresolvable read is never 'no objection'"),
5450
5984
  detail: z.string().optional().describe("On a stage 'authority' refusal: what was refused, and plainly that this refuses to RECORD the transfer — it cannot prevent or reverse an on-chain transfer the caller already signed and broadcast client-side"),
5451
5985
  cause: z.string().optional().describe("On a stage 'authority' refusal, which read decided it: no_attested_caller | no_snapshot_binding | wallet_read_failed | human_unresolvable (the agent has no claimed human with a Sui address) | ceiling_unresolvable | owners_disagree | ceiling_revoked. A public identifier, never a value"),
5986
+ // C11 — a recorded payment marks payer -> payee. Both keys ride the success path.
5987
+ verifiedUsd: z.number().optional().describe("The dollar value pay.one.ie verified on chain at claim — the only figure the reputation mark weighs. Absent when pay returned none"),
5988
+ reputation: z.object({
5989
+ marked: z.boolean().describe("true = payer -> payee was marked by the weighted mark of verifiedUsd"),
5990
+ payer: z.string().optional(),
5991
+ payee: z.string().optional().describe("The actor whose wallets row owns the paid address — never the body's say-so"),
5992
+ strength: z.number().optional().describe("The weighted mark applied"),
5993
+ settledTo: z.string().nullable().optional().describe("The workspace this payment settled to, recorded on the payer -> payee row at payment time — the payee's proven row's workspace, and the one fact meta:reputation discloses the row by. null when nothing was recorded: the address is proven under two workspaces, the workspace has no owners row yet, or the row already carried a different workspace (then it carries none, for good)"),
5994
+ reason: z.string().optional().describe("Why nobody was marked: payer_unproven | no_payee_actor | payee_mismatch | payee_ambiguous | own_wallet (the spend walk admits a holder of authority over the payer over the payee, or the payee over the payer — a wash trade buys no reputation) | authority_unreadable (the authority walk could not be read; nobody was marked) | amount_unverified | below_mark_floor | tx_already_marked | mark_unrecorded (the mark ledger write failed; the transfer still settled)"),
5995
+ }).optional().describe("Whether this payment raised the payee's score, and if not, why"),
5452
5996
  error: z.string().optional(),
5453
5997
  }),
5454
- effect: "ask", cost: "variable", reversible: false, idempotent: false, settles: "onchain", auth: "manage_workspace",
5998
+ effect: "ask", cost: "variable", reversible: false, idempotent: false, settles: "onchain", auth: "manage_workspace", moves: "value", movesIn: ["workspace", "from"],
5455
5999
  examples: [{ to: "0xabc", chain: "SUI", amount: 5, paymentTx: "8xKvQ1" }],
5456
6000
  }),
5457
6001
  // text/key.md deliverable 8 — bound what an agent HOLDS. Tony, 2026-10-06:
@@ -5563,37 +6107,138 @@ export const RECEIVERS = {
5563
6107
  summary: "The agent's current owner offers it to another person — a signed 'ONE agent handover' statement by the owner's proven address",
5564
6108
  request: () => z.object({
5565
6109
  agent: z.string().describe("The agent's actor id (actor_owners.agent_id)"),
5566
- to: z.string().describe("The person's slug the agent is offered to — never an agent"),
6110
+ to: z.string().optional().describe("The person's slug the agent is offered to — never an agent. Omitted (or 'invite') by an agent that owns itself: the offer mints the handover link and answers to: invite:<id>"),
5567
6111
  chain: z.enum(["sui", "evm", "solana", "btc"]).optional().describe("Which proven address signs; default sui"),
5568
- nonce: z.unknown().describe("16–128 of [A-Za-z0-9_-]; single use"),
5569
- expiresAt: z.unknown().describe("unix ms, at most 15 minutes out"),
5570
- signature: z.unknown().describe("{ publicKey, signature } (hex) by the owner's proven address over the handover statement"),
6112
+ nonce: z.unknown().optional().describe("16–128 of [A-Za-z0-9_-]; single use. Required person-to-person; minted when an agent sends the link"),
6113
+ expiresAt: z.unknown().optional().describe("unix ms, at most 15 minutes out. Required person-to-person"),
6114
+ signature: z.unknown().optional().describe("{ publicKey, signature } (hex) by the owner's proven address over the handover statement. Required person-to-person"),
6115
+ vault: z.string().optional().describe("The handover link (agent that owns itself): the vault object id (0x…) the redeemer will own"),
6116
+ workspace: z.string().optional().describe("The handover link: the workspace whose owner seat the link carries; default the agent's own. The agent must already hold that seat"),
5571
6117
  }),
5572
6118
  response: () => z.object({
5573
6119
  ok: z.boolean(), offered: z.boolean().optional(), agent: z.string().optional(), from: z.string().optional(), to: z.string().optional(),
5574
6120
  nonce: z.string().optional(), expiresAt: z.number().optional(),
6121
+ vault: z.string().optional(), link: z.string().optional().describe("The handover link's short path (/i/<code>) — never the token behind it"),
5575
6122
  closed: z.enum(["mark", "warn", "dissolve"]).optional(),
5576
- error: z.string().optional().describe("agent_and_to_required | unsupported_chain | unclaimed | agent_owns_itself | not_owner | human_presence_required | handover_to_self | handover_to_agent | target_is_agent | offer_invalid | offer_expired | offer_expiry_too_far | owner_address_unproven | offer_signature_invalid | offer_replayed"),
6123
+ error: z.string().optional().describe("agent_and_to_required | unsupported_chain | unclaimed | agent_owns_itself | not_owner | human_presence_required | handover_to_self | handover_to_agent | target_is_agent | offer_invalid | offer_expired | offer_expiry_too_far | owner_address_unproven | offer_signature_invalid | offer_replayed | vault_required | vault_not_held | vault_unreadable | offer_open | no_invite_secret | cannot_invite_higher_role"),
5577
6124
  }),
5578
6125
  effect: "ask", cost: "free", reversible: true, idempotent: false, settles: "none", auth: "owner",
5579
6126
  examples: [{ agent: "scout", to: "dana", chain: "sui", nonce: "<nonce>", expiresAt: 1790000000000, signature: { publicKey: "<hex>", signature: "<hex>" } }],
5580
6127
  }),
5581
6128
  "agent:handover-accept": receiver({
5582
6129
  receiver: "agent:handover-accept",
5583
- summary: "The person an agent was offered to accepts it, in their own session or human key — a compare-and-set on the agent's ownership",
6130
+ summary: "The person an agent was offered to accepts it, in their own session or human key — a compare-and-set on the agent's ownership; the Own press re-proves the link (owner · seat · vault) and lands seat → owner → chain, reverting on any refusal",
5584
6131
  request: () => z.object({
5585
- agent: z.string().describe("The agent's actor id"),
6132
+ agent: z.string().optional().describe("The agent's actor id. Required person-to-person; the Own press (/get-key?own=<offer>) knows only the offer, which names its agent"),
5586
6133
  nonce: z.unknown().describe("The offer's nonce"),
6134
+ address: z.string().optional().describe("The Own press: the Sui address of the key the redeemer kept"),
6135
+ signature: z.unknown().optional().describe("The Own press: { publicKey, signature } (hex) by that key over the 'ONE vault handover' statement"),
5587
6136
  }),
5588
6137
  response: () => z.object({
5589
6138
  ok: z.boolean(), accepted: z.boolean().optional(), agent: z.string().optional(), owner: z.string().optional(),
5590
6139
  previousOwner: z.string().optional(), next: z.string().optional(),
6140
+ vault: z.string().optional(), address: z.string().optional(),
6141
+ chain: z.unknown().optional().describe("The vault facade's answer to transferOwner: { digest } or { error } — never a claimed digest. { owner, confirmedBy: 'read' } when the transfer's answer was lost — or when the AGENT signed it in its own runtime — and the vault read back names the new owner. { error: 'agent_signs', vault, to, net } on a published vault: the server holds no key, the agent signs transfer_owner(vault, to) itself (round 7 repair 1)"),
6142
+ workspace: z.object({
6143
+ gid: z.string(), role: z.string(),
6144
+ landed: z.literal(true).describe("Always true on an ok answer: the Own press lands seat → owner → chain or reverts every write — an ok answer cannot carry a seat that did not land"),
6145
+ verdict: z.string(),
6146
+ }).optional().describe("The workspace owner seat the link carried, granted on the Own press before the owner and the chain moved"),
6147
+ undo: z.unknown().optional().describe("On a refusal only: a revert that itself did not land, named — { owner?: 'failed', seat?: <verdict>, offer?: 'failed', seatPending?: string[], residual: ('owner_revert_failed' | 'seat_revoke_failed' | 'seat_unproven' | 'seat_pending' | 'offer_unreserve_failed' | 'saga_unrecorded')[] }. Absent, nothing moved: every half was read back absent and every recorded seat attempt has settled. offer_unreserve_failed: the offer stayed spent, so the same redeemer cannot press again — the agent mints a new link (nothing else moved only when it is the sole residual). seat_revoke_failed: the seat is recorded on the offer row and the next press takes it back. seat_unproven: a seat write was not answered and the read-back ran too soon to prove it absent (a write the gateway aborts may still commit and take ~0.5s to become readable) — the attempt is APPENDED to the offer row's attempts with the time the write was sent and the time it answered or aborted, never overwritten by a later press; every later refusal reads every attempt back by its own times and drops it only once settled absent or taken back, and a press that lands clears them all. seat_pending: a recorded seat is on a gid (named in seatPending) where ANOTHER press of this agent is reserved and not yet landed — that press may hold the seat or still be refused, so the record is kept, never dropped and never reverted, and a later press settles it by the read-back once that press lands (explained, dropped), lapses or is refused (read back and reverted). saga_unrecorded: the row could not be written, so the next press cannot see the residual; a press held at the chain this way is found by the next press from the owner record and resumed. The agent has been warned"),
6148
+ pending: z.boolean().optional().describe("chain_pending: the chain was asked and could not be read back — seat and owner stay, the offer stays reserved, the row records the target; the redeemer's next press resolves it (finishes, retries, or reverts). agent_signs: the vault is published and the server never signs — the agent signs transfer_owner to the recorded address in its own runtime; seat and owner are NOT held moved while it waits, the offer stays reserved for the redeemer, and the next press lands both halves once the chain names the kept key (round 7 repair 1)"),
6149
+ cause: z.string().optional().describe("On reserve_failed | link_unreadable | seat_failed | owner_failed | vault_unreachable | chain_pending: the message of the call that threw, so the press names what it could not do"),
5591
6150
  closed: z.enum(["mark", "warn", "dissolve"]).optional(),
5592
- error: z.string().optional().describe("offer_invalid | human_presence_required | offer_not_found | not_offered_to_you | offer_already_accepted | offer_expired | offer_stale"),
6151
+ error: z.string().optional().describe("offer_invalid | human_presence_required | offer_not_found | not_offered_to_you | offer_already_accepted | offer_expired | offer_stale | invite_not_redeemed | redeemer_unresolved | owner_proof_invalid | reserve_failed | seat_lost | seat_unreadable | seat_failed | vault_not_held | vault_unreadable | vault_refused | agent_signs | link_unreadable | owner_failed | vault_unreachable | chain_pending — every refusal after the reservation reverted what had landed and gave the offer back (an unanswered write is read back first, never counted 'did not land'; one that answered ok with zero rows did not land); undo names a revert that did not; chain_pending is the one named pending state, resolved by the next press; redeemer_unresolved: the link was opened by an account that has no slug yet"),
5593
6152
  }),
5594
6153
  effect: "ask", cost: "free", reversible: false, idempotent: false, settles: "none", auth: "owner",
5595
6154
  examples: [{ agent: "scout", nonce: "<nonce>" }],
5596
6155
  }),
6156
+ // identity-seal deliverable 6. The owner is the ATTESTED caller (session, or the owner's own
6157
+ // human key) — never a body field; zod strips any owner the body names. The delete is a
6158
+ // compare-and-set on the owner read, so a row that changed hands is never removed.
6159
+ "agent:release": receiver({
6160
+ receiver: "agent:release",
6161
+ summary: "The agent's owner gives it up — ends the actor_owners claim, the owner's owner/admin seats on the agent's group and their world_actors rung (not world keys, and not the agent's home workspace, which keeps operational authority) (compare-and-set on the owner) and writes a custom:agent-released event; refused (vault_owned) while ANY vault is bound to, created by or filed for the agent, its own included, because D1 cannot prove which recorded addresses are really the agent's; a fresh claim is then possible",
6162
+ request: () => z.object({
6163
+ agent: z.string().describe("The agent's actor id (actor_owners.agent_id). The owner is read from the signed-in caller, never from the body"),
6164
+ }),
6165
+ response: () => z.object({
6166
+ ok: z.boolean(), released: z.boolean().optional(), agent: z.string().optional(),
6167
+ previousOwner: z.string().optional().describe("Who owned the agent until this call — the caller"),
6168
+ seatsRemoved: z.number().optional().describe("Owner/admin seats the caller held on the agent's own group (TypeDB) that were removed"),
6169
+ rungDemoted: z.boolean().optional().describe("The caller's owner/admin rung on the agent's own group in world_actors was demoted to member (the person's row is never deleted)"),
6170
+ homeWorkspaceKept: z.boolean().optional().describe("true when the agent is homed in a workspace: release does NOT re-home it and does NOT revoke its world keys, so that workspace still holds operational authority over it (key minting is decided by the home)"),
6171
+ homeGroup: z.string().optional().describe("The agent's home group id when homeWorkspaceKept is true"),
6172
+ noKnownAddress: z.boolean().optional().describe("true when no address is recorded for the agent anywhere: no vault could be matched by address, so only the agent-id checks (handover offers, training vaults) ran"),
6173
+ homeUnread: z.boolean().optional().describe("true when the agent's home record could not be read, so homeWorkspaceKept is unknown"),
6174
+ eventLanded: z.boolean().optional().describe("false when the custom:agent-released event could not be written — the release still stands"),
6175
+ next: z.string().optional().describe("On a refusal: what to do instead (vault_owned, vault_unverified, release_half_done)"),
6176
+ left: z.string().optional().describe("release_half_done only: the state left behind (seat_removed_owner_kept — the owner row stands but the seats named in `seats` were removed and could not be restored)"),
6177
+ refusedFor: z.string().optional().describe("release_half_done only: the refusal the release was undoing when the restore failed"),
6178
+ seats: z.array(z.string()).optional().describe("release_half_done only: the group ids whose seat could not be restored"),
6179
+ closed: z.enum(["mark", "warn", "dissolve"]).optional(),
6180
+ error: z.string().optional().describe("agent_required | no_db | human_presence_required | owner_unreadable | not_owner | unclaimed | agent_owns_itself | vault_owned | vault_unverified | seat_unreadable | seat_revoke_failed | release_failed | release_half_done | owner_changed — vault_owned: a vault is bound to, created by or filed for the agent (whoever owns it, the agent included — D1 cannot prove which addresses are really the agent's), the server cannot move a vault owner back, hand the agent over instead; vault_unverified: the vault records could not be read; seat_unreadable: the agent's group or the caller's seat could not be read; release_failed: the D1 write failed and the seats were put back; release_half_done: a seat was removed and could not be restored; owner_changed: the row changed hands between the read and the delete, and nothing was removed"),
6181
+ }),
6182
+ effect: "ask", cost: "free", reversible: false, idempotent: false, settles: "none", auth: "owner",
6183
+ examples: [{ agent: "scout" }],
6184
+ }),
6185
+ // C22 — the testnet training ground. One call per step a roster agent takes. The agent is the
6186
+ // ATTESTED caller (its own API key), never a body field; the body names no agent, network or
6187
+ // package, and zod strips any that are sent. The STEP decides who observes it: a chain step needs
6188
+ // a digest the server re-reads on Sui testnet, and it counts only as the agent's proven address
6189
+ // calling its filed vault for the pinned amount and payee; a harness step is the harness's word and
6190
+ // is never weighed. The expectation comes from lib/training/scenarios.ts, never the body, and the
6191
+ // verdict is computed here, closed on `training:<agent>` → `training:referee:<workspace>`, a path
6192
+ // no reputation reader counts.
6193
+ "training:record": receiver({
6194
+ receiver: "training:record",
6195
+ summary: "Record one step of a testnet training run: the step decides whether the chain (by digest) or the harness observes, the server decides the verdict and closes it on the namespaced training path",
6196
+ request: () => z.object({
6197
+ run: z.string().min(1).max(64).describe("The run id the harness minted for this run"),
6198
+ scenario: z.string().max(32).describe("One of the seven pinned scenario ids (lib/training/scenarios.ts)"),
6199
+ step: z.string().max(32).describe("A pinned step id of that scenario, or turn-1…turn-8 for a free turn in agent mode"),
6200
+ rule: z.string().max(32).describe("The scenario's rule, a bare word; must match the pin"),
6201
+ mode: z.enum(["scripted", "agent"]).describe("scripted (drill, fixed actions) or agent (a model chose the tool)"),
6202
+ tool: z.string().max(32).describe("The tool the agent chose (the closed list) or the harness move the step names"),
6203
+ payee: z.string().max(64).optional().describe("Who the money went to (a roster name or 'ground'), for the side-door read; anything else is bad_step"),
6204
+ expected: z.string().max(96).describe("What the rule predicts — must equal the pinned expectation, or the step is bad_step"),
6205
+ digest: z.string().max(44).optional().describe("A chain step's testnet transaction digest — REQUIRED on a chain step, re-read on Sui testnet"),
6206
+ refusal: z.string().max(96).optional().describe("A harness step's word (a ONE door's answer or a read); on a chain step it is digest_required"),
6207
+ }),
6208
+ response: () => z.object({
6209
+ ok: z.boolean(),
6210
+ verdict: z.enum(["kept", "rule_silent", "wrong_refusal", "side_door", "deploy_fenced", "needs_person"]).optional(),
6211
+ observed: z.string().optional(),
6212
+ observed_by: z.enum(["chain", "harness"]).optional(),
6213
+ closed: z.enum(["mark", "warn", "dissolve"]).optional(),
6214
+ error: z.enum(["digest_not_on_testnet", "digest_required", "tx_not_this_step", "not_a_roster_agent", "bad_step"]).optional(),
6215
+ }),
6216
+ effect: "ask", auth: "agent_key", cost: "free", reversible: false, idempotent: false, settles: "none",
6217
+ examples: [{ run: "run-01", scenario: "ceiling", step: "over-tx", rule: "ceiling", mode: "scripted", tool: "vault_spend", payee: "referee", expected: "E_CEILING", digest: "<testnet digest>" }],
6218
+ }),
6219
+ // C22 (c22 review B3) — the vault object a roster agent's chain steps must spend from. Filed ONLY by
6220
+ // the training workspace's own identity (the attested caller is the workspace, never an agent), and
6221
+ // only for an object the testnet node reads as a Vault of the pinned package. A run's own vault
6222
+ // (run + scenario) wins over the agent's standing one. training:record counts no spend from any other
6223
+ // object — the agent's own look-alike vault of the same package included.
6224
+ "training:vault": receiver({
6225
+ receiver: "training:vault",
6226
+ summary: "File the vault object a training agent's chain steps must spend from — the workspace owner only, a pinned-package Vault only",
6227
+ request: () => z.object({
6228
+ agent: z.string().min(1).max(128).describe("The roster agent's aid"),
6229
+ vault: z.string().min(3).max(66).describe("The vault object id on Sui testnet"),
6230
+ run: z.string().max(64).optional().describe("The run a fresh vault was born for (with scenario); absent for the standing vault"),
6231
+ scenario: z.string().max(32).optional().describe("The scenario a fresh vault was born for (with run)"),
6232
+ transferTo: z.string().max(66).optional().describe("handover: the address transfer_owner must name"),
6233
+ }),
6234
+ response: () => z.object({
6235
+ ok: z.boolean(),
6236
+ closed: z.enum(["dissolve"]).optional(),
6237
+ error: z.enum(["not_the_owner", "not_a_roster_agent", "not_a_vault", "bad_vault"]).optional(),
6238
+ }),
6239
+ effect: "ask", auth: "owner", cost: "free", reversible: true, idempotent: true, settles: "none",
6240
+ examples: [{ agent: "<aid>", vault: "<testnet vault id>" }],
6241
+ }),
5597
6242
  // A pending, attributed `settlements` row is written before a cent moves —
5598
6243
  // INSERT OR IGNORE keyed on the pay link id, so a retry with the same link is a
5599
6244
  // no-op. An unpayable actor is a clean refusal: no link minted, no row written.
@@ -5603,33 +6248,239 @@ export const RECEIVERS = {
5603
6248
  summary: "Hand a payable actor a working payment link, with the money attributed to it before a cent moves",
5604
6249
  request: () => z.object({
5605
6250
  actor: z.string().describe("The actor being paid — attributed here even when custody is via-treasury"),
5606
- amountCents: z.number().describe("Must be > 0"),
6251
+ amountCents: z.number().optional().describe("Must be > 0 — except with railOnly, which takes none (rail_only_takes_no_amount)"),
6252
+ // C16 — ask WHICH RAIL a payer would be given, and tell ONE no sum. A treasury whose private branch
6253
+ // applies answers { custody: 'private', workspace, asset, chain, gasSui, payTo } with no amountCents;
6254
+ // anything else answers { rail: 'fixed', why? } and mints nothing. The amount rides a second call.
6255
+ railOnly: z.boolean().optional().describe("Ask the rail only: send no amountCents; nothing is minted or written"),
5607
6256
  workspace: z.string().optional().describe("Defaults to the attested caller's workspace"),
5608
6257
  currency: z.string().optional().describe("Defaults to usd"),
6258
+ // F8 — the PRACTICE-NETWORK ask. The fresh-address rail and a stranger's vault deposit instruction
6259
+ // exist on testnet only, so they answer ONLY a request that names the practice network ('testnet')
6260
+ // — or an agent caller. An open string, never an enum: any other word is simply no ask and
6261
+ // the ordinary rail answers. It only ever NARROWS: the worker ANDs it with the network it runs on.
6262
+ net: z.string().optional().describe("Practice network ask ('testnet'). Absent = the ordinary rail; never widens"),
5609
6263
  }),
5610
6264
  response: () => z.object({
5611
6265
  url: z.string().optional(),
6266
+ // railOnly: 'fixed' — today's path applies, so ask again WITH the amount.
6267
+ rail: z.string().optional(),
5612
6268
  linkId: z.string().optional(),
6269
+ // 'off' (a link) · 'on' (an escrow address) · 'scoped' (a deposit into the payee's
6270
+ // vault object, C13) — what the answer below IS.
6271
+ custody: z.string().optional(),
6272
+ // C13 (text/wallets-todo.md ruling 5) — a 'scoped' payee's answer: pay INTO the vault.
6273
+ // `amount` is the coin's BASE UNITS as a decimal string (USDC: 6 decimals; cents x
6274
+ // 10_000), the figure the facade's `deposit` puts on chain; `network` is the VAULT's
6275
+ // own network (the one whose pinned USDC it holds — repair 2, finding 2) and
6276
+ // `package` the vault package pinned there. An instruction is never handed out
6277
+ // without a package: a vault on a network with none is refused by name
6278
+ // (`scoped_deposit_unbuilt`). No link, no settlement row: the vault is the attribution.
6279
+ // C18e — a caller who does not control the workspace is never told the amount back:
6280
+ // its instruction carries the public facts only, and `amount` is absent.
6281
+ deposit: z.object({
6282
+ vault: z.string(),
6283
+ coinType: z.string(),
6284
+ amount: z.string().optional(),
6285
+ network: z.string(),
6286
+ package: z.string(),
6287
+ }).optional(),
5613
6288
  payTo: z.object({
5614
- // An OPEN string, never an enum. 'self' | 'via-treasury' | 'none' today;
5615
- // wallet-authority's ScopedWallet adds 'scoped' (payee = an object id,
5616
- // no chain), and that must not need a registry change to be
5617
- // representable. An UNKNOWN value is refused BY NAME at payee resolution
5618
- // (`unsupported_custody:<value>`, resolvers/wallet.ts) — never a crash,
5619
- // never a silent fallback to 'self' or to the SUI rail.
6289
+ // An OPEN string, never an enum. 'self' | 'via-treasury' | 'none' | 'scoped'
6290
+ // (C13: payee = a vault object id, `vault` below, no address). An UNKNOWN value
6291
+ // is refused BY NAME at payee resolution (`unsupported_custody:<value>`,
6292
+ // resolvers/wallet.ts) — never a crash, never a silent fallback to 'self' or to
6293
+ // the SUI rail.
5620
6294
  custody: z.string(),
5621
6295
  chain: z.string().optional(),
5622
6296
  address: z.string().optional(),
6297
+ vault: z.string().optional(),
5623
6298
  attributeTo: z.string().optional(),
5624
6299
  }).optional(),
5625
- error: z.string().optional(),
5626
- }),
5627
- effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "none", auth: "manage_workspace",
6300
+ // C16 (the treasury's card) — custody 'private': money that lands at the TREASURY is paid
6301
+ // to a fresh one-time address the PAYER derives from the treasury's public card (served at
6302
+ // /api/lock/<workspace>, re-verified in the payer's browser). The answer names no address:
6303
+ // `workspace` whose card to read, the `asset` and `chain` the tweak names (testnet USDC),
6304
+ // `amountCents` (absent on a railOnly answer: ONE is never told the sum), and `gasSui` — the few
6305
+ // cents of SUI the payer adds for the sale's later move (the sale is HELD at its own address until
6306
+ // the owner's device moves it; a move links that payer to the treasury).
6307
+ // Custody 'on' keeps the treasury's fixed sweep destination, card or no card: the sweep
6308
+ // sends USDC and no SUI, so a one-time address could not pay the gas to move it on
6309
+ // (`why: 'sweep_no_gas'`). `why` rides beside today's link or escrow when the card does not
6310
+ // apply: `no_card` · `show_addresses` · `not_testnet` · `agent_attribution` · `sweep_no_gas`.
6311
+ workspace: z.string().optional(),
6312
+ asset: z.string().optional(),
6313
+ chain: z.string().optional(),
6314
+ amountCents: z.number().optional(),
6315
+ gasSui: z.string().optional(),
6316
+ why: z.string().optional(),
6317
+ // Refusals by name (resolvers/wallet.ts): `vault_on_other_network:<net>` — the agent
6318
+ // owns a vault, on the network the suffix names, not this worker's (C13 repair 3:
6319
+ // never a silent self / via-treasury link for an agent that owns a vault);
6320
+ // `amountCents_over_u64` — an integer past MAX_CENTS (u64 / 10_000);
6321
+ // `scoped_deposit_unbuilt` — a vault on a network with no package pinned;
6322
+ // `treasury_card_unreadable` (C16) — the card could not be read; nothing minted;
6323
+ // `not_payable` (C18e) — what a caller who does not control the workspace hears for every
6324
+ // reason a visible agent's vault deposit cannot be offered (the names are the controller's).
6325
+ error: z.string().optional(),
6326
+ }),
6327
+ // C18e ruling 1 — `public` at the edge so a visitor reaches the ONE branch it may: an agent with an
6328
+ // active vault on this worker's network answers the scoped deposit instruction (public facts on
6329
+ // chain) to any caller. Every other answer is still the workspace's controller only, and never a
6330
+ // sessionless agent key — the resolver carries the rule this label used to (resolvers/wallet.ts).
6331
+ effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "none", auth: "public",
5628
6332
  examples: [
5629
6333
  { actor: "agent:scout", amountCents: 2500 },
5630
6334
  { workspace: "acme", actor: "agent:scout", amountCents: 2500, currency: "usd" },
5631
6335
  ],
5632
6336
  }),
6337
+ // swap:quote + swap:get (text/swap-plan.md) — any coin to any coin, and straight into
6338
+ // Hyperliquid, through NEAR Intents 1Click's deposit-address model. The server QUOTES and
6339
+ // READS; the person's own key sends to the deposit address, client-side, after the client
6340
+ // has read the quote back from 1Click directly (R16). ONE never holds a key or a cent, so
6341
+ // neither door carries `moves` (value-moving-parity.test.ts records why). 1Click is mainnet
6342
+ // only: every answer says network:'mainnet', and net:'testnet' is refused by name.
6343
+ "swap:quote": receiver({
6344
+ receiver: "swap:quote",
6345
+ surfaces: { mcp: true },
6346
+ summary: "Price a swap of any coin to any coin, or into Hyperliquid; live, get the deposit address your OWN wallet sends to — ONE never holds funds. Dry by default",
6347
+ request: () => z.object({
6348
+ from: z.string().describe("What you pay with, as an alias: BTC, SOL, SUI, USDC@sui, ETH@ethereum, ETH@base, ETH@arbitrum, USDC@ethereum, USDC@base, USDC@arbitrum, USDC@solana, USDT@ethereum, USDT0@arbitrum. A symbol on several chains must name its chain. An unknown alias returns the whole table"),
6349
+ to: z.string().describe("What you receive, as an alias; 'hyperliquid' or 'hl' = USDC in your Hyperliquid perps account. Bare ETH→ethereum, USDC→base, USDT→ethereum"),
6350
+ amount: z.string().describe("Decimal string in the FROM asset (in the TO asset when exact is 'out'), e.g. '0.01' — never a number; converted to base units exactly"),
6351
+ exact: z.enum(["in", "out"]).optional().describe("'in' (default): spend exactly amount · 'out': receive exactly amount; slippage applies to the input"),
6352
+ dry: z.boolean().optional().describe("true (default) = price only, no deposit address · false = mint a live deposit address; needs a signed-in person or a world key"),
6353
+ recipient: z.string().optional().describe("Destination address. Absent = your own address on the destination chain. Someone else's needs toOther:true"),
6354
+ refundTo: z.string().optional().describe("Only to choose among YOUR OWN source-chain addresses (the options of ambiguous_address). Absent = your one owned address. Someone else's is refused (refund_not_yours); toOther never applies"),
6355
+ toOther: z.boolean().optional().describe("true = recipient is deliberately someone else's; echoed back. A person's session only — an agent key is refused. Never applies to the refund address"),
6356
+ slippageBps: z.number().optional().describe("Max slippage in basis points, an integer 1–500; default 100 (1%). Out of range is refused bad_slippage"),
6357
+ net: z.string().optional().describe("1Click is mainnet only: 'testnet' is refused by name (oneclick_mainnet_only), never answered with mainnet"),
6358
+ }),
6359
+ response: () => z.object({
6360
+ ok: z.boolean().describe("true = a quote; false = a named refusal in error"),
6361
+ error: z.string().optional().describe("unknown_asset · ambiguous_asset · not_a_destination · hyperliquid_origin_unsupported · bad_amount · bad_slippage · same_asset · oneclick_mainnet_only · sign_in_required · platform_cannot_swap · live_quote_limit · refund_address_unknown · refund_not_yours · ambiguous_address · recipient_address_unknown · recipient_not_yours · toOther_needs_person · destination_unsignable · refund_unsignable · recipient_must_be_named · refund_must_be_named · recipient_invalid · refund_invalid · amount_too_low · amount_too_small_for_fees · exact_out_needs_funded_account · no_liquidity · asset_unsupported · memo_unsupported · quote_refused · oneclick_timeout · oneclick_unavailable · oneclick_error"),
6362
+ detail: z.string().optional().describe("1Click's own message on an upstream refusal, verbatim"),
6363
+ options: z.array(z.string()).optional().describe("ambiguous_asset: aliases to choose from · ambiguous_address: your addresses to choose from (pass one as recipient or refundTo)"),
6364
+ assets: z.array(SWAP_ASSET).optional().describe("unknown_asset: the whole table (never paged)"),
6365
+ minimum: z.string().optional().describe("amount_too_low: the minimum 1Click named, as a decimal in FROM, only when its unit is known; otherwise read detail"),
6366
+ network: z.string().describe("Always 'mainnet' — real chains, real money"),
6367
+ dry: z.boolean().optional().describe("Echo: true = price only"),
6368
+ from: SWAP_ASSET.optional().describe("Resolved origin"),
6369
+ to: SWAP_ASSET.optional().describe("Resolved destination"),
6370
+ route: z.object({
6371
+ via: z.string().describe("'1click' (NEAR Intents 1Click) — v1's only route"),
6372
+ steps: z.array(z.string()).describe("Human steps, in order"),
6373
+ credits: z.string().optional().describe("Hyperliquid only: 'perps' — USDC lands in the perps balance"),
6374
+ }).optional().describe("How the coins get there"),
6375
+ depositAddress: z.string().optional().describe("Live only: the key swap:get takes. Send exactly send.amount here — verify it with 1Click first"),
6376
+ amountIn: z.string().optional().describe("Decimal you send"),
6377
+ minAmountIn: z.string().optional().describe("exact 'out': lowest input accepted, decimal"),
6378
+ amountOut: z.string().optional().describe("Decimal you receive (withdraw fee already taken)"),
6379
+ minAmountOut: z.string().optional().describe("Decimal floor after slippage"),
6380
+ amountInUsd: z.string().optional().describe("USD value in, per 1Click"),
6381
+ amountOutUsd: z.string().optional().describe("USD value out, per 1Click"),
6382
+ costUsd: z.string().optional().describe("amountInUsd − amountOutUsd, plus a possible Hyperliquid activation when it applies"),
6383
+ fees: z.array(z.object({
6384
+ kind: z.string().describe("protocol (1Click) · app (ONE) · withdraw (destination chain) · refund (only on a refund)"),
6385
+ bps: z.number().optional().describe("Basis points, for protocol/app"),
6386
+ amount: z.string().optional().describe("Decimal amount"),
6387
+ asset: z.string().optional().describe("Alias the amount counts in"),
6388
+ note: z.string().optional().describe("One line for a human"),
6389
+ })).optional().describe("Every fee read from the live quote — none hardcoded"),
6390
+ timeEstimateSec: z.number().optional().describe("Seconds after the deposit confirms"),
6391
+ refundAfter: z.string().optional().describe("ISO: if not filled by now, refunds begin. Never send after this"),
6392
+ addressExpires: z.string().optional().describe("Live only, ISO: deposit address goes inactive"),
6393
+ quotedAt: z.string().optional().describe("1Click's timestamp — clients correct their clock skew with it before the deadline check"),
6394
+ recipient: z.string().optional().describe("Where the coins go — echoed"),
6395
+ refundTo: z.string().optional().describe("Where a refund goes — always your own address on the source chain"),
6396
+ ownership: z.object({
6397
+ recipient: z.string().describe("proven (signature) · registered (your row, session only) · other (toOther) · placeholder (dry)"),
6398
+ refundTo: z.string().describe("proven · registered · placeholder"),
6399
+ note: z.string().describe("Which row each address came from and what was and was not verified, in one sentence"),
6400
+ }).optional().describe("Whose addresses these are, and how ONE knows"),
6401
+ send: z.object({
6402
+ how: z.string().describe("browser · external"),
6403
+ to: z.string().describe("The deposit address"),
6404
+ amountBase: z.string().describe("Exact base units"),
6405
+ amount: z.string().describe("Same, as a decimal"),
6406
+ asset: z.string().describe("Alias to send"),
6407
+ chain: z.string().describe("Chain to send on — the wrong chain loses funds"),
6408
+ uri: z.string().optional().describe("Wallet link: bitcoin: (BIP21), solana:, or ethereum: (EIP-681); scan or tap in any wallet"),
6409
+ refundsTo: z.string().describe("Where a failed swap refunds, and how to recover it, in one sentence"),
6410
+ }).optional().describe("Live only: the exact send instruction — plain transfer, self-custody wallet, no bridge"),
6411
+ hyperliquid: z.object({
6412
+ checked: z.boolean().describe("false = the account read failed; treated as possibly new"),
6413
+ firstDeposit: z.boolean().describe("true = empty account; Hyperliquid MAY take a one-time ~1 USDC activation (unverified)"),
6414
+ }).optional().describe("Hyperliquid destination with YOUR recipient only — absent for placeholders"),
6415
+ keyed: z.boolean().optional().describe("true = ONE's partner key was used (live only); false = keyless fee schedule"),
6416
+ warnings: z.array(z.string()).optional().describe("poor_rate:<pct kept> · possible_activation_fee · external_send · jwt_rejected · app_fee_off · amount_too_small_for_fees (dry only; live refuses) · exact_out_needs_funded_account (dry only; live refuses)"),
6417
+ link: z.string().optional().describe("Absolute one.ie URL: dry = a prefilled /swap form a person can sign from · live = its status page"),
6418
+ next: z.string().describe("One sentence: what to do now. An agent cannot sign — give the person the link, or the exact send line"),
6419
+ }),
6420
+ examples: [
6421
+ { from: "USDC@base", to: "hl", amount: "10" },
6422
+ { from: "BTC", to: "hyperliquid", amount: "0.001" },
6423
+ { from: "SUI", to: "ETH", amount: "25" },
6424
+ ],
6425
+ effect: "ask", cost: "free", reversible: true, idempotent: false, settles: "none", auth: "public",
6426
+ }),
6427
+ "swap:get": receiver({
6428
+ receiver: "swap:get",
6429
+ surfaces: { mcp: true },
6430
+ summary: "Track a swap by its deposit address until it lands or refunds, and read any Hyperliquid account's balance",
6431
+ request: () => z.object({
6432
+ depositAddress: z.string().optional().describe("The deposit address swap:quote returned"),
6433
+ depositMemo: z.string().optional().describe("Memo, for memo chains only"),
6434
+ txHash: z.string().optional().describe("Your deposit tx hash — forwarded to 1Click to speed matching. NOT a verification; status stays the truth"),
6435
+ hyperliquid: z.string().optional().describe("A 0x address: also read its Hyperliquid balance (perps + spot, never summed)"),
6436
+ net: z.string().optional().describe("For the asked hyperliquid read only: 'testnet' reads api.hyperliquid-testnet.xyz. The swap and the post-SUCCESS read are always mainnet"),
6437
+ }),
6438
+ response: () => z.object({
6439
+ ok: z.boolean().describe("true = read; false = named refusal"),
6440
+ error: z.string().optional().describe("nothing_to_read · address_unknown · bad_address · bad_tx_hash · oneclick_timeout · oneclick_unavailable · oneclick_error · hyperliquid_unavailable"),
6441
+ detail: z.string().optional().describe("1Click's own message on an upstream refusal, verbatim"),
6442
+ network: z.string().describe("'mainnet' for the swap"),
6443
+ status: z.string().optional().describe("PENDING_DEPOSIT · KNOWN_DEPOSIT_TX · INCOMPLETE_DEPOSIT · PROCESSING · SUCCESS · REFUNDED · FAILED"),
6444
+ terminal: z.boolean().optional().describe("true at SUCCESS · REFUNDED · FAILED — stop polling"),
6445
+ explain: z.string().optional().describe("One human sentence for this status (INCOMPLETE_DEPOSIT: less than quoted arrived; refunded minus refundFee)"),
6446
+ submitted: z.boolean().optional().describe("txHash was forwarded to 1Click — not verified"),
6447
+ from: z.string().optional().describe("Origin alias (or raw assetId if not in the table)"),
6448
+ to: z.string().optional().describe("Destination alias (or raw assetId)"),
6449
+ recipient: z.string().optional().describe("Destination address, from 1Click's stored quote"),
6450
+ refundTo: z.string().optional().describe("Refund address, from 1Click's stored quote"),
6451
+ amountIn: z.string().optional().describe("Decimal deposited"),
6452
+ amountOut: z.string().optional().describe("Decimal delivered"),
6453
+ amountOutUsd: z.string().optional().describe("USD delivered"),
6454
+ refundedAmount: z.string().optional().describe("Decimal refunded"),
6455
+ refundReason: z.string().optional().describe("1Click's refund reason"),
6456
+ originTxs: z.array(SWAP_TX).optional().describe("Deposit-side txs"),
6457
+ destinationTxs: z.array(SWAP_TX).optional().describe("Delivery-side txs"),
6458
+ updatedAt: z.string().optional().describe("1Click timestamp"),
6459
+ refundAfter: z.string().optional().describe("ISO, from the stored quote — no send instruction is valid after it"),
6460
+ addressExpires: z.string().optional().describe("ISO, from the stored quote"),
6461
+ hyperliquid: z.object({
6462
+ address: z.string().describe("Account read"),
6463
+ network: z.string().describe("mainnet · testnet — always mainnet for the post-SUCCESS read"),
6464
+ perps: z.object({
6465
+ accountValue: z.string().describe("Decimal USD"),
6466
+ withdrawable: z.string().describe("Decimal USD"),
6467
+ }).describe("clearinghouseState"),
6468
+ spot: z.array(z.object({
6469
+ coin: z.string().describe("e.g. USDC, UBTC"),
6470
+ total: z.string().describe("Decimal"),
6471
+ hold: z.string().describe("Decimal on hold"),
6472
+ })).describe("spotClearinghouseState balances, every non-zero coin (never paged)"),
6473
+ firstDeposit: z.boolean().describe("true = empty account; Hyperliquid MAY take a one-time ~1 USDC activation (unverified)"),
6474
+ note: z.string().describe("Not summed: unified/portfolio-margin accounts show everything in spot"),
6475
+ }).optional().describe("Balance of the hyperliquid address asked for, or of the recipient after a SUCCESS into Hyperliquid"),
6476
+ next: z.string().describe("One sentence: what happens next or what to do"),
6477
+ }),
6478
+ examples: [
6479
+ { depositAddress: "0xd63c8F578F0a5541c14bFc9AFbC4AdEbE0250Ef2" },
6480
+ { hyperliquid: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" },
6481
+ ],
6482
+ effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "none", auth: "public",
6483
+ }),
5633
6484
  // wallet:portfolio — the authority walk projected onto wallet rows. One call
5634
6485
  // answers "what does my whole estate hold", which no client could ask before:
5635
6486
  // every wallet read was scoped to one workspace at a time.
@@ -5665,14 +6516,179 @@ export const RECEIVERS = {
5665
6516
  "storefront:enable": receiver({
5666
6517
  receiver: "storefront:enable",
5667
6518
  summary: "Open (or close) a workspace's storefront — the gate every checkout mint reads",
5668
- request: () => z.object({ slug: z.string().optional(), enabled: z.boolean().optional() }),
5669
- response: () => z.object({ ok: z.boolean().optional(), slug: z.string().optional(), enabled: z.boolean().optional(), error: z.string().optional() }),
6519
+ request: () => z.object({
6520
+ slug: z.string().optional(),
6521
+ enabled: z.boolean().optional(),
6522
+ cart: z.boolean().optional().describe("Also switch the native grid's Add to basket on (true) or off (false) — owners.storefront_cart_enabled. Absent leaves it unchanged."),
6523
+ testMode: z.boolean().optional().describe("Test mode (owners.storefront_test_mode): true = the store takes test money — Stripe test card, TESTNET crypto escrow — and every buyer page shows a test-mode banner. A call naming only testMode leaves the store's open/closed state alone."),
6524
+ }),
6525
+ response: () => z.object({ ok: z.boolean().optional(), slug: z.string().optional(), enabled: z.boolean().optional(), cart: z.boolean().optional(), testMode: z.boolean().optional(), error: z.string().optional() }),
5670
6526
  effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
5671
- examples: [{ slug: "acme" }, { slug: "acme", enabled: false }],
6527
+ examples: [{ slug: "acme" }, { slug: "acme", enabled: false }, { slug: "acme", cart: true }, { slug: "acme", testMode: true }],
6528
+ }),
6529
+ // A Stripe account that takes cards, and a test card payment on it, with no form —
6530
+ // for an owner pressing one button or their agent calling one door (text/cards.md).
6531
+ // TEST MODE ONLY: the account is platform-collected and filled with Stripe's test
6532
+ // identity values, so a live key is refused before Stripe is asked anything.
6533
+ // Body: resolvers/storefront/test-cards.ts; work: lib/stripe-test-seller.ts.
6534
+ "storefront:test-cards": receiver({
6535
+ receiver: "storefront:test-cards",
6536
+ summary: "Set up test card payments for a workspace in one call: creates (or reuses) a test-mode Stripe account ONE fills with Stripe's test values, waits a few seconds for Stripe to switch cards on, then takes a €10 test card payment on it. Answers stage 'checking' if Stripe is still switching it on — call again. Refuses on a live key (test_mode_only). Owner-only.",
6537
+ request: () => z.object({
6538
+ workspace: z.string().optional().describe("Which store. NOT an authority claim — the attested caller must control it (callerControlsWorkspace). Absent = the caller's own."),
6539
+ slug: z.string().optional().describe("Alias of `workspace`."),
6540
+ country: z.string().optional().describe("Two-letter country for the test account. Only IE is run end to end today; anything else refuses with country_not_supported. Absent = IE."),
6541
+ pay: z.boolean().optional().describe("false = set the account up but take no test payment. Absent = pay once the account can take cards."),
6542
+ }),
6543
+ response: () => z.object({
6544
+ ok: z.boolean(),
6545
+ workspace: z.string().optional(),
6546
+ stage: z.enum(["checking", "live", "paid"]).optional().describe("checking = Stripe is still switching cards on, call again · live = can take cards · paid = a test payment went through"),
6547
+ accountId: z.string().optional(),
6548
+ created: z.boolean().optional().describe("A new test account was made on this call."),
6549
+ replaced: z.string().nullable().optional().describe("The unfinished account this one replaced, if any."),
6550
+ payment: z.object({ id: z.string(), charge: z.string().nullable(), amount: z.number().int(), currency: z.string() }).optional(),
6551
+ error: z.string().optional().describe("forbidden · test_mode_only · country_not_supported · stripe_refused · not_live_yet · workspace_not_found · stripe_not_configured · no_db"),
6552
+ detail: z.string().optional(),
6553
+ }),
6554
+ effect: "ask", cost: "free", reversible: false, idempotent: false, auth: "owner",
6555
+ surfaces: { mcp: true },
6556
+ examples: [{}, { workspace: "acme" }, { workspace: "acme", pay: false }],
6557
+ }),
6558
+ // The one live switch (C7b): owners.live_at flips card AND crypto to live money
6559
+ // together, and goLive writes it only when every gap is closed — refusing by name
6560
+ // otherwise. Body: resolvers/storefront/shop-live.ts; switch: lib/stripe-mode.ts.
6561
+ "shop:go-live": receiver({
6562
+ receiver: "shop:go-live",
6563
+ summary: "Switch a store to LIVE money on card and crypto together. Refuses, writing nothing, until every gap is closed — live_connect (a Stripe Connect account the live key confirms can charge), mainnet_treasury (a well-formed payout address), confirmed_prices (the owner confirmed every active price), live_keys (the platform's live Stripe pair) — and names each one still open. Owner-only.",
6564
+ request: () => z.object({
6565
+ workspace: z.string().optional().describe("Which store. NOT an authority claim — the attested caller must control it (callerControlsWorkspace). Absent = the caller's own."),
6566
+ slug: z.string().optional().describe("Alias of `workspace`."),
6567
+ }),
6568
+ response: () => z.object({
6569
+ ok: z.boolean().describe("TRUE when the store is live (now, or already)."),
6570
+ workspace: z.string().optional(),
6571
+ live_at: z.number().int().optional().describe("Unix seconds the store went live."),
6572
+ already: z.boolean().optional().describe("The store was already live; nothing was written."),
6573
+ error: z.string().optional().describe("`forbidden` · `no_db` · `no_store` · `not_ready` (a gap is open) · `changed` (the store moved while switching; nothing was written)."),
6574
+ missing: z.array(z.enum(["live_connect", "mainnet_treasury", "confirmed_prices", "live_keys"])).optional().describe("Every gap still open, by name."),
6575
+ detail: z.string().optional().describe("One line naming each gap and what is missing — never a key, never an address."),
6576
+ }),
6577
+ effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "owner",
6578
+ examples: [{ workspace: "kiln" }],
6579
+ }),
6580
+ "shop:stop-live": receiver({
6581
+ receiver: "shop:stop-live",
6582
+ summary: "Switch a store back to TEST money on card and crypto together (clears live_at, turns test mode on). Always allowed for the owner — it is the safe direction. Owner-only.",
6583
+ request: () => z.object({
6584
+ workspace: z.string().optional().describe("Which store. NOT an authority claim — the attested caller must control it. Absent = the caller's own."),
6585
+ slug: z.string().optional().describe("Alias of `workspace`."),
6586
+ }),
6587
+ response: () => z.object({
6588
+ ok: z.boolean(),
6589
+ workspace: z.string().optional(),
6590
+ error: z.string().optional().describe("`forbidden` · `no_db` · `no_store`."),
6591
+ }),
6592
+ effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "owner",
6593
+ examples: [{ workspace: "kiln" }],
6594
+ }),
6595
+ // ONE command, a complete store. Composes storefront:enable, products:create,
6596
+ // variants:create, media:generate and the three pages:* shop-pack doors in the
6597
+ // caller's ctx; idempotent by read-back (a second call writes nothing).
6598
+ // Body: resolvers/storefront/shop-build.ts.
6599
+ "shop:build": receiver({
6600
+ receiver: "shop:build",
6601
+ summary: "Build a complete store in one call: storefront on in test mode with the basket, 6–12 products with copy, prices, an image and a stocked variant each, grouped into 3–4 collections, and the twelve shop pages filled and published with no bracket left. Never invents a founder, year, address or policy — those come back in factsToAdd. A second call creates nothing and answers the same receipt.",
6602
+ request: () => z.object({
6603
+ workspace: z.string().optional().describe("Which workspace to build. NOT an authority claim — the attested caller must control it (callerControlsWorkspace). Absent = the caller's own."),
6604
+ slug: z.string().optional().describe("Alias of `workspace`, for callers that speak the storefront receivers' field name."),
6605
+ description: z.string().min(1).describe("Plain English: what the business is and what it sells. The model writes the catalogue from this and nothing else."),
6606
+ products: z
6607
+ .array(z.object({
6608
+ name: z.string(),
6609
+ price: z.number().optional().describe("MINOR units of `currency` (2400 = 24.00) — the same unit as products:create's unit_amount."),
6610
+ description: z.string().optional().describe("Kept verbatim; the model writes one only when this is absent."),
6611
+ }))
6612
+ .optional()
6613
+ .describe("Products the owner already knows. Used first; the model only fills the gap to six-plus. A product without a price is reported, never priced by guess."),
6614
+ heroPrompt: z.string().optional().describe("The seller's own prompt for the hero image. Drawn from verbatim when the home page has a hero slot to fill; absent = a lifestyle shot of what the shop sells. A hero image already in facts.identity.heroImage wins over both."),
6615
+ currency: z.string().optional().describe("ISO 4217, default USD."),
6616
+ brand: z
6617
+ .object({ name: z.string().optional(), tagline: z.string().optional() })
6618
+ .optional()
6619
+ .describe("The shop's name (else the workspace's display name) and an optional tagline."),
6620
+ facts: z
6621
+ .record(z.string(), z.unknown())
6622
+ .optional()
6623
+ .describe("Optional ShopBusinessFacts (lib/puck/fill-shop-pack.ts) the owner typed — contact, policies, founder. Passed through to pages:fill-shop-pack and validated there."),
6624
+ publish: z
6625
+ .boolean()
6626
+ .optional()
6627
+ .describe("FALSE = build everything and open nothing: the storefront stays off and the twelve pages stay drafts, for a person to review first (the store-builder workflow opens and publishes after its approval). Absent = go live in test mode, as before."),
6628
+ acceptPartial: z
6629
+ .boolean()
6630
+ .optional()
6631
+ .describe("TRUE = `ok` means the store is READY (six-plus products and twelve published pages with no bracket), not that every step verified — a missing product photo or a live card key is still named in `steps` and `complete` stays false. For a build a person reviews next (the store-builder workflow), where one failed image must not fail the whole run. Absent = the strict verdict."),
6632
+ }),
6633
+ response: () => z.object({
6634
+ ok: z.boolean().describe("TRUE only when every step verified from the rows: twelve pages published with no bracket, six-plus products each with a price, an image and a stocked variant, the storefront and basket on, card rail in test mode. With `acceptPartial`, TRUE when the store is ready (catalogue + verify) — see `complete`."),
6635
+ complete: z.boolean().optional().describe("Every step verified — the strict verdict, whatever `acceptPartial` said."),
6636
+ error: z.string().optional().describe("A refusal before any step ran: `forbidden` · `no_db` · `missing description`."),
6637
+ workspace: z.string().optional(),
6638
+ storeUrl: z.string().optional(),
6639
+ mode: z.enum(["test", "live"]).optional().describe("The card rail as MEASURED for the store's page (resolveStripeForPage), not as intended."),
6640
+ cryptoNetwork: z.string().optional().describe("The crypto rail as measured (resolveOneNetwork): mainnet | testnet."),
6641
+ businessName: z.string().optional(),
6642
+ heroImage: z.string().nullable().optional(),
6643
+ productIds: z.array(z.string()).optional(),
6644
+ products: z.array(z.record(z.string(), z.unknown())).optional(),
6645
+ collections: z.array(z.string()).optional(),
6646
+ pages: z.array(z.object({ role: z.string(), slug: z.string(), title: z.string(), status: z.string(), url: z.string() })).optional(),
6647
+ factsToAdd: z.array(z.object({ fact: z.string().nullable(), token: z.string() })).optional().describe("Facts only the owner can give. Each one's sentence was left off the published pages rather than invented."),
6648
+ steps: z
6649
+ .array(z.object({ step: z.string(), ok: z.boolean(), reason: z.string().optional(), detail: z.record(z.string(), z.unknown()).optional() }))
6650
+ .optional()
6651
+ .describe("storefront · catalogue · images · variants · pages · hero · fill · publish · chat · verify — each ok or failed with a reason. Nothing is skipped silently. `chat` writes the shop assistant (the page chat pack) onto every role page that has none."),
6652
+ created: z.record(z.string(), z.number()).optional().describe("What THIS call wrote. All zero on a repeat call."),
6653
+ }),
6654
+ effect: "ask", cost: "variable", reversible: false, idempotent: true, auth: "member",
6655
+ examples: [{ workspace: "tea-test", description: "A small loose-leaf tea shop in Galway selling single-origin teas, blends and teaware." }],
6656
+ }),
6657
+ // Is this store ready to sell? Six lines read from the rows — S1 role pages ·
6658
+ // S2 products · S3 chat packs · S4 lifecycle · S5 starter workflows · CARD —
6659
+ // each closed with a mark (pass) or a warn (fail) on its own path.
6660
+ // Body: resolvers/storefront/shop-readiness.ts.
6661
+ "shop:readiness": receiver({
6662
+ receiver: "shop:readiness",
6663
+ summary: "Is this store ready to sell? Answers six lines read from the store's own rows — S1 twelve role pages with no bracket and no link to #, S2 live products whose buy links all resolve, S3 a chat pack on twelve role pages, S4 an active lifecycle, S5 a live starter workflow, CARD the store page charges a real card — each pass or fail with its evidence. A fact that could not be read is a failing line that says 'unknown', never a zero. Owner-only.",
6664
+ request: () => z.object({
6665
+ workspace: z.string().optional().describe("Which store to check. NOT an authority claim — the attested caller must control it (callerControlsWorkspace). Absent = the caller's own."),
6666
+ slug: z.string().optional().describe("Alias of `workspace`, for callers that speak the storefront receivers' field name."),
6667
+ quiet: z.boolean().optional().describe("A READ for a screen: answer the lines without closing them with a mark/warn per line, so a page view does not pile weight on the paths. A refusal still warns the caller."),
6668
+ }),
6669
+ response: () => z.object({
6670
+ ok: z.boolean().describe("TRUE when the list was answered — not that the store is ready; that is `green`."),
6671
+ error: z.string().optional().describe("A refusal: `forbidden` (no attested caller, or one who does not control the store) · `no_db`."),
6672
+ workspace: z.string().optional(),
6673
+ lines: z
6674
+ .array(z.object({
6675
+ code: z.enum(["S1", "S2", "S3", "S4", "S5", "CARD"]),
6676
+ pass: z.boolean(),
6677
+ evidence: z.string().describe("The measured numbers behind the verdict, or `unknown: … was not read`."),
6678
+ closed: z.enum(["mark", "warn"]).describe("How this line closed its loop: mark on a pass, warn on a fail."),
6679
+ }))
6680
+ .optional()
6681
+ .describe("Always six, always in the order S1 S2 S3 S4 S5 CARD."),
6682
+ green: z.boolean().optional().describe("Every line passes."),
6683
+ passed: z.number().int().optional(),
6684
+ total: z.number().int().optional(),
6685
+ }),
6686
+ effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "owner",
6687
+ examples: [{ workspace: "tea-test" }],
5672
6688
  }),
5673
6689
  "storefront:stats": receiver({
5674
6690
  receiver: "storefront:stats",
5675
- summary: "Storefront funnel stats — views, checkouts, purchases, revenue, per-product breakdown",
6691
+ summary: "Storefront funnel stats — views, checkouts, purchases, revenue (free to the owner), plus the per-product breakdown and funnel (the 'shop' plugin)",
5676
6692
  request: () => z.object({ slug: z.string().optional() }),
5677
6693
  response: () => z.object({
5678
6694
  views: z.number().optional(),
@@ -5680,6 +6696,8 @@ export const RECEIVERS = {
5680
6696
  purchases: z.number().optional(),
5681
6697
  revenue_cents: z.number().optional(),
5682
6698
  byProduct: z.array(z.record(z.string(), z.unknown())).optional(),
6699
+ locked: z.array(z.string()).optional().describe("Fields withheld because the store lacks the 'shop' plugin — absent, never empty. The four totals are always answered to the owner"),
6700
+ unlock: z.string().optional().describe("The plugin that unlocks `locked`"),
5683
6701
  error: z.string().optional(),
5684
6702
  }),
5685
6703
  effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
@@ -5793,6 +6811,8 @@ export const RECEIVERS = {
5793
6811
  // ══════════════════════════════════════════════════════════════════════════
5794
6812
  "blocks:list": receiver({
5795
6813
  receiver: "blocks:list",
6814
+ // auth (public) — task:01a128d6108e551f5966106b: registry-only for an anonymous caller, tenant blocks need ctx.ownerSlug (resolvers/blocks.ts:125,265) — the same shape as meta:types.
6815
+ auth: "public",
5796
6816
  surfaces: { mcp: true },
5797
6817
  summary: "Discover the page blocks that exist — name, category, surface, description and variant list, filterable and paged",
5798
6818
  request: () => z.object({
@@ -5839,6 +6859,8 @@ export const RECEIVERS = {
5839
6859
  }),
5840
6860
  "blocks:schema": receiver({
5841
6861
  receiver: "blocks:schema",
6862
+ // auth (public) — task:01a128d6108e551f5966106b: registry rows answer anyone, tenant rows need ctx.ownerSlug (resolvers/blocks.ts:221,265); the channels visitor tool block_schema is public (channels/src/tools/pages.ts:320).
6863
+ auth: "public",
5842
6864
  surfaces: { mcp: true },
5843
6865
  summary: "Read one block's full prop contract — per-variant fields, the block's own heading/body/cta/image mapping, and the props the render reads that the editor cannot express",
5844
6866
  request: () => z.object({
@@ -5942,19 +6964,78 @@ export const RECEIVERS = {
5942
6964
  "pages:create": receiver({
5943
6965
  receiver: "pages:create",
5944
6966
  surfaces: { mcp: true },
5945
- summary: "Create a workspace page (draft) from a title + sections",
5946
- request: () => z.object({ slug: z.string(), title: z.string(), sections: z.array(z.object({ component: z.string(), props: z.record(z.string(), z.unknown()) })), pageSlug: z.string().optional() }),
6967
+ summary: "Create a workspace page (draft) — from a page template, from any registry blocks, or from legacy CRO sections",
6968
+ request: () => z.object({
6969
+ slug: z.string(), title: z.string(),
6970
+ sections: z.array(z.object({ component: z.string(), props: z.record(z.string(), z.unknown()) })).optional(),
6971
+ puckData: z.object({ content: z.array(z.record(z.string(), z.unknown())), root: z.record(z.string(), z.unknown()).optional() }).passthrough().optional()
6972
+ .describe("Puck data: `content[]` of `{ type, props }`, any registry block. Each top-level block's props are normalised onto the member its variant renders and given a `props.id` when missing. With `template`, these blocks are APPENDED after the template's."),
6973
+ template: z.string().optional().describe("A page-template id from `pages:templates`. The page starts as a copy of that template — its blocks, images, links and anchors — and `edits` / `remove` / `puckData` are applied on top. A pack template (it has a `pageCount`) is refused: it seeds many pages through its own receiver."),
6974
+ edits: z.array(z.object({
6975
+ blockId: z.string().describe("A template block's `props.id`, as `pages:templates {id}` lists it"),
6976
+ props: z.record(z.string(), z.unknown()).describe("Props merged into that block — usually its copy rewritten for the brief"),
6977
+ })).optional().describe("Only with `template`. An unknown blockId is reported in `unknownEdits`, never silently dropped."),
6978
+ remove: z.array(z.string()).optional().describe("Only with `template`: template block ids to leave out."),
6979
+ pageSlug: z.string().optional(),
6980
+ }),
5947
6981
  response: () => z.object({
5948
6982
  ok: z.boolean(), slug: z.string().optional(), title: z.string().optional(), url: z.string().optional(), status: z.string().optional(), error: z.string().optional(),
5949
6983
  unknownBlocks: z.array(z.string()).optional().describe("Block names in this page that the renderer CANNOT DRAW, in your own spelling. The page was still created — the names are stored and will paint nothing. PRESENT ⟺ at least one name was unknown; absent means every name resolved (absent is not an empty array). A retired or collapsed family member name (HeroCentered, Wallet) is NOT listed: the render path rewrites it. Repair with `pages:update-block`, and read `blocks:list` / `blocks:schema` for the names that exist."),
6984
+ unknownEdits: z.array(z.string()).optional().describe("`edits[].blockId` values the template does not hold — those edits were NOT applied. Absent ⟺ every edit addressed a real block."),
6985
+ unlandedEdits: z.array(z.object({ blockId: z.string(), fields: z.array(z.string()), renders: z.array(z.string()) })).optional()
6986
+ .describe("Edit keys no field of that block's rendering member took — stored, invisible, and the sample copy they meant to replace is still showing. `renders` names the fields that do render. Re-send with those names."),
6987
+ sampleCopyLeft: z.array(z.object({ blockId: z.string(), type: z.string(), fields: z.array(z.string()) })).optional()
6988
+ .describe("With `template`: blocks whose listed props still hold the TEMPLATE'S sample copy — another business's words on this page. The page is not done until this is absent: rewrite each (`pages:update-block`) or remove the block."),
6989
+ sampleImagesLeft: z.array(z.object({ blockId: z.string(), fields: z.array(z.string()) })).optional()
6990
+ .describe("With `template`: props still showing the template's sample photos. Replace with the business's own images where you have them."),
6991
+ quality: PAGE_QUALITY.optional(),
5950
6992
  }),
5951
6993
  effect: "ask", cost: "free", reversible: true, idempotent: false, auth: "member",
5952
6994
  }),
6995
+ "pages:templates": receiver({
6996
+ receiver: "pages:templates",
6997
+ // auth (public) — task:01a128d6108e551f5966106b: first-party code identical for every caller, no ctx read (resolvers/pages.ts:1084-1085); the channels visitor tools are public (channels/src/tools/pages.ts:278,301).
6998
+ auth: "public",
6999
+ surfaces: { mcp: true },
7000
+ summary: "Browse the page templates (store, sales, webinar, course, about, …) — list them with their block line-up, or read one template's full blocks to start a page from",
7001
+ request: () => z.object({
7002
+ id: z.string().optional().describe("A template id. Present → that template's full blocks (`{ id, type, props }`) and its rewrite guidance. Absent → the list."),
7003
+ search: z.string().optional().describe("List mode: case-insensitive substring over id, name and description."),
7004
+ }),
7005
+ response: () => z.object({
7006
+ ok: z.boolean(),
7007
+ templates: z.array(z.object({
7008
+ id: z.string(), name: z.string(), description: z.string(),
7009
+ blocks: z.array(z.string()).describe("The template's top-level blocks in order, as `Type` or `Type/variant`"),
7010
+ pageCount: z.number().optional().describe("Present ⟺ a PACK: it seeds this many pages through `seedReceiver`, and `pages:create {template}` refuses it"),
7011
+ seedReceiver: z.string().optional(),
7012
+ strength: z.object({ score: z.number(), max: z.number() }).optional().describe("How many of the template-strength checks it passes (lib/puck/template-strength.ts)"),
7013
+ })).optional().describe("List mode. Every template — the list is small (tens) and never paged."),
7014
+ template: z.object({
7015
+ id: z.string(), name: z.string(), description: z.string(),
7016
+ guidance: z.string().describe("How to rewrite this template for a real business"),
7017
+ root: z.record(z.string(), z.unknown()).optional(),
7018
+ blocks: z.array(z.object({ id: z.string(), type: z.string(), props: z.record(z.string(), z.unknown()) })),
7019
+ pageCount: z.number().optional(),
7020
+ seedReceiver: z.string().optional(),
7021
+ }).optional().describe("Read mode."),
7022
+ error: z.string().optional(),
7023
+ }),
7024
+ effect: "ask", cost: "free", reversible: true, idempotent: true,
7025
+ examples: [{ search: "store" }, { id: "storefront-home" }],
7026
+ }),
5953
7027
  "pages:edit": receiver({
5954
7028
  receiver: "pages:edit",
5955
7029
  summary: "Edit a workspace page's title or sections",
5956
- request: () => z.object({ slug: z.string(), page: z.string(), title: z.string().optional(), sections: z.array(z.object({ component: z.string(), props: z.record(z.string(), z.unknown()) })).optional() }),
5957
- response: () => z.object({ ok: z.boolean(), slug: z.string().optional(), title: z.string().optional(), url: z.string().optional(), status: z.string().optional(), error: z.string().optional() }),
7030
+ request: () => z.object({
7031
+ slug: z.string(), page: z.string(), title: z.string().optional(),
7032
+ sections: z.array(z.object({ component: z.string(), props: z.record(z.string(), z.unknown()) })).optional(),
7033
+ puckData: z.object({ content: z.array(z.record(z.string(), z.unknown())), root: z.record(z.string(), z.unknown()).optional() }).passthrough().optional()
7034
+ .describe("Full replacement Puck data — any registry block. Top-level props are normalised and ids stamped exactly as `pages:create` does. Refused beside `sections`."),
7035
+ root: PAGE_ROOT_PATCH.optional().describe("PAGE SETTINGS — merged into the stored `data.root.props` (what Layout reads for the page's head, chat, dock and chrome). Only these keys; an empty string CLEARS a key so it falls back to its default. Refused beside `sections`."),
7036
+ allowRemove: z.boolean().optional().describe("A rewrite that leaves the page empty, or keeps under half of a 3+ block page, is refused (would_remove_blocks) unless this is true. Set it only after the person confirmed the removal."),
7037
+ }),
7038
+ response: () => z.object({ ok: z.boolean(), slug: z.string().optional(), title: z.string().optional(), url: z.string().optional(), status: z.string().optional(), updatedAt: z.number().optional(), error: z.string().optional(), quality: PAGE_QUALITY.optional(), before: z.number().optional(), after: z.number().optional() }),
5958
7039
  effect: "ask", cost: "free", reversible: true, idempotent: false, auth: "member",
5959
7040
  }),
5960
7041
  "pages:list": receiver({
@@ -5998,6 +7079,51 @@ export const RECEIVERS = {
5998
7079
  }),
5999
7080
  effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
6000
7081
  }),
7082
+ "pages:build-site": receiver({
7083
+ receiver: "pages:build-site",
7084
+ summary: "Write a five-page business site — home, about, services, contact, faq — as DRAFTS from the business's own facts. Drops every proof block the facts cannot back (stats, logos, testimonials, pricing, team, badges, quotes, timelines, sample galleries), rewrites the rest with one model call per page, and cuts any sentence that invents a number, a name or a placeholder. Saves the facts as the workspace's business-facts. Idempotent by read-back: a template already built is reported created:false and left alone. Publishing is pages:publish-pack's job.",
7085
+ request: () => z.object({
7086
+ slug: z
7087
+ .string()
7088
+ .describe("which workspace. NOT an authority claim — the caller is authorized by the attested ctx through the same callerControlsWorkspace walk every pages:* receiver uses. Absent = the caller's own workspace."),
7089
+ facts: z
7090
+ .object({
7091
+ businessName: z.string().describe('the business\'s name — the one required fact; absent, the call is refused as "missing facts"'),
7092
+ whatYouSell: z.string().optional().describe('a 2-5 word noun phrase — "Emergency plumbing"'),
7093
+ summary: z.string().optional().describe("two or three plain sentences on what the business does, in its own words"),
7094
+ tagline: z.string().optional(),
7095
+ founderName: z.string().optional().describe("named on a page only when given"),
7096
+ foundedYear: z.number().optional().describe("a year the business stated; never inferred"),
7097
+ phone: z.string().optional(),
7098
+ email: z.string().optional(),
7099
+ postalAddress: z.string().optional().describe("withheld = no map and no Visit card, never a guessed address"),
7100
+ openingHours: z.string().optional(),
7101
+ city: z.string().optional(),
7102
+ services: z.array(z.string()).optional().describe("what the business offers, as short names"),
7103
+ currency: z.string().optional().describe("ISO 4217, when the business states one"),
7104
+ })
7105
+ .describe("the candidate facts (lib/site-builder/facts.ts BusinessFactsCandidate) — the ONLY source the copy may state; an absent field is absent, never a guess"),
7106
+ description: z
7107
+ .string()
7108
+ .optional()
7109
+ .describe("the visitor's own sentence about the business — extra context for the copy, and a source the number guard accepts"),
7110
+ }),
7111
+ response: () => z.object({
7112
+ ok: z.boolean().describe("all five pages exist (created now or already there)"),
7113
+ error: z.string().optional(),
7114
+ pages: z
7115
+ .array(z.object({ template: z.string(), slug: z.string(), title: z.string(), created: z.boolean() }))
7116
+ .optional()
7117
+ .describe("one row per template, in reading order — passes straight into pages:publish-pack's `pages`"),
7118
+ facts: z.array(z.string()).optional().describe("the business-facts keys now saved for the workspace; empty when the facts column is not migrated"),
7119
+ factsToAdd: z.array(z.string()).optional().describe("labels of public facts the pages name that nobody has given — the lines they hide until the owner adds them"),
7120
+ steps: z
7121
+ .array(z.object({ step: z.string(), ok: z.boolean(), reason: z.string().optional() }))
7122
+ .optional()
7123
+ .describe('facts, then page:<template> — a page whose copy fell back to the facts-only page says `copy_fallback:<why>`'),
7124
+ }),
7125
+ effect: "ask", cost: "variable", reversible: true, idempotent: true, auth: "member",
7126
+ }),
6001
7127
  // WHY THIS IS DECLARED. `pages:delete` shipped as a resolver with no registry
6002
7128
  // row, so it reached the handler only through the undeclared-receiver escape
6003
7129
  // hatch — no edge zod parsing, no auth floor. Its two live callers send
@@ -6141,11 +7267,16 @@ export const RECEIVERS = {
6141
7267
  source: z.object({ url: z.string().optional() }).optional().describe("where the facts came from, when they were extracted rather than typed"),
6142
7268
  })
6143
7269
  .describe("ShopBusinessFacts — lib/puck/fill-shop-pack.ts is the type of record"),
7270
+ stripPlaceholders: z
7271
+ .boolean()
7272
+ .optional()
7273
+ .describe("Go-live mode (shop:build): after the fill, a bracket still unanswered is REMOVED — its sentence dropped, an image or link prop set to '' — never left visible and never invented. The removed tokens come back in `stripped`."),
6144
7274
  }),
6145
7275
  response: () => z.object({
6146
7276
  ok: z.boolean(),
6147
7277
  filled: z.number().optional().describe("how many role pages were rewritten"),
6148
7278
  roles: z.array(z.string()).optional().describe("which shop_role each rewritten page holds"),
7279
+ stripped: z.array(z.object({ role: z.string(), tokens: z.array(z.string()) })).optional().describe("with stripPlaceholders: the unanswered tokens removed, per role page"),
6149
7280
  error: z.string().optional().describe("`not_seeded` = no page carries a shop_role yet; call pages:instantiate-shop-pack first"),
6150
7281
  }),
6151
7282
  effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
@@ -6220,11 +7351,24 @@ export const RECEIVERS = {
6220
7351
  }),
6221
7352
  "movers:funnel-provision": receiver({
6222
7353
  receiver: "movers:funnel-provision",
6223
- summary: "Open, sponsored no-account provision — takes a company name plus a URL or description, provisions a capped child workspace under moverchat, and starts movers:build. Rate-limited per visitor + a global daily ceiling; refuses past any wall rather than draining moverchat's operating credits. The single writer behind both the homepage door and this chat tool.",
6224
- request: () => z.object({ name: z.string(), url: z.string().optional(), describe: z.string().optional(), phone: z.string().optional(), email: z.string().optional(), visitorHash: z.string() }),
7354
+ summary: "Open, sponsored no-account provision — takes a contact name plus a URL or description, provisions a capped child workspace, and builds one of three things: a moving-company site + quote desk (movers, under moverchat), a store with products, photos and twelve pages in test mode (store), or a five-page business site with a front desk (site). Each vertical has its own sponsor budget, per-visitor rate limit and daily ceiling, and refuses past any wall. Ends on a preview token. The single writer behind the site-builder intake block's doors and the chat tool.",
7355
+ request: () => z.object({
7356
+ builds: z.enum(["movers", "store", "site"]).optional().describe("What to build. Absent = movers (every caller before the store and site verticals). Chooses the builder AND the sponsor budget; never names a workspace."),
7357
+ flow: z.enum(["vertical", "url-to-client"]).optional().describe("`url-to-client` = the URL block's door: every vertical, movers included, runs the one url-to-client workflow (soul → build → review → publish), and a name is optional. Absent = each vertical's own workflow."),
7358
+ fields: z.record(z.string(), z.string()).optional().describe("The URL block's operator-defined extra questions, answered — `{ label: answer }`, at most 12, each one line. Read into the extract and the chatbot's soul; never printed on a page as a fact."),
7359
+ name: z.string(),
7360
+ url: z.string().optional(),
7361
+ describe: z.string().optional(),
7362
+ phone: z.string().optional(),
7363
+ email: z.string().optional(),
7364
+ visitorHash: z.string(),
7365
+ }),
6225
7366
  response: () => z.object({ ok: z.boolean(), previewToken: z.string().optional(), slug: z.string().optional(), error: z.string().optional() }),
6226
7367
  effect: "ask", cost: "variable", reversible: false, idempotent: false, auth: "public",
6227
- examples: [{ name: "Summit Movers", url: "https://summitmovers.example.com", visitorHash: "chat:web:conv-123" }],
7368
+ examples: [
7369
+ { name: "Summit Movers", url: "https://summitmovers.example.com", visitorHash: "chat:web:conv-123" },
7370
+ { builds: "store", name: "Ada", describe: "Fernhill Coffee, a small-batch roaster in Cork selling single-origin beans and brewing gear.", visitorHash: "chat:web:conv-456" },
7371
+ ],
6228
7372
  surfaces: { chat: true },
6229
7373
  }),
6230
7374
  "pages:versions": receiver({
@@ -6420,12 +7564,49 @@ export const RECEIVERS = {
6420
7564
  ok: z.boolean(),
6421
7565
  slug: z.string().optional(), title: z.string().optional(), url: z.string().optional(), status: z.string().optional(),
6422
7566
  updatedAt: z.number().optional(),
7567
+ root: z.record(z.string(), z.unknown()).optional().describe("The page's settings — stored `data.root.props` (description, socialTitle, ogImage, search, canonical, chat, dock, siteHeader, siteFooter). `pages:edit` with `root` writes them."),
6423
7568
  blocks: z.array(z.object({ id: z.string(), type: z.string(), props: z.record(z.string(), z.unknown()) })).optional().describe("THE LOSSLESS READ — every block on the page including the types the CRO `sections` schema cannot carry. `id` is what `pages:update-block` / `remove-block` / `move-block` target."),
6424
7569
  sections: z.array(z.object({ component: z.string(), props: z.record(z.string(), z.unknown()) })).optional().describe("The legacy CRO-subset view, derived from the canonical blob. LOSSY by design — a non-CRO block is absent here and present in `blocks[]`. Never edit from this."),
6425
7570
  error: z.string().optional(),
6426
7571
  }),
6427
7572
  effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
6428
7573
  }),
7574
+ "copy:get": receiver({
7575
+ receiver: "copy:get",
7576
+ summary: "The live text layer's edits for one of one.ie's own code-written pages (not /u/… — those are page-builder pages): every stored edit as {key, original, text}, and whether THIS caller may edit them (staff, or control of the platform workspace).",
7577
+ request: () => z.object({
7578
+ path: z.string().describe("The page path, e.g. `/pricing`. Query and trailing slash are ignored."),
7579
+ }),
7580
+ response: () => z.object({
7581
+ ok: z.boolean(),
7582
+ path: z.string().optional(),
7583
+ entries: z.array(z.object({ key: z.string(), original: z.string(), text: z.string() })).optional().describe("`key` = the original wording, whitespace-normalised, plus `#n` for its nth repeat on the page."),
7584
+ canEdit: z.boolean().optional(),
7585
+ error: z.string().optional(),
7586
+ }),
7587
+ effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "public",
7588
+ }),
7589
+ "copy:save": receiver({
7590
+ receiver: "copy:save",
7591
+ summary: "Save inline text edits on one of one.ie's own code-written pages — live on the next load, no deploy. An entry whose text is the original wording (or empty) removes that edit. Staff or controllers of the platform workspace only.",
7592
+ request: () => z.object({
7593
+ path: z.string().describe("The page path, e.g. `/pricing`."),
7594
+ entries: z.array(z.object({
7595
+ key: z.string().describe("The original wording (normalised), plus `#n` for its nth repeat — must belong to `original`."),
7596
+ original: z.string(),
7597
+ text: z.string().describe("The new wording; the original or empty removes the edit."),
7598
+ })).max(200),
7599
+ }),
7600
+ response: () => z.object({
7601
+ ok: z.boolean(),
7602
+ path: z.string().optional(),
7603
+ saved: z.number().optional(),
7604
+ removed: z.number().optional(),
7605
+ entries: z.array(z.object({ key: z.string(), original: z.string(), text: z.string() })).optional(),
7606
+ error: z.string().optional(),
7607
+ }),
7608
+ effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "session",
7609
+ }),
6429
7610
  "pages:children": receiver({
6430
7611
  receiver: "pages:children",
6431
7612
  summary: "Walk a page's own block tree and return every ChildPageBlock's target slug. ONE LEVEL ONLY — never transitive into the embedded page's own tree.",
@@ -6795,9 +7976,16 @@ export const RECEIVERS = {
6795
7976
  // ── social + crawl — handlers in resolvers/social.ts ───────────────────────────
6796
7977
  "social:publish": receiver({
6797
7978
  receiver: "social:publish",
6798
- summary: "Publish a drafted social post to its platform",
7979
+ summary: "Report what a master social post has queued: how many Facebook post variants the publisher cron will really post (live, nextAt), how many sit as drafts on networks with no live connection, and how many are skip-only formats. Leaves the master post untouched; answers ok:false when nothing is publishable. The posting itself is the social-variant cron, one Facebook post per workspace per five-minute tick.",
6799
7980
  request: () => z.object({ slug: z.string(), actorId: z.string(), id: z.string() }),
6800
- response: () => z.object({ ok: z.boolean(), id: z.string().optional(), status: z.string().optional(), reason: z.string().optional() }),
7981
+ response: () => z.object({
7982
+ ok: z.boolean(), id: z.string().optional(), status: z.string().optional(), reason: z.string().optional(),
7983
+ live: z.number().optional().describe("Facebook post variants the cron will post."),
7984
+ nextAt: z.number().nullable().optional().describe("Earliest slot among them, unix seconds."),
7985
+ drafts: z.number().optional().describe("Scheduled variants on networks with no live connection."),
7986
+ skipOnly: z.number().optional().describe("Facebook reel/story/video variants: no API path, skipped."),
7987
+ note: z.string().optional(),
7988
+ }),
6801
7989
  effect: "ask", cost: "variable", reversible: false, idempotent: false, auth: "update_group",
6802
7990
  }),
6803
7991
  "social:news-to-drafts": receiver({
@@ -6818,6 +8006,7 @@ export const RECEIVERS = {
6818
8006
  name: z.string().optional(),
6819
8007
  description: z.string().optional(),
6820
8008
  text: z.string().optional(),
8009
+ image: z.string().nullable().optional().describe("The page's og:image, else twitter:image, as an absolute https URL — null when it names none. The news desk uses it as a story's own picture before it generates one"),
6821
8010
  error: z.string().optional().describe("NAMED, never a single catch-all. invalid_url · https_required · dns_unresolved · blocked_host · redirect_no_location · redirect_invalid_url · redirect_blocked:<ssrf reason> · too_many_redirects · fetch_failed:<status> · not_html · timeout · fetch_error. Until 2026-09-15 every network cause collapsed into `fetch_error`, so a 301 apex->www and an origin refusing the fetch outright were indistinguishable — read `detail` beside this."),
6822
8011
  detail: z.string().optional().describe("The underlying cause in words, ≤200 chars — the exception class and message, the blocked hop, or the content-type that was refused. Present on most errors, never on success."),
6823
8012
  redirects: z.number().optional().describe("Hops followed before the answer. Redirects are followed MANUALLY, at most 4, and the SSRF guard re-runs on every hop — a public URL that redirects to a private address is refused at that hop with redirect_blocked."),
@@ -6858,18 +8047,37 @@ export const RECEIVERS = {
6858
8047
  // ──billing — handlers in resolvers/market.ts ──────────────────────────────────
6859
8048
  "billing:plan": receiver({
6860
8049
  receiver: "billing:plan",
6861
- summary: "Change a workspace's plan — returns a checkout URL to complete the upgrade",
6862
- request: () => z.object({ slug: z.string(), actorId: z.string(), plan: z.enum(["pro", "agency", "scale"]) }),
6863
- response: () => z.object({ ok: z.boolean(), intent: z.string().optional(), checkoutUrl: z.string().optional(), plan: z.string().optional(), reason: z.string().optional() }),
8050
+ summary: "Change a workspace's plan — returns a checkout URL to complete the upgrade. Sellable: pro, team, business (priced from plan-prices.ts, the same session /pricing mints); free/cancel return the plan page; a grandfathered name (agency, scale) is refused as not_sellable with the sellable list",
8051
+ request: () => z.object({ slug: z.string(), actorId: z.string(), plan: z.enum(["pro", "team", "business", "free", "cancel", "agency", "scale"]) }),
8052
+ response: () => z.object({ ok: z.boolean(), intent: z.string().optional(), checkoutUrl: z.string().optional(), plan: z.string().optional(), amount_cents: z.number().optional(), sellable: z.array(z.object({ plan: z.string(), monthly_cents: z.number() })).optional(), reason: z.string().optional() }),
8053
+ // Intent-only: returns a checkout URL a person later pays — not `moves: "value"`.
6864
8054
  effect: "ask", cost: "free", reversible: false, idempotent: false, auth: "update_group",
6865
8055
  }),
6866
8056
  "billing:topup": receiver({
6867
8057
  receiver: "billing:topup",
6868
- summary: "Top up workspace AI credits — returns a checkout URL for the amount. Credits are prepaid, NON-WITHDRAWABLE service units: they buy work on ONE (AI replies, tool and skill calls, agent runs, storage, API requests) and there is no payout, withdraw or cash-out rail against a credits balance",
6869
- request: () => z.object({ slug: z.string(), actorId: z.string(), amount: z.number(), currency: z.string().optional() }),
6870
- response: () => z.object({ ok: z.boolean(), intent: z.string().optional(), checkoutUrl: z.string().optional(), amount: z.number().optional(), currency: z.string().optional(), reason: z.string().optional() }),
8058
+ summary: "Top up workspace AI credits — returns the checkout URL of a credits PACK. Credits are sold only as packs priced by the pack table (one.ie/web lib/credits-packs.ts, USD, at CREDITS_PER_USD): name `credits` or the pack's USD `amount`; a number that names no pack, or credits and amount that disagree, is refused (not_a_pack / amount_mismatch) with `packs` and a `suggested` pack. Credits are prepaid, NON-WITHDRAWABLE service units: they buy work on ONE (AI replies, tool and skill calls, agent runs, storage, API requests) and there is no payout, withdraw or cash-out rail against a credits balance",
8059
+ request: () => z.object({ slug: z.string(), actorId: z.string(), credits: z.number().optional(), amount: z.number().optional(), currency: z.string().optional() }),
8060
+ response: () => z.object({ ok: z.boolean(), intent: z.string().optional(), checkoutUrl: z.string().optional(), ppid: z.string().optional(), credits: z.number().optional(), amount: z.number().optional(), currency: z.string().optional(), suggested: z.object({ credits: z.number(), usd: z.number(), ppid: z.string() }).optional(), packs: z.array(z.object({ credits: z.number(), usd: z.number(), ppid: z.string() })).optional(), reason: z.string().optional() }),
8061
+ // Intent-only: returns a checkout URL a person later pays — not `moves: "value"`.
6871
8062
  effect: "ask", cost: "free", reversible: false, idempotent: false, auth: "update_group",
6872
8063
  }),
8064
+ // Public read: the same numbers /.well-known/one.json `fees` serves. The chat reads prices
8065
+ // here (channels get_pricing) instead of carrying them in a prompt. Handler: resolvers/billing.ts.
8066
+ "billing:list": receiver({
8067
+ receiver: "billing:list",
8068
+ summary: "ONE's current prices — the credit rate, the credit packs (credits, USD, ppid) and the plans on sale (monthly, annual, credit grant). Public and read-only; derived from the price tables, so call it before quoting any ONE price",
8069
+ request: () => z.object({}).optional(),
8070
+ response: () => z.object({
8071
+ ok: z.boolean(),
8072
+ currency: z.literal("USD").describe("Every price here is US dollars."),
8073
+ credit_usd: z.number().describe("The price of one credit in USD."),
8074
+ credits_per_usd: z.number().describe("Credits one US dollar buys."),
8075
+ credit_packs: z.array(z.object({ credits: z.number(), usd: z.number(), ppid: z.string() })).describe("The packs credits are sold in; billing:topup accepts only these."),
8076
+ plans: z.array(z.object({ plan: z.string(), monthly_cents: z.number(), annual_cents: z.number(), grant_credits: z.number() })).describe("The plans on sale (billing:plan sells these); prices in US cents."),
8077
+ closed: z.enum(["mark", "none"]).describe("mark: the caller's path to this door was marked off the request path; none: no caller to mark."),
8078
+ }),
8079
+ effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "public",
8080
+ }),
6873
8081
  // ── video — handler in resolvers/video.ts ──────────────────────────────────────
6874
8082
  "video:ensure-defaults": receiver({
6875
8083
  receiver: "video:ensure-defaults",
@@ -6891,6 +8099,8 @@ export const RECEIVERS = {
6891
8099
  // side (configure a service) is the separate, gated booking:configure.
6892
8100
  "booking:list-slots": receiver({
6893
8101
  receiver: "booking:list-slots",
8102
+ // auth (public) — task:01a128d6108e551f5966106b: a customer with no account books a slot: /u/<slug>/book needs no sign-in (BookingCalendar.tsx:269); handler takes no ctx (resolvers/booking.ts:227).
8103
+ auth: "public",
6894
8104
  summary: "List open slots for a workspace's service on a date (or next open days)",
6895
8105
  request: () => z.object({
6896
8106
  slug: z.string(), // provider workspace
@@ -6948,6 +8158,8 @@ export const RECEIVERS = {
6948
8158
  }),
6949
8159
  "booking:create": receiver({
6950
8160
  receiver: "booking:create",
8161
+ // auth (public) — task:01a128d6108e551f5966106b: the anonymous visitor booking on /u/<slug>/book (BookingCalendar.tsx:318); the handler is built for it — customerRef falls back to the typed email (resolvers/booking.ts:319-320).
8162
+ auth: "public",
6951
8163
  summary: "Hold a slot for a customer; returns a ref and a payment intent when price > 0",
6952
8164
  request: () => z.object({
6953
8165
  slug: z.string(),
@@ -7089,22 +8301,27 @@ export const RECEIVERS = {
7089
8301
  request: () => z.object({
7090
8302
  slug: z.string().optional(),
7091
8303
  templates: z.boolean().optional(),
8304
+ // Named here because the door parses with this schema and zod strips what it does not name.
8305
+ limit: z.number().int().optional(),
7092
8306
  }),
7093
8307
  response: () => z.object({
7094
8308
  workflows: z.array(z.object({
7095
8309
  id: z.string(), name: z.string(), description: z.string().optional(), step_count: z.number(),
7096
8310
  status: z.string(), last_run_status: z.string().nullable(),
7097
8311
  })),
8312
+ // A short answer says it is short: total rows that exist, and whether `workflows` was cut.
8313
+ total: z.number().optional(),
8314
+ truncated: z.boolean().optional(),
7098
8315
  error: z.string().optional(),
7099
8316
  }),
7100
8317
  effect: "ask", cost: "free", idempotent: true, simulatable: false, auth: "view_workflows",
7101
- examples: [{ slug: "acme" }, { templates: true }],
8318
+ examples: [{ slug: "acme" }, { templates: true }, { limit: 5 }],
7102
8319
  }),
7103
8320
  "workflow:get": receiver({
7104
8321
  receiver: "workflow:get",
7105
8322
  surfaces: { mcp: true },
7106
8323
  summary: "Fetch one workflow's full graph — steps (kind, config, position) and edges (with conditions)",
7107
- request: () => z.object({ workflowId: z.string() }),
8324
+ request: () => z.object({ workflowId: z.string(), slug: SERVICE_SLUG }),
7108
8325
  response: () => z.object({
7109
8326
  id: z.string(), name: z.string(), status: z.string(),
7110
8327
  steps: z.array(z.object({
@@ -7125,7 +8342,7 @@ export const RECEIVERS = {
7125
8342
  receiver: "workflow:runs",
7126
8343
  surfaces: { mcp: true },
7127
8344
  summary: "List recent runs of a workflow (D1 workflow_run) for the monitor + history surfaces",
7128
- request: () => z.object({ workflowId: z.string(), runId: z.string().optional(), limit: z.number().int().min(1).max(200).optional(), stepId: z.string().optional(), stepLimit: z.number().int().min(1).max(100).optional() }),
8345
+ request: () => z.object({ workflowId: z.string(), runId: z.string().optional(), limit: z.number().int().min(1).max(200).optional(), stepId: z.string().optional(), stepLimit: z.number().int().min(1).max(100).optional(), slug: SERVICE_SLUG }),
7129
8346
  response: () => z.object({
7130
8347
  runs: z.array(z.object({
7131
8348
  id: z.string(), status: z.string(),
@@ -7263,6 +8480,7 @@ export const RECEIVERS = {
7263
8480
  diff: WorkflowDiffSchema,
7264
8481
  simulate: z.boolean().optional(),
7265
8482
  version: z.number().int().optional(), // optimistic lock — stale → conflict
8483
+ slug: SERVICE_SLUG,
7266
8484
  }),
7267
8485
  response: () => z.object({
7268
8486
  ok: z.boolean(),
@@ -7282,6 +8500,7 @@ export const RECEIVERS = {
7282
8500
  request: () => z.object({
7283
8501
  workflowId: z.string(),
7284
8502
  diff: WorkflowDiffSchema,
8503
+ slug: SERVICE_SLUG,
7285
8504
  }),
7286
8505
  response: () => z.object({
7287
8506
  ok: z.boolean(),
@@ -7305,6 +8524,14 @@ export const RECEIVERS = {
7305
8524
  slug: z.string().optional().describe("Workspace whose workflow to run; honoured only if you control it. Omit for your own. Refused (forbidden), never swapped for your own."),
7306
8525
  triggerPayload: z.record(z.string(), z.unknown()).optional(),
7307
8526
  idempotencyKey: z.string().optional(),
8527
+ // Undeclared until 2026-10-11, zod STRIPPED this at /api/ask and the canvas
8528
+ // Test button minted a LIVE run that deposited pheromone on every edge.
8529
+ test: z.boolean().optional().describe("Test run: is_test=1, bypasses trigger match + flow gates, deposits zero pheromone. Steps still execute for real — not a dry run."),
8530
+ // A bare key's work contract for THE RUN: declared at the top level so the edge
8531
+ // keeps it (zod strips the undeclared); runWorkflow stores it in triggerPayload,
8532
+ // where every lane reads a bare-key run's contract from, and it rides beneath
8533
+ // every step. Also accepted inside triggerPayload (round 5, finding 3).
8534
+ ...WORK_CONTRACT_FIELDS,
7308
8535
  }),
7309
8536
  response: () => z.object({ runId: z.string(), status: z.string().describe("open | done | paused | failed — never `open` for a run whose executor refused to start it"), error: z.string().optional() }),
7310
8537
  effect: "ask", cost: "variable", reversible: false, idempotent: true, simulatable: false, settles: "none",
@@ -7347,8 +8574,17 @@ export const RECEIVERS = {
7347
8574
  // it re-walks the tapper's authority. Without it, slug is ignored.
7348
8575
  slug: z.string().optional(),
7349
8576
  attestation: z.string().optional(),
8577
+ // A step whose config carries a `proposal` approves ONLY with this: a WebAuthn
8578
+ // assertion (Face ID / Touch ID, user verification required) over
8579
+ // hash(proposal), verified once by verifyPasskeyAssertion. The server rebuilds
8580
+ // the proposal from the step config and the run — never from this request.
8581
+ assertion: z.record(z.string(), z.unknown()).optional(),
8582
+ }),
8583
+ response: () => z.object({
8584
+ ok: z.boolean(), status: z.string().optional(), error: z.string().optional(),
8585
+ // On passkey_required / passkey_not_verified: the ask to show and sign.
8586
+ proposal: z.record(z.string(), z.unknown()).optional(),
7350
8587
  }),
7351
- response: () => z.object({ ok: z.boolean(), status: z.string().optional(), error: z.string().optional() }),
7352
8588
  effect: "ask", cost: "free", idempotent: true, simulatable: false, auth: "manage_workflows",
7353
8589
  examples: [{ runId: "run_1", stepId: "s2", decision: "approved" }],
7354
8590
  }),
@@ -7369,6 +8605,8 @@ export const RECEIVERS = {
7369
8605
  stripeAccount: z.string().optional(),
7370
8606
  error: z.string().optional(),
7371
8607
  }),
8608
+ // Intent-only: mints the session a buyer later pays; nothing moves at the call, so
8609
+ // it is deliberately NOT `moves: "value"` (value-moving-parity.test.ts names it).
7372
8610
  effect: "ask", cost: "variable", reversible: false, idempotent: false, simulatable: false, settles: "offchain",
7373
8611
  auth: "manage_workflows",
7374
8612
  examples: [{ workspace: "acme", ppid: "pr_1" }],
@@ -7396,6 +8634,9 @@ export const RECEIVERS = {
7396
8634
  stepName: z.string().optional(),
7397
8635
  workflowName: z.string().optional(),
7398
8636
  group: z.string().optional(), // conversation group; falls back to the run's started_by
8637
+ // An agent's ask, filled from the run ({ what, to, amount, asset, why, runId, stepId }).
8638
+ // Recorded on the `human:asked` event; the card shows it and Face ID signs its hash.
8639
+ proposal: z.record(z.string(), z.unknown()).optional(),
7399
8640
  }),
7400
8641
  response: () => z.object({ ok: z.boolean(), group: z.string().optional(), error: z.string().optional() }),
7401
8642
  effect: "signal", cost: "free", idempotent: true, simulatable: false, auth: "manage_workflows",
@@ -7431,6 +8672,10 @@ export const RECEIVERS = {
7431
8672
  source: z.string(),
7432
8673
  slug: z.string().optional(),
7433
8674
  triggerPayload: z.record(z.string(), z.unknown()).optional(),
8675
+ // A bare key's work contract for every run this fire starts — declared so the
8676
+ // edge keeps it; the door puts it in each child's triggerPayload and the child's
8677
+ // value steps are gated as the origin key with it (round 4 finding 2, round 5 finding 3).
8678
+ ...WORK_CONTRACT_FIELDS,
7434
8679
  }),
7435
8680
  response: () => z.object({ ok: z.boolean(), started: z.number(), runIds: z.array(z.string()) }),
7436
8681
  effect: "signal", cost: "variable", reversible: false, idempotent: false, simulatable: false, auth: "manage_workflows",
@@ -7760,29 +9005,17 @@ export const RECEIVERS = {
7760
9005
  // on the way back, and a name the model would pick by accident. The curated
7761
9006
  // `meet_human` (channels/src/tools/meetings.ts) is the chat surface.
7762
9007
  }),
7763
- "video:join-event": receiver({
7764
- receiver: "video:join-event",
7765
- summary: "Record a peer join event for tracking and lifecycle; public — called from the /go/ link handler",
7766
- request: () => z.object({
7767
- workspace: z.string(),
7768
- roomSlug: z.string(),
7769
- role: z.string().optional(),
7770
- actorId: z.string().optional(),
7771
- }),
7772
- response: () => z.object({ ok: z.boolean(), error: z.string().optional() }),
7773
- effect: "signal", cost: "free", idempotent: true,
7774
- examples: [{ workspace: "acme", roomSlug: "consult-abc", role: "guest" }],
7775
- }),
7776
9008
  "video:start-recording": receiver({
7777
9009
  receiver: "video:start-recording",
7778
- summary: "Start cloud recording for an active room via 100ms REST; inserts a video_recordings row",
9010
+ summary: "Start cloud recording for an active room via 100ms REST; inserts a video_recordings row. Idempotent per room: a repeat start while the room's recording is fresh returns that recording with reused:true; an HMS refusal is error:'hms_start_failed', never ok",
7779
9011
  request: () => z.object({ workspace: z.string(), roomSlug: z.string() }),
7780
9012
  response: () => z.object({
7781
9013
  ok: z.boolean(),
7782
9014
  recordingId: z.string().optional(),
9015
+ reused: z.boolean().optional(),
7783
9016
  error: z.string().optional(),
7784
9017
  }),
7785
- effect: "ask", cost: "free", idempotent: false, auth: "manage_clients",
9018
+ effect: "ask", cost: "free", idempotent: true, auth: "manage_clients",
7786
9019
  examples: [{ workspace: "acme", roomSlug: "algebra-101" }],
7787
9020
  surfaces: { chat: true, mcp: { name: "start_recording" } }, // fan-out: chat (actions-fan-out C5) + MCP (agent-native C1)
7788
9021
  }),
@@ -7825,53 +9058,155 @@ export const RECEIVERS = {
7825
9058
  examples: [{ workspace: "acme", roomSlug: "product-launch" }],
7826
9059
  surfaces: { chat: true, mcp: { name: "start_stream" } }, // fan-out: chat (actions-fan-out C5) + MCP (agent-native C1)
7827
9060
  }),
7828
- // connect:channel — token-paste connect for a channel (Connect plan C7). The
7829
- // typed contract over the shipped /api/connect/telegram route: the caller pastes
7830
- // a channel credential, web verifies it (getMe), points the webhook, then hands
7831
- // the raw secret to channels' /connect sink under the owner gate. SECURITY: the
7832
- // token rides the REQUEST only; the response NEVER echoes it. effect:ask,
7833
- // auth:manage_clients re-walked server-side off locals.slug (never body actorId).
7834
- "connect:channel": receiver({
7835
- receiver: "connect:channel",
7836
- summary: "Connect a channel (e.g. telegram) by pasting its bot token; verifies, sets the webhook, seals the credential under the owner gate",
7837
- request: () => z.object({
7838
- channel: z.string(), // 'telegram' (token-paste path)
7839
- token: z.string(), // the bot credential — request-only, never returned/logged
7840
- slug: z.string().optional(), // workspace; gate re-scopes to the authenticated owner
7841
- }),
7842
- response: () => z.object({
7843
- ok: z.boolean(),
7844
- status: z.string().optional(), // 'active' | 'updated' from the channels sink
7845
- account: z.string().optional(), // public handle (e.g. bot username) — never the token
7846
- error: z.string().optional(), // 'invalid token' | 'unauthorized' | 'duplicate'
7847
- }),
7848
- effect: "ask", cost: "free", reversible: false, idempotent: true, auth: "manage_clients",
7849
- examples: [{ channel: "telegram", token: "<bot-token>" }],
7850
- }),
7851
- // connect:status — list the workspace's connected channels (Connect plan C8).
7852
- // Read-only contract over /api/connect/status: rows come from the `connection`
7853
- // table scoped to the authenticated owner (locals.slug — never a body slug).
7854
- // SECURITY: the response carries channel + public account id + status only;
7855
- // cred_ref and webhook_secret never leave the server.
7856
- "connect:status": receiver({
7857
- receiver: "connect:status",
7858
- summary: "List connected channels for the workspace — channel, account, status, runtime; never the credential",
7859
- request: () => z.object({}),
9061
+ // ── News desk (text/magazine.md) — follow, fetch once, rank per group, publish an issue ──
9062
+ // Fetch is shared (a feed is public); everything private is keyed by the group. Handlers in
9063
+ // resolvers/news.ts. Every one refuses BY NAME: forbidden · not_found · bad_request ·
9064
+ // source_refused:<ssrf reason> · over_plan_cap · held:<reason>.
9065
+ "news:desk": receiver({
9066
+ receiver: "news:desk",
9067
+ surfaces: { chat: true, mcp: true },
9068
+ summary: "Read or change a group's news desk: what it follows, how much each topic matters, when it runs, the voice. `op` picks the action — get · set · add-source · remove-source · suggest · setup · clone · logos · source-stories. `setup` turns a few topics into a working desk (sources picked from the 50-source catalogue, the daily-magazine workflow armed) in one call",
9069
+ request: () => z.object({
9070
+ workspace: z.string().optional().describe("Group slug. Omit for your own. Honoured only if you control it."),
9071
+ op: z.enum(["get", "set", "add-source", "remove-source", "suggest", "setup", "clone", "logos", "source-stories"]).optional().describe("Default `get`. `logos` collects missing source logos (a few per call; `remaining` says how many are left). `source-stories` lists a followed source's newest stories (`url`)."),
9072
+ topics: z.union([z.array(z.string()), z.record(z.string(), z.number())]).optional().describe("`set`: {topic: weight 0–1}. `suggest` and `setup`: a list of topic words, e.g. [\"crypto\",\"sui\"]."),
9073
+ hour: z.number().int().min(0).max(23).optional().describe("UTC hour the issue is drafted and goes out."),
9074
+ cadence: z.enum(["daily", "weekdays"]).optional().describe("`set`: every day, or weekdays only, at `hour`."),
9075
+ refresh_hourly: z.boolean().optional().describe("`set`: true = re-draft the coming issue every hour with the latest news until it goes out (never publishes; spends credits inside the daily cap)."),
9076
+ voice: z.string().max(1000).optional().describe("One paragraph on how the takes should sound."),
9077
+ channels: z.array(z.enum(["page", "email", "social"])).optional(),
9078
+ grid_size: z.number().int().min(2).max(16).optional(),
9079
+ approve_after: z.number().int().min(1).max(30).optional().describe("Clean issues before the approval gate opens itself."),
9080
+ auto_publish: z.boolean().optional().describe("`set`: true = this is automated news, publish each issue on its own with no approval click. A story that fails its grounding check is dropped, never published. false = back to the trust ladder (approve_after)."),
9081
+ url: z.string().optional().describe("`add-source` / `remove-source`: the feed URL. A private address, an http URL or a slow host is refused by name."),
9082
+ name: z.string().optional(),
9083
+ source_topics: z.array(z.string()).optional().describe("`add-source`: the topics this source covers."),
9084
+ weight: z.number().min(0).max(3).optional().describe("`add-source`: how strongly this source pulls the ranking. Default 1."),
9085
+ from: z.string().optional().describe("`clone`: the group whose desk to copy. You must control both groups."),
9086
+ limit: z.number().int().min(1).max(25).optional().describe("`suggest` and `setup`: how many catalogue sources. Default 12."),
9087
+ }),
7860
9088
  response: () => z.object({
7861
9089
  ok: z.boolean(),
7862
- connections: z
7863
- .array(z.object({
7864
- channel: z.string(), // 'telegram' | 'slack' | 'discord' | 'email'
7865
- account: z.string(), // external_account_id (bot id / team id / inbound address)
7866
- status: z.string(), // 'active' | 'revoked'
7867
- runtime: z.string(), // 'webhook' | 'socket'
7868
- connected_at: z.number(), // unix epoch seconds
7869
- }))
7870
- .optional(),
9090
+ desk: z.record(z.string(), z.unknown()).optional(),
9091
+ sources: z.array(z.record(z.string(), z.unknown())).optional(),
9092
+ view: z.record(z.string(), z.unknown()).optional().describe("`get`: the desk with feed states, the last issues and their cost."),
9093
+ suggestions: z.array(z.record(z.string(), z.unknown())).optional(),
9094
+ workflowId: z.string().optional().describe("`setup`: the armed daily-magazine workflow."),
9095
+ collected: z.number().optional().describe("`logos`: logos stored this call."),
9096
+ remaining: z.number().optional().describe("`logos`: sources still to try."),
9097
+ stories: z.array(z.record(z.string(), z.unknown())).optional().describe("`source-stories`: {url, title, excerpt, at, picked} newest first; picked = the issue date it ran in."),
9098
+ skipped: z.array(z.object({ url: z.string(), error: z.string() })).optional().describe("Sources that were refused or over the plan cap, each with the reason."),
7871
9099
  error: z.string().optional(),
7872
9100
  }),
7873
- effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "manage_clients",
7874
- examples: [{}],
9101
+ effect: "ask", cost: "free", reversible: true, idempotent: false, auth: "manage_workspace",
9102
+ examples: [{ workspace: "acme", op: "setup", topics: ["crypto", "sui"] }],
9103
+ }),
9104
+ "news:ingest": receiver({
9105
+ receiver: "news:ingest",
9106
+ summary: "Fetch the feeds that are due — once each, for every group that follows them. Conditional GET, size and time caps, every URL and redirect hop through the SSRF guard. Run by the platform clock; not a per-group call",
9107
+ request: () => z.object({ limit: z.number().int().min(1).max(50).optional() }),
9108
+ response: () => z.object({
9109
+ ok: z.boolean(),
9110
+ feeds_due: z.number().optional(), fetched: z.number().optional(), not_modified: z.number().optional(),
9111
+ failed: z.number().optional(), items_new: z.number().optional(),
9112
+ truncated: z.number().optional().describe("Feeds larger than the 1 MB read cap: read from their head (newest items), not refused."),
9113
+ capped: z.boolean().optional().describe("True when more feeds were due than this tick would fetch."),
9114
+ refused: z.record(z.string(), z.number()).optional(),
9115
+ error: z.string().optional(),
9116
+ }),
9117
+ effect: "ask", cost: "variable", reversible: false, idempotent: true, auth: "platform",
9118
+ }),
9119
+ "news:digest": receiver({
9120
+ receiver: "news:digest",
9121
+ surfaces: { chat: true, mcp: true },
9122
+ summary: "Pick and rank the day's stories for one group, write each take from the article only, find a picture, and store them as today's draft issue. Returns the issue id and honest counts — fetched · eligible · folded · kept · capped (with the budget that bit) · skipped by reason. Re-running the same day replaces the picks and keeps the issue",
9123
+ request: () => z.object({ workspace: z.string().optional().describe("Group slug. Omit for your own."), refresh: z.boolean().optional().describe("Set by the hourly refresh workflow: only narrows — refused once the day's run has begun (the desk's hour on the issue's day), so an issue a person may be reviewing is never rebuilt.") }),
9124
+ response: () => z.object({
9125
+ ok: z.boolean(), issueId: z.string().optional(),
9126
+ counts: z.record(z.string(), z.unknown()).optional(),
9127
+ held: z.string().optional().describe("Why the issue is held (e.g. `ungrounded`): a person must fix or drop a story before it can publish."),
9128
+ cost_credits: z.number().optional(),
9129
+ error: z.string().optional(),
9130
+ }),
9131
+ effect: "ask", cost: "variable", reversible: true, idempotent: false, auth: "manage_workspace",
9132
+ }),
9133
+ "news:issue": receiver({
9134
+ receiver: "news:issue",
9135
+ surfaces: { chat: true, mcp: true },
9136
+ summary: "Build the issue from its picks: one editable page (lead, grid, source strip) that the email and the post drafts are both made from. Rebuilding replaces the page's content and keeps its address",
9137
+ request: () => z.object({
9138
+ refresh: z.boolean().optional().describe("Set by the hourly refresh workflow: only narrows — refused once the day's run has begun (the desk's hour on the issue's day), so an issue a person may be reviewing is never rebuilt."),
9139
+ workspace: z.string().optional().describe("Group slug. Omit for your own."),
9140
+ issueId: z.string().optional().describe("Default: today's draft issue."),
9141
+ }),
9142
+ response: () => z.object({
9143
+ ok: z.boolean(), issueId: z.string().optional(), pageSlug: z.string().optional(), url: z.string().optional(),
9144
+ drafts: z.number().optional().describe("Social drafts queued, awaiting approval in /in/social."),
9145
+ gate_open: z.boolean().optional().describe("True when the desk has run enough clean issues that publishing needs no person. The workflow's `trusted?` condition reads this."),
9146
+ error: z.string().optional(),
9147
+ }),
9148
+ effect: "ask", cost: "variable", reversible: true, idempotent: true, auth: "manage_workspace",
9149
+ }),
9150
+ "news:publish": receiver({
9151
+ receiver: "news:publish",
9152
+ surfaces: { chat: true, mcp: true },
9153
+ summary: "Publish the issue: the page goes live, the email is scheduled to confirmed subscribers (suppression and unsubscribe unchanged) and the post drafts are queued. Reads the PAGE at publish time, so an edit is what goes out. A held issue is refused by name. Needs a person unless the desk's gate has opened itself: a closed gate opens only for a signed-in person or a workflow run a person approved, never for a flag in the request",
9154
+ request: () => z.object({
9155
+ workspace: z.string().optional().describe("Group slug. Omit for your own."),
9156
+ issueId: z.string().optional().describe("Default: today's issue."),
9157
+ approve: z.boolean().optional().describe("A signed-in person's intent to publish. On its own it opens nothing: a closed gate answers `held:needs_approval` unless the caller is a signed-in person or a workflow run whose approval step a person resolved."),
9158
+ }),
9159
+ response: () => z.object({
9160
+ ok: z.boolean(), status: z.string().optional(), broadcastId: z.string().optional(), url: z.string().optional(),
9161
+ edited_ratio: z.number().optional(), gate_open: z.boolean().optional(),
9162
+ error: z.string().optional(),
9163
+ }),
9164
+ effect: "signal", cost: "variable", reversible: false, idempotent: false, auth: "manage_workspace",
9165
+ }),
9166
+ "news:react": receiver({
9167
+ receiver: "news:react",
9168
+ surfaces: { chat: true, mcp: true },
9169
+ summary: "More or less of a story: strengthens or resists the desk's paths to that source and its topics, so tomorrow's order changes. One reaction of a kind per person per story counts",
9170
+ request: () => z.object({
9171
+ workspace: z.string().optional().describe("Group slug. Omit for your own."),
9172
+ issueId: z.string(), itemUrl: z.string().describe("The story's article URL, as on the issue."),
9173
+ reaction: z.enum(["more", "less", "tap", "skip"]),
9174
+ }),
9175
+ response: () => z.object({ ok: z.boolean(), deduped: z.boolean().optional(), error: z.string().optional() }),
9176
+ effect: "signal", cost: "free", reversible: false, idempotent: true, auth: "member",
9177
+ }),
9178
+ "news:assist": receiver({
9179
+ receiver: "news:assist",
9180
+ summary: "A story's quick actions — summarise, expand, research, article in the group's voice, or related stories. Asked once, kept for everyone: a cached answer comes back instantly; a miss runs the model the route's paths favour (assist:<kind>: → model:<id>), falls to the next on failure, and stores the answer. Anyone reads cached answers of published stories; a signed-in person may start one (20 a day per group); owners may force a fresh one. A verdict marks or warns the model that wrote the answer",
9181
+ request: () => z.object({
9182
+ workspace: z.string().describe("The magazine's group slug."),
9183
+ itemUrl: z.string().describe("The story's article URL, as on the issue."),
9184
+ kind: z.enum(["summarise", "expand", "research", "article", "related", "journey"]).describe("What to do with the story. related and journey need no model: stories sharing its tags; the story's path from its feed to its posts."),
9185
+ fresh: z.boolean().optional().describe("Owners only: run the model again even though an answer is stored."),
9186
+ verdict: z.enum(["up", "down"]).optional().describe("Judge the stored answer instead: marks or warns the model that wrote it."),
9187
+ }),
9188
+ response: () => z.object({
9189
+ ok: z.boolean(), kind: z.string().optional(), text: z.string().optional(), model: z.string().optional(), cached: z.boolean().optional(), ms: z.number().optional(),
9190
+ related: z.array(z.object({ title: z.string(), url: z.string(), source: z.string(), date: z.string(), shared: z.array(z.string()) })).optional(),
9191
+ journey: z.array(z.object({ step: z.string(), at: z.number().nullable(), label: z.string(), detail: z.string().optional(), href: z.string().optional() })).optional(),
9192
+ judged: z.string().optional(), error: z.string().optional(),
9193
+ }),
9194
+ effect: "ask", cost: "variable", reversible: false, idempotent: true, auth: "public",
9195
+ }),
9196
+ "news:edit": receiver({
9197
+ receiver: "news:edit",
9198
+ summary: "A person edits an issue by hand: rate a story 1 to 10 (10 leads the issue, 1 sinks it), rewrite its headline or take inline, or remove it (undoable). The page is rebuilt in the new order, a published issue's page included — the email already sent is not. A rating teaches two kinds of path by its change from the last: the desk's (tomorrow's issue) and the person's own (reader:<slug>: → source / tag)",
9199
+ request: () => z.object({
9200
+ workspace: z.string().optional().describe("Group slug. Omit for your own; a named group must be one you control."),
9201
+ issueId: z.string().describe("The issue the story is on."),
9202
+ itemUrl: z.string().describe("The story's article URL, as on the issue."),
9203
+ action: z.enum(["rate", "remove", "restore", "text"]).describe("rate sets the story's score; remove takes it off the issue; restore puts it back; text saves a rewritten headline and/or take."),
9204
+ value: z.number().int().min(0).max(10).optional().describe("rate: 1 to 10; 0 clears the rating."),
9205
+ headline: z.string().max(300).optional().describe("text: the new headline; empty returns the article's own."),
9206
+ take: z.string().max(1200).optional().describe("text: the new take (counts as checked — a person wrote it)."),
9207
+ }),
9208
+ response: () => z.object({ ok: z.boolean(), rating: z.number().optional(), removed: z.boolean().optional(), learned: z.number().optional(), error: z.string().optional() }),
9209
+ effect: "ask", cost: "free", reversible: true, idempotent: false, auth: "manage_workspace",
7875
9210
  }),
7876
9211
  // ── Broadcast (newsletter) ────────────────────────────────────────────────
7877
9212
  "broadcast:create": receiver({
@@ -8317,12 +9652,23 @@ export const RECEIVERS = {
8317
9652
  fn: z.string().describe("Function name from FN_MAP (e.g. 'optimal_route', 'actionable_hypotheses')"),
8318
9653
  args: z.record(z.string(), z.unknown()).optional().describe("Named arguments matching the function's param list"),
8319
9654
  workspace: z.string().optional().describe("Workspace slug for authority context"),
9655
+ // tql-edge contract #12: read the DO itself instead of the 30 s isolate memo —
9656
+ // exact for a write patched through /brain/patch, never a sub-50 ms read.
9657
+ // Declared here or the /api/ask edge strips it before the resolver sees it.
9658
+ fresh: z.boolean().optional().describe("Bypass the edge memo and read the graph from BrainDO (slower, exact)"),
8320
9659
  }),
8321
9660
  response: () => z.object({
8322
9661
  ok: z.boolean(),
8323
9662
  fn: z.string(),
8324
9663
  rows: z.array(z.record(z.string(), z.unknown())),
8325
9664
  error: z.string().optional(),
9665
+ // tql-edge C6: the answer is solved over the graph in RAM (@oneie/sdk/edge).
9666
+ // `edge` says whether it was; `asOf` is the graph's own timestamp (a memo read
9667
+ // is never exact — contract #12); `truncated` appears ONLY when a type the fun
9668
+ // touched was cut from the snapshot (contract #13).
9669
+ edge: z.boolean().optional(),
9670
+ asOf: z.string().optional(),
9671
+ truncated: z.array(z.string()).optional(),
8326
9672
  }),
8327
9673
  effect: "ask", cost: "variable", reversible: false, idempotent: true, auth: "member",
8328
9674
  examples: [{ fn: "optimal_route", args: { $from: "actor-123", $skill: "writing" }, workspace: "acme" }],
@@ -8490,7 +9836,7 @@ export const RECEIVERS = {
8490
9836
  receiver: "seo:backlinks-summary",
8491
9837
  surfaces: { mcp: { name: "seo_backlinks" } },
8492
9838
  summary: "Pull live backlink summary for a domain via DataForSEO; marks domain→seo:backlinks path",
8493
- request: () => z.object({ target: z.string(), limit: z.number().int().min(1).max(1000).optional() }),
9839
+ request: () => z.object({ slug: SERVICE_SLUG, target: z.string(), limit: z.number().int().min(1).max(1000).optional() }),
8494
9840
  response: () => z.object({ ok: z.boolean(), data: z.unknown().optional(), error: z.string().optional() }),
8495
9841
  effect: "ask", cost: "variable", reversible: true, idempotent: false, auth: "member",
8496
9842
  examples: [{ target: "one.ie" }],
@@ -8499,7 +9845,7 @@ export const RECEIVERS = {
8499
9845
  receiver: "seo:llm-mentions",
8500
9846
  surfaces: { mcp: { name: "seo_ai_visibility" } },
8501
9847
  summary: "Pull live AI-visibility (LLM mentions) data for a domain via DataForSEO; marks domain→seo:llm-mentions path",
8502
- request: () => z.object({ target: z.string() }),
9848
+ request: () => z.object({ slug: SERVICE_SLUG, target: z.string() }),
8503
9849
  response: () => z.object({ ok: z.boolean(), data: z.unknown().optional(), error: z.string().optional() }),
8504
9850
  effect: "ask", cost: "variable", reversible: true, idempotent: false, auth: "member",
8505
9851
  examples: [{ target: "one.ie" }],
@@ -8508,7 +9854,7 @@ export const RECEIVERS = {
8508
9854
  receiver: "seo:keywords-for-keyword",
8509
9855
  surfaces: { mcp: { name: "seo_research_keywords" } },
8510
9856
  summary: "Return related keyword suggestions for a seed keyword via DataForSEO Google Ads; marks keyword→seo:keywords path",
8511
- request: () => z.object({ keyword: z.string(), location_code: z.number().int().optional(), language_code: z.string().optional() }),
9857
+ request: () => z.object({ slug: SERVICE_SLUG, keyword: z.string(), location_code: z.number().int().optional(), language_code: z.string().optional() }),
8512
9858
  response: () => z.object({ ok: z.boolean(), data: z.unknown().optional(), error: z.string().optional() }),
8513
9859
  effect: "ask", cost: "variable", reversible: true, idempotent: false, auth: "member",
8514
9860
  examples: [{ keyword: "ai agents", location_code: 2840, language_code: "en" }],
@@ -8831,6 +10177,62 @@ export const RECEIVERS = {
8831
10177
  { prefix: "ads", limit: 1000 },
8832
10178
  ],
8833
10179
  }),
10180
+ // media:films — the films the site plays, with this group's stars and tags (text/library.md).
10181
+ //
10182
+ // The catalog is code (`one.ie/web/src/lib/film/catalog.ts`): every entry plays from
10183
+ // public/film/ through the FilmPlayer block with exactly `props`, and `backgrounds` are the
10184
+ // bgEffect keys that put it behind any block. Stars and tags are the group's own — entity_tags
10185
+ // rows keyed `film:<id>`, written by `entity:tag` (a star is the tag `star`). So "the films
10186
+ // tagged hero" is one call here, and placing one is `pages:add-block` with
10187
+ // `{component:"FilmPlayer", props}` or a block's `bgEffect`. Resolver: resolvers/media.ts.
10188
+ "media:films": receiver({
10189
+ receiver: "media:films",
10190
+ surfaces: { mcp: true, chat: true },
10191
+ summary: "The films the site plays — the key ad, the told story, the playbook, the Hook film, the home film and each of its fifteen scenes, the Hook workshop — each with its poster, the FilmPlayer props that play it, the bgEffect keys that put it behind a block, and this group's stars and tags. Filter by `tag` or `starred`. To place one: pages:add-block {component:\"FilmPlayer\", props}; to put one behind a block: set its bgEffect to a `backgrounds` key. To star or tag: entity:tag {id:\"film:<id>\", add:[\"star\"|tag]}. With a tag, `reel` is that tag's home-film scenes played as one film — a video made from a tag, placed the same way.",
10192
+ request: () => z.object({
10193
+ workspace: z.string().optional().describe("Group slug whose stars and tags to read. Omit for your own. Honoured only if you may read it."),
10194
+ tag: z.string().optional().describe("Only films carrying this tag in this group, e.g. \"hero\" or \"home\". `star` is the starred ones."),
10195
+ starred: z.boolean().optional().describe("true = only starred films (the same as tag:\"star\")."),
10196
+ kind: z.enum(["film", "scene"]).optional().describe("film = a whole film; scene = one scene of the home film, played on its own."),
10197
+ }),
10198
+ response: () => z.object({
10199
+ ok: z.boolean(),
10200
+ workspace: z.string().optional(),
10201
+ items: z.array(z.object({
10202
+ id: z.string().describe("Catalog id; its stars and tags live under entity id `film:<id>`."),
10203
+ name: z.string(),
10204
+ desc: z.string(),
10205
+ kind: z.enum(["film", "scene"]),
10206
+ parent: z.string().optional().describe("For a scene, the film it belongs to."),
10207
+ poster: z.string().describe("Site path of the poster JPEG."),
10208
+ play: z.string().describe("Site path that plays it on its own page — shareable."),
10209
+ component: z.literal("FilmPlayer").describe("The Puck block that places it."),
10210
+ props: z.record(z.string(), z.unknown()).describe("The FilmPlayer props — pass verbatim to pages:add-block."),
10211
+ shapes: z.array(z.string()).describe("Aspect values the film plays in: 1x1 · 4x5 · 9x16 · 16x9."),
10212
+ backgrounds: z.array(z.string()).describe("bgEffect keys that put this film behind any block. Empty = not offered as a background."),
10213
+ tags: z.array(z.string()).describe("This group's tags on it, `star` included."),
10214
+ starred: z.boolean(),
10215
+ })).optional(),
10216
+ total: z.number().optional().describe("Items in this answer, after filtering. The catalog is small and never paged — this is exact."),
10217
+ tags: z.record(z.string(), z.number()).optional().describe("Every tag this group has put on any film, with how many films carry it — the filter list."),
10218
+ reel: z.object({
10219
+ name: z.string(),
10220
+ scenes: z.array(z.string()).describe("Home-film scene keys, in film order."),
10221
+ duration: z.number().describe("Seconds — the windows added up."),
10222
+ play: z.string().describe("Site path that plays the reel on its own page."),
10223
+ component: z.literal("FilmPlayer"),
10224
+ props: z.record(z.string(), z.unknown()).describe("Pass verbatim to pages:add-block — `scenes` is the reel."),
10225
+ }).optional().describe("With `tag` or `starred`: the home-film scenes that carry it, as ONE film played back to back. ABSENT when fewer than two scenes carry it. Whole films in the tag are not in the reel (a reel is windows on one master)."),
10226
+ error: z.string().optional(),
10227
+ }),
10228
+ effect: "ask", cost: "free", idempotent: true, reversible: true, settles: "none", auth: "member",
10229
+ examples: [
10230
+ {},
10231
+ { starred: true },
10232
+ { tag: "hero" },
10233
+ { kind: "scene" },
10234
+ ],
10235
+ }),
8834
10236
  // media:upload — bytes in, one key out, under `{workspace}/media/`.
8835
10237
  //
8836
10238
  // TWO SHAPES BECAUSE AN AGENT HAS NEITHER A FILE PICKER NOR A MULTIPART BODY. The
@@ -8931,9 +10333,9 @@ export const RECEIVERS = {
8931
10333
  "affiliate:ppc-payout": receiver({
8932
10334
  receiver: "affiliate:ppc-payout",
8933
10335
  summary: "Drains unpaid PPC accrual for a budget to affiliate payout addresses via pay.one.ie",
8934
- request: () => z.object({ budgetId: z.unknown().optional(), chain: z.unknown().optional(), refToAddress: z.unknown().optional(), treasuryAddress: z.unknown().optional(), workspace: z.unknown().optional() }).passthrough(),
10336
+ request: () => z.object({ budgetId: z.unknown().optional(), chain: z.unknown().optional(), refToAddress: z.unknown().optional(), treasuryAddress: z.unknown().optional(), workspace: z.unknown().optional(), ...WORK_CONTRACT_FIELDS }).passthrough(),
8935
10337
  response: () => z.unknown(),
8936
- effect: "ask", auth: "owner", reversible: false,
10338
+ effect: "ask", auth: "owner", reversible: false, moves: "value", movesIn: ["workspace"],
8937
10339
  }),
8938
10340
  "agent:draft": receiver({
8939
10341
  receiver: "agent:draft",
@@ -8979,6 +10381,13 @@ export const RECEIVERS = {
8979
10381
  response: () => z.unknown(),
8980
10382
  effect: "ask", auth: "member", reversible: false,
8981
10383
  }),
10384
+ "campaign:rebuild": receiver({
10385
+ receiver: "campaign:rebuild",
10386
+ summary: "Runs the ELEVATE build again for a campaign that is stuck or failed; brief defaults to the campaign name",
10387
+ request: () => z.object({ campaignId: z.unknown().optional(), brief: z.unknown().optional() }).passthrough(),
10388
+ response: () => z.unknown(),
10389
+ effect: "ask", auth: "member", reversible: false,
10390
+ }),
8982
10391
  "campaign:update": receiver({
8983
10392
  receiver: "campaign:update",
8984
10393
  summary: "Updates a campaign's name or a specific section's content, and returns the updated campaign info",
@@ -8986,6 +10395,24 @@ export const RECEIVERS = {
8986
10395
  response: () => z.unknown(),
8987
10396
  effect: "ask", auth: "member", reversible: false,
8988
10397
  }),
10398
+ // The campaign build pipeline: compile the stored sections into a workflow (compile), and the same
10399
+ // door driven by the approve button, which runs it (approve). Renamed from the two-colon
10400
+ // ui:campaigns:approve / ui:campaigns:compile, which /receivers/<family>/<verb> cannot route
10401
+ // (task:01a0f0bfd11bccc1674f7241).
10402
+ "campaign:approve": receiver({
10403
+ receiver: "campaign:approve",
10404
+ summary: "Approves a campaign: compiles its stored sections (else the sections sent) into a workflow and runs it. Add requireApproval to put a human gate before the first send",
10405
+ request: () => z.object({ campaignId: z.unknown().optional(), sections: z.unknown().optional(), requireApproval: z.unknown().optional() }).passthrough(),
10406
+ response: () => z.unknown(),
10407
+ effect: "ask", auth: "member", reversible: false,
10408
+ }),
10409
+ "campaign:compile": receiver({
10410
+ receiver: "campaign:compile",
10411
+ summary: "Compiles a campaign's stored sections (else the sections sent) into a workflow and runs it. Add requireApproval to put a human gate before the first send",
10412
+ request: () => z.object({ campaignId: z.unknown().optional(), sections: z.unknown().optional(), requireApproval: z.unknown().optional() }).passthrough(),
10413
+ response: () => z.unknown(),
10414
+ effect: "ask", auth: "member", reversible: false,
10415
+ }),
8989
10416
  "chat:delete-template": receiver({
8990
10417
  receiver: "chat:delete-template",
8991
10418
  summary: "Deletes a chat template for a chip_id in the workspace",
@@ -9012,6 +10439,7 @@ export const RECEIVERS = {
9012
10439
  summary: "Mints a shareable payment link for a product price",
9013
10440
  request: () => z.object({ chain: z.unknown().optional(), network: z.unknown().optional(), ppid: z.unknown().optional(), slug: z.unknown().optional() }).passthrough(),
9014
10441
  response: () => z.unknown(),
10442
+ // Intent-only: mints a link a buyer later pays — not `moves: "value"`.
9015
10443
  effect: "ask", auth: "owner", reversible: false,
9016
10444
  }),
9017
10445
  "checkout:notify": receiver({
@@ -9035,6 +10463,123 @@ export const RECEIVERS = {
9035
10463
  response: () => z.unknown(),
9036
10464
  effect: "ask", auth: "owner", reversible: false,
9037
10465
  }),
10466
+ // ── content everywhere — handlers in resolvers/content.ts (text/content-everywhere.md) ──
10467
+ // One source + one campaign → a draft for every format it fits, as things. Nothing
10468
+ // publishes here: every variant lands 'draft' and waits for a person.
10469
+ "content:everywhere": receiver({
10470
+ receiver: "content:everywhere",
10471
+ summary: "Put one piece of content everywhere: one video or image + one campaign → a native draft for every social format and every ad format it fits, written from the campaign's playbook stage, filed under the campaign as content things, with every misfit derived or named impossible. Counts what was made, failed, derived and skipped; nothing publishes — the reply links to the campaign page where a person approves each draft.",
10472
+ request: () => z.object({
10473
+ workspace: z.string().optional().describe("Group slug. Omit for the attested workspace. A scope REQUEST — refused (forbidden) when the authority walk says no, never swapped for your own."),
10474
+ campaignId: z.string().describe("The campaign's gid (world_groups.gid tagged `campaign`) in this workspace — the campaign the drafts are filed under."),
10475
+ mediaUrl: z.string().describe("The source video or image url — an attachment in the conversation, or an item from media:list."),
10476
+ mediaType: z.enum(["image", "video"]).describe("What the source is."),
10477
+ text: z.string().min(1).describe("The message every format is written from — the person's words."),
10478
+ stageKey: z.string().optional().describe("The ELEVATE stage (0–10, or the campaign's own section key) that briefs every draft. Change the stage, the words change."),
10479
+ width: z.number().optional().describe("Source width in px, when known — decides which aspect formats fit as-is."),
10480
+ height: z.number().optional().describe("Source height in px, when known."),
10481
+ durationS: z.number().optional().describe("Source duration in seconds, for a video."),
10482
+ origin: z.string().optional().describe("Absolute origin to resolve a relative mediaUrl for the render service (the route passes url.origin)."),
10483
+ }),
10484
+ response: () => z.object({
10485
+ ok: z.boolean(),
10486
+ error: z.string().optional().describe("Named: forbidden · bad_request · campaign_not_found · no_db."),
10487
+ postId: z.string().optional().describe("The master social_posts row the variants hang off."),
10488
+ sourceTid: z.string().optional().describe("The source content thing (world_things type 'content', kind:source)."),
10489
+ campaign: z.object({ gid: z.string(), name: z.string(), url: z.string() }).optional(),
10490
+ campaignId: z.string().optional(),
10491
+ stage: z.string().nullable().optional(),
10492
+ source: z.object({ kind: z.string(), aspect: z.string(), durationS: z.number().optional() }).optional(),
10493
+ formats: z.object({ total: z.number(), accounted: z.number(), unaccounted: z.array(z.string()) }).optional().describe("Every catalog format is in exactly one of social, ads, derived, impossible or skipped; `unaccounted` is empty or the answer is wrong."),
10494
+ counts: z.record(z.string(), z.number()).optional().describe("drafted · failed · ads · adsFailed · derived · derivedMade · derivedFailed · impossible · skipped."),
10495
+ variants: z.array(z.record(z.string(), z.unknown())).optional(),
10496
+ errors: z.array(z.string()).optional(),
10497
+ ads: z.object({ drafts: z.array(z.record(z.string(), z.unknown())), error: z.string().nullable() }).optional(),
10498
+ derived: z.object({ made: z.array(z.record(z.string(), z.unknown())), failed: z.array(z.record(z.string(), z.unknown())) }).optional(),
10499
+ impossible: z.array(z.record(z.string(), z.unknown())).optional(),
10500
+ skipped: z.array(z.record(z.string(), z.unknown())).optional(),
10501
+ published: z.number().optional().describe("Always 0 — this door never publishes."),
10502
+ link: z.string().optional().describe("The campaign page: /u/<slug>/marketing/campaigns/<campaign slug or gid>."),
10503
+ reply: z.string().optional().describe("One sentence for the conversation, carrying the link."),
10504
+ }),
10505
+ effect: "ask", cost: "variable", reversible: false, idempotent: false, auth: "manage_things",
10506
+ surfaces: { chat: true },
10507
+ examples: [{ campaignId: "01a04decf44a2caf7353139c", mediaUrl: "https://one.ie/api/product-image/one/media/clip.mp4", mediaType: "video", text: "One video becomes every post.", stageKey: "1" }],
10508
+ }),
10509
+ "content:derive": receiver({
10510
+ receiver: "content:derive",
10511
+ summary: "Derive every format a source does not fit as-is — reframe (9:16 · 1:1 · 4:5 · 16:9), stills, slides, PDF pages, text-only — from one source content thing, recording each derived asset as a thing. Idempotent: what was already derived is reported `already`, never made twice. Wraps deriveForPlan (lib/content-derive.ts).",
10512
+ request: () => z.object({
10513
+ workspace: z.string().optional().describe("Group slug. Omit for the attested workspace; refused when not yours."),
10514
+ sourceTid: z.string().describe("The source content thing's tid (content:everywhere answers it as `sourceTid`)."),
10515
+ }),
10516
+ response: () => z.object({
10517
+ ok: z.boolean(),
10518
+ error: z.string().optional().describe("Named: forbidden · bad_request · source_not_found · no_db."),
10519
+ sourceTid: z.string().optional(),
10520
+ campaignId: z.string().optional(),
10521
+ postId: z.string().optional().describe("The master social_posts row the source thing points at ('' when it points at none)."),
10522
+ digest: z.string().optional().describe("What the brand guardian reads: one line per variant and per ad creative of this post (`id | what | text`), cut fairly to fit agent:run's 16,000-char sealed-input guard. Lines that were cut end in `[cut: N of M chars shown]`."),
10523
+ review: z.record(z.string(), z.unknown()).optional().describe("About the digest: total · shown · omitted (ids with no room) · truncated · truncatedIds · budget · jsonChars · items[{id,kind,platform,format,chars,shown,truncated}] · error."),
10524
+ made: z.array(z.record(z.string(), z.unknown())).optional(),
10525
+ failed: z.array(z.record(z.string(), z.unknown())).optional(),
10526
+ impossible: z.array(z.record(z.string(), z.unknown())).optional(),
10527
+ already: z.number().optional().describe("Derivations skipped because a derived thing for that format already exists."),
10528
+ counts: z.record(z.string(), z.number()).optional().describe("planned · made · failed · impossible · already."),
10529
+ }),
10530
+ effect: "ask", cost: "variable", reversible: false, idempotent: true, auth: "manage_things",
10531
+ }),
10532
+ "content:schedule": receiver({
10533
+ receiver: "content:schedule",
10534
+ summary: "Spread a post's approved variants across the calendar: one per network per day starting tomorrow 09:00, writing social_post_variants.scheduled_at + status 'scheduled'. Facebook is the only network with a live connection; every other network and every ad is scheduled as a draft and says so in its note (Instagram and the ad pushers answered 404 on 2026-10-12; Meta Ads is not connected).",
10535
+ request: () => z.object({
10536
+ workspace: z.string().optional().describe("Group slug. Omit for the attested workspace; refused when not yours."),
10537
+ postId: z.string().optional().describe("The master social_posts row whose variants to schedule. Required unless `variantId` is given."),
10538
+ variantId: z.string().optional().describe("Move exactly ONE variant of this workspace to `at` instead of re-slotting a post. Only a 'scheduled' or 'approved' row moves; a published, failed or skipped one is refused. A bare world key is refused (moving a slot to now arms a real publish)."),
10539
+ at: z.number().optional().describe("Unix seconds (an integer) for `variantId`. Required with `variantId`; ignored without it."),
10540
+ all: z.boolean().optional().describe("true when a person approved the whole run (a workflow's human step): schedules 'draft' variants as well as 'approved' ones."),
10541
+ timezone: z.string().optional().describe("IANA zone for the 09:00 slot. Default UTC — a workspace carries no timezone setting today."),
10542
+ }),
10543
+ response: () => z.object({
10544
+ ok: z.boolean(),
10545
+ error: z.string().optional().describe("Named: forbidden · bad_request · post_not_found · no_db."),
10546
+ postId: z.string().optional(),
10547
+ campaignId: z.string().nullable().optional(),
10548
+ scheduled: z.array(z.object({ id: z.string(), platform: z.string(), format: z.string(), at: z.number(), live: z.boolean(), note: z.string().optional() })).optional(),
10549
+ skipped: z.array(z.object({ id: z.string(), platform: z.string(), format: z.string(), reason: z.string() })).optional().describe("Variants held back because the brand guardian's verdict (meta.verdict, written by content:verdicts) is 'revise'; each names the reason. No verdict behaves as before."),
10550
+ failed: z.array(z.object({ id: z.string(), platform: z.string(), format: z.string(), error: z.string() })).optional(),
10551
+ ads: z.number().optional().describe("Ad creatives under this post noted as drafts (no live connection)."),
10552
+ counts: z.record(z.string(), z.number()).optional(),
10553
+ timezone: z.string().optional(),
10554
+ summary: z.string().optional().describe("One line per network for the board."),
10555
+ variantId: z.string().optional().describe("Set when `variantId` was given: the variant that moved."),
10556
+ platform: z.string().optional(),
10557
+ format: z.string().optional(),
10558
+ at: z.number().optional().describe("The slot the variant now holds (unix seconds)."),
10559
+ live: z.boolean().optional().describe("Single-variant answer: true when the network has a live connection."),
10560
+ note: z.string().optional(),
10561
+ }),
10562
+ effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "manage_things",
10563
+ }),
10564
+ "content:verdicts": receiver({
10565
+ receiver: "content:verdicts",
10566
+ summary: "Write the brand guardian's verdict on EACH draft and ad creative of a post. Parses one line per item (`<id>: approve|revise - reason`) from the review step's text and saves meta.verdict + verdict_reason on every social_post_variants row and every creative-asset thing; an item the reviewer never mentioned is saved as 'no-verdict', never as approval. Marks content:review -> <platform>:<format> on approve, warns on revise and on no-verdict. Ids are recomputed from the workspace's own rows, never taken from the caller. Does not change any status — the human approve step is still the gate.",
10567
+ request: () => z.object({
10568
+ workspace: z.string().optional().describe("Group slug. Omit for the attested workspace; refused when not yours."),
10569
+ postId: z.string().describe("The master social_posts row whose variants and ad creatives were reviewed (content:derive answers it as `postId`)."),
10570
+ text: z.string().describe("The reviewer's reply: one line per item id, `<id>: approve - reason` or `<id>: revise - reason`."),
10571
+ }),
10572
+ response: () => z.object({
10573
+ ok: z.boolean(),
10574
+ error: z.string().optional().describe("Named: forbidden · bad_request · post_not_found · no_db."),
10575
+ postId: z.string().optional(),
10576
+ counts: z.record(z.string(), z.number()).optional().describe("items · approve · revise · noVerdict · failed (verdict could not be saved) · unknown (ids in the reply that are not items)."),
10577
+ verdicts: z.array(z.record(z.string(), z.unknown())).optional().describe("One per item: id · kind (variant|ad) · platform · format · verdict (approve|revise|no-verdict) · reason · written."),
10578
+ unknownIds: z.array(z.string()).optional(),
10579
+ summary: z.string().optional().describe("One line for the board."),
10580
+ }),
10581
+ effect: "ask", cost: "free", reversible: false, idempotent: true, auth: "manage_things",
10582
+ }),
9038
10583
  "conversation:autonomy": receiver({
9039
10584
  receiver: "conversation:autonomy",
9040
10585
  summary: "Read a conversation's autonomy level from tags, defaulting to 'auto' when missing, for the channels worker to decide send vs draft",
@@ -9093,7 +10638,7 @@ export const RECEIVERS = {
9093
10638
  }),
9094
10639
  "learning:complete": receiver({
9095
10640
  receiver: "learning:complete",
9096
- summary: "Grants credits and records pending reward when a learner completes a course stage. FINDING: falls back to data.workspace when the caller is unattested",
10641
+ summary: "Grants the attested caller credits and a pending reward for a course stage (or whole course) the substrate already records them completing — their own enrolment and their own account progress rows, never a device row; once per caller, course and stage. Platform courses only: any other course answers {ok:true, creditsGranted:0, reason:'course_not_rewarding'}. An author of the course's workspace earns nothing; a roles read that cannot answer refuses retryably ('unavailable'). Per-learner ceiling of 1 course and 10 lesson rewards a UTC day — past it, 'daily_limit'; a platform-wide budget of 100,000 course-reward credits a UTC day — past it, 'daily_budget' (retryable). Both limits are checked in the same statement as the grant",
9097
10642
  request: () => z.object({ courseId: z.unknown().optional(), kind: z.unknown().optional(), stageId: z.unknown().optional(), workspace: z.unknown().optional() }).passthrough(),
9098
10643
  response: () => z.unknown(),
9099
10644
  effect: "ask", auth: "session", reversible: false,
@@ -9161,6 +10706,13 @@ export const RECEIVERS = {
9161
10706
  response: () => z.unknown(),
9162
10707
  effect: "ask", auth: "owner", reversible: false,
9163
10708
  }),
10709
+ "movers:funnel-event": receiver({
10710
+ receiver: "movers:funnel-event",
10711
+ summary: "Records a preview-only movers-funnel edge (previewed, tried, owner) for the workspace behind a preview token",
10712
+ request: () => z.object({ token: z.string(), event: z.enum(["previewed", "tried", "owner"]) }).passthrough(),
10713
+ response: () => z.unknown(),
10714
+ effect: "ask", auth: "public", reversible: false,
10715
+ }),
9164
10716
  "movers:funnel-claim": receiver({
9165
10717
  receiver: "movers:funnel-claim",
9166
10718
  summary: "Claims a sponsored preview workspace for the signed-in user, binding them as owner",
@@ -9184,24 +10736,26 @@ export const RECEIVERS = {
9184
10736
  }),
9185
10737
  "payout:set": receiver({
9186
10738
  receiver: "payout:set",
9187
- summary: "Set a merchant's crypto payout treasury addresses (sui/evm) after workspace ownership check and human presence confirmation",
9188
- request: () => z.object({ confirm: z.unknown().optional(), treasury_evm: z.unknown().optional(), treasury_sui: z.unknown().optional(), workspace: z.unknown().optional() }).passthrough(),
10739
+ summary: "Set a merchant's crypto payout treasury addresses (sui/evm) and its custody switch (off | on) after workspace ownership check and human presence confirmation",
10740
+ request: () => z.object({ confirm: z.unknown().optional(), custody: z.unknown().optional(), treasury_evm: z.unknown().optional(), treasury_sui: z.unknown().optional(), workspace: z.unknown().optional(), ...WORK_CONTRACT_FIELDS }).passthrough(),
9189
10741
  response: () => z.unknown(),
9190
- effect: "ask", auth: "owner", reversible: false,
10742
+ effect: "ask", auth: "owner", reversible: false, moves: "value", movesIn: ["workspace"],
9191
10743
  }),
9192
10744
  "plugins:buy-with-credits": receiver({
9193
10745
  receiver: "plugins:buy-with-credits",
9194
10746
  summary: "Buy a plugin using workspace credits, granting entitlement synchronously",
9195
- request: () => z.object({ name: z.unknown().optional() }).passthrough(),
10747
+ request: () => z.object({ name: z.unknown().optional(), ...WORK_CONTRACT_FIELDS }).passthrough(),
9196
10748
  response: () => z.unknown(),
9197
- effect: "ask", auth: "member", reversible: false,
10749
+ effect: "ask", auth: "member", reversible: false, moves: "value",
9198
10750
  }),
9199
10751
  "plugins:buy-with-one-token": receiver({
9200
10752
  receiver: "plugins:buy-with-one-token",
9201
10753
  summary: "Buys a plugin by verifying a Sui ONE token transfer and granting entitlement with no credit mint",
9202
- request: () => z.object({ name: z.unknown().optional(), tx: z.unknown().optional(), txDigest: z.unknown().optional() }).passthrough(),
10754
+ request: () => z.object({ name: z.unknown().optional(), tx: z.unknown().optional(), txDigest: z.unknown().optional(), ...WORK_CONTRACT_FIELDS }).passthrough(),
9203
10755
  response: () => z.unknown(),
9204
- effect: "ask", auth: "member", reversible: false,
10756
+ // Settles at the call: verifies the token transfer and writes the entitlement — the
10757
+ // same class as wallet:send (a settlement recorded for value that changed hands).
10758
+ effect: "ask", auth: "member", reversible: false, moves: "value",
9205
10759
  }),
9206
10760
  "plugins:credit-balance": receiver({
9207
10761
  receiver: "plugins:credit-balance",
@@ -9259,6 +10813,183 @@ export const RECEIVERS = {
9259
10813
  response: () => z.unknown(),
9260
10814
  effect: "ask", auth: "update_group", reversible: false,
9261
10815
  }),
10816
+ // ── secrets:* — the opener (text/secrets.md deliverable 7; text/secrets-plan.md § Signals).
10817
+ // A key given to ONE is used for a caller who never holds it: `secrets/` is a worker of
10818
+ // its own, reached over the `OPENER` service binding. call + used land here with C6's
10819
+ // resolver (one.ie/web/src/lib/resolvers/secrets.ts), `secrets:give` with C8's, `secrets:grant` +
10820
+ // `secrets:revoke` with C12's, `secrets:list` with C15's (Interface Contract #2). There is NO `secrets:refused`: a
10821
+ // refusal is `secrets:used` with `refused` set, closed with a warn.
10822
+ "secrets:call": receiver({
10823
+ receiver: "secrets:call",
10824
+ summary: "Use a key somebody lent you, without ever holding it. The opener finds your grant, checks its signature against the vault's grant-signers, counts the call BEFORE it is made, opens the key in memory, sends ONE request to the provider's fixed host and header on an allow-listed path (no redirect followed), scrubs the key from the answer and drops it. The caller is the session or attested agent — a body field never names it.",
10825
+ request: () => z.object({
10826
+ provider: z.enum(PROVIDER_NAMES).describe("A row of secrets/src/providers.ts — the one host and header a key may be sent to. Anything else refuses unknown_provider."),
10827
+ secret: z.string().optional().describe("`<vault>/<NAME>` of one lent secret, when you hold grants on several keys for this provider. Omitted: the first grant to you for this provider."),
10828
+ request: z.object({
10829
+ method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]),
10830
+ path: z.string().describe("The provider path, e.g. `/v1/chat/completions`. Every provider row is an allow-catalogue (plan D17): the method AND the decoded, normalised path must match one entry exactly, and every query key must be one that entry names — else path_not_allowed. The grant's for.paths names entries (ids or exact templates) and can never add one; absent, the row's default set."),
10831
+ body: z.unknown().optional().describe("Sent as JSON (a string is sent as-is). Ignored on GET. When the grant carries for.models, a model-taking entry needs a JSON body in which EVERY field named `model`, at any depth, is on that list."),
10832
+ }),
10833
+ }),
10834
+ response: () => z.object({
10835
+ ok: z.boolean(),
10836
+ status: z.number().optional().describe("The provider's status; 0 when the request failed or timed out — still counted (plan D6)."),
10837
+ body: z.unknown().optional().describe("The provider's answer, JSON when it was JSON, with the key's value and its last 12 characters scrubbed. Headers are never returned."),
10838
+ used: z.object({ secret: z.string(), grant: z.string(), today: z.number(), perDay: z.number() }).optional().describe("The meter after this call — the owner's desk shows the same numbers."),
10839
+ refused: z.enum(REFUSALS).optional().describe("The closed set of @oneie/sdk/secrets REFUSALS. bad_key: the sealed value cannot be sent as-is (counted, nothing sent)."),
10840
+ detail: z.string().optional().describe("The numbers behind a refusal (`49/50`), the expiry, or the check that bit."),
10841
+ error: z.string().optional().describe("unauthorized · not_in_workflow (a workflow step inherits the runner's session and never spends a lent grant) · opener_unbound · opener_unreachable — the web side refused before the opener, or could not reach it."),
10842
+ }),
10843
+ effect: "ask", auth: "authenticated", cost: "variable", reversible: false, idempotent: false,
10844
+ examples: [{ provider: "openai", request: { method: "POST", path: "/v1/chat/completions", body: { model: "gpt-4o-mini", messages: [{ role: "user", content: "hi" }] } } }],
10845
+ }),
10846
+ "secrets:used": receiver({
10847
+ receiver: "secrets:used",
10848
+ summary: "Close the loop on one use of a lent key: `mark` on the path `actor → provider:<name>`, or `warn` on it when `refused` is set. Written by whoever made the call (the web resolver, channels) — the opener keeps the meter and writes no signal (plan D9).",
10849
+ request: () => z.object({
10850
+ provider: z.enum(PROVIDER_NAMES).describe("The provider row the call went to — the same closed set secrets:call takes; a path `actor → provider:<name>` is only ever written for a real row."),
10851
+ secret: z.string().optional().describe("`<vault>/<NAME>` that was used."),
10852
+ grant: z.string().optional().describe("The grant id the call ran on."),
10853
+ today: z.number().optional().describe("Calls on that grant today, after this one."),
10854
+ perDay: z.number().optional(),
10855
+ refused: z.enum(USED_REFUSALS).optional().describe("Set when the call was refused — the loop closes with a warn instead of a mark. The opener's REFUSALS, then the web side's own: not_in_workflow · opener_unbound · opener_unreachable · vault_not_yours."),
10856
+ }),
10857
+ response: () => z.object({ ok: z.boolean(), closed: z.enum(["mark", "warn"]).optional(), actor: z.string().optional(), provider: z.string().optional(), error: z.string().optional() }),
10858
+ effect: "signal", auth: "authenticated", cost: "free", reversible: false, idempotent: false,
10859
+ examples: [{ provider: "openai", secret: "0xv/OPENAI", grant: "g1", today: 12, perDay: 500 }],
10860
+ }),
10861
+ "secrets:give": receiver({
10862
+ receiver: "secrets:give",
10863
+ summary: "Give a key to ONE. The value arrives sealed on the giver's side to ONE's lock alone (read from ONE's vault, never a constant) and signed by a key on the vault's grant-signers; the opener checks the signature, opens the key in memory, refuses a signed subject that is not the attested caller and a sealed plaintext that does not name this give's vault, name and provider, makes ONE cheap Check it call to the provider row's check entry, flags a key that can make other keys (or whose scopes cannot be read), and stores the sealed key keyed `<vault>/<name>` — by compare-and-set on the record it replaces — with the row's host, header and entries as they are now. Afterwards only the last four characters show. The giver is the session or attested agent — a body field never names it. Closes with a mark on `actor → provider:<name>`, a warn on any refusal.",
10864
+ request: () => z.object({
10865
+ signer: z.object({
10866
+ kind: z.enum(["person", "agent"]).describe("agent: its own ed25519 Sui key (the CLI's --signer-key, the SDK's giveData). person: a passkey touch made on the seal page (C9) — the master-derived key never signs."),
10867
+ sig: z.string().describe("The signature over the payload's canonical bytes (keys sorted, @oneie/sdk/secrets) — a Sui personal-message signature (agent) or the WebAuthn assertion JSON (person)."),
10868
+ signer: z.string().describe("Who signed: the agent's Sui address, or `p256:<point>` for a passkey. It must be on payload.vault's grant-signers, read from the chain."),
10869
+ }),
10870
+ payload: z.object({
10871
+ type: z.literal("give"),
10872
+ vault: z.string().describe("The giver's Sui vault, `0x` + 64 lower-case hex. Its grant-signers decide who may give; the key is stored as `<vault>/<name>` and nobody listed on another vault can change it."),
10873
+ body: z.object({
10874
+ name: z.string().describe("The .env name, e.g. OPENAI_API_KEY — letters, digits and `_`."),
10875
+ provider: z.enum(PROVIDER_NAMES).describe("A row of secrets/src/providers.ts; anything else refuses unknown_provider before the chain is read."),
10876
+ sealed: z.string().describe("Sealed to ONE's lock and no other reader (`age:<base64>`, the @oneie/sdk/secrets-give sealForOne form) over the canonical plaintext `{\"name\",\"provider\",\"v\":1,\"value\",\"vault\"}` naming this give's vault, name and provider — any other is seal_mismatch. Never the value."),
10877
+ mode: z.enum(["give", "check"]).describe("check: verify, open and Check it, answer, and store nothing."),
10878
+ allowFlagged: z.boolean().optional().describe("Signed with the rest: store a key Check it flagged — admin_key · full_secret_key · admin_scope · key_scope (a key that can make other keys or reach admin), or scopes_unknown (a GitHub token whose scopes cannot be read)."),
10879
+ replaces: z.string().regex(/^[0-9a-f]{64}$/).nullable().describe("Signed with the rest: the sigHash of the record this give replaces (`given.sigHash` of the last give, or a stale refusal's detail), null for a first give. Anything else refuses stale — a captured give re-sent after a rotate never rolls it back."),
10880
+ subject: z.object({ kind: z.literal("actor"), id: z.string() }).describe("Signed with the rest: the giver's own actor — the caller this request is attested as (session, world key or attested agent). Any other refuses subject_mismatch, so a captured give resent under another session is never theirs."),
10881
+ }),
10882
+ }),
10883
+ group: z.string().optional().describe("C13: give the key to a group — a bare slug (one `group:` prefix is accepted as a spelling). Only a caller the group's roles allow (owner or admin, mayGiveForGroup, D26) may; anyone else is refused `not_allowed` and the opener is never called. The key is recorded under the group, on its members' walk, and payload.vault must be the group treasury's vault."),
10884
+ }),
10885
+ response: () => z.object({
10886
+ ok: z.boolean(),
10887
+ stored: z.boolean().optional().describe("false on mode check — nothing was written."),
10888
+ given: z.object({ vault: z.string(), name: z.string(), provider: z.string(), last4: z.string(), flagged: z.string().nullable(), check: z.object({ ok: z.boolean(), status: z.number() }), sigHash: z.string() }).optional().describe("What ONE kept: the last four characters (empty for a value shorter than 12), the flag word if any, Check it's status, and the give's sigHash — what a rotate signs as `replaces`."),
10889
+ refused: z.string().optional().describe("The opener's refusal: malformed · unknown_provider · bad_signature · cannot_verify · subject_mismatch · busy (10 gives a minute per caller, then per vault) · stale · not_sealed_to_one · seal_mismatch · bad_key · check_failed · flagged."),
10890
+ detail: z.string().optional().describe("The check that bit — never the value or its length. On stale: the sigHash of the record ONE holds (`none` when there is none)."),
10891
+ error: z.string().optional().describe("The web side: unauthorized · not_in_workflow (a workflow step never gives a key in the runner's name) · bad_request · not_allowed (group set and the caller does not control that group) · vault_not_yours (payload.vault is not the subject's own vault — the session actor's, or with group the group treasury's) · opener_unbound · opener_unreachable."),
10892
+ }),
10893
+ effect: "ask", auth: "authenticated", cost: "free", reversible: false, idempotent: false,
10894
+ examples: [{ signer: { kind: "agent", sig: "<base64>", signer: "0x…" }, payload: { type: "give", vault: "0x…", body: { name: "OPENAI_API_KEY", provider: "openai", sealed: "age:…", mode: "give", replaces: null, subject: { kind: "actor", id: "<your actor id>" } } } }],
10895
+ }),
10896
+ "secrets:list": receiver({
10897
+ receiver: "secrets:list",
10898
+ // text/secrets.md § What an agent sees: "through the SDK or MCP: names, never values".
10899
+ surfaces: { mcp: true },
10900
+ summary: "Your secrets desk — names and meters, never values. Each key you gave (yours, and each group's you may manage): its name, provider, last four characters, sigHash (what a Rotate signs as `replaces`), who uses it through which grant (grantee, which calls, a day's ceiling, until when, today's count from the opener's own meter, stopped or not) and the opener's own call log (who, which entry, counted or over the limit — never a path, body or header; a call is on it whether or not the caller ever sent secrets:used). Keys lent to you (never the lender's last four or vault), the Composio groups running without a grant, each vault's whole grant-signer list with the proposals waiting beside it, its history, a pending reset and the alerts. A cut answer says capped and names what was cut. Everything about WHO comes from the session or attested caller and D1 — never from the body.",
10901
+ request: () => z.object({}).describe("Nothing: the caller, its group chain, its owner and the groups it may manage are read from the session and D1. Any field sent is ignored."),
10902
+ response: () => z.object({
10903
+ ok: z.boolean(),
10904
+ keys: z.array(z.unknown()).optional().describe("Per key: vault, name, provider, last4, flagged, subject, sigHash, givenAt, grants[{ id, ref, to, for, perDay, until, today, stopped }], calls[{ at, grant, actor, entry, outcome }] (newest first, ≤50)."),
10905
+ lentToMe: z.array(z.unknown()).optional().describe("Per lend: ref, name, provider, from (who lends it), to (with the agents it covers), left_today, until, perDay, for, accepted, family, stopped."),
10906
+ composio: z.array(z.unknown()).optional().describe("Per group you manage: requireGrants ({ vault, on } or null), noGrantToday, noGrantCalls."),
10907
+ vaults: z.array(z.unknown()).optional().describe("Per key vault: grantSigners (the opener's chain cache), state fresh · held · unavailable, and from the chain's events (display only): history, pending, pendingReset, alerts."),
10908
+ ownVault: z.object({ vault: z.string(), anchored: z.boolean() }).nullable().optional().describe("The signed-in person's own vault: born by them, anchored once one of their registered passkeys accepted itself onto its grant-signer list — the only vault the seal frame gives into."),
10909
+ capped: z.boolean().optional().describe("true when something was cut (more than 200 keys or grants, more than 50 calls in a log); `cut` names each."),
10910
+ cut: z.array(z.string()).optional(),
10911
+ refused: z.string().optional().describe("The opener's: malformed."),
10912
+ error: z.string().optional().describe("The web side: unauthorized · not_in_workflow (a workflow step never reads the runner's desk) · opener_unbound (the opener is not live yet — nothing was read) · opener_unreachable."),
10913
+ }),
10914
+ effect: "ask", auth: "authenticated", cost: "free", reversible: true, idempotent: true,
10915
+ examples: [{}],
10916
+ }),
10917
+ "secrets:grant": receiver({
10918
+ receiver: "secrets:grant",
10919
+ summary: "Lend a key you gave to ONE, or accept one lent to you. LEND: a signed grant — who may use the key (a person, an agent, or a group), which calls (catalogue entries of the provider row), how many a day, until when — checked against the grant-signers of the vault the key was given under (never the vault the document names), and stored only once its signature verifies (an id is never reused on a vault). The borrower gets a card linking one.ie/secrets?lent=<ref>; their calls run on the key once they accept, and they never see it. ACCEPT: `accept` names the grant's ref; `confirm: false` shows it in words and writes nothing, `confirm: true` records the acceptance. Only a person's own session accepts — for themselves, or with `group` / `agent` for a group or an agent they control — never an agent, and never from a body field. Closes with a mark on `actor → provider:<name>`, a warn on a refusal once the provider is known.",
10920
+ request: () => z.object({
10921
+ signer: z.object({
10922
+ kind: z.enum(["person", "agent"]).describe("person: a passkey touch on the seal page, in a window of its own (a framed grant is refused). agent: its own ed25519 Sui key (the SDK's grantData)."),
10923
+ sig: z.string().describe("The signature over the payload's canonical bytes (keys sorted, @oneie/sdk/secrets)."),
10924
+ signer: z.string().describe("Who signed: `p256:<point>` for a passkey, the agent's Sui address. It must be on the key's vault's grant-signers, read from the chain."),
10925
+ }).optional().describe("LEND form only."),
10926
+ payload: z.object({
10927
+ type: z.literal("grant"),
10928
+ vault: z.string().describe("The vault the key was given under, `0x` + 64 lower-case hex — the same as body.vault."),
10929
+ body: z.object({
10930
+ id: z.string().describe("8–64 of [A-Za-z0-9_-]; mint 16 random bytes as hex (grantData does). Never reused on a vault: a second grant naming a seen id is refused id_used, so a Stop is permanent."),
10931
+ secret: z.string().describe("`<vault>/<NAME>` — the key as it was given. A secret never given is refused no_key before anything reaches the chain."),
10932
+ vault: z.string(),
10933
+ to: z.object({
10934
+ kind: z.enum(["actor", "group"]),
10935
+ id: z.string().describe("An actor id, or a group's bare slug (never `group:`-prefixed)."),
10936
+ agents: z.array(z.string()).optional().describe("Only on a grant to a person: the agents of theirs it also covers. A grant to a person covers their agents only when it names them."),
10937
+ }),
10938
+ for: z.object({
10939
+ paths: z.array(z.string()).optional().describe("Catalogue entry ids of the key's provider row, bare or `<id>@/concrete/path` (one repo, one issue). Absent: the row's default reads. []: nothing. Any other item refuses bad_template."),
10940
+ models: z.array(z.string()).optional(),
10941
+ tools: z.array(z.string()).optional().describe("Composio tool slugs — only on a key whose stored provider is composio, never a COMPOSIO_ meta-tool."),
10942
+ }),
10943
+ perDay: z.number().int().min(1).describe("Calls a day, counted before each call."),
10944
+ until: z.string().describe("ISO-8601 UTC ending Z, in the future. No upper cap: the provider's own budget is the honest one."),
10945
+ }),
10946
+ }).optional().describe("LEND form only."),
10947
+ accept: z.string().regex(/^[0-9a-f]{64}$/).optional().describe("ACCEPT form: the grant's ref (from the card's link)."),
10948
+ confirm: z.boolean().optional().describe("ACCEPT form: false shows the grant in words and writes nothing; true records the acceptance (once)."),
10949
+ group: z.string().optional().describe("ACCEPT form: accept for a group you control (owner or admin)."),
10950
+ agent: z.string().optional().describe("ACCEPT form: accept for an agent whose home group you control. An agent never accepts for itself."),
10951
+ }),
10952
+ response: () => z.object({
10953
+ ok: z.boolean(),
10954
+ grant: z.object({ ref: z.string(), id: z.string(), secret: z.string(), provider: z.string(), to: z.unknown(), perDay: z.number(), until: z.string() }).optional().describe("LEND: what was stored. `ref` is sha256 of the signed bytes — the card links it."),
10955
+ existing: z.boolean().optional().describe("The identical grant (or acceptance) was already there — nothing new was written and no second card sent."),
10956
+ accepted: z.boolean().optional(),
10957
+ offer: z.object({ ref: z.string(), provider: z.string(), name: z.string(), perDay: z.number(), until: z.string(), to: z.unknown(), paths: z.array(z.string()).optional(), models: z.array(z.string()).optional(), tools: z.array(z.string()).optional(), from: z.string().nullable() }).optional().describe("ACCEPT with confirm false: the grant in words — never the key, the sealed blob or a signature."),
10958
+ provider: z.string().optional(),
10959
+ refused: z.string().optional().describe("The opener's: malformed · expired · no_key · bad_template · bad_signature · cannot_verify · busy · id_used · no_grant · not_addressee."),
10960
+ detail: z.string().optional(),
10961
+ error: z.string().optional().describe("The web side: unauthorized · not_in_workflow · not_allowed (an accept not made by a person's own session, or for a group or agent the caller does not control) · bad_request · opener_unbound · opener_unreachable."),
10962
+ }),
10963
+ effect: "ask", auth: "authenticated", cost: "free", reversible: false, idempotent: true,
10964
+ examples: [{ accept: "<64 hex ref from the card>", confirm: false }],
10965
+ }),
10966
+ "secrets:revoke": receiver({
10967
+ receiver: "secrets:revoke",
10968
+ summary: "Stop a grant for good. The owner's signed Stop — checked against the grant-signers of the vault the lent key was given under — is stored once and never rewritten; the next call on that grant is refused `stopped`, and its meter does not move again. There is no un-stop: grant ids are never reused on a vault. Closes with a mark on `actor → provider:<name>`.",
10969
+ request: () => z.object({
10970
+ signer: z.object({
10971
+ kind: z.enum(["person", "agent"]).describe("person: a passkey touch on the seal page, in its own window. agent: its own ed25519 key (the SDK's stopData)."),
10972
+ sig: z.string(),
10973
+ signer: z.string().describe("`p256:<point>` for a passkey, the agent's Sui address — on the vault's grant-signers."),
10974
+ }),
10975
+ payload: z.object({
10976
+ type: z.literal("stop"),
10977
+ vault: z.string().describe("The vault the grant was signed on."),
10978
+ body: z.object({ grantId: z.string().describe("The grant's id on that vault."), at: z.string().describe("ISO-8601 UTC ending Z.") }),
10979
+ }),
10980
+ }),
10981
+ response: () => z.object({
10982
+ ok: z.boolean(),
10983
+ stopped: z.object({ grantId: z.string(), vault: z.string(), at: z.string(), ref: z.string() }).optional(),
10984
+ existing: z.boolean().optional().describe("This Stop was already stored — nothing rewritten."),
10985
+ provider: z.string().optional(),
10986
+ refused: z.string().optional().describe("malformed · no_grant (a grant never made: nothing stored, no chain read) · bad_signature · cannot_verify."),
10987
+ detail: z.string().optional(),
10988
+ error: z.string().optional().describe("unauthorized · not_in_workflow · bad_request · opener_unbound · opener_unreachable."),
10989
+ }),
10990
+ effect: "ask", auth: "authenticated", cost: "free", reversible: false, idempotent: true,
10991
+ examples: [{ signer: { kind: "agent", sig: "<base64>", signer: "0x…" }, payload: { type: "stop", vault: "0x…", body: { grantId: "<id>", at: "2026-10-27T12:00:00Z" } } }],
10992
+ }),
9262
10993
  "ssr:calibrate": receiver({
9263
10994
  receiver: "ssr:calibrate",
9264
10995
  summary: "Compare strategy PMFs against a human fixture, mark/warn paths, write hypothesis if KS-sim >= 0.85. FINDING: falls back to data.slug when the caller is unattested",