@levi/control-plane-sdk

Client-side TypeScript SDK for talking to the Levi Supervisor HTTP API (no auth).

What you’d use it for

• Build a UI/dashboard: show workers, jobs, work queue, questions, and live agent events.
• Automation / scripting: submit jobs, ingest work items, spawn/destroy workers, answer questions.
• Agent self-reporting: post log, checkpoint, help_requested, job_done, heartbeat events to the server.

What it is NOT

• Not a “host access” SDK: it does not read local files, run shell commands, or SSH anywhere.
• It only talks to the Supervisor API over HTTP using fetch.

Install

• Inside this repo: supervisor/ depends on it via file:../supervisor-sdk.
• In another project:
• If you publish it: npm i @levi/control-plane-sdk
  • Or install from a git/path source, depending on your deployment workflow.

Create a client (Node or browser)

import { createLeviathanClient } from '@levi/control-plane-sdk';

const client = createLeviathanClient({ baseUrl: 'http://supervisor-host:4118' });

const status = await client.getStatus();
console.log(status);

Live events (SSE)

Prefer the self-reporting stream:

for await (const msg of await client.streamReportEvents('job-id')) {
  // msg is a parsed JSON object from `data: <json>`
  console.log(msg);
}

Job event stream:

for await (const msg of await client.streamJobEvents('job-id')) {
  console.log(msg);
}

Submit a job and wait for completion (example)

const job = await client.createJob('Implement feature X', 7);

for await (const msg of await client.streamReportEvents(job.id)) {
  if (msg && typeof msg === 'object' && (msg as any).type === 'event') {
    const ev = (msg as any).event;
    if (ev?.type === 'job_done') {
      console.log(ev.result, ev.summary);
      break;
    }
  }
}

Work queue

const item = await client.addWork('Investigate bug Y', 5);
console.log('work item', item.id);

const list = await client.listWork(50);
console.log('work items', list.length);

Questions (from help_requested)

const pending = await client.listQuestions('pending', 50, 'job-123');
if (pending.length > 0) {
  const q = pending[0];
  await client.answerQuestion(q.id, 'Use approach Z; avoid touching X');
}

Agent-side reporting (no auth)

import { createReporter } from '@levi/control-plane-sdk';

const reporter = createReporter({
  leviathanUrl: 'http://supervisor-host:4118',
  jobId: 'job-id',
  agentId: 'agent-id',
});

await reporter.log('info', 'starting');
await reporter.checkpoint('repo_scanned', 'success', { files: 12 });
await reporter.helpRequested('blocker', 'Need config value for X', ['checked README', 'searched env vars']);
await reporter.taskDone('success', 'Implemented X', { files_changed: ['src/x.ts'] });

Security note (important)

This SDK assumes the Supervisor API is reachable and unauthenticated. If you deploy across machines/networks, treat the API as trusted-network only (or add auth/ACLs at the network layer).