@rubytech/taskmaster 1.18.2 → 1.19.1

package/templates/beagle-zanzibar/agents/admin/AGENTS.md

@@ -12,6 +12,11 @@ Before doing anything else:
 1. Read `SOUL.md` — this is who you are
 2. Read `IDENTITY.md` — your role and boundaries
 3. Check memory for recent bookings, driver issues, and any pending follow-ups
+4. Ensure the stall-detection cron job is configured — call `cron` with action: `list` and check for a job named "Ride Booking Stall Check". If it does not exist, create it:
+   - action: `add`, name: `Ride Booking Stall Check`, schedule: `*/10 * * * *` (every 10 minutes)
+   - sessionTarget: `isolated`, wakeMode: `next-heartbeat`
+   - message: `Run the ride booking stall check.`
+   - deliver: false (operator does not need a notification unless a stall is found)
 
 ## Tools
 
@@ -64,61 +69,124 @@ response_rate: 0
 
 ## 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.
+Messages prefixed with `[System: Ride Dispatch — ...]` are automated dispatches from the ride-dispatch hook. Each message contains fully prescriptive steps — follow them exactly. The steps in this section are a reference summary; the message body is authoritative.
+
+### Shared File Locations
+
+All cross-agent state flows through structured files. Never rely on session memory to recover data another agent should provide.
+
+| File | Written by | Read by |
+|------|-----------|---------|
+| `shared/dispatch/{jobId}-trip-request.md` | Public agent | Hook → Admin |
+| `shared/dispatch/{jobId}-booking-confirm.md` | Public agent | Hook → Admin |
+| `shared/active-negotiations/{phone-digits}.md` | Admin | Hook (driver reply routing) |
+| `shared/offers/{jobId}.md` | Admin | Public agent (when tourist selects) |
+| `shared/bookings/{jobId}.md` | Admin | Admin (post-payment) |
+| `shared/state/{tourist-phone}-active.md` | Public agent | Public agent (job ID lookup) |
 
 ### Trip Request
 
-When you receive `[System: Ride Dispatch — Trip Request]`:
+When you receive `[System: Ride Dispatch — Trip Request]`, the message body contains step-by-step instructions. Summary:
 
-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
+1. `contact_lookup` → get all drivers
+2. `memory_get` on `drivers/{name}.md` for each → check `status` field
+3. Select up to 3 with `status: idle`, preferring route history matches
 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. When driver replies arrive (dispatched as `[System: Ride Dispatch — Driver Reply]`), compile offers
-7. Message the tourist at `tourist_phone` using the `message` tool with `accountId` from this dispatch
-   - Include up to 3 offers: fare, vehicle type, driver rating, estimated journey time
-   - Do NOT reveal driver name, phone, or plate — those are gated by payment
-   - Cross-agent echo will relay the WhatsApp message to the tourist's active session automatically
-   - Do NOT write a dispatch file for the offers — message directly
+   - `memory_write` to `drivers/{name}.md` — set `status: awaiting_response`, `current_booking: {jobId}`
+   - `memory_write` to `shared/active-negotiations/{phone-digits}.md`
+5. `message` each driver in Swahili — fare enquiry, not confirmed job (exact text in dispatch)
+6. `message` the tourist — acknowledged, waiting for quotes (exact text in dispatch)
+7. On each driver reply: record quote, then when all in (or after 5 min):
+   - `memory_write` to `shared/offers/{jobId}.md` (prescribed format below)
+   - `message` the tourist with formatted options (exact text in dispatch)
+
+**Offers file format** (`shared/offers/{jobId}.md`):
+
+```
+# Offers: BGL-XXXX
+job_id: BGL-XXXX
+status: ready
+tourist_phone: [tourist phone]
+offer_1_driver: [name]
+offer_1_phone: [digits only, no +]
+offer_1_vehicle: [vehicle type]
+offer_1_rating: [rating]
+offer_1_fare: [USD amount as number]
+offer_1_duration: [estimated minutes as number]
+offer_2_driver: [if applicable]
+offer_2_phone: [if applicable]
+offer_2_vehicle: [if applicable]
+offer_2_rating: [if applicable]
+offer_2_fare: [if applicable]
+offer_2_duration: [if applicable]
+[offer_3_* fields if applicable]
+```
+
+Sort by fare ascending. Omit fields for offers you don't have.
 
 ### Booking Confirmation
 
