@cyrnixlab/cyrboard-local-agent 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 - 2026-05-24
+
+- Initial public MVP for Tracker `Local Agent / MCP` jobs.
+- Added `connect`, `run-once`, `start`, `status`, and `disconnect` commands.
+- Added `codex` and `command` local execution modes.
+- Stores runner token in `.cyrboard/local-agent.json` with `0600` permissions.
+- Does not store one-time setup tokens.

package/CONTRIBUTING.md

@@ -0,0 +1,20 @@
+# Contributing
+
+This repository contains the local connector that users run next to their own
+source code. Keep changes small, auditable, and explicit.
+
+## Development
+
+```bash
+npm test
+npm run smoke
+```
+
+## Rules
+
+- Do not commit tokens, environment files, or local `.cyrboard/` directories.
+- Do not add telemetry or network calls beyond the configured Tracker server.
+- Keep dependencies minimal. Prefer Node.js standard library when practical.
+- Redact bearer tokens in errors, logs, tests, and fixtures.
+- Any change that affects authentication or token storage must update
+  `SECURITY.md`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cyrboard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# Cyrnix Lab Local Agent
+
+Local runner connector for Cyrnix/Cyrboard Tracker `Local Agent / MCP` jobs.
+
+The connector runs on a developer machine, inside a project repository. It never
+opens inbound ports. It registers with Tracker once, polls jobs over HTTPS, runs
+the selected local AI tool, and reports status back to Tracker.
+
+## Install
+
+```bash
+npx @cyrnixlab/cyrboard-local-agent --help
+```
+
+## Connect a repository
+
+Copy the one-time command from the Tracker project AI settings and run it from
+the repository root:
+
+```bash
+npx @cyrnixlab/cyrboard-local-agent connect \
+  --server https://tracker.example.com \
+  --project-id 1 \
+  --token cyr_mcp_xxx \
+  --repo . \
+  --agent codex
+```
+
+The setup token is short-lived and is not stored. After registration the local
+config stores only the runner token in `.cyrboard/local-agent.json` with `0600`
+permissions.
+
+## Run
+
+```bash
+npx @cyrnixlab/cyrboard-local-agent start
+```
+
+For a single claim/execute/report cycle:
+
+```bash
+npx @cyrnixlab/cyrboard-local-agent run-once
+```
+
+## Agent modes
+
+- `codex`: runs `codex exec` in the repository.
+- `command`: runs an explicit command. Useful for controlled smoke tests.
+
+Command mode example:
+
+```bash
+npx @cyrnixlab/cyrboard-local-agent connect \
+  --server http://localhost:8182 \
+  --project-id 1 \
+  --token cyr_mcp_xxx \
+  --repo . \
+  --agent command \
+  --command "node ./scripts/local-agent-smoke.js"
+```
+
+The child process receives:
+
+- `CYRBOARD_JOB_ID`
+- `CYRBOARD_PROJECT_ID`
+- `CYRBOARD_ISSUE_ID`
+- `CYRBOARD_JOB_KIND`
+- `CYRBOARD_BRANCH_NAME`
+- `CYRBOARD_JOB_PROMPT_PATH`
+- `CYRBOARD_JOB_RESULT_PATH`
+
+## Security model
+
+- No inbound connection to the developer machine.
+- No secrets are committed or shipped in this repository.
+- The setup token is used only for `/tracker/local-runners/register`.
+- The long-lived runner token is local to the repository checkout.
+- `.cyrboard/` should be ignored by Git.
+- Revoke a runner from the Tracker project AI integration page.
+
+## Publishing
+
+The package is intended to be published under the npm scope `@cyrnixlab`:
+
+```bash
+npm test
+npm run smoke
+npm pack --dry-run
+npm publish --access public
+```
+
+Before publishing, make sure the GitHub repository URL in `package.json`
+matches the public repository that hosts this code.

package/SECURITY.md

