osuite 2.9.3 → 2.9.5

package/README.md

@@ -1,4 +1,4 @@
-# OSuite SDK (v2.9.2)
+# OSuite SDK (v2.9.5)
 
 **Governed action SDK for AI agents.**
 
@@ -11,6 +11,13 @@ The OSuite SDK helps teams route approvals, record governed decisions, and produ
 npm install osuite
 ```
 
+### One-command runtime connect
+```bash
+curl -fsSL https://studio.osuite.ai/install.sh | bash
+```
+
+The installer detects Codex, Claude Code, SDK, or MCP-style projects, opens a browser handoff, and writes the approved runtime environment into the project (`.codex/.env`, `.claude/.env`, or `.osuite/.env`). API keys remain available as a fallback, but the normal path is terminal start -> Studio approval -> terminal auto-finish.
+
 ### Python
 ```bash
 pip install requests
@@ -451,11 +458,11 @@ OSuite uses standard HTTP status codes and custom error classes:
 Install the OSuite CLI from the project root where your agent works. For Codex and Claude Code, the installer adds project-scoped hook files (`.codex` or `.claude`) while the CLI remains the control surface for doctor, explain, review, and approval:
 
 ```bash
-curl -fsSL https://studio.osuite.ai/install.sh | bash -s -- codex
-# or
-curl -fsSL https://studio.osuite.ai/install.sh | bash -s -- claude
+curl -fsSL https://studio.osuite.ai/install.sh | bash
 ```
 
+The default installer auto-detects common project lanes and starts a browser handoff. If auto-detection is wrong, force a lane with `OSUITE_INSTALL_TARGET=codex`, `OSUITE_INSTALL_TARGET=claude`, `OSUITE_INSTALL_TARGET=sdk`, or `OSUITE_INSTALL_TARGET=mcp`.
+
 If you prefer npm directly:
 
 ```bash
@@ -464,6 +471,7 @@ npm install -g osuite
 
 ```bash
 osuite                         # branded welcome and command map
+osuite connect auto            # detect the current project and start browser handoff
 osuite doctor                  # check env, Studio health, runtime, and signature posture
 osuite status                  # show the current Studio connection
 osuite init codex              # install .codex hook files into the current project
@@ -475,7 +483,7 @@ osuite approve <actionId>      # approve a specific action
 osuite deny <actionId>         # deny a specific action
 ```
 
-For local CLI agents, copy `.codex/.env.example` or `.claude/.env.example` to `.env`, fill `OSUITE_API_KEY`, and run the agent from the same project root. The CLI is intentionally more than an API wrapper:
+For local CLI agents, `osuite connect auto` prints a browser handoff URL and installs the project hook lane when it can detect Codex or Claude Code. If browser handoff is unavailable, copy `.codex/.env.example` or `.claude/.env.example` to `.env`, fill `OSUITE_API_KEY`, and run the agent from the same project root. The CLI is intentionally more than an API wrapper:
 - `doctor` tells a developer what is missing before they connect an agent.
 - `explain` gives a local CAVA preview before a command reaches OSuite.
 - `approvals` provides a readable approval inbox instead of raw JSON.
@@ -488,10 +496,10 @@ When an agent calls `waitForApproval()`, it prints the action ID and replay link
 Govern Claude Code tool calls without any SDK instrumentation. The preferred path is the project-root installer:
 
 ```bash
