@oneie/sdk 0.16.1 → 0.16.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
@@ -202,18 +202,54 @@ export const RECEIVERS = {
202
202
  }),
203
203
  "world:request-access": receiver({
204
204
  receiver: "world:request-access",
205
- summary: "Request membership in a group — always pends, never auto-grants",
206
- request: z.object({ group: z.string(), role: z.string().optional(), reason: z.string().optional() }),
207
- response: z.object({ requestId: z.string() }),
205
+ summary: "Request membership in a group — always pends, never auto-grants; refuses a group that does not exist (group_not_found) and notifies its owner",
206
+ request: z.object({ group: z.string(), role: z.string().optional(), reason: z.string().max(500).optional().describe("shown to the owner; control characters are stored as spaces") }),
207
+ response: z.object({
208
+ requestId: z.string(),
209
+ notified: z.boolean().optional().describe("the owner notice was attempted and landed; false = the request stands but nobody was paged. Absent on an existing request."),
210
+ existing: z.boolean().optional().describe("true = a pending request for this (group, requester) already existed; requestId is that one and no second notice was sent"),
211
+ }),
208
212
  effect: "ask", auth: "member",
209
213
  }),
210
214
  "world:approve-request": receiver({
211
215
  receiver: "world:approve-request",
212
- summary: "Approve or reject a pending access request",
216
+ summary: "Approve or reject a pending access request — approval writes the group membership and the requester is notified",
213
217
  request: z.object({ requestId: z.string(), decision: z.enum(["approved", "rejected"]) }),
214
- response: ok,
218
+ response: z.object({
219
+ ok: z.boolean(),
220
+ membership: z.string().optional().describe("the membership write's verdict on approve: created | updated | unchanged (already held at or above) | refused | failed. Absent on reject."),
221
+ notified: z.boolean().optional().describe("the decision notice to the requester landed"),
222
+ }),
215
223
  effect: "ask", auth: "manage_members", reversible: false,
216
224
  }),