@@ -0,0 +1,32 @@
+# Security Policy
+
+## Supported versions
+
+The current `0.x` line is an early MVP. Security fixes are published in the
+latest available version.
+
+## Reporting a vulnerability
+
+Report security issues privately by email:
+
+```text
+cyrboard@cyrnix.dev
+```
+
+Please include:
+
+- package version;
+- operating system;
+- Tracker server version, if relevant;
+- exact command that triggered the issue, with tokens redacted;
+- impact and reproduction steps.
+
+Do not open public GitHub issues for vulnerabilities until we have coordinated a
+fix.
+
+## Token handling
+
+- Setup tokens are short-lived and should not be stored by this connector.
+- Runner tokens are stored only in `.cyrboard/local-agent.json`.
+- `.cyrboard/` must not be committed to a project repository.
+- Logs and error messages should not print bearer tokens.

package/bin/cyrboard-local-agent.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { formatCliError, main } from '../src/cli.js';
+
+main(process.argv.slice(2)).catch((error) => {
+  console.error(formatCliError(error));
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@cyrnixlab/cyrboard-local-agent",
+  "version": "0.1.0",
+  "description": "Local runner connector for Cyrnix/Cyrboard Tracker Local Agent / MCP jobs.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Cyrnix Lab <cyrboard@cyrnix.dev>",
+  "homepage": "https://github.com/CyrnixLab/cyrboard-local-agent#readme",
+  "bugs": {
+    "url": "https://github.com/CyrnixLab/cyrboard-local-agent/issues",
+    "email": "cyrboard@cyrnix.dev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CyrnixLab/cyrboard-local-agent.git"
+  },
+  "keywords": [
+    "cyrnix",
+    "cyrboard",
+    "tracker",
+    "local-agent",
+    "mcp",
+    "codex",
+    "claude"
+  ],
+  "bin": {
+    "cyrboard-local-agent": "bin/cyrboard-local-agent.js",
+    "cyrnixlab-local-agent": "bin/cyrboard-local-agent.js",
+    "cyrnix-local-agent": "bin/cyrboard-local-agent.js"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test",
+    "smoke": "node ./bin/cyrboard-local-agent.js --help",
+    "pack:dry-run": "npm pack --dry-run",
+    "prepublishOnly": "npm test && npm run smoke"
+  }
+}

package/src/agents.js

@@ -0,0 +1,147 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { runProcess } from './process.js';
+
+export async function runAgent(config, job, repoPath) {
+  const workspaceDir = resolve(repoPath, '.cyrboard', 'jobs');
+  const promptPath = resolve(workspaceDir, `${job.id}-prompt.md`);
+  const resultPath = resolve(workspaceDir, `${job.id}-result.md`);
+  const prompt = buildPrompt(job);
+
+  await mkdir(workspaceDir, { recursive: true, mode: 0o700 });
+  await writeFile(promptPath, prompt, { mode: 0o600 });
+
+  if (config.agent === 'codex') {
+    return runCodexAgent(config, job, repoPath, promptPath, resultPath);
+  }
+
+  if (config.agent === 'command') {
+    return runCommandAgent(config, job, repoPath, promptPath, resultPath);
+  }
+
+  throw new Error(`Unsupported agent mode: ${config.agent}`);
+}
+
+function buildPrompt(job) {
+  return [
+    `# Cyrboard Tracker Job #${job.id}`,
+    '',
+    `Project ID: ${job.projectId}`,
+    `Issue ID: ${job.issueId}`,
+    `Job kind: ${job.jobKind}`,
+    `Command ID: ${job.commandId}`,
+    `Branch: ${job.branchName || '-'}`,
+    '',
+    '## Prompt',
+    '',
+    job.promptText || '',
+    '',
+    '## Input',
+    '',
+    '```json',
+    JSON.stringify(job.input || {}, null, 2),
+    '```',
+    '',
+  ].join('\n');
+}
+
+async function runCodexAgent(config, job, repoPath, promptPath, resultPath) {
+  const args = [
+    'exec',
+    '--cd',
+    repoPath,
+    '--skip-git-repo-check',
+    '--sandbox',
+    config.sandbox || 'workspace-write',
+    '--output-last-message',
+    resultPath,
+    '-',
+  ];
+  const env = buildJobEnv(config, job, promptPath, resultPath);
+  const prompt = await import('node:fs/promises').then((fs) => fs.readFile(promptPath, 'utf8'));
+  const result = await runWithInput('codex', args, prompt, { cwd: repoPath, env });
+
+  return {
+    summary: trimSummary(result.stdout || result.stderr || `Codex completed job #${job.id}.`),
+    resultPath,
+  };
+}
+
+async function runCommandAgent(config, job, repoPath, promptPath, resultPath) {
+  if (!config.command) {
+    throw new Error('Command agent requires --command.');
+  }
+
+  const env = buildJobEnv(config, job, promptPath, resultPath);
+  const result = await runProcess(config.command, [], {
+    cwd: repoPath,
+    env,
+    shell: true,
+  });
+
+  return {
+    summary: trimSummary(result.stdout || `Command agent completed job #${job.id}.`),
+    resultPath,
+  };
+}
+
+function buildJobEnv(config, job, promptPath, resultPath) {
+  return {
+    ...process.env,
+    CYRBOARD_SERVER: config.serverUrl,
+    CYRBOARD_PROJECT_ID: String(job.projectId),
+    CYRBOARD_ISSUE_ID: String(job.issueId),
+    CYRBOARD_JOB_ID: String(job.id),
+    CYRBOARD_JOB_KIND: String(job.jobKind || ''),
+    CYRBOARD_BRANCH_NAME: String(job.branchName || ''),
+    CYRBOARD_JOB_PROMPT_PATH: promptPath,
+    CYRBOARD_JOB_RESULT_PATH: resultPath,
+  };
+}
+
+function trimSummary(value) {
+  const normalized = String(value || '').trim();
+
+  if (normalized.length <= 2000) {
+    return normalized;
+  }
+
+  return `${normalized.slice(0, 1997)}...`;
+}
+
+async function runWithInput(command, args, input, options = {}) {
+  const { spawn } = await import('node:child_process');
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      env: options.env,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk.toString();
+      process.stdout.write(chunk);
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk.toString();
+      process.stderr.write(chunk);
+    });
+    child.on('error', reject);
+    child.on('close', (code) => {
+      const result = { code: code ?? 0, stdout, stderr };
+
+      if (result.code === 0) {
+        resolve(result);
+        return;
+      }
+
+      const error = new Error(`${command} exited with code ${result.code}.`);
+      error.result = result;
+      reject(error);
+    });
+    child.stdin.end(input);
+  });
+}

