@intent-systems/nexus 2026.1.5-3

package/docs/automation/nexus-sync.md

@@ -0,0 +1,371 @@
+---
+summary: "Daily NexusBot upstream sync monitoring via cron jobs"
+read_when:
+  - Setting up automated upstream monitoring
+  - Configuring daily sync checks for nexus and pi-ai
+  - Understanding cron job patterns in Nexus
+---
+
+# NexusBot Sync Automation
+
+Monitor nexus and pi-ai upstreams daily using Nexus cron jobs to stay informed about changes that may need porting.
+
+## Overview
+
+Nexus is a fork of NexusBot and uses pi-ai packages for authentication. To keep nexus current, we need to monitor:
+- **NexusBot repository**: New commits in the main branch
+- **Pi-AI packages**: Version updates for `@mariozechner/pi-agent-core` and `@mariozechner/pi-coding-agent`
+
+The `upstream-sync` skill (see `skills/upstream-sync/SKILL.md`) provides scripts to check both upstreams. This document shows how to automate these checks using Nexus cron jobs.
+
+## Quick Start
+
+Create a daily cron job that runs at 9 AM:
+
+```bash
+nexus cron add \
+  --name "Daily upstream sync check" \
+  --cron "0 9 * * *" \
+  --tz "America/Los_Angeles" \
+  --session isolated \
+  --wake now \
+  --message "Run the upstream-sync skill (check-all.sh) and show me a summary of any new commits or version updates." \
+  --deliver \
+  --provider last
+```
+
+This will:
+1. Run daily at 9 AM (Pacific time)
+2. Execute in an isolated session (won't pollute your main session)
+3. Check both nexus and pi-ai for changes
+4. Send you a notification via your last-used channel (WhatsApp, Telegram, etc.)
+
+## Cron Job Configuration
+
+### Schedule Options
+
+**Daily at specific time:**
+```bash
+--cron "0 9 * * *" --tz "America/Los_Angeles"
+```
+
+**Weekdays only (Mon-Fri):**
+```bash
+--cron "0 9 * * 1-5" --tz "America/Los_Angeles"
+```
+
+**Every 12 hours:**
+```bash
+--every "12h"
+```
+
+**One-time check (tomorrow at 9 AM):**
+```bash
+--at "2026-01-10T09:00:00-08:00"
+```
+
+### Session Options
+
+**Isolated session (recommended):**
+```bash
+--session isolated --wake now
+```
+- Runs in separate session (`cron:<jobId>`)
+- Won't clutter your main conversation history
+- Can run in parallel with main session
+- Still posts a summary to main when complete
+
+**Main session:**
+```bash
+--session main --wake now
+```
+- Runs in your main session
+- Shows full output in conversation history
+- Serialized with other main session activity
+
+### Delivery Options
+
+**Deliver to last-used provider:**
+```bash
+--deliver --provider last
+```
+
+**Deliver to specific provider:**
+```bash
+--deliver --provider whatsapp --to "+1234567890"
+```
+
+**No delivery (main session summary only):**
+```bash
+# Omit --deliver flag
+```
+
+## Example Configurations
+
+### 1. Daily morning check (recommended)
+
+Check every morning and get notified via your preferred messaging app:
+
+```bash
+nexus cron add \
+  --name "Morning upstream sync" \
+  --cron "0 8 * * *" \
+  --tz "America/Los_Angeles" \
+  --session isolated \
+  --wake now \
+  --message "Check upstream-sync (all sources) and notify me if there are new commits or package updates. Focus on: auth, sessions, gateway, ODU patterns." \
+  --deliver \
+  --provider last
+```
+
+### 2. Weekday check (business hours only)
+
+Skip weekends:
+
+```bash
+nexus cron add \
+  --name "Weekday upstream sync" \
+  --cron "0 9 * * 1-5" \
+  --tz "America/Los_Angeles" \
+  --session isolated \
+  --wake now \
+  --message "Run upstream-sync check-all.sh and summarize any changes." \
+  --deliver \
+  --provider last
+```
+
+### 3. Quiet check (no notifications)
+
+Check daily but only add summary to main session (no push notifications):
+
+```bash
+nexus cron add \
+  --name "Silent upstream sync" \
+  --cron "0 6 * * *" \
+  --tz "America/Los_Angeles" \
+  --session isolated \
+  --wake now \
+  --message "Run upstream-sync check-all.sh and summarize findings."
+  # Note: no --deliver flag
+```
+
+### 4. Weekly detailed review
+
+Once per week, get a more detailed summary:
+
+```bash
+nexus cron add \
+  --name "Weekly upstream review" \
+  --cron "0 10 * * 1" \
+  --tz "America/Los_Angeles" \
+  --session isolated \
+  --wake now \
+  --message "Run upstream-sync check-all.sh with --limit 20 to show more commits. Review each commit and highlight any that should be ported to nexus, especially: auth changes, session improvements, gateway fixes, ODU patterns, or API updates." \
+  --deliver \
+  --provider last
+```
+
+## Managing Cron Jobs
+
+### List all cron jobs
+
+```bash
+nexus cron list
+```
+
+With JSON output:
+```bash
+nexus cron list --json
+```
+
+### View specific job details
+
+```bash
+nexus cron list --json | jq '.jobs[] | select(.name | contains("upstream"))'
+```
+
+### Edit existing job
+
+```bash
+# Change schedule
+nexus cron edit <job-id> --cron "0 10 * * *"
+
+# Change message
+nexus cron edit <job-id> --message "New message text"
+
+# Enable/disable delivery
+nexus cron edit <job-id> --deliver
+```
+
+### Disable/enable job
+
+```bash
+# Temporarily disable
+nexus cron disable <job-id>
+
+# Re-enable
+nexus cron enable <job-id>
+```
+
+### Remove job
+
+```bash
+nexus cron rm <job-id>
+```
+
+### Test job manually
+
+Run the job immediately without waiting for schedule:
+
+```bash
+nexus cron run <job-id>
+```
+
+### View job run history
+
+See past executions:
+
+```bash
+nexus cron runs --id <job-id> --limit 10
+```
+
+## What to Watch For
+
+When you receive upstream sync notifications, prioritize porting these types of changes:
+
+### NexusBot commits to review:
+- **Authentication**: OAuth, token management, credential storage
+- **Sessions**: Session format, metadata, compaction
+- **Gateway**: Message routing, provider integration, WebSocket handling
+- **Agent runtime**: ODU patterns, agent lifecycle, control plane
+- **API changes**: New Anthropic SDK features or breaking changes
+
+### Pi-AI package updates to review:
+- **Auth/OAuth**: Changes to authentication flow
+- **Session management**: Session format or API changes
+- **Agent runtime**: Core agent behavior or tool changes
+- **Breaking changes**: Version jumps or deprecation notices
+
+## Advanced: Custom Filters
+
+### Check only NexusBot commits by specific author
+
+```bash
+nexus cron add \
+  --name "Track Peter's commits" \
+  --cron "0 9 * * *" \
+  --tz "America/Los_Angeles" \
+  --session isolated \
+  --wake now \
+  --message "Run check-nexus.sh --author peter --limit 10 and summarize the changes." \
+  --deliver \
+  --provider last
+```
+
+### Check only auth-related commits
+
+```bash
+nexus cron add \
+  --name "Auth change monitor" \
+  --cron "0 9 * * *" \
+  --tz "America/Los_Angeles" \
+  --session isolated \
+  --wake now \
+  --message "Run check-nexus.sh --grep auth --limit 10 and tell me if any auth changes need porting." \
+  --deliver \
+  --provider last
+```
+
+### Check recent commits only (last 7 days)
+
+```bash
+nexus cron add \
+  --name "Recent changes only" \
+  --every "12h" \
+  --session isolated \
+  --wake now \
+  --message "Run check-nexus.sh --since '7 days ago' --limit 20 and highlight important changes." \
+  --deliver \
+  --provider last
+```
+
+## Troubleshooting
+
+### Job not running
+
+Check if cron is enabled:
+```bash
+nexus cron status
+```
+
+If disabled, enable via config:
+```json5
+{
+  "cron": {
+    "enabled": true
+  }
+}
+```
+
+### Job running but no output
+
+Check the job's run history:
+```bash
+nexus cron runs --id <job-id> --limit 5
+```
+
+Look for errors in the logs:
+```bash
+# Gateway logs show cron execution
+tail -f ~/nexus/state/logs/gateway.log | grep cron
+```
+
+### Notification not delivered
+
+Verify your provider is configured:
+```bash
+nexus providers list
+```
+
+Try running manually to see output:
+```bash
+nexus cron run <job-id> --force
+```
+
+### Paths not found (nexus or nexus)
+
+Set environment variables in your config or shell:
+```bash
+export NEXUS_PATH="/path/to/nexus"
+export NEXUS_PATH="/path/to/nexus"
+```
+
+Or specify in the cron message:
+```bash
+--message "Run check-nexus.sh --nexus-path /path/to/nexus and summarize."
+```
+
+## Disabling Sync Monitoring
+
+To temporarily stop all upstream sync checks:
+
+1. List upstream sync jobs:
+   ```bash
+   nexus cron list | grep -i upstream
+   ```
+
+2. Disable each job:
+   ```bash
+   nexus cron disable <job-id>
+   ```
+
+3. Or remove permanently:
+   ```bash
+   nexus cron rm <job-id>
+   ```
+
+## See Also
+
+- [Cron system documentation](../cron.md) - Full cron system RFC
+- [Upstream sync skill](../../skills/upstream-sync/SKILL.md) - Manual sync checking
+- [Gateway documentation](../gateway.md) - Gateway architecture and scheduling

package/docs/background-process.md

@@ -0,0 +1,74 @@
+---
+summary: "Background bash execution and process management"
+read_when:
+  - Adding or modifying background bash behavior
+  - Debugging long-running bash tasks
+---
+
+# Background Bash + Process Tool
+
+Nexus runs shell commands through the `bash` tool and keeps long‑running tasks in memory. The `process` tool manages those background sessions.
+
+## bash tool
+
+Key parameters:
+- `command` (required)
+- `yieldMs` (default 10000): auto‑background after this delay
+- `background` (bool): background immediately
+- `timeout` (seconds, default 1800): kill the process after this timeout
+- `elevated` (bool): run on host if elevated mode is enabled/allowed
+- Need a real TTY? Use the tmux skill.
+- `workdir`, `env`
+
+Behavior:
+- Foreground runs return output directly.
+- When backgrounded (explicit or timeout), the tool returns `status: "running"` + `sessionId` and a short tail.
+- Output is kept in memory until the session is polled or cleared.
+
+Environment overrides:
+- `PI_BASH_YIELD_MS`: default yield (ms)
+- `PI_BASH_MAX_OUTPUT_CHARS`: in‑memory output cap (chars)
+- `PI_BASH_JOB_TTL_MS`: TTL for finished sessions (ms, bounded to 1m–3h)
+
+Config (preferred):
+- `agent.bash.backgroundMs` (default 10000)
+- `agent.bash.timeoutSec` (default 1800)
+- `agent.bash.cleanupMs` (default 1800000)
+
+## process tool
+
+Actions:
+- `list`: running + finished sessions
+- `poll`: drain new output for a session (also reports exit status)
+- `log`: read the aggregated output (supports `offset` + `limit`)
+- `write`: send stdin (`data`, optional `eof`)
+- `kill`: terminate a background session
+- `clear`: remove a finished session from memory
+- `remove`: kill if running, otherwise clear if finished
+
+Notes:
+- Only backgrounded sessions are listed/persisted in memory.
+- Sessions are lost on process restart (no disk persistence).
+- Session logs are only saved to chat history if you run `process poll/log` and the tool result is recorded.
+- `process list` includes a derived `name` (command verb + target) for quick scans.
+- `process log` uses line-based `offset`/`limit` (omit `offset` to grab the last N lines).
+
+## Examples
+
+Run a long task and poll later:
+```json
+{"tool": "bash", "command": "sleep 5 && echo done", "yieldMs": 1000}
+```
+```json
+{"tool": "process", "action": "poll", "sessionId": "<id>"}
+```
+
+Start immediately in background:
+```json
+{"tool": "bash", "command": "npm run build", "background": true}
+```
+
+Send stdin:
+```json
+{"tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n"}
+```

package/docs/bash.md

@@ -0,0 +1,32 @@
+---
+summary: "Bash tool usage, stdin modes, and TTY support"
+read_when:
+  - Using or modifying the bash tool
+  - Debugging stdin or TTY behavior
+---
+
+# Bash tool
+
+Run shell commands in the workspace. Supports foreground + background execution via `process`.
+
+## Parameters
+
+- `command` (required)
+- `yieldMs` (default 10000): auto-background after delay
+- `background` (bool): background immediately
+- `timeout` (seconds, default 1800): kill on expiry
+- `elevated` (bool): run on host if elevated mode is enabled/allowed
+- Need a real TTY? Use the tmux skill.
+
+## Examples
+
+Foreground:
+```json
+{"tool":"bash","command":"ls -la"}
+```
+
+Background + poll:
+```json
+{"tool":"bash","command":"npm run build","yieldMs":1000}
+{"tool":"process","action":"poll","sessionId":"<id>"}
+```

package/docs/bedrock.md

@@ -0,0 +1,71 @@
+---
+summary: "Use Amazon Bedrock (Converse API) models with Nexus"
+read_when:
+  - You want to use Amazon Bedrock models with Nexus
+  - You need AWS credential/region setup for model calls
+---
+# Amazon Bedrock
+
+Nexus can use **Amazon Bedrock** models via pi‑ai’s **Bedrock Converse**
+streaming provider. Bedrock auth uses the **AWS SDK default credential chain**,
+not an API key.
+
+## What pi‑ai supports
+
+- Provider: `amazon-bedrock`
+- API: `bedrock-converse-stream`
+- Auth: AWS credentials (env vars, shared config, or instance role)
+- Region: `AWS_REGION` or `AWS_DEFAULT_REGION` (default: `us-east-1`)
+
+## Setup (manual)
+
+1) Ensure AWS credentials are available on the **gateway host**:
+
+```bash
+export AWS_ACCESS_KEY_ID="AKIA..."
+export AWS_SECRET_ACCESS_KEY="..."
+export AWS_REGION="us-east-1"
+# Optional:
+export AWS_SESSION_TOKEN="..."
+export AWS_PROFILE="your-profile"
+```
+
+2) Add a Bedrock provider and model to your config:
+
+```json5
+{
+  models: {
+    providers: {
+      "amazon-bedrock": {
+        baseUrl: "https://bedrock-runtime.us-east-1.amazonaws.com",
+        api: "bedrock-converse-stream",
+        models: [
+          {
+            id: "anthropic.claude-3-7-sonnet-20250219-v1:0",
+            name: "Claude 3.7 Sonnet (Bedrock)",
+            reasoning: true,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 200000,
+            maxTokens: 8192
+          }
+        ]
+      }
+    }
+  },
+  agents: {
+    defaults: {
+      model: { primary: "amazon-bedrock/anthropic.claude-3-7-sonnet-20250219-v1:0" }
+    }
+  }
+}
+```
+
+## Notes
+
+- Bedrock requires **model access** enabled in your AWS account/region.
+- If you use profiles, set `AWS_PROFILE` on the gateway host.
+- Reasoning support depends on the model; check the Bedrock model card for
+  current capabilities.
+- If you prefer a managed key flow, you can also place an OpenAI‑compatible
+  proxy in front of Bedrock and configure it as an OpenAI provider instead.

