@kashscript/neuron

Sovereign Intelligence Layer — an agentic reasoning kernel + RAG orchestrator with a tamper-evident audit ledger.

⚠ Commercial package (SSLA Schedule B). Production use requires an active paid Plan on the Kash-Registry. See LICENSE.

bun add @kashscript/neuron @kashscript/identity-core @kashscript/lexicons

Neuron is the "brain" artifact in the KashScript Foundry trinity (Identity, Trade, Neuron). It dispatches AI operations through kash.neuron.* envelopes, records every step in an append-only ledger, and ships with seven phases of audit verification: zero double-spends, no judge hallucinations, deterministic replay, mid-action crash recovery.

Highlights

• Deterministic, kernel-mediated reasoning. Resolver → Executor → Critic pipeline over an authored procedure library; cycle detection, hallucination catches, and zombie-process cleanup.
• Append-only audit ledger. Every decision is signed and chained; full replay from any point in history.
• RAG orchestration. Pluggable retrievers + privacy-filtered context.
• Provider seam, not bundled SDKs. No LLM vendor SDK is imported — hosts wire any model through the one-method LLMProvider interface (complete(req)). The kernel ships a StubLLMProvider for tests.
• Atomic actions. Mid-action crashes leave the ledger consistent; resumption is deterministic.
• Operation prototypes. Pre-built example plugins like the Oreoasis ride mapping + pricing vertical; register your own.

Quickstart

createAgent wires the whole runtime (resolver + executor + permission gate + budgeter + optional signed-receipt ledger + verified handshake) from one config:

import { createAgent, defineAgentProgram } from "@kashscript/neuron";

const agent = createAgent({
  program: defineAgentProgram({ /* authored procedures */ }),
  spec,                                       // AgenticSpec: persona, tool allowlist, quotas
  toolDispatcher,                             // your MCP / in-process tools
  resolver: { /* llm?, retriever? */ },       // omit llm ⇒ deterministic lexical
  reasoning: { llm },                         // run pure-reasoning nodes with an LLM
  receipts: { writer, agentId, invokerId },   // auto chain-linked, signed ledger
  handshake,                                  // optional: owner-signs strategic actions
  judge: { judge, agentId, invokerId },       // optional: post-DAG adversarial audit
});

const r = await agent.handle("refund my order 9");
switch (r.kind) {
  case "completed":           break;          // r.outputs
  case "needs-clarification": break;          // ask r.questions
  case "awaiting-signature":                  // owner signs r.challenge, then:
    await agent.resume({ dag: r.dag, executionId: r.executionId, envelopesByToolName, priorOutputs: r.priorOutputs });
    break;
  case "escalated": case "failed": case "denied": break;  // hand off
}

See v2 — Deterministic DAG + Resolver below for the lower-level Resolver / AgentLoop API the factory wraps.

v2 — Deterministic DAG + Resolver (accountable agency)

v1 generated a fresh plan with an LLM on every call. v2 authors the graph once (a deterministic, auditable, signable library of Procedures) and uses a Resolver to retrieve + reason + compose over that fixed library at runtime — it never invents nodes. The heavy machinery (Critic, receipts, owner-signature handshake) is tiered by each node's consequence, so reads stay frictionless and only consequential actions are gated. See specs/neuron-v2-pivot.md.

import {
  defineAgentProgram,
  Resolver,
  AgentLoop,
  DAGExecutor,
  InMemoryToolDispatcher,
  ResourceBudgeter,
} from "@kashscript/neuron";

// 1. Author the agent's procedure library (deterministic, inspectable).
const program = defineAgentProgram({
  agentId: myAgentDid,
  version: "1.0.0",
  name: "Support",
  procedures: [{
    name: "issue_refund",
    version: "1.0.0",
    description: "Look up an order and refund the customer.",
    triggers: ["refund my order", "i want a refund"],
    nodes: [
      { id: "lookup", class: "tool-bind", consequence: "read",
        description: "Look up the order", tool: "orders.get",
        inputSchema: "[email protected]", outputSchema: "[email protected]" },
      { id: "refund", class: "tool-bind", consequence: "strategic",  // owner must sign
        description: "Issue the refund", tool: "payments.refund", predecessors: ["lookup"],
        inputSchema: "[email protected]", outputSchema: "[email protected]" },
    ],
    definitionOfDone: [{ kind: "step-output-matches", stepId: "refund", lexicon: "[email protected]" }],
  }],
});

