osuite 2.9.2 → 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.**
 
@@ -448,12 +448,14 @@ OSuite uses standard HTTP status codes and custom error classes:
 
 ## CLI Approval Channel
 
-Install the OSuite CLI to connect a runtime, preview CAVA interpretation, review Decision V2 output, and approve agent actions from the terminal:
+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 -- sdk
+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
@@ -462,9 +464,11 @@ 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              # print runtime setup steps
+osuite init codex              # install .codex hook files into the current project
+osuite init claude             # install .claude hook files into the current project
 osuite explain "git push origin main"
 osuite approvals               # approval inbox
 osuite review <actionId>       # Decision V2 review surface
@@ -472,7 +476,7 @@ osuite approve <actionId>      # approve a specific action
 osuite deny <actionId>         # deny a specific action
 ```
 
-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.
@@ -482,15 +486,13 @@ When an agent calls `waitForApproval()`, it prints the action ID and replay link
 
 ## Claude Code Hooks
 
-Govern Claude Code tool calls without any SDK instrumentation. Copy two files from the `hooks/` directory in the repo into your `.claude/hooks/` folder:
+Govern Claude Code tool calls without any SDK instrumentation. The preferred path is the project-root installer:
 
 ```bash
-# In your project directory
-cp path/to/OSuite/hooks/osuite_pretool.py .claude/hooks/
-cp path/to/OSuite/hooks/osuite_posttool.py .claude/hooks/
+curl -fsSL https://studio.osuite.ai/install.sh | bash
 ```
 
-Then merge the hooks block from `hooks/settings.json` into your `.claude/settings.json`. Set `OSUITE_BASE_URL`, `OSUITE_API_KEY`, and optionally `OSUITE_HOOK_MODE=enforce`.
+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';
 
@@ -24,6 +25,25 @@ const PROTECTED_REFS = new Set(['main', 'master', 'prod', 'production', 'stable'
 const OBSERVE_OPS = new Set(['get', 'describe', 'logs', 'top', 'version', 'diff']);
 const PLAN_OPS = new Set(['plan', 'show', 'validate', 'output', 'fmt', 'providers', 'graph']);
 const MUTATION_OPS = new Set(['apply', 'destroy', 'delete', 'create', 'replace', 'taint', 'untaint', 'import', 'upgrade', 'rollback', 'install', 'uninstall']);
+const DEFAULT_BASE_URL = 'https://studio.osuite.ai';
+const PROJECT_BOOTSTRAPS = {
+  codex: {
+    label: 'Codex hook runtime',
+    endpoint: '/api/runtimes/codex/bootstrap',
+    envPath: '.codex/.env.example',
+    readmePath: '.codex/README.osuite.md',
+    runLine: 'Run Codex from this project root so .codex/hooks.json can govern Bash/Edit/Write actions.',
+    smokeLine: 'Try: osuite explain "git push origin main", then ask Codex to run a low-risk command such as git status.',
+  },
+  claude: {
+    label: 'Claude Code hook runtime',
+    endpoint: '/api/runtimes/claude-code/bootstrap',
+    envPath: '.claude/.env.example',
+    readmePath: '.claude/README.osuite.md',
+    runLine: 'Run Claude Code from this project root so .claude/settings.json can govern tool calls.',
+    smokeLine: 'Try: osuite explain "git push origin main", then ask Claude Code to run a low-risk command such as git status.',
+  },
+};
 
 function useColor() {
   return !process.env.NO_COLOR && process.stdout.isTTY !== false;
@@ -37,6 +57,25 @@ function write(value = '') {
   process.stdout.write(`${value}\n`);
 }
 
+function loadDotenvFile(relativePath) {
+  const absolute = path.join(process.cwd(), relativePath);
+  if (!fs.existsSync(absolute)) return;
+  const body = fs.readFileSync(absolute, 'utf8');
+  body.split(/\r?\n/).forEach((line) => {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#') || !trimmed.includes('=')) return;
+    const [rawKey, ...rawValue] = trimmed.split('=');
+    const key = rawKey.trim();
+    let value = rawValue.join('=').trim().replace(/^['"]|['"]$/g, '');
+    if (value.includes(' #')) value = value.slice(0, value.indexOf(' #')).trim();
+    if (key && !process.env[key]) process.env[key] = value;
+  });
+}
+
+function loadProjectEnvironment() {
+  ['.codex/.env', '.claude/.env', '.osuite/.env', '.env'].forEach(loadDotenvFile);
+}
+
 function parseArgs(argv) {
   const [command = 'help', ...rest] = argv;
   const args = { _: [] };
@@ -57,6 +96,8 @@ function parseArgs(argv) {
   return { command, args };
 }
 
+loadProjectEnvironment();
+
 function envValue(name, fallback) {
   return process.env[name] || process.env[fallback] || '';
 }
@@ -82,6 +123,115 @@ function requireClient() {
   return new OSuite(config);
 }
 
+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());
+  const absolute = path.resolve(root, clean);
+  if (absolute !== root && !absolute.startsWith(`${root}${path.sep}`)) {
+    throw new Error(`Refusing to write outside the project root: ${relativePath}`);
+  }
+  return absolute;
+}
+
+function writeProjectFile(relativePath, body, { force = false } = {}) {
+  const absolute = projectFilePath(relativePath);
+  if (fs.existsSync(absolute) && !force) return { relativePath, status: 'skipped' };
+  fs.mkdirSync(path.dirname(absolute), { recursive: true });
+  fs.writeFileSync(absolute, String(body || ''));
+  return { relativePath, status: 'written' };
+}
+
+function remapBootstrapPath(spec, relativePath) {
+  if (relativePath === 'README.md') return spec.readmePath;
+  return relativePath;
+}
+
+async function loadRuntimeBootstrap(spec, args, config) {
+  if (args.from) {
+    const fixturePath = path.resolve(process.cwd(), String(args.from));
+    return JSON.parse(fs.readFileSync(fixturePath, 'utf8'));
+  }
+
+  const baseUrl = normalizedBaseUrl(args['base-url'] || config.baseUrl || DEFAULT_BASE_URL);
+  const response = await fetch(`${baseUrl}${spec.endpoint}`);
+  if (!response.ok) {
+    throw new Error(`Unable to download ${spec.label} bootstrap: HTTP ${response.status}`);
+  }
+  return response.json();
+}
+
+async function installRuntimeProjectBootstrap(target, args = {}) {
+  const spec = PROJECT_BOOTSTRAPS[target];
+  const config = readConfig();
+  const bootstrap = await loadRuntimeBootstrap(spec, args, config);
+  const force = Boolean(args.force);
+  const results = [];
+
+  Object.entries(bootstrap.files || {}).forEach(([relativePath, body]) => {
+    results.push(writeProjectFile(remapBootstrapPath(spec, relativePath), body, { force }));
+  });
+
+  if (bootstrap.recommended_env) {
+    results.push(writeProjectFile(spec.envPath, `${bootstrap.recommended_env.trim()}\n`, { force }));
+  }
+
+  const written = results.filter((item) => item.status === 'written');
+  const skipped = results.filter((item) => item.status === 'skipped');
+
+  write(c(spec.label, ANSI.bold));
+  write(`Installing project files into ${process.cwd()}`);
+  write('');
+  written.forEach((item) => write(`  ${c('created', ANSI.green)} ${item.relativePath}`));
+  skipped.forEach((item) => write(`  ${c('kept   ', ANSI.yellow)} ${item.relativePath} (use --force to replace)`));
+  write('');
+  write(c('Next steps', ANSI.bold));
+  write(`  1. Copy ${spec.envPath} to ${spec.envPath.replace(/\.example$/, '')} and fill OSUITE_API_KEY.`);
+  write('  2. Run osuite doctor.');
+  write(`  3. ${spec.runLine}`);
+  write(`  4. ${spec.smokeLine}`);
+  write('');
+  write(c('OSuite CLI is the control surface; the project hook files are what intercept agent actions.', ANSI.dim));
+}
+
 function banner() {
   return [
     c('OSUITE', `${ANSI.bold}${ANSI.cyan}`),
@@ -103,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));
@@ -373,8 +524,13 @@ async function decide(actionId, decision, args) {
   if (result?.action?.status) write(`New status           ${result.action.status}`);
 }
 
-function init(target = 'generic') {
+async function init(target = 'generic', args = {}) {
   write(c('OSuite init', `${ANSI.bold}${ANSI.cyan}`));
+  if (PROJECT_BOOTSTRAPS[target]) {
+    await installRuntimeProjectBootstrap(target, args);
+    return;
+  }
+
   write('Paste these into your shell, then run `osuite doctor`:');
   write('');
   write('export OSUITE_BASE_URL=https://studio.osuite.ai');
@@ -388,20 +544,58 @@ function init(target = 'generic') {
     write('  export OSUITE_RUNTIME_FAMILY=framework_sdk');
     write('  export OSUITE_ADAPTER_MODE=inline_sdk');
     write('  osuite doctor');
-  } else if (target === 'codex') {
-    write(c('Codex runtime lane', ANSI.bold));
-    write('  osuite doctor');
-    write('  npm run runtime:install:codex-plugin');
-  } else if (target === 'claude') {
-    write(c('Claude Code runtime lane', ANSI.bold));
-    write('  export OSUITE_RUNTIME_ADAPTER_ID=claude_code_hooks');
-    write('  export OSUITE_SIGNATURE_MODE=required');
   } else if (target === 'mcp') {
     write(c('MCP runtime lane', ANSI.bold));
     write('  Use OSuite preflight, wait-for-approval, and complete-action tools around consequential actions.');
   }
 }
 
+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));
 
@@ -414,7 +608,8 @@ 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 === 'init') return init(args._[0] || 'generic');
+  if (command === 'connect') return connect(args._[0] || 'auto', args);
+  if (command === 'init') return init(args._[0] || 'generic', args);
 
   write(`Unknown command: ${command}`);
   write('');

package/package.json

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