@rubytech/taskmaster 1.27.0 → 1.28.1

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

@@ -17,6 +17,11 @@ Before doing anything else:
    - 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)
+5. Ensure the booking lifecycle cron job is configured — call `cron` with action: `list` and check for a job named "Booking Lifecycle Check". If it does not exist, create it:
+   - action: `add`, name: `Booking Lifecycle Check`, schedule: `*/10 * * * *` (every 10 minutes)
+   - sessionTarget: `isolated`, wakeMode: `next-heartbeat`
+   - message: `Run the booking lifecycle check.`
+   - deliver: false
 
 ## Tools
 
@@ -59,6 +64,7 @@ rating_knowledge: -
 rating_punctuality: -
 trips_completed: 0
 response_rate: 0
+standing: 0
 
 ## Route History
 (builds from booking data)
@@ -80,6 +86,7 @@ All cross-agent state flows through structured files. Never rely on session memo
 | `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/active-bookings/{driver-phone-digits}.md` | Admin | Hook (post-booking 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) |
@@ -152,9 +159,15 @@ destination: [location]
 date: [date]
 time: [time]
 fare: [USD amount]
+duration: [estimated journey minutes from shared/offers/{jobId}.md]
 payment_url: [Stripe URL]
 created_at: [timestamp]
 pin:
+reminder_sent_at:
+acknowledgement_at:
+tourist_checkin_sent_at:
+estimated_arrival:
+rating_requested_at:
 ```
 
 ### Payment Confirmed
@@ -167,7 +180,8 @@ When you receive `[System: Ride Dispatch — Payment Confirmed]`, the message bo
 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
+7. `memory_write` to `shared/active-negotiations/{driver-phone-digits}.md` — empty content (clears negotiation routing)
+8. `memory_write` to `shared/active-bookings/{driver-phone-digits}.md` — routing index for post-booking driver messages
 
 ### Driver Reply
 
@@ -184,6 +198,30 @@ When you receive `[System: Ride Dispatch — Driver Reply]`, the message body co
 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
 
+### Driver Message (Post-Booking)
+
+When you receive `[System: Ride Dispatch — Driver Message]`, the driver has messaged during a confirmed booking (after payment, before journey completion). The message body contains step-by-step instructions. Interpret the message and act:
+
+STEP 1 — Read the booking record
+`memory_get` on `shared/bookings/{jobId}.md` to load all booking fields (tourist_phone, driver_name, destination, duration, acknowledgement_at, etc.).
+
+STEP 1.5 — Record driver acknowledgement
+If `acknowledgement_at` is empty in the booking record, set it now:
+`memory_write` to `shared/bookings/{jobId}.md` — set `acknowledgement_at: [current_time]`.
+This marks that the driver has been in contact regarding this booking, regardless of what the message says.
+
+STEP 2 — Interpret and act on the message:
+
+- **Pickup confirmed:**
+   a. `memory_write` to `shared/bookings/{jobId}.md` — set `status: picked_up`, set `picked_up_at: [current_time]`, set `estimated_arrival: [picked_up_at + duration minutes]`.
+   b. `memory_write` to `drivers/{driver_name}.md` — add +1 to `standing`.
+   c. Call `message` with channel: "whatsapp", accountId: [WhatsApp account], to: [tourist_phone from booking record].
+      Send: "Good news — [driver_name] has confirmed they've picked you up! Enjoy your ride to [destination]."
+- **Driver running late** → message tourist with reassurance
+- **Passenger no-show** → message tourist to come to pickup point; output ALERT in response (not via message tool)
+- **Substitution request** → do NOT approve; output ALERT in response for operator decision
+- **Unclear** → interpret charitably; if genuinely ambiguous, ask driver for clarification
+
 ### Active Negotiation Index
 
 `shared/active-negotiations/{phone-digits}.md` format:
@@ -253,6 +291,46 @@ 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}.
 ```
 
