niahere 0.2.58 → 0.2.59

package/README.md

@@ -1,5 +1,9 @@
 # nia
 
+[![npm version](https://img.shields.io/npm/v/niahere.svg)](https://www.npmjs.com/package/niahere)
+[![npm downloads](https://img.shields.io/npm/dm/niahere.svg)](https://www.npmjs.com/package/niahere)
+[![license](https://img.shields.io/npm/l/niahere.svg)](https://github.com/onlyoneaman/niahere/blob/main/LICENSE)
+
 A personal AI agent you fork and make your own. Small enough to understand, built for one user. Powered by Claude Agent SDK.
 
 - npm package: [`niahere`](https://www.npmjs.com/package/niahere)
@@ -33,7 +37,7 @@ nia start               # starts daemon + registers OS service
 - **Telegram** — message your agent from your phone, typing indicator while processing
 - **Slack** — Socket Mode bot with thread awareness, thinking emoji, watch channels for proactive monitoring
 - **Terminal chat** — REPL with session resume support
-- **Scheduled jobs** — recurring jobs and crons that run Claude and can message you back
+- **Scheduled jobs** — recurring jobs and crons that run Claude and can message you back. Stateful by default (working memory), per-job model routing for cost savings
 - **Persona system** — customizable identity, soul, owner profile, rules, and memory (preloaded every session)
 - **Agents** — domain specialists (marketer, senior-dev) via Claude Agent SDK subagents
 - **Skills** — loads skills from multiple directories, invokable as slash commands
@@ -63,8 +67,8 @@ nia update                     — update to latest version (auto-backup + resta
 nia job list                   — list all jobs
 nia job show [name]            — full details + recent runs
 nia job status [name]          — quick status check
-nia job add <n> <s> <p>        — add a job (--type, --always, --agent, --stateless, --prompt-file)
-nia job update <name>          — update a job (--schedule, --prompt, --prompt-file, --type, --always, --agent, --stateless)
+nia job add <n> <s> <p>        — add a job (--type, --always, --agent, --model, --stateless, --prompt-file)
+nia job update <name>          — update a job (--schedule, --prompt, --prompt-file, --type, --always, --agent, --model, --stateless)
 nia job remove <name>          — delete a job
 nia job enable / disable <n>   — toggle a job
 nia job run <name>             — run a job once
@@ -106,6 +110,8 @@ All config and data lives in `~/.niahere/`:
     soul.md         — how the agent works
     rules.md        — behavioral instructions (loaded every session)
     memory.md       — persistent facts and context (loaded every session)
+  jobs/               — per-job working memory and state (auto-created)
+  optimizations/      — optimization loop run workspaces
   images/
     reference.webp  — visual identity reference image
     profile.webp    — profile picture for Telegram/Slack

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "niahere",
-  "version": "0.2.58",
+  "version": "0.2.59",
   "description": "A personal AI assistant daemon — chat, scheduled jobs, persona system, extensible via skills.",
   "type": "module",
   "scripts": {
@@ -43,7 +43,7 @@
   "license": "MIT",
   "private": false,
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.74",
+    "@anthropic-ai/claude-agent-sdk": "^0.2.97",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@slack/bolt": "^4.6.0",
     "cron-parser": "^5.5.0",

package/skills/beads-tasks/SKILL.md

@@ -3,9 +3,8 @@ name: beads-tasks
 description: >
   Persistent task management via Beads CLI (bd). Use when user mentions tasks, todos, issues, or tracking work.
   Check `which bd` first — if missing, offer: `npm install -g @beads/bd`.
-  Prefer setting `BEATS_DIR` (for example `~/.niahere/beads`) and run commands from there:
-  `cd "$BEATS_DIR" && bd <command>`. Always label: `--label project:<project-name>`.
-  Run `cd "$BEATS_DIR" && bd help-all` for available commands. Not for ephemeral in-conversation tracking.
+  All commands: run from `$BEATS_DIR` (for example `~/.niahere/beads`) and use `bd <command>`. Always label: `--label project:<project-name>`.
+  Run `bd help-all` for available commands. Not for ephemeral in-conversation tracking.
 ---
 
 ## Overview
@@ -19,7 +18,63 @@ Global task manager powered by [Beads](https://github.com/steveyegge/beads). Sto
 2. Ensure `~/.niahere/beads/.beads` exists — `bd init` if not.
 3. Set `BEATS_DIR` to your Beads workspace (for example `~/.niahere/beads`).
 4. All commands: `cd "$BEATS_DIR" && bd <command>`.
-5. Always label with `--label project:<project-name>`.
+5. Always label with `--label project:<name>`.
+6. Run `cd "$BEATS_DIR" && bd help-all` for available commands.
+
+## Core Commands
+
+### Creating tasks
+
+```bash
+# Basic
+bd create --title "Fix auth token refresh" --priority P2 --type bug
+
+# With parent (subtask)
+bd create --title "Extract shared logic" --priority P2 --type task --parent <parent-id>
+
+# With description — ALWAYS add context: what's broken, links, references
+bd create --title "Chat fails on long docs" --type bug --description "Fails on docs >500 pages. Ref: https://..."
+
+# Epic (container for related tasks)
+bd create --title "API performance improvements" --type epic --priority P2
+```
+
+### Updating tasks
+
+`bd update` is the workhorse — use it for reparenting, reprioritizing, retyping, renaming:
+
+```bash
+bd update <id> --parent <new-parent-id>    # Reparent / move under epic
+bd update <id> --parent ""                 # Remove parent (make top-level)
+bd update <id> --priority P1               # Change priority
+bd update <id> --type bug                  # Change type
+bd update <id> --title "Better title"      # Rename
+bd update <id> --status in_progress        # Start work
+bd update <id> --description "..."         # Add/replace description
+bd update <id> --add-label personal        # Add label
+bd update <id> --set-labels bug,urgent     # Replace all labels
+```
+
+Chain multiple updates: `bd update <id> --priority P1 --type bug --parent <parent-id>`
+
+### Viewing tasks
+
+```bash
+bd list                          # Open tasks (tree view)
+bd list --all                    # Include closed/deferred tasks
+bd list --label project:<name>   # Filter by project
+bd show <id>                     # Full details of a task
+bd children <id>                 # List children of a parent
+```
+
+### Closing tasks
+
+```bash
+bd close <id>                    # Close a task
+bd reopen <id>                   # Reopen if closed prematurely
+```
+
+**Warning:** Closing a parent does NOT close or reparent its children. If a parent epic is done but children remain open, reparent them first or they become orphaned top-level items.
 
 ## Decision Points
 
@@ -29,22 +84,45 @@ Global task manager powered by [Beads](https://github.com/steveyegge/beads). Sto
 - User says "done with X" / "finished" → `bd close <id>`
 - User wants to see cross-project work → `bd list` (no project filter)
 - User wants project-specific view → `bd list --label project:<name>`
-- User asks for task in-progress state → use task status:
-  - `bd update <task-id> --status in_progress`
-- `bd set-state ... state=...` is for operational metadata only and does not
-  change list-visible task status.
 - bd not installed → offer install, don't silently fail
 - Ephemeral/conversation-only tracking → use conversation context, not beads
+- `bd set-state ... state=...` is for operational metadata only; it does not change the task status shown in list.
+
+## Hierarchy & Organization
+
+### When to use parent-child vs labels
+
+- **Parent-child** (`--parent`): for structural grouping — epics containing subtasks, features broken into steps.
+- **Labels** (`--add-label`): for cross-cutting tags — `personal`, `urgent`, `project:<name>`. A task can have multiple labels but only one parent.
+
+### Epic patterns
+
+- Use `--type epic` for containers that group related work.
+- Epics can nest: epic > sub-epic > tasks.
+- Keep epic titles broad ("API improvements"), subtask titles specific ("Reduce /search latency from 2s to 200ms").
+
+### Cleanup & auditing
+
+Periodically review with `bd list` and look for:
+- **Orphaned tasks** — top-level items that should be under an epic.
+- **Similar ungrouped tasks** — multiple tasks on the same topic that should share a parent.
+- **Misplaced tasks** — bugs under improvement epics or vice versa.
+- **Stale tasks** — open tasks that are actually done or no longer relevant.
+
+When reorganizing, reparent with `bd update <id> --parent <new-parent>` — don't delete and recreate.
 
 ## Conventions
 
-- Titles: descriptive, actionable (e.g. "Fix auth token refresh in niahere")
-- Labels: `project:<name>`, `bug`, `feature`, `chore`, `urgent`
-- Priority: default P2 unless user specifies urgency
-- Status flow: `open` → `in_progress` → `closed`
+- **Titles:** descriptive, actionable (e.g. "Fix auth token refresh in niahere")
+- **Descriptions:** always include context — what's broken, why it matters, links to references (Canny, threads, logs). Future you needs enough to start working without asking questions.
+- **Types:** `epic`, `bug`, `feature`, `task`, `chore`, `decision`
+- **Priority:** P0 (critical) → P4 (nice-to-have). Default P2 unless user specifies.
+- **Labels:** `project:<name>`, `personal`, `bug`, `feature`, `chore`, `urgent`
+- **Status flow:** `open` → `in_progress` → `closed`
 
 ## Validation
 
-- `cd "$BEATS_DIR" && bd list` returns results after creating a task
+- `bd list` returns results after creating a task
 - Labels appear correctly in list output
+- Parent-child relationships show as indented tree in `bd list`
 - Dependencies show in `bd dep tree`

package/src/chat/engine.ts

@@ -382,6 +382,7 @@ export async function createChatEngine(
                 duration_ms: msg.duration_ms,
                 duration_api_ms: msg.duration_api_ms,
                 stop_reason: msg.stop_reason,
+                terminal_reason: msg.terminal_reason,
                 session_id: msg.session_id,
                 subtype: msg.subtype,
                 usage: msg.usage,

package/src/cli/index.ts

@@ -1,6 +1,12 @@
 #!/usr/bin/env bun
 import { existsSync, mkdirSync } from "fs";
-import { isRunning, readPid, runDaemon, startDaemon, stopDaemon } from "../core/daemon";
+import {
+  isRunning,
+  readPid,
+  runDaemon,
+  startDaemon,
+  stopDaemon,
+} from "../core/daemon";
 import { getConfig } from "../utils/config";
 import { localTime } from "../utils/time";
 import { startRepl } from "../chat/repl";
@@ -29,7 +35,12 @@ try {
 const command = process.argv[2];
 
 // Ensure ~/.niahere/ exists for commands that need it
-if (command && !["init", "help", "version", "-v", "--version", "-h", "--help"].includes(command)) {
+if (
+  command &&
+  !["init", "help", "version", "-v", "--version", "-h", "--help"].includes(
+    command,
+  )
+) {
   mkdirSync(getNiaHome(), { recursive: true });
 }
 
@@ -45,7 +56,8 @@ async function awaitStartup(timeout = 60_000): Promise<void> {
   const expecting = new Set<string>();
   if (config.channels.enabled) {
     if (config.channels.telegram.bot_token) expecting.add("telegram");
-    if (config.channels.slack.bot_token && config.channels.slack.app_token) expecting.add("slack");
+    if (config.channels.slack.bot_token && config.channels.slack.app_token)
+      expecting.add("slack");
   }
   expecting.add("scheduler");
 
@@ -54,13 +66,19 @@ async function awaitStartup(timeout = 60_000): Promise<void> {
   const { readFileSync } = await import("fs");
   const ready = new Set<string>();
   let logOffset = 0;
-  try { logOffset = readFileSync(daemonLog, "utf8").length; } catch {}
+  try {
+    logOffset = readFileSync(daemonLog, "utf8").length;
+  } catch {}
 
   const startTime = Date.now();
   while (ready.size < expecting.size && Date.now() - startTime < timeout) {
     await new Promise((r) => setTimeout(r, 500));
     let content = "";
-    try { content = readFileSync(daemonLog, "utf8").slice(logOffset); } catch { continue; }
+    try {
+      content = readFileSync(daemonLog, "utf8").slice(logOffset);
+    } catch {
+      continue;
+    }
 
     for (const name of expecting) {
       if (ready.has(name)) continue;
@@ -125,7 +143,8 @@ switch (command) {
   }
 
   case "restart": {
-    const { isServiceInstalled, restartService } = await import("../commands/service");
+    const { isServiceInstalled, restartService } =
+      await import("../commands/service");
     if (isServiceInstalled()) {
       // Service-aware: unload (stops KeepAlive respawn), kill, then reload
       await restartService();
@@ -134,7 +153,9 @@ switch (command) {
       startDaemon();
     }
     const restartPid = readPid();
-    console.log(`nia restarting${restartPid ? ` (pid: ${restartPid})` : ""}...`);
+    console.log(
+      `nia restarting${restartPid ? ` (pid: ${restartPid})` : ""}...`,
+    );
     await awaitStartup();
     console.log("nia restarted");
     break;
@@ -145,7 +166,12 @@ switch (command) {
     if (prompt) {
       const { createChatEngine } = await import("../chat/engine");
       const { getMcpServers } = await import("../mcp");
-      const { DIM, RESET: RST, CLEAR_LINE, SPINNER: FRAMES } = await import("../utils/cli");
+      const {
+        DIM,
+        RESET: RST,
+        CLEAR_LINE,
+        SPINNER: FRAMES,
+      } = await import("../utils/cli");
       let frame = 0;
       let statusText = "thinking";
       let spinTimer: ReturnType<typeof setInterval> | null = null;
@@ -153,31 +179,47 @@ switch (command) {
       let streaming = false;
 
       const renderSpinner = () => {
-        process.stderr.write(`${CLEAR_LINE}${DIM}  ${FRAMES[frame]} ${statusText}${RST}`);
+        process.stderr.write(
+          `${CLEAR_LINE}${DIM}  ${FRAMES[frame]} ${statusText}${RST}`,
+        );
         frame = (frame + 1) % FRAMES.length;
       };
 
       await withDb(async () => {
-        const engine = await createChatEngine({ room: "cli-run", channel: "terminal", resume: false, mcpServers: getMcpServers() });
+        const engine = await createChatEngine({
+          room: "cli-run",
+          channel: "terminal",
+          resume: false,
+          mcpServers: getMcpServers(),
+        });
         spinTimer = setInterval(renderSpinner, 80);
         renderSpinner();
 
         const { result, costUsd, turns } = await engine.send(prompt, {
           onStream(textSoFar) {
             if (!streaming) {
-              if (spinTimer) { clearInterval(spinTimer); spinTimer = null; }
+              if (spinTimer) {
+                clearInterval(spinTimer);
+                spinTimer = null;
+              }
               process.stderr.write("\x1b[2K\r");
               streaming = true;
             }
             const chunk = textSoFar.slice(streamedLen);
-            if (chunk) { process.stdout.write(chunk); streamedLen = textSoFar.length; }
+            if (chunk) {
+              process.stdout.write(chunk);
+              streamedLen = textSoFar.length;
+            }
           },
           onActivity(text) {
             if (!streaming) statusText = text;
           },
         });
 
-        if (spinTimer) { clearInterval(spinTimer); spinTimer = null; }
+        if (spinTimer) {
+          clearInterval(spinTimer);
+          spinTimer = null;
+        }
 
         if (!streaming && result.trim()) {
           process.stderr.write("\x1b[2K\r");
@@ -190,13 +232,15 @@ switch (command) {
         }
 
         const costStr = costUsd > 0 ? `$${costUsd.toFixed(4)}` : "";
-        const turnsStr = turns > 0 ? `${turns} turn${turns !== 1 ? "s" : ""}` : "";
+        const turnsStr =
+          turns > 0 ? `${turns} turn${turns !== 1 ? "s" : ""}` : "";
         const meta = [costStr, turnsStr].filter(Boolean).join(" · ");
         if (meta) process.stderr.write(`\n${DIM}${meta}${RST}`);
         process.stdout.write("\n");
 
         engine.close();
       });
+      process.exit(0);
     } else {
       await runDaemon();
     }
@@ -235,8 +279,13 @@ switch (command) {
             const time = localTime(new Date(m.createdAt));
             const prefix = m.sender === "user" ? "you" : m.sender;
             const roomTag = room ? "" : `[${m.room}] `;
-            const snippet = m.content.length > 120 ? m.content.slice(0, 120) + "..." : m.content;
-            console.log(`  ${roomTag}${time}  ${prefix} > ${snippet.replace(/\n/g, " ")}`);
+            const snippet =
+              m.content.length > 120
+                ? m.content.slice(0, 120) + "..."
+                : m.content;
+            console.log(
+              `  ${roomTag}${time}  ${prefix} > ${snippet.replace(/\n/g, " ")}`,
+            );
           }
         }
       });
@@ -253,16 +302,25 @@ switch (command) {
     const follow = logArgs.includes("-f") || logArgs.includes("--follow");
     // --channel <name> filters logs by channel/component via grep
     const chIdx = logArgs.indexOf("--channel");
-    const channelFilter = chIdx !== -1 && logArgs[chIdx + 1] ? logArgs[chIdx + 1] : null;
+    const channelFilter =
+      chIdx !== -1 && logArgs[chIdx + 1] ? logArgs[chIdx + 1] : null;
 
     if (channelFilter) {
       // Pipe through grep to filter by channel name in structured logs
-      const tailArgs = follow ? ["tail", "-f", daemonLog] : ["tail", "-200", daemonLog];
-      const tail = Bun.spawn(tailArgs, { stdio: ["ignore", "pipe", "inherit"] });
-      const grep = Bun.spawn(["grep", "-i", channelFilter], { stdio: [tail.stdout, "inherit", "inherit"] });
+      const tailArgs = follow
+        ? ["tail", "-f", daemonLog]
+        : ["tail", "-200", daemonLog];
+      const tail = Bun.spawn(tailArgs, {
+        stdio: ["ignore", "pipe", "inherit"],
+      });
+      const grep = Bun.spawn(["grep", "-i", channelFilter], {
+        stdio: [tail.stdout, "inherit", "inherit"],
+      });
       await grep.exited;
     } else {
-      const args = follow ? ["tail", "-f", daemonLog] : ["tail", "-50", daemonLog];
+      const args = follow
+        ? ["tail", "-f", daemonLog]
+        : ["tail", "-50", daemonLog];
       const proc = Bun.spawn(args, { stdio: ["ignore", "inherit", "inherit"] });
       await proc.exited;
     }
@@ -276,13 +334,15 @@ switch (command) {
 
   case "chat": {
     const chatArgs = process.argv.slice(3);
-    const mode = (chatArgs.includes("--continue") || chatArgs.includes("-c"))
-      ? "continue" as const
-      : (chatArgs.includes("--resume") || chatArgs.includes("-r"))
-        ? "pick" as const
-        : "new" as const;
+    const mode =
+      chatArgs.includes("--continue") || chatArgs.includes("-c")
+        ? ("continue" as const)
+        : chatArgs.includes("--resume") || chatArgs.includes("-r")
+          ? ("pick" as const)
+          : ("new" as const);
     const chIdx = chatArgs.indexOf("--channel");
-    const simChannel = chIdx !== -1 && chatArgs[chIdx + 1] ? chatArgs[chIdx + 1] : undefined;
+    const simChannel =
+      chIdx !== -1 && chatArgs[chIdx + 1] ? chatArgs[chIdx + 1] : undefined;
     await startRepl(mode, simChannel);
     break;
   }
@@ -300,7 +360,9 @@ switch (command) {
       skills = skills.filter((s) => s.source === filter);
     }
     if (skills.length === 0) {
-      console.log(filter ? `No skills found in "${filter}".` : "No skills found.");
+      console.log(
+        filter ? `No skills found in "${filter}".` : "No skills found.",
+      );
     } else {
       for (const s of skills) {
         const tag = filter ? "" : `  [${s.source}]`;
@@ -354,8 +416,12 @@ switch (command) {
       const parts = configKey.split(".");
       let val: unknown = raw;
       for (const p of parts) {
-        if (val && typeof val === "object") val = (val as Record<string, unknown>)[p];
-        else { val = undefined; break; }
+        if (val && typeof val === "object")
+          val = (val as Record<string, unknown>)[p];
+        else {
+          val = undefined;
+          break;
+        }
       }
       if (val === undefined) {
         console.log(`${configKey}: (not set)`);
@@ -389,7 +455,9 @@ switch (command) {
         process.kill(pid, "SIGHUP");
         console.log(`channels ${enabled ? "enabled" : "disabled"}`);
       } else {
-        console.log(`channels ${enabled ? "enabled" : "disabled"} — start nia to apply`);
+        console.log(
+          `channels ${enabled ? "enabled" : "disabled"} — start nia to apply`,
+        );
       }
     } else {
       console.log(`channels: ${getConfig().channels.enabled ? "on" : "off"}`);
@@ -404,8 +472,11 @@ switch (command) {
   }
 
   case "test": {
-    const verbose = process.argv.includes("-v") || process.argv.includes("--verbose");
-    const extraArgs = process.argv.slice(3).filter((a) => a !== "-v" && a !== "--verbose");
+    const verbose =
+      process.argv.includes("-v") || process.argv.includes("--verbose");
+    const extraArgs = process.argv
+      .slice(3)
+      .filter((a) => a !== "-v" && a !== "--verbose");
     const proc = Bun.spawn(["bun", "test", ...extraArgs], {
       stdio: ["ignore", "pipe", "pipe"],
       cwd: import.meta.dir + "/../..",
@@ -423,7 +494,12 @@ switch (command) {
       process.stdout.write(output);
     } else {
       for (const line of output.split("\n")) {
-        if (/^\s*\d+ pass/.test(line) || /^\s*\d+ fail/.test(line) || /^Ran \d+ tests/.test(line) || /expect\(\) calls/.test(line)) {
+        if (
+          /^\s*\d+ pass/.test(line) ||
+          /^\s*\d+ fail/.test(line) ||
+          /^Ran \d+ tests/.test(line) ||
+          /expect\(\) calls/.test(line)
+        ) {
           console.log(line);
         } else if (/^✗|FAIL|error:/i.test(line.trim())) {
           console.log(line);
@@ -460,13 +536,18 @@ switch (command) {
       console.log(`⚠ backup skipped: ${errMsg(err)}`);
     }
     console.log("Updating...");
-    const install = Bun.spawn(["npm", "i", "-g", "niahere@latest"], { stdio: ["ignore", "inherit", "inherit"] });
+    const install = Bun.spawn(["npm", "i", "-g", "niahere@latest"], {
+      stdio: ["ignore", "inherit", "inherit"],
+    });
     const installExit = await install.exited;
     if (installExit !== 0) {
       fail("Update failed.");
     }
     // Get new version
-    const check = Bun.spawn(["npm", "view", "niahere", "version"], { stdout: "pipe", stderr: "pipe" });
+    const check = Bun.spawn(["npm", "view", "niahere", "version"], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
     const newVersion = (await new Response(check.stdout).text()).trim();
     await check.exited;
     if (newVersion === currentVersion) {
@@ -475,7 +556,8 @@ switch (command) {
       console.log(`Updated: v${currentVersion} → v${newVersion}`);
       if (isRunning()) {
         console.log("Restarting daemon...");
-        const { isServiceInstalled, restartService } = await import("../commands/service");
+        const { isServiceInstalled, restartService } =
+          await import("../commands/service");
         if (isServiceInstalled()) {
           await restartService();
         } else {
@@ -540,7 +622,11 @@ System:
 
     console.log(HELP);
     // Unknown command → exit 1, help/no command → exit 0
-    const isHelp = !command || command === "help" || command === "--help" || command === "-h";
+    const isHelp =
+      !command ||
+      command === "help" ||
+      command === "--help" ||
+      command === "-h";
     if (!isHelp) console.error(`\nUnknown command: ${command}`);
     process.exit(isHelp ? 0 : 1);
   }