@oneie/sdk 0.17.0 → 0.17.2

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
@@ -95,6 +95,33 @@ export const RECEIVERS = {
95
95
  }),
96
96
  effect: "ask", auth: "owner", reversible: false, idempotent: false,
97
97
  }),
98
+ // task:01a0bdfb3f29839d65c303aa — pay's /spend-cap/register is SERVICE-ONLY and
99
+ // checks the ceiling's live on-chain owner against the ceilingOwner one.ie hands
100
+ // it. That owner is the agent's CLAIMED human, read server-side from rows the
101
+ // agent cannot write — never a request field, so none is declared here.
102
+ "agent:register-ceiling": receiver({
103
+ receiver: "agent:register-ceiling",
104
+ summary: "The agent's claimed owner, in a signed-in session, registers the agent's on-chain spend ceiling with pay — pay checks the object bounds this agent and is owned by that owner's own address",
105
+ request: () => z.object({
106
+ agentId: z.string().describe("The agent's actor id — the exact string its on-chain SpendCeiling carries as agent_id"),
107
+ objectId: z.string().describe("The SpendCeiling object id (0x + hex), already handed to the owner with transfer_ownership"),
108
+ replace: z.boolean().optional().describe("Replace a ceiling already registered for this agent. Default false: a second registration is refused, not overwritten"),
109
+ }),
110
+ response: () => z.object({
111
+ ok: z.boolean(),
112
+ agentId: z.string().optional(),
113
+ objectId: z.string().optional(),
114
+ owner: z.string().optional().describe("The owner's address pay verified as the ceiling's live on-chain owner"),
115
+ status: z.string().optional().describe("pay's registry outcome: created | unchanged | replaced"),
116
+ 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"),
117
+ 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"),
118
+ stage: z.string().optional().describe("On a pay refusal, which call refused: agent (the pay record) | register"),
119
+ payCode: z.string().nullable().optional().describe("pay's own error code, verbatim, beside the named refusal"),
120
+ closed: z.string().optional().describe("mark on a registration, warn on every refusal"),
121
+ }),
122
+ effect: "ask", cost: "free", reversible: false, idempotent: true, settles: "none", auth: "manage_workspace",
123
+ examples: [{ agentId: "acme--research-agent", objectId: "0x5f3a" }],
124
+ }),
98
125
  "agent:provision": receiver({
99
126
  receiver: "agent:provision",
100
127
  canonical: "agent:enroll",
@@ -529,6 +556,8 @@ export const RECEIVERS = {
529
556
  email: z.string().optional(),
530
557
  phone: z.string().optional(),
531
558
  website: z.string().optional(),
559
+ // social links by platform — a handle, @handle or profile URL; "" removes it
560
+ links: z.record(z.string(), z.string()).optional(),
532
561
  // professional
533
562
  jobTitle: z.string().optional(),
534
563
  company: z.string().optional(),
@@ -917,6 +946,46 @@ export const RECEIVERS = {
917
946
  version: "1.0.0",
918
947
  examples: [{ limit: 5 }],
919
948
  }),
949
+ // crm:advertise — the CRM's Advertise action, `ada:advertise` in text/crm.md.
950
+ // Ads consent is OPT-IN and checked here, in the receiver, so chat, the API and
951
+ // MCP meet the same refusal as the button. It never reaches Meta: it only READS
952
+ // whether a Composio FACEBOOK connection exists.
953
+ "crm:advertise": receiver({
954
+ receiver: "crm:advertise",
955
+ summary: "Add one person to an ad campaign's targeting — refused without their ads consent (opt-in: no record is no), then the campaign's persona/region tags land on them and the campaign:targeting count is read back. Without a campaign, answers the sheet: campaigns, consent, Meta connection",
956
+ request: () => z.object({
957
+ actorId: z.string().describe("The person's actor uid (with or without the `actor:` prefix). Their consent is read from their own row in this group, `actor:<uid>`; a grant filed under their email does not count."),
958
+ campaign: z.string().optional().describe("Ad campaign gid in the caller's attested group. Omit to read the sheet instead of writing."),
959
+ workspace: z.string().optional().describe("Lets a verified SERVICE caller (channels chat) name the group: /api/ask promotes it to the attested group for that caller class only. A session or world-key caller's value is ignored — the group is always the attested one, so the consent read and the tag write can never land in two different groups."),
960
+ }),
961
+ response: () => z.object({
962
+ ok: z.boolean(),
963
+ consent: z.enum(["granted", "required", "declined", "suppressed", "unreadable"]).optional().describe("The person's ads consent. Only `granted` lets them be added; `unreadable` refuses (the gate fails closed)"),
964
+ campaigns: z.array(z.object({ gid: z.string(), name: z.string(), targeting: z.array(z.string()) })).optional().describe("Sheet mode: the group's ad campaigns, newest first, at most 50, and the persona/region tags each would put on a person"),
965
+ truncated: z.boolean().optional().describe("Sheet mode: true when the group has more than 50 ad campaigns and this list is cut"),
966
+ meta: z.object({ state: z.enum(["connected", "not_connected", "unknown"]), connectUrl: z.string() }).optional().describe("Sheet mode: the Composio FACEBOOK connection for this group. `unknown` = could not check, never 'not connected'"),
967
+ added: z.object({
968
+ campaign: z.string(),
969
+ name: z.string(),
970
+ tags: z.array(z.string()).describe("The targeting tags written on the person"),
971
+ holds: z.boolean().describe("The person's row was read back and carries every tag"),
972
+ audienceBefore: z.number().describe("campaign:targeting audienceSize before the write (an OR over the tags — an upper bound)"),
973
+ audienceAfter: z.number().describe("The same count after; it moves by one unless the person already held a tag"),
974
+ }).optional(),
975
+ campaign: z.string().optional(),
976
+ workspace: z.string().optional().describe("Sheet mode: the attested group the answer is about — the group whose campaigns, consent and Meta connection these are"),
977
+ error: z.string().optional().describe("consent_required | consent_declined | consent_suppressed | consent_unreadable | campaign_not_found | campaign_has_no_targeting | campaigns_unreadable | write_failed | write_not_read_back | bad_request | no_db | forbidden"),
978
+ }),
979
+ effect: "ask",
980
+ auth: "manage_lifecycle",
981
+ roleAction: "manage_lifecycle",
982
+ cost: "free",
983
+ idempotent: true,
984
+ reversible: true,
985
+ settles: "none",
986
+ version: "1.0.0",
987
+ examples: [{ actorId: "ada" }, { actorId: "ada", campaign: "01a0..." }],
988
+ }),
920
989
  "campaign:targeting": receiver({
921
990
  receiver: "campaign:targeting",
922
991
  summary: "Size a campaign's audience BEFORE spending on reach — the tag combo plus a distinct-entity count over entity_tags",
@@ -1089,6 +1158,220 @@ export const RECEIVERS = {
1089
1158
  auth: "manage_integrations", roleAction: "manage_integrations",
1090
1159
  examples: [{ endpoint: "thumbs", input: { title: "How we shipped in a week", style: "bold" } }],
1091
1160
  }),
1161
+ // ── agentverse: — a ONE actor as a uAgent on Fetch.ai's Agentverse ─────────
1162
+ // Handlers: one.ie/web/src/lib/resolvers/agentverse.ts. The address is a
1163
+ // SIGNING identity derived from the worker secret UAGENT_MASTER_SECRET (HKDF,
1164
+ // lib/uagents/identity.ts) — never a wallet, never stored. Messages arrive at
1165
+ // POST /api/uagents and are answered by agent:run's own handler, so the
1166
+ // workspace pays for each turn exactly as it does in chat.
1167
+ "agentverse:enroll": receiver({
1168
+ receiver: "agentverse:enroll",
1169
+ summary: "Make one of the workspace's agents reachable on Agentverse / ASI:One: derive its uAgents address, enable it at https://one.ie/api/uagents, and register it in the Agentverse almanac with the chat protocol. Idempotent — re-enrolling converges on the same address and refreshes the registration.",
1170
+ request: () => z.object({
1171
+ workspace: z.string().optional().describe("Group slug. Omit for your own. A scope REQUEST — refused when the authority walk says no, never swapped for your own."),
1172
+ actor: z.string().describe("The actor id of the agent to publish (the persona channels resolves for agent:run), e.g. `ceo`."),
1173
+ }),
1174
+ response: () => z.object({
1175
+ ok: z.boolean(),
1176
+ workspace: z.string().optional(),
1177
+ actor: z.string().optional(),
1178
+ address: z.string().optional().describe("The agent's uAgents address (bech32 `agent1…`). Message it from ASI:One or any uAgent."),
1179
+ endpoint: z.string().optional(),
1180
+ registered: z.boolean().optional().describe("true once the almanac accepted the attestation and the status update. false with `error` means the row is enabled but the almanac refused — the daily re-registration retries it."),
1181
+ registeredUntil: z.number().optional().describe("Almanac record expiry, ms since epoch. Re-registered daily before it."),
1182
+ protocols: z.array(z.string()).optional().describe("The protocol digests the almanac record advertises: the chat protocol, plus the payment seller role when the agent is actually charging (agentverse:price)."),
1183
+ manifests: z.record(z.string(), z.string()).optional().describe("Per advertised digest, `ok` or the named reason the almanac refused its manifest (almanac_manifest_<status> · almanac_unreachable). A refused manifest is retried by the daily tick; it does not undo the registration."),
1184
+ error: z.string().optional().describe("Named: unauthorized · forbidden · bad_request · uagent_secret_unset · not_configured · almanac_<status> · almanac_status_<status> · almanac_unreachable."),
1185
+ }),
1186
+ effect: "ask", cost: "free", reversible: true, idempotent: true,
1187
+ auth: "manage_integrations", roleAction: "manage_integrations",
1188
+ examples: [{ workspace: "one", actor: "ceo" }],
1189
+ }),
1190
+ "agentverse:unenroll": receiver({
1191
+ receiver: "agentverse:unenroll",
1192
+ summary: "Unpublish one of the workspace's agents from Agentverse / ASI:One: disable its row so https://one.ie/api/uagents stops routing to it at once, and the daily re-registration stops refreshing it. The almanac record is not deleted (the almanac has no delete) — it lapses on its own within about 7 days (`lapsesAt`). agentverse:enroll re-publishes the same address.",
1193
+ request: () => z.object({
1194
+ workspace: z.string().optional().describe("Group slug. Omit for your own. Refused when the authority walk says no."),
1195
+ actor: z.string().describe("The enrolled actor id, e.g. `ceo`."),
1196
+ }),
1197
+ response: () => z.object({
1198
+ ok: z.boolean(),
1199
+ workspace: z.string().optional(),
1200
+ actor: z.string().optional(),
1201
+ address: z.string().optional(),
1202
+ enabled: z.literal(false).optional(),
1203
+ lapsesAt: z.number().nullable().optional().describe("When the almanac record expires by itself, ms since epoch. null = it was never confirmed or has already lapsed."),
1204
+ error: z.string().optional().describe("Named: unauthorized · forbidden · bad_request · not_enrolled · not_configured."),
1205
+ }),
1206
+ effect: "ask", cost: "free", reversible: true, idempotent: true,
1207
+ auth: "manage_integrations", roleAction: "manage_integrations",
1208
+ examples: [{ workspace: "one", actor: "ceo" }],
1209
+ }),
1210
+ "agentverse:status": receiver({
1211
+ receiver: "agentverse:status",
1212
+ summary: "Read which of the workspace's agents are enrolled on Agentverse, their uAgents addresses and when each almanac registration expires. Read-only.",
1213
+ request: () => z.object({
1214
+ workspace: z.string().optional().describe("Group slug. Omit for your own. Refused when the authority walk says no."),
1215
+ actor: z.string().optional().describe("Only this actor's row."),
1216
+ }),
1217
+ response: () => z.object({
1218
+ ok: z.boolean(),
1219
+ workspace: z.string().optional(),
1220
+ endpoint: z.string().optional(),
1221
+ agents: z.array(z.object({
1222
+ actor: z.string(),
1223
+ address: z.string(),
1224
+ enabled: z.boolean(),
1225
+ registeredUntil: z.number().nullable(),
1226
+ registered: z.boolean().describe("registeredUntil is in the future."),
1227
+ })).optional(),
1228
+ error: z.string().optional(),
1229
+ }),
1230
+ effect: "ask", cost: "free", idempotent: true,
1231
+ auth: "manage_integrations", roleAction: "manage_integrations",
1232
+ examples: [{ workspace: "one" }],
1233
+ }),
1234
+ // ── agentverse: OUTBOUND — a ONE agent messaging an Agentverse agent ───────
1235
+ // Handlers: one.ie/web/src/lib/resolvers/agentverse-outbound.ts; the wire is
1236
+ // lib/uagents/outbound.ts. No `roleAction` on send/reply on purpose: a workflow
1237
+ // `tool` step (`config.receiver: "agentverse:send"`) must not be ceiling-denied
1238
+ // below the integrations rung — the resolver's workspace-control check is the gate.
1239
+ // `surfaces.chat` makes all three chat tools for ONE's own agents (channels
1240
+ // from-registry.ts), dispatched through the ask door with the attested workspace.
1241
+ "agentverse:search": receiver({
1242
+ receiver: "agentverse:search",
1243
+ summary: "Search the Fetch.ai Agentverse index for agents to talk to. Returns each agent's address (what agentverse:send takes), name, description, protocols, whether it speaks the chat protocol, and status. Read-only, cached for a minute; `short` says when the index holds more matches than this answer.",
1244
+ request: () => z.object({
1245
+ query: z.string().describe("What to search for, in words — e.g. `weather`, `flight booking`."),
1246
+ protocol: z.string().optional().describe("`chat` (default — only agents agentverse:send can talk to), `any`, or a protocol digest (`proto:<64 hex>`)."),
1247
+ limit: z.number().optional().describe("How many to return. Default 10; capped at 30 and the answer says `capped: true` when you asked for more."),
1248
+ }),
1249
+ response: () => z.object({
1250
+ ok: z.boolean(),
1251
+ query: z.string().optional(),
1252
+ protocol: z.string().nullable().optional(),
1253
+ agents: z.array(z.object({
1254
+ address: z.string(),
1255
+ name: z.string(),
1256
+ description: z.string().describe("Cut at 300 characters."),
1257
+ protocols: z.array(z.object({ digest: z.string(), name: z.string().nullable(), version: z.string().nullable() })),
1258
+ chat: z.boolean().describe("Speaks the uAgents chat protocol."),
1259
+ status: z.string().describe("active · inactive · unresponsive (the index's own flag)."),
1260
+ type: z.string().nullable(),
1261
+ rating: z.number().nullable(),
1262
+ interactions: z.number().nullable(),
1263
+ })).optional(),
1264
+ returned: z.number().optional(),
1265
+ total: z.number().nullable().optional().describe("The index's own count of matches."),
1266
+ short: z.boolean().optional().describe("true when total > returned — this answer is a page, not every match."),
1267
+ capped: z.boolean().optional(),
1268
+ limit: z.number().optional(),
1269
+ cached: z.boolean().optional(),
1270
+ error: z.string().optional().describe("Named: bad_request · agentverse_rate_limited · agentverse_<status> · agentverse_unreachable · agentverse_too_large · agentverse_bad_response."),
1271
+ }),
1272
+ effect: "ask", cost: "free", idempotent: true,
1273
+ auth: "read",
1274
+ surfaces: { chat: true },
1275
+ examples: [{ query: "weather", limit: 5 }],
1276
+ }),
1277
+ "agentverse:send": receiver({
1278
+ receiver: "agentverse:send",
1279
+ summary: "Message one Agentverse agent by address, as one of your workspace's enrolled agents (agentverse:enroll), and wait up to timeout_s for its reply. Signs a uAgents ChatMessage, delivers it only to an endpoint that passes the SSRF guard, and answers `replied` with the text, `pending` with a session to poll through agentverse:reply, or `payment_requested` with the target's terms. Costs no FET and NEVER pays — a payment request is surfaced, not settled.",
1280
+ request: () => z.object({
1281
+ workspace: z.string().optional().describe("Group slug. Omit for your own. A scope REQUEST — refused when the authority walk says no."),
1282
+ from_actor: z.string().describe("The actor id of YOUR enrolled agent to speak as, e.g. `ceo`. Must be enrolled and registered (agentverse:status)."),
1283
+ to_address: z.string().describe("The target's Agentverse address, `agent1…` — from agentverse:search."),
1284
+ text: z.string().describe("What to say. Cut at 4000 characters, and the answer says `text_truncated: true`."),
1285
+ timeout_s: z.number().optional().describe("Seconds to wait for the reply inside this call. Default 20; capped at 40 (`timeout_capped: true`). 0 sends and returns `pending` at once."),
1286
+ }),
1287
+ response: () => z.object({
1288
+ ok: z.boolean(),
1289
+ workspace: z.string().optional(),
1290
+ from: z.string().optional().describe("Our agent's address the message was signed by."),
1291
+ to: z.string().optional(),
1292
+ session: z.string().optional().describe("The conversation id — pass it to agentverse:reply."),
1293
+ status: z.enum(["replied", "pending", "payment_requested", "failed", "expired"]).optional(),
1294
+ reply: z.string().optional().describe("Every text the target sent on this conversation, joined; cut at 8000 characters (`truncated: true`)."),
1295
+ replies: z.number().optional(),
1296
+ truncated: z.boolean().optional(),
1297
+ payment: z.object({
1298
+ accepted_funds: z.array(z.object({ amount: z.string(), currency: z.string(), payment_method: z.string() })),
1299
+ recipient: z.string(),
1300
+ deadline_seconds: z.number().nullable(),
1301
+ reference: z.string().nullable(),
1302
+ description: z.string().nullable(),
1303
+ }).optional().describe("Present when status is payment_requested. NOT paid."),
1304
+ poll: z.object({ receiver: z.literal("agentverse:reply"), data: z.object({ session: z.string() }) }).optional(),
1305
+ timeout_s: z.number().optional(),
1306
+ timeout_capped: z.boolean().optional(),
1307
+ text_truncated: z.boolean().optional(),
1308
+ detail: z.string().optional(),
1309
+ retryAfterS: z.number().optional(),
1310
+ error: z.string().optional().describe("Named: unauthorized · forbidden · bad_request · not_configured · not_enrolled · not_registered · own_agent · rate_limited · uagent_secret_unset · identity_mismatch · endpoint_blocked:<reasons> · unreachable:<almanac error> · delivery_failed_<status> · delivery_redirect_refused_<status>."),
1311
+ }),
1312
+ effect: "ask", cost: "free", reversible: false, idempotent: false,
1313
+ auth: "manage_integrations",
1314
+ surfaces: { chat: true },
1315
+ examples: [{ from_actor: "ceo", to_address: "agent1qfvydlgcxrvga2kqjxhj3hpngegtysm2c7uk48ywdue0kgvtc2f5cwhyffv", text: "What is the weather in Dublin?", timeout_s: 30 }],
1316
+ }),
1317
+ "agentverse:reply": receiver({
1318
+ receiver: "agentverse:reply",
1319
+ summary: "Read a conversation agentverse:send started: `replied` with the text, `pending` while the target has not answered, `payment_requested` with its terms (never paid), `failed`, or `expired` after an hour with no reply. Read-only.",
1320
+ request: () => z.object({
1321
+ session: z.string().describe("The `session` agentverse:send returned."),
1322
+ }),
1323
+ response: () => z.object({
1324
+ ok: z.boolean(),
1325
+ workspace: z.string().optional(),
1326
+ from: z.string().optional(),
1327
+ to: z.string().optional(),
1328
+ session: z.string().optional(),
1329
+ status: z.enum(["replied", "pending", "payment_requested", "failed", "expired"]).optional(),
1330
+ reply: z.string().optional(),
1331
+ replies: z.number().optional(),
1332
+ truncated: z.boolean().optional(),
1333
+ payment: z.unknown().optional(),
1334
+ poll: z.unknown().optional(),
1335
+ detail: z.string().optional(),
1336
+ error: z.string().optional().describe("Named: bad_request · not_configured · not_found (also what a session you cannot see answers)."),
1337
+ }),
1338
+ effect: "ask", cost: "free", idempotent: true,
1339
+ auth: "manage_integrations",
1340
+ surfaces: { chat: true },
1341
+ examples: [{ session: "6f1c2a0e-1b7d-4c55-9a43-2f0d8f1e9b21" }],
1342
+ }),
1343
+ // Handler: one.ie/web/src/lib/resolvers/agentverse-price.ts. A priced agent
1344
+ // answers ASI:One only after a verified FET payment (uAgents payment protocol,
1345
+ // seller role — lib/uagents/payment.ts). Money only comes IN.
1346
+ "agentverse:price": receiver({
1347
+ receiver: "agentverse:price",
1348
+ summary: "Set (or, without `priceFet`, read) what one answer from an enrolled Agentverse agent costs in native FET. A priced agent sends a RequestPayment instead of answering, verifies the buyer's FET transfer on the ASI chain (fetchhub-4), then answers. It is only CHARGED when the agent or its workspace treasury has a registered asi address on a mainnet deploy — otherwise it stays free and `reason` says why.",
1349
+ request: () => z.object({
1350
+ workspace: z.string().optional().describe("Group slug. Omit for your own. Refused when the authority walk says no."),
1351
+ actor: z.string().describe("The enrolled actor id (agentverse:enroll first), e.g. `ceo`."),
1352
+ priceFet: z.union([z.string(), z.number(), z.null()]).optional().describe("Whole FET per answer as a decimal, e.g. \"0.5\" (at most 18 decimals). null, \"\" or 0 = free. Omit to read the current price without changing it."),
1353
+ }),
1354
+ response: () => z.object({
1355
+ ok: z.boolean(),
1356
+ workspace: z.string().optional(),
1357
+ actor: z.string().optional(),
1358
+ address: z.string().optional(),
1359
+ priceFet: z.string().nullable().optional().describe("The stored price, canonical decimal FET. null = free."),
1360
+ currency: z.literal("FET").optional(),
1361
+ charging: z.boolean().optional().describe("true only when the price is set AND there is a real asi address to be paid at AND the deploy is on mainnet."),
1362
+ recipient: z.string().optional().describe("The `fetch1…` address buyers pay — the agent's own asi address, else the workspace treasury's."),
1363
+ custody: z.enum(["self", "via-treasury"]).optional(),
1364
+ reason: z.string().optional().describe("Why it is free: free · no_asi_address · no_fetch_network."),
1365
+ protocols: z.array(z.string()).optional().describe("Set on a price change to an enabled agent: the digests now advertised — the payment seller role is added when charging, dropped when not."),
1366
+ reregistered: z.boolean().optional().describe("Set on a price change: whether the almanac took the new protocol list now. false keeps the price; `reregisterError` says why, and the daily tick retries."),
1367
+ reregisterError: z.string().optional(),
1368
+ manifests: z.record(z.string(), z.string()).optional().describe("Per advertised digest, `ok` or the named reason the almanac refused its manifest."),
1369
+ error: z.string().optional().describe("Named: unauthorized · forbidden · bad_request · not_enrolled · not_configured."),
1370
+ }),
1371
+ effect: "ask", cost: "free", reversible: true, idempotent: true,
1372
+ auth: "manage_integrations", roleAction: "manage_integrations",
1373
+ examples: [{ workspace: "one", actor: "ceo", priceFet: "0.5" }],
1374
+ }),
1092
1375
  "brand:set": receiver({
1093
1376
  receiver: "brand:set",
1094
1377
  summary: "Write up to 6 brand color tokens (primary/secondary/accent/bg/text/border) to a workspace theme",
@@ -3728,6 +4011,7 @@ export const RECEIVERS = {
3728
4011
  description: z.string(),
3729
4012
  price_usd: z.number(),
3730
4013
  })),
4014
+ store: z.array(z.object({ kind: z.enum(["agent", "skill"]), id: z.string(), model: z.string(), credits: z.number(), resultCredits: z.number().optional(), attribution: z.string().optional(), on_sale: z.boolean() })).optional(),
3731
4015
  }),
3732
4016
  effect: "ask", cost: "free", idempotent: true,
3733
4017
  examples: [{}],
@@ -3738,6 +4022,9 @@ export const RECEIVERS = {
3738
4022
  request: () => z.object({
3739
4023
  name: z.string(),
3740
4024
  method: z.enum(["stripe", "credits"]).optional(),
4025
+ kind: z.enum(["plugin", "agent", "skill"]).optional(),
4026
+ uses: z.number().optional(),
4027
+ idem: z.string().optional(),
3741
4028
  }),
3742
4029
  response: () => z.object({
3743
4030
  method: z.enum(["stripe", "credits"]),
@@ -3750,6 +4037,10 @@ export const RECEIVERS = {
3750
4037
  entitled: z.boolean().optional(),
3751
4038
  already: z.boolean().optional(),
3752
4039
  credits_spent: z.number().optional(),
4040
+ kind: z.enum(["plugin", "agent", "skill"]).optional(),
4041
+ item: z.string().optional(),
4042
+ model: z.string().optional(),
4043
+ uses: z.number().optional(),
3753
4044
  plugin: z.string(),
3754
4045
  feature: z.string(),
3755
4046
  }),
@@ -4371,7 +4662,9 @@ export const RECEIVERS = {
4371
4662
  // zod's PARSED output, so an undeclared key is stripped at the HTTP edge and
4372
4663
  // never reaches the handler. `delivery_r2_key` is accepted ONLY as a
4373
4664
  // `{kind}:{ref}` install descriptor — the plain-R2-key write door stays shut.
4374
- product_kind: z.literal("artifact").optional(),
4665
+ // 'physical' | 'one_time' are the seller's shipping switch (a plain product either ships a
4666
+ // parcel or does not; one_time, the default, does not) and take no delivery key.
4667
+ product_kind: z.enum(["artifact", "physical", "one_time"]).optional(),
4375
4668
  delivery_r2_key: z.string().optional(),
4376
4669
  }),
4377
4670
  response: () => z.object({ pid: z.string().optional(), ppid: z.string().optional(), name: z.string().optional(), workspace: z.string().optional(), error: z.string().optional() }),
@@ -4383,22 +4676,26 @@ export const RECEIVERS = {
4383
4676
  // `status` carries the same history as on products:create — the resolver has
4384
4677
  // always read it, the declaration never listed it, so zod stripped it and a
4385
4678
  // draft product could not be published through this receiver either.
4386
- request: () => z.object({ slug: z.string(), pid: z.string(), name: z.string().optional(), description: z.string().optional(), images: z.array(z.string()).optional(), collection: z.string().optional(), status: z.enum(["draft", "active", "archived"]).optional(), product_kind: z.literal("artifact").optional(), delivery_r2_key: z.string().optional() }),
4679
+ request: () => z.object({ slug: z.string(), pid: z.string(), name: z.string().optional(), description: z.string().optional(), images: z.array(z.string()).optional(), collection: z.string().optional(), status: z.enum(["draft", "active", "archived"]).optional(), product_kind: z.enum(["artifact", "physical", "one_time"]).optional(), delivery_r2_key: z.string().optional() }),
4387
4680
  response: () => z.object({ pid: z.string().optional(), workspace: z.string().optional(), error: z.string().optional() }),
4388
4681
  effect: "ask", cost: "free", reversible: false, idempotent: true, auth: "member",
4389
4682
  }),
4390
4683
  "products:list": receiver({
4391
4684
  receiver: "products:list",
4392
- summary: "List a workspace's storefront products with their prices (public)",
4685
+ surfaces: { mcp: true },
4686
+ summary: "List a workspace's storefront products with their prices (public). To buy as an agent: open an ACP session with POST /api/checkout_sessions, or pay the item's x402 link.",
4393
4687
  request: () => z.object({
4394
4688
  slug: z.string().optional(),
4395
- collection: z.string().optional().describe("Narrow the catalogue to one collection, matched TRIMMED on both sides (the facet label is derived as `(collection ?? '').trim()`, so an untrimmed predicate would match zero rows and filter everything). Empty or unknown returns the whole catalogue, never an error. Public: it can only narrow rows an anonymous caller could already see — unlike includeDrafts, which is honoured only for the attested owner and is deliberately NOT declared here."),
4689
+ collection: z.string().optional().describe("Narrow the catalogue to one collection, matched TRIMMED on both sides (the facet label is derived as `(collection ?? '').trim()`, so an untrimmed predicate would match zero rows and filter everything). Empty or unknown returns the whole catalogue, never an error. Public: it can only narrow rows an anonymous caller could already see — unlike includeDrafts, which is honoured only for the attested owner (ctx.ownerSlug), never a body claim."),
4690
+ includeDrafts: z.boolean().optional().describe("Owner-only: true returns draft products and every active price row. Honoured only when the attested caller owns slug (ctx.ownerSlug === slug); for anyone else it is ignored, never an error."),
4691
+ sort: z.string().optional().describe("featured | newest | price-asc | price-desc, trimmed and lower-cased by the resolver; anything else orders as featured (updated_at desc)."),
4396
4692
  }),
4397
4693
  response: () => z.object({ products: z.array(z.record(z.string(), z.unknown())).optional(), error: z.string().optional() }),
4398
4694
  effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "public",
4399
4695
  }),
4400
4696
  "products:get": receiver({
4401
4697
  receiver: "products:get",
4698
+ surfaces: { mcp: true },
4402
4699
  summary: "Get one storefront product with its prices (public, active-only) — the single-record read a data-bound page block resolves through",
4403
4700
  request: () => z.object({ slug: z.string(), pid: z.string() }),
4404
4701
  response: () => z.object({ product: z.record(z.string(), z.unknown()).nullable().optional(), error: z.string().optional() }),
@@ -4649,6 +4946,73 @@ export const RECEIVERS = {
4649
4946
  effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "none", auth: "public",
4650
4947
  examples: [{ workspace: "acme", token: "<uid>.<exp>.<sig>" }],
4651
4948
  }),
4949
+ // ── reviews:* — product reviews (handler: one.ie/web/src/lib/resolvers/reviews.ts, E1a/E1b) ──
4950
+ // A review is a D1 row (0292). Only a VERIFIED PURCHASER writes: identity is the
4951
+ // uid the signed orders link token proves (the same credential orders:mine takes),
4952
+ // and "verified" is a LIVE read of a paid/active order line of that uid at that
4953
+ // shop naming the product — never a stored flag. There is deliberately NO
4954
+ // customer_uid / email / buyer field. Average and count are derived per read;
4955
+ // review text comes back fenced as foreign data. Moderation is the seller's.
4956
+ "reviews:write": receiver({
4957
+ receiver: "reviews:write",
4958
+ summary: "Write a product review as a verified purchaser — identity from the signed order-history link token, never from the body",
4959
+ request: () => z.object({
4960
+ workspace: z.string().describe("The SELLER's slug — whose shop the product and the order belong to. Bound into the token's MAC."),
4961
+ pid: z.string().describe("The product reviewed. Verified against an order line naming it (by pid, or by a ppid that maps to it)."),
4962
+ rating: z.number().int().min(1).max(5).describe("Stars, an integer 1..5."),
4963
+ body: z.string().describe("The review text, 1..2000 characters after trimming. Stored trimmed; returned fenced."),
4964
+ token: z.string().describe("The signed order-history link token (`<uid>.<exp>.<sig>`). The ONLY source of reviewer identity."),
4965
+ }),
4966
+ response: () => z.object({
4967
+ ok: z.boolean().optional(),
4968
+ rid: z.string().optional(),
4969
+ pid: z.string().optional(),
4970
+ state: z.string().optional().describe("`published` on a fresh write."),
4971
+ error: z.string().optional().describe("`workspace_required`, `pid_required`, `invalid_rating`, `invalid_body`, `no_db`, `link_not_configured`, `forbidden`, `link_expired`, `not_verified_purchaser`, `already_reviewed`."),
4972
+ status: z.number().optional(),
4973
+ }),
4974
+ effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "none", auth: "public",
4975
+ examples: [{ workspace: "acme", pid: "prod_mug", rating: 5, body: "Holds heat.", token: "<uid>.<exp>.<sig>" }],
4976
+ }),
4977
+ "reviews:list": receiver({
4978
+ receiver: "reviews:list",
4979
+ summary: "List a product's published reviews with the DERIVED average and count, and how many are hidden",
4980
+ request: () => z.object({
4981
+ workspace: z.string().describe("The seller's slug."),
4982
+ pid: z.string().describe("The product."),
4983
+ limit: z.number().int().positive().optional().describe("Page size, default 20, clamped to 1..50."),
4984
+ }),
4985
+ response: () => z.object({
4986
+ ok: z.boolean().optional(),
4987
+ average: z.number().nullable().optional().describe("Mean rating over published reviews, 2 decimals; null when there are none — never a default."),
4988
+ count: z.number().optional().describe("EXACT count of published reviews."),
4989
+ hidden: z.number().optional().describe("Count of reviews the seller hid."),
4990
+ returned: z.number().optional(),
4991
+ truncated: z.boolean().optional().describe("True when `returned` < `count` — this page is short of the whole."),
4992
+ reviews: z.unknown().optional().describe("Fenced foreign data: rows of { rid, rating, body, vid, createdAt }. No buyer hash, no order id."),
4993
+ error: z.string().optional(),
4994
+ }).passthrough(),
4995
+ effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "none", auth: "public",
4996
+ examples: [{ workspace: "acme", pid: "prod_mug" }],
4997
+ }),
4998
+ "reviews:moderate": receiver({
4999
+ receiver: "reviews:moderate",
5000
+ summary: "Hide or re-publish one review — the seller workspace only",
5001
+ request: () => z.object({
5002
+ workspace: z.string().describe("The seller's slug; the caller must control it."),
5003
+ rid: z.string().describe("The review id."),
5004
+ state: z.enum(["published", "hidden"]),
5005
+ }),
5006
+ response: () => z.object({
5007
+ ok: z.boolean().optional(),
5008
+ rid: z.string().optional(),
5009
+ state: z.string().optional(),
5010
+ error: z.string().optional().describe("`workspace_required`, `rid_required`, `invalid_state`, `forbidden`, `no_db`, `not_found`."),
5011
+ status: z.number().optional(),
5012
+ }),
5013
+ effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "none", auth: "member",
5014
+ examples: [{ workspace: "acme", rid: "rev_…", state: "hidden" }],
5015
+ }),
4652
5016
  // ── orders:send-link — the MINT orders:mine named and did not build ──────────
4653
5017
  // (handler: resolvers/storefront/orders-send-link.ts)
4654
5018
  //
@@ -5036,7 +5400,7 @@ export const RECEIVERS = {
5036
5400
  // things happened, so no reader has to infer it. All optional: a response
5037
5401
  // carries the pair that matches its branch, never all of them at once.
5038
5402
  twoLedgerCheck: z.string().optional().describe("'in_force' = the two-ledger check RAN; twoLedgerVerdict says what it found. 'not_in_force' = the check DID NOT RUN — no SPEND_CEILING_READER is bound, or there is no agent-kind wallet — so nothing here was verified against the chain. Never read 'not_in_force' as a pass"),
5039
- twoLedgerVerdict: z.string().optional().describe("Only when the check RAN: 'agree' — the ONE walk's key IS the on-chain ceiling owner. 'mismatch' and 'unknown' never reach a success response; both refuse at stage 'authority'"),
5403
+ twoLedgerVerdict: z.string().optional().describe("Only when the check RAN: 'agree' — the agent's claimed human's address IS the on-chain ceiling owner. 'mismatch' and 'unknown' never reach a success response; both refuse at stage 'authority'"),
5040
5404
  twoLedgerReason: z.string().optional().describe("Only when twoLedgerCheck is 'not_in_force': why the check did not run — reader_unconfigured | no_agent_wallet"),
5041
5405
  twoLedgerDetail: z.string().optional().describe("Only when twoLedgerCheck is 'not_in_force': plain-language statement of what was NOT verified, so an absent check can never be mistaken for a passed one"),
5042
5406
  // The stage 'authority' refusal shape (TwoLedgerRefusal). `cause` is what
@@ -5044,12 +5408,152 @@ export const RECEIVERS = {
5044
5408
  // response parse would strip exactly that.
5045
5409
  verdict: z.string().optional().describe("On a stage 'authority' refusal: mismatch | unknown. 'unknown' FAILS CLOSED — an unresolvable read is never 'no objection'"),
5046
5410
  detail: z.string().optional().describe("On a stage 'authority' refusal: what was refused, and plainly that this refuses to RECORD the transfer — it cannot prevent or reverse an on-chain transfer the caller already signed and broadcast client-side"),
5047
- cause: z.string().optional().describe("On a stage 'authority' refusal, which read decided it: no_attested_caller | no_snapshot_binding | wallet_read_failed | ceiling_unresolvable | owners_disagree | ceiling_revoked. A public identifier, never a value"),
5411
+ cause: z.string().optional().describe("On a stage 'authority' refusal, which read decided it: no_attested_caller | no_snapshot_binding | wallet_read_failed | human_unresolvable (the agent has no claimed human with a Sui address) | ceiling_unresolvable | owners_disagree | ceiling_revoked. A public identifier, never a value"),
5048
5412
  error: z.string().optional(),
5049
5413
  }),
5050
5414
  effect: "ask", cost: "variable", reversible: false, idempotent: false, settles: "onchain", auth: "manage_workspace",
5051
5415
  examples: [{ to: "0xabc", chain: "SUI", amount: 5, paymentTx: "8xKvQ1" }],
5052
5416
  }),
