@aitne-sh/aitne 0.1.3 → 0.1.4

package/agent-assets/skills/external-services/SKILL.native.codex.md

@@ -0,0 +1,243 @@
+---
+name: external-services
+description: Load when an external-services surface is in scope (Google Calendar / Obsidian / GitHub / Skills CRUD / scheduling) and Google Calendar is in native mode bound to Codex (`nativeBackend === "codex"`). Calendar runs through Codex's hosted Calendar MCP directly; the daemon does not proxy Calendar. Other surfaces (Apple/Outlook Calendar, Obsidian, GitHub, scheduling, Skills CRUD) keep their direct routes.
+allowed-tools:
+  - Bash(curl *)
+  - Bash(jq *)
+  - Read
+---
+
+# External Services — Native Mode (Codex Calendar MCP)
+
+Base URL: `http://localhost:8321`. All daemon calls via `curl -s`
+with `Content-Type: application/json` on POST/PATCH/PUT.
+
+> **Refusal directive — read first.** Google Calendar is in `native`
+> mode bound to Codex. Do **NOT** call any of:
+>
+> - `POST /api/integrations/google_calendar/exec` (410 with
+>   `X-Integration-Mode: native`)
+> - `POST /api/integrations/google_calendar/reconcile` (410)
+> - `/api/calendar/*` (route-prefix 410)
+>
+> Reach Google Calendar through the
+> `mcp__codex_apps__google_calendar._*` MCP tools your Codex session
+> already holds.
+>
+> Only **Google Calendar** is integration-gated here. Apple Calendar,
+> Outlook Calendar, Obsidian, GitHub, recurring-schedule CRUD,
+> one-shot scheduling, and Skills CRUD remain direct-mode routes.
+
+Confirm the binding via `<integration_modes>` (`google_calendar="native"`)
+and the `<integration-routing-table>` block in the session preamble.
+
+## Source of Truth (READ FIRST)
+
+Same as the direct-mode body — `rules/management.md` →
+`## Source of Truth` and `~/.personal-agent/integrations.md` →
+`## Note Sources`. If `rules/management.md` Schedule != Google
+Calendar, the native binding is irrelevant; route through the
+provider-specific direct route (`/api/apple-calendar/*` or
+`/api/calendar/outlook/*`).
+
+## Shell rules
+
+`jq`, never `python3`. `curl` restricted to `http://localhost:8321`.
+See the direct-mode body's "Shell rules" subsection for the full
+allowlist constraints.
+
+---
+
+<!-- service:calendar -->
+## Google Calendar — Codex hosted Calendar MCP (native)
+
+Tool namespace: `mcp__codex_apps__google_calendar._`
+
+The Codex namespace terminates with `._`; the bare suffix below is what
+you write after the namespace (`_search` = `mcp__codex_apps__google_calendar._search`).
+
+### Read-class tools
+
+| Capability | Tool(s) | Use |
+|---|---|---|
+| `search` | `_search`, `_search_events` | Free-text / filter search. |
+| `read` | `_read_event`, `_fetch` | Single-event read; `_fetch` returns the full payload incl. attendees. |
+| `get_availability` | `_get_availability` | Free-busy across one or more calendars (pure compute, no side effect). |
+| `batch_read` | `_batch_read_event` | Pull many events by id in one round-trip. |
+
+Canonical search call (window-list):
+
+```
+mcp__codex_apps__google_calendar._search_events(
+  calendar_id="primary",
+  time_min="<ISO-8601 with offset>",
+  time_max="<ISO-8601 with offset>",
+  max_results=50
+)
+```
+
+Canonical detail read:
+
+```
+mcp__codex_apps__google_calendar._read_event(
+  calendar_id="primary",
+  event_id="<id>"
+)
+```
+
+### Destructive tools (require explicit user confirmation)
+
+Per the registry's
+`google_calendar.backendConnectors.codex.destructiveTools`:
+
+- `_create_event`
+- `_update_event` — attendees field is whole-list replacement; see
+  warning below.
+- `_delete_event`
+- `_respond_event` — dispatches an RSVP to the organizer.
+
+Apply the destructive-confirm contract: summarise the plan, wait for
+explicit OK, then issue. The starter `deniedTools` list is enforced
+before the call lands.
+
+**ATTENDEES WARNING.** `_update_event(attendees=[...])` replaces the
+list verbatim. To add one attendee:
+
+1. `_read_event(...)` → copy `attendees`.
+2. Append the new attendee.
+3. `_update_event(..., attendees=[<full list>])`.
+
+**Recurring events.** Single-instance edits require the instance id;
+master-id PATCH shifts the whole series. Confirm scope before issuing.
+
+### Time discipline
+
+Same as Claude's native body — ISO 8601 with TZ offset for timed
+events; `YYYY-MM-DD` for all-day. Reject naked-ISO inputs.
+
+### Imminent-event reminders (hourly_check)
+
+The hourly_check native variant's Step 0b drives the imminent-window
+fetch each hour; this skill describes the per-call surface. POST each
+materialised event to `/api/observations` per the section at the end of
+this file.
+
+<!-- /service:calendar -->
+
+---
+
+<!-- service:apple-calendar -->
+## Apple Calendar (iCloud CalDAV) — direct, unchanged
+
+If `rules/management.md` Schedule = Apple Calendar, use the
+`/api/apple-calendar/*` routes documented in the base body. Apple
+Calendar has no MCP connector; native-mode gating does not apply.
+<!-- /service:apple-calendar -->
+
+---
+
+<!-- service:outlook-calendar -->
+## Outlook Calendar (Microsoft Graph) — direct, unchanged
+
+If `rules/management.md` Schedule = Outlook Calendar, use
+`/api/calendar/outlook/*` per the direct-mode body. No Outlook
+connector ships for Codex today; native-mode gating does not apply.
+<!-- /service:outlook-calendar -->
+
+---
+
+<!-- service:obsidian -->
+## Obsidian (external vault) — direct, unchanged
+
+Same surface as the direct-mode body. Full CRUD via
+`/api/obsidian/*`; requires the Obsidian app running. Omit `.md`
+extensions from paths. Never use this skill to read or write the
+agent's primary management vault (`today.md`, `roadmap.md`,
+`projects/`, `rules/`, …) — that lives behind `/api/context/*`.
+
+```bash
+curl -s http://localhost:8321/api/obsidian/status
+curl -s "http://localhost:8321/api/obsidian/search?q=meeting+notes&limit=10"
+curl -s http://localhost:8321/api/obsidian/notes/Daily%20Notes/2026-04-06
+curl -s -X POST http://localhost:8321/api/obsidian/notes \
+  -H 'Content-Type: application/json' \
+  -d '{"name": "Meeting Notes 2026-04-02", "content": "# Meeting\n..."}'
+curl -s -X PUT http://localhost:8321/api/obsidian/notes/Projects/ProjectA \
+  -H 'Content-Type: application/json' -d '{"content": "# Full body"}'
+curl -s -X PATCH http://localhost:8321/api/obsidian/notes \
+  -H 'Content-Type: application/json' \
+  -d '{"file": "Meeting Notes 2026-04-02", "content": "\n- Action item"}'
+curl -s -X PATCH http://localhost:8321/api/obsidian/daily \
+  -H 'Content-Type: application/json' -d '{"content": "- [ ] Follow up"}'
+curl -s -X DELETE http://localhost:8321/api/obsidian/notes/Projects/Old
+```
+<!-- /service:obsidian -->
+
+---
+
+<!-- service:github -->
+## GitHub — direct, unchanged
+
+```bash
+curl -s http://localhost:8321/api/github/repos
+curl -s "http://localhost:8321/api/github/pulls?state=open"
+curl -s -X POST http://localhost:8321/api/github/pulls/comment \
+  -H 'Content-Type: application/json' \
+  -d '{"owner": "user", "repo": "repo", "pullNumber": 42, "body": "LGTM"}'
+```
+<!-- /service:github -->
+
+---
+
+<!-- service:notion -->
+## Notion
+
+Load the dedicated `notion` skill — its body picks the right variant
+from the session's integration state independently of Calendar.
+<!-- /service:notion -->
+
+---
+
+## Persisting Calendar observations from native fetches
+
+```bash
+curl -s -X POST http://localhost:8321/api/observations \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "source": "google_calendar",
+    "type": "calendar:lifecycle",
+    "ref": "<eventId>",
+    "actor": "user",
+    "receivedAt": "<ISO-8601 UTC>",
+    "summary_text": "<title — start..end>",
+    "refs": {
+      "eventId": "<id>",
+      "calendarId": "primary",
+      "windowKey": "primary:imminent"
+    },
+    "payload": <verbatim MCP event object>
+  }'
+```
+
+The daemon computes `contentHash` server-side — pass the raw `payload`
+verbatim. HTTP 409 indicates a mode-flip race window (§11.3.1); stop
+and re-read `<integration_modes>`.
+
+---
+
+## Scheduling — direct, unchanged
+
+`/api/schedule`, `/api/schedule/dm`, `/api/recurring-schedules` live in
+the `schedule` skill. Native-mode gating does not apply.
+
+## Skills Management — direct, unchanged
+
+`/api/skills` CRUD per the direct-mode body. User-authored only;
+built-ins are read-only (403). Native-mode gating does not apply.
+
+## Cost / audit
+
+Native MCP calls land `agent_actions` rows of type `mcp_call` with
+`provider="codex"`, the tool name, and the parent `event_id` /
+`processKey`. The cost dashboard joins these to the registry by
+`toolNamespace` prefix (§14.4 `nativeAttribution`).

