@11agents/cli 0.1.1

package/README.md

@@ -0,0 +1,103 @@
+# 11agents CLI
+
+Local CLI for connecting AI coding runtimes to the 11agents control plane.
+
+## Install
+
+```bash
+npm install -g @11agents/cli@latest
+```
+
+The CLI requires Node.js 22 or newer.
+
+## Configure
+
+```bash
+export GTM_WRITES_TOKEN="<control-plane-token>"
+export ELEVENAGENTS_MACHINE="mac-mini-01"
+```
+
+The default control plane is `https://app.11agents.ai`. Set `ELEVENAGENTS_SERVER` only when targeting a local or custom deployment:
+
+```bash
+export ELEVENAGENTS_SERVER="http://localhost:8082"
+```
+
+`ELEVENAGENTS_MACHINE` is optional. If omitted, the CLI uses the local hostname.
+
+On startup, the CLI prints its current version and target server to stderr. It also checks npm for a newer `@11agents/cli` package and prints an upgrade command when one is available.
+
+## Runtime Pool
+
+Scan local AI runtimes:
+
+```bash
+11agents runtime scan
+```
+
+Register this machine and its detected runtimes:
+
+```bash
+11agents runtime register
+```
+
+Run the foreground daemon:
+
+```bash
+11agents daemon start
+```
+
+Run the daemon in the background:
+
+```bash
+11agents daemon start --background
+11agents daemon status
+11agents daemon stop
+```
+
+Background mode writes its pid to `~/.11agents/daemon.pid` and logs to `~/.11agents/daemon.log`.
+
+Useful daemon options:
+
+```bash
+11agents daemon start --heartbeat-interval 15 --scan-interval 60 --task-interval 15
+11agents daemon start --handler ./worker.js
+```
+
+The built-in task runner currently supports Codex tasks. A custom handler may export:
+
+```js
+export async function handleRuntimeTask(task) {
+  return {
+    status: 'in_review',
+    comment: `Handled task ${task.id}`,
+    memory_delta: ''
+  }
+}
+```
+
+## Telemetry Compatibility
+
+The package still includes the original `gtm-swarm` binary for swarm telemetry compatibility.
+
+```bash
+export GTM_SWARM_SERVER="https://<your-11agents-platform>"
+export GTM_SWARM_TOKEN="<workspace-swarm-token>"
+export GTM_SWARM_WORKSPACE="flatkey"
+export GTM_SWARM_AGENT="x-growth-agent"
+export GTM_SWARM_NODE="mac-mini-01"
+
+gtm-swarm validate examples/x-agent-batch.json
+gtm-swarm push batch examples/x-agent-batch.json
+```
+
+## Publish
+
+First public release should go out on the beta dist-tag:
+
+```bash
+npm login
+npm test
+npm pack --dry-run --json
+npm publish --tag beta
+```