package/docs/bonjour.md

@@ -0,0 +1,159 @@
+---
+summary: "Bonjour/mDNS discovery + debugging (Gateway beacons, clients, and common failure modes)"
+read_when:
+  - Debugging Bonjour discovery issues on macOS/iOS
+  - Changing mDNS service types, TXT records, or discovery UX
+---
+# Bonjour / mDNS discovery
+
+Nexus uses Bonjour (mDNS / DNS-SD) as a **LAN-only convenience** to discover a running Gateway bridge transport. It is best-effort and does **not** replace SSH or Tailnet-based connectivity.
+
+## Wide-Area Bonjour (Unicast DNS-SD) over Tailscale
+
+If you want iOS node auto-discovery while the Gateway is on another network (e.g. Vienna ⇄ London), you can keep the `NWBrowser` UX but switch discovery from multicast mDNS (`local.`) to **unicast DNS-SD** (“Wide-Area Bonjour”) over Tailscale.
+
+High level:
+
+1) Run a DNS server on the gateway host (reachable via tailnet IP).
+2) Publish DNS-SD records for `_nexus-bridge._tcp` in a dedicated zone (example: `nexus.internal.`).
+3) Configure Tailscale **split DNS** so `nexus.internal` resolves via that DNS server for clients (including iOS).
+
+Nexus standardizes on the discovery domain `nexus.internal.` for this mode. iOS/Android nodes browse both `local.` and `nexus.internal.` automatically (no per-device knob).
+
+### Gateway config (recommended)
+
+On the gateway host (the machine running the Gateway bridge), add to `~/nexus/state/nexus.json` (JSON5):
+
+```json5
+{
+  bridge: { bind: "tailnet" }, // tailnet-only (recommended)
+  discovery: { wideArea: { enabled: true } } // enables nexus.internal DNS-SD publishing
+}
+```
+
+### One-time DNS server setup (gateway host)
+
+On the gateway host (macOS), run:
+
+```bash
+nexus dns setup --apply
+```
+
+This installs CoreDNS and configures it to:
+- listen on port 53 **only** on the gateway’s Tailscale interface IPs
+- serve the zone `nexus.internal.` from the gateway-owned zone file `~/nexus/state/dns/nexus.internal.db`
+
+The Gateway writes/updates that zone file when `discovery.wideArea.enabled` is true.
+
+Validate from any tailnet-connected machine:
+
+```bash
+dns-sd -B _nexus-bridge._tcp nexus.internal.
+dig @<TAILNET_IPV4> -p 53 _nexus-bridge._tcp.nexus.internal PTR +short
+```
+
+### Tailscale DNS settings
+
+In the Tailscale admin console:
+
+- Add a nameserver pointing at the gateway’s tailnet IP (UDP/TCP 53).
+- Add split DNS so the domain `nexus.internal` uses that nameserver.
+
+Once clients accept tailnet DNS, iOS nodes can browse `_nexus-bridge._tcp` in `nexus.internal.` without multicast.
+Wide-area beacons also include `tailnetDns` (when available) so the macOS app can auto-fill SSH targets off-LAN.
+
+### Bridge listener security (recommended)
+
+The bridge port (default `18790`) is a plain TCP service. By default it binds to `0.0.0.0`, which makes it reachable from *any* interface on the gateway machine (LAN/Wi‑Fi/Tailscale).
+
+For a tailnet-only setup, bind it to the Tailscale IP instead:
+
+- Set `bridge.bind: "tailnet"` in `~/nexus/state/nexus.json`.
+- Restart the Gateway (or restart the macOS menubar app via `./scripts/restart-mac.sh` on that machine).
+
+This keeps the bridge reachable only from devices on your tailnet (while still listening on loopback for local/SSH port-forwards).
+
+## What advertises
+
+Only the **Node Gateway** (`nexus` / `nexus gateway`) advertises Bonjour beacons.
+
+- Implementation: `src/infra/bonjour.ts`
+- Gateway wiring: `src/gateway/server.ts`
+
+## Service types
+
+- `_nexus-bridge._tcp` — bridge transport beacon (used by macOS/iOS/Android nodes).
+
+## TXT keys (non-secret hints)
+
+The Gateway advertises small non-secret hints to make UI flows convenient:
+
+- `role=gateway`
+- `lanHost=<hostname>.local`
+- `sshPort=<port>` (defaults to 22 when not overridden)
+- `gatewayPort=<port>` (informational; the Gateway WS is typically loopback-only)
+- `bridgePort=<port>` (only when bridge is enabled)
+- `canvasPort=<port>` (only when the canvas host is enabled + reachable; default `18793`; serves `/__nexus__/canvas/`)
+- `cliPath=<path>` (optional; absolute path to a runnable `nexus` entrypoint or binary)
+- `tailnetDns=<magicdns>` (optional hint; auto-detected from Tailscale when available; may be absent)
+
+## Debugging on macOS
+
+Useful built-in tools:
+
+- Browse instances:
+  - `dns-sd -B _nexus-bridge._tcp local.`
+- Resolve one instance (replace `<instance>`):
+  - `dns-sd -L "<instance>" _nexus-bridge._tcp local.`
+
+If browsing shows instances but resolving fails, you’re usually hitting a LAN policy / multicast issue.
+
+## Debugging in Gateway logs
+
+The Gateway writes a rolling log file (printed on startup as `gateway log file: ...`).
+
+Look for `bonjour:` lines, especially:
+
+- `bonjour: advertise failed ...` (probing/announce failure)
+- `bonjour: ... name conflict resolved` / `hostname conflict resolved`
+- `bonjour: watchdog detected non-announced service; attempting re-advertise ...` (self-heal attempt after sleep/interface churn)
+
+## Debugging on iOS node
+
+The iOS node app discovers bridges via `NWBrowser` browsing `_nexus-bridge._tcp`.
+
+To capture what the browser is doing:
+
+- Settings → Bridge → Advanced → enable **Discovery Debug Logs**
+- Settings → Bridge → Advanced → open **Discovery Logs** → reproduce the “Searching…” / “No bridges found” case → **Copy**
+
+The log includes browser state transitions (`ready`, `waiting`, `failed`, `cancelled`) and result-set changes (added/removed counts).
+
+## Common failure modes
+
+- **Bonjour doesn’t cross networks**: London/Vienna style setups require Tailnet (MagicDNS/IP) or SSH.
+- **Multicast blocked**: some Wi‑Fi networks (enterprise/hotels) disable mDNS; expect “no results”.
+- **Sleep / interface churn**: macOS may temporarily drop mDNS results when switching networks; retry.
+- **Browse works but resolve fails (iOS “NoSuchRecord”)**: make sure the advertiser publishes a valid SRV target hostname.
+  - Implementation detail: `@homebridge/ciao` defaults `hostname` to the *service instance name* when `hostname` is omitted. If your instance name contains spaces/parentheses, some resolvers can fail to resolve the implied A/AAAA record.
+  - Fix: set an explicit DNS-safe `hostname` (single label; no `.local`) in `src/infra/bonjour.ts`.
+
+## Escaped instance names (`\\032`)
+Bonjour/DNS-SD often escapes bytes in service instance names as decimal `\\DDD` sequences (e.g. spaces become `\\032`).
+
+- This is normal at the protocol level.
+- UIs should decode for display (iOS uses `BonjourEscapes.decode` in `apps/shared/NexusKit`).
+
+## Disabling / configuration
+
+- `NEXUS_DISABLE_BONJOUR=1` disables advertising.
+- `NEXUS_BRIDGE_ENABLED=0` disables the bridge listener (and therefore the bridge beacon).
+- `bridge.bind` / `bridge.port` in `~/nexus/state/nexus.json` control bridge bind/port (preferred).
+- `NEXUS_BRIDGE_HOST` / `NEXUS_BRIDGE_PORT` still work as a back-compat override when `bridge.bind` / `bridge.port` are not set.
+- `NEXUS_SSH_PORT` overrides the SSH port advertised in `_nexus-bridge._tcp`.
+- `NEXUS_TAILNET_DNS` publishes a `tailnetDns` hint (MagicDNS) in `_nexus-bridge._tcp`. If unset, the gateway auto-detects Tailscale and publishes the MagicDNS name when possible.
+
+## Related docs
+
+- Discovery policy and transport selection: [`docs/discovery.md`](https://docs.nexus.bot/discovery)
+- Node pairing + approvals: [`docs/gateway/pairing.md`](https://docs.nexus.bot/gateway/pairing)