@tpsdev-ai/cli 0.2.0 → 0.3.1

package/README.md

@@ -0,0 +1,65 @@
+# @tpsdev-ai/cli
+
+> TPS (Team Provisioning System) — an Agent OS CLI for managing isolated AI agents.
+
+Hire agents, provision secure branch offices, manage identity and encrypted comms, track operational health — all from the command line.
+
+## Install
+
+```bash
+npm install -g @tpsdev-ai/cli
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `tps hire <report>` | Onboard a new agent from a TPS report |
+| `tps roster` | List all agents and their status |
+| `tps bootstrap <agent>` | Run first-boot health checks and workspace scaffolding |
+| `tps office setup` | Configure sandbox environment from workspace manifest |
+| `tps backup <agent>` | Create encrypted, checksummed workspace backup |
+| `tps restore <agent> <archive>` | Restore agent workspace with transactional rollback |
+| `tps status` | Operational dashboard — health, uptime, cost tracking |
+| `tps heartbeat <agent>` | Agent self-reports health (workspace, gateway, provider) |
+| `tps identity init` | Generate Ed25519 host keypair |
+| `tps branch init` | Initialize a remote branch office |
+| `tps office join` | Join a branch to the head office via Noise_IK handshake |
+| `tps office connect` | Establish persistent encrypted relay channel |
+| `tps mail send` | Send async mail to a branch agent |
+| `tps mail check` | Check for incoming mail |
+| `tps secrets set/get` | Encrypted vault for API keys and credentials |
+
+## Architecture
+
+TPS treats AI agents like employees in an organization:
+
+- **Branch Offices** — isolated sandboxes (Docker, VMs, or `nono` process isolation)
+- **The Mailroom** — async, persistent, cross-boundary messaging via Maildir
+- **Wire Security** — Noise_IK protocol over WebSocket for E2E encrypted transport
+- **Identity** — Ed25519 keypairs with signed join tokens
+
+Agents communicate through three channels:
+1. **Mail** for messages (tasks, status, coordination)
+2. **Git** for artifacts (code, reports, generated files)
+3. **APIs** for external data
+
+## Security
+
+- All inter-office traffic is E2E encrypted (Noise_IK + MessagePack)
+- Sandbox profiles enforce filesystem, network, and exec boundaries
+- Encrypted secrets vault (Argon2id key derivation)
+- Audit trail with append-only logging and search
+- Path traversal protection on all user-supplied identifiers
+
+See [SECURITY.md](https://github.com/tpsdev-ai/cli/blob/main/SECURITY.md) for responsible disclosure.
+
+## Links
+
+- [GitHub](https://github.com/tpsdev-ai/cli)
+- [Runtime Library](https://www.npmjs.com/package/@tpsdev-ai/agent)
+- [Contributing](https://github.com/tpsdev-ai/cli/blob/main/CONTRIBUTING.md)
+
+## License
+
+Apache-2.0

package/bin/tps.cjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+
+const { execFileSync } = require('child_process');
+
+const platform = process.platform;
+const arch = process.arch;
+const pkg = `@tpsdev-ai/cli-${platform}-${arch}`;
+
+function runBinary() {
+  try {
+    const path = require('path');
+    const pkgJson = require.resolve(`${pkg}/package.json`);
+    const binPath = path.join(path.dirname(pkgJson), 'tps');
+    execFileSync(binPath, process.argv.slice(2), { stdio: 'inherit' });
+    return;
+  } catch (err) {
+    console.error(`TPS: no binary package available for ${platform}-${arch}.`);
+    console.error(`Run npm install -g ${pkg} to install the platform binary package.`);
+    console.error('Or run from source inside the repository via `bun run tps` in packages/cli.');
+    process.exitCode = 1;
+  }
+}
+
+runBinary();

package/bin/tps.ts

@@ -0,0 +1,435 @@
+#!/usr/bin/env node
+import meow from "meow";
+
+const cli = meow(
+  `
+  Usage
+    $ tps <command> [options]
+
+  Commands
+    hire <report>     Onboard a new agent from a .tps report or persona
+    roster <action>   Agent directory (list/show/find)
+    review <name>     Performance review for a specific agent
+    office <action>   Branch office sandbox lifecycle (start/stop/list/status/kill)
+    bootstrap <agent-id>  Bring a hired agent to operational state
+    backup <agent-id> [--schedule daily|off] [--keep n] [--sanitize]  Backup agent workspace
+    restore <agent-id> <archive> [--clone] [--overwrite] [--from <archive>] Restore agent workspace from a backup
+    status [agent-id] [--auto-prune] [--prune] [--json] [--cost] [--shared]
+    heartbeat <agent-id> [--nonono] Send a heartbeat/ping for an agent
+    context <action>  Workstream context memory (read/update/list)
+    mail <action>     Mailroom operations (send/check/list/search)
+    identity <action> Key management (init/show/register/list/revoke/verify)
+    secrets <action>  Secret management (set/list/remove)
+    git <action>      Git utilities (worktree)
+    branch <action>   Branch office node (init/start/stop/status/log)
+
+  Options
+    --help            Show this help text
+    --version         Show version number
+    --config <path>   Path to openclaw.json (default: auto-discover)
+
+  Examples
+    $ tps hire developer --name Fred
+    $ tps hire ./reports/strategy-lead.tps --dry-run
+    $ tps hire developer --name Scout --runtime claude-code
+    $ tps hire ops --name Monitor --runtime ollama --base-model llama3.1:8b
+    $ tps hire developer --name Coder --runtime codex
+    $ tps roster list
+    $ tps roster show flint --json
+    $ tps roster find --channel discord
+    $ tps roster list --config ~/custom/openclaw.json
+    $ tps mail send kern "hi"
+    $ tps mail check kern
+    $ tps mail log --limit 10
+    $ tps mail log flint --since 2026-02-20
+    $ tps office start branch-a
+    $ tps office status branch-a
+    $ tps bootstrap flint
+    $ tps backup flint --schedule daily
+    $ tps restore flint ~/.tps/backups/flint/old.tps-backup.tar.gz
+    $ tps status
+    $ tps status flint --cost
+    $ tps heartbeat flint
+    $ tps review flint
+
+  Built-in personas: developer, designer, support, ea, ops, strategy, security
+
+  If you could just go ahead and use the correct command, that'd be great.
+`,
+  {
+    importMeta: import.meta,
+    flags: {
+      reason: { type: "string" },
+      expiresIn: { type: "string" },
+      trust: { type: "string" },
+      pubkey: { type: "string" },
+      encPubkey: { type: "string" },
+      name: { type: "string" },
+      workspace: { type: "string" },
+      dryRun: { type: "boolean", default: false },
+      json: { type: "boolean", default: false },
+      config: { type: "string" },
+      deep: { type: "boolean", default: false },
+      summary: { type: "string" },
+      channel: { type: "string" },
+      branch: { type: "boolean", default: false },
+      manifest: { type: "string" },
+      soundstage: { type: "boolean", default: false },
+      nonono: { type: "boolean", default: false },
+      inject: { type: "boolean", default: true },
+      runtime: { type: "string", default: "openclaw" },
+      baseModel: { type: "string" },
+      since: { type: "string" },
+      limit: { type: "number" },
+      from: { type: "string" },
+      clone: { type: "boolean", default: false },
+      overwrite: { type: "boolean", default: false },
+      schedule: { type: "string" },
+      keep: { type: "number" },
+      sanitize: { type: "boolean", default: true },
+      listen: { type: "number" },
+      host: { type: "string" },
+      force: { type: "boolean", default: false },
+      follow: { type: "boolean", default: false },
+      lines: { type: "number" },
+      transport: { type: "string" },
+      autoPrune: { type: "boolean", default: false },
+      prune: { type: "boolean", default: false },
+      staleMinutes: { type: "number" },
+      offlineHours: { type: "number" },
+      shared: { type: "boolean", default: false },
+      cost: { type: "boolean", default: false },
+      statusOverride: { type: "string" },
+    },
+  }
+);
+
+const [command, ...rest] = cli.input;
+
+// nono availability check (skip for --no-nono or office/mail relay commands)
+async function checkNono() {
+  if (cli.flags.nonono) return;
+  if (command === "office" && rest[0] === "relay") return; // relay runs in background
+  const { findNono } = await import("../src/utils/nono.js");
+  if (!findNono()) {
+    console.warn(
+      "⚠️  nono not found. Host agents will run without process isolation.\n" +
+      "   Install nono for syscall filtering + filesystem boundaries.\n" +
+      "   Use --nonono to run anyway (not recommended).\n"
+    );
+  }
+}
+
+async function main() {
+  await checkNono();
+  switch (command) {
+    case "hire": {
+      const reportPath = rest[0];
+      if (!reportPath) {
+        console.error(
+          "I'm gonna need you to specify a TPS report file or persona.\n\n  tps hire <report.tps | persona> [--name Name]\n\nBuilt-in personas: developer, designer, support, ea, ops, strategy"
+        );
+        process.exit(1);
+      }
+      const { runHire } = await import("../src/cli/hire.js");
+      runHire({
+        reportPath,
+        name: cli.flags.name,
+        workspace: cli.flags.workspace,
+        dryRun: cli.flags.dryRun,
+        jsonOutput: cli.flags.json,
+        configPath: cli.flags.config,
+        branch: cli.flags.branch,
+        inject: cli.flags.inject,
+        runtime: cli.flags.runtime as any,
+        baseModel: cli.flags.baseModel,
+      });
+      break;
+    }
+    case "roster": {
+      // Backward-compatible path (keeps nono re-exec behavior used by existing tests):
+      // `tps roster` with no subcommand routes to the legacy CLI implementation.
+      if (!rest[0]) {
+        const { runRoster } = await import("../src/cli/roster.js");
+        runRoster({ configPath: cli.flags.config });
+        break;
+      }
+
+      const action = rest[0] as "list" | "show" | "find";
+      if (!["list", "show", "find"].includes(action)) {
+        console.error(
+          "Usage:\n  tps roster\n  tps roster list\n  tps roster show <agent> [--json]\n  tps roster find --channel <channel> [--json]"
+        );
+        process.exit(1);
+      }
+      const { runRoster } = await import("../src/commands/roster.js");
+      runRoster({
+        action,
+        agent: rest[1],
+        channel: cli.flags.channel || undefined,
+        json: cli.flags.json,
+        configPath: cli.flags.config,
+      });
+      break;
+    }
+    case "review": {
+      const agentName = rest[0];
+      if (!agentName) {
+        console.error(
+          "Review who? I'm gonna need a name.\n\n  tps review <agent-name>"
+        );
+        process.exit(1);
+      }
+      const { runReview } = await import("../src/cli/review.js");
+      runReview({ agentName, configPath: cli.flags.config, deep: cli.flags.deep });
+      break;
+    }
+    case "bootstrap": {
+      const agentId = rest[0];
+      if (!agentId) {
+        console.error("Usage: tps bootstrap <agent-id>");
+        process.exit(1);
+      }
+
+      const { runBootstrap } = await import("../src/commands/bootstrap.js");
+      await runBootstrap({
+        agentId,
+        configPath: cli.flags.config,
+        channel: cli.flags.channel,
+      });
+      break;
+    }
+
+    case "office": {
+      const action = rest[0] as "start" | "stop" | "list" | "status" | "relay" | "exec" | "join" | "revoke" | "sync" | "connect" | "kill" | "setup" | undefined;
+      const validActions = ["start", "stop", "list", "status", "relay", "exec", "join", "revoke", "sync", "connect", "kill", "setup"];
+      // Backward compatibility: `tps office <agent>` maps to `start <agent>`.
+      const isLegacy = action && !validActions.includes(action);
+      if ((!action && !isLegacy) || (!isLegacy && !validActions.includes(action!))) {
+        console.error(
+          "Usage:\n  tps office start <agent>\n  tps office stop <agent>\n  tps office list\n  tps office status [agent]\n  tps office exec <agent> -- <command...>\n  tps office join <name> <join-token>\n  tps office revoke <name>\n  tps office sync <name>\n  tps office connect <name>\n  tps office setup <agent> [--dry-run]\n  tps office kill"
+        );
+        process.exit(1);
+      }
+
+      const { runOffice } = await import("../src/commands/office.js");
+      if (isLegacy) {
+        await runOffice({ action: "start", agent: rest[0] });
+      } else if (action === "exec") {
+        // Everything after "--" is the command
+        const dashIdx = process.argv.indexOf("--");
+        const execCmd = dashIdx >= 0 ? process.argv.slice(dashIdx + 1) : rest.slice(2);
+        await runOffice({ action: "exec", agent: rest[1], command: execCmd });
+      } else if (action === "join") {
+        const joinToken = rest[2];
+        if (!rest[1] || !joinToken) {
+          console.error("Usage: tps office join <name> <join-token-url>");
+          process.exit(1);
+        }
+        await runOffice({ action: "join", agent: rest[1], joinToken });
+      } else if (action === "revoke") {
+        if (!rest[1]) {
+          console.error("Usage: tps office revoke <name>");
+          process.exit(1);
+        }
+        await runOffice({ action: "revoke", agent: rest[1] });
+      } else if (action === "setup") {
+        const dryRun = process.argv.includes("--dry-run") || process.argv.includes("--dry");
+        await runOffice({ action: "setup", agent: rest[1], dryRun });
+      } else {
+        const soundstageIdx = process.argv.indexOf("--soundstage");
+        const isSoundstage = soundstageIdx >= 0 || cli.flags.soundstage;
+        if (soundstageIdx >= 0) process.argv.splice(soundstageIdx, 1);
+
+        await runOffice({ action: action!, agent: rest[1], manifest: cli.flags.manifest, soundstage: isSoundstage });
+      }
+      break;
+    }
+    case "context": {
+      const action = rest[0] as "read" | "update" | "list" | undefined;
+      const workstream = rest[1];
+      if (!action || !["read", "update", "list"].includes(action)) {
+        console.error(
+          "Usage:\n  tps context read <workstream>\n  tps context update <workstream> --summary \"...\"\n  tps context list"
+        );
+        process.exit(1);
+      }
+      const { runContext } = await import("../src/commands/context.js");
+      runContext({
+        action,
+        workstream,
+        summary: cli.flags.summary,
+        json: cli.flags.json,
+      });
+      break;
+    }
+    case "mail": {
+      const action = rest[0] as "send" | "check" | "list" | "log" | "read" | "watch" | "search" | undefined;
+      if (cli.flags.help || !action || !["send", "check", "list", "log", "read", "watch", "search"].includes(action)) {
+        console.log(
+          "Usage:\n  tps mail send <agent> <message>   Send mail to a local or remote agent\n  tps mail check [agent]             Read new messages (marks as read)\n  tps mail watch [agent]             Watch inbox for new messages\n  tps mail list [agent]              List all messages (read + unread)\n  tps mail read <agent> <id>         Show a specific message by ID (prefix ok)\n  tps mail search <query>            Search mail history using full-text search\n  tps mail log [agent]               Show audit log [--since YYYY-MM-DD] [--limit N]"
+        );
+        process.exit(cli.flags.help ? 0 : 1);
+      }
+      const { runMail } = await import("../src/commands/mail.js");
+      await runMail({
+        action,
+        agent: rest[1],
+        message: action === "send" ? rest.slice(2).join(" ") : undefined,
+        messageId: action === "read" ? rest[2] : undefined,
+        json: cli.flags.json,
+        since: cli.flags.since,
+        limit: cli.flags.limit ? Number(cli.flags.limit) : undefined,
+      });
+      break;
+    }
+    case "identity": {
+      const action = rest[0] as "init" | "show" | "register" | "list" | "revoke" | "verify" | undefined;
+      if (!action || !["init", "show", "register", "list", "revoke", "verify"].includes(action)) {
+        console.error(
+          "Usage:\n  tps identity init [--expires-in 90d]\n  tps identity show\n  tps identity register <branch> [--expires-in 90d] [--trust standard]\n  tps identity list\n  tps identity revoke <branch> --reason \"...\"\n  tps identity verify <branch>"
+        );
+        process.exit(1);
+      }
+      const { runIdentity } = await import("../src/commands/identity.js");
+      await runIdentity({
+        action,
+        branch: rest[1],
+        reason: cli.flags.reason,
+        json: cli.flags.json,
+        expiresIn: cli.flags.expiresIn,
+        trust: cli.flags.trust as any,
+        pubkey: cli.flags.pubkey,
+        encPubkey: cli.flags.encPubkey,
+      });
+      break;
+    }
+    case "secrets": {
+      const action = rest[0] as "set" | "list" | "remove" | undefined;
+      if (!action || !["set", "list", "remove"].includes(action)) {
+        console.error("Usage:\n  tps secrets set <KEY>=<VALUE>\n  tps secrets list\n  tps secrets remove <KEY>");
+        process.exit(1);
+      }
+      const { runSecrets } = await import("../src/commands/secrets.js");
+      let key: string | undefined;
+      let value: string | undefined;
+      if (action === "set") {
+        const parts = rest[1]?.split("=");
+        key = parts?.[0];
+        value = parts?.slice(1).join("=");
+      } else {
+        key = rest[1];
+      }
+      await runSecrets({ action, key, value, json: cli.flags.json });
+      break;
+    }
+    case "backup": {
+      const agentId = rest[0];
+      if (!agentId) {
+        console.error("Usage: tps backup <agent-id> [--schedule daily|off] [--keep n]");
+        process.exit(1);
+      }
+      const { runBackup } = await import("../src/commands/backup.js");
+      await runBackup({
+        agentId,
+        keep: typeof cli.flags.keep === "number" ? Number(cli.flags.keep) : undefined,
+        schedule: cli.flags.schedule,
+        sanitize: cli.flags.sanitize,
+        configPath: cli.flags.config,
+      });
+      break;
+    }
+    case "restore": {
+      const agentId = rest[0];
+      const archivePath = cli.flags.from || rest[1];
+      if (!agentId || !archivePath) {
+        console.error("Usage: tps restore <agent-id> <archive> [--from <archive>] [--clone] [--overwrite] [--force]");
+        process.exit(1);
+      }
+      const { runRestore } = await import("../src/commands/backup.js");
+      await runRestore({
+        agentId,
+        archivePath,
+        force: !!cli.flags.force,
+        overwrite: !!cli.flags.overwrite,
+        clone: !!cli.flags.clone,
+        configPath: cli.flags.config,
+      });
+      break;
+    }
+    case "heartbeat": {
+      const agentId = rest[0];
+      if (!agentId) {
+        console.error("Usage: tps heartbeat <agent-id>");
+        process.exit(1);
+      }
+      const { runHeartbeat } = await import("../src/commands/status.js");
+      await runHeartbeat({
+        agentId,
+        status: (cli.flags.statusOverride as any) || undefined,
+        nonono: !!cli.flags.nonono,
+        profile: "tps-status",
+      });
+      break;
+    }
+    case "status": {
+      const agentId = rest[0];
+      const { runStatus } = await import("../src/commands/status.js");
+      await runStatus({
+        agentId,
+        autoPrune: !!cli.flags.autoPrune,
+        prune: !!cli.flags.prune,
+        json: !!cli.flags.json,
+        staleMinutes: cli.flags.staleMinutes ? Number(cli.flags.staleMinutes) : undefined,
+        offlineHours: cli.flags.offlineHours ? Number(cli.flags.offlineHours) : undefined,
+        cost: !!cli.flags.cost,
+        shared: !!cli.flags.shared,
+      });
+      break;
+    }
+    case "branch": {
+      const action = rest[0] as "init" | "start" | "stop" | "status" | "log" | undefined;
+      const valid = ["init", "start", "stop", "status", "log"];
+      if (!action || !valid.includes(action)) {
+        console.error("Usage:\n  tps branch init [--listen <port>] [--host <hostname>] [--transport ws|tcp]\n  tps branch start\n  tps branch stop\n  tps branch status\n  tps branch log [--lines N] [--follow]");
+        process.exit(1);
+      }
+      const { runBranch } = await import("../src/commands/branch.js");
+      await runBranch({
+        action,
+        port: typeof cli.flags.listen === "number" ? Number(cli.flags.listen) : undefined,
+        host: cli.flags.host,
+        transport: cli.flags.transport === "tcp" ? "tcp" : cli.flags.transport === "ws" ? "ws" : undefined,
+        force: cli.flags.force,
+        lines: typeof cli.flags.lines === "number" ? Number(cli.flags.lines) : undefined,
+        follow: !!cli.flags.follow,
+      });
+      break;
+    }
+    case "git": {
+      const action = rest[0];
+      if (action === "worktree") {
+        const agent = rest[1];
+        const repoPath = rest[2];
+        const branchName = rest[3];
+        if (!agent || !repoPath) {
+          console.error("Usage: tps git worktree <agent> <repo-path> [branch-name]");
+          process.exit(1);
+        }
+        const { runGit } = await import("../src/commands/git.js");
+        await runGit({ action, agent, repoPath, branchName });
+      } else {
+        console.error("Unknown git action. Supported: worktree");
+        process.exit(1);
+      }
+      break;
+    }
+    default:
+      cli.showHelp();
+  }
+}
+
+main().catch((err) => {
+  console.error(err?.message || err);
+  process.exit(1);
+});

package/package.json

@@ -1,13 +1,24 @@
 {
   "name": "@tpsdev-ai/cli",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "TPS Report CLI — because every agent needs the proper paperwork.",
   "type": "module",
   "bin": {
-    "tps": "./dist/bin/tps.js"
+    "tps": "./bin/tps.cjs"
+  },
+  "optionalDependencies": {
+    "@tpsdev-ai/cli-darwin-arm64": "0.3.1",
+    "@tpsdev-ai/cli-darwin-x64": "0.3.1",
+    "@tpsdev-ai/cli-linux-arm64": "0.3.1",
+    "@tpsdev-ai/cli-linux-x64": "0.3.1"
   },
   "scripts": {
     "build": "tsc",
+    "build:binary": "bun run build:binary:darwin-arm64 && bun run build:binary:darwin-x64 && bun run build:binary:linux-arm64 && bun run build:binary:linux-x64",
+    "build:binary:darwin-arm64": "bun build --compile bin/tps.ts --target=bun-darwin-arm64 --outfile=dist/tps-darwin-arm64",
+    "build:binary:darwin-x64": "bun build --compile bin/tps.ts --target=bun-darwin-x64 --outfile=dist/tps-darwin-x64",
+    "build:binary:linux-arm64": "bun build --compile bin/tps.ts --target=bun-linux-arm64 --outfile=dist/tps-linux-arm64",
+    "build:binary:linux-x64": "bun build --compile bin/tps.ts --target=bun-linux-x64 --outfile=dist/tps-linux-x64",
     "dev": "tsc --watch",
     "start": "node dist/bin/tps.js",
     "tps": "node dist/bin/tps.js",
@@ -16,7 +27,12 @@
     "pretest": "tsc",
     "test": "bun test"
   },
-  "keywords": ["cli", "agents", "openclaw", "tps"],
+  "keywords": [
+    "cli",
+    "agents",
+    "openclaw",
+    "tps"
+  ],
   "license": "Apache-2.0",
   "dependencies": {
     "@noble/curves": "^2.0.1",
@@ -42,7 +58,15 @@
     "fast-check": "^4.5.3",
     "typescript": "^5.7.0"
   },
-  "files": ["dist", "nono-profiles", "personas", "reports"],
+  "files": [
+    "bin",
+    "nono-profiles",
+    "personas",
+    "reports",
+    "README.md"
+  ],
   "author": "tpsdev-ai",
-  "publishConfig": { "access": "public" }
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/dist/bin/tps.d.ts

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-export {};
-//# sourceMappingURL=tps.d.ts.map

package/dist/bin/tps.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"tps.d.ts","sourceRoot":"","sources":["../../bin/tps.ts"],"names":[],"mappings":""}