package/bin/11agents.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from '../src/args.js'
+import { runNode } from '../src/commands/node.js'
+import { pushArtifact, pushBatch, pushObservation } from '../src/commands/push.js'
+import { registerRuntime, scanRuntime, startRuntimeDaemon } from '../src/commands/runtime.js'
+import { startBackgroundDaemon, statusBackgroundDaemon, stopBackgroundDaemon } from '../src/daemon-process.js'
+import { getControlConfig } from '../src/client.js'
+import { printStartupInfo } from '../src/info.js'
+import { validateTelemetryBatch } from '../src/schema.js'
+
+function usage() {
+  console.log(`11agents CLI
+
+Usage:
+  11agents help
+  11agents runtime scan
+  11agents runtime register [--server <url>] [--token <token>] [--machine <key>]
+  11agents daemon start [--server <url>] [--token <token>] [--machine <key>] [--task-interval <seconds>] [--background]
+  11agents daemon status
+  11agents daemon stop
+  11agents daemon start --handler ./worker.js  # optional custom worker override
+  11agents validate <file>
+  11agents push batch <file>
+  11agents push artifact --workspace <slug> --agent <key> --platform x --type post --external-id <id>
+  11agents push observation --workspace <slug> --agent <key> --platform x --type post --external-id <id> --metric views=123
+  11agents node run --workspace <slug> --agent <key> --node <node-id> --handler ./collect-x.js [--once]
+
+Environment:
+  ELEVENAGENTS_SERVER  default https://app.11agents.ai
+  GTM_SWARM_SERVER     compatibility fallback for server URL
+  GTM_WRITES_TOKEN     control-plane token for runtime registration
+  ELEVENAGENTS_MACHINE stable machine key, defaults to hostname
+  GTM_SWARM_TOKEN      project swarm token for push/node commands`)
+}
+
+async function main() {
+  const argv = process.argv.slice(2)
+  const { positional, flags } = parseArgs(argv)
+  const [command, subcommand, target] = positional
+
+  if (!command || command === 'help') {
+    usage()
+    return
+  }
+
+  await printStartupInfo({
+    server: getControlConfig({ server: flags.server }).server,
+    quiet: Boolean(flags.quiet),
+  })
+
+  if (command === 'runtime' && subcommand === 'scan') {
+    await scanRuntime(flags)
+    return
+  }
+
+  if (command === 'runtime' && subcommand === 'register') {
+    await registerRuntime(flags)
+    return
+  }
+
+  if (command === 'daemon' && subcommand === 'start') {
+    if (flags.background) {
+      const result = await startBackgroundDaemon({
+        argv,
+        scriptPath: fileURLToPath(import.meta.url),
+      })
+      if (result.alreadyRunning) {
+        console.log(`11agents daemon already running with pid ${result.pid}`)
+      } else {
+        console.log(`11agents daemon started with pid ${result.pid}`)
+      }
+      console.log(`log: ${result.logPath}`)
+      return
+    }
+    await startRuntimeDaemon(flags)
+    return
+  }
+
+  if (command === 'daemon' && subcommand === 'status') {
+    const status = await statusBackgroundDaemon()
+    if (status.running) console.log(`11agents daemon running with pid ${status.pid}`)
+    else if (status.stale) console.log(`11agents daemon not running; stale pid ${status.pid}`)
+    else console.log('11agents daemon not running')
+    console.log(`log: ${status.logPath}`)
+    return
+  }
+
+  if (command === 'daemon' && subcommand === 'stop') {
+    const result = await stopBackgroundDaemon()
+    if (result.stopped) console.log(`11agents daemon stopped pid ${result.pid}`)
+    else console.log('11agents daemon not running')
+    return
+  }
+
+  if (command === 'validate') {
+    const file = subcommand
+    if (!file) throw new Error('validate requires a file')
+    const json = JSON.parse(await readFile(file, 'utf-8'))
+    const result = validateTelemetryBatch(json)
+    if (!result.ok) throw new Error(result.error)
+    console.log('valid')
+    return
+  }
+
+  if (command === 'push' && subcommand === 'batch') {
+    if (!target) throw new Error('push batch requires a file')
+    await pushBatch(target)
+    return
+  }
+
+  if (command === 'push' && subcommand === 'artifact') {
+    await pushArtifact(flags)
+    return
+  }
+
+  if (command === 'push' && subcommand === 'observation') {
+    await pushObservation(flags)
+    return
+  }
+
+  if (command === 'node' && subcommand === 'run') {
+    await runNode(flags)
+    return
+  }
+
+  usage()
+  process.exitCode = 1
+}
+
+main().catch(error => {
+  console.error(error instanceof Error ? error.message : String(error))
+  process.exitCode = 1
+})

package/bin/gtm-swarm.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises'
+import { parseArgs } from '../src/args.js'
+import { pushArtifact, pushBatch, pushObservation } from '../src/commands/push.js'
+import { runNode } from '../src/commands/node.js'
+import { validateTelemetryBatch } from '../src/schema.js'
+
+function usage() {
+  console.log(`GTM Swarm CLI
+
+Usage:
+  gtm-swarm help
+  gtm-swarm validate <file>
+  gtm-swarm push batch <file>
+  gtm-swarm push artifact --workspace <slug> --agent <key> --platform x --type post --external-id <id> [--url <url>] [--body <text>]
+  gtm-swarm push observation --workspace <slug> --agent <key> --platform x --type post --external-id <id> --metric views=123 --metric replies=4
+  gtm-swarm node run --workspace <slug> --agent <key> --node <node-id> --handler ./collect-x.js [--once]
+
+Environment:
+  GTM_SWARM_SERVER     default https://app.11agents.ai
+  GTM_SWARM_TOKEN      bearer token
+  GTM_SWARM_WORKSPACE  default workspace
+  GTM_SWARM_AGENT      default agent key
+  GTM_SWARM_NODE       default node id`)
+}
+
+async function main() {
+  const { positional, flags } = parseArgs(process.argv.slice(2))
+  const [command, subcommand, target] = positional
+
+  if (!command || command === 'help') {
+    usage()
+    return
+  }
+
+  if (command === 'validate') {
+    const file = subcommand
+    if (!file) throw new Error('validate requires a file')
+    const json = JSON.parse(await readFile(file, 'utf-8'))
+    const result = validateTelemetryBatch(json)
+    if (!result.ok) throw new Error(result.error)
+    console.log('valid')
+    return
+  }
+
+  if (command === 'push' && subcommand === 'batch') {
+    if (!target) throw new Error('push batch requires a file')
+    await pushBatch(target)
+    return
+  }
+
+  if (command === 'push' && subcommand === 'artifact') {
+    await pushArtifact(flags)
+    return
+  }
+
+  if (command === 'push' && subcommand === 'observation') {
+    await pushObservation(flags)
+    return
+  }
+
+  if (command === 'node' && subcommand === 'run') {
+    await runNode(flags)
+    return
+  }
+
+  usage()
+  process.exitCode = 1
+}
+
+main().catch(error => {
+  console.error(error instanceof Error ? error.message : String(error))
+  process.exitCode = 1
+})

