Node SDK — aricode

Overview

SDK shape

The public SDK is intentionally narrow: Node-only, async-iterator-first, and built around host-managed session state.

Client + Session runtime

Create a reusable client, then spawn isolated sessions for each conversation or workflow branch.

createAriadne(...)
client.createSession(...)
session.run(...)

Quick start

Structured Events streaming

Consume `message.delta`, `tool.call`, `approval.required`, `usage`, and `turn.completed` over a single async iterator.

for await (const event of session.run(task)) {
  ...
}

Event model

Public Tooling API extensible

Register application-specific tools with `defineTool(...)` and `createToolRegistry(...)` while keeping aricode's built-ins available.

defineTool(...)
createToolRegistry([...])

Custom tools

Quick Start

Create a client and stream a run

The package root now exports the SDK directly. New integrations should use the aricode package and the createAricode(...) factory. Legacy createAriadne(...) aliases remain available for compatibility.

npm install aricode

Install aricode once. The same package ships the CLI binaries and the SDK runtime.

npm install aricode

ts createAricode()

Provide model and backend config once at client construction, then create one or more isolated sessions.

import { createAricode } from "aricode";

const client = createAricode({
  model: "glm-5",
  baseUrl: "http://localhost:11434/v1",
});

const session = client.createSession({
  cwd: process.cwd(),
});

ts session.run()

Runs stream structured events with `for await`, which works equally well in CLIs, servers, and desktop apps.

for await (const event of session.run("Read package.json and summarize the scripts.")) {
  if (event.type === "message.delta") {
    process.stdout.write(event.delta);
  }

  if (event.type === "tool.call") {
    console.log("tool", event.name, event.args);
  }
}

Events

Event stream contract

The async iterator is the primary runtime interface in v1. aricode emits structured events instead of requiring callback orchestration.

Conversation

message.delta streams partial text, and message.completed marks the full assistant message for a turn.

Execution

tool.call, tool.result, and turn.completed show exactly how the engine progressed.

Control

status, usage, warning, error, approval.required, and approval.resolved cover control flow and safety.

Custom Tools

Register application-specific capabilities

The public tool SDK is part of the first release. Define tools once, register them in a registry, and pass that registry into the client or session.

import { createAricode, createToolRegistry, defineTool } from "aricode";

const tools = createToolRegistry([
  defineTool({
    name: "lookup_ticket",
    schema: {
      name: "lookup_ticket",
      description: "Look up a ticket by id.",
      parameters: {
        type: "object",
        properties: {
          id: { type: "string" },
        },
        required: ["id"],
      },
    },
    async execute(args) {
      return { result: `ticket:${args.id}` };
    },
    metadata: {
      sideEffects: "none",
      permissionTier: "readonly",
      concurrentSafe: true,
      category: "plugin",
      kind: "tool",
      idempotent: true,
      cancellable: false,
      streaming: false,
      timeoutMs: 0,
      requiresApproval: false,
    },
  }),
]);

const client = createAricode({
  model: "glm-5",
  baseUrl: "http://localhost:11434/v1",
  toolRegistry: tools,
});

State

Host-owned persistence

The SDK defaults to in-memory host-managed state. Persist snapshots yourself, or use the included workspace adapter if you want aricode-style on-disk sessions.

Default store

InMemorySessionStore ships by default and keeps the SDK free of filesystem assumptions.

Snapshots

session.snapshot() returns serializable state and session.restore(state) rehydrates it later.

Workspace adapter

WorkspaceSessionStore bridges the SDK into aricode's existing workspace session model for internal product use.

Embed aricode in Node