@intent-systems/nexus 2026.1.5-4 → 2026.1.5-8

package/dist/commands/cursor-hooks.js

@@ -0,0 +1,240 @@
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { resolveUserPath } from "../utils.js";
+const DEFAULT_SCRIPT_NAME = "nexus-session-start.js";
+const HOOK_SCRIPT = `#!/usr/bin/env node
+const { execFile } = require("child_process");
+const fs = require("fs");
+const fsp = require("fs/promises");
+const os = require("os");
+const path = require("path");
+
+const MAX_IDENTITY_CHARS = 120000;
+const MAX_MEMORY_CHARS = 120000;
+const MAX_DAILY_CHARS = 40000;
+const MAX_BOOTSTRAP_CHARS = 80000;
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on("end", () => resolve(data));
+  });
+}
+
+function safeJsonParse(raw) {
+  if (!raw || !raw.trim()) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function formatDate(date) {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  return \`\${year}-\${month}-\${day}\`;
+}
+
+function resolveWorkspaceRoot(payload) {
+  const roots = payload?.workspace_roots;
+  if (Array.isArray(roots) && roots.length > 0 && roots[0]) {
+    return roots[0];
+  }
+  if (process.env.NEXUS_ROOT?.trim()) return process.env.NEXUS_ROOT.trim();
+  const home = os.homedir();
+  if (home) return path.join(home, "nexus");
+  return process.cwd();
+}
+
+function resolveStateDir(workspaceRoot) {
+  if (process.env.NEXUS_STATE_DIR?.trim()) {
+    return process.env.NEXUS_STATE_DIR.trim();
+  }
+  return path.join(workspaceRoot, "state");
+}
+
+function execFileAsync(command, args, options) {
+  return new Promise((resolve) => {
+    execFile(command, args, options, (error, stdout, stderr) => {
+      resolve({ error, stdout, stderr });
+    });
+  });
+}
+
+async function runStatus(env, cwd) {
+  const result = await execFileAsync("nexus", ["status", "--json"], {
+    env,
+    cwd,
+  });
+  const parsed = safeJsonParse(result.stdout);
+  if (parsed) return parsed;
+  if (result.error && result.error.stdout) {
+    const fallback = safeJsonParse(result.error.stdout.toString());
+    if (fallback) return fallback;
+  }
+  return null;
+}
+
+async function readFileSnippet(filePath, limit) {
+  if (!filePath) return null;
+  try {
+    const content = await fsp.readFile(filePath, "utf8");
+    if (!content.trim()) return null;
+    if (content.length <= limit) return content.trim();
+    const slice = content.slice(-limit).trimStart();
+    return \`\${slice}\\n\\n[truncated]\`;
+  } catch {
+    return null;
+  }
+}
+
+function addSection(sections, title, body) {
+  if (!body) return;
+  sections.push(\`## \${title}\\n\${body}\`);
+}
+
+async function main() {
+  const input = await readStdin();
+  const payload = safeJsonParse(input) || {};
+  const workspaceRoot = resolveWorkspaceRoot(payload);
+  const stateDir = resolveStateDir(workspaceRoot);
+  const env = {
+    ...process.env,
+    NEXUS_ROOT: workspaceRoot,
+    NEXUS_STATE_DIR: stateDir,
+  };
+  const status = await runStatus(env, workspaceRoot);
+  const identity = status?.identity || null;
+  const agentId = identity?.agentId || process.env.NEXUS_AGENT_ID || "default";
+  const agentIdentityPath =
+    identity?.agentIdentityPath ||
+    path.join(stateDir, "agents", agentId, "IDENTITY.md");
+  const agentSoulPath =
+    identity?.agentSoulPath || path.join(stateDir, "agents", agentId, "SOUL.md");
+  const agentMemoryPath =
+    identity?.agentMemoryPath ||
+    path.join(stateDir, "agents", agentId, "MEMORY.md");
+  const userIdentityPath =
+    identity?.userIdentityPath || path.join(stateDir, "user", "IDENTITY.md");
+  const userProfilePath = path.join(stateDir, "user", "PROFILE.md");
+  const resolvedUserPath = fs.existsSync(userIdentityPath)
+    ? userIdentityPath
+    : fs.existsSync(userProfilePath)
+      ? userProfilePath
+      : userIdentityPath;
+
+  const sections = ["# Nexus Session Bootstrap"];
+  if (identity) {
+    const summary = [
+      \`Agent: \${identity.agentName || "(unknown)"} (\${identity.agentId})\`,
+      \`User: \${identity.userName || "(unknown)"}\`,
+      \`Agent ID: \${identity.agentId}\`,
+    ];
+    addSection(sections, "Status", summary.join("\\n"));
+  }
+
+  const bootstrapPath =
+    status?.identity?.bootstrapPath ||
+    path.join(stateDir, "agents", "BOOTSTRAP.md");
+  const hasIdentity =
+    typeof identity?.hasIdentity === "boolean"
+      ? identity.hasIdentity
+      : fs.existsSync(agentIdentityPath) && fs.existsSync(resolvedUserPath);
+  let bootstrapPrompt = status?.bootstrap?.prompt || null;
+  if (!bootstrapPrompt && !hasIdentity) {
+    bootstrapPrompt = await readFileSnippet(
+      bootstrapPath,
+      MAX_BOOTSTRAP_CHARS,
+    );
+  }
+  if (bootstrapPrompt) {
+    addSection(sections, "Bootstrap Prompt", bootstrapPrompt.trim());
+  }
+
+  const agentIdentity = await readFileSnippet(
+    agentIdentityPath,
+    MAX_IDENTITY_CHARS,
+  );
+  const agentSoul = await readFileSnippet(agentSoulPath, MAX_IDENTITY_CHARS);
+  const agentMemory = await readFileSnippet(agentMemoryPath, MAX_MEMORY_CHARS);
+  const userIdentity = await readFileSnippet(
+    resolvedUserPath,
+    MAX_IDENTITY_CHARS,
+  );
+
+  addSection(sections, "Agent Identity", agentIdentity);
+  addSection(sections, "Agent Soul", agentSoul);
+  addSection(sections, "Agent Memory", agentMemory);
+  addSection(sections, "User Identity", userIdentity);
+
+  const memoryDir = path.join(workspaceRoot, "home", "memory");
+  const today = formatDate(new Date());
+  const yesterday = formatDate(new Date(Date.now() - 86400000));
+  const todayLog = await readFileSnippet(
+    path.join(memoryDir, \`\${today}.md\`),
+    MAX_DAILY_CHARS,
+  );
+  const yesterdayLog = await readFileSnippet(
+    path.join(memoryDir, \`\${yesterday}.md\`),
+    MAX_DAILY_CHARS,
+  );
+
+  addSection(sections, \`Daily Memory (\${today})\`, todayLog);
+  addSection(sections, \`Daily Memory (\${yesterday})\`, yesterdayLog);
+
+  const additional = sections.join("\\n\\n").trim();
+  const output = { continue: true, additional_context: additional };
+  const envOut = {};
+  if (!process.env.NEXUS_ROOT?.trim() && workspaceRoot) {
+    envOut.NEXUS_ROOT = workspaceRoot;
+  }
+  if (!process.env.NEXUS_STATE_DIR?.trim() && stateDir) {
+    envOut.NEXUS_STATE_DIR = stateDir;
+  }
+  if (Object.keys(envOut).length > 0) {
+    output.env = envOut;
+  }
+  process.stdout.write(JSON.stringify(output) + "\\n");
+}
+
+main().catch(() => {
+  process.stdout.write(JSON.stringify({ continue: true }) + "\\n");
+});
+`;
+async function writeFileIfMissing(filePath, content) {
+    try {
+        await fsp.writeFile(filePath, content, { encoding: "utf-8", flag: "wx" });
+        return true;
+    }
+    catch (err) {
+        const anyErr = err;
+        if (anyErr.code === "EEXIST")
+            return false;
+        throw err;
+    }
+}
+export async function writeCursorHooks(options = {}) {
+    const workspaceDir = resolveUserPath(options.workspaceDir ?? process.cwd());
+    const hooksPath = options.hooksPath ?? path.join(workspaceDir, ".cursor", "hooks.json");
+    const scriptPath = options.scriptPath ??
+        path.join(workspaceDir, ".cursor", "hooks", DEFAULT_SCRIPT_NAME);
+    await fsp.mkdir(path.dirname(hooksPath), { recursive: true });
+    await fsp.mkdir(path.dirname(scriptPath), { recursive: true });
+    const hooksConfig = JSON.stringify({
+        version: 1,
+        hooks: {
+            sessionStart: [
+                { command: `node .cursor/hooks/${DEFAULT_SCRIPT_NAME}` },
+            ],
+        },
+    }, null, 2);
+    const hooksCreated = await writeFileIfMissing(hooksPath, `${hooksConfig}\n`);
+    const scriptCreated = await writeFileIfMissing(scriptPath, HOOK_SCRIPT);
+    return { hooksPath, scriptPath, hooksCreated, scriptCreated };
+}