package/examples/voc-mcp-tool-call-batch.json

@@ -0,0 +1,45 @@
+{
+  "schema_version": "swarm.telemetry.v1",
+  "workspace": "voc-ai",
+  "agent_key": "voc-amazon-reviews-mcp",
+  "node_id": "vercel-prod",
+  "sent_at": "2026-05-25T10:00:02Z",
+  "artifacts": [
+    {
+      "platform": "mcp",
+      "artifact_type": "mcp_tool_call",
+      "external_id": "1766656800000-client_abc123-fetch_reviews-a8f21c",
+      "title": "fetch_reviews ok",
+      "created_at": "2026-05-25T10:00:00Z",
+      "payload": {
+        "service_name": "voc-amazon-reviews-mcp",
+        "metric_name": "mcp_tool_calls_total",
+        "tool": "fetch_reviews",
+        "status": "ok",
+        "client": "claude-code",
+        "error_type": "",
+        "source_catalog": "amazon-us",
+        "client_instance_id": "client_abc123",
+        "business_success": true,
+        "route": "POST /mcp",
+        "http_status": 200
+      }
+    }
+  ],
+  "observations": [
+    {
+      "platform": "mcp",
+      "artifact_type": "mcp_tool_call",
+      "external_id": "1766656800000-client_abc123-fetch_reviews-a8f21c",
+      "observed_at": "2026-05-25T10:00:02Z",
+      "metrics": {
+        "calls": 1,
+        "latency_ms": 842,
+        "business_success": 1,
+        "http_2xx": 1,
+        "http_4xx": 0,
+        "http_5xx": 0
+      }
+    }
+  ]
+}

package/examples/x-agent-batch.json

@@ -0,0 +1,54 @@
+{
+  "schema_version": "swarm.telemetry.v1",
+  "workspace": "flatkey",
+  "agent_key": "x-growth-agent",
+  "node_id": "mac-mini-01",
+  "sent_at": "2026-05-25T09:30:00Z",
+  "artifacts": [
+    {
+      "platform": "x",
+      "artifact_type": "post",
+      "external_id": "1794312345678900000",
+      "url": "https://x.com/acme/status/1794312345678900000",
+      "body": "We shipped a new API key flow today.",
+      "created_at": "2026-05-25T08:10:00Z",
+      "payload": {
+        "account": "@acme"
+      }
+    },
+    {
+      "platform": "x",
+      "artifact_type": "reply",
+      "external_id": "1794312345678900001",
+      "url": "https://x.com/acme/status/1794312345678900001",
+      "body": "Thanks for the feedback. We added this to the roadmap.",
+      "created_at": "2026-05-25T08:12:00Z",
+      "payload": {
+        "account": "@acme",
+        "reply_to_external_id": "1794300000000000000"
+      }
+    }
+  ],
+  "observations": [
+    {
+      "platform": "x",
+      "artifact_type": "post",
+      "external_id": "1794312345678900000",
+      "observed_at": "2026-05-25T09:25:00Z",
+      "metrics": {
+        "views": 1834,
+        "replies": 12
+      }
+    },
+    {
+      "platform": "x",
+      "artifact_type": "reply",
+      "external_id": "1794312345678900001",
+      "observed_at": "2026-05-25T09:25:00Z",
+      "metrics": {
+        "views": 321,
+        "replies": 1
+      }
+    }
+  ]
+}