+### Booking Lifecycle Check
+
+When you receive `Run the booking lifecycle check.` (from the lifecycle cron), execute every step below.
+
+**STEP 1 — Scan confirmed and picked-up bookings**
+Call `memory_search` on `shared/bookings/` for all files. For each, call `memory_get` and read `status`. Process only bookings with `status: confirmed` or `status: picked_up`.
+
+**STEP 2 — Send driver reminder (T−30 min)**
+For each `confirmed` booking where `reminder_sent_at` is empty:
+- Read `date`, `time`, `tourist_name`, `driver_phone`, `pickup`, `job_id`, `account_id`.
+- If pickup time is within 30 minutes from now:
+  - Call `message` with channel: "whatsapp", accountId: [account_id], to: [driver_phone].
+  - Send exactly: "[job_id] Your pickup is in 30 minutes — [tourist_name] at [pickup]. Please message here when you have collected your passenger. Confirming pickup improves your standing with Beagle, which means you get offered jobs first."
+  - `memory_write` to `shared/bookings/{jobId}.md` — set `reminder_sent_at: [current_time]`.
+
+**STEP 3 — Tourist check-in (T+15 min, no acknowledgement)**
+For each `confirmed` booking where `acknowledgement_at` is empty and `tourist_checkin_sent_at` is empty:
+- If pickup time was 15+ minutes ago:
+  - Call `message` with channel: "whatsapp", accountId: [account_id], to: [tourist_phone].
+  - Send exactly: "Just checking — did [driver_name] pick you up okay?"
+  - `memory_write` to `shared/bookings/{jobId}.md` — set `tourist_checkin_sent_at: [current_time]`.
+
+**STEP 4 — Auto-close (estimated arrival + 60 min)**
+For each `confirmed` or `picked_up` booking:
+- If `estimated_arrival` is set and current time is more than 60 minutes past `estimated_arrival`: auto-close.
+- If `estimated_arrival` is empty and current time is more than 60 minutes past (pickup time + duration): auto-close.
+
+Auto-close steps:
+  1. `memory_write` to `shared/bookings/{jobId}.md` — set `status: completed`, set `rating_requested_at: [current_time]`.
+  2. `memory_write` to `shared/active-bookings/{driver_phone_digits}.md` — empty content.
+  3. If `picked_up_at` is empty: `memory_write` to `drivers/{driver_name}.md` — subtract 1 from `standing` (no pickup confirmation).
+  4. Call `message` with channel: "whatsapp", accountId: [account_id], to: [tourist_phone].
+     Send: "Hope you enjoyed your ride! How was it? Was everything okay with [driver_name]?"
+
+**STEP 5 — Log outcome**
+`memory_write` to `shared/lifecycle-checks/{date}.md`:
+```
+{timestamp}: Processed {N} bookings. Reminded: {list of jobIds}. Checked-in: {list}. Closed: {list}.
+```
+
 ### 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
@@ -266,6 +344,23 @@ Write a brief note via `memory_write` to `shared/stall-checks/{date}.md`:
 - Track driver state: who is available, who is mid-negotiation, who is booked
 - Recommend deprioritising unreliable drivers
 
+### Standing Score
+
+Each driver has a `standing` field in their memory profile (starts at 0). Update it when closing bookings:
+
+| Event | Change |
+|-------|--------|
+| Driver acknowledges 30-min reminder | +1 |
+| Driver confirms pickup | +1 |
+| No acknowledgement — tourist check-in was required | −1 |
+| No pickup confirmation — job auto-closed | −1 |
+| No-show or unannounced substitution | −2 |
+
+When selecting drivers for a new trip request, rank idle candidates by:
+1. `standing` descending
+2. Average tourist rating descending (across all 5 rating dimensions)
+3. Route history match (as tiebreaker)
+
 ### Driver Substitution Follow-up
 
 When a substitution is flagged in a booking record:

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

