@veedubin/neuralgentics 0.9.1

package/dist/neuralgentics/orchestrator.js

@@ -0,0 +1,154 @@
+/**
+ * Neuralgentics Orchestrator — main hook into OpenCode's agent lifecycle.
+ *
+ * The orchestrator injects identity strings into system prompts, validates
+ * routing decisions against the mandatory matrix, and exposes the list of
+ * available Neuralgentics agents.
+ *
+ * The orchestrator now communicates with the Go backend via JSON-RPC over
+ * stdio (GoBackendClient), replacing the previous HTTP transport to the
+ * Python memini-core server.
+ */
+import { ROUTING_MATRIX, validateAgentRouting } from "./routing.js";
+import { MemoryClient } from "./memory-client.js";
+import { StatelessProtocol } from "./stateless.js";
+/**
+ * Identity string injected into every agent's system prompt.
+ */
+const NEURALGENTICS_IDENTITY = "You are Neuralgentics, powered by OpenCode. Follow the Neuralgentics Stateless Agent Protocol. All tasks MUST go through the routing matrix.";
+/**
+ * The canonical Neuralgentics agent roster.
+ *
+ * Each entry matches the routing matrix so that the orchestrator can
+ * look up agent capabilities and dispatch tasks correctly.
+ */
+const AGENT_DEFINITIONS = [
+    {
+        name: "neuralgentics-coder",
+        description: "Fast code generation and bug-fix agent.",
+        model: "glm-5.1:cloud",
+        mode: "subagent",
+        steps: 50,
+    },
+    {
+        name: "neuralgentics-architect",
+        description: "Design decisions and architecture review agent.",
+        model: "deepseek-v4-pro:cloud",
+        mode: "subagent",
+        steps: 100,
+    },
+    {
+        name: "neuralgentics-explorer",
+        description: "Codebase exploration and file-finding agent.",
+        model: "devstral-2:123b-cloud",
+        mode: "subagent",
+        steps: 30,
+    },
+    {
+        name: "neuralgentics-tester",
+        description: "Test writing and execution agent.",
+        model: "deepseek-v4-flash:cloud",
+        mode: "subagent",
+        steps: 50,
+    },
+    {
+        name: "neuralgentics-linter",
+        description: "Linting, formatting, and style enforcement agent.",
+        model: "qwen3-coder-next:cloud",
+        mode: "subagent",
+        steps: 30,
+    },
+    {
+        name: "neuralgentics-git",
+        description: "Version control and git operations agent.",
+        model: "minimax-m2.7:cloud",
+        mode: "subagent",
+        steps: 30,
+    },
+    {
+        name: "neuralgentics-writer",
+        description: "Documentation and Markdown writing agent.",
+        model: "gemma4:31b-cloud",
+        mode: "subagent",
+        steps: 50,
+    },
+    {
+        name: "neuralgentics-researcher",
+        description: "Web research and data extraction agent.",
+        model: "kimi-k2.6:cloud",
+        mode: "subagent",
+        steps: 50,
+    },
+];
+/**
+ * The main orchestrator class for Neuralgentics within OpenCode.
+ *
+ * Provides three core hooks:
+ * 1. **injectSystemPrompt** — appends Neuralgentics identity to agent prompts.
+ * 2. **validateRouting** — enforces the mandatory routing matrix.
+ * 3. **getAgentList** — returns the full roster of Neuralgentics agents.
+ */
+export class NeuralgenticsOrchestrator {
+    routing;
+    stateless;
+    memoryClient;
+    /**
+     * Create a new NeuralgenticsOrchestrator.
+     *
+     * @param backend - One of:
+     *   - A `GoBackendClient` instance (useful for testing with a mock).
+     *   - A string path to the `neuralgentics-backend` binary.
+     *   - `undefined` to auto-resolve from env / $PATH.
+     */
+    constructor(backend) {
+        this.memoryClient = new MemoryClient(backend);
+        this.stateless = new StatelessProtocol(this.memoryClient);
+        this.routing = ROUTING_MATRIX;
+    }
+    /**
+     * Inject the Neuralgentics identity string into an agent's system prompt.
+     *
+     * The identity string is appended to the existing system prompt array.
+     *
+     * @param system - The mutable system prompt array to modify in-place.
+     * @param _agent - The agent configuration (reserved for future use).
+     * @param _session - The active session object (reserved for future use).
+     */
+    injectSystemPrompt(system, _agent, _session) {
+        system.push(NEURALGENTICS_IDENTITY);
+    }
+    /**
+     * Validate that a proposed agent assignment conforms to the routing matrix.
+     *
+     * @param params - Object containing the subagent type and optional parent/tasks.
+     * @returns An error string if routing is violated, or `undefined` if valid.
+     */
+    validateRouting(params) {
+        const { subagentType } = params;
+        const taskType = subagentType;
+        // Check against every routing rule for the "never" list.
+        for (const [type, rule] of Object.entries(this.routing)) {
+            if (rule.never.includes(subagentType)) {
+                const result = validateAgentRouting(type, subagentType);
+                if (!result.valid) {
+                    return result.reason;
+                }
+            }
+        }
+        // Also validate that the specific task type is known.
+        const result = validateAgentRouting(taskType, subagentType);
+        if (!result.valid) {
+            return result.reason;
+        }
+        return undefined;
+    }
+    /**
+     * Return the full list of Neuralgentics agent definitions.
+     *
+     * @returns An array of AgentDefinition objects.
+     */
+    getAgentList() {
+        return [...AGENT_DEFINITIONS];
+    }
+}
+//# sourceMappingURL=orchestrator.js.map