package/examples/x-observation-job-result.json

@@ -0,0 +1,24 @@
+{
+  "status": "completed",
+  "summary": "Collected 1 X post observation.",
+  "batch": {
+    "schema_version": "swarm.telemetry.v1",
+    "workspace": "flatkey",
+    "agent_key": "x-growth-agent",
+    "node_id": "mac-mini-01",
+    "sent_at": "2026-05-25T09:34:00Z",
+    "artifacts": [],
+    "observations": [
+      {
+        "platform": "x",
+        "artifact_type": "post",
+        "external_id": "1794312345678900000",
+        "observed_at": "2026-05-25T09:33:30Z",
+        "metrics": {
+          "views": 1901,
+          "replies": 13
+        }
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@11agents/cli",
+  "version": "0.1.1",
+  "description": "11agents local runtime and telemetry CLI",
+  "type": "module",
+  "bin": {
+    "11agents": "bin/11agents.js",
+    "gtm-swarm": "bin/gtm-swarm.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "!src/**/*.test.js",
+    "examples/",
+    "specs/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test src/*.test.js src/commands/*.test.js"
+  },
+  "engines": {
+    "node": "22.x"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/11Agents/11agents-ai.git",
+    "directory": "gtm-swarm-cli"
+  },
+  "homepage": "https://11agents.ai",
+  "bugs": {
+    "url": "https://github.com/11Agents/11agents-ai/issues"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/specs/agent-json-contract.md

@@ -0,0 +1,77 @@
+# Agent JSON Contract
+
+This is the short document an AI agent should read before pushing data to GTM Swarm.
+
+## Rules
+
+- Use `schema_version: "swarm.telemetry.v1"`.
+- Use ISO 8601 timestamps with timezone, preferably UTC `Z`.
+- `workspace` is the GTM workspace slug.
+- `agent_key` is a stable machine-readable agent name.
+- `node_id` is a stable machine name.
+- `platform` and `artifact_type` are lowercase.
+- `external_id` is required and should match the source platform ID.
+- Metric values must be numbers. Put raw strings and nested metadata in `payload`.
+
+## Batch
+
+```json
+{
+  "schema_version": "swarm.telemetry.v1",
+  "workspace": "flatkey",
+  "agent_key": "x-growth-agent",
+  "node_id": "mac-mini-01",
+  "sent_at": "2026-05-25T09:30:00Z",
+  "artifacts": [],
+  "observations": []
+}
+```
+
+## Artifact
+
+Use an artifact when the agent created or discovered a durable object.
+
+```json
+{
+  "platform": "x",
+  "artifact_type": "post",
+  "external_id": "1794312345678900000",
+  "url": "https://x.com/acme/status/1794312345678900000",
+  "body": "We shipped a new API key flow today.",
+  "created_at": "2026-05-25T08:10:00Z",
+  "payload": {
+    "account": "@acme"
+  }
+}
+```
+
+## Observation
+
+Use an observation when the agent collects current metrics for an artifact.
+
+```json
+{
+  "platform": "x",
+  "artifact_type": "post",
+  "external_id": "1794312345678900000",
+  "observed_at": "2026-05-25T09:25:00Z",
+  "metrics": {
+    "views": 1834,
+    "replies": 12
+  }
+}
+```
+
+## Push
+
+```bash
+export GTM_SWARM_SERVER="https://gtm.shulex.com"
+export GTM_SWARM_TOKEN="..."
+
+gtm-swarm push batch ./result.json
+```
+
+For examples, see:
+
+- `examples/x-agent-batch.json`
+- `examples/x-observation-job-result.json`

package/src/args.js

@@ -0,0 +1,43 @@
+export function parseArgs(argv) {
+  const positional = []
+  const flags = {}
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (!arg.startsWith('--')) {
+      positional.push(arg)
+      continue
+    }
+    const key = arg.slice(2)
+    const next = argv[i + 1]
+    if (!next || next.startsWith('--')) {
+      flags[key] = true
+      continue
+    }
+    if (flags[key] === undefined) flags[key] = next
+    else if (Array.isArray(flags[key])) flags[key].push(next)
+    else flags[key] = [flags[key], next]
+    i += 1
+  }
+  return { positional, flags }
+}
+
+export function flag(flags, name, fallback = '') {
+  return flags[name] ?? fallback
+}
+
+export function listFlag(flags, name) {
+  const value = flags[name]
+  if (value === undefined) return []
+  return Array.isArray(value) ? value : [value]
+}
+
+export function parseMetricFlags(values) {
+  const metrics = {}
+  for (const item of values) {
+    const [key, raw] = String(item).split('=')
+    const value = Number(raw)
+    if (!key || !Number.isFinite(value)) throw new Error(`invalid metric: ${item}`)
+    metrics[key] = value
+  }
+  return metrics
+}

package/src/client.js

@@ -0,0 +1,42 @@
+export const DEFAULT_SERVER = 'https://app.11agents.ai'
+
+export function getConfig(overrides = {}) {
+  const env = overrides.env || process.env
+  return {
+    server: overrides.server || env.ELEVENAGENTS_SERVER || env['11AGENTS_SERVER'] || env.GTM_SWARM_SERVER || DEFAULT_SERVER,
+    token: overrides.token || env.GTM_SWARM_TOKEN || '',
+  }
+}
+
+export function getControlConfig(overrides = {}) {
+  const env = overrides.env || process.env
+  return {
+    server: overrides.server || env.ELEVENAGENTS_SERVER || env['11AGENTS_SERVER'] || env.GTM_SWARM_SERVER || DEFAULT_SERVER,
+    token: overrides.token || env.GTM_WRITES_TOKEN || '',
+  }
+}
+
+export async function requestJson(path, { method = 'GET', body = null, config = getConfig() } = {}) {
+  const headers = { 'content-type': 'application/json' }
+  if (config.token) headers.authorization = `Bearer ${config.token}`
+  const response = await fetch(`${config.server.replace(/\/$/, '')}${path}`, {
+    method,
+    headers,
+    body: body ? JSON.stringify(body) : undefined,
+  })
+  const data = await response.json().catch(() => ({}))
+  if (!response.ok) {
+    const error = new Error(data.error || `HTTP ${response.status}`)
+    error.status = response.status
+    throw error
+  }
+  return data
+}
+
+export function encodeQuery(params) {
+  const q = new URLSearchParams()
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined && value !== null && value !== '') q.set(key, String(value))
+  }
+  return q.toString()
+}

package/src/commands/node.js

@@ -0,0 +1,54 @@
+import { pathToFileURL } from 'node:url'
+import { flag } from '../args.js'
+import { encodeQuery, requestJson } from '../client.js'
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+export async function runNode(flags) {
+  const workspace = flag(flags, 'workspace', process.env.GTM_SWARM_WORKSPACE || '')
+  const agent_key = flag(flags, 'agent', process.env.GTM_SWARM_AGENT || '')
+  const node_id = flag(flags, 'node', process.env.GTM_SWARM_NODE || 'local')
+  const handlerPath = flag(flags, 'handler')
+  const once = Boolean(flags.once)
+  const intervalMs = Number(flag(flags, 'interval-ms', '5000'))
+
+  if (!workspace) throw new Error('--workspace or GTM_SWARM_WORKSPACE required')
+  if (!agent_key) throw new Error('--agent or GTM_SWARM_AGENT required')
+  if (!handlerPath) throw new Error('--handler required')
+
+  const handlerModule = await import(pathToFileURL(handlerPath).href)
+  if (typeof handlerModule.handleJob !== 'function') throw new Error('handler must export async function handleJob(job)')
+
+  while (true) {
+    const qs = encodeQuery({ workspace, agent_key, node_id })
+    const lease = await requestJson(`/api/swarm/jobs/lease?${qs}`)
+    if (!lease.job) {
+      if (once) {
+        console.log(JSON.stringify({ job: null }, null, 2))
+        return
+      }
+      await sleep(intervalMs)
+      continue
+    }
+
+    console.log(JSON.stringify({ leased: lease.job.id, kind: lease.job.kind }, null, 2))
+    let completion
+    try {
+      completion = await handlerModule.handleJob(lease.job)
+    } catch (error) {
+      completion = {
+        status: 'failed',
+        summary: error instanceof Error ? error.message : String(error),
+        error: 'handler_error',
+      }
+    }
+    const result = await requestJson(`/api/swarm/jobs/${lease.job.id}/complete`, {
+      method: 'POST',
+      body: completion,
+    })
+    console.log(JSON.stringify(result, null, 2))
+    if (once) return
+  }
+}