@oneie/sdk 0.14.7 → 0.14.9

package/dist/receivers.js

@@ -668,28 +668,39 @@ export const RECEIVERS = {
     }),
     "world:announce": receiver({
         receiver: "world:announce",
-        summary: "Broadcast a tagged signal; the world fans it to every subscriber whose follow-tags intersect",
+        summary: "Broadcast a tagged signal; the world fans it to every subscriber whose follow-tags intersect. reply:true also invokes up to 5 of the matched actors and returns their answers inline (repliesTruncated:true if more matched)",
         request: z.object({
             tags: z.array(z.string()),
             content: z.string().optional(),
+            limit: z.number().optional(),
+            reply: z.boolean().optional(),
             board: z.literal("marketplace").optional(),
             slug: z.string().optional(),
             workspace: z.string().optional(),
+        }).catchall(z.unknown()), // extra keys = the message payload — carried through to every fanned-out actor, never stripped
+        response: z.object({
+            ok: z.boolean(),
+            matched: z.number().optional(),
+            actors: z.array(z.string()).optional(),
+            replies: z.array(z.object({
+                actorId: z.string(), ok: z.boolean(), text: z.string().optional(), error: z.string().optional(),
+            })).optional(),
+            repliesTruncated: z.boolean().optional(),
         }),
-        response: z.object({ ok: z.boolean(), matched: z.number().optional(), actors: z.array(z.string()).optional() }),
         effect: "ask",
     }),
     "world": receiver({
         receiver: "world",
-        summary: "THE door — say it once, the world decides. Routes a tagged signal via the ladder (learned path → staked subscribers → CEO); fan:'all' broadcasts to every matching subscriber instead. Address form world:<tag-expr> carries tags in the receiver",
+        summary: "THE door — say it once, the world decides. Routes a tagged signal via the ladder (learned path → staked subscribers → CEO); fan:'all' broadcasts to every matching subscriber instead. Address form world:<tag-expr> carries tags in the receiver. reply:true also invokes the resolved actor and returns its answer inline (single-actor routes only, not fan:'all')",
         request: z.object({
             tags: z.array(z.string()).optional(),
             fan: z.enum(["one", "all"]).optional(),
             deliver: z.boolean().optional(),
+            reply: z.boolean().optional(),
             board: z.literal("marketplace").optional(),
             slug: z.string().optional(),
             workspace: z.string().optional(),
-        }),
+        }).catchall(z.unknown()), // extra keys = the message payload (e.g. content) — carried through to the resolved actor, never stripped
         response: z.object({
             ok: z.boolean(),
             routed: z.enum(["learned", "staked", "explore", "ceo"]).optional(),
@@ -697,6 +708,7 @@ export const RECEIVERS = {
             matched: z.number().optional(),
             actors: z.array(z.string()).optional(),
             tags: z.array(z.string()).optional(),
+            reply: z.object({ ok: z.boolean(), text: z.string().optional(), error: z.string().optional() }).optional(),
         }),
         effect: "ask",
     }),
@@ -722,19 +734,21 @@ export const RECEIVERS = {
     }),
     "world:route": receiver({
         receiver: "world:route",
-        summary: "Route a tagged signal to THE handler via the ladder: learned tag-node path (follow_route) → staked subscribers (reputation-ranked) → CEO standing workflow; marks the delivery path so the next route is smarter",
+        summary: "Route a tagged signal to THE handler via the ladder: learned tag-node path (follow_route) → staked subscribers (reputation-ranked) → CEO standing workflow; marks the delivery path so the next route is smarter. reply:true also invokes the resolved actor and returns its answer inline",
         request: z.object({
             tags: z.array(z.string()),
             deliver: z.boolean().optional(),
+            reply: z.boolean().optional(),
             board: z.literal("marketplace").optional(),
             slug: z.string().optional(),
             workspace: z.string().optional(),
-        }),
+        }).catchall(z.unknown()), // extra keys = the message payload (e.g. content) — carried through to the resolved actor, never stripped
         response: z.object({
             ok: z.boolean(),
             routed: z.enum(["learned", "staked", "explore", "ceo"]).optional(),
             actor: z.string().optional(),
             tags: z.array(z.string()).optional(),
+            reply: z.object({ ok: z.boolean(), text: z.string().optional(), error: z.string().optional() }).optional(),
         }),
         effect: "ask",
     }),