package/dist/neuralgentics/orchestrator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.js","sourceRoot":"","sources":["../../src/neuralgentics/orchestrator.ts"],"names":[],"mappings":"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"}

package/dist/neuralgentics/routing.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Neuralgentics Routing Matrix — mandatory task-to-agent assignment rules.
+ *
+ * Every task dispatched by the orchestrator MUST pass through this matrix.
+ * Violations result in a rejected routing with a descriptive reason.
+ */
+import type { RoutingRule } from "./types.js";
+/**
+ * The canonical routing matrix.
+ *
+ * Keys are task-type identifiers. Each entry names the **primary** agent
+ * that MUST handle that task type, plus a list of agents that MUST NOT
+ * be assigned to it.
+ */
+export declare const ROUTING_MATRIX: Record<string, RoutingRule>;
+/**
+ * Validate whether an agent assignment conforms to the routing matrix.
+ *
+ * @param taskType - The task-type identifier (must match a key in ROUTING_MATRIX).
+ * @param agentName - The agent being considered for the task.
+ * @returns An object with `valid: true`, or `valid: false` plus a `reason` string.
+ */
+export declare function validateAgentRouting(taskType: string, agentName: string): {
+    valid: boolean;
+    reason?: string;
+};
+/**
+ * Look up the primary agent for a task type.
+ *
+ * @param taskType - The task-type identifier.
+ * @returns The primary agent name, or `undefined` if no rule exists.
+ */
+export declare function getPrimaryAgent(taskType: string): string | undefined;
+//# sourceMappingURL=routing.d.ts.map

package/dist/neuralgentics/routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../src/neuralgentics/routing.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAiCtD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CA4BrC;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEpE"}

package/dist/neuralgentics/routing.js

