nemoris 0.1.0

package/config/skills/telegram-onboarding-spec.md

@@ -0,0 +1,240 @@
+# Spec: Telegram Onboarding TUI Phase
+
+## Overview
+
+Add Telegram setup as an optional sub-phase inside the Build phase (Phase 3) of the onboarding wizard. Users can connect Telegram during `nemoris init` or defer to `nemoris setup telegram` later.
+
+## Placement
+
+Inside `buildFresh()` and `buildShadow()` in `src/onboarding/phases/build.js`, after auth completes:
+
+```
+scaffold → identity → auth → telegram (optional) → done
+```
+
+Not a new top-level phase. Lock file carries `telegramConfigured: boolean` and `telegramVerified: boolean` in wizard state — no phase index change.
+
+---
+
+## Interactive Flow
+
+### Gate
+
+```
+  Connect Telegram? (Y/n)
+```
+
+- `n` → skip, `state.telegramConfigured = false`
+- `Y` → enter sub-flow
+
+### Step 1: Bot Token
+
+```
+  Telegram Bot Token (from @BotFather): ●●●●●●
+  ✓ Token validated                      @kodi_nemoris_bot
+```
+
+- Input via `promptSecret()`
+- Validate by calling Telegram `getMe` API — new function in `telegram-inbound.js`:
+  ```js
+  export async function getMe(botToken, { fetchImpl = globalThis.fetch } = {}) {
+    const res = await fetchImpl(`https://api.telegram.org/bot${botToken}/getMe`, { method: "GET" });
+    const body = await res.json();
+    if (!body.ok) return { ok: false, error: body.description || "getMe failed" };
+    return { ok: true, username: body.result.username, firstName: body.result.first_name };
+  }
+  ```
+- On failure: show error, offer re-entry or skip
+- On success: write token to `.env` as `NEMORIS_TELEGRAM_BOT_TOKEN=<value>`
+- macOS only: call `launchctl setenv NEMORIS_TELEGRAM_BOT_TOKEN <value>` so the running daemon picks it up without restart. Guard with `process.platform === "darwin"`.
+
+### Step 2: Chat ID Discovery (daemon-aware)
+
+Two paths based on whether the daemon is currently running.
+
+#### Detection
+
+Check if daemon is running:
+1. macOS: `launchctl list ai.nanoclaw.daemon` — exit code 0 means loaded
+2. Fallback: check for `state/daemon.pid` or similar runtime indicator
+
+#### Path A: Daemon is running
+
+```
+  Daemon is running. Send any message to @kodi_nemoris_bot on Telegram...
+  Waiting for your message...
+  ✓ Found you                            chat_id: 7781763328, @leeUsername
+```
+
+- Poll the SQLite state store (`state/active.db`) for the first interactive job row where `source = 'telegram'`
+- Query: `SELECT chat_id FROM interactive_jobs WHERE source = 'telegram' ORDER BY created_at DESC LIMIT 1`
+- Poll interval: 2s, timeout: 120s
+- On timeout: offer to enter chat_id manually or retry
+
+This avoids any conflict with the daemon's getUpdates polling connection. No `deleteWebhook`, no `getUpdates` — the daemon handles message ingestion, the wizard just reads the result.
+
+#### Path B: Daemon is not running
+
+```
+  Send any message to @kodi_nemoris_bot on Telegram, then press Enter...
+  ✓ Found you                            chat_id: 7781763328, @leeUsername
+```
+
+- Reuses existing `whoami(botToken)` function (deleteWebhook → getUpdates → extract chat)
+- No conflict because no daemon is competing for getUpdates
+- On failure (no messages found): prompt user to send a message first and press Enter to retry
+
+#### Both paths
+
+- Auto-fill `operator_chat_id` and `authorized_chat_ids[0]` with discovered chat_id
+- If chat_id was already in `config/runtime.toml`, show it and ask to confirm or replace
+
+### Step 3: Delivery Mode
+
+```
+  Delivery mode:
+    [1] Long polling (recommended — no tunnel needed)
+    [2] Webhook (requires public URL)
+```
+
+- Uses `select()` from tui.js
+- **Polling** (default): `polling_mode = true`, `webhook_url = ""`
+- **Webhook**: prompts for public URL, validates format, calls `registerWebhook(token, url)`. On failure: show error, offer retry or fall back to polling.
+
+### Step 4: Write Config
+
+Writes the `[telegram]` section to `config/runtime.toml`:
+
+```toml
+[telegram]
+bot_token_env = "NEMORIS_TELEGRAM_BOT_TOKEN"
+polling_mode = true
+webhook_url = ""
+operator_chat_id = "7781763328"
+authorized_chat_ids = ["7781763328"]
+default_agent = "kodi"
+```
+
+- `default_agent` is set to `state.agentId` from the Build phase
+- Preserves all other sections in runtime.toml (read → patch → write)
+- Uses TOML serialization consistent with existing config writer patterns
+
+### Step 5: Smoke Test (with failure handling)
+
+```
+  Sending test message...
+  ✓ Telegram connected                   "Hello from Nemoris"
+```
+
+Sends a test message via `sendMessage` to the discovered `chat_id` using the validated token.
+
+#### Failure path
+
+```
+  Sending test message...
+  ✗ Delivery failed: 403 Forbidden — bot was blocked by the user
+
+  [1] Retry
+  [2] Skip — finish setup without verification
+  [3] Re-enter bot token
+
+  Choice:
+```
+
+- **Retry**: loops back to sendMessage
+- **Skip**: sets `state.telegramConfigured = true`, `state.telegramVerified = false`. Verify phase will show a warning: `"⚠ Telegram configured but not verified — run nemoris setup telegram to test"`
+- **Re-enter token**: loops back to Step 1
+
+The wizard does NOT exit cleanly on a failed smoke test. It always gives the user a choice.
+
+---
+
+## Non-Interactive Mode
+
+Env-var driven, zero prompts. Suitable for Docker/CI.
+
+| Env Var | Required | Default | Purpose |
+|---------|----------|---------|---------|
+| `NEMORIS_TELEGRAM_BOT_TOKEN` | Yes (to enable) | — | If set, Telegram phase runs |
+| `NEMORIS_TELEGRAM_CHAT_ID` | No | — | Skips whoami/state-store probe |
+| `NEMORIS_TELEGRAM_MODE` | No | `polling` | `polling` or `webhook` |
+| `NEMORIS_TELEGRAM_WEBHOOK_URL` | If mode=webhook | — | Public URL for webhook registration |
+| `NEMORIS_SKIP_TELEGRAM` | No | — | Set to `true` to skip entirely |
+
+If `NEMORIS_TELEGRAM_BOT_TOKEN` is not set, Telegram phase is silently skipped. No error.
+
+If `NEMORIS_TELEGRAM_CHAT_ID` is not set and daemon is not running, the whoami probe runs automatically (no stdin needed). If it returns null, Telegram is configured without a chat_id — the user must set it manually later.
+
+---
+
+## Verify Phase Changes
+
+### Telegram configured + verified
+
+```
+  What's next:
+
+    nemoris start              start the daemon
+    nemoris status             see your agent's state
+    Message @kodi_nemoris_bot  talk to your agent via Telegram
+```
+
+### Telegram configured + NOT verified
+
+```
+  ⚠ Telegram configured but not verified
+
+  What's next:
+
+    nemoris setup telegram     verify Telegram connection
+    nemoris start              start the daemon
+```
+
+### Telegram not configured
+
+```
+  What's next:
+
+    nemoris start              start the daemon
+    nemoris status             see your agent's state
+    nemoris setup telegram     connect Telegram later
+```
+
+---
+
+## CLI Refactor
+
+Extract shared logic from `setupTelegram()` and `telegramWhoami()` in `cli.js` so both the wizard phase and the standalone commands use the same code paths:
+
+- `validateBotToken(token)` → calls `getMe`, returns `{ ok, username, error }`
+- `discoverChatId(token, { daemonRunning, stateStore, webhookUrl })` → daemon-aware chat_id discovery
+- `writeTelegramConfig(installDir, config)` → patches `[telegram]` section in runtime.toml
+- `sendTestMessage(token, chatId)` → smoke test delivery
+
+These live in `src/onboarding/phases/telegram.js` and are imported by `cli.js`.
+
+The standalone `nemoris setup telegram` command becomes a thin wrapper that calls the same phase functions with an interactive readline session, outside the wizard context.
+
+---
+
+## Files
+
+| File | Change |
+|------|--------|
+| `src/onboarding/phases/telegram.js` | **New** — Telegram sub-phase: token validation, daemon-aware chat_id discovery, mode selection, config writing, smoke test with failure handling |
+| `src/onboarding/phases/build.js` | Import and call `runTelegramPhase()` after auth in both `buildFresh()` and `buildShadow()` |
+| `src/onboarding/phases/verify.js` | Conditional "What's Next" based on `telegramConfigured` / `telegramVerified` |
+| `src/onboarding/tui.js` | Add `waitForEnter(message)` helper |
+| `src/runtime/telegram-inbound.js` | Add `getMe(botToken)` function |
+| `src/cli.js` | Refactor `setupTelegram()` / `telegramWhoami()` to use shared functions from `telegram.js` |
+
+## Scope
+
+- `telegram.js`: ~150 lines
+- `build.js` changes: ~15 lines
+- `verify.js` changes: ~15 lines
+- `telegram-inbound.js` addition: ~10 lines
+- `tui.js` addition: ~10 lines
+- `cli.js` refactor: ~30 lines changed
+
+Total: ~200 lines new, ~60 lines modified. One new file.

package/config/skills/workspace-monitor.toml

@@ -0,0 +1,15 @@
+[skill]
+id = "workspace_monitor"
+description = "Monitor workspace directory for changes and summarise"
+agent_scope = ["ops", "main"]
+
+[skill.context]
+prompt = "You are monitoring a workspace directory for changes. Compare current state against last known checkpoint. Report: new files, modified files, deleted files, key content changes. Keep summary under 200 words."
+
+[skill.tools]
+required = ["read_file", "list_dir"]
+optional = ["shell_exec"]
+
+[skill.budget]
+max_tokens = 4096
+max_tool_calls = 10

package/config/task-router.toml

@@ -0,0 +1,42 @@
+[defaults]
+enabled = true
+default_route_mode = "primary"
+
+[rules.local_reporting]
+description = "Keep bounded reporting jobs on the stronger local reporting lane."
+target_lane = "local_report"
+match_task_types = ["workspace_health", "memory_rollup"]
+priority = 90
+
+[rules.coding_work]
+description = "Escalate code-edit and repo-fix work to a stronger coding lane before model resolution."
+target_lane = "job_heavy"
+route_mode = "primary"
+match_keywords = ["code", "coding", "repo", "repository", "bug", "fix", "patch", "refactor", "test", "file fix"]
+match_task_types = ["code_fix", "repo_maintenance", "code_review", "test_repair"]
+require_tools = ["apply_patch"]
+priority = 100
+
+[rules.memory_heavy_reporting]
+description = "Use the report lane for memory-heavy summaries and handoff work."
+target_lane = "local_report"
+route_mode = "primary"
+match_keywords = ["summary", "rollup", "handoff", "memory", "backlog", "projects"]
+match_task_types = ["memory_rollup", "handoff_summary", "project_rollup"]
+priority = 80
+
+[rules.user_visible_handoff]
+description = "Promote cheap local maintenance work to the stronger report lane when it owes the user a visible handoff or pingback."
+target_lane = "local_report"
+route_mode = "primary"
+match_task_types = ["heartbeat", "heartbeat_check", "light_maintenance", "classification", "triage"]
+require_pingback = true
+priority = 70
+
+[rules.cheap_maintenance]
+description = "Keep low-risk heartbeat and maintenance loops on the cheap local lane."
+target_lane = "local_cheap"
+route_mode = "primary"
+match_keywords = ["heartbeat", "status", "maintenance", "triage", "check"]
+match_task_types = ["heartbeat", "heartbeat_check", "light_maintenance", "classification", "triage"]
+priority = 40

package/install.sh

@@ -0,0 +1,50 @@
+#!/bin/bash
+set -euo pipefail
+
+echo ""
+echo "  🌿 Nemoris Installer"
+echo ""
+
+OS="unknown"
+case "$(uname -s)" in
+  Darwin*)  OS="macOS" ;;
+  Linux*)   OS="Linux" ;;
+  MINGW*|MSYS*|CYGWIN*) OS="Windows (WSL recommended)" ;;
+esac
+echo "  Platform: $OS ($(uname -m))"
+
+check_node() {
+  if ! command -v node &>/dev/null; then
+    return 1
+  fi
+  local major
+  major=$(node -e "console.log(process.version.split('.')[0].replace('v',''))")
+  [ "$major" -ge 22 ]
+}
+
+if check_node; then
+  echo "  Node.js: $(node --version) ✓"
+else
+  echo "  Node.js >= 22.5 required."
+  if command -v nvm &>/dev/null; then
+    echo "  nvm detected — installing Node.js 22..."
+    nvm install 22
+    nvm use 22
+  else
+    echo "  Install Node.js 22+: https://nodejs.org"
+    echo "  Or install nvm: curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash"
+    exit 1
+  fi
+fi
+
+if ! command -v git &>/dev/null; then
+  echo "  ⚠ Git required: https://git-scm.com"
+  exit 1
+fi
+
+echo ""
+echo "  Installing nemoris..."
+npm install -g nemoris
+
+echo ""
+nemoris setup

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "nemoris",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Personal AI agent runtime — persistent memory, delivery guarantees, task contracts, self-healing. Local-first, no cloud.",
+  "license": "MIT",
+  "author": "Lee <amzer24@gmail.com> (https://github.com/amzer24)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amzer24/nemoris.git"
+  },
+  "homepage": "https://nemoris.dev",
+  "bugs": {
+    "url": "https://github.com/amzer24/nemoris/issues"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "runtime",
+    "personal-agent",
+    "llm",
+    "anthropic",
+    "claude",
+    "ollama",
+    "telegram",
+    "memory",
+    "self-healing",
+    "daemon",
+    "local-first",
+    "mcp"
+  ],
+  "bin": {
+    "nemoris": "bin/nemoris"
+  },
+  "files": [
+    ".env.example",
+    "bin/",
+    "src/",
+    "config/",
+    "vendor/",
+    "install.sh",
+    "LICENSE",
+    "README.md",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "init": "node src/cli.js init",
+    "demo": "node src/cli.js demo",
+    "run:heartbeat": "node src/cli.js execute-job heartbeat-check dry-run",
+    "run:heartbeat:provider": "NEMORIS_ALLOW_PROVIDER_MODE=1 node src/cli.js execute-job heartbeat-check provider",
+    "compare:heartbeat": "node src/cli.js shadow-compare heartbeat-check",
+    "scheduler:due": "node src/cli.js due-jobs",
+    "scheduler:tick": "node src/cli.js tick-scheduler dry-run",
+    "runs:review": "node src/cli.js review-runs 10",
+    "runs:evaluate": "node src/cli.js evaluate-runs 20",
+    "embeddings:index": "NEMORIS_ALLOW_EMBEDDINGS=1 node src/cli.js index-embeddings heartbeat",
+    "embeddings:query": "NEMORIS_ALLOW_EMBEDDINGS=1 node src/cli.js query-embeddings heartbeat \"heartbeat memory\"",
+    "memory:backends": "node src/cli.js memory-backends heartbeat",
+    "memory:qmd": "node src/cli.js query-qmd heartbeat \"memory heartbeat\"",
+    "memory:plan": "node src/cli.js plan-job heartbeat-check",
+    "inspect": "node src/cli.js inspect-memory main \"memory heartbeat\"",
+    "manifest:summary": "node src/cli.js manifest-summary",
+    "plan:heartbeat": "node src/cli.js plan-job heartbeat-check",
+    "cron:live": "node src/cli.js live-cron-summary",
+    "compare:jobs": "node src/cli.js compare-jobs",
+    "shadow:summary": "node src/cli.js shadow-summary main",
+    "shadow:import": "node src/cli.js shadow-import main",
+    "provider:policy": "node src/cli.js provider-mode-policy",
+    "setup": "node src/cli.js setup",
+    "battle": "NEMORIS_ALLOW_PROVIDER_MODE=1 node src/cli.js battle",
+    "lint": "eslint .",
+    "publish:check": "node scripts/check-publish-dry-run.js",
+    "status": "node src/cli.js runtime-status",
+    "test": "node --test",
+    "test:e2e": "node tests/e2e/run-report.js"
+  },
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.1.0",
+    "@mariozechner/pi-ai": "^0.60.0",
+    "js-tiktoken": "^1.0.21",
+    "smol-toml": "file:vendor/smol-toml-1.5.2.tgz"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.0.3"
+  }
+}

package/src/auth/auth-profiles.js

@@ -0,0 +1,169 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const AUTH_PROFILE_FILE_NAME = "auth-profiles.json";
+export const AUTH_PROFILE_DIR_NAME = "state";
+
+function dedupe(items = []) {
+  return [...new Set(items.filter(Boolean))];
+}
+
+export function resolveInstallDir({ env = process.env, cwd: _cwd = process.cwd() } = {}) {
+  if (env.NEMORIS_INSTALL_DIR) {
+    return env.NEMORIS_INSTALL_DIR;
+  }
+  if (_cwd) {
+    const hasPackageJson = fs.existsSync(path.join(_cwd, "package.json"));
+    const hasCliEntry = fs.existsSync(path.join(_cwd, "src", "cli.js"));
+    if (hasPackageJson && hasCliEntry) {
+      return _cwd;
+    }
+  }
+  return path.join(os.homedir(), ".nemoris");
+}
+
+export function resolveAuthProfilesPath({ env = process.env, cwd = process.cwd() } = {}) {
+  if (env.NEMORIS_AUTH_PROFILES_PATH) {
+    return path.resolve(env.NEMORIS_AUTH_PROFILES_PATH);
+  }
+  const installDir = resolveInstallDir({ env, cwd });
+  return path.join(installDir, AUTH_PROFILE_DIR_NAME, AUTH_PROFILE_FILE_NAME);
+}
+
+export function defaultAuthProfilesPath() {
+  return resolveAuthProfilesPath();
+}
+
+export function defaultAuthProfileSearchPaths({ env = process.env, cwd = process.cwd() } = {}) {
+  const installDir = resolveInstallDir({ env, cwd });
+  return dedupe([
+    resolveAuthProfilesPath({ env, cwd }),
+    path.join(cwd, AUTH_PROFILE_DIR_NAME, AUTH_PROFILE_FILE_NAME),
+    path.join(installDir, AUTH_PROFILE_DIR_NAME, AUTH_PROFILE_FILE_NAME),
+    path.join(os.homedir(), ".openclaw", "agents", "main", "agent", AUTH_PROFILE_FILE_NAME)
+  ]);
+}
+
+function readJsonFile(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function secureChmod(filePath) {
+  if (process.platform === "win32") return;
+  try {
+    fs.chmodSync(filePath, 0o600);
+  } catch {
+    // Best effort only.
+  }
+}
+
+function writeFileAtomic(filePath, content) {
+  const dirPath = path.dirname(filePath);
+  fs.mkdirSync(dirPath, { recursive: true, mode: 0o700 });
+  const tempPath = path.join(dirPath, `.${path.basename(filePath)}.${process.pid}.${Date.now()}.tmp`);
+  fs.writeFileSync(tempPath, content, { encoding: "utf8", mode: 0o600 });
+  secureChmod(tempPath);
+  fs.renameSync(tempPath, filePath);
+  secureChmod(filePath);
+}
+
+function resolveEnvRef(ref) {
+  if (!ref || typeof ref !== "object") return null;
+  if (ref.source !== "env" || !ref.id) return null;
+  return process.env[ref.id] || null;
+}
+
+export function readAuthProfiles(filePath = defaultAuthProfilesPath()) {
+  const parsed = readJsonFile(filePath);
+  const profiles = parsed?.profiles && typeof parsed.profiles === "object" ? parsed.profiles : {};
+  return {
+    version: Number(parsed?.version || 1),
+    profiles
+  };
+}
+
+export function writeAuthProfiles(document, filePath = defaultAuthProfilesPath()) {
+  writeFileAtomic(filePath, `${JSON.stringify(document, null, 2)}\n`);
+}
+
+export function updateAuthProfile(profileId, updater, filePath = defaultAuthProfilesPath()) {
+  const document = readAuthProfiles(filePath);
+  const nextProfile = updater(document.profiles?.[profileId] || null);
+  if (nextProfile === null) {
+    delete document.profiles[profileId];
+  } else {
+    document.profiles[profileId] = nextProfile;
+  }
+  writeAuthProfiles(document, filePath);
+  return document;
+}
+
+export function upsertAuthProfile(profileId, profile, filePath = defaultAuthProfilesPath()) {
+  return updateAuthProfile(profileId, () => profile, filePath);
+}
+
+export function getAuthProfile(profileId, filePath = defaultAuthProfilesPath()) {
+  return readAuthProfiles(filePath).profiles?.[profileId] || null;
+}
+
+export function resolveProfileSecret(profile) {
+  if (!profile || typeof profile !== "object") return null;
+  if (profile.type === "oauth") return profile.access || resolveEnvRef(profile.accessRef) || null;
+  if (profile.type === "api_key") return profile.key || resolveEnvRef(profile.keyRef) || null;
+  if (profile.type === "token") return profile.token || resolveEnvRef(profile.tokenRef) || null;
+  return (
+    profile.access ||
+    profile.key ||
+    profile.token ||
+    resolveEnvRef(profile.accessRef) ||
+    resolveEnvRef(profile.keyRef) ||
+    resolveEnvRef(profile.tokenRef) ||
+    null
+  );
+}
+
+export function describeAuthRef(authRef, { filePath = defaultAuthProfilesPath() } = {}) {
+  if (!authRef) {
+    return {
+      authRef: null,
+      present: false,
+      source: null,
+      detail: "missing_auth_ref"
+    };
+  }
+
+  if (String(authRef).startsWith("env:")) {
+    const envName = String(authRef).slice(4);
+    return {
+      authRef,
+      present: Boolean(process.env[envName]),
+      source: "env",
+      envName,
+      detail: process.env[envName] ? "ok" : `missing ${envName}`
+    };
+  }
+
+  if (String(authRef).startsWith("profile:")) {
+    const profileId = String(authRef).slice("profile:".length);
+    const profile = getAuthProfile(profileId, filePath);
+    return {
+      authRef,
+      present: Boolean(resolveProfileSecret(profile)),
+      source: "profile",
+      profileId,
+      detail: profile ? "ok" : `missing profile ${profileId}`
+    };
+  }
+
+  return {
+    authRef,
+    present: false,
+    source: "unknown",
+    detail: "unsupported_auth_ref"
+  };
+}