-When you receive `[System: Ride Dispatch — Booking Confirmation]`:
+When you receive `[System: Ride Dispatch — Booking Confirmation]`, the message body contains step-by-step instructions. Summary:
+
+1. Load the `stripe` skill. Create a Checkout Session for $2.00 USD:
+   - `success_url: https://zanzibar.beagle.taxi/booking-confirmed`
+   - `cancel_url: https://zanzibar.beagle.taxi/booking-cancelled`
+   - `metadata: booking_id, tourist_phone, account_id`
+2. `memory_write` to `shared/bookings/{jobId}.md` (prescribed format below)
+3. `message` the tourist with the payment link (exact text in dispatch)
+4. Clear `shared/active-negotiations/{phone-digits}.md` for unselected drivers; reset their `drivers/{name}.md` status to `idle`
 
-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 at `tourist_phone` using the `message` tool with the payment link and booking terms
-   - Cross-agent echo relays the message to the tourist's active session automatically
-3. Record booking details in `shared/bookings/{job-id}.md` via `memory_write`
-   - Include `tourist_phone` for post-payment messaging
-4. Clear `shared/active-negotiations/{phone}.md` for drivers NOT selected
+**Booking record format** (`shared/bookings/{jobId}.md`):
+
+```
+# Booking: BGL-XXXX
+status: payment_pending
+tourist_phone: [phone]
+tourist_name: [name]
+driver_name: [name]
+driver_phone: [digits only]
+vehicle: [vehicle type]
+plate: [plate]
+pickup: [location]
+destination: [location]
+date: [date]
+time: [time]
+fare: [USD amount]
+payment_url: [Stripe URL]
+created_at: [timestamp]
+pin:
+```
 
 ### Payment Confirmed
 
-When you receive `[System: Ride Dispatch — Payment Confirmed]`:
+When you receive `[System: Ride Dispatch — Payment Confirmed]`, the message body contains step-by-step instructions. Summary:
 
-1. Read the booking record at `shared/bookings/{job-id}.md` for driver details and `tourist_session_key`
-2. Generate the pickup PIN and QR code (see `references/pin-qr.md`)
-3. Message the tourist at `tourist_phone` (from the booking record) using the `message` tool with driver details and pickup PIN
-   - Cross-agent echo relays to the tourist's active session automatically
-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
+1. `memory_get` on `shared/bookings/{bookingId}.md` — get all driver and tourist details
+2. Generate a random 4-digit PIN (1000–9999)
+3. QR code URL: `https://api.qrserver.com/v1/create-qr-code/?size=300x300&data=PIN%3A+{pin}`
+4. `message` the tourist with driver details and PIN (exact text in dispatch)
+5. `message` the driver with the QR code image and booking details (exact text in dispatch)
+6. `memory_write` to `shared/bookings/{bookingId}.md` — set `status: confirmed`, set `pin: {pin}`
+7. `memory_write` to `shared/active-negotiations/{driver-phone-digits}.md` — empty content
 
 ### Driver Reply
 
-When you receive `[System: Ride Dispatch — Driver Reply]`:
+When you receive `[System: Ride Dispatch — Driver Reply]`, the message body contains step-by-step instructions. Summary:
+
+**If quoting a fare:**
+1. `contact_lookup` → match driver by phone digits → get name and vehicle
+2. `memory_write` to `drivers/{name}.md` — record quote under `## Quotes`
+3. Count active negotiations for this job — if all replied or 5 min elapsed:
+   - Write `shared/offers/{jobId}.md` with all quotes (format above)
+   - `message` the tourist with formatted options (exact text in dispatch — read `tourist_phone` from the offers file)
 
-1. If the driver is quoting a fare: record it in their memory profile (`memory_write` on `drivers/{name}.md`)
-2. When all expected quotes are received (or after a reasonable wait): compile the offers and message the tourist directly using the `message` tool at the `tourist_phone` from the trip-request earlier in this session — do NOT write a dispatch file
-3. If the driver is declining: update their status in memory to `idle` and delete their `shared/active-negotiations/{phone-digits}.md` file
+**If declining:**
+1. `memory_write` to `drivers/{name}.md` — set `status: idle`, `current_booking: null`
+2. `memory_write` to `shared/active-negotiations/{phone-digits}.md` — empty content
 
 ### Active Negotiation Index
 