@@ -0,0 +1,88 @@
+/**
+ * Neuralgentics Routing Matrix — mandatory task-to-agent assignment rules.
+ *
+ * Every task dispatched by the orchestrator MUST pass through this matrix.
+ * Violations result in a rejected routing with a descriptive reason.
+ */
+/**
+ * The canonical routing matrix.
+ *
+ * Keys are task-type identifiers. Each entry names the **primary** agent
+ * that MUST handle that task type, plus a list of agents that MUST NOT
+ * be assigned to it.
+ */
+export const ROUTING_MATRIX = {
+    "code-implementation": {
+        primary: "neuralgentics-coder",
+        never: ["general", "neuralgentics-explorer"],
+    },
+    "architecture-design": {
+        primary: "neuralgentics-architect",
+        never: ["general", "neuralgentics-coder"],
+    },
+    testing: {
+        primary: "neuralgentics-tester",
+        never: ["general", "neuralgentics-coder"],
+    },
+    "file-finding": {
+        primary: "neuralgentics-explorer",
+        never: ["general", "neuralgentics-architect"],
+    },
+    linting: {
+        primary: "neuralgentics-linter",
+        never: [],
+    },
+    "git-operations": {
+        primary: "neuralgentics-git",
+        never: [],
+    },
+    documentation: {
+        primary: "neuralgentics-writer",
+        never: [],
+    },
+    "web-research": {
+        primary: "neuralgentics-researcher",
+        never: [],
+    },
+};
+/**
+ * Validate whether an agent assignment conforms to the routing matrix.
+ *
+ * @param taskType - The task-type identifier (must match a key in ROUTING_MATRIX).
+ * @param agentName - The agent being considered for the task.
+ * @returns An object with `valid: true`, or `valid: false` plus a `reason` string.
+ */
+export function validateAgentRouting(taskType, agentName) {
+    const rule = ROUTING_MATRIX[taskType];
+    if (!rule) {
+        return {
+            valid: false,
+            reason: `Unknown task type: "${taskType}". No routing rule defined.`,
+        };
+    }
+    if (rule.never.includes(agentName)) {
+        return {
+            valid: false,
+            reason: `Agent "${agentName}" is forbidden for task type "${taskType}".`,
+        };
+    }
+    if (agentName !== rule.primary && rule.never.length === 0) {
+        // Permissive: any agent is allowed when there are no "never" restrictions.
+        return { valid: true };
+    }
+    if (agentName === rule.primary) {
+        return { valid: true };
+    }
+    // Not the primary, but not in the never-list either — allowed with a caveat.
+    return { valid: true };
+}
+/**
+ * Look up the primary agent for a task type.
+ *
+ * @param taskType - The task-type identifier.
+ * @returns The primary agent name, or `undefined` if no rule exists.
+ */
+export function getPrimaryAgent(taskType) {
+    return ROUTING_MATRIX[taskType]?.primary;
+}
+//# sourceMappingURL=routing.js.map

package/dist/neuralgentics/routing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.js","sourceRoot":"","sources":["../../src/neuralgentics/routing.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAgC;IACzD,qBAAqB,EAAE;QACrB,OAAO,EAAE,qBAAqB;QAC9B,KAAK,EAAE,CAAC,SAAS,EAAE,wBAAwB,CAAC;KAC7C;IACD,qBAAqB,EAAE;QACrB,OAAO,EAAE,yBAAyB;QAClC,KAAK,EAAE,CAAC,SAAS,EAAE,qBAAqB,CAAC;KAC1C;IACD,OAAO,EAAE;QACP,OAAO,EAAE,sBAAsB;QAC/B,KAAK,EAAE,CAAC,SAAS,EAAE,qBAAqB,CAAC;KAC1C;IACD,cAAc,EAAE;QACd,OAAO,EAAE,wBAAwB;QACjC,KAAK,EAAE,CAAC,SAAS,EAAE,yBAAyB,CAAC;KAC9C;IACD,OAAO,EAAE;QACP,OAAO,EAAE,sBAAsB;QAC/B,KAAK,EAAE,EAAE;KACV;IACD,gBAAgB,EAAE;QAChB,OAAO,EAAE,mBAAmB;QAC5B,KAAK,EAAE,EAAE;KACV;IACD,aAAa,EAAE;QACb,OAAO,EAAE,sBAAsB;QAC/B,KAAK,EAAE,EAAE;KACV;IACD,cAAc,EAAE;QACd,OAAO,EAAE,0BAA0B;QACnC,KAAK,EAAE,EAAE;KACV;CACF,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,QAAgB,EAChB,SAAiB;IAEjB,MAAM,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IAEtC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,MAAM,EAAE,uBAAuB,QAAQ,6BAA6B;SACrE,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QACnC,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,MAAM,EAAE,UAAU,SAAS,iCAAiC,QAAQ,IAAI;SACzE,CAAC;IACJ,CAAC;IAED,IAAI,SAAS,KAAK,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1D,2EAA2E;QAC3E,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACzB,CAAC;IAED,IAAI,SAAS,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC;QAC/B,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACzB,CAAC;IAED,6EAA6E;IAC7E,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACzB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,OAAO,cAAc,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;AAC3C,CAAC"}

