teamshift 0.1.0

package/README.md

@@ -0,0 +1,65 @@
+# teamshift
+
+Run TeamShift agent teams from your terminal. Metered by usage — you do **not**
+bring your own model key, so a run costs you TeamShift credit rather than an
+Anthropic or OpenAI bill.
+
+```bash
+npx teamshift login
+npx teamshift catalog                  # prebuilt teams you can add
+npx teamshift add code-audit-swarm     # adds it to your workspace
+npx teamshift run <team-id> "review services/api for auth mistakes"
+```
+
+`teamshift teams` lists everything callable, including teams you built yourself
+in the portal. `add` is idempotent — running it twice will not duplicate a team
+or overwrite edits you have made to it.
+
+## Parallel fan-out
+
+The reason to reach for the CLI instead of the API: one command dispatches many
+prompts at once and reports what each one cost.
+
+```bash
+npx teamshift run <team-id> \
+  -p "audit auth" -p "map the schema" -p "find dead code" --concurrency 3
+```
+
+```
+STATUS     CHARGE  TIME  PROMPT
+─────────  ──────  ────  ───────────────
+completed  $1.20   4.1s  audit auth
+completed  $1.20   4.0s  map the schema
+completed  $1.20   4.0s  find dead code
+
+3 run(s) · $3.60 total · 8.1s wall clock (12.1s if run one at a time)
+```
+
+`--file prompts.txt` reads one prompt per line. Concurrency is bounded (default
+5) so a large batch does not trip the API's write rate limit.
+
+## Already using Claude Code or Codex?
+
+Prefer the MCP server — it exposes the same teams as tools inside your existing
+agent, with no second CLI to learn. Both install commands are in the portal under
+**Programmatic setup**.
+
+## Auth
+
+`TEAMSHIFT_API_KEY` wins over the stored config, so CI never has to write a file.
+`teamshift login` writes `~/.teamshift/config.json` at mode `0600`.
+`TEAMSHIFT_API_URL` overrides the endpoint.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | every run reached a terminal status |
+| `1` | usage error, auth failure, or at least one run failed to dispatch |
+| `2` | out of credit — add credits and rerun |
+
+## Releasing
+
+This package is `private: true` so a workspace-wide publish cannot push it by
+accident. Releasing is deliberate: set `private: false`, `pnpm build`, then
+`npm publish`.

package/dist/api.js

@@ -0,0 +1,76 @@
+/** A 402 from the API means "out of credit", which is a normal, actionable state. */
+export class PaymentRequiredError extends Error {
+    detail;
+    constructor(detail) {
+        super('payment required');
+        this.detail = detail;
+    }
+}
+export class ApiError extends Error {
+    status;
+    detail;
+    constructor(status, detail) {
+        super(`${status}: ${detail}`);
+        this.status = status;
+        this.detail = detail;
+    }
+}
+export class TeamShiftClient {
+    credentials;
+    constructor(credentials) {
+        this.credentials = credentials;
+    }
+    async request(path, init = {}) {
+        const response = await fetch(`${this.credentials.apiUrl}${path}`, {
+            ...init,
+            headers: {
+                Authorization: `Bearer ${this.credentials.apiKey}`,
+                'Content-Type': 'application/json',
+                ...(init.headers ?? {}),
+            },
+        });
+        if (response.ok)
+            return (await response.json());
+        const detail = await this.readDetail(response);
+        if (response.status === 402)
+            throw new PaymentRequiredError(detail);
+        throw new ApiError(response.status, detail);
+    }
+    async readDetail(response) {
+        try {
+            const body = (await response.json());
+            const detail = body.detail ?? body.reason ?? body.error;
+            return typeof detail === 'string' ? detail : JSON.stringify(body);
+        }
+        catch {
+            return response.statusText || 'request failed';
+        }
+    }
+    async catalog() {
+        return (await this.request('/v1/team-catalog')).teams;
+    }
+    activate(catalogId) {
+        return this.request(`/v1/team-catalog/${catalogId}/activate`, {
+            method: 'POST',
+        });
+    }
+    interop() {
+        return this.request('/v1/interop');
+    }
+    /**
+     * Start a run. The API returns 202 with a run id rather than a result, which
+     * is what makes fan-out cheap: N runs are N dispatches, then one poll loop.
+     */
+    async startRun(kind, id, message) {
+        const path = kind === 'team' ? `/v1/teamshift-teams/${id}/runs` : `/v1/teamshift-agents/${id}/runs`;
+        const accepted = await this.request(path, {
+            method: 'POST',
+            body: JSON.stringify({ message, payload: {} }),
+        });
+        return accepted.workflow_run_id;
+    }
+    async getRun(runId) {
+        const body = await this.request(`/v1/runs/${runId}`);
+        return body.run;
+    }
+}