package/dist/commands/cursor-rules.js

@@ -1,10 +1,7 @@
-import fs from "node:fs";
 import fsp from "node:fs/promises";
 import path from "node:path";
-import { flattenManifest, generateSkillManifest, readSkillManifest, } from "./skills-manifest.js";
-import { resolveStateDir } from "../config/paths.js";
-import { MANAGED_SKILLS_DIR, NEXUS_ROOT, resolveUserPath } from "../utils.js";
 import { defaultRuntime } from "../runtime.js";
+import { NEXUS_ROOT, SKILLS_STATE_DIR, WORKSPACE_SKILLS_DIR, resolveUserPath, } from "../utils.js";
 /**
  * Generate and write `.cursor/rules` for a given workspace.
  *
@@ -12,8 +9,7 @@ import { defaultRuntime } from "../runtime.js";
  *   nexus cursor-rules [--workspace <path>]
  */
 export async function cursorRulesCommand(opts, runtime = defaultRuntime) {
-    const workspaceDir = opts?.workspace?.trim() ||
-        path.join(process.env.HOME || "~", "nexus", "home");
+    const workspaceDir = opts?.workspace?.trim() || NEXUS_ROOT;
     const resolvedWorkspace = resolveUserPath(workspaceDir);
     runtime.log(`Generating .cursor/rules for workspace: ${resolvedWorkspace}`);
     const outputPath = await writeCursorRules({
@@ -24,196 +20,26 @@ export async function cursorRulesCommand(opts, runtime = defaultRuntime) {
     });
     runtime.log(`✓ Wrote ${outputPath}`);
 }
-/**
- * Group skills by category based on their description/name
- */
-function categorizeSkills(skills) {
-    const categories = {
-        "Communication & Messaging": [],
-        "Productivity & Notes": [],
-        "Google & Cloud Services": [],
-        "Media & Content": [],
-        "Smart Home & Devices": [],
-        "Development & Tools": [],
-        "Other": [],
-    };
-    const categoryPatterns = [
-        ["Communication & Messaging", [/imsg|imessage|whatsapp|discord|slack|telegram|sms|message|chat/i]],
-        ["Productivity & Notes", [/note|reminder|bear|obsidian|notion|things|trello|task|todo/i]],
-        ["Google & Cloud Services", [/google|gmail|calendar|drive|sheets|docs|gemini|gog|places/i]],
-        ["Media & Content", [/image|video|audio|camera|gif|pdf|whisper|speech|photo|screenshot/i]],
-        ["Smart Home & Devices", [/hue|sonos|spotify|eight|sleep|smart|home|light|speaker/i]],
-        ["Development & Tools", [/github|git|code|coding|terminal|bash|cli|api|mcp|1password|search/i]],
-    ];
-    for (const skill of skills) {
-        const text = `${skill.name} ${skill.description || ""}`;
-        let matched = false;
-        for (const [category, patterns] of categoryPatterns) {
-            if (patterns.some(p => p.test(text))) {
-                categories[category].push(skill);
-                matched = true;
-                break;
-            }
-        }
-        if (!matched) {
-            categories["Other"].push(skill);
-        }
-    }
-    return categories;
-}
-/**
- * Format skill entries for the rules file
- */
-function formatSkillsSection(skills) {
-    const categories = categorizeSkills(skills);
-    const lines = [];
-    for (const [category, categorySkills] of Object.entries(categories)) {
-        if (categorySkills.length === 0)
-            continue;
-        lines.push(`### ${category}`);
-        for (const skill of categorySkills.sort((a, b) => a.name.localeCompare(b.name))) {
-            const desc = skill.description
-                ? skill.description.slice(0, 80) + (skill.description.length > 80 ? "..." : "")
-                : "(no description)";
-            lines.push(`- **${skill.name}**: ${desc}`);
-        }
-        lines.push("");
-    }
-    return lines.join("\n");
-}
-/**
- * Load AGENTS.md from the Nexus root
- */
-async function loadAgentsMd(workspaceDir) {
-    const candidates = [
-        path.join(NEXUS_ROOT, "AGENTS.md"),
-        path.join(workspaceDir, "AGENTS.md"),
-        path.join(workspaceDir, ".intent", "AGENTS.md"),
-    ];
-    for (const candidate of candidates) {
-        try {
-            if (fs.existsSync(candidate)) {
-                return await fsp.readFile(candidate, "utf-8");
-            }
-        }
-        catch {
-            // continue
-        }
-    }
-    return undefined;
-}
-/**
- * Load bootstrap files (IDENTITY.md, PROFILE.md, SOUL.md) if they exist
- */
-async function loadBootstrapFiles(workspaceDir) {
-    const files = {};
-    const agentId = process.env.NEXUS_AGENT_ID?.trim() || "default";
-    const stateDir = resolveStateDir();
-    const agentIdentityDir = path.join(stateDir, "agents", agentId, "identity");
-    const userIdentityDir = path.join(stateDir, "user", "identity");
-    const bootstrapFiles = ["IDENTITY.md", "PROFILE.md", "SOUL.md"];
-    for (const filename of bootstrapFiles) {
-        const candidates = filename === "PROFILE.md"
-            ? [path.join(userIdentityDir, filename)]
-            : [path.join(agentIdentityDir, filename)];
-        for (const candidate of candidates) {
-            try {
-                if (fs.existsSync(candidate)) {
-                    files[filename] = await fsp.readFile(candidate, "utf-8");
-                    break;
-                }
-            }
-            catch {
-                // continue
-            }
-        }
-    }
-    return files;
-}
 /**
  * Generate .cursor/rules content from Nexus skills and config
  */
 export async function generateCursorRules(options = {}) {
-    const workspaceDir = options.workspaceDir || process.cwd();
-    const skillsDir = options.skillsDir || MANAGED_SKILLS_DIR;
-    const userSkillsDir = options.userSkillsDir || path.join(NEXUS_ROOT, "home", "skills");
-    // Try to read existing manifest, or generate one
-    let manifest = await readSkillManifest();
-    if (!manifest) {
-        manifest = await generateSkillManifest(skillsDir, userSkillsDir);
-    }
-    const skills = flattenManifest(manifest);
-    const skillsSection = formatSkillsSection(skills);
-    // Load AGENTS.md if requested
-    let agentsMdSection = "";
-    if (options.includeAgentsMd !== false) {
-        const agentsMd = await loadAgentsMd(workspaceDir);
-        if (agentsMd) {
-            agentsMdSection = `
-## Project Guidelines (from AGENTS.md)
-
-${agentsMd}
-`;
-        }
-    }
-    // Load bootstrap files if requested
-    let bootstrapSection = "";
-    if (options.includeBootstrap) {
-        const bootstrapFiles = await loadBootstrapFiles(workspaceDir);
-        if (Object.keys(bootstrapFiles).length > 0) {
-            const parts = [];
-            for (const [filename, content] of Object.entries(bootstrapFiles)) {
-                parts.push(`### ${filename}\n\n${content}`);
-            }
-            bootstrapSection = `
-## User Context
-
-${parts.join("\n\n")}
-`;
-        }
-    }
-    const rules = `# Nexus Workspace Rules
-
-This file is auto-generated by \`nexus cursor-rules\`. Regenerate with:
-\`\`\`bash
-nexus cursor-rules --output .cursor/rules
-\`\`\`
-
-## Available Skills (${skills.length} total)
-
-The following skills are available in \`~/nexus/skills/\`. Read the full \`SKILL.md\` when you need detailed usage instructions.
-
-${skillsSection}
-## How to Use Skills
-
-1. **When a user's request relates to a skill**, read the corresponding SKILL.md:
-   \`\`\`bash
-   cat ~/nexus/skills/<skill>/SKILL.md
-   \`\`\`
-
-2. **Skills provide CLI tools** - use bash to run them:
-   \`\`\`bash
-   eve db query --sql "SELECT * FROM messages LIMIT 5"
-   imsg chats --limit 10 --json
-   gog gmail search "is:unread" --max 5
-   \`\`\`
-
-3. **Most tools support \`--json\`** for structured output.
+    const skillsDir = options.skillsDir || WORKSPACE_SKILLS_DIR;
+    const agentsPath = path.join(NEXUS_ROOT, "AGENTS.md");
+    const rules = `# Nexus Workspace - Cursor Configuration
 
-4. **Check if a tool is installed** before using:
-   \`\`\`bash
-   which eve imsg gog
-   \`\`\`
-${agentsMdSection}${bootstrapSection}
-## Skill Directory Structure
+This workspace uses Nexus. Follow the root \`AGENTS.md\` file for all protocols.
 
-- **Bundled**: \`~/nexus/skills/\` (${manifest.bundled.count} skills)
-- **Managed**: \`~/nexus/skills/managed/\` (${manifest.managed.count} skills)  
-- **User**: \`~/nexus/home/skills/\` (${manifest.user.count} skills)
+## Cursor-Specific
 
-Precedence: User > Managed > Bundled
+- Run \`nexus status\` first
+- Cursor sessionStart hook injects identity context (see \`.cursor/hooks.json\`)
+- Use the Shell tool for \`nexus\` commands
+- Skill definitions live in \`${skillsDir}\`
+- Skill state and usage logs live in \`${SKILLS_STATE_DIR}\`
+- Read \`${agentsPath}\` for full instructions
 `;
-    return rules.trim() + "\n";
+    return `${rules.trim()}\n`;
 }
 /**
  * Write cursor rules to the specified output path

package/dist/commands/doctor.js

@@ -24,7 +24,7 @@ import { ensureSystemdUserLingerInteractive } from "./systemd-linger.js";
 function resolveMode(cfg) {
     return cfg.gateway?.mode === "remote" ? "remote" : "local";
 }
-function resolveLegacyConfigPath(env) {
+function resolveLegacyConfigPath(_env) {
     return path.join(os.homedir(), ".nexus", "nexus.json");
 }
 async function noteSecurityWarnings(cfg) {
@@ -438,8 +438,7 @@ async function maybeMigrateLegacyConfigFile(runtime) {
     const gatewayBind = typeof legacySnapshot.parsed?.gateway?.bind === "string"
         ? legacySnapshot.parsed.gateway?.bind
         : undefined;
-    const agentWorkspace = typeof legacySnapshot.parsed?.agent?.workspace ===
-        "string"
+    const agentWorkspace = typeof legacySnapshot.parsed?.agent?.workspace === "string"
         ? legacySnapshot.parsed.agent?.workspace
         : undefined;
     note([
@@ -471,7 +470,9 @@ async function maybeMigrateLegacyGatewayService(cfg, runtime) {
     const legacyServices = await findLegacyGatewayServices(process.env);
     if (legacyServices.length === 0)
         return;
-    note(legacyServices.map((svc) => `- ${svc.label} (${svc.platform}, ${svc.detail})`).join("\n"), "Legacy Nexus services detected");
+    note(legacyServices
+        .map((svc) => `- ${svc.label} (${svc.platform}, ${svc.detail})`)
+        .join("\n"), "Legacy Nexus services detected");
     const migrate = guardCancel(await confirm({
         message: "Migrate legacy Nexus services to Nexus now?",
         initialValue: true,

package/dist/commands/identity.js

@@ -1,40 +1,37 @@
-import fs from "node:fs";
-import path from "node:path";
-import { resolveStateDir } from "../config/paths.js";
+import { resolveIdentitySnapshot } from "../agents/identity-state.js";
 import { defaultRuntime } from "../runtime.js";
-function readField(pathname, label) {
-    try {
-        const raw = fs.readFileSync(pathname, "utf-8");
-        const regex = new RegExp(`^[-*]?\\s*${label}\\s*:\\s*(.+)$`, "im");
-        const match = raw.match(regex);
-        return match?.[1]?.trim();
-    }
-    catch {
-        return undefined;
-    }
-}
 export async function identityCommand(opts, runtime = defaultRuntime) {
-    const stateDir = resolveStateDir();
-    const agentId = process.env.NEXUS_AGENT_ID?.trim() || "default";
-    const agentIdentityDir = path.join(stateDir, "agents", agentId, "identity");
-    const userIdentityDir = path.join(stateDir, "user", "identity");
-    const agentIdentityPath = path.join(agentIdentityDir, "IDENTITY.md");
-    const agentSoulPath = path.join(agentIdentityDir, "SOUL.md");
-    const agentMemoryPath = path.join(agentIdentityDir, "MEMORY.md");
-    const userProfilePath = path.join(userIdentityDir, "PROFILE.md");
+    const resolution = resolveIdentitySnapshot();
+    if (!resolution.ok) {
+        const payload = {
+            ok: false,
+            error: "multiple_agents",
+            agents: resolution.agentOptions,
+        };
+        if (opts.json) {
+            runtime.log(JSON.stringify(payload, null, 2));
+        }
+        else {
+            runtime.error("Multiple agents detected in state/agents.");
+            runtime.error(`Set NEXUS_AGENT_ID to one of: ${payload.agents.join(", ")}`);
+        }
+        runtime.exit(2);
+        return;
+    }
+    const identity = resolution.snapshot;
     const payload = {
         agent: {
-            id: agentId,
-            name: readField(agentIdentityPath, "Name"),
-            identityPath: agentIdentityPath,
-            soulPath: agentSoulPath,
-            memoryPath: agentMemoryPath,
-            exists: fs.existsSync(agentIdentityPath),
+            id: identity.agentId,
+            name: identity.agentName,
+            identityPath: identity.agentIdentityPath,
+            soulPath: identity.agentSoulPath,
+            memoryPath: identity.agentMemoryPath,
+            exists: identity.agentIdentityExists,
         },
         user: {
-            name: readField(userProfilePath, "Name"),
-            profilePath: userProfilePath,
-            exists: fs.existsSync(userProfilePath),
+            name: identity.userName,
+            identityPath: identity.userIdentityPath,
+            exists: identity.userIdentityExists,
         },
     };
     if (opts.json) {
@@ -43,7 +40,7 @@ export async function identityCommand(opts, runtime = defaultRuntime) {
     }
     if (!opts.target || opts.target === "user") {
         runtime.log(`User: ${payload.user.name ?? "(unknown)"}`);
-        runtime.log(`  ${payload.user.profilePath}`);
+        runtime.log(`  ${payload.user.identityPath}`);
     }
     if (!opts.target || opts.target === "agent") {
         runtime.log(`Agent: ${payload.agent.name ?? "(unknown)"} (${payload.agent.id})`);