@oneie/sdk 0.17.6 → 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.
package/dist/receivers.js CHANGED
@@ -220,6 +220,8 @@ export const RECEIVERS = {
220
220
  agentId: z.string().describe("The agent's actor id — the exact string its on-chain SpendCeiling carries as agent_id"),
221
221
  objectId: z.string().describe("The SpendCeiling object id (0x + hex), already handed to the owner with transfer_ownership"),
222
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"),
223
225
  }),
224
226
  response: () => z.object({
225
227
  ok: z.boolean(),
@@ -228,7 +230,7 @@ export const RECEIVERS = {
228
230
  owner: z.string().optional().describe("The owner's address pay verified as the ceiling's live on-chain owner"),
229
231
  status: z.string().optional().describe("pay's registry outcome: created | unchanged | replaced"),
230
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"),
231
- 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"),
232
234
  stage: z.string().optional().describe("On a pay refusal, which call refused: agent (the pay record) | register"),
233
235
  payCode: z.string().nullable().optional().describe("pay's own error code, verbatim, beside the named refusal"),
234
236
  closed: z.string().optional().describe("mark on a registration, warn on every refusal"),
@@ -648,6 +650,11 @@ export const RECEIVERS = {
648
650
  // workspace is a nominated value, so a visitorHash binds only behind this;
649
651
  // undeclared, the edge would strip it and no chat browser would ever bind.
650
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(),
651
658
  freeText: z.string().optional(),
652
659
  source: z.enum(["door", "chat", "asked", "event"]),
653
660
  }),
@@ -1232,12 +1239,12 @@ export const RECEIVERS = {
1232
1239
  totalTokens: z.number().optional(),
1233
1240
  totalCost: z.number().optional().describe("Inference cost in USD — SUM(credit_burns.cost_credits) × USD_PER_CREDIT (1 credit = $0.001)"),
1234
1241
  costPerResolution: z.number().optional().describe("totalCost / journey-complete events; 0 when there were none"),
1235
- revenue: z.number().optional(),
1236
- 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"),
1237
1244
  tokensByAgent: z.array(z.object({ label: z.string(), tokens: z.number(), cost: z.number() })).optional().describe("By MODEL, ranked by cost, top 30"),
1238
1245
  tokensBySkill: z.array(z.object({ label: z.string(), tokens: z.number(), cost: z.number() })).optional(),
1239
1246
  attribution: z.array(z.unknown()).optional(),
1240
- 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."),
1241
1248
  error: z.string().optional().describe("no_db | workspace required | forbidden"),
1242
1249
  }),
1243
1250
  effect: "ask",
@@ -1250,6 +1257,247 @@ export const RECEIVERS = {
1250
1257
  version: "1.0.0",
1251
1258
  examples: [{ workspace: "one" }],
1252
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
+ }),
1253
1501
  "tools:composio": receiver({
1254
1502
  receiver: "tools:composio",
1255
1503
  summary: "Execute one connected Composio tool from a workflow `tool` step (config.composio)",
@@ -3076,6 +3324,30 @@ export const RECEIVERS = {
3076
3324
  }),
3077
3325
  effect: "ask", idempotent: true, auth: "member",
3078
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
+ }),
3079
3351
  "tasks:rename": receiver({
3080
3352
  receiver: "tasks:rename",
3081
3353
  surfaces: { mcp: true },
@@ -4543,6 +4815,45 @@ export const RECEIVERS = {
4543
4815
  effect: "ask",
4544
4816
  idempotent: false,
4545
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
+ }),
4546
4857
  "space:post": receiver({
4547
4858
  receiver: "space:post",
4548
4859
  // auth (member) — task:01a128d6108e551f5966106b: handler: `if (!from) return forbidden` + callerMayPostToSpace (resolvers/messaging.ts:1081-1090).
@@ -5826,21 +6137,30 @@ export const RECEIVERS = {
5826
6137
  request: () => z.object({
5827
6138
  workspace: z.string().optional().describe("Defaults to the attested caller's workspace"),
5828
6139
  actor: z.string().optional().describe("Actor whose spend ceiling is read; defaults to the workspace"),
5829
- // C13 repair 2 — the network the VAULT PROJECTION is read on (the /w `?net=` door);
5830
- // defaults to the deploy's NETWORK. It moves the D1 read only: chain balances stay
5831
- // on the deploy's endpoints. Each row's `vault.net` says which network it answered.
5832
- net: z.enum(["mainnet", "testnet"]).optional().describe("Network whose vault projection the wallet rows read; defaults to the deploy's"),
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"),
5833
6145
  }),
5834
6146
  response: () => z.object({
5835
6147
  workspace: z.string().optional(),
5836
6148
  actor: z.string().optional(),
6149
+ network: z.enum(["mainnet", "testnet"]).optional().describe("The one network every balance row below was read on"),
5837
6150
  credits: z.number().optional(),
5838
6151
  wallets: z.array(z.record(z.string(), z.unknown())).optional(),
5839
6152
  spendCeiling: z.object({
5840
6153
  limitCredits: z.number(), spentCredits: z.number(), remainingCredits: z.number(),
5841
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'.
5842
6158
  balances: z.array(z.object({
5843
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"),
5844
6164
  })).optional(),
5845
6165
  addresses: z.array(z.object({ actor: z.string(), chain: z.string(), address: z.string() })).optional(),
5846
6166
  // The per-agent PROJECTION of the on-chain ceiling (text/launch.md §0d).
@@ -5850,7 +6170,7 @@ export const RECEIVERS = {
5850
6170
  error: z.string().optional(),
5851
6171
  }),
5852
6172
  effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "none", auth: "member",
5853
- examples: [{}, { workspace: "acme" }, { workspace: "acme", actor: "agent:scout" }],
6173
+ examples: [{}, { workspace: "acme" }, { workspace: "acme", actor: "agent:scout" }, { workspace: "acme", net: "mainnet" }],
5854
6174
  }),
5855
6175
  // wallet:update — the owner's one number: how many credits an agent may spend a month.
5856
6176
  // Lowering (and pausing at 0) is open to the workspace's controllers and to the agent for
@@ -5993,6 +6313,15 @@ export const RECEIVERS = {
5993
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)"),
5994
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)"),
5995
6315
  }).optional().describe("Whether this payment raised the payee's score, and if not, why"),
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"),
5996
6325
  error: z.string().optional(),
5997
6326
  }),