package/dist/neuralgentics/stateless.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Neuralgentics Stateless Agent Protocol.
+ *
+ * Each agent invocation is fully self-contained. The protocol prepares
+ * a context package (storing it in memini-core) and returns a thin
+ * reference that the agent can use to pull full context at runtime.
+ * After execution, the agent stores a wrap-up record for audit/training.
+ */
+import type { ContextPackage } from "./types.js";
+import { MemoryClient } from "./memory-client.js";
+/**
+ * Implements the Neuralgentics Stateless Agent Protocol.
+ *
+ * The protocol has two phases:
+ * 1. **Prepare** — stores task context in memini-core and returns a
+ *    `ContextPackage` referencing the stored memory.
+ * 2. **Wrapup** — stores the agent's result alongside the original
+ *    memory ID for later review, training, or trust scoring.
+ */
+export declare class StatelessProtocol {
+    private memoryClient;
+    /**
+     * Create a new StatelessProtocol.
+     *
+     * @param memoryClient - The MemoryClient used to interact with memini-core.
+     */
+    constructor(memoryClient: MemoryClient);
+    /**
+     * Prepare a context package for a stateless agent invocation.
+     *
+     * The method stores the task context as a memory record and returns
+     * a `ContextPackage` containing the memory ID, a seed prompt that
+     * instructs the agent to fetch context from memini-core, and the
+     * task and agent metadata.
+     *
+     * @param task - Short description of the task to execute.
+     * @param agent - Name of the agent that will receive this package.
+     * @param previousMemoryId - Optional memory ID from a prior step to link contexts.
+     * @returns A fully populated ContextPackage ready for injection.
+     */
+    prepareContextPackage(task: string, agent: string, previousMemoryId?: string): Promise<ContextPackage>;
+    /**
+     * Store the result of a completed agent invocation.
+     *
+     * Links the result back to the original context memory for traceability.
+     *
+     * @param memoryId - The memory ID from the original ContextPackage.
+     * @param result - The agent's output text.
+     * @param metadata - Optional metadata (e.g. trust signal, duration).
+     */
+    storeWrapup(memoryId: string, result: string, metadata?: Record<string, unknown>): Promise<void>;
+}
+//# sourceMappingURL=stateless.d.ts.map

package/dist/neuralgentics/stateless.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stateless.d.ts","sourceRoot":"","sources":["../../src/neuralgentics/stateless.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD;;;;;;;;GAQG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,YAAY,CAAe;IAEnC;;;;OAIG;gBACS,YAAY,EAAE,YAAY;IAItC;;;;;;;;;;;;OAYG;IACG,qBAAqB,CACzB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,gBAAgB,CAAC,EAAE,MAAM,GACxB,OAAO,CAAC,cAAc,CAAC;IA6B1B;;;;;;;;OAQG;IACG,WAAW,CACf,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,CAAC,IAAI,CAAC;CAYjB"}

package/dist/neuralgentics/stateless.js