package/src/args.js

@@ -0,0 +1,70 @@
+import { UsageError } from './errors.js';
+
+export function parseArgs(argv) {
+  const args = { _: [] };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const item = argv[index];
+
+    if (!item.startsWith('--')) {
+      args._.push(item);
+      continue;
+    }
+
+    const eqIndex = item.indexOf('=');
+
+    if (eqIndex > 2) {
+      args[item.slice(2, eqIndex)] = item.slice(eqIndex + 1);
+      continue;
+    }
+
+    const key = item.slice(2);
+    const next = argv[index + 1];
+
+    if (next === undefined || next.startsWith('--')) {
+      args[key] = true;
+      continue;
+    }
+
+    args[key] = next;
+    index += 1;
+  }
+
+  return args;
+}
+
+export function requiredString(args, key) {
+  const value = args[key];
+
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new UsageError(`Missing required --${key}.`);
+  }
+
+  return value.trim();
+}
+
+export function optionalString(args, key, fallback) {
+  const value = args[key];
+
+  if (typeof value !== 'string' || value.trim() === '') {
+    return fallback;
+  }
+
+  return value.trim();
+}
+
+export function optionalInt(args, key, fallback) {
+  const value = args[key];
+
+  if (typeof value !== 'string' || value.trim() === '') {
+    return fallback;
+  }
+
+  const parsed = Number.parseInt(value, 10);
+
+  if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+    throw new UsageError(`--${key} must be a positive integer.`);
+  }
+
+  return parsed;
+}

