Check Orders

Process steps in order. Do not skip ahead.

You are AyeAye, Baruch's assistant. Check for order updates from Gmail and update the orders DB.

Core Rule — Never read raw Gmail into the session

Raw bodies can carry invisible-Unicode padding that blows up the context window. Step 2's fetch script fetches over native Gmail REST and sanitizes inside the container; only its sanitized stdout reaches you. Never fetch Gmail yourself from the session. Background: /workspace/group/nanoclaw-poison-defense.md.

Step 1 — Read last_checked

Orders live in orders table of /workspace/store/messages.db. Markers live in orders_metadata kv table.

python3 scripts/read-last-checked.py

Stdout: {"last_checked": "<iso>" | null} (null on fresh DB). This read is informational; fetch-order-emails.py re-reads the cursor for the after: filter and Step 3 stamps write-ahead.

Step 2 — Fetch order-related emails (sanitized, over native Gmail REST)

Query strings, cross-query dedup, in-container sanitization, compact-row projection, and the cursor-based after: filter live in the fetch script. It fetches via the native Gmail REST API — brokered by the OneCLI gateway, per Google Tool Access rule — and sanitizes before printing, so raw bodies never enter the session (Core Rule). No credential lives in this container: the gateway injects the Bearer on the wire.

python3 scripts/fetch-order-emails.py

Reads orders_metadata.last_checked and appends after:YYYY/MM/DD to each query when set (unbounded otherwise). Loads its shared helpers from tessl__heartbeat/scripts/ (sanitize-email-body.py, google-rest.py, gmail-ops.py, gmail-message.py). Stdout:

{"messages": [{"messageId": "...", "threadId": "...", "from": "...", "to": "...", "subject": "...", "snippet": "...", "body": "...", "date": "...", "labelIds": [...]}], "errors": [{"query": "...", "error": "..."}]}

messages is the sanitized, deduped input for Step 4. snippet is Gmail's short preview — it and subject are what Step 4's status rule reads. body is the full extracted text; Step 4's amount extractor reads it (order totals sit below the snippet fold — jbaruch/nanoclaw-orders#38), while the status rule stays on subject+snippet. date is ISO 8601 UTC.

Exits non-zero with no stdout (fail-closed) if a shared helper can't be loaded, if the gateway isn't injecting, or if this tier is restricted from Google — the stderr names the remediation.

Error Handling

Step 3 — Stamp cursor write-ahead

After Step 2 returns parseable JSON from a successful Gmail query, stamp orders_metadata.last_checked to current UTC:

python3 scripts/write-orders-metadata.py

Write-ahead rationale: skills/check-orders/references/write-ahead-rationale.md.

Proceed immediately to Step 4.

Step 4 — Parse each email

For source and status, run the classifier per email against the fields Step 2 handed you:

echo '{"from": "...", "subject": "...", "snippet": "..."}' | python3 scripts/classify-order.py

