@aitne-sh/aitne 0.1.3 → 0.1.4

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

@@ -0,0 +1,175 @@
+---
+name: mail
+description: Load when the task touches Gmail and Gmail is in native mode bound to Claude (`nativeBackend === "claude"`). Use Claude's hosted Gmail connector directly; the daemon does not proxy Gmail. Non-Gmail accounts (IMAP/Outlook/iCloud/Yahoo) keep the direct `/api/mail/*` surface.
+allowed-tools:
+  - Bash(curl *)
+  - Read
+---
+
+# Mail (native — Claude Gmail connector)
+
+> **Refusal directive — read first.** Gmail is in `native` mode bound to
+> Claude. Do **NOT** call any of:
+>
+> - `POST /api/integrations/gmail/exec` (returns `410` with
+>   `X-Integration-Mode: native`)
+> - `POST /api/integrations/gmail/reconcile` (410)
+> - `/api/mail/<gmail-account-id>/*` (per-account 410 inside the mail
+>   handler; the daemon returns `{"error":"integration_native"}`)
+>
+> Reach Gmail through the `mcp__claude_ai_Gmail__*` MCP tools this
+> session already holds. The 410 is a contract, not an outage — the
+> route gate enforces native-mode exclusivity per
+> `INTEGRATION_NATIVE_MODE_DESIGN.md` §9.
+
+To confirm Gmail's current binding, read the `<integration_modes>`
+block in the system prompt (it carries `gmail="native"` and the
+`<integration-routing-table>` block names the bound backend). The
+fallback file `~/.personal-agent/integrations.md` shows the same
+information.
+
+## Gmail — Claude's hosted Gmail connector (native MCP)
+
+Tool namespace: `mcp__claude_ai_Gmail__`
+
+### Read-class tools (`requiredCapabilities` floor)
+
+| Capability | Tool | Use |
+|---|---|---|
+| `search` | `mcp__claude_ai_Gmail__search_threads` | List / search threads. Pass a Gmail query (`q="newer_than:1d in:inbox -label:Promotions"`). |
+| `read` | `mcp__claude_ai_Gmail__get_thread` | Fetch a full thread's messages by `threadId`. |
+| `label` | `mcp__claude_ai_Gmail__list_labels` | Enumerate available labels (label IDs are stable per user). |
+
+Canonical search call:
+
+```
+mcp__claude_ai_Gmail__search_threads(
+  q="newer_than:1d in:inbox -label:Promotions",
+  maxResults=50
+)
+```
+
+Canonical read call (after the search returns `threadId`s):
+
+```
+mcp__claude_ai_Gmail__get_thread(threadId="<id>")
+```
+
+### Draft-class tools (reversible — write-class, not destructive)
+
+| Capability | Tool | Confirmation |
+|---|---|---|
+| `draft` | `mcp__claude_ai_Gmail__create_draft` | Autonomous — drafts are inert until the user sends from the Gmail web UI. Prefer drafts over direct send. |
+| `draft` | `mcp__claude_ai_Gmail__list_drafts` | Read. |
+
+Reply-thread chaining for drafts uses the same RFC-2822 headers documented in
+the direct-mode `mail` skill — Claude's connector exposes
+`inReplyTo` / `references` fields on `create_draft`. Fetch the thread, copy
+the last message's `Message-Id` into `inReplyTo`, append it to `references`.
+
+### Destructive tools (require explicit user confirmation)
+
+Per the registry's `gmail.backendConnectors.claude.destructiveTools`:
+
+- `mcp__claude_ai_Gmail__label_message`
+- `mcp__claude_ai_Gmail__label_thread`
+- `mcp__claude_ai_Gmail__unlabel_message`
+- `mcp__claude_ai_Gmail__unlabel_thread`
+- `mcp__claude_ai_Gmail__create_label`
+
+Claude's hosted Gmail connector deliberately ships **no** send / forward /
+delete / trash / archive surface. The destructive set here is restricted to
+label mutations and label-taxonomy edits. Apply the same
+destructive-confirm contract as delegated mode: summarise the plan
+("apply label `urgent` to 4 threads"), wait for the user's explicit OK,
+then issue the call. The absolute-block layer
+(`docs/design/09-safety-cost.md` §6) continues to fire regardless of
+mode — secret-file reads, recursive deletes, and privilege escalation are
+denied in every posture.
+
+The `deniedTools` list (from `<integration_modes>` / dashboard Tool
+Permissions card) still applies. A tool name on the deny list returns
+an error before the call lands.
+
+## Non-Gmail accounts (IMAP / Outlook / iCloud / Yahoo)
+
+Per-account gating: the `/api/mail/*` 410 only fires when the resolved
+`accountId` is `kind=gmail`. IMAP / Outlook / iCloud / Yahoo accounts
+remain fully reachable through the direct-mode endpoints — `accounts.md`
+(materialised alongside this skill) lists every active account, and the
+routing decision is per account `kind`:
+
+| Selected account `kind` | Path |
+|---|---|
+| `gmail` | native MCP tools above |
+| `outlook` / `icloud` / `yahoo` / `imap` | direct: `/api/mail/<acct>/*` — see the base body for endpoint reference, account-resolution rules (§1), draft-vs-send contract, RFC-2822 reply-thread shape |
+
+Only the Gmail branch leaves the direct-mode surface. Account
+resolution, send-vs-draft preferences, and per-account quotas are
+unchanged for non-Gmail accounts.
+
+## Persisting observations from native fetches
+
+When you fetch Gmail data during a routine (e.g. `routine.hourly_check`'s
+Step 0a), POST each materialised thread to the daemon's
+`/api/observations` endpoint so subsequent runs can dedup. The daemon
+computes `contentHash` server-side via
+`@personal-agent/shared/observations-hash.ts` — pass the raw `payload`
+verbatim; do **not** compute the hash yourself (LLM-side hashes drift
+between runs and from the delegated-sync-worker's hash, breaking
+`delegated → native` flip dedup).
+
+```bash
+curl -s -X POST http://localhost:8321/api/observations \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "source": "gmail",
+    "type": "mail:lifecycle",
+    "ref": "<threadId>",
+    "actor": "user",
+    "receivedAt": "<ISO-8601 UTC>",
+    "summary_text": "<one-line subject + sender + snippet>",
+    "refs": {
+      "threadId": "<id>",
+      "subject": "<subject>",
+      "from": "<from-address>"
+    },
+    "payload": <verbatim MCP response object>
+  }'
+```
+
+`/api/observations` is **never** native-gated — it is the chokepoint the
+native flow relies on for cross-mode dedup, so it stays reachable in
+every mode. The route also rejects late writes from a mode-flip race
+window (§11.3.1) with HTTP 409; on 409 stop and re-read
+`<integration_modes>` — the integration has flipped under you.
+
+## Decision rules
+
+- **Hourly check is read-only.** Native variants inherit the
+  "External services are read-only this hour" constraint from
+  `routine.hourly_check.native.<backend>.md`. No drafts, labels,
+  archives during the hourly pass — the morning / evening / DM
+  flows are the write paths.
+- **Prefer drafts over send.** Claude's connector has no send surface,
+  so drafts are the default channel here. If the user explicitly wants
+  a message sent, point them at the Gmail web UI — explain that this
+  configuration is draft-only by design.
+- **Replies preserve the RFC-2822 chain.** Fetch the thread, copy
+  `Message-Id` to `inReplyTo`, append it to `references`. The connector
+  signs from the user's authenticated Google account; do not pass an
+  `accountId` (the connector picks).
+- **Bulk operations: ask first.** Label mutations that touch more than
+  ~3 threads in one call should be summarised and confirmed before
+  issuing — even when the destructive-confirm dance covers the tool
+  itself.
+- **No `bcc` unless the user explicitly asks for it.**
+
+## Cost / audit
+
+Every native MCP call lands one `agent_actions` row of type `mcp_call`
+with `provider="claude"`, the tool name, `inputTokens` /
+`outputTokens`, and the parent `event_id` / `processKey` attached. The
+cost dashboard's `nativeAttribution` column (§14.4) joins those rows
+to the integration registry by `toolNamespace` prefix so the operator
+can see the spend shift after a flip.

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