225
+ "world:list-requests": receiver({
226
+ receiver: "world:list-requests",
227
+ summary: "List access requests — a group's queue (caller must hold authority over it) or, with no group, the caller's own",
228
+ request: z.object({
229
+ group: z.string().optional().describe("gid or slug. Present = that group's queue, refused unless the caller is an authority over it. Absent = the caller's OWN requests."),
230
+ status: z.enum(["pending", "approved", "rejected"]).optional(),
231
+ }),
232
+ response: z.object({
233
+ requests: z.array(z.object({
234
+ requestId: z.string(),
235
+ group: z.string(),
236
+ requester: z.string(),
237
+ requesterKind: z.enum(["human", "agent"]).nullable().describe("null on requests made before the kind was recorded"),
238
+ role: z.string(),
239
+ reason: z.string().nullable(),
240
+ status: z.string(),
241
+ decidedBy: z.string().nullable(),
242
+ decidedAt: z.number().nullable().describe("unix SECONDS"),
243
+ createdAt: z.number().describe("unix SECONDS (older ms rows are normalised on read)"),
244
+ })),
245
+ total: z.number().describe("rows matching before the cap — exact"),
246
+ truncated: z.object({ rows: z.number() }).optional().describe("present iff total exceeds the rows returned; rows = the cap that bit"),
247
+ }),
248
+ // auth member, not manage_members: a plain member lists its OWN requests.
249
+ // Authority over a named group is checked inside the resolver (groupAuthority).
250
+ effect: "ask", auth: "member", cost: "free", idempotent: true,
251
+ examples: [{ group: "acme", status: "pending" }, {}],
252
+ }),
217
253
  "world:remove-member": receiver({
218
254
  receiver: "world:remove-member",
219
255
  summary: "Remove a member from a workspace",
@@ -1085,6 +1121,23 @@ export const RECEIVERS = {
1085
1121
  response: z.object({ ok: z.boolean(), seeded: z.number().optional() }),
1086
1122
  effect: "ask", auth: "platform", reversible: true,
1087
1123
  }),
1124
+ "world:bake-outcome": receiver({
1125
+ receiver: "world:bake-outcome",
1126
+ summary: "One bake row moves one (family → model) path: pass marks, fail warns, could-not-run moves nothing (platform-gated)",
1127
+ request: z.object({
1128
+ family: z.string().regex(/^[a-z][a-z0-9-]{0,39}$/).describe("The card's FAMILY from its shape.env — a bare word (text/work-categories.md § The families). The path key is shape:<family>"),
1129
+ model: z.string().min(1).max(96).describe("The model id the row ran, e.g. 'deepseek/deepseek-v4-flash'. The path target is model:<id>"),
1130
+ verdict: z.enum(["pass", "fail", "could-not-run"]).describe("pass → mark · fail → warn · could-not-run (provider error, cap) → nothing, because the model never answered"),
1131
+ }),
1132
+ response: z.object({
1133
+ ok: z.boolean(),
1134
+ moved: z.enum(["mark", "warn", "none"]).optional(),
1135
+ path: z.string().optional(),
1136
+ error: z.string().optional(),
1137
+ }),
1138
+ effect: "ask", auth: "platform", reversible: false,
1139
+ examples: [{ family: "ts-lib", model: "deepseek/deepseek-v4-flash", verdict: "pass" }],
1140
+ }),
1088
1141
  "attention:follow": receiver({
1089
1142
  receiver: "attention:follow",
1090
1143
  summary: "Subscribe to a do-event axis; writes ws-scoped mark so fan-out stays tenant-isolated",
@@ -1277,6 +1330,39 @@ export const RECEIVERS = {
1277
1330
  response: ok,
1278
1331
  effect: "signal", auth: "manage_members",
1279
1332
  }),
1333
+ // Watch a PUBLIC group (text/join-existing-plan.md W3 D2). Writes one
1334
+ // `follows` row on that group's board — receiver world:announce, tags ["*"],
1335
+ // scope "watch" — so the existing announce fan-out reaches the caller. It is
1336
+ // awareness, not membership: no role, no read, never a world:route target.
1337
+ "groups:follow": receiver({
1338
+ receiver: "groups:follow",
1339
+ summary: "Watch a public group — its world:announce fan-out reaches your inbox",
1340
+ request: z.object({
1341
+ group: z.string().describe("slug or gid of the group to watch"),
1342
+ }),
1343
+ response: z.object({
1344
+ ok: z.boolean(),
1345
+ group: z.string().optional().describe("the group's slug — the board the watch row sits on"),
1346
+ following: z.boolean().optional(),
1347
+ error: z.string().optional()
1348
+ .describe("group_not_found · not_public · own_group · visibility_undetermined (the visibility read failed; retry — never a verdict) · already_staked (you hold a declared subscription on that board, which already routes its announces to you)"),
1349
+ }),
1350
+ effect: "signal", auth: "member", idempotent: true,
1351
+ examples: [{ group: "acme" }],
1352
+ }),
1353
+ "groups:unfollow": receiver({
1354
+ receiver: "groups:unfollow",
1355
+ summary: "Stop watching a group — removes the watch row only, never a declared subscription",
1356
+ request: z.object({ group: z.string().describe("slug or gid") }),
1357
+ response: z.object({
1358
+ ok: z.boolean(),
1359
+ group: z.string().optional(),
1360
+ following: z.boolean().optional(),
1361
+ error: z.string().optional(),
1362
+ }),
1363
+ effect: "signal", auth: "member", idempotent: true,
1364
+ examples: [{ group: "acme" }],
1365
+ }),
1280
1366
  "groups:members": receiver({
1281
1367
  receiver: "groups:members",
1282
1368
  surfaces: { mcp: true },
@@ -1866,6 +1952,55 @@ export const RECEIVERS = {
1866
1952
  }),
1867
1953
  effect: "ask", cost: "free", reversible: false, idempotent: false, auth: "session",
1868
1954
  }),
1955
+ // The evidence locker, read and pruned from chat (the operator, 2026-09-24:
1956
+ // "we should remove [the evidence] and allow it to be removed with chat").
1957
+ // The case file is static TypeScript, so a removal is an OVERLAY row in D1 —
1958
+ // an append-only log of who removed or restored which artefact, when. Nothing
1959
+ // is deleted: a plan is evidence, and the locker says how many items the
1960
+ // owner removed. The list door exists because a chat agent cannot import the
1961
+ // case registry: it names the artefact from `caption`, then writes by exact id.
1962
+ "ehc:evidence": receiver({
1963
+ receiver: "ehc:evidence",
1964
+ summary: "List the evidence filed on one EHC case — id, caption, sections, and whether the case owner has removed it. The only way a chat agent learns which id 'the bath photo' is before calling ehc:evidence-remove",
1965
+ request: z.object({
1966
+ cyp: z.string(), // case id or slug, e.g. 'cyp-001' | 'brian' — resolved through the registry
1967
+ }),
1968
+ response: z.object({
1969
+ ok: z.boolean(),
1970
+ cyp: z.string().optional(),
1971
+ items: z.array(z.object({
1972
+ id: z.string(),
1973
+ caption: z.string(),
1974
+ sections: z.array(z.string()),
1975
+ kind: z.string(),
1976
+ removed: z.boolean(),
1977
+ })).optional(),
1978
+ removed: z.number().optional(), // how many items the owner has removed
1979
+ error: z.string().optional(), // 'not_found' | 'read_failed'
1980
+ }),
1981
+ effect: "ask", cost: "free", reversible: true, idempotent: true, auth: "session",
1982
+ }),
1983
+ "ehc:evidence-remove": receiver({
1984
+ receiver: "ehc:evidence-remove",
1985
+ summary: "Remove one artefact from an EHC case's evidence locker, or restore it (removed:false). Owner-only: authority is the caller's control of the case's group, read off the attested caller and never the payload. Writes one row to an append-only log — nothing is deleted, and every page says how many items the owner removed. Takes an exact evidence id from ehc:evidence; never matches a caption",
1986
+ request: z.object({
1987
+ cyp: z.string(), // case id or slug
1988
+ evidenceId: z.string(), // exact id from ehc:evidence, e.g. 'ev-a7-railay'
1989
+ removed: z.boolean().optional(), // default true; false restores
1990
+ }),
1991
+ response: z.object({
1992
+ ok: z.boolean(),
1993
+ cyp: z.string().optional(),
1994
+ evidenceId: z.string().optional(),
1995
+ caption: z.string().optional(),
1996
+ removed: z.boolean().optional(),
1997
+ by: z.string().optional(),
1998
+ at: z.string().optional(),
1999
+ error: z.string().optional(), // 'not_found' | 'unknown_evidence' | 'forbidden' | 'not_synthetic' | 'write_failed'
2000
+ detail: z.string().optional(),
2001
+ }),
2002
+ effect: "signal", cost: "free", reversible: true, idempotent: true, auth: "session",
2003
+ }),
1869
2004
  // The event a provision's `verification.closesOn` names (cases/cyp-001.ts H1).
1870
2005
  // A receiver cannot be per-child, so the child rides in `cyp` and the instance
1871
2006
  // name `ehc:<cyp>:meal-served` is what the event row carries. It records a
@@ -1891,6 +2026,43 @@ export const RECEIVERS = {
1891
2026
  }),
