nodmix 2026.5.25

package/docs/automation/hooks.md

@@ -0,0 +1,365 @@
+---
+summary: "Hooks: event-driven automation for commands and lifecycle events"
+read_when:
+  - You want event-driven automation for /new, /reset, /stop, and agent lifecycle events
+  - You want to build, install, or debug hooks
+title: "Hooks"
+---
+
+Hooks are small scripts that run when something happens inside the Gateway. They can be discovered from directories and inspected with `nodmix hooks`. The Gateway loads internal hooks only after you enable hooks or configure at least one hook entry, hook pack, legacy handler, or extra hook directory.
+
+There are two kinds of hooks in Nodmix:
+
+- **Internal hooks** (this page): run inside the Gateway when agent events fire, like `/new`, `/reset`, `/stop`, or lifecycle events.
+- **Webhooks**: external HTTP endpoints that let other systems trigger work in Nodmix. See [Webhooks](/automation/cron-jobs#webhooks).
+
+Hooks can also be bundled inside plugins. `nodmix hooks list` shows both standalone hooks and plugin-managed hooks.
+
+## Quick start
+
+```bash
+# List available hooks
+nodmix hooks list
+
+# Enable a hook
+nodmix hooks enable session-memory
+
+# Check hook status
+nodmix hooks check
+
+# Get detailed information
+nodmix hooks info session-memory
+```
+
+## Event types
+
+| Event                    | When it fires                                              |
+| ------------------------ | ---------------------------------------------------------- |
+| `command:new`            | `/new` command issued                                      |
+| `command:reset`          | `/reset` command issued                                    |
+| `command:stop`           | `/stop` command issued                                     |
+| `command`                | Any command event (general listener)                       |
+| `session:compact:before` | Before compaction summarizes history                       |
+| `session:compact:after`  | After compaction completes                                 |
+| `session:patch`          | When session properties are modified                       |
+| `agent:bootstrap`        | Before workspace bootstrap files are injected              |
+| `gateway:startup`        | After channels start and hooks are loaded                  |
+| `gateway:shutdown`       | When gateway shutdown begins                               |
+| `gateway:pre-restart`    | Before an expected gateway restart                         |
+| `message:received`       | Inbound message from any channel                           |
+| `message:transcribed`    | After audio transcription completes                        |
+| `message:preprocessed`   | After media and link preprocessing completes or is skipped |
+| `message:sent`           | Outbound message delivered                                 |
+
+## Writing hooks
+
+### Hook structure
+
+Each hook is a directory containing two files:
+
+```
+my-hook/
+├── HOOK.md          # Metadata + documentation
+└── handler.ts       # Handler implementation
+```
+
+### HOOK.md format
+
+```markdown
+---
+name: my-hook
+description: "Short description of what this hook does"
+metadata:
+  { "nodmix": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
+---
+
+# My Hook
+
+Detailed documentation goes here.
+```
+
+**Metadata fields** (`metadata.nodmix`):
+
+| Field      | Description                                          |
+| ---------- | ---------------------------------------------------- |
+| `emoji`    | Display emoji for CLI                                |
+| `events`   | Array of events to listen for                        |
+| `export`   | Named export to use (defaults to `"default"`)        |
+| `os`       | Required platforms (e.g., `["darwin", "linux"]`)     |
+| `requires` | Required `bins`, `anyBins`, `env`, or `config` paths |
+| `always`   | Bypass eligibility checks (boolean)                  |
+| `install`  | Installation methods                                 |
+
+### Handler implementation
+
+```typescript
+const handler = async (event) => {
+  if (event.type !== "command" || event.action !== "new") {
+    return;
+  }
+
+  console.log(`[my-hook] New command triggered`);
+  // Your logic here
+
+  // Optionally send message to user
+  event.messages.push("Hook executed!");
+};
+
+export default handler;
+```
+
+Each event includes: `type`, `action`, `sessionKey`, `timestamp`, `messages` (push to send to user), and `context` (event-specific data). Agent and tool plugin hook contexts can also include `trace`, a read-only W3C-compatible diagnostic trace context that plugins may pass into structured logs for OTEL correlation.
+
+### Event context highlights
+
+**Command events** (`command:new`, `command:reset`): `context.sessionEntry`, `context.previousSessionEntry`, `context.commandSource`, `context.workspaceDir`, `context.cfg`.
+
+**Message events** (`message:received`): `context.from`, `context.content`, `context.channelId`, `context.metadata` (provider-specific data including `senderId`, `senderName`, `guildId`). `context.content` prefers a nonblank command body for command-like messages, then falls back to the raw inbound body and generic body; it does not include agent-only enrichment such as thread history or link summaries.
+
+**Message events** (`message:sent`): `context.to`, `context.content`, `context.success`, `context.channelId`.
+
+**Message events** (`message:transcribed`): `context.transcript`, `context.from`, `context.channelId`, `context.mediaPath`.
+
+**Message events** (`message:preprocessed`): `context.bodyForAgent` (final enriched body), `context.from`, `context.channelId`.
+
+**Bootstrap events** (`agent:bootstrap`): `context.bootstrapFiles` (mutable array), `context.agentId`.
+
+**Session patch events** (`session:patch`): `context.sessionEntry`, `context.patch` (only changed fields), `context.cfg`. Only privileged clients can trigger patch events.
+
+**Compaction events**: `session:compact:before` includes `messageCount`, `tokenCount`. `session:compact:after` adds `compactedCount`, `summaryLength`, `tokensBefore`, `tokensAfter`.
+
+`command:stop` observes the user issuing `/stop`; it is cancellation/command
+lifecycle, not an agent-finalization gate. Plugins that need to inspect a
+natural final answer and ask the agent for one more pass should use the typed
+plugin hook `before_agent_finalize` instead. See [Plugin hooks](/plugins/hooks).
+
+**Gateway lifecycle events**: `gateway:shutdown` includes `reason` and `restartExpectedMs` and fires when gateway shutdown begins. `gateway:pre-restart` includes the same context but only fires when shutdown is part of an expected restart and a finite `restartExpectedMs` value is supplied. During shutdown, each lifecycle hook wait is best-effort and bounded so shutdown continues if a handler stalls. The default wait budget is 5 seconds for `gateway:shutdown` and 10 seconds for `gateway:pre-restart`.
+
+Use `gateway:pre-restart` for short restart notices while channels are still available:
+
+```typescript
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export default async function handler(event) {
+  if (event.type !== "gateway" || event.action !== "pre-restart") {
+    return;
+  }
+
+  const restartInSeconds = Math.ceil(event.context.restartExpectedMs / 1000);
+  await execFileAsync("nodmix", [
+    "system",
+    "event",
+    "--mode",
+    "now",
+    "--text",
+    `Gateway restarting in ~${restartInSeconds}s (${event.context.reason}). Checkpoint now.`,
+  ]);
+}
+```
+
+Between the `gateway:shutdown` (or `gateway:pre-restart`) event and the rest of the shutdown sequence, the gateway also fires a typed `session_end` plugin hook for every session that was still active when the process stopped. The event's `reason` is `shutdown` for a plain SIGTERM/SIGINT stop and `restart` when the close was scheduled as part of an expected restart. This drain is bounded so a slow `session_end` handler cannot block process exit, and sessions that have already been finalized through replace / reset / delete / compaction are skipped to avoid double-firing.
+
+## Hook discovery
+
+Hooks are discovered from these directories, in order of increasing override precedence:
+
+1. **Bundled hooks**: shipped with Nodmix
+2. **Plugin hooks**: hooks bundled inside installed plugins
+3. **Managed hooks**: `~/.nodmix/hooks/` (user-installed, shared across workspaces). Extra directories from `hooks.internal.load.extraDirs` share this precedence.
+4. **Workspace hooks**: `<workspace>/hooks/` (per-agent, disabled by default until explicitly enabled)
+
+Workspace hooks can add new hook names but cannot override bundled, managed, or plugin-provided hooks with the same name.
+
+The Gateway skips internal hook discovery on startup until internal hooks are configured. Enable a bundled or managed hook with `nodmix hooks enable <name>`, install a hook pack, or set `hooks.internal.enabled=true` to opt in. When you enable one named hook, the Gateway loads only that hook's handler; `hooks.internal.enabled=true`, extra hook directories, and legacy handlers opt into broad discovery.
+
+### Hook packs
+
+Hook packs are npm packages that export hooks via `nodmix.hooks` in `package.json`. Install with:
+
+```bash
+nodmix plugins install <path-or-spec>
+```
+
+Npm specs are registry-only (package name + optional exact version or dist-tag). Git/URL/file specs and semver ranges are rejected.
+
+## Bundled hooks
+
+| Hook                  | Events                                            | What it does                                                   |
+| --------------------- | ------------------------------------------------- | -------------------------------------------------------------- |
+| session-memory        | `command:new`, `command:reset`                    | Saves session context to `<workspace>/memory/`                 |
+| bootstrap-extra-files | `agent:bootstrap`                                 | Injects additional bootstrap files from glob patterns          |
+| command-logger        | `command`                                         | Logs all commands to `~/.nodmix/logs/commands.log`           |
+| compaction-notifier   | `session:compact:before`, `session:compact:after` | Sends visible chat notices when session compaction starts/ends |
+| boot-md               | `gateway:startup`                                 | Runs `BOOT.md` when the gateway starts                         |
+
+Enable any bundled hook:
+
+```bash
+nodmix hooks enable <hook-name>
+```
+
+<a id="session-memory"></a>
+
+### session-memory details
+
+Extracts the last 15 user/assistant messages and saves to `<workspace>/memory/YYYY-MM-DD-HHMM.md` using the host local date. Memory capture runs in the background so `/new` and `/reset` acknowledgements are not delayed by transcript reads or optional slug generation. Set `hooks.internal.entries.session-memory.llmSlug: true` to generate descriptive filename slugs with the configured model. Requires `workspace.dir` to be configured.
+
+<a id="bootstrap-extra-files"></a>
+
+### bootstrap-extra-files config
+
+```json
+{
+  "hooks": {
+    "internal": {
+      "entries": {
+        "bootstrap-extra-files": {
+          "enabled": true,
+          "paths": ["packages/*/AGENTS.md", "packages/*/TOOLS.md"]
+        }
+      }
+    }
+  }
+}
+```
+
+Paths resolve relative to workspace. Only recognized bootstrap basenames are loaded (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, `MEMORY.md`).
+
+<a id="command-logger"></a>
+
+### command-logger details
+
+Logs every slash command to `~/.nodmix/logs/commands.log`.
+
+<a id="compaction-notifier"></a>
+
+### compaction-notifier details
+
+Sends short status messages into the current conversation when Nodmix starts and finishes compacting the session transcript. This makes long turns less confusing on chat surfaces because the user can see that the assistant is summarizing context and will continue after compaction.
+
+<a id="boot-md"></a>
+
+### boot-md details
+
+Runs `BOOT.md` from the active workspace when the gateway starts.
+
+## Plugin hooks
+
+Plugins can register typed hooks through the Plugin SDK for deeper integration:
+intercepting tool calls, modifying prompts, controlling message flow, and more.
+Use plugin hooks when you need `before_tool_call`, `before_agent_reply`,
+`before_install`, or other in-process lifecycle hooks.
+
+For the complete plugin hook reference, see [Plugin hooks](/plugins/hooks).
+
+## Configuration
+
+```json
+{
+  "hooks": {
+    "internal": {
+      "enabled": true,
+      "entries": {
+        "session-memory": { "enabled": true },
+        "command-logger": { "enabled": false }
+      }
+    }
+  }
+}
+```
+
+Per-hook environment variables:
+
+```json
+{
+  "hooks": {
+    "internal": {
+      "entries": {
+        "my-hook": {
+          "enabled": true,
+          "env": { "MY_CUSTOM_VAR": "value" }
+        }
+      }
+    }
+  }
+}
+```
+
+Extra hook directories:
+
+```json
+{
+  "hooks": {
+    "internal": {
+      "load": {
+        "extraDirs": ["/path/to/more/hooks"]
+      }
+    }
+  }
+}
+```
+
+<Note>
+The legacy `hooks.internal.handlers` array config format is still supported for backwards compatibility, but new hooks should use the discovery-based system.
+</Note>
+
+## CLI reference
+
+```bash
+# List all hooks (add --eligible, --verbose, or --json)
+nodmix hooks list
+
+# Show detailed info about a hook
+nodmix hooks info <hook-name>
+
+# Show eligibility summary
+nodmix hooks check
+
+# Enable/disable
+nodmix hooks enable <hook-name>
+nodmix hooks disable <hook-name>
+```
+
+## Best practices
+
+- **Keep handlers fast.** Hooks run during command processing. Fire-and-forget heavy work with `void processInBackground(event)`.
+- **Handle errors gracefully.** Wrap risky operations in try/catch; do not throw so other handlers can run.
+- **Filter events early.** Return immediately if the event type/action is not relevant.
+- **Use specific event keys.** Prefer `"events": ["command:new"]` over `"events": ["command"]` to reduce overhead.
+
+## Troubleshooting
+
+### Hook not discovered
+
+```bash
+# Verify directory structure
+ls -la ~/.nodmix/hooks/my-hook/
+# Should show: HOOK.md, handler.ts
+
+# List all discovered hooks
+nodmix hooks list
+```
+
+### Hook not eligible
+
+```bash
+nodmix hooks info my-hook
+```
+
+Check for missing binaries (PATH), environment variables, config values, or OS compatibility.
+
+### Hook not executing
+
+1. Verify the hook is enabled: `nodmix hooks list`
+2. Restart your gateway process so hooks reload.
+3. Check gateway logs: `./scripts/clawlog.sh | grep hook`
+
+## Related
+
+- [CLI Reference: hooks](/cli/hooks)
+- [Webhooks](/automation/cron-jobs#webhooks)
+- [Plugin hooks](/plugins/hooks) — in-process plugin lifecycle hooks
+- [Configuration](/gateway/configuration-reference#hooks)

package/docs/automation/index.md

@@ -0,0 +1,135 @@
+---
+doc-schema-version: 1
+summary: "Overview of automation mechanisms: tasks, cron, hooks, standing orders, and Task Flow"
+read_when:
+  - Deciding how to automate work with Nodmix
+  - Choosing between heartbeat, cron, commitments, hooks, and standing orders
+  - Looking for the right automation entry point
+title: "Automation"
+---
+
+Nodmix runs work in the background through tasks, scheduled jobs, inferred
+commitments, event hooks, and standing instructions. This page helps you choose
+the right mechanism and understand how they fit together.
+
+## Quick decision guide
+
+```mermaid
+flowchart TD
+    START([What do you need?]) --> Q1{Schedule work?}
+    START --> Q2{Track detached work?}
+    START --> Q3{Orchestrate multi-step flows?}
+    START --> Q4{React to lifecycle events?}
+    START --> Q5{Give the agent persistent instructions?}
+    START --> Q6{Remember a natural follow-up?}
+
+    Q1 -->|Yes| Q1a{Exact timing or flexible?}
+    Q1a -->|Exact| CRON["Scheduled Tasks (Cron)"]
+    Q1a -->|Flexible| HEARTBEAT[Heartbeat]
+
+    Q2 -->|Yes| TASKS[Background Tasks]
+    Q3 -->|Yes| FLOW[Task Flow]
+    Q4 -->|Yes| HOOKS[Hooks]
+    Q5 -->|Yes| SO[Standing Orders]
+    Q6 -->|Yes| COMMITMENTS[Inferred Commitments]
+```
+
+| Use case                                | Recommended            | Why                                              |
+| --------------------------------------- | ---------------------- | ------------------------------------------------ |
+| Send daily report at 9 AM sharp         | Scheduled Tasks (Cron) | Exact timing, isolated execution                 |
+| Remind me in 20 minutes                 | Scheduled Tasks (Cron) | One-shot with precise timing (`--at`)            |
+| Run weekly deep analysis                | Scheduled Tasks (Cron) | Standalone task, can use different model         |
+| Check inbox every 30 min                | Heartbeat              | Batches with other checks, context-aware         |
+| Monitor calendar for upcoming events    | Heartbeat              | Natural fit for periodic awareness               |
+| Check in after a mentioned interview    | Inferred Commitments   | Memory-like follow-up, no exact reminder request |
+| Gentle care check-in after user context | Inferred Commitments   | Scoped to the same agent and channel             |
+| Inspect status of a subagent or ACP run | Background Tasks       | Tasks ledger tracks all detached work            |
+| Audit what ran and when                 | Background Tasks       | `nodmix tasks list` and `nodmix tasks audit` |
+| Multi-step research then summarize      | Task Flow              | Durable orchestration with revision tracking     |
+| Run a script on session reset           | Hooks                  | Event-driven, fires on lifecycle events          |
+| Execute code on every tool call         | Plugin hooks           | In-process hooks can intercept tool calls        |
+| Always check compliance before replying | Standing Orders        | Injected into every session automatically        |
+
+### Scheduled Tasks (Cron) vs Heartbeat
+
+| Dimension       | Scheduled Tasks (Cron)              | Heartbeat                             |
+| --------------- | ----------------------------------- | ------------------------------------- |
+| Timing          | Exact (cron expressions, one-shot)  | Approximate (default every 30 min)    |
+| Session context | Fresh (isolated) or shared          | Full main-session context             |
+| Task records    | Always created                      | Never created                         |
+| Delivery        | Channel, webhook, or silent         | Inline in main session                |
+| Best for        | Reports, reminders, background jobs | Inbox checks, calendar, notifications |
+
+Use Scheduled Tasks (Cron) when you need precise timing or isolated execution. Use Heartbeat when the work benefits from full session context and approximate timing is fine.
+
+## Core concepts
+
+### Scheduled tasks (cron)
+
+Cron is the Gateway's built-in scheduler for precise timing. It persists jobs, wakes the agent at the right time, and can deliver output to a chat channel or webhook endpoint. Supports one-shot reminders, recurring expressions, and inbound webhook triggers.
+
+See [Scheduled Tasks](/automation/cron-jobs).
+
+### Tasks
+
+The background task ledger tracks all detached work: ACP runs, subagent spawns, isolated cron executions, and CLI operations. Tasks are records, not schedulers. Use `nodmix tasks list` and `nodmix tasks audit` to inspect them.
+
+See [Background Tasks](/automation/tasks).
+
+### Inferred commitments
+
+Commitments are opt-in, short-lived follow-up memories. Nodmix infers them
+from normal conversations, scopes them to the same agent and channel, and
+delivers due check-ins through heartbeat. Exact user-requested reminders still
+belong to cron.
+
+See [Inferred Commitments](/concepts/commitments).
+
+### Task Flow
+
+Task Flow is the flow orchestration substrate above background tasks. It manages durable multi-step flows with managed and mirrored sync modes, revision tracking, and `nodmix tasks flow list|show|cancel` for inspection.
+
+See [Task Flow](/automation/taskflow).
+
+### Standing orders
+
+Standing orders grant the agent permanent operating authority for defined programs. They live in workspace files (typically `AGENTS.md`) and are injected into every session. Combine with cron for time-based enforcement.
+
+See [Standing Orders](/automation/standing-orders).
+
+### Hooks
+
+Internal hooks are event-driven scripts triggered by agent lifecycle events
+(`/new`, `/reset`, `/stop`), session compaction, gateway startup, and message
+flow. They are automatically discovered from directories and can be managed
+with `nodmix hooks`. For in-process tool-call interception, use
+[Plugin hooks](/plugins/hooks).
+
+See [Hooks](/automation/hooks).
+
+### Heartbeat
+
+Heartbeat is a periodic main-session turn (default every 30 minutes). It batches multiple checks (inbox, calendar, notifications) in one agent turn with full session context. Heartbeat turns do not create task records and do not extend daily/idle session reset freshness. Use `HEARTBEAT.md` for a small checklist, or a `tasks:` block when you want due-only periodic checks inside heartbeat itself. Empty heartbeat files skip as `empty-heartbeat-file`; due-only task mode skips as `no-tasks-due`. Heartbeats defer while cron work is active or queued, and `heartbeat.skipWhenBusy` can also defer an agent while that same agent's session-keyed subagent or nested lanes are busy.
+
+See [Heartbeat](/gateway/heartbeat).
+
+## How they work together
+
+- **Cron** handles precise schedules (daily reports, weekly reviews) and one-shot reminders. All cron executions create task records.
+- **Heartbeat** handles routine monitoring (inbox, calendar, notifications) in one batched turn every 30 minutes.
+- **Hooks** react to specific events (session resets, compaction, message flow) with custom scripts. Plugin hooks cover tool calls.
+- **Standing orders** give the agent persistent context and authority boundaries.
+- **Task Flow** coordinates multi-step flows above individual tasks.
+- **Tasks** automatically track all detached work so you can inspect and audit it.
+
+## Related
+
+- [Scheduled Tasks](/automation/cron-jobs) — precise scheduling and one-shot reminders
+- [Inferred Commitments](/concepts/commitments) — memory-like follow-up check-ins
+- [Background Tasks](/automation/tasks) — task ledger for all detached work
+- [Task Flow](/automation/taskflow) — durable multi-step flow orchestration
+- [Hooks](/automation/hooks) — event-driven lifecycle scripts
+- [Plugin hooks](/plugins/hooks) — in-process tool, prompt, message, and lifecycle hooks
+- [Standing Orders](/automation/standing-orders) — persistent agent instructions
+- [Heartbeat](/gateway/heartbeat) — periodic main-session turns
+- [Configuration Reference](/gateway/configuration-reference) — all config keys

package/docs/automation/poll.md

@@ -0,0 +1,12 @@
+---
+summary: "Redirect to /cli/message"
+title: "Polls"
+---
+
+This page moved to [Message tool](/cli/message). See [Message tool](/cli/message) for poll documentation.
+
+## Related
+
+- [Webhook](/automation/webhook)
+- [Scheduled tasks](/automation/cron-jobs)
+- [Background tasks](/automation/tasks)