@oneie/sdk 0.17.5 → 0.17.7

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 (74) hide show
  1. package/dist/billing.d.ts +244 -14
  2. package/dist/billing.d.ts.map +1 -1
  3. package/dist/billing.js +374 -55
  4. package/dist/billing.js.map +1 -1
  5. package/dist/broadcast.d.ts +1 -1
  6. package/dist/broadcast.d.ts.map +1 -1
  7. package/dist/client.d.ts +2 -2
  8. package/dist/client.d.ts.map +1 -1
  9. package/dist/client.js +8 -1
  10. package/dist/client.js.map +1 -1
  11. package/dist/evm-tx.d.ts +24 -0
  12. package/dist/evm-tx.d.ts.map +1 -0
  13. package/dist/evm-tx.js +128 -0
  14. package/dist/evm-tx.js.map +1 -0
  15. package/dist/generated/fn-map.d.ts +2 -2
  16. package/dist/generated/fn-map.d.ts.map +1 -1
  17. package/dist/generated/fn-map.js +32 -2
  18. package/dist/generated/fn-map.js.map +1 -1
  19. package/dist/generated/schemas/index.d.ts +2 -2
  20. package/dist/generated/schemas.d.ts +10 -10
  21. package/dist/index.d.ts +2 -2
  22. package/dist/index.d.ts.map +1 -1
  23. package/dist/index.js +1 -1
  24. package/dist/index.js.map +1 -1
  25. package/dist/meta.d.ts +13 -0
  26. package/dist/meta.d.ts.map +1 -1
  27. package/dist/meta.js +11 -0
  28. package/dist/meta.js.map +1 -1
  29. package/dist/prices/vendors.d.ts +7 -0
  30. package/dist/prices/vendors.d.ts.map +1 -0
  31. package/dist/prices/vendors.js +229 -0
  32. package/dist/prices/vendors.js.map +1 -0
  33. package/dist/prices.d.ts +41 -0
  34. package/dist/prices.d.ts.map +1 -0
  35. package/dist/prices.js +79 -0
  36. package/dist/prices.js.map +1 -0
  37. package/dist/proof-bar.d.ts +228 -0
  38. package/dist/proof-bar.d.ts.map +1 -0
  39. package/dist/proof-bar.js +252 -0
  40. package/dist/proof-bar.js.map +1 -0
  41. package/dist/receiver-layers.d.ts +52 -0
  42. package/dist/receiver-layers.d.ts.map +1 -1
  43. package/dist/receiver-layers.js +118 -5
  44. package/dist/receiver-layers.js.map +1 -1
  45. package/dist/receivers.d.ts +1311 -90
  46. package/dist/receivers.d.ts.map +1 -1
  47. package/dist/receivers.js +1568 -153
  48. package/dist/receivers.js.map +1 -1
  49. package/dist/secrets-give.d.ts +1 -1
  50. package/dist/secrets-give.d.ts.map +1 -1
  51. package/dist/secrets-give.js +1 -1
  52. package/dist/secrets-give.js.map +1 -1
  53. package/dist/secrets-list.d.ts +169 -0
  54. package/dist/secrets-list.d.ts.map +1 -0
  55. package/dist/secrets-list.js +13 -0
  56. package/dist/secrets-list.js.map +1 -0
  57. package/dist/secrets-one-vault.d.ts +33 -1
  58. package/dist/secrets-one-vault.d.ts.map +1 -1
  59. package/dist/secrets-one-vault.js +42 -2
  60. package/dist/secrets-one-vault.js.map +1 -1
  61. package/dist/secrets.d.ts +9 -0
  62. package/dist/secrets.d.ts.map +1 -1
  63. package/dist/secrets.js +12 -0
  64. package/dist/secrets.js.map +1 -1
  65. package/dist/types.d.ts +4 -4
  66. package/dist/types.d.ts.map +1 -1
  67. package/dist/work-contract-grammar.json +64 -5
  68. package/dist/work-contract.d.ts +24 -0
  69. package/dist/work-contract.d.ts.map +1 -1
  70. package/dist/work-contract.js +60 -1
  71. package/dist/work-contract.js.map +1 -1
  72. package/package.json +14 -2
  73. package/src/generated/funs.json +1 -1
  74. package/dist/.build-fingerprint +0 -1