@@ -0,0 +1,83 @@
+/**
+ * Neuralgentics Stateless Agent Protocol.
+ *
+ * Each agent invocation is fully self-contained. The protocol prepares
+ * a context package (storing it in memini-core) and returns a thin
+ * reference that the agent can use to pull full context at runtime.
+ * After execution, the agent stores a wrap-up record for audit/training.
+ */
+/**
+ * Implements the Neuralgentics Stateless Agent Protocol.
+ *
+ * The protocol has two phases:
+ * 1. **Prepare** — stores task context in memini-core and returns a
+ *    `ContextPackage` referencing the stored memory.
+ * 2. **Wrapup** — stores the agent's result alongside the original
+ *    memory ID for later review, training, or trust scoring.
+ */
+export class StatelessProtocol {
+    memoryClient;
+    /**
+     * Create a new StatelessProtocol.
+     *
+     * @param memoryClient - The MemoryClient used to interact with memini-core.
+     */
+    constructor(memoryClient) {
+        this.memoryClient = memoryClient;
+    }
+    /**
+     * Prepare a context package for a stateless agent invocation.
+     *
+     * The method stores the task context as a memory record and returns
+     * a `ContextPackage` containing the memory ID, a seed prompt that
+     * instructs the agent to fetch context from memini-core, and the
+     * task and agent metadata.
+     *
+     * @param task - Short description of the task to execute.
+     * @param agent - Name of the agent that will receive this package.
+     * @param previousMemoryId - Optional memory ID from a prior step to link contexts.
+     * @returns A fully populated ContextPackage ready for injection.
+     */
+    async prepareContextPackage(task, agent, previousMemoryId) {
+        const content = previousMemoryId
+            ? `Task: ${task}\nPrevious context: ${previousMemoryId}`
+            : `Task: ${task}`;
+        const metadata = {
+            agent,
+            protocol: "stateless",
+            timestamp: new Date().toISOString(),
+        };
+        if (previousMemoryId) {
+            metadata.previousMemoryId = previousMemoryId;
+        }
+        const memoryId = await this.memoryClient.addMemory(content, metadata);
+        const seedPrompt = `Task: ${task}\nMemory ID: ${memoryId}\n` +
+            "Action: Fetch context from memini-core using the provided memory ID, then execute the task.";
+        return {
+            memoryId,
+            seedPrompt,
+            task,
+            agent,
+        };
+    }
+    /**
+     * Store the result of a completed agent invocation.
+     *
+     * Links the result back to the original context memory for traceability.
+     *
+     * @param memoryId - The memory ID from the original ContextPackage.
+     * @param result - The agent's output text.
+     * @param metadata - Optional metadata (e.g. trust signal, duration).
+     */
+    async storeWrapup(memoryId, result, metadata) {
+        const content = `Wrapup for memory ${memoryId}:\n${result}`;
+        const wrapupMetadata = {
+            ...(metadata ?? {}),
+            protocol: "stateless-wrapup",
+            sourceMemoryId: memoryId,
+            timestamp: new Date().toISOString(),
+        };
+        await this.memoryClient.addMemory(content, wrapupMetadata);
+    }
+}
+//# sourceMappingURL=stateless.js.map

package/dist/neuralgentics/stateless.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stateless.js","sourceRoot":"","sources":["../../src/neuralgentics/stateless.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH;;;;;;;;GAQG;AACH,MAAM,OAAO,iBAAiB;IACpB,YAAY,CAAe;IAEnC;;;;OAIG;IACH,YAAY,YAA0B;QACpC,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACnC,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,qBAAqB,CACzB,IAAY,EACZ,KAAa,EACb,gBAAyB;QAEzB,MAAM,OAAO,GAAG,gBAAgB;YAC9B,CAAC,CAAC,SAAS,IAAI,uBAAuB,gBAAgB,EAAE;YACxD,CAAC,CAAC,SAAS,IAAI,EAAE,CAAC;QAEpB,MAAM,QAAQ,GAA4B;YACxC,KAAK;YACL,QAAQ,EAAE,WAAW;YACrB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC;QAEF,IAAI,gBAAgB,EAAE,CAAC;YACrB,QAAQ,CAAC,gBAAgB,GAAG,gBAAgB,CAAC;QAC/C,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,SAAS,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAEtE,MAAM,UAAU,GACd,SAAS,IAAI,gBAAgB,QAAQ,IAAI;YACzC,6FAA6F,CAAC;QAEhG,OAAO;YACL,QAAQ;YACR,UAAU;YACV,IAAI;YACJ,KAAK;SACN,CAAC;IACJ,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,WAAW,CACf,QAAgB,EAChB,MAAc,EACd,QAAkC;QAElC,MAAM,OAAO,GAAG,qBAAqB,QAAQ,MAAM,MAAM,EAAE,CAAC;QAE5D,MAAM,cAAc,GAA4B;YAC9C,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC;YACnB,QAAQ,EAAE,kBAAkB;YAC5B,cAAc,EAAE,QAAQ;YACxB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC;QAEF,MAAM,IAAI,CAAC,YAAY,CAAC,SAAS,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;IAC7D,CAAC;CACF"}

