@nexrall/code-core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Nexrall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# @nexrall/code-core
+
+Core agent loop, tools, and extension primitives for **Nexrall Code** — embed an AI coding agent in any Node.js application.
+
+```bash
+npm install @nexrall/code-core
+```
+
+## What's inside
+
+| Module | Description |
+|--------|-------------|
+| `@nexrall/code-core` | Everything via the root export |
+| `@nexrall/code-core/agent` | `runAgentLoop` — the main agentic loop |
+| `@nexrall/code-core/tools` | `executeTool` — built-in tool executor (bash, file I/O, search…) |
+| `@nexrall/code-core/symbols` | `getSymbols`, `getWorkspaceSymbols` — regex-based LSP-lite scanner |
+| `@nexrall/code-core/checkpoint` | `CheckpointManager` — persistent rewind / rollback |
+| `@nexrall/code-core/commands` | `loadSlashCommands`, `expandCommand` — slash command loader & expander |
+| `@nexrall/code-core/plugins` | `loadPlugins`, `pluginHooks`, `pluginMcpServers` — plugin system |
+| `@nexrall/code-core/permissions` | `loadSettings`, `evaluatePermission` — 4-tier permission rules |
+| `@nexrall/code-core/mcp` | `McpManager` — MCP server manager (stdio / HTTP / SSE) |
+| `@nexrall/code-core/api` | `streamChat` — streaming chat API client |
+| `@nexrall/code-core/types` | Shared TypeScript types |
+
+## Quick start
+
+```ts
+import { runAgentLoop } from '@nexrall/code-core/agent';
+import type { AgentLoopOptions } from '@nexrall/code-core';
+
+const messages = [
+  { role: 'user', content: [{ type: 'text', text: 'List the files in src/ and summarise what this project does.' }] }
+];
+
+const opts: AgentLoopOptions = {
+  model: 'turbo',          // 'turbo' (Sonnet) | 'pro' (Opus) | 'ultra' (Fable 5)
+  workDir: process.cwd(),
+  env: { platform: 'node', cwd: process.cwd(), shell: 'bash' },
+  clientType: 'cli',
+  mode: 'auto',
+  onText:       (t) => process.stdout.write(t),
+  onThinking:   () => {},
+  onThinkingDelta:    () => {},
+  onThinkingProgress: () => {},
+  onToolUse:    (name, input) => console.error(`[tool] ${name}`, input),
+  onToolResult: (name, res)   => console.error(`[tool result] ${name}`, res.error ?? '✓'),
+  onInjectedInput: () => {},
+  onUsage:      () => {},
+  requestPermission: async () => true,   // auto-approve everything
+};
+
+const history = await runAgentLoop(messages, opts);
+console.log('Done —', history.length, 'messages');
+```
+
+> **Requires authentication.** The agent streams through the Nexrall API — users must be logged in via `nexrall-code login` (or set `NEXRALL_TOKEN` env var).
+
+## Agent loop options
+
+```ts
+interface AgentLoopOptions {
+  model: 'turbo' | 'pro' | 'ultra';
+  workDir: string;
+  env: EnvContext;
+  clientType?: 'cli' | 'vscode';
+  mode?: 'auto' | 'ask' | 'edit' | 'plan';
+  effort?: 'low' | 'medium' | 'high' | 'extra';
+  nexrallMd?: string;            // project instructions (nexrall.md contents)
+  maxIterations?: number;        // default 500, ceiling 2000
+  autoContinue?: boolean;        // auto-extend budget when agent is mid-task (default: true)
+  autoCompact?: boolean;         // auto-summarise history at 80% context window (default: true)
+  abortSignal?: { aborted: boolean };
+  checkpointManager?: CheckpointManager;
+  mcpManager?: McpManager;
+  // Stream callbacks
+  onText: (text: string) => void;
+  onThinking: (text: string) => void;
+  onThinkingDelta: (text: string) => void;
+  onThinkingProgress: (tokens: number) => void;
+  onToolUse: (name: string, input: Record<string, unknown>, isSubTask?: boolean) => void;
+  onToolResult: (name: string, result: ToolResult, isSubTask?: boolean) => void;
+  onInjectedInput: (text: string) => void;
+  onUsage: (usage: UsageStats) => void;
+  requestPermission: (req: PermissionRequest) => Promise<boolean>;
+  // Optional: inject follow-up messages while the agent is running
+  takePendingInput?: () => string[];
+  // Optional: handle tools not in the built-in executor (e.g. VS Code LSP tools)
+  executeExternalTool?: (name: string, input: Record<string, unknown>) => Promise<ToolResult | null>;
+}
+```
+
+## Plugin system
+
+Drop a folder into `.nexrall/plugins/<name>/` (project) or `~/.nexrall/plugins/<name>/` (global):
+
+```
+.nexrall/plugins/my-plugin/
+  plugin.json          # { "name", "version", "description" }
+  commands/review.md   # custom /review slash command
+  agents/reviewer.md   # custom sub-agent type
+  hooks.json           # PreToolUse / PostToolUse hooks
+  mcp.json             # { "mcpServers": { ... } }
+```
+
+Precedence: **project** > **global** > **plugin** > **builtin**.
+
+```ts
+import { loadPlugins, pluginHooks, pluginMcpServers } from '@nexrall/code-core/plugins';
+
+const plugins = loadPlugins(process.cwd());
+// [{ name: 'my-plugin', version: '1.0.0', dir: '...', scope: 'project' }]
+```
+
+## Slash commands & agents
+
+```ts
+import { loadSlashCommands, expandCommand, findSlashCommand } from '@nexrall/code-core/commands';
+import { loadAgentTypes, findAgentType } from '@nexrall/code-core/agent-types';
+
+// Built-in /review command is always available (overridable)
+const cmds = loadSlashCommands(process.cwd());
+const review = findSlashCommand(cmds, 'review');
+const prompt = expandCommand(review, 'main..feature-branch', process.cwd());
+
+// Built-in 'reviewer' agent (read-only, usable as subagent_type: 'reviewer')
+const agents = loadAgentTypes(process.cwd());
+const reviewer = findAgentType(agents, 'reviewer');
+```
+
+## Checkpoint / rewind
+
+```ts
+import { CheckpointManager } from '@nexrall/code-core/checkpoint';
+
+// Scoped per session — persists to ~/.nexrall/checkpoints/<hash>/
+const cp = new CheckpointManager(workDir, sessionId);
+cp.beginTurn('refactor auth module', messages.length);
+// ... agent runs and mutates files ...
+cp.commitTurn();
+
+// Roll back files + conversation
+const result = cp.restore(cp.list()[0].id);
+// result.restored      → absolute paths rolled back
+// result.bashCount     → shell commands NOT undone (with warning)
+// result.gitStashHashes → git stash create recovery points
+```
+
+## Requirements
+
+- Node.js ≥ 18
+- A Nexrall account (sign up at [nexrall.com](https://nexrall.com))
+
+## License
+
+MIT © [Nexrall](https://nexrall.com)

package/dist/agent/agentTypes.d.ts

@@ -0,0 +1,17 @@
+export interface AgentType {
+    name: string;
+    description: string;
+    /** Optional allowlist — when set, the sub-agent may only use these tools. */
+    tools?: string[];
+    /** Optional model override for the sub-agent. */
+    model?: 'turbo' | 'pro' | 'ultra';
+    /** System instructions (the markdown body below the frontmatter). */
+    prompt: string;
+    source: 'project' | 'global' | 'builtin' | 'plugin';
+}
+/** Discover all custom agent types (project overrides global overrides builtin). */
+export declare function loadAgentTypes(workDir: string): AgentType[];
+/** A compact catalogue injected into the system prompt so the model can pick a type. */
+export declare function summariseAgents(types: AgentType[]): string;
+export declare function findAgentType(types: AgentType[], name: string | undefined): AgentType | undefined;
+//# sourceMappingURL=agentTypes.d.ts.map

package/dist/agent/agentTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentTypes.d.ts","sourceRoot":"","sources":["../../src/agent/agentTypes.ts"],"names":[],"mappings":"AAuBA,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,iDAAiD;IACjD,KAAK,CAAC,EAAE,OAAO,GAAG,KAAK,GAAG,OAAO,CAAC;IAClC,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;CACrD;AAoFD,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,CAS3D;AAED,wFAAwF;AACxF,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,MAAM,CAQ1D;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAIjG"}

package/dist/agent/agentTypes.js

@@ -0,0 +1,156 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadAgentTypes = loadAgentTypes;
+exports.summariseAgents = summariseAgents;
+exports.findAgentType = findAgentType;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const index_1 = require("../plugins/index");
+// ── Built-in agent types ──────────────────────────────────────────────────────
+// Shipped defaults; lowest precedence (project > global > builtin), so a user
+// can override any of them with a same-name .nexrall/agents/<name>.md file.
+const BUILTIN_AGENTS = [
+    {
+        name: 'reviewer',
+        description: 'Read-only code reviewer — finds correctness bugs, edge cases, and security issues in a diff or file set. Cannot modify files.',
+        tools: ['read_file', 'search_files', 'glob', 'list_directory', 'bash', 'get_symbols', 'get_workspace_symbols', 'find_references', 'go_to_definition', 'get_diagnostics'],
+        source: 'builtin',
+        prompt: [
+            'You are a meticulous senior code reviewer. You NEVER modify files — you only read, search, and report.',
+            '',
+            'Method:',
+            '1. Read the full context around every change you are asked to review; never judge a hunk in isolation.',
+            '2. Hunt specifically for: correctness bugs, unhandled edge cases (empty/null/unicode/concurrency/timezone),',
+            '   security issues (injection, path traversal, secrets in code, unsafe deserialization), breaking API',
+            '   changes (search for callers first), silent behaviour changes, and swallowed errors.',
+            '3. Verify test coverage: are the changed paths tested? Were assertions weakened or tests deleted?',
+            '4. Only use bash for read-only commands (git diff/log/show, grep, test runs). Never run mutating commands.',
+            '',
+            'Report format: 🔴 Critical / 🟡 Warning / 🟢 Suggestion, each with file:line and a concrete fix,',
+            'then a final verdict (APPROVE or REQUEST CHANGES) with a one-paragraph rationale.',
+        ].join('\n'),
+    },
+];
+function parseFrontmatter(raw) {
+    const m = /^\s*---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(raw);
+    if (!m)
+        return { meta: {}, body: raw.trim() };
+    const meta = {};
+    for (const line of m[1].split(/\r?\n/)) {
+        const kv = /^([A-Za-z0-9_-]+)\s*:\s*(.*)$/.exec(line.trim());
+        if (kv)
+            meta[kv[1].toLowerCase()] = kv[2].trim().replace(/^["']|["']$/g, '');
+    }
+    return { meta, body: (m[2] ?? '').trim() };
+}
+function parseModel(v) {
+    const s = (v ?? '').toLowerCase();
+    return s === 'turbo' || s === 'pro' || s === 'ultra' ? s : undefined;
+}
+function parseToolList(v) {
+    if (!v)
+        return undefined;
+    const tools = v
+        .replace(/^\[|\]$/g, '') // tolerate [a, b] style
+        .split(/[,\s]+/)
+        .map((t) => t.trim())
+        .filter(Boolean);
+    return tools.length ? tools : undefined;
+}
+function loadDir(dir, source, into) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir).filter((f) => f.endsWith('.md'));
+    }
+    catch {
+        return;
+    }
+    for (const file of entries) {
+        try {
+            const raw = fs.readFileSync(path.join(dir, file), 'utf-8');
+            const { meta, body } = parseFrontmatter(raw);
+            const name = (meta.name || path.basename(file, '.md')).trim();
+            if (!name)
+                continue;
+            // Earlier tiers win (project > global > plugin).
+            if (source !== 'project' && into.has(name))
+                continue;
+            into.set(name, {
+                name,
+                description: meta.description || `Custom ${name} agent`,
+                tools: parseToolList(meta.tools),
+                model: parseModel(meta.model),
+                prompt: body,
+                source,
+            });
+        }
+        catch {
+            /* skip unreadable / malformed definitions */
+        }
+    }
+}
+/** Discover all custom agent types (project overrides global overrides builtin). */
+function loadAgentTypes(workDir) {
+    const out = new Map();
+    loadDir(path.join(workDir, '.nexrall', 'agents'), 'project', out);
+    loadDir(path.join(os.homedir(), '.nexrall', 'agents'), 'global', out);
+    for (const dir of (0, index_1.pluginAssetDirs)(workDir, 'agents'))
+        loadDir(dir, 'plugin', out);
+    for (const agent of BUILTIN_AGENTS) {
+        if (!out.has(agent.name))
+            out.set(agent.name, agent);
+    }
+    return [...out.values()];
+}
+/** A compact catalogue injected into the system prompt so the model can pick a type. */
+function summariseAgents(types) {
+    if (!types.length)
+        return '';
+    return types
+        .map((t) => {
+        const tools = t.tools ? ` (tools: ${t.tools.join(', ')})` : '';
+        return `- ${t.name}: ${t.description}${tools}`;
+    })
+        .join('\n');
+}
+function findAgentType(types, name) {
+    if (!name)
+        return undefined;
+    const want = name.trim().toLowerCase();
+    return types.find((t) => t.name.toLowerCase() === want);
+}
+//# sourceMappingURL=agentTypes.js.map

package/dist/agent/loop.d.ts

@@ -0,0 +1,3 @@
+import type { Message, AgentLoopOptions } from '../types';
+export declare function runAgentLoop(initialMessages: Message[], options: AgentLoopOptions): Promise<Message[]>;
+//# sourceMappingURL=loop.d.ts.map

package/dist/agent/loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../src/agent/loop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EAMP,gBAAgB,EACjB,MAAM,UAAU,CAAC;AAuflB,wBAAsB,YAAY,CAChC,eAAe,EAAE,OAAO,EAAE,EAC1B,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,OAAO,EAAE,CAAC,CAuWpB"}