package/agent-assets/skills/external-services/SKILL.native.gemini.md

@@ -0,0 +1,237 @@
+---
+name: external-services
+description: Load when an external-services surface is in scope (Google Calendar / Obsidian / GitHub / Skills CRUD / scheduling) and Google Calendar is in native mode bound to Gemini (`nativeBackend === "gemini"`). Calendar runs through the google-workspace extension directly; the daemon does not proxy Calendar. Other surfaces (Apple/Outlook Calendar, Obsidian, GitHub, scheduling, Skills CRUD) keep their direct routes.
+allowed-tools:
+  - Bash(curl *)
+  - Bash(jq *)
+  - Read
+---
+
+# External Services — Native Mode (Gemini google-workspace extension)
+
+Base URL: `http://localhost:8321`. All daemon calls via `curl -s` with
+`Content-Type: application/json` on POST/PATCH/PUT.
+
+> **Refusal directive — read first.** Google Calendar is in `native`
+> mode bound to Gemini. Do **NOT** call any of:
+>
+> - `POST /api/integrations/google_calendar/exec` (410 with
+>   `X-Integration-Mode: native`)
+> - `POST /api/integrations/google_calendar/reconcile` (410)
+> - `/api/calendar/*` (route-prefix 410)
+>
+> Reach Google Calendar through the
+> `mcp_google-workspace_calendar.*` MCP tools your Gemini session
+> already holds via the `google-workspace` extension.
+>
+> Only **Google Calendar** is integration-gated here. Apple Calendar,
+> Outlook Calendar, Obsidian, GitHub, scheduling, and Skills CRUD
+> remain direct-mode routes.
+
+Confirm the binding via `<integration_modes>` (`google_calendar="native"`)
+and the `<integration-routing-table>` block in the session preamble.
+
+## Source of Truth (READ FIRST)
+
+Same files as the direct-mode body — `rules/management.md` →
+`## Source of Truth` and `~/.personal-agent/integrations.md` →
+`## Note Sources`. If Schedule != Google Calendar, route through the
+provider-specific direct route (`/api/apple-calendar/*` or
+`/api/calendar/outlook/*`); the native binding is irrelevant.
+
+## Shell rules
+
+`jq`, never `python3`. `curl` restricted to `http://localhost:8321`.
+
+---
+
+<!-- service:calendar -->
+## Google Calendar — google-workspace extension (native MCP)
+
+Tool namespace: `mcp_google-workspace_calendar.`
+
+### Read-class tools
+
+| Capability | Tool | Use |
+|---|---|---|
+| `list_events` | `listEvents` | Window-list events on a calendar. |
+| `get_event` | `getEvent` | Single-event read. |
+| `list_calendars` | `list` | Enumerate the user's calendars (the `primary: true` flag identifies the default). |
+| `find_free_time` | `findFreeTime` | Free-slot proposal — pure compute. |
+
+Canonical list call:
+
+```
+mcp_google-workspace_calendar.listEvents(
+  calendarId="primary",
+  timeMin="<ISO-8601 with offset>",
+  timeMax="<ISO-8601 with offset>",
+  maxResults=50
+)
+```
+
+**Gemini-specific Calendar quirk** (carries over from delegated mode):
+
+| Quirk | Effect | Workaround |
+|---|---|---|
+| `maxResults` is silently ignored on `listEvents` | Result set bounded only by the time window + Google's default | Narrow the time window when the connector returns more than expected; do not assume the cap applies. |
+| Default `attendeeResponseStatus = ["accepted","tentative","needsAction"]` drops declined events | Declined meetings invisible | Pass `attendeeResponseStatus=["declined"]` or the full set explicitly when needed. |
+
+Canonical detail read (always GET-before-PATCH):
+
+```
+mcp_google-workspace_calendar.getEvent(
+  calendarId="primary",
+  eventId="<id>"
+)
+```
+
+### Destructive tools (require explicit user confirmation)
+
+Per the registry's
+`google_calendar.backendConnectors.gemini.destructiveTools`:
+
+- `createEvent`
+- `updateEvent` — attendees whole-list replacement; see warning below.
+- `deleteEvent`
+- `respondToEvent` — dispatches RSVP.
+
+Apply the destructive-confirm contract every time. The starter
+`deniedTools` list is enforced before the call lands.
+
+**ATTENDEES WARNING.** `updateEvent(attendees=[...])` replaces the
+list verbatim. To add one attendee:
+
+1. `getEvent(...)` → copy `attendees`.
+2. Append the new attendee.
+3. `updateEvent(..., attendees=[<full list>])`.
+
+**Recurring events.** Single-instance edits require the instance id;
+master-id update shifts the whole series. Confirm scope.
+
+### Time discipline
+
+ISO 8601 with TZ offset for timed events; `YYYY-MM-DD` for all-day.
+The extension rejects naked-ISO inputs.
+
+### Imminent-event reminders (hourly_check)
+
+The hourly_check native variant's Step 0b drives the imminent-window
+fetch each hour; this skill describes the per-call surface. POST each
+materialised event to `/api/observations` per the section below.
+
+<!-- /service:calendar -->
+
+---
+
+<!-- service:apple-calendar -->
+## Apple Calendar (iCloud CalDAV) — direct, unchanged
+
+Use `/api/apple-calendar/*` per the direct-mode body if
+`rules/management.md` Schedule = Apple Calendar.
+<!-- /service:apple-calendar -->
+
+---
+
+<!-- service:outlook-calendar -->
+## Outlook Calendar (Microsoft Graph) — direct, unchanged
+
+Use `/api/calendar/outlook/*` per the direct-mode body if Schedule =
+Outlook Calendar. No Outlook MCP connector ships for Gemini today.
+<!-- /service:outlook-calendar -->
+
+---
+
+<!-- service:obsidian -->
+## Obsidian (external vault) — direct, unchanged
+
+`/api/obsidian/*` per the direct-mode body. Requires the Obsidian app
+running. Never use this skill to read or write the agent's primary
+management vault.
+
+```bash
+curl -s http://localhost:8321/api/obsidian/status
+curl -s "http://localhost:8321/api/obsidian/search?q=meeting+notes&limit=10"
+curl -s http://localhost:8321/api/obsidian/notes/Daily%20Notes/2026-04-06
+curl -s -X POST http://localhost:8321/api/obsidian/notes \
+  -H 'Content-Type: application/json' \
+  -d '{"name": "Meeting Notes 2026-04-02", "content": "# Meeting\n..."}'
+curl -s -X PUT http://localhost:8321/api/obsidian/notes/Projects/ProjectA \
+  -H 'Content-Type: application/json' -d '{"content": "# Full body"}'
+curl -s -X PATCH http://localhost:8321/api/obsidian/notes \
+  -H 'Content-Type: application/json' \
+  -d '{"file": "Meeting Notes 2026-04-02", "content": "\n- Action item"}'
+curl -s -X PATCH http://localhost:8321/api/obsidian/daily \
+  -H 'Content-Type: application/json' -d '{"content": "- [ ] Follow up"}'
+curl -s -X DELETE http://localhost:8321/api/obsidian/notes/Projects/Old
+```
+<!-- /service:obsidian -->
+
+---
+
+<!-- service:github -->
+## GitHub — direct, unchanged
+
+```bash
+curl -s http://localhost:8321/api/github/repos
+curl -s "http://localhost:8321/api/github/pulls?state=open"
+curl -s -X POST http://localhost:8321/api/github/pulls/comment \
+  -H 'Content-Type: application/json' \
+  -d '{"owner": "user", "repo": "repo", "pullNumber": 42, "body": "LGTM"}'
+```
+<!-- /service:github -->
+
+---
+
+<!-- service:notion -->
+## Notion
+
+Load the dedicated `notion` skill — its body picks the right variant
+from the session's integration state independently of Calendar.
+<!-- /service:notion -->
+
+---
+
+## Persisting Calendar observations from native fetches
+
+```bash
+curl -s -X POST http://localhost:8321/api/observations \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "source": "google_calendar",
+    "type": "calendar:lifecycle",
+    "ref": "<eventId>",
+    "actor": "user",
+    "receivedAt": "<ISO-8601 UTC>",
+    "summary_text": "<title — start..end>",
+    "refs": {
+      "eventId": "<id>",
+      "calendarId": "primary",
+      "windowKey": "primary:imminent"
+    },
+    "payload": <verbatim MCP event object>
+  }'
+```
+
+The daemon computes `contentHash` server-side. Pass the raw `payload`.
+HTTP 409 indicates a mode-flip race window (§11.3.1); stop and re-read
+`<integration_modes>`.
+
+---
+
+## Scheduling — direct, unchanged
+
+`/api/schedule`, `/api/schedule/dm`, `/api/recurring-schedules` live
+in the `schedule` skill. Native-mode gating does not apply.
+
+## Skills Management — direct, unchanged
+
+`/api/skills` CRUD per the direct-mode body. Native-mode gating does
+not apply.
+
+## Cost / audit
+
+Native MCP calls land `agent_actions` rows of type `mcp_call` with
+`provider="gemini"`, the tool name, and the parent `event_id` /
+`processKey`. The cost dashboard joins these to the registry by
+`toolNamespace` prefix (§14.4 `nativeAttribution`).

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