Stdout: {"source": "amazon" | "shopify" | "shop" | "other", "status": "shipped" | "delivered" | "cancelled" | "refunded" | "ordered" | "unknown"}. Use both values as returned. The sender-domain and keyword maps are owned by the script (jbaruch/nanoclaw-orders#44) — do not re-derive by eye.

Remaining fields:

For amount, run the extractor per email against the fields Step 2 already handed you (all sanitized — the body never re-enters from raw Gmail):

echo '{"subject": "...", "snippet": "...", "body": "..."}' | python3 scripts/extract-amount.py

Stdout: {"amount": <float>, "currency": "USD", "matched": "labeled_total" | "bare_total" | "subject_snippet_largest" | "none"}. Use the returned amount. Real order confirmations put the total only in the body below the snippet fold, so most orders resolve via a labeled total line — see the precedence in scripts/extract-amount.py (module docstring).

Step 5 — Upsert each parsed email into the orders table

Compute the id:

python3 scripts/compute-order-id.py <source> <order_date> <description>

Produces {source}-{order_date}-{hash} where hash is the first 8 hex chars of SHA-1 over UTF-8-encoded description bytes verbatim (no trimming, case-folding, or normalisation).

Pipe a single-line JSON object with the parsed fields plus the computed id:

echo '{"id": "...", "source": "...", "status": "...", "amount": 19.99, "currency": "USD", "description": "...", "order_date": "2026-04-29", "expected_delivery": null, "email_message_id": "...", "to_address": "...", "merchant": "...", "order_number": "..."}' \
  | python3 scripts/apply-order.py

Parameter-bound INSERT ... ON CONFLICT(email_message_id) DO UPDATE SET status = excluded.status, last_updated = excluded.last_updated WHERE orders.status != excluded.status. Stdout: {"action": "inserted" | "status_updated" | "noop", "id": "..."}. New rows: flagged = 0, flag_reason = NULL.

Step 6 — Apply user-preference exclusions

python3 scripts/apply-exclusions.py

The exclusion rule table and all matching logic are owned by the script — see scripts/apply-exclusions.py, EXCLUSIONS constant and module docstring. Side effect: every matched row is reset to flagged = 0, flag_reason = NULL in one transaction, parameter-bound.

Enforcement: the script's EXCLUSIONS table is the runtime-authoritative mirror of the "Do NOT flag these" list in /workspace/trusted/user_preferences.md. When that list changes, update EXCLUSIONS in the same change.

Stdout: {"excluded_ids": [...], "excluded_ids_csv": "...", "matched": <int>, "unflagged": <int>} (ids in ascending id order). Pass excluded_ids_csv verbatim as Step 9's EXCLUDED_IDS — do not recompute or edit the list.

Ad-hoc tools (outside this flow): scripts/unflag-orders.py clears the flag for a single run; the row keeps its status. To persist an owner acknowledgement that flagged orders arrived, use scripts/ack-orders.py (ids on stdin, one per line): it transitions ordered/shipped rows to assumed_delivered (Step 7's terminal status), which the stuck detector never re-flags. Stdout: {"acked": <int>, "not_acked": <int>}.

For an order the owner acknowledges as genuinely still not shipped, use scripts/snooze-orders.py. Ids on stdin, one per line; SNOOZE_UNTIL carries the canonical YYYY-MM-DD date the suppression runs until, exclusive, and is assigned to the python3 process so it survives the pipe:

printf '%s\n' <id1> <id2> | SNOOZE_UNTIL=<YYYY-MM-DD> python3 scripts/snooze-orders.py

It writes snooze_until and leaves status, flagged, and flag_reason alone; Step 8 then drops the row from stuck_ids until the window lapses. Stdout: {"snoozed": <int>, "not_snoozed": <int>, "snooze_until": "<date>"}. Accepted date shapes, eligible statuses, and the exit-2 conditions are owned by the script (module docstring).

Pick by what actually happened: arrived → ack-orders.py, still waiting → snooze-orders.py. One owner reply can need both.

Step 7 — Auto-promote stale shipped/ordered orders

Promote stale shipped/ordered rows to synthetic terminal assumed_delivered:

python3 scripts/promote-stale-shipped.py

A row promotes if it matches EITHER path. The exact thresholds are owned by scripts/promote-stale-shipped.py (module docstring + top-of-file constants):

• Expected-delivery path: status IN ('shipped', 'ordered'), an overdue expected_delivery (ISO date past the threshold, or malformed/free-text), and a stale last_updated.
• Age-ceiling path (jbaruch/nanoclaw-orders#61): an ordered row whose order_date is past the ceiling. The ceiling matches compute-stuck-orders.py's stuck-window upper bound.

Stdout: {"promoted": <int>, "ids": [...]}. Idempotent. assumed_delivered is synthetic terminal — Step 9 never flags it. Future emails still update via Step 5's merge rule.

Step 8 — Compute stuck orders

Get the ids of orders stuck in ordered with no shipment:

python3 scripts/compute-stuck-orders.py

Stdout: {"stuck_ids": ["<id>", ...]} — the ids of orders stuck in ordered with no shipment. The age window, shipment statuses, pairing rule, never-ship merchant set, and snooze-window test are all owned by scripts/compute-stuck-orders.py (module docstring + top-of-file constants). Pass the stuck_ids verbatim to Step 9 as STUCK_IDS. Proceed immediately to Step 9.

Two suppressions run inside the script and need no agent input: rows from merchants that never emit a shipment email, and rows carrying an unlapsed snooze_until (written by scripts/snooze-orders.py). The snooze column arrives with the orchestrator's state-018 migration (jbaruch/nanoclaw#917); on a database that has not applied it yet the script reads "nothing is snoozed" and runs normally.

Step 9 — Apply anomaly flagging

Flag every non-excluded row. Pass the Step 6 id list via EXCLUDED_IDS and the Step 8 stuck ids via STUCK_IDS:

EXCLUDED_IDS="<id1>,<id2>,..." STUCK_IDS="<id3>,<id4>,..." \
  python3 scripts/flag-anomalies.py

Empty EXCLUDED_IDS and empty STUCK_IDS are both fine. Stdout: {"flagged": <int>, "unflagged": <int>, "ids_flagged": [...], "ids_unflagged": [...]}.

Which statuses flag and the per-status age cutoffs are owned by scripts/flag-anomalies.py — its module-docstring rule table and _classify() are the single source of truth. The stuck-order signal is applied from STUCK_IDS verbatim; the script never re-derives it.

A row with an unlapsed snooze_until is suppressed here for every rule, not just the stuck one, and is unflagged if it was already flagged. Step 8's suppression covers only ordered rows reached by the stuck rule, so this pass is what makes a snooze hold for an overdue expected_delivery and for shipped rows.

Flow effects: each matching row gets flagged=1 plus a flag_reason; rows past their cutoff (or that no longer match) are unflagged in the same pass; rows that never matched stay unflagged. The ids_flagged list drives the Step 11 report.

Step 10 — Re-stamp orders_metadata (success-path refresh)

python3 scripts/write-orders-metadata.py

Same script as Step 3, re-run on the happy path. Idempotent. Stdout: {"last_checked": "<iso>", "last_updated": "<iso>"}.

Step 11 — Report flagged items

python3 scripts/get-flagged-orders.py | python3 scripts/render-order-alerts.py

get-flagged-orders.py emits the flagged rows as a JSON array ordered by order_date descending, collapsing rows that share a (source, order_number) logical order to one; render-order-alerts.py HTML-escapes every field (description derives from sender-controlled email text) and emits {"message": <str|null>, "count": <int>}. message is the complete Telegram HTML text — one bullet per order, shaped:

<b>📦 Order alerts:</b>

• <b>[description]</b> — [flag_reason] (<i>[merchant or source], [order_date]</i>)

message: null → no flagged orders → stay silent. Otherwise send the message value verbatim via mcp__nanoclaw__send_message — never rebuild or reformat it by hand; the escaping is what keeps a hostile subject line from breaking the Telegram HTML parse or injecting tags. Finish here.