@@ -762,8 +776,129 @@ export const RECEIVERS = {
                 name: z.string(),
                 tags: z.array(z.string()),
                 weight: z.number(),
+                // The context a puller needs to act: notes = the prose goal / what "done" looks
+                // like; contextDocs = the doc stems (`<slug>-plan`, `<slug>-todo`, …) to load
+                // before running /do <slug>. Empty until the task is enriched (seed/backfill).
+                notes: z.string().optional(),
+                contextDocs: z.array(z.string()).optional(),
+            })),
+        }),
+        effect: "ask", idempotent: true,
+    }),
+    "tasks:everywhere": receiver({
+        receiver: "tasks:everywhere",
+        summary: "Every workspace I belong to, one queue: open+picked tasks visible by assignment/follow/ownership, with claimable + mine + offeredByMe flags; closed:true returns the logbook (done/verified, newest first)",
+        request: z.object({ limit: z.number().optional(), closed: z.boolean().optional() }),
+        response: z.object({
+            ok: z.boolean(),
+            tasks: z.array(z.object({
+                id: z.string(),
+                name: z.string(),
+                tags: z.array(z.string()),
+                weight: z.number(),
+                notes: z.string().optional(),
+                contextDocs: z.array(z.string()).optional(),
+                workspace: z.string(),
+                status: z.string(),
+                dueAt: z.string().optional(),
+                assignee: z.string().optional(),
+                mine: z.boolean(),
+                claimable: z.boolean(),
+                offeredByMe: z.boolean(),
+                closedAt: z.string().optional(),
+            })),
+        }),
+        effect: "ask", idempotent: true,
+    }),
+    "tasks:create": receiver({
+        receiver: "tasks:create",
+        summary: "Write one open task to the substrate and announce it by its tags in the same act — the quick-add entry point",
+        request: z.object({
+            title: z.string(),
+            tags: z.array(z.string()).optional(),
+            assignee: z.string().optional(),
+            // Prose goal / what "done" looks like — the context a human attaches at create so
+            // the task is pickable by an agent or a Claude Code session without a round trip.
+            notes: z.string().optional(),
+            // The viewed /u/<slug> workspace to file the task under. Honored only when the
+            // caller is authorized for it (attested staff or owner-tree control); otherwise
+            // the resolver falls back to the caller's own slug. Reconciles the create tag
+            // with the /api/things read filter so a created task survives reload.
+            workspace: z.string().optional(),
+        }),
+        response: z.object({ ok: z.boolean(), tid: z.string().optional(), tags: z.array(z.string()).optional() }),
+        effect: "ask", idempotent: false,
+    }),
+    "tasks:claim": receiver({
+        receiver: "tasks:claim",
+        summary: "Take a task off the queue: blocker-gate → status picked → tag the claimant @<slug>. The claimant is the attested caller, never a body field",
+        request: z.object({
+            tid: z.string(),
+            // Viewed workspace — same authorization contract as tasks:create's workspace.
+            workspace: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean().optional(),
+            tid: z.string().optional(),
+            status: z.string().optional(),
+            claimant: z.string().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", idempotent: true,
+    }),
+    "tasks:undepend": receiver({
+        receiver: "tasks:undepend",
+        summary: "Remove one blocks edge — the inverse of tasks:depend. Deletes exactly the (blockedBy → tid) pair; does not touch task status. Auth: attested caller only, both ends in the caller's workspace",
+        request: z.object({
+            tid: z.string(),
+            blockedBy: z.string(),
+            workspace: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean().optional(),
+            tid: z.string().optional(),
+            blockedBy: z.string().optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", idempotent: true,
+    }),
+    "tasks:launch": receiver({
+        receiver: "tasks:launch",
+        summary: "Batch-launch ready agent-assigned tasks: per task re-check blockers, resolve the @assignee, set picked, fire agent:run, mark owner→assignee on success or revert to open + warn on failure. Per-task receipts — a batch is never all-or-nothing. Caps at 20 tids; skips human assignees",
+        request: z.object({
+            tids: z.array(z.string()),
+            workspace: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            results: z.array(z.object({
+                tid: z.string(),
+                ok: z.boolean(),
+                actorId: z.string().optional(),
+                reason: z.enum(["unassigned", "human-assignee", "blocked", "forbidden", "fire_failed"]).optional(),
             })),
         }),
+        effect: "ask", idempotent: false,
+    }),
+    "tasks:link": receiver({
+        receiver: "tasks:link",
+        summary: "Close the handoff: record that a claimed task was built via /do <slug> — append a provenance line to the task's notes (the id back-ref + doc stems) and move it to done. Auth: attested caller only",
+        request: z.object({
+            tid: z.string(),
+            // The kebab /do slug the task was built into (the docs backfilled under text/<slug>*).
+            slug: z.string(),
+            // Doc stems the /do run produced (e.g. ["usage-billing", "usage-billing-plan"]).
+            docs: z.array(z.string()).optional(),
+            workspace: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean().optional(),
+            tid: z.string().optional(),
+            slug: z.string().optional(),
+            docs: z.array(z.string()).optional(),
+            status: z.string().optional(),
+            error: z.string().optional(),
+        }),
         effect: "ask", idempotent: true,
     }),
     // ── agents (TRADE / lifecycle) ──
@@ -1236,12 +1371,13 @@ export const RECEIVERS = {
     }),
     "notify": receiver({
         receiver: "notify",
-        summary: "Notify any actor (human or agent) by uid — channels routes the door (Telegram/Discord/peer inbox), mirrors into the web inbox, and nudges an open client live. One verb, both actor kinds.",
+        summary: "Notify any actor (human or agent) by uid — channels routes the door (Telegram/Discord/peer inbox), mirrors into the web inbox, nudges an open client live, and sends a web push if the recipient subscribed. One verb, both actor kinds. An optional action renders as one tap-through link.",
         request: z.object({
             receiver: z.string(),
             kind: z.string().optional(),
             body: z.union([z.string(), z.record(z.string(), z.unknown())]).optional(),
             content: z.string().optional(),
+            action: z.object({ label: z.string(), redirect: z.string() }).optional(),
         }),
         response: z.object({
             ok: z.boolean(),
@@ -1276,6 +1412,17 @@ export const RECEIVERS = {
         response: z.object({ ok: z.boolean(), ts: z.number().optional(), error: z.string().optional() }),
         effect: "ask", idempotent: true,
     }),
+    "push:subscribe": receiver({
+        receiver: "push:subscribe",
+        summary: "Store a browser's Web Push subscription so notify() can reach the caller off-screen — the send side behind the shipped inbox service worker. Optional slug keys the row to a workspace the caller controls (else their own slug).",
+        request: z.object({
+            endpoint: z.string(),
+            keys: z.object({ p256dh: z.string(), auth: z.string() }),
+            slug: z.string().optional(),
+        }),
+        response: z.object({ ok: z.boolean(), error: z.string().optional() }),
+        effect: "ask", idempotent: true,
+    }),
     "thread:append": receiver({
         receiver: "thread:append",
         summary: "Gateway-callable write into web threads — carries tags into entity_tags so slug/in renders every channel by tag. Called by the channels bridge after every inbound signal.",
@@ -1893,7 +2040,14 @@ export const RECEIVERS = {
         response: z.object({ ok: z.boolean(), threadId: z.string().optional(), error: z.string().optional() }),
         effect: "ask", cost: "free", reversible: false, idempotent: false, auth: "member",
     }),
-    // ── billing — handlers in resolvers/market.ts ──────────────────────────────────
+    "pages:view": receiver({
+        receiver: "pages:view",
+        summary: "Read one published page's Puck render data by workspace + page slug (public) — the read an external site's page-editor plugin renders through; drafts are invisible (see pages:get for the member-scoped editor read)",
+        request: z.object({ slug: z.string(), page: z.string() }),
+        response: z.object({ ok: z.boolean(), slug: z.string().optional(), title: z.string().optional(), data: z.unknown().optional(), url: z.string().optional(), error: z.string().optional() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "public",
+    }),
+    // ──billing — handlers in resolvers/market.ts ──────────────────────────────────
     "billing:plan": receiver({
         receiver: "billing:plan",
         summary: "Change a workspace's plan — returns a checkout URL to complete the upgrade",
@@ -1940,6 +2094,14 @@ export const RECEIVERS = {
             service: z.object({
                 service_id: z.string(), name: z.string(), duration_min: z.number(),
                 price: z.number(), currency: z.string(),
+                description: z.string().nullable().optional(), // shown on /book, read by the agent (§12.2)
+                location: z.string().nullable().optional(), // 'video' | 'phone' | free-text address
+                intake: z.array(z.object({
+                    key: z.string(), label: z.string(),
+                    type: z.enum(["text", "number", "choice"]).optional(),
+                    required: z.boolean().optional(),
+                    options: z.array(z.string()).optional(),
+                })).optional(), // per-service intake questions — both doors ask them
             }).nullable(),
             slots: z.array(z.object({ date: z.string(), times: z.array(z.string()) })), // CalendarCard shape
             error: z.string().optional(),
@@ -1947,6 +2109,35 @@ export const RECEIVERS = {
         effect: "ask", cost: "free", idempotent: true, simulatable: false,
         examples: [{ slug: "clearwater", date: "2026-06-10" }],
     }),
+    // booking:list-services — public discover: the service menu (§12.3). Lets the
+    // chat agent offer "in-home survey, video walkthrough, or storage?" instead of
+    // silently defaulting to the first active row. Active services, public fields
+    // only (hours/buffer are inferable from list-slots output, so not secrets).
+    "booking:list-services": receiver({
+        receiver: "booking:list-services",
+        summary: "List a workspace's active bookable services (menu: name, duration, price, description, location, intake)",
+        request: z.object({ slug: z.string() }),
+        response: z.object({
+            services: z.array(z.object({
+                service_id: z.string(), name: z.string(), duration_min: z.number(),
+                price: z.number(), currency: z.string(),
+                description: z.string().nullable().optional(),
+                location: z.string().nullable().optional(),
+                buffer_min: z.number().optional(),
+                tz: z.string().optional(),
+                hours_json: z.array(z.array(z.object({ start: z.string(), end: z.string() }))).optional(),
+                intake: z.array(z.object({
+                    key: z.string(), label: z.string(),
+                    type: z.enum(["text", "number", "choice"]).optional(),
+                    required: z.boolean().optional(),
+                    options: z.array(z.string()).optional(),
+                })).optional(),
+            })),
+            error: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", idempotent: true, auth: "public",
+        examples: [{ slug: "clearwater" }],
+    }),
     "booking:create": receiver({
         receiver: "booking:create",
         summary: "Hold a slot for a customer; returns a ref and a payment intent when price > 0",
@@ -1955,7 +2146,12 @@ export const RECEIVERS = {
             service: z.string(),
             slotDate: z.string(), // 'YYYY-MM-DD'
             slotTime: z.string(), // 'HH:MM' 24h, slot start
-            customer: z.object({ name: z.string(), email: z.string().email().optional() }),
+            customer: z.object({
+                name: z.string(),
+                email: z.string().email().optional(),
+                phone: z.string().optional(), // speed-to-lead callback number (§12.3)
+            }),
+            details: z.union([z.string(), z.record(z.string(), z.unknown())]).optional(), // intake answers OR free text; 2KB serialized cap at the resolver, never shape-validated
             paymentRail: z.enum(["stripe", "sui"]).optional(), // resolver overrides by caller kind
         }),
         response: z.object({
@@ -1965,7 +2161,7 @@ export const RECEIVERS = {
             paymentRail: z.enum(["stripe", "sui"]).nullable().optional(),
             paymentIntent: z.object({ clientSecret: z.string(), amount: z.number() }).optional(), // human, price>0
             escrow: z.object({ escrowId: z.string(), bounty: z.number(), deadline: z.string() }).optional(), // agent
-            error: z.string().optional(), // 'slot_taken' | 'closed' | 'unknown_service'
+            error: z.string().optional(), // 'slot_taken' | 'closed' | 'unknown_service' | 'details_too_large'
         }),
         effect: "ask", cost: "variable", settles: "offchain", reversible: false,
         simulatable: true, idempotent: true, // idempotencyKey dedupes a retried hold
@@ -1990,6 +2186,15 @@ export const RECEIVERS = {
             hours_json: z.array(z.array(z.object({ start: z.string(), end: z.string() }))), // 7 entries, 0=Sun
             tz: z.string().optional(),
             active: z.boolean().optional(),
+            description: z.string().optional(), // shown on /book + read by the agent (§12.1)
+            location: z.string().optional(), // 'video' | 'phone' | free-text address
+            buffer_min: z.number().int().nonnegative().optional(), // drive time between slots (§12.5)
+            intake: z.array(z.object({
+                key: z.string(), label: z.string(),
+                type: z.enum(["text", "number", "choice"]).optional(),
+                required: z.boolean().optional(),
+                options: z.array(z.string()).optional(),
+            })).optional(), // per-service intake questions (§12.2); full-body upsert — omitted clears
         }),
         response: z.object({ ok: z.boolean(), service_id: z.string().optional(), error: z.string().optional() }),
         effect: "ask", cost: "free", idempotent: true, reversible: true, auth: "manage_clients",
@@ -2011,25 +2216,56 @@ export const RECEIVERS = {
                 id: z.string(), ref: z.string(), service_name: z.string(),
                 slot_date: z.string(), slot_time: z.string(),
                 customer_name: z.string(), status: z.string(),
+                customer_phone: z.string().nullable().optional(), // §12.3 — the job, not just the name
+                details: z.union([z.string(), z.record(z.string(), z.unknown())]).nullable().optional(), // parsed details_json (record) or verbatim free text; untrusted display data
             })),
             error: z.string().optional(),
         }),
         effect: "ask", cost: "free", idempotent: true, auth: "manage_clients",
         examples: [{ slug: "clearwater", month: "2026-06" }],
     }),
-    // booking:cancel — provider dissolves a booking by ref, releasing the slot
-    // immediately (the partial unique index drops dissolved rows from scope, §9).
-    // Tenant-private write: scoped to the authenticated owner. Idempotent.
+    // booking:cancel — dual-path (§12.6). Provider dissolves by ref (ctx-gated to
+    // the attested owner). Customer self-cancels with ref + matching contact (public;
+    // possession IS the gate, exactly like the public book path). Either way
+    // status='dissolved' releases the slot via the partial unique index (§9).
     "booking:cancel": receiver({
         receiver: "booking:cancel",
-        summary: "Provider-gated: dissolve a booking by ref, releasing the slot",
+        summary: "Dissolve a booking by ref — provider (ctx-gated) or customer (ref + matching contact)",
         request: z.object({
             slug: z.string(),
             ref: z.string(),
+            email: z.string().email().optional(), // customer path: possession = ref + matching contact
+            phone: z.string().optional(),
         }),
         response: z.object({ ok: z.boolean(), error: z.string().optional() }),
-        effect: "ask", cost: "free", idempotent: true, reversible: false, auth: "manage_clients",
-        examples: [{ slug: "clearwater", ref: "CLE-2026-4821" }],
+        effect: "ask", cost: "free", idempotent: true, reversible: false, auth: "public",
+        examples: [{ slug: "clearwater", ref: "CLE-2026-4821", email: "s@ex.com" }],
+    }),
+    // booking:reschedule — customer self-serve move (§12.6). Public; the gate is
+    // ref + matching contact. Hold-new-first: the resolver INSERTs the new slot
+    // (same guarded INSERT — can lose with slot_taken) THEN dissolves the old row,
+    // so a lost race leaves the original booking standing. Payment rail/ref carry over.
+    "booking:reschedule": receiver({
+        receiver: "booking:reschedule",
+        summary: "Customer self-serve: move a booking to a new slot by ref + matching contact (hold-new-first)",
+        request: z.object({
+            slug: z.string(),
+            ref: z.string(),
+            email: z.string().email().optional(),
+            phone: z.string().optional(),
+            newDate: z.string(), // 'YYYY-MM-DD'
+            newTime: z.string(), // 'HH:MM' 24h slot start
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            ref: z.string().optional(), // the NEW booking ref (ref is UNIQUE — a moved booking gets a fresh ref)
+            status: z.enum(["pending", "confirmed"]).optional(),
+            slotDate: z.string().optional(),
+            slotTime: z.string().optional(),
+            error: z.string().optional(), // 'not_found' | 'slot_taken' | 'closed' | 'unknown_service'
+        }),
+        effect: "ask", cost: "free", idempotent: true, reversible: false, auth: "public",
+        examples: [{ slug: "clearwater", ref: "CLE-2026-4821", email: "s@ex.com", newDate: "2026-06-12", newTime: "10:30" }],
     }),
     // ── workflows — define an SOP, run it, watch it learn (text/workflows-plan.md) ──
     // Every workflow op is a typed receiver. No new REST routes. apply-diff is
@@ -2090,6 +2326,23 @@ export const RECEIVERS = {
         effect: "ask", cost: "free", idempotent: true, simulatable: false, auth: "view_workflows",
         examples: [{ workflowId: "wf_abc", limit: 20 }, { workflowId: "wf_abc", runId: "run_1" }],
     }),
+    "workflow:preview-step": receiver({
+        receiver: "workflow:preview-step",
+        summary: "Resolve one step's receiver + args through the real substitution code, with an optional mock trigger/step payload standing in for run history — never dispatches, reads no run history",
+        request: z.object({
+            workflowId: z.string(),
+            stepId: z.string(),
+            mockTrigger: z.record(z.string(), z.unknown()).optional(),
+            mockSteps: z.record(z.string(), z.record(z.string(), z.unknown())).optional(),
+        }),
+        response: z.object({
+            receiver: z.string().nullable(),
+            data: z.record(z.string(), z.unknown()),
+            error: z.string().optional(),
+        }),
+        effect: "ask", cost: "free", reversible: false, idempotent: true, simulatable: false, auth: "view_workflows",
+        examples: [{ workflowId: "wf_abc", stepId: "step_1", mockTrigger: { email: "a@b.com" } }],
+    }),
     "workflow:create": receiver({
         receiver: "workflow:create",
         summary: "Create a blank workflow (group group-type=workflow) — optionally cloned from a template",
@@ -2294,13 +2547,21 @@ export const RECEIVERS = {
     "skills:list": receiver({
         receiver: "skills:list",
         summary: "List the caller's workspace skill catalog (R2) — powers the canvas SkillPicker",
-        request: z.object({}),
+        request: z.object({ name: z.string().optional() }),
         response: z.object({
-            skills: z.array(z.object({ name: z.string(), size: z.number(), sealed: z.boolean().optional() })),
+            skills: z.array(z.object({ name: z.string(), size: z.number(), sealed: z.boolean().optional(), description: z.string().optional(), inputs: z.array(z.object({ name: z.string(), label: z.string(), required: z.boolean().optional() })).optional() })),
         }),
         effect: "ask", cost: "free", idempotent: true, simulatable: false, auth: "view_workflows",
         examples: [{}],
     }),
+    "skill:save": receiver({
+        receiver: "skill:save",
+        summary: "Write a skill body into a workspace's R2 catalog — the store skill:run/skills:list read; explicit-slug, ownership-walk authorized (mirrors world:publish-agent)",
+        request: z.object({ slug: z.string(), name: z.string(), content: z.string() }),
+        response: z.object({ ok: z.boolean(), name: z.string(), bytes: z.number() }),
+        effect: "ask", auth: "update_group", idempotent: true,
+        examples: [{ slug: "elitemoversca", name: "quote-estimate", content: "---\nname: quote-estimate\n---\n…" }],
+    }),
     "skill:run": receiver({
         receiver: "skill:run",
         summary: "Run a workspace skill — loads its body from R2, runs one bounded turn via channels, returns { text }",
@@ -2594,6 +2855,48 @@ export const RECEIVERS = {
         response: z.object({ broadcast: z.record(z.string(), z.unknown()) }),
         effect: "ask", cost: "free", reversible: false, idempotent: true, auth: "read",
     }),
+    "segment:create": receiver({
+        receiver: "segment:create",
+        summary: "Create an audience segment from a rule definition (SegmentDef: {all, any?})",
+        request: z.object({ workspace: z.string(), name: z.string(), description: z.string().optional(), definition: z.record(z.string(), z.unknown()) }),
+        response: z.object({ id: z.string() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: false, auth: "write",
+    }),
+    "segment:update": receiver({
+        receiver: "segment:update",
+        summary: "Update an audience segment — name, description, or definition",
+        request: z.object({ workspace: z.string(), id: z.string(), name: z.string().optional(), description: z.string().optional(), definition: z.record(z.string(), z.unknown()).optional() }),
+        response: z.object({ ok: z.boolean() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "write",
+    }),
+    "segment:list": receiver({
+        receiver: "segment:list",
+        summary: "List audience segments for a workspace",
+        request: z.object({ workspace: z.string() }),
+        response: z.object({ segments: z.array(z.record(z.string(), z.unknown())) }),
+        effect: "ask", cost: "free", reversible: false, idempotent: true, auth: "read",
+    }),
+    "segment:get": receiver({
+        receiver: "segment:get",
+        summary: "Get one audience segment with its rule definition",
+        request: z.object({ workspace: z.string(), id: z.string() }),
+        response: z.object({ segment: z.record(z.string(), z.unknown()) }),
+        effect: "ask", cost: "free", reversible: false, idempotent: true, auth: "read",
+    }),
+    "segment:preview": receiver({
+        receiver: "segment:preview",
+        summary: "Preview an audience segment — live count + up to 10 sample addresses (read-only)",
+        request: z.object({ workspace: z.string(), definition: z.record(z.string(), z.unknown()), channel: z.enum(["email", "sms", "whatsapp"]).optional() }),
+        response: z.object({ count: z.number(), sample: z.array(z.string()) }),
+        effect: "ask", cost: "free", reversible: false, idempotent: true, auth: "read",
+    }),
+    "segment:delete": receiver({
+        receiver: "segment:delete",
+        summary: "Delete an audience segment and its membership snapshot",
+        request: z.object({ workspace: z.string(), id: z.string() }),
+        response: z.object({ ok: z.boolean() }),
+        effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "write",
+    }),
     "broadcast:test": receiver({
         receiver: "broadcast:test",
         summary: "Send a test email for a broadcast to one address",