osuite 2.9.3 → 2.9.4

package/README.md

@@ -1,4 +1,4 @@
-# OSuite SDK (v2.9.2)
+# OSuite SDK (v2.9.4)
 
 **Governed action SDK for AI agents.**
 
@@ -451,11 +451,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 +464,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 +476,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 +489,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,41 @@ 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 projectFilePath(relativePath) {
   const clean = String(relativePath || '').replace(/^\/+/, '');
   const root = path.resolve(process.cwd());
@@ -217,6 +253,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 +550,52 @@ 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 code = String(args.code || generateConnectCode()).trim() || generateConnectCode();
+  const handoffUrl = buildConnectHandoffUrl({ baseUrl, runtime, code });
+  const hasApiKey = Boolean(config.apiKey);
+
+  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('');
+  write(c('What happens next', ANSI.bold));
+  write('  1. Open the browser handoff URL and choose the workspace that should own this runtime.');
+  write('  2. OSuite prepares the runtime identity and project hook lane for the detected agent.');
+  write('  3. Run osuite doctor, then trigger one low-risk governed action from the same project root.');
+  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.');
+  }
+
+  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 +608,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.4",
   "description": "OSuite governed action SDK for AI agents. Approve, replay, prove, and verify runtime decisions.",
   "type": "module",
   "publishConfig": {