-When contacting drivers, write `shared/active-negotiations/{phone-digits}.md` for each:
+`shared/active-negotiations/{phone-digits}.md` format:
 
 ```
 job_id: BGL-XXXX
@@ -126,17 +194,65 @@ 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.
+The hook uses this file to route incoming driver WhatsApp replies to the correct admin ride session, without requiring drivers to include the job ID in their messages. Clear by writing empty content (not deletion) when a driver declines, is not selected, or after the booking is confirmed.
 
 ---
 
 ## Operational Focus Areas
 
+### Ride Booking Stall Check
+
+When you receive `Run the ride booking stall check.` (from the stall-detection cron), execute every step below.
+
+**STEP 1 — Scan for trip requests without booking records**
+Call `memory_search` on `shared/dispatch/` for all files matching `*-trip-request.md`.
+For each job ID found, check if `shared/bookings/{jobId}.md` exists via `memory_get`.
+If the booking record exists (status: payment_pending or confirmed), this job is active — skip it.
+If no booking record, the job may be stalled — proceed to STEP 2.
+
+**STEP 2 — Classify the stall**
+For each stalled job ID:
+
+a. Read `shared/dispatch/{jobId}-trip-request.md` to get `tourist_phone`, `pickup`, `destination`, `date`, `time`, `created_at` (or use file modification time).
+
+b. If the trip request is less than 15 minutes old: skip — it may still be in progress.
+
+c. Check if `shared/offers/{jobId}.md` exists via `memory_get`.
+
+**STEP 3 — Recover (offers file exists)**
+If `shared/offers/{jobId}.md` exists, the tourist likely confirmed but the booking-confirm dispatch was never written. Recover automatically:
+- Read the offers file to get `tourist_phone` and all offer fields.
+- Assume the tourist selected Option 1 (the lowest-fare option — already sorted ascending).
+- Write `shared/dispatch/{jobId}-booking-confirm.md` via `memory_write`:
+  ```
+  # Dispatch: Booking Confirmation
+  job_id: {jobId}
+  phase: booking-confirm
+  tourist_phone: {tourist_phone from offers file}
+  tourist_name: unknown
+  selected_offer: Option 1 (auto-recovered)
+  driver_name: {offer_1_driver}
+  driver_phone: {offer_1_phone}
+  vehicle: {offer_1_vehicle}
+  fare: {offer_1_fare}
+  account_id: beagle-zanzibar
+  ```
+- This triggers the hook, which dispatches the booking confirmation to you in the ride session for that job.
+
+**STEP 4 — Alert (no offers file, job >30 minutes old)**
+If `shared/offers/{jobId}.md` does NOT exist and the trip request is >30 minutes old, the negotiation stalled before drivers responded.
+- Include this text in your response output (do NOT use the `message` tool — this is an internal alert for the operator, not an outbound WhatsApp message):
+  `STALL ALERT [{jobId}]: No driver quotes received for {pickup} → {destination} at {time}. Tourist: {tourist_phone}. Please investigate or retry.`
+- The cron job posts your response to the operator's control panel session automatically.
+
+If the job is between 15 and 30 minutes old with no offers file: no action needed — negotiations can take time.
+
+**STEP 5 — Log outcome**
+Write a brief note via `memory_write` to `shared/stall-checks/{date}.md`:
+```
+{timestamp}: Checked {N} stalled jobs. Recovered: {list of jobIds}. Alerted: {list of jobIds}. No action needed: {list of jobIds}.
+```
+
 ### Bookings
 - Booking records live at `bookings/{job-id}.md` in memory. Each tracks: route, fare, driver, status, timestamps, ratings, and any substitution flag.
 - Summarise recent booking activity: confirmed, completed, cancelled, no-shows

package/templates/beagle-zanzibar/agents/public/AGENTS.md

@@ -89,33 +89,52 @@ passengers: [count]
 luggage: [description]
 special_requests: [any requests or "none"]
 fare_estimate: [range from knowledge base or "unknown"]
-account_id: [your account ID]
+account_id: beagle-zanzibar
 ```
 
+The `account_id` must be `beagle-zanzibar` — the WhatsApp account ID. Do not use your agent ID here.
+
+Then write a second file via `memory_write` to `shared/state/{tourist-phone}-active.md`:
+
+```
+job_id: BGL-XXXX
+tourist_phone: [tourist phone]
+```
+
+This gives you a reliable, direct-read source for the job ID when the tourist confirms. Do not rely on memory search to recover the job ID later.
+
 ### 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 as a `[System: Ride Dispatch — Driver Offers]` message, 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.
+When the operations agent messages the tourist with driver quotes, the message is echoed into your conversation. It will include the job ID (e.g. `[BGL-0002]`) and up to 3 numbered options. Present the options to the tourist clearly: fare, vehicle type, driver rating, estimated journey time. No driver personal details — 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`:
+When the tourist chooses an offer:
+
+1. Call `memory_get` on `shared/state/{tourist-phone}-active.md` to get the job ID. Do not use `memory_search` — this file was written at Step 4 and contains the job ID directly.
+2. Call `memory_get` on `shared/offers/{job-id}.md` to get the full offer details (driver name, driver phone, vehicle, rating, fare, duration). This file was written by the operations agent after collecting driver quotes.
+3. Write the booking confirmation dispatch via `memory_write` to `shared/dispatch/{job-id}-booking-confirm.md`:
 
 ```
 # Dispatch: Booking Confirmation
 job_id: BGL-XXXX
 phase: booking-confirm
 tourist_phone: [same phone used in trip-request]