-curl -fsSL https://studio.osuite.ai/install.sh | bash -s -- claude
+curl -fsSL https://studio.osuite.ai/install.sh | bash
 ```
 
-It creates `.claude/hooks/*`, `.claude/settings.json`, `.claude/settings.local.json`, and `.claude/.env.example`. Copy the env example to `.claude/.env`, fill `OSUITE_API_KEY`, then run Claude Code from that project root.
+It detects `.claude`, creates `.claude/hooks/*`, `.claude/settings.json`, `.claude/settings.local.json`, and `.claude/.env.example`, then prints the browser handoff. Copy the env example to `.claude/.env` and fill `OSUITE_API_KEY` only when the browser flow is not available.
 
 ---
 

package/cli.js

@@ -2,6 +2,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import crypto from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { OSuite, buildReviewSurface } from './osuite.js';
 
@@ -126,6 +127,159 @@ function normalizedBaseUrl(value) {
   return String(value || DEFAULT_BASE_URL).replace(/\/$/, '');
 }
 
+function sanitizeRuntimeTarget(value, fallback = 'auto') {
+  const normalized = String(value || fallback)
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]/g, '');
+  if (!normalized) return fallback;
+  if (normalized === 'claude-code' || normalized === 'claudecode') return 'claude';
+  if (normalized === 'generic') return 'auto';
+  return normalized;
+}
+
+function detectRuntimeTarget(preferred = 'auto') {
+  const target = sanitizeRuntimeTarget(preferred);
+  if (target !== 'auto') return target;
+
+  const cwd = process.cwd();
+  if (fs.existsSync(path.join(cwd, '.codex'))) return 'codex';
+  if (fs.existsSync(path.join(cwd, '.claude'))) return 'claude';
+  if (fs.existsSync(path.join(cwd, 'mcp.json')) || fs.existsSync(path.join(cwd, '.mcp.json'))) return 'mcp';
+  if (fs.existsSync(path.join(cwd, 'package.json'))) return 'sdk';
+  return 'sdk';
+}
+
+function generateConnectCode() {
+  return `OS-${crypto.randomBytes(3).toString('hex').toUpperCase()}`;
+}
+
+function buildConnectHandoffUrl({ baseUrl, runtime, code }) {
+  const url = new URL('/connect', normalizedBaseUrl(baseUrl));
+  url.searchParams.set('runtime', runtime);
+  url.searchParams.set('source', 'cli');
+  url.searchParams.set('code', code);
+  return url.toString();
+}
+
+function defaultAgentIdForRuntime(runtime) {
+  if (runtime === 'codex') return 'codex-runtime';
+  if (runtime === 'claude') return 'claude-code-runtime';
+  if (runtime === 'mcp') return 'mcp-runtime';
+  return 'sdk-runtime';
+}
+
+function envPathForRuntime(runtime) {
+  if (runtime === 'codex') return '.codex/.env';
+  if (runtime === 'claude') return '.claude/.env';
+  return '.osuite/.env';
+}
+
+function orderedEnvEntries(env = {}) {
+  const preferred = [
+    'OSUITE_BASE_URL',
+    'OSUITE_API_KEY',
+    'OSUITE_AGENT_ID',
+    'OSUITE_RUNTIME_ADAPTER_ID',
+    'OSUITE_SIGNATURE_MODE',
+  ];
+  const seen = new Set();
+  const entries = [];
+  preferred.forEach((key) => {
+    if (env[key] !== undefined && env[key] !== null && env[key] !== '') {
+      seen.add(key);
+      entries.push([key, env[key]]);
+    }
+  });
+  Object.keys(env)
+    .sort()
+    .forEach((key) => {
+      if (!seen.has(key) && env[key] !== undefined && env[key] !== null && env[key] !== '') {
+        entries.push([key, env[key]]);
+      }
+    });
+  return entries;
+}
+
+function formatEnvBody(env = {}) {
+  return `${orderedEnvEntries(env)
+    .map(([key, value]) => `${key}=${String(value).replace(/\n/g, '')}`)
+    .join('\n')}\n`;
+}
+
+function parsePositiveInt(value, fallback) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed < 0) return fallback;
+  return parsed;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function postJson(url, body) {
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body || {}),
+  });
+  const text = await response.text();
+  let payload = {};
+  if (text) {
+    try {
+      payload = JSON.parse(text);
+    } catch {
+      payload = { raw: text };
+    }
+  }
+  return { response, payload };
+}
+
+async function startDeviceConnect({ baseUrl, runtime, agentId }) {
+  const { response, payload } = await postJson(`${normalizedBaseUrl(baseUrl)}/api/onboarding/device-connect/start`, {
+    runtime,
+    agent_id: agentId,
+    project_root: process.cwd(),
+  });
+  if (!response.ok) {
+    throw new Error(payload.error || `Unable to start browser handoff: HTTP ${response.status}`);
+  }
+  if (!payload.device_code || !payload.poll_token || !payload.user_code) {
+    throw new Error('Studio did not return a complete device-connect payload.');
+  }
+  return payload;
+}
+
+async function pollDeviceConnect({ baseUrl, deviceCode, pollToken, timeoutMs, intervalMs }) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() <= deadline) {
+    const { response, payload } = await postJson(`${normalizedBaseUrl(baseUrl)}/api/onboarding/device-connect/poll`, {
+      device_code: deviceCode,
+      poll_token: pollToken,
+    });
+
+    if (response.status === 200 && payload.status === 'approved' && payload.credential?.env) {
+      return payload.credential;
+    }
+    if (response.status === 202 || payload.status === 'pending') {
+      const serverInterval = Number(payload.interval_seconds || 0) * 1000;
+      await sleep(serverInterval > 0 ? Math.max(intervalMs, serverInterval) : intervalMs);
+      continue;
+    }
+    if (response.status === 410 || payload.status === 'expired') {
+      throw new Error('Browser handoff expired. Run osuite connect again.');
+    }
+    if (response.status === 409 || payload.status === 'consumed') {
+      throw new Error(payload.error || 'Browser handoff was already consumed.');
+    }
+    if (response.status === 404) {
+      throw new Error('Browser handoff was not found. Run osuite connect again.');
+    }
+    throw new Error(payload.error || `Unable to finish browser handoff: HTTP ${response.status}`);
+  }
+  return null;
+}
+
 function projectFilePath(relativePath) {
   const clean = String(relativePath || '').replace(/^\/+/, '');
   const root = path.resolve(process.cwd());
@@ -217,6 +371,7 @@ function printHelp() {
   write('  osuite review <actionId>              Render the decision review card');
   write('  osuite approve <actionId> --reason "Looks safe"');
   write('  osuite deny <actionId> --reason "Outside change window"');
+  write('  osuite connect [auto|codex|claude|sdk|mcp]  Detect runtime and start browser handoff');
   write('  osuite init [sdk|codex|claude|mcp]    Print setup steps for a runtime lane');
   write('');
   write(c('Environment', ANSI.bold));
@@ -513,6 +668,96 @@ async function init(target = 'generic', args = {}) {
   }
 }
 
+async function connect(target = 'auto', args = {}) {
+  const config = readConfig();
+  const runtime = detectRuntimeTarget(target);
+  const baseUrl = normalizedBaseUrl(args['base-url'] || config.baseUrl || DEFAULT_BASE_URL);
+  const configuredAgentId = envValue('OSUITE_AGENT_ID', 'DASHCLAW_AGENT_ID');
+  const agentId = String(args['agent-id'] || configuredAgentId || defaultAgentIdForRuntime(runtime));
+  const dryRunCode = String(args.code || generateConnectCode()).trim() || generateConnectCode();
+  let connectPayload = null;
+  let code = dryRunCode;
+  let handoffUrl = buildConnectHandoffUrl({ baseUrl, runtime, code });
+  const hasApiKey = Boolean(config.apiKey);
+
+  if (!args['dry-run']) {
+    connectPayload = await startDeviceConnect({ baseUrl, runtime, agentId });
+    code = connectPayload.user_code;
+    handoffUrl = connectPayload.verification_uri_complete || buildConnectHandoffUrl({ baseUrl, runtime, code });
+  }
+
+  write(c('OSuite Connect', `${ANSI.bold}${ANSI.cyan}`));
+  write(c('Project-root setup for governed agent actions.', ANSI.dim));
+  write('');
+  write(`Detected runtime     ${runtime}`);
+  write(`Project root         ${process.cwd()}`);
+  write(`Browser handoff      ${handoffUrl}`);
+  write(`One-time code        ${code}`);
+  write('');
+  write(c('What happens next', ANSI.bold));
+  write('  1. Open the browser handoff URL and approve this terminal connection in Studio.');
+  write('  2. OSuite prepares the runtime identity, project hook lane, and signed env for this project.');
+  write('  3. Return here; the CLI will finish automatically and then you can run osuite doctor.');
+  write('');
+
+  if (PROJECT_BOOTSTRAPS[runtime]) {
+    if (args['dry-run']) {
+      write(`Dry run: would install project hook files for ${runtime}.`);
+    } else {
+      await installRuntimeProjectBootstrap(runtime, args);
+    }
+  } else {
+    write(c('Runtime setup', ANSI.bold));
+    write('  This runtime uses the embedded SDK/MCP lane. Install the SDK in the app code path that dispatches actions.');
+    if (runtime === 'sdk') write('  npm install osuite');
+    if (runtime === 'mcp') write('  Wrap consequential tool calls with OSuite preflight, wait-for-approval, and complete-action steps.');
+  }
+
+  if (!args['dry-run'] && connectPayload) {
+    const timeoutMs = parsePositiveInt(args['poll-timeout-ms'], 180000);
+    const intervalMs = parsePositiveInt(
+      args['poll-interval-ms'],
+      Math.max(1000, Number(connectPayload.interval_seconds || 2) * 1000),
+    );
+
+    write('');
+    write(c('Waiting for browser approval', ANSI.bold));
+    write(`  Code ${code} expires in about ${Math.round(Number(connectPayload.expires_in || 600) / 60)} minutes.`);
+
+    const credential = await pollDeviceConnect({
+      baseUrl,
+      deviceCode: connectPayload.device_code,
+      pollToken: connectPayload.poll_token,
+      timeoutMs,
+      intervalMs,
+    });
+
+    if (credential?.env) {
+      const envPath = envPathForRuntime(runtime);
+      const result = writeProjectFile(envPath, formatEnvBody(credential.env), { force: true });
+      write('');
+      write(c('Connected to OSuite', ANSI.green));
+      write(`  ${result.status === 'written' ? 'wrote' : 'kept'} ${result.relativePath}`);
+      write('  Run osuite doctor, then start the agent from this project root.');
+    } else {
+      write('');
+      write(c('Browser approval not completed before the timeout.', ANSI.yellow));
+      write('  Keep the browser handoff open or run osuite connect again.');
+    }
+  }
+
+  write('');
+  write(c('API key fallback', ANSI.bold));
+  if (hasApiKey) {
+    write('  OSUITE_API_KEY is already present in this shell or project env. Browser handoff can be skipped for this project.');
+  } else if (PROJECT_BOOTSTRAPS[runtime]) {
+    const envPath = PROJECT_BOOTSTRAPS[runtime].envPath.replace(/\.example$/, '');
+    write(`  If browser handoff is unavailable, copy ${PROJECT_BOOTSTRAPS[runtime].envPath} to ${envPath} and paste a workspace API key.`);
+  } else {
+    write('  If browser handoff is unavailable, export OSUITE_BASE_URL and OSUITE_API_KEY before running the agent.');
+  }
+}
+
 async function main() {
   const { command, args } = parseArgs(process.argv.slice(2));
 
@@ -525,6 +770,7 @@ async function main() {
   if (command === 'review') return review(args._[0]);
   if (command === 'approve') return decide(args._[0], 'allow', args);
   if (command === 'deny') return decide(args._[0], 'deny', args);
+  if (command === 'connect') return connect(args._[0] || 'auto', args);
   if (command === 'init') return init(args._[0] || 'generic', args);
 
   write(`Unknown command: ${command}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "osuite",
-  "version": "2.9.3",
+  "version": "2.9.5",
   "description": "OSuite governed action SDK for AI agents. Approve, replay, prove, and verify runtime decisions.",
   "type": "module",
   "publishConfig": {