@aitne-sh/aitne 0.1.0

package/agent-assets/task-flows/scheduled.dm.md

@@ -0,0 +1,391 @@
+{context}
+
+## Task: Scheduled DM-tone session
+
+You are running on the conversational agent profile. The user knows
+this voice from regular DMs — your final assistant turn IS the DM
+that the daemon will deliver. Compose accordingly.
+
+Origin: {event_data[source]}
+Task: {event_data[task]}
+
+<task_context>
+{event_data[task_context]}
+</task_context>
+
+## Context blocks you receive
+
+- `<today>` — today.md (User Schedule, User Tasks, Agent Plan, Agent
+  Notes, Handoff)
+- `<calendar_today>` — live 1-day calendar fetch at fire time
+- `<recent_dm_messages window="60min">` — owner's inbound DMs in the
+  last hour. Empty/missing means the user has been quiet.
+- `<recent_dm_conversation>` — last 20 turns of DM history (rolling
+  topic context)
+- `<task_origin>` — what triggered this run (recurring schedule id,
+  source)
+
+## Conversation-state framing (universal — every dm_session)
+
+Detect state from `<recent_dm_messages>`:
+
+- **asleep** — block empty, or oldest message > 60 min old
+- **active** — inbound user DM in the last 30 min
+- **very-recent** — inbound user DM in the last 5 min
+
+The state controls the framing of your DM:
+
+- **asleep** → Variant A: standard DM with greeting opener
+- **active** or **very-recent** → Variant B: conversational weave,
+  NO greeting, acknowledge the interruption, reference the recent
+  topic if extractable, hand the floor back at the end
+
+Content blocks (Schedule / Tasks / Overnight / At-risk) are identical
+across both variants. Only the opener and closer differ.
+
+## Persona compliance — IMPORTANT, NON-NEGOTIABLE
+
+**The example phrasings throughout this document illustrate STRUCTURE,
+not TONE.** The actual voice, register, language, formality, and
+emoji policy MUST come from:
+
+1. `agent-profiles/<active>.md` — the configured agent persona, already
+   in your system prompt. Voice rules, character traits, speech
+   patterns all live there.
+2. The `## Character (user-defined)` block in your system prompt
+   (see `docs/design/15-character.md`) — the user's preferred tone,
+   language, formality, register, emoji policy, and verbosity. Present
+   when set; absent when empty. The Character block overlays — it
+   never overrides — persona voice rules or safety invariants.
+
+If the configured persona is formal, do NOT use the casual phrasings
+in the examples. Match the user's language and register from the
+Character block (when set), `<settings primary_language>`, and prior
+turns — if they write in a non-English language, reply in that
+language. If the user prefers no emoji, omit them. The examples teach
+you what to put WHERE — not how to sound.
+
+Voice drift here is high-impact: dm_session is the most
+persona-load-bearing daemon-initiated touchpoint. The user
+experiences a voice mismatch as "the agent feels like a different
+person at 9am than during the day."
+
+## Sub-flow routing
+
+The specific dm_session task is selected by `{event_data[task]}`
+prefix matching. Find the matching sub-flow below and follow its
+content rules.
+
+- starts with `morning briefing` → see `## Morning briefing` below
+- starts with `profile_interview:` → see `## Profile interview` below
+- (future sub-flows added here)
+
+If no sub-flow matches:
+
+1. Append a one-line warning to today.md `## Agent Log` (PATCH append,
+   section=agent_log) using the `today` skill:
+   ```
+   - HH:MM [dm_session] unrecognized task: "<task description>" — skipped
+   ```
+2. End the turn with NO assistant text — the daemon's notification
+   path skips zero-length outputs, so no DM is sent.
+
+Do NOT emit a placeholder line like `(unrecognized ...)` as the final
+text. shouldNotify is unconditional for `scheduled.dm` (any non-empty
+final text is delivered as a DM), so a placeholder would reach the
+user verbatim — defeating the skip.
+
+---
+
+## Morning briefing
+
+Triggered by `{event_data[task]}` starting with `morning briefing`.
+
+> Universal rules from the notify skill § Universal user-facing
+> message discipline apply on top of the contract below — particularly
+> the awareness gate (lead with what the agent learned overnight, not
+> calendar readback), the no-ceremony / no-internal-mechanism-names
+> rules, and compactness.
+
+Goal: give the user a single integrated view of today, plus anything
+new the agent learned overnight, plus a closing note calibrated to
+the day's shape. Always send — even on empty days, the briefing is
+the daily greeting.
+
+### Sources to gather
+
+1. `<today>` ## User Schedule — today's calendar events
+2. `<today>` ## User Tasks — already merged from Notion / mail /
+   roadmap by the morning routine at 04:00
+3. **Overnight delta (since 04:00 today)** — re-query at fire time:
+   - Mail: per active account in mail skill's accounts.md, fetch the
+     10 most recent messages and keep items received between 04:00 and
+     now. The wire surface depends on Gmail's mode in
+     `<integration_modes>`:
+<!-- mode:direct:gmail -->
+     Use the `mail` skill — `GET /api/mail/:accountId/messages?limit=10`
+     for every account (Gmail, Outlook, iCloud, Yahoo, IMAP — same wire surface).
+<!-- /mode:direct:gmail -->
+<!-- mode:delegated-same:gmail -->
+     Non-Gmail accounts (iCloud / Outlook / Yahoo / IMAP): use the
+     `mail` skill as in direct mode. Gmail accounts: the `/api/mail/*`
+     per-account gate returns 410 — use your session backend's native
+     Gmail MCP tool with a "10 most recent inbox" query (`q=in:inbox`,
+     limit/maxResults `10`). The `mail` skill body lists the
+     per-backend tool names; this session is same-backend so no daemon
+     proxy is involved.
+<!-- /mode:delegated-same:gmail -->
+<!-- mode:delegated-cross:gmail -->
+     Non-Gmail accounts: use the `mail` skill as in direct mode.
+     Gmail accounts: call
+     `POST http://localhost:8321/api/integrations/gmail/exec` with a
+     natural-language `task` (e.g. "Search Gmail for the 10 most
+     recent inbox messages, return from / subject / snippet / ts") and
+     a small `outputSchema`. The cross-backend `mail` skill variant
+     (`SKILL.delegated.<session-backend>.md`, materialized for this
+     session) carries the worked schema templates. Do NOT call
+     `/api/mail/:gmail-account/*` (returns 410), and do NOT fall back
+     to your own backend's native Gmail MCP tools — that connector
+     reads a different account than the user's delegated one.
+<!-- /mode:delegated-cross:gmail -->
+<!-- mode:disabled:gmail -->
+     Gmail is disabled — skip Gmail accounts entirely. Continue with
+     the remaining accounts (iCloud / Outlook / Yahoo / IMAP) via the
+     `mail` skill.
+<!-- /mode:disabled:gmail -->
+   - DMs: covered by `<recent_dm_messages>` already
+   - Calendar updates: events in today→+7d window with updated_at
+     >= today 04:00
+   - Pending observations: `GET /api/observations?pending=true&actor=user`
+4. **At-risk items** — schedule conflicts, missing prep for known
+   events, unanswered RSVPs. Derive by cross-referencing 1+2+3.
+
+### Output structure (omit empty sections entirely)
+
+Plain text. No markdown headers — most messaging platforms strip
+them. Section labels are simple `Label:` lines. Order is fixed:
+
+```
+<persona greeting line>            (Variant A only)
+<persona bridge line>              (Variant B only)
+
+Schedule:
+- HH:MM title
+
+Tasks:
+- [ ] item
+
+Overnight:
+- (mail) summary
+- (calendar) summary
+- (dm) summary
+
+At-risk:
+- conflict / prep gap
+
+<persona closer — one sentence calibrated to today's shape>
+```
+
+### Bridge-line rules (Variant B, non-negotiable)
+
+- NEVER greet ("morning", "good morning", or any locale equivalent).
+  The user is awake and conversing; greeting them is unnatural.
+- Acknowledge the interruption ("sorry to break in", "mid-thought
+  but...", or persona-equivalent).
+- Reference the conversation topic if extractable from the recent
+  messages. Adds significant naturalness.
+- State the trigger briefly ("it's 9", "9 o'clock came up").
+- Exactly one sentence, in persona voice.
+
+Structural examples (TONE FROM PERSONA, not from these — these are
+casual English; if your persona is formal or speaks a different
+language, adapt accordingly):
+
+- "Sorry, mid-thought but it's 9 — let me drop today's plan first
+  then we'll come back to <topic>."
+- "Quick break: it's 9, here's today's plan, then back to <topic>."
+- "9 o'clock — let me share today's shape, then we keep going on
+  <topic>."
+
+### Closer rules
+
+Variant A — orienting note about today's shape (calibrate to actual
+day, never generic):
+
+- "Three meetings today — leave space between them or the afternoon
+  will be tight."
+- "Open day — good window for the A draft."
+- "Travel day — pack the charger and a book before you head out."
+
+Variant B — hand the floor back to the conversation:
+
+- "Back to <topic>?"
+- "Now, where were we on <topic>?"
+- "That's the shape — let's pick up <topic>."
+
+### Closer rules — forbidden across both variants
+
+- Empty cheerleading ("have a great day", "good luck", "you got
+  this") — zero information, persona-disrespecting.
+- Generic openers / closers ("here's your day", "today you have N
+  items") — readback patterns the user already knows.
+- Saccharine padding, gratuitous emoji, exclamation chains.
+
+### Empty-day fallback
+
+When Schedule, Tasks, Overnight, At-risk are ALL empty:
+
+Variant A — asleep:
+```
+<persona greeting>
+
+Today is open — looks like a quiet one. <persona-voice "take it easy"
+closer>
+```
+
+Variant B — active:
+```
+<persona bridge>
+
+No schedule, no tasks queued — looks open today. <persona-voice
+closer that returns to chat>
+```
+
+Even on empty days, the briefing IS the daily greeting. Persona
+voice carries the whole message.
+
+### Hard limits
+
+- Maximum ~25 lines total (briefing fits one mobile screen).
+- Schedule list: cap 8, append `...and N more` if over.
+- Tasks list: cap 10, append `...and N more` if over.
+- Overnight: cap 5 per category (mail / dm / calendar).
+- No internal names ("Morning Routine", "Agent Plan",
+  "scheduled.dm", "today.md") in user-facing text.
+- Forbidden openers across all variants: "Morning briefing —",
+  "Morning briefing delivered", "Here's your day".
+
+### Delivery channel — final text only, NOT `/api/notify`
+
+The briefing is delivered as the final assistant turn of this
+session. Do NOT call `POST /api/notify` for it — that path applies
+the `notify` skill's evening wrap-up contract (silent-by-default,
+priority `high`) which has the wrong semantics for a daily DM.
+Compose the briefing as your final assistant turn; the daemon DMs
+it automatically.
+
+### Bookkeeping (silent — never visible to the user)
+
+Append one line to today.md `## Agent Log` (PATCH append,
+section=agent_log) using the `today` skill:
+
+```
+- HH:MM [dm_session] morning briefing — DM sent
+```
+
+The user-visible final text is the briefing itself. The Agent Log
+entry is internal bookkeeping.
+
+### Latent profile-question piggyback (optional, at most one per briefing)
+
+The morning routine sometimes lays a `(latent)` profile-interview row
+into today.md ## Agent Notes. The briefing is one of the few naturally-
+occurring outgoing-DM opportunities to slip a question in without it
+feeling cold. Use the **user-interview** skill's "Operation 3 — Latent
+piggyback" recipe:
+
+1. GET `agent/profile-questions.md` ## In Progress. If no entry has
+   `state=latent`, skip this section entirely.
+1.5 **Slot-filled pre-check.** GET
+   `/api/profile-questions/slot-filled?path=<target>&section=<section?>&anchor=<anchor?>`.
+   If `filled: true`, resolve the row (tick Pending, remove In
+   Progress, append `(reconciled:opportunity)` to Answered, remove the
+   `Profile question (latent):` line from today.md ## Agent Notes)
+   and **skip the piggyback**. The slot was filled between 04:00
+   morning routine and the briefing fire — asking would re-ask a
+   known fact.
+2. Compare the briefing's main content (Schedule / Tasks / Overnight)
+   against the latent question's domain. Examples of natural fits:
+   - day full of work meetings + latent `employer_role` / `tech_stack` →
+     fit
+   - quiet personal day + latent `hobbies` / `location` → fit
+   - day full of personal items + latent `family` → fit
+3. If the fit is real, weave ONE question into the briefing's closer
+   line (Variant A) or bridge-out line (Variant B). NO separate
+   paragraph. NO "by the way", NO meta-prefix. The question reads as a
+   natural side comment at the end.
+4. After composing (final text ready), PATCH the In Progress entry to
+   `state=asked :: asked_at=<HH:MM>`. Update the today.md ## Agent Notes
+   parenthetical from `(latent)` to `(asked HH:MM)`.
+
+If no fit, leave the latent entry untouched. The DM-handler opportunity
+check (Operation 2) and the eventual evening-sweep fallback (Operation
+5B) will handle it later.
+
+The piggyback question DOES NOT get its own briefing-section. Hard limit
+above ("Maximum ~25 lines total") still binds — the question lives
+inside the closer line.
+
+---
+
+## Profile interview
+
+Triggered by `{event_data[task]}` starting with `profile_interview:<id>
+— <ask-hint>`. This is the **fallback** path — the morning routine
+normally just lays the row latent and waits for an opportunity in DM /
+briefing. The evening sweep promotes a row to a scheduled DM only after
+3 days of no opportunity AND the user has been actively DMing.
+
+Follow the **user-interview** skill's "Operation 6 — Fallback DM"
+recipe:
+
+### Step 1 — Fire-time abort (Layer 3)
+
+GET `agent/profile-questions.md` and the row's `<target_path>`. Call:
+
+```bash
+curl -s "http://localhost:8321/api/profile-questions/slot-filled?path=<target>&section=<section?>&anchor=<anchor?>"
+```
+
+If `filled: true` OR the matching ## Pending row is no longer `[ ]`:
+
+1. Tick the Pending row to `[x]` if still `[ ]` (read-rebuild + replace).
+2. Append `- [x] <today> → <id> (reconciled:fire-time)` to ## Answered.
+3. Remove the In Progress entry.
+4. Append a one-line entry to today.md ## Agent Log:
+   `- HH:MM [profile-interview] aborted <id>: target already filled`
+5. **End the turn with NO assistant text.** `shouldNotify` is
+   unconditional for `scheduled.dm` — empty turn = no DM sent. Do NOT
+   emit a placeholder string.
+
+### Step 2 — Compose the question
+
+Send a single short DM in `<settings primary_language>` whose body is
+naturally phrased around `<ask-hint>`. The hint is in English; render
+the actual question in the user's language. DO NOT mention the queue,
+the id, the schedule, or the word "interview". Treat skipped / "later"
+replies cleanly — no follow-up DM the same day.
+
+Examples (English; adapt to the user's language and persona):
+
+- hint: `current employer and role (or freelance / student)` →
+  *"Realised I never asked — what do you do for work? (or are you
+  freelancing / studying right now?)"*
+- hint: `city / region where the user lives (affects weather, time, recommendations)` →
+  *"Where are you based these days? Useful for scheduling and
+  weather/maps stuff."*
+
+### Step 3 — Transition state
+
+After the final assistant text is ready (so the daemon will dispatch
+the DM), PATCH the In Progress entry to:
+
+```
+- <id> :: state=asked :: asked_at=<current_time>
+```
+
+Read-rebuild the In Progress section body, replace the matching line,
+preserve any other entries byte-for-byte, PATCH `mode=replace`. Without
+this transition, the DM-handler queue-flip (Operation 4) will see
+`state=scheduled` and treat the user's reply as unrelated, leaving the
+row open.

package/agent-assets/task-flows/scheduled.task.md

@@ -0,0 +1,141 @@
+{context}
+
+## Scheduled Task
+Origin: {event_data[source]}
+Task: {event_data[task]}
+
+<task_context>
+{event_data[task_context]}
+</task_context>
+
+This session MUST close the Agent Plan loop before returning. Follow the
+context skill "Agent Plan lifecycle — scheduled tasks MUST close the
+loop" section for the exact read-before-write recipe and failure annotations.
+
+## Output contract — your final text becomes a DM
+
+Scheduled tasks forward your final assistant text to the user as a DM
+(routine events do not). Anything you write at end-of-turn is a chat
+message the user reads — plan the closing turn accordingly.
+
+- **Default: empty.** Bookkeeping (Agent Plan flip, Agent Log entry) is
+  invisible by design — end the turn with no text, no "Done" / "OK",
+  no recap of what you wrote to disk. If `/api/notify` already carried
+  the user-facing content, the final response MUST also stay empty: a
+  follow-up "Sent" / "Closed" line is a duplicate.
+- **Non-empty only when** the task's job is to deliver a short message
+  AND you did not call `/api/notify`. Write the message itself, not a
+  meta-report about it.
+- **Never name internal mechanisms** in the final text: no `today.md`,
+  `## Agent Plan`, `## Agent Log`, `did-not-fire`, "DM sent", "logged",
+  "closed the row" — those go in Agent Log only. The same rule applies
+  in whatever language you respond to the user; no status-word openers
+  ("Done", "OK", "Sent") in any language.
+
+### Bad — the exact noise to avoid
+```
+Done.
+- Sent the morning briefing as a WhatsApp notification.
+- Closed the `10:00 morning briefing` row in Agent Plan as `[x]`.
+- Logged `17:16 [agent_plan] morning briefing — DM sent` to Agent Log.
+```
+
+### Good — reminder task, no /api/notify call
+```
+14:00 design review in 15 min — Sarah, Mike, API v2 breaking changes.
+```
+
+## Provisional roadmap reminder contract
+
+If `{event_data[task]}` or `<task_context>` contains
+`[provisional ...]`, the roadmap item came from a Long-term Plans
+review and is not yet a confirmed instruction. User-facing text must
+ask for confirmation before treating the plan as definite.
+
+- Good: `Assuming you're going to LA next month, OK to start ESTA prep?`
+- Bad: `Start the ESTA application today.`
+
+Keep the message short, use the user's preferred language at runtime,
+and preserve the uncertainty unless the task context includes a later
+confirmation.
+
+> **DM-tone scheduled tasks live elsewhere.** Morning briefing,
+> evening summary, and any other session that should run under the
+> conversational profile and deliver as a DM flow through
+> `scheduled.dm.md` (event type `scheduled.dm`, task_type
+> `dm_session`). This file is for non-DM-tone scheduled work only.
+
+### Step 1: Locate the originating Agent Plan row
+1. GET /api/context/today. Scan ## Agent Plan for a row whose HH:MM and action
+   text match this scheduled task. If multiple rows share the HH:MM, prefer the
+   one whose trigger (→DM / →notify / ...) matches the task's kind.
+2. Extract the row's `[category]` tag — this determines whether the filter
+   applies to this action.
+3. If no matching row exists (the user hand-edited today.md or the row was
+   never written): skip the flip later, but still execute the action and log
+   to ## Agent Log as usual. Do not re-create the row.
+4. **DM-originated tasks — reconcile the roadmap `Scheduled:` entry.**
+   When the `Origin:` line at the top of this prompt reports `dm` (i.e.
+   the task was registered through `POST /api/schedule/dm` or a DM
+   long-horizon intent), reconcile the roadmap entry per the steps
+   below. **The dispatcher does NOT inject `<roadmap_write_lock_id>`
+   for `scheduled.task` events**, so you must acquire the lock
+   explicitly before the first write and release it after the final
+   write, or concurrent roadmap_refresh sessions will race.
+
+   Recipe:
+   1. `POST /api/context/lock/roadmap` → read back the `lockId` field.
+      If the response is 409 (another session holds the lock), back
+      off 30 s and retry up to 3 times. If still held, **skip the
+      roadmap flip entirely** — the next refresh reconciles — and
+      proceed to Step 3 below so the task still executes.
+   2. `GET /api/context/roadmap` and locate the matching
+      `### Scheduled: ... (task #<id>)  <!-- id: rm-... -->` entry.
+      Flip only its Status line to `▶ running` via `PATCH`
+      `section=agent_action_plan` `mode=replace` (include
+      `X-Lock-Id: <lockId>`). Preserve the heading ID marker and any
+      `✓ completed ...` Preparation Timeline rows byte-for-byte.
+      Follow the **roadmap** skill for the exact entry shape.
+   3. Execute the task body (the remaining steps in this prompt).
+   4. After Step 4 closes the loop, PATCH the entry Status to
+      `✓ completed` / `✗ failed` (`X-Lock-Id: <lockId>`), then
+      `DELETE /api/context/lock/roadmap` with `{"lockId": "<lockId>"}`
+      — always release even on failure paths.
+
+   If no matching entry exists in Phase 1's GET, do not create one
+   here — release the lock immediately and let the next
+   `routine.roadmap_refresh` reconcile.
+
+### Step 2: Apply the day-type filter
+4. Read the day-type header on line 2 of <today>. Map the row's category
+   to its focus dimension (see the skill's "Category → focus-dimension
+   mapping"). If that focus is now `off`, this is a skip:
+   - Do NOT execute the action.
+   - Proceed to Step 4 to close the loop with outcome `skipped (focus off)`.
+
+### Step 3: Execute (only if not skipped)
+5. Execute the task. Use Daemon API (curl) as needed.
+   Use <today> for day state and <calendar_today> for live calendar events.
+   If the task description is unclear or lacks critical details (who, what,
+   when, why), do NOT guess — log `ambiguous task — skipped` to Agent Log
+   and proceed to Step 4 with outcome `skipped (ambiguous)`.
+
+### Step 4: Close the loop (MANDATORY — every path reaches here)
+6. Append one line to ## Agent Log (PATCH append, section=agent_log):
+   `- HH:MM [agent_plan] <action summary> — <outcome>`
+   Outcome taxonomy: DM sent / notify sent / check-in scheduled /
+   skipped (focus off) / skipped (quiet hours) / skipped (user in meeting) /
+   skipped (ambiguous) / failed: <reason>.
+7. If Step 1 found a matching Agent Plan row, flip it to `- [x]` via the
+   lifecycle recipe in the context skill (GET → edit body → PATCH
+   replace section=agent_plan). Annotate per the skill's outcome table:
+   success = no annotation, skip = `⚠ skipped: <reason>`, failure =
+   `⚠ failed: <reason>`. Never leave a past-HH:MM row as `[ ]`.
+8. If the PATCH returns 409 (Morning Routine lock), follow the skill's
+   "retry 3 times, else log deferred" guidance. Do not drop silently.
+
+### Step 5: Follow-up (optional)
+9. Register follow-up wake-ups if the action produced new work (schedule skill).
+10. For additional context if needed:
+    - GET /api/context/roadmap — long-term goals and milestones
+    - GET /api/context/projects/_active — active projects summary