@miruzero/zero-agent 0.2.0

package/README.md

@@ -0,0 +1,36 @@
+# Zero Agent
+
+Local worker agent for Zero MCP multi-device execution.
+
+## Commands
+
+```powershell
+zero-agent init --server https://zero.miru.work
+zero-agent pair --server https://zero.miru.work --code ZERO-XXXX
+zero-agent start --once
+zero-agent start
+zero-agent status
+zero-agent doctor
+zero-agent providers
+zero-agent tools
+zero-agent capabilities
+```
+
+## State
+
+Default state path:
+
+```text
+%USERPROFILE%\.zero-agent\device.json
+```
+
+Device names default to the local PC hostname. Use --name only when you want a custom display name.
+
+Device tokens are local secrets and must not be printed or committed.
+
+## Package checks
+
+```powershell
+npm test
+npm pack --dry-run
+```

package/bin/zero-agent.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+'use strict';
+
+const cli = require('../src/cli');
+
+cli.run(process.argv.slice(2), process.env)
+  .then((code) => {
+    process.exitCode = code;
+  })
+  .catch((error) => {
+    console.error('[zero-agent] fatal: ' + (error && error.message ? error.message : String(error)));
+    process.exitCode = 1;
+  });

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@miruzero/zero-agent",
+  "version": "0.2.0",
+  "description": "MiruZero local worker agent for multi-device tool execution.",
+  "type": "commonjs",
+  "bin": {
+    "zero-agent": "bin/zero-agent.js"
+  },
+  "scripts": {
+    "test": "node --test",
+    "start": "node bin/zero-agent.js start",
+    "doctor": "node bin/zero-agent.js doctor"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "UNLICENSED"
+}

package/src/agent.js

@@ -0,0 +1,111 @@
+'use strict';
+
+const os = require('node:os');
+const config = require('./config');
+const caps = require('./capabilities');
+const { requestJson } = require('./http');
+
+const nowIso = () => new Date().toISOString();
+
+const serverBase = (server) => String(server || 'https://zero.miru.work').replace(/\/$/, '');
+
+const initDevice = ({ name, server }, env = process.env) => {
+  const host = os.hostname();
+  const device = {
+    name: name || host,
+    host,
+    server: server || 'https://zero.miru.work',
+    device_id: null,
+    status: 'initialized',
+    created_at: nowIso(),
+    updated_at: nowIso()
+  };
+  const file = config.saveDevice(device, env);
+  return { file, device: config.redactedDevice(device) };
+};
+
+const pairDevice = async ({ name, server, code }, env = process.env) => {
+  if (!server) throw Object.assign(new Error('server is required'), { exitCode: 64 });
+  if (!code) throw Object.assign(new Error('pairing code is required'), { exitCode: 64 });
+  const host = os.hostname();
+  const payload = { name: name || host, pairing_code: code, host };
+  const result = await requestJson(`${serverBase(server)}/devices/register`, {
+    method: 'POST',
+    body: payload
+  });
+  if (!result.ok) {
+    const error = new Error(`pair failed status=${result.status}`);
+    error.response = result.json;
+    throw error;
+  }
+  const device = {
+    name: payload.name,
+    host,
+    server,
+    device_id: result.json.device_id,
+    device_token: result.json.device_token,
+    status: 'paired',
+    paired_at: nowIso(),
+    updated_at: nowIso()
+  };
+  const file = config.saveDevice(device, env);
+  return { file, device: config.redactedDevice(device) };
+};
+
+const getPairedDevice = (env = process.env) => {
+  const device = config.loadDevice(env);
+  if (!device || !device.device_id || !device.device_token || !device.server) {
+    return null;
+  }
+  return device;
+};
+
+const heartbeatPayload = (device, env = process.env) => {
+  const capability = caps.buildCapabilities(env);
+  return {
+    name: device.name,
+    status: 'online',
+    last_seen: nowIso(),
+    capability_hash: capability.capability_hash,
+    provider_count: capability.providers.length
+  };
+};
+
+const heartbeatOnce = async (env = process.env) => {
+  const device = getPairedDevice(env);
+  if (!device) return { ok: false, code: 'NOT_PAIRED', message: 'run zero-agent pair first' };
+  const url = `${serverBase(device.server)}/devices/${encodeURIComponent(device.device_id)}/heartbeat`;
+  const result = await requestJson(url, {
+    method: 'POST',
+    token: device.device_token,
+    body: heartbeatPayload(device, env)
+  });
+  return { ok: result.ok, status: result.status, body: result.json };
+};
+
+const syncCapabilitiesOnce = async (env = process.env) => {
+  const device = getPairedDevice(env);
+  if (!device) return { ok: false, code: 'NOT_PAIRED' };
+  const url = `${serverBase(device.server)}/devices/${encodeURIComponent(device.device_id)}/capabilities`;
+  const result = await requestJson(url, {
+    method: 'POST',
+    token: device.device_token,
+    body: caps.buildCapabilities(env)
+  });
+  return { ok: result.ok, status: result.status, body: result.json };
+};
+
+const listDevices = async (env = process.env) => {
+  const device = config.loadDevice(env);
+  const result = await requestJson(`${serverBase(device?.server)}/devices`);
+  return { ok: result.ok, status: result.status, body: result.json };
+};
+module.exports = {
+  initDevice,
+  pairDevice,
+  heartbeatPayload,
+  heartbeatOnce,
+  syncCapabilitiesOnce,
+  listDevices,
+  getPairedDevice
+};

