@rubytech/taskmaster 1.14.2 → 1.16.1

package/dist/agents/workspace-migrations.js

@@ -285,6 +285,352 @@ async function patchBeagleSkillRename(agentsPath, content) {
         return null;
     return content.replaceAll("zanzi-taxi", "beagle-zanzibar");
 }
+// ---------------------------------------------------------------------------
+// Migration: Beagle Zanzibar — prescribed ride request workflow (v1.14)
+// ---------------------------------------------------------------------------
+//
+// The old "## Ride Request Flow" was a brief summary that left the agent
+// guessing at tool calls. Replaced with a 12-step prescribed workflow with
+// explicit tool invocations at each stage.
+const OLD_RIDE_FLOW_HEADER = "## Ride Request Flow";
+const NEW_RIDE_WORKFLOW_HEADER = "## Ride Request Workflow";
+const BEAGLE_RIDE_WORKFLOW = `## Ride Request Workflow
+
+This is a **prescribed workflow**. When a tourist requests a ride, execute every step in order. Do not stop, skip, or defer any step. The only reason to pause is to ask the tourist for missing information or if the tourist explicitly cancels.
+
+### Step 1 — Capture the request
+
+Gather: pickup location, destination, date/time, number of passengers. If the tourist gave everything in one message, proceed immediately. If anything is missing, ask — then resume from Step 2 when they reply.
+
+### Step 2 — Check knowledge base
+
+Call \`memory_search\` for the route. Note the fare range and journey time if found. If the route is not covered, note that — but proceed to Step 3 regardless. Never stop here.
+
+### Step 3 — Get the driver roster
+
+Call \`contact_lookup\` with \`driver: true\`. This returns all registered drivers.
+
+### Step 4 — Check driver availability
+
+For each driver returned in Step 3, call \`memory_get\` on \`memory/drivers/{name}.md\` to read their current \`status\`. Collect a list of drivers whose status is \`idle\`. Skip any driver whose status is \`awaiting_response\` or \`engaged\`.
+
+### Step 5 — Contact drivers
+
+For up to 3 idle drivers from Step 4, call \`message\` to send each a negotiation request in Swahili. Include: the route, pickup time, number of passengers, and the job ID (\`[BGL-XXXX]\`). Before each send, call \`memory_write\` to set that driver's status to \`awaiting_response\`.
+
+If no idle drivers are available, tell the tourist honestly and offer to try again later. This is the only permitted early exit other than tourist cancellation.
+
+### Step 6 — Notify the tourist
+
+After sending all driver messages, respond to the tourist: confirm you've contacted drivers and are waiting for quotes. Do not send this message before completing Steps 3–5.
+
+### Step 7 — Present offers
+
+When drivers respond with quotes, present up to 3 competing offers: fare, driver rating, vehicle type, estimated journey time. No driver personal details at this stage. See \`references/ride-matching.md\` for formatting.
+
+### Step 8 — Confirm booking
+
+When the tourist chooses an offer, confirm the details and generate a Stripe payment link for the booking fee. See \`references/ride-matching.md\` Phase 4.
+
+### Step 9 — Post-payment
+
+Once payment clears, send the tourist: driver name, phone number, vehicle details, plate number, and the pickup PIN. Send the driver: passenger details, pickup location, fare, and QR code. See \`references/pin-qr.md\`.
+
+### Step 10 — Record the booking
+
+Call \`memory_write\` to create a structured record at \`memory/bookings/{job-id}.md\`. Update at each lifecycle event. See \`references/ride-matching.md\` Phase 7.
+
+### Step 11 — Driver reminders
+
+For advance bookings, send tiered reminders via \`message\` (evening-before, 2-hour, 30-minute). Escalate immediately if a driver doesn't confirm. See \`references/ride-matching.md\` Phase 6.
+
+### Step 12 — Follow up
+
+After estimated journey completion, prompt the tourist for feedback and collect ratings. See \`references/post-ride.md\`.`;
+async function patchBeagleRideWorkflow(_agentsPath, content) {
+    if (!isBeaglePublicAgent(content))
+        return null;
+    // Already migrated?
+    if (content.includes(NEW_RIDE_WORKFLOW_HEADER))
+        return null;
+    // Old section not present?
+    if (!content.includes(OLD_RIDE_FLOW_HEADER))
+        return null;
+    // Find the old section boundaries: from "## Ride Request Flow" to the next "---"
+    const startIdx = content.indexOf(OLD_RIDE_FLOW_HEADER);
+    const separatorIdx = content.indexOf("\n---", startIdx + OLD_RIDE_FLOW_HEADER.length);
+    if (separatorIdx === -1)
+        return null;
+    return content.slice(0, startIdx) + BEAGLE_RIDE_WORKFLOW + content.slice(separatorIdx);
+}
+// ---------------------------------------------------------------------------
+// Migration: Narrow escalation clause (v1.14)
+// ---------------------------------------------------------------------------
+//
+// "Anything you're uncertain about" in escalation sections gives public agents
+// a blanket excuse to defer any uncomfortable moment (including closing a sale).
+// Replaced with a specific, bounded criterion.
+const BLANKET_ESCALATION = "Anything you're uncertain about";
+const NARROW_ESCALATION = "Technical questions you cannot answer from memory or product knowledge";
+function hasBlanketEscalation(content) {
+    return content.toLowerCase().includes(BLANKET_ESCALATION.toLowerCase());
+}
+async function patchEscalationClause(_agentsPath, content) {
+    if (!isPublicAgent(content))
+        return null;
+    if (!hasBlanketEscalation(content))
+        return null;
+    // Replace all case-insensitive occurrences of the blanket clause
+    return content.replace(new RegExp(BLANKET_ESCALATION.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "gi"), NARROW_ESCALATION);
+}
+// ---------------------------------------------------------------------------
+// Migration: Beagle Zanzibar — Dispatch-based workflow (v1.15)
+// ---------------------------------------------------------------------------
+//
+// Replaces the 12-step workflow that used `contact_lookup` and `message`
+// directly with a 10-step dispatch-based workflow. The public agent now
+// writes dispatch files; the admin agent handles privileged operations.
+const DISPATCH_WORKFLOW_MARKER = "shared/dispatch/";
+const BEAGLE_DISPATCH_WORKFLOW = `## Ride Request Workflow
+
+This is a **prescribed workflow**. When a tourist requests a ride, execute every step in order. Do not stop, skip, or defer any step. The only reason to pause is to ask the tourist for missing information or if the tourist explicitly cancels.
+
+### Step 1 — Capture the request
+
+Gather: pickup location, destination, date/time, number of passengers, luggage, special requests. If the tourist gave everything in one message, proceed immediately. If anything is missing, ask — then resume from Step 2 when they reply.
+
+### Step 2 — Check knowledge base
+
+Call \`memory_search\` for the route. Note the fare range and journey time if found. If the route is not covered, note that — but proceed to Step 3 regardless. Never stop here.
+
+### Step 3 — Generate job ID
+
+Create a booking job ID in the format \`BGL-XXXX\` (e.g. \`BGL-0042\`). Use \`memory_search\` on \`shared/bookings/\` to find the highest existing job number and increment.
+
+### Step 4 — Dispatch trip request
+
+Write a dispatch file via \`memory_write\` to \`shared/dispatch/{job-id}-trip-request.md\` with the following format:
+
+\\\`\\\`\\\`
+# Dispatch: Trip Request
+job_id: BGL-XXXX
+phase: trip-request
+tourist_phone: +XXXXXXXXXXX
+tourist_name: [name if given]
+pickup: [pickup location]
+destination: [destination]
+date: [date]
+time: [time]
+passengers: [count]
+luggage: [description]
+special_requests: [any requests or "none"]
+fare_estimate: [range from knowledge base or "unknown"]
+account_id: [your account ID]
+\\\`\\\`\\\`
+
+### Step 5 — Notify the tourist
+
+After writing the dispatch file, tell the tourist: "I'm reaching out to our drivers now. I'll have quotes for you shortly." Do not send this before writing the dispatch file.
+
+### Step 6 — Present offers
+
+When driver offers appear in your conversation (injected by the operations agent), present up to 3 competing offers to the tourist: fare, driver rating, vehicle type, estimated journey time. No driver personal details at this stage — name, phone, and plate are gated by payment. See \`references/ride-matching.md\` for formatting.
+
+### Step 7 — Confirm booking
+
+When the tourist chooses an offer, confirm the details and write a booking confirmation dispatch via \`memory_write\` to \`shared/dispatch/{job-id}-booking-confirm.md\`.
+
+### Step 8 — Payment
+
+The operations agent will generate a Stripe payment link and send it directly to the tourist. Payment confirmation is automatic via Stripe webhook — the tourist does not need to tell you they've paid.
+
+### Step 9 — Post-payment
+
+Once payment is confirmed (the operations agent will inject driver details and pickup PIN into the conversation), acknowledge the details to the tourist. Explain the PIN verification process.
+
+### Step 10 — Record and follow up
+
+After estimated journey completion, prompt the tourist for feedback and collect ratings. See \`references/post-ride.md\`.`;
+async function patchBeaglePublicDispatchWorkflow(_agentsPath, content) {
+    if (!isBeaglePublicAgent(content))
+        return null;
+    // Already migrated to dispatch model?
+    if (content.includes(DISPATCH_WORKFLOW_MARKER))
+        return null;
+    // Must have the old workflow to replace
+    if (!content.includes(NEW_RIDE_WORKFLOW_HEADER))
+        return null;
+    // Find the workflow section boundaries
+    const startIdx = content.indexOf(NEW_RIDE_WORKFLOW_HEADER);
+    if (startIdx === -1)
+        return null;
+    // Find the end: next "---" separator or "## " heading at same level
+    const afterHeader = startIdx + NEW_RIDE_WORKFLOW_HEADER.length;
+    const nextSeparator = content.indexOf("\n---", afterHeader);
+    const nextH2 = content.indexOf("\n## ", afterHeader);
+    let endIdx;
+    if (nextSeparator !== -1 && (nextH2 === -1 || nextSeparator < nextH2)) {
+        endIdx = nextSeparator;
+    }
+    else if (nextH2 !== -1) {
+        endIdx = nextH2;
+    }
+    else {
+        endIdx = content.length;
+    }
+    return content.slice(0, startIdx) + BEAGLE_DISPATCH_WORKFLOW + content.slice(endIdx);
+}
+// ---------------------------------------------------------------------------
+// Migration: Beagle Zanzibar — Public agent tools dispatch (v1.15)
+// ---------------------------------------------------------------------------
+//
+// Replaces the public agent's tools table to remove `contact_lookup` and
+// `message`. These are now handled by the admin agent via dispatch.
+const DISPATCH_TOOLS_MARKER = "dispatch requests";
+const BEAGLE_DISPATCH_TOOLS_SECTION = `## Tools
+
+| Tool | Use |
+|------|-----|
+| \`memory_search\` | Find bookings, knowledge base content |
+| \`memory_get\` | Read specific files (bookings, knowledge base) |
+| \`memory_write\` | Write dispatch requests, update booking state, store tourist preferences |
+| \`memory_save_media\` | Save media files sent by tourists |
+| \`web_search\` | Search the web for tourist queries |
+| \`web_fetch\` | Fetch web content |
+| \`current_time\` | Timestamps for booking records |
+
+You do not have \`message\` or \`contact_lookup\` tools. Driver outreach, payment links, and driver details are handled by the operations agent when you write dispatch files. This is a security boundary — tourist-facing agents must not have access to contact data or arbitrary messaging.`;
+async function patchBeaglePublicToolsDispatch(_agentsPath, content) {
+    if (!isBeaglePublicAgent(content))
+        return null;
+    // Already migrated?
+    if (content.includes(DISPATCH_TOOLS_MARKER))
+        return null;
+    // Must have a ## Tools section to replace
+    if (!content.includes("## Tools"))
+        return null;
+    // Find the tools section
+    const toolsStart = content.indexOf("## Tools");
+    if (toolsStart === -1)
+        return null;
+    // Find end of tools section: next "---" or next "## " heading
+    const afterTools = toolsStart + "## Tools".length;
+    const nextSeparator = content.indexOf("\n---", afterTools);
+    const nextH2 = content.indexOf("\n## ", afterTools);
+    let endIdx;
+    if (nextSeparator !== -1 && (nextH2 === -1 || nextSeparator < nextH2)) {
+        endIdx = nextSeparator;
+    }
+    else if (nextH2 !== -1) {
+        endIdx = nextH2;
+    }
+    else {
+        endIdx = content.length;
+    }
+    return content.slice(0, toolsStart) + BEAGLE_DISPATCH_TOOLS_SECTION + content.slice(endIdx);
+}
+// ---------------------------------------------------------------------------
+// Migration: Beagle Zanzibar — Admin dispatch instructions (v1.15)
+// ---------------------------------------------------------------------------
+//
+// Adds the "Ride Dispatch Processing" section to the admin agent and
+// the `message` tool to its tools table.
+const ADMIN_DISPATCH_MARKER = "## Ride Dispatch Processing";
+const BEAGLE_ADMIN_DISPATCH_SECTION = `## Ride Dispatch Processing
+
+Messages prefixed with \`[System: Ride Dispatch — ...]\` are automated dispatches from the ride-dispatch hook. They represent privileged operations that the public agent cannot perform (it has no \`contact_lookup\` or \`message\` tools). Process each dispatch type as instructed.
+
+### Trip Request
+
+When you receive \`[System: Ride Dispatch — Trip Request]\`:
+
+1. Call \`contact_lookup\` to get the driver roster
+2. For each driver, call \`memory_get\` on \`drivers/{name}.md\` to check their status
+3. Select up to 3 idle drivers, preferring those with route history for the requested route
+4. For each selected driver:
+   - Update their status to \`awaiting_response\` via \`memory_write\`
+   - Write \`shared/active-negotiations/{driver-phone-digits}.md\` with \`job_id\`, \`driver_name\`, and \`contacted_at\`
+5. Message each driver in Swahili via the \`message\` tool with route details, pickup time, passengers, and job ID
+6. Message the tourist confirming drivers have been contacted and quotes are being gathered
+7. When driver replies arrive (dispatched as \`[System: Ride Dispatch — Driver Reply]\`), compile offers
+8. Message the tourist with up to 3 competing offers — fare, rating, vehicle type, journey time. Do NOT reveal driver name, phone, or plate (gated by payment)
+
+### Booking Confirmation
+
+When you receive \`[System: Ride Dispatch — Booking Confirmation]\`:
+
+1. Load the \`stripe\` skill and generate a Checkout Session for the booking fee
+   - Set metadata: \`booking_id\`, \`tourist_phone\`, \`account_id\` (for webhook routing)
+2. Message the tourist with the payment link and booking terms
+3. Record booking details in \`shared/bookings/{job-id}.md\` via \`memory_write\`
+4. Clear \`shared/active-negotiations/{phone}.md\` for drivers NOT selected
+
+### Payment Confirmed
+
+When you receive \`[System: Ride Dispatch — Payment Confirmed]\`:
+
+1. Read the booking record at \`shared/bookings/{job-id}.md\` for driver details
+2. Generate the pickup PIN and QR code (see \`references/pin-qr.md\`)
+3. Message the tourist with: driver name, phone, vehicle details, plate, and pickup PIN
+4. Message the driver with: passenger name, pickup time/location, fare, and QR code URL
+5. Update the booking record status to \`confirmed\`
+6. Clear the active negotiation file for the confirmed driver
+
+### Driver Reply
+
+When you receive \`[System: Ride Dispatch — Driver Reply]\`:
+
+Process the driver's message in the context of the ongoing negotiation. If it's a fare quote, note it. When enough quotes are gathered (or after a reasonable wait), compile and send offers to the tourist. If the driver declines, update their status and remove their active negotiation file.
+
+### Active Negotiation Index
+
+When contacting drivers, write \`shared/active-negotiations/{phone-digits}.md\` for each:
+
+\\\`\\\`\\\`
+job_id: BGL-XXXX
+driver_name: [name]
+contacted_at: [timestamp]
+\\\`\\\`\\\`
+
+Clear these files when:
+- A driver declines or is not selected
+- The booking is confirmed (keep only the selected driver's file until pickup completes)
+- A negotiation expires with no response
+
+This index enables the hook to route driver WhatsApp replies to the correct ride session without requiring drivers to include job IDs in their messages.`;
+const ADMIN_MESSAGE_TOOL_ROW = `| \`message\` | Send WhatsApp messages to drivers and tourists (ride dispatch, reminders, payment links) |`;
+async function patchBeagleAdminDispatchInstructions(_agentsPath, content) {
+    if (!isBeagleTaxiAdmin(content))
+        return null;
+    // Already migrated?
+    if (content.includes(ADMIN_DISPATCH_MARKER))
+        return null;
+    let result = content;
+    // Add `message` tool if not present
+    if (!result.includes("`message`")) {
+        const sessionsListRow = "| `sessions_list`";
+        const idx = result.indexOf(sessionsListRow);
+        if (idx !== -1) {
+            result = result.slice(0, idx) + ADMIN_MESSAGE_TOOL_ROW + "\n" + result.slice(idx);
+        }
+    }
+    // Insert dispatch section before "## Operational Focus Areas"
+    const insertBefore = "## Operational Focus Areas";
+    const idx = result.indexOf(insertBefore);
+    if (idx !== -1) {
+        result =
+            result.slice(0, idx) + BEAGLE_ADMIN_DISPATCH_SECTION + "\n\n---\n\n" + result.slice(idx);
+    }
+    else {
+        result = result.trimEnd() + "\n\n---\n\n" + BEAGLE_ADMIN_DISPATCH_SECTION + "\n";
+    }
+    // Update boundaries: remove "Interact with tourists directly" if present
+    const oldBoundary = "- Interact with tourists directly\n";
+    if (result.includes(oldBoundary)) {
+        result = result.replace(oldBoundary, "- Message tourists outside of ride dispatch processing (dispatch messages are sent on behalf of the system, not as conversational interaction)\n");
+    }
+    return result;
+}
 const MIGRATIONS = [
     { name: "skill-recommendations", apply: patchSkillRecommendations },
     { name: "owner-learning", apply: patchOwnerLearning },
@@ -294,6 +640,11 @@ const MIGRATIONS = [
     { name: "beagle-driver-substitution", apply: patchBeagleDriverSubstitution },
     { name: "beagle-public-tools", apply: patchBeaglePublicTools },
     { name: "beagle-skill-rename", apply: patchBeagleSkillRename },
+    { name: "beagle-ride-workflow", apply: patchBeagleRideWorkflow },
+    { name: "narrow-escalation", apply: patchEscalationClause },
+    { name: "beagle-public-dispatch-workflow", apply: patchBeaglePublicDispatchWorkflow },
+    { name: "beagle-public-tools-dispatch", apply: patchBeaglePublicToolsDispatch },
+    { name: "beagle-admin-dispatch-instructions", apply: patchBeagleAdminDispatchInstructions },
 ];
 /**
  * Run all workspace migrations for every configured agent.

package/dist/build-info.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.14.2",
-  "commit": "f271b744c2d7ecc57dd62feadb9187cbc128b875",
-  "builtAt": "2026-03-04T07:40:11.872Z"
+  "version": "1.16.1",
+  "commit": "cefc01b75d3ff0790f81d413cbc5273afa2af452",
+  "builtAt": "2026-03-04T17:39:48.836Z"
 }

package/dist/config/agent-tools-reconcile.js

@@ -19,6 +19,12 @@ function isAdminAgent(agent) {
     const id = agent.id?.trim() ?? "";
     return id === "admin" || id.endsWith("-admin");
 }
+/** Tools that must be removed from Beagle public agents (privilege separation). */
+const BEAGLE_PUBLIC_RESTRICTED_TOOLS = ["message", "contact_lookup", "group:contacts"];
+function isBeaglePublicAgent(agent) {
+    const id = (agent.id ?? "").trim().toLowerCase();
+    return id.includes("beagle") && id.endsWith("-public");
+}
 /**
  * Ensure admin agents use `group:contacts` instead of individual contact tools.
  *
@@ -118,3 +124,76 @@ export function reconcileStaleToolEntries(params) {
     }
     return { config, changes };
 }
+/**
+ * Add `qr_generate` to any agent whose explicit allow list contains `document_to_pdf`.
+ *
+ * Both tools are in `group:documents`. Agents that reference the group by name already
+ * receive `qr_generate` automatically. Agents with explicit allow lists do not — this
+ * reconciliation patches them on gateway startup.
+ *
+ * Idempotent — skips agents that already have `qr_generate`.
+ */
+export function reconcileQrGenerateTool(params) {
+    const config = structuredClone(params.config);
+    const changes = [];
+    const agents = config.agents?.list;
+    if (!Array.isArray(agents))
+        return { config, changes };
+    for (const agent of agents) {
+        if (!agent)
+            continue;
+        const allow = agent.tools?.allow;
+        if (!Array.isArray(allow))
+            continue;
+        // Only patch agents that explicitly have document_to_pdf and lack qr_generate
+        if (!allow.includes("document_to_pdf"))
+            continue;
+        if (allow.includes("qr_generate"))
+            continue;
+        const idx = allow.indexOf("document_to_pdf");
+        allow.splice(idx + 1, 0, "qr_generate");
+        changes.push(`Added qr_generate to agent "${agent.id ?? "<unnamed>"}" tools.allow.`);
+    }
+    return { config, changes };
+}
+/**
+ * Remove privileged tools (`message`, `contact_lookup`, `group:contacts`) from
+ * Beagle public agent allow lists.
+ *
+ * The public agent dispatches ride requests via memory files; the admin agent
+ * handles all privileged operations. Keeping `message` or contact tools on the
+ * public agent exposes driver PII to prompt injection.
+ *
+ * Runs unconditionally on gateway startup. Idempotent — skips agents that
+ * don't have any restricted tools.
+ */
+export function reconcileBeaglePublicTools(params) {
+    const config = structuredClone(params.config);
+    const changes = [];
+    const agents = config.agents?.list;
+    if (!Array.isArray(agents))
+        return { config, changes };
+    for (const agent of agents) {
+        if (!agent || !isBeaglePublicAgent(agent))
+            continue;
+        const allow = agent.tools?.allow;
+        if (!Array.isArray(allow))
+            continue;
+        for (const tool of BEAGLE_PUBLIC_RESTRICTED_TOOLS) {
+            const idx = allow.indexOf(tool);
+            if (idx !== -1) {
+                allow.splice(idx, 1);
+                changes.push(`Removed ${tool} from agent "${agent.id}" tools.allow (privilege separation).`);
+            }
+        }
+        // Also remove individual contact tools that might have been added directly
+        for (const tool of INDIVIDUAL_CONTACT_TOOLS) {
+            const idx = allow.indexOf(tool);
+            if (idx !== -1) {
+                allow.splice(idx, 1);
+                changes.push(`Removed ${tool} from agent "${agent.id}" tools.allow (privilege separation).`);
+            }
+        }
+    }
+    return { config, changes };
+}