aloita-extensions 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Frank Vliegen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,413 @@
+# aloita-extensions
+
+Pi extensions that **replace both** the [Aura SignalR receiver](https://github.com/frankvl76/aura-signalr-client) and the [Aura MCP server](https://github.com/frankvl76/aura-mcp-server) with a single Pi extension.
+
+Instead of spawning `claude -p` / `opencode` per ticket and talking to Aloita over MCP stdio, **one Pi session connects to Aloita over SignalR and works on tickets natively.** The 28 `aura_*` tools are registered as first-class Pi tools — no MCP, no subprocess, no separate FastAPI dashboard.
+
+```
+                ┌─────────────────────────────────────────────┐
+                │  ONE Pi session (this extension loaded)      │
+                │                                              │
+   Aloita ──SignalR──► onWebhookEvent                          │
+   board         │        ├─ dedup → resolve folder           │
+   (formerly     │        ├─ set "In Progress" + agent-task    │
+   "Aura")       │        └─ pi.sendUserMessage(prompt) ──┐    │
+        ◄─REST───│◄── aura_* tools (28) ◄─────────────── the   │
+                │    (get ticket, comment, checklist, …) agent │
+                │                                              │
+                │    on agent_end → "Done" + drain next queued │
+                └─────────────────────────────────────────────┘
+```
+
+## What this replaces
+
+| Old (Python)                         | New (this extension)                                   |
+|---------------------------------------|--------------------------------------------------------|
+| `signalr_receiver.py` (2848 lines)    | `src/signalr.ts` + `src/index.ts` webhook handling     |
+| `signalr_loop_bridge.py` + supervisor | gone — the Pi session **is** the long-lived consumer   |
+| FastAPI dashboard + `static/`         | `ctx.ui.setStatus()` footer + `notify()` + `/aloita-*` |
+| `aura-mcp-server/server.py` (28 tools)| `src/tools.ts` — same 28 tools, registered natively    |
+| `aura_client.py` (httpx)              | `src/aura-client.ts` (`fetch`)                         |
+| Subprocess spawn + `.cmd` shims       | gone — no subprocesses                                 |
+| Usage reconstruction from transcripts | `message_end` usage → `/agent-run-usage` on `agent_end` |
+| `AuraAgentLogPusher` + stdout line reader | `src/agent-log.ts` — fed from Pi streaming events (see §Agent log streaming) |
+| `--resume <sessionID>` dance          | gone — the session is already long-lived               |
+
+## Quick start
+
+**Prerequisites:** Pi (`@earendil-works/pi-coding-agent`) on your PATH and Node 18+.
+
+### 1. Install the extension (one command)
+
+```powershell
+pi install npm:aloita-extensions
+```
+
+That's it. `pi install` writes the package to Pi's global settings (`~/.pi/agent/settings.json` → `packages: [...]`) and fetches its `dependencies` (`ws`). Plain `pi` (no flags) now auto-loads the extension on **every startup** — no manual path configuration, no `--extension` flag, no rebuild step.
+
+Pi bundles the `@earendil-works/*` and `typebox` packages this extension imports (declared as `peerDependencies`), so they are provided by Pi at runtime.
+
+> **Offline / air-gapped install:** if the npm tarball (`.tgz`) is available locally instead of published to a registry, install directly from it: `pi install ./aloita-extensions-0.2.0.tgz`. See [§Distributable](#distributable) for details.
+
+Manage the registration:
+
+```powershell
+pi list                               # confirm it's registered
+pi remove npm:aloita-extensions       # unregister
+pi update --extensions                # update all installed packages
+```
+
+### 2. Configure Aloita access
+
+Set your Aloita server URL + API key (env vars are the simplest — good for secrets):
+
+```powershell
+# PowerShell (current session):
+$env:ALOITA_URL = "https://your-aloita-server"
+$env:ALOITA_API_KEY = "kai_your_key_here"
+
+# Or persist as user environment variables (run once):
+setx ALOITA_URL "https://your-aloita-server"
+setx ALOITA_API_KEY "kai_your_key_here"
+```
+
+Alternatively, copy `config.example.json` to one of these paths and edit (full schema in [§Configure](#configure)):
+- `~/.pi/aloita.json` — global (**recommended** for `repos`, capabilities, and auto-start settings)
+- `<cwd>/.pi/aloita.json` — project-local (preferred for per-project overrides)
+
+**Or skip the env vars entirely** — run `/aloita-configure` inside Pi and set the server URL + API key in the **Connection settings** screen. They persist to `~/.pi/aloita.json` (global) so every Pi session on this machine uses them.
+
+Launch `pi`. The footer shows `● Aloita: connected` when the SignalR socket is up.
+
+### 3. (Optional) Auto-start + `/aloita-configure`
+
+To let this Pi session automatically start a dedicated child `pi` in specific project folders, open the interactive settings UI:
+
+```
+/aloita-configure
+```
+
+Toggle which projects are in the auto-start allow-list, adjust options, then **Save & close** — changes persist to the config file and hot-reload immediately. See [§Auto-start supervisor](#auto-start-supervisor) and [§`/aloita-configure`](#aloita-configure--interactive-settings-ui) for detail. (Auto-start is opt-in and off by default.)
+
+## Distributable
+
+The extension ships as an npm tarball (`npm pack` output): `aloita-extensions-0.2.0.tgz`. This is the single artifact for distribution — it contains exactly the package contents (source, docs, README, LICENSE, config example, tsconfig) and nothing else (no `node_modules`, no `.git`, no test artifacts).
+
+Two install paths from the tarball:
+
+1. **Publish to npm**, then install by name (recommended for repeated installs):
+   ```powershell
+   npm publish aloita-extensions-0.2.0.tgz   # one-time publish
+   pi install npm:aloita-extensions           # install on any machine
+   ```
+
+2. **Install directly from the tarball** (no registry needed — good for air-gapped / private setups):
+   ```powershell
+   pi install ./aloita-extensions-0.2.0.tgz
+   ```
+   This registers the tarball path in Pi's settings and auto-loads the extension on every startup, just like the npm path.
+
+A `distributable.zip` is attached to the packaging ticket — it contains the `.tgz` plus this README, so a developer has everything needed in one download.
+
+---
+
+## Install (local development)
+
+For hacking on this extension from a clone:
+
+```powershell
+git clone https://github.com/frankvl76/aloita-extensions
+cd aloita-extensions
+npm install            # fetches ws + dev/type deps
+npm run build          # tsc --noEmit type-check
+npm test               # node --test src/*.test.ts
+```
+
+Register the local folder so it auto-loads (reads the `pi.extensions` manifest from `package.json`):
+
+```powershell
+# Global — loads in EVERY project folder (matches the one-Pi-per-folder model).
+pi install C:\path\to\aloita-extensions
+
+# Project-local — only the current folder:
+pi install -l C:\path\to\aloita-extensions
+```
+
+`pi install` stores a path relative to `~/.pi/agent`; `pi list` prints the resolved absolute path so you can sanity-check it. Global packages are loaded regardless of project trust, so they apply in every cwd.
+
+Because Pi loads extensions via [jiti](https://github.com/unjs/jiti) on each launch, **source edits are picked up immediately on the next `pi` start** and `/reload` hot-reloads them in a running session — no rebuild step.
+
+### Manual / one-off (no registration)
+
+For a single run with no registration, use the explicit flag:
+
+```powershell
+pi --extension C:\path\to\aloita-extensions\src\index.ts
+```
+
+## Configure
+
+Two sources, first non-empty wins:
+
+1. **Env vars** (good for secrets): `ALOITA_URL`, `ALOITA_API_KEY` (also `AURA_REPOS`).
+2. **JSON file** discovered at one of:
+   - `<extensionDir>/aloita.json` — sibling of `package.json`
+   - `<cwd>/.pi/aloita.json` — project-local (**preferred**, per-folder)
+   - `~/.pi/aloita.json` — global
+
+Copy `config.example.json` to one of those paths and edit. Full schema:
+
+| Field                  | Default | Purpose                                                                 |
+|------------------------|---------|-------------------------------------------------------------------------|
+| `aloitaUrl`            | —       | Base URL of the Aloita server (env `ALOITA_URL`).                       |
+| `apiKey`               | —       | `kai_…` key (env `ALOITA_API_KEY`).                                     |
+| `subscription`         | see ex  | `{ events, allProjects, allUsers, projectIds, userIds }` bitmask filter.|
+| `projectFolders`       | `{}`    | `projectId → local path` override (wins over Aura-side `LocalFolder`).  |
+| `projectFilter`        | `""`    | If set, this session only claims tickets for that project id.           |
+| `matchAllProjects`     | `false` | If true, claim every ticket regardless of folder (uses this cwd).       |
+| `repos`                | `""`    | `${REPOS}` expansion target (env `AURA_REPOS`).                         |
+| `labelToCommand`       | see ex  | Ticket label → command template.                                        |
+| `defaultCommand`       | `aura-work-on-ticket` | Fallback command.                                         |
+| `guardStatus`          | `true`  | Block the agent from changing ticket status (enforces the #1 rule).     |
+| `autoFinalizeOnAgentEnd` | `true` | Set ticket "Done" when the triggered turn ends.                         |
+| `postUsage`            | `true`  | POST per-model token/cost to Aloita on `agent_end` (see §Usage post-back).|
+| `postDiff`             | `true`  | POST the run's git diff to Aloita's per-ticket diff viewer on `agent_end` (see §Run diff post-back).|
+| `streamAgentLog`       | `true`  | Stream the agent's text to Aloita's per-ticket agent-log tab in real time (see §Agent log streaming).|
+| `dedupWindowSeconds`   | `2`     | Webhook dedup window.                                                   |
+| `autoStartProjects`    | `false` | Supervisor: poll `/api/projects` and spawn a child `pi` in each NEW project's folder (see §Auto-start supervisor). |
+| `autoStartPollSeconds` | `60`    | Auto-start poll interval (seconds).                                     |
+| `autoStartCreateFolder`| `true`  | Auto-start: `mkdir -p` the project folder if it doesn't exist yet.       |
+| `autoStartPiCommand`   | `""`     | Auto-start: override the `pi` command to spawn (default `pi.cmd`/`pi`). |
+| `autoStartExcludeProjects` | `[]` | Auto-start: project ids to never launch.                                |
+| `autoStartSeedExisting`| `false` | Auto-start: launch for all existing projects on startup (not just new). |
+| `autoStartProjectIds` | `[]`    | Auto-start: allow-list of project ids to launch for (new projects do nothing until added here — use `/aloita-configure`). |
+| `capabilities`         | `[]`    | GLOBAL fallback caps registered against the auth user (see §Capability tiers). |
+| `userMappings`         | `{}`    | GLOBAL per-agent-user profiles + their capability tiers (see §Capability tiers). |
+
+## How a ticket flows through Pi
+
+1. **`session_start`** → opens the SignalR WebSocket to `<aloitaUrl>/hubs/webhooks`, handshakes, subscribes. Status footer shows `○ aloita: connected`.
+2. **`WebhookEvent`** arrives → dedup (2s fingerprint) → resolve working dir → decide whether *this* session claims it (see *Multi-project* below) → fetch ticket context → resolve label → command → set **In Progress** + `agent-task/start` → `pi.sendUserMessage(prompt)`.
+3. The Pi agent **works the ticket** using the native `aura_*` tools (get context, comment, attachments, checklist, conversations, search data…). Its streamed text is mirrored live to Aloita's per-ticket agent-log tab (see §Agent log streaming).
+4. **`agent_end`** → finalize: set **Done** + `agent-task/end` → drain the next queued ticket if any.
+5. **`StopTask`** (user clicks Stop in Aloita UI) → drops queued + `ctx.abort()` the active turn.
+6. **`session_shutdown`** → closes the socket cleanly.
+
+## Label routing (which prompt runs)
+
+When a ticket is claimed, its labels are matched (case-insensitive, trimmed, first match wins) against `labelToCommand` to pick the prompt template; any unmatched label (or no label) falls back to `defaultCommand`. Defaults (`src/config.ts`) — override/add in your `aloita.json`:
+
+| Label                  | Command                              | What the agent does                                                                          |
+|------------------------|--------------------------------------|----------------------------------------------------------------------------------------------|
+| `plan`                 | `aura-plan-ticket`                   | Write a technical plan/spec, attach it; no code.                                             |
+| `review`               | `aura-review-ticket`                 | Review recent changes for the ticket; no code.                                              |
+| `document`             | `aura-document`                      | Generate documentation.                                                                      |
+| `workflow-implementation` | `aloita-workflow-implement-with-pr` | Implement on a `feature/<name>` branch off latest `main`, then **open a PR into `staging`**. |
+| *(no / unmatched label)* | `aura-work-on-ticket` *(default)*  | Implement the ticket directly (full work loop, no git/PR).                                   |
+
+To add your own, map a label to a command name and define that template in `PROMPTS` (`src/prompts.ts`).
+
+## Multi-project (one Pi per folder)
+
+A Pi session is bound to its launch cwd, so run **one Pi per project folder** — exactly the model `RUNNING.md` already documents for the supervisor:
+
+```powershell
+# In project A's folder, dedicated to project A:
+cd C:\path\to\projectA
+pi --extension ...\aloita-extensions\src\index.ts
+#   → set projectFilter to project A's id in .\.pi\aloita.json
+```
+
+Ticket-claiming logic (`src/working-dir.ts shouldClaimTicket`):
+- `matchAllProjects: true` → claim everything (use this cwd).
+- `projectFilter: "<id>"` → claim only that project.
+- **default** → claim only when the ticket's resolved folder exists **and equals this session's cwd**.
+
+## Auto-start supervisor
+
+Normally you start one Pi per project folder manually (`cd <folder> && pi`). With `autoStartProjects: true`, this Pi session becomes a **supervisor**: it polls `GET /api/projects` every `autoStartPollSeconds` and, for each project that is in your **allow-list** (`autoStartProjectIds`) and not yet launched, spawns a **detached child `pi`** in that project's folder.
+
+**Allow-list model:** a brand-new project does **nothing** until you explicitly opt it in — either by adding its id to `autoStartProjectIds` in the config file, or interactively via `/aloita-configure` (recommended). This keeps you in control of which folders get a child pi.
+
+```json
+{
+  "autoStartProjects": true,
+  "repos": "C:\\Users\\frank\\source\\repos",
+  "autoStartCreateFolder": true,
+  "autoStartPollSeconds": 60
+}
+```
+
+**How a project is launched** (pure logic in `src/project-launcher.ts`, I/O in `src/index.ts`):
+1. Poll → `normalizeProjects` → `detectProjectsToLaunch` (allow-listed projects not yet launched).
+2. Resolve the folder, in order: `projectFolders[id]` override → project `LocalFolder` → `$REPOS/<sanitized-name>` (derived from `repos`).
+3. If the folder doesn't exist and `autoStartCreateFolder` is on, `mkdir -p` it.
+4. Write a tiny project-local `.pi/aloita.json` containing `{ "projectFilter": "<id>" }` so the child claims only that project.
+5. `spawn(<pi>, { detached: true, stdio: "ignore" })` + `child.unref()` — the child survives the supervisor.
+
+Credentials are passed via `ALOITA_URL` / `ALOITA_API_KEY` env vars, **not** written into the per-project file, so no secrets are duplicated.
+
+**Why polling:** Aloita's `WebhookEventType` bitmask only covers ticket events today — there is no `ProjectCreated` flag. Polling `/api/projects` is the server-agnostic signal. If Aloita adds a `ProjectCreated` event later, only the supervisor's trigger changes; the pure planning layer stays as-is.
+
+**Safe by default:** off unless you opt in; never blocks the session; failed launches/polls log a warning and continue.
+
+## `/aloita-configure` — interactive settings UI
+
+The `/aloita-configure` command opens a full-screen TUI wizard (built from Pi's `SelectList` + `SettingsList` components) where you can manage all Aloita extension settings without editing JSON. All settings persist to the **global** config file (`~/.pi/aloita.json`) so they apply to every Pi session on this machine.
+
+- **Connection settings** — server URL, API key (`kai_…`), and agent user IDs. These are the credentials every Pi session needs to connect to Aloita. Set them once here and they're global — no need to repeat `ALOITA_URL`/`ALOITA_API_KEY` env vars per session. Changing them triggers an immediate SignalR reconnect.
+- **Model capabilities** — browse the models you've configured in Pi (from your providers — `ctx.modelRegistry.getAvailable()`) and toggle which to broadcast to Aloita. Costs are **auto-filled from Pi's model pricing** (`Model.cost`). The display name defaults to the model name. This is how Aloita learns what models this machine can run and what they cost — used for `/cost` and complexity-tier mapping.
+- **Auto-start projects** — browse every project on the Aloita board and toggle which ones are in the allow-list (`autoStartProjectIds`). Searchable for large boards.
+- **Auto-start options** — master switch, poll interval (30s/60s/2m/5m/10m presets), folder creation, seed-existing.
+- **General options** — status guard, auto-finalize, token-usage / diff / agent-log post-backs.
+- **Save & close** — persists changes to the config JSON file and hot-reloads. **Cancel** discards.
+
+The API key is masked in the input dialog (`kai_••••••`). Press Esc at any prompt to skip that field without changing it. Connection settings are written to `~/.pi/aloita.json` (global) — env vars (`ALOITA_URL`/`ALOITA_API_KEY`) still take precedence at load time if set.
+
+Changes persist via `src/config-store.ts` (read → merge → write), which shallow-merges so untouched keys survive and secrets (`aloitaUrl`/`apiKey`) are never written into the file.
+
+## Commands
+
+| Command             | Action                                                    |
+|---------------------|-----------------------------------------------------------|
+| `/aloita-status`    | Print connection state, active ticket, queue depth.       |
+| `/aloita-connect`   | Force reconnect the SignalR socket.                       |
+| `/aloita-disconnect`| Disconnect the socket.                                    |
+| `/aloita-next`      | Force-drain the next queued ticket into this session.     |
+| `/aloita-configure` | Interactive settings UI: toggle auto-start projects, edit options, persist. |
+
+## Tools (28, grouped like the MCP server)
+
+**Essential** — `aura_get_ticket_context`, `aura_add_comment`, `aura_upload_attachment`, `aura_update_ticket_status` *(guarded)*, `aura_create_subtask`, `aura_add_checklist_item`, `aura_toggle_checklist_item`, `aura_set_custom_field`.
+
+**Important** — `aura_search_tickets`, `aura_list_tickets`, `aura_update_ticket` *(status guarded)*, `aura_list_projects`, `aura_list_comments`, `aura_upload_comment_attachment`, `aura_list_attachments`, `aura_download_attachment`.
+
+**Nice-to-have** — `aura_assign_ticket`, `aura_create_ticket`, `aura_list_labels`, `aura_list_users`, `aura_log_time`, `aura_get_activity`.
+
+**Search data** — `aura_search_console_query`, `aura_ga4_report`, `aura_pagespeed_audit`.
+
+**Conversation** — `aura_start_conversation`, `aura_reply_in_conversation`, `aura_resolve_conversation`.
+
+> Asking a question (`aura_start_conversation`) used to require an exit/resume dance because `claude -p` was stateless. In Pi the session just idles — when the human answers, a new webhook event arrives and `sendUserMessage` continues the **same** session. No session-ID bookkeeping.
+
+## Critical rules (preserved from the Python stack)
+
+- **Agents must not change ticket status.** Enforced at runtime by a `tool_call` interceptor (`guardStatus`): `aura_update_ticket_status` is blocked outright; the `status` field is stripped from `aura_update_ticket`. The orchestrator owns status (In Progress on start, Done on `agent_end`).
+- **Working dir must already exist** — never auto-created (`resolveWorkingDir` returns null if missing; the ticket is skipped with a log line).
+- **Run one SignalR subscription per Aloita auth user.** Like the receiver, one connection per Pi process.
+- **Stable per-run `sessionId`.** On `session_start` the extension mints one UUID (`runSessionId`) and sends it in the Subscribe payload's `SessionId` field, then reuses that same id for every per-ticket artifact — `agent-task/start`|`end`, usage, diff, and the agent-log stream. This lets the Agent Activity orbit render each Pi run as its own satellite and pin activity to it (without it, the orbit merges an agent's connections into a single satellite).
+
+## Capability tiers (global, broadcast on connect)
+
+Capabilities tell Aloita what models this machine can run and what they cost. Aloita uses them two ways:
+
+1. **Pricing** — upserts an `AgentModelPricing` row (`Source=ClientRegistered`, never clobbering an `AdminOverride`) so `/cost` can price runs.
+2. **Complexity mapping** — links each model into the per-user complexity-tier admin UI, so Aloita's `AnalyzeTaskComplexity` flow can stamp the right model on a ticket based on its tier.
+
+This is **global config** (not per-project) — put it in `~/.pi/aloita.json` so every Pi session on this machine advertises the same set. Two sources, unioned:
+
+- `capabilities[]` — top-level fallback, registered against the auth user (the `.env` key).
+- `userMappings[<userId>].capabilities[]` — explicit per agent user (**preferred**).
+
+```json
+"userMappings": {
+  "927fc980-4cd6-4323-ac72-2a9be24f2730": {
+    "tool": "pi",
+    "capabilities": [
+      { "tool": "pi", "provider": "anthropic", "model": "claude-sonnet-4-5",
+        "displayName": "Sonnet 4.5 (medium)",
+        "inputCostPerMTok": 3, "outputCostPerMTok": 15,
+        "cachedInputCostPerMTok": 0.3, "cacheWriteCostPerMTok": 3.75 }
+    ]
+  }
+}
+```
+
+**Auth binding:** Aloita attributes `RegisterCapabilities` to the *connected* user; only SuperAdmin can register for other users. So the auth user's caps go on the main connection; each *other* mapped user gets its own helper connection (authenticated with that user's `apiKey`, `registerOnly` mode — no Subscribe, just kept alive so the caps stay registered). Include `apiKey` on every non-auth `userMappings` entry.
+
+On `session_start`, the extension resolves the auth user via `GET /api/profile`, builds the plan (`src/capabilities.ts`), and starts the main + helper connections. `/aloita-connect` re-runs the whole flow.
+
+## Usage post-back (on `agent_end`)
+
+When the Pi job for a ticket finishes (`agent_end`), the extension POSTs the run's token/cost to `/api/tickets/{id}/agent-run-usage`. This is the smart orchestration moment — usage is accumulated **while a ticket is active** and flushed exactly once when the turn ends.
+
+- **Source of truth:** Pi's per-assistant-message `usage` on `message_end` (`input`, `output`, `cacheRead`, `cacheWrite`, `totalTokens`, `cost.total`), plus `message.provider` / `message.model`. This is the Pi equivalent of Claude's authoritative `result.modelUsage`.
+- **Per-model breakdown:** aggregated by `(provider, model)` and sent as the `models[]` array Aloita's `AgentRunUsageEndpoints` expects. One `AgentRunUsage` row is written per model.
+- **Best-effort, never blocks:** posts happen after the turn ends and before finalize; a failure logs a warning but does not block status/queue drain.
+- **Zero-row visibility:** if no usage was captured (e.g. the turn was aborted), a single zero-token row is still posted so the run shows up in `/cost` rather than silently absent — matching the Python receiver.
+- **Auto-stub pricing:** Aloita auto-creates an `AgentModelPricing` stub for any unknown `(tool, provider, model)` triple, so cost is never a silent `$0`.
+
+Toggle with `postUsage: false` to disable.
+
+## Run diff post-back (on `agent_end`)
+
+When the Pi job for a ticket finishes, the extension captures what the agent changed in the ticket's working directory and POSTs a unified diff to Aloita's per-ticket **diff viewer** — `POST /api/tickets/{id}/diffs` (`TicketDiffEndpoints.cs`). This is the "review without leaving the kanban" artifact, ported 1:1 from the Python receiver's `post_agent_run_diff`.
+
+- **Baseline snapshot at start:** when a ticket is injected, the extension snapshots the working dir's HEAD (`git rev-parse --short HEAD`) *before* the agent runs. The post-run diff is taken against that baseline, so it captures **both committed and uncommitted changes** made during this run — not the whole history.
+- **Untracked files included:** `git diff <base>` is appended with each untracked file (`git ls-files --others --exclude-standard`) rendered as a new-file diff via `git diff --no-index -- /dev/null <path>` — exactly the receiver's technique.
+- **Body:** `{ title, diffText, source: AgentRun(1), baseRef, headRef, sessionId }`. The server stores the raw diff verbatim and caches parsed summary counts (files/additions/deletions).
+- **Best-effort, never blocks:** runs last in `agent_end` (after status is finalized), gated on `postDiff`. A non-git folder, a git failure, or an API error logs a warning and never affects the ticket. `postDiff: false` disables it.
+- **No working dir → skipped:** when a ticket's working dir doesn't resolve (or isn't a git repo), capture is skipped silently.
+
+## Agent log streaming (real time)
+
+While a ticket is active, the extension mirrors the agent's activity to Aloita's per-ticket **agent-log** tab in real time — a direct port of the Python receiver's `AuraAgentLogPusher`. This is what makes a run observable live (and reviewable afterward) without the old subprocess/dashboard.
+
+- **Same pipeline & contract as the receiver:** entries are buffered and flushed in batches of ≤ 50 every 0.5 s to `POST /api/tickets/{id}/agent-log/batch`, each carrying `{ content, sessionId, source, timestamp }`. Best-effort — a failed push logs a warning and never blocks the run.
+- **No subprocess → events are the source.** The old receiver read the CLI's stdout line-by-line. Here Pi *is* the agent, so the equivalent "display lines" are captured from Pi's streaming events and fed to the same pusher:
+  - `message_update` → assistant **text deltas**, split into newline-delimited lines (the analog of the receiver's `read_line_unbounded`). Thinking blocks are intentionally not streamed, matching the old adapter which surfaced display text only.
+- **No tool noise.** Tool calls and results (`▶ bash(…)` / `✓ bash` / `✗ … (error)` markers) are intentionally **not** logged — only the assistant's own text and the lifecycle markers are streamed, to keep the log readable.
+- **Lifecycle mirrors the receiver:** a `--- started ---` line is pushed when the ticket is injected; the pusher is drained + flushed (`close()`) in `agent_end` **before** finalize/usage (the same ordering the receiver's `finally` block uses), and on StopTask/shutdown.
+- **Toggle:** `streamAgentLog: false` disables it with zero overhead (no pusher is created; the feed handlers short-circuit).
+
+The implementation is isolated in `src/agent-log.ts` (`AgentLogPusher`, `TextLineBuffer`, `createAuraAgentLogPoster`), unit-tested with Node's built-in test runner (`npm test`).
+
+## Logging
+
+The extension **never writes to stdout/stderr** — that would corrupt Pi's TUI rendering. All diagnostics (connection events, webhook handling, usage/diff post-backs, auto-start launches, capability registration) go to a **log file**:
+
+``
+~/.pi/aloita.log
+```
+
+Tail it in a separate terminal while Pi runs:
+
+```powershell
+Get-Content ~/.pi/aloita.log -Wait -Tail 20
+# or on Linux/macOS:
+tail -f ~/.pi/aloita.log
+```
+
+**Log levels** (set via `ALOITA_LOG_LEVEL`, case-insensitive): `debug` > `info` (default) > `warn` > `error` > `off`.
+
+**Custom log file** (optional): set `ALOITA_LOG_FILE` to any path (`~` is expanded).
+
+User-facing events (ticket started/finished, errors) still appear as transient toast notifications via `ctx.ui.notify()`, and connection state lives in the footer via `ctx.ui.setStatus()` — the correct Pi UI channels. `/aloita-status` shows a concise one-line summary as a toast; the full detail goes to the log file.
+
+## Status & caveats
+
+This is a v1 port. Tested live: REST (`GET /api/projects` → 28 projects), SignalR (connect → handshake → subscribe → ping → clean disconnect), capability plan build + auth-user resolution, and usage POST + read-back all pass against the real server.
+
+Known differences from the Python receiver, by design:
+- **Subscription billing only.** The old receiver had two billing paths (Agent SDK credit via `claude -p`, and subscription via the loop bridge). A live Pi session is subscription-billed.
+- **No web dashboard.** Visibility is the Pi status footer + notifications + `/aloita-status`. The full event log / terminal-stream dashboard is gone.
+- **`autoFinalizeOnAgentEnd` marks Done after the triggered turn.** If the agent posts a `aura_start_conversation` and stops, the ticket is still marked Done (matching the old receiver's behavior on `claude -p` exit) — the conversation is resumed when the next webhook arrives. Set `autoFinalizeOnAgentEnd: false` to keep tickets In Progress until a human moves them.
+
+## Layout
+
+```
+src/
+├── index.ts        # entry: lifecycle, webhook→sendUserMessage, queue, finalize, status guard, usage flush, commands
+├── config.ts       # env + JSON config loader (global userMappings + capabilities)
+├── aura-client.ts  # fetch-based port of aura_client.py (get/post/put/delete/upload/download)
+├── signalr.ts      # hand-rolled SignalR JSON protocol over ws (main + registerOnly helper mode)
+├── tools.ts        # all 28 aura_* tools (port of server.py)
+├── prompts.ts      # embedded command templates + label→command routing
+├── capabilities.ts # builds the capability broadcast plan (main + per-user helper split)
+├── agent-log.ts    # real-time agent-log streamer (port of AuraAgentLogPusher) + TextLineBuffer + tool-summary helpers
+├── usage.ts        # accumulates per-model token/cost, posts to /agent-run-usage on agent_end
+├── working-dir.ts  # resolveWorkingDir + shouldClaimTicket (port of resolve_working_dir)
+├── project-launcher.ts # pure auto-start logic (normalize/detect/plan) — see §Auto-start supervisor
+├── config-store.ts # read/write/merge the JSON config file for /aloita-configure
+├── aloita-configure.ts # interactive /aloita-configure settings UI (SelectList + SettingsList)
+```

package/config.example.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "./config.schema.json",
+  "aloitaUrl": "https://srv1322862.hstgr.cloud",
+  "apiKey": "kai_REPLACE_ME",
+
+  "subscription": {
+    "eventNames": ["TicketCreated", "TicketStatusChanged"],
+    "statusFilters": {
+      "TicketCreated": ["Todo"],
+      "TicketStatusChanged": ["Todo"]
+    },
+    "allProjects": true,
+    "allUsers": false,
+    "projectIds": [],
+    "userIds": ["5fcb57d1-f3a8-4501-b6f6-82228425b6a3"]
+  },
+
+  "projectFolders": {
+    "00000000-0000-0000-0000-000000000000": "C:\\Users\\frank\\source\\repos\\my-project"
+  },
+
+  "projectFilter": "",
+  "matchAllProjects": false,
+  "repos": "C:\\Users\\frank\\source\\repos",
+
+  "labelToCommand": {
+    "plan": "aura-plan-ticket",
+    "review": "aura-review-ticket",
+    "document": "aura-document",
+    "workflow-implementation": "aloita-workflow-implement-with-pr"
+  },
+  "defaultCommand": "aura-work-on-ticket",
+
+  "guardStatus": true,
+  "autoFinalizeOnAgentEnd": true,
+  "postUsage": true,
+  "// postDiff": "Capture the run's git diff (vs the HEAD snapshot taken at ticket start) and POST it to Aloita's per-ticket diff viewer (POST /api/tickets/{id}/diffs). Port of the Python receiver's post_agent_run_diff. Best-effort; never blocks or fails the ticket.",
+  "postDiff": true,
+  "// streamAgentLog": "Stream the agent's text + tool activity to Aloita's per-ticket agent-log tab in real time (POST /api/tickets/{id}/agent-log/batch). Port of the Python receiver's AuraAgentLogPusher. Best-effort; never blocks.",
+  "streamAgentLog": true,
+  "dedupWindowSeconds": 2,
+
+  "// logging": "Diagnostics go to ~/.pi/aloita.log (never stdout/stderr, which would corrupt Pi's TUI). Override the path via env ALOITA_LOG_FILE. Level via ALOITA_LOG_LEVEL (debug/info/warn/error/off, default info). See README §Logging.",
+
+  "// autoStart": "Supervisor mode: when on, this Pi session periodically polls /api/projects and spawns a detached child `pi` in each NEW project's folder, so a Pi CLI is online the moment a project is created — no manual `cd <folder> && pi`. Off by default. See README §Auto-start supervisor.",
+  "autoStartProjects": false,
+  "// autoStartPollSeconds": "Poll interval for new projects, in seconds.",
+  "autoStartPollSeconds": 60,
+  "// autoStartCreateFolder": "mkdir the project folder if it doesn't exist yet (a brand-new Aloita project usually has no folder on disk). This is what makes 'no manual step' actually work.",
+  "autoStartCreateFolder": true,
+  "// autoStartPiCommand": "Override the pi command to spawn (defaults to pi.cmd on Windows, pi elsewhere).",
+  "autoStartPiCommand": "",
+  "// autoStartExcludeProjects": "Project ids to never auto-start.",
+  "autoStartExcludeProjects": [],
+  "// autoStartSeedExisting": "When true, launch a child pi for EVERY existing project on supervisor startup (not just new ones). Default false — only newly-created projects are launched.",
+  "autoStartSeedExisting": false,
+  "// autoStartProjectIds": "Allow-list of project ids that the supervisor should auto-start a child pi for. A brand-new project does nothing until you add its id here. Easiest via /aloita-configure.",
+  "autoStartProjectIds": [],
+
+  "// capabilities": "GLOBAL fallback caps registered against the auth user. Prefer userMappings below. Each entry pushes pricing into Aloita AND links the model into the per-user complexity-tier admin UI.",
+  "capabilities": [],
+
+  "// userMappings": "Per-agent-user profiles. Key = Aloita agent user id. The auth user (env key) may omit apiKey; OTHER users must include their own apiKey so their capabilities register over a connection authenticated as them (Aloita binds RegisterCapabilities to the connected user).",
+  "userMappings": {
+    "927fc980-4cd6-4323-ac72-2a9be24f2730": {
+      "tool": "pi",
+      "capabilities": [
+        {
+          "tool": "pi",
+          "provider": "anthropic",
+          "model": "claude-sonnet-4-5",
+          "displayName": "Sonnet 4.5 (medium complexity)",
+          "inputCostPerMTok": 3,
+          "outputCostPerMTok": 15,
+          "cachedInputCostPerMTok": 0.3,
+          "cacheWriteCostPerMTok": 3.75
+        },
+        {
+          "tool": "pi",
+          "provider": "anthropic",
+          "model": "claude-haiku-4-5",
+          "displayName": "Haiku 4.5 (low complexity)",
+          "inputCostPerMTok": 0.8,
+          "outputCostPerMTok": 4,
+          "cachedInputCostPerMTok": 0.08,
+          "cacheWriteCostPerMTok": 1
+        }
+      ]
+    }
+  }
+}

package/docs/status-indicator-preview.md

@@ -0,0 +1,65 @@
+# Aloita Status Bar — Indicator Styling (before / after)
+
+Ticket: **Pi Status Bar: Improve Aloita Connection Indicator Styling**
+
+## Requirements (all met)
+
+1. ✅ Status circle (dot) **green** to signal an active connection
+2. ✅ Label **capitalized** to "Aloita" (was "aloita")
+3. ✅ "connected" text **green** for visual clarity
+
+## How it renders
+
+Color is applied via Pi's `Theme.fg(color, text)` (`ctx.ui.theme`), which embeds
+ANSI codes the footer renders natively. `success` = green by default and respects
+the user's theme. The footer's `sanitizeStatusText` does not strip ANSI, and its
+`truncateToWidth` (from `@earendil-works/pi-tui`) is ANSI-aware, so truncation
+stays correct.
+
+### Before
+
+```
+○ aloita: connected
+● aloita: connected · working #abc-123 · +2 queued
+✕ aloita: connection lost: timeout
+```
+(all one color — the terminal's default fg)
+
+### After
+
+```
+{green}○{reset} Aloita: {green}connected{reset}
+{green}●{reset} Aloita: {green}connected{reset} · working #abc-123 · +2 queued
+{dim}✕{reset} Aloita: {dim}connection lost: timeout{reset}
+```
+
+Concrete ANSI (what `Theme.fg` actually emits):
+
+| State | Dot | Label | Connection |
+|---|---|---|---|
+| Connected & idle | `\x1b[32m○\x1b[39m` (green hollow) | `Aloita` | `\x1b[32mconnected\x1b[39m` (green) |
+| Working a ticket | `\x1b[32m●\x1b[39m` (green filled) | `Aloita` | `\x1b[32mconnected\x1b[39m` (green) |
+| Disconnected | `\x1b[2m✕\x1b[39m` (dim) | `Aloita` | `\x1b[2m<connectionState>\x1b[39m` (dim) |
+
+## Design decisions
+
+- **Green = "active connection" only.** Reserved for the connected/working
+  indicator as the ticket specifies. The working/queue suffix is left uncolored
+  so the green indicator stands out.
+- **Disconnected is dim, not red.** Neutral — avoids crying wolf during benign
+  states like "not started" / "stopped" at startup. The `✕` glyph already
+  communicates "down". (A red-for-real-errors variant is a trivial follow-up if
+  desired: pass `"error"` instead of `"dim"` in `buildStatusText`.)
+- **Internal `setStatus` key stays lowercase `"aloita"`.** The footer renders
+  only the value, not the key; the capitalized "Aloita" is the visible label.
+
+## Files
+
+- `src/status.ts` — pure `buildStatusText(input, colorizer)` + types
+- `src/status.test.ts` — 12 unit tests (`node:test`, fake tag-wrapping colorizer)
+- `src/index.ts` — `renderStatus` delegates to `buildStatusText(..., ctx.ui.theme)`
+
+## Verification
+
+- `npm run build` (`tsc --noEmit`): **green**
+- `npm test`: **42/42 pass** (12 new + 30 prior)