package/src/args.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const parseArgs = (argv = []) => {
+  const out = { _: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const item = argv[index];
+    if (!item.startsWith('--')) {
+      out._.push(item);
+      continue;
+    }
+    const raw = item.slice(2);
+    const eq = raw.indexOf('=');
+    if (eq >= 0) {
+      out[raw.slice(0, eq)] = raw.slice(eq + 1);
+      continue;
+    }
+    const next = argv[index + 1];
+    if (next && !next.startsWith('--')) {
+      out[raw] = next;
+      index += 1;
+    } else {
+      out[raw] = true;
+    }
+  }
+  return out;
+};
+
+module.exports = { parseArgs };

package/src/capabilities.js

@@ -0,0 +1,83 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const defaultMcpRoot = () => path.resolve(__dirname, '../..');
+const mcpRoot = (env = process.env) => path.resolve(env.ZERO_MCP_ROOT || defaultMcpRoot());
+const providersDir = (env = process.env) => path.join(mcpRoot(env), 'providers');
+
+const readManifest = (file) => {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    return { error: error.message };
+  }
+};
+
+const manifestProviders = (env = process.env) => {
+  const dir = providersDir(env);
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true })
+    .filter((item) => item.isDirectory())
+    .map((item) => {
+      const root = path.join(dir, item.name);
+      const manifestFile = path.join(root, 'provider.json');
+      const manifest = fs.existsSync(manifestFile) ? readManifest(manifestFile) : {};
+      return {
+        name: item.name,
+        type: manifest.type || 'unknown',
+        description: manifest.description || '',
+        providerRoot: root,
+        manifestFile,
+        manifestError: manifest.error || null,
+        module: manifest.module || null,
+        command: manifest.command || null,
+        args: manifest.args || []
+      };
+    });
+};
+
+const safeInternalTools = (provider) => {
+  if (!provider.module) return [];
+  const modulePath = provider.module.replaceAll('{providerRoot}', provider.providerRoot.replace(/\\/g, '/'));
+  const resolved = path.resolve(modulePath);
+  try {
+    const runtime = require(resolved);
+    if (typeof runtime.listTools !== 'function') return [];
+    return runtime.listTools({}).map((tool) => ({
+      name: tool.name,
+      description: tool.description || '',
+      inputSchema: tool.inputSchema || null
+    }));
+  } catch (error) {
+    return [{ name: '__scan_error__', description: error.message, inputSchema: null }];
+  }
+};
+const buildCapabilities = (env = process.env) => {
+  const providers = manifestProviders(env).map((provider) => {
+    const tools = provider.type === 'internal' ? safeInternalTools(provider) : [];
+    return {
+      name: provider.name,
+      type: provider.type,
+      description: provider.description,
+      status: provider.manifestError ? 'invalid' : 'present',
+      tools,
+      tool_count: tools.length,
+      mcp_stdio_live_scan: provider.type === 'mcp-stdio' ? false : undefined
+    };
+  });
+  const payload = {
+    agent_version: require('../package.json').version,
+    mcp_root: mcpRoot(env),
+    providers
+  };
+  payload.capability_hash = crypto
+    .createHash('sha256')
+    .update(JSON.stringify(payload.providers))
+    .digest('hex');
+  return payload;
+};
+
+module.exports = { mcpRoot, providersDir, manifestProviders, buildCapabilities };

package/src/cli.js

