osuite 2.9.1 → 2.9.3

package/README.md

@@ -1,4 +1,4 @@
-# OSuite SDK (v2.9.1)
+# OSuite SDK (v2.9.2)
 
 **Governed action SDK for AI agents.**
 
@@ -448,7 +448,15 @@ 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 -- codex
+# or
+curl -fsSL https://studio.osuite.ai/install.sh | bash -s -- claude
+```
+
+If you prefer npm directly:
 
 ```bash
 npm install -g osuite
@@ -458,7 +466,8 @@ npm install -g osuite
 osuite                         # branded welcome and command map
 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
@@ -466,7 +475,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, 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.
@@ -476,15 +485,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 -s -- claude
 ```
 
-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 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.
 
 ---
 

package/cli.js

@@ -24,6 +24,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 +56,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 +95,8 @@ function parseArgs(argv) {
   return { command, args };
 }
 
+loadProjectEnvironment();
+
 function envValue(name, fallback) {
   return process.env[name] || process.env[fallback] || '';
 }
@@ -82,6 +122,80 @@ function requireClient() {
   return new OSuite(config);
 }
 
+function normalizedBaseUrl(value) {
+  return String(value || DEFAULT_BASE_URL).replace(/\/$/, '');
+}
+
+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,7 +217,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 init [codex|claude|mcp]        Print setup steps for a runtime lane');
+  write('  osuite init [sdk|codex|claude|mcp]    Print setup steps for a runtime lane');
   write('');
   write(c('Environment', ANSI.bold));
   write('  OSUITE_BASE_URL     Studio URL, for example https://studio.osuite.ai');
@@ -373,8 +487,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');
@@ -382,14 +501,12 @@ function init(target = 'generic') {
   write('export OSUITE_AGENT_ID=<agent-or-runtime-id>');
   write('');
 
-  if (target === 'codex') {
-    write(c('Codex runtime lane', ANSI.bold));
+  if (target === 'sdk') {
+    write(c('Embedded SDK runtime lane', ANSI.bold));
+    write('  npm install osuite');
+    write('  export OSUITE_RUNTIME_FAMILY=framework_sdk');
+    write('  export OSUITE_ADAPTER_MODE=inline_sdk');
     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.');
@@ -408,7 +525,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 === 'init') return init(args._[0] || 'generic');
+  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.1",
+  "version": "2.9.3",
   "description": "OSuite governed action SDK for AI agents. Approve, replay, prove, and verify runtime decisions.",
   "type": "module",
   "publishConfig": {