@@ -12,28 +12,56 @@ All mail work goes through `/api/mail/*`. Gmail, Outlook, Yahoo, iCloud —
 same route surface, per-account routing, provider-native translation at the
 daemon.
 
-## 0. Delegation-aware routing (read before §1)
+## 0. Per-account mode-aware routing (read before §1)
 
-This body is materialized only in direct mode and same-backend Gmail
+This body is materialized in direct mode and same-backend Gmail
 delegation. (Cross-backend Gmail delegation pulls
 `SKILL.delegated.<backend>.md` instead — that variant has its own
-routing prose.) Read the `<integration_modes>` block injected above:
-
-- **Non-Gmail accounts (iCloud, Outlook, Yahoo, IMAP):** unaffected —
-  use the `/api/mail/:acct/*` endpoints documented below regardless of
-  Gmail's mode.
-- **Gmail accounts AND `gmail="delegated"` (same-backend):** the
-  per-account gate inside the mail handler returns
-  `410 {"error": "integration_delegated"}`. Do NOT retry through
-  `/api/mail/*`. Use the connector tools your session already holds
-  natively — `mcp__claude_ai_Gmail__*` (Claude session),
+routing prose.) Read the `<integration_modes>` block injected above
+for every gated kind that is not in direct mode and dispatch
+accordingly:
+
+- **IMAP, Yahoo, iCloud:** always reachable via `/api/mail/:acct/*` —
+  these kinds have no integration-registry entry and stay direct-only
+  by design. They are unaffected by Gmail / Outlook mode flips.
+
+<!-- mode:delegated-same:gmail -->
+- **Gmail when `gmail="delegated"` (same-backend):** the per-account
+  gate returns `410 {"error": "integration_delegated"}`. Do NOT retry
+  via `/api/mail/*`. Use the connector tools your session already
+  holds natively — `mcp__claude_ai_Gmail__*` (Claude session),
   `mcp__codex_apps__gmail._*` (Codex session), or
   `mcp_google-workspace_gmail.*` (Gemini session, via the
   `google-workspace` extension).
