@paigy/mcp 0.40.0 → 0.40.1
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/README.md +18 -8
- package/dist/{chunk-DM6YPBQH.js → chunk-3QUIB42M.js} +604 -614
- package/dist/{chunk-CWGZVTPZ.js → chunk-4UZAPBKK.js} +740 -905
- package/dist/{chunk-BOLKVO6W.js → chunk-CXABA27N.js} +1 -1
- package/dist/{chunk-FYH6FW2D.js → chunk-TLASZUJD.js} +6 -91
- package/dist/enable.js +3 -3
- package/dist/index.js +11 -153
- package/dist/listen.js +25 -5
- package/dist/onboard.js +4 -4
- package/dist/slot.js +1 -1
- package/dist/statusline.js +4 -2
- package/package.json +12 -13
- package/dist/chunk-2SWUY5WK.js +0 -57
|
@@ -1,23 +1,21 @@
|
|
|
1
1
|
// ../../packages/schema/dist/index.js
|
|
2
|
+
import { z as z3 } from "zod";
|
|
2
3
|
import { z as z2 } from "zod";
|
|
3
|
-
import { z } from "zod";
|
|
4
4
|
import { zodToJsonSchema } from "zod-to-json-schema";
|
|
5
|
+
import { z } from "zod";
|
|
5
6
|
var OPTIONS_MIN = 2;
|
|
6
7
|
var OPTIONS_MAX = 6;
|
|
7
|
-
var MISSED_CALL_PLAN = {
|
|
8
|
-
retry_10m: { kind: "every", minutes: 10 },
|
|
9
|
-
retry_30m: { kind: "every", minutes: 30 },
|
|
10
|
-
retry_60m: { kind: "every", minutes: 60 },
|
|
11
|
-
backoff_gentle: { kind: "at", minutes: [30, 120, 360] },
|
|
12
|
-
backoff_standard: { kind: "at", minutes: [10, 30, 120] },
|
|
13
|
-
backoff_aggressive: { kind: "at", minutes: [5, 15, 45] },
|
|
14
|
-
inbox: { kind: "once" },
|
|
15
|
-
dismiss: { kind: "grace", minutes: 2 }
|
|
16
|
-
};
|
|
17
8
|
function draft2020(node) {
|
|
18
9
|
if (Array.isArray(node)) return node.map(draft2020);
|
|
19
10
|
if (node && typeof node === "object") {
|
|
20
11
|
const o = node;
|
|
12
|
+
if (Array.isArray(o.items)) {
|
|
13
|
+
o.prefixItems = o.items;
|
|
14
|
+
if ("additionalItems" in o) {
|
|
15
|
+
o.items = o.additionalItems;
|
|
16
|
+
delete o.additionalItems;
|
|
17
|
+
} else delete o.items;
|
|
18
|
+
}
|
|
21
19
|
for (const [excl, lim] of [["exclusiveMinimum", "minimum"], ["exclusiveMaximum", "maximum"]]) {
|
|
22
20
|
if (typeof o[excl] === "boolean") {
|
|
23
21
|
if (o[excl] === true && typeof o[lim] === "number") {
|
|
@@ -36,95 +34,82 @@ function mcpInputSchema(s) {
|
|
|
36
34
|
delete schema.$schema;
|
|
37
35
|
return draft2020(schema);
|
|
38
36
|
}
|
|
39
|
-
var
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
});
|
|
55
|
-
var
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
),
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
});
|
|
90
|
-
const out = mcpInputSchema(surface);
|
|
91
|
-
delete out.required;
|
|
92
|
-
out.anyOf = [{ required: ["ask"] }, { required: ["wait"] }];
|
|
93
|
-
return out;
|
|
94
|
-
}
|
|
95
|
-
var CONTACT_DESCRIPTION = `Reach the user through Paigy \u2014 tell them something, or ask and get their answer. State what you need in \`ask\`, say what happens to your work while you wait in \`waiting\`, and Paigy handles the rest (channel, phrasing, answer format). If the user explicitly asks you to CALL them, send waiting:'hard' and say so in the ask. Returns { notificationId, parentId, workId?, decisionId?, wait? }. WHEN IT RANG, contact holds the first ~45 s window ITSELF and \`wait\` carries the outcome: { type:'reply', answer } to act on; { type:'partial', inFlight:true, turn } \u2014 what the user is saying to each turn, provisional: use it to PREPARE (fetch, draft, warm the build), never to act irreversibly, they can still revise it until the final reply (partial = intelligence, settled = authorization; if a partial's acts carry a question aimed at you and you know the answer, contact on the SAME parentId right away \u2014 they hear it on the same call); { type:'remind', remindInSeconds } \u2014 schedule a wake-up; { type:'idle' } \u2014 still waiting. TO KEEP WAITING, call contact again with ONLY { wait: notificationId } \u2014 no ask, nothing new is sent; it holds the next scoped ~45 s window (under the 60 s host cap, so it always returns) and never returns another notification's reply. Keep doing that until the reply \u2014 THAT one is the decision \u2014 so the user steps away and comes back to find you already continued; stop only to do other work and check back, or after an unreasonably long stretch worth telling them about. A message delivery has NO \`wait\`: never poll for it \u2014 the reply arrives through check_replies or your wake. Pass parentId to a later contact to continue the conversation. When it rang, the reply also carries { ifMissed: { mode, means } }: what the user's own policy does with a call they don't take ("${STANDARD_MEANS}"), so a no-answer tells you how long to wait before coming back. THREADING REPLACES: a threaded follow-up SUPERSEDES your earlier pending items on that thread \u2014 right for updates to one ask, WRONG for a checklist (send independent to-dos un-threaded). A threaded re-send with IDENTICAL content escalates the pending ask in place. If a reply comes back as {kind:'clarify', chunks:[...]}, the user wants more detail \u2014 contact again on the SAME parentId with an expanded ask. BLOCKED ON A DECISION for existing work? Pass that work's \`workId\`; the reply returns the same workId plus a decisionId, so the answer resumes the right outcome. ONE ASK, ONE ROW: never restate a still-pending ask's question inside a NEW contact (e.g. weaving it into a briefing) \u2014 the whole answer settles on the new row and the original can never receive it. Keep waiting on the original (a live call reads every pending ask out separately, each answer routes to its own row), and use \`needs\` for a genuinely multi-part NEW ask. ANSWERABLE, NOT JUST ASKED: when the reply comes back carrying \`plan.units[].needs\`, that unit asked for something it gave the user no way to answer \u2014 'options' means it posed a choice with nothing to choose from, 'visuals' means it asked about something to look at with nothing to look at. Send it again on the SAME parentId with ${OPTIONS_MIN}-${OPTIONS_MAX} options (or the image), drawn from your own sentence. Paigy will not add them for you: a shape it guessed wrong cannot be undone, and you are the one who knows what the real alternatives are. \`units\` reports WHAT BECAME OF YOUR PROSE \u2014 { kept, raw, why }: how many topics Paigy compressed for delivery, how many kept your exact words, and the reason when it kept them (e.g. 'no_output' = compression produced nothing usable, so the user got your raw sentence). It needs no action and is not an error \u2014 read it only when the delivered wording matters to you; a high \`raw\` count means the user is hearing you verbatim. READING A CALL'S REPLY: it can come back as {kind:'turns', turns:[{prompt,reply}]} \u2014 the ordered log of that call. Read turns[0].reply as the user's main instruction. Usually that's the only turn; if there are more (e.g. an end-of-call 'call me back when it's done / I have a question that blocks me'), read each one in order as a further follow-up instruction, not a single combined one. If they asked for a callback, re-engage in the SAME thread (contact with the reply's parentId) when the task is done or you hit a blocker \u2014 waiting:'hard' for a blocker, waiting:'none' for done. Paigy has no scheduler; the callback is yours to send (use ScheduleWakeup/cron for timing). A call-mapped answer may carry \`intents\` \u2014 next steps the user attached, each { kind, detail } with detail quoting their words. ACT on them, don't just read them: 'defer' ("call me after lunch") \u2192 register it NOW with schedule_callback \u2014 when the intent carries \`dueInSeconds\` (Paigy pre-parsed the spoken time against the user's clock) pass it straight through; otherwise derive it from the detail yourself \u2014 then follow up on the same thread; 'delegate' ("you pick") \u2192 make the call yourself and tell them what you chose; 'channel' ("text me next time") \u2192 honor it on your next contact (channel:'message'); 'question' (an open question aimed back at you that the call couldn't answer) \u2192 you OWE them the answer \u2014 work it out and follow up on the same thread without being asked, the call deliberately skipped "should I call you back?" because the follow-up is implied. \`transcript\` is the user's raw words behind a shaped answer \u2014 read it for hedges and conditions ("yes, IF tests pass") before acting. If your ask declared \`points\`, the reply carries \`covered\` \u2014 the points actually addressed. Compare against what you declared: a missing point is STILL unanswered \u2014 re-ask it (contact on the same parentId) or proceed knowingly partial; never treat a partial answer as complete.`;
|
|
96
|
-
var CHECK_REPLIES_DESCRIPTION = "The catch-up sweep for everything outstanding \u2014 a PURE read, takes no arguments, safe to call as often as you like: nothing here is consumed by reading it. Returns `replies` (answers to notifications you sent), `work` \u2014 durable outcomes currently owned by you \u2014 plus your still-pending notifications and `requests`, requests the user started toward you (each { notificationId, parentId, workId?, text }); replies tied to Work carry workId and decisionId too. Pass workId back to contact when a new decision blocks that outcome. A REQUEST keeps reappearing until you engage with it \u2014 call set_work_state with its workId, or notificationId once when workId is absent, to claim it \u2014 because human-initiated work must never be silently dropped just because you read the list. A REPLY is different: it is acknowledged by being delivered to you, and needs no set_work_state to stop resurfacing \u2014 report state on it only when it starts real follow-up work. Also returns `threads` \u2014 the SAME replies + requests grouped by conversation, oldest thread first, each with a `busy` flag and its `items` in arrival order. WORK ONE THREAD AT A TIME: take the oldest thread whose `busy` is false, handle ALL of its items together in a single turn (one set_work_state), then go to the next \u2014 don't interleave threads item-by-item. A `busy` thread already has a turn in progress; leave it and let its new items ride the next turn. Use check_replies when booting up / starting a session, or when you've been waiting a long time on something else. To wait on an answer to a contact call you just made, call contact again with only { wait: notificationId } instead. Also returns owedCallbacks: callbacks now due that you promised \u2014 fulfill each with contact on its parentId. EVERY Paigy reply \u2014 this one and contact's \u2014 may carry `also`: work assigned to you that no wake could reach, handed to you because you happened to be here. It is NOT what you asked about and it is never urgent: FINISH what you came for first, then take it up. Each entry has a `noteId` and the owner's own words; report on its `parentId` thread when it has one, and call set_work_state with its noteId as the bootstrap notificationId. Ignoring it costs nothing \u2014 it rides your next reply too. Also returns `stalled`: work (either direction) you reported in_progress via set_work_state a while ago and never reported completed \u2014 likely left half-done by this session or a prior one that crashed or went idle. For each, either continue the work and report a real state, or investigate why it stalled. Also returns `you` \u2014 WHICH IDENTITY you are speaking as ({ name, device, tokenId }), the same name and device the user sees on their Agents screen. This is the only safe way to find out (calling `pair` can MINT a new identity instead of telling you about the current one). Use it when the user asks who you are, and to tell whether work addressed to a name is addressed to you. A request may also carry `stranded`: it was addressed to ANOTHER agent on this account (that name) which has not been seen since it landed, so nobody came for it and it is handed to you because you are the session that is here. Take it exactly like your own \u2014 set_work_state claims it, reply with contact on its parentId \u2014 and say whose it was, because the user picked that agent on purpose. Replies may carry `intents`/`transcript`/`covered` (call-mapped answers) \u2014 handle intents exactly as contact's description says (defer \u2192 schedule_callback now; delegate \u2192 decide and say so; channel \u2192 honor next contact), and treat a `covered` list missing one of your declared points as that part still unanswered.";
|
|
97
|
-
var SCHEDULE_CALLBACK_DESCRIPTION = "Promise the user a follow-up you'll keep even if you go idle. Use it when they ask you to report back: trigger 'on_done' (when you finish \u2014 fires when you call set_work_state completed), 'on_blocked' (if you hit a blocker \u2014 fires on set_work_state needs_input), or 'scheduled' with dueInSeconds (e.g. 'remind me in 10 min'). Pass the parentId of the conversation and a short note. Fulfill it by calling contact on that parentId; check_replies re-lists due callbacks until you do.";
|
|
37
|
+
var StartContactSchema = z.object({
|
|
38
|
+
goalIds: z.tuple([z.string().uuid()]),
|
|
39
|
+
ask: z.string().trim().min(1).max(1e4),
|
|
40
|
+
waiting: z.enum(["none", "hard"]).default("none"),
|
|
41
|
+
channel: z.enum(["notification", "call"]).default("notification"),
|
|
42
|
+
options: z.array(z.object({ label: z.string().trim().min(1).max(1e3), image: z.string().url().optional(), html: z.string().max(16384).optional() }).strict()).min(2).max(6).optional(),
|
|
43
|
+
threadId: z.string().uuid().optional().describe("Continue an existing Thread: the threadId a prior Delivery returned. Omit to start a new Thread.")
|
|
44
|
+
}).strict();
|
|
45
|
+
var ContactSchema = z.union([StartContactSchema, z.object({ deliveryId: z.string().uuid() }).strict()]);
|
|
46
|
+
var CONTACT_SCHEMA = { type: "object", ...mcpInputSchema(ContactSchema) };
|
|
47
|
+
var CONTACT_DESCRIPTION = "Contact the user about exactly one existing Goal: pass goalIds:[goalId], ask, channel:'notification'|'call', and waiting:'none'|'hard'. Options supply choices. Notification returns immediately; collect durable answers with claim_goal/get_goal. On stdio, a Call holds one cancellable ~45s window; continue with ONLY {deliveryId}. Continuation sends nothing and rereads the same durable evidence, including previously read answers. Entries retain authorship and provenance; accepted decisions are separate from quoted speech. Call state open does not mean ringing. Unsupported: soft waiting, multiple Goals/questions, outcome admission, and re-presentation of an existing request. Create a Goal explicitly first; never resend a pending ask to continue waiting.";
|
|
48
|
+
var CreateGoalSchema = z2.object({
|
|
49
|
+
outcome: z2.string().trim().min(1).max(1e4),
|
|
50
|
+
ownerParticipant: z2.string().trim().min(1).optional(),
|
|
51
|
+
idempotencyKey: z2.string().trim().min(1).max(200)
|
|
52
|
+
});
|
|
53
|
+
var CreateGoalToolSchema = CreateGoalSchema.extend({
|
|
54
|
+
idempotencyKey: CreateGoalSchema.shape.idempotencyKey.optional().describe("Optional. One is minted per call; pass your own only so a retry lands on the same Goal.")
|
|
55
|
+
}).strict();
|
|
56
|
+
var CREATE_GOAL_DESCRIPTION = "Create a durable root Goal for an outcome. Admission only: the owner must claim it before doing work, then update it as it advances. Returns an admission receipt with goalId, current state, revision, ownerParticipant, and the next step; no Goal content or execution lease.";
|
|
57
|
+
var UpdateGoalSchema = z2.object({
|
|
58
|
+
revision: z2.number().int().positive(),
|
|
59
|
+
changes: z2.object({
|
|
60
|
+
outcome: z2.string().trim().min(1).max(1e4).optional(),
|
|
61
|
+
ownerParticipant: z2.string().trim().min(1).optional(),
|
|
62
|
+
parentGoalId: z2.string().uuid().nullable().optional(),
|
|
63
|
+
dependencies: z2.array(z2.object({ goalId: z2.string().uuid(), gate: z2.enum(["start", "finish"]) }).strict()).optional(),
|
|
64
|
+
children: z2.array(z2.object({ outcome: z2.string().trim().min(1).max(1e4), ownerParticipant: z2.string().trim().min(1), gate: z2.enum(["start", "finish"]).optional() }).strict()).optional(),
|
|
65
|
+
state: z2.enum(["active", "done", "cancelled"]).optional(),
|
|
66
|
+
progress: z2.string().trim().min(1).max(1e4).optional(),
|
|
67
|
+
reviewed: z2.literal(true).optional()
|
|
68
|
+
}).strict().refine((v) => Object.keys(v).length > 0),
|
|
69
|
+
reason: z2.string().trim().min(1).max(2e3),
|
|
70
|
+
operationId: z2.string().uuid().optional()
|
|
71
|
+
}).strict();
|
|
72
|
+
var UpdateGoalToolSchema = UpdateGoalSchema.omit({ operationId: true }).extend({ goalId: z2.string().uuid() }).strict();
|
|
73
|
+
var ClaimGoalSchema = z2.object({ goalId: z2.string().uuid().optional() }).strict();
|
|
74
|
+
var GetGoalSchema = z2.object({ goalId: z2.string().uuid() }).strict();
|
|
75
|
+
var GET_GOAL_DESCRIPTION = "Read the current authorized Goal brief: state, owner, blockers, open decisions, progress, and the next operation. Foreign or sibling-owned Goals are not disclosed.";
|
|
76
|
+
var UPDATE_GOAL_DESCRIPTION = "Update an owned Goal at an exact revision. State, ownership, dependencies, children, progress, and review acknowledgement are explicit; stale revisions are rejected. Returns the new revision and a prose summary.";
|
|
77
|
+
var CLAIM_GOAL_DESCRIPTION = "Claim the oldest runnable or review-pending Goal you own, or pass goalId to claim that Goal. Returns a Goal-scoped brief, current revision, blockers, and the next valid operation. Claiming creates or renews the execution lease.";
|
|
78
|
+
var CHECK_REPLIES_DESCRIPTION = "Your open Deliveries: every Notification or Call currently addressed to you \u2014 a request the user started toward you, an answer relayed to something you asked, a handoff \u2014 each with its durable Entries, accepted decisions and open decision needs, in the same shape a contact read returns. A pure read with no arguments: nothing is consumed, acknowledged or claimed by reading it, so call it on startup, after a long wait, or whenever you want to know what is outstanding. To act on one, claim its Goal (claim_goal) or reread it with contact({deliveryId}). Your runnable and review-pending Goals come from claim_goal, not from here.";
|
|
79
|
+
var CheckRepliesSchema = z2.object({}).strict();
|
|
80
|
+
var GetThreadSchema = z2.object({
|
|
81
|
+
parentId: z2.string().describe("The Thread to read \u2014 the threadId a Delivery returned, or the parentId of a search hit.")
|
|
82
|
+
}).strict();
|
|
83
|
+
var GET_THREAD_DESCRIPTION = "Read the authorized durable Entries on one conversation Thread \u2014 what you wrote there and what was delivered to you, oldest first. Use claim_goal to find the work to resume; use this to rehydrate a Thread that a search hit or a Delivery named.";
|
|
84
|
+
var SearchThreadsSchema = z2.object({
|
|
85
|
+
q: z2.string().describe("What to look for \u2014 plain words or a phrase (e.g. 'the livekit timeout', 'deploy to prod').")
|
|
86
|
+
}).strict();
|
|
98
87
|
var SEARCH_THREADS_DESCRIPTION = `Search your PAST conversations before asking \u2014 "have we discussed this before?". Full-text over your own threads (the asks you sent + the user's answers); returns ranked threads with highlighted snippets, NOT rows: { hits: [{ parentId, at, agentLabel, matches: [{ notificationId, role, snippet }] }] }. The loop this exists for: search first \u2192 get_thread the best hit to rehydrate it \u2192 THEN continue or contact, so you answer with receipts ("last week you said ship it") instead of re-asking. Read-only, safe to call anytime; scoped to your own account's threads.`;
|
|
99
|
-
var
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
//
|
|
113
|
-
// The carve-out is stated rather than left to per-session judgment, because judgment
|
|
114
|
-
// exercised cold, once per session, is not judgment — it is a coin landing the same way.
|
|
115
|
-
"Never end a turn that still needs the user without contact (and, for a call, the wait it holds) \u2014 WHEN THEY ARE NOT THERE TO ASK. In an interactive session with the user at the terminal, the prompt IS the channel: ending your turn with the question already reaches them, faster and richer than a push, so do NOT send one for an ordinary blocked-or-done moment. Reach for Paigy exactly when the terminal is not enough \u2014 work that will run more than a few minutes unattended (a long build, a deploy, a background job, a cloud session), anything you finish or get stuck on while they are away, or when they have said they are stepping out. If you cannot tell which situation you are in, ask them once, in passing, how they want to be reached, and follow that for the rest of the session. When you need a decision or input, WRITE THE QUESTION and Paigy derives the answer shape from it \u2014 there is no shape parameter to set, and passing one is an error. Ask a yes/no question and they get yes/no; ask them to approve an action and they get approve/deny; ask them to pick, and to pick several, and to rank, and each gets the control it needs. So phrase the ask precisely: 'which of these should I do first' and 'should I do this' are different questions and become different answers. The one thing the prose can't supply is the CHOICES themselves \u2014 when you're asking them to pick between concrete alternatives, pass `options` (${OPTIONS_MIN}-${OPTIONS_MAX} of them, drawn from your own sentence), because Paigy will not invent alternatives it can't know. On a { kind: 'clarify' } reply, see contact's own description for how to respond. When you send waiting:'hard' (or the user asked you to call), remember the ask may be spoken aloud \u2014 write it short and conversational, and name things instead of using IDs (e.g. 'the pull request about the agents page', not 'PR #235'). When the user asks you to follow up later \u2014 when you're done, if you're blocked, or at a set time \u2014 record it with schedule_callback so you don't drop it if you go idle. If you're about to start a genuinely long-running or blocking piece of work \u2014 one where the user would otherwise sit and wait \u2014 mention ONCE, in passing, that you can reach them when it's done or if you hit a blocker, instead of them needing to babysit the terminal. Don't offer this for quick tasks, and don't repeat the offer if they've already said yes or no earlier in the conversation. NEVER go quietly idle while something might still be pending for you: whenever you end a turn with any Paigy notification unanswered (or any chance the user replied through the app while you worked), schedule your own ~2-minute wake-up (harness ScheduleWakeup or equivalent) and call check_replies when it fires; if still nothing, re-schedule and keep looping until resolved or the user says stop. For legibility, always use this exact wording \u2014 reason: 'Paigy idle check \u2014 waiting on <thing>', wake-up prompt: 'Paigy idle check: call check_replies and engage with anything unacknowledged; if idle, re-schedule (~2min).' \u2014 so the user can recognize every idle check at a glance. This self-polling in your own live session (full context intact) is the PRIMARY mechanism; the plugin's Stop hooks are only the dead-session safety net.";
|
|
88
|
+
var AGENT_TOOLS = [
|
|
89
|
+
{ name: "contact", description: CONTACT_DESCRIPTION, inputSchema: CONTACT_SCHEMA },
|
|
90
|
+
{ name: "check_replies", description: CHECK_REPLIES_DESCRIPTION, inputSchema: mcpInputSchema(CheckRepliesSchema) },
|
|
91
|
+
{ name: "get_thread", description: GET_THREAD_DESCRIPTION, inputSchema: mcpInputSchema(GetThreadSchema) },
|
|
92
|
+
{ name: "search_threads", description: SEARCH_THREADS_DESCRIPTION, inputSchema: mcpInputSchema(SearchThreadsSchema) },
|
|
93
|
+
{ name: "create_goal", description: CREATE_GOAL_DESCRIPTION, inputSchema: mcpInputSchema(CreateGoalToolSchema) },
|
|
94
|
+
{ name: "claim_goal", description: CLAIM_GOAL_DESCRIPTION, inputSchema: mcpInputSchema(ClaimGoalSchema) },
|
|
95
|
+
{ name: "get_goal", description: GET_GOAL_DESCRIPTION, inputSchema: mcpInputSchema(GetGoalSchema) },
|
|
96
|
+
{ name: "update_goal", description: UPDATE_GOAL_DESCRIPTION, inputSchema: mcpInputSchema(UpdateGoalToolSchema) }
|
|
97
|
+
];
|
|
98
|
+
var AGENT_TOOL_NAMES = AGENT_TOOLS.map((t) => t.name);
|
|
99
|
+
function serverInstructions(_opts) {
|
|
100
|
+
return "On startup and after a wake, call check_replies for the open Deliveries addressed to you, and claim_goal for your runnable or review-pending Goal and its durable Entries and accepted decisions. get_goal rereads the same evidence without consuming it. Contact only for an existing Goal. Notifications return immediately: keep working and collect answers through claim_goal/get_goal. On stdio, Calls hold one bounded window; on hosted MCP, Calls return after one read; continue with contact({deliveryId}) to reread that exact Delivery. Evidence can repeat: reads do not acknowledge or hide it. Use update_goal to report progress and explicitly acknowledge review. Never infer ringing from an open Call Delivery. Soft waiting, multipart contact, and re-presentation are unsupported. In an interactive session, ask the user directly; use Paigy when they asked for it or are away.";
|
|
116
101
|
}
|
|
117
|
-
var ContextSchema =
|
|
118
|
-
title:
|
|
119
|
-
description:
|
|
102
|
+
var ContextSchema = z3.object({
|
|
103
|
+
title: z3.string().min(1).describe("One-line headline of what you need (required, non-empty)."),
|
|
104
|
+
description: z3.array(z3.string().min(1)).describe(
|
|
120
105
|
"Semantic chunks of detail (each a standalone, non-empty piece). The user can select chunks to ask you to expand. MAY BE EMPTY: a claim whose whole content is its heading \u2014 a single sentence \u2014 has no body, and saying so beats repeating the heading underneath itself. That repeat is what `min(1)` used to force, at 2x the storage, with every reader subtracting it back out at render time."
|
|
121
106
|
)
|
|
122
107
|
});
|
|
123
|
-
var ParticipantSchema =
|
|
124
|
-
kind:
|
|
125
|
-
id:
|
|
108
|
+
var ParticipantSchema = z3.object({
|
|
109
|
+
kind: z3.enum(["human", "agent"]),
|
|
110
|
+
id: z3.string()
|
|
126
111
|
});
|
|
127
|
-
var TransformSchema =
|
|
112
|
+
var TransformSchema = z3.enum([
|
|
128
113
|
"structure",
|
|
129
114
|
// shape intent into an answer contract; pick channel/urgency — broker `ask`, `select` shapes, `points`
|
|
130
115
|
"request_more",
|
|
@@ -140,25 +125,25 @@ var TransformSchema = z2.enum([
|
|
|
140
125
|
"summarize"
|
|
141
126
|
// reduce volume, keep decision value — 30-turn cap, spoken briefing
|
|
142
127
|
]);
|
|
143
|
-
var OptionSchema =
|
|
144
|
-
id:
|
|
145
|
-
label:
|
|
128
|
+
var OptionSchema = z3.object({
|
|
129
|
+
id: z3.string(),
|
|
130
|
+
label: z3.string(),
|
|
146
131
|
// .describe() flows into the MCP contact JSON schema (zodToJsonSchema), so
|
|
147
132
|
// the constraints below are what an agent reads when deciding to use these.
|
|
148
|
-
html:
|
|
133
|
+
html: z3.string().max(16384).describe(
|
|
149
134
|
"Optional sandboxed HTML/CSS preview for a visual 'pick one' (shown in the option card). Untrusted-sandboxed: NO JavaScript, NO external network or images \u2014 inline CSS and data: URIs only; <=16KB. Use for layout/CSS mockups, tables, diffs. For a hosted image use `image` instead."
|
|
150
135
|
).optional(),
|
|
151
|
-
image:
|
|
136
|
+
image: z3.string().url().describe(
|
|
152
137
|
"Optional image URL rendered as the option's preview (plain image, not sandboxed). For agent-generated HTML/CSS mockups, use `html` instead."
|
|
153
138
|
).optional()
|
|
154
139
|
});
|
|
155
|
-
var VisualSchema =
|
|
156
|
-
url:
|
|
157
|
-
label:
|
|
140
|
+
var VisualSchema = z3.object({
|
|
141
|
+
url: z3.string().url(),
|
|
142
|
+
label: z3.string().optional()
|
|
158
143
|
});
|
|
159
|
-
var NotifyLevelSchema =
|
|
160
|
-
var SelectShapeSchema =
|
|
161
|
-
var ReceiptEventSchema =
|
|
144
|
+
var NotifyLevelSchema = z3.enum(["inbox", "push", "banner", "call"]);
|
|
145
|
+
var SelectShapeSchema = z3.enum(["one", "many", "rank", "confirm", "text"]);
|
|
146
|
+
var ReceiptEventSchema = z3.enum([
|
|
162
147
|
"delivered",
|
|
163
148
|
// the bundle reached the recipient at some level
|
|
164
149
|
"seen",
|
|
@@ -188,44 +173,47 @@ var ReceiptEventSchema = z2.enum([
|
|
|
188
173
|
// be rewound by a writer that forgot to advance it.
|
|
189
174
|
"restarted"
|
|
190
175
|
]);
|
|
191
|
-
var AttentionSchema =
|
|
176
|
+
var AttentionSchema = z3.object({
|
|
192
177
|
urgency: NotifyLevelSchema,
|
|
193
178
|
/** The required answer shape, or null for a plain notify that asks nothing back. */
|
|
194
179
|
select: SelectShapeSchema.nullable(),
|
|
195
180
|
/** Coverage contract (#396) — points the answer must address; null = none declared. */
|
|
196
|
-
points:
|
|
181
|
+
points: z3.array(z3.string()).nullable(),
|
|
197
182
|
/** Whether the ask blocks the sender — what lets arbitration escalate it on silence. */
|
|
198
|
-
blocking:
|
|
183
|
+
blocking: z3.boolean(),
|
|
199
184
|
/** Reserved (MODEL.md lists it): a response deadline. No row column yet — a later Phase 2
|
|
200
185
|
* slice wires it; optional so today's rows/callers project cleanly. */
|
|
201
|
-
deadline:
|
|
186
|
+
deadline: z3.string().datetime().nullable().optional()
|
|
202
187
|
});
|
|
203
|
-
var NotifyRequestFields =
|
|
188
|
+
var NotifyRequestFields = z3.object({
|
|
204
189
|
/** Plaintext message content. Present on the plaintext path (today's shape);
|
|
205
190
|
* ABSENT on the E2EE path, where the sealed `envelope` below carries it. The
|
|
206
191
|
* superRefine at the bottom enforces exactly one of the two. */
|
|
207
192
|
context: ContextSchema.optional(),
|
|
208
|
-
options:
|
|
193
|
+
options: z3.array(OptionSchema.omit({ id: true })).min(OPTIONS_MIN).max(OPTIONS_MAX).optional().describe(
|
|
209
194
|
"The choices, in order \u2014 required when select is 'one'/'many'/'rank', omitted otherwise. Ids are assigned automatically by position ('1', '2', \u2026); the user's answer references them as optionId(s)."
|
|
210
195
|
),
|
|
211
|
-
points:
|
|
196
|
+
points: z3.array(z3.string().min(1)).optional().describe(
|
|
212
197
|
"The distinct things you need answered, each a short phrase \u2014 on a call the broker keeps the conversation going until each is addressed, and the reply reports which were covered, so a half-answer is never silently returned as final. Omit for single-part asks."
|
|
213
198
|
),
|
|
214
|
-
visuals:
|
|
199
|
+
visuals: z3.array(VisualSchema).optional().describe(
|
|
215
200
|
"Images attached to the message itself \u2014 context for the whole question (a screenshot, a chart). For a preview on one selectable choice, use that option's `html`/`image` instead."
|
|
216
201
|
),
|
|
217
202
|
/** Git repo the agent is working in ("owner/name"). Local MCP fills this from the checkout — omit unless overriding. */
|
|
218
|
-
repo:
|
|
203
|
+
repo: z3.string().optional(),
|
|
219
204
|
/** Git branch the agent is on. Local MCP fills this from the checkout — omit unless overriding. */
|
|
220
|
-
branch:
|
|
205
|
+
branch: z3.string().optional(),
|
|
221
206
|
/** Continue an existing conversation — the id of any notification in it (its root
|
|
222
207
|
* is the conversation's identity). Omitted = start a new conversation. Renamed
|
|
223
208
|
* from `parentId` (2026-08-03): one linkage system, the parent; the API edge
|
|
224
209
|
* still accepts the old name from older clients. */
|
|
225
|
-
parentId:
|
|
210
|
+
parentId: z3.string().uuid().optional(),
|
|
226
211
|
/** The durable outcome this contact advances. Optional during the notification-to-Work
|
|
227
212
|
* migration; when present, a blocking ask creates a DecisionNeed for this Work. */
|
|
228
|
-
workId:
|
|
213
|
+
workId: z3.string().uuid().optional(),
|
|
214
|
+
/** Target Goal scope. During staged migration this is accepted by the shared contract but
|
|
215
|
+
* target delivery activation remains model-gated; workId and goalId are mutually exclusive. */
|
|
216
|
+
goalId: z3.string().uuid().optional(),
|
|
229
217
|
urgency: NotifyLevelSchema.default("inbox").describe(
|
|
230
218
|
"The level you're requesting \u2014 the user's account permissions + session mode can lower it. 'inbox' (default) = sits silently in the inbox for the user to get to. 'push' = a quiet passive push (lands in Notification Center, no sound) \u2014 a gentle heads-up. 'banner' = a time-sensitive banner/lock-screen push with sound (a 'paige') they tap to open \u2014 use when you need them soon-ish but it's not worth ringing them. 'call' = rings the user's phone now (a CallKit voice call) \u2014 use only when you genuinely need them in the moment (blocked and waiting, time-sensitive). context.title is what they see on the banner/ring, so make it specific."
|
|
231
219
|
),
|
|
@@ -233,7 +221,7 @@ var NotifyRequestFields = z2.object({
|
|
|
233
221
|
* visible and marks it needs_input. Renamed from the old `parentId` (2026-08-03)
|
|
234
222
|
* when `parentId` became the conversation handle: `parentId` says WHERE, this
|
|
235
223
|
* says HOW. */
|
|
236
|
-
clarifies:
|
|
224
|
+
clarifies: z3.string().optional(),
|
|
237
225
|
/** E2EE (text lane): when the pairing is E2EE, the sealed replacements for the
|
|
238
226
|
* plaintext content fields, keyed by field name. FINALIZED wire shape (was
|
|
239
227
|
* provisional in the storage PR): a per-field map `{ context?, options?,
|
|
@@ -246,10 +234,10 @@ var NotifyRequestFields = z2.object({
|
|
|
246
234
|
* notifications.envelope and relays it blindly; it never decrypts. Absent =
|
|
247
235
|
* today's plaintext path (context/options/visuals carry the cleartext).
|
|
248
236
|
* z.lazy because EnvelopeSchema is declared further down (E2EE section). */
|
|
249
|
-
envelope:
|
|
250
|
-
context:
|
|
251
|
-
options:
|
|
252
|
-
visuals:
|
|
237
|
+
envelope: z3.object({
|
|
238
|
+
context: z3.lazy(() => EnvelopeSchema).optional(),
|
|
239
|
+
options: z3.lazy(() => EnvelopeSchema).optional(),
|
|
240
|
+
visuals: z3.lazy(() => EnvelopeSchema).optional()
|
|
253
241
|
}).optional(),
|
|
254
242
|
select: SelectShapeSchema.optional().describe(
|
|
255
243
|
"How the user answers \u2014 required on the fully-shaped form, pick the shape that fits the question: 'one' = pick one option, 'many' = pick several, 'rank' = pick & order (each needs `options`); 'confirm' = yes/no or approve/deny; 'text' = free-form reply only (status updates, open questions). 'confirm' and 'text' take no options. Omit only when sending the simplified `ask` form \u2014 the broker picks the shape."
|
|
@@ -264,20 +252,20 @@ var NotifyRequestFields = z2.object({
|
|
|
264
252
|
// (broker/agenda-design.md) — not by a wire cap the agent has to pre-summarize under.
|
|
265
253
|
// Owner, 2026-07-28: "our actual limitation on how long something is to the user should
|
|
266
254
|
// come from the broker splitting and summarizing." The cap that remains is a size guard.
|
|
267
|
-
ask:
|
|
255
|
+
ask: z3.string().min(1).max(1e4).optional().describe(
|
|
268
256
|
'SIMPLIFIED FORM \u2014 state in plain prose what you need to learn from the user and why it matters now (e.g. "I need to know whether to deploy the auth fix \u2014 tests are green, staging verified"). Write as much as the situation needs (up to 10k characters) \u2014 Paigy breaks it into topics and reads it back a few sentences at a time; do NOT pre-summarize it into one line. Paigy derives the title, answer shape, options, and delivery channel for you. Mutually exclusive with context/select/options \u2014 send one form or the other.'
|
|
269
257
|
),
|
|
270
|
-
needs:
|
|
258
|
+
needs: z3.array(z3.string().min(1)).optional().describe(
|
|
271
259
|
"With `ask` only: the distinct things you need answered when the ask is multi-part \u2014 becomes the coverage contract (`points`), so a half-answer is never silently final."
|
|
272
260
|
),
|
|
273
|
-
urgencyHint:
|
|
261
|
+
urgencyHint: z3.enum(["whenever", "soon", "now"]).optional().describe(
|
|
274
262
|
"With `ask` only: how urgently you need the answer \u2014 'whenever' (inbox), 'soon' (worth a heads-up), 'now' (you're blocked this minute). A hint, not a command: the user's settings still have the final word."
|
|
275
263
|
),
|
|
276
264
|
/** #575: the ONE self-report that replaces urgencyHint + blocking — what happens
|
|
277
265
|
* to the agent's work while it waits. Normalized server-side into those two
|
|
278
266
|
* fields (normalizeWaiting) so everything downstream is untouched; explicit
|
|
279
267
|
* urgencyHint/blocking win when both are sent. */
|
|
280
|
-
waiting:
|
|
268
|
+
waiting: z3.enum(["none", "soft", "hard"]).optional().describe(
|
|
281
269
|
"With `ask`: what happens to your work while you wait. 'none' = you're just informing the user. 'soft' = you'd like an answer but can keep working. 'hard' = you are stopped until they answer (reaches them urgently and escalates to a real phone call if unanswered). Replaces urgencyHint + blocking \u2014 send this one field."
|
|
282
270
|
),
|
|
283
271
|
/** Δ9b (#895): HOLD this claim so the sender can correct the plan before anyone is
|
|
@@ -285,123 +273,124 @@ var NotifyRequestFields = z2.object({
|
|
|
285
273
|
* holding by default would charge every quiet claim that minute before any agent could
|
|
286
274
|
* correct anything. Ignored for `waiting: 'hard'`: a blocking ask rings on what we have,
|
|
287
275
|
* and the enrichment can still land mid-call (#781 re-plans the unspoken tail). */
|
|
288
|
-
confirm:
|
|
276
|
+
confirm: z3.boolean().optional().describe(
|
|
289
277
|
"Hold this one so you can correct the plan before the user is interrupted. The response comes back with `held: true` and the plan; POST the confirm route to release it (with options/visuals/urgency corrections, or nothing at all). If you never do, it is announced anyway a couple of minutes later. Ignored when waiting is 'hard'."
|
|
290
278
|
),
|
|
291
279
|
/** #575: a RELAY of the user's explicitly stated preference, never the agent's
|
|
292
280
|
* choice. Outranks waiting in both directions: 'call' rings even for a
|
|
293
281
|
* waiting:'none' "call me when it's done"; 'message' never rings even for
|
|
294
282
|
* waiting:'hard'. */
|
|
295
|
-
channel:
|
|
283
|
+
channel: z3.enum(["call", "message"]).optional().describe(
|
|
296
284
|
"Only if the user explicitly said how to reach them \u2014 'call me' \u2192 'call', 'just message/text me' \u2192 'message'. Omit otherwise; Paigy picks."
|
|
297
285
|
),
|
|
298
|
-
confirmStyle:
|
|
286
|
+
confirmStyle: z3.enum(["yesno", "approve"]).default("yesno").describe(
|
|
299
287
|
"Labels for a select:'confirm' paige \u2014 'yesno' (Yes/No) or 'approve' (Approve/Deny). Ignored unless select is 'confirm'."
|
|
300
288
|
),
|
|
301
|
-
blocking:
|
|
289
|
+
blocking: z3.boolean().default(false).describe(
|
|
302
290
|
"Set true when real downstream work is stuck behind this specific decision \u2014 you can't make meaningful progress until it's answered. This is the real signal for how urgently the user should be reached; it's what the premier use case (an agent that stays unblocked instead of going idle) depends on. Independent of `urgency`: a `banner`-level question can still be `blocking` (something IS stuck, just not time-critical enough to ring for immediately) \u2014 if it goes unanswered a while, Paigy escalates it to a real call using this flag rather than guessing from how many other things happen to be pending. Leave false for anything you could work around, defer, or where other useful work exists meanwhile."
|
|
303
291
|
)
|
|
304
292
|
});
|
|
305
293
|
var NotifyRequestSchema = NotifyRequestFields.superRefine((r, ctx) => {
|
|
294
|
+
if (r.workId && r.goalId) ctx.addIssue({ code: z3.ZodIssueCode.custom, path: ["goalId"], message: "pass goalId or workId, not both" });
|
|
306
295
|
const sealed = !!r.envelope;
|
|
307
296
|
if (sealed) {
|
|
308
297
|
if (!r.envelope?.context)
|
|
309
|
-
ctx.addIssue({ code:
|
|
298
|
+
ctx.addIssue({ code: z3.ZodIssueCode.custom, path: ["envelope", "context"], message: "sealed request must include envelope.context" });
|
|
310
299
|
for (const f of ["context", "options", "visuals"]) {
|
|
311
300
|
if (r[f] !== void 0)
|
|
312
|
-
ctx.addIssue({ code:
|
|
301
|
+
ctx.addIssue({ code: z3.ZodIssueCode.custom, path: [f], message: `E2EE request must not carry plaintext ${f} \u2014 it's sealed in envelope.${f}` });
|
|
313
302
|
}
|
|
314
303
|
if (r.points !== void 0)
|
|
315
|
-
ctx.addIssue({ code:
|
|
304
|
+
ctx.addIssue({ code: z3.ZodIssueCode.custom, path: ["points"], message: "E2EE request must not carry plaintext points" });
|
|
316
305
|
if (r.ask !== void 0)
|
|
317
|
-
ctx.addIssue({ code:
|
|
306
|
+
ctx.addIssue({ code: z3.ZodIssueCode.custom, path: ["ask"], message: "E2EE request must not carry a plaintext ask \u2014 derive the shape agent-side and seal it" });
|
|
318
307
|
if (r.needs !== void 0)
|
|
319
|
-
ctx.addIssue({ code:
|
|
308
|
+
ctx.addIssue({ code: z3.ZodIssueCode.custom, path: ["needs"], message: "E2EE request must not carry plaintext needs" });
|
|
320
309
|
return;
|
|
321
310
|
}
|
|
322
311
|
if (r.ask !== void 0) {
|
|
323
312
|
for (const f of ["context", "select", "points"]) {
|
|
324
313
|
if (r[f] !== void 0)
|
|
325
|
-
ctx.addIssue({ code:
|
|
314
|
+
ctx.addIssue({ code: z3.ZodIssueCode.custom, path: [f], message: `the simplified \`ask\` form takes no ${f} \u2014 the broker derives the answer shape from your prose. Drop ${f} and say it in \`ask\` instead ("should I\u2026" for approve/deny, "which of these\u2026" for a pick), passing \`options\` when you're offering concrete alternatives.` });
|
|
326
315
|
}
|
|
327
316
|
return;
|
|
328
317
|
}
|
|
329
318
|
if (r.needs !== void 0 || r.urgencyHint !== void 0)
|
|
330
|
-
ctx.addIssue({ code:
|
|
319
|
+
ctx.addIssue({ code: z3.ZodIssueCode.custom, path: ["needs"], message: "needs/urgencyHint belong to the simplified `ask` form \u2014 with a shaped request use points/urgency" });
|
|
331
320
|
if (!r.context)
|
|
332
|
-
ctx.addIssue({ code:
|
|
321
|
+
ctx.addIssue({ code: z3.ZodIssueCode.custom, path: ["context"], message: "context is required (plaintext path)" });
|
|
333
322
|
if (!r.select)
|
|
334
|
-
ctx.addIssue({ code:
|
|
323
|
+
ctx.addIssue({ code: z3.ZodIssueCode.custom, path: ["select"], message: "select is required on the shaped form" });
|
|
335
324
|
const needsOptions = r.select === "one" || r.select === "many" || r.select === "rank";
|
|
336
325
|
if (needsOptions && !r.options?.length)
|
|
337
|
-
ctx.addIssue({ code:
|
|
326
|
+
ctx.addIssue({ code: z3.ZodIssueCode.custom, path: ["options"], message: `select:'${r.select}' requires options` });
|
|
338
327
|
if (!needsOptions && r.options?.length)
|
|
339
|
-
ctx.addIssue({ code:
|
|
328
|
+
ctx.addIssue({ code: z3.ZodIssueCode.custom, path: ["options"], message: `select:'${r.select}' takes no options` });
|
|
340
329
|
});
|
|
341
|
-
var NotifyStatusSchema =
|
|
342
|
-
var AgentStateSchema =
|
|
343
|
-
var SetTaskStateSchema =
|
|
344
|
-
state:
|
|
330
|
+
var NotifyStatusSchema = z3.enum(["pending", "answered", "ignored"]);
|
|
331
|
+
var AgentStateSchema = z3.enum(["idle", "in_progress", "completed", "needs_input"]);
|
|
332
|
+
var SetTaskStateSchema = z3.object({
|
|
333
|
+
state: z3.enum(["in_progress", "completed", "needs_input"])
|
|
345
334
|
});
|
|
346
|
-
var SetWorkStateSchema =
|
|
347
|
-
workId:
|
|
348
|
-
notificationId:
|
|
335
|
+
var SetWorkStateSchema = z3.object({
|
|
336
|
+
workId: z3.string().uuid().optional(),
|
|
337
|
+
notificationId: z3.string().optional(),
|
|
349
338
|
state: SetTaskStateSchema.shape.state
|
|
350
339
|
}).refine((value) => Number(Boolean(value.workId)) + Number(Boolean(value.notificationId)) === 1, {
|
|
351
340
|
message: "exactly one of workId or notificationId is required"
|
|
352
341
|
});
|
|
353
|
-
var TurnSchema =
|
|
354
|
-
prompt:
|
|
355
|
-
reply:
|
|
356
|
-
});
|
|
357
|
-
var UserAnswerSchema =
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
342
|
+
var TurnSchema = z3.object({
|
|
343
|
+
prompt: z3.string(),
|
|
344
|
+
reply: z3.string()
|
|
345
|
+
});
|
|
346
|
+
var UserAnswerSchema = z3.discriminatedUnion("kind", [
|
|
347
|
+
z3.object({ kind: z3.literal("option"), optionId: z3.string(), label: z3.string().optional() }),
|
|
348
|
+
z3.object({ kind: z3.literal("text"), text: z3.string() }),
|
|
349
|
+
z3.object({ kind: z3.literal("ignored") }),
|
|
350
|
+
z3.object({ kind: z3.literal("multi"), optionIds: z3.array(z3.string()), labels: z3.array(z3.string()).optional() }),
|
|
351
|
+
z3.object({ kind: z3.literal("ranked"), optionIds: z3.array(z3.string()), labels: z3.array(z3.string()).optional() }),
|
|
352
|
+
z3.object({ kind: z3.literal("clarify"), chunks: z3.array(z3.string()).min(1) }),
|
|
353
|
+
z3.object({ kind: z3.literal("confirm"), approved: z3.boolean() }),
|
|
354
|
+
z3.object({ kind: z3.literal("turns"), turns: z3.array(TurnSchema).min(1) }),
|
|
366
355
|
/** An auto-answer derived from the user's PAST decisions (broker/precedent-design.md §2):
|
|
367
356
|
* delivered through the same settle/await path as a human answer, carrying the judge's
|
|
368
357
|
* derivation and the precedent ids it grew from. Always paired with a visible trail
|
|
369
358
|
* card the user can reply to — the broker never overrides the user. */
|
|
370
|
-
|
|
359
|
+
z3.object({ kind: z3.literal("precedent"), answer: z3.string(), derivation: z3.string(), sources: z3.array(z3.string()).min(1) })
|
|
371
360
|
]);
|
|
372
|
-
var IntentSchema =
|
|
361
|
+
var IntentSchema = z3.object({
|
|
373
362
|
// The full vocabulary the bot's mapper emits (mapper.INTENT_KINDS) — the schema lagged
|
|
374
363
|
// it by two ("detail", "feedback"), and because the settle handler parsed the array
|
|
375
364
|
// all-or-nothing, ONE feedback act silently dropped EVERY intent on the call,
|
|
376
365
|
// questions included. Found auditing five calls' stored feedback, 2026-08-01.
|
|
377
|
-
kind:
|
|
378
|
-
detail:
|
|
366
|
+
kind: z3.enum(["defer", "delegate", "channel", "question", "detail", "feedback", "command", "control"]),
|
|
367
|
+
detail: z3.string(),
|
|
379
368
|
/** Defer only: seconds until the callback the caller asked for, when something upstream
|
|
380
369
|
* already read the time. Nothing sets it today (#397 documented an MCP parser that was
|
|
381
370
|
* never written) — the API reads the defer's `detail` itself with `notes/when.ts`
|
|
382
371
|
* (`parseDelay`, #1292), and a value here simply wins over that reading. */
|
|
383
|
-
dueInSeconds:
|
|
372
|
+
dueInSeconds: z3.number().int().positive().optional(),
|
|
384
373
|
/** Feedback only (#812): WHICH failure the complaint names — typed by the mapper that
|
|
385
374
|
* already read the utterance, so `feedback_from_call.kind` stops defaulting to
|
|
386
375
|
* 'other' on every row. A table that records that something was wrong and nothing
|
|
387
376
|
* about what cannot answer "is the bot looping less this week?". */
|
|
388
|
-
fault:
|
|
377
|
+
fault: z3.enum(["loop", "unanswered", "overridden", "misheard", "slow", "other"]).optional()
|
|
389
378
|
});
|
|
390
|
-
var RideAlongSchema =
|
|
379
|
+
var RideAlongSchema = z3.object({
|
|
391
380
|
/** The note this came from — assign/clarify/close it through /api/notes/:id. */
|
|
392
|
-
noteId:
|
|
381
|
+
noteId: z3.string(),
|
|
393
382
|
/** What to do, in the owner's own words (the note's headline). Never model-rewritten. */
|
|
394
|
-
text:
|
|
383
|
+
text: z3.string(),
|
|
395
384
|
/** The thread to report back on, when the note was dispatched over the request rail. */
|
|
396
|
-
parentId:
|
|
397
|
-
});
|
|
398
|
-
var AwaitItemSchema =
|
|
399
|
-
|
|
400
|
-
type:
|
|
401
|
-
parentId:
|
|
402
|
-
notificationId:
|
|
403
|
-
workId:
|
|
404
|
-
decisionId:
|
|
385
|
+
parentId: z3.string().nullable()
|
|
386
|
+
});
|
|
387
|
+
var AwaitItemSchema = z3.discriminatedUnion("type", [
|
|
388
|
+
z3.object({
|
|
389
|
+
type: z3.literal("reply"),
|
|
390
|
+
parentId: z3.string(),
|
|
391
|
+
notificationId: z3.string(),
|
|
392
|
+
workId: z3.string().uuid().optional(),
|
|
393
|
+
decisionId: z3.string().uuid().optional(),
|
|
405
394
|
answer: UserAnswerSchema,
|
|
406
395
|
/** E2EE: present when the answer is sealed. The server relays the opaque answer
|
|
407
396
|
* envelope + the plaintext `ignored` status hint; the receiving agent OPENS it
|
|
@@ -409,7 +398,7 @@ var AwaitItemSchema = z2.discriminatedUnion("type", [
|
|
|
409
398
|
* against `ignored` as tampering. Absent = today's plaintext answer (in `answer`).
|
|
410
399
|
* On a sealed reply the plaintext `answer` is a placeholder (kind reflects only
|
|
411
400
|
* the `ignored` bit) — never the real content, which stays sealed. */
|
|
412
|
-
sealed:
|
|
401
|
+
sealed: z3.lazy(() => SealedAnswerSchema).optional(),
|
|
413
402
|
/** WHAT THE AGENT CANNOT KNOW FROM THE FIELDS BESIDE IT (owner, 2026-09-04, issue
|
|
414
403
|
* #1537). One line, built from the record: the ask and the caller's reply VERBATIM,
|
|
415
404
|
* the notification they belong to, and the `contact` call that reaches the person
|
|
@@ -418,147 +407,147 @@ var AwaitItemSchema = z2.discriminatedUnion("type", [
|
|
|
418
407
|
* "call me back after you merge" in their own words decides for itself what to do,
|
|
419
408
|
* and now knows exactly which call to make. Absent when either half is missing —
|
|
420
409
|
* a sentence with a hole in it is worse than no sentence. */
|
|
421
|
-
note:
|
|
410
|
+
note: z3.string().optional(),
|
|
422
411
|
/** The call record rendered for THIS agent (`voice/record-design.md`): the words the
|
|
423
412
|
* shaped answer was mapped from, filtered to its own claims. There is no second list
|
|
424
413
|
* of labels beside it — the acts went 2026-09-04 and `intents` went with them (owner,
|
|
425
414
|
* 2026-09-04): the agent reads the sentence and decides. */
|
|
426
|
-
transcript:
|
|
415
|
+
transcript: z3.string().optional(),
|
|
427
416
|
/** Coverage report (#396), when the ask declared `points`: which of them this
|
|
428
417
|
* answer addressed. Missing points = re-ask or proceed knowingly partial. */
|
|
429
|
-
covered:
|
|
418
|
+
covered: z3.array(z3.string()).optional(),
|
|
430
419
|
/** Ride-alongs (RideAlongSchema) — pending work for you, attached to the moment you
|
|
431
420
|
* became free. Only `reply` and `idle` carry it: those are the two outcomes that
|
|
432
421
|
* END a wait. `remind`, `superseded` and `turn` are mid-flight, and handing an
|
|
433
422
|
* agent a side-quest while it is still holding the line is how the main thing gets
|
|
434
423
|
* dropped. Absent/empty = nothing owed. */
|
|
435
|
-
also:
|
|
424
|
+
also: z3.array(RideAlongSchema).optional()
|
|
436
425
|
}),
|
|
437
|
-
|
|
438
|
-
type:
|
|
439
|
-
parentId:
|
|
440
|
-
notificationId:
|
|
441
|
-
remindAt:
|
|
426
|
+
z3.object({
|
|
427
|
+
type: z3.literal("remind"),
|
|
428
|
+
parentId: z3.string(),
|
|
429
|
+
notificationId: z3.string(),
|
|
430
|
+
remindAt: z3.string().datetime({ offset: true }),
|
|
442
431
|
/** Seconds until remindAt, server-computed — pass straight to ScheduleWakeup. */
|
|
443
|
-
remindInSeconds:
|
|
432
|
+
remindInSeconds: z3.number()
|
|
444
433
|
}),
|
|
445
434
|
/** The awaited ask was REPLACED by a newer notification on its thread (e.g. a
|
|
446
435
|
* post-feedback revision, #633) — the user will never answer this id. Stop
|
|
447
436
|
* awaiting it; the live ask is the thread's newest turn (await that one, or
|
|
448
437
|
* re-orient via get_thread / check_replies). */
|
|
449
|
-
|
|
450
|
-
type:
|
|
451
|
-
parentId:
|
|
452
|
-
notificationId:
|
|
438
|
+
z3.object({
|
|
439
|
+
type: z3.literal("superseded"),
|
|
440
|
+
parentId: z3.string(),
|
|
441
|
+
notificationId: z3.string()
|
|
453
442
|
}),
|
|
454
443
|
/** A LIVE call's turn, streamed as it lands (#783). PROVISIONAL: the user can still
|
|
455
444
|
* revise any of these until the final reply arrives — partial = intelligence,
|
|
456
445
|
* settled = authorization. Use it to PREPARE (fetch, draft, warm), never to act
|
|
457
446
|
* irreversibly. If `acts` carries a question aimed at you and you know the answer,
|
|
458
447
|
* contact on the same thread right away — the caller hears it on the same call. */
|
|
459
|
-
|
|
460
|
-
type:
|
|
461
|
-
notificationId:
|
|
462
|
-
inFlight:
|
|
463
|
-
turn:
|
|
464
|
-
idx:
|
|
465
|
-
prompt:
|
|
466
|
-
reply:
|
|
467
|
-
acts:
|
|
448
|
+
z3.object({
|
|
449
|
+
type: z3.literal("partial"),
|
|
450
|
+
notificationId: z3.string(),
|
|
451
|
+
inFlight: z3.literal(true),
|
|
452
|
+
turn: z3.object({
|
|
453
|
+
idx: z3.number(),
|
|
454
|
+
prompt: z3.string(),
|
|
455
|
+
reply: z3.string(),
|
|
456
|
+
acts: z3.array(IntentSchema).nullable().optional()
|
|
468
457
|
})
|
|
469
458
|
}),
|
|
470
|
-
|
|
471
|
-
type:
|
|
472
|
-
also:
|
|
459
|
+
z3.object({
|
|
460
|
+
type: z3.literal("idle"),
|
|
461
|
+
also: z3.array(RideAlongSchema).optional(),
|
|
473
462
|
/** Is a call live for this agent's user right now? The SDK polls the partial stream
|
|
474
463
|
* (#783) between idle ticks ONLY while this is not `false` — a partial can only exist
|
|
475
464
|
* during a live call, and polling for one on a banner/message was a wasted HTTP call +
|
|
476
465
|
* 3 queries on every idle tick of every waiting agent (~80% of all traffic at scale).
|
|
477
466
|
* Absent = an older API → the SDK keeps polling, exactly as before. */
|
|
478
|
-
inFlight:
|
|
467
|
+
inFlight: z3.boolean().optional()
|
|
479
468
|
})
|
|
480
469
|
]);
|
|
481
|
-
var CallbackTriggerSchema =
|
|
482
|
-
var ScheduleCallbackSchema =
|
|
483
|
-
parentId:
|
|
484
|
-
goalId:
|
|
470
|
+
var CallbackTriggerSchema = z3.enum(["on_done", "on_blocked", "scheduled"]);
|
|
471
|
+
var ScheduleCallbackSchema = z3.object({
|
|
472
|
+
parentId: z3.string().describe("The thread to call back on (from a prior contact / reply / request)."),
|
|
473
|
+
goalId: z3.string().uuid().optional().describe("The Goal this callback advances; preferred for Goal-owned work."),
|
|
485
474
|
trigger: CallbackTriggerSchema,
|
|
486
|
-
dueInSeconds:
|
|
487
|
-
note:
|
|
488
|
-
});
|
|
489
|
-
var PendingRepliesSchema =
|
|
490
|
-
replies:
|
|
491
|
-
|
|
492
|
-
parentId:
|
|
493
|
-
notificationId:
|
|
494
|
-
workId:
|
|
495
|
-
decisionId:
|
|
475
|
+
dueInSeconds: z3.number().int().positive().optional().describe("For 'scheduled' only: how many seconds from now to fire."),
|
|
476
|
+
note: z3.string().optional().describe("What to tell the user when you follow up.")
|
|
477
|
+
});
|
|
478
|
+
var PendingRepliesSchema = z3.object({
|
|
479
|
+
replies: z3.array(
|
|
480
|
+
z3.object({
|
|
481
|
+
parentId: z3.string(),
|
|
482
|
+
notificationId: z3.string(),
|
|
483
|
+
workId: z3.string().uuid().optional(),
|
|
484
|
+
decisionId: z3.string().uuid().optional(),
|
|
496
485
|
answer: UserAnswerSchema,
|
|
497
486
|
/** E2EE: the sealed answer (opaque envelope + plaintext `ignored` hint) when the
|
|
498
487
|
* pairing is E2EE — the agent opens it and re-derives the real answer. Absent =
|
|
499
488
|
* plaintext answer (in `answer`). See AwaitItemSchema's reply variant. */
|
|
500
|
-
sealed:
|
|
489
|
+
sealed: z3.lazy(() => SealedAnswerSchema).optional(),
|
|
501
490
|
/** The call record rendered for THIS agent: the raw words the shaped answer was
|
|
502
491
|
* mapped from, filtered to its own claims. See AwaitItemSchema's reply variant. */
|
|
503
|
-
transcript:
|
|
492
|
+
transcript: z3.string().optional(),
|
|
504
493
|
/** Coverage report (#396): which declared `points` this answer addressed. */
|
|
505
|
-
covered:
|
|
494
|
+
covered: z3.array(z3.string()).optional()
|
|
506
495
|
})
|
|
507
496
|
),
|
|
508
|
-
pending:
|
|
509
|
-
|
|
497
|
+
pending: z3.array(
|
|
498
|
+
z3.object({ parentId: z3.string(), notificationId: z3.string(), createdAt: z3.string() })
|
|
510
499
|
),
|
|
511
500
|
/** WHO YOU ARE on this account (field report 2026-08-28): the name and device the user
|
|
512
501
|
* sees for this session's identity. From inside a session there was no way to find out —
|
|
513
502
|
* `pair` with no arguments can HATCH a fresh identity, so it is not a safe probe — and an
|
|
514
503
|
* agent that cannot tell which agent it is cannot tell whether work addressed to
|
|
515
504
|
* "Reta" was addressed to it. Absent only for a token with no pairing behind it. */
|
|
516
|
-
you:
|
|
505
|
+
you: z3.object({ name: z3.string(), device: z3.string().nullable(), tokenId: z3.string() }).optional(),
|
|
517
506
|
/** User-initiated requests addressed to this agent; act on them and reply via
|
|
518
507
|
* contact on the same parentId. Keeps reappearing until you call
|
|
519
508
|
* set_work_state on its workId (or notificationId once while bootstrapping). */
|
|
520
|
-
requests:
|
|
521
|
-
|
|
522
|
-
parentId:
|
|
523
|
-
notificationId:
|
|
524
|
-
workId:
|
|
525
|
-
text:
|
|
526
|
-
createdAt:
|
|
509
|
+
requests: z3.array(
|
|
510
|
+
z3.object({
|
|
511
|
+
parentId: z3.string(),
|
|
512
|
+
notificationId: z3.string(),
|
|
513
|
+
workId: z3.string().uuid().optional(),
|
|
514
|
+
text: z3.string(),
|
|
515
|
+
createdAt: z3.string(),
|
|
527
516
|
/** The user seeded this request with a past conversation — call get_thread on it
|
|
528
517
|
* FIRST and treat the transcript as prior context (#57/#251). */
|
|
529
|
-
contextParentId:
|
|
518
|
+
contextParentId: z3.string().optional(),
|
|
530
519
|
/** STRANDED (field report 2026-08-28): this request was addressed to ANOTHER agent on
|
|
531
520
|
* the account — the name here — which has not been seen since it landed, so nobody
|
|
532
521
|
* came for it. Handed to you because you are the session that is here. Take it like
|
|
533
522
|
* any request (set_work_state claims it, reply with contact on its parentId), and say
|
|
534
523
|
* whose it was, because the user chose that agent on purpose. */
|
|
535
|
-
stranded:
|
|
524
|
+
stranded: z3.string().optional()
|
|
536
525
|
})
|
|
537
526
|
),
|
|
538
527
|
/** Durable outcomes currently owned by this agent. This is the Work-native queue; flat
|
|
539
528
|
* notification lists remain during migration so old clients keep their existing view. */
|
|
540
|
-
work:
|
|
541
|
-
workId:
|
|
542
|
-
parentId:
|
|
543
|
-
objective:
|
|
544
|
-
state:
|
|
545
|
-
blockedOn:
|
|
546
|
-
updatedAt:
|
|
529
|
+
work: z3.array(z3.object({
|
|
530
|
+
workId: z3.string().uuid(),
|
|
531
|
+
parentId: z3.string().optional(),
|
|
532
|
+
objective: z3.string().nullable(),
|
|
533
|
+
state: z3.enum(["active", "blocked", "waiting_external"]),
|
|
534
|
+
blockedOn: z3.array(z3.string().uuid()),
|
|
535
|
+
updatedAt: z3.string()
|
|
547
536
|
})).optional(),
|
|
548
537
|
/** Callbacks you owe the user that are now DUE (you said you'd follow up when done,
|
|
549
538
|
* if blocked, or at a time that has passed). Re-surfaced every sweep until you
|
|
550
539
|
* fulfill one by calling contact on its parentId. */
|
|
551
540
|
/** Ride-alongs (RideAlongSchema): notes assigned to this agent that no wake could
|
|
552
541
|
* reach. Same array the contact/await replies carry — one queue, every carrier. */
|
|
553
|
-
also:
|
|
554
|
-
owedCallbacks:
|
|
555
|
-
|
|
542
|
+
also: z3.array(RideAlongSchema).optional(),
|
|
543
|
+
owedCallbacks: z3.array(
|
|
544
|
+
z3.object({ parentId: z3.string(), trigger: CallbackTriggerSchema, note: z3.string() })
|
|
556
545
|
),
|
|
557
546
|
/** Work (either direction) you reported in_progress a while ago and never reported
|
|
558
547
|
* completed — likely left half-done by this session or a prior one that crashed or
|
|
559
548
|
* went idle. Report a real state (set_work_state) or continue the work. */
|
|
560
|
-
stalled:
|
|
561
|
-
|
|
549
|
+
stalled: z3.array(
|
|
550
|
+
z3.object({ parentId: z3.string(), notificationId: z3.string(), title: z3.string().nullable(), startedAt: z3.string() })
|
|
562
551
|
),
|
|
563
552
|
/** The queue rail (#614, pending/design.md): the same replies + requests, grouped by
|
|
564
553
|
* thread and ordered oldest-thread-first, so you work ONE thread at a time — fold all of
|
|
@@ -567,125 +556,132 @@ var PendingRepliesSchema = z2.object({
|
|
|
567
556
|
* ride the next turn. `items` are that thread's replies/requests in arrival order; the
|
|
568
557
|
* full payload for each is in the flat `replies`/`requests` arrays (matched by
|
|
569
558
|
* notificationId). Derived, never stored — a crashed agent recomputes it exactly. */
|
|
570
|
-
threads:
|
|
571
|
-
|
|
572
|
-
parentId:
|
|
573
|
-
busy:
|
|
574
|
-
items:
|
|
575
|
-
|
|
576
|
-
kind:
|
|
577
|
-
notificationId:
|
|
578
|
-
at:
|
|
559
|
+
threads: z3.array(
|
|
560
|
+
z3.object({
|
|
561
|
+
parentId: z3.string(),
|
|
562
|
+
busy: z3.boolean(),
|
|
563
|
+
items: z3.array(
|
|
564
|
+
z3.object({
|
|
565
|
+
kind: z3.enum(["reply", "request"]),
|
|
566
|
+
notificationId: z3.string(),
|
|
567
|
+
at: z3.string()
|
|
579
568
|
})
|
|
580
569
|
)
|
|
581
570
|
})
|
|
582
571
|
)
|
|
583
572
|
});
|
|
584
|
-
var NotifyResponseSchema =
|
|
585
|
-
notificationId:
|
|
586
|
-
workId:
|
|
587
|
-
decisionId:
|
|
573
|
+
var NotifyResponseSchema = z3.object({
|
|
574
|
+
notificationId: z3.string(),
|
|
575
|
+
workId: z3.string().uuid().optional(),
|
|
576
|
+
decisionId: z3.string().uuid().optional(),
|
|
588
577
|
status: NotifyStatusSchema,
|
|
589
|
-
createdAt:
|
|
578
|
+
createdAt: z3.string().datetime(),
|
|
590
579
|
answer: UserAnswerSchema.optional(),
|
|
591
|
-
answeredAt:
|
|
580
|
+
answeredAt: z3.string().datetime().optional(),
|
|
592
581
|
/** Ride-alongs for THIS agent — pending work it should pick up when it's done with
|
|
593
582
|
* what it came for. Present on any reply, because an unwakeable agent's only
|
|
594
583
|
* reliable moment is one it initiated. Absent/empty = nothing owed. */
|
|
595
|
-
also:
|
|
584
|
+
also: z3.array(RideAlongSchema).optional()
|
|
596
585
|
});
|
|
597
|
-
var NotifyPlanUnitSchema =
|
|
598
|
-
notificationId:
|
|
586
|
+
var NotifyPlanUnitSchema = z3.object({
|
|
587
|
+
notificationId: z3.string(),
|
|
599
588
|
/** The unit's own heading, so the agent can tell which of its paragraphs this became. */
|
|
600
|
-
title:
|
|
589
|
+
title: z3.string(),
|
|
601
590
|
/** How loudly this unit was arbitrated to arrive — per unit, which is the point of units. */
|
|
602
591
|
level: NotifyLevelSchema,
|
|
603
592
|
/** Answered from something the user already decided: nobody is interrupted, and a trail card
|
|
604
593
|
* says so. The agent should not wait on this one. */
|
|
605
|
-
settled:
|
|
594
|
+
settled: z3.literal(true).optional(),
|
|
606
595
|
/** What this unit would need to be answerable and does not carry (#894). A PROPOSAL to the
|
|
607
596
|
* agent — nothing here changed the ask, and ignoring it costs nothing. */
|
|
608
|
-
needs:
|
|
597
|
+
needs: z3.array(z3.enum(["options", "visuals"])).optional(),
|
|
609
598
|
/** The SHAPE the broker would give this unit, for the agent to ratify (#886/#894). The
|
|
610
599
|
* split layer reads prose and can see that a paragraph is a yes/no or a pick-one — but a
|
|
611
600
|
* broker that DECIDES that destroys the only fact separating a statement from a real ask
|
|
612
601
|
* (#731), so it is offered, never applied: the unit is stored `text` until the agent
|
|
613
602
|
* confirms the shape (POST /notify/:id/confirm). Ignoring it costs nothing. */
|
|
614
|
-
proposal:
|
|
603
|
+
proposal: z3.object({
|
|
615
604
|
select: SelectShapeSchema,
|
|
616
|
-
options:
|
|
605
|
+
options: z3.array(z3.object({ label: z3.string().min(1) })).optional()
|
|
617
606
|
}).optional(),
|
|
618
607
|
/** What the broker READ this unit as wanting from the human (#952 layer 2): a `decision`
|
|
619
608
|
* between alternatives, an `approval` the agent is blocked on, or `knowledge` it just
|
|
620
609
|
* needs to know. Reported so the agent can correct a misread the same way it ratifies a
|
|
621
610
|
* shape — the read RAISES (a decision always asks) and never silences a question the
|
|
622
611
|
* agent declared (#731, #923). */
|
|
623
|
-
wants:
|
|
612
|
+
wants: z3.enum(["decision", "approval", "knowledge"]).optional()
|
|
624
613
|
});
|
|
625
|
-
var NotifyPlanSchema =
|
|
626
|
-
units:
|
|
614
|
+
var NotifyPlanSchema = z3.object({
|
|
615
|
+
units: z3.array(NotifyPlanUnitSchema),
|
|
627
616
|
/** Which unit is this arrival's ONE interruption (units-design.md D23). Absent means nobody
|
|
628
617
|
* was interrupted — every unit was either settled or quiet enough to sit in the inbox. */
|
|
629
|
-
speaks:
|
|
618
|
+
speaks: z3.string().optional()
|
|
630
619
|
});
|
|
631
|
-
var UserResponseSchema =
|
|
632
|
-
requestId:
|
|
620
|
+
var UserResponseSchema = z3.object({
|
|
621
|
+
requestId: z3.string(),
|
|
633
622
|
answer: UserAnswerSchema,
|
|
634
|
-
answeredAt:
|
|
635
|
-
transcript:
|
|
623
|
+
answeredAt: z3.string().datetime(),
|
|
624
|
+
transcript: z3.string().optional(),
|
|
636
625
|
/** E2EE: the sealed answer (opaque envelope + plaintext `ignored` hint) when the item was
|
|
637
626
|
* E2EE-sealed. Present → the server persists it opaquely and branches status on `ignored`;
|
|
638
627
|
* the plaintext `answer` is a placeholder (`{ kind: "ignored" }`) the server ignores for a
|
|
639
628
|
* sealed row. Absent = today's plaintext answer, unchanged. */
|
|
640
|
-
sealed:
|
|
629
|
+
sealed: z3.lazy(() => SealedAnswerSchema).optional(),
|
|
641
630
|
/** Coverage report (#396): which of the ask's declared `points` were addressed. */
|
|
642
|
-
covered:
|
|
643
|
-
});
|
|
644
|
-
var VoiceKeySchema =
|
|
645
|
-
var AgendaTurnSchema =
|
|
631
|
+
covered: z3.array(z3.string()).optional()
|
|
632
|
+
});
|
|
633
|
+
var VoiceKeySchema = z3.enum(["rachel", "george", "jessica", "brian", "lily"]);
|
|
634
|
+
var AgendaTurnSchema = z3.object({
|
|
635
|
+
/** THE TURN'S IDENTITY (the first-sentence stream, 2026-09-09): the brain call that wrote
|
|
636
|
+
* it and its place in that reply — `<brainCallId>:<index>`, with `:p` on the first
|
|
637
|
+
* sentence a re-plan publishes ahead of the rest. A turn is spoken once, by this id: the
|
|
638
|
+
* completion of a streamed re-plan carries the published sentence again, and the walk
|
|
639
|
+
* drops what it already said by identity, never by the API's guess of what was polled.
|
|
640
|
+
* Absent on plans nothing streams (a ring plan, a floor). */
|
|
641
|
+
id: z3.string().optional(),
|
|
646
642
|
/** Twin coverage (#1089): sibling claim ids this asking turn's answer ALSO settles —
|
|
647
643
|
* the planner declares duplicates instead of asking them twice. */
|
|
648
|
-
coveredIds:
|
|
644
|
+
coveredIds: z3.array(z3.string()).optional(),
|
|
649
645
|
/** At most three short spoken sentences. Capped because a turn is a breath: a 1031-char
|
|
650
646
|
* line went out on 2026-07-28 and the caller could not answer it at all. */
|
|
651
|
-
info:
|
|
652
|
-
question:
|
|
647
|
+
info: z3.array(z3.string().min(1)).max(3).default([]),
|
|
648
|
+
question: z3.string().min(1).nullable(),
|
|
653
649
|
/** True on the one turn carrying the agent's own declared question. */
|
|
654
|
-
asks:
|
|
650
|
+
asks: z3.boolean().optional(),
|
|
655
651
|
/** The claim this turn belongs to (#781) — the RETURN identity: answers route by it.
|
|
656
652
|
* Absent on a single-claim plan (the session's own claim) and on shared context turns,
|
|
657
653
|
* which route nothing. */
|
|
658
|
-
claimId:
|
|
654
|
+
claimId: z3.string().optional(),
|
|
659
655
|
/** The claim's voice key (#462) — the OUTBOUND identity, audible who-is-asking. */
|
|
660
|
-
voice:
|
|
656
|
+
voice: z3.string().optional(),
|
|
661
657
|
/** The claim's AGENT NAME (#838) — the spoken identity. A voice alone doesn't say
|
|
662
658
|
* whose request this is: an item that folded in from another agent arrived as a bare
|
|
663
659
|
* non-sequitur ("First real production sign-in is yours to make whenever you want.")
|
|
664
660
|
* and the owner answered "What?". The bot names the agent before its first turn. */
|
|
665
|
-
agent:
|
|
661
|
+
agent: z3.string().optional(),
|
|
666
662
|
/** The claim's agent by ID — the pairing's connection id (`notifications.token_id`), the
|
|
667
663
|
* same id a face is minted from. A name is not an identity: two pairings may be called
|
|
668
664
|
* "Claude", and a name cannot be joined on. The record's entries carry it (`agent_id`)
|
|
669
665
|
* so "who said that" survives the call, and it rides PER TURN because a coalesced call
|
|
670
666
|
* speaks for several agents — the turn is the only place that knows which. */
|
|
671
|
-
agentId:
|
|
667
|
+
agentId: z3.string().optional(),
|
|
672
668
|
select: SelectShapeSchema.optional(),
|
|
673
|
-
options:
|
|
669
|
+
options: z3.array(OptionSchema.omit({ id: true })).optional(),
|
|
674
670
|
/** Pacing (#826, owner 2026-08-03: "how fast we move through them ... are parameters"):
|
|
675
671
|
* seconds the floor stays open after this turn speaks. Absent = the bot's defaults
|
|
676
672
|
* (the beat for context, the answer window for asks). Clamped bot-side. */
|
|
677
|
-
pace:
|
|
673
|
+
pace: z3.number().positive().optional(),
|
|
678
674
|
/** Whether the walk WAITS for an answer before moving on. Absent = derived as today
|
|
679
675
|
* (a question blocks, context flows). blocking:false on a question = ask and move
|
|
680
676
|
* on, the claim stays pending; blocking:true on context = hold for a reply. */
|
|
681
|
-
blocking:
|
|
677
|
+
blocking: z3.boolean().optional()
|
|
682
678
|
});
|
|
683
679
|
var CLAIM_STALE_MS = 30 * 6e4;
|
|
684
|
-
var InboxItemSchema =
|
|
685
|
-
id:
|
|
680
|
+
var InboxItemSchema = z3.object({
|
|
681
|
+
id: z3.string(),
|
|
686
682
|
/** The conversation thread + connection this item lives on. Present on the replied
|
|
687
683
|
* detail — they power History's "Continue" / "New session from this" (#57/#251). */
|
|
688
|
-
parentId:
|
|
684
|
+
parentId: z3.string().optional(),
|
|
689
685
|
/** THE ARRIVAL this row is one unit of (`notifications.ask_id` → `asks`). A claim is one
|
|
690
686
|
* arrival and its units are N rows of it, so this — not `parentId` — is what makes a
|
|
691
687
|
* multi-part notification one thing on screen. The thread is the whole CONVERSATION: it
|
|
@@ -693,13 +689,13 @@ var InboxItemSchema = z2.object({
|
|
|
693
689
|
* unrelated updates as a single "12-part request". Absent on rows written before the
|
|
694
690
|
* `asks` table, and on anything that never went through `notify` — both fall back to the
|
|
695
691
|
* thread, which is what the client did for all rows until now. */
|
|
696
|
-
askId:
|
|
692
|
+
askId: z3.string().optional(),
|
|
697
693
|
/** WHERE this unit sat in the message it was cut from (`notifications.seq`). The batch
|
|
698
694
|
* shares one `created_at` to the microsecond, so without it the author's order is
|
|
699
695
|
* unrecoverable client-side — a four-paragraph briefing rendered opening-paragraph-last
|
|
700
696
|
* (live 2026-08-10, D35). The API already orders by it; this lets a reader that
|
|
701
697
|
* re-sorts (grouping, filtering) put an arrival back in the order it was written. */
|
|
702
|
-
seq:
|
|
698
|
+
seq: z3.number().int().optional(),
|
|
703
699
|
/** HOW MANY units the arrival was cut into. A device reads a LENS, never the arrival —
|
|
704
700
|
* `/api/inbox` serves `open`, so the units already settled are gone from it — and a client
|
|
705
701
|
* counting what it can see is counting what is LEFT. Walking a three-unit ask on the answer
|
|
@@ -708,13 +704,13 @@ var InboxItemSchema = z2.object({
|
|
|
708
704
|
* server that can still see every row states it. Absent on any row with no `askId`: a
|
|
709
705
|
* unit knows WHICH ask it came from and WHERE it sat in it, and how many there were is
|
|
710
706
|
* the one part of its own arrival a single row cannot answer. */
|
|
711
|
-
units:
|
|
712
|
-
tokenId:
|
|
707
|
+
units: z3.number().int().positive().optional(),
|
|
708
|
+
tokenId: z3.string().optional(),
|
|
713
709
|
status: NotifyStatusSchema,
|
|
714
710
|
context: ContextSchema,
|
|
715
|
-
options:
|
|
711
|
+
options: z3.array(OptionSchema).optional(),
|
|
716
712
|
/** The ask's declared coverage points (#396), when the agent sent them. */
|
|
717
|
-
points:
|
|
713
|
+
points: z3.array(z3.string()).optional(),
|
|
718
714
|
/** The call's AGENDA (broker/agenda-design.md): the ordered turns it is made of, built at
|
|
719
715
|
* ring/enqueue time. Replaces the condensed line + index-aligned phrased points, which
|
|
720
716
|
* between them could not express a call as a sequence. `question: null` is a real turn —
|
|
@@ -723,12 +719,12 @@ var InboxItemSchema = z2.object({
|
|
|
723
719
|
* `requestAsks` — the agent's own declaration, not a guess. `false` is what earns a card
|
|
724
720
|
* its acknowledge affordance: without it a status update offers a text box and a dismiss,
|
|
725
721
|
* and neither of those is "got it" (owner, 2026-08-10). */
|
|
726
|
-
asks:
|
|
722
|
+
asks: z3.boolean().optional(),
|
|
727
723
|
/** When a live process last pulsed for this row's agent — the liveness input for
|
|
728
724
|
* "working requires a pulse" (#928): the list said "Working…" from agent_state alone
|
|
729
725
|
* while the party called the same dead claim stalled. Absent = no token/no data,
|
|
730
726
|
* which must never CLAIM stalled. */
|
|
731
|
-
lastSeenAt:
|
|
727
|
+
lastSeenAt: z3.string().optional(),
|
|
732
728
|
/** WHEN THE AGENT LAST SAID ANYTHING ABOUT THIS CLAIM — the newest `agent_state` row in
|
|
733
729
|
* the `notification_events` ledger (trigger-written since 20260621010000, so every row a
|
|
734
730
|
* user can see has one). The age input for `CLAIM_STALE_MS`, and it has to be this rather
|
|
@@ -738,53 +734,53 @@ var InboxItemSchema = z2.object({
|
|
|
738
734
|
* work. Reading the row's birth as the claim's age brands that "No update in 8h" the
|
|
739
735
|
* instant the agent picks it up (#997). Absent = pre-trigger row; fall back to
|
|
740
736
|
* `createdAt`. */
|
|
741
|
-
agentStateAt:
|
|
742
|
-
agenda:
|
|
743
|
-
visuals:
|
|
737
|
+
agentStateAt: z3.string().datetime().optional(),
|
|
738
|
+
agenda: z3.array(AgendaTurnSchema).optional(),
|
|
739
|
+
visuals: z3.array(VisualSchema).optional(),
|
|
744
740
|
/** The connected agent's name (the single pairing name — user-typed, or the
|
|
745
741
|
* agent's suggestion, or a default silly name). */
|
|
746
|
-
name:
|
|
742
|
+
name: z3.string(),
|
|
747
743
|
/** The pairing's assigned voice (#462); absent = the default voice. */
|
|
748
744
|
voice: VoiceKeySchema.optional(),
|
|
749
|
-
repo:
|
|
750
|
-
branch:
|
|
751
|
-
createdAt:
|
|
752
|
-
snoozedUntil:
|
|
745
|
+
repo: z3.string().optional(),
|
|
746
|
+
branch: z3.string().optional(),
|
|
747
|
+
createdAt: z3.string().datetime(),
|
|
748
|
+
snoozedUntil: z3.string().datetime().optional(),
|
|
753
749
|
agentState: AgentStateSchema.default("idle"),
|
|
754
750
|
/** Whose action the item is waiting on: "you" = an agent asked you (the default,
|
|
755
751
|
* every agent→user notification); "agent" = you sent a request and it's awaiting the
|
|
756
752
|
* agent (held in the inbox until the agent replies on the thread). */
|
|
757
|
-
turn:
|
|
753
|
+
turn: z3.enum(["you", "agent"]).default("you"),
|
|
758
754
|
/** Hard error reason on an awaiting request (turn="agent") — the wake failed to reach
|
|
759
755
|
* the agent (provider-agnostic; set server-side). Absent = no hard error, though the
|
|
760
756
|
* client may still flag a stall by age. Drives the inbox error badge + Retry. */
|
|
761
|
-
error:
|
|
762
|
-
clarifies:
|
|
757
|
+
error: z3.string().optional(),
|
|
758
|
+
clarifies: z3.string().optional(),
|
|
763
759
|
/** The ring ladder ran out while this was still pending — we tried to reach you and
|
|
764
760
|
* STOPPED trying (`arbitration/arbitrate.ts` `nextRing` → `stop`). Distinct from an
|
|
765
761
|
* agent with nothing to say, which the roster drew identically until now: "nothing to
|
|
766
762
|
* say" and "gave up saying it" are opposite situations wearing the same face
|
|
767
763
|
* (navigation-design.md, gap 1). False for anything that never rang. */
|
|
768
|
-
gaveUp:
|
|
764
|
+
gaveUp: z3.boolean().default(false),
|
|
769
765
|
/** Why this arrived the way it did, read back off the delivery receipt (`notify/why.ts`).
|
|
770
766
|
* Absent for anything never delivered through a push, and for older rows written before
|
|
771
767
|
* the reason was recorded. Deliberately a debug affordance, shown small (owner,
|
|
772
768
|
* 2026-08-07) — its real job is to give "this didn't need a call" something to be
|
|
773
769
|
* feedback ABOUT. */
|
|
774
|
-
why:
|
|
770
|
+
why: z3.object({
|
|
775
771
|
asked: NotifyLevelSchema,
|
|
776
772
|
got: NotifyLevelSchema,
|
|
777
|
-
because:
|
|
778
|
-
line:
|
|
773
|
+
because: z3.enum(["unresponsive", "dismissed", "not_permitted", "silent", "coalesced", "agent_capped", "unplanned", "learned_raise"]).optional(),
|
|
774
|
+
line: z3.string()
|
|
779
775
|
}).optional(),
|
|
780
|
-
select:
|
|
781
|
-
confirmStyle:
|
|
776
|
+
select: z3.enum(["one", "many", "rank", "confirm", "text"]).default("one"),
|
|
777
|
+
confirmStyle: z3.enum(["yesno", "approve"]).default("yesno").describe(
|
|
782
778
|
"Labels for a select:'confirm' paige \u2014 'yesno' (Yes/No) or 'approve' (Approve/Deny). Ignored unless select is 'confirm'."
|
|
783
779
|
),
|
|
784
780
|
/** Real downstream work is stuck behind this one — set by the agent, independent of
|
|
785
781
|
* urgency (see the main README's "premier use case" + notify/states.md). Drives the
|
|
786
782
|
* inbox's blocking badge and the extra confirm step before dismissing it. */
|
|
787
|
-
blocking:
|
|
783
|
+
blocking: z3.boolean().default(false),
|
|
788
784
|
/** The user's locked-in answer; present only for replied items (GET /api/replied/:id). */
|
|
789
785
|
answer: UserAnswerSchema.optional(),
|
|
790
786
|
/** E2EE (text lane): the sealed content this item carries when the pairing is E2EE, in
|
|
@@ -793,39 +789,39 @@ var InboxItemSchema = z2.object({
|
|
|
793
789
|
* NotifyRequest.envelope. The native app decrypts it locally via openNotification;
|
|
794
790
|
* web / an un-enrolled device can't and renders a locked placeholder. Absent = today's
|
|
795
791
|
* plaintext item (context carries the cleartext), so plaintext items are unchanged. */
|
|
796
|
-
envelope:
|
|
797
|
-
context:
|
|
798
|
-
options:
|
|
799
|
-
visuals:
|
|
792
|
+
envelope: z3.object({
|
|
793
|
+
context: z3.lazy(() => EnvelopeSchema).optional(),
|
|
794
|
+
options: z3.lazy(() => EnvelopeSchema).optional(),
|
|
795
|
+
visuals: z3.lazy(() => EnvelopeSchema).optional()
|
|
800
796
|
}).optional(),
|
|
801
797
|
/** E2EE: the agent's device X25519 public key to seal the user's answer BACK to (the
|
|
802
798
|
* sender the phone replies to). Sourced server-side from this item's pairing credential.
|
|
803
799
|
* Present only alongside `envelope`; the phone seals via sealAnswer(answer, this, id). */
|
|
804
|
-
agentX25519:
|
|
800
|
+
agentX25519: z3.string().optional()
|
|
805
801
|
});
|
|
806
|
-
var SnoozeRequestSchema =
|
|
807
|
-
requestId:
|
|
808
|
-
until:
|
|
802
|
+
var SnoozeRequestSchema = z3.object({
|
|
803
|
+
requestId: z3.string(),
|
|
804
|
+
until: z3.string().datetime()
|
|
809
805
|
});
|
|
810
806
|
var APNS_TOKEN_RE = /^[0-9a-fA-F]{64}$/;
|
|
811
|
-
var PushTokenSchema =
|
|
812
|
-
voipToken:
|
|
813
|
-
alertToken:
|
|
814
|
-
fcmToken:
|
|
815
|
-
platform:
|
|
807
|
+
var PushTokenSchema = z3.object({
|
|
808
|
+
voipToken: z3.string().min(1).optional(),
|
|
809
|
+
alertToken: z3.string().min(1).optional(),
|
|
810
|
+
fcmToken: z3.string().min(1).optional(),
|
|
811
|
+
platform: z3.enum(["ios", "android"])
|
|
816
812
|
}).superRefine((v, ctx) => {
|
|
817
813
|
if (v.platform !== "ios") return;
|
|
818
814
|
for (const field of ["voipToken", "alertToken"]) {
|
|
819
815
|
const token = v[field];
|
|
820
816
|
if (token === void 0 || APNS_TOKEN_RE.test(token)) continue;
|
|
821
817
|
ctx.addIssue({
|
|
822
|
-
code:
|
|
818
|
+
code: z3.ZodIssueCode.custom,
|
|
823
819
|
path: [field],
|
|
824
820
|
message: `not an APNs device token (want 64 hex chars, got ${token.length})`
|
|
825
821
|
});
|
|
826
822
|
}
|
|
827
823
|
});
|
|
828
|
-
var MissedCallSchema =
|
|
824
|
+
var MissedCallSchema = z3.enum([
|
|
829
825
|
"retry_10m",
|
|
830
826
|
"retry_30m",
|
|
831
827
|
"retry_60m",
|
|
@@ -835,32 +831,32 @@ var MissedCallSchema = z2.enum([
|
|
|
835
831
|
"inbox",
|
|
836
832
|
"dismiss"
|
|
837
833
|
]);
|
|
838
|
-
var BrokerTuningSchema =
|
|
834
|
+
var BrokerTuningSchema = z3.object({
|
|
839
835
|
/** 'none' = skip the spoken ack after a mapped answer (power users find it slow). */
|
|
840
|
-
ackVerbosity:
|
|
836
|
+
ackVerbosity: z3.enum(["normal", "none"]).optional(),
|
|
841
837
|
/** How readily the mapper asks its one clarification: 'low' = only when truly
|
|
842
838
|
* uninterpretable, 'high' = whenever not fully certain. */
|
|
843
|
-
clarifyEagerness:
|
|
839
|
+
clarifyEagerness: z3.enum(["low", "normal", "high"]).optional(),
|
|
844
840
|
/** The user's own shorthand: when they say `say`, they mean `mean`. */
|
|
845
|
-
phrasebook:
|
|
841
|
+
phrasebook: z3.array(z3.object({ say: z3.string().min(1).max(60), mean: z3.string().min(1).max(120) })).max(24).optional(),
|
|
846
842
|
/** The language calls are PLANNED in, when the account has chosen one (#1272). Absent —
|
|
847
843
|
* which is every account today — means the agent's own words decide, per ask: a call
|
|
848
844
|
* about an English ask opens in English. This is the only thing that overrides that,
|
|
849
845
|
* and a live caller who switches language mid-call still outranks it (broker/lang.ts).
|
|
850
846
|
* Set per user (no UI yet), like `voiceTuning`. */
|
|
851
|
-
language:
|
|
847
|
+
language: z3.enum(["en", "es"]).optional()
|
|
852
848
|
});
|
|
853
|
-
var UserSettingsSchema =
|
|
854
|
-
permissions:
|
|
855
|
-
call:
|
|
856
|
-
banner:
|
|
857
|
-
push:
|
|
849
|
+
var UserSettingsSchema = z3.object({
|
|
850
|
+
permissions: z3.object({
|
|
851
|
+
call: z3.boolean(),
|
|
852
|
+
banner: z3.boolean(),
|
|
853
|
+
push: z3.boolean()
|
|
858
854
|
}),
|
|
859
|
-
sessionMode:
|
|
860
|
-
silentPush:
|
|
861
|
-
autoCallback:
|
|
855
|
+
sessionMode: z3.enum(["default", "all_calls", "silent"]),
|
|
856
|
+
silentPush: z3.boolean(),
|
|
857
|
+
autoCallback: z3.boolean(),
|
|
862
858
|
/** Opt-in (default false) to using your content to improve Paigy and train models. */
|
|
863
|
-
improveConsent:
|
|
859
|
+
improveConsent: z3.boolean(),
|
|
864
860
|
missedCall: MissedCallSchema.default("backoff_standard"),
|
|
865
861
|
/** Where voice audio is processed. 'hosted' (default) = Paigy's voice services
|
|
866
862
|
* (ElevenLabs TTS, faster-whisper STT, the call bot); 'on_device' = the phone
|
|
@@ -868,7 +864,7 @@ var UserSettingsSchema = z2.object({
|
|
|
868
864
|
* Optional, NOT defaulted: a stale client PATCHing the full settings object
|
|
869
865
|
* must not silently reset this privacy choice. Absent = leave unchanged on
|
|
870
866
|
* write, 'hosted' on read (see store.ts). */
|
|
871
|
-
voiceMode:
|
|
867
|
+
voiceMode: z3.enum(["hosted", "on_device"]).optional(),
|
|
872
868
|
/** Per-user ring budget (#603): calls per rolling day before further calls
|
|
873
869
|
* degrade to banner. Absent = the global default (25). A number, never a
|
|
874
870
|
* bypass — every account keeps a ceiling. No UI; set per user for testing. */
|
|
@@ -876,10 +872,10 @@ var UserSettingsSchema = z2.object({
|
|
|
876
872
|
* payload['tuning'] (e.g. { silence_s: 3.5 } — a longer pause window for a
|
|
877
873
|
* slower speaker). No API-side semantics; the bot resolves each key with its
|
|
878
874
|
* own defaults. Set per user (no UI yet); absent = bot defaults. */
|
|
879
|
-
voiceTuning:
|
|
875
|
+
voiceTuning: z3.record(z3.string(), z3.union([z3.number(), z3.string()])).optional(),
|
|
880
876
|
/** Opt-in to real-phone (PSTN) calls when the app can't ring. Optional, not
|
|
881
877
|
* defaulted — an older client PATCHing the full object must not clobber it. */
|
|
882
|
-
pstnCalls:
|
|
878
|
+
pstnCalls: z3.boolean().optional(),
|
|
883
879
|
/** The user's IANA timezone (e.g. "America/Bogota"), recorded by the app — it is the
|
|
884
880
|
* only party that knows it. REMINDERS are why it exists: "remind me at ten" becomes
|
|
885
881
|
* an absolute `due_at` only if we know whose ten. Optional and never defaulted, for
|
|
@@ -888,59 +884,59 @@ var UserSettingsSchema = z2.object({
|
|
|
888
884
|
* that failure reads as the reminder rail being unreliable rather than as a missing
|
|
889
885
|
* setting. Absent = a spoken time can't be landed, so the reminder rides the next
|
|
890
886
|
* call — honest about what we know. */
|
|
891
|
-
timezone:
|
|
887
|
+
timezone: z3.string().min(1).max(64).optional(),
|
|
892
888
|
/** Account E2EE state (text lane): 'off' (default) = today's plaintext; 'on' =
|
|
893
889
|
* content is sealed end-to-end between the local agent and the phone. Like
|
|
894
890
|
* voiceMode, OPTIONAL and NOT defaulted so a stale client PATCHing the full
|
|
895
891
|
* settings object without it can't silently flip the account's E2EE state.
|
|
896
892
|
* Absent = leave unchanged on write, 'off' on read (see store.ts). The demo
|
|
897
893
|
* account is plaintext by construction and refuses any non-'off' value. */
|
|
898
|
-
e2eeMode:
|
|
894
|
+
e2eeMode: z3.enum(["off", "on"]).optional(),
|
|
899
895
|
/** Rung-2 broker tuning (#381). Optional and NOT defaulted, same stale-client
|
|
900
896
|
* clobber guard as voiceMode: absent = leave unchanged on write. */
|
|
901
897
|
broker: BrokerTuningSchema.optional()
|
|
902
898
|
});
|
|
903
|
-
var HistoryItemSchema =
|
|
904
|
-
id:
|
|
905
|
-
parentId:
|
|
899
|
+
var HistoryItemSchema = z3.object({
|
|
900
|
+
id: z3.string(),
|
|
901
|
+
parentId: z3.string(),
|
|
906
902
|
/** 'user' = a request you sent; 'agent' = a notification an agent sent you. */
|
|
907
|
-
initiator:
|
|
908
|
-
title:
|
|
903
|
+
initiator: z3.enum(["user", "agent"]),
|
|
904
|
+
title: z3.string(),
|
|
909
905
|
/** The agent on the other end (its name). */
|
|
910
|
-
name:
|
|
911
|
-
createdAt:
|
|
906
|
+
name: z3.string(),
|
|
907
|
+
createdAt: z3.string(),
|
|
912
908
|
/** When the agent fetched your request (user→agent only). */
|
|
913
|
-
agentAckedAt:
|
|
909
|
+
agentAckedAt: z3.string().nullable(),
|
|
914
910
|
/** When you answered the agent's notification (agent→user only). */
|
|
915
|
-
humanAckedAt:
|
|
911
|
+
humanAckedAt: z3.string().nullable()
|
|
916
912
|
});
|
|
917
913
|
var ACTIVITY_LINES = 2;
|
|
918
914
|
var ACTIVITY_LINE_MAX = 80;
|
|
919
|
-
var AgentActivitySchema =
|
|
915
|
+
var AgentActivitySchema = z3.object({
|
|
920
916
|
/** Oldest first, so the newest line is last — the one that replaces in place. */
|
|
921
|
-
lines:
|
|
917
|
+
lines: z3.array(z3.string().max(ACTIVITY_LINE_MAX)).max(ACTIVITY_LINES),
|
|
922
918
|
/** When the harness observed this tail. Its own timestamp, not the heartbeat's: a beat
|
|
923
919
|
* that carries an UNCHANGED tail must not make a stalled agent look like it just moved. */
|
|
924
|
-
at:
|
|
920
|
+
at: z3.string().datetime()
|
|
925
921
|
});
|
|
926
|
-
var ConnectionSummarySchema =
|
|
922
|
+
var ConnectionSummarySchema = z3.object({
|
|
927
923
|
/** The connection = the agent's token id (used to address a request). */
|
|
928
|
-
id:
|
|
924
|
+
id: z3.string(),
|
|
929
925
|
/** The credential kind: "device" = a paired machine (mint-only — it hosts and mints, it
|
|
930
926
|
* never talks); "agent" = an identity that sends. The roster and devices surfaces split
|
|
931
927
|
* on this. Optional/absent reads as "agent" (a row predating the kind column). See
|
|
932
928
|
* apps/api/src/tokens/devices-vs-agents-design.md. */
|
|
933
|
-
kind:
|
|
929
|
+
kind: z3.enum(["device", "agent"]).optional(),
|
|
934
930
|
/** For an agent, the token id of the DEVICE that minted it — so agents group under their
|
|
935
931
|
* machine, and revoking a device cascades to them. Null on devices, and on unlinked
|
|
936
932
|
* agents (phone-launched, provider-managed, or minted before the link existed). */
|
|
937
|
-
mintedByDevice:
|
|
938
|
-
device:
|
|
933
|
+
mintedByDevice: z3.string().nullable().optional(),
|
|
934
|
+
device: z3.string().nullable(),
|
|
939
935
|
/** The agent's display name (the single pairing name). */
|
|
940
|
-
name:
|
|
936
|
+
name: z3.string(),
|
|
941
937
|
/** For a managed connection, the provider key (e.g. "cma") that agentOrigin maps to a
|
|
942
938
|
* label; null for a local connection. Sourced from the token's provider, not the name. */
|
|
943
|
-
provider:
|
|
939
|
+
provider: z3.string().nullable(),
|
|
944
940
|
/** The pairing's assigned voice (#462); null = the default voice. */
|
|
945
941
|
voice: VoiceKeySchema.nullable(),
|
|
946
942
|
/** The LOUDEST this agent may ever reach you — a ceiling on `NOTIFY_LADDER`, set by the
|
|
@@ -951,19 +947,19 @@ var ConnectionSummarySchema = z2.object({
|
|
|
951
947
|
* every surface at once and outranks even `sessionMode: all_calls` — a mode the user
|
|
952
948
|
* set once must not overrule a rule they set about one agent. */
|
|
953
949
|
reach: NotifyLevelSchema.nullable().optional(),
|
|
954
|
-
createdAt:
|
|
950
|
+
createdAt: z3.string().datetime(),
|
|
955
951
|
/** Most recent notification on this connection, either direction. Null = no contact yet.
|
|
956
952
|
* Drives the agents-page recency grouping (Today / This week / …). */
|
|
957
|
-
lastContactAt:
|
|
953
|
+
lastContactAt: z3.string().datetime().nullable(),
|
|
958
954
|
/** Last presence heartbeat from a running agent process (POST /api/presence) — the
|
|
959
955
|
* desktop app while open. Null = never seen; stale = offline. */
|
|
960
|
-
lastSeenAt:
|
|
956
|
+
lastSeenAt: z3.string().datetime().nullable().optional(),
|
|
961
957
|
/** What a live desktop can run (companion.md §2.2), advertised on its heartbeat:
|
|
962
958
|
* harness availabilities + granted workspaces — the option set the phone's
|
|
963
959
|
* "new session" sheet offers. Absent for ordinary MCP agents. */
|
|
964
|
-
runtime:
|
|
965
|
-
harnesses:
|
|
966
|
-
workspaces:
|
|
960
|
+
runtime: z3.object({
|
|
961
|
+
harnesses: z3.array(z3.object({ name: z3.string(), label: z3.string(), status: z3.string() })).optional(),
|
|
962
|
+
workspaces: z3.array(z3.string()).optional()
|
|
967
963
|
}).optional(),
|
|
968
964
|
/** The tail of this agent's working log, when a harness is driving it — the agent page's
|
|
969
965
|
* live strip. Absent for anything the desktop harness isn't running (a hatched identity
|
|
@@ -972,119 +968,119 @@ var ConnectionSummarySchema = z2.object({
|
|
|
972
968
|
activity: AgentActivitySchema.optional(),
|
|
973
969
|
/** True = a provider-managed agent running in the provider's cloud (e.g. Anthropic CMA);
|
|
974
970
|
* false = a local MCP connection running on the user's computer (Claude Code/Codex/…). */
|
|
975
|
-
managed:
|
|
971
|
+
managed: z3.boolean()
|
|
976
972
|
});
|
|
977
|
-
var LedgerItemSchema =
|
|
978
|
-
var AgentLedgerSchema =
|
|
979
|
-
agent:
|
|
973
|
+
var LedgerItemSchema = z3.object({ id: z3.string(), parentId: z3.string(), title: z3.string(), createdAt: z3.string() });
|
|
974
|
+
var AgentLedgerSchema = z3.object({
|
|
975
|
+
agent: z3.object({ id: z3.string(), name: z3.string(), revokedAt: z3.string().nullable() }),
|
|
980
976
|
/** Its own questions you have not answered. */
|
|
981
|
-
asks:
|
|
977
|
+
asks: z3.array(LedgerItemSchema),
|
|
982
978
|
/** Its questions you answered that nobody acted on — still owed to somebody. */
|
|
983
|
-
answered:
|
|
979
|
+
answered: z3.array(LedgerItemSchema),
|
|
984
980
|
/** Requests you sent it that it never took. */
|
|
985
|
-
requests:
|
|
986
|
-
goals:
|
|
987
|
-
callbacks:
|
|
981
|
+
requests: z3.array(LedgerItemSchema),
|
|
982
|
+
goals: z3.array(z3.object({ id: z3.string(), outcome: z3.string(), state: z3.string() })),
|
|
983
|
+
callbacks: z3.array(z3.object({ id: z3.string(), parentId: z3.string(), trigger: z3.string(), note: z3.string(), dueAt: z3.string().nullable() }))
|
|
988
984
|
});
|
|
989
|
-
var ReassignResultSchema =
|
|
990
|
-
moved:
|
|
991
|
-
parentId:
|
|
985
|
+
var ReassignResultSchema = z3.object({
|
|
986
|
+
moved: z3.object({ asks: z3.number(), answered: z3.number(), requests: z3.number(), goals: z3.number(), callbacks: z3.number() }),
|
|
987
|
+
parentId: z3.string().nullable()
|
|
992
988
|
});
|
|
993
|
-
var MoveRingSchema =
|
|
994
|
-
var MoveSchema =
|
|
995
|
-
id:
|
|
989
|
+
var MoveRingSchema = z3.enum(["home", "travels", "retired", "quarantined"]);
|
|
990
|
+
var MoveSchema = z3.object({
|
|
991
|
+
id: z3.string(),
|
|
996
992
|
/** The reusable question, as distill normalized it. */
|
|
997
|
-
question:
|
|
993
|
+
question: z3.string(),
|
|
998
994
|
/** The operative ruling. Editable by the user (PATCH) — which resets the ledger. */
|
|
999
|
-
answer:
|
|
995
|
+
answer: z3.string(),
|
|
1000
996
|
/** The user's stated reason, when they gave one. Null = inherently narrow: the judge is
|
|
1001
997
|
* told so, and the ruling only derives essentially the same question in the same scope. */
|
|
1002
|
-
rationale:
|
|
998
|
+
rationale: z3.string().nullable(),
|
|
1003
999
|
/** Where the ruling lives: a repo/workspace, or 'global'. */
|
|
1004
|
-
scope:
|
|
1000
|
+
scope: z3.string(),
|
|
1005
1001
|
ring: MoveRingSchema,
|
|
1006
1002
|
/** True = the user pinned it with `always` (travel granted by hand, not by evidence). */
|
|
1007
|
-
pinned:
|
|
1003
|
+
pinned: z3.boolean(),
|
|
1008
1004
|
/** True = a pin the user placed was BROKEN by later counter-evidence. Surfaced so the
|
|
1009
1005
|
* break is visible instead of a pin silently disappearing. */
|
|
1010
|
-
pinBroken:
|
|
1006
|
+
pinBroken: z3.boolean(),
|
|
1011
1007
|
/** When the ruling was distilled. */
|
|
1012
|
-
learnedAt:
|
|
1008
|
+
learnedAt: z3.string(),
|
|
1013
1009
|
/** Last time it answered an ask. Null = never fired. */
|
|
1014
|
-
lastUsedAt:
|
|
1010
|
+
lastUsedAt: z3.string().nullable(),
|
|
1015
1011
|
/** How many asks it has answered. Instrumentation — deliberately NOT an input to the
|
|
1016
1012
|
* evidence curve: firing says the question keeps arising, not that the ruling is right. */
|
|
1017
|
-
usedCount:
|
|
1013
|
+
usedCount: z3.number(),
|
|
1018
1014
|
/** Ledger: outcomes that said it held up. Saturating — the tenth is worth almost nothing. */
|
|
1019
|
-
confirms:
|
|
1015
|
+
confirms: z3.number(),
|
|
1020
1016
|
/** Ledger: contradictions, in signal units (a full override = 1, weaker signals less).
|
|
1021
1017
|
* Linear and priced above the entire confirmation budget, so any full counter wins. */
|
|
1022
|
-
counters:
|
|
1018
|
+
counters: z3.number(),
|
|
1023
1019
|
/** The agent that asked the question this move came from, when known. Null for a move
|
|
1024
1020
|
* distilled from a clarify ruling (those carry no agent) or one whose source rows are gone. */
|
|
1025
|
-
learnedFrom:
|
|
1021
|
+
learnedFrom: z3.object({ id: z3.string(), name: z3.string() }).nullable()
|
|
1026
1022
|
});
|
|
1027
|
-
var CreateRequestSchema =
|
|
1023
|
+
var CreateRequestSchema = z3.object({
|
|
1028
1024
|
/** The connection (token id) to send to, from GET /api/tokens. */
|
|
1029
|
-
tokenId:
|
|
1025
|
+
tokenId: z3.string(),
|
|
1030
1026
|
/** The user's message to the agent. */
|
|
1031
|
-
text:
|
|
1027
|
+
text: z3.string().min(1),
|
|
1032
1028
|
/** Land the request on an existing conversation thread (History → "Continue")
|
|
1033
1029
|
* instead of minting a fresh one. Must belong to the requesting user. */
|
|
1034
|
-
parentId:
|
|
1030
|
+
parentId: z3.string().optional(),
|
|
1035
1031
|
/** Point the agent at a past conversation (possibly with a different agent) as
|
|
1036
1032
|
* starting context (History → "New session from this"). A reference, not a copy —
|
|
1037
1033
|
* the agent reads it via get_thread. Must belong to the requesting user. */
|
|
1038
|
-
contextParentId:
|
|
1034
|
+
contextParentId: z3.string().optional()
|
|
1039
1035
|
});
|
|
1040
|
-
var HandoffSchema =
|
|
1036
|
+
var HandoffSchema = z3.object({
|
|
1041
1037
|
/** Move this existing outcome to `target` without reminting it. Requires `target`. */
|
|
1042
|
-
workId:
|
|
1038
|
+
workId: z3.string().uuid().optional(),
|
|
1043
1039
|
/** Land the note on an existing thread; omitted mints a fresh one. */
|
|
1044
|
-
parentId:
|
|
1040
|
+
parentId: z3.string().uuid().optional(),
|
|
1045
1041
|
/** One-line headline of the working context handed off. */
|
|
1046
|
-
title:
|
|
1042
|
+
title: z3.string().min(1),
|
|
1047
1043
|
/** The brief — standalone notes the successor reads (what was done, what's left, links). */
|
|
1048
|
-
notes:
|
|
1044
|
+
notes: z3.array(z3.string().min(1)).min(1),
|
|
1049
1045
|
/** A sibling connection to dispatch directly to (token id or agent nickname). Same-account
|
|
1050
1046
|
* only; omit to leave the thread for the user to hand off in the app. */
|
|
1051
|
-
target:
|
|
1047
|
+
target: z3.string().optional(),
|
|
1052
1048
|
/** Write the note as a RECAP (kind:'recap', #617): a summary turn that supersedes the
|
|
1053
1049
|
* thread's earlier turns for rehydration — get_thread returns the latest recap + only
|
|
1054
1050
|
* the turns after it. Handoff-to-a-successor and handoff-to-yourself-later are the
|
|
1055
1051
|
* same primitive; a recap is one whose audience includes you. */
|
|
1056
|
-
recap:
|
|
1052
|
+
recap: z3.boolean().optional()
|
|
1057
1053
|
}).refine((value) => !value.workId || Boolean(value.target), {
|
|
1058
1054
|
message: "target is required when handing off Work",
|
|
1059
1055
|
path: ["target"]
|
|
1060
1056
|
});
|
|
1061
|
-
var NoteSourceSchema =
|
|
1062
|
-
var NoteStatusSchema =
|
|
1063
|
-
var NoteRepeatSchema =
|
|
1064
|
-
var DecisionSchema =
|
|
1065
|
-
id:
|
|
1057
|
+
var NoteSourceSchema = z3.enum(["app", "call"]);
|
|
1058
|
+
var NoteStatusSchema = z3.enum(["open", "assigned", "in_progress", "done"]);
|
|
1059
|
+
var NoteRepeatSchema = z3.enum(["once", "until_done"]);
|
|
1060
|
+
var DecisionSchema = z3.object({
|
|
1061
|
+
id: z3.string(),
|
|
1066
1062
|
/** The note this decision refines; null = recorded on a bare thread (the
|
|
1067
1063
|
* extensibility seam — any conversation can accrue decisions). */
|
|
1068
|
-
noteId:
|
|
1064
|
+
noteId: z3.string().nullable(),
|
|
1069
1065
|
/** What was ambiguous — the broker's (or the user's own) question. */
|
|
1070
|
-
question:
|
|
1066
|
+
question: z3.string(),
|
|
1071
1067
|
/** The user's ruling; null while the question is open. */
|
|
1072
|
-
answer:
|
|
1073
|
-
decidedAt:
|
|
1074
|
-
createdAt:
|
|
1068
|
+
answer: z3.string().nullable(),
|
|
1069
|
+
decidedAt: z3.string().nullable(),
|
|
1070
|
+
createdAt: z3.string()
|
|
1075
1071
|
});
|
|
1076
|
-
var NoteSchema =
|
|
1077
|
-
id:
|
|
1072
|
+
var NoteSchema = z3.object({
|
|
1073
|
+
id: z3.string(),
|
|
1078
1074
|
/** One-line headline (broker-titled; deterministic floor). */
|
|
1079
|
-
title:
|
|
1075
|
+
title: z3.string(),
|
|
1080
1076
|
/** The original intent, verbatim — assignees always see the user's own words. */
|
|
1081
|
-
intent:
|
|
1077
|
+
intent: z3.string(),
|
|
1082
1078
|
source: NoteSourceSchema,
|
|
1083
1079
|
status: NoteStatusSchema,
|
|
1084
1080
|
/** Who it was assigned to (a participant ref, 'agent:<tokenId>'); null = unassigned. */
|
|
1085
|
-
assignee:
|
|
1081
|
+
assignee: z3.string().nullable(),
|
|
1086
1082
|
/** The request thread minted at assignment; null until assigned. */
|
|
1087
|
-
parentId:
|
|
1083
|
+
parentId: z3.string().nullable(),
|
|
1088
1084
|
/** REMINDERS (reminders-design.md): the NOT-BEFORE this becomes eligible to ride a
|
|
1089
1085
|
* call — never a deadline. It only ever comes from the user's own words, so when it
|
|
1090
1086
|
* passes Paigy rings ONCE (#1293, owner 2026-08-26: a time said out loud is consent to
|
|
@@ -1093,202 +1089,215 @@ var NoteSchema = z2.object({
|
|
|
1093
1089
|
// Defaulted, not required: a Note from an API deploy older than the reminders
|
|
1094
1090
|
// migration has none of these, and the defaults ARE what it means — no not-before,
|
|
1095
1091
|
// one ride, never ridden. Parsing must not fail across a rolling deploy.
|
|
1096
|
-
dueAt:
|
|
1092
|
+
dueAt: z3.string().nullable().default(null),
|
|
1097
1093
|
repeat: NoteRepeatSchema.default("once"),
|
|
1098
1094
|
/** How many calls have already carried it — the fatigue cap counts rides, not days. */
|
|
1099
|
-
rides:
|
|
1100
|
-
lastRideAt:
|
|
1101
|
-
createdAt:
|
|
1095
|
+
rides: z3.number().int().default(0),
|
|
1096
|
+
lastRideAt: z3.string().nullable().default(null),
|
|
1097
|
+
createdAt: z3.string()
|
|
1102
1098
|
});
|
|
1103
|
-
var CreateNoteSchema =
|
|
1099
|
+
var CreateNoteSchema = z3.object({
|
|
1104
1100
|
/** The intent, in the user's own words. Stored verbatim; the broker only titles it. */
|
|
1105
|
-
text:
|
|
1101
|
+
text: z3.string().min(1).max(4e3),
|
|
1106
1102
|
/** Capture it as a REMINDER — a note assigned to the user themselves, which rides
|
|
1107
1103
|
* their next call instead of being handed to an agent. Everything else about the
|
|
1108
1104
|
* note is identical; this is the one parameter that separates the two. */
|
|
1109
|
-
forMe:
|
|
1105
|
+
forMe: z3.boolean().optional(),
|
|
1110
1106
|
/** The not-before, when the user already said one. Absent = the very next call. */
|
|
1111
|
-
dueAt:
|
|
1107
|
+
dueAt: z3.string().datetime().optional(),
|
|
1112
1108
|
repeat: NoteRepeatSchema.optional()
|
|
1113
1109
|
});
|
|
1114
|
-
var RecordDecisionSchema =
|
|
1110
|
+
var RecordDecisionSchema = z3.object({
|
|
1115
1111
|
/** An open decision (from /clarify) to answer. */
|
|
1116
|
-
decisionId:
|
|
1112
|
+
decisionId: z3.string().optional(),
|
|
1117
1113
|
/** For an ad-hoc decision: what was ambiguous. Required without `decisionId`. */
|
|
1118
|
-
question:
|
|
1114
|
+
question: z3.string().min(1).max(500).optional(),
|
|
1119
1115
|
/** The ruling. */
|
|
1120
|
-
answer:
|
|
1116
|
+
answer: z3.string().min(1).max(2e3)
|
|
1121
1117
|
}).refine((d) => d.decisionId || d.question, { message: "decisionId or question required" });
|
|
1122
|
-
var AssignNoteSchema =
|
|
1118
|
+
var AssignNoteSchema = z3.object({
|
|
1123
1119
|
/** An EXISTING agent: token id or nickname. Omit when spawning fresh. */
|
|
1124
|
-
target:
|
|
1120
|
+
target: z3.string().min(1).optional(),
|
|
1125
1121
|
/** Spawn a NEW session for this note (companion.md §2.2): the assignee doesn't
|
|
1126
1122
|
* exist yet — mint it on a live desktop that advertises the harness+workspace,
|
|
1127
1123
|
* named after the note. The brief arrives as its opening request. */
|
|
1128
|
-
spawn:
|
|
1129
|
-
hostTokenId:
|
|
1130
|
-
harness:
|
|
1131
|
-
workspace:
|
|
1124
|
+
spawn: z3.object({
|
|
1125
|
+
hostTokenId: z3.string().uuid(),
|
|
1126
|
+
harness: z3.string().min(1),
|
|
1127
|
+
workspace: z3.string().min(1)
|
|
1132
1128
|
}).optional()
|
|
1133
1129
|
}).refine((a) => !!a.target !== !!a.spawn, { message: "exactly one of target or spawn" });
|
|
1134
|
-
var TriageVerdictSchema =
|
|
1135
|
-
var TriageItemSchema =
|
|
1136
|
-
noteId:
|
|
1130
|
+
var TriageVerdictSchema = z3.enum(["keep", "stale", "close", "assign"]);
|
|
1131
|
+
var TriageItemSchema = z3.object({
|
|
1132
|
+
noteId: z3.string(),
|
|
1137
1133
|
/** The note's headline at run time. */
|
|
1138
|
-
title:
|
|
1134
|
+
title: z3.string(),
|
|
1139
1135
|
/** WHY, in one short human line, evidence first — this is read on a phone underneath
|
|
1140
1136
|
* the note's title: "no movement in 34 days", "worked 3 notes in this repo this week".
|
|
1141
1137
|
* Never a model's reasoning transcript, never an id. */
|
|
1142
|
-
why:
|
|
1138
|
+
why: z3.string()
|
|
1143
1139
|
});
|
|
1144
|
-
var TriageAssignmentSchema =
|
|
1140
|
+
var TriageAssignmentSchema = z3.object({
|
|
1145
1141
|
/** The agent's token id — what `dispatchNote` resolves and what a request is addressed to. */
|
|
1146
|
-
agent:
|
|
1142
|
+
agent: z3.string(),
|
|
1147
1143
|
/** Its display name at run time (the name on the hatchling's card). Denormalized for the
|
|
1148
1144
|
* same reason as `title`: the card must render from the proposal alone. */
|
|
1149
|
-
agentName:
|
|
1150
|
-
notes:
|
|
1145
|
+
agentName: z3.string(),
|
|
1146
|
+
notes: z3.array(TriageItemSchema)
|
|
1151
1147
|
});
|
|
1152
|
-
var TriageStatusSchema =
|
|
1153
|
-
var SubmitTriageSchema =
|
|
1148
|
+
var TriageStatusSchema = z3.enum(["open", "superseded", "dismissed"]);
|
|
1149
|
+
var SubmitTriageSchema = z3.object({
|
|
1154
1150
|
/** Which runtime judged: "ollama" (inference never left the machine) or a harness the
|
|
1155
1151
|
* user already runs under their own credentials ("claude" / "codex" / "agy"). Recorded
|
|
1156
1152
|
* so the phone can say where the content went — an unattributed privacy claim is worth
|
|
1157
1153
|
* nothing, and #1106's promise is precisely "Paigy's servers never see this". */
|
|
1158
|
-
provider:
|
|
1154
|
+
provider: z3.string().min(1).max(60),
|
|
1159
1155
|
/** The concrete model when the provider names one (an ollama tag); null otherwise. */
|
|
1160
|
-
model:
|
|
1156
|
+
model: z3.string().max(200).nullable().optional(),
|
|
1161
1157
|
/** How many open notes the run actually looked at — the denominator on the phone
|
|
1162
1158
|
* ("6 of 50"), and the honest answer to "did it read the whole queue?". */
|
|
1163
|
-
reviewed:
|
|
1164
|
-
close:
|
|
1165
|
-
stale:
|
|
1166
|
-
assign:
|
|
1159
|
+
reviewed: z3.number().int().min(0).max(1e4).default(0),
|
|
1160
|
+
close: z3.array(TriageItemSchema).max(200).default([]),
|
|
1161
|
+
stale: z3.array(TriageItemSchema).max(200).default([]),
|
|
1162
|
+
assign: z3.array(TriageAssignmentSchema).max(50).default([])
|
|
1167
1163
|
});
|
|
1168
1164
|
var TriageProposalSchema = SubmitTriageSchema.extend({
|
|
1169
|
-
id:
|
|
1170
|
-
runAt:
|
|
1165
|
+
id: z3.string(),
|
|
1166
|
+
runAt: z3.string(),
|
|
1171
1167
|
status: TriageStatusSchema,
|
|
1172
|
-
model:
|
|
1173
|
-
});
|
|
1174
|
-
var AcceptTriageSchema =
|
|
1175
|
-
|
|
1176
|
-
|
|
1177
|
-
|
|
1178
|
-
group:
|
|
1179
|
-
agent:
|
|
1180
|
-
noteIds:
|
|
1168
|
+
model: z3.string().nullable().default(null)
|
|
1169
|
+
});
|
|
1170
|
+
var AcceptTriageSchema = z3.discriminatedUnion("group", [
|
|
1171
|
+
z3.object({ group: z3.literal("close"), noteIds: z3.array(z3.string()).max(200).optional() }),
|
|
1172
|
+
z3.object({ group: z3.literal("stale"), noteIds: z3.array(z3.string()).max(200).optional() }),
|
|
1173
|
+
z3.object({
|
|
1174
|
+
group: z3.literal("assign"),
|
|
1175
|
+
agent: z3.string().min(1),
|
|
1176
|
+
noteIds: z3.array(z3.string()).max(200).optional()
|
|
1181
1177
|
})
|
|
1182
1178
|
]);
|
|
1183
|
-
var AcceptTriageResultSchema =
|
|
1184
|
-
accepted:
|
|
1185
|
-
failed:
|
|
1179
|
+
var AcceptTriageResultSchema = z3.object({
|
|
1180
|
+
accepted: z3.array(z3.string()),
|
|
1181
|
+
failed: z3.array(z3.object({ noteId: z3.string(), reason: z3.string() }))
|
|
1186
1182
|
});
|
|
1187
|
-
var DeliveryModeSchema =
|
|
1183
|
+
var DeliveryModeSchema = z3.enum(["poll", "self_hosted"]);
|
|
1188
1184
|
var WAKE_EVENT = "wake";
|
|
1189
1185
|
var wakeChannel = (tokenId) => `wake:${tokenId}`;
|
|
1190
|
-
var RegisterDeliverySchema =
|
|
1191
|
-
var OAuthStartSchema =
|
|
1192
|
-
provider:
|
|
1193
|
-
returnTo:
|
|
1186
|
+
var RegisterDeliverySchema = z3.object({ mode: DeliveryModeSchema });
|
|
1187
|
+
var OAuthStartSchema = z3.object({
|
|
1188
|
+
provider: z3.enum(["cma"]),
|
|
1189
|
+
returnTo: z3.string().min(1)
|
|
1194
1190
|
});
|
|
1195
|
-
var DeliveryConfigSchema =
|
|
1196
|
-
tokenId:
|
|
1191
|
+
var DeliveryConfigSchema = z3.object({
|
|
1192
|
+
tokenId: z3.string(),
|
|
1197
1193
|
mode: DeliveryModeSchema,
|
|
1198
1194
|
/** null when the server has no SUPABASE_ANON_KEY set — the listener then falls
|
|
1199
1195
|
* back to its own PAIGY_SUPABASE_URL / PAIGY_SUPABASE_ANON_KEY env. */
|
|
1200
|
-
realtime:
|
|
1196
|
+
realtime: z3.object({ url: z3.string(), anonKey: z3.string() }).nullable()
|
|
1201
1197
|
});
|
|
1202
|
-
var StatusSchema =
|
|
1203
|
-
name:
|
|
1204
|
-
sessionMode:
|
|
1198
|
+
var StatusSchema = z3.object({
|
|
1199
|
+
name: z3.string(),
|
|
1200
|
+
sessionMode: z3.enum(["default", "all_calls", "silent"]),
|
|
1205
1201
|
/** A phone is registered for push/ring (any push token on the account). */
|
|
1206
|
-
phone:
|
|
1207
|
-
|
|
1208
|
-
|
|
1209
|
-
|
|
1210
|
-
|
|
1211
|
-
|
|
1212
|
-
|
|
1213
|
-
|
|
1214
|
-
|
|
1215
|
-
|
|
1216
|
-
|
|
1217
|
-
|
|
1218
|
-
|
|
1219
|
-
|
|
1220
|
-
});
|
|
1221
|
-
var
|
|
1222
|
-
|
|
1223
|
-
|
|
1224
|
-
|
|
1202
|
+
phone: z3.boolean(),
|
|
1203
|
+
/** HOW MANY THINGS ARE WAITING ON THIS IDENTITY — replies it never collected and requests
|
|
1204
|
+
* it never picked up. THE SAME NUMBER the harness's wake gate reads
|
|
1205
|
+
* (`pendingSummary.unacknowledged`), from the same function, because a statusline saying
|
|
1206
|
+
* zero while the sweep sees one is two ideas of "waiting".
|
|
1207
|
+
*
|
|
1208
|
+
* Why it is here at all (owner, 2026-09-07): nothing can interrupt an idle agent process
|
|
1209
|
+
* that nobody spawned, so a terminal session only learns of work by asking. The harness
|
|
1210
|
+
* used to paper over that by spawning a SECOND process on the identity; now it stands
|
|
1211
|
+
* back, correctly, and the person sitting at the terminal is the one who can act. A
|
|
1212
|
+
* coffee-beans request sat unread for three days.
|
|
1213
|
+
*
|
|
1214
|
+
* Optional: an older API sends no field, and the statusline then renders exactly as before. */
|
|
1215
|
+
waiting: z3.number().int().nonnegative().optional()
|
|
1216
|
+
});
|
|
1217
|
+
var EnvelopeRecipientSchema = z3.object({
|
|
1218
|
+
keyId: z3.string(),
|
|
1219
|
+
epk: z3.string(),
|
|
1220
|
+
wnonce: z3.string(),
|
|
1221
|
+
wrap: z3.string()
|
|
1222
|
+
});
|
|
1223
|
+
var EnvelopeHeaderSchema = z3.object({
|
|
1224
|
+
field: z3.enum(["context", "options", "visuals", "answer"]),
|
|
1225
|
+
kind: z3.string(),
|
|
1226
|
+
senderRole: z3.enum(["agent", "user"]),
|
|
1227
|
+
recipientKeyIds: z3.array(z3.string()),
|
|
1228
|
+
seq: z3.number().int().nonnegative()
|
|
1229
|
+
});
|
|
1230
|
+
var EnvelopeSchema = z3.object({
|
|
1231
|
+
v: z3.literal(1),
|
|
1232
|
+
alg: z3.literal("x25519-xsalsa20poly1305"),
|
|
1233
|
+
msgId: z3.string(),
|
|
1225
1234
|
hdr: EnvelopeHeaderSchema,
|
|
1226
|
-
recipients:
|
|
1227
|
-
nonce:
|
|
1228
|
-
ct:
|
|
1235
|
+
recipients: z3.array(EnvelopeRecipientSchema).min(1),
|
|
1236
|
+
nonce: z3.string(),
|
|
1237
|
+
ct: z3.string()
|
|
1229
1238
|
});
|
|
1230
|
-
var SealedAnswerSchema =
|
|
1231
|
-
ignored:
|
|
1239
|
+
var SealedAnswerSchema = z3.object({
|
|
1240
|
+
ignored: z3.boolean(),
|
|
1232
1241
|
envelope: EnvelopeSchema
|
|
1233
1242
|
});
|
|
1234
|
-
var DeviceCredentialSchema =
|
|
1235
|
-
deviceId:
|
|
1236
|
-
kind:
|
|
1237
|
-
x25519Pub:
|
|
1238
|
-
ed25519Pub:
|
|
1239
|
-
sig:
|
|
1240
|
-
});
|
|
1241
|
-
var DeviceRosterSchema =
|
|
1242
|
-
uikPub:
|
|
1243
|
-
devices:
|
|
1244
|
-
});
|
|
1245
|
-
var WakeNudgeSchema =
|
|
1246
|
-
kind:
|
|
1247
|
-
notificationId:
|
|
1248
|
-
parentId:
|
|
1249
|
-
});
|
|
1250
|
-
var PairingStatusSchema =
|
|
1251
|
-
var PairingRevealSchema =
|
|
1252
|
-
x25519:
|
|
1253
|
-
ed25519:
|
|
1254
|
-
nonce:
|
|
1255
|
-
});
|
|
1256
|
-
var DeviceCodeRequestSchema =
|
|
1243
|
+
var DeviceCredentialSchema = z3.object({
|
|
1244
|
+
deviceId: z3.string(),
|
|
1245
|
+
kind: z3.enum(["phone", "web", "agent"]),
|
|
1246
|
+
x25519Pub: z3.string(),
|
|
1247
|
+
ed25519Pub: z3.string(),
|
|
1248
|
+
sig: z3.string()
|
|
1249
|
+
});
|
|
1250
|
+
var DeviceRosterSchema = z3.object({
|
|
1251
|
+
uikPub: z3.string(),
|
|
1252
|
+
devices: z3.array(DeviceCredentialSchema)
|
|
1253
|
+
});
|
|
1254
|
+
var WakeNudgeSchema = z3.object({
|
|
1255
|
+
kind: z3.enum(["reply", "request", "callback"]),
|
|
1256
|
+
notificationId: z3.string().optional(),
|
|
1257
|
+
parentId: z3.string()
|
|
1258
|
+
});
|
|
1259
|
+
var PairingStatusSchema = z3.enum(["pending", "approved", "denied", "expired"]);
|
|
1260
|
+
var PairingRevealSchema = z3.object({
|
|
1261
|
+
x25519: z3.string(),
|
|
1262
|
+
ed25519: z3.string(),
|
|
1263
|
+
nonce: z3.string()
|
|
1264
|
+
});
|
|
1265
|
+
var DeviceCodeRequestSchema = z3.object({
|
|
1257
1266
|
/** The agent's suggested name for the pairing — the human sees it pre-filled at
|
|
1258
1267
|
* approval and can override. Optional; blank → a default silly name server-side. */
|
|
1259
|
-
suggestedName:
|
|
1268
|
+
suggestedName: z3.string().optional(),
|
|
1260
1269
|
/** Legacy alias for suggestedName (older MCPs sent `agent`). Accepted for
|
|
1261
1270
|
* back-compat; `suggestedName` wins when both are present. ponytail: drop once no
|
|
1262
1271
|
* pre-`name` MCP is in the wild. */
|
|
1263
|
-
agent:
|
|
1264
|
-
device:
|
|
1265
|
-
proto:
|
|
1272
|
+
agent: z3.union([z3.string(), z3.object({ name: z3.string().optional() })]).optional(),
|
|
1273
|
+
device: z3.string().optional(),
|
|
1274
|
+
proto: z3.string().optional(),
|
|
1266
1275
|
// compiled-in tag, e.g. "paigy-pair-v2|sas=24"
|
|
1267
|
-
commitment:
|
|
1276
|
+
commitment: z3.string().optional()
|
|
1268
1277
|
// agent's Ca
|
|
1269
1278
|
});
|
|
1270
|
-
var DeviceCodeSchema =
|
|
1271
|
-
device_code:
|
|
1272
|
-
user_code:
|
|
1273
|
-
verification_uri:
|
|
1274
|
-
verification_uri_complete:
|
|
1275
|
-
interval:
|
|
1276
|
-
expires_in:
|
|
1279
|
+
var DeviceCodeSchema = z3.object({
|
|
1280
|
+
device_code: z3.string(),
|
|
1281
|
+
user_code: z3.string(),
|
|
1282
|
+
verification_uri: z3.string().url(),
|
|
1283
|
+
verification_uri_complete: z3.string().url(),
|
|
1284
|
+
interval: z3.number(),
|
|
1285
|
+
expires_in: z3.number()
|
|
1277
1286
|
});
|
|
1278
|
-
var DeviceInfoSchema =
|
|
1279
|
-
code:
|
|
1287
|
+
var DeviceInfoSchema = z3.object({
|
|
1288
|
+
code: z3.string(),
|
|
1280
1289
|
/** The agent's suggested name (from /device/code) — shown on the approval screen,
|
|
1281
1290
|
* pre-filling the name field the human can edit. */
|
|
1282
|
-
name:
|
|
1291
|
+
name: z3.string(),
|
|
1283
1292
|
/** @deprecated Legacy alias of `name` for the pre-#531 embedded bundle in App Store
|
|
1284
1293
|
* build 35, whose DeviceFlow renders `info.agent.slice(0, 2)` — without this a FRESH
|
|
1285
1294
|
* install crashes on the pairing screen on first launch, before the OTA lands
|
|
1286
1295
|
* (seen live: PAIGY-5T, 2026-07-21). Remove once a newer binary is the floor. */
|
|
1287
|
-
agent:
|
|
1288
|
-
device:
|
|
1296
|
+
agent: z3.string().optional(),
|
|
1297
|
+
device: z3.string().nullable(),
|
|
1289
1298
|
status: PairingStatusSchema,
|
|
1290
|
-
proto:
|
|
1291
|
-
agent_commitment:
|
|
1299
|
+
proto: z3.string().nullable().optional(),
|
|
1300
|
+
agent_commitment: z3.string().nullable().optional(),
|
|
1292
1301
|
// Ca
|
|
1293
1302
|
agent_reveal: PairingRevealSchema.nullable().optional(),
|
|
1294
1303
|
// present once the agent reveals
|
|
@@ -1298,48 +1307,48 @@ var DeviceInfoSchema = z2.object({
|
|
|
1298
1307
|
// withheld until e2ee=true) can compute the SAS WITHOUT a token. Public keys — same safety
|
|
1299
1308
|
// class as agent_reveal above. Present only once the phone reveals; null otherwise.
|
|
1300
1309
|
phone_reveal: PairingRevealSchema.nullable().optional(),
|
|
1301
|
-
uik_pub:
|
|
1310
|
+
uik_pub: z3.string().nullable().optional()
|
|
1302
1311
|
});
|
|
1303
|
-
var DeviceTokenRequestSchema =
|
|
1304
|
-
device_code:
|
|
1312
|
+
var DeviceTokenRequestSchema = z3.object({
|
|
1313
|
+
device_code: z3.string(),
|
|
1305
1314
|
reveal: PairingRevealSchema.optional()
|
|
1306
1315
|
// agent's reveal {x25519, ed25519, nonce}
|
|
1307
1316
|
});
|
|
1308
|
-
var DeviceTokenSchema =
|
|
1309
|
-
access_token:
|
|
1317
|
+
var DeviceTokenSchema = z3.object({
|
|
1318
|
+
access_token: z3.string(),
|
|
1310
1319
|
/** The pairing's single name (user-typed at approval, the agent's suggestion, or
|
|
1311
1320
|
* a default silly name). */
|
|
1312
|
-
name:
|
|
1313
|
-
device:
|
|
1321
|
+
name: z3.string(),
|
|
1322
|
+
device: z3.string().nullable(),
|
|
1314
1323
|
/** The pairing's assigned voice, cached so the desktop can seed the SAME face the phone
|
|
1315
1324
|
* draws — voice is the third ingredient of a hatchling's build (party/traits.ts). */
|
|
1316
|
-
voice:
|
|
1325
|
+
voice: z3.string().nullable().optional(),
|
|
1317
1326
|
/** The token's server-side id — the face's COLOUR anchor, and the only seed ingredient
|
|
1318
1327
|
* that survives a rename. Cached by the host's identity beat. */
|
|
1319
|
-
token_id:
|
|
1328
|
+
token_id: z3.string().nullable().optional(),
|
|
1320
1329
|
/** WHERE this identity works — the folder a wake should land it in. Written by the host
|
|
1321
1330
|
* at spawn and by `paigy-harness handoff` from a live terminal. Without it every wake
|
|
1322
1331
|
* landed in the FIRST granted workspace and the agent rediscovered its own repo from
|
|
1323
1332
|
* the thread each time (host.ts, live catch 2026-08-06 — prompt-papered until now). */
|
|
1324
|
-
workspace:
|
|
1333
|
+
workspace: z3.string().nullable().optional(),
|
|
1325
1334
|
phone_reveal: PairingRevealSchema.nullable().optional(),
|
|
1326
1335
|
// present once the phone reveals
|
|
1327
|
-
uik_pub:
|
|
1336
|
+
uik_pub: z3.string().nullable().optional()
|
|
1328
1337
|
});
|
|
1329
|
-
var DeviceCommitRequestSchema =
|
|
1330
|
-
code:
|
|
1331
|
-
commitment:
|
|
1338
|
+
var DeviceCommitRequestSchema = z3.object({
|
|
1339
|
+
code: z3.string(),
|
|
1340
|
+
commitment: z3.string()
|
|
1332
1341
|
// Cb
|
|
1333
1342
|
});
|
|
1334
|
-
var DevicePeerCommitSchema =
|
|
1335
|
-
commitment:
|
|
1343
|
+
var DevicePeerCommitSchema = z3.object({
|
|
1344
|
+
commitment: z3.string().nullable()
|
|
1336
1345
|
});
|
|
1337
|
-
var SupportRequestSchema =
|
|
1338
|
-
email:
|
|
1339
|
-
message:
|
|
1340
|
-
name:
|
|
1346
|
+
var SupportRequestSchema = z3.object({
|
|
1347
|
+
email: z3.string().email().max(320),
|
|
1348
|
+
message: z3.string().trim().min(1).max(5e3),
|
|
1349
|
+
name: z3.string().trim().max(120).optional()
|
|
1341
1350
|
});
|
|
1342
|
-
var NotificationFeedbackKindSchema =
|
|
1351
|
+
var NotificationFeedbackKindSchema = z3.enum([
|
|
1343
1352
|
"break_down",
|
|
1344
1353
|
// "This should be more than one ask — break it down."
|
|
1345
1354
|
"regenerate_options",
|
|
@@ -1353,46 +1362,27 @@ var NotificationFeedbackKindSchema = z2.enum([
|
|
|
1353
1362
|
"other"
|
|
1354
1363
|
// anything else — the note carries it.
|
|
1355
1364
|
]);
|
|
1356
|
-
var NotificationFeedbackSchema =
|
|
1357
|
-
notificationId:
|
|
1365
|
+
var NotificationFeedbackSchema = z3.object({
|
|
1366
|
+
notificationId: z3.string(),
|
|
1358
1367
|
kind: NotificationFeedbackKindSchema,
|
|
1359
1368
|
/** Optional free-text elaboration for a preset; required (non-empty) for 'other'. */
|
|
1360
|
-
note:
|
|
1369
|
+
note: z3.string().trim().max(2e3).optional()
|
|
1361
1370
|
}).superRefine((r, ctx) => {
|
|
1362
1371
|
if (r.kind === "other" && !r.note)
|
|
1363
|
-
ctx.addIssue({ code:
|
|
1372
|
+
ctx.addIssue({ code: z3.ZodIssueCode.custom, path: ["note"], message: "note is required for 'other' feedback" });
|
|
1364
1373
|
});
|
|
1365
|
-
var FeedbackResolutionSchema =
|
|
1366
|
-
var FeedbackOutcomeSchema =
|
|
1374
|
+
var FeedbackResolutionSchema = z3.enum(["broker_fixed", "sent_to_agent"]);
|
|
1375
|
+
var FeedbackOutcomeSchema = z3.object({
|
|
1367
1376
|
resolution: FeedbackResolutionSchema,
|
|
1368
1377
|
transform: TransformSchema,
|
|
1369
|
-
message:
|
|
1370
|
-
childIds:
|
|
1371
|
-
});
|
|
1372
|
-
var CONTACT_SCHEMA = contactSchemaFrom({
|
|
1373
|
-
ask: NotifyRequestFields.shape.ask,
|
|
1374
|
-
waiting: NotifyRequestFields.shape.waiting,
|
|
1375
|
-
options: NotifyRequestFields.shape.options,
|
|
1376
|
-
channel: NotifyRequestFields.shape.channel,
|
|
1377
|
-
parentId: NotifyRequestFields.shape.parentId,
|
|
1378
|
-
workId: NotifyRequestFields.shape.workId
|
|
1378
|
+
message: z3.string(),
|
|
1379
|
+
childIds: z3.array(z3.string()).optional()
|
|
1379
1380
|
});
|
|
1380
1381
|
|
|
1381
1382
|
export {
|
|
1382
1383
|
mcpInputSchema,
|
|
1383
|
-
|
|
1384
|
-
CREATE_GOAL_DESCRIPTION,
|
|
1385
|
-
CONTACT_DESCRIPTION,
|
|
1386
|
-
CHECK_REPLIES_DESCRIPTION,
|
|
1387
|
-
SCHEDULE_CALLBACK_DESCRIPTION,
|
|
1388
|
-
SEARCH_THREADS_DESCRIPTION,
|
|
1389
|
-
SET_WORK_STATE_DESCRIPTION,
|
|
1384
|
+
AGENT_TOOLS,
|
|
1390
1385
|
serverInstructions,
|
|
1391
|
-
SetTaskStateSchema,
|
|
1392
|
-
SetWorkStateSchema,
|
|
1393
|
-
ScheduleCallbackSchema,
|
|
1394
|
-
HandoffSchema,
|
|
1395
1386
|
WAKE_EVENT,
|
|
1396
|
-
wakeChannel
|
|
1397
|
-
CONTACT_SCHEMA
|
|
1387
|
+
wakeChannel
|
|
1398
1388
|
};
|