-tourist_name: [name]
-driver_name: [selected driver name from offer]
-driver_phone: [selected driver phone from offer]
-fare: [agreed fare]
-account_id: [your account ID]
+tourist_name: [name if known]
+selected_offer: Option 1
+driver_name: [offer_1_driver from shared/offers/{job-id}.md]
+driver_phone: [offer_1_phone from shared/offers/{job-id}.md]
+vehicle: [offer_1_vehicle from shared/offers/{job-id}.md]
+fare: [offer_1_fare from shared/offers/{job-id}.md]
+account_id: beagle-zanzibar
 ```
 
+Substitute the correct offer number (1, 2, or 3) based on the tourist's selection. All field values come directly from the offers file — do not invent or guess any driver details.
+
 ### Step 8 — Payment
 
 The operations agent will generate a Stripe payment link and relay it to your conversation as a `[System: Ride Dispatch — Payment Link]` message. Present the payment link and terms to the tourist. If the tourist has questions about payment, explain the booking fee. Payment confirmation is automatic via Stripe webhook — the tourist does not need to tell you they've paid.

package/templates/beagle-zanzibar/skills/beagle-zanzibar/cron-template.json

@@ -0,0 +1,20 @@
+{
+  "templateId": "beagle-zanzibar-stall-check",
+  "name": "Ride Booking Stall Check",
+  "description": "Monitors active ride negotiations every 10 minutes. Automatically recovers stalled bookings where the tourist confirmed but the dispatch was missed. Alerts the operator if driver quotes are not received within 30 minutes.",
+  "enabled": true,
+  "agentId": "beagle-zanzibar-admin",
+  "schedule": { "kind": "cron", "expr": "*/10 * * * *" },
+  "sessionTarget": "isolated",
+  "wakeMode": "next-heartbeat",
+  "payload": {
+    "kind": "agentTurn",
+    "message": "Run the ride booking stall check.",
+    "deliver": false,
+    "bestEffortDeliver": false
+  },
+  "isolation": {
+    "postToMainMode": "summary",
+    "postToMainPrefix": "Stall Check"
+  }
+}

package/templates/beagle-zanzibar/skills/beagle-zanzibar/references/pin-qr.md

@@ -2,7 +2,12 @@
 
 ## Overview
 
-Each confirmed booking gets a unique 4-digit pickup PIN. The tourist holds the PIN. The driver receives a QR code image that encodes it. At pickup, the tourist scans the QR code or asks the driver to read the PIN aloud — both parties should see the same number.
+Each confirmed booking gets a unique 4-digit pickup PIN. The tourist receives the PIN via WhatsApp. The driver receives a QR code image encoding it. At pickup, the tourist either:
+
+- Scans the driver's QR code — phone camera shows the PIN inline, tourist confirms it matches their message (works offline)
+- Or simply asks the driver to read the number aloud — driver reads it from the caption on their WhatsApp message
+
+Both methods require no internet and no app.
 
 ## Generating the PIN
 
@@ -16,16 +21,24 @@ pin: 4827
 
 ## Generating the QR Code Image
 
-Construct the QR image URL from the PIN:
+Encode the PIN as labelled plain text — NOT a URL. Plain text QR codes display inline in the phone camera without opening any app or requiring internet.
+
+Format:
+
+```
+PIN: {pin}
+```
+
+QR image URL:
 
 ```
-https://api.qrserver.com/v1/create-qr-code/?size=300x300&data={pin}
+https://api.qrserver.com/v1/create-qr-code/?size=300x300&data=PIN%3A+{pin}
 ```
 
 Example — PIN 4827:
-`https://api.qrserver.com/v1/create-qr-code/?size=300x300&data=4827`
+`https://api.qrserver.com/v1/create-qr-code/?size=300x300&data=PIN%3A+4827`
 
-This URL returns a PNG image of the QR code. No separate API call is needed to generate it.
+This URL returns a PNG image. When the tourist scans it, their phone camera displays `PIN: 4827` immediately — no browser, no internet needed.
 
 ## Sending to the Driver
 
