@synaplink/orqlaude 0.3.2 → 0.4.0

package/dist/tools/userio.js

@@ -0,0 +1,116 @@
+import { z } from "zod";
+import { randomUUID } from "node:crypto";
+import { findPlan, findUserResponseRequest } from "../lib/state.js";
+/**
+ * Broker-to-user tools (v0.4+).
+ *
+ * The other broker tools (send_message / post_note) only connect primary
+ * Claude to spawned children. These three close the gap to the user:
+ *
+ *   notify_user           one-way push (Telegram), no response expected
+ *   request_user_response push + await; user taps a button or replies
+ *   poll_user_response    primary Claude polls for the answer
+ *
+ * Implementation: writes to plan.userNotifications / plan.userResponseRequests.
+ * The Telegram notifier (separate process, `orqlaude tg start`) detects new
+ * entries on its 5-second tick and pushes them. The bot listens for callback_query
+ * updates and writes the response back into state.
+ */
+const URGENCY = z.enum(["low", "normal", "high"]);
+export function registerUserIo(server, store, audit) {
+    // ---- notify_user ----------------------------------------------------------
+    server.tool("notify_user", "PRIMARY CLAUDE → USER (Telegram). One-way push of an arbitrary message to the user's whitelisted Telegram chats. The notifier picks it up on its next 5-second tick. Use for mid-fleet status updates the user might want to know about (e.g. 'reviewer agent flagged 3 BLOCKERs', 'agent 2 finished early', 'budget at 80%'). Doesn't await a response — pair with request_user_response if you need one.", {
+        plan_id: z.string().describe("Plan id this notification belongs to (for filtering / context)."),
+        text: z.string().min(1).max(2000).describe("The message text. Will be Markdown-escaped before send. Keep concise."),
+        urgency: URGENCY.default("normal").describe("Affects emoji prefix in the Telegram message. low → 💬, normal → 📢, high → 🚨."),
+        task_id: z.string().optional().describe("Optional: attribute the notification to a specific task in the plan."),
+    }, audit.wrap("notify_user", async ({ plan_id, text, urgency, task_id }) => {
+        const result = await store.update((state) => {
+            const plan = findPlan(state, plan_id);
+            const note = {
+                id: randomUUID(),
+                taskId: task_id,
+                text,
+                urgency,
+                createdAt: Date.now(),
+                delivered: false,
+            };
+            plan.userNotifications.push(note);
+            return {
+                plan_id,
+                notification_id: note.id,
+                queued: true,
+                delivered_via_telegram: "pending — depends on `orqlaude tg start` running with at least one whitelisted user.",
+            };
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }, ({ plan_id }) => ({ planId: plan_id })));
+    // ---- request_user_response -----------------------------------------------
+    server.tool("request_user_response", "PRIMARY CLAUDE asks the user a question via Telegram and awaits the response. If `options` is provided, the message has inline-keyboard buttons; otherwise the user is told to reply with `/respond <short_id> <text>`. Returns a `request_id` — poll it via `poll_user_response`. Times out after `timeout_sec` (default 600s = 10 min); if no response, status returns `timed_out`.", {
+        plan_id: z.string(),
+        prompt: z.string().min(1).max(2000).describe("The question to ask the user."),
+        options: z.array(z.string().min(1).max(32)).max(8).optional().describe("Optional list of button labels (≤8, each ≤32 chars). If provided, Telegram shows an inline keyboard. If omitted, freeform reply expected."),
+        timeout_sec: z.number().int().positive().max(3600).default(600).describe("Max seconds to wait. After this, poll returns `timed_out`. Default 600 (10 min); cap 3600 (1h)."),
+        task_id: z.string().optional(),
+    }, audit.wrap("request_user_response", async ({ plan_id, prompt, options, timeout_sec, task_id }) => {
+        const result = await store.update((state) => {
+            const plan = findPlan(state, plan_id);
+            const id = randomUUID();
+            const shortId = id.slice(0, 8);
+            const req = {
+                id,
+                shortId,
+                taskId: task_id,
+                prompt,
+                options,
+                createdAt: Date.now(),
+                timeoutAt: Date.now() + timeout_sec * 1000,
+                delivered: false,
+            };
+            plan.userResponseRequests.push(req);
+            return {
+                plan_id,
+                request_id: id,
+                short_id: shortId,
+                timeout_at: req.timeoutAt,
+                has_options: Boolean(options && options.length > 0),
+                next_step: "Poll `poll_user_response(request_id)` periodically. It returns status=`pending` until the user answers (or timeout). If no Telegram bot is running, the user can't respond — fall back to AskUserQuestion.",
+            };
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }, ({ plan_id }) => ({ planId: plan_id })));
+    // ---- poll_user_response ---------------------------------------------------
+    server.tool("poll_user_response", "Poll a previously-issued `request_user_response`. Returns `status: pending | answered | timed_out | cancelled` and the `response` text when answered. Safe to call repeatedly; no side effects.", {
+        request_id: z.string().describe("Either the full UUID or the 8-char short_id returned by request_user_response."),
+    }, audit.wrap("poll_user_response", async ({ request_id }) => {
+        const result = await store.read((state) => {
+            const found = findUserResponseRequest(state, request_id);
+            if (!found) {
+                return { request_id, status: "unknown", note: "No request with that id or short_id." };
+            }
+            const { req } = found;
+            if (req.cancelled)
+                return { request_id: req.id, status: "cancelled" };
+            if (req.response !== undefined) {
+                return {
+                    request_id: req.id,
+                    status: "answered",
+                    response: req.response,
+                    responded_at: req.respondedAt,
+                };
+            }
+            if (Date.now() > req.timeoutAt) {
+                return { request_id: req.id, status: "timed_out", timeout_at: req.timeoutAt };
+            }
+            return {
+                request_id: req.id,
+                status: "pending",
+                delivered: req.delivered,
+                timeout_at: req.timeoutAt,
+                remaining_sec: Math.max(0, Math.round((req.timeoutAt - Date.now()) / 1000)),
+            };
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }));
+}
+//# sourceMappingURL=userio.js.map

package/dist/tools/userio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"userio.js","sourceRoot":"","sources":["../../src/tools/userio.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synaplink/orqlaude",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Multi-agent orchestrator for Claude Code. One primary session decomposes a complex task, gets a single budget approval, then dispatches N parallel agents via the Desktop app's native spawn_task. Tracks cost/status via JSONL tails; brokers messages between agents; detects hallucination; manages PRs.",
   "type": "module",
   "bin": {