@@ -0,0 +1,20 @@
+{
+  "templateId": "beagle-zanzibar-lifecycle-check",
+  "name": "Booking Lifecycle Check",
+  "description": "Runs every 10 minutes. Sends driver reminders 30 minutes before pickup, tourist check-ins if the driver hasn't acknowledged, and auto-closes bookings 1 hour after estimated arrival, sending a rating request.",
+  "enabled": true,
+  "agentId": "beagle-zanzibar-admin",
+  "schedule": { "kind": "cron", "expr": "*/10 * * * *" },
+  "sessionTarget": "isolated",
+  "wakeMode": "next-heartbeat",
+  "payload": {
+    "kind": "agentTurn",
+    "message": "Run the booking lifecycle check.",
+    "deliver": false,
+    "bestEffortDeliver": false
+  },
+  "isolation": {
+    "postToMainMode": "summary",
+    "postToMainPrefix": "Lifecycle Check"
+  }
+}

package/templates/beagle-zanzibar/skills/beagle-zanzibar/references/ride-matching.md

@@ -73,13 +73,13 @@ You will see these messages appear in your conversation via cross-agent echo. Ac
 
 ## Driver Pickup Reminders
 
-The operations agent handles driver reminders for advance bookings via its periodic heartbeat:
+The admin agent's Booking Lifecycle Check cron runs every 10 minutes and manages:
 
-1. **Evening before** — Reminder with pickup details, request confirmation
-2. **2 hours before** — Second reminder, request confirmation
-3. **30 minutes before** — Final reminder
+1. **30 minutes before pickup** — driver reminder via WhatsApp, asking them to message when they've collected the passenger. The reminder explains that confirming pickup improves their standing.
+2. **15 minutes after pickup (no driver acknowledgement)** — tourist check-in: "Just checking — did [driver] pick you up okay?"
+3. **Estimated arrival + 60 minutes** — auto-close: status set to `completed`, rating request sent to tourist.
 
-If a driver doesn't confirm, the operations agent escalates — attempting to reach the driver again or sourcing a replacement. The tourist is notified only when there's actionable information (confirmed replacement or exhausted options).
+Driver acknowledgement of the reminder triggers a tourist reassurance message: "[Driver name] has confirmed they're on their way."
 
 ## Booking Record
 
@@ -92,12 +92,26 @@ Every confirmed booking is recorded by the operations agent at `shared/bookings/
 - **Driver** — name, WhatsApp number, vehicle, plate
 - **Fare** — negotiated amount, booking fee amount, Stripe payment ID
 - **PIN** — the 4-digit pickup code
-- **Status** — one of: `confirmed`, `reminded`, `picked_up`, `completed`, `cancelled`, `no_show`
+- **Duration** — estimated journey minutes (from driver offer)
+- **Lifecycle timestamps** — `reminder_sent_at`, `acknowledgement_at`, `tourist_checkin_sent_at`, `estimated_arrival`, `rating_requested_at`
+- **Status** — one of: `payment_pending`, `confirmed`, `picked_up`, `completed`, `cancelled`, `no_show`
 - **Timestamps** — when each status transition occurred
 - **Rating** — post-ride ratings (added after feedback)
 
 The admin agent uses these records for operational oversight — booking summaries, driver reliability tracking, and dispute resolution.
 
+## Driver Standing
+
+Each driver has a `standing` score that affects their priority for new jobs. Standing is updated by the admin agent:
+
+- **+1** for acknowledging the 30-min reminder
+- **+1** for confirming pickup
+- **−1** for no acknowledgement (tourist check-in was required)
+- **−1** for no pickup confirmation (auto-close without confirmation)
+- **−2** for no-show or unannounced substitution
+
+When the admin selects drivers for a new trip request, candidates are ranked: standing (highest first) → average tourist rating → route history.
+
 ## Edge Cases
 
 **Tourist wants to cancel after payment:** Explain the booking fee is non-refundable (commitment device for both sides). Offer to reschedule at no extra charge.