@north-light/crouter-sdk

The ESM-only Node and browser client for a crouter daemon. Create agent runs, wait for typed results, stream work as it happens, and use the daemon's application-facing APIs.

Install and connect

npm install @north-light/crouter-sdk

In Node, new Crouter() uses the local unix socket and starts the daemon on the first request when the socket is cold. In a browser or a remote process, pass the TCP URL and bearer token returned by crtr sys connect — the owner token, or a scoped token from crtr sys connect --scopes whose list caps what the application and its runs may do. Call client.auth.status() before enabling a run button: its instructions tells the user what to do when next_step is not null.

import Crouter from '@north-light/crouter-sdk';

const client = new Crouter();
const status = await client.auth.status();

if (status.next_step !== null) {
  console.log(status.instructions);
} else {
  console.log('The daemon and selected provider are ready.');
}

const client = new Crouter({
  baseURL: 'http://127.0.0.1:8787',
  token: 'the-token-from-crtr-sys-connect',
});

Run and parse a result

parse() creates a root run, waits for its outcome, and types output_parsed from a Zod or Standard Schema. Pass scopes to give a run a per-run allow-list; under a scoped token the list must stay inside the token's ceiling, and omitting it gives the run the ceiling.

import Crouter from '@north-light/crouter-sdk';
import { z } from 'zod';

const client = new Crouter();
const run = await client.nodes.parse({
  prompt: 'Read package.json and return its name and version.',
  cwd: '/absolute/path/to/project',
  scopes: ['ask', 'memory:read'],
  output_schema: z.object({ name: z.string(), version: z.string() }),
});

if (run.kind === 'result') console.log(run.output_parsed.name, run.output_parsed.version);
else if (run.reason === 'declined') console.warn(run.declined?.reason);
else console.error(run.reason, run.detail);

Stream a run

nodes.stream() creates a run and opens its event stream. followActivity() turns tool-call events into snapshots for an activity view. Disconnecting or calling stream.abort() stops the stream, not the run.

import { followActivity } from '@north-light/crouter-sdk';

const stream = client.nodes.stream({
  prompt: 'Inspect the repository and report the failing tests.',
  cwd: '/absolute/path/to/project',
});

for await (const steps of followActivity(stream)) {
  renderActivity(steps);
}

const outcome = await stream.finalOutcome();
console.log(outcome.kind);

Read files, run bash, and use memory

File paths and the bash working directory are absolute. bash.run() returns non-zero exits as values. Memory methods accept a target such as node, cwd, profile, or store.

const source = await client.files.read('/absolute/path/to/project/package.json');
const command = await client.bash.run({
  command: 'npm test',
  cwd: '/absolute/path/to/project',
  timeout_s: 60,
});
const memory = await client.memory.retrieve('project/conventions', {
  cwd: '/absolute/path/to/project',
  frontmatter: true,
});

console.log(source.content, command.exit_code, memory.body);

Localhost demo

See the complete localhost SDK demo for streaming, structured output, and an HTTP plugin in one local page.

Reference

The SDK guide covers client construction, nodes and scopes, streaming, memory, files, bash, Docker, errors, and the complete resource map.

The SDK re-exports its public DTO types. Most applications should install this package rather than the lower-level @north-light/crouter-api.