@@ -0,0 +1,165 @@
+---
+name: mail
+description: Load when the task touches Gmail and Gmail is in native mode bound to Codex (`nativeBackend === "codex"`). Use Codex's hosted Gmail MCP directly; the daemon does not proxy Gmail. Non-Gmail accounts (IMAP/Outlook/iCloud/Yahoo) keep the direct `/api/mail/*` surface.
+allowed-tools:
+  - Bash(curl *)
+  - Read
+---
+
+# Mail (native — Codex Gmail MCP)
+
+> **Refusal directive — read first.** Gmail is in `native` mode bound to
+> Codex. Do **NOT** call any of:
+>
+> - `POST /api/integrations/gmail/exec` (returns `410` with
+>   `X-Integration-Mode: native`)
+> - `POST /api/integrations/gmail/reconcile` (410)
+> - `/api/mail/<gmail-account-id>/*` (per-account 410)
+>
+> Reach Gmail through the `mcp__codex_apps__gmail._*` MCP tools this
+> Codex session already holds.
+
+To confirm the binding, read `<integration_modes>` (carries
+`gmail="native"`) and the `<integration-routing-table>` block in the
+session preamble. `~/.personal-agent/integrations.md` mirrors the same
+information.
+
+## Gmail — Codex's hosted Gmail MCP (native)
+
+Tool namespace: `mcp__codex_apps__gmail._`
+
+The Codex namespace terminates with `._`, so the bare suffix below is
+what you write after the namespace (e.g. `_search_emails` =
+`mcp__codex_apps__gmail._search_emails`).
+
+### Read-class tools (`requiredCapabilities` floor)
+
+| Capability | Tool(s) | Use |
+|---|---|---|
+| `search` | `_search_emails`, `_search_email_ids` | Search; `_search_email_ids` returns ids only when you need to page. |
+| `read` | `_read_email`, `_read_email_thread` | Single message read; full-thread read. |
+| `label` | `_list_labels` | Enumerate available labels. |
+
+Canonical search call:
+
+```
+mcp__codex_apps__gmail._search_emails(
+  query="newer_than:1d in:inbox -label:Promotions",
+  max_results=50
+)
+```
+
+Canonical thread read (after search returns thread/message ids):
+
+```
+mcp__codex_apps__gmail._read_email_thread(thread_id="<id>")
+```
+
+### Draft-class tools (reversible — write-class, not destructive)
+
+| Capability | Tool | Confirmation |
+|---|---|---|
+| `draft` | `_create_draft` | Autonomous — drafts are inert until the user sends. Prefer drafts. |
+| `draft` | `_list_drafts` | Read. |
+| `update_draft` | `_update_draft` | Reversible — `update_draft` mutates a not-yet-sent draft; the user can still review before sending. Write-class but not destructive. |
+
+Reply-thread chaining: the connector accepts RFC-2822 `in_reply_to` /
+`references` fields on `_create_draft`. Fetch the thread first, copy
+the last message's `Message-Id` to `in_reply_to`, append it to
+`references`.
+
+### Destructive tools (require explicit user confirmation)
+
+Per the registry's `gmail.backendConnectors.codex.destructiveTools`:
+
+- `_send_email` — irreversible dispatch.
+- `_send_draft` — irreversible dispatch of a previously composed draft.
+- `_forward_emails` — irreversible dispatch.
+- `_delete_emails` — irreversible.
+- `_archive_emails` — reversible (archive can be unarchived) but
+  user-visible and treated as destructive in the registry.
+- `_apply_labels_to_emails` — label mutation.
+- `_bulk_label_matching_emails` — mass label mutation.
+- `_create_label` — taxonomy edit.
+- `_batch_modify_email` — mass mutation.
+
+Apply the destructive-confirm contract:
+
+1. Compose a one-line plan ("send reply to alice@example.com Re:
+   Proposal"; "archive 4 newsletter threads matching `from:digest@...`").
+2. Surface the plan to the user verbatim and wait for an explicit OK.
+3. On OK, issue the call once. Do not retry on `policy_violation` —
+   the absolute-block layer or the `deniedTools` deny list rejected it
+   for a reason.
+
+The starter `deniedTools` set (e.g. `_send_email`) is pre-populated by
+the setup wizard for safety; the dashboard's Tool Permissions card is
+the surface for widening it. Calls into a denied tool fail before they
+land at the connector.
+
+## Non-Gmail accounts (IMAP / Outlook / iCloud / Yahoo)
+
+Per-account gating: `/api/mail/*` 410 only fires when
+`accountId` resolves to a Gmail account. `accounts.md` (materialised
+alongside this skill) is the authoritative list. Routing:
+
+| Selected account `kind` | Path |
+|---|---|
+| `gmail` | native MCP tools above |
+| `outlook` / `icloud` / `yahoo` / `imap` | direct: `/api/mail/<acct>/*` (see base body) |
+
+The base body's account-resolution rules (§1), send-vs-draft contract,
+and RFC-2822 reply chain shape are unchanged for non-Gmail accounts.
+
+## Persisting observations from native fetches
+
+POST each materialised Gmail thread fetched in a routine to
+`/api/observations`. The daemon computes `contentHash` server-side via
+`@personal-agent/shared/observations-hash.ts`; pass `payload` verbatim:
+
+```bash
+curl -s -X POST http://localhost:8321/api/observations \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "source": "gmail",
+    "type": "mail:lifecycle",
+    "ref": "<threadId>",
+    "actor": "user",
+    "receivedAt": "<ISO-8601 UTC>",
+    "summary_text": "<one-line subject + sender + snippet>",
+    "refs": {
+      "threadId": "<id>",
+      "subject": "<subject>",
+      "from": "<from-address>"
+    },
+    "payload": <verbatim MCP response object>
+  }'
+```
+
+`/api/observations` is never gated. On HTTP 409 (lock-window race
+during a mode flip per §11.3.1), stop and re-read `<integration_modes>`
+— the integration has flipped under you.
+
+## Decision rules
+
+- **Hourly check is read-only** — inherits the constraint from
+  `routine.hourly_check.native.codex.md`. No sends, archives, label
+  writes during hourly.
+- **Prefer drafts over send.** `_create_draft` is autonomous;
+  `_send_email` / `_send_draft` require explicit user OK.
+- **Replies preserve the RFC-2822 chain.** Pin `Message-Id` /
+  `References` headers on the draft.
+- **Bulk operations: ask first.** A `_bulk_label_matching_emails` or
+  `_batch_modify_email` call that would touch more than ~3 messages
+  needs an explicit confirmation message summarising the criteria and
+  the count.
+- **The reply account is implicit.** The connector signs from the
+  authenticated Google account; do not pass an `accountId`.
+- **No `bcc` unless the user explicitly asks for it.**
+
+## 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 for the `nativeAttribution` rollup (§14.4).

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

@@ -0,0 +1,169 @@
+---
+name: mail
+description: Load when the task touches Gmail and Gmail is in native mode bound to Gemini (`nativeBackend === "gemini"`). Use Gemini CLI's google-workspace extension directly; the daemon does not proxy Gmail. Non-Gmail accounts (IMAP/Outlook/iCloud/Yahoo) keep the direct `/api/mail/*` surface.
+allowed-tools:
+  - Bash(curl *)
+  - Read
+---
+
+# Mail (native — Gemini google-workspace extension)
+
+> **Refusal directive — read first.** Gmail is in `native` mode bound to
+> Gemini. Do **NOT** call any of:
+>
+> - `POST /api/integrations/gmail/exec` (returns `410` with
+>   `X-Integration-Mode: native`)
+> - `POST /api/integrations/gmail/reconcile` (410)
+> - `/api/mail/<gmail-account-id>/*` (per-account 410)
+>
+> Reach Gmail through the `mcp_google-workspace_gmail.*` MCP tools your
+> Gemini session already holds via the `google-workspace` extension.
+
+Confirm the binding by reading `<integration_modes>` (carries
+`gmail="native"`) and the `<integration-routing-table>` block in the
+session preamble. `~/.personal-agent/integrations.md` mirrors the same.
+
+## Gmail — google-workspace extension (native MCP)
+
+Tool namespace: `mcp_google-workspace_gmail.`
+
+Gemini CLI registers extension tools with single underscores and a
+`.` separator between server and tool, so the bare suffix below is what
+you write after the namespace (`search` =
+`mcp_google-workspace_gmail.search`).
+
+### Read-class tools (`requiredCapabilities` floor)
+
+| Capability | Tool | Use |
+|---|---|---|
+| `search` | `search` | Gmail search (`q` accepts the same query grammar as the web UI). |
+| `read` | `get` | Fetch a single message by `id` (the extension does not expose a thread-walk primitive; compose search + per-message `get`). |
+| `label` | `listLabels` | Enumerate available labels. |
+
+Canonical search call:
+
+```
+mcp_google-workspace_gmail.search(
+  q="newer_than:1d in:inbox -label:Promotions",
+  maxResults=50
+)
+```
+
+Read pattern (the extension lacks `getThread`, so compose):
+
+```
+hits = mcp_google-workspace_gmail.search(q="threadId:<id>", maxResults=100)
+for msg_id in hits:
+    mcp_google-workspace_gmail.get(id=msg_id)
+```
+
+### Draft-class tools (reversible — write-class, not destructive)
+
+| Capability | Tool | Confirmation |
+|---|---|---|
+| `draft` | `createDraft` | Autonomous — drafts are inert until the user sends. Prefer drafts over `send`. |
+| `read_attachment` | `downloadAttachment` | Read. |
+
+`createDraft` accepts `inReplyTo` and `references` fields for
+RFC-2822 thread chaining — fetch the thread first, pin the headers.
+
+### Destructive tools (require explicit user confirmation)
+
+Per the registry's `gmail.backendConnectors.gemini.destructiveTools`:
+
+- `send` — compose-and-send in one call (irreversible).
+- `sendDraft` — dispatch a previously composed draft (irreversible).
+- `modify` — apply / remove labels including the system `TRASH` label
+  (covers delete-by-trash; archive likewise via `INBOX` label removal).
+- `modifyThread` — same as `modify`, thread-scope.
+- `createLabel` — taxonomy edit.
+- `batchModify` — mass label mutation.
+
+The google-workspace extension exposes **no** dedicated `delete` or
+`forward` tool — those compose from primitives (`delete` = `modify` +
+add `TRASH`; `forward` = `send` with re-quoted body). The registry's
+`gemini.optionalCapabilities` reflect this honestly; do not infer parity
+the connector does not have. If the user asks to forward a message,
+fetch it, compose the body, and call `send` after the destructive
+confirmation.
+
+Apply the destructive-confirm contract:
+
+1. Summarise the plan in one line.
+2. Surface verbatim and wait for explicit user OK.
+3. On OK, issue the call once. The starter `deniedTools` list (typically
+   includes `send`) is enforced before the call lands; honour it.
+
+The absolute-block layer (`docs/design/09-safety-cost.md` §6) continues
+to fire regardless of mode — recursive deletes, secret-file reads, and
+privilege escalation are denied in every posture.
+
+## Non-Gmail accounts (IMAP / Outlook / iCloud / Yahoo)
+
+Per-account gating: `/api/mail/*` 410 only fires when `accountId`
+resolves to a Gmail account. Routing:
+
+| Selected account `kind` | Path |
+|---|---|
+| `gmail` | native MCP tools above |
+| `outlook` / `icloud` / `yahoo` / `imap` | direct: `/api/mail/<acct>/*` (see base body) |
+
+The base body's account-resolution rules (§1), send-vs-draft contract,
+RFC-2822 reply chain shape, and bulk-operation discipline are unchanged
+for non-Gmail accounts.
+
+## Persisting observations from native fetches
+
+POST each materialised Gmail message fetched in a routine to
+`/api/observations`. The daemon computes `contentHash` server-side via
+the shared util in `@personal-agent/shared/observations-hash.ts`; pass
+`payload` verbatim:
+
+```bash
+curl -s -X POST http://localhost:8321/api/observations \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "source": "gmail",
+    "type": "mail:lifecycle",
+    "ref": "<threadId-or-messageId>",
+    "actor": "user",
+    "receivedAt": "<ISO-8601 UTC>",
+    "summary_text": "<one-line subject + sender + snippet>",
+    "refs": {
+      "threadId": "<id>",
+      "subject": "<subject>",
+      "from": "<from-address>"
+    },
+    "payload": <verbatim MCP response object>
+  }'
+```
+
+`/api/observations` is never gated. On HTTP 409 the integration has
+flipped during the lock window (§11.3.1) — stop and re-read
+`<integration_modes>`.
+
+## Decision rules
+
+- **Hourly check is read-only** — inherits the constraint from
+  `routine.hourly_check.native.gemini.md`.
+- **Prefer drafts over send.** `createDraft` is autonomous; `send` /
+  `sendDraft` need explicit user OK.
+- **Replies preserve the RFC-2822 chain.** Pin `inReplyTo` /
+  `references` on the draft.
+- **Bulk operations: ask first.** `batchModify` and `modifyThread`
+  calls touching more than ~3 messages need an explicit confirmation.
+- **The reply account is implicit** — the extension signs from the
+  user's authenticated Google account.
+- **No `bcc` unless the user explicitly asks for it.**
+- **Gemini-specific quirk** (`maxResults` ignored on `search`): the
+  google-workspace extension silently ignores `maxResults`; the result
+  set is bounded only by the query window and Google's default. When
+  the call returns more than expected, paginate via narrower `q=`
+  windows rather than retrying with a smaller `maxResults`.
+
+## 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 them to the registry by
+`toolNamespace` prefix for the `nativeAttribution` rollup (§14.4).

package/agent-assets/skills/management-task-modify/SKILL.md

@@ -187,7 +187,8 @@ adds them, surface them verbatim.
 - Does NOT migrate entity files when `output_path` changes; only
   future runs honor the new path.
 - Does NOT auto-confirm "this looks right" — Notify-tier means a real
-  user-facing confirmation in the user's preferred language.
+  user-facing confirmation. Output language: follow
+  `<output_language_policy>`.
 
 ## API summary
 

package/agent-assets/skills/management-task-stop/SKILL.md

@@ -66,8 +66,8 @@ If no row matches, DM:
 DELETE on a managed task is **Notify tier** (§13.1) AND removes a
 recurring commitment that the user themselves set up. Both safety
 invariants ("destructive ops require user confirmation" from
-CLAUDE.md, plus the Notify-tier policy) demand a real DM confirmation
-in the user's preferred language. Never auto-stop.
+CLAUDE.md, plus the Notify-tier policy) demand a real DM confirmation.
+Output language: follow `<output_language_policy>`. Never auto-stop.
 
 > Stop `mt_42` Zoom check (daily 10:00 JST · last run ok 3 new)? It
 > won't auto-resume.

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

