ultra-builder-pro-cli 0.22.0 → 0.24.0

package/adapters/_shared/interaction-contract.cjs

@@ -23,16 +23,21 @@ const SURFACES = Object.freeze({
     fallback: 'direct_user_interaction',
     availability: 'interactive_non_auto_mode',
   }),
+  grok: Object.freeze({
+    primary: 'AskUserQuestion',
+    fallback: 'direct_user_interaction',
+    availability: 'interactive_session',
+  }),
 });
 
 const GENERIC_QUESTION_GUIDANCE =
-  /Use the host-native structured question surface declared by the installed interaction\s+contract(?: when it exists)?\./g;
+  /Use the host-native (?:structured )?question surface declared by the installed interaction\s+contract(?: when it exists)?(?:;?\s+prefer its structured form when the host exposes one)?\./g;
 
 function interactionContract(runtime) {
   const question = SURFACES[runtime];
   if (!question) throw new Error(`unsupported interaction runtime: ${runtime}`);
   return {
-    schema_version: '1.2',
+    schema_version: '1.3',
     runtime,
     public_capability_graph: PUBLIC_CAPABILITY_GRAPH,
     authority: {
@@ -50,9 +55,9 @@ function interactionContract(runtime) {
         'accepted_intent_normalization',
       ],
       ultra_mcp: [
-        'durable_state_and_evidence_refs',
-        'digests_freshness_locks_and_recovery',
-        'allowed_and_required_transitions',
+        'durable_checkpoints_and_evidence_refs',
+        'digests_freshness_leases_archives_and_recovery',
+        'mutable_semantic_diagnostics',
       ],
     },
     interaction: {
@@ -85,8 +90,15 @@ function interactionContract(runtime) {
     routing: {
       semantic_recommendation_owner: 'host_model',
       durable_recommendation_authority: false,
-      hard_invariant_field: 'required_transition',
-      valid_capabilities_field: 'allowed_transitions',
+      current_context_tool: 'ultra.context',
+      checkpoint_diagnostic_fields: ['warnings', 'blockers'],
+      hard_blocker_boundary: [
+        'corruption',
+        'unsafe_path',
+        'concurrency_conflict',
+        'permission',
+        'irreversible_external_effect',
+      ],
     },
   };
 }
@@ -99,6 +111,7 @@ function interactionPrompt(runtime) {
     codex: 'Codex',
     opencode: 'OpenCode',
     kimi: 'Kimi Code',
+    grok: 'Grok Build',
   }[runtime];
   const primary = runtime === 'opencode' ? `\`${surface.primary}\`` : surface.primary;
   return `Use ${host} ${primary} when ${surface.availability.replaceAll('_', ' ')} permits it.`;

package/adapters/_shared/provenance.cjs

@@ -187,7 +187,8 @@ function assetRefsForTree(rootName, root, { exclude = [] } = {}) {
 function writeProvenance({
   file, adapter, packageInfo, repository, sourceCommit: commit = null,
   sourceDirty: dirty = null, sourceWorktreeDigest: worktreeDigest = null,
-  roots: inputRoots, assets: inputAssets, contracts: inputContracts = {},
+  roots: inputRoots, assetRoots: inputAssetRoots = inputRoots,
+  assets: inputAssets, contracts: inputContracts = {},
 }) {
   if (!file || !adapter || !packageInfo?.name || !packageInfo?.version || !repository) {
     throw new Error('provenance file, adapter, package, version, and repository are required');
@@ -199,9 +200,13 @@ function writeProvenance({
     throw new Error('provenance source worktree digest must be a SHA-256 digest or null');
   }
   const roots = normalizeRoots(inputRoots);
+  const assetRoots = normalizeRoots(inputAssetRoots);
+  for (const root of Object.keys(roots)) {
+    if (!assetRoots[root]) throw new Error(`missing provenance asset root: ${root}`);
+  }
   const refs = normalizeAssetRefs(inputAssets, roots);
   const assets = refs.map((ref) => {
-    const { target } = resolveRef(roots, ref);
+    const { target } = resolveRef(assetRoots, ref);
     const stat = fs.statSync(target);
     if (!stat.isFile()) throw new Error(`provenance asset is not a file: ${target}`);
     return { ...ref, size_bytes: stat.size, sha256: hashFile(target) };

package/adapters/_shared/runtime-assets.cjs

@@ -41,7 +41,7 @@ const PUBLIC_CAPABILITY_GRAPH = Object.freeze(Object.fromEntries(
     Object.freeze({
       mode: PUBLIC_CAPABILITY_MODES[name],
       activation: 'explicit_only',
-      next_capability_source: 'mcp_allowed_transitions',
+      next_capability_source: 'host_model_from_ultra_context',
       recommendation_owner: 'host_model',
       selection_owner: 'user',
       automatic_invocation: false,
@@ -56,13 +56,14 @@ const INTERNAL_AGENT_SKILLS = Object.freeze([
   'testing-rules',
 ]);
 
-const SUPPORTED_RUNTIMES = Object.freeze(['claude', 'opencode', 'codex', 'kimi']);
+const SUPPORTED_RUNTIMES = Object.freeze(['claude', 'opencode', 'codex', 'kimi', 'grok']);
 
 const COLLAB_SKILLS_BY_RUNTIME = Object.freeze({
   claude: Object.freeze(['codex-collab', 'ultra-verify']),
   codex: Object.freeze(['cc-collab', 'ultra-verify']),
   opencode: Object.freeze(['cc-collab', 'codex-collab', 'ultra-verify']),
   kimi: Object.freeze(['cc-collab', 'codex-collab', 'ultra-verify']),
+  grok: Object.freeze(['cc-collab', 'codex-collab', 'ultra-verify']),
 });
 
 const MCP_DEPENDENT_SKILLS = Object.freeze([
@@ -80,7 +81,7 @@ const MCP_DEPENDENT_SKILLS = Object.freeze([
 
 const WORKFLOW_HOOK_FILES = Object.freeze([
   'active_task_context.py',
-  'context_spine.py',
+  'context_envelope.py',
   'health_check.py',
   'pre_stop_check.py',
   'runtime_paths.py',

package/adapters/_shared/runtime-native.cjs

@@ -0,0 +1,132 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const MANIFEST_FILE = 'native-runtime.json';
+
+class RuntimeNativeError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = 'RuntimeNativeError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+function sha256(file) {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
+function readManifest(runtimeRoot) {
+  const file = path.join(path.resolve(runtimeRoot), MANIFEST_FILE);
+  if (!fs.existsSync(file)) {
+    throw new RuntimeNativeError(
+      'RUNTIME_NATIVE_MISSING',
+      `Ultra native runtime manifest is missing: ${file}`,
+      { path: file },
+    );
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (cause) {
+    throw new RuntimeNativeError(
+      'RUNTIME_NATIVE_MISSING',
+      `Ultra native runtime manifest is invalid: ${file}`,
+      { path: file, cause: cause.message },
+    );
+  }
+  if (manifest?.schema_version !== 1
+      || typeof manifest.native_module !== 'string'
+      || !/^[0-9a-f]{64}$/i.test(manifest.native_sha256 || '')) {
+    throw new RuntimeNativeError(
+      'RUNTIME_NATIVE_MISSING',
+      `Ultra native runtime manifest is incomplete: ${file}`,
+      { path: file },
+    );
+  }
+  return { file, manifest };
+}
+
+function inspectRuntimeNative(runtimeRoot, { load = true } = {}) {
+  const root = path.resolve(runtimeRoot);
+  const { file, manifest } = readManifest(root);
+  const expected = {
+    platform: process.platform,
+    arch: process.arch,
+    modules: process.versions.modules,
+  };
+  const actual = {
+    platform: manifest.platform,
+    arch: manifest.arch,
+    modules: String(manifest.modules || ''),
+  };
+  if (actual.platform !== expected.platform
+      || actual.arch !== expected.arch
+      || actual.modules !== expected.modules) {
+    throw new RuntimeNativeError(
+      'RUNTIME_ABI_MISMATCH',
+      `Ultra native runtime requires ${actual.platform}/${actual.arch} ABI ${
+        actual.modules
+      }, but the active Node is ${expected.platform}/${expected.arch} ABI ${expected.modules}`,
+      { expected: actual, actual: expected, manifest: file },
+    );
+  }
+  const nativeFile = path.resolve(root, manifest.native_module);
+  if (nativeFile !== root && !nativeFile.startsWith(`${root}${path.sep}`)) {
+    throw new RuntimeNativeError(
+      'RUNTIME_NATIVE_MISSING',
+      'Ultra native module path escapes the runtime root',
+      { path: manifest.native_module },
+    );
+  }
+  if (!fs.existsSync(nativeFile) || !fs.statSync(nativeFile).isFile()) {
+    throw new RuntimeNativeError(
+      'RUNTIME_NATIVE_MISSING',
+      `Ultra native SQLite driver is missing: ${nativeFile}`,
+      { path: nativeFile },
+    );
+  }
+  const digest = sha256(nativeFile);
+  if (digest !== manifest.native_sha256) {
+    throw new RuntimeNativeError(
+      'RUNTIME_NATIVE_MISSING',
+      `Ultra native SQLite driver digest does not match its manifest: ${nativeFile}`,
+      { path: nativeFile, expected: manifest.native_sha256, actual: digest },
+    );
+  }
+  if (load) {
+    let Database;
+    try {
+      Database = require(require.resolve('better-sqlite3', {
+        paths: [path.join(root, 'node_modules')],
+      }));
+      const db = new Database(':memory:');
+      db.prepare('SELECT 1 AS ok').get();
+      db.close();
+    } catch (cause) {
+      throw new RuntimeNativeError(
+        'RUNTIME_ABI_MISMATCH',
+        `Ultra native SQLite driver cannot load in the active Node runtime: ${cause.message}`,
+        { path: nativeFile, cause: cause.code || cause.message },
+      );
+    }
+  }
+  return {
+    status: 'healthy',
+    manifest: file,
+    platform: actual.platform,
+    arch: actual.arch,
+    modules: actual.modules,
+    native_module: nativeFile,
+    native_sha256: digest,
+  };
+}
+
+module.exports = {
+  MANIFEST_FILE,
+  RuntimeNativeError,
+  inspectRuntimeNative,
+};

package/adapters/claude.js

@@ -14,7 +14,11 @@ const {
   removeTree,
   writeAtomic,
 } = require('./_shared/file-ops.cjs');
-const { buildMcpRuntime } = require('./_shared/codex-assets.cjs');
+const {
+  applyNativeDoctor,
+  buildMcpRuntime,
+  mcpCommand,
+} = require('./_shared/codex-assets.cjs');
 const { parse: parseFrontmatter, serialize: serializeFrontmatter } = require('./_shared/frontmatter.cjs');
 const { adaptInteractionGuidance } = require('./_shared/interaction-contract.cjs');
 const provenance = require('./_shared/provenance.cjs');
@@ -66,7 +70,7 @@ function copySkills(repoRoot, target, names) {
         let adaptedBody = adaptInteractionGuidance(body, 'claude');
         if (name === 'ultra-review') {
           adaptedBody = adaptedBody.replace(
-            /the current host's native bounded-worker\s+mechanism/g,
+            /(?:the current host's native|the host-native) bounded-worker\s+mechanism/g,
             'Claude Code Task workers using the installed review agent definitions',
           );
         }
@@ -139,83 +143,109 @@ function buildHooksManifest() {
   };
 }
 
-function install(ctx = {}) {
-  const target = resolvePluginRoot(ctx);
-  const repoRoot = resolveRepoRoot(ctx);
-  if (fs.existsSync(target)) {
-    const entries = fs.readdirSync(target);
-    if (entries.length > 0 && !isManaged(target)) {
-      throw new Error(`refusing to replace unmanaged Claude plugin: ${target}`);
-    }
-    if (entries.length > 0) removeTree(target);
-  }
-  ensureDir(target);
-
+function buildStaging(repoRoot, staging, target) {
   const report = { target, copied: {}, config: { updated: false } };
-  report.copied.commands = copyCommands(repoRoot, target);
-  report.copied.skills = copySkills(repoRoot, target, skillsForRuntime('claude'));
-  report.copied.agents = copyTree(path.join(repoRoot, 'agents'), path.join(target, 'agents'));
+  report.copied.commands = copyCommands(repoRoot, staging);
+  report.copied.skills = copySkills(repoRoot, staging, skillsForRuntime('claude'));
+  report.copied.agents = copyTree(path.join(repoRoot, 'agents'), path.join(staging, 'agents'));
 
-  ensureDir(path.join(target, 'hooks'));
+  ensureDir(path.join(staging, 'hooks'));
   report.copied.hooks = [];
   for (const name of WORKFLOW_HOOK_FILES) {
-    fs.copyFileSync(path.join(repoRoot, 'hooks', name), path.join(target, 'hooks', name));
+    fs.copyFileSync(path.join(repoRoot, 'hooks', name), path.join(staging, 'hooks', name));
     report.copied.hooks.push(name);
   }
-  writeAtomic(path.join(target, 'hooks', 'hooks.json'), JSON.stringify(buildHooksManifest(), null, 2) + '\n');
+  writeAtomic(path.join(staging, 'hooks', 'hooks.json'), JSON.stringify(buildHooksManifest(), null, 2) + '\n');
 
-  const runtime = buildMcpRuntime(repoRoot, target, { runtime: 'claude' });
-  writeAtomic(path.join(target, '.mcp.json'), JSON.stringify({
+  buildMcpRuntime(repoRoot, staging, { runtime: 'claude' });
+  const command = mcpCommand(path.join(target, 'runtime', 'launch.cjs'));
+  writeAtomic(path.join(staging, '.mcp.json'), JSON.stringify({
     mcpServers: {
       [MCP_SERVER_NAME]: {
-        command: process.execPath,
-        args: [runtime.launcher],
+        command: command.command,
+        args: command.args,
       },
     },
   }, null, 2) + '\n');
 
   const pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8'));
-  writeAtomic(path.join(target, '.claude-plugin', 'plugin.json'), JSON.stringify({
+  writeAtomic(path.join(staging, '.claude-plugin', 'plugin.json'), JSON.stringify({
     name: PLUGIN_NAME,
     version: pkg.version,
-    description: 'Claude Code native Ultra Builder Pro workflows, agents, hooks, and MCP task state.',
+    description: 'Claude Code native Ultra Builder Pro workflows with a persistent safety kernel.',
     author: { name: typeof pkg.author === 'string' ? pkg.author : 'Ultra Builder Pro contributors' },
     repository: pkg.homepage,
     license: pkg.license || 'MIT',
   }, null, 2) + '\n');
-  markManaged(target, { adapter: 'claude', plugin: PLUGIN_NAME });
+  markManaged(staging, { adapter: 'claude', plugin: PLUGIN_NAME });
   const source = provenance.packageSource(repoRoot);
-  const provenanceFile = path.join(target, PROVENANCE_FILE);
+  const provenanceFile = path.join(staging, PROVENANCE_FILE);
   report.provenance = provenance.writeProvenance({
     file: provenanceFile,
     adapter: 'claude',
     ...source,
     roots: { plugin: target },
-    assets: provenance.assetRefsForTree('plugin', target, {
+    assetRoots: { plugin: staging },
+    assets: provenance.assetRefsForTree('plugin', staging, {
       exclude: ['.ubp-managed', PROVENANCE_FILE],
     }),
     contracts: {
       plugin_manifest: { root: 'plugin', path: '.claude-plugin/plugin.json' },
       mcp_registration: { root: 'plugin', path: '.mcp.json' },
       mcp_launcher: { root: 'plugin', path: 'runtime/launch.cjs' },
+      native_runtime: { root: 'plugin', path: 'runtime/native-runtime.json' },
+      context_envelope_helper: { root: 'plugin', path: 'runtime/hook-context.cjs' },
       hook_event_helper: { root: 'plugin', path: 'runtime/hook-event.cjs' },
       hooks_manifest: { root: 'plugin', path: 'hooks/hooks.json' },
       checkpoint_hook: { root: 'plugin', path: 'hooks/workflow_checkpoint.py' },
       resume_hook: { root: 'plugin', path: 'hooks/workflow_resume.py' },
     },
   });
-  report.provenance.file = provenanceFile;
+  report.provenance.file = path.join(target, PROVENANCE_FILE);
   return report;
 }
 
+function install(ctx = {}) {
+  const target = resolvePluginRoot(ctx);
+  const repoRoot = resolveRepoRoot(ctx);
+  if (fs.existsSync(target)) {
+    const entries = fs.readdirSync(target);
+    if (entries.length > 0 && !isManaged(target)) {
+      throw new Error(`refusing to replace unmanaged Claude plugin: ${target}`);
+    }
+  }
+  ensureDir(path.dirname(target));
+  const staging = fs.mkdtempSync(path.join(path.dirname(target), `.${PLUGIN_NAME}-staging-`));
+  const backup = `${staging}-previous`;
+  let movedPrevious = false;
+  let published = false;
+  try {
+    const report = buildStaging(repoRoot, staging, target);
+    if (fs.existsSync(target)) {
+      fs.renameSync(target, backup);
+      movedPrevious = true;
+    }
+    fs.renameSync(staging, target);
+    published = true;
+    if (movedPrevious) removeTree(backup);
+    return report;
+  } catch (error) {
+    if (published && fs.existsSync(target)) removeTree(target);
+    else if (fs.existsSync(staging)) removeTree(staging);
+    if (movedPrevious && fs.existsSync(backup)) fs.renameSync(backup, target);
+    throw error;
+  }
+}
+
 function doctor(ctx = {}) {
   const repoRoot = resolveRepoRoot(ctx);
   const source = provenance.packageSource(repoRoot);
-  return provenance.inspectProvenance({
+  const report = provenance.inspectProvenance({
     file: path.join(resolvePluginRoot(ctx), PROVENANCE_FILE),
     expectedAdapter: 'claude',
     expectedPackageVersion: source.packageInfo.version,
   });
+  return applyNativeDoctor(report, path.join(resolvePluginRoot(ctx), 'runtime'));
 }
 
 function uninstall(ctx = {}) {