@aitne-sh/aitne 0.1.0

package/agent-assets/skills/travel/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: travel
+description: Load when the user asks about an upcoming trip or reservation, morning routines need to surface travel within the next 7 days, or reviews need a travel overview — flight, hotel, restaurant, train, and bus bookings detected by the Gmail observer.
+allowed-tools:
+  - Bash(curl *)
+  - Read
+---
+
+# Travel & Booking Tracker
+
+The daemon's Gmail observer detects booking confirmation emails from airlines,
+hotels, OTAs, restaurant reservation platforms, and rail services. Data is
+stored in the `travel_bookings` SQLite table.
+
+## When to Use
+
+- **Morning routine**: include upcoming travel/bookings in today.md.
+- **Evening review**: report newly detected bookings.
+- **User asks about trips/reservations**: query bookings and summarize.
+- **Pre-trip reminders**: surface upcoming travel day before departure.
+
+## Workflow
+
+1. Fetch upcoming bookings from `/api/travel-bookings/upcoming`.
+2. For morning routine, highlight bookings within the next 7 days.
+3. For evening review, check for newly detected bookings (today's createdAt).
+
+---
+
+## API Reference
+
+Base URL: `http://localhost:8321`
+
+### GET /api/travel-bookings
+
+List travel bookings with optional filters.
+
+```bash
+# All bookings
+curl -s "http://localhost:8321/api/travel-bookings?limit=20"
+
+# Filter by type
+curl -s "http://localhost:8321/api/travel-bookings?type=flight"
+
+# Upcoming only
+curl -s "http://localhost:8321/api/travel-bookings?status=upcoming"
+
+# Date range
+curl -s "http://localhost:8321/api/travel-bookings?from=2026-04-01&to=2026-05-01"
+```
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `type` | string | — | flight, hotel, restaurant, train, bus, other |
+| `status` | string | all | upcoming, completed, cancelled, all |
+| `from` | ISO date | — | Bookings with start_date on or after |
+| `to` | ISO date | — | Bookings with start_date before |
+| `limit` | number | 50 | Max results (1–200) |
+
+Response:
+```json
+{
+  "bookings": [
+    {
+      "id": 1,
+      "type": "flight",
+      "provider": "United",
+      "destination": null,
+      "startDate": "2026-05-15T10:30:00Z",
+      "endDate": null,
+      "confirmationNumber": "ABC123",
+      "amount": 350,
+      "currency": "USD",
+      "status": "upcoming",
+      "gmailMessageId": "18f...",
+      "createdAt": "2026-04-12T10:00:00Z"
+    }
+  ],
+  "total": 1
+}
+```
+
+### GET /api/travel-bookings/upcoming
+
+Convenience endpoint for upcoming bookings sorted by start date.
+
+```bash
+curl -s "http://localhost:8321/api/travel-bookings/upcoming?limit=10"
+```
+
+### PATCH /api/travel-bookings/:id
+
+Update booking status or destination.
+
+```bash
+curl -s -X PATCH "http://localhost:8321/api/travel-bookings/1" \
+  -H "Content-Type: application/json" \
+  -d '{"status": "completed"}'
+```
+
+---
+
+## Formatting Guide
+
+### Morning routine — today.md
+
+```
+## Travel & Reservations
+Upcoming flight: United to SFO (May 15) — confirmation ABC123
+Hotel: Marriott SF (May 15-17) — confirmation XYZ789
+Restaurant: OpenTable reservation tonight 19:00
+```
+
+Omit section if no upcoming bookings within 7 days.
+
+### Evening review
+
+```
+## New Bookings Detected
+- United flight: May 15, confirmation ABC123, $350
+```
+
+### Booking type display names
+
+| type value | Display name |
+|------------|-------------|
+| flight | Flight |
+| hotel | Hotel |
+| restaurant | Restaurant |
+| train | Train |
+| bus | Bus |
+| other | Reservation |

package/agent-assets/skills/travel-time/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: travel-time
+description: Load when a calendar event needs a departure time, the user asks about commute / transit duration, or a reminder includes "leave by HH:MM".
+when_to_use: Backed by Google Maps Directions — requires `googleMapsApiKey` in the daemon secret store; falls back gracefully when missing.
+allowed-tools:
+  - Bash(curl *)
+  - Read
+---
+
+# Travel Time & Commute Optimizer
+
+Uses the Google Maps Directions API to estimate travel time between locations.
+Integrates with the calendar to compute departure times for events with
+location fields.
+
+**Prerequisite**: Google Maps API key must be configured in the daemon's
+secret store (`googleMapsApiKey`). The API key needs the Directions API
+enabled.
+
+## When to Use
+
+- **Morning routine**: check today's calendar events with locations,
+  compute departure times, add to today.md.
+- **User asks about commute/travel time**: query specific routes.
+- **Pre-event reminders**: DM departure time suggestions.
+
+## Workflow
+
+1. Fetch today's calendar events. The right call depends on the current
+   Google Calendar mode (read `<integration_modes>` injected at session
+   start):
+<!-- mode:direct:google_calendar -->
+   Direct mode → `GET /api/calendar/events?date=today&days=1`
+   (see the `external-services` skill).
+<!-- /mode:direct:google_calendar -->
+<!-- mode:delegated-same:google_calendar -->
+   Same-backend delegated → use this session backend's native Calendar
+   list-events MCP tool. `/api/calendar/events` returns 410.
+<!-- /mode:delegated-same:google_calendar -->
+<!-- mode:delegated-cross:google_calendar -->
+   Cross-backend delegated → `POST /api/integrations/google_calendar/exec`
+   with a natural-language `task` + `outputSchema` (see the
+   `external-services` skill — cross-backend variant for worked
+   examples).
+<!-- /mode:delegated-cross:google_calendar -->
+<!-- mode:disabled:google_calendar -->
+   Disabled → skip this skill; there is no calendar to source events from.
+<!-- /mode:disabled:google_calendar -->
+2. For events with a `location` field, call `/api/travel-time` or
+   `/api/travel-time/for-event/:eventId` to get travel duration.
+3. Include departure time recommendations in today.md or DM.
+
+---
+
+## API Reference
+
+Base URL: `http://localhost:8321`
+
+### GET /api/travel-time
+
+Estimate travel time between two locations.
+
+```bash
+# Transit (default)
+curl -s "http://localhost:8321/api/travel-time?origin=Grand+Central&destination=Times+Square"
+
+# Driving with arrival time
+curl -s "http://localhost:8321/api/travel-time?origin=Brooklyn&destination=Newark&mode=driving&arrival=2026-04-12T14:00:00-04:00"
+```
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `origin` | string | (required) | Origin address or place name |
+| `destination` | string | (required) | Destination address or place name |
+| `mode` | string | transit | driving, transit, walking, bicycling |
+| `arrival` | ISO 8601 | — | Desired arrival time (computes departure time) |
+
+Response:
+```json
+{
+  "origin": "Grand Central Terminal, NY",
+  "destination": "Times Square, NY",
+  "mode": "transit",
+  "durationSeconds": 1380,
+  "durationText": "23 mins",
+  "distanceMeters": 8500,
+  "distanceText": "8.5 km",
+  "departBy": "2026-04-12T13:34:00.000Z"
+}
+```
+
+### GET /api/travel-time/for-event/:eventId
+
+Estimate travel time for a specific calendar event.
+
+```bash
+curl -s "http://localhost:8321/api/travel-time/for-event/abc123?origin=Home&mode=transit"
+```
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `origin` | string | (required) | Your starting location |
+| `mode` | string | transit | Travel mode |
+
+Response:
+```json
+{
+  "event": {
+    "id": "abc123",
+    "summary": "Team meeting",
+    "location": "WeWork Times Square",
+    "start": "2026-04-12T14:00:00-04:00"
+  },
+  "travelTime": {
+    "origin": "Home, NY",
+    "destination": "WeWork Times Square, NY",
+    "mode": "transit",
+    "durationSeconds": 2400,
+    "durationText": "40 mins",
+    "distanceMeters": 15000,
+    "distanceText": "15 km",
+    "departBy": "2026-04-12T13:16:00.000Z"
+  }
+}
+```
+
+---
+
+## Formatting Guide
+
+### Morning routine — today.md
+
+```
+## Commute & Travel
+14:00 Team meeting @ WeWork Times Square — depart by 13:15 (transit, 40 min)
+18:30 Dinner @ Restaurant ABC — depart by 18:00 (transit, 25 min)
+```
+
+Only include events that have a `location` field.
+Omit section if no events with locations today.
+
+### Mode display names
+
+| mode | Display |
+|------|---------|
+| transit | Transit |
+| driving | Driving |
+| walking | Walking |
+| bicycling | Bicycle |

package/agent-assets/skills/user-interview/SKILL.md

@@ -0,0 +1,323 @@
+---
+name: user-interview
+description: Read or modify the profile-interview queue at agent/profile-questions.md. Pick a question (latent), weave a latent question into a natural reply, tick when the user answers, fallback-promote stale rows, or reconcile against user/*.md. Never sends cold standalone DMs.
+allowed-tools:
+  - Bash(curl *)
+  - Read
+---
+
+# Profile Interview Queue Skill
+
+The agent has a slow-pace queue of profile facts to learn (name,
+timezone, location, work, hobbies, …). Questions are NOT pushed at the
+user as cold scheduled DMs. They wait in **latent** state until a
+natural opportunity arrives (a topically-related inbound DM, or the
+morning briefing). This skill is how every callsite touches that queue.
+
+## Source-of-truth file
+
+**`agent/profile-questions.md`** — agent-internal markdown. Three
+top-level sections: `## Pending`, `## In Progress`, `## Answered`.
+Never auto-injected into prompts; load only when this skill is in use.
+
+```bash
+curl -s http://localhost:8321/api/context/agent/profile-questions
+```
+
+### Pending row format
+
+```
+- [ ] (PRIO) <id> :: <target_path[ ## Section]> [:: match=<anchor>] :: <ask-hint in English> [<!-- last_attempted=YYYY-MM-DD -->]
+```
+
+| Field | Meaning |
+|---|---|
+| `PRIO`        | `HIGH` / `MID` / `LOW` — selection priority |
+| `<id>`        | snake_case unique. Doubles as the correlation id in any scheduled DM description (`profile_interview:<id> — <hint>`) |
+| `target_path` | which user file the answer should land in, e.g. `user/profile.md` |
+| `## Section`  | optional — narrows to a section within the target file |
+| `match=<anchor>` | optional — bullet key (English, like `Name`, `Timezone`, `Sleep`, `Working hours`). Required when multiple rows share a section, or when setup pre-seeds the section with an unrelated bullet |
+| `ask-hint`    | English brief of WHAT to ask. Render the actual DM in the user's `primary_language` at delivery time |
+| `last_attempted=...` | optional inline HTML comment maintained by the evening sweep — selector deprioritises rows whose comment is < 7 days old |
+
+### In Progress entry format
+
+```
+- <id> :: state=<state> :: since=<YYYY-MM-DD> [:: scheduled_at=<ISO>] [:: asked_at=<ISO>]
+```
+
+`since=` is the agent-day date the entry was first added (set by the
+morning routine when picking the question). Load-bearing: the evening
+sweep's latent-fallback promotion (Operation 5B) computes
+`today − since` to decide whether ≥ 3 days have elapsed without an
+opportunity. Without it the sweep cannot tell a day-1 latent row from a
+day-3 one. `since=` is preserved across `state=latent → asked → resolved`
+transitions; only the state field flips.
+
+State machine:
+
+```
+Pending
+  └── morning routine Step 7.5 ──▶ latent
+                                     │
+            ┌─ DM-handler topic match ┘
+            │  / briefing piggyback
+            ▼
+          asked ──── user replies ────▶ resolved (Pending row [x])
+            ▲
+            └─ scheduled (fallback) ── fires DM ─┐
+                ▲                                 │
+                │ 3 days latent + active user    │
+                └─────────────────────────────────┘
+```
+
+- The DM-handler queue-flip MUST gate on `state=asked` only. An
+  unrelated 09:00 DM cannot close out a 14:00 question that has not
+  been asked yet.
+
+### Answered entry format
+
+Append-only log:
+
+```
+- [x] YYYY-MM-DD → <id> (<source>)
+```
+
+Sources:
+- `(DM)` — user answered in chat (load-bearing: never untick)
+- `(import:<source>)` — profile import migration (never untick)
+- `(reconciled:skeleton|morning|opportunity|fire-time|sweep)` — heuristic / LLM closure
+
+## "Section is filled" check (Layers 2/3/5)
+
+Before scheduling or asking, every callsite SHOULD verify the target
+slot is genuinely empty:
+
+```bash
+curl -s "http://localhost:8321/api/profile-questions/slot-filled?path=user/profile.md&section=Identity&anchor=Name"
+# → {"filled":true|false,"sectionPresent":true|false,"fileExists":true|false,...}
+```
+
+This wraps the canonical TS helper. Use it — do NOT re-derive the rule
+in prose. URL-encode `section` and `anchor` if they contain spaces.
+
+## Operation 1 — Pick a question (morning routine Step 7.5)
+
+```
+1. GET agent/profile-questions.md.
+2. Skip the entire step if any of:
+     - ## In Progress is non-empty.
+     - ## Pending is empty.
+     - User has not sent a DM in the last 24h.
+     - Day-type focus for [personal] on line 2 of <today> is `off`.
+     - The current run is the initial morning routine
+       (`routine.morning_routine_initial`) — it lands during setup; piling
+       on a question is bad UX.
+3. Walk Pending rows in priority order (HIGH → MID → LOW, then file
+   order). For each candidate:
+     a. If the row carries `<!-- last_attempted=YYYY-MM-DD -->` and that
+        date is within the last 7 days, skip — cooldown.
+     b. Call /api/profile-questions/slot-filled for the row's target. If
+        the slot turns out to be filled (Layer 2 catches drift since
+        last sweep), tick the row [x] (read-rebuild + replace) and
+        append `- [x] <today> → <id> (reconciled:morning)` to ## Answered.
+        Continue to the next candidate.
+     c. Otherwise, this is the chosen row. Stop walking.
+4. Append a single line to today.md ## Agent Notes (latent-question
+   flavor, see "Today.md surfacing" below):
+     `- Profile question (latent): <id> — wait for natural opportunity`
+5. Append to ## In Progress in the queue file (PATCH replace, read-rebuild):
+     `- <id> :: state=latent :: since=<today>`
+   The `since=` date is load-bearing — the evening sweep needs it to
+   compute the 3-day fallback threshold.
+6. Do NOT POST /api/schedule for this row. Latent rows are NOT
+   scheduled DMs — they wait for an opportunity.
+```
+
+## Operation 2 — Latent opportunity check (DM handler)
+
+Run this AFTER the standard "Capture user info" block in
+`message.received.dm.md` / `message.received.dm_first.md`, BEFORE
+composing the reply.
+
+```
+1. GET agent/profile-questions.md ## In Progress.
+2. If no entry has state=latent, skip — return to the normal reply path.
+2.5 Slot-filled pre-check (MANDATORY before any weaving decision).
+   GET /api/profile-questions/slot-filled?path=<target>&section=<section?>&anchor=<anchor?>
+   for the latent row's target. If `filled: true`, the slot was filled
+   between morning routine and now (the user may have volunteered the
+   answer in a previous DM, or the sweep that runs at 17:50 hasn't
+   caught up yet). Resolve the row instead of weaving:
+     - Tick the matching ## Pending row [ ] → [x] (read-rebuild + replace).
+     - Remove the entry from ## In Progress.
+     - Append `- [x] <today> → <id> (reconciled:opportunity)` to ## Answered.
+     - Remove the matching `Profile question (latent): <id>` line from
+       today.md ## Agent Notes.
+   Return to the normal reply path — DO NOT weave a question. The user
+   has effectively already answered it.
+3. Otherwise (slot still empty), judge whether the inbound DM is a
+   natural moment to ask the question. The criteria:
+     - Topic match. The user's message touches the question's domain
+       (work questions when the user mentions a meeting, code, deadline;
+       personal questions when the user discusses lifestyle, hobbies,
+       weekend plans; identity / location questions when the user makes
+       a general greeting on day 1 or asks for time/weather).
+     - Length appropriateness. Your reply will be more than a one-liner;
+       there is room to weave a question without making the message look
+       forced.
+     - Mood appropriateness. The user is not venting / in crisis / asking
+       a single short factual question.
+4. If yes:
+     a. Compose the reply with the question woven in NATURALLY. Do NOT
+        make a separate paragraph or "By the way, …" preamble. The
+        question should feel like a side comment, not an interview cue.
+     b. After the reply is ready (final assistant text already includes
+        the question), issue **two PATCH replaces** (separate calls —
+        they target different files):
+        - `PATCH /api/context/agent/profile-questions` section=in_progress
+          — flip the entry to
+          `state=asked :: since=<unchanged> :: asked_at=<current_time>`
+          (preserve the original `since=` date).
+        - `PATCH /api/context/today` section=agent_notes — replace the
+          parenthetical from `(latent)` to `(asked HH:MM)` and append
+          `(asked HH:MM)` to the same line; preserve every other Agent
+          Notes line byte-for-byte.
+5. If no, leave the latent entry untouched. Return to the normal reply
+   path. The opportunity will come (or the evening sweep will eventually
+   promote to a fallback scheduled DM if it doesn't).
+```
+
+## Operation 3 — Latent piggyback (morning briefing composition)
+
+Mirror of Operation 2, run inside the `## Morning briefing` sub-flow of
+`scheduled.dm.md`. The briefing is already an outgoing DM the agent
+composes; it is one of the few naturally-occurring opportunities to
+slip in a question.
+
+```
+1. GET agent/profile-questions.md ## In Progress.
+2. If no entry has state=latent, skip.
+2.5 Slot-filled pre-check (MANDATORY). Same recipe as Operation 2 step 2.5:
+   GET /api/profile-questions/slot-filled. If `filled: true`, resolve
+   the row (tick Pending, remove In Progress, append
+   `- [x] <today> → <id> (reconciled:opportunity)` to Answered, remove
+   the matching `Profile question (latent):` line from today.md ## Agent Notes) and
+   skip the piggyback — DO NOT weave the question.
+3. Decide whether the briefing's main content overlaps with the
+   question's domain (work questions when the day is calendar-heavy
+   with work meetings; personal questions when the day is light /
+   personal). If yes, weave one question into the briefing as a closing
+   side note. Same naturalness rules as Operation 2 — no preamble, no
+   separate paragraph.
+4. After composing, issue two PATCH replaces (separate calls):
+   - `PATCH /api/context/agent/profile-questions` section=in_progress —
+     flip the entry to
+     `state=asked :: since=<unchanged> :: asked_at=<current_time>`.
+   - `PATCH /api/context/today` section=agent_notes — flip the matching
+     `Profile question (latent):` line by changing the parenthetical to
+     `(asked HH:MM)`.
+```
+
+## Operation 4 — Capture the answer (DM handler queue reconcile)
+
+Run this AFTER "Capture user info" and Operation 2's opportunity check,
+BEFORE composing the reply text.
+
+```
+1. GET agent/profile-questions.md ## In Progress.
+2. If an entry has state=asked AND (now − asked_at) < 24h:
+     a. Tick the matching ## Pending row [ ] → [x] via PATCH replace
+        (read-rebuild full Pending body, change just that one line).
+     b. Remove the entry from ## In Progress (PATCH replace).
+     c. Append `- [x] <today> → <id> (DM)` to ## Answered.
+     d. Remove the matching today.md ## Agent Notes line — match by
+        the `Profile question (` prefix and the `: <id>` id segment;
+        works for both `(asked HH:MM)` and `(latent)` parenthetical
+        states (PATCH replace, read-rebuild — preserve every other line
+        byte-for-byte). Without this the line lingers in today.md
+        until tomorrow's PUT-replace and confuses the user.
+3. If state=latent or state=scheduled, leave the entry alone — this
+   inbound DM is by definition unrelated to a question the user has
+   not been asked.
+```
+
+The "one DM after fire = one tick" rule is intentional. Trying to detect
+"did the user ACTUALLY answer?" is unreliable and would re-ask forever
+on partial answers. The 7-day `last_attempted` cooldown means an
+unresolved fact will surface again later through the natural-volunteering
+path or the next opportunity.
+
+{{> ref:sweep-and-fallback }}
+
+## Today.md surfacing — Agent Notes flavor
+
+A latent question is mirrored to today.md ## Agent Notes for visibility.
+This is informational only — Agent Plan keeps its strict HH:MM-+-schedule
+contract; latent rows do NOT belong there.
+
+```
+- Profile question (latent): <id> — wait for natural opportunity
+- Profile question (asked HH:MM): <id>        # after Operation 2/3/6
+```
+
+The morning routine writes the `(latent)` line. The DM handler /
+morning briefing flips the parenthetical to `(asked HH:MM)` when the
+question is woven into a reply. The evening sweep's stale recovery
+removes the line entirely if the user did not reply within 24h.
+
+## Anchor convention — load-bearing
+
+The heuristic anchor lookup matches against bullet keys written by the
+**user-profile** skill: English label keys, any-language values:
+
+```
+- Name: Alex
+- Timezone: America/New_York
+- Working hours: Weekdays 09:00–18:00
+- Sleep: 23:00–07:00
+```
+
+Anchors in `agent/profile-questions.md` MUST match these English keys —
+not the user's primary-language phrasing. If a future `user-profile`
+schema change introduces non-English keys, Layers 1–3 silently miss
+those bullets and the system degrades to Layer-4-only protection
+(≤ 24h staleness). Cross-reference: `agent-assets/skills/user-profile/SKILL.md`
+§"File schema" + `setup.initial.md` (canonical bullet examples).
+
+## Rules
+
+- Never ask via cold standalone DM if a natural opportunity is plausible.
+- Never weave a question that is unrelated to the current conversation
+  topic — better to wait.
+- Never ask twice the same agent-day.
+- Never tick a row whose target section is genuinely placeholder-only.
+- Never write to ## Pending from any callsite other than skeleton seeding,
+  Layer 4 untick (sweep), and Phase 2 evening-review extension.
+- Never ask the user identity-class confirmations (name, timezone,
+  primary_language) twice — these have explicit setup paths; if they
+  are still empty after setup, the queue may ask once.
+
+## API quick reference
+
+```bash
+# Read the queue
+curl -s http://localhost:8321/api/context/agent/profile-questions
+
+# Slot-filled probe
+curl -s "http://localhost:8321/api/profile-questions/slot-filled?path=user/profile.md&section=Identity&anchor=Name"
+
+# Section-level edit (queue file uses the standard context API)
+curl -s -X PATCH http://localhost:8321/api/context/agent/profile-questions \
+  -H 'Content-Type: application/json' \
+  -d '{"section": "in_progress", "mode": "replace", "content": "- name :: state=latent"}'
+
+# Fallback DM scheduling (Operation 5B only)
+curl -s -X POST http://localhost:8321/api/schedule \
+  -H 'Content-Type: application/json' \
+  -d '{"time":"<ISO>","taskType":"dm_session","description":"profile_interview:<id> — <hint>","model":"sonnet","taskContext":{"scheduledBy":"user_profile_sweep_fallback","queueId":"<id>","importance":"low"}}'
+```
+
+The PATCH `section` argument is snake_case of the heading: `pending`,
+`in_progress`, `answered`. Read-before-write applies to every PATCH
+replace.