@oneie/sdk 0.14.13 → 0.14.14

package/dist/receivers.js

@@ -440,6 +440,73 @@ export const RECEIVERS = {
         effect: "ask", auth: "manage_integrations", reversible: false,
         examples: [{ slug: "acme", toolkit: "stripe", credentials: { api_key: "sk_test_..." } }],
     }),
+    // git:pr — open or update ONE pull request on the repository a workspace owns.
+    //
+    // THE REPO IS NOT A PARAMETER, and that is the security property, not an
+    // ergonomic one. `bind-receiver.ts` splits the work: the binder asks "does this
+    // caller hold this CLASS of authority?", the handler asks "…over this
+    // PARTICULAR object?". Every other tenant receiver can answer the second
+    // because its object is a node in the six dimensions. A GitHub repository is
+    // not one — grep every schema/*.tql and the only hit is a `front-door`
+    // attribute whose VALUE may be the string "github". So `git:pr({ repo, … })`
+    // would take its target from the body and its credential from env: workspace
+    // authority anywhere becoming a write to any repo the token can reach, signed
+    // by ONE. That is the confused deputy, and it is the same defect class as
+    // trusting an actorId from a request body.
+    //
+    // So the caller never names the repository. The object of the decision is the
+    // WORKSPACE — dimension 1, a real node — resolved from the attested
+    // `ctx.ownerSlug` exactly as `tools:composio` resolves its entity ("never a
+    // body field", in that resolver's own words), and the repo is looked up FROM
+    // the workspace. No binding is a refusal, never a fallback to a default repo.
+    //
+    // `auth` is `manage_integrations` because it must be: AUTH_POLICY maps that to
+    // the `tenant` floor, and an unrecognised label falls to `authenticated`
+    // (bind-receiver.ts:120) — a novel name would have shipped this WEAKER, and
+    // nothing in the suite would have said so.
+    //
+    // It cannot derive its own title or body: there is no git and no shell in a
+    // Worker. Those are the caller's, which is why this receiver is the DOOR and
+    // `.claude/scripts/pr-body.sh` is the document.
+    "git:pr": receiver({
+        receiver: "git:pr",
+        summary: "Open or update one pull request on the repository this workspace is bound to — the repo is resolved from the workspace, never from the payload",
+        request: z.object({
+            workspace: z.string().optional().describe("Workspace slug; defaults to the attested caller's. The bound repo is resolved FROM this."),
+            head: z.string().describe("Branch to merge from — must already be pushed"),
+            base: z.string().optional().describe("Branch to merge into; defaults to main"),
+            title: z.string().describe("PR title"),
+            body: z.string().optional().describe("PR body — derive it with .claude/scripts/pr-body.sh; a Worker cannot"),
+            draft: z.boolean().optional().describe("Open as a draft"),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            url: z.string().optional(),
+            number: z.number().optional(),
+            updated: z.boolean().optional().describe("true = an open PR was updated rather than a new one created"),
+            repo: z.string().optional(),
+            error: z.string().optional(),
+            detail: z.string().optional(),
+        }),
+        effect: "ask",
+        auth: "manage_integrations",
+        // A PR is closable, and a re-run updates the open one rather than opening a
+        // second — so a retried workflow step is safe as-is.
+        reversible: true,
+        idempotent: true,
+        cost: "free",
+        settles: "none",
+        version: "1.0.0",
+        examples: [{ head: "feat/x", base: "main", title: "feat: x" }],
+    }),
+    "tools:composio": receiver({
+        receiver: "tools:composio",
+        summary: "Execute one connected Composio tool from a workflow `tool` step (config.composio)",
+        request: z.object({ workspace: z.string().optional().describe("Workspace slug; defaults to the attested caller's"), tool: z.string().describe("Composio tool slug to execute"), args: z.record(z.string(), z.unknown()).optional().describe("Arguments passed to the tool") }),
+        response: z.object({ ok: z.boolean(), tool: z.string().optional(), result: z.unknown().optional(), error: z.string().optional() }),
+        effect: "ask", auth: "manage_integrations", reversible: false, idempotent: false,
+        examples: [{ workspace: "acme", tool: "GMAIL_SEND_EMAIL", args: { to: "x@y.com" } }],
+    }),
     "brand:set": receiver({
         receiver: "brand:set",
         summary: "Write up to 6 brand color tokens (primary/secondary/accent/bg/text/border) to a workspace theme",
@@ -947,6 +1014,37 @@ export const RECEIVERS = {
         }),
         effect: "ask", idempotent: true,
     }),