@@ -35,17 +48,17 @@ Use the `message` tool to send the QR code as an inline WhatsApp image:
 action: send
 channel: whatsapp
 target: {driver_phone_number}
-media: https://api.qrserver.com/v1/create-qr-code/?size=300x300&data={pin}
-caption: [BGL-XXXX] Your passenger's verification code. Show this QR code at pickup — your passenger will scan it to confirm you're the right driver.
+media: https://api.qrserver.com/v1/create-qr-code/?size=300x300&data=PIN%3A+{pin}
+caption: [BGL-XXXX] Your pickup PIN is {pin}. When you meet your passenger, tell them this number. Say: "Your PIN is {pin}." They will confirm it matches theirs. The QR code above is a backup — they can scan it instead if they prefer.
 ```
 
-The driver opens WhatsApp, sees the QR code image inline, and shows their phone screen to the tourist at pickup.
+The PIN is included in the caption so the driver can read it aloud if the tourist prefers that.
 
 ## Sending to the Tourist
 
 Send the PIN with an explanation alongside the other driver details (in the main conversation):
 
-> "Your driver verification PIN is **{pin}**. When your driver arrives, ask them to show their QR code — scan it with your phone camera and it should display your PIN. Or ask the driver to read the number aloud. If it matches, you've got the right driver. Works offline — no internet needed."
+> "Your pickup PIN is **{pin}**. When your driver arrives, either scan their QR code (your camera will show the number instantly) or just ask them to read it out — it should match. If it does, you're in the right car."
 
 ## Timing
 

package/templates/beagle-zanzibar/skills/stripe/references/payment-links.md

@@ -34,38 +34,48 @@ line_items[0][price_data][product_data][description]={route} on {date}
 line_items[0][quantity]=1
 metadata[booking_id]={job_id}
 metadata[tourist_phone]={tourist_phone}
+metadata[account_id]={whatsapp_account_id}
 metadata[negotiated_fare]={fare_usd}
+success_url=https://zanzibar.beagle.taxi/booking-confirmed
+cancel_url=https://zanzibar.beagle.taxi/booking-cancelled
 ```
 
-The Stripe secret key is the `stripe` key stored in your API key config (`sk_test_...` for test mode, `sk_live_...` for production).
+The `stripe` API key from `api_keys` provides the secret key.
 
-The response includes a `url` field — this is the hosted checkout page to send the tourist.
+The response includes a `url` field — the hosted checkout page to send the tourist.
+
+## Metadata Fields
+
+| Field | Purpose |
+|-------|---------|
+| `booking_id` | Links payment to the booking record (`BGL-XXXX`) |
+| `tourist_phone` | For post-payment messaging (E.164 format) |
+| `account_id` | WhatsApp account ID for delivery routing |
+| `negotiated_fare` | Full fare amount (paid to driver, not via Stripe) |
+
+These metadata fields are returned in webhook events, enabling the gateway to route the payment confirmation to the correct booking workflow.
 
 ## Sending the Link
 
-Send the tourist the checkout URL with context:
+Message the tourist with the checkout URL:
 
 > "To confirm your booking, pay the $[fee] booking fee here: [url]
 > This locks in your ride. You pay $[fare] directly to your driver at the end of the journey."
 
-## Verifying Payment
-
-Before releasing driver details (Phase 5), verify the session is paid:
+## Adaptive Pricing (Local Currency Display)
 
-```
-GET https://api.stripe.com/v1/checkout/sessions/{session_id}
-Authorization: Bearer {stripe_secret_key}
-```
+Stripe's adaptive pricing is enabled by default. Tourists in the UK, EU, or other non-USD regions will see the booking fee in their local currency (e.g. £1.50 instead of $2.00 — the FX equivalent). The amount you receive is always the USD equivalent after conversion.
 
-Check `payment_status == "paid"`. If not yet paid, wait for the tourist to say they've paid — then verify. Do not take their word alone; always confirm with the API before proceeding.
+This is intentional and improves the tourist experience — no action needed. If the operator wants to force USD for all customers, they can disable it: Stripe Dashboard → Settings → Adaptive pricing → off.
 
 ## What to Store in the Booking Record
 
-Add these fields to `bookings/{job-id}.md` when the session is created and confirmed:
+Add to `shared/bookings/{job-id}.md`:
 
 ```
 stripe_session_id: cs_...
-booking_fee_usd: 2.50
-payment_status: pending   → paid (update when confirmed)
-paid_at: [timestamp from session]
+booking_fee_usd: X.XX
+payment_status: pending
 ```
+
+Update `payment_status` to `paid` and add `paid_at` timestamp when the webhook confirms payment.