@intent-systems/nexus 2026.1.5-3

package/dist/agents/shell-utils.js

@@ -0,0 +1,53 @@
+import { spawn } from "node:child_process";
+export function getShellConfig() {
+    if (process.platform === "win32") {
+        const shell = process.env.COMSPEC?.trim() || "cmd.exe";
+        return { shell, args: ["/d", "/s", "/c"] };
+    }
+    const shell = process.env.SHELL?.trim() || "sh";
+    return { shell, args: ["-c"] };
+}
+export function sanitizeBinaryOutput(text) {
+    const scrubbed = text.replace(/[\p{Format}\p{Surrogate}]/gu, "");
+    if (!scrubbed)
+        return scrubbed;
+    const chunks = [];
+    for (const char of scrubbed) {
+        const code = char.codePointAt(0);
+        if (code == null)
+            continue;
+        if (code === 0x09 || code === 0x0a || code === 0x0d) {
+            chunks.push(char);
+            continue;
+        }
+        if (code < 0x20)
+            continue;
+        chunks.push(char);
+    }
+    return chunks.join("");
+}
+export function killProcessTree(pid) {
+    if (process.platform === "win32") {
+        try {
+            spawn("taskkill", ["/F", "/T", "/PID", String(pid)], {
+                stdio: "ignore",
+                detached: true,
+            });
+        }
+        catch {
+            // ignore errors if taskkill fails
+        }
+        return;
+    }
+    try {
+        process.kill(-pid, "SIGKILL");
+    }
+    catch {
+        try {
+            process.kill(pid, "SIGKILL");
+        }
+        catch {
+            // process already dead
+        }
+    }
+}

package/dist/agents/skill-runner.js