package/dist/cli.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+import { createInterface } from 'node:readline/promises';
+import { PaymentRequiredError, TeamShiftClient } from './api.js';
+import { DEFAULT_API_URL, loadCredentials, maskKey, saveCredentials } from './config.js';
+import { chargeUsd, duration, money, table } from './format.js';
+import { runBatch } from './run.js';
+const DEFAULT_MARKUP = 3;
+const USAGE = `teamshift — run agent teams from your terminal
+
+  teamshift login                     Store an API key (or set TEAMSHIFT_API_KEY)
+  teamshift whoami                    Show the active key and endpoint
+  teamshift catalog                   Browse prebuilt teams you can add
+  teamshift add <catalog-id>          Add a prebuilt team to your workspace
+  teamshift teams                     List callable teams and agents
+  teamshift run <id> "<prompt>"       Run one team, wait, print status and charge
+  teamshift run <id> -p "a" -p "b"    Fan out prompts in parallel
+  teamshift run <id> --file prompts.txt   One prompt per line, run in parallel
+
+Options
+  --agent               Target an agent id instead of a team id
+  --concurrency <n>     Parallel runs in flight (default 5)
+  --json                Emit machine-readable JSON
+
+Runs are billed on metered usage — you do not bring your own model key.`;
+export function parseArgs(argv) {
+    const parsed = {
+        command: argv[0] ?? 'help',
+        positional: [],
+        prompts: [],
+        agent: false,
+        json: false,
+        concurrency: 5,
+    };
+    for (let index = 1; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === '-p' || token === '--prompt')
+            parsed.prompts.push(argv[++index] ?? '');
+        else if (token === '--file')
+            parsed.file = argv[++index];
+        else if (token === '--concurrency')
+            parsed.concurrency = Number(argv[++index] ?? 5);
+        else if (token === '--agent')
+            parsed.agent = true;
+        else if (token === '--json')
+            parsed.json = true;
+        else
+            parsed.positional.push(token);
+    }
+    return parsed;
+}
+function requireClient() {
+    const credentials = loadCredentials();
+    if (!credentials) {
+        console.error('Not logged in. Run `teamshift login`, or set TEAMSHIFT_API_KEY.');
+        process.exit(1);
+    }
+    return new TeamShiftClient(credentials);
+}
+async function login() {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const apiKey = (await rl.question('TeamShift API key: ')).trim();
+        if (!apiKey) {
+            console.error('No key entered.');
+            process.exit(1);
+        }
+        const apiUrl = (await rl.question(`API URL [${DEFAULT_API_URL}]: `)).trim() || DEFAULT_API_URL;
+        const path = saveCredentials({ apiKey, apiUrl });
+        console.log(`Saved ${maskKey(apiKey)} to ${path}`);
+    }
+    finally {
+        rl.close();
+    }
+}
+async function listCallable(json) {
+    const payload = await requireClient().interop();
+    if (json) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+    }
+    const rows = [
+        ...payload.teams.map((item) => ['team', item.id, item.name]),
+        ...payload.agents.map((item) => ['agent', item.id, item.name]),
+    ];
+    if (rows.length === 0) {
+        console.log('Nothing callable yet — create a team in the portal first.');
+        return;
+    }
+    console.log(table(['KIND', 'ID', 'NAME'], rows));
+}
+async function showCatalog(json) {
+    const teams = await requireClient().catalog();
+    if (json) {
+        console.log(JSON.stringify(teams, null, 2));
+        return;
+    }
+    console.log(table(['ID', 'NAME', 'ADDED', 'BEST FOR'], teams.map((team) => [team.id, team.name, team.activated ? 'yes' : '—', team.best_for])));
+    console.log('\nAdd one with:  teamshift add <id>');
+}
+async function addFromCatalog(args) {
+    const catalogId = args.positional[0];
+    if (!catalogId) {
+        console.error('Usage: teamshift add <catalog-id>   (see `teamshift catalog`)');
+        process.exit(1);
+    }
+    const result = await requireClient().activate(catalogId);
+    if (args.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    // Activation is idempotent server-side; say so rather than implying a new team.
+    console.log(result.created ? `Added ${result.name}.` : `${result.name} was already in your workspace.`);
+    console.log(`\n  ${result.run_command}`);
+}
+async function run(args) {
+    const client = requireClient();
+    const id = args.positional[0];
+    if (!id) {
+        console.error('Usage: teamshift run <id> "<prompt>"');
+        process.exit(1);
+    }
+    const prompts = await collectPrompts(args);
+    if (prompts.length === 0) {
+        console.error('No prompt given. Pass one inline, with -p, or via --file.');
+        process.exit(1);
+    }
+    const kind = args.agent ? 'agent' : 'team';
+    const startedAt = Date.now();
+    if (!args.json) {
+        console.log(`Running ${prompts.length} prompt(s) against ${kind} ${id}…`);
+    }
+    const outcomes = await runBatch(client, kind, id, prompts, {
+        concurrency: args.concurrency,
+        onSettled: (outcome) => {
+            if (args.json)
+                return;
+            const charge = money(chargeUsd(outcome.costUsd, DEFAULT_MARKUP));
+            console.log(`  ${outcome.status.padEnd(16)} ${duration(outcome.elapsedMs).padStart(7)}  ${charge}`);
+        },
+    });
+    if (args.json) {
+        console.log(JSON.stringify({ outcomes }, null, 2));
+        return;
+    }
+    console.log(`\n${table(['STATUS', 'CHARGE', 'TIME', 'PROMPT'], outcomes.map((outcome) => [
+        outcome.status,
+        money(chargeUsd(outcome.costUsd, DEFAULT_MARKUP)),
+        duration(outcome.elapsedMs),
+        outcome.prompt.length > 48 ? `${outcome.prompt.slice(0, 47)}…` : outcome.prompt,
+    ]))}`);
+    const total = outcomes.reduce((sum, outcome) => sum + (chargeUsd(outcome.costUsd, DEFAULT_MARKUP) ?? 0), 0);
+    // Wall-clock vs summed run time is the whole pitch for fan-out, so show both.
+    const serial = outcomes.reduce((sum, outcome) => sum + outcome.elapsedMs, 0);
+    console.log(`\n${outcomes.length} run(s) · ${money(total)} total · ${duration(Date.now() - startedAt)} wall clock ` +
+        `(${duration(serial)} if run one at a time)`);
+    const failed = outcomes.filter((outcome) => outcome.error).length;
+    if (failed > 0) {
+        console.log(`${failed} run(s) failed to dispatch — rerun just those prompts.`);
+        process.exitCode = 1;
+    }
+}
+async function collectPrompts(args) {
+    const prompts = [...args.prompts];
+    if (args.file) {
+        const { readFile } = await import('node:fs/promises');
+        const contents = await readFile(args.file, 'utf8');
+        prompts.push(...contents.split('\n').map((line) => line.trim()).filter(Boolean));
+    }
+    const inline = args.positional.slice(1).join(' ').trim();
+    if (inline)
+        prompts.push(inline);
+    return prompts;
+}
+export async function main(argv = process.argv.slice(2)) {
+    const args = parseArgs(argv);
+    try {
+        switch (args.command) {
+            case 'login':
+                return await login();
+            case 'whoami': {
+                const credentials = loadCredentials();
+                console.log(credentials ? `${maskKey(credentials.apiKey)} → ${credentials.apiUrl}` : 'Not logged in.');
+                return;
+            }
+            case 'catalog':
+                return await showCatalog(args.json);
+            case 'add':
+                return await addFromCatalog(args);
+            case 'teams':
+                return await listCallable(args.json);
+            case 'run':
+                return await run(args);
+            default:
+                console.log(USAGE);
+        }
+    }
+    catch (error) {
+        if (error instanceof PaymentRequiredError) {
+            console.error(`Out of credit: ${error.detail}`);
+            console.error('Add credits in the portal, then rerun.');
+            process.exit(2);
+        }
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+}
+const invokedDirectly = process.argv[1]?.endsWith('cli.js') || process.argv[1]?.endsWith('cli.ts');
+if (invokedDirectly)
+    void main();

package/dist/config.js

@@ -0,0 +1,47 @@
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+export const DEFAULT_API_URL = 'https://api.teamshift.io';
+export function configPath(env = process.env) {
+    return env.TEAMSHIFT_CONFIG ?? join(homedir(), '.teamshift', 'config.json');
+}
+/**
+ * Resolve credentials, environment first.
+ *
+ * The env var wins so CI and one-off shells never have to touch the config file,
+ * and so a shared machine can run as a different tenant without rewriting state.
+ */
+export function loadCredentials(env = process.env) {
+    const apiUrl = env.TEAMSHIFT_API_URL ?? readStored(env)?.apiUrl ?? DEFAULT_API_URL;
+    const apiKey = env.TEAMSHIFT_API_KEY ?? readStored(env)?.apiKey;
+    return apiKey ? { apiKey, apiUrl } : null;
+}
+function readStored(env) {
+    try {
+        const parsed = JSON.parse(readFileSync(configPath(env), 'utf8'));
+        if (typeof parsed !== 'object' || parsed === null)
+            return null;
+        const record = parsed;
+        return {
+            apiKey: typeof record.apiKey === 'string' ? record.apiKey : undefined,
+            apiUrl: typeof record.apiUrl === 'string' ? record.apiUrl : undefined,
+        };
+    }
+    catch {
+        // No config yet, or an unreadable/corrupt one — treat both as "not logged
+        // in" so a broken file prompts a fresh login instead of crashing the CLI.
+        return null;
+    }
+}
+/** Persist credentials 0600 — this file holds a live billing credential. */
+export function saveCredentials(credentials, env = process.env) {
+    const target = configPath(env);
+    mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+    writeFileSync(target, `${JSON.stringify(credentials, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(target, 0o600);
+    return target;
+}
+/** Show enough of a key to identify it, never enough to use it. */
+export function maskKey(apiKey) {
+    return apiKey.length <= 8 ? '****' : `${apiKey.slice(0, 6)}…${apiKey.slice(-4)}`;
+}

package/dist/format.js

@@ -0,0 +1,42 @@
+export const TERMINAL_STATUSES = new Set([
+    'completed',
+    'failed',
+    'canceled',
+    'terminated',
+    'timed_out',
+    'approval_expired',
+    'blocked',
+    'guardrail_tripped',
+]);
+export function isTerminal(status) {
+    return TERMINAL_STATUSES.has(String(status ?? ''));
+}
+/**
+ * Charge in USD for a run's reconciled cost, at the metered markup.
+ *
+ * Mirrors the server's resolver rather than inventing a number: the CLI only
+ * ever PREVIEWS what reconciliation will debit, so it must not round somewhere
+ * the server does not. Returns null for an unreconciled run so the caller can
+ * print "pending" instead of a misleading $0.00.
+ */
+export function chargeUsd(costUsd, markup) {
+    if (costUsd === null || costUsd === undefined || costUsd === '')
+        return null;
+    const cost = typeof costUsd === 'number' ? costUsd : Number(costUsd);
+    if (!Number.isFinite(cost) || cost < 0)
+        return null;
+    return Math.max(Math.ceil(Number((cost * markup * 100).toFixed(6))), cost > 0 ? 1 : 0) / 100;
+}
+export function money(value) {
+    return value === null ? '—' : `$${value.toFixed(2)}`;
+}
+export function duration(ms) {
+    const seconds = Math.round(ms / 100) / 10;
+    return seconds < 60 ? `${seconds.toFixed(1)}s` : `${Math.floor(seconds / 60)}m${Math.round(seconds % 60)}s`;
+}
+/** Fixed-width table so a fan-out of many runs stays scannable in a terminal. */
+export function table(headers, rows) {
+    const widths = headers.map((header, index) => Math.max(header.length, ...rows.map((row) => (row[index] ?? '').length)));
+    const line = (cells) => cells.map((cell, index) => (cell ?? '').padEnd(widths[index] ?? 0)).join('  ').trimEnd();
+    return [line(headers), line(widths.map((width) => '─'.repeat(width))), ...rows.map(line)].join('\n');
+}

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from './api.js';
+export * from './config.js';
+export * from './format.js';
+export * from './run.js';
+export { parseArgs } from './cli.js';

package/dist/run.js

@@ -0,0 +1,63 @@
+import { isTerminal } from './format.js';
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Poll one run to a terminal status, or give up at the timeout. */
+export async function waitForRun(client, runId, options = {}) {
+    const { intervalMs = 2000, timeoutMs = 900_000, now = Date.now, sleep = defaultSleep } = options;
+    const startedAt = now();
+    let latest = await client.getRun(runId);
+    while (!isTerminal(latest.status)) {
+        if (now() - startedAt >= timeoutMs)
+            return latest;
+        await sleep(intervalMs);
+        latest = await client.getRun(runId);
+    }
+    return latest;
+}
+/**
+ * Dispatch many prompts against one team and collect every result.
+ *
+ * Bounded concurrency rather than an unbounded Promise.all: a fan-out of a few
+ * hundred prompts would otherwise open that many sockets at once and trip the
+ * API's write rate limit, turning a large batch into a wall of 429s.
+ *
+ * A failed run never rejects the batch — it is recorded as its own outcome, so
+ * one bad prompt cannot discard the work of every sibling that succeeded.
+ */
+export async function runBatch(client, kind, id, prompts, options = {}) {
+    const { concurrency = 5, onSettled, now = Date.now, ...pollOptions } = options;
+    const results = new Array(prompts.length);
+    let cursor = 0;
+    const worker = async () => {
+        for (;;) {
+            const index = cursor++;
+            const prompt = prompts[index];
+            if (prompt === undefined)
+                return;
+            const startedAt = now();
+            try {
+                const runId = await client.startRun(kind, id, prompt);
+                const summary = await waitForRun(client, runId, { ...pollOptions, now });
+                results[index] = {
+                    prompt,
+                    runId,
+                    status: String(summary.status ?? 'unknown'),
+                    costUsd: summary.cost_estimate_usd ?? null,
+                    elapsedMs: now() - startedAt,
+                };
+            }
+            catch (error) {
+                results[index] = {
+                    prompt,
+                    runId: null,
+                    status: 'dispatch_failed',
+                    costUsd: null,
+                    elapsedMs: now() - startedAt,
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+            onSettled?.(results[index]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(concurrency, prompts.length)) }, worker));
+    return results;
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "teamshift",
+  "private": false,
+  "version": "0.1.0",
+  "description": "Run TeamShift agent teams from your terminal. Metered by usage — no model key of your own required.",
+  "type": "module",
+  "bin": {
+    "teamshift": "dist/cli.js"
+  },
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.1",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './api.js';
+export * from './config.js';
+export * from './format.js';
+export * from './run.js';
+export { parseArgs } from './cli.js';