package/src/cli.js

@@ -0,0 +1,142 @@
+import { parseArgs, optionalInt, optionalString, requiredString } from './args.js';
+import { isLocalConfigIgnored, loadConfig, removeConfig, resolveRepoPath, saveConfig } from './config.js';
+import { UsageError } from './errors.js';
+import { redactSecrets } from './redact.js';
+import { TrackerClient } from './tracker-client.js';
+import { runOnce, startLoop } from './runner.js';
+
+export async function main(argv) {
+  const args = parseArgs(argv);
+  const command = args._[0];
+
+  if (!command || args.help === true || command === 'help') {
+    printHelp();
+    return;
+  }
+
+  if (command === 'connect') {
+    await connect(args);
+    return;
+  }
+
+  if (command === 'run-once') {
+    await runFromConfig(args, true);
+    return;
+  }
+
+  if (command === 'start') {
+    await runFromConfig(args, false);
+    return;
+  }
+
+  if (command === 'status') {
+    await status(args);
+    return;
+  }
+
+  if (command === 'disconnect') {
+    await disconnect(args);
+    return;
+  }
+
+  throw new UsageError(`Unknown command: ${command}`);
+}
+
+async function connect(args) {
+  const serverUrl = requiredString(args, 'server').replace(/\/+$/, '');
+  const projectId = optionalInt(args, 'project-id', 0);
+  const setupToken = requiredString(args, 'token');
+  const repoPath = resolveRepoPath(optionalString(args, 'repo', '.'));
+  const agent = optionalString(args, 'agent', 'codex');
+  const label = optionalString(args, 'label', `${process.platform} local agent`);
+  const command = optionalString(args, 'command', '');
+  const sandbox = optionalString(args, 'sandbox', 'workspace-write');
+
+  if (projectId <= 0) {
+    throw new UsageError('Missing required --project-id.');
+  }
+
+  if (!['codex', 'command'].includes(agent)) {
+    throw new UsageError('--agent must be codex or command.');
+  }
+
+  if (agent === 'command' && command === '') {
+    throw new UsageError('--command is required for command agent mode.');
+  }
+
+  const client = new TrackerClient(serverUrl);
+  const registered = await client.register({ setupToken, projectId, label });
+
+  if (typeof registered.rawToken !== 'string' || registered.rawToken.trim() === '') {
+    throw new Error('Tracker did not return a runner token.');
+  }
+
+  await saveConfig(repoPath, {
+    schemaVersion: 1,
+    serverUrl,
+    projectId,
+    runnerId: registered.runnerId,
+    runnerToken: registered.rawToken,
+    label,
+    agent,
+    command,
+    sandbox,
+  });
+
+  console.log(`Local runner #${registered.runnerId} connected.`);
+  console.log(`Config saved to ${repoPath}/.cyrboard/local-agent.json.`);
+
+  if (!(await isLocalConfigIgnored(repoPath))) {
+    console.warn('Warning: add .cyrboard/ to this repository .gitignore before committing.');
+  }
+}
+
+async function runFromConfig(args, once) {
+  const repoPath = resolveRepoPath(optionalString(args, 'repo', '.'));
+  const config = await loadConfig(repoPath);
+
+  if (once) {
+    await runOnce(config, repoPath);
+    return;
+  }
+
+  const intervalSeconds = optionalInt(args, 'interval', 10);
+  await startLoop(config, repoPath, intervalSeconds);
+}
+
+async function status(args) {
+  const repoPath = resolveRepoPath(optionalString(args, 'repo', '.'));
+  const config = await loadConfig(repoPath);
+
+  console.log(`Server: ${config.serverUrl}`);
+  console.log(`Project ID: ${config.projectId}`);
+  console.log(`Runner ID: ${config.runnerId}`);
+  console.log(`Agent: ${config.agent}`);
+}
+
+async function disconnect(args) {
+  const repoPath = resolveRepoPath(optionalString(args, 'repo', '.'));
+
+  await removeConfig(repoPath);
+  console.log('Local config removed. Revoke the runner in Cyrboard UI as well.');
+}
+
+function printHelp() {
+  console.log(`Cyrnix Lab Local Agent
+
+Usage:
+  cyrnixlab-local-agent connect --server <url> --project-id <id> --token <setup-token> [--repo .] [--agent codex]
+  cyrnixlab-local-agent run-once [--repo .]
+  cyrnixlab-local-agent start [--repo .] [--interval 10]
+  cyrnixlab-local-agent status [--repo .]
+  cyrnixlab-local-agent disconnect [--repo .]
+
+Agent modes:
+  codex      Run codex exec locally.
+  command    Run an explicit shell command, intended for controlled smoke tests.
+`);
+}
+
+export function formatCliError(error) {
+  return redactSecrets(error instanceof Error ? error.message : String(error));
+}