package/dist/receivers.js CHANGED
@@ -3,6 +3,47 @@ import { AgentActionResponseSchema, AgentStatusResponseSchema, CapabilityItemSch
3
3
  import { FieldSchema, ResourceTypeSchema } from "./types.js";
4
4
  import { GroupEntitySchema } from "./generated/schemas/index.js";
5
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.");
6
47
  /**
7
48
  * Declare a receiver contract. Identity at runtime — its only job is to pin the
8
49
  * `Req`/`Res` generics so the catalog infers payload + outcome types.
@@ -67,6 +108,22 @@ const CARD_STEP_RESPONSE = z.object({
67
108
  * receiver that pages, caps or reads a snapshot names its window in the response, every
68
109
  * time — and `reason` had three readers branching on it while the contract denied it.
69
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") });
70
127
  const QUEUE_READ_FIELDS = {
71
128
  total: z.number().optional().describe("Rows matching BEFORE `limit`. A FLOOR, not a count, whenever `truncatedTypes` is present"),
72
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`)"),
@@ -163,6 +220,8 @@ export const RECEIVERS = {
163
220
  agentId: z.string().describe("The agent's actor id — the exact string its on-chain SpendCeiling carries as agent_id"),
164
221
  objectId: z.string().describe("The SpendCeiling object id (0x + hex), already handed to the owner with transfer_ownership"),
165
222
  replace: z.boolean().optional().describe("Replace a ceiling already registered for this agent. Default false: a second registration is refused, not overwritten"),
223
+ challenge: z.string().optional().describe("Without a signed-in session: a fresh wallet:challenge the owner fetched with its own human-class key"),
224
+ proof: z.unknown().optional().describe("Without a signed-in session: the owner's Sui signature (signAddressProof) over that challenge, by the address the ceiling is owned by — `one wallet ceiling register --dir <owner vault>` makes it behind Touch ID"),
166
225
  }),
167
226
  response: () => z.object({
168
227
  ok: z.boolean(),
@@ -171,7 +230,7 @@ export const RECEIVERS = {
171
230
  owner: z.string().optional().describe("The owner's address pay verified as the ceiling's live on-chain owner"),
172
231
  status: z.string().optional().describe("pay's registry outcome: created | unchanged | replaced"),
173
232
  enabled: z.boolean().optional().describe("false until the owner re-sets the bounds with update_ceiling — transfer_ownership disables a ceiling, and escrow answers CEILING_DISABLED until then"),
174
- error: z.string().optional().describe("A refusal by name: human_session_required | not_owner | unclaimed | agent_owns_itself | no_owner_address | read_failed | pay_unconfigured | pay_unreachable | ceiling_not_owned_by_human | ceiling_bounds_another_agent | not_a_spend_ceiling | ceiling_already_registered | ceiling_not_found | pay_unavailable | pay_refused"),
233
+ error: z.string().optional().describe("A refusal by name: human_session_required | owner_signature_required | not_owner | unclaimed | agent_owns_itself | no_owner_address | read_failed | pay_unconfigured | pay_unreachable | ceiling_not_owned_by_human | ceiling_bounds_another_agent | not_a_spend_ceiling | ceiling_already_registered | ceiling_not_found | pay_unavailable | pay_refused"),
175
234
  stage: z.string().optional().describe("On a pay refusal, which call refused: agent (the pay record) | register"),
176
235
  payCode: z.string().nullable().optional().describe("pay's own error code, verbatim, beside the named refusal"),
177
236
  closed: z.string().optional().describe("mark on a registration, warn on every refusal"),
@@ -179,25 +238,51 @@ export const RECEIVERS = {
179
238
  effect: "ask", cost: "free", reversible: false, idempotent: true, settles: "none", auth: "manage_workspace",
180
239
  examples: [{ agentId: "acme--research-agent", objectId: "0x5f3a" }],
181
240
  }),
182
- "agent:provision": receiver({
183
- receiver: "agent:provision",
184
- canonical: "agent:enroll",
185
- summary: "Zero-to-live in one unauthenticated call — register + workspace + publish agent + import skills + invite owner",
241
+ // ── agents:approve / agents:update — the attested grant store the work-contract gate reads ──
242
+ // A bare key (agent- or human-typed, no browser session) that calls a receiver
243
+ // declared `moves: "value"` must carry a contract naming `signal:<receiver>`, and
244
+ // that capability is held ONLY through a `work_contract_grants` row (migration
245
+ // 0370) keyed (workspace, actor, capability). This is the door that writes the
246
+ // row: a person's own session, controlling the workspace, never a bare key
247
+ // (requireHumanPresence) and never a workflow step. The gate reads the row
248
+ // (one.ie/web lib/contract-grants.ts) and refuses `grant_required` without it.
249
+ "agents:approve": receiver({
250
+ receiver: "agents:approve",
251
+ 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",
186
252
  request: () => z.object({
187
- name: z.string().optional(),
188
- agentName: z.string().optional(),
189
- content: z.string().optional(),
190
- skills: z.array(z.string()).optional(),
191
- invite: z.object({ email: z.string().email().optional(), role: z.string().optional() }).optional(),
192
- live: z.boolean().optional(),
253
+ 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"),
254
+ 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"),
255
+ 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"),
193
256
  }),
194
257
  response: () => z.object({
195
- uid: z.string(),
196
- workspace: z.string(),
197
- apiKey: z.string(),
198
- inviteUrl: z.string().optional(),
258
+ ok: z.boolean(),
259
+ workspace: z.string().optional(),
260
+ actor: z.string().optional(),
261
+ capability: z.string().optional(),
262
+ grantedBy: z.string().optional().describe("The session's attested slug that wrote the row"),
263
+ 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"),
199
264
  }),
200
- effect: "ask", auth: "none", reversible: false, idempotent: false,
265
+ effect: "ask", auth: "manage_workspace", cost: "free", reversible: true, idempotent: true,
266
+ examples: [{ actor: "01a1b2b393c785de0503803b", capability: "signal:market:escrow" }],
267
+ }),
268
+ "agents:update": receiver({
269
+ receiver: "agents:update",
270
+ 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",
271
+ request: () => z.object({
272
+ actor: z.string().min(1).max(128).describe("The key's actor id the grant names"),
273
+ capability: z.string().min(1).max(128).describe("The capability to revoke, exactly as granted"),
274
+ status: z.literal("revoked").describe("The only status this door writes — a grant is re-armed by agents:approve, never here"),
275
+ workspace: z.string().optional().describe("The workspace the grant is scoped to; defaults to the caller's own. The caller must control it"),
276
+ }),
277
+ response: () => z.object({
278
+ ok: z.boolean(),
279
+ revoked: z.boolean().optional().describe("false when no live row matched — already revoked or never granted"),
280
+ workspace: z.string().optional(),
281
+ actor: z.string().optional(),
282
+ capability: z.string().optional(),
283
+ error: z.string().optional().describe("unauthorized | approval_required | not_in_workflow | forbidden | no_db"),
284
+ }),
285
+ effect: "ask", auth: "manage_workspace", cost: "free", reversible: true, idempotent: true,
201
286
  }),
202
287
  "agent:bootstrap": receiver({
203
288
  receiver: "agent:bootstrap",
@@ -220,6 +305,8 @@ export const RECEIVERS = {
220
305
  }),
221
306
  "auth:agent": receiver({
222
307
  receiver: "auth:agent",
308
+ // 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.
309
+ auth: "public",
223
310
  canonical: "agent:enroll",
224
311
  // `wallet` is a PUBLIC receiving address the caller derived in its own process.
225
312
  // Nothing here generates keys. The address is stored on the TypeDB actor but NOT
@@ -237,6 +324,8 @@ export const RECEIVERS = {
237
324
  }),
238
325
  "agents:sync": receiver({
239
326
  receiver: "agents:sync",
327
+ // 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.
328
+ auth: "member",
240
329
  surfaces: { mcp: { name: "sync_agent" } },
241
330
  summary: "Declare capability — sync agent definitions, skills, and memberships",
242
331
  // Accepts a single markdown body or a structured multi-agent world payload.
@@ -305,6 +394,8 @@ export const RECEIVERS = {
305
394
  }),
306
395
  "world:accept-client-invite": receiver({
307
396
  receiver: "world:accept-client-invite",
397
+ // 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).
398
+ auth: "public",
308
399
  summary: "Redeem a client invite — creates the workspace owned by the invitee (single-use, replay-protected)",
309
400
  request: () => z.object({ token: z.string(), email: z.string().email().optional(), name: z.string().optional() }),
310
401
  response: () => z.object({ wsid: z.string(), slug: z.string(), owner: z.string(), parent: z.string() }),
@@ -520,7 +611,10 @@ export const RECEIVERS = {
520
611
  "visitor:promote": receiver({
521
612
  receiver: "visitor:promote",
522
613
  summary: "Promote a tracked anonymous visitor to a TypeDB actor (anon:<hash12>) so it surfaces in People; binds rung-1 visitor_hash→aid. Idempotent.",
523
- request: () => z.object({ visitorHash: z.string() }),
614
+ request: () => z.object({
615
+ visitorHash: z.string(),
616
+ 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."),
617
+ }),
524
618
  response: () => z.object({
525
619
  ok: z.boolean(),
526
620
  aid: z.string().optional(),
@@ -556,6 +650,11 @@ export const RECEIVERS = {
556
650
  // workspace is a nominated value, so a visitorHash binds only behind this;
557
651
  // undeclared, the edge would strip it and no chat browser would ever bind.
558
652
  visitorAttest: z.string().optional(),
653
+ // The web thread a chat turn is stored in (one.ie/web /api/chat → channels
654
+ // /message → here). A first turn's `group` is a derived key naming no thread,
655
+ // so this is how an attested stranger's conversation is attached to their lead.
656
+ // Linked only when the thread belongs to the workspace web attested.
657
+ thread: z.string().optional(),
559
658
  freeText: z.string().optional(),
560
659
  source: z.enum(["door", "chat", "asked", "event"]),
561
660
  }),
@@ -1140,12 +1239,12 @@ export const RECEIVERS = {
1140
1239
  totalTokens: z.number().optional(),
1141
1240
  totalCost: z.number().optional().describe("Inference cost in USD — SUM(credit_burns.cost_credits) × USD_PER_CREDIT (1 credit = $0.001)"),
1142
1241
  costPerResolution: z.number().optional().describe("totalCost / journey-complete events; 0 when there were none"),
1143
- revenue: z.number().optional(),
1144
- ltv: z.number().optional(),
1242
+ revenue: z.number().optional().describe("Real cash in, USD, through the books fence (finance/books-fence.ts readWorkspaceRevenue): live, paid, a cash rail, a payer not ours. For the platform workspace it is ONE's revenue; for any other, the workspace's own sales, never a credit top-up (that money is ONE's). If the read failed, 'revenue' is in pending"),
1243
+ ltv: z.number().optional().describe("revenue ÷ paying customers; paying customers are not counted in this rollup, so it is in pending"),
1145
1244
  tokensByAgent: z.array(z.object({ label: z.string(), tokens: z.number(), cost: z.number() })).optional().describe("By MODEL, ranked by cost, top 30"),
1146
1245
  tokensBySkill: z.array(z.object({ label: z.string(), tokens: z.number(), cost: z.number() })).optional(),
1147
1246
  attribution: z.array(z.unknown()).optional(),
1148
- pending: z.array(z.string()).optional().describe("THE FIELDS WHOSE ZERO IS NOT A MEASUREMENT — no signal carries a skill field and payment events do not reach this rollup yet, so tokensBySkill/revenue/attribution are empty by wiring, not by finding. Read revenue:0 as 'unbuilt', never as 'earned nothing'."),
1247
+ pending: z.array(z.string()).optional().describe("THE FIELDS WHOSE ZERO IS NOT A MEASUREMENT — no signal carries a skill field and payment events do not reach this rollup's attribution, so tokensBySkill, attribution and ltv are empty by wiring, not by finding. revenue is measured; it is listed here only when its read failed."),
1149
1248
  error: z.string().optional().describe("no_db | workspace required | forbidden"),
1150
1249
  }),
1151
1250
  effect: "ask",
@@ -1158,6 +1257,247 @@ export const RECEIVERS = {
1158
1257
  version: "1.0.0",
1159
1258
  examples: [{ workspace: "one" }],
1160
1259
  }),
1260
+ // ONE's own books (text/finance.md § Health), read through the books fence
1261
+ // (one.ie/web/src/lib/finance/books-fence.ts). Platform-only: there is no workspace
1262
+ // field, and the resolver admits staff or a caller that controls the platform
1263
+ // workspace (its root owner, an owner/admin of group one, or a key whose group is
1264
+ // 'one', agent keys included: the finance seats read the books, and a read moves
1265
+ // nothing). A child of 'one' and every other workspace are refused by name.
1266
+ "finance:get": receiver({
1267
+ receiver: "finance:get",
1268
+ summary: "ONE's own books, one view at a time. view 'health': ONE's health line, eight numbers read now: cash in, cost of goods, gross margin, unbilled model cost (over the window), cash on hand, credits owed, drift rows, paying customers (now). Each with its source, asOf and truncated; a number not read says why; a number past its line says the line in words. Platform owners only. view 'pnl': ONE's P&L by month, read through the books fence: cash in from outside customers, seller money shown apart, cost of goods from the provider's own figures, gross margin; Tony's open rulings as named lines that never enter a total. Platform owners only. Was finance:health and finance:pnl until 2026-11-19 (each an alias for one release that carries its view)",
1269
+ request: () => z.object({
1270
+ view: z.enum(["health", "pnl"]).describe("health = the eight-number health line now; pnl = the P&L by month"),
1271
+ days: z.number().int().optional().describe("view health: the window for the windowed numbers: 7, 30 or 90 days ending now. Absent (or any other value) = this calendar month"),
1272
+ months: z.number().int().optional().describe("view pnl: how many calendar months to read, ending with this one (UTC). Default 12, clamped to 1..24"),
1273
+ }),
1274
+ response: () => z.object({
1275
+ ok: z.boolean(),
1276
+ view: z.enum(["health", "pnl"]).optional().describe("The view this answer is"),
1277
+ asOf: z.string().optional().describe("When the books were read (ISO)"),
1278
+ window: z.object({ from: z.string(), to: z.string(), days: z.number().nullable(), label: z.string() }).optional().describe("view health: the window the windowed numbers read"),
1279
+ sentence: z.string().optional().describe("view health: the health line in one sentence, built from the numbers (the Finance tab header, `oneie finance`, the chat)"),
1280
+ numbers: z.array(z.object({
1281
+ key: z.string().describe("cash_in | cost_of_goods | gross_margin | unbilled_cost | cash_on_hand | credits_owed | drift_rows | paying_customers"),
1282
+ label: z.string(),
1283
+ short: z.string().optional(),
1284
+ windowed: z.boolean().optional(),
1285
+ figure: z.unknown().describe("A Figure: value, unit, source, asOf, truncated, status, note"),
1286
+ line: z.string().optional(),
1287
+ })).optional().describe("view health: the eight numbers"),
1288
+ from: z.string().optional().describe("view pnl"),
1289
+ to: z.string().optional().describe("view pnl"),
1290
+ months: z.array(z.unknown()).optional().describe("view pnl: one row per month: cashIn, sellerSales, platformFees, costOfGoods, grossMargin, each a Figure"),
1291
+ totals: z.unknown().optional().describe("view pnl: cashIn, costOfGoods, grossMargin over the window, as Figures"),
1292
+ open: z.unknown().optional().describe("view pnl: lines that wait on a ruling, counted:false"),
1293
+ error: z.string().optional().describe("unauthenticated | forbidden | no_db | bad_view"),
1294
+ }),
1295
+ effect: "ask",
1296
+ auth: "manage_workspace",
1297
+ roleAction: "read_revenue",
1298
+ cost: "free",
1299
+ idempotent: true,
1300
+ reversible: true,
1301
+ settles: "none",
1302
+ version: "1.0.0",
1303
+ examples: [{ view: "health" }, { view: "health", days: 30 }, { view: "pnl", months: 3 }],
1304
+ surfaces: { chat: true, mcp: true },
1305
+ }),
1306
+ // The on-ramp (text/onramp-plan.md § Receivers, C1): money IN from a person's bank to
1307
+ // THEIR OWN proven address, ONE never holding it. Sandbox only today: no provider key
1308
+ // exists, so every path that would reach one refuses `provider_not_configured`, and the
1309
+ // location gate ships closed (HK and TH hard-denied, everything else off until config
1310
+ // opens it, an unknown country refused). A signed-in PERSON only, as themselves: no
1311
+ // workspace field exists, and an API key (agent or human) is refused `person_only`.
1312
+ // ramp:landed is deliberately NOT here: it must never be reachable from the edge.
1313
+ "ramp:create": receiver({
1314
+ receiver: "ramp:create",
1315
+ summary: "Open an on-ramp for the caller, by kind. kind 'kyc': Begin, or reuse, the identity check an on-ramp needs, through VerifiedOnce (one.ie/web/src/lib/ramp/verify.ts): Bridge's hosted KYC link (door 1, Bridge re-verifies), or verify once with Sumsub and hand a one-use share token to a ramp that accepts it (Transak, Banxa, MoonPay), so the person is not asked twice. A signed-in person only; sandbox, closed by location. kind 'account': The caller's own bank details for a chain (a US account and routing number, or a euro IBAN) that pay out as USDC into the caller's PROVEN address for that chain, never a typed or payload address. Read back if already issued (last four only); issuing needs the provider (Bridge sandbox), refused by name until then. A signed-in person only; sandbox, closed by location. Was ramp:kyc and ramp:account until 2026-11-19 (each an alias for one release that carries its kind)",
1316
+ request: () => z.object({
1317
+ kind: z.enum(["kyc", "account"]).describe("kyc = begin or reuse the identity check; account = the caller's own bank details that pay out as USDC"),
1318
+ verifier: z.enum(["bridge-kyc-link", "sumsub-share"]).optional().describe("kind kyc: which VerifiedOnce implementation: bridge-kyc-link (default, door 1) or sumsub-share (verify once, share by token)"),
1319
+ recipient: z.enum(["transak", "banxa", "moonpay"]).optional().describe("kind kyc, sumsub-share only: the ramp the one-use share token is for (Transak and Banxa carry Sui USDC; MoonPay does not)"),
1320
+ chain: z.enum(["sui", "base", "solana"]).optional().describe("kind account: where the USDC lands; default sui. The address is the caller's proven one for this chain (base reads the EVM proof)"),
1321
+ rail: z.enum(["us_ach", "eu_sepa"]).optional().describe("kind account: which bank details; default us_ach"),
1322
+ }),
1323
+ response: () => z.object({
1324
+ ok: z.boolean(),
1325
+ step: z.unknown().optional().describe("kind kyc: {kind:'link', url} finish at the provider's page · {kind:'shared', recipient, expiresAt} · {kind:'verified'}"),
1326
+ account: z.object({
1327
+ rail: z.string(), last4: z.string().nullable(), chain: z.string(),
1328
+ destAddress: z.string().describe("The caller's proven address the USDC lands in"),
1329
+ state: z.string(), test: z.boolean().describe("true = sandbox; never live money"),
1330
+ }).optional().describe("kind account"),
1331
+ error: z.string().optional().describe("unauthenticated | person_only | blocked_location | bad_kind | recipient_required | bad_chain | bad_rail | address_not_proven | provider_not_configured | provider_error | no_db"),
1332
+ }),
1333
+ effect: "ask",
1334
+ auth: "owner",
1335
+ cost: "free",
1336
+ idempotent: true,
1337
+ reversible: true,
1338
+ settles: "none",
1339
+ version: "1.0.0",
1340
+ examples: [{ kind: "kyc" }, { kind: "kyc", verifier: "sumsub-share", recipient: "transak" }, { kind: "account", chain: "sui" }],
1341
+ }),
1342
+ // `ramp:get` (C4; was ramp:status, an alias for one release): what is TRUE about adding money (/on) and cashing out (/off) today,
1343
+ // from lib/ramp/status.ts, the one source the pages, chat, CLI, MCP and llms.txt print.
1344
+ // Read-only and PUBLIC on purpose: it is a fact about the door, not about a person, so it
1345
+ // carries no address, no account and no config value, only what the public page shows.
1346
+ // Composed from the gates the other ramp receivers enforce, so it cannot say "open" while
1347
+ // they refuse. Its loop closes in D1 only (d1Mark): an anonymous read never reaches TypeDB.
1348
+ "ramp:get": receiver({
1349
+ receiver: "ramp:get",
1350
+ summary: "What is true about adding money and cashing out today: whether each door is open, every reason it is not (countries, ID check, bank or payout partner), what comes next, and what works today. The same facts as one.ie/on and one.ie/off. No provider is named as live. Anyone may ask; nothing personal is returned.",
1351
+ request: () => z.object({}),
1352
+ response: () => z.object({
1353
+ ok: z.boolean(),
1354
+ network: z.string().optional().describe("This deploy's network word for USDC, e.g. 'Sui' or 'Sui testnet'"),
1355
+ on: z.unknown().optional().describe("Add money: { door, title, open, pill, why, stops, checks: [{ key, ok, label, state, detail, clause }], next, today, one, summary }"),
1356
+ off: z.unknown().optional().describe("Cash out: the same shape"),
1357
+ error: z.string().optional(),
1358
+ }),
1359
+ effect: "ask",
1360
+ auth: "public",
1361
+ cost: "free",
1362
+ idempotent: true,
1363
+ reversible: true,
1364
+ settles: "none",
1365
+ version: "1.0.0",
1366
+ examples: [{}],
1367
+ surfaces: { chat: true, mcp: true },
1368
+ }),
1369
+ "ramp:list": receiver({
1370
+ receiver: "ramp:list",
1371
+ summary: "The caller's own on-ramp deposits, newest first: amount, the provider's fee, the USDC delivered, the chain, and the transaction digest once a chain read confirms it landed. A row alone never says landed. A signed-in person only.",
1372
+ request: () => z.object({
1373
+ limit: z.number().int().optional().describe("1 to 50, default 20; truncated says if there are more"),
1374
+ }),
1375
+ response: () => z.object({
1376
+ ok: z.boolean(),
1377
+ deposits: z.array(z.unknown()).optional(),
1378
+ truncated: z.boolean().optional().describe("true when more deposits exist than were returned"),
1379
+ error: z.string().optional().describe("unauthenticated | person_only | no_db"),
1380
+ }),
1381
+ effect: "ask",
1382
+ auth: "owner",
1383
+ cost: "free",
1384
+ idempotent: true,
1385
+ reversible: true,
1386
+ settles: "none",
1387
+ version: "1.0.0",
1388
+ examples: [{ limit: 10 }],
1389
+ }),
1390
+ // `analytics:get` (was analytics:overview, renamed 2026-11-19; an alias for one release) is the dashboard as a read: the SAME `loadDashboard`
1391
+ // (one.ie/web/src/lib/dashboard/load-dashboard.ts) that `/u/<slug>/dashboard`
1392
+ // renders from, so the figures cannot drift from the page. One receiver for the
1393
+ // page, not one per chart. Its authority is BOTH the page's guard
1394
+ // (`authorizeWorkspace`) and the sibling's (`callerControlsWorkspace`), so it is
1395
+ // never wider than the page.
1396
+ "analytics:get": receiver({
1397
+ receiver: "analytics:get",
1398
+ summary: "The workspace dashboard as data — visitors, chats, money, credits, runs, sources, pages, what needs you and the live feed: the exact figures /u/<slug>/dashboard draws, from the same loader",
1399
+ request: () => z.object({
1400
+ workspace: z.string().optional().describe("Workspace slug; defaults to the attested caller's. Names a target only — the caller must pass the dashboard page's own guard for it AND control it."),
1401
+ range: z.enum(["7", "30", "90"]).optional().describe("Window in days, the page's ?range=. Default '7'. Visit figures cover at most 14 of them (see overview.visitDays)."),
1402
+ host: z.string().optional().describe("Hostname the dashboard is viewed on (e.g. app.vespio.ai). Referrers from it count as same-site, as the page counts its own host. The workspace's verified domains and one.ie always do; the hosts used come back as `ownHosts`."),
1403
+ }),
1404
+ response: () => z.object({
1405
+ ok: z.boolean(),
1406
+ workspace: z.string().optional(),
1407
+ range: z.enum(["7", "30", "90"]).optional(),
1408
+ ownHosts: z.array(z.string()).optional().describe("The hosts treated as same-site when classing referrers into sources"),
1409
+ overview: z.object({
1410
+ slug: z.string(),
1411
+ range: z.string(),
1412
+ days: z.number(),
1413
+ visitDays: z.number().describe("How many of `days` the visit figures cover — raw visits are KEPT 14 days, so a 30/90-day range reads 14 days of visits. Not a sample: a retention cap"),
1414
+ asOfMs: z.number(),
1415
+ humans: z.object({ now: z.number(), prev: z.number().nullable() }).describe("Distinct human visitors; prev null = the earlier window is not kept, never zero"),
1416
+ bots: z.object({ now: z.number(), prev: z.number().nullable() }),
1417
+ views: z.object({ now: z.number(), prev: z.number().nullable() }),
1418
+ chats: z.object({ now: z.number(), prev: z.number().nullable() }).describe("Visitor conversations started (threads with a visitor cookie) over the full range"),
1419
+ chatsInVisitWindow: z.object({ now: z.number(), prev: z.number().nullable() }),
1420
+ revenueCents: z.object({ now: z.number(), prev: z.number().nullable() }).describe("Settled cash, USD cents — credits never added in"),
1421
+ payments: z.object({ now: z.number(), prev: z.number().nullable() }),
1422
+ paymentsInVisitWindow: z.number(),
1423
+ creditsEarned: z.object({ now: z.number(), prev: z.number().nullable() }),
1424
+ pending: z.object({ cents: z.number(), count: z.number() }),
1425
+ waiting: z.number().describe("EXACT count of visitor chats whose last word is the customer's"),
1426
+ runs: z.object({
1427
+ done: z.object({ now: z.number(), prev: z.number().nullable() }),
1428
+ failed: z.object({ now: z.number(), prev: z.number().nullable() }),
1429
+ running: z.number(),
1430
+ }),
1431
+ creditsBalance: z.number().nullable(),
1432
+ creditsSpent: z.object({ now: z.number(), prev: z.number().nullable() }),
1433
+ series: z.array(z.unknown()).describe("One point per day: humans/views/bots (null older than 14 days — not kept), chats, revenueCents, runsDone, runsFailed"),
1434
+ sources: z.array(z.unknown()).describe("Visitors by referrer class (direct/search/social/ai/referral) with hosts; built from at most the top 200 referrers"),
1435
+ pages: z.array(z.unknown()).describe("Top pages by visitors — CAPPED at 25"),
1436
+ devices: z.array(z.unknown()),
1437
+ buyers: z.array(z.unknown()),
1438
+ failedFlows: z.array(z.unknown()),
1439
+ bookings: z.array(z.unknown()),
1440
+ waitingChats: z.array(z.unknown()).describe("The newest waiting chats — CAPPED at 20; `waiting` is the exact count"),
1441
+ needs: z.array(z.unknown()),
1442
+ feed: z.array(z.unknown()),
1443
+ lifetimeCents: z.number(),
1444
+ }).optional(),
1445
+ childCount: z.number().optional().describe("Direct child workspaces; decides `view`"),
1446
+ view: z.enum(["operator", "portfolio"]).optional(),
1447
+ portfolio: z.unknown().optional().describe("The Clients section (last 7 days); null unless view is 'portfolio' and the read succeeded"),
1448
+ education: z.unknown().optional().describe("The learners section (last 7 days); null = the read failed"),
1449
+ signalMap: z.object({ workspaces: z.array(z.string()), rows: z.array(z.unknown()) }).nullable().optional().describe("Signals by workspace and event, last 24 hours; this workspace, the caller's own and up to 7 of the busiest descendants (CAPPED at 9). null = could not look, never 'nothing happened'"),
1450
+ error: z.string().optional().describe("no_db | workspace required | forbidden | authority_undetermined (membership could not be read — retry) | bad_slug"),
1451
+ }),
1452
+ effect: "ask",
1453
+ auth: "manage_workspace",
1454
+ roleAction: "read_revenue",
1455
+ cost: "free",
1456
+ idempotent: true,
1457
+ reversible: true,
1458
+ settles: "none",
1459
+ version: "1.0.0",
1460
+ surfaces: { mcp: true },
1461
+ examples: [{ workspace: "vespio", range: "7", host: "app.vespio.ai" }],
1462
+ }),
1463
+ // `analytics:run` is the step the `monthly-report` and `weekly-digest` paths
1464
+ // call (one.ie/web/src/lib/reports/report.ts): a path's args are substituted
1465
+ // whole, so something must return the finished text for message:send. It takes
1466
+ // NO workspace and NO recipient: the report is always the attested caller's own
1467
+ // workspace, mailed to that workspace's own owner row.
1468
+ "analytics:run": receiver({
1469
+ receiver: "analytics:run",
1470
+ summary: "The caller's own performance report as finished email text — new leads, bookings, sales and time to first reply over the last calendar month or the last seven days, addressed to the workspace owner. A figure that could not be read says so, never 0",
1471
+ request: () => z.object({
1472
+ cadence: z.enum(["month", "week"]).describe("month = the whole previous calendar month (UTC); week = the seven days up to now"),
1473
+ }),
1474
+ response: () => z.object({
1475
+ ok: z.boolean(),
1476
+ workspace: z.string().optional().describe("Always the attested caller's workspace"),
1477
+ cadence: z.enum(["month", "week"]).optional(),
1478
+ window: z.object({ fromMs: z.number(), toMs: z.number(), label: z.string() }).optional().describe("The window read, from inclusive, to exclusive"),
1479
+ to: z.string().optional().describe("The workspace owner's email: owners.recovery_email, else the human role-'owner' actor world:create-workspace recorded on this workspace. Never a caller field, never a contact"),
1480
+ subject: z.string().optional(),
1481
+ text: z.string().optional().describe("The report body, ready for message:send"),
1482
+ facts: z.object({
1483
+ leads: z.number().nullable(),
1484
+ bookings: z.number().nullable(),
1485
+ sales: z.object({ count: z.number(), byCurrency: z.record(z.string(), z.number()) }).nullable().describe("Paid orders; minor units per currency, never summed across currencies"),
1486
+ firstReplyMinutes: z.number().nullable().describe("Median minutes from capture to first reply, as lead:reply recorded them; null when none was recorded in the window or the read failed"),
1487
+ firstReplies: z.number().nullable().describe("First replies lead:reply recorded in the window; null = could not be read"),
1488
+ }).optional().describe("null = could not be read, never zero"),
1489
+ error: z.string().optional().describe("no_db | unauthenticated | bad_request | forbidden | no_recipient (the workspace has no owner email) | recipient_unreadable"),
1490
+ }),
1491
+ effect: "ask",
1492
+ auth: "manage_workspace",
1493
+ roleAction: "read_revenue",
1494
+ cost: "free",
1495
+ idempotent: true,
1496
+ reversible: true,
1497
+ settles: "none",
1498
+ version: "1.0.0",
1499
+ examples: [{ cadence: "month" }],
1500
+ }),
1161
1501
  "tools:composio": receiver({
1162
1502
  receiver: "tools:composio",
1163
1503
  summary: "Execute one connected Composio tool from a workflow `tool` step (config.composio)",
@@ -1712,6 +2052,8 @@ export const RECEIVERS = {
1712
2052
  // ── identity ──
1713
2053
  "identity:address": receiver({
1714
2054
  receiver: "identity:address",
2055
+ // 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.
2056
+ auth: "member",
1715
2057
  surfaces: { mcp: true },
1716
2058
  summary: "Resolve an actor's wallet address",
1717
2059
  request: () => z.object({ uid: z.string() }),
@@ -1805,21 +2147,14 @@ export const RECEIVERS = {
1805
2147
  }),
1806
2148
  effect: "ask", auth: "public", cost: "free", idempotent: true,
1807
2149
  }),
1808
- // ── auth (human session) ──
1809
- // auth:sign-in killed (C7): Better Auth handles all human auth; signal/ask pipeline returns dissolved
1810
- "auth:sign-out": receiver({
1811
- receiver: "auth:sign-out",
1812
- summary: "End the current session",
1813
- request: () => z.object({}),
1814
- response: () => ok,
1815
- effect: "signal", idempotent: true,
1816
- }),
1817
2150
  // board:join killed (C7): no resolver, no route, no caller
1818
2151
  // agency:push:complete killed (C7): no resolver, no route, no caller
1819
2152
  // agency:friction killed (C7): no resolver, no route, no caller
1820
2153
  // ── groups ──
1821
2154
  "groups:join": receiver({
1822
2155
  receiver: "groups:join",
2156
+ // 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.
2157
+ auth: "member",
1823
2158
  canonical: "world:request-access",
1824
2159
  surfaces: { mcp: true },
1825
2160
  summary: "Join a group",
@@ -1829,6 +2164,8 @@ export const RECEIVERS = {
1829
2164
  }),
1830
2165
  "groups:leave": receiver({
1831
2166
  receiver: "groups:leave",
2167
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!gid || !uid) return { ok: false }` on ctx.ownerSlug (resolvers/groups.ts:155-156).
2168
+ auth: "member",
1832
2169
  canonical: "world:remove-member",
1833
2170
  surfaces: { mcp: true },
1834
2171
  summary: "Leave a group",
@@ -1881,6 +2218,8 @@ export const RECEIVERS = {
1881
2218
  }),
1882
2219
  "groups:members": receiver({
1883
2220
  receiver: "groups:members",
2221
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!ctx.ownerSlug) throw forbidden` (resolvers/groups.ts:108).
2222
+ auth: "member",
1884
2223
  canonical: "world:list-actors",
1885
2224
  surfaces: { mcp: true },
1886
2225
  summary: "List a group's members",
@@ -1937,6 +2276,7 @@ export const RECEIVERS = {
1937
2276
  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",
1938
2277
  request: () => z.object({
1939
2278
  token: z.string().min(10).max(4000).describe("The token credits:request returned (also in the inbox notice)."),
2279
+ ...WORK_CONTRACT_FIELDS,
1940
2280
  }),
1941
2281
  response: () => z.object({
1942
2282
  ok: z.boolean(),
@@ -1945,7 +2285,7 @@ export const RECEIVERS = {
1945
2285
  clamped: z.boolean().optional().describe("true when the approval was cut to the funder's own plan grant."),
1946
2286
  error: z.string().optional().describe("unauthorized | invalid_token | expired | not_the_funder | self_approval | recipient_moved | request_unavailable"),
1947
2287
  }),
1948
- effect: "ask", auth: "manage_clients", cost: "free", idempotent: true,
2288
+ effect: "ask", auth: "manage_clients", cost: "free", idempotent: true, moves: "value",
1949
2289
  }),
1950
2290
  "billing:clients": receiver({
1951
2291
  receiver: "billing:clients",
@@ -1971,6 +2311,8 @@ export const RECEIVERS = {
1971
2311
  // ── subscriptions ──
1972
2312
  "subscriptions:register": receiver({
1973
2313
  receiver: "subscriptions:register",
2314
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!actor) return forbidden` on ctx.ownerSlug (resolvers/subscriptions.ts:1092-1093).
2315
+ auth: "member",
1974
2316
  canonical: "world:subscribe",
1975
2317
  summary: "Subscribe to a receiver's events by tag",
1976
2318
  request: () => z.object({
@@ -2004,6 +2346,8 @@ export const RECEIVERS = {
2004
2346
  }),
2005
2347
  "world:announce": receiver({
2006
2348
  receiver: "world:announce",
2349
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!sender) return forbidden` (resolvers/subscriptions.ts:1143).
2350
+ auth: "member",
2007
2351
  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)",
2008
2352
  request: () => z.object({
2009
2353
  tags: z.array(z.string()),
@@ -2027,6 +2371,8 @@ export const RECEIVERS = {
2027
2371
  }),
2028
2372
  "world": receiver({
2029
2373
  receiver: "world",
2374
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!sender) return forbidden` (resolvers/subscriptions.ts:1078).
2375
+ auth: "member",
2030
2376
  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')",
2031
2377
  request: () => z.object({
2032
2378
  tags: z.array(z.string()).optional(),
@@ -2050,6 +2396,8 @@ export const RECEIVERS = {
2050
2396
  }),
2051
2397
  "world:outcome": receiver({
2052
2398
  receiver: "world:outcome",
2399
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!sender) return forbidden` (resolvers/subscriptions.ts:1469).
2400
+ auth: "member",
2053
2401
  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",
2054
2402
  request: () => z.object({
2055
2403
  tags: z.array(z.string()),
@@ -2070,6 +2418,8 @@ export const RECEIVERS = {
2070
2418
  }),
2071
2419
  "world:route": receiver({
2072
2420
  receiver: "world:route",
2421
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!sender) return forbidden` (resolvers/subscriptions.ts:1211).
2422
+ auth: "member",
2073
2423
  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)",
2074
2424
  request: () => z.object({
2075
2425
  tags: z.array(z.string()).optional(),
@@ -2096,6 +2446,8 @@ export const RECEIVERS = {
2096
2446
  }),
2097
2447
  "world:suggest-workflow": receiver({
2098
2448
  receiver: "world:suggest-workflow",
2449
+ // 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.
2450
+ auth: "member",
2099
2451
  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",
2100
2452
  request: () => z.object({
2101
2453
  tags: z.array(z.string()),
@@ -2116,6 +2468,8 @@ export const RECEIVERS = {
2116
2468
  }),
2117
2469
  "tasks:announce": receiver({
2118
2470
  receiver: "tasks:announce",
2471
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!sender) return forbidden` (resolvers/subscriptions.ts:1518).
2472
+ auth: "member",
2119
2473
  surfaces: { mcp: true },
2120
2474
  summary: "Announce a task into the world by its tags — the first caller of world:announce",
2121
2475
  request: () => z.object({
@@ -2145,6 +2499,8 @@ export const RECEIVERS = {
2145
2499
  }),
2146
2500
  "tasks:mine": receiver({
2147
2501
  receiver: "tasks:mine",
2502
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!actor) return forbidden` (resolvers/subscriptions.ts:1544).
2503
+ auth: "member",
2148
2504
  surfaces: { mcp: true },
2149
2505
  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`",
2150
2506
  // `workspace` is not decoration — /api/ask reads a SERVICE caller's nominated slug off
@@ -2178,6 +2534,8 @@ export const RECEIVERS = {
2178
2534
  }),
2179
2535
  "tasks:everywhere": receiver({
2180
2536
  receiver: "tasks:everywhere",
2537
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!actor) return forbidden` (resolvers/subscriptions.ts:1655).
2538
+ auth: "member",
2181
2539
  surfaces: { mcp: true },
2182
2540
  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)",
2183
2541
  // See tasks:mine — a service caller nominates its workspace here, and zod strips any
@@ -2221,6 +2579,8 @@ export const RECEIVERS = {
2221
2579
  }),
2222
2580
  "factory:elaborate": receiver({
2223
2581
  receiver: "factory:elaborate",
2582
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!actor) return forbidden` + inWorkspace(parent) (resolvers/factory.ts:285,307-309).
2583
+ auth: "member",
2224
2584
  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",
2225
2585
  request: () => z.object({
2226
2586
  type: z.enum(["objective", "deliverable", "task"]),
@@ -2254,6 +2614,8 @@ export const RECEIVERS = {
2254
2614
  }),
2255
2615
  "factory:size": receiver({
2256
2616
  receiver: "factory:size",
2617
+ // 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).
2618
+ auth: "public",
2257
2619
  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",
2258
2620
  request: () => z.object({
2259
2621
  // The changed paths, repo-relative. do-tier sizes a DIFF, never a sentence,
@@ -2285,6 +2647,8 @@ export const RECEIVERS = {
2285
2647
  }),
2286
2648
  "factory:recon": receiver({
2287
2649
  receiver: "factory:recon",
2650
+ // auth (public) — task:01a128d6108e551f5966106b: pure function over build-time PAGE_FILES, no ctx (resolvers/factory.ts:218) — the read-only sibling of factory:size.
2651
+ auth: "public",
2288
2652
  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",
2289
2653
  request: () => z.object({
2290
2654
  // The captured sentence. do-triage reads what the text LITERALLY names —
@@ -2318,6 +2682,8 @@ export const RECEIVERS = {
2318
2682
  }),
2319
2683
  "factory:attempt": receiver({
2320
2684
  receiver: "factory:attempt",
2685
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!actor) return forbidden` + inWorkspace(task) (resolvers/factory.ts:356,371-373).
2686
+ auth: "member",
2321
2687
  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",
2322
2688
  request: () => z.object({
2323
2689
  phase: z.enum(["open", "close"]),
@@ -2615,6 +2981,7 @@ export const RECEIVERS = {
2615
2981
  receiver: "ehc:evidence-remove",
2616
2982
  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",
2617
2983
  request: () => z.object({
2984
+ slug: SERVICE_SLUG,
2618
2985
  cyp: z.string(), // case id or slug
2619
2986
  evidenceId: z.string(), // exact id from ehc:evidence, e.g. 'ev-a7-railay'
2620
2987
  removed: z.boolean().optional(), // default true; false restores
@@ -2804,6 +3171,8 @@ export const RECEIVERS = {
2804
3171
  }),
2805
3172
  "do:halt": receiver({
2806
3173
  receiver: "do:halt",
3174
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!actor) return forbidden` + inWorkspace(plan) (resolvers/factory.ts:576,592-594).
3175
+ auth: "member",
2807
3176
  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",
2808
3177
  request: () => z.object({
2809
3178
  // The plan slug the operator sees ("factory"). The plan tid is resolved server-side;
@@ -2831,6 +3200,8 @@ export const RECEIVERS = {
2831
3200
  }),
2832
3201
  "tasks:create": receiver({
2833
3202
  receiver: "tasks:create",
3203
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!actor) return { error: 'workspace required' }` (resolvers/tasks.ts:415); operate on the parent (:459).
3204
+ auth: "member",
2834
3205
  surfaces: { mcp: true },
2835
3206
  summary: "Write one open task to the substrate and announce it by its tags in the same act — the quick-add entry point",
2836
3207
  request: () => z.object({
@@ -2861,6 +3232,8 @@ export const RECEIVERS = {
2861
3232
  }),
2862
3233
  "tasks:claim": receiver({
2863
3234
  receiver: "tasks:claim",
3235
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!claimant) return { error: 'workspace required' }` + taskAccess === 'operate' (resolvers/tasks.ts:1319,1336-1337).
3236
+ auth: "member",
2864
3237
  surfaces: { mcp: true },
2865
3238
  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",
2866
3239
  // Addressable two ways, and BOTH must be optional here. The resolver has always
@@ -2889,6 +3262,8 @@ export const RECEIVERS = {
2889
3262
  }),
2890
3263
  "tasks:reap": receiver({
2891
3264
  receiver: "tasks:reap",
3265
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!ctx.ownerSlug) return { error: 'workspace required' }` (resolvers/tasks.ts:1273).
3266
+ auth: "member",
2892
3267
  surfaces: { mcp: true },
2893
3268
  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",
2894
3269
  // The other half of the claim seam. tasks:claim is atomic, so two workers can
@@ -2949,6 +3324,30 @@ export const RECEIVERS = {
2949
3324
  }),
2950
3325
  effect: "ask", idempotent: true, auth: "member",
2951
3326
  }),
3327
+ "tasks:approve": receiver({
3328
+ receiver: "tasks:approve",
3329
+ summary: "A person closes a row with Touch ID: the passkey assertion must belong to the caller's own web session (never a body field), over the challenge hash({ tasks: 'touch-close', tid, nonce }); only then is the row set done through tasks:status under the same caller, and the thread says who closed it. A key, an agent or a workflow step is refused",
3330
+ request: () => z.object({
3331
+ tid: z.string(),
3332
+ // A fresh value per press, inside the signed subject: a reopened row can be closed again, and no
3333
+ // assertion can be replayed onto another press.
3334
+ nonce: z.string(),
3335
+ // The WebAuthn assertion (AuthenticationResponseJSON). Checked by auth-plugins/passkey-assert.ts.
3336
+ assertion: z.record(z.string(), z.unknown()),
3337
+ workspace: z.string().optional(),
3338
+ }),
3339
+ response: () => z.object({
3340
+ ok: z.boolean(),
3341
+ tid: z.string().optional(),
3342
+ status: z.string().optional(),
3343
+ by: z.string().optional(),
3344
+ at: z.string().optional(),
3345
+ recurred: z.boolean().optional(),
3346
+ error: z.string().optional(),
3347
+ detail: z.string().optional(),
3348
+ }),
3349
+ effect: "ask", idempotent: false, auth: "member",
3350
+ }),
2952
3351
  "tasks:rename": receiver({
2953
3352
  receiver: "tasks:rename",
2954
3353
  surfaces: { mcp: true },
@@ -3023,7 +3422,11 @@ export const RECEIVERS = {
3023
3422
  surfaces: { mcp: true },
3024
3423
  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",
3025
3424
  request: () => z.object({
3026
- tag: z.string(),
3425
+ // Optional: without a tag the handler lists the caller's workspace's ACTIVE rows
3426
+ // (open|blocked|picked) from the board snapshot — a page of `limit`, with `total` +
3427
+ // `truncated`. A tag narrows to one plan's rows, unbounded as before.
3428
+ tag: z.string().optional(),
3429
+ limit: z.number().int().positive().optional().describe("Tag-less page size (default 50, cap 1000); ignored when a tag is given."),
3027
3430
  // Optional task-status filter (open|blocked|picked|done|verified|failed|dissolved).
3028
3431
  // Declared here because the HTTP edge dispatches zod's PARSED output — an
3029
3432
  // undeclared field is silently stripped before the resolver reads it, and the
@@ -3040,6 +3443,11 @@ export const RECEIVERS = {
3040
3443
  status: z.string(),
3041
3444
  name: z.string().optional(),
3042
3445
  })).optional(),
3446
+ total: z.number().optional().describe("Tag-less list only: rows matched before the page cut."),
3447
+ 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."),
3448
+ asOf: z.string().optional().describe("Tag-less list only: when the board snapshot it was read from was built."),
3449
+ stale: z.boolean().optional().describe("Tag-less list only: the snapshot rebuild failed and this is the last board that was built."),
3450
+ status: z.string().optional().describe("Echo of the status filter, when one was given."),
3043
3451
  error: z.string().optional(),
3044
3452
  }),
3045
3453
  effect: "ask", idempotent: true, auth: "member",
@@ -3523,6 +3931,8 @@ export const RECEIVERS = {
3523
3931
  }),
3524
3932
  "tasks:undepend": receiver({
3525
3933
  receiver: "tasks:undepend",
3934
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!actor) return { error: 'workspace required' }` + gateTask on both rows (resolvers/tasks.ts:1768,1773-1774).
3935
+ auth: "member",
3526
3936
  surfaces: { mcp: true },
3527
3937
  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",
3528
3938
  request: () => z.object({
@@ -3540,6 +3950,8 @@ export const RECEIVERS = {
3540
3950
  }),
3541
3951
  "tasks:launch": receiver({
3542
3952
  receiver: "tasks:launch",
3953
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!owner) return { error: 'workspace required' }` + operate per tid (resolvers/tasks.ts:2100,2118-2121).
3954
+ auth: "member",
3543
3955
  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",
3544
3956
  request: () => z.object({
3545
3957
  tids: z.array(z.string()),
@@ -3565,6 +3977,8 @@ export const RECEIVERS = {
3565
3977
  }),
3566
3978
  "tasks:link": receiver({
3567
3979
  receiver: "tasks:link",
3980
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!actor) return { error: 'workspace required' }` + gateTask (resolvers/tasks.ts:1451,1467).
3981
+ auth: "member",
3568
3982
  surfaces: { mcp: true },
3569
3983
  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",
3570
3984
  // The slug IS the handle here — the resolver requires it and resolves the origin tid
@@ -3619,6 +4033,8 @@ export const RECEIVERS = {
3619
4033
  }),
3620
4034
  "agents:commend": receiver({
3621
4035
  receiver: "agents:commend",
4036
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!voter) throw forbidden` (resolvers/market.ts:1865-1866).
4037
+ auth: "member",
3622
4038
  summary: "Commend an agent — strengthen its reputation path",
3623
4039
  request: () => z.object({ uid: z.string() }),
3624
4040
  response: () => AgentActionResponseSchema,
@@ -3626,6 +4042,8 @@ export const RECEIVERS = {
3626
4042
  }),
3627
4043
  "agents:flag": receiver({
3628
4044
  receiver: "agents:flag",
4045
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!voter) throw forbidden` (resolvers/market.ts:1878-1879).
4046
+ auth: "member",
3629
4047
  summary: "Flag an agent — add resistance to its reputation path",
3630
4048
  request: () => z.object({ uid: z.string() }),
3631
4049
  response: () => AgentActionResponseSchema,
@@ -3633,6 +4051,8 @@ export const RECEIVERS = {
3633
4051
  }),
3634
4052
  "agents:status": receiver({
3635
4053
  receiver: "agents:status",
4054
+ // 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.
4055
+ auth: "owner",
3636
4056
  canonical: "world:update-actor",
3637
4057
  summary: "Set an agent active or inactive",
3638
4058
  request: () => z.object({ uid: z.string(), status: z.string() }),
@@ -3641,6 +4061,8 @@ export const RECEIVERS = {
3641
4061
  }),
3642
4062
  "agents:capabilities": receiver({
3643
4063
  receiver: "agents:capabilities",
4064
+ // 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).
4065
+ auth: "public",
3644
4066
  summary: "List an agent's published capabilities",
3645
4067
  request: () => z.object({ uid: z.string() }),
3646
4068
  response: () => z.array(CapabilityItemSchema),
@@ -3650,6 +4072,8 @@ export const RECEIVERS = {
3650
4072
  // ── pay (TRANSACT — onchain settlement) ──
3651
4073
  "pay:weight": receiver({
3652
4074
  receiver: "pay:weight",
4075
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!callerSlug) throw forbidden` (resolvers/market.ts:1561).
4076
+ auth: "member",
3653
4077
  surfaces: { mcp: { name: "pay" } },
3654
4078
  summary: "Pay for a task by weighting the path between two actors",
3655
4079
  request: () => z.object({
@@ -3658,9 +4082,10 @@ export const RECEIVERS = {
3658
4082
  // before the handler could derive it — and before its own auth check ran.
3659
4083
  from: z.string().optional(),
3660
4084
  to: z.string(), task: z.string(), amount: z.number(),
4085
+ ...WORK_CONTRACT_FIELDS,
3661
4086
  }),
3662
4087
  response: () => PayResponseSchema,
3663
- effect: "ask", cost: "variable", settles: "onchain", reversible: false, simulatable: true,
4088
+ effect: "ask", cost: "variable", settles: "onchain", reversible: false, simulatable: true, moves: "value",
3664
4089
  }),
3665
4090
  "tasks:stake": receiver({
3666
4091
  receiver: "tasks:stake",
@@ -3685,6 +4110,7 @@ export const RECEIVERS = {
3685
4110
  receiver: "market:offer",
3686
4111
  summary: "Buyer creates a Deal at OFFER stage — initiates A2A negotiation",
3687
4112
  request: () => z.object({
4113
+ slug: SERVICE_SLUG,
3688
4114
  id: z.string().uuid().optional(),
3689
4115
  seller: z.string().min(1),
3690
4116
  skill: z.string().min(1),
@@ -3718,7 +4144,7 @@ export const RECEIVERS = {
3718
4144
  "market:accept": receiver({
3719
4145
  receiver: "market:accept",
3720
4146
  summary: "Buyer accepts deal — OFFER → ESCROW",
3721
- request: () => z.object({ dealId: z.string().min(1) }),
4147
+ request: () => z.object({ slug: SERVICE_SLUG, dealId: z.string().min(1) }),
3722
4148
  response: () => z.union([
3723
4149
  z.object({ ok: z.literal(true), deal: z.object({ id: z.string(), stage: z.string(), version: z.number() }) }),
3724
4150
  z.object({ ok: z.literal(false), error: z.string() }),
@@ -3764,12 +4190,12 @@ export const RECEIVERS = {
3764
4190
  "market:settle": receiver({
3765
4191
  receiver: "market:settle",
3766
4192
  summary: "Release escrow payment — SETTLE → RECEIPT",
3767
- request: () => z.object({ dealId: z.string().min(1) }),
4193
+ request: () => z.object({ slug: SERVICE_SLUG, dealId: z.string().min(1), ...WORK_CONTRACT_FIELDS }),
3768
4194
  response: () => z.union([
3769
4195
  z.object({ ok: z.literal(true), deal: z.object({ id: z.string(), stage: z.string(), version: z.number() }) }),
3770
4196
  z.object({ ok: z.literal(false), error: z.string() }),
3771
4197
  ]),
3772
- effect: "ask", auth: "required", reversible: false, idempotent: false,
4198
+ effect: "ask", auth: "required", reversible: false, idempotent: false, moves: "value",
3773
4199
  }),
3774
4200
  "market:dispute": receiver({
3775
4201
  receiver: "market:dispute",
@@ -3784,17 +4210,17 @@ export const RECEIVERS = {
3784
4210
  "market:escrow": receiver({
3785
4211
  receiver: "market:escrow",
3786
4212
  summary: "Buyer locks payment via pay.one.ie — ESCROW → EXECUTE on confirmed tx",
3787
- request: () => z.object({ dealId: z.string().min(1) }),
4213
+ request: () => z.object({ dealId: z.string().min(1), ...WORK_CONTRACT_FIELDS }),
3788
4214
  response: () => z.union([
3789
4215
  z.object({ ok: z.literal(true), deal: z.object({ id: z.string(), stage: z.string(), version: z.number() }), escrowRef: z.string() }),
3790
4216
  z.object({ ok: z.literal(false), error: z.string(), deal: z.object({ id: z.string(), stage: z.string() }).optional() }),
3791
4217
  ]),
3792
- effect: "ask", auth: "required", reversible: false, idempotent: false,
4218
+ effect: "ask", auth: "required", reversible: false, idempotent: false, moves: "value",
3793
4219
  }),
3794
4220
  "market:offers": receiver({
3795
4221
  receiver: "market:offers",
3796
4222
  summary: "List the caller's own deals (as buyer or seller), optionally filtered by stage",
3797
- request: () => z.object({ stage: z.string().optional() }),
4223
+ request: () => z.object({ slug: SERVICE_SLUG, stage: z.string().optional() }),
3798
4224
  response: () => z.union([
3799
4225
  z.object({ ok: z.literal(true), deals: z.array(z.object({
3800
4226
  id: z.string(), buyer: z.string(), seller: z.string(), skill: z.string(),
@@ -3808,6 +4234,8 @@ export const RECEIVERS = {
3808
4234
  // ── market (TRADE) ──
3809
4235
  "market:hire": receiver({
3810
4236
  receiver: "market:hire",
4237
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!callerSlug) throw forbidden` (resolvers/market.ts:1493).
4238
+ auth: "member",
3811
4239
  summary: "Hire an agent for a skill — opens a chat or returns an escrow template",
3812
4240
  request: () => z.object({ providerUid: z.string(), skillId: z.string(), initialMessage: z.string().optional() }),
3813
4241
  response: () => z.union([
@@ -3821,6 +4249,8 @@ export const RECEIVERS = {
3821
4249
  }),
3822
4250
  "market:bounty": receiver({
3823
4251
  receiver: "market:bounty",
4252
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!callerSlug) throw forbidden` (resolvers/market.ts:1616).
4253
+ auth: "member",
3824
4254
  summary: "Post a bounty for a skill, backed by an escrow",
3825
4255
  request: () => z.object({
3826
4256
  skillId: z.string(), sellerUid: z.string(),
@@ -3844,6 +4274,8 @@ export const RECEIVERS = {
3844
4274
  }),
3845
4275
  "market:bounties": receiver({
3846
4276
  receiver: "market:bounties",
4277
+ // auth (public) — task:01a128d6108e551f5966106b: the prerendered public /marketplace reads it logged out (MarketplaceApp.tsx:278); handler reads no ctx (resolvers/market.ts:1649).
4278
+ auth: "public",
3847
4279
  summary: "List bounties, optionally filtered by seller or poster",
3848
4280
  request: () => z.object({ seller: z.string().optional(), poster: z.string().optional() }),
3849
4281
  response: () => z.array(z.object({
@@ -3854,6 +4286,8 @@ export const RECEIVERS = {
3854
4286
  }),
3855
4287
  "market:claim": receiver({
3856
4288
  receiver: "market:claim",
4289
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!claimantUid) throw forbidden` (resolvers/market.ts:1689-1690).
4290
+ auth: "member",
3857
4291
  summary: "Claim an open bounty — atomically marks it picked and binds the claimant",
3858
4292
  request: () => z.object({ bountyId: z.string() }),
3859
4293
  response: () => z.union([
@@ -3890,6 +4324,8 @@ export const RECEIVERS = {
3890
4324
  }),
3891
4325
  "market:list": receiver({
3892
4326
  receiver: "market:list",
4327
+ // 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).
4328
+ auth: "public",
3893
4329
  summary: "List the capability market",
3894
4330
  request: () => z.object({ tag: z.string().optional(), maxPrice: z.number().optional() }),
3895
4331
  response: () => z.object({ capabilities: z.array(z.unknown()) }),
@@ -3898,6 +4334,8 @@ export const RECEIVERS = {
3898
4334
  // ── capabilities ──
3899
4335
  "capabilities:publish": receiver({
3900
4336
  receiver: "capabilities:publish",
4337
+ // auth (owner) — task:01a128d6108e551f5966106b: handler requires sellerUid === caller or callerControlsWorkspace (resolvers/market.ts:1908-1916).
4338
+ auth: "owner",
3901
4339
  summary: "Publish a capability (skill listing) to the market",
3902
4340
  request: () => z.object({
3903
4341
  skillId: z.string(), name: z.string(),
@@ -3921,8 +4359,14 @@ export const RECEIVERS = {
3921
4359
  // ── reads (free · idempotent) ──
3922
4360
  "signals:list": receiver({
3923
4361
  receiver: "signals:list",
4362
+ // 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.
4363
+ auth: "member",
3924
4364
  summary: "List recent signals",
3925
4365
  request: () => z.object({
4366
+ // The service lane (channels' analytics tools) names the workspace it asks for; the ask
4367
+ // door reads only a service caller's nomination, from the PARSED payload — undeclared,
4368
+ // zod strips it and the member label refuses the call.
4369
+ slug: z.string().optional(),
3926
4370
  limit: z.number().optional(), since: z.number().optional(),
3927
4371
  from: z.number().optional(), to: z.number().optional(),
3928
4372
  intent: z.string().optional(),
@@ -3936,16 +4380,26 @@ export const RECEIVERS = {
3936
4380
  }),
3937
4381
  "stats:current": receiver({
3938
4382
  receiver: "stats:current",
4383
+ // auth (member) — task:01a128d6108e551f5966106b: handler reads no ctx (resolvers/billing.ts:8); every caller found carries a key (SDK, MCP stats, channels service lane).
4384
+ auth: "member",
3939
4385
  surfaces: { mcp: { name: "stats" } },
3940
4386
  summary: "Current world stats — units, skills, highways, revenue, signals",
3941
- request: () => z.object({}),
4387
+ request: () => z.object({
4388
+ // The service lane names the workspace it asks for (see signals:list).
4389
+ slug: z.string().optional(),
4390
+ }),
3942
4391
  response: () => StatsSchema,
3943
4392
  effect: "ask", cost: "free", idempotent: true,
3944
4393
  }),
3945
4394
  "dashboard:usage": receiver({
3946
4395
  receiver: "dashboard:usage",
4396
+ // 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.
4397
+ auth: "member",
3947
4398
  summary: "Caller's plan usage — calls, agents, limits",
3948
- request: () => z.object({}),
4399
+ request: () => z.object({
4400
+ // The service lane names the workspace it asks for (see signals:list).
4401
+ slug: z.string().optional(),
4402
+ }),
3949
4403
  response: () => z.object({
3950
4404
  tier: z.string(), calls_this_month: z.number(), agents_count: z.number(),
3951
4405
  api_limit: z.number(), agent_limit: z.number(), loops: z.array(z.string()),
@@ -3955,6 +4409,8 @@ export const RECEIVERS = {
3955
4409
  }),
3956
4410
  "world:state": receiver({
3957
4411
  receiver: "world:state",
4412
+ // 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.
4413
+ auth: "member",
3958
4414
  summary: "Full world snapshot — units, edges, highways, tags, stats",
3959
4415
  request: () => z.object({}),
3960
4416
  response: () => z.object({}).passthrough(),
@@ -3967,9 +4423,11 @@ export const RECEIVERS = {
3967
4423
  // ════════════════════════════════════════════════════════════════════════
3968
4424
  "meta:catalog": receiver({
3969
4425
  receiver: "meta:catalog",
4426
+ // 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).
4427
+ auth: "public",
3970
4428
  surfaces: { mcp: true },
3971
4429
  summary: "List every receiver the caller can use (with cost/reversibility/settlement), or a goal's recipe",
3972
- request: () => z.object({ goal: z.enum(["spine", "build", "trade", "transact"]).optional() }),
4430
+ request: () => z.object({ goal: z.enum(["spine", "build", "trade", "transact"]).optional(), tag: z.string().optional() }),
3973
4431
  response: () => z.union([
3974
4432
  z.array(z.object({
3975
4433
  receiver: z.string(), summary: z.string(), effect: z.enum(["signal", "ask"]),
@@ -3982,6 +4440,8 @@ export const RECEIVERS = {
3982
4440
  }),
3983
4441
  "meta:schema": receiver({
3984
4442
  receiver: "meta:schema",
4443
+ // 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).
4444
+ auth: "public",
3985
4445
  surfaces: { mcp: true },
3986
4446
  summary: "JSON Schema for one receiver's request + response — read it before you call",
3987
4447
  request: () => z.object({ receiver: z.string() }),
@@ -3993,6 +4453,8 @@ export const RECEIVERS = {
3993
4453
  }),
3994
4454
  "meta:recall": receiver({
3995
4455
  receiver: "meta:recall",
4456
+ // 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).
4457
+ auth: "member",
3996
4458
  surfaces: { mcp: true },
3997
4459
  summary: "Recall the caller's hypotheses (memory), optionally filtered by a search term",
3998
4460
  request: () => z.object({ match: z.string().optional(), limit: z.number().optional() }),
@@ -4005,6 +4467,8 @@ export const RECEIVERS = {
4005
4467
  }),
4006
4468
  "meta:reputation": receiver({
4007
4469
  receiver: "meta:reputation",
4470
+ // 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.
4471
+ auth: "public",
4008
4472
  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",
4009
4473
  request: () => z.object({ uid: z.string().describe("The actor's slug or aid to look up") }),
4010
4474
  response: () => z.object({
@@ -4031,6 +4495,8 @@ export const RECEIVERS = {
4031
4495
  }),
4032
4496
  "meta:types": receiver({
4033
4497
  receiver: "meta:types",
4498
+ // 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.
4499
+ auth: "public",
4034
4500
  surfaces: { mcp: true },
4035
4501
  summary: "Read the resource-type manifest for the caller's workspace, plus the built-in industry templates",
4036
4502
  request: () => z.object({}),
@@ -4042,6 +4508,8 @@ export const RECEIVERS = {
4042
4508
  }),
4043
4509
  "meta:entitlements": receiver({
4044
4510
  receiver: "meta:entitlements",
4511
+ // 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.
4512
+ auth: "member",
4045
4513
  summary: "Check the caller workspace's entitlement for one feature — the authoritative paid-plugin gate; absent/over-limit claim → not allowed (backend returns 402)",
4046
4514
  request: () => z.object({ feature: z.string() }),
4047
4515
  response: () => z.object({
@@ -4129,6 +4597,8 @@ export const RECEIVERS = {
4129
4597
  }),
4130
4598
  "plugins:list": receiver({
4131
4599
  receiver: "plugins:list",
4600
+ // auth (public) — task:01a128d6108e551f5966106b: the static plugin catalog, no ctx (resolvers/plugins.ts:71); the chat PluginPanel reads it logged out (PluginPanel.tsx:236).
4601
+ auth: "public",
4132
4602
  summary: "List all available ONE plugins with their feature key, price, and description",
4133
4603
  request: () => z.object({}),
4134
4604
  response: () => z.object({
@@ -4153,6 +4623,7 @@ export const RECEIVERS = {
4153
4623
  kind: z.enum(["plugin", "agent", "skill"]).optional(),
4154
4624
  uses: z.number().optional(),
4155
4625
  idem: z.string().optional(),
4626
+ ...WORK_CONTRACT_FIELDS,
4156
4627
  }),
4157
4628
  response: () => z.object({
4158
4629
  method: z.enum(["stripe", "credits"]),
@@ -4172,7 +4643,7 @@ export const RECEIVERS = {
4172
4643
  plugin: z.string(),
4173
4644
  feature: z.string(),
4174
4645
  }),
4175
- effect: "ask", auth: "owner", cost: "variable", idempotent: false,
4646
+ effect: "ask", auth: "owner", cost: "variable", idempotent: false, moves: "value",
4176
4647
  examples: [{ name: "shop" }, { name: "shop", method: "credits" }],
4177
4648
  }),
4178
4649
  "plugins:grant": receiver({
@@ -4195,6 +4666,8 @@ export const RECEIVERS = {
4195
4666
  }),
4196
4667
  "plugins:source": receiver({
4197
4668
  receiver: "plugins:source",
4669
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!ws) return { error: 'unauthenticated' }` + checkEntitlement (resolvers/plugins.ts:288-292).
4670
+ auth: "member",
4198
4671
  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.",
4199
4672
  request: () => z.object({ feature: z.string() }),
4200
4673
  response: () => z.object({
@@ -4209,6 +4682,8 @@ export const RECEIVERS = {
4209
4682
  // ── actor discovery + messaging ──────────────────────────────────────────
4210
4683
  "actors:find": receiver({
4211
4684
  receiver: "actors:find",
4685
+ // 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).
4686
+ auth: "public",
4212
4687
  summary: "Find agents on the marketplace by name fragment or skill — marketplace discovery only",
4213
4688
  request: () => z.object({
4214
4689
  // human is excluded: personal names/emails are PII, not marketplace data.
@@ -4225,6 +4700,8 @@ export const RECEIVERS = {
4225
4700
  }),
4226
4701
  "peer:message": receiver({
4227
4702
  receiver: "peer:message",
4703
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!from) throw forbidden` (resolvers/messaging.ts:699-700).
4704
+ auth: "member",
4228
4705
  summary: "Send an async message to another agent's inbox — instant store, no LLM, no streaming",
4229
4706
  request: () => z.object({ to: z.string(), content: z.string(), from: z.string().optional() }),
4230
4707
  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() }),
@@ -4232,6 +4709,8 @@ export const RECEIVERS = {
4232
4709
  }),
4233
4710
  "notify": receiver({
4234
4711
  receiver: "notify",
4712
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!from) throw forbidden` (resolvers/messaging.ts:789-790).
4713
+ auth: "member",
4235
4714
  // NOT surfaces.mcp — the curated `message` tool in packages/mcp/src/tools/
4236
4715
  // messaging.ts already fronts this receiver and carries shaping the registry
4237
4716
  // cannot infer: it defaults `kind: "message"` and names the argument
@@ -4261,6 +4740,8 @@ export const RECEIVERS = {
4261
4740
  }),
4262
4741
  "notify:count": receiver({
4263
4742
  receiver: "notify:count",
4743
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!slug) throw forbidden` (resolvers/messaging.ts:819-820).
4744
+ auth: "member",
4264
4745
  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).",
4265
4746
  request: () => z.object({}),
4266
4747
  response: () => z.object({ unread: z.number() }),
@@ -4268,6 +4749,8 @@ export const RECEIVERS = {
4268
4749
  }),
4269
4750
  "notify:list": receiver({
4270
4751
  receiver: "notify:list",
4752
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!slug) throw forbidden` (resolvers/messaging.ts:839-840).
4753
+ auth: "member",
4271
4754
  summary: "The caller's unread threads, newest first, each with a short preview.",
4272
4755
  request: () => z.object({ limit: z.number().optional() }),
4273
4756
  response: () => z.object({ unread: z.array(z.object({ id: z.string(), ts: z.number(), preview: z.string() })) }),
@@ -4275,6 +4758,8 @@ export const RECEIVERS = {
4275
4758
  }),
4276
4759
  "notify:read": receiver({
4277
4760
  receiver: "notify:read",
4761
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!slug) throw forbidden` (resolvers/messaging.ts:875-876).
4762
+ auth: "member",
4278
4763
  summary: "Mark one thread (threadId) or all of the caller's threads (all:true) as read; nudges the inbox live.",
4279
4764
  request: () => z.object({ threadId: z.string().optional(), id: z.string().optional(), all: z.boolean().optional() }),
4280
4765
  response: () => z.object({ ok: z.boolean(), ts: z.number().optional(), error: z.string().optional() }),
@@ -4282,6 +4767,8 @@ export const RECEIVERS = {
4282
4767
  }),
4283
4768
  "push:subscribe": receiver({
4284
4769
  receiver: "push:subscribe",
4770
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!caller) throw forbidden` (resolvers/messaging.ts:914-915).
4771
+ auth: "member",
4285
4772
  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).",
4286
4773
  request: () => z.object({
4287
4774
  endpoint: z.string(),
@@ -4293,6 +4780,8 @@ export const RECEIVERS = {
4293
4780
  }),
4294
4781
  "thread:append": receiver({
4295
4782
  receiver: "thread:append",
4783
+ // 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.
4784
+ auth: "member",
4296
4785
  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.",
4297
4786
  request: () => z.object({
4298
4787
  slug: z.string(),
@@ -4326,8 +4815,49 @@ export const RECEIVERS = {
4326
4815
  effect: "ask",
4327
4816
  idempotent: false,
4328
4817
  }),
4818
+ "thread:list": receiver({
4819
+ receiver: "thread:list",
4820
+ // auth (member) — the handler walks authorizeWorkspace over the STORED thread's slug with the
4821
+ // attested ctx.ownerSlug, the same guard GET /api/threads/:tid runs (resolvers/messaging.ts
4822
+ // threadRead), so the route and the receiver cannot disagree on who may read. No body field
4823
+ // names a workspace: the thread row does.
4824
+ auth: "member",
4825
+ surfaces: { mcp: true },
4826
+ cost: "free",
4827
+ summary: "Read one thread (a room, an inbox conversation) a page at a time — newest messages last. Members of the thread's group only; staff-only rows (internal notes, unapproved drafts) appear only for staff of that group. The answer says when it is short: `older: true` + `nextCursor` mean earlier messages exist — pass nextCursor back as `before`; on an `after` read, `newer: true` + `newerCursor` mean more arrived than one page holds.",
4828
+ request: () => z.object({
4829
+ threadId: z.string().min(1).max(128).describe("The thread id (e.g. a room thread). Authority is read off this thread's group, never from the caller's body."),
4830
+ limit: z.number().int().min(1).max(200).optional().describe("Messages per page. Default 50, max 200 — a larger value is refused, never silently cut."),
4831
+ before: z.string().optional().describe("`<ts>~<id>` cursor — the nextCursor of the previous page; returns the messages older than it."),
4832
+ after: z.string().optional().describe("`<ts>~<id>` cursor — returns only messages newer than it (what arrived since the last read)."),
4833
+ }),
4834
+ response: () => z.object({
4835
+ ok: z.boolean(),
4836
+ thread: z.object({ id: z.string(), slug: z.string(), name: z.string().nullable().optional(), lastMsgAt: z.number() }).optional(),
4837
+ messages: z.array(z.object({
4838
+ id: z.string(),
4839
+ at: z.number().describe("The row's raw ts — the cursor unit."),
4840
+ role: z.string(),
4841
+ text: z.string(),
4842
+ sender: z.string().optional(),
4843
+ authorKind: z.string().optional(),
4844
+ tags: z.array(z.string()).optional(),
4845
+ replyTo: z.string().optional(),
4846
+ })).optional(),
4847
+ older: z.boolean().optional().describe("true = this page is SHORT: earlier messages exist past it."),
4848
+ nextCursor: z.string().optional().describe("Present iff older (on a `before`/first read) — pass as `before` to read the next (older) page."),
4849
+ newer: z.boolean().optional().describe("On an `after` read: true = this page is SHORT, newer messages exist past it."),
4850
+ newerCursor: z.string().optional().describe("Present iff newer — pass as `after` to keep reading forward."),
4851
+ limit: z.number().optional().describe("The page size actually applied."),
4852
+ error: z.string().optional(),
4853
+ }),
4854
+ effect: "ask",
4855
+ idempotent: true,
4856
+ }),
4329
4857
  "space:post": receiver({
4330
4858
  receiver: "space:post",
4859
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!from) return forbidden` + callerMayPostToSpace (resolvers/messaging.ts:1081-1090).
4860
+ auth: "member",
4331
4861
  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",
4332
4862
  request: () => z.object({
4333
4863
  space: z.string(),
@@ -4346,6 +4876,8 @@ export const RECEIVERS = {
4346
4876
  }),
4347
4877
  "space:create": receiver({
4348
4878
  receiver: "space:create",
4879
+ // auth (owner) — task:01a128d6108e551f5966106b: handler requires callerControlsWorkspace(from, slug) (resolvers/space.ts:14-22).
4880
+ auth: "owner",
4349
4881
  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",
4350
4882
  request: () => z.object({
4351
4883
  slug: z.string(),
@@ -4362,6 +4894,8 @@ export const RECEIVERS = {
4362
4894
  }),
4363
4895
  "space:join": receiver({
4364
4896
  receiver: "space:join",
4897
+ // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!from) return forbidden` (resolvers/space.ts:53-54).
4898
+ auth: "member",
4365
4899
  canonical: "world:request-access",
4366
4900
  summary: "Join a public Space — caller begins receiving its signals and their posts are stamped with the space tag",
4367
4901
  request: () => z.object({ space: z.string() }),
@@ -4374,6 +4908,8 @@ export const RECEIVERS = {
4374
4908
  }),
4375
4909
  "space:invite": receiver({
4376
4910
  receiver: "space:invite",
4911
+ // auth (owner) — task:01a128d6108e551f5966106b: handler requires callerControlsWorkspace(from, space) (resolvers/space.ts:76-83).
4912
+ auth: "owner",
4377
4913
  canonical: "world:invite-member",
4378
4914
  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",
4379
4915
  request: () => z.object({
@@ -4524,6 +5060,7 @@ export const RECEIVERS = {
4524
5060
  receiver: "entity:reply",
4525
5061
  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",
4526
5062
  request: () => z.object({
5063
+ slug: SERVICE_SLUG,
4527
5064
  entityId: z.string(), // conv/session/thread id (alias: id)
4528
5065
  content: z.string(),
4529
5066
  kind: z.enum(["send", "note"]).optional(), // 'send' (default, egresses) | 'note' (internal)
@@ -4546,6 +5083,7 @@ export const RECEIVERS = {
4546
5083
  receiver: "entity:tag",
4547
5084
  summary: "Tag a conversation/entity (add/remove) or move it between lifecycle stages — the sole stage_transition writer",
4548
5085
  request: () => z.object({
5086
+ slug: SERVICE_SLUG,
4549
5087
  id: z.string(),
4550
5088
  add: z.array(z.string()).optional(),
4551
5089
  remove: z.array(z.string()).optional(),
@@ -4760,7 +5298,6 @@ export const RECEIVERS = {
4760
5298
  // conversation:autonomy — read by the channels worker per inbound turn (send vs
4761
5299
  // draft), not an operator/agent verb.
4762
5300
  // member:invited — an internal event hook, not a callable capability.
4763
- // ui:campaigns:compile · ui:campaigns:approve — UI build-pipeline steps.
4764
5301
  // These have live resolvers but no RECEIVERS entry by design — keep it that way.
4765
5302
  // ── commerce (storefront products) — handlers in resolvers/commerce.ts ─────────
4766
5303
  "products:create": receiver({
@@ -4843,7 +5380,9 @@ export const RECEIVERS = {
4843
5380
  surfaces: { mcp: true },
4844
5381
  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.",
4845
5382
  request: () => z.object({
4846
- slug: z.string().optional(),
5383
+ // Required: a public storefront read names its storefront. No default to the caller's own
5384
+ // group — an anonymous caller has none — so a missing slug is 400 validation field slug.
5385
+ slug: z.string(),
4847
5386
  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."),
4848
5387
  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."),
4849
5388
  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)."),
@@ -5598,21 +6137,30 @@ export const RECEIVERS = {
5598
6137
  request: () => z.object({
5599
6138
  workspace: z.string().optional().describe("Defaults to the attested caller's workspace"),
5600
6139
  actor: z.string().optional().describe("Actor whose spend ceiling is read; defaults to the workspace"),
5601
- // C13 repair 2 — the network the VAULT PROJECTION is read on (the /w `?net=` door);
5602
- // defaults to the deploy's NETWORK. It moves the D1 read only: chain balances stay
5603
- // on the deploy's endpoints. Each row's `vault.net` says which network it answered.
5604
- net: z.enum(["mainnet", "testnet"]).optional().describe("Network whose vault projection the wallet rows read; defaults to the deploy's"),
6140
+ // C13 repair 2 — the network the read is on (the /w `?net=` door); defaults to the
6141
+ // deploy's NETWORK. One response, one network: the vault projection AND every chain
6142
+ // balance row read on it (before 2026-11-09 the chain rows stayed on the deploy's
6143
+ // endpoints, so a testnet deploy answered Sepolia's 0 beside mainnet money).
6144
+ net: z.enum(["mainnet", "testnet"]).optional().describe("Network every balance and vault row is read on; defaults to the deploy's. Ask mainnet for real money on a testnet deploy"),
5605
6145
  }),
5606
6146
  response: () => z.object({
5607
6147
  workspace: z.string().optional(),
5608
6148
  actor: z.string().optional(),
6149
+ network: z.enum(["mainnet", "testnet"]).optional().describe("The one network every balance row below was read on"),
5609
6150
  credits: z.number().optional(),
5610
6151
  wallets: z.array(z.record(z.string(), z.unknown())).optional(),
5611
6152
  spendCeiling: z.object({
5612
6153
  limitCredits: z.number(), spentCredits: z.number(), remainingCredits: z.number(),
5613
6154
  }).nullable().optional(),
6155
+ // One row per chain per wallet: sui · evm · solana · btc, plus `hyperliquid` for every
6156
+ // EVM address (an EVM address IS a Hyperliquid account; its money lives only in the
6157
+ // exchange's info API). `balance` is whole units; null = unread, never '0'.
5614
6158
  balances: z.array(z.object({
5615
6159
  actor: z.string(), chain: z.string(), address: z.string(), balance: z.string().nullable(),
6160
+ network: z.enum(["mainnet", "testnet"]).optional().describe("The network this row was read on"),
6161
+ unit: z.string().optional().describe("The unit of `balance` when not the chain's native coin — hyperliquid rows: USDC (spot total)"),
6162
+ perps: z.object({ accountValue: z.string(), withdrawable: z.string() }).optional().describe("hyperliquid rows: perps account value in USD, never summed with spot"),
6163
+ spot: z.array(z.object({ coin: z.string(), total: z.string(), hold: z.string() })).optional().describe("hyperliquid rows: every non-zero spot coin"),
5616
6164
  })).optional(),
5617
6165
  addresses: z.array(z.object({ actor: z.string(), chain: z.string(), address: z.string() })).optional(),
5618
6166
  // The per-agent PROJECTION of the on-chain ceiling (text/launch.md §0d).
@@ -5622,7 +6170,35 @@ export const RECEIVERS = {
5622
6170
  error: z.string().optional(),
5623
6171
  }),
5624
6172
  effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "none", auth: "member",
5625
- examples: [{}, { workspace: "acme" }, { workspace: "acme", actor: "agent:scout" }],
6173
+ examples: [{}, { workspace: "acme" }, { workspace: "acme", actor: "agent:scout" }, { workspace: "acme", net: "mainnet" }],
6174
+ }),
6175
+ // wallet:update — the owner's one number: how many credits an agent may spend a month.
6176
+ // Lowering (and pausing at 0) is open to the workspace's controllers and to the agent for
6177
+ // itself, never a sibling; raising needs a person's hand (a session, or the owner's own human key).
6178
+ "wallet:update": receiver({
6179
+ receiver: "wallet:update",
6180
+ surfaces: { mcp: { name: "wallet_limit" } },
6181
+ 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",
6182
+ request: () => z.object({
6183
+ actor: z.string().min(1).max(200).describe("The agent whose limit is set — its wallets row (kind 'agent') in `workspace`"),
6184
+ 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"),
6185
+ workspace: z.string().optional().describe("The workspace that holds the agent's wallet; defaults to the attested caller"),
6186
+ }),
6187
+ response: () => z.object({
6188
+ ok: z.boolean(),
6189
+ workspace: z.string().optional(),
6190
+ actor: z.string().optional(),
6191
+ monthlyCredits: z.number().optional(),
6192
+ spentCredits: z.number().optional().describe("What this period has used against the limit"),
6193
+ paused: z.boolean().optional(),
6194
+ changed: z.boolean().optional(),
6195
+ raised: z.boolean().optional(),
6196
+ closed: z.enum(["mark", "warn", "dissolve"]).optional(),
6197
+ detail: z.string().optional(),
6198
+ 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"),
6199
+ }),
6200
+ effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "none", auth: "member",
6201
+ examples: [{ actor: "scout", limit: 5000 }, { actor: "scout", limit: 0 }],
5626
6202
  }),
5627
6203
  "wallet:transactions": receiver({
5628
6204
  receiver: "wallet:transactions",
@@ -5631,12 +6207,14 @@ export const RECEIVERS = {
5631
6207
  request: () => z.object({
5632
6208
  workspace: z.string().optional().describe("Defaults to the attested caller's workspace"),
5633
6209
  limit: z.number().optional().describe("Rows to return; the handler caps at 500"),
6210
+ 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'"),
5634
6211
  }),
5635
6212
  response: () => z.object({
5636
6213
  transactions: z.array(z.object({
5637
6214
  ts: z.number(), rail: z.string(), direction: z.enum(["in", "out"]), counterparty: z.string(),
5638
6215
  amountCents: z.number(), currency: z.string(), ref: z.string(), status: z.string(),
5639
6216
  })).optional(),
6217
+ truncated: z.boolean().optional().describe("With `actor`: true when more rows exist than `limit` returned"),
5640
6218
  error: z.string().optional(),
5641
6219
  }),
5642
6220
  effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "none", auth: "member",
@@ -5659,6 +6237,7 @@ export const RECEIVERS = {
5659
6237
  from: z.string().optional().describe("Alias for `workspace` — the source the authority walk runs against"),
5660
6238
  transferId: z.string().optional().describe("Idempotency key; both legs share it as rail_ref"),
5661
6239
  memo: z.string().optional(),
6240
+ ...WORK_CONTRACT_FIELDS,
5662
6241
  }),
5663
6242
  response: () => z.object({
5664
6243
  ok: z.boolean(),
@@ -5670,7 +6249,7 @@ export const RECEIVERS = {
5670
6249
  }),
5671
6250
  // Zero-sum inside the credit ledger — real value, settled OFFCHAIN (never on
5672
6251
  // chain), reversible by a compensating transfer. Idempotent on `transferId`.
5673
- effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "offchain", auth: "manage_workspace",
6252
+ effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "offchain", auth: "manage_workspace", moves: "value", movesIn: ["workspace", "from"],
5674
6253
  examples: [{ to: "acme", amount: 500 }],
5675
6254
  }),
5676
6255
  // The caller signs and broadcasts the transfer CLIENT-SIDE and passes the
@@ -5694,6 +6273,7 @@ export const RECEIVERS = {
5694
6273
  userAddress: z.string().optional().describe("Sender address; defaults to `to`"),
5695
6274
  memo: z.string().optional(),
5696
6275
  product: z.string().optional().describe("Falls back to `memo`, then a generated transfer label"),
6276
+ ...WORK_CONTRACT_FIELDS,
5697
6277
  }),
5698
6278
  response: () => z.object({
5699
6279
  ok: z.boolean(),
@@ -5733,9 +6313,18 @@ export const RECEIVERS = {
5733
6313
  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)"),
5734
6314
  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)"),
5735
6315
  }).optional().describe("Whether this payment raised the payee's score, and if not, why"),
5736
- error: z.string().optional(),
5737
- }),
5738
- effect: "ask", cost: "variable", reversible: false, idempotent: false, settles: "onchain", auth: "manage_workspace",
6316
+ // The sponsored-gas cap (lib/sponsor-policy.ts): ONE pays the gas on a Sui USDC send, no markup,
6317
+ // up to 1,000 sends per wallet. Eligibility only — wallet:send records a transfer the client
6318
+ // already broadcast, so `paidBy` says who actually paid until a relayer exists.
6319
+ gas: z.object({
6320
+ sponsored: z.boolean().describe("true = this send was within the cap, so ONE is the one who pays its gas once a relayer runs; false = past the cap (or not a Sui USDC send): the wallet pays its own, and the send still worked"),
6321
+ remaining: z.number().describe("Sponsored sends this wallet has left AFTER this one"),
6322
+ markupBps: z.number().describe("Markup on the gas inside the cap: 0"),
6323
+ paidBy: z.literal("sender").describe("Who paid the gas on chain for this send. Always 'sender' today: no relayer exists yet"),
6324
+ }).optional().describe("Whether ONE pays this send's gas, and how many sponsored sends the wallet has left"),
6325
+ error: z.string().optional(),
6326
+ }),
6327
+ effect: "ask", cost: "variable", reversible: false, idempotent: false, settles: "onchain", auth: "manage_workspace", moves: "value", movesIn: ["workspace", "from"],
5739
6328
  examples: [{ to: "0xabc", chain: "SUI", amount: 5, paymentTx: "8xKvQ1" }],
5740
6329
  }),
5741
6330
  // text/key.md deliverable 8 — bound what an agent HOLDS. Tony, 2026-10-06:
@@ -6074,6 +6663,337 @@ export const RECEIVERS = {
6074
6663
  { workspace: "acme", actor: "agent:scout", amountCents: 2500, currency: "usd" },
6075
6664
  ],
6076
6665
  }),
6666
+ // swap:quote + swap:get (text/swap-plan.md) — any coin to any coin, and straight into
6667
+ // Hyperliquid, through NEAR Intents 1Click's deposit-address model. The server QUOTES and
6668
+ // READS; the person's own key sends to the deposit address, client-side, after the client
6669
+ // has read the quote back from 1Click directly (R16). ONE never holds a key or a cent, so
6670
+ // neither door carries `moves` (value-moving-parity.test.ts records why). 1Click is mainnet
6671
+ // only: every answer says network:'mainnet', and net:'testnet' is refused by name.
6672
+ "swap:quote": receiver({
6673
+ receiver: "swap:quote",
6674
+ surfaces: { mcp: true },
6675
+ 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",
6676
+ request: () => z.object({
6677
+ 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"),
6678
+ 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"),
6679
+ 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"),
6680
+ exact: z.enum(["in", "out"]).optional().describe("'in' (default): spend exactly amount · 'out': receive exactly amount; slippage applies to the input"),
6681
+ 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"),
6682
+ recipient: z.string().optional().describe("Destination address. Absent = your own address on the destination chain. Someone else's needs toOther:true"),
6683
+ 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"),
6684
+ 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"),
6685
+ slippageBps: z.number().optional().describe("Max slippage in basis points, an integer 1–500; default 100 (1%). Out of range is refused bad_slippage"),
6686
+ net: z.string().optional().describe("1Click is mainnet only: 'testnet' is refused by name (oneclick_mainnet_only), never answered with mainnet"),
6687
+ }),
6688
+ response: () => z.object({
6689
+ ok: z.boolean().describe("true = a quote; false = a named refusal in error"),
6690
+ error: z.string().optional().describe("unknown_asset · ambiguous_asset · not_a_destination · hyperliquid_origin_unsupported · hyperliquid_region_blocked · 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"),
6691
+ detail: z.string().optional().describe("1Click's own message on an upstream refusal, verbatim"),
6692
+ 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)"),
6693
+ assets: z.array(SWAP_ASSET).optional().describe("unknown_asset: the whole table (never paged)"),
6694
+ 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"),
6695
+ network: z.string().describe("Always 'mainnet' — real chains, real money"),
6696
+ dry: z.boolean().optional().describe("Echo: true = price only"),
6697
+ from: SWAP_ASSET.optional().describe("Resolved origin"),
6698
+ to: SWAP_ASSET.optional().describe("Resolved destination"),
6699
+ route: z.object({
6700
+ via: z.string().describe("'1click' (NEAR Intents 1Click) — v1's only route"),
6701
+ steps: z.array(z.string()).describe("Human steps, in order"),
6702
+ credits: z.string().optional().describe("Hyperliquid only: 'perps' — USDC lands in the perps balance"),
6703
+ }).optional().describe("How the coins get there"),
6704
+ depositAddress: z.string().optional().describe("Live only: the key swap:get takes. Send exactly send.amount here — verify it with 1Click first"),
6705
+ amountIn: z.string().optional().describe("Decimal you send"),
6706
+ minAmountIn: z.string().optional().describe("exact 'out': lowest input accepted, decimal"),
6707
+ amountOut: z.string().optional().describe("Decimal you receive (withdraw fee already taken)"),
6708
+ minAmountOut: z.string().optional().describe("Decimal floor after slippage"),
6709
+ amountInUsd: z.string().optional().describe("USD value in, per 1Click"),
6710
+ amountOutUsd: z.string().optional().describe("USD value out, per 1Click"),
6711
+ costUsd: z.string().optional().describe("amountInUsd − amountOutUsd, plus a possible Hyperliquid activation when it applies"),
6712
+ fees: z.array(z.object({
6713
+ kind: z.string().describe("protocol (1Click) · app (ONE) · withdraw (destination chain) · refund (only on a refund)"),
6714
+ bps: z.number().optional().describe("Basis points, for protocol/app"),
6715
+ amount: z.string().optional().describe("Decimal amount"),
6716
+ asset: z.string().optional().describe("Alias the amount counts in"),
6717
+ note: z.string().optional().describe("One line for a human"),
6718
+ })).optional().describe("Every fee read from the live quote — none hardcoded"),
6719
+ timeEstimateSec: z.number().optional().describe("Seconds after the deposit confirms"),
6720
+ refundAfter: z.string().optional().describe("ISO: if not filled by now, refunds begin. Never send after this"),
6721
+ addressExpires: z.string().optional().describe("Live only, ISO: deposit address goes inactive"),
6722
+ quotedAt: z.string().optional().describe("1Click's timestamp — clients correct their clock skew with it before the deadline check"),
6723
+ recipient: z.string().optional().describe("Where the coins go — echoed"),
6724
+ refundTo: z.string().optional().describe("Where a refund goes — always your own address on the source chain"),
6725
+ ownership: z.object({
6726
+ recipient: z.string().describe("proven (signature) · registered (your row, session only) · other (toOther) · placeholder (dry)"),
6727
+ refundTo: z.string().describe("proven · registered · placeholder"),
6728
+ note: z.string().describe("Which row each address came from and what was and was not verified, in one sentence"),
6729
+ }).optional().describe("Whose addresses these are, and how ONE knows"),
6730
+ send: z.object({
6731
+ how: z.string().describe("browser · external"),
6732
+ to: z.string().describe("The deposit address"),
6733
+ amountBase: z.string().describe("Exact base units"),
6734
+ amount: z.string().describe("Same, as a decimal"),
6735
+ asset: z.string().describe("Alias to send"),
6736
+ chain: z.string().describe("Chain to send on — the wrong chain loses funds"),
6737
+ uri: z.string().optional().describe("Wallet link: bitcoin: (BIP21), solana:, or ethereum: (EIP-681); scan or tap in any wallet"),
6738
+ refundsTo: z.string().describe("Where a failed swap refunds, and how to recover it, in one sentence"),
6739
+ }).optional().describe("Live only: the exact send instruction — plain transfer, self-custody wallet, no bridge"),
6740
+ hyperliquid: z.object({
6741
+ checked: z.boolean().describe("false = the account read failed; treated as possibly new"),
6742
+ firstDeposit: z.boolean().describe("true = empty account; Hyperliquid MAY take a one-time ~1 USDC activation (unverified)"),
6743
+ }).optional().describe("Hyperliquid destination with YOUR recipient only — absent for placeholders"),
6744
+ keyed: z.boolean().optional().describe("true = ONE's partner key was used (live only); false = keyless fee schedule"),
6745
+ 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)"),
6746
+ link: z.string().optional().describe("Absolute one.ie URL: dry = a prefilled /swap form a person can sign from · live = its status page"),
6747
+ next: z.string().describe("One sentence: what to do now. An agent cannot sign — give the person the link, or the exact send line"),
6748
+ }),
6749
+ examples: [
6750
+ { from: "USDC@base", to: "hl", amount: "10" },
6751
+ { from: "BTC", to: "hyperliquid", amount: "0.001" },
6752
+ { from: "SUI", to: "ETH", amount: "25" },
6753
+ ],
6754
+ effect: "ask", cost: "free", reversible: true, idempotent: false, settles: "none", auth: "public",
6755
+ }),
6756
+ "swap:get": receiver({
6757
+ receiver: "swap:get",
6758
+ surfaces: { mcp: true },
6759
+ summary: "Track a swap by its deposit address until it lands or refunds, and read any Hyperliquid account's balance",
6760
+ request: () => z.object({
6761
+ depositAddress: z.string().optional().describe("The deposit address swap:quote returned"),
6762
+ depositMemo: z.string().optional().describe("Memo, for memo chains only"),
6763
+ txHash: z.string().optional().describe("Your deposit tx hash — forwarded to 1Click to speed matching. NOT a verification; status stays the truth"),
6764
+ hyperliquid: z.string().optional().describe("A 0x address: also read its Hyperliquid balance (perps + spot, never summed)"),
6765
+ 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"),
6766
+ }),
6767
+ response: () => z.object({
6768
+ ok: z.boolean().describe("true = read; false = named refusal"),
6769
+ error: z.string().optional().describe("nothing_to_read · address_unknown · bad_address · bad_tx_hash · oneclick_timeout · oneclick_unavailable · oneclick_error · hyperliquid_unavailable · hyperliquid_region_blocked"),
6770
+ detail: z.string().optional().describe("1Click's own message on an upstream refusal, verbatim"),
6771
+ network: z.string().describe("'mainnet' for the swap"),
6772
+ status: z.string().optional().describe("PENDING_DEPOSIT · KNOWN_DEPOSIT_TX · INCOMPLETE_DEPOSIT · PROCESSING · SUCCESS · REFUNDED · FAILED"),
6773
+ terminal: z.boolean().optional().describe("true at SUCCESS · REFUNDED · FAILED — stop polling"),
6774
+ explain: z.string().optional().describe("One human sentence for this status (INCOMPLETE_DEPOSIT: less than quoted arrived; refunded minus refundFee)"),
6775
+ submitted: z.boolean().optional().describe("txHash was forwarded to 1Click — not verified"),
6776
+ from: z.string().optional().describe("Origin alias (or raw assetId if not in the table)"),
6777
+ to: z.string().optional().describe("Destination alias (or raw assetId)"),
6778
+ recipient: z.string().optional().describe("Destination address, from 1Click's stored quote"),
6779
+ refundTo: z.string().optional().describe("Refund address, from 1Click's stored quote"),
6780
+ amountIn: z.string().optional().describe("Decimal deposited"),
6781
+ amountOut: z.string().optional().describe("Decimal delivered"),
6782
+ amountOutUsd: z.string().optional().describe("USD delivered"),
6783
+ refundedAmount: z.string().optional().describe("Decimal refunded"),
6784
+ refundReason: z.string().optional().describe("1Click's refund reason"),
6785
+ originTxs: z.array(SWAP_TX).optional().describe("Deposit-side txs"),
6786
+ destinationTxs: z.array(SWAP_TX).optional().describe("Delivery-side txs"),
6787
+ updatedAt: z.string().optional().describe("1Click timestamp"),
6788
+ refundAfter: z.string().optional().describe("ISO, from the stored quote — no send instruction is valid after it"),
6789
+ addressExpires: z.string().optional().describe("ISO, from the stored quote"),
6790
+ hyperliquid: z.object({
6791
+ address: z.string().describe("Account read"),
6792
+ network: z.string().describe("mainnet · testnet — always mainnet for the post-SUCCESS read"),
6793
+ perps: z.object({
6794
+ accountValue: z.string().describe("Decimal USD"),
6795
+ withdrawable: z.string().describe("Decimal USD"),
6796
+ }).describe("clearinghouseState"),
6797
+ spot: z.array(z.object({
6798
+ coin: z.string().describe("e.g. USDC, UBTC"),
6799
+ total: z.string().describe("Decimal"),
6800
+ hold: z.string().describe("Decimal on hold"),
6801
+ })).describe("spotClearinghouseState balances, every non-zero coin (never paged)"),
6802
+ firstDeposit: z.boolean().describe("true = empty account; Hyperliquid MAY take a one-time ~1 USDC activation (unverified)"),
6803
+ note: z.string().describe("Not summed: unified/portfolio-margin accounts show everything in spot"),
6804
+ }).optional().describe("Balance of the hyperliquid address asked for, or of the recipient after a SUCCESS into Hyperliquid"),
6805
+ next: z.string().describe("One sentence: what happens next or what to do"),
6806
+ }),
6807
+ examples: [
6808
+ { depositAddress: "0xd63c8F578F0a5541c14bFc9AFbC4AdEbE0250Ef2" },
6809
+ { hyperliquid: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" },
6810
+ ],
6811
+ effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "none", auth: "public",
6812
+ }),
6813
+ // hyperliquid:get · hyperliquid:list · hyperliquid:quote (text/hyperliquid-api.md) — the
6814
+ // READ side of a Hyperliquid account through the public info API (no key), and the PREPARE
6815
+ // side of acting: unsigned action + EIP-712 typed data the caller's OWN key signs and posts to
6816
+ // Hyperliquid itself. The server holds no key and signs nothing (R19), so no door carries
6817
+ // `moves` (value-moving-parity.test.ts records why). A stranger's address is public data:
6818
+ // readable, labelled mine:false. A failed read is null, never 0; a short list says so.
6819
+ "hyperliquid:get": receiver({
6820
+ receiver: "hyperliquid:get",
6821
+ surfaces: { mcp: true },
6822
+ summary: "Read a Hyperliquid account: perps + spot balances (never summed), open positions with entry/mark/liquidation/PnL, and open orders. Defaults to your own EVM address",
6823
+ request: () => z.object({
6824
+ address: z.string().optional().describe("0x address to read. Absent = your one EVM address from your wallet rows (needs a signed-in caller). Anyone's is readable — public data, answered mine:false"),
6825
+ net: z.string().optional().describe("'mainnet' (default — where real Hyperliquid funds live) or 'testnet'"),
6826
+ }),
6827
+ response: () => z.object({
6828
+ ok: z.boolean().describe("true = read; false = a named refusal in error"),
6829
+ error: z.string().optional().describe("bad_net · bad_address · address_required · address_unknown · ambiguous_address · hyperliquid_unavailable · hyperliquid_region_blocked"),
6830
+ options: z.array(z.string()).optional().describe("ambiguous_address: your EVM addresses — pass one as address"),
6831
+ network: z.string().describe("mainnet · testnet — the chain every number is from"),
6832
+ address: z.string().optional().describe("The account read"),
6833
+ mine: z.boolean().optional().describe("true = one of YOUR addresses (attested wallet rows or a signed proof); false = someone else's, or an unattested caller"),
6834
+ source: z.string().optional().describe("Which row made it yours, or why it is not"),
6835
+ perps: z.object({ accountValue: z.string(), withdrawable: z.string() }).optional().describe("clearinghouseState, decimal USD"),
6836
+ spot: z.array(z.object({ coin: z.string(), total: z.string(), hold: z.string() })).optional().describe("Every non-zero spot balance (never paged)"),
6837
+ margin: z.object({
6838
+ totalMarginUsed: z.string().nullable(),
6839
+ totalNtlPos: z.string().nullable(),
6840
+ maintenance: z.string().nullable(),
6841
+ }).optional().describe("Perps margin summary; null = Hyperliquid sent no value"),
6842
+ positions: z.array(z.object({
6843
+ coin: z.string(),
6844
+ side: z.string().describe("long · short"),
6845
+ size: z.string().describe("Absolute size in coin units"),
6846
+ entryPx: z.string().nullable(),
6847
+ markPx: z.string().nullable().describe("DERIVED: positionValue ÷ size (clearinghouseState carries no mark field)"),
6848
+ positionValue: z.string().nullable(),
6849
+ unrealizedPnl: z.string().nullable(),
6850
+ returnOnEquity: z.string().nullable(),
6851
+ liquidationPx: z.string().nullable().describe("null = Hyperliquid names no liquidation price — never 0"),
6852
+ leverage: z.object({ type: z.string(), value: z.number().nullable() }),
6853
+ marginUsed: z.string().nullable(),
6854
+ funding: z.object({ sinceOpen: z.string().nullable(), allTime: z.string().nullable() }).describe("Cumulative funding paid (+) or received (−)"),
6855
+ })).optional().describe("Every open perps position (never paged)"),
6856
+ orders: z.array(z.object({
6857
+ coin: z.string(),
6858
+ side: z.string().nullable().describe("buy · sell"),
6859
+ limitPx: z.string().nullable(),
6860
+ size: z.string().nullable(),
6861
+ origSize: z.string().nullable(),
6862
+ oid: z.number().nullable().describe("The id hyperliquid:quote {action:'cancel'} takes"),
6863
+ timestamp: z.number().nullable(),
6864
+ reduceOnly: z.boolean(),
6865
+ })).nullable().optional().describe("Open orders; null = the read failed (named in unread), never an empty book"),
6866
+ firstDeposit: z.boolean().optional().describe("true = empty account; Hyperliquid MAY take a one-time ~1 USDC activation (unverified)"),
6867
+ unread: z.array(z.string()).optional().describe("Parts that failed to read and are null"),
6868
+ note: z.string().optional(),
6869
+ next: z.string().describe("One sentence: what to do now"),
6870
+ }),
6871
+ examples: [
6872
+ {},
6873
+ { address: "0x18cA3dB9436111C5A5bEc7A0F13E806fa324080E" },
6874
+ { address: "0x18cA3dB9436111C5A5bEc7A0F13E806fa324080E", net: "testnet" },
6875
+ ],
6876
+ effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "none", auth: "public",
6877
+ }),
6878
+ "hyperliquid:list": receiver({
6879
+ receiver: "hyperliquid:list",
6880
+ surfaces: { mcp: true },
6881
+ summary: "List Hyperliquid fills (newest first, capped — says so), funding payments over a window, or the asset table (perps meta + spot pairs, szDecimals, the asset id an order carries)",
6882
+ request: () => z.object({
6883
+ of: z.enum(["fills", "funding", "assets"]).describe("fills · funding · assets"),
6884
+ address: z.string().optional().describe("fills/funding: 0x address. Absent = yours (signed in). Anyone's is readable, answered mine:false"),
6885
+ net: z.string().optional().describe("'mainnet' (default) or 'testnet'"),
6886
+ limit: z.number().optional().describe("fills/funding: newest N, 1–500, default 50 · assets: 1–1000, default 100"),
6887
+ since: z.number().optional().describe("funding: millisecond timestamp the window starts at; default 7 days back. Echoed"),
6888
+ market: z.enum(["perps", "spot", "all"]).optional().describe("assets: which table; default all"),
6889
+ query: z.string().optional().describe("assets: case-insensitive filter on the name, e.g. 'BTC' or 'PURR'"),
6890
+ }),
6891
+ response: () => z.object({
6892
+ ok: z.boolean(),
6893
+ error: z.string().optional().describe("bad_net · bad_of · bad_limit · bad_since · bad_market · bad_address · address_required · address_unknown · ambiguous_address · hyperliquid_unavailable · hyperliquid_region_blocked"),
6894
+ options: z.array(z.string()).optional(),
6895
+ network: z.string(),
6896
+ of: z.string().optional(),
6897
+ address: z.string().optional(),
6898
+ mine: z.boolean().optional(),
6899
+ source: z.string().optional(),
6900
+ fills: z.array(z.object({
6901
+ coin: z.string(), side: z.string().nullable(), px: z.string().nullable(), size: z.string().nullable(),
6902
+ dir: z.string().nullable().describe("Open Long · Close Short · Buy · Sell …"), closedPnl: z.string().nullable(),
6903
+ fee: z.string().nullable(), feeToken: z.string().nullable(), time: z.number().nullable(),
6904
+ hash: z.string().nullable(), oid: z.number().nullable(), crossed: z.boolean().nullable(),
6905
+ })).optional().describe("Newest first"),
6906
+ funding: z.array(z.object({
6907
+ time: z.number().nullable(), coin: z.string(), usdc: z.string().nullable().describe("− = paid, + = received"),
6908
+ size: z.string().nullable(), fundingRate: z.string().nullable(),
6909
+ })).optional().describe("Newest first"),
6910
+ since: z.number().optional().describe("funding: the window start used"),
6911
+ assets: z.array(z.object({
6912
+ market: z.string().describe("perps · spot"),
6913
+ name: z.string().describe("BTC · PURR/USDC — spot names resolved from token names"),
6914
+ hlName: z.string().describe("Hyperliquid's own name — '@107' for most spot pairs"),
6915
+ asset: z.number().describe("The asset id an order carries: perps index, or 10000 + spot index"),
6916
+ szDecimals: z.number().nullable().describe("Size decimals an order must respect"),
6917
+ maxLeverage: z.number().nullable(),
6918
+ delisted: z.boolean(),
6919
+ tokens: z.array(z.object({ name: z.string(), index: z.number(), szDecimals: z.number().nullable(), weiDecimals: z.number().nullable() })).optional(),
6920
+ })).optional(),
6921
+ page: z.object({
6922
+ returned: z.number(),
6923
+ upstream: z.number().optional().describe("fills/funding: how many Hyperliquid sent"),
6924
+ total: z.number().optional().describe("assets: how many matched"),
6925
+ limit: z.number(),
6926
+ capped: z.boolean().describe("true = this answer is SHORT — more exist than returned"),
6927
+ upstreamCapped: z.boolean().optional().describe("true = Hyperliquid itself stopped at its ceiling (2000 fills · 500 funding rows)"),
6928
+ }).optional().describe("What this page says about itself — a short answer says it is short"),
6929
+ next: z.string(),
6930
+ }),
6931
+ examples: [
6932
+ { of: "fills" },
6933
+ { of: "funding", since: 1794000000000 },
6934
+ { of: "assets", query: "BTC" },
6935
+ ],
6936
+ effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "none", auth: "public",
6937
+ }),
6938
+ "hyperliquid:quote": receiver({
6939
+ receiver: "hyperliquid:quote",
6940
+ surfaces: { mcp: true },
6941
+ summary: "Prepare a Hyperliquid action — transfer, order, cancel, withdraw — as the UNSIGNED action + EIP-712 typed data YOUR key signs and posts to Hyperliquid. ONE signs nothing. An agent moving value for someone else needs its owner's co-sign",
6942
+ request: () => z.object({
6943
+ action: z.enum(["transfer", "order", "cancel", "withdraw"]).describe("transfer (USDC/spot token to an address, or spot↔perps with between) · order · cancel · withdraw (to an EVM address on Arbitrum)"),
6944
+ address: z.string().optional().describe("The Hyperliquid account that acts. Absent = yours. It must be yours: only its key can sign"),
6945
+ net: z.string().optional().describe("'mainnet' (default) or 'testnet'"),
6946
+ to: z.string().optional().describe("transfer/withdraw: destination 0x address; withdraw defaults to the acting address"),
6947
+ amount: z.string().optional().describe("transfer/withdraw: decimal string, e.g. '5' — never a number"),
6948
+ token: z.string().optional().describe("transfer: spot token name, default USDC"),
6949
+ between: z.enum(["spot->perps", "perps->spot"]).optional().describe("transfer: move between your own spot and perps balances instead of to an address"),
6950
+ coin: z.string().optional().describe("order/cancel: the asset name from hyperliquid:list {of:'assets'}"),
6951
+ side: z.enum(["buy", "sell"]).optional().describe("order"),
6952
+ size: z.string().optional().describe("order: decimal string, at most the asset's szDecimals"),
6953
+ price: z.string().optional().describe("order: limit price as a decimal string; absent = market (IOC at a slippage-bounded price)"),
6954
+ reduceOnly: z.boolean().optional().describe("order: only reduce an open position"),
6955
+ tif: z.enum(["Gtc", "Ioc", "Alo"]).optional().describe("order: time in force — default Gtc with a price, Ioc without one; a market order (no price) is Ioc only, anything else is refused bad_order"),
6956
+ oid: z.number().optional().describe("cancel: the order id from hyperliquid:get orders"),
6957
+ }),
6958
+ response: () => z.object({
6959
+ ok: z.boolean().describe("true = unsigned action prepared; false = a named refusal"),
6960
+ error: z.string().optional().describe("bad_net · bad_action · bad_amount · bad_destination · bad_between · bad_order · bad_oid · sign_in_required · bad_address · address_unknown · ambiguous_address · address_not_yours · needs_cosign · core_not_landed · hyperliquid_region_blocked"),
6961
+ detail: z.string().optional(),
6962
+ options: z.array(z.string()).optional(),
6963
+ network: z.string(),
6964
+ action: z.string().optional(),
6965
+ address: z.string().optional().describe("The account that acts"),
6966
+ mine: z.boolean().optional(),
6967
+ prepared: z.record(z.string(), z.unknown()).optional().describe("The checked, normalised request the typed data is built from"),
6968
+ unsigned: z.object({
6969
+ action: z.record(z.string(), z.unknown()).describe("The Hyperliquid /exchange action object, exactly"),
6970
+ nonce: z.number().describe("Millisecond nonce; Hyperliquid refuses a reused or stale one"),
6971
+ signer: z.string().describe("user (EIP-712 user-signed: transfer · withdraw) · l1 (phantom-agent: order · cancel)"),
6972
+ typedData: z.object({
6973
+ domain: z.record(z.string(), z.unknown()),
6974
+ types: z.record(z.string(), z.unknown()),
6975
+ primaryType: z.string(),
6976
+ message: z.record(z.string(), z.unknown()),
6977
+ }).describe("Pass to eth_signTypedData_v4 with the acting address's key, then POST {action, nonce, signature} to Hyperliquid /exchange"),
6978
+ }).optional().describe("Present only when ok — the server never signs or sends it"),
6979
+ cosign: z.object({
6980
+ required: z.boolean(),
6981
+ who: z.string(),
6982
+ why: z.string(),
6983
+ proposal: z.record(z.string(), z.unknown()).describe("What the owner is asked to approve"),
6984
+ notified: z.boolean().describe("false today: human:notify posts only from a workflow run — carry the proposal in a path with a human step"),
6985
+ notifyNote: z.string(),
6986
+ }).optional().describe("needs_cosign: an agent key asked to move value on an account, or to a destination, that is not its own"),
6987
+ next: z.string().describe("One sentence: what to do now"),
6988
+ }),
6989
+ examples: [
6990
+ { action: "transfer", between: "spot->perps", amount: "5" },
6991
+ { action: "order", coin: "ETH", side: "buy", size: "0.01", price: "2000" },
6992
+ { action: "cancel", coin: "ETH", oid: 599650185703 },
6993
+ { action: "withdraw", amount: "5" },
6994
+ ],
6995
+ effect: "ask", cost: "free", reversible: true, idempotent: false, settles: "none", auth: "public",
6996
+ }),
6077
6997
  // wallet:portfolio — the authority walk projected onto wallet rows. One call
6078
6998
  // answers "what does my whole estate hold", which no client could ask before:
6079
6999
  // every wallet read was scoped to one workspace at a time.
@@ -6170,6 +7090,25 @@ export const RECEIVERS = {
6170
7090
  effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "owner",
6171
7091
  examples: [{ workspace: "kiln" }],
6172
7092
  }),
7093
+ // The only writer of owners.prices_confirmed_at, the column goLive's confirmed_prices gap
7094
+ // reads. Body: resolvers/storefront/shop-live.ts (shopApprove).
7095
+ "shop:approve": receiver({
7096
+ receiver: "shop:approve",
7097
+ summary: "Confirm that the store's price list is the owner's own, stamping the time. shop:go-live refuses with confirmed_prices until this has been called, and a price or variant created or changed after it is unconfirmed again — call it once more after an edit. Owner-only.",
7098
+ request: () => z.object({
7099
+ workspace: z.string().optional().describe("Which store. NOT an authority claim — the attested caller must control it (callerControlsWorkspace). Absent = the caller's own."),
7100
+ slug: z.string().optional().describe("Alias of `workspace`."),
7101
+ }),
7102
+ response: () => z.object({
7103
+ ok: z.boolean().describe("TRUE when the confirmation was stamped."),
7104
+ workspace: z.string().optional(),
7105
+ prices_confirmed_at: z.number().int().optional().describe("Unix seconds stamped on the store."),
7106
+ active_prices: z.number().int().optional().describe("How many active prices the store has now; 0 still leaves the confirmed_prices gap open."),
7107
+ error: z.string().optional().describe("`forbidden` · `no_db` · `no_store`."),
7108
+ }),
7109
+ effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "owner",
7110
+ examples: [{ workspace: "kiln" }],
7111
+ }),
6173
7112
  "shop:stop-live": receiver({
6174
7113
  receiver: "shop:stop-live",
6175
7114
  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.",
@@ -6204,6 +7143,7 @@ export const RECEIVERS = {
6204
7143
  }))
6205
7144
  .optional()
6206
7145
  .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."),
7146
+ sourceUrl: z.string().optional().describe("A URL the seller gave — their shop, home page or one product page. Before the catalogue step the build reads that site and makes its REAL product as a draft: the URL itself when it is a product page, else the best seller (an explicit best-seller sort), else the first product the home page features, else the first in the sitemap — `imported.picked` names which. Title, description, price, currency, stated variants and every image (copied into R2, never hotlinked). When it lands, no product is invented around it and the hero is its photo. Never a guessed price: no stated price → `imported.needsPrice` and the model catalogue runs as before. SSRF-guarded, byte-capped, at most one Cloudflare render, three imports per workspace a day."),
6207
7147
  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."),
6208
7148
  currency: z.string().optional().describe("ISO 4217, default USD."),
6209
7149
  brand: z
@@ -6241,8 +7181,10 @@ export const RECEIVERS = {
6241
7181
  steps: z
6242
7182
  .array(z.object({ step: z.string(), ok: z.boolean(), reason: z.string().optional(), detail: z.record(z.string(), z.unknown()).optional() }))
6243
7183
  .optional()
6244
- .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."),
7184
+ .describe("storefront · import (with sourceUrl) · 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."),
6245
7185
  created: z.record(z.string(), z.number()).optional().describe("What THIS call wrote. All zero on a repeat call."),
7186
+ imported: z.record(z.string(), z.unknown()).nullable().optional().describe("With `sourceUrl`: the import receipt — imported, pid, url (the product link), picked (product_page · best_seller · home_featured · sitemap_first), platform, tier (fetch · cloudflare), fetches, renders, images {found, copied, failed}, needsPrice, reason. Null without `sourceUrl`."),
7187
+ productUrl: z.string().nullable().optional().describe("The imported product's storefront link — buyable once the store is approved (TEST mode until go-live)."),
6246
7188
  }),
6247
7189
  effect: "ask", cost: "variable", reversible: false, idempotent: true, auth: "member",
6248
7190
  examples: [{ workspace: "tea-test", description: "A small loose-leaf tea shop in Galway selling single-origin teas, blends and teaware." }],
@@ -6404,6 +7346,8 @@ export const RECEIVERS = {
6404
7346
  // ══════════════════════════════════════════════════════════════════════════
6405
7347
  "blocks:list": receiver({
6406
7348
  receiver: "blocks:list",
7349
+ // 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.
7350
+ auth: "public",
6407
7351
  surfaces: { mcp: true },
6408
7352
  summary: "Discover the page blocks that exist — name, category, surface, description and variant list, filterable and paged",
6409
7353
  request: () => z.object({
@@ -6450,6 +7394,8 @@ export const RECEIVERS = {
6450
7394
  }),
6451
7395
  "blocks:schema": receiver({
6452
7396
  receiver: "blocks:schema",
7397
+ // 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).
7398
+ auth: "public",
6453
7399
  surfaces: { mcp: true },
6454
7400
  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",
6455
7401
  request: () => z.object({
@@ -6583,6 +7529,8 @@ export const RECEIVERS = {
6583
7529
  }),
6584
7530
  "pages:templates": receiver({
6585
7531
  receiver: "pages:templates",
7532
+ // 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).
7533
+ auth: "public",
6586
7534
  surfaces: { mcp: true },
6587
7535
  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",
6588
7536
  request: () => z.object({
@@ -6620,8 +7568,9 @@ export const RECEIVERS = {
6620
7568
  puckData: z.object({ content: z.array(z.record(z.string(), z.unknown())), root: z.record(z.string(), z.unknown()).optional() }).passthrough().optional()
6621
7569
  .describe("Full replacement Puck data — any registry block. Top-level props are normalised and ids stamped exactly as `pages:create` does. Refused beside `sections`."),
6622
7570
  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`."),
7571
+ 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."),
6623
7572
  }),
6624
- 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() }),
7573
+ 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() }),
6625
7574
  effect: "ask", cost: "free", reversible: true, idempotent: false, auth: "member",
6626
7575
  }),
6627
7576
  "pages:list": receiver({
@@ -7096,6 +8045,34 @@ export const RECEIVERS = {
7096
8045
  effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
7097
8046
  }),
7098
8047
  // ── the two block-tree reads ────────────────────────────────────────────────
8048
+ // ── path: — the mark verb as a receiver (task:01a1cdecb53376a271c7e405) ──
8049
+ // `mark` was an HTTP route only (/api/mark/:edge), so a workflow step could not
8050
+ // reach it. This is a thin door over the SAME function the route calls
8051
+ // (substrate.mark → the TypeDB path + its D1 mirror) — one store, one code path.
8052
+ // Endpoints are steps of a workflow BY NAME; a step's id is its thing's tid: a
8053
+ // workflow is a path (text/architecture.md), and a beat is a step.
8054
+ "path:mark": receiver({
8055
+ receiver: "path:mark",
8056
+ auth: "manage_paths",
8057
+ summary: "Mark the path between two steps of a workflow — strength on the edge from one step's thing to another's, through the same substrate.mark the /api/mark route uses (TypeDB path + D1 mirror). Steps are named; a step's id is its thing's tid (apply-diff projects every step; workflow:update { project: true } backfills). The caller must control the workflow's workspace; a workflow you do not control answers not_found. Contract (text/contracts.md § mark): pre both endpoints resolve and strength ≥ 0; post the edge reads back with strength grown by at most `strength`.",
8058
+ effect: "ask",
8059
+ cost: "free",
8060
+ idempotent: false,
8061
+ request: () => z.object({
8062
+ workflow: z.string().describe("The workflow id whose steps the edge joins — the path the edge belongs to"),
8063
+ from: z.string().describe("The step the move came from, by its name in that workflow (e.g. a beat's name, 'start' for the first)"),
8064
+ to: z.string().describe("The step the move arrived at, by its name in that workflow"),
8065
+ strength: z.number().min(0).max(10).optional().describe("How much to deposit, 0–10. Default 1"),
8066
+ }),
8067
+ response: () => z.object({
8068
+ ok: z.boolean(),
8069
+ source: z.string().optional().describe("The from step's thing tid"),
8070
+ target: z.string().optional().describe("The to step's thing tid"),
8071
+ strength: z.number().optional().describe("The edge's strength after the mark, read back"),
8072
+ delta: z.number().optional().describe("How much it grew — never more than the requested strength"),
8073
+ error: z.string().optional().describe("Why it was refused, by name: missing · bad_strength · self_edge · not_found · unknown_step:<name> · thing_missing:<tid> (run workflow:update with project:true) · graph_unavailable:<why> · post_failed"),
8074
+ }),
8075
+ }),
7099
8076
  // ── nav: — Next is one function (text/navigation.md card 7) ──────────────
7100
8077
  "nav:next": receiver({
7101
8078
  receiver: "nav:next",
@@ -7286,6 +8263,216 @@ export const RECEIVERS = {
7286
8263
  response: () => z.object({ ok: z.boolean(), chars: z.number().optional(), error: z.string().optional() }),
7287
8264
  effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
7288
8265
  }),
8266
+ // The AI front desk playbook, for any business (Vespio C2, text/vespio-plan.md):
8267
+ // the mover:agent-context bridge generalised, plus qualifying as a condition at
8268
+ // booking:create. Body in one.ie/web/src/lib/front-desk/write.ts.
8269
+ "name:list": receiver({
8270
+ receiver: "name:list",
8271
+ summary: "Is this workspace name free? A free read over the one namespace (text/workspace-names-plan.md): answers available, or the reason it is not (bad_shape, uuid_shaped, reserved, blocked, taken, is_a_workspace, is_an_actor). An anonymous caller gets taken in place of is_a_workspace and is_an_actor, so it learns only taken or free; a signed-in caller sees why; names are public URLs. Was name:check (renamed 2026-11-19 onto the verb vocabulary; the old name answers for one release)",
8272
+ request: () => z.object({
8273
+ available: z.string().optional().describe("The name to check, as it would appear in one.ie/u/<name>: lowercase letters, digits and single dashes, 3 to 40 characters"),
8274
+ name: z.string().optional().describe("The same name under name:check's field, accepted for one release. `available` wins when both are sent"),
8275
+ }),
8276
+ response: () => z.object({
8277
+ ok: z.boolean(),
8278
+ name: z.string().optional(),
8279
+ available: z.boolean().optional(),
8280
+ reason: z.string().optional().describe("Why it is not available: bad_shape · uuid_shaped · reserved · blocked · taken · is_a_workspace · is_an_actor (the last two only to a signed-in caller; anonymous gets taken)"),
8281
+ url: z.string().optional(),
8282
+ error: z.string().optional().describe("names_not_ready when the names table has not shipped; lookup_failed when the read failed (unknown, never free)"),
8283
+ }),
8284
+ effect: "ask",
8285
+ auth: "public",
8286
+ cost: "free",
8287
+ idempotent: true,
8288
+ reversible: true,
8289
+ settles: "none",
8290
+ version: "1.0.0",
8291
+ examples: [{ available: "acme" }],
8292
+ surfaces: { mcp: true },
8293
+ }),
8294
+ "name:get": receiver({
8295
+ receiver: "name:get",
8296
+ summary: "A workspace's current name, its URL, and the names it retired (each still answers with a redirect to the current one). Reads your own workspace, or one you control by `workspace`; a workspace you do not control is refused, never swapped for yours",
8297
+ request: () => z.object({
8298
+ workspace: z.string().optional().describe("The workspace slug to read; omit for the caller's own"),
8299
+ }),
8300
+ response: () => z.object({
8301
+ ok: z.boolean(),
8302
+ workspace: z.string().optional().describe("The slug, the key that never changes"),
8303
+ name: z.string().nullable().optional().describe("The current name; null when the workspace answers at its slug"),
8304
+ url: z.string().optional(),
8305
+ retired: z.array(z.string()).optional(),
8306
+ error: z.string().optional(),
8307
+ }),
8308
+ effect: "ask",
8309
+ auth: "member",
8310
+ cost: "free",
8311
+ idempotent: true,
8312
+ reversible: true,
8313
+ settles: "none",
8314
+ version: "1.0.0",
8315
+ examples: [{}],
8316
+ surfaces: { mcp: true },
8317
+ }),
8318
+ "name:update": receiver({
8319
+ receiver: "name:update",
8320
+ summary: "Rename a workspace: one.ie/u/<name> becomes its address. Was name:set (renamed 2026-11-19; the old name answers for one release). The slug, keys, wallets and every row stay as they are; the old name and the slug keep answering with a 301 to the new name forever, and stay this workspace's. Owner only, from the session or key; a named workspace you do not control is refused. At most 3 renames in 30 days and 10 names held in all",
8321
+ request: () => z.object({
8322
+ name: z.string().describe("The new name: lowercase letters, digits and single dashes, 3 to 40 characters; usually the company's name"),
8323
+ workspace: z.string().optional().describe("The workspace slug to rename; omit for the caller's own"),
8324
+ }),
8325
+ response: () => z.object({
8326
+ ok: z.boolean(),
8327
+ workspace: z.string().optional(),
8328
+ name: z.string().optional(),
8329
+ previous: z.string().nullable().optional().describe("The name it had, which now redirects here; null when it answered at its slug"),
8330
+ unchanged: z.boolean().optional(),
8331
+ url: z.string().optional(),
8332
+ error: z.string().optional().describe("forbidden · refused (see reason) · names_not_ready · lookup_failed"),
8333
+ reason: z.string().optional().describe("Why a rename was refused: missing name · bad_shape · uuid_shaped · reserved · blocked · taken · is_a_workspace · is_an_actor · rename_cap · name_cap"),
8334
+ }),
8335
+ effect: "ask",
8336
+ auth: "owner",
8337
+ cost: "free",
8338
+ idempotent: true,
8339
+ reversible: true,
8340
+ settles: "none",
8341
+ version: "1.0.0",
8342
+ examples: [{ name: "acme" }],
8343
+ surfaces: { mcp: true },
8344
+ }),
8345
+ "front-desk:update": receiver({
8346
+ receiver: "front-desk:update",
8347
+ summary: "Write a client's AI front desk playbook once: the greeting, how the desk answers, the qualifying questions (each with choices or a number range), booking rules and the hand-off. It is added beside what the chat agent already knows (never replacing it) and read on every chat turn; the questions go onto the booked service, where booking:create refuses a lead who misses or fails one; the greeting becomes the chat widget's first line. A playbook too long for the context store is refused by name. Owner of the workspace only, from the session.",
8348
+ request: () => z.object({
8349
+ slug: z.string(),
8350
+ playbook: z.object({
8351
+ business: z.string(),
8352
+ greeting: z.string().describe("The first line a visitor sees, at most 200 characters"),
8353
+ answer: z.array(z.string()).optional().describe("How the desk answers: tone and facts, one line each"),
8354
+ questions: z.array(z.object({
8355
+ key: z.string().describe("lowercase key the answer is stored under, e.g. budget"),
8356
+ ask: z.string(),
8357
+ oneOf: z.array(z.string()).optional().describe("the answers that qualify; shown to visitors as choices"),
8358
+ min: z.number().optional().describe("a number answer qualifies at this or more; never shown to visitors"),
8359
+ max: z.number().optional().describe("a number answer qualifies at this or less; never shown to visitors"),
8360
+ })),
8361
+ booking: z.object({ service: z.string().optional(), rules: z.array(z.string()).optional() }).optional(),
8362
+ handoff: z.object({ to: z.string(), when: z.array(z.string()) }),
8363
+ }),
8364
+ }),
8365
+ response: () => z.object({
8366
+ ok: z.boolean(), chars: z.number().optional(), questions: z.number().optional(),
8367
+ service: z.string().nullable().optional().describe("the service whose intake now carries the questions; null when the workspace has none"),
8368
+ gated: z.boolean().optional().describe("true when booking:create now checks the answers"),
8369
+ error: z.string().optional(),
8370
+ }),
8371
+ effect: "ask",
8372
+ auth: "manage_workspace",
8373
+ cost: "free",
8374
+ idempotent: true,
8375
+ reversible: true,
8376
+ settles: "none",
8377
+ version: "1.0.0",
8378
+ examples: [{
8379
+ slug: "brightdental",
8380
+ playbook: {
8381
+ business: "Bright Dental",
8382
+ greeting: "Hi, you have reached Bright Dental. I can answer questions and book you in.",
8383
+ questions: [
8384
+ { key: "treatment", ask: "What treatment are you looking for?", oneOf: ["cleaning", "whitening"] },
8385
+ { key: "budget", ask: "Roughly what budget do you have in mind?", min: 100 },
8386
+ ],
8387
+ handoff: { to: "the practice manager", when: ["a dental emergency"] },
8388
+ },
8389
+ }],
8390
+ surfaces: { mcp: true },
8391
+ }),
8392
+ "front-desk:get": receiver({
8393
+ receiver: "front-desk:get",
8394
+ summary: "Read a client's AI front desk playbook as it was written (null when none is stored, or another writer replaced the context since), and the rules the booking door checks now, read off the booked service — they can differ from the playbook when the owner edited a question's choices in the booking settings. Owner of the workspace only, from the session.",
8395
+ request: () => z.object({ slug: z.string() }),
8396
+ response: () => z.object({
8397
+ ok: z.boolean(),
8398
+ playbook: z.unknown().nullable().optional(),
8399
+ rules: z.object({
8400
+ service: z.string(),
8401
+ checks: z.array(z.object({ key: z.string(), question: z.string(), rule: z.record(z.string(), z.unknown()) })),
8402
+ notQualifiedThisHour: z.number().nullable().optional().describe("answers that did not qualify this hour, across every visitor — a warning for the owner, never a refusal; null when it could not be read"),
8403
+ }).nullable().optional().describe("what booking:create checks now; null when the workspace has no bookable service"),
8404
+ error: z.string().optional(),
8405
+ }),
8406
+ effect: "ask",
8407
+ auth: "manage_workspace",
8408
+ cost: "free",
8409
+ idempotent: true,
8410
+ reversible: true,
8411
+ settles: "none",
8412
+ version: "1.0.0",
8413
+ examples: [{ slug: "brightdental" }],
8414
+ surfaces: { mcp: true },
8415
+ }),
8416
+ // ── sms:* — text messages in and out of a client's front desk (Vespio lane C3) ──
8417
+ "sms:send": receiver({
8418
+ receiver: "sms:send",
8419
+ summary: "Send one text message from the workspace's own Twilio number, through Composio, behind the consent gate. `purpose` decides the bar: conversational (a reply to someone who texted in) and invite (a fixed 'reply YES for offers' ask, never free text) only from the channels text door's own signed send — anyone else is sent as marketing — or marketing (needs their JOIN, or YES to an invitation). STOP, a suppression or Twilio's 21610 refuses all. Capped per number per day (marketing 1, invitations 1, replies 25) and metered against the workspace's daily Composio calls. No Twilio account connected answers sms_not_configured with cannot_run, never sent.",
8420
+ request: () => z.object({
8421
+ to: z.string().describe("The person's number with its country code, e.g. +15551234567; punctuation is ignored"),
8422
+ body: z.string().describe("The text, 1-1600 characters"),
8423
+ purpose: z.enum(["conversational", "marketing", "invite"]).describe("conversational: the desk answering, qualifying, booking or confirming a conversation the person started by texting in — only the channels text door may say this; any other caller's text is sent as marketing. invite: one 'reply YES to get offers' ask to someone who texted in; their YES then opts them in. marketing: a campaign, sequence or promo, which needs the person's express opt-in (JOIN, or YES to an invitation). Required: a text that does not say why is not sent"),
8424
+ workspace: z.string().optional().describe("The workspace to send from; defaults to the caller's own. Naming another needs control of it"),
8425
+ slug: z.string().optional().describe("Service callers only (the channels door): the workspace the reply belongs to"),
8426
+ campaign: z.string().optional().describe("Campaign id stamped on the sms-sent event"),
8427
+ attest: z.string().optional().describe("The channels text door's HMAC over (workspace, to, body, purpose, at). Only a send carrying it, fresh, may be conversational or an invite; without it the send is marketing"),
8428
+ at: z.number().optional().describe("Epoch ms the door signed at; older than five minutes is not the door"),
8429
+ }),
8430
+ response: () => z.object({
8431
+ ok: z.boolean(),
8432
+ purpose: z.string().optional(),
8433
+ from: z.string().optional().describe("The workspace's number it went from"),
8434
+ to: z.string().optional().describe("The number in E.164"),
8435
+ sid: z.string().optional().describe("Twilio's message sid"),
8436
+ error: z.string().optional().describe("forbidden · bad_request · bad_number · consent_declined · consent_unreadable · no_sms_consent · no_marketing_consent · marketing_cap · invite_cap · reply_cap · capped · over_limit · sms_not_configured · sms_provider_unreachable · sms_send_failed"),
8437
+ cannot_run: z.boolean().optional().describe("true when the environment, not the build, stopped it: no Twilio number or account, or Composio unreachable"),
8438
+ detail: z.string().optional(),
8439
+ }),
8440
+ effect: "ask",
8441
+ auth: "write",
8442
+ cost: "variable",
8443
+ idempotent: false,
8444
+ reversible: false,
8445
+ settles: "none",
8446
+ version: "1.0.0",
8447
+ examples: [{ to: "+15551234567", body: "Thanks! What postcode are you in?", purpose: "conversational" }],
8448
+ surfaces: { mcp: true },
8449
+ }),
8450
+ "sms:receive": receiver({
8451
+ receiver: "sms:receive",
8452
+ summary: "Record one Twilio-signed inbound text against the consent of the workspace whose number was texted, and say whether the front desk answers it. A text is consent for conversational replies only; JOIN, or YES to an invitation, adds marketing (any other yes is conversation); STOP and its family end both; START gives back replies only. Every change writes an sms-consent evidence row. Only the channels sms door, carrying its HMAC over the text; a message id is acted on once.",
8453
+ request: () => z.object({
8454
+ from: z.string().describe("The texter's number (Twilio From)"),
8455
+ to: z.string().describe("The workspace's number that was texted (Twilio To) — the workspace is read from it, never from the caller"),
8456
+ body: z.string().describe("The text as received"),
8457
+ messageSid: z.string().describe("Twilio's MessageSid: the evidence key, and acted on once — a replay changes nothing"),
8458
+ attest: z.string().describe("The text door's HMAC-SHA256 (SERVER_SECRET) over from, to, body and messageSid; without it nothing is recorded"),
8459
+ }),
8460
+ response: () => z.object({
8461
+ ok: z.boolean(),
8462
+ workspace: z.string().optional(),
8463
+ keyword: z.enum(["stop", "start", "join", "yes", "help"]).nullable().optional(),
8464
+ answer: z.boolean().optional().describe("false: a keyword, a replay, or a number that said STOP — the desk does not answer"),
8465
+ duplicate: z.boolean().optional().describe("true: this message id was already recorded; nothing changed"),
8466
+ error: z.string().optional().describe("forbidden (not a service caller) · unattested (no or wrong door HMAC) · unknown_number · no_db"),
8467
+ }),
8468
+ effect: "ask",
8469
+ auth: "write",
8470
+ cost: "free",
8471
+ idempotent: true,
8472
+ reversible: true,
8473
+ settles: "none",
8474
+ version: "1.0.0",
8475
+ }),
7289
8476
  "settings:write": receiver({
7290
8477
  receiver: "settings:write",
7291
8478
  summary: "Write a workspace setting value (caller or authorized descendant)",
@@ -7633,18 +8820,37 @@ export const RECEIVERS = {
7633
8820
  // ──billing — handlers in resolvers/market.ts ──────────────────────────────────
7634
8821
  "billing:plan": receiver({
7635
8822
  receiver: "billing:plan",
7636
- summary: "Change a workspace's plan — returns a checkout URL to complete the upgrade",
7637
- request: () => z.object({ slug: z.string(), actorId: z.string(), plan: z.enum(["pro", "agency", "scale"]) }),
7638
- response: () => z.object({ ok: z.boolean(), intent: z.string().optional(), checkoutUrl: z.string().optional(), plan: z.string().optional(), reason: z.string().optional() }),
8823
+ 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",
8824
+ request: () => z.object({ slug: z.string(), actorId: z.string(), plan: z.enum(["pro", "team", "business", "free", "cancel", "agency", "scale"]) }),
8825
+ 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() }),
8826
+ // Intent-only: returns a checkout URL a person later pays — not `moves: "value"`.
7639
8827
  effect: "ask", cost: "free", reversible: false, idempotent: false, auth: "update_group",
7640
8828
  }),
7641
8829
  "billing:topup": receiver({
7642
8830
  receiver: "billing:topup",
7643
- 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",
7644
- request: () => z.object({ slug: z.string(), actorId: z.string(), amount: z.number(), currency: z.string().optional() }),
7645
- 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() }),
8831
+ 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",
8832
+ request: () => z.object({ slug: z.string(), actorId: z.string(), credits: z.number().optional(), amount: z.number().optional(), currency: z.string().optional() }),
8833
+ 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() }),
8834
+ // Intent-only: returns a checkout URL a person later pays — not `moves: "value"`.
7646
8835
  effect: "ask", cost: "free", reversible: false, idempotent: false, auth: "update_group",
7647
8836
  }),
8837
+ // Public read: the same numbers /.well-known/one.json `fees` serves. The chat reads prices
8838
+ // here (channels get_pricing) instead of carrying them in a prompt. Handler: resolvers/billing.ts.
8839
+ "billing:list": receiver({
8840
+ receiver: "billing:list",
8841
+ 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",
8842
+ request: () => z.object({}).optional(),
8843
+ response: () => z.object({
8844
+ ok: z.boolean(),
8845
+ currency: z.literal("USD").describe("Every price here is US dollars."),
8846
+ credit_usd: z.number().describe("The price of one credit in USD."),
8847
+ credits_per_usd: z.number().describe("Credits one US dollar buys."),
8848
+ 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."),
8849
+ 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."),
8850
+ 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."),
8851
+ }),
8852
+ effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "public",
8853
+ }),
7648
8854
  // ── video — handler in resolvers/video.ts ──────────────────────────────────────
7649
8855
  "video:ensure-defaults": receiver({
7650
8856
  receiver: "video:ensure-defaults",
@@ -7654,18 +8860,22 @@ export const RECEIVERS = {
7654
8860
  effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
7655
8861
  }),
7656
8862
  // ── booking — one calendar, two doors (text/booking-plan.md §5) ───────────────
7657
- // booking:confirm-payment (public) finalises a paid booking by payment ref.
8863
+ // booking:confirm-payment confirms nothing, for anyone: a booking is confirmed only by the
8864
+ // payment webhook that verified its payment (resolvers/booking.ts confirmBookedPayment).
8865
+ // Tenant-class label so an anonymous caller is refused at the door, before the handler.
7658
8866
  "booking:confirm-payment": receiver({
7659
8867
  receiver: "booking:confirm-payment",
7660
- summary: "Confirm a booking after payment settles, by payment reference (public)",
8868
+ summary: "Refuses every caller: a booking is confirmed by the payment webhook that verified its payment",
7661
8869
  request: () => z.object({ paymentRef: z.string() }),
7662
8870
  response: () => z.object({ ok: z.boolean(), error: z.string().optional() }),
7663
- effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "public",
8871
+ effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "owner",
7664
8872
  }),
7665
8873
  // Both public-bookable: a customer with no account books a slot. The provider
7666
8874
  // side (configure a service) is the separate, gated booking:configure.
7667
8875
  "booking:list-slots": receiver({
7668
8876
  receiver: "booking:list-slots",
8877
+ // 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).
8878
+ auth: "public",
7669
8879
  summary: "List open slots for a workspace's service on a date (or next open days)",
7670
8880
  request: () => z.object({
7671
8881
  slug: z.string(), // provider workspace
@@ -7723,6 +8933,8 @@ export const RECEIVERS = {
7723
8933
  }),
7724
8934
  "booking:create": receiver({
7725
8935
  receiver: "booking:create",
8936
+ // 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).
8937
+ auth: "public",
7726
8938
  summary: "Hold a slot for a customer; returns a ref and a payment intent when price > 0",
7727
8939
  request: () => z.object({
7728
8940
  slug: z.string(),
@@ -7864,22 +9076,27 @@ export const RECEIVERS = {
7864
9076
  request: () => z.object({
7865
9077
  slug: z.string().optional(),
7866
9078
  templates: z.boolean().optional(),
9079
+ // Named here because the door parses with this schema and zod strips what it does not name.
9080
+ limit: z.number().int().optional(),
7867
9081
  }),
7868
9082
  response: () => z.object({
7869
9083
  workflows: z.array(z.object({
7870
9084
  id: z.string(), name: z.string(), description: z.string().optional(), step_count: z.number(),
7871
9085
  status: z.string(), last_run_status: z.string().nullable(),
7872
9086
  })),
9087
+ // A short answer says it is short: total rows that exist, and whether `workflows` was cut.
9088
+ total: z.number().optional(),
9089
+ truncated: z.boolean().optional(),
7873
9090
  error: z.string().optional(),
7874
9091
  }),
7875
9092
  effect: "ask", cost: "free", idempotent: true, simulatable: false, auth: "view_workflows",
7876
- examples: [{ slug: "acme" }, { templates: true }],
9093
+ examples: [{ slug: "acme" }, { templates: true }, { limit: 5 }],
7877
9094
  }),
7878
9095
  "workflow:get": receiver({
7879
9096
  receiver: "workflow:get",
7880
9097
  surfaces: { mcp: true },
7881
9098
  summary: "Fetch one workflow's full graph — steps (kind, config, position) and edges (with conditions)",
7882
- request: () => z.object({ workflowId: z.string() }),
9099
+ request: () => z.object({ workflowId: z.string(), slug: SERVICE_SLUG }),
7883
9100
  response: () => z.object({
7884
9101
  id: z.string(), name: z.string(), status: z.string(),
7885
9102
  steps: z.array(z.object({
@@ -7900,7 +9117,7 @@ export const RECEIVERS = {
7900
9117
  receiver: "workflow:runs",
7901
9118
  surfaces: { mcp: true },
7902
9119
  summary: "List recent runs of a workflow (D1 workflow_run) for the monitor + history surfaces",
7903
- 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() }),
9120
+ 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 }),
7904
9121
  response: () => z.object({
7905
9122
  runs: z.array(z.object({
7906
9123
  id: z.string(), status: z.string(),
@@ -7915,6 +9132,50 @@ export const RECEIVERS = {
7915
9132
  effect: "ask", cost: "free", idempotent: true, simulatable: false, auth: "view_workflows",
7916
9133
  examples: [{ workflowId: "wf_abc", limit: 20 }, { workflowId: "wf_abc", runId: "run_1" }],
7917
9134
  }),
9135
+ "workflow:quote": receiver({
9136
+ receiver: "workflow:quote",
9137
+ surfaces: { mcp: true },
9138
+ summary: "The path builder's read (text/path-builder.md): every step of a saved workflow you can view (workflowId), or of an imported path definition (an inline WorkflowDiff, priced without saving), in edge order, with its routed owner and its cost — BEFORE it runs. Owner from the run's own binding, an unbound agent's from world:route decide (zero tokens), an agent's model from world:pick-model seeded per step, a tool's cost from its receiver's declared cost. Nothing dispatches. A step that cannot be priced answers usd null, never 0, and the total counts it",
9139
+ request: () => z.object({
9140
+ workflowId: z.string().optional().describe("A saved workflow to price"),
9141
+ diff: WorkflowDiffSchema.optional().describe("An imported path definition — the same WorkflowDiff workflow:apply-diff saves — priced WITHOUT saving. Used when workflowId is absent"),
9142
+ name: z.string().optional().describe("The imported path's name, echoed back"),
9143
+ triggerSource: z.string().optional().describe("The imported path's trigger source, the trigger step's owner"),
9144
+ slug: SERVICE_SLUG,
9145
+ }),
9146
+ response: () => z.object({
9147
+ ok: z.boolean(),
9148
+ workflowId: z.string().optional(),
9149
+ name: z.string().optional(),
9150
+ status: z.string().optional().describe("The saved workflow's status, or 'unsaved' for an imported definition"),
9151
+ prices: z.string().optional().describe("The model price table read, source@asOf"),
9152
+ steps: z.array(z.object({
9153
+ id: z.string(),
9154
+ kind: z.string(),
9155
+ name: z.string(),
9156
+ owner: z.string(),
9157
+ via: z.string().describe("source | receiver | actor | skill | sub-path | route:highway | route:classified | route:ceo | unbound | inline | person | clock | buyer"),
9158
+ tags: z.array(z.string()),
9159
+ cost: z.object({
9160
+ usd: z.number().nullable().describe("USD per run of this step; null = not priced, never zero"),
9161
+ basis: z.string().describe("zero | declared-free | pinned | router-pick | variable | fixed | undeclared | skill-model | sub-path | unbound"),
9162
+ model: z.string().optional(),
9163
+ reason: z.string().optional(),
9164
+ }),
9165
+ time: z.object({ ms: z.number().nullable(), basis: z.string().describe("runs | configured | waits | none") }),
9166
+ suggested: z.object({ owner: z.string(), via: z.string() }).optional().describe("A bound agent whose tags world:route would hand to someone else — the router's suggestion beside the named actor"),
9167
+ })).optional(),
9168
+ total: z.object({
9169
+ steps: z.number().int(),
9170
+ usd: z.number(),
9171
+ priced: z.number().int(),
9172
+ unpriced: z.number().int(),
9173
+ picks: z.number().int().describe("Priced steps whose model is the router's pick, not pinned"),
9174
+ }).optional(),
9175
+ error: z.string().optional(),
9176
+ }),
9177
+ effect: "ask", cost: "free", idempotent: true, reversible: true, simulatable: false, auth: "view_workflows",
9178
+ }),
7918
9179
  "workflow:step-stats": receiver({
7919
9180
  receiver: "workflow:step-stats",
7920
9181
  surfaces: { mcp: true },
@@ -8038,12 +9299,15 @@ export const RECEIVERS = {
8038
9299
  diff: WorkflowDiffSchema,
8039
9300
  simulate: z.boolean().optional(),
8040
9301
  version: z.number().int().optional(), // optimistic lock — stale → conflict
9302
+ slug: SERVICE_SLUG,
8041
9303
  }),
8042
9304
  response: () => z.object({
8043
9305
  ok: z.boolean(),
8044
9306
  stepCount: z.number().optional(),
8045
9307
  warnings: z.array(z.string()).optional(), // §9 advisories (never block); grammar: code | code:stepId
8046
9308
  idMap: z.record(z.string(), z.string()).optional(), // tempId → persisted id
9309
+ projected: z.boolean().optional().describe("Every added/renamed step written to TypeDB as a thing (tid = step id) and every removed one closed (closed-at). False never fails the save — workflow:update { project: true } retries"),
9310
+ projectReason: z.string().optional().describe("Why the projection did not land, when projected is false"),
8047
9311
  error: z.string().optional(), // 'cycle_detected' | 'conflict' | 'invalid_diff' | 'multiple_triggers' | 'edge_unknown_step' | 'invalid_config' | 'bad_expr' | 'unsupported_field'
8048
9312
  }),
8049
9313
  effect: "ask", cost: "free", reversible: true, idempotent: false, simulatable: true,
@@ -8057,6 +9321,7 @@ export const RECEIVERS = {
8057
9321
  request: () => z.object({
8058
9322
  workflowId: z.string(),
8059
9323
  diff: WorkflowDiffSchema,
9324
+ slug: SERVICE_SLUG,
8060
9325
  }),
8061
9326
  response: () => z.object({
8062
9327
  ok: z.boolean(),
@@ -8083,6 +9348,11 @@ export const RECEIVERS = {
8083
9348
  // Undeclared until 2026-10-11, zod STRIPPED this at /api/ask and the canvas
8084
9349
  // Test button minted a LIVE run that deposited pheromone on every edge.
8085
9350
  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."),
9351
+ // A bare key's work contract for THE RUN: declared at the top level so the edge
9352
+ // keeps it (zod strips the undeclared); runWorkflow stores it in triggerPayload,
9353
+ // where every lane reads a bare-key run's contract from, and it rides beneath
9354
+ // every step. Also accepted inside triggerPayload (round 5, finding 3).
9355
+ ...WORK_CONTRACT_FIELDS,
8086
9356
  }),
8087
9357
  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() }),
8088
9358
  effect: "ask", cost: "variable", reversible: false, idempotent: true, simulatable: false, settles: "none",
@@ -8156,6 +9426,8 @@ export const RECEIVERS = {
8156
9426
  stripeAccount: z.string().optional(),
8157
9427
  error: z.string().optional(),
8158
9428
  }),
9429
+ // Intent-only: mints the session a buyer later pays; nothing moves at the call, so
9430
+ // it is deliberately NOT `moves: "value"` (value-moving-parity.test.ts names it).
8159
9431
  effect: "ask", cost: "variable", reversible: false, idempotent: false, simulatable: false, settles: "offchain",
8160
9432
  auth: "manage_workflows",
8161
9433
  examples: [{ workspace: "acme", ppid: "pr_1" }],
@@ -8221,6 +9493,10 @@ export const RECEIVERS = {
8221
9493
  source: z.string(),
8222
9494
  slug: z.string().optional(),
8223
9495
  triggerPayload: z.record(z.string(), z.unknown()).optional(),
9496
+ // A bare key's work contract for every run this fire starts — declared so the
9497
+ // edge keeps it; the door puts it in each child's triggerPayload and the child's
9498
+ // value steps are gated as the origin key with it (round 4 finding 2, round 5 finding 3).
9499
+ ...WORK_CONTRACT_FIELDS,
8224
9500
  }),
8225
9501
  response: () => z.object({ ok: z.boolean(), started: z.number(), runIds: z.array(z.string()) }),
8226
9502
  effect: "signal", cost: "variable", reversible: false, idempotent: false, simulatable: false, auth: "manage_workflows",
@@ -8237,9 +9513,25 @@ export const RECEIVERS = {
8237
9513
  "workflow:update": receiver({
8238
9514
  receiver: "workflow:update",
8239
9515
  surfaces: { mcp: true },
8240
- summary: "Rename a workflow or change its status (draft|active|paused)",
8241
- request: () => z.object({ workflowId: z.string(), name: z.string().optional(), status: z.enum(["draft", "active", "paused"]).optional() }),
8242
- response: () => z.object({ ok: z.boolean(), error: z.string().optional() }),
9516
+ summary: "Rename a workflow or change its status (draft|active|paused). With { project: true }, project its steps into TypeDB as things instead (tid = the step id, thing-type step, step-kind; the step → workflow link is D1's), through the same function workflow:apply-diff runs on every save: the retry after a save answered projected:false, and the backfill for workflows saved before projection existed. { project: true, workflowId } projects one; { project: true, all: true } every workflow you control (templates excluded). Was workflow:project until 2026-11-19 (an alias for one release)",
9517
+ request: () => z.object({
9518
+ workflowId: z.string().optional().describe("The workflow to change or project. Required except with project + all"),
9519
+ name: z.string().optional(),
9520
+ status: z.enum(["draft", "active", "paused"]).optional(),
9521
+ project: z.boolean().optional().describe("Project the steps into TypeDB as things instead of renaming or changing status"),
9522
+ all: z.boolean().optional().describe("With project: every workflow the caller controls"),
9523
+ }).refine((v) => !!v.workflowId || (v.project === true && v.all === true), {
9524
+ message: "workflowId is required, except with project: true and all: true",
9525
+ path: ["workflowId"],
9526
+ }),
9527
+ response: () => z.object({
9528
+ ok: z.boolean(),
9529
+ error: z.string().optional(),
9530
+ projected: z.boolean().optional().describe("With project: true only when every step write landed"),
9531
+ workflows: z.number().optional().describe("With project: workflows projected"),
9532
+ steps: z.number().optional().describe("With project: step things written"),
9533
+ failed: z.array(z.object({ workflowId: z.string(), reason: z.string() })).optional(),
9534
+ }),
8243
9535
  effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "manage_workflows",
8244
9536
  examples: [{ workflowId: "wf_abc", name: "Renamed Workflow" }, { workflowId: "wf_abc", status: "paused" }],
8245
9537
  }),
@@ -8334,12 +9626,24 @@ export const RECEIVERS = {
8334
9626
  .max(12)
8335
9627
  .optional()
8336
9628
  .describe("Bare routing words for THIS call — a shape ('react-component'), a department ('sales'), a bake run id. Never namespaced. Carried onto the AI Gateway log as metadata beside the call's tokens and cost (channels/src/gateway-meta.ts), so spend can be filtered by them; never part of the user turn. The door's own signalId rides beside them from ctx, never from this body."),
9629
+ maxOutputTokens: z
9630
+ .number()
9631
+ .int()
9632
+ .min(1)
9633
+ .max(32768)
9634
+ .optional()
9635
+ .describe("Hold this turn's output to at most this many tokens. A DOWNGRADE only: channels runs the smaller of this and the persona's own cap, so a caller can lower the cost of a turn, never raise it. Never part of the user turn."),
9636
+ noTools: z
9637
+ .literal(true)
9638
+ .optional()
9639
+ .describe("Run this turn with NO tools (`one browse explore` sends an untrusted page here). A DOWNGRADE only: absent = today's behaviour, and a caller can remove tools, never add them. Enforced server-side: channels binds none and answers `noTools: true, toolsBound: 0`; an answer without that echo is withheld (`no_tools_unconfirmed`), and a flag that is not `true` is refused (`noTools_invalid`). Billing is unchanged - the turn still burns to the same payer. Never part of the user turn."),
8337
9640
  }).catchall(z.unknown()), // extra keys = the agent's input
8338
9641
  response: () => z.object({
8339
9642
  ok: z.boolean(),
8340
9643
  text: z.string().optional(),
8341
9644
  actorId: z.string().optional(),
8342
9645
  error: z.string().optional(),
9646
+ noTools: z.literal(true).optional().describe("Present only on a run that asked for `noTools` and whose channels CONFIRMED it bound no tools (`toolsBound: 0`). A caller that needs the guarantee requires this field; its absence on a flagged call never happens (the call refuses with `no_tools_unconfirmed` instead)."),
8343
9647
  usage: z
8344
9648
  .object({
8345
9649
  model: z.string(),
@@ -8372,21 +9676,62 @@ export const RECEIVERS = {
8372
9676
  description: z.string().optional(),
8373
9677
  type: z.enum(["meeting", "classroom", "webinar"]).optional(),
8374
9678
  region: z.string().optional(),
9679
+ access: z.enum(["open", "members"]).optional().describe("'open' (default) keeps the public guest door; 'members' closes the room on every door — a signed-in caller with authority over the workspace only, and no invite or session links can be made for it"),
9680
+ threadId: z.string().optional().describe("Bind an existing conversation as the room's thread instead of creating a new one — must belong to the same workspace"),
8375
9681
  }),
8376
9682
  response: () => z.object({
8377
9683
  ok: z.boolean(),
8378
9684
  room: z.object({
8379
9685
  slug: z.string(), name: z.string(), description: z.string(),
8380
9686
  type: z.string(), hmsRoomId: z.string(), url: z.string(),
9687
+ access: z.string().optional(), threadId: z.string().nullable().optional(),
8381
9688
  }).optional(),
8382
9689
  error: z.string().optional(),
8383
9690
  }),
8384
9691
  effect: "ask", cost: "free", idempotent: false, auth: "manage_clients",
8385
- examples: [{ workspace: "acme", roomSlug: "algebra-101", name: "Algebra 101", type: "classroom" }],
9692
+ examples: [{ workspace: "acme", roomSlug: "algebra-101", name: "Algebra 101", type: "classroom" }, { workspace: "one", roomSlug: "finance", name: "Finance meeting", access: "members", threadId: "6eGGB5VpPXIAQxjr" }],
8386
9693
  // Fan-out pilot (actions-fan-out C2): offered to chat via chatToolsFor — no
8387
9694
  // curated workspace tool needed; the registry derivation is the whole tool.
8388
9695
  surfaces: { chat: true, mcp: { name: "create_room" } },
8389
9696
  }),
9697
+ "video:call": receiver({
9698
+ receiver: "video:call",
9699
+ summary: "Mint a non-host 100ms peer token for the calling agent, so it can join a room (members rooms included) and share a screen",
9700
+ request: () => z.object({
9701
+ workspace: z.string().describe("The workspace that owns the room — the caller needs authority over it"),
9702
+ roomSlug: z.string().describe("The room's slug, e.g. 'finance'"),
9703
+ }),
9704
+ response: () => z.object({
9705
+ ok: z.boolean(),
9706
+ token: z.string().optional().describe("100ms peer token; role is the guest/meet role, never host; user_id is agent:<actor>"),
9707
+ name: z.string().optional().describe("The agent actor the token is named for — use it as the peer name"),
9708
+ role: z.string().optional(),
9709
+ roomSlug: z.string().optional(),
9710
+ url: z.string().optional(),
9711
+ error: z.string().optional(),
9712
+ }),
9713
+ effect: "ask", cost: "free", idempotent: false, auth: "manage_clients",
9714
+ examples: [{ workspace: "one", roomSlug: "finance" }],
9715
+ surfaces: { chat: false },
9716
+ }),
9717
+ "video:update": receiver({
9718
+ receiver: "video:update",
9719
+ summary: "Switch an existing room between open and members-only, in place — the room, its thread, codes and links all stay",
9720
+ request: () => z.object({
9721
+ workspace: z.string().describe("The workspace that owns the room — the caller must control it"),
9722
+ roomSlug: z.string().describe("The room's slug, e.g. 'finance'"),
9723
+ access: z.enum(["open", "members"]).describe("'members' closes every door to signed-in members of the workspace (member, admin or owner); 'open' restores the public guest door"),
9724
+ }),
9725
+ response: () => z.object({
9726
+ ok: z.boolean(),
9727
+ workspace: z.string().optional(), roomSlug: z.string().optional(),
9728
+ access: z.string().optional(), was: z.string().optional().describe("The access the room had before this call"),
9729
+ error: z.string().optional(),
9730
+ }),
9731
+ effect: "ask", cost: "free", idempotent: true, auth: "manage_clients",
9732
+ examples: [{ workspace: "one", roomSlug: "finance", access: "members" }],
9733
+ surfaces: { chat: false },
9734
+ }),
8390
9735
  "video:delete-room": receiver({
8391
9736
  receiver: "video:delete-room",
8392
9737
  surfaces: { mcp: { name: "delete_room" } },
@@ -8550,29 +9895,17 @@ export const RECEIVERS = {
8550
9895
  // on the way back, and a name the model would pick by accident. The curated
8551
9896
  // `meet_human` (channels/src/tools/meetings.ts) is the chat surface.
8552
9897
  }),
8553
- "video:join-event": receiver({
8554
- receiver: "video:join-event",
8555
- summary: "Record a peer join event for tracking and lifecycle; public — called from the /go/ link handler",
8556
- request: () => z.object({
8557
- workspace: z.string(),
8558
- roomSlug: z.string(),
8559
- role: z.string().optional(),
8560
- actorId: z.string().optional(),
8561
- }),
8562
- response: () => z.object({ ok: z.boolean(), error: z.string().optional() }),
8563
- effect: "signal", cost: "free", idempotent: true,
8564
- examples: [{ workspace: "acme", roomSlug: "consult-abc", role: "guest" }],
8565
- }),
8566
9898
  "video:start-recording": receiver({
8567
9899
  receiver: "video:start-recording",
8568
- summary: "Start cloud recording for an active room via 100ms REST; inserts a video_recordings row",
9900
+ 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",
8569
9901
  request: () => z.object({ workspace: z.string(), roomSlug: z.string() }),
8570
9902
  response: () => z.object({
8571
9903
  ok: z.boolean(),
8572
9904
  recordingId: z.string().optional(),
9905
+ reused: z.boolean().optional(),
8573
9906
  error: z.string().optional(),
8574
9907
  }),
8575
- effect: "ask", cost: "free", idempotent: false, auth: "manage_clients",
9908
+ effect: "ask", cost: "free", idempotent: true, auth: "manage_clients",
8576
9909
  examples: [{ workspace: "acme", roomSlug: "algebra-101" }],
8577
9910
  surfaces: { chat: true, mcp: { name: "start_recording" } }, // fan-out: chat (actions-fan-out C5) + MCP (agent-native C1)
8578
9911
  }),
@@ -8615,54 +9948,6 @@ export const RECEIVERS = {
8615
9948
  examples: [{ workspace: "acme", roomSlug: "product-launch" }],
8616
9949
  surfaces: { chat: true, mcp: { name: "start_stream" } }, // fan-out: chat (actions-fan-out C5) + MCP (agent-native C1)
8617
9950
  }),
8618
- // connect:channel — token-paste connect for a channel (Connect plan C7). The
8619
- // typed contract over the shipped /api/connect/telegram route: the caller pastes
8620
- // a channel credential, web verifies it (getMe), points the webhook, then hands
8621
- // the raw secret to channels' /connect sink under the owner gate. SECURITY: the
8622
- // token rides the REQUEST only; the response NEVER echoes it. effect:ask,
8623
- // auth:manage_clients re-walked server-side off locals.slug (never body actorId).
8624
- "connect:channel": receiver({
8625
- receiver: "connect:channel",
8626
- summary: "Connect a channel (e.g. telegram) by pasting its bot token; verifies, sets the webhook, seals the credential under the owner gate",
8627
- request: () => z.object({
8628
- channel: z.string(), // 'telegram' (token-paste path)
8629
- token: z.string(), // the bot credential — request-only, never returned/logged
8630
- slug: z.string().optional(), // workspace; gate re-scopes to the authenticated owner
8631
- }),
8632
- response: () => z.object({
8633
- ok: z.boolean(),
8634
- status: z.string().optional(), // 'active' | 'updated' from the channels sink
8635
- account: z.string().optional(), // public handle (e.g. bot username) — never the token
8636
- error: z.string().optional(), // 'invalid token' | 'unauthorized' | 'duplicate'
8637
- }),
8638
- effect: "ask", cost: "free", reversible: false, idempotent: true, auth: "manage_clients",
8639
- examples: [{ channel: "telegram", token: "<bot-token>" }],
8640
- }),
8641
- // connect:status — list the workspace's connected channels (Connect plan C8).
8642
- // Read-only contract over /api/connect/status: rows come from the `connection`
8643
- // table scoped to the authenticated owner (locals.slug — never a body slug).
8644
- // SECURITY: the response carries channel + public account id + status only;
8645
- // cred_ref and webhook_secret never leave the server.
8646
- "connect:status": receiver({
8647
- receiver: "connect:status",
8648
- summary: "List connected channels for the workspace — channel, account, status, runtime; never the credential",
8649
- request: () => z.object({}),
8650
- response: () => z.object({
8651
- ok: z.boolean(),
8652
- connections: z
8653
- .array(z.object({
8654
- channel: z.string(), // 'telegram' | 'slack' | 'discord' | 'email'
8655
- account: z.string(), // external_account_id (bot id / team id / inbound address)
8656
- status: z.string(), // 'active' | 'revoked'
8657
- runtime: z.string(), // 'webhook' | 'socket'
8658
- connected_at: z.number(), // unix epoch seconds
8659
- }))
8660
- .optional(),
8661
- error: z.string().optional(),
8662
- }),
8663
- effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "manage_clients",
8664
- examples: [{}],
8665
- }),
8666
9951
  // ── News desk (text/magazine.md) — follow, fetch once, rank per group, publish an issue ──
8667
9952
  // Fetch is shared (a feed is public); everything private is keyed by the group. Handlers in
8668
9953
  // resolvers/news.ts. Every one refuses BY NAME: forbidden · not_found · bad_request ·
@@ -8908,7 +10193,7 @@ export const RECEIVERS = {
8908
10193
  surfaces: { mcp: true },
8909
10194
  summary: "Seed recipients from audience tag, apply suppression, enqueue the send batch",
8910
10195
  request: () => z.object({ workspace: z.string(), broadcastId: z.string() }),
8911
- response: () => z.object({ enqueued: z.number() }),
10196
+ response: () => z.object({ ok: z.boolean(), sent: z.number(), failed: z.number(), paused: z.boolean().optional(), ended: z.literal("no_audience").optional(), reason: z.enum(["no_audience_tag", "no_subscriber"]).optional() }),
8912
10197
  effect: "signal", cost: "variable", reversible: false, idempotent: false, auth: "write",
8913
10198
  }),
8914
10199
  "broadcast:schedule": receiver({
@@ -9441,7 +10726,7 @@ export const RECEIVERS = {
9441
10726
  receiver: "seo:backlinks-summary",
9442
10727
  surfaces: { mcp: { name: "seo_backlinks" } },
9443
10728
  summary: "Pull live backlink summary for a domain via DataForSEO; marks domain→seo:backlinks path",
9444
- request: () => z.object({ target: z.string(), limit: z.number().int().min(1).max(1000).optional() }),
10729
+ request: () => z.object({ slug: SERVICE_SLUG, target: z.string(), limit: z.number().int().min(1).max(1000).optional() }),
9445
10730
  response: () => z.object({ ok: z.boolean(), data: z.unknown().optional(), error: z.string().optional() }),
9446
10731
  effect: "ask", cost: "variable", reversible: true, idempotent: false, auth: "member",
9447
10732
  examples: [{ target: "one.ie" }],
@@ -9450,7 +10735,7 @@ export const RECEIVERS = {
9450
10735
  receiver: "seo:llm-mentions",
9451
10736
  surfaces: { mcp: { name: "seo_ai_visibility" } },
9452
10737
  summary: "Pull live AI-visibility (LLM mentions) data for a domain via DataForSEO; marks domain→seo:llm-mentions path",
9453
- request: () => z.object({ target: z.string() }),
10738
+ request: () => z.object({ slug: SERVICE_SLUG, target: z.string() }),
9454
10739
  response: () => z.object({ ok: z.boolean(), data: z.unknown().optional(), error: z.string().optional() }),
9455
10740
  effect: "ask", cost: "variable", reversible: true, idempotent: false, auth: "member",
9456
10741
  examples: [{ target: "one.ie" }],
@@ -9459,7 +10744,7 @@ export const RECEIVERS = {
9459
10744
  receiver: "seo:keywords-for-keyword",
9460
10745
  surfaces: { mcp: { name: "seo_research_keywords" } },
9461
10746
  summary: "Return related keyword suggestions for a seed keyword via DataForSEO Google Ads; marks keyword→seo:keywords path",
9462
- request: () => z.object({ keyword: z.string(), location_code: z.number().int().optional(), language_code: z.string().optional() }),
10747
+ request: () => z.object({ slug: SERVICE_SLUG, keyword: z.string(), location_code: z.number().int().optional(), language_code: z.string().optional() }),
9463
10748
  response: () => z.object({ ok: z.boolean(), data: z.unknown().optional(), error: z.string().optional() }),
9464
10749
  effect: "ask", cost: "variable", reversible: true, idempotent: false, auth: "member",
9465
10750
  examples: [{ keyword: "ai agents", location_code: 2840, language_code: "en" }],
@@ -9938,9 +11223,9 @@ export const RECEIVERS = {
9938
11223
  "affiliate:ppc-payout": receiver({
9939
11224
  receiver: "affiliate:ppc-payout",
9940
11225
  summary: "Drains unpaid PPC accrual for a budget to affiliate payout addresses via pay.one.ie",
9941
- request: () => z.object({ budgetId: z.unknown().optional(), chain: z.unknown().optional(), refToAddress: z.unknown().optional(), treasuryAddress: z.unknown().optional(), workspace: z.unknown().optional() }).passthrough(),
11226
+ 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(),
9942
11227
  response: () => z.unknown(),
9943
- effect: "ask", auth: "owner", reversible: false,
11228
+ effect: "ask", auth: "owner", reversible: false, moves: "value", movesIn: ["workspace"],
9944
11229
  }),
9945
11230
  "agent:draft": receiver({
9946
11231
  receiver: "agent:draft",
@@ -9982,7 +11267,7 @@ export const RECEIVERS = {
9982
11267
  "campaign:brief": receiver({
9983
11268
  receiver: "campaign:brief",
9984
11269
  summary: "Creates a campaign group from a brief, fires async channels BUILD, and returns the group ID and slug",
9985
- request: () => z.object({ brief: z.unknown().optional(), name: z.unknown().optional(), url: z.unknown().optional() }).passthrough(),
11270
+ request: () => z.object({ brief: z.unknown().optional(), name: z.unknown().optional(), url: z.unknown().optional(), targetCpa: z.unknown().optional().describe("Most to pay for a sale, in dollars (sop-campaign step 3); written as the target-cpa tag. null clears it"), targetCpl: z.unknown().optional().describe("Most to pay for a lead, in dollars; written as the target-cpl tag. null clears it") }).passthrough(),
9986
11271
  response: () => z.unknown(),
9987
11272
  effect: "ask", auth: "member", reversible: false,
9988
11273
  }),
@@ -9995,8 +11280,66 @@ export const RECEIVERS = {
9995
11280
  }),
9996
11281
  "campaign:update": receiver({
9997
11282
  receiver: "campaign:update",
9998
- summary: "Updates a campaign's name or a specific section's content, and returns the updated campaign info",
9999
- request: () => z.object({ campaignId: z.unknown().optional(), content: z.unknown().optional(), name: z.unknown().optional(), stageKey: z.unknown().optional(), stageName: z.unknown().optional() }).passthrough(),
11283
+ summary: "Updates a campaign's name, a section's content, or its target cost per sale and per lead, and returns the updated campaign info",
11284
+ request: () => z.object({ campaignId: z.unknown().optional(), content: z.unknown().optional(), name: z.unknown().optional(), stageKey: z.unknown().optional(), stageName: z.unknown().optional(), targetCpa: z.unknown().optional().describe("Most to pay for a sale, in dollars (sop-campaign step 3); written as the target-cpa tag. null clears it"), targetCpl: z.unknown().optional().describe("Most to pay for a lead, in dollars; written as the target-cpl tag. null clears it") }).passthrough(),
11285
+ response: () => z.unknown(),
11286
+ effect: "ask", auth: "member", reversible: false,
11287
+ }),
11288
+ // The campaign build pipeline: compile the stored sections into a workflow (compile), and the same
11289
+ // door driven by the approve button, which runs it (approve). Renamed from the two-colon
11290
+ // ui:campaigns:approve / ui:campaigns:compile, which /receivers/<family>/<verb> cannot route
11291
+ // (task:01a0f0bfd11bccc1674f7241).
11292
+ "campaign:approve": receiver({
11293
+ receiver: "campaign:approve",
11294
+ 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",
11295
+ request: () => z.object({ campaignId: z.unknown().optional(), sections: z.unknown().optional(), requireApproval: z.unknown().optional() }).passthrough(),
11296
+ response: () => z.unknown(),
11297
+ effect: "ask", auth: "member", reversible: false,
11298
+ }),
11299
+ // campaign:get { view: 'score' } (was campaign:score, renamed 2026-11-19; an alias for one release) — the SOP read for agents (text/marketing-sops-grow.md, phase 2): analyst and
11300
+ // media-buyer ask it for each campaign's verdict per SOP. Members only; never on a public surface.
11301
+ "campaign:get": receiver({
11302
+ receiver: "campaign:get",
11303
+ summary: "Every campaign in your workspace (or one) scored against the marketing SOPs it runs: per SOP the verdict word (kill, scale, hold, warn, ok, unknown) the sop-<slug> paths branch on, the step it is on, the gates and each rule's state with why. A number ONE cannot read is unknown, never 0",
11304
+ request: () => z.object({
11305
+ view: z.enum(["score"]).optional().describe("What to read about the campaigns. `score` (the default, and the only view today): the SOP verdicts"),
11306
+ campaignId: z.string().optional().describe("One campaign's gid; omit for every campaign in the caller's workspace, running ones first. The workspace is always the attested caller's — no body field names it"),
11307
+ }),
11308
+ response: () => z.object({
11309
+ ok: z.boolean(),
11310
+ workspace: z.string().optional().describe("Always the attested caller's workspace"),
11311
+ windowDays: z.number().optional().describe("The days of events and spend the scores read"),
11312
+ total: z.number().optional().describe("Campaigns that matched, before the cap"),
11313
+ limit: z.number().optional().describe("The most campaigns one answer carries"),
11314
+ capped: z.boolean().optional().describe("true when total > limit: the answer is SHORT, ask by campaignId for the rest"),
11315
+ campaigns: z.array(z.object({
11316
+ gid: z.string(), name: z.string(), vertical: z.string().nullable(), live: z.boolean(),
11317
+ sops: z.array(z.object({
11318
+ slug: z.string(), title: z.string(),
11319
+ verdict: z.string().describe("kill outranks all; anything unread makes it unknown, never ok"),
11320
+ step: z.object({ n: z.number(), title: z.string(), who: z.string(), doneWhen: z.string() }).nullable().describe("null = no tag says which step"),
11321
+ gates: z.array(z.object({ id: z.string(), must: z.string(), state: z.string() })),
11322
+ kpis: z.array(z.object({ key: z.string(), name: z.string(), state: z.string(), shown: z.string(), why: z.string() })),
11323
+ href: z.string().describe("The member SOP page"),
11324
+ })),
11325
+ })).optional(),
11326
+ error: z.string().optional().describe("forbidden | bad_campaign_id | no_db | read_failed | not_found"),
11327
+ }),
11328
+ effect: "ask",
11329
+ auth: "manage_workspace",
11330
+ roleAction: "read_revenue",
11331
+ cost: "free",
11332
+ idempotent: true,
11333
+ reversible: true,
11334
+ settles: "none",
11335
+ version: "1.0.0",
11336
+ surfaces: { mcp: true },
11337
+ examples: [{ campaignId: "01a1edad703405d807b6b913" }],
11338
+ }),
11339
+ "campaign:compile": receiver({
11340
+ receiver: "campaign:compile",
11341
+ 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",
11342
+ request: () => z.object({ campaignId: z.unknown().optional(), sections: z.unknown().optional(), requireApproval: z.unknown().optional() }).passthrough(),
10000
11343
  response: () => z.unknown(),
10001
11344
  effect: "ask", auth: "member", reversible: false,
10002
11345
  }),
@@ -10024,8 +11367,11 @@ export const RECEIVERS = {
10024
11367
  "checkout:link": receiver({
10025
11368
  receiver: "checkout:link",
10026
11369
  summary: "Mints a shareable payment link for a product price",
10027
- request: () => z.object({ chain: z.unknown().optional(), network: z.unknown().optional(), ppid: z.unknown().optional(), slug: z.unknown().optional() }).passthrough(),
11370
+ // `via` — the channel the link is sent through (whatsapp, sms…); it rides the
11371
+ // checkout href as utm_source so /sales counts the sale by channel.
11372
+ request: () => z.object({ chain: z.unknown().optional(), network: z.unknown().optional(), ppid: z.unknown().optional(), slug: z.unknown().optional(), via: z.unknown().optional() }).passthrough(),
10028
11373
  response: () => z.unknown(),
11374
+ // Intent-only: mints a link a buyer later pays — not `moves: "value"`.
10029
11375
  effect: "ask", auth: "owner", reversible: false,
10030
11376
  }),
10031
11377
  "checkout:notify": receiver({
@@ -10222,9 +11568,39 @@ export const RECEIVERS = {
10222
11568
  response: () => z.unknown(),
10223
11569
  effect: "ask", auth: "public", reversible: false,
10224
11570
  }),
11571
+ // `lead:reply` is the step the `lead-follow-up` path runs after it tags a new
11572
+ // lead (one.ie/web/src/lib/resolvers/lead-reply.ts, Vespio #9). It takes NO
11573
+ // workspace: the reply is always from the attested caller's own workspace, and
11574
+ // the minutes are written only on that workspace's own contact.
11575
+ "lead:reply": receiver({
11576
+ receiver: "lead:reply",
11577
+ summary: "Sends a new lead the first reply from the caller's own workspace, at once: one transactional email through message:send, with the workspace's booking link when it has a bookable service, and records the seconds from the capture to the reply on the lead (meta.lead.firstReply) for the monthly report. One reply per address per workspace in 14 days (the reservation row rides agent_events_warm's 14-day purge); at most 100 first replies a UTC day per workspace and 3 a UTC day per address across every workspace — every bound keys on the inbox (lower-cased, +tag dropped, gmail dots folded); the email says a stranger can ignore it and carries an unsubscribe link signed for the inbox, so following it blocks every spelling; a canary lead, a suppressed or a declined address gets nothing and nothing is recorded",
11578
+ request: () => z.object({
11579
+ email: z.string().describe("The address the lead typed — the lead-follow-up path passes $trigger.email. It must be a plain addr-spec (no display name, angle brackets, quotes, lists or IP literal; broadcast/address.ts strictAddress), and the reply goes to that address as typed (domain lower-cased), while every bound, the stop link and consent key on its canonical form (lower-cased, +tag dropped, gmail dots folded). Anything else answers {ok:true, sent:false, reason:'no_email'}"),
11580
+ personId: z.string().nullable().optional().describe("The lead's contact id from lead:capture ($trigger.personId). Used only to read the capture time and write the minutes, and only when it is a contact of the caller's own workspace; otherwise the reply still goes, unrecorded"),
11581
+ }),
11582
+ response: () => z.object({
11583
+ ok: z.boolean(),
11584
+ sent: z.boolean().optional().describe("true = the email left through message:send"),
11585
+ reason: z.string().optional().describe("Why nothing was sent, when ok is true and sent is false: no_email | already_replied | daily_cap (this workspace's 100 a day) | address_daily_cap (this inbox's 3 a day across every workspace) | cap_unreadable | canary (a readiness walk's test lead) | canary_unreadable | suppressed (the typed address or its inbox unsubscribed from this workspace) | suppression_unreadable | a message:send refusal"),
11586
+ bookingUrl: z.string().nullable().optional().describe("The booking link the reply carried; null when the workspace has no active bookable service"),
11587
+ seconds: z.number().nullable().optional().describe("Capture to reply; null when the capture time could not be read, and then nothing is recorded"),
11588
+ minutes: z.number().nullable().optional(),
11589
+ withinTarget: z.boolean().nullable().optional().describe("seconds <= 300, the five-minute speed-to-lead target"),
11590
+ error: z.string().optional().describe("unauthenticated | no_db | send_failed (the send threw; nothing recorded, a later run may try again)"),
11591
+ }),
11592
+ effect: "ask",
11593
+ auth: "manage_workflows",
11594
+ cost: "free",
11595
+ idempotent: true,
11596
+ reversible: false,
11597
+ settles: "none",
11598
+ version: "1.0.0",
11599
+ examples: [{ email: "sam@example.com", personId: "p_123" }],
11600
+ }),
10225
11601
  "learning:complete": receiver({
10226
11602
  receiver: "learning:complete",
10227
- 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",
11603
+ 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",
10228
11604
  request: () => z.object({ courseId: z.unknown().optional(), kind: z.unknown().optional(), stageId: z.unknown().optional(), workspace: z.unknown().optional() }).passthrough(),
10229
11605
  response: () => z.unknown(),
10230
11606
  effect: "ask", auth: "session", reversible: false,
@@ -10306,6 +11682,22 @@ export const RECEIVERS = {
10306
11682
  response: () => z.unknown(),
10307
11683
  effect: "ask", auth: "session", reversible: false,
10308
11684
  }),
11685
+ // The URL funnel store's test-mode approval: the preview token is the capability.
11686
+ // Body: one.ie/web/src/lib/resolvers/site-funnel.ts previewApprove.
11687
+ "preview:approve": receiver({
11688
+ receiver: "preview:approve",
11689
+ summary: "The visitor approves their URL-funnel store from its preview link: resolves the run's review step so the products go on sale and the storefront opens in TEST mode (test cards only; crypto waits for a claimed owner's wallet). Real money stays behind claim + shop:go-live. Answers the store and product links; a second call moves nothing.",
11690
+ request: () => z.object({ token: z.string().describe("The preview token from /preview/<token> — the same capability that shows the draft") }),
11691
+ response: () => z.object({
11692
+ ok: z.boolean(),
11693
+ error: z.string().optional().describe("invalid_or_expired · already_claimed (approving is the owner's now) · invalid_workspace · store_is_live · not_found · not_a_url_store · not_ready · build_failed · resolve_failed"),
11694
+ storeUrl: z.string().optional(),
11695
+ productUrl: z.string().nullable().optional().describe("The product read from the visitor's site when there was one, else the first product"),
11696
+ mode: z.literal("test").optional(),
11697
+ approved: z.enum(["now", "already"]).optional(),
11698
+ }),
11699
+ effect: "ask", auth: "public", reversible: false, idempotent: true,
11700
+ }),
10309
11701
  "pages:chat-generate": receiver({
10310
11702
  receiver: "pages:chat-generate",
10311
11703
  summary: "Generates a deterministic chat pack for a page, updates the database, and returns the pack and its hash",
@@ -10323,23 +11715,25 @@ export const RECEIVERS = {
10323
11715
  "payout:set": receiver({
10324
11716
  receiver: "payout:set",
10325
11717
  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",
10326
- 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() }).passthrough(),
11718
+ 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(),
10327
11719
  response: () => z.unknown(),
10328
- effect: "ask", auth: "owner", reversible: false,
11720
+ effect: "ask", auth: "owner", reversible: false, moves: "value", movesIn: ["workspace"],
10329
11721
  }),
10330
11722
  "plugins:buy-with-credits": receiver({
10331
11723
  receiver: "plugins:buy-with-credits",
10332
11724
  summary: "Buy a plugin using workspace credits, granting entitlement synchronously",
10333
- request: () => z.object({ name: z.unknown().optional() }).passthrough(),
11725
+ request: () => z.object({ name: z.unknown().optional(), ...WORK_CONTRACT_FIELDS }).passthrough(),
10334
11726
  response: () => z.unknown(),
10335
- effect: "ask", auth: "member", reversible: false,
11727
+ effect: "ask", auth: "member", reversible: false, moves: "value",
10336
11728
  }),
10337
11729
  "plugins:buy-with-one-token": receiver({
10338
11730
  receiver: "plugins:buy-with-one-token",
10339
11731
  summary: "Buys a plugin by verifying a Sui ONE token transfer and granting entitlement with no credit mint",
10340
- request: () => z.object({ name: z.unknown().optional(), tx: z.unknown().optional(), txDigest: z.unknown().optional() }).passthrough(),
11732
+ request: () => z.object({ name: z.unknown().optional(), tx: z.unknown().optional(), txDigest: z.unknown().optional(), ...WORK_CONTRACT_FIELDS }).passthrough(),
10341
11733
  response: () => z.unknown(),
10342
- effect: "ask", auth: "member", reversible: false,
11734
+ // Settles at the call: verifies the token transfer and writes the entitlement — the
11735
+ // same class as wallet:send (a settlement recorded for value that changed hands).
11736
+ effect: "ask", auth: "member", reversible: false, moves: "value",
10343
11737
  }),
10344
11738
  "plugins:credit-balance": receiver({
10345
11739
  receiver: "plugins:credit-balance",
@@ -10401,7 +11795,7 @@ export const RECEIVERS = {
10401
11795
  // A key given to ONE is used for a caller who never holds it: `secrets/` is a worker of
10402
11796
  // its own, reached over the `OPENER` service binding. call + used land here with C6's
10403
11797
  // resolver (one.ie/web/src/lib/resolvers/secrets.ts), `secrets:give` with C8's, `secrets:grant` +
10404
- // `secrets:revoke` with C12's; list lands with its own (C15 — Interface Contract #2). There is NO `secrets:refused`: a
11798
+ // `secrets:revoke` with C12's, `secrets:list` with C15's (Interface Contract #2). There is NO `secrets:refused`: a
10405
11799
  // refusal is `secrets:used` with `refused` set, closed with a warn.
10406
11800
  "secrets:call": receiver({
10407
11801
  receiver: "secrets:call",
@@ -10477,9 +11871,30 @@ export const RECEIVERS = {
10477
11871
  effect: "ask", auth: "authenticated", cost: "free", reversible: false, idempotent: false,
10478
11872
  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>" } } } }],
10479
11873
  }),
11874
+ "secrets:list": receiver({
11875
+ receiver: "secrets:list",
11876
+ // text/secrets.md § What an agent sees: "through the SDK or MCP: names, never values".
11877
+ surfaces: { mcp: true },
11878
+ 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.",
11879
+ 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."),
11880
+ response: () => z.object({
11881
+ ok: z.boolean(),
11882
+ 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)."),
11883
+ 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."),
11884
+ composio: z.array(z.unknown()).optional().describe("Per group you manage: requireGrants ({ vault, on } or null), noGrantToday, noGrantCalls."),
11885
+ 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."),
11886
+ 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."),
11887
+ 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."),
11888
+ cut: z.array(z.string()).optional(),
11889
+ refused: z.string().optional().describe("The opener's: malformed."),
11890
+ 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."),
11891
+ }),
11892
+ effect: "ask", auth: "authenticated", cost: "free", reversible: true, idempotent: true,
11893
+ examples: [{}],
11894
+ }),
10480
11895
  "secrets:grant": receiver({
10481
11896
  receiver: "secrets:grant",
10482
- 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/keys?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.",
11897
+ 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.",
10483
11898
  request: () => z.object({
10484
11899
  signer: z.object({
10485
11900
  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)."),