+    "factory:size": receiver({
+        receiver: "factory:size",
+        summary: "How big is this change — the tier `.claude/scripts/do-tier.sh` returns for the same paths, answered where a Worker can ask (a Worker cannot run a shell script, which is the only reason the Size card at factory flow.ts:306 is a gap). Zero real paths is REFUSED as `unsized`, mirroring the script's exit 3: absence of recon must not read as simplicity. The pin ladder in the response is a pure function of the tier; the surfaces are additive obligation, never a second gate selector",
+        request: z.object({
+            // The changed paths, repo-relative. do-tier sizes a DIFF, never a sentence,
+            // so this is the only field that can decide the answer.
+            paths: z.array(z.string()).max(2000),
+            // Free text. It can only RAISE the answer to FEATURE, and is ignored entirely
+            // when `paths` is empty — "add a null check" and "add a settings page" share a verb.
+            intent: z.string().max(2000).optional(),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            tier: z.enum(["PATCH", "FIX", "FEATURE", "SCHEMA"]).optional(),
+            spine: z.string().optional(),
+            classifier: z.string().optional(),
+            ceilingTokens: z.number().optional(),
+            // The pinned suites this tier buys — derived from `tier` alone, mirroring
+            // .claude/scripts/verify-fast.sh:302-306. There is no second selector.
+            pins: z.array(z.string()).optional(),
+            // What the paths touch, and the ceremony rung after every surface floor is
+            // applied. Obligations, not gate selection.
+            surfaces: z.array(z.string()).optional(),
+            risk: z.string().optional(),
+            ratcheted: z.boolean().optional(),
+            produces: z.array(z.object({ what: z.string(), source: z.string() })).optional(),
+            gates: z.array(z.object({ what: z.string(), source: z.string() })).optional(),
+            error: z.string().optional(),
+        }),
+        effect: "ask", idempotent: true, reversible: true,
+    }),
     "factory:attempt": receiver({
         receiver: "factory:attempt",
         summary: "Open an attempt contained by its task, or close it with the production edge to what it produced plus the rubric. A do-cycle IS an attempt (factory-plan.md §3.1) — do:cycle-close arms as a caller of the close phase, never as a second writer",
@@ -986,6 +1084,82 @@ export const RECEIVERS = {
         }),
         effect: "ask", idempotent: true,
     }),