5998
6327
  effect: "ask", cost: "variable", reversible: false, idempotent: false, settles: "onchain", auth: "manage_workspace", moves: "value", movesIn: ["workspace", "from"],
@@ -6358,7 +6687,7 @@ export const RECEIVERS = {
6358
6687
  }),
6359
6688
  response: () => z.object({
6360
6689
  ok: z.boolean().describe("true = a quote; false = a named refusal in error"),
6361
- error: z.string().optional().describe("unknown_asset · ambiguous_asset · not_a_destination · hyperliquid_origin_unsupported · bad_amount · bad_slippage · same_asset · oneclick_mainnet_only · sign_in_required · platform_cannot_swap · live_quote_limit · refund_address_unknown · refund_not_yours · ambiguous_address · recipient_address_unknown · recipient_not_yours · toOther_needs_person · destination_unsignable · refund_unsignable · recipient_must_be_named · refund_must_be_named · recipient_invalid · refund_invalid · amount_too_low · amount_too_small_for_fees · exact_out_needs_funded_account · no_liquidity · asset_unsupported · memo_unsupported · quote_refused · oneclick_timeout · oneclick_unavailable · oneclick_error"),
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"),
6362
6691
  detail: z.string().optional().describe("1Click's own message on an upstream refusal, verbatim"),
6363
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)"),
6364
6693
  assets: z.array(SWAP_ASSET).optional().describe("unknown_asset: the whole table (never paged)"),
@@ -6437,7 +6766,7 @@ export const RECEIVERS = {
6437
6766
  }),
6438
6767
  response: () => z.object({
6439
6768
  ok: z.boolean().describe("true = read; false = named refusal"),
6440
- error: z.string().optional().describe("nothing_to_read · address_unknown · bad_address · bad_tx_hash · oneclick_timeout · oneclick_unavailable · oneclick_error · hyperliquid_unavailable"),
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"),
6441
6770
  detail: z.string().optional().describe("1Click's own message on an upstream refusal, verbatim"),
6442
6771
  network: z.string().describe("'mainnet' for the swap"),
6443
6772
  status: z.string().optional().describe("PENDING_DEPOSIT · KNOWN_DEPOSIT_TX · INCOMPLETE_DEPOSIT · PROCESSING · SUCCESS · REFUNDED · FAILED"),
@@ -6481,6 +6810,190 @@ export const RECEIVERS = {
6481
6810
  ],
6482
6811
  effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "none", auth: "public",
6483
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
+ }),
6484
6997
  // wallet:portfolio — the authority walk projected onto wallet rows. One call
6485
6998
  // answers "what does my whole estate hold", which no client could ask before:
6486
6999
  // every wallet read was scoped to one workspace at a time.
@@ -6577,6 +7090,25 @@ export const RECEIVERS = {
6577
7090
  effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "owner",
6578
7091
  examples: [{ workspace: "kiln" }],
6579
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
+ }),
6580
7112
  "shop:stop-live": receiver({
6581
7113
  receiver: "shop:stop-live",
6582
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.",
@@ -6611,6 +7143,7 @@ export const RECEIVERS = {
6611
7143
  }))
6612
7144
  .optional()
6613
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."),
6614
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."),
6615
7148
  currency: z.string().optional().describe("ISO 4217, default USD."),
6616
7149
  brand: z
@@ -6648,8 +7181,10 @@ export const RECEIVERS = {
6648
7181
  steps: z
6649
7182
  .array(z.object({ step: z.string(), ok: z.boolean(), reason: z.string().optional(), detail: z.record(z.string(), z.unknown()).optional() }))
6650
7183
  .optional()
6651
- .describe("storefront · catalogue · images · variants · pages · hero · fill · publish · chat · verify — each ok or failed with a reason. Nothing is skipped silently. `chat` writes the shop assistant (the page chat pack) onto every role page that has none."),
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."),
6652
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)."),
6653
7188
  }),
6654
7189
  effect: "ask", cost: "variable", reversible: false, idempotent: true, auth: "member",
6655
7190
  examples: [{ workspace: "tea-test", description: "A small loose-leaf tea shop in Galway selling single-origin teas, blends and teaware." }],
@@ -7510,6 +8045,34 @@ export const RECEIVERS = {
7510
8045
  effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
7511
8046
  }),
7512
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
+ }),
7513
8076
  // ── nav: — Next is one function (text/navigation.md card 7) ──────────────
7514
8077
  "nav:next": receiver({
7515
8078
  receiver: "nav:next",
@@ -7700,6 +8263,216 @@ export const RECEIVERS = {
7700
8263
  response: () => z.object({ ok: z.boolean(), chars: z.number().optional(), error: z.string().optional() }),
7701
8264
  effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
7702
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
+ }),
7703
8476
  "settings:write": receiver({
7704
8477
  receiver: "settings:write",
7705
8478
  summary: "Write a workspace setting value (caller or authorized descendant)",
@@ -8087,13 +8860,15 @@ export const RECEIVERS = {
8087
8860
  effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "member",
8088
8861
  }),
8089
8862
  // ── booking — one calendar, two doors (text/booking-plan.md §5) ───────────────
8090
- // 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.
8091
8866
  "booking:confirm-payment": receiver({
8092
8867
  receiver: "booking:confirm-payment",
8093
- 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",
8094
8869
  request: () => z.object({ paymentRef: z.string() }),
8095
8870
  response: () => z.object({ ok: z.boolean(), error: z.string().optional() }),
8096
- effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "public",
8871
+ effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "owner",
8097
8872
  }),
8098
8873
  // Both public-bookable: a customer with no account books a slot. The provider
8099
8874
  // side (configure a service) is the separate, gated booking:configure.
@@ -8357,6 +9132,50 @@ export const RECEIVERS = {
8357
9132
  effect: "ask", cost: "free", idempotent: true, simulatable: false, auth: "view_workflows",
8358
9133
  examples: [{ workflowId: "wf_abc", limit: 20 }, { workflowId: "wf_abc", runId: "run_1" }],
8359
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
+ }),
8360
9179
  "workflow:step-stats": receiver({
8361
9180
  receiver: "workflow:step-stats",
8362
9181
  surfaces: { mcp: true },
@@ -8487,6 +9306,8 @@ export const RECEIVERS = {
8487
9306
  stepCount: z.number().optional(),
8488
9307
  warnings: z.array(z.string()).optional(), // §9 advisories (never block); grammar: code | code:stepId
8489
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"),
8490
9311
  error: z.string().optional(), // 'cycle_detected' | 'conflict' | 'invalid_diff' | 'multiple_triggers' | 'edge_unknown_step' | 'invalid_config' | 'bad_expr' | 'unsupported_field'
8491
9312
  }),
8492
9313
  effect: "ask", cost: "free", reversible: true, idempotent: false, simulatable: true,
@@ -8692,9 +9513,25 @@ export const RECEIVERS = {
8692
9513
  "workflow:update": receiver({
8693
9514
  receiver: "workflow:update",
8694
9515
  surfaces: { mcp: true },
8695
- summary: "Rename a workflow or change its status (draft|active|paused)",
8696
- request: () => z.object({ workflowId: z.string(), name: z.string().optional(), status: z.enum(["draft", "active", "paused"]).optional() }),
8697
- 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
+ }),
8698
9535
  effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "manage_workflows",
8699
9536
  examples: [{ workflowId: "wf_abc", name: "Renamed Workflow" }, { workflowId: "wf_abc", status: "paused" }],
8700
9537
  }),
@@ -8789,12 +9626,24 @@ export const RECEIVERS = {
8789
9626
  .max(12)
8790
9627
  .optional()
8791
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."),
8792
9640
  }).catchall(z.unknown()), // extra keys = the agent's input
8793
9641
  response: () => z.object({
8794
9642
  ok: z.boolean(),
8795
9643
  text: z.string().optional(),
8796
9644
  actorId: z.string().optional(),
8797
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)."),
8798
9647
  usage: z
8799
9648
  .object({
8800
9649
  model: z.string(),
@@ -8827,21 +9676,62 @@ export const RECEIVERS = {
8827
9676
  description: z.string().optional(),
8828
9677
  type: z.enum(["meeting", "classroom", "webinar"]).optional(),
8829
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"),
8830
9681
  }),
8831
9682
  response: () => z.object({
8832
9683
  ok: z.boolean(),
8833
9684
  room: z.object({
8834
9685
  slug: z.string(), name: z.string(), description: z.string(),
8835
9686
  type: z.string(), hmsRoomId: z.string(), url: z.string(),
9687
+ access: z.string().optional(), threadId: z.string().nullable().optional(),
8836
9688
  }).optional(),
8837
9689
  error: z.string().optional(),
8838
9690
  }),
8839
9691
  effect: "ask", cost: "free", idempotent: false, auth: "manage_clients",
8840
- 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" }],
8841
9693
  // Fan-out pilot (actions-fan-out C2): offered to chat via chatToolsFor — no
8842
9694
  // curated workspace tool needed; the registry derivation is the whole tool.
8843
9695
  surfaces: { chat: true, mcp: { name: "create_room" } },
8844
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
+ }),
8845
9735
  "video:delete-room": receiver({
8846
9736
  receiver: "video:delete-room",
8847
9737
  surfaces: { mcp: { name: "delete_room" } },
@@ -9303,7 +10193,7 @@ export const RECEIVERS = {
9303
10193
  surfaces: { mcp: true },
9304
10194
  summary: "Seed recipients from audience tag, apply suppression, enqueue the send batch",
9305
10195
  request: () => z.object({ workspace: z.string(), broadcastId: z.string() }),
9306
- 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() }),
9307
10197
  effect: "signal", cost: "variable", reversible: false, idempotent: false, auth: "write",
9308
10198
  }),
9309
10199
  "broadcast:schedule": receiver({
@@ -10377,7 +11267,7 @@ export const RECEIVERS = {
10377
11267
  "campaign:brief": receiver({
10378
11268
  receiver: "campaign:brief",
10379
11269
  summary: "Creates a campaign group from a brief, fires async channels BUILD, and returns the group ID and slug",
10380
- 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(),
10381
11271
  response: () => z.unknown(),
10382
11272
  effect: "ask", auth: "member", reversible: false,
10383
11273
  }),
@@ -10390,8 +11280,8 @@ export const RECEIVERS = {
10390
11280
  }),
10391
11281
  "campaign:update": receiver({
10392
11282
  receiver: "campaign:update",
10393
- summary: "Updates a campaign's name or a specific section's content, and returns the updated campaign info",
10394
- 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(),
10395
11285
  response: () => z.unknown(),
10396
11286
  effect: "ask", auth: "member", reversible: false,
10397
11287
  }),
@@ -10406,6 +11296,46 @@ export const RECEIVERS = {
10406
11296
  response: () => z.unknown(),
10407
11297
  effect: "ask", auth: "member", reversible: false,
10408
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
+ }),
10409
11339
  "campaign:compile": receiver({
10410
11340
  receiver: "campaign:compile",
10411
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",
@@ -10437,7 +11367,9 @@ export const RECEIVERS = {
10437
11367
  "checkout:link": receiver({
10438
11368
  receiver: "checkout:link",
10439
11369
  summary: "Mints a shareable payment link for a product price",
10440
- 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(),
10441
11373
  response: () => z.unknown(),
10442
11374
  // Intent-only: mints a link a buyer later pays — not `moves: "value"`.
10443
11375
  effect: "ask", auth: "owner", reversible: false,
@@ -10636,6 +11568,36 @@ export const RECEIVERS = {
10636
11568
  response: () => z.unknown(),
10637
11569
  effect: "ask", auth: "public", reversible: false,
10638
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
+ }),
10639
11601
  "learning:complete": receiver({
10640
11602
  receiver: "learning:complete",
10641
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",
@@ -10720,6 +11682,22 @@ export const RECEIVERS = {
10720
11682
  response: () => z.unknown(),
10721
11683
  effect: "ask", auth: "session", reversible: false,
10722
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
+ }),
10723
11701
  "pages:chat-generate": receiver({
10724
11702
  receiver: "pages:chat-generate",
10725
11703
  summary: "Generates a deterministic chat pack for a page, updates the database, and returns the pack and its hash",