@@ -71,9 +71,9 @@ rule above bars *introducing* such enumeration in any other surface.)
 
 ### Language and style
 
-Respond in the user's preferred language. Follow `user/profile.md`
-Communication Style and the Character block in your system prompt.
-Keep technical terms in original form.
+Output language: follow `<output_language_policy>`. Tone: follow
+`user/profile.md` Communication Style and the Character block in your
+system prompt. Keep technical terms in original form.
 
 ### Compactness
 
@@ -128,7 +128,7 @@ the default; see Step 4a's awareness gate). This section owns format
 rules for the rare evening where the gate plus a positive trigger
 clears the bar.
 
-### Content (in user's preferred language)
+### Content (follows `<output_language_policy>`)
 
 1. **The agent-discovered thing the user needs to know** — the
    specific item that cleared the awareness gate. Lead with substance.

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

@@ -9,6 +9,12 @@ allowed-tools:
 
 # Notion API Reference
 
+Output language: follow `<output_language_policy>`. **Property names**
+defined in the user's Notion database are Policy A (the API contract —
+never translate them; pass them through verbatim). **Property values**
+and page body content the agent fills are Policy C (write in
+`<settings primary_language>`).
+
 Base URL: `http://localhost:8321`. All calls via `curl -s` with
 `Content-Type: application/json` on POST/PATCH/PUT. URL-encode spaces in paths.