@@ -0,0 +1,224 @@
+import fs from "node:fs";
+import path from "node:path";
+import { loadConfig } from "../config/config.js";
+import { runCommandWithTimeout } from "../process/exec.js";
+import { MANAGED_SKILLS_DIR, resolveUserPath } from "../utils.js";
+import { DEFAULT_AGENT_WORKSPACE_DIR } from "./workspace.js";
+import { buildWorkspaceSkillStatus } from "./skills-status.js";
+import { getSkillMetadata, hasBinary, loadWorkspaceSkillEntries, } from "./skills.js";
+import { getSkillExecutionType, getSkillScriptConfig, getSkillToolConfig, } from "./skill-tools.js";
+function loadSkillContext(name) {
+    const config = loadConfig();
+    const workspaceDir = resolveUserPath(config.agent?.workspace ?? DEFAULT_AGENT_WORKSPACE_DIR);
+    const managedSkillsDir = MANAGED_SKILLS_DIR;
+    const entries = loadWorkspaceSkillEntries(workspaceDir, {
+        config,
+        managedSkillsDir,
+    });
+    const entry = entries.find((item) => item.skill.name.toLowerCase() === name.toLowerCase());
+    const status = buildWorkspaceSkillStatus(workspaceDir, {
+        config,
+        managedSkillsDir,
+        entries,
+    });
+    const statusEntry = entry
+        ? status.skills.find((skill) => skill.name.toLowerCase() === entry.skill.name.toLowerCase())
+        : undefined;
+    return { entry, statusEntry };
+}
+function summarizeMissingRequirements(statusEntry) {
+    if (!statusEntry)
+        return null;
+    const missing = statusEntry.missing;
+    const parts = [];
+    if (missing.bins.length > 0) {
+        parts.push(`bins: ${missing.bins.join(", ")}`);
+    }
+    if (missing.env.length > 0) {
+        parts.push(`env: ${missing.env.join(", ")}`);
+    }
+    if (missing.config.length > 0) {
+        parts.push(`config: ${missing.config.join(", ")}`);
+    }
+    if (missing.os.length > 0) {
+        parts.push(`os: ${missing.os.join(", ")}`);
+    }
+    return parts.length > 0 ? parts.join(" | ") : null;
+}
+export function getSkillInfo(name) {
+    const { entry, statusEntry } = loadSkillContext(name);
+    if (!entry) {
+        return {
+            exists: false,
+            name,
+            description: "",
+            type: "unknown",
+            configured: false,
+        };
+    }
+    const metadata = getSkillMetadata(entry);
+    const execType = getSkillExecutionType(entry.skill.name);
+    const toolConfig = getSkillToolConfig(entry.skill.name);
+    const scriptConfig = getSkillScriptConfig(entry.skill.name);
+    const type = metadata?.type ?? execType;
+    const tool = toolConfig?.tool ?? (scriptConfig ? scriptConfig.runner : undefined);
+    const verify = toolConfig?.verify ??
+        (scriptConfig
+            ? `${scriptConfig.runner} ${scriptConfig.script}`
+            : undefined);
+    const configured = statusEntry?.eligible ?? execType === "prompt";
+    let prompt;
+    try {
+        prompt = fs.readFileSync(entry.skill.filePath, "utf-8");
+    }
+    catch {
+        prompt = undefined;
+    }
+    return {
+        exists: true,
+        name: entry.skill.name,
+        description: entry.skill.description,
+        type: type || "unknown",
+        tool,
+        verify,
+        configured,
+        prompt,
+    };
+}
+export async function runSkill(name, args) {
+    const { entry } = loadSkillContext(name);
+    if (!entry) {
+        return { ok: false, error: `Skill not found: ${name}` };
+    }
+    const execType = getSkillExecutionType(entry.skill.name);
+    if (execType === "prompt") {
+        return {
+            ok: false,
+            error: "Skill is prompt-only and has no runnable command.",
+        };
+    }
+    if (execType === "tool") {
+        const toolConfig = getSkillToolConfig(entry.skill.name);
+        if (!toolConfig?.tool) {
+            return { ok: false, error: "Skill tool configuration missing." };
+        }
+        if (!hasBinary(toolConfig.tool)) {
+            return { ok: false, error: `Missing binary: ${toolConfig.tool}` };
+        }
+        const result = await runCommandWithTimeout([toolConfig.tool, ...args], { timeoutMs: 300_000, cwd: entry.skill.baseDir });
+        if (result.code !== 0) {
+            return {
+                ok: false,
+                error: result.stderr || result.stdout || "Skill command failed.",
+                stdout: result.stdout,
+                stderr: result.stderr,
+                code: result.code,
+            };
+        }
+        return {
+            ok: true,
+            stdout: result.stdout,
+            stderr: result.stderr,
+            code: result.code,
+        };
+    }
+    if (execType === "script") {
+        const scriptConfig = getSkillScriptConfig(entry.skill.name);
+        if (!scriptConfig) {
+            return { ok: false, error: "Skill script configuration missing." };
+        }
+        if (!hasBinary(scriptConfig.runner)) {
+            return {
+                ok: false,
+                error: `Missing runner: ${scriptConfig.runner}`,
+            };
+        }
+        const scriptPath = path.join(entry.skill.baseDir, scriptConfig.script);
+        if (!fs.existsSync(scriptPath)) {
+            return { ok: false, error: `Script not found: ${scriptConfig.script}` };
+        }
+        if (scriptConfig.requiredEnv?.length) {
+            const missingEnv = scriptConfig.requiredEnv.filter((envName) => !process.env[envName]);
+            if (missingEnv.length > 0) {
+                return {
+                    ok: false,
+                    error: `Missing env: ${missingEnv.join(", ")}`,
+                };
+            }
+        }
+        const result = await runCommandWithTimeout([scriptConfig.runner, scriptPath, ...args], { timeoutMs: 300_000, cwd: entry.skill.baseDir });
+        if (result.code !== 0) {
+            return {
+                ok: false,
+                error: result.stderr || result.stdout || "Skill script failed.",
+                stdout: result.stdout,
+                stderr: result.stderr,
+                code: result.code,
+            };
+        }
+        return {
+            ok: true,
+            stdout: result.stdout,
+            stderr: result.stderr,
+            code: result.code,
+        };
+    }
+    return { ok: false, error: "Unknown skill execution type." };
+}
+export async function verifySkill(name) {
+    const { entry, statusEntry } = loadSkillContext(name);
+    if (!entry) {
+        return { ok: false, error: `Skill not found: ${name}` };
+    }
+    const missingSummary = summarizeMissingRequirements(statusEntry);
+    if (missingSummary) {
+        return { ok: false, error: `Missing requirements: ${missingSummary}` };
+    }
+    const execType = getSkillExecutionType(entry.skill.name);
+    if (execType === "prompt") {
+        return { ok: true, message: "Prompt-only skill requires no verification." };
+    }
+    if (execType === "tool") {
+        const toolConfig = getSkillToolConfig(entry.skill.name);
+        if (!toolConfig?.tool) {
+            return { ok: false, error: "Skill tool configuration missing." };
+        }
+        if (!hasBinary(toolConfig.tool)) {
+            return { ok: false, error: `Missing binary: ${toolConfig.tool}` };
+        }
+        if (!toolConfig.verify) {
+            return { ok: true, message: "Skill appears configured." };
+        }
+        const result = await runCommandWithTimeout(["sh", "-c", toolConfig.verify], { timeoutMs: 60_000, cwd: entry.skill.baseDir });
+        if (result.code !== 0) {
+            return {
+                ok: false,
+                error: result.stderr || result.stdout || "Verification failed.",
+            };
+        }
+        return { ok: true, message: "Skill verified successfully." };
+    }
+    if (execType === "script") {
+        const scriptConfig = getSkillScriptConfig(entry.skill.name);
+        if (!scriptConfig) {
+            return { ok: false, error: "Skill script configuration missing." };
+        }
+        if (!hasBinary(scriptConfig.runner)) {
+            return {
+                ok: false,
+                error: `Missing runner: ${scriptConfig.runner}`,
+            };
+        }
+        if (scriptConfig.requiredEnv?.length) {
+            const missingEnv = scriptConfig.requiredEnv.filter((envName) => !process.env[envName]);
+            if (missingEnv.length > 0) {
+                return {
+                    ok: false,
+                    error: `Missing env: ${missingEnv.join(", ")}`,
+                };
+            }
+        }
+        return { ok: true, message: "Skill appears configured." };
+    }
+    return { ok: false, error: "Unknown skill execution type." };
+}

