@oneie/sdk 0.17.1 → 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",
@@ -3942,6 +4011,7 @@ export const RECEIVERS = {
3942
4011
  description: z.string(),
3943
4012
  price_usd: z.number(),
3944
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(),
3945
4015
  }),
3946
4016
  effect: "ask", cost: "free", idempotent: true,
3947
4017
  examples: [{}],
@@ -3952,6 +4022,9 @@ export const RECEIVERS = {
3952
4022
  request: () => z.object({
3953
4023
  name: z.string(),
3954
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(),
3955
4028
  }),
3956
4029
  response: () => z.object({
3957
4030
  method: z.enum(["stripe", "credits"]),
@@ -3964,6 +4037,10 @@ export const RECEIVERS = {
3964
4037
  entitled: z.boolean().optional(),
3965
4038
  already: z.boolean().optional(),
3966
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(),
3967
4044
  plugin: z.string(),
3968
4045
  feature: z.string(),
3969
4046
  }),
@@ -4585,7 +4662,9 @@ export const RECEIVERS = {
4585
4662
  // zod's PARSED output, so an undeclared key is stripped at the HTTP edge and
4586
4663
  // never reaches the handler. `delivery_r2_key` is accepted ONLY as a
4587
4664
  // `{kind}:{ref}` install descriptor — the plain-R2-key write door stays shut.
4588
- 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(),
4589
4668
  delivery_r2_key: z.string().optional(),
4590
4669
  }),
4591
4670
  response: () => z.object({ pid: z.string().optional(), ppid: z.string().optional(), name: z.string().optional(), workspace: z.string().optional(), error: z.string().optional() }),
@@ -4597,22 +4676,26 @@ export const RECEIVERS = {
4597
4676
  // `status` carries the same history as on products:create — the resolver has
4598
4677
  // always read it, the declaration never listed it, so zod stripped it and a
4599
4678
  // draft product could not be published through this receiver either.
4600
- 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() }),
4601
4680
  response: () => z.object({ pid: z.string().optional(), workspace: z.string().optional(), error: z.string().optional() }),
4602
4681
  effect: "ask", cost: "free", reversible: false, idempotent: true, auth: "member",
4603
4682
  }),
4604
4683
  "products:list": receiver({
4605
4684
  receiver: "products:list",
4606
- 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.",
4607
4687
  request: () => z.object({
4608
4688
  slug: z.string().optional(),
4609
- 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)."),
4610
4692
  }),
4611
4693
  response: () => z.object({ products: z.array(z.record(z.string(), z.unknown())).optional(), error: z.string().optional() }),
4612
4694
  effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "public",
4613
4695
  }),
4614
4696
  "products:get": receiver({
4615
4697
  receiver: "products:get",
4698
+ surfaces: { mcp: true },
4616
4699
  summary: "Get one storefront product with its prices (public, active-only) — the single-record read a data-bound page block resolves through",
4617
4700
  request: () => z.object({ slug: z.string(), pid: z.string() }),
4618
4701
  response: () => z.object({ product: z.record(z.string(), z.unknown()).nullable().optional(), error: z.string().optional() }),
@@ -4863,6 +4946,73 @@ export const RECEIVERS = {
4863
4946
  effect: "ask", cost: "free", reversible: true, idempotent: true, settles: "none", auth: "public",
4864
4947
  examples: [{ workspace: "acme", token: "<uid>.<exp>.<sig>" }],
4865
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
+ }),
4866
5016
  // ── orders:send-link — the MINT orders:mine named and did not build ──────────
4867
5017
  // (handler: resolvers/storefront/orders-send-link.ts)
4868
5018
  //
@@ -5250,7 +5400,7 @@ export const RECEIVERS = {
5250
5400
  // things happened, so no reader has to infer it. All optional: a response
5251
5401
  // carries the pair that matches its branch, never all of them at once.
5252
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"),
5253
- 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'"),
5254
5404
  twoLedgerReason: z.string().optional().describe("Only when twoLedgerCheck is 'not_in_force': why the check did not run — reader_unconfigured | no_agent_wallet"),
5255
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"),
5256
5406
  // The stage 'authority' refusal shape (TwoLedgerRefusal). `cause` is what
@@ -5258,12 +5408,152 @@ export const RECEIVERS = {
5258
5408
  // response parse would strip exactly that.
5259
5409
  verdict: z.string().optional().describe("On a stage 'authority' refusal: mismatch | unknown. 'unknown' FAILS CLOSED — an unresolvable read is never 'no objection'"),
5260
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"),
5261
- 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"),
5262
5412
  error: z.string().optional(),
5263
5413
  }),
5264
5414
  effect: "ask", cost: "variable", reversible: false, idempotent: false, settles: "onchain", auth: "manage_workspace",
5265
5415
  examples: [{ to: "0xabc", chain: "SUI", amount: 5, paymentTx: "8xKvQ1" }],
5266
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
+ }),
5267
5557
  // A pending, attributed `settlements` row is written before a cent moves —
5268
5558
  // INSERT OR IGNORE keyed on the pay link id, so a retry with the same link is a
5269
5559
  // no-op. An unpayable actor is a clean refusal: no link minted, no row written.
@@ -6221,7 +6511,7 @@ export const RECEIVERS = {
6221
6511
  "course:save": receiver({
6222
6512
  receiver: "course:save",
6223
6513
  summary: "Create or update a course (upsert by courseId)",
6224
- 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() }),
6225
6515
  response: () => z.object({ ok: z.boolean(), courseId: z.string().optional() }),
6226
6516
  effect: "ask", cost: "free", reversible: false, idempotent: true, auth: "member",
6227
6517
  }),
@@ -6249,7 +6539,7 @@ export const RECEIVERS = {
6249
6539
  "course:lessons-save": receiver({
6250
6540
  receiver: "course:lessons-save",
6251
6541
  summary: "Upsert one or more lessons on a course",
6252
- 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())]) }),
6253
6543
  response: () => z.object({ ok: z.boolean(), saved: z.number().optional() }),
6254
6544
  effect: "ask", cost: "free", reversible: false, idempotent: true, auth: "member",
6255
6545
  }),
@@ -8566,7 +8856,18 @@ export const RECEIVERS = {
8566
8856
  receiver: "calendar:schedule-meeting",
8567
8857
  summary: "Sends a scheduling email to a contact and returns status",
8568
8858
  request: () => z.object({ amountLabel: z.unknown().optional(), email: z.unknown().optional(), name: z.unknown().optional(), stepName: z.unknown().optional() }).passthrough(),
8569
- 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
+ }),
8570
8871
  effect: "signal", auth: "session", reversible: false,
8571
8872
  }),
8572
8873
  "campaign:brief": receiver({