@aitne-sh/aitne 0.1.0

package/agent-assets/docs/concepts/safety-model.md

@@ -0,0 +1,279 @@
+---
+schema_version: 1
+slug: concepts/safety-model
+title: Safety Model (deniedTools + Approve Tier)
+id: safety-model
+aliases:
+  - safety model
+  - 2-tier safety
+  - notify abolished
+  - deny list
+  - deniedTools
+  - on-demand retrospective
+category: concepts
+summary: |
+  Aitne's safety model collapsed from four tiers to two: most
+  actions run autonomously, a small set of posture-changing operations
+  require explicit Approve. The previous Notify tier (DM the operator
+  before / during a write) was abolished — the operator's `deniedTools`
+  list is now the primary defense, and "what did the agent do?" is
+  answered on demand via `GET /api/agent/actions` instead of pushed as
+  a daily digest.
+section: safety
+tags:
+  - core
+  - safety
+  - integrations
+  - skills
+status: stable
+ask_examples:
+  - Why doesn't the agent ask before sending an email anymore?
+  - How do I stop the agent from deleting things on its own?
+  - What does the agent ask me to approve, vs do without asking?
+  - Where do I see what the agent has been doing?
+locale: en-US
+created: 2026-04-26
+updated: 2026-04-26
+keywords:
+  - deniedTools
+  - safety floor
+  - Approve tier
+  - Autonomous tier
+  - ReadSensitive
+  - agent_actions
+  - retrospective
+  - starter denylist
+related:
+  - concepts/delegated-mode
+  - concepts/safety-and-execution
+  - features/operations/approvals
+  - reference/disallowed-tools
+ui_anchors:
+  - /connections
+  - /settings/cost
+config_keys:
+  - integrations
+  - deniedTools
+---
+
+# Safety Model (deniedTools + Approve Tier)
+
+## TL;DR
+
+The risk classifier has two write tiers, not three:
+
+- **Autonomous** — agent runs the action without asking. Default for
+  every connector tool call (send mail, archive, label, create event,
+  delete event, …) and for normal context writes.
+- **Approve** — agent must present a Bearer token issued through the
+  dashboard. Reserved for posture-changing daemon configuration:
+  flipping integration modes, swapping the main backend, deleting
+  backends, wiping config.
+- (`ReadSensitive` is the third tier, but it gates *reads* of personal
+  data — orthogonal to write notifications. It is unchanged.)
+
+The middleware that used to DM the operator before a write
+("Notify-tier") is gone. The defenses against unwanted destructive
+actions are:
+
+1. **`deniedTools` list** (primary) — per-integration deny list. The
+   setup wizard pre-populates a recommended starter list on first
+   delegated setup so the floor is non-empty out of the box.
+2. **Approve tier** — only for daemon-config changes that affect the
+   safety posture itself.
+3. **On-demand retrospective** — `GET /api/agent/actions` returns the
+   agent's own audit trail. When the operator asks "what did you do
+   yesterday?", the agent queries this and answers in conversation.
+
+## Why This Concept Exists
+
+The previous Notify tier (3-tier model: Autonomous / Notify / Approve)
+gave a *false sense* of safety: the action completed regardless, the
+operator could miss the DM, and the middleware was structurally unable
+to intercept native MCP calls (the agent could reach Gmail through the
+backend's connector without ever touching the daemon). Curating a
+per-tool Notify policy across direct + cross-backend + same-backend +
+operator-installed MCPs was an ever-growing maintenance trap.
+
+The new model is honest: dangerous actions either (a) are denied at the
+chokepoint by the operator's `deniedTools`, (b) require explicit
+Approve (sparse, intentional, daemon-config only), or (c) happen
+autonomously and are auditable on demand.
+
+The *value proposition* — the agent manages the operator's life — is
+preserved. The operator should not have to manage the agent's calendar
+of "report to me" events. Information about what the agent did is
+**available on demand**, not pushed.
+
+## Definitions
+
+- **Risk tier** — `Autonomous`, `ReadSensitive`, or `Approve`. The
+  former `Notify` tier was removed. `ReadSensitive` is unchanged and
+  gates personal-data *reads* via X-Read-Token / Bearer.
+- **`deniedTools`** — per-integration list of tool names (or
+  prefix-globs) the agent must not call. Lives in
+  `integrationStateSchema.deniedTools`. Editable in
+  **Connections → \<integration\> → Tool Permissions**.
+- **Starter denylist** — non-empty default `deniedTools` the setup
+  wizard pre-populates when the operator first picks `delegated` for an
+  integration. Closes the "fresh-install with empty deny list lets the
+  agent send freely" gap.
+- **`matchToolPattern`** — pattern matcher used everywhere `deniedTools`
+  is enforced. Exact match (`send_email`), prefix glob (`send_*`), or
+  bare `*`.
+- **`/api/integrations/:key/exec`** — the cross-backend chokepoint
+  (task mode). Enforces `deniedTools` and the per-task allowed-tools
+  envelope server-side before spawning a subprocess. The legacy RPC
+  `/api/integrations/:key/invoke` route is retired (preserved as
+  commented code for future reactivation; the internal
+  `DelegatedBackendInvoker.invoke()` API remains wired for
+  daemon-internal pollers).
+- **`agent_actions`** — SQLite table of every agent action. Direct +
+  cross-backend rows are full-fidelity. Same-backend native MCP rolls
+  up to `mcp_tool_calls` + the parent session row.
+
+## Where the Defenses Apply
+
+| Path | Enforcement |
+|---|---|
+| Direct mode (`/api/mail/*`, `/api/calendar/*`) | Route handler middleware checks `deniedTools` against the materialized skill body's `allowed-tools` list (frontmatter). |
+| Cross-backend (`/api/integrations/:key/exec`) | The task-mode subprocess is launched with the integration's allowed tools minus the user's `deniedTools`; daemon-side stream pre-emption aborts on out-of-allowlist `tool_use` events as `policy_violation`. |
+| Same-backend native MCP — Claude | `collectSessionDeniedTools` merges the deny patterns into the SDK's `disallowedTools` array at `query()` time. |
+| Same-backend native MCP — Gemini | Patterns are folded into `generateAdminPolicy`'s TOML deny rules (priority 1000). |
+| Same-backend native MCP — Codex | **Prose-only.** Codex bundles its connector apps into the binary; there is no per-tool deny config and the workspace-write sandbox does not match MCP tool calls. Skill prose lists the denied tools explicitly. Operators who require strict deny on Gmail / Calendar should pick a non-Codex DM backend or run those integrations through the proxy. |
+
+## Recommended Starter Denylists
+
+The setup wizard pre-populates these on first delegated setup. The
+operator can keep them, edit, or explicitly opt for an empty list (a
+confirmation modal explains the trade-off).
+
+**Gmail × Codex** (Codex's `mcp__codex_apps__gmail._*`):
+
+| Tool | Why deny by default |
+|---|---|
+| `send_email` | Strictly destructive — irreversible from the agent's POV |
+| `delete_emails` | Strictly destructive — moves to Trash; the connector exposes no separate "trash" tool |
+| `archive_emails` | Recoverable from "All Mail" but easy to lose track of |
+| `apply_labels_to_emails` | Mutating; can hide threads from default views |
+
+**Gmail × Claude** (the hosted connector is draft-only — no send /
+delete / archive surface):
+
+| Tool | Why deny by default |
+|---|---|
+| `label_message` | The only mutating tool the connector exposes |
+| `label_thread` | Same |
+
+**Google Calendar** (Codex + Claude):
+
+| Tool | Why deny by default |
+|---|---|
+| `delete_event` | Strictly destructive |
+| `update_event` | Mutating; not strictly destructive but hard to undo cleanly |
+
+The floor is intentionally wider than the strict
+"irreversible-only" minimum. `archive_emails`,
+`apply_labels_to_emails`, and `update_event` are technically reversible
+but practically destructive in a manage-my-life context: an agent that
+silently archives 30 threads or rewrites calendar invites creates
+cleanup work that may take longer than the agent saved. If you want
+the agent to archive freely, remove `archive_emails`. If you trust it
+on calendar edits, remove `update_event`. The strictly-destructive
+entries (`send_email`, `delete_emails`, `delete_event`) are the ones
+to keep.
+
+Tool names are **bare**: no `mcp__*` prefix, no leading underscore. The
+daemon prepends the connector's namespace before forwarding.
+
+## Pattern Language
+
+`deniedTools` accepts both exact names and prefix globs:
+
+- `send_email` — exact match.
+- `send_*` — anything starting with `send_` (matches `send_email`,
+  `send_message`, `send_draft` …).
+- `*` — matches anything (deny everything in the integration; rare).
+
+Anchors are implicit. `*` is only honored as a suffix to keep the
+pattern language single-purpose. Patterns are validated at PATCH time
+against the connector's `capabilityTools` set so typos fail fast.
+
+## When the Wizard Re-Fires the Starter Floor
+
+The starter floor re-fires not just on first-delegated setup but also
+on `delegatedBackend` swap (e.g. claude → codex) when the previous
+deny list is namespace-stale on the new backend and the operator
+hadn't already chosen an empty list. The audit row carries
+`trigger="backend_swap_stale"` to distinguish from
+`trigger="first_delegated"`. Operators who explicitly set
+`deniedTools: []` before the swap are honored — the swap clause does
+not silently re-establish a floor they had already rejected.
+
+## On-Demand Retrospective
+
+When the operator asks "what did you do yesterday?" / "have you sent
+anything from Gmail this week?" the agent calls:
+
+```bash
+curl 'http://localhost:8321/api/agent/actions?since=2026-04-25T00:00:00Z&kind=delegated_proxy.invoke&limit=50'
+```
+
+and answers in conversation. The endpoint:
+
+- Lives at `Autonomous` tier — the agent reads only its own audit
+  trail, no operator data.
+- Accepts `since`, `kind`, `limit` (default 50, max 200).
+- Redacts values via the standard secret-redaction utility before
+  serializing.
+- Returns rows from `agent_actions`, optionally joined with
+  `mcp_tool_calls` when `kind=mcp` (same-backend native MCP).
+
+This **replaces** the rejected daily-digest pattern. Reasons:
+
+- Token cost is paid only when the operator actually wants to know.
+- Information arrives as conversation, not a wall-of-text DM.
+- The operator does not have to manage the agent's reporting calendar.
+
+The optional fallback — extending the existing morning routine to
+summarize yesterday's `agent_actions` into `agent/journal.md` — is
+deferred until the on-demand path proves insufficient.
+
+## What Stayed Approve-Tier
+
+Approve is reserved for operations that change the safety posture or
+infrastructure itself, not for connector tool calls. Every connector
+tool call (send, delete, archive, …) is `Autonomous`, gated only by
+`deniedTools`.
+
+Approve still gates:
+
+- `PATCH /api/integrations/:key` — mode / `delegatedBackend` /
+  `deniedTools` changes.
+- `PUT /api/backends/main`, `DELETE /api/backends/:id`.
+- `PATCH /api/config` for fields that wipe protections.
+- `/api/system/*` — config reset, history purge, factory reset.
+
+## Where You See It in the Dashboard
+
+- **Connections → \<integration\> → Tool Permissions** — the
+  `deniedTools` editor with the starter list pre-populated. Above the
+  editor, the safety guidance prose explains each entry and which the
+  team recommends keeping.
+- **Settings → Cost → Delegated proxy facet** — only cross-backend
+  invocations show here; same-backend rolls up under the parent
+  session.
+- **Activity / Audit** — every action with full attribution, queried
+  the same way the agent queries `GET /api/agent/actions`.
+
+## Related
+
+- [Delegated Mode](delegated-mode.md) — the three modes and two
+  delegated sub-cases that this safety floor applies to.
+- [Safety and Execution](safety-and-execution.md) — the lower-level
+  always-disallowed layer; absolute-block holds in both Safe and
+  Allow modes.
+- Integration Delegation Framework (design) — `docs/design/14-integration-delegation.md`
+  §14.12, the deniedTools spec.
+- Delegated Mode v2 (design) — `DELEGATED-MODE-V2-DESIGN.md` §4.5,
+  the rationale for Notify-tier abolition + the starter denylist.

package/agent-assets/docs/concepts/skills.md

@@ -0,0 +1,100 @@
+---
+schema_version: 1
+slug: concepts/skills
+title: Skills
+id: skills
+aliases:
+  - SKILL.md
+  - skill manifest
+  - allowed-tools
+category: concepts
+summary: |
+  Skills are the per-task playbooks the agent follows. Each skill is a
+  Markdown file with frontmatter that names the skill, describes when
+  to load it, and pins the exact tools the session may use.
+section: skills
+tags:
+  - core
+  - skills
+  - safety
+status: stable
+ask_examples:
+  - What skills does the agent have?
+  - How do I add a new skill?
+  - Why does the agent refuse to run a tool?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+keywords:
+  - SKILL.md
+  - allowed-tools
+  - skills-compiler
+  - manifest
+related:
+  - concepts/safety-and-execution
+  - concepts/process-keys
+  - reference/skills
+ui_anchors:
+  - /knowledge
+  - /connections/mcp
+---
+
+# Skills
+
+## TL;DR
+
+A skill is a Markdown file the daemon copies into the agent's working
+directory before each session. Its frontmatter declares the skill's
+`name`, `description`, and the `allowed-tools` the session may use.
+The agent reads `SKILL.md` at the start of every session that loads
+that skill and follows it as a contract.
+
+## Why This Concept Exists
+
+The agent runs against a real machine. Without scoped permissions, a
+"please summarize my mail" turn could in principle invoke `Bash(rm)`,
+post to your social accounts, or rewrite arbitrary files. Skills fix
+that by making the available toolset task-shaped: the morning routine
+loads the routines/observations/today/schedule skills; a docs question
+loads only `docs-search`. Tools outside the allow-list aren't even
+visible to the model.
+
+## Definitions
+
+- **SKILL.md**: the Markdown file that defines a single skill. Lives
+  under `agent-assets/skills/<slug>/SKILL.md` in the repo and is
+  materialized into each session workdir as `.claude/skills/<slug>/SKILL.md`
+  (or the per-backend equivalent).
+- **`allowed-tools`**: a YAML list in the skill's frontmatter naming
+  tools and patterns the session may use. Patterns like
+  `Bash(curl http://localhost:8321/api/context/*)` are the daemon's
+  primary chokepoint.
+- **Manifest**: the per-event-type set of skill slugs to load, defined
+  in `packages/daemon/src/core/skills-manifest.ts`. Different
+  ProcessKeys load different manifests.
+- **Profile**: the persona document (e.g. `conversational.md`) prepended
+  to every session. Profiles live under `agent-assets/agent-profiles/`.
+
+## Concrete Examples
+
+- `today` — read and rewrite `today.md`.
+- `schedule` — produce per-date schedule files from the calendar.
+- `mail` — search and label messages via the daemon's mail proxy.
+- `docs-search` — read-only fetch over the docs corpus, used only by
+  `dashboard.docs_qa`.
+- `notify` — emit notifications through the configured messaging app.
+
+## Where You See It in the Dashboard
+
+- **Knowledge → Skills** lists every skill, its description, and the
+  events it loads for.
+- **Connections → MCP** is where MCP servers (which surface as tools
+  inside skills) attach.
+
+## Related
+
+- [Safety and Execution](safety-and-execution.md) — how the
+  always-disallowed layer enforces guardrails even when a skill's
+  `allowed-tools` is too permissive.
+- [Process Keys](process-keys.md) — the dispatch identity that picks
+  which skill manifest to load.

package/agent-assets/docs/features/integrations/calendar.md

@@ -0,0 +1,92 @@
+---
+schema_version: 1
+slug: features/integrations/calendar
+title: Calendar
+id: calendar
+aliases:
+  - google calendar
+  - calendar integration
+  - events
+category: features
+summary: |
+  The calendar integration pulls your events into Aitne so the
+  morning routine, schedule files, and travel-time skill can reason
+  about your day.
+section: integrations
+tags:
+  - integration
+  - calendar
+  - core
+status: stable
+ask_examples:
+  - How do I connect my Google Calendar?
+  - Why doesn't my calendar event show up in today's schedule?
+  - Can the agent create calendar events?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+keywords:
+  - calendar
+  - google calendar
+  - events
+related:
+  - features/routines/morning-routine
+  - features/memory-files/schedule
+ui_anchors:
+  - /connections/calendar
+api_endpoints:
+  - /api/calendar
+config_keys:
+  - calendarPollIntervalSeconds
+---
+
+# Calendar
+
+## In One Sentence
+
+Pull events from one or more calendars (Google Calendar today, more
+backends planned) so Aitne can plan your day around them.
+
+## What It Does
+
+- **Polls** the connected calendar(s) on `calendarPollIntervalSeconds`.
+- **Records observations** when events change (add / move / remove),
+  consumed by the hourly check.
+- **Surfaces today's events** to the morning routine so they land in
+  `today.md` and the day's schedule file.
+- **Reads** events on demand for reactive turns ("am I free at 3?").
+
+The agent can create events when the operator asks (a `notify`-tier
+action). It does not auto-schedule on its own.
+
+## When It Runs / How It Is Triggered
+
+- The poller is continuous in the background.
+- The morning routine reads today's events as part of its plan.
+- Reactive DMs trigger on-demand reads.
+
+## What It Outputs
+
+- Events written into the schedule files.
+- Observations recorded for any change between polls.
+
+## Where in the Dashboard
+
+- **Connections → Calendar** holds OAuth, scope, and polling.
+
+## Configuration
+
+| Setting | Default | Notes |
+|---|---|---|
+| `calendarPollIntervalSeconds` | 300 | How often to poll for changes. |
+
+## When Something Goes Wrong
+
+- A **stale calendar** in `/schedule` after a real-world add usually
+  means the poll has not yet run. Check the next-fire timestamp.
+- An **OAuth-expired** state reports on the auth-health card.
+
+## Related
+
+- [Morning Routine](../routines/morning-routine.md)
+- [daily/ files](../memory-files/schedule.md)

package/agent-assets/docs/features/integrations/git.md

@@ -0,0 +1,95 @@
+---
+schema_version: 1
+slug: features/integrations/git
+title: Git
+id: git
+aliases:
+  - git repos
+  - git observer
+  - git integration
+category: features
+summary: |
+  Watch one or more git repositories for new commits. Changes record
+  observations the hourly check coalesces — there is no per-commit
+  notification spam.
+section: integrations
+tags:
+  - integration
+  - git
+  - observation
+status: stable
+ask_examples:
+  - How do I add a git repo to watch?
+  - Will the agent message me on every commit?
+  - Can the agent push to my repos?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+keywords:
+  - git
+  - commit
+  - repository
+  - observer
+related:
+  - features/integrations/github
+  - features/routines/hourly-check
+  - concepts/observations
+ui_anchors:
+  - /connections/repositories
+config_keys:
+  - gitPollIntervalSeconds
+---
+
+# Git
+
+## In One Sentence
+
+Add local git repositories to a watched set; the daemon polls them
+and the hourly check decides whether the recent activity is worth
+flagging.
+
+## What It Does
+
+- **Polls** each watched repo every `gitPollIntervalSeconds`.
+- **Records observations** when new commits land between polls. The
+  commit range, changed files, and summary stats are included so the
+  hourly check can decide whether the activity matters.
+- **Surfaces patterns**, not individual commits — three small commits
+  in an hour will not page you.
+
+The agent never pushes, never amends, never force-resets. Read-only
+by design.
+
+## When It Runs / How It Is Triggered
+
+- The poller is continuous.
+- The hourly check consumes the accumulated observations.
+
+## What It Outputs
+
+- An `observation` row per detected change set.
+- A summary in the hourly check's output when observations qualified.
+
+## Where in the Dashboard
+
+- **Connections → Git** lists the watched paths and last-poll times.
+
+## Configuration
+
+| Setting | Default | Notes |
+|---|---|---|
+| `gitPollIntervalSeconds` | 300 | How often to scan watched repos. |
+
+## When Something Goes Wrong
+
+- A **missing observation** for a commit you just made: check that the
+  repo path is actually watched on `/connections/repositories` and that
+  the poll has fired since.
+- A repo that **never appears** in observations: the agent's own
+  writes are filtered out (see `AgentWriteTracker`); make sure the
+  commit was authored by you, not by an agent session.
+
+## Related
+
+- [GitHub](github.md) — separate integration for remote-side data.
+- [Hourly Check](../routines/hourly-check.md) — the consumer.