package/dist/neuralgentics/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Neuralgentics shared type definitions.
+ *
+ * These types define the data contracts used across the Neuralgentics overlay:
+ * agent definitions, routing rules, context packages, memory records,
+ * and broker catalog entries.
+ */
+/** Describes a Neuralgentics agent and its operational parameters. */
+export interface AgentDefinition {
+    /** Unique agent name (e.g. "neuralgentics-coder"). */
+    name: string;
+    /** Human-readable description of the agent's role. */
+    description: string;
+    /** Ollama / cloud model identifier the agent should use. */
+    model: string;
+    /** Execution mode — "all" for full access, "subagent" for delegated, "primary" for top-level. */
+    mode: "all" | "subagent" | "primary";
+    /** Maximum protocol steps the agent may execute (0 = unlimited). */
+    steps?: number;
+}
+/** Encodes a mandatory routing rule — which agent must handle a task type
+ *  and which agents must NEVER be assigned to it. */
+export interface RoutingRule {
+    /** The canonical agent name that MUST handle this task type. */
+    primary: string;
+    /** Agent names that MUST NOT be assigned this task type. */
+    never: string[];
+}
+/** A self-contained context package passed to a stateless agent.
+ *  Contains a memory reference so the agent can fetch full context at runtime. */
+export interface ContextPackage {
+    /** ID of the stored memory record in memoryManager. */
+    memoryId: string;
+    /** Seed prompt that bootstraps the agent with enough context to start. */
+    seedPrompt: string;
+    /** Short description of the task. */
+    task: string;
+    /** Name of the agent this package is prepared for. */
+    agent: string;
+}
+/** A record returned from the memoryManager server. */
+export interface MemoryRecord {
+    /** Unique memory identifier. */
+    id: string;
+    /** The memory content text. */
+    content: string;
+    /** Optional key-value metadata attached to the memory. */
+    metadata?: Record<string, unknown>;
+}
+/** An entry in the MCP broker's server catalog. */
+export interface ServerCatalogEntry {
+    /** Server name (e.g. "github", "memoryManager"). */
+    name: string;
+    /** Human-readable description of the server. */
+    description: string;
+    /** Number of tools this server exposes. */
+    toolCount: number;
+}
+/** A tool match result from the broker's intent-matching system. */
+export interface ToolMatch {
+    /** The MCP server that owns the matched tool. */
+    server: string;
+    /** The tool name within the server. */
+    tool: string;
+    /** Confidence score (0.0 – 1.0) for the match. */
+    confidence: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/neuralgentics/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/neuralgentics/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,sEAAsE;AACtE,MAAM,WAAW,eAAe;IAC9B,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,iGAAiG;IACjG,IAAI,EAAE,KAAK,GAAG,UAAU,GAAG,SAAS,CAAC;IACrC,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;qDACqD;AACrD,MAAM,WAAW,WAAW;IAC1B,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;kFACkF;AAClF,MAAM,WAAW,cAAc;IAC7B,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;CACf;AAED,uDAAuD;AACvD,MAAM,WAAW,YAAY;IAC3B,gCAAgC;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,mDAAmD;AACnD,MAAM,WAAW,kBAAkB;IACjC,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,oEAAoE;AACpE,MAAM,WAAW,SAAS;IACxB,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC;CACpB"}

package/dist/neuralgentics/types.js

@@ -0,0 +1,9 @@
+/**
+ * Neuralgentics shared type definitions.
+ *
+ * These types define the data contracts used across the Neuralgentics overlay:
+ * agent definitions, routing rules, context packages, memory records,
+ * and broker catalog entries.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/neuralgentics/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/neuralgentics/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/neuralgentics/updater.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Neuralgentics update interceptor.
+ *
+ * Intercepts OpenCode's built-in auto-updater so that vanilla upstream
+ * binaries never overwrite our patched build. When an update is available
+ * the user is directed to the Neuralgentics update script instead.
+ */
+export declare class NeuralgenticsUpdater {
+    static readonly IS_NEURALGENTICS = true;
+    static isActive(): boolean;
+    /**
+     * Check whether the opencode-base remote has newer commits than the local branch.
+     *
+     * @returns A human-readable message if updates exist, or `undefined` if up-to-date.
+     */
+    static checkLatest(): string | undefined;
+    /**
+     * Notify the user that an update is available and direct them to the
+     * Neuralgentics update script (does NOT auto-apply).
+     */
+    static applyUpdate(): void;
+}
+//# sourceMappingURL=updater.d.ts.map

package/dist/neuralgentics/updater.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"updater.d.ts","sourceRoot":"","sources":["../../src/neuralgentics/updater.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH,qBAAa,oBAAoB;IAC/B,MAAM,CAAC,QAAQ,CAAC,gBAAgB,QAAQ;IAExC,MAAM,CAAC,QAAQ,IAAI,OAAO;IAI1B;;;;OAIG;IACH,MAAM,CAAC,WAAW,IAAI,MAAM,GAAG,SAAS;IAuBxC;;;OAGG;IACH,MAAM,CAAC,WAAW,IAAI,IAAI;CAK3B"}

package/dist/neuralgentics/updater.js

@@ -0,0 +1,47 @@
+/**
+ * Neuralgentics update interceptor.
+ *
+ * Intercepts OpenCode's built-in auto-updater so that vanilla upstream
+ * binaries never overwrite our patched build. When an update is available
+ * the user is directed to the Neuralgentics update script instead.
+ */
+import { execSync } from "node:child_process";
+/** Base directory for opencode source repository. */
+const OPENCODE_BASE_DIR = process.env.NEURALGENTICS_OPENCODE_BASE_DIR ?? "/home/jcharles/Projects/MCP-Servers/neuralgentics/opencode-base";
+export class NeuralgenticsUpdater {
+    static IS_NEURALGENTICS = true;
+    static isActive() {
+        return this.IS_NEURALGENTICS;
+    }
+    /**
+     * Check whether the opencode-base remote has newer commits than the local branch.
+     *
+     * @returns A human-readable message if updates exist, or `undefined` if up-to-date.
+     */
+    static checkLatest() {
+        try {
+            execSync("git fetch origin", {
+                cwd: OPENCODE_BASE_DIR,
+                stdio: "pipe",
+                timeout: 15_000,
+            });
+            const output = execSync("git rev-list --count HEAD..origin/dev", { cwd: OPENCODE_BASE_DIR, encoding: "utf-8", timeout: 10_000 }).trim();
+            const count = parseInt(output, 10);
+            if (count > 0) {
+                return `origin/dev is ${count} commit(s) ahead`;
+            }
+            return undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Notify the user that an update is available and direct them to the
+     * Neuralgentics update script (does NOT auto-apply).
+     */
+    static applyUpdate() {
+        console.error("[Neuralgentics] Update available. Run: ./scripts/update-opencode.sh");
+    }
+}
+//# sourceMappingURL=updater.js.map

package/dist/neuralgentics/updater.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"updater.js","sourceRoot":"","sources":["../../src/neuralgentics/updater.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,qDAAqD;AACrD,MAAM,iBAAiB,GACrB,OAAO,CAAC,GAAG,CAAC,+BAA+B,IAAI,iEAAiE,CAAC;AAEnH,MAAM,OAAO,oBAAoB;IAC/B,MAAM,CAAU,gBAAgB,GAAG,IAAI,CAAC;IAExC,MAAM,CAAC,QAAQ;QACb,OAAO,IAAI,CAAC,gBAAgB,CAAC;IAC/B,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,WAAW;QAChB,IAAI,CAAC;YACH,QAAQ,CAAC,kBAAkB,EAAE;gBAC3B,GAAG,EAAE,iBAAiB;gBACtB,KAAK,EAAE,MAAM;gBACb,OAAO,EAAE,MAAM;aAChB,CAAC,CAAC;YAEH,MAAM,MAAM,GAAG,QAAQ,CACrB,uCAAuC,EACvC,EAAE,GAAG,EAAE,iBAAiB,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAC/D,CAAC,IAAI,EAAE,CAAC;YAET,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YACnC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;gBACd,OAAO,iBAAiB,KAAK,kBAAkB,CAAC;YAClD,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,WAAW;QAChB,OAAO,CAAC,KAAK,CACX,qEAAqE,CACtE,CAAC;IACJ,CAAC"}