+    "factory:event": receiver({
+        receiver: "factory:event",
+        summary: "One factory-executor stage lands on the same run/event stream the canvas already reads — the six-stage pipeline (ready·claim·build·review·prove·close) that until now touched the substrate only at claim and close, so every surface could show a job before and after but never during. An unknown stage or status is REFUSED, never recorded as a default frame",
+        request: z.object({
+            // The task id being built. It IS the run key (`factory:<job>`), which is why
+            // a retried stage appends to its own run instead of minting a second one.
+            job: z.string(),
+            // Must equal FACTORY_SPINE_STEPS (one.ie/web/src/lib/factory/event.ts).
+            // Retyped because packages/sdk cannot import from one.ie/web; pinned by
+            // tests/unit/factory/event-receiver.test.ts so the two cannot drift.
+            stage: z.enum(["ready", "claim", "build", "review", "prove", "close"]),
+            // There is deliberately no "skip": a stage that did not run must be ABSENT.
+            status: z.enum(["start", "ok", "fail"]),
+            // Board workspace. TAGS ONLY *inside the resolver* — effectiveWorkspace
+            // (resolvers/tasks.ts:35) reads `workspace` and never `slug`, so the resolver
+            // itself cannot be steered by this field.
+            //
+            // BUT NOT BEFORE IT. For a VERIFIED SERVICE CALLER the ask route nominates
+            // the identity from the body and `slug` WINS:
+            //   pages/api/ask/[...receiver].ts:237
+            //     nominated = typeof p.slug === 'string' ? p.slug
+            //               : typeof p.workspace === 'string' ? p.workspace : undefined
+            //   :324  ownerSlug = locals.slug ?? callerUid ?? serviceOwnerSlug
+            // A sessionless curl (no `locals.slug`, and `callerUid` is only resolved in the
+            // `bearerToken && !isServiceCaller` branch) therefore lands ctx.ownerSlug =
+            // data.slug, and effectiveWorkspace returns that owner unchanged. So on the
+            // shipped emitter — .claude/scripts/factory-emit.sh, which posts
+            // `Authorization: Bearer $GATEWAY_API_KEY` (isVerifiedServiceCaller case 2,
+            // gateway-guard.ts:118) and sends `--slug` but never `workspace` — the `slug`
+            // COLUMN is data.slug, chosen by the caller. That is by design for a caller
+            // holding a shared service secret, and it is NOT what "never authz" says.
+            // The tags/authz split is a property of the RESOLVER, not of this field.
+            slug: z.string().optional(),
+            model: z.string().optional(),
+            detail: z.record(z.string(), z.unknown()).optional(),
+            reason: z.string().optional(),
+            // "dev" flags the projected run is_test so a worktree never pollutes the list.
+            env: z.string().optional(),
+            // Which authorized workspace the `slug` COLUMN resolves to (effectiveWorkspace,
+            // resolvers/tasks.ts). Never identity: an unauthorized value falls back to the
+            // attested ownerSlug rather than escalating.
+            workspace: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            runId: z.string().optional(),
+            stage: z.string().optional(),
+            status: z.string().optional(),
+            events: z.number().optional(),
+            slug: z.string().optional(),
+            error: z.string().optional(),
+        }),
+        // VERIFIED, not assumed: authClassFor(undefined) returns 'open'
+        // (bind-receiver.ts:117-120), and the 'authenticated' floor tests exactly
+        // `ctx.staff === true || Boolean(ctx.ownerSlug)` (bind-receiver.ts:159) — the
+        // same predicate the handler's own guard uses, one layer earlier, never
+        // stricter. The four siblings omit the label; declaring it here makes the
+        // fail-closed intent survive a refactor of the handler.
+        //
+        // HOW THE FLOOR ACTUALLY CLEARS — the previous note here said "the executor's
+        // world-key call carries `data.workspace`, which the ask route turns into
+        // ctx.ownerSlug". Both halves were wrong. The shipped emitter
+        // (.claude/scripts/factory-emit.sh) is NOT a world-key call: it posts
+        // `Authorization: Bearer $GATEWAY_API_KEY`, which is isVerifiedServiceCaller
+        // case 2 (gateway-guard.ts:118) — the SERVICE-secret door, not the per-actor
+        // one. A world-key bearer takes the other branch entirely
+        // (`bearerToken && !isServiceCaller`, [...receiver].ts:238) and resolves
+        // `callerUid`, never `serviceOwnerSlug`. And it does not send `workspace` at
+        // all; it sends `slug`, which is the FIRST nomination at :237 and therefore
+        // wins for a service caller. So the floor clears on a caller-supplied `slug`
+        // reaching ctx.ownerSlug — see the note on the `slug` field above.
+        auth: "required",
+        // Two `build/ok` events for one job are two real frames with rising seq, not
+        // a dedupe. The RUN row dedupes (INSERT OR IGNORE); the events do not.
+        effect: "ask", idempotent: false,
+    }),
     "do:halt": receiver({
         receiver: "do:halt",
         summary: "Stop a factory run, or release the stop. Sets a halt latch on the plan thing that `factory:attempt` phase \"open\" refuses against, so no new attempt can be claimed; with `attempt`, also closes that in-flight attempt as dissolved. It does NOT kill an OS process — a cycle already executing stops at its next substrate write",
@@ -1024,13 +1198,18 @@ export const RECEIVERS = {
             // 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(),
+            // Optional parent tid — writes the `containment` edge in the SAME pipeline as the
+            // row, so the factory's downward walk (fn ready-tasks -> derived-from) can reach the
+            // task. Without it the task is an orphan: on the board, unreachable from any plan.
+            // Refused unless the caller has operate access to the parent.
+            parent: 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() }),
+        response: z.object({ ok: z.boolean(), tid: z.string().optional(), tags: z.array(z.string()).optional(), parent: z.string().optional() }),
         effect: "ask", idempotent: false,
     }),
     "tasks:claim": receiver({
@@ -1140,12 +1319,70 @@ export const RECEIVERS = {
         }),
         effect: "ask", idempotent: true, auth: "member",
     }),