package/dist/agents/skill-state.js

@@ -0,0 +1,164 @@
+/**
+ * Skill State Management
+ *
+ * Manages persistent runtime state for skills in ~/nexus/state/skill-state.json.
+ * This tracks per-skill information that changes over time:
+ * - Configuration status (has verification passed?)
+ * - Last verification/usage timestamps
+ * - Error history
+ * - Usage statistics
+ *
+ * This is separate from the static SKILL.md metadata which lives with the skill.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { STATE_DIR_NEXUS } from "../config/paths.js";
+const SKILL_STATE_FILENAME = "skill-state.json";
+const SKILL_STATE_VERSION = 1;
+/**
+ * Get the path to the skill state file
+ */
+export function resolveSkillStatePath(stateDir = STATE_DIR_NEXUS) {
+    return path.join(stateDir, SKILL_STATE_FILENAME);
+}
+/**
+ * Load skill state from disk.
+ * Returns default empty state if file doesn't exist or is invalid.
+ */
+export function loadSkillState(stateDir = STATE_DIR_NEXUS) {
+    const statePath = resolveSkillStatePath(stateDir);
+    try {
+        if (!fs.existsSync(statePath)) {
+            return createEmptyState();
+        }
+        const raw = fs.readFileSync(statePath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (!isValidSkillStateFile(parsed)) {
+            // Invalid format, return empty state
+            return createEmptyState();
+        }
+        return parsed;
+    }
+    catch {
+        return createEmptyState();
+    }
+}
+/**
+ * Save skill state to disk with atomic write
+ */
+export function saveSkillState(state, stateDir = STATE_DIR_NEXUS) {
+    const statePath = resolveSkillStatePath(stateDir);
+    const dir = path.dirname(statePath);
+    // Ensure directory exists
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    // Update timestamp
+    state.updatedAt = new Date().toISOString();
+    // Atomic write: write to temp file, then rename
+    const tmpPath = `${statePath}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
+    fs.writeFileSync(tmpPath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+    fs.renameSync(tmpPath, statePath);
+    fs.chmodSync(statePath, 0o600);
+}
+/**
+ * Get state for a specific skill
+ */
+export function getSkillRuntimeState(skillName, stateDir = STATE_DIR_NEXUS) {
+    const state = loadSkillState(stateDir);
+    return state.skills[skillName];
+}
+/**
+ * Update state for a specific skill (merges with existing)
+ */
+export function updateSkillRuntimeState(skillName, updates, stateDir = STATE_DIR_NEXUS) {
+    const state = loadSkillState(stateDir);
+    const existing = state.skills[skillName] ?? { configured: false };
+    const updated = {
+        ...existing,
+        ...updates,
+    };
+    state.skills[skillName] = updated;
+    saveSkillState(state, stateDir);
+    return updated;
+}
+/**
+ * Mark a skill as successfully configured
+ */
+export function markSkillConfigured(skillName, stateDir = STATE_DIR_NEXUS) {
+    const now = new Date().toISOString();
+    const existing = getSkillRuntimeState(skillName, stateDir);
+    return updateSkillRuntimeState(skillName, {
+        configured: true,
+        configuredAt: existing?.configuredAt ?? now,
+        lastVerified: now,
+        lastError: undefined,
+    }, stateDir);
+}
+/**
+ * Mark a skill verification as failed
+ */
+export function markSkillVerificationFailed(skillName, error, stateDir = STATE_DIR_NEXUS) {
+    const now = new Date().toISOString();
+    return updateSkillRuntimeState(skillName, {
+        configured: false,
+        lastVerified: now,
+        lastError: error.slice(0, 500), // Truncate long errors
+    }, stateDir);
+}
+/**
+ * Update skill usage statistics after execution
+ */
+export function recordSkillExecution(skillName, success, stateDir = STATE_DIR_NEXUS) {
+    const now = new Date().toISOString();
+    const existing = getSkillRuntimeState(skillName, stateDir) ?? {
+        configured: false,
+    };
+    const totalInvocations = (existing.totalInvocations ?? 0) + 1;
+    const prevSuccesses = (existing.successRate ?? 1) * (totalInvocations - 1);
+    const newSuccesses = prevSuccesses + (success ? 1 : 0);
+    const successRate = newSuccesses / totalInvocations;
+    return updateSkillRuntimeState(skillName, {
+        lastUsed: now,
+        totalInvocations,
+        successRate: Math.round(successRate * 1000) / 1000, // 3 decimal places
+    }, stateDir);
+}
+/**
+ * Get all configured skill names
+ */
+export function getConfiguredSkillNames(stateDir = STATE_DIR_NEXUS) {
+    const state = loadSkillState(stateDir);
+    return Object.entries(state.skills)
+        .filter(([_, s]) => s.configured)
+        .map(([name]) => name);
+}
+/**
+ * Get all unconfigured skill names (that have been attempted)
+ */
+export function getUnconfiguredSkillNames(stateDir = STATE_DIR_NEXUS) {
+    const state = loadSkillState(stateDir);
+    return Object.entries(state.skills)
+        .filter(([_, s]) => !s.configured)
+        .map(([name]) => name);
+}
+// ============================================================================
+// Internal helpers
+// ============================================================================
+function createEmptyState() {
+    return {
+        version: SKILL_STATE_VERSION,
+        updatedAt: new Date().toISOString(),
+        skills: {},
+    };
+}
+function isValidSkillStateFile(data) {
+    if (!data || typeof data !== "object")
+        return false;
+    const obj = data;
+    if (typeof obj.version !== "number")
+        return false;
+    if (typeof obj.skills !== "object" || obj.skills === null)
+        return false;
+    return true;
+}

package/dist/agents/skill-tools.js

@@ -0,0 +1,191 @@
+/**
+ * Skill Tool Mappings
+ *
+ * Maps skills to their required tools, verification commands, and execution types.
+ * This is the single source of truth for how to execute and verify each skill.
+ *
+ * Skills are classified into three types:
+ * 1. Tool-based: Require a binary (e.g., gog, tmux, ffmpeg)
+ * 2. Script-based: Run via interpreter (node, python)
+ * 3. Prompt-only: Pure instructions, no external tool needed
+ */
+/**
+ * Tool-based skills that require a binary
+ *
+ * Each entry maps skill name to tool binary and verification command.
+ * Verification commands should be lightweight and not require user input.
+ */
+export const KNOWN_SKILL_TOOLS = {
+    // OAuth/Complex skills (require auth setup)
+    gog: {
+        tool: "gog",
+        verify: "gog gmail labels list --account default",
+        requiresAuth: true,
+    },
+    eve: {
+        tool: "eve",
+        verify: "eve messages --limit 1",
+        requiresAuth: true,
+        configEnv: ["EVE_APPLEID", "EVE_PASSWORD"],
+    },
+    "1password": {
+        tool: "op",
+        verify: "op whoami",
+        requiresAuth: true,
+    },
+    // Tool skills (installable binaries)
+    tmux: {
+        tool: "tmux",
+        verify: "tmux -V",
+    },
+    peekaboo: {
+        tool: "peekaboo",
+        verify: "peekaboo --version",
+    },
+    qmd: {
+        tool: "qmd",
+        verify: "qmd status",
+    },
+    aix: {
+        tool: "aix",
+        verify: "aix --version",
+    },
+    summarize: {
+        tool: "summarize",
+        verify: "summarize --help",
+        configEnv: ["OPENAI_API_KEY", "ANTHROPIC_API_KEY"],
+    },
+    "video-frames": {
+        tool: "ffmpeg",
+        verify: "ffmpeg -version",
+    },
+    camsnap: {
+        tool: "camsnap",
+        verify: "camsnap --help",
+    },
+    gifgrep: {
+        tool: "gifgrep",
+        verify: "gifgrep --version",
+    },
+    "nano-pdf": {
+        tool: "nano-pdf",
+        verify: "nano-pdf --help",
+    },
+    songsee: {
+        tool: "songsee",
+        verify: "songsee --version",
+    },
+    "bear-notes": {
+        tool: "bear",
+        verify: "bear --version",
+    },
+    openhue: {
+        tool: "openhue",
+        verify: "openhue --version",
+    },
+    "obsidian-semantic-search": {
+        tool: "obsidian-semantic-search",
+        verify: "obsidian-semantic-search --help",
+    },
+    "nexus-cloud": {
+        tool: "wrangler",
+        verify: "wrangler --version",
+        requiresAuth: true,
+    },
+    // Coding tools
+    "coding-agent": {
+        tool: "codex",
+        verify: "codex --version",
+        configEnv: ["OPENAI_API_KEY", "ANTHROPIC_API_KEY"],
+    },
+};
+/**
+ * Script-based skills that run via interpreter
+ */
+export const SCRIPT_SKILLS = {
+    "brave-search": {
+        runner: "node",
+        script: "scripts/search.mjs",
+        requiredEnv: ["BRAVE_API_KEY"],
+    },
+    "openai-image-gen": {
+        runner: "python",
+        script: "scripts/gen.py",
+        requiredEnv: ["OPENAI_API_KEY"],
+    },
+};
+/**
+ * Pure prompt skills (no external tool needed)
+ *
+ * These skills work immediately after loading - they just provide
+ * instructions/prompts that guide agent behavior.
+ */
+export const PROMPT_ONLY_SKILLS = new Set([
+    // Core capabilities (always available)
+    "filesystem",
+    "computer-use",
+    "weather",
+    "web-scraping",
+    // Platform integrations (use internal tools/APIs)
+    "github",
+    "discord",
+    "x-twitter",
+    "apple-calendar",
+    "apple-notes",
+    "apple-reminders",
+    "things",
+    // AI/Agent patterns
+    "gemini",
+    "model-usage",
+    // Content/Data
+    "blogwatcher",
+    "newsletter-generation",
+]);
+/**
+ * Get the tool configuration for a skill
+ */
+export function getSkillToolConfig(skillName) {
+    return KNOWN_SKILL_TOOLS[skillName];
+}
+/**
+ * Get the script configuration for a skill
+ */
+export function getSkillScriptConfig(skillName) {
+    return SCRIPT_SKILLS[skillName];
+}
+/**
+ * Check if a skill is prompt-only
+ */
+export function isPromptOnlySkill(skillName) {
+    return PROMPT_ONLY_SKILLS.has(skillName);
+}
+/**
+ * Determine the execution type for a skill
+ */
+export function getSkillExecutionType(skillName) {
+    if (KNOWN_SKILL_TOOLS[skillName])
+        return "tool";
+    if (SCRIPT_SKILLS[skillName])
+        return "script";
+    if (PROMPT_ONLY_SKILLS.has(skillName))
+        return "prompt";
+    return "unknown";
+}
+/**
+ * Get all tool-based skill names
+ */
+export function getToolSkillNames() {
+    return Object.keys(KNOWN_SKILL_TOOLS);
+}
+/**
+ * Get all script-based skill names
+ */
+export function getScriptSkillNames() {
+    return Object.keys(SCRIPT_SKILLS);
+}
+/**
+ * Get all prompt-only skill names
+ */
+export function getPromptOnlySkillNames() {
+    return Array.from(PROMPT_ONLY_SKILLS);
+}

package/dist/agents/skill-usage.js

@@ -0,0 +1,43 @@
+import { loadConfig } from "../config/config.js";
+import { MANAGED_SKILLS_DIR, resolveUserPath } from "../utils.js";
+import { DEFAULT_AGENT_WORKSPACE_DIR } from "./workspace.js";
+import { buildWorkspaceSkillStatus } from "./skills-status.js";
+import { loadWorkspaceSkillEntries } from "./skills.js";
+function loadSkillEntries() {
+    const config = loadConfig();
+    const workspaceDir = resolveUserPath(config.agent?.workspace ?? DEFAULT_AGENT_WORKSPACE_DIR);
+    const managedSkillsDir = MANAGED_SKILLS_DIR;
+    const entries = loadWorkspaceSkillEntries(workspaceDir, {
+        config,
+        managedSkillsDir,
+    });
+    return { config, workspaceDir, managedSkillsDir, entries };
+}
+export async function getSkillStats(name) {
+    const { entries } = loadSkillEntries();
+    const entry = entries.find((item) => item.skill.name.toLowerCase() === name.toLowerCase());
+    if (!entry)
+        return null;
+    return {
+        runs: 0,
+        errors: 0,
+        lastUsed: undefined,
+        avgDurationMs: undefined,
+    };
+}
+export async function getAggregateStats() {
+    const { config, workspaceDir, managedSkillsDir, entries } = loadSkillEntries();
+    const status = buildWorkspaceSkillStatus(workspaceDir, {
+        config,
+        managedSkillsDir,
+        entries,
+    });
+    return {
+        totalRuns: 0,
+        activeSkills: entries.length,
+        mostUsed: undefined,
+        readyButUnused: status.skills
+            .filter((skill) => skill.eligible)
+            .map((skill) => skill.name),
+    };
+}