5417
+ // text/key.md deliverable 8 — bound what an agent HOLDS. Tony, 2026-10-06:
5418
+ // "the sweep is signed by the human who owns the agent; agents can be claimed
5419
+ // by any owner." The owner (actor_owners claimant) signs an ORDER; the agent's
5420
+ // runtime performs the transfer it names. The destination is NEVER a request
5421
+ // field: it is the owner's PROVEN address (wallet:sweep-set), and a body naming
5422
+ // one is refused (destination_not_accepted). Never signs anything itself.
5423
+ "wallet:sweep": receiver({
5424
+ receiver: "wallet:sweep",
5425
+ summary: "Settle an agent's balance above its float to its claimed owner on the owner's signed order — is a sweep due, verify the order, or settle it. Never signs; the destination is never a request field",
5426
+ request: () => z.object({
5427
+ actor: z.string().optional().describe("The agent whose wallet is swept; defaults to `workspace` (an agent workspace)"),
5428
+ workspace: z.string().optional().describe("The workspace that holds the agent's wallets row; defaults to the attested caller"),
5429
+ chain: z.enum(["sui", "evm", "solana", "btc"]).optional().describe("Wallet chain family; default sui"),
5430
+ // z.unknown, not a typed union: the resolver's strict parsers must see
5431
+ // every junk value and warn on it by name, never a silent edge 400.
5432
+ balance: z.unknown().optional().describe("Due / verify modes: the agent's balance on `chain` in INTEGER BASE UNITS (mist, wei, lamports, sats) as a digit string. Anything else is refused — never read as 0"),
5433
+ order: z.unknown().optional().describe("Verify mode: { destination, amount (base-unit digit string), nonce (16–128 of [A-Za-z0-9_-]), expiresAt (unix ms) } as the owner signed it"),
5434
+ signature: z.unknown().optional().describe("Verify mode: { publicKey, signature } (hex) by the owner's proven address over the 'ONE sweep order' statement"),
5435
+ nonce: z.unknown().optional().describe("Settle mode: the nonce of an order this door already verified"),
5436
+ pending: z.boolean().optional().describe("Pending mode (the agent runtime's read): the owner's proven address, the agent's address and every unsettled, unexpired order with its owner signature"),
5437
+ paymentTx: z.unknown().optional().describe("Settle mode: the tx hash of the transfer the agent's runtime signed for exactly the verified order"),
5438
+ // DECLARED SO THEY ARE REFUSED, NOT STRIPPED. The edge dispatches zod's
5439
+ // parsed output; an undeclared `to` would vanish silently and the caller
5440
+ // would believe it steered the sweep.
5441
+ to: z.unknown().optional().describe("REFUSED — the destination is the owner's proven address, never a request field"),
5442
+ destination: z.unknown().optional().describe("REFUSED — see `to` (the order's own destination lives inside `order`)"),
5443
+ address: z.unknown().optional().describe("REFUSED — see `to`"),
5444
+ treasury: z.unknown().optional().describe("REFUSED — see `to`"),
5445
+ treasuries: z.unknown().optional().describe("REFUSED — see `to`"),
5446
+ userAddress: z.unknown().optional().describe("REFUSED — the sender is the agent's own wallets row"),
5447
+ }),
5448
+ response: () => z.object({
5449
+ ok: z.boolean(),
5450
+ due: z.boolean().optional().describe("Due mode: the balance is above the threshold; ask the owner for an order up to maxUnits"),
5451
+ verified: z.boolean().optional().describe("Verify mode: the owner's order is valid and recorded — perform the transfer it names"),
5452
+ settled: z.boolean().optional().describe("Settle mode: pay.one.ie claimed the transfer at the owner's address"),
5453
+ reason: z.string().optional(),
5454
+ workspace: z.string().optional(),
5455
+ actor: z.string().optional(),
5456
+ chain: z.string().optional(),
5457
+ owner: z.string().optional().describe("The claimed owner (actor_owners)"),
5458
+ to: z.string().optional().describe("The owner's proven address — resolved server-side, never supplied"),
5459
+ nonce: z.string().optional(),
5460
+ amountUnits: z.string().optional(),
5461
+ amount: z.string().optional().describe("amountUnits as an exact token decimal"),
5462
+ maxUnits: z.string().optional().describe("Due mode: balance − float, the most an order may move"),
5463
+ pending: z.boolean().optional(),
5464
+ agentAddress: z.string().optional().describe("Pending mode: the agent's own address on `chain` — the runner checks its key derives it"),
5465
+ floatUnits: z.string().optional(),
5466
+ orders: z.array(z.object({
5467
+ nonce: z.unknown(), destination: z.unknown(), amountUnits: z.string(), expiresAt: z.number(), signature: z.unknown(),
5468
+ })).optional().describe("Pending mode: unsettled, unexpired orders the current owner signed to its current proven address"),
5469
+ keepUnits: z.string().optional(),
5470
+ freeUnits: z.string().optional(),
5471
+ thresholdUnits: z.string().optional(),
5472
+ expiresAt: z.number().optional(),
5473
+ stage: z.string().optional().describe("Settle mode failure: which pay.one.ie stage refused"),
5474
+ paymentTx: z.string().optional(),
5475
+ receipt: z.object({ id: z.string(), url: z.string() }).optional(),
5476
+ closed: z.enum(["mark", "warn", "dissolve"]).optional().describe("How this signal closed its loop"),
5477
+ error: z.string().optional().describe("destination_not_accepted | unsupported_chain | no_wallet | not_an_agent_wallet | no_agent_address | unclaimed | agent_owns_itself | forbidden | owner_address_unproven | destination_is_agent | no_sweep_rule | rule_owner_changed | owner_address_changed | bad_rule | unreadable_balance | order_invalid | order_destination_mismatch | order_expired | order_expiry_too_far | order_amount_exceeds_free_balance | amount_not_representable | order_signature_invalid | order_replayed | order_required | order_already_settled | paymentTx_invalid | treasury_mismatch | not_claimed | a pay.one.ie error"),
5478
+ }),
5479
+ // `owner`, not manage_workspace: the AGENT's own runtime must reach this door
5480
+ // (pending + settle), and manage_workspace is in AGENT_FORBIDDEN_LABELS. The
5481
+ // floor is still tenant-class; the resolver admits only the agent itself or
5482
+ // its claimed owner.
5483
+ effect: "ask", cost: "variable", reversible: false, idempotent: false, settles: "onchain", auth: "owner",
5484
+ examples: [{ actor: "scout", chain: "sui", balance: "7250000000" }],
5485
+ }),
5486
+ // The sweep rule is the CLAIMED OWNER's, set in a human session, with a
5487
+ // signature by the owner's address over a fresh wallet:challenge (workspace =
5488
+ // actor = the owner) — that signature is where the owner's address is proven.
5489
+ "wallet:sweep-set": receiver({
5490
+ receiver: "wallet:sweep-set",
5491
+ summary: "The agent's claimed owner sets its sweep rule — the threshold above which a sweep is due and the float it keeps — and proves the address sweeps settle to",
5492
+ request: () => z.object({
5493
+ actor: z.string().optional().describe("The agent whose rule is set; defaults to `workspace`"),
5494
+ workspace: z.string().optional().describe("The workspace that holds the agent's wallets row; defaults to the attested caller"),
5495
+ chain: z.enum(["sui", "evm", "solana", "btc"]).optional().describe("Wallet chain family; default sui"),
5496
+ threshold: z.unknown().describe("A sweep is due when the balance is ABOVE this, integer base units as a digit string"),
5497
+ float: z.unknown().describe("What the agent keeps after a sweep, integer base units, strictly below threshold"),
5498
+ address: z.unknown().describe("The owner's own address on `chain` — what sweeps settle to once this proof verifies. Never the agent's"),
5499
+ challenge: z.unknown().describe("A fresh wallet:challenge the owner fetched with workspace = actor = its own slug"),
5500
+ proof: z.unknown().describe("{ publicKey, signature } (hex) by the owner's address over the wallet-registration statement for that challenge"),
5501
+ }),
5502
+ response: () => z.object({
5503
+ ok: z.boolean(),
5504
+ workspace: z.string().optional(),
5505
+ actor: z.string().optional(),
5506
+ chain: z.string().optional(),
5507
+ owner: z.string().optional(),
5508
+ ownerAddress: z.string().optional(),
5509
+ thresholdUnits: z.string().optional(),
5510
+ floatUnits: z.string().optional(),
5511
+ detail: z.string().optional(),
5512
+ closed: z.enum(["mark", "warn", "dissolve"]).optional(),
5513
+ error: z.string().optional().describe("unsupported_chain | not_an_agent_wallet | unclaimed | agent_owns_itself | not_owner | human_presence_required | bad_rule | address_required | destination_is_agent | owner_address_unproven"),
5514
+ }),
5515
+ effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "none", auth: "owner",
5516
+ examples: [{ actor: "scout", chain: "sui", threshold: "5000000000", float: "1000000000", address: "0x<owner sui address>", challenge: "<wallet:challenge>", proof: { publicKey: "<hex>", signature: "<hex>" } }],
5517
+ }),
5518
+ // An agent changes hands only by the current claimant's signed OFFER and the
5519
+ // target's own ACCEPT (actor_owners is otherwise first-claim-wins). Afterwards
5520
+ // nothing sweeps until the new owner proves an address via wallet:sweep-set.
5521
+ "agent:handover-offer": receiver({
5522
+ receiver: "agent:handover-offer",
5523
+ summary: "The agent's current owner offers it to another person — a signed 'ONE agent handover' statement by the owner's proven address",
5524
+ request: () => z.object({
5525
+ agent: z.string().describe("The agent's actor id (actor_owners.agent_id)"),
5526
+ to: z.string().describe("The person's slug the agent is offered to — never an agent"),
5527
+ chain: z.enum(["sui", "evm", "solana", "btc"]).optional().describe("Which proven address signs; default sui"),
5528
+ nonce: z.unknown().describe("16–128 of [A-Za-z0-9_-]; single use"),
5529
+ expiresAt: z.unknown().describe("unix ms, at most 15 minutes out"),
5530
+ signature: z.unknown().describe("{ publicKey, signature } (hex) by the owner's proven address over the handover statement"),
5531
+ }),
5532
+ response: () => z.object({
5533
+ ok: z.boolean(), offered: z.boolean().optional(), agent: z.string().optional(), from: z.string().optional(), to: z.string().optional(),
5534
+ nonce: z.string().optional(), expiresAt: z.number().optional(),
5535
+ closed: z.enum(["mark", "warn", "dissolve"]).optional(),
5536
+ error: z.string().optional().describe("agent_and_to_required | unsupported_chain | unclaimed | agent_owns_itself | not_owner | human_presence_required | handover_to_self | handover_to_agent | target_is_agent | offer_invalid | offer_expired | offer_expiry_too_far | owner_address_unproven | offer_signature_invalid | offer_replayed"),
5537
+ }),
5538
+ effect: "ask", cost: "free", reversible: true, idempotent: false, settles: "none", auth: "owner",
5539
+ examples: [{ agent: "scout", to: "dana", chain: "sui", nonce: "<nonce>", expiresAt: 1790000000000, signature: { publicKey: "<hex>", signature: "<hex>" } }],
5540
+ }),
5541
+ "agent:handover-accept": receiver({
5542
+ receiver: "agent:handover-accept",
5543
+ summary: "The person an agent was offered to accepts it, in their own session or human key — a compare-and-set on the agent's ownership",
5544
+ request: () => z.object({
5545
+ agent: z.string().describe("The agent's actor id"),
5546
+ nonce: z.unknown().describe("The offer's nonce"),
5547
+ }),
5548
+ response: () => z.object({
5549
+ ok: z.boolean(), accepted: z.boolean().optional(), agent: z.string().optional(), owner: z.string().optional(),
5550
+ previousOwner: z.string().optional(), next: z.string().optional(),
5551
+ closed: z.enum(["mark", "warn", "dissolve"]).optional(),
5552
+ error: z.string().optional().describe("offer_invalid | human_presence_required | offer_not_found | not_offered_to_you | offer_already_accepted | offer_expired | offer_stale"),
5553
+ }),
5554
+ effect: "ask", cost: "free", reversible: false, idempotent: false, settles: "none", auth: "owner",
5555
+ examples: [{ agent: "scout", nonce: "<nonce>" }],
5556
+ }),
5053
5557
  // A pending, attributed `settlements` row is written before a cent moves —