@@ -0,0 +1,195 @@
+'use strict';
+
+const childProcess = require('node:child_process');
+const os = require('node:os');
+const pkg = require('../package.json');
+const config = require('./config');
+const caps = require('./capabilities');
+const agent = require('./agent');
+const { parseArgs } = require('./args');
+
+const usage = () => `Zero Agent
+
+Usage:
+  zero-agent setup [--server <url>] [--name <device>] [--code <pairing-code>] [--no-global]
+  zero-agent init --server <url> [--name <device>]
+  zero-agent pair --server <url> --code <pairing-code> [--name <device>]
+  zero-agent start [--once] [--interval <ms>]
+  zero-agent status
+  zero-agent devices
+  zero-agent doctor
+  zero-agent providers
+  zero-agent tools
+  zero-agent capabilities
+`;
+
+const printJson = (value) => console.log(JSON.stringify(value, null, 2));
+const okMark = (ok) => ok ? 'OK' : 'FAIL';
+const DEFAULT_SERVER = 'https://zero.miru.work';
+
+const runGlobalInstall = (parsed, env) => {
+  if (parsed['no-global'] || env.ZERO_AGENT_SKIP_GLOBAL_INSTALL === '1') {
+    console.log('globalInstall=SKIPPED');
+    return { skipped: true };
+  }
+  const spec = parsed.package || (pkg.name + '@' + pkg.version);
+  const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  console.log('globalInstall=START ' + spec);
+  const result = childProcess.spawnSync(npmCmd, ['install', '-g', spec], { stdio: 'inherit', env });
+  if (result.status === 0) {
+    console.log('globalInstall=OK');
+    return { ok: true };
+  }
+  console.log('globalInstall=WARN exitCode=' + result.status);
+  return { ok: false, exitCode: result.status };
+};
+
+const runSetup = async (parsed, env) => {
+  const server = parsed.server || DEFAULT_SERVER;
+  const name = parsed.name || undefined;
+  console.log('Zero Agent Setup');
+  console.log('server=' + server);
+  console.log('name=' + (name || os.hostname()));
+  runGlobalInstall(parsed, env);
+  const init = agent.initDevice({ name, server }, env);
+  console.log('init=OK file=' + init.file);
+  if (!parsed.code) {
+    console.log('pairing=NEEDS_CODE');
+    console.log('Next: zero-agent pair --server ' + server + ' --code ZERO-XXXXXX --name ' + init.device.name);
+    console.log('Or:   npx ' + pkg.name + '@latest setup --server ' + server + ' --name ' + init.device.name + ' --code ZERO-XXXXXX');
+    return 0;
+  }
+  const paired = await agent.pairDevice({ name: init.device.name, server, code: parsed.code }, env);
+  console.log('pair=OK file=' + paired.file);
+  printJson(paired.device);
+  const heartbeat = await runStartOnce(env);
+  console.log('verify=OK');
+  printJson(heartbeat);
+  console.log('Start: zero-agent start');
+  return 0;
+};
+
+
+const status = (env) => {
+  const device = config.loadDevice(env);
+  if (!device) return { paired: false, home: config.agentHome(env) };
+  return { paired: Boolean(device.device_id), home: config.agentHome(env), device: config.redactedDevice(device) };
+};
+
+const doctor = (env) => {
+  const capability = caps.buildCapabilities(env);
+  return {
+    ok: true,
+    node: process.version,
+    platform: process.platform,
+    agent_home: config.agentHome(env),
+    mcp_root: capability.mcp_root,
+    providers: capability.providers.length,
+    capability_hash: capability.capability_hash
+  };
+};
+
+const runStartOnce = async (env) => {
+  const heartbeat = await agent.heartbeatOnce(env);
+  if (!heartbeat.ok && heartbeat.code === 'NOT_PAIRED') return heartbeat;
+  const capability = await agent.syncCapabilitiesOnce(env);
+  return { heartbeat, capability };
+};
+
+const printStartBanner = (env) => {
+  const device = config.loadDevice(env);
+  console.log('🚀 Starting Zero Agent...');
+  console.log('🔁 Session restored: ' + (device?.device_id ? 'yes' : 'no'));
+  console.log('👤 Device Name: ' + (device?.name || '(unpaired)'));
+  console.log('🆔 Device ID: ' + (device?.device_id || '(not paired)'));
+  console.log('🌐 Server: ' + (device?.server || 'https://zero.miru.work'));
+};
+
+const printLoopResult = (result) => {
+  if (!result || result.code === 'NOT_PAIRED') {
+    console.log('❌ Device not paired: run zero-agent pair first');
+    return;
+  }
+  const hb = result.heartbeat || {};
+  const cap = result.capability || {};
+  const device = cap.body?.device || hb.body?.device || null;
+  console.log(JSON.stringify({
+    at: new Date().toISOString(),
+    heartbeat: okMark(Boolean(hb.ok)),
+    capabilities: okMark(Boolean(cap.ok)),
+    status: device?.status || null,
+    name: device?.name || null,
+    host: device?.host || null,
+    providers: device?.provider_count || null,
+    last_seen: device?.last_seen || null
+  }));
+};
+
+async function run(argv = [], env = process.env) {
+  const parsed = parseArgs(argv);
+  const command = parsed._[0] || 'help';
+  if (command === 'help' || parsed.help) {
+    console.log(usage());
+    return 0;
+  }
+  if (command === 'setup') {
+    return runSetup(parsed, env);
+  }
+  if (command === 'init') {
+    const result = agent.initDevice({ name: parsed.name, server: parsed.server }, env);
+    console.log(`init=OK file=${result.file}`);
+    printJson(result.device);
+    return 0;
+  }
+  if (command === 'pair') {
+    const result = await agent.pairDevice({ name: parsed.name, server: parsed.server, code: parsed.code }, env);
+    console.log(`pair=OK file=${result.file}`);
+    printJson(result.device);
+    return 0;
+  }
+  if (command === 'status') {
+    printJson(status(env));
+    return 0;
+  }
+  if (command === 'devices') {
+    printJson(await agent.listDevices(env));
+    return 0;
+  }
+  if (command === 'doctor') {
+    printJson(doctor(env));
+    return 0;
+  }
+  if (command === 'providers') {
+    printJson(caps.manifestProviders(env).map((item) => ({
+      name: item.name,
+      type: item.type,
+      description: item.description,
+      status: item.manifestError ? 'invalid' : 'present'
+    })));
+    return 0;
+  }
+  if (command === 'tools' || command === 'capabilities') {
+    printJson(caps.buildCapabilities(env));
+    return 0;
+  }
+  if (command === 'start') {
+    if (parsed.once) {
+      printJson(await runStartOnce(env));
+      return 0;
+    }
+    const interval = Number(parsed.interval || 10000);
+    printStartBanner(env);
+    console.log('⏱️  Heartbeat interval: ' + interval + 'ms');
+    console.log('🟢 Device ready; press Ctrl+C to stop');
+    while (true) {
+      const result = await runStartOnce(env);
+      printLoopResult(result);
+      await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+  }
+  console.error('unknown command: ' + command);
+  console.error(usage());
+  return 64;
+}
+
+module.exports = { run, usage, status, doctor };

package/src/config.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const defaultHome = () => path.join(os.homedir(), '.zero-agent');
+
+const agentHome = (env = process.env) => path.resolve(env.ZERO_AGENT_HOME || defaultHome());
+const deviceFile = (env = process.env) => path.join(agentHome(env), 'device.json');
+const logDir = (env = process.env) => path.join(agentHome(env), 'logs');
+
+const ensureDirs = (env = process.env) => {
+  fs.mkdirSync(agentHome(env), { recursive: true });
+  fs.mkdirSync(logDir(env), { recursive: true });
+};
+
+const readJson = (file, fallback = null) => {
+  if (!fs.existsSync(file)) return fallback;
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+};
+const writeJson = (file, value) => {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(value, null, 2) + '\n', 'utf8');
+};
+
+const loadDevice = (env = process.env) => readJson(deviceFile(env), null);
+
+const saveDevice = (device, env = process.env) => {
+  ensureDirs(env);
+  writeJson(deviceFile(env), device);
+  return deviceFile(env);
+};
+
+const redactedDevice = (device) => {
+  if (!device) return null;
+  const clone = { ...device };
+  if (clone.device_token) clone.device_token = 'REDACTED';
+  if (clone.token) clone.token = 'REDACTED';
+  return clone;
+};
+module.exports = {
+  agentHome,
+  deviceFile,
+  logDir,
+  ensureDirs,
+  readJson,
+  writeJson,
+  loadDevice,
+  saveDevice,
+  redactedDevice
+};

package/src/http.js

@@ -0,0 +1,25 @@
+'use strict';
+
+const requestJson = async (url, { method = 'GET', token = null, body = null, timeoutMs = 15000 } = {}) => {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const headers = { accept: 'application/json' };
+    if (body !== null) headers['content-type'] = 'application/json';
+    if (token) headers.authorization = `Bearer ${token}`;
+    const response = await fetch(url, {
+      method,
+      headers,
+      body: body === null ? undefined : JSON.stringify(body),
+      signal: controller.signal
+    });
+    const text = await response.text();
+    let json = null;
+    try { json = text ? JSON.parse(text) : null; } catch { json = { raw: text }; }
+    return { ok: response.ok, status: response.status, json };
+  } finally {
+    clearTimeout(timeout);
+  }
+};
+
+module.exports = { requestJson };