1892
2027
  effect: "signal", cost: "free", reversible: false, idempotent: false, auth: "session",
1893
2028
  }),
2029
+ // trace:read — one signal's journey, read back hop by hop (text/signal-trace-plan.md).
2030
+ // A READ of Analytics Engine dataset `one_trace`; no D1, no TypeDB, no model.
2031
+ "trace:read": receiver({
2032
+ receiver: "trace:read",
2033
+ summary: "Read one signal trace back by the 24-hex id a response handed its caller in X-Trace-Id: every span that shares it, ordered by startMs, each {spanId, parent, hop, outcome, service, colo, startMs, durMs, offsetMs, mixedClock, sampleInterval}. THREE states, never a fourth: `found` (the spans), `pending` (none written yet \u2014 Analytics Engine ingests with a lag, and a hop with no binding writes nothing; this is NEVER \"a trace with no hops\"), `failed` (the read itself failed, with `error`; a failure is never an empty list). `offsetMs` across two services subtracts two workers' clocks and says so in `mixedClock`. Caps at 200 spans and names the cut in `truncated`; `sampled` is true when Analytics Engine kept a sample. Requires an attested caller (session, world key or staff) \u2014 the id is a correlation label, never authority",
2034
+ request: z.object({
2035
+ traceId: z.string().describe("The 24 lowercase hex trace id (12 hex of mint-time ms + 12 random). Anything else is refused as not_a_trace_id before it reaches SQL"),
2036
+ }),
2037
+ response: z.object({
2038
+ ok: z.boolean(),
2039
+ state: z.enum(["found", "pending", "failed"]).describe("found = spans below; pending = nothing written yet, not 'no hops'; failed = the read failed, see error"),
2040
+ traceId: z.string().optional(),
2041
+ spans: z.array(z.object({
2042
+ spanId: z.string(),
2043
+ parent: z.string().describe("The caller's span id, or '' at the root"),
2044
+ hop: z.string().describe("Closed vocabulary: web.chat · web.first-chunk · web.stream · channels.message"),
2045
+ outcome: z.string().describe("ok · error · refused · dissolved"),
2046
+ service: z.string(),
2047
+ colo: z.string(),
2048
+ startMs: z.number().describe("Epoch ms at the span's opening I/O edge"),
2049
+ durMs: z.number().describe("Ms between two I/O edges; Workers clocks do not advance during pure CPU"),
2050
+ offsetMs: z.number(),
2051
+ mixedClock: z.boolean(),
2052
+ sampleInterval: z.number(),
2053
+ })).optional(),
2054
+ total: z.number().optional(),
2055
+ sampled: z.boolean().optional(),
2056
+ truncated: z.object({ spans: z.number() }).optional().describe("Present only when the 200-span cap bit"),
2057
+ reason: z.string().optional(),
2058
+ error: z.string().optional().describe("On state:failed \u2014 not_a_trace_id · unauthenticated · no_account · no_credentials · unreachable · sql_<status>"),
2059
+ }),
2060
+ // A pure read that spends a Cloudflare API call, so a caller must be attested:
2061
+ // the ask door's auth is the rate limit a public route did not have. The
2062
+ // resolver enforces it from ctx too, because `session` only WARNS in the binder.
2063
+ auth: "session",
2064
+ effect: "ask", idempotent: true, reversible: true,
2065
+ }),
1894
2066
  "story:chain": receiver({
1895
2067
  receiver: "story:chain",
1896
2068
  summary: "The stories, counted: sets of two or more signals sharing one `origin`, read from the D1 lineage ledger (migrations/0244_story_link.sql). A story is a COUNT over a shared origin, not an entity \u2014 zero new types, zero new dimensions. The number moves as a side effect of signals that already flow; nobody types a row. `count` is the whole qualifying population, `stories` a page of at most 50 ordered by members desc \u2014 a capped count would plateau exactly when the substrate got busy. Zero is a real answer, never an error",
@@ -2473,8 +2645,13 @@ export const RECEIVERS = {
2473
2645
  ok: z.boolean(),
2474
2646
  workspace: z.string().optional(),
2475
2647
  workspaces: z.array(z.string()).optional().describe("Every group the rows were read from (scope:'tree')."),
2476
- asOf: z.string().optional().describe("ISO time the snapshot was built. Rows are at most this stale."),
2648
+ asOf: z.string().optional().describe("ISO time the snapshot was built. Rows are at most this stale — unless `stale` is present, when they are exactly this stale."),
2477
2649
  cached: z.boolean().optional(),
2650
+ stale: z.literal(true).optional().describe("Present only when the rebuild FAILED and this answer is the last board that was successfully built (kept up to 7 days). `asOf` is when that board was built; `upstream` is why the rebuild failed. Absent = a live snapshot. tasks:bulk never acts on a stale board."),
2651
+ upstream: z.object({
2652
+ status: z.number().describe("HTTP status of the failed TypeDB read (0 = no response)."),
2653
+ detail: z.string().optional().describe("The gateway's error text, first 200 chars."),
2654
+ }).optional().describe("Why the rebuild failed. Present iff `stale`."),
2478
2655
  total: z.number().optional().describe("Rows matching the filters, before paging. Exact — UNLESS `truncated.rows` is present, in which case the snapshot itself was capped and total is a floor."),
2479
2656
  returned: z.number().optional(),
2480
2657
  nextCursor: z.string().optional().describe("Present iff more rows match. Absent = you have them all."),
@@ -2486,12 +2663,13 @@ export const RECEIVERS = {
2486
2663
  summary: z.object({
2487
2664
  byStatus: z.record(z.string(), z.number()),
2488
2665
  byTag: z.record(z.string(), z.number()).describe("Bare tags only (no workspace:/slug:/@ namespaces), top 100 by count."),
2489
- byAssignee: z.record(z.string(), z.number()).describe("'' key = unassigned."),
2666
+ byAssignee: z.record(z.string(), z.number()).describe("'' key = KNOWN unassigned. Rows whose assignee is unknown (see assigneeUnknown) are in no key."),
2490
2667
  byWorkspace: z.record(z.string(), z.number()),
2491
2668
  ready: z.number().describe("Open with every blocker closed — claimable now."),
2492
2669
  blocked: z.number().describe("Has at least one open blocker, or status blocked."),
2493
2670
  overdue: z.number(),
2494
- unassigned: z.number(),
2671
+ unassigned: z.number().describe("Rows with no @assignee tag. A FLOOR when `assigneeUnknown` is present: those rows may be assigned."),
2672
+ assigneeUnknown: z.number().optional().describe("Rows whose tag read was cut (truncated.tags) and carried no @assignee in the part that was read — UNKNOWN, not unassigned. Absent = every assignee is known."),
2495
2673
  orphans: z.number().describe("No parent — unreachable from any plan's containment walk."),
2496
2674
  noNotes: z.number().describe("No prose goal — the rows a puller cannot act on."),
2497
2675
  readyIds: z.array(z.string()).describe("Top 50 ready rows by priority."),
@@ -2504,6 +2682,7 @@ export const RECEIVERS = {
2504
2682
  priority: z.number(),
2505
2683
  tags: z.array(z.string()).describe("Bare tags; workspace:/@assignee are lifted into their own fields."),
2506
2684
  assignee: z.string().optional(),
2685
+ assigneeUnknown: z.literal(true).optional().describe("This row's tags were cut before any @assignee was seen: absent `assignee` means UNKNOWN here, not unassigned."),
2507
2686
  workspace: z.string(),
2508
2687
  parent: z.string().optional(),
2509
2688
  blockedBy: z.array(z.string()).optional(),
@@ -2573,7 +2752,9 @@ export const RECEIVERS = {
2573
2752
  removeBlockedBy: z.array(z.string()).optional().describe("tasks:undepend per id"),
2574
2753
  comment: z.string().optional().describe("Post to the task's inbox thread (tasks:comment) — say WHY you changed it, so the humans watching the thread see the decision"),
2575
2754
  workspace: z.string().optional().describe("Per-row override of the envelope workspace. A request, never a grant — one you may not operate refuses the whole call before any write."),
2576
- })).max(25).optional(),
2755
+ // STRICT: an unknown key (a typo like `priorty`) is REFUSED by name, never
2756
+ // stripped — a stripped key answers ok:true for a field nobody wrote.
2757
+ }).strict()).max(25).optional(),
2577
2758
  creates: z.array(z.object({
2578
2759
  ref: z.string().optional().describe("A local handle, e.g. 'a'. Other rows in THIS call may name it in parent/blockedBy/addBlockedBy; the receipt maps ref → tid."),
2579
2760
  title: z.string(),
@@ -2585,7 +2766,8 @@ export const RECEIVERS = {
2585
2766
  blockedBy: z.array(z.string()).optional().describe("Existing task ids or refs created earlier in this array"),
2586
2767
  dueAt: z.string().optional(),
2587
2768
  workspace: z.string().optional(),
2588
- })).max(25).optional(),
2769
+ // STRICT, for the same reason as `edits`: `asignee` must refuse at 400, not vanish.
2770
+ }).strict()).max(25).optional(),
2589
2771
  where: z.object({
2590
2772
  status: z.union([z.string(), z.array(z.string())]).optional(),
2591
2773
  tags: z.array(z.string()).optional(),
@@ -6454,10 +6636,33 @@ export const RECEIVERS = {
6454
6636
  .max(64)
6455
6637
  .optional()
6456
6638
  .describe("Run this turn on a named model (an OpenRouter id, e.g. 'moonshotai/kimi-k3') instead of the actor's own. VETTED server-side against the workspace's enabledModelIds — a claim outside that list degrades to the operator's configured model, never to the claim. Absent = the actor's model, unchanged."),
6639
+ tags: z
6640
+ .array(z.string().min(1).max(64))
6641
+ .max(12)
6642
+ .optional()
6643
+ .describe("Bare routing words for THIS call — a shape ('react-component'), a department ('sales'), a bake run id. Never namespaced. Carried onto the AI Gateway log as metadata beside the call's tokens and cost (channels/src/gateway-meta.ts), so spend can be filtered by them; never part of the user turn. The door's own signalId rides beside them from ctx, never from this body."),
6457
6644
  }).catchall(z.unknown()), // extra keys = the agent's input
6458
- response: z.object({ ok: z.boolean(), text: z.string().optional(), actorId: z.string().optional(), error: z.string().optional() }),
6645
+ response: z.object({
6646
+ ok: z.boolean(),
6647
+ text: z.string().optional(),
6648
+ actorId: z.string().optional(),
6649
+ error: z.string().optional(),
6650
+ usage: z
6651
+ .object({
6652
+ model: z.string(),
6653
+ tokensIn: z.number(),
6654
+ tokensOut: z.number().describe("Provider-reported output tokens, INCLUDING reasoning — the part the answer text never shows"),
6655
+ reasoningTokens: z.number().optional(),
6656
+ credits: z.number().optional().describe("What the workspace was charged: upstream cost + margin, whole credits"),
6657
+ costCredits: z.number().optional().describe("Upstream cost alone, priced per model from the live OpenRouter blob"),
6658
+ refused: z.string().optional().describe("A gate that would have refused this spend (402 | floored | budget_exhausted | float_locked). The row was still written: the tokens were already spent"),
6659
+ unmetered: z.literal(true).optional().describe("No burn row was written — say so, never read it as free"),
6660
+ })
6661
+ .optional()
6662
+ .describe("What this run cost, one-router card 11. Absent only when channels reported no usage."),
6663
+ }),
6459
6664
  effect: "ask", cost: "variable", reversible: false, idempotent: false, simulatable: false, settles: "none", auth: "manage_workflows",
6460
- examples: [{ actorId: "one:support", skill: "support", instructions: "Reply kindly." }],
6665
+ examples: [{ actorId: "one:support", skill: "support", instructions: "Reply kindly." }, { actorId: "m-deepseek", instructions: "Write the component.", tags: ["bake", "react-component"] }],
6461
6666
  }),
6462
6667
  // ── video — room provisioning, sessions, invitations, recording (text/video-live-improve-plan.md) ──
6463
6668
  // Seven receivers already ship in receiver-resolvers.ts. These declarations expose