+<!-- /mode:delegated-same:gmail -->
+
+<!-- mode:delegated:outlook_mail -->
+- **Outlook when `outlook_mail="delegated"`:** the per-account gate
+  returns `410 {"error": "integration_delegated"}`. `outlook_mail` is
+  a user-managed connector — the daemon ships no proxy. Use whatever
+  Outlook / Microsoft Graph MCP server or connector you (the user)
+  registered on the backend named in the 410 body's `backend` field.
+  If your session runs on a different backend, ask the user which
+  Outlook tools are available there; the daemon cannot route this for
+  you.
+<!-- /mode:delegated:outlook_mail -->
+
+<!-- mode:native:outlook_mail -->
+- **Outlook when `outlook_mail="native"`:** the per-account gate
+  returns `410 {"error": "integration_native"}`. Native is bound to
+  the main backend (see the 410 body's `backend` field) and the
+  daemon ships no proxy. Use the Outlook MCP / connector you (the
+  user) registered on that backend. The daemon does not poll Outlook
+  in this mode — mail observations only land when the agent fetches
+  in-turn through the user's MCP during a DM that needs them. There
+  is no proactive hourly_check fetch for `outlook_mail` (user-managed
+  reactive-only contract; see
+  `docs/design/appendices/native-integration-mode.md`).
+<!-- /mode:native:outlook_mail -->
 
 Account-resolution (§1) is unchanged: `accounts.md` lists every active
-account regardless of mode. The branch above only affects the wire call
-once an account is selected.
+account regardless of mode. The branches above only affect the wire
+call once an account is selected.
 
 ## 1. Account resolution (do this first)