package/src/config.js

@@ -0,0 +1,56 @@
+import { mkdir, readFile, rm, writeFile, chmod } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+const CONFIG_DIR = '.cyrboard';
+const CONFIG_FILE = 'local-agent.json';
+
+export function resolveRepoPath(repo) {
+  return resolve(process.cwd(), repo || '.');
+}
+
+export function configPath(repoPath) {
+  return resolve(repoPath, CONFIG_DIR, CONFIG_FILE);
+}
+
+export async function saveConfig(repoPath, config) {
+  const dir = resolve(repoPath, CONFIG_DIR);
+  const path = configPath(repoPath);
+  const body = `${JSON.stringify(config, null, 2)}\n`;
+
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  await writeFile(path, body, { mode: 0o600 });
+  await chmod(path, 0o600);
+}
+
+export async function loadConfig(repoPath) {
+  const raw = await readFile(configPath(repoPath), 'utf8');
+  const parsed = JSON.parse(raw);
+
+  if (!parsed || typeof parsed !== 'object') {
+    throw new Error('Local agent config is invalid.');
+  }
+
+  return parsed;
+}
+
+export async function removeConfig(repoPath) {
+  await rm(configPath(repoPath), { force: true });
+}
+
+export async function isLocalConfigIgnored(repoPath) {
+  try {
+    const gitignore = await readFile(resolve(repoPath, '.gitignore'), 'utf8');
+    const entries = gitignore
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter((line) => line !== '' && !line.startsWith('#'));
+
+    return entries.includes(CONFIG_DIR) || entries.includes(`${CONFIG_DIR}/`) || entries.includes(`${CONFIG_DIR}/**`);
+  } catch (error) {
+    if (error && error.code === 'ENOENT') {
+      return false;
+    }
+
+    throw error;
+  }
+}

package/src/errors.js

@@ -0,0 +1,6 @@
+export class UsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'UsageError';
+  }
+}

package/src/process.js

@@ -0,0 +1,36 @@
+import { spawn } from 'node:child_process';
+
+export async function runProcess(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      env: options.env,
+      shell: options.shell || false,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk.toString();
+      process.stdout.write(chunk);
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk.toString();
+      process.stderr.write(chunk);
+    });
+    child.on('error', reject);
+    child.on('close', (code) => {
+      const result = { code: code ?? 0, stdout, stderr };
+
+      if (result.code === 0) {
+        resolve(result);
+        return;
+      }
+
+      const error = new Error(`${command} exited with code ${result.code}.`);
+      error.result = result;
+      reject(error);
+    });
+  });
+}

package/src/redact.js