+    // tasks:generate — read what a page says, propose the work it implies, and file it.
+    //
+    // The one task verb that does not take a title: the caller hands over the PAGE
+    // (its title, its own summary, its visible text) and gets back real rows on the
+    // board. Every row is written through `tasks:create`, so the workspace gate, the
+    // announce and the write-failure semantics are the ones that verb already holds —
+    // this receiver only decides WHAT to file, never who may file it.
+    //
+    // No URL is fetched server-side. The caller sends the text it can already see
+    // (the browser reads its own DOM, or same-origin-fetches a page under the
+    // viewer's own session); a receiver that fetched an arbitrary `url` would be an
+    // SSRF door on a surface that spends LLM tokens. `url` is a LABEL here — it
+    // names the source and seeds the dedupe key, and is never dereferenced.
+    //
+    // Idempotent by (source, title): each row carries a derived `slug:` tag, which
+    // tasks:create dedupes on. Clicking twice on the same page cannot double the
+    // board, while a genuinely new suggestion still lands.
+    "tasks:generate": receiver({
+        receiver: "tasks:generate",
+        surfaces: { mcp: true },
+        summary: "Turn a page into tasks: read the page text the caller supplies, propose 3-7 concrete next actions, and write each one through tasks:create (deduped by source+title). Never fetches the URL — `url` labels the source and seeds the dedupe key",
+        request: z.object({
+            /** Source label + dedupe seed. Never fetched. */
+            url: z.string().optional(),
+            title: z.string().optional(),
+            /** The page's own description / heading trail — what `readPageSummary()` returns. */
+            summary: z.string().optional(),
+            /** Visible page text, if the caller has it. Capped server-side. */
+            text: z.string().optional(),
+            /** How many tasks to aim for. Clamped to 1-8. */
+            count: z.number().optional(),
+            /** Extra tags every generated task carries, on top of `from-page`. */
+            tags: z.array(z.string()).optional(),
+            /** The viewed /u/<slug> workspace — same authorization contract as tasks:create. */
+            workspace: z.string().optional(),
+        }),
+        response: z.object({
+            ok: z.boolean(),
+            created: z.number().optional(),
+            deduped: z.number().optional(),
+            /** The workspace the rows actually landed in — the resolver's own answer,
+             *  not the caller's request. A caller that guessed this instead would link
+             *  the operator at a board their tasks are not on whenever the workspace
+             *  override was refused. */
+            workspace: z.string().optional(),
+            tasks: z.array(z.object({ tid: z.string(), title: z.string(), deduped: z.boolean().optional() })).optional(),
+            error: z.string().optional(),
+        }),
+        // Spends LLM tokens and writes rows. An undeclared label is an anonymous door
+        // (see receiver-envelope.ts § requiresAttestedCaller) — this one refuses.
+        effect: "ask", auth: "member", reversible: false, idempotent: true,
+    }),
     "tasks:list": receiver({
         receiver: "tasks:list",
         surfaces: { mcp: true },
         summary: "Every task carrying a tag, with its task-status — the read that lets a plan's checkboxes be a PROJECTION of task state instead of a second copy. Scoped to the caller's workspace on the server",
         request: z.object({
             tag: z.string(),
+            // Optional task-status filter (open|blocked|picked|done|verified|failed|dissolved).
+            // Declared here because the HTTP edge dispatches zod's PARSED output — an
+            // undeclared field is silently stripped before the resolver reads it, and the
+            // factory turn (one.ie/ai/workflows/factory-turn.tql step:rows) needs the
+            // plan's OPEN rows to fan tasks:launch over.
+            status: z.string().optional(),
             workspace: z.string().optional(),
         }),
         response: z.object({
@@ -1282,12 +1519,20 @@ export const RECEIVERS = {
     "tasks:subtask": receiver({
         receiver: "tasks:subtask",
         surfaces: { mcp: true },
-        summary: "Create a child task and hang it under its parent with `containment` in one write. Reuses create's insert path — there is no second task-insert anywhere",
+        summary: "Create a child task COMPLETE — row, notes, tags, its `containment` edge to the parent and every `blockedBy` prerequisite — in ONE pipeline, so a child never appears claimable with an empty body or missing ordering",
         request: z.object({
             parent: z.string(),
             title: z.string(),
             tags: z.array(z.string()).optional(),
             assignee: z.string().optional(),
+            // The prose goal, written at creation. A child that arrives with an empty body is
+            // claimable-but-unbuildable; notes here close that window.
+            notes: z.string().optional(),
+            // One tid or a list (max 16) of prerequisites. Each writes a `blocks` edge in the
+            // same pipeline as the row, so ordering is created at intake rather than remembered
+            // later. Validated exactly as tasks:depend does: operate-role on each prerequisite
+            // and the transitive cycle walk.
+            blockedBy: z.union([z.string(), z.array(z.string())]).optional(),
             workspace: z.string().optional(),
         }),
         response: z.object({
@@ -1295,6 +1540,7 @@ export const RECEIVERS = {
             tid: z.string().optional(),
             parent: z.string().optional(),
             tags: z.array(z.string()).optional(),
+            blockedBy: z.array(z.string()).optional(),
             error: z.string().optional(),
         }),
         effect: "ask", idempotent: false, auth: "member",
@@ -1390,7 +1636,14 @@ export const RECEIVERS = {
                 tid: z.string(),
                 ok: z.boolean(),
                 actorId: z.string().optional(),
-                reason: z.enum(["unassigned", "human-assignee", "blocked", "forbidden", "fire_failed"]).optional(),
+                // `unspecced` = the task has no Proof: row (factory/spec-gate.ts).
+                // `spec_unreadable` = we could not READ the task to decide — an outage,
+                // kept distinct from a verdict per factory-spec.md demand 6.
+                reason: z.enum(["unassigned", "human-assignee", "blocked", "forbidden", "fire_failed", "unspecced", "spec_unreadable"]).optional(),
+                /** Why the gate refused, in one human-readable line. */
+                detail: z.string().optional(),
+                /** Set when the task launched only on the spec gate's grandfather clause. */
+                warning: z.string().optional(),
             })),
         }),
         effect: "ask", idempotent: false,
@@ -2283,6 +2536,55 @@ export const RECEIVERS = {
         }),
         effect: "ask", cost: "free", reversible: true, idempotent: false, auth: "member",
     }),
+    // ── EVENTS (dim 5) — the analytics ingress ───────────────────────────────────
+    // event:track — the write behind POST /api/events, the browser pixel's door.
+    // PUBLIC by construction: the pixel runs on third-party pages with no session,
+    // no key and no cookie the substrate controls, so an auth label here would
+    // throw in bindReceiver's applyAuth and silently kill 46k events/30d.
+    // Identity is never taken from this payload; the route attests the caller and
+    // hands the resolver an already-enriched row.
+    "event:track": receiver({
+        receiver: "event:track",
+        summary: "Record one analytics event (agent_events_warm) and broadcast it to the workspace AnalyticsRelay",
+        request: z.object({
+            id: z.string(),
+            ts: z.number(),
+            slug: z.string(),
+            event: z.string(),
+            source: z.string(),
+            visitor_hash: z.string().optional().nullable(),
+            agent_id: z.string().optional().nullable(),
+            variant: z.string().optional().nullable(),
+            thread_id: z.string().optional().nullable(),
+            actor_id: z.string().optional().nullable(),
+            actor_type: z.string().optional().nullable(),
+            channel: z.string().optional().nullable(),
+            campaign: z.string().optional().nullable(),
+            link_id: z.string().optional().nullable(),
+            referrer: z.string().optional().nullable(),
+            user_agent_class: z.string().optional().nullable(),
+            locale: z.string().optional().nullable(),
+            payload: z.record(z.string(), z.unknown()).optional().nullable(),
+            consent_state: z.string().optional().nullable(),
+            region: z.string().optional().nullable(),
+            tags: z.array(z.string()).optional().nullable(),
+        }),
+        response: z.object({ ok: z.boolean(), id: z.string().optional(), error: z.string().optional() }),
+        examples: [
+            {
+                id: "01J8ZQ3K2P0000000000000000",
+                ts: 1767225600000,
+                slug: "one",
+                event: "pageview",
+                source: "web",
+                visitor_hash: "d41d8cd98f00b204",
+                consent_state: "granted",
+                region: "IE",
+                payload: { page: "/pricing" },
+            },
+        ],
+        effect: "signal", cost: "free", reversible: false, idempotent: true, auth: "public",
+    }),
     // ── FUNNELS (text/funnels-plan.md) — author + run funnel definitions ──────────
     // funnel:create — create a new funnel definition (draft).
     "funnel:create": receiver({
@@ -4667,6 +4969,21 @@ export const RECEIVERS = {
         }),
         effect: "ask", auth: "public", cost: "free", reversible: false, idempotent: true,
     }),
+    // ── health — the doctor. Handler in resolvers/health.ts ───────────────────
+    "health:diagnose": receiver({
+        receiver: "health:diagnose",
+        summary: "Probe every deployed surface and the receiver failure rates D1 already records, then write the verdict back as weighted paths (mark on up, warn on down or on a sick receiver) so the next sweep starts from what the last one learned. Diagnoses only — it never restarts, redeploys or kills anything, because the remote half has no provably safe remedy. Fired by the health-tick cron trigger.",
+        request: z.object({}),
+        response: z.object({
+            ok: z.boolean(),
+            verdict: z.enum(["healthy", "degraded", "unhealthy"]).optional(),
+            symptoms: z.array(z.string()).optional(),
+            surfaces: z.array(z.unknown()).optional(),
+            sick: z.array(z.unknown()).optional(),
+            checkedAt: z.string().optional(),
+        }),
+        effect: "ask", auth: "public", cost: "free", reversible: false, idempotent: true,
+    }),
     // ── seo — handlers in resolvers/seo.ts (C1 live; C2 async) ─────────────────
     "seo:backlinks-summary": receiver({
         receiver: "seo:backlinks-summary",