@aitne-sh/aitne 0.1.0

package/agent-assets/task-flows/routine.hourly_check.delegated.codex.md

@@ -0,0 +1,400 @@
+{context}
+
+## Hourly Observation Review — Delegated Mode (Codex connectors)
+
+Variant of `routine.hourly_check` selected when any of Gmail /
+Google Calendar / Notion is `delegated` on the Codex backend. The
+corresponding direct-mode signal paths (`MailPoller` mail:lifecycle,
+`CalendarPoller` calendar:* + `schedule.approaching` emits, `NotionPoller`
+notion:* observations) shut off under delegation; Step 0 below restores
+coverage by fetching the same windows via MCP tools. The rest of the
+decision workflow is identical to the direct variant.
+
+> **Connector mode (Codex DM)**: `<integration_modes>` carries
+> `<key>_delegated_to="<backend>"` for delegated keys. Same-backend
+> (`=codex`) → use `mcp__codex_apps__*` natively. Cross-backend
+> (`=claude` / `=gemini`) → route through `POST
+> /api/integrations/<key>/exec` with a natural-language `task` and
+> a JSON `outputSchema`; do NOT call `mcp__codex_apps__*` for that
+> integration. The daemon enforces allowed-tools / destructive /
+> deniedTools / cost / audit and validates the JSON. The
+> `/api/notion/databases` label → UUID config dump is ungated in
+> either mode — use it before any Notion read so your `task` prose
+> carries a concrete data-source UUID.
+
+The "Vault policy files" block appended to this prompt includes
+`routines/hourly.md` — your canonical check list for this cadence.
+The "Vault review context" block includes `context-index.md` and
+`dossiers/hourly.md`; consult it before Step 1 and update the dossier's
+Open items / Last run before finishing. Writes to `dossiers/<flow>.md`
+MUST preserve the existing YAML frontmatter block (`---\ntype: dossier\nowner: agent\nupdated: <date>\n---`); prefer `PATCH` with a
+section target to mutate a single block, and when doing a `PUT` full
+rewrite keep the frontmatter and only refresh `updated:` — writes that
+drop the frontmatter are rejected with 422.
+Execute each `### <label>` entry in order, skipping any whose
+precondition does not hold. The steps below are the built-in decision
+framework for the observation-review step; additional checks the user
+has added to the routine file run alongside them using the same
+routing rules.
+
+Fetch pending user-originated observations:
+`GET /api/observations?pending=true&actor=user&limit=20`. Obsidian /
+Git always feed that table; Notion only in direct mode.
+Delegated signals arrive via Step 0 below.
+
+### Execution budget
+Target: 5–10 turns. If you reach 15 turns, wrap up current work and log.
+Do NOT read roadmap.md, projects/*.md, or user/*.md unless an
+observation warrants project-state context (e.g. references a project,
+milestone, or deliverable — not merely a file edit in a watched repo).
+
+### Default stance — silence + idempotence
+Most hourly runs are silent bookkeeping: consume observations, update
+today.md, log, done. The baseline assumption for every step below is
+that the user does NOT want another notification and does NOT want a
+new Agent Plan row unless this run has something genuinely new to add.
+The morning routine is authoritative for the day's plan; your job is
+to fold in new signals, not to re-plan. Two hard rules:
+
+- **No duplicate Agent Plan rows / schedules.** Before appending to
+  `## Agent Plan` or calling `POST /api/schedule`, run the dedup
+  pre-check in Step 4. If a matching row/schedule already exists,
+  skip and log — never add a second one.
+- **No duplicate notifications.** Before `POST /api/notify`, run the
+  dedup pre-check in Step 8. If the same item was already notified
+  earlier today, stay silent and log.
+
+When in doubt, stay silent and log to `## Agent Log`.
+
+### External services are read-only this hour
+
+This routine reads external state for context — it does not push back. While running this hourly check, do **not**:
+
+- Create / update / archive Notion pages or change Notion schema.
+- Send / draft / move / tag mail.
+- Create / update / delete calendar events.
+- Open / merge / comment on GitHub PRs or issues.
+
+External-source signals (`mail:*`, `notion:*`, `calendar:*`, `git:*`) reach you through `<observations>` and the delegated-sync-worker rows pulled in Step 0 below. Consume them, route to `today.md` / `projects/*.md` / the `roadmap_candidate` queue per the Decision Framework, but do **not** act back on the source system through the connector or the daemon `/exec` proxy. Outbound writes against external services belong in the morning routine, evening review, or DM-reply paths — `routine.hourly_check` is a silent bookkeeping pass.
+
+This rule applies regardless of integration mode (same-backend delegated, cross-backend delegated). It is owned by the routine, so a session whose `notion` / `mail` / `external-services` skill body was dropped under same-backend delegation (because the connector covers the surface) still inherits the constraint.
+
+### Decision Framework
+
+#### Step 0 — Collect delegated-mode signals (replaces lost observations)
+
+Run this step FIRST, before fetching `/api/observations`. The
+delegated-sync-worker (0a / 0c) and the calendar reconcile route (0b)
+write **real** `mail:lifecycle` / `notion:<db>` / `calendar:<id>`
+observation rows server-side, so Step 1's `/api/observations` fetch
+already includes them; Step 7's `/api/observations/consume` call still
+applies — there are no "synthetic, row-less" Step 0 signals after
+Phase 5. The only Step 0 output that does NOT flow through the
+observations table is the imminent-meeting reminder (0b → EventBus
+`schedule.approaching`), which the daemon DMs the user directly
+without a DB row.
+
+**Per-substep precondition.** Each `0[abc]` substep runs only when its
+integration is `delegated`: 0a iff `gmail="delegated"`, 0b iff
+`google_calendar="delegated"`, 0c iff `notion="delegated"`. In `direct`
+/ `disabled` mode the corresponding poller (MailPoller / CalendarPoller
+/ NotionPoller) is recording observations normally — Step 1's
+`/api/observations` call sees them. Calendar additionally restores the
+`schedule.approaching` emit path under direct mode.
+
+**0a. Recent Gmail (delegated worker owns the drift snapshot).**
+When `gmail="delegated"`, the daemon's `delegated-sync-worker` polls
+Gmail on its own cadence (~30 min default, operator-tunable) and writes
+coalesced `mail:lifecycle` observations server-side via the
+`integration_snapshots` (`inbox:7d`) partition. Drafts the agent
+created or labels the agent applied within the `integration_writes` TTL
+window are pre-tagged `actor='agent'` so Step 1's
+`GET /api/observations?actor=user` already excludes them. **Do NOT call
+`/api/integrations/gmail/reconcile` from this step** — the route's
+LLM-callable allowlist excludes the gmail partition for this reason: a
+narrow `newer_than:1d` LLM fetch posted into the worker's 7d partition
+would classify every prior 1-7d-old thread as `deleted` and trigger
+ghost observations on the next worker tick.
+
+If a downstream observation references a thread you want to read for
+deeper context (e.g. an `mail:lifecycle` row in Step 1 looks
+actionable), branch on `gmail_delegated_to`. Cross-backend reads are
+dispatched through `/exec` with a natural-language intent — the
+daemon's delegate composes the right MCP primitives whichever backend
+currently owns Gmail.
+
+```bash
+curl -sS -X POST http://localhost:8321/api/integrations/gmail/exec \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "task": "Fetch every message in Gmail thread <THREAD_ID>. For each return from / subject / body / timestamp. Sort ascending by timestamp.",
+    "outputSchema": { "type": "object", "required": ["messages"], "properties": { "messages": { "type": "array", "items": { "type": "object", "required": ["from","subject","body","ts"] } } } },
+    "maxToolCalls": 7,
+    "cacheable": true
+  }'
+```
+
+| `gmail_delegated_to` | Routing | How |
+|---|---|---|
+| `codex` | same-backend | `mcp__codex_apps__gmail._read_email_thread(threadId="<id>")` |
+| `claude` / `gemini` / custom | cross-backend | `POST /api/integrations/gmail/exec` with the task prose above |
+
+The worker's snapshot covers the actor-attribution case the legacy
+prompt used to call out: you do NOT need to cross-check the agent
+journal for prior agent writes; the daemon's `integration_writes` row
+does it for you.
+
+**0b. Calendar drift detection (replaces `calendar:*` observations AND
+the lost `schedule.approaching` emit path).** When
+`google_calendar="delegated"`, branch on `google_calendar_delegated_to`,
+run TWO fetches against the connector, and POST each result to the
+daemon's reconcile chokepoint. The chokepoint computes the structural
+diff against the prior snapshot, fires per-change side effects
+(observations, `routine.today_refresh` auto-schedule, roadmap-refresh
+trigger), and returns `{diff, sideEffects}` for you to reason over.
+Cross-backend fetches go through `/exec` with a natural-language
+`task`:
+
+```bash
+curl -sS -X POST http://localhost:8321/api/integrations/google_calendar/exec \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "task": "List every event on the primary calendar between <timeMin> and <timeMax>. Return up to <maxResults> with id, title, start, end, attendees.",
+    "outputSchema": { "type": "object", "required": ["events"], "properties": { "events": { "type": "array", "items": { "type": "object", "required": ["id","title","start","end"] } } } },
+    "cacheable": true
+  }'
+```
+
+| `google_calendar_delegated_to` | Routing | How |
+|---|---|---|
+| `codex` | same-backend | `mcp__codex_apps__google_calendar._search` |
+| `claude` / `gemini` / custom | cross-backend | `POST /api/integrations/google_calendar/exec` with the task prose above |
+
+**Gemini-specific Calendar flow** (when `google_calendar_delegated_to=gemini`):
+
+| Quirk | Effect | Workaround |
+|---|---|---|
+| `maxResults` is silently ignored | Result set bounded only by the time window + Google's per-list default | Cross-backend curl still passes `maxResults` (codex / claude honor it); accept the wider gemini result set |
+| Default `attendeeResponseStatus = ["accepted","tentative","needsAction"]` drops declined events | Declined meetings invisible | Pass `attendeeResponseStatus=["declined"]` or the full set explicitly when you need them |
+
+(The previous Gemini `updated`-field gap no longer applies under
+reconcile: the daemon hashes the normalized payload on each call and
+detects mid-horizon edits regardless of whether the connector surfaces
+`updated`.)
+
+Run TWO fetches with the same call shape, swapping only the time
+window and `maxResults`. Same-backend form (Codex shown):
+
+```
+mcp__codex_apps__google_calendar._search(
+  timeMin="<...>", timeMax="<...>",
+)
+```
+
+- **Fetch 1 — imminent meeting window**: `timeMin=now-15min`, `timeMax=now+60min`, `maxResults=50`.
+- **Fetch 2 — 24-hour change-detection window**: `timeMin=now`, `timeMax=now+24h`, `maxResults=250`.
+
+POST each result to the reconcile chokepoint. The daemon normalises
+event payloads server-side and re-hashes them to detect drift, so pass
+the raw connector items verbatim — no `contentHash`, no per-item
+hashing on your side:
+
+```bash
+# Fetch 1 — imminent (windowKey="primary:imminent")
+curl -s -X POST http://localhost:8321/api/integrations/google_calendar/reconcile \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "windowKey": "primary:imminent",
+    "windowMin": "<now-15min UTC ISO>",
+    "windowMax": "<now+60min UTC ISO>",
+    "fetchedAt": "<now UTC ISO>",
+    "items": [<raw event objects from Fetch 1>]
+  }'
+
+# Fetch 2 — 24h (windowKey="primary:24h")
+curl -s -X POST http://localhost:8321/api/integrations/google_calendar/reconcile \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "windowKey": "primary:24h",
+    "windowMin": "<now UTC ISO>",
+    "windowMax": "<now+24h UTC ISO>",
+    "fetchedAt": "<now UTC ISO>",
+    "items": [<raw event objects from Fetch 2>]
+  }'
+```
+
+Each response carries:
+
+- `diff.created` — events new to this window-key partition since the previous reconcile.
+- `diff.modified` — events whose normalised hash changed (start/end/summary/location/attendees moved).
+- `diff.deleted` — events present in the prior snapshot but absent now AND still inside the queried window. Items that simply slid out of the window are pruned silently and counted under `diff.prunedOutOfWindow`; do not treat those as deletions.
+- `diff.unchanged` — count only, no item bodies returned. Most hourly runs are mostly-unchanged.
+- `diff.isInitialSnapshot` — `true` on the first reconcile of this window-key partition (e.g. fresh install, after a clean reinstall, or after a long downtime). Treat as "no signal": skip all per-change actions for that fetch this run; the next tick returns real diffs.
+- `sideEffects.scheduleApproachingEmitted` — array of `eventId`s the daemon's imminent-event-scheduler already published to the EventBus (DM dispatch is in flight). Skip notifying these — re-notifying duplicates the user-facing reminder.
+- `sideEffects.observationsWritten` — count of `observations` rows the daemon coalesced from this diff. The downstream `/api/observations` fetch in Step 1 picks them up.
+- `sideEffects.todayRefreshScheduled` / `todayRefreshPending` — whether the daemon queued a `routine.today_refresh` (or deferred until the morning lock releases). When `true`, you should NOT also rewrite `## User Schedule` from Step 4 — the auto-refresh will own that section.
+- `sideEffects.roadmapRefreshTriggered` — whether the daemon enqueued a roadmap-refresh because a created/modified event landed beyond the 14-day horizon.
+
+Use the diff response for downstream decisions:
+
+- **Imminent (Fetch 1, ≤15 min away).** The daemon's imminent-event-scheduler emits `schedule.approaching` every 60s for any snapshot row whose `start` falls in `[now, now+15min]`. **Do NOT send a duplicate `POST /api/notify` for any `eventId` listed in `sideEffects.scheduleApproachingEmitted`** — the dispatcher is already running the DM. For events NOT in that array AND NOT already covered by a `## Agent Log` `[cal] ... — reminder sent` entry within the last hour AND NOT covered by a matching Agent Plan row firing in the next 20 minutes, fold into Step 8 trigger (b) "calendar change needing same-hour attention" for at most one `POST /api/notify`. Then append a line to `## Agent Log`: `- HH:MM [cal] "<summary>" starts HH:MM — reminder sent`.
+- **15–60 min out (Fetch 1).** Information-only; do not notify.
+- **24-hour horizon (Fetch 2).** Treat each `diff.created` / `diff.modified` / `diff.deleted` entry as a calendar observation for Steps 1–5. The daemon already wrote the matching `observations` row (counted in `sideEffects.observationsWritten`) AND, when the change lands inside today's local-day window, scheduled `routine.today_refresh` to rewrite `## User Schedule` autonomously. **Do NOT cross-reference the Fetch 2 result with `## User Schedule` text-by-text** — `diff.deleted` carries the deletion signal that the legacy text-scan used to derive, and double-rewriting User Schedule races the auto-refresh.
+
+If either fetch returns `diff.isInitialSnapshot === true`, log
+`- HH:MM [delegated-sync] calendar partition <windowKey> bootstrapped (no diff this run)` to ## Agent Log and skip the per-change actions for that fetch.
+
+**Dedup against a truncated `## Agent Log`:** if `<today>` contains
+`[...N earlier entries omitted ...]`, a prior reminder this day may be
+hidden. Before sending any notify from this step, issue
+`curl -s http://localhost:8321/api/context/today` once and scan the
+full log for the item. Do NOT skip this check — duplicate 15-min
+reminders within the same meeting are a reported UX regression.
+
+**0c. Recent Notion edits (delegated worker owns the drift snapshot).**
+When `notion="delegated"`, the daemon's `delegated-sync-worker` polls
+Notion on its own cadence (~60 min default) and writes coalesced
+`notion:<parentDatabase>` (or `notion:lifecycle` for workspace-rooted
+pages) observations server-side via the `integration_snapshots`
+(`recently_updated`) partition. The daemon hashes each page on
+`{title, lastEditedTime, parentDatabase, propertiesSummaryHash,
+relationsHash}`, so a property-only edit surfaces as `modified` even
+without a body fetch. Pages the agent wrote within the
+`integration_writes` TTL window are pre-tagged `actor='agent'` so Step
+1's `GET /api/observations?actor=user` already excludes them. **Do NOT
+call `/api/integrations/notion/reconcile` from this step** — the
+route's LLM-callable allowlist excludes the notion partition for this
+reason: a narrow `created_date_range:yesterday` LLM fetch posted into
+the worker's 7d partition would classify every prior 1-7d-old page as
+`deleted` and trigger ghost observations on the next worker tick.
+
+If a downstream observation references a page you want to fetch the
+full body for (e.g. a `notion:<db>` row in Step 1 needs context for
+routing), branch on `notion_delegated_to`. The label→UUID map is
+ungated under delegation (`/api/notion/databases` is a config dump, no
+Notion API call) and remains useful when an observation identifies a
+page by database label rather than UUID:
+
+```
+curl -s http://localhost:8321/api/notion/databases
+# → { "databases": { "tasks": "<uuid>", "projects": "<uuid>", ... } }
+```
+
+| `notion_delegated_to` | Routing | Fetch tool |
+|-----------------------|---------|------------|
+| `codex`               | same-backend | `mcp__codex_apps__notion._fetch(id="<page-url-or-uuid>")` |
+| `claude` / `gemini` / custom | cross-backend | `POST /api/integrations/notion/exec` with `{"task": "Fetch Notion page <UUID> with its block tree…", "outputSchema": …, "cacheable": true}` |
+
+**Notion delegation coverage gap** (accepted): the worker's search uses
+`created_date_range` (no `last_edited_time` filter exists upstream), so
+pages created more than 7 days ago but edited within the last hour can
+fall outside the worker's window; pages whose body / title don't match
+the worker's `"updated"` query token may rank off the first 25 results
+even when recently edited. Direct-mode `NotionPoller` covers both. If
+the user notices missed Notion updates, flip the integration back to
+`direct` mode.
+
+**0d. Log the calendar collection summary** to ## Agent Log when Step
+0b ran: `- HH:MM [delegated-sync] calendar <M> events (<K> imminent)`.
+The daemon's `delegated-sync-worker` records its own gmail / notion
+audit rows in `agent_actions` (queryable via `audit --type=delegated_sync`),
+so no prompt-side log line is needed for those. Skip this whole step
+if `google_calendar` is `direct` / `disabled` this run.
+
+#### Steps 1–9 — identical to the direct variant
+
+1. Group related observations before acting. One concise update beats many small patches.
+2. Classify each observation with a category tag: work/ folders, employer
+   repos, Notion "Work" → `[work]`; coursework, study notes → `[study]`;
+   journals, hobby repos, fitness, medical → `[personal]`; home logistics
+   → `[home]`. Default `[personal]` when ambiguous.
+3. Read the day-type filter on line 2 of <today>. Map categories to focus
+   dimensions per the today skill's "Category → focus-dimension mapping".
+   Drop observations whose focus is `off` and log:
+   `- HH:MM [observations] skipped <n> item(s): <category> focus off`.
+4. Route each surviving actionable observation to the right today.md section.
+   **Before writing a new row or scheduling anything, run the dedup
+   pre-check**:
+   - Scan `<today>` `## Agent Plan` for an existing row with HH:MM
+     within ±15 min AND overlapping subject/keywords. If found → skip
+     (log `- HH:MM [observations] skipped <item>: already planned`).
+   - Scan `<today>` `## User Tasks` for the same subject. If found →
+     skip (log `skipped: already in User Tasks`).
+   - For schedule registrations, also query:
+     `GET /api/schedule?status=pending,running` AND
+     `GET /api/recurring-schedules?enabled=true`.
+     If a pending/recurring item covers the same trigger → skip.
+
+   Only after dedup clears, route the observation:
+   - New TODO for the user → append to ## User Tasks with the row shape in the
+     context skill. Derive HH:MM from (a) deadline if known, (b) proximity
+     to a related calendar event, or (c) working-hours midpoint.
+   - New proactive reminder Claude should fire → append to ## Agent Plan AND
+     register the matching POST /api/schedule in the same turn. Agent Plan rows
+     and schedule entries are always in lock-step (see skill "User Tasks vs
+     Agent Plan → The Agent Plan contract").
+   - Day-time observation (git push, Step 0a/0b/0c sync, or `notion:*`
+     observation in direct mode) → append to ## Agent Notes.
+5. Update projects/*.md when the observation materially changes project
+   state. Do NOT write to roadmap.md from hourly — for long-horizon
+   signals that don't belong in today.md but aren't yet strong enough
+   for direct roadmap edits (e.g. a user edited a vault note mentioning
+   a trip "sometime this summer", a far-future calendar event with an
+   unclear prep window), **queue them as `roadmap_candidate`
+   observations** via POST /api/observations (observations skill). The
+   next roadmap_refresh run consumes them and decides routing; this
+   hourly flow intentionally does not load the long-term-plan taxonomy
+   at all.
+   ```
+   curl -s -X POST http://localhost:8321/api/observations \
+     -H 'Content-Type: application/json' \
+     -d '{"source":"roadmap_candidate:<subkind>","ref":"<stable-ref>","changeType":"created","actor":"agent","payload":{...}}'
+   ```
+   `<subkind>` examples: `travel`, `calendar`, `vault`, `dm`.
+6. Skip noise: journal-only edits, trivial formatting, auto-generated churn,
+   already-processed agent writes, deletion of auto-generated artifacts.
+7. Mark processed observations consumed via POST /api/observations/consume.
+   Note: Step 0b imminent-meeting reminders are emitted on the EventBus
+   (`schedule.approaching`), not the observations table — those are
+   delivered as direct DMs and have no row to consume here.
+8. Urgency gate for POST /api/notify — the default is SILENCE. At most
+   ONE call per run, and only after the dedup pre-check passes AND one
+   of (a)(b)(c) holds with its concrete threshold:
+
+   **Dedup pre-check (mandatory — skip `/api/notify` if any hit):**
+   - `<today>` `## Agent Log` contains a `notify sent` / `DM sent` /
+     `[cal] ... — reminder sent` entry for the same item within the
+     last 4 hours.
+   - The truncation marker `[...N earlier entries omitted ...]` appears
+     in `<today>` and you cannot rule out a same-day prior notification
+     from the truncated view. In that case `GET /api/context/today`
+     once for the full log before deciding.
+   - A matching pending `POST /api/schedule/dm` or Agent Plan row is
+     already going to fire for this item within the next 2 hours
+     (prefer the planned channel — don't pre-empt it).
+
+   **Positive triggers — at least one must hold with its threshold:**
+   (a) Hard deadline ≤ 2 hours away that the agent surfaced **this
+       hour** from new input (mail, DM, observation) AND the user has
+       not yet acted on it. **Self-set deadlines, course assignments,
+       class times, and items already in `today.md` ## User Tasks do
+       NOT qualify** — they fail the awareness gate (see notify skill
+       § Universal user-facing message discipline § Awareness gate).
+       A 6-hour deadline is NOT urgent regardless.
+   (b) Inbound DM, Gmail (from Step 0a), or calendar change (from Step
+       0b) received in the last hour that needs a same-hour reply or
+       decision from the user. This is also where a Step 0b imminent
+       meeting (≤ 15 min) cleared for notification is delivered.
+   (c) Concrete failure / blocker / conflict the user would not
+       discover in time on their own (e.g. meeting moved onto an
+       existing slot; CI flagged a deploy the user triggered).
+
+   **Never urgency triggers** (log-only, no notify): "processed N
+   observations", Agent Plan / schedule reshuffles, context-file
+   updates, routine summaries of agent activity, roadmap candidates
+   queued, observations consumed.
+
+   When in doubt, stay silent and log.
+9. Append one line to ## Agent Log even on no-op runs (Agent Log only — do
+   not echo as final text, do not send via notify):
+   `- HH:MM [observations] reviewed N items, added X tasks / Y plan rows, skipped Z`.