@@ -0,0 +1,22 @@
+const TOKEN_PATTERNS = [
+  /cyr_mcp_[a-f0-9]+/gi,
+  /cyr_runner_[a-f0-9]+/gi,
+  /(Authorization:\s*Bearer\s+)[^\s]+/gi,
+  /(Bearer\s+)cyr_[^\s]+/gi,
+];
+
+export function redactSecrets(value) {
+  let result = String(value || '');
+
+  for (const pattern of TOKEN_PATTERNS) {
+    result = result.replace(pattern, (match, prefix = '') => {
+      if (typeof prefix === 'string' && prefix !== '') {
+        return `${prefix}[redacted]`;
+      }
+
+      return '[redacted-token]';
+    });
+  }
+
+  return result;
+}

package/src/runner.js

@@ -0,0 +1,57 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { runAgent } from './agents.js';
+import { TrackerClient } from './tracker-client.js';
+
+export async function runOnce(config, repoPath) {
+  const client = new TrackerClient(config.serverUrl);
+  const claim = await client.claim(config.runnerToken);
+  const job = claim.job || null;
+
+  if (job === null) {
+    console.log('No queued local_mcp jobs.');
+    return { claimed: false };
+  }
+
+  console.log(`Claimed job #${job.id} (${job.jobKind}).`);
+
+  try {
+    await client.heartbeat(config.runnerToken, {
+      jobId: job.id,
+      progressPercent: 10,
+      progressStage: 'local_agent_started',
+    });
+
+    const result = await runAgent(config, job, repoPath);
+
+    await client.heartbeat(config.runnerToken, {
+      jobId: job.id,
+      progressPercent: 90,
+      progressStage: 'local_agent_reporting',
+    });
+    await client.complete(config.runnerToken, {
+      jobId: job.id,
+      resultSummary: result.summary,
+    });
+
+    console.log(`Completed job #${job.id}.`);
+    return { claimed: true, jobId: job.id };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+
+    await client.fail(config.runnerToken, {
+      jobId: job.id,
+      errorMessage: message,
+    });
+
+    throw error;
+  }
+}
+
+export async function startLoop(config, repoPath, intervalSeconds) {
+  console.log(`Local agent started. Poll interval: ${intervalSeconds}s.`);
+
+  while (true) {
+    await runOnce(config, repoPath);
+    await delay(intervalSeconds * 1000);
+  }
+}

package/src/tracker-client.js

@@ -0,0 +1,62 @@
+import { redactSecrets } from './redact.js';
+
+export class TrackerClient {
+  constructor(serverUrl) {
+    this.serverUrl = normalizeServerUrl(serverUrl);
+  }
+
+  async register({ setupToken, projectId, label }) {
+    return this.postJson('/tracker/local-runners/register', setupToken, {
+      projectId,
+      label,
+    });
+  }
+
+  async claim(runnerToken) {
+    return this.postJson('/tracker/local-runners/claim', runnerToken, {});
+  }
+
+  async heartbeat(runnerToken, payload) {
+    return this.postJson('/tracker/local-runners/heartbeat', runnerToken, payload);
+  }
+
+  async complete(runnerToken, payload) {
+    return this.postJson('/tracker/local-runners/complete', runnerToken, payload);
+  }
+
+  async fail(runnerToken, payload) {
+    return this.postJson('/tracker/local-runners/fail', runnerToken, payload);
+  }
+
+  async postJson(path, bearerToken, payload) {
+    const response = await fetch(`${this.serverUrl}${path}`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${bearerToken}`,
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+      },
+      body: JSON.stringify(payload),
+    });
+
+    const text = await response.text();
+    const data = text.trim() !== '' ? JSON.parse(text) : {};
+
+    if (!response.ok) {
+      const message = typeof data.error === 'string' ? data.error : text;
+      throw new Error(redactSecrets(`Tracker request failed: ${response.status} ${message}`));
+    }
+
+    return data;
+  }
+}
+
+function normalizeServerUrl(serverUrl) {
+  const normalized = String(serverUrl || '').trim().replace(/\/+$/, '');
+
+  if (!normalized.startsWith('http://') && !normalized.startsWith('https://')) {
+    throw new Error('--server must start with http:// or https://.');
+  }
+
+  return normalized;
+}