// 2. Wire the loop. Resolver runs heuristic-only with no `llm`, or RAG-like
//    select/compose/slot-fill with one.
const loop = new AgentLoop({
  resolver: new Resolver({ /* llm, retriever, confidenceThreshold */ }),
  executor: new DAGExecutor({ toolDispatcher, permissionGate }),
  spec, program,
  onConsequentialOutcome: (rec) => receiptWriter.write(/* … */),  // tiered receipts
});

// 3. Drive intents. The loop perceives → resolves → acts → observes → adapts.
const res = await loop.run({ intent: "refund my order 9", budgeter: new ResourceBudgeter(spec.resourceQuotas) });
// res.kind: "completed" | "awaiting-signature" | "needs-clarification" | "escalated" | "failed"
//   awaiting-signature → owner signs via Identity, then loop.resume({ dag, envelopesByToolName, priorOutputs, budgeter })

| v2 symbol | What it is | |-----------|------------| | defineProcedure / defineAgentProgram | author + validate the deterministic procedure library | | compileToTaskDAG | compose selected procedures into an executable DAG | | Resolver | retrieve → reason → compose → adapt (drop-in for the v1 decomposer) | | AgentLoop | the perceive→act→observe→adapt running loop with tiered receipts | | ConsequenceTier | read | write | strategic — the accountability dial on every node |

What's in the box

| Subpath | Purpose | Status | |----------------------------------------------------|---------------------------------------------------------------------|---------------| | @kashscript/neuron | Default — re-exports kernel + schemas + types | stable | | @kashscript/neuron/kernel | createAgent, Resolver, AgentLoop, DAGExecutor, StrategicCritic, InMemoryVectorRetriever/makeHybridRetriever, ReceiptWriter/makeReceiptSink, LifecycleManager | stable | | @kashscript/neuron/schemas | Procedure/AgentProgram, TaskDAG, AgenticSpec, receipts | stable | | @kashscript/neuron/handshake | Signed-action handshake + permission gate | stable | | @kashscript/neuron/adapters | Identity / Trade adapters | stable | | @kashscript/neuron/operations | MCP tool registry + dispatch | stable | | @kashscript/neuron/deployment | Headless deploy + secret vault | stable | | @kashscript/neuron/audit | Receipt-chain verification | stable | | @kashscript/neuron/interop | AP2-style mandate export (toAP2Mandate) | stable | | @kashscript/neuron/rag | Retrieval contracts (Retriever) — bring your own vector store | contract only | | @kashscript/neuron/orchestration | Multi-agent swarm coordination | experimental | | @kashscript/neuron/plugins/oreoasis · …/operations/prototypes/oreoasis | Ride-logistics demo vertical | example |

Audit posture

Neuron has been through seven internal audit phases. Each phase has a runnable proof in the repo's test/audit/ suite (not shipped in the npm tarball):

• Phase 1 — manifest hydration determinism
• Phase 2 — ledger append-only invariant
• Phase 3 — DAG cycle detection
• Phase 4 — judge hallucination catches
• Phase 5 — zombie process cleanup
• Phase 6 — privacy-filter scrubbing
• Phase 7 — mid-atomic-action crash recovery

These are internal audits, not third-party. For high-stakes deployments, consider commissioning an external review.

Licensing

This is a Schedule B Commercial Package. See LICENSE for the full terms. Quick summary:

| Use | Plan required | |-----------------------------|-------------------------| | Local development / eval | free (no Plan needed) | | 14-day production trial | trial | | Production AI inference | paid / team / enterprise |

Per-monthly-call licensing is available for high-volume deployments — contact [email protected].