5054
5558
  // INSERT OR IGNORE keyed on the pay link id, so a retry with the same link is a
5055
5559
  // no-op. An unpayable actor is a clean refusal: no link minted, no row written.
@@ -6007,7 +6511,7 @@ export const RECEIVERS = {
6007
6511
  "course:save": receiver({
6008
6512
  receiver: "course:save",
6009
6513
  summary: "Create or update a course (upsert by courseId)",
6010
- request: () => z.object({ courseId: z.string(), title: z.string().optional(), description: z.string().optional(), published: z.boolean().optional(), price_cents: z.number().optional() }),
6514
+ request: () => z.object({ courseId: z.string(), workspace: z.string().optional(), slug: z.string().optional(), title: z.string().optional(), description: z.string().optional(), published: z.boolean().optional(), price_cents: z.number().optional() }),
6011
6515
  response: () => z.object({ ok: z.boolean(), courseId: z.string().optional() }),
6012
6516
  effect: "ask", cost: "free", reversible: false, idempotent: true, auth: "member",
6013
6517
  }),
@@ -6035,7 +6539,7 @@ export const RECEIVERS = {
6035
6539
  "course:lessons-save": receiver({
6036
6540
  receiver: "course:lessons-save",
6037
6541
  summary: "Upsert one or more lessons on a course",
6038
- request: () => z.object({ courseId: z.string(), lessons: z.union([z.array(z.record(z.string(), z.unknown())), z.record(z.string(), z.unknown())]) }),
6542
+ request: () => z.object({ courseId: z.string(), workspace: z.string().optional(), slug: z.string().optional(), lessons: z.union([z.array(z.record(z.string(), z.unknown())), z.record(z.string(), z.unknown())]) }),
6039
6543
  response: () => z.object({ ok: z.boolean(), saved: z.number().optional() }),
6040
6544
  effect: "ask", cost: "free", reversible: false, idempotent: true, auth: "member",
6041
6545
  }),
@@ -8352,7 +8856,18 @@ export const RECEIVERS = {
8352
8856
  receiver: "calendar:schedule-meeting",
8353
8857
  summary: "Sends a scheduling email to a contact and returns status",
8354
8858
  request: () => z.object({ amountLabel: z.unknown().optional(), email: z.unknown().optional(), name: z.unknown().optional(), stepName: z.unknown().optional() }).passthrough(),
8355
- response: () => z.unknown(),
8859
+ // bookUrl is the PLAIN public booking page (/u/<slug>/book) — never a key, so it
8860
+ // grants no membership. error "forbidden": no caller, or a group the caller does
8861
+ // not control. reason: the consent refusal (a declined or suppressed address), or
8862
+ // "email_failed" when the provider refused the send (ok:true, bookUrl still returned).
8863
+ response: () => z.object({
8864
+ ok: z.boolean(),
8865
+ emailed: z.boolean().optional(),
8866
+ email: z.string().nullable().optional(),
8867
+ bookUrl: z.string().optional(),
8868
+ error: z.enum(["forbidden"]).optional(),
8869
+ reason: z.string().optional(),
8870
+ }),
8356
8871
  effect: "signal", auth: "session", reversible: false,
8357
8872
  }),
8358
8873
  "campaign:brief": receiver({