@tekmidian/pai 0.49.0 → 0.51.0

package/docs/commands/config.md

@@ -15,6 +15,11 @@ pai config <subcommand> [options]
 | Command | Description |
 |---------|-------------|
 | [`pai config path`](#pai-config-path) | Print the PAI_HOME namespace dir and each resolved per-user file |
+| [`pai config yaml`](#pai-config-yaml) | Convert config.json → config.yaml (and voices.json → voices.yaml), with a short |
+| [`pai config list`](#pai-config-list) | Print the main PAI config as YAML (secrets masked). Defaults to what the file explicitly sets. |
+| [`pai config get <path>`](#pai-config-get-path) | Print one config value (dotted path, e.g. search.recencyBoostDays), masked if it looks like a secret. An object/array subtree prints as YAML; pass --json for JSON. |
+| [`pai config set <path> <value>`](#pai-config-set-path-value) | Set one config value (dotted path). Value parsing: true/false, null, numbers, |
+| [`pai config unset <path>`](#pai-config-unset-path) | Remove one config value (dotted path), reverting it to the built-in default |
 | [`pai config migrate`](#pai-config-migrate) | Move config.json, workers.yaml, whisper-rules.md, advisor-mode.json, session-state/, |
 
 ### pai config path
@@ -22,6 +27,85 @@ pai config <subcommand> [options]
 Print the PAI_HOME namespace dir and each resolved per-user file
 
 
+### pai config yaml
+
+Convert config.json → config.yaml (and voices.json → voices.yaml), with a short
+
+# comment above every top-level section and any "_comment"/"_...Note" JSON-
+      workaround key re-attached as a real comment. Verifies the generated YAML
+      re-parses to the exact same data before writing anything; the JSON is then
+      renamed to <name>.migrated-<YYYY-MM-DD> (never deleted). Every writer keeps
+      working unmodified afterwards — see docs/config.md.
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--dry-run` | Print the plan without writing anything |  |
+| `--force` | Regenerate config.yaml (or voices.yaml) even if it already exists |  |
+
+
+### pai config list
+
+Print the main PAI config as YAML (secrets masked). Defaults to what the file explicitly sets.
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--all` | Include every default value, not just what the file sets |  |
+| `--json` | Print JSON instead of YAML |  |
+
+
+### pai config get <path>
+
+Print one config value (dotted path, e.g. search.recencyBoostDays), masked if it looks like a secret. An object/array subtree prints as YAML; pass --json for JSON.
+
+**Arguments**
+
+| Argument | Kind |
+|----------|------|
+| `<path>` | required |
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--json` | Print an object/array value as JSON instead of YAML |  |
+
+
+### pai config set <path> <value>
+
+Set one config value (dotted path). Value parsing: true/false, null, numbers,
+
+[...] / {...} as JSON, else a string. Creates config.yaml (from config.json,
+      if any) on first use, then writes comment-preserving.
+
+**Arguments**
+
+| Argument | Kind |
+|----------|------|
+| `<path>` | required |
+| `<value>` | required |
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--force` | Set an unknown top-level key, or a value of a different type than the default |  |
+
+
+### pai config unset <path>
+
+Remove one config value (dotted path), reverting it to the built-in default
+
+**Arguments**
+
+| Argument | Kind |
+|----------|------|
+| `<path>` | required |
+
+
 ### pai config migrate
 
 Move config.json, workers.yaml, whisper-rules.md, advisor-mode.json, session-state/,

package/docs/commands/daemon.md

@@ -20,6 +20,7 @@ pai daemon <subcommand> [options]
 | [`pai daemon restart`](#pai-daemon-restart) | Send SIGTERM to the running daemon (launchd will restart it) |
 | [`pai daemon install`](#pai-daemon-install) | Install daemon as a launchd service and update ~/.claude.json to use the shim |
 | [`pai daemon uninstall`](#pai-daemon-uninstall) | Remove the launchd service and revert to direct MCP |
+| [`pai daemon keepalive`](#pai-daemon-keepalive) | Show interactive-session cache keepalive config, per-session beat counters, and recent ledger lines |
 | [`pai daemon logs`](#pai-daemon-logs) | Tail the daemon log (/tmp/pai-daemon.log) |
 
 ### pai daemon serve
@@ -58,6 +59,11 @@ Install daemon as a launchd service and update ~/.claude.json to use the shim
 Remove the launchd service and revert to direct MCP
 
 
+### pai daemon keepalive
+
+Show interactive-session cache keepalive config, per-session beat counters, and recent ledger lines
+
+
 ### pai daemon logs
 
 Tail the daemon log (/tmp/pai-daemon.log)

package/docs/commands/worker.md

@@ -44,6 +44,7 @@ pai worker <subcommand> [options]
 | [`pai worker providers`](#pai-worker-providers) | Providers: list (default), add, remove, use, enable, disable, test |
 | [`pai worker classes`](#pai-worker-classes) | Classes: which provider serves draft / implement / review / … |
 | [`pai worker model [what] [model]`](#pai-worker-model-what-model) | Model ids per provider: no args lists them, |
+| [`pai worker capability [name] [providers]`](#pai-worker-capability-name-providers) | Which provider(s) serve a capability (e.g. image), independent of any one |
 | [`pai worker config`](#pai-worker-config) | workers.yaml itself: path, init, migrate, check, inline-keys |
 
 ### pai worker run [args...]
@@ -75,6 +76,11 @@ Grant MCP tools by naming mcp__server__tool in --allowedTools (the server loads
 | `--provider <name>` | Provider to run on (default: active, else routing order) |  |
 | `--class <name>` | Use the provider of this class (draft, implement, review, research, spotcheck, simple, complex, image) |  |
 | `--role <name>` | Alias of --class (roles were renamed to classes) |  |
+| `--capability <name>` | Run on whichever configured provider serves this capability (see `pai worker capability`), not the active provider or --class's own one — e.g. --capability image runs an `engine: image` provider directly, POSTing a prompt and writing the PNG instead of spawning claude |  |
+| `--for <name>` | Alias of --capability |  |
+| `--out <file>` | Where an image-capability run writes its PNG (default: <logDir>/<worker-id>.png) |  |
+| `--size <WxH>` | Image size for an image-capability run, e.g. 1024x1024 (default: 1024x1024) |  |
+| `--timeout-ms <n>` | Timeout for an image-capability run's HTTP request (default: 120000) |  |
 | `--chain <stages>` | Comma-separated stage classes, e.g. draft,implement or draft,implement,review |  |
 | `--agent <name>` | Run the agent definition ~/.claude/agents/<name>.md on a worker |  |
 | `--model <model>` | Override the model for this run. Headless (-p) workers default to the --class model; an interactive launch (no -p) with no --model uses the harness default model from settings.json. |  |
@@ -391,6 +397,8 @@ Example: pai worker providers add glm --url https://…/anthropic \
 --key-file writes only a path to a 0600 file holding it — use one or the other.
 OpenAI-protocol: --protocol openai --upstream-url https://…/v1 (runs via the PAI proxy).
 Codex (ChatGPT plan): --engine codex — runs through the Codex CLI.
+Image generation: --engine image — `pai worker run --capability image` then POSTs
+straight to {url}/images/generations instead of spawning claude.
 
 **Arguments**
 
@@ -412,7 +420,7 @@ Codex (ChatGPT plan): --engine codex — runs through the Codex CLI.
 | `--note <text>` | Human note shown in `providers list` |  |
 | `--protocol <proto>` | anthropic (default) or openai — openai runs through the local PAI proxy |  |
 | `--upstream-url <url>` | Chat Completions base URL (required for --protocol openai) |  |
-| `--engine <engine>` | claude (default) or codex — codex runs `codex exec --json` |  |
+| `--engine <engine>` | claude (default), codex, or image — codex runs `codex exec --json`, image POSTs {url}/images/generations |  |
 | `--context-window <tokens>` | Context window for the meter (default 200000; init event overrides) |  |
 | `--quota-probe <url>` | URL whose JSON first number is the quota percent (0-100) |  |
 | `--cost-tier <1-5>` | Cost tier 1 (cheapest) … 5 (most expensive; default 3) |  |
@@ -543,7 +551,9 @@ Model ids per provider: no args lists them,
 
 `model <model-id>` sets the active provider's default model (back-compat),
 `model <capability>` shows one capability, `model <capability> <model-id>` sets it.
-Capabilities: default, fast, image. --provider targets another provider.
+Capability names are open (default, fast, image, … — any ^[a-z][a-z0-9-]*$ name);
+`pai worker capability` picks which provider serves one across the whole config.
+--provider targets another provider.
 
 **Arguments**
 
@@ -559,6 +569,31 @@ Capabilities: default, fast, image. --provider targets another provider.
 | `--provider <name>` | Provider to read or change (default: the active one) |  |
 
 
+### pai worker capability [name] [providers]
+
+Which provider(s) serve a capability (e.g. image), independent of any one
+
+provider's own model table: no args lists every preference and what it
+resolves to; `capability <name> <provider>[,<provider>…]` sets the
+preference list (first usable one wins); `capability <name> --unset`
+removes it. An `engine: image` provider preferred for "image" runs
+`pai worker run --capability image` directly against its images API.
+
+**Arguments**
+
+| Argument | Kind |
+|----------|------|
+| `[name]` | optional |
+| `[providers]` | optional |
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--unset` | Remove the preference for <name> |  |
+| `--json` | Machine-readable output |  |
+
+
 ### pai worker config
 
 workers.yaml itself: path, init, migrate, check, inline-keys

package/docs/config.md

@@ -0,0 +1,171 @@
+# config.yaml
+
+The main PAI config — everything `src/daemon/config.ts`'s `loadConfig()`
+returns (search defaults, storage backend, notifications, task bus,
+identity, the non-provider `workers` settings) plus whatever else a writer
+has stashed in the file. Before 2026-09-20 this was JSON only, undocumented
+in place, with no CLI or MCP surface to read or change a single value
+without opening the file. `pai config yaml` converts it to YAML with
+comments; `pai config list/get/set/unset` and the matching `config_*` MCP
+tools work whether the file is YAML or JSON.
+
+## File map
+
+| File | Format | Read/written by |
+|---|---|---|
+| `config.yaml` | YAML, comment-preserving | preferred whenever it exists — `readMainConfigRaw`/`writeMainConfigRaw` (`src/daemon/config.ts`) |
+| `config.json` | JSON | fallback when no `config.yaml` exists; unchanged pre-2026-09-20 behaviour |
+| `workers.yaml` | YAML, comment-preserving | `providers`/`classes`/`mcp_sets`/`active` only — see [docs/workers-config.md](workers-config.md) |
+| `voices.yaml` | YAML, comment-preserving | preferred whenever it exists — `loadVoicesConfig`/`migrateVoicesToYaml` (`src/config/voices-config.ts`) |
+| `voices.json` | JSON | fallback; currently an orphan (nothing in `src/` reads it) |
+
+All five live under the PAI_HOME namespace dir (`~/.claude/pai` by default,
+`PAI_HOME=<dir>` to move it; `pai config path` prints the resolved paths).
+
+### Known external readers
+
+`~/.claude/statusline-command.sh` (outside the repo) reads `workers.providers` from the config file using `jq` and therefore sees only JSON. Since `providers` moved into `workers.yaml` on 2026-09-19, that lookup now falls back to `anthropic` (a pre-existing default), which is fine — the file is for display and already treats missing providers gracefully.
+
+**State files stay JSON** — they are written many times a second by the
+daemon or hooks, never hand-edited, and gain nothing from comments:
+`advisor-mode.json`, `scheduler-state.json`, `work-queue.json`,
+`session-routing.json`, `summary-cooldowns.json`, `kg-backfill-state.json`,
+`registry-scan.json`, `session-scan-cache.json`. Only the two human-facing
+config files above became YAML.
+
+## Migrating
+
+```
+pai config yaml --dry-run   # print the plan, write nothing
+pai config yaml             # convert config.json → config.yaml (and
+                             # voices.json → voices.yaml), each JSON file
+                             # renamed to <name>.json.migrated-<YYYY-MM-DD>
+```
+
+What changes on disk:
+- A `#` comment is added above every top-level section, drawn from
+  `PaiDaemonConfig`'s doc comments (`MAIN_CONFIG_SECTION_COMMENTS` in
+  `src/config/main-config.ts`).
+- Any `_comment` / `_...Note` JSON-comment-workaround key is folded into a
+  real `#` comment above the key it was documenting, then dropped from the
+  data.
+- The generated YAML is re-parsed and checked byte-for-byte equal (as JSON)
+  to the original before anything is written — a mismatch aborts with
+  nothing touched.
+- The JSON file is renamed to `config.json.migrated-<YYYY-MM-DD>` (never
+  deleted) only after that check passes.
+- Idempotent: re-running `pai config yaml` once `config.yaml` exists is a
+  no-op unless you pass `--force` (which regenerates it from the current
+  JSON, if any).
+
+Every existing writer (identity, notifications, obsidian vault path,
+setup wizard, memory search settings, the workers section) keeps working
+unmodified — they all go through `readMainConfigRaw`/`writeMainConfigRaw`,
+which pick YAML over JSON automatically.
+
+## Example `config.yaml`
+
+```yaml
+# Unix Domain Socket path for daemon IPC.
+socketPath: /tmp/pai.sock
+
+# How often the daemon re-indexes changed files, in seconds.
+indexIntervalSecs: 300
+
+# How often the daemon runs the embedding pass, in seconds.
+embedIntervalSecs: 600
+
+# Storage backend: "sqlite" (default) or "postgres".
+storageBackend: sqlite
+
+# PostgreSQL connection settings, used when storageBackend is "postgres".
+postgres:
+  connectionString: postgresql://pai:pai@localhost:5432/pai_<username>
+  maxConnections: 5
+  connectionTimeoutMs: 5000
+
+# Embedding model name, used for semantic/hybrid search.
+embeddingModel: Snowflake/snowflake-arctic-embed-m-v1.5
+
+# Daemon log level: debug, info, warn, or error.
+logLevel: info
+
+# Search defaults, applied when an MCP tool or CLI call doesn't specify one.
+search:
+  mode: keyword
+  rerank: true
+  recencyBoostDays: 90
+  defaultLimit: 10
+  snippetLength: 200
+
+# Who "me" is — addresses that count as the user's own. Empty by default
+# and never guessed: nothing is self-addressed until this is set.
+identity:
+  selfEmails:
+    - you@example.com
+  deliverTo: you@example.com
+  sendingAccount: you@example.com
+
+# Non-provider worker settings (pane, routing, tree, cache keepalive,
+# fallback). Providers/classes/mcp_sets live in workers.yaml, not here.
+workers:
+  enabled: true
+  cacheKeepaliveSecs: 15
+```
+
+`postgres.connectionString` and anything under a `key`/`token`/`secret`/
+`password` field is a secret: `pai config list`/`get` and `config_list`/
+`config_get` always print it masked (`****<last4>`), and the file itself is
+written mode `0600`.
+
+## CLI
+
+```
+pai config path                                # resolved paths for every PAI_HOME file
+pai config yaml [--dry-run] [--force]           # convert config.json/voices.json → YAML
+pai config list [--all] [--json]                # file-set values as YAML (--all: defaults merged in too)
+pai config get search.recencyBoostDays          # one value, defaults-merged, masked if secret
+pai config set search.recencyBoostDays 45       # writes config.yaml, comment-preserving
+pai config set some.newThing 1 --force          # allow an unknown top-level key / type mismatch
+pai config unset search.recencyBoostDays        # revert to the built-in default
+```
+
+`pai config set` value parsing: `true`/`false`, `null`, bare numbers,
+`[...]`/`{...}` parsed as JSON, everything else a plain string. `set`
+refuses an unknown top-level key, or a value whose type disagrees with the
+built-in default in `DEFAULTS`, unless `--force`.
+
+Example session:
+
+```
+$ pai config set search.recencyBoostDays 45
+Set search.recencyBoostDays = 45
+
+$ pai config get search.recencyBoostDays
+45
+
+$ pai config list
+search:
+  mode: keyword
+  rerank: true
+  recencyBoostDays: 45
+  defaultLimit: 10
+  snippetLength: 200
+```
+
+## MCP tools
+
+On the `pai` MCP server (`src/daemon-mcp/index.ts`), backed by the same
+`src/config/main-config-ops.ts` functions the CLI calls — masking and
+validation cannot drift between the two surfaces.
+
+- **`config_list`** — `{ "all": false, "json": false }` → the file-set config
+  as YAML (or JSON), secrets masked.
+- **`config_get`** — `{ "path": "search.recencyBoostDays" }` → the
+  defaults-merged value, masked if the path looks like a secret.
+- **`config_set`** — `{ "path": "search.recencyBoostDays", "value": "45" }`
+  → **writes config.yaml** (creating it from config.json first if neither
+  exists yet), comment-preserving. Add `"force": true` to bypass the
+  unknown-key/type checks.
+- **`config_unset`** — `{ "path": "search.recencyBoostDays" }` → **writes
+  the file**, removing the key so it reverts to the built-in default.