nativesoul 0.1.0

package/plugins/grok-nativesoul/commands/nativesoul-explore.md

@@ -0,0 +1,22 @@
+# nativesoul-explore
+
+Explore the current project with NativeSoul context.
+
+Default policy: read-only and bounded. Do not edit files, install packages, start services, create schedulers, or perform external writes.
+
+1. Call MCP `life_bootstrap` with `host="grok"`.
+2. Inspect readiness with:
+
+```bash
+nativesoul dashboard data --host grok --limit 25 --json
+```
+
+3. Scope discovery to the operator request. Prefer targeted local reads:
+
+```bash
+rg --files
+rg "<specific term from the task>"
+```
+
+4. Avoid broad unbounded scans. If a write is needed, stop and ask for normal approval.
+

package/plugins/grok-nativesoul/commands/nativesoul-heartbeat.md

@@ -0,0 +1,9 @@
+# nativesoul-heartbeat
+
+Run a heartbeat tick without creating a hidden scheduler:
+
+1. Claim a lease with host `grok`.
+2. If the result is `HEARTBEAT_OK`, stay silent.
+3. Complete only leases won by Grok.
+
+Native schedule status remains `native_schedule_supported=false` until Grok documents an official scheduler surface.

package/plugins/grok-nativesoul/commands/nativesoul-plan.md

@@ -0,0 +1,23 @@
+# nativesoul-plan
+
+Build a NativeSoul-aware plan for the current Grok task.
+
+Default policy: read-only.
+
+1. Call MCP `life_bootstrap` with `host="grok"` and the current working directory.
+2. Read dashboard state:
+
+```bash
+nativesoul dashboard data --host grok --limit 25 --json
+```
+
+3. Read commitments and capabilities when relevant:
+
+```bash
+nativesoul commitments list --project <project-id> --status open --limit 25 --json
+nativesoul capabilities list --host grok --limit 25 --json
+```
+
+4. Separate implemented, degraded/fallback, and approval-required work.
+5. Do not mutate schedules, memory, policy, or files without explicit approval.
+

package/plugins/grok-nativesoul/commands/nativesoul-recall.md

@@ -0,0 +1,16 @@
+# nativesoul-recall
+
+Recall NativeSoul project memory and capability context for the current Grok task.
+
+Default policy: read-only.
+
+1. Prefer MCP `life_recall` with `host="grok"` and the current working directory.
+2. If MCP is unavailable, run:
+
+```bash
+nativesoul memory recall-hook --host grok --cwd "$PWD" --prompt "<task query>" --limit 8 --json
+```
+
+3. Treat recovered memory as advisory and verify against files.
+4. Report readiness honestly as `ready`, `full native capability`, `official-fallback`, or `degraded`.
+

package/plugins/grok-nativesoul/commands/nativesoul-start.md

@@ -0,0 +1,9 @@
+# nativesoul-start
+
+Call MCP `life_bootstrap` with `host="grok"` and the current working directory.
+
+If MCP is unavailable, run:
+
+```bash
+nativesoul bootstrap --host grok --cwd "$PWD" --format inject --json
+```

package/plugins/grok-nativesoul/hooks/hooks.json

@@ -0,0 +1,59 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$GROK_PLUGIN_ROOT/shared/hooks/host-hook.cjs\" session-start --host grok --project-env GROK_WORKSPACE_ROOT",
+            "timeout": 9
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$GROK_PLUGIN_ROOT/shared/hooks/host-hook.cjs\" prompt-bootstrap --host grok --project-env GROK_WORKSPACE_ROOT",
+            "timeout": 9
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$GROK_PLUGIN_ROOT/shared/hooks/host-hook.cjs\" pre-tool-use --host grok --project-env GROK_WORKSPACE_ROOT",
+            "timeout": 9
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$GROK_PLUGIN_ROOT/shared/hooks/host-hook.cjs\" memory-flush --host grok --project-env GROK_WORKSPACE_ROOT",
+            "timeout": 9
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$GROK_PLUGIN_ROOT/shared/hooks/host-hook.cjs\" memory-flush --host grok --project-env GROK_WORKSPACE_ROOT",
+            "timeout": 9
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/grok-nativesoul/nativesoul-package.json

@@ -0,0 +1,22 @@
+{
+  "name": "grok-nativesoul",
+  "version": "0.1.0",
+  "nativeSoul": {
+    "host": "grok",
+    "packageKind": "native-plugin",
+    "nativeHooksSupported": true,
+    "nativeSchedulerSupported": false,
+    "mcpServer": {
+      "name": "nativesoul",
+      "command": "nativesoul-mcp",
+      "args": []
+    },
+    "commands": [
+      "nativesoul-start",
+      "nativesoul-heartbeat",
+      "nativesoul-recall",
+      "nativesoul-plan",
+      "nativesoul-explore"
+    ]
+  }
+}

package/plugins/grok-nativesoul/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "nativesoul",
+  "version": "0.1.0",
+  "description": "NativeSoul continuity, memory, policy, and MCP bootstrap for Grok."
+}

package/plugins/shared/hooks/host-hook.cjs

@@ -0,0 +1,207 @@
+'use strict';
+
+const lib = require('./lib.cjs');
+const policy = require('./policy-fail-closed.cjs');
+
+const kind = (process.argv[2] || 'session-start').trim();
+const options = parseOptions(process.argv.slice(3));
+const host = (options.host || process.env.NATIVESOUL_HOOK_HOST || 'codex').trim();
+const projectEnv = (options.projectEnv || process.env.NATIVESOUL_PROJECT_ENV || defaultProjectEnv(host)).trim();
+const eventName = (options.event || process.env.NATIVESOUL_HOOK_EVENT_NAME || '').trim();
+
+function parseOptions(args) {
+  const parsed = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--host' && args[index + 1]) {
+      parsed.host = args[index + 1];
+      index += 1;
+      continue;
+    }
+    if (arg === '--project-env' && args[index + 1]) {
+      parsed.projectEnv = args[index + 1];
+      index += 1;
+      continue;
+    }
+    if (arg === '--event' && args[index + 1]) {
+      parsed.event = args[index + 1];
+      index += 1;
+    }
+  }
+  return parsed;
+}
+
+function defaultProjectEnv(currentHost) {
+  if (currentHost === 'codex') {
+    return 'CODEX_PROJECT_DIR';
+  }
+  if (currentHost === 'grok') {
+    return 'GROK_WORKSPACE_ROOT';
+  }
+  if (currentHost === 'gemini' || currentHost === 'antigravity') {
+    return 'GEMINI_CWD';
+  }
+  return 'CLAUDE_PROJECT_DIR';
+}
+
+function jsonOutput(value) {
+  process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+
+function hookEventName(input, fallback) {
+  return eventName || input.hook_event_name || input.hookEventName || input.event_name || input.eventName || process.env.GROK_HOOK_EVENT || fallback;
+}
+
+function bootstrapContext(cwd) {
+  const injectArgs = lib.appendHomeArg(['bootstrap', '--host', host, '--cwd', cwd, '--format', 'inject', '--json']);
+  const inject = lib.spawnNativeSoul(injectArgs);
+  const injectJson = lib.parseJsonStdout(inject);
+  if (injectJson && typeof injectJson.content === 'string') {
+    return {
+      content: injectJson.content,
+      degraded: false,
+      source: 'inject',
+      warnings: Array.isArray(injectJson.warnings) ? injectJson.warnings : []
+    };
+  }
+
+  const cacheArgs = lib.appendHomeArg(['bootstrap', '--host', host, '--cwd', cwd, '--format', 'cache', '--json']);
+  const cache = lib.spawnNativeSoul(cacheArgs);
+  const cacheJson = lib.parseJsonStdout(cache);
+  if (cacheJson && typeof cacheJson.content === 'string') {
+    return {
+      content: cacheJson.content,
+      degraded: true,
+      source: 'cache',
+      warnings: Array.isArray(cacheJson.warnings) ? cacheJson.warnings : []
+    };
+  }
+
+  return null;
+}
+
+function outputBootstrapContext(input, fallbackEvent) {
+  const cwd = lib.resolveProjectDir(input, projectEnv);
+  const context = bootstrapContext(cwd);
+  if (!context || context.content.trim().length === 0) {
+    return;
+  }
+  const hookName = hookEventName(input, fallbackEvent);
+  jsonOutput({
+    context: context.content,
+    degraded: context.degraded,
+    source: context.source,
+    warnings: context.warnings,
+    hookSpecificOutput: {
+      hookEventName: hookName,
+      additionalContext: context.content
+    }
+  });
+}
+
+function runRecallHook(input) {
+  const prompt = input.prompt || input.userPrompt || input.message || '';
+  if (typeof prompt !== 'string' || prompt.trim().length === 0) {
+    return null;
+  }
+  const cwd = lib.resolveProjectDir(input, projectEnv);
+  const args = lib.appendHomeArg(['memory', 'recall-hook', '--host', host, '--cwd', cwd, '--json']);
+  const result = lib.spawnNativeSoul(args, { input: `${JSON.stringify(input)}\n` });
+  const json = lib.parseJsonStdout(result);
+  if (!json || typeof json.context !== 'string' || json.context.trim().length === 0) {
+    return null;
+  }
+  return json.context.trim();
+}
+
+function recallContext(input) {
+  const recall = runRecallHook(input);
+  if (!recall) {
+    return;
+  }
+  jsonOutput({
+    hookSpecificOutput: {
+      hookEventName: hookEventName(input, 'UserPromptSubmit'),
+      additionalContext: recall
+    }
+  });
+}
+
+function outputPromptBootstrap(input, fallbackEvent) {
+  const cwd = lib.resolveProjectDir(input, projectEnv);
+  const bootstrap = bootstrapContext(cwd);
+  const recall = runRecallHook(input);
+  const parts = [];
+  if (bootstrap && typeof bootstrap.content === 'string' && bootstrap.content.trim().length > 0) {
+    parts.push(bootstrap.content.trim());
+  }
+  if (recall) {
+    parts.push(recall);
+  }
+  if (parts.length === 0) {
+    return;
+  }
+  const combined = parts.join('\n\n');
+  const hookName = hookEventName(input, fallbackEvent);
+  jsonOutput({
+    context: combined,
+    degraded: bootstrap ? bootstrap.degraded : false,
+    source: bootstrap ? bootstrap.source : 'recall',
+    warnings: bootstrap && Array.isArray(bootstrap.warnings) ? bootstrap.warnings : [],
+    hookSpecificOutput: {
+      hookEventName: hookName,
+      additionalContext: combined
+    }
+  });
+}
+
+function evaluatePreToolUse(input) {
+  const cwd = lib.resolveProjectDir(input, projectEnv);
+  const payload = JSON.stringify(input);
+  const args = lib.appendHomeArg(['policy', 'evaluate-pre-tool-use', '--host', host, '--cwd', cwd, '--json']);
+  const cliResult = lib.spawnNativeSoul(args, { input: payload });
+  const result = lib.parseJsonStdout(cliResult) || policy.evaluate(input);
+  const output = lib.buildPreToolUseHookOutput(result);
+  if (output) {
+    jsonOutput({
+      ...output,
+      hookSpecificOutput: {
+        ...output.hookSpecificOutput,
+        hookEventName: hookEventName(input, 'PreToolUse')
+      }
+    });
+  }
+}
+
+function flushMemory(input) {
+  const cwd = lib.resolveProjectDir(input, projectEnv);
+  const args = lib.appendHomeArg(['memory', 'flush-hook', '--host', host, '--cwd', cwd, '--json']);
+  const result = lib.spawnNativeSoul(args, { input: JSON.stringify(input) });
+  const json = lib.parseJsonStdout(result);
+  if (json) {
+    jsonOutput({ nativeSoul: json });
+  }
+}
+
+lib.runNonBlocking(async () => {
+  const input = await lib.readStdin({ fallback: (raw) => ({ raw }) });
+  if (kind === 'session-start') {
+    outputBootstrapContext(input, 'SessionStart');
+    return;
+  }
+  if (kind === 'prompt-bootstrap') {
+    outputPromptBootstrap(input, 'UserPromptSubmit');
+    return;
+  }
+  if (kind === 'recall') {
+    recallContext(input);
+    return;
+  }
+  if (kind === 'pre-tool-use') {
+    evaluatePreToolUse(input);
+    return;
+  }
+  if (kind === 'memory-flush') {
+    flushMemory(input);
+  }
+});

package/plugins/shared/hooks/lib.cjs

@@ -0,0 +1,279 @@
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DEFAULT_HOOK_TIMEOUT_MS = 9000;
+const PROJECT_CACHE_DIR = '.nativesoul-cache';
+
+function claudeDesktopConfigPath(homeDir) {
+  if (process.platform === 'darwin') {
+    return path.join(homeDir, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+  }
+  if (process.platform === 'win32') {
+    const appData = process.env.APPDATA && process.env.APPDATA.trim().length > 0
+      ? process.env.APPDATA
+      : path.join(homeDir, 'AppData', 'Roaming');
+    return path.join(appData, 'Claude', 'claude_desktop_config.json');
+  }
+  const configHome = process.env.XDG_CONFIG_HOME && process.env.XDG_CONFIG_HOME.trim().length > 0
+    ? process.env.XDG_CONFIG_HOME
+    : path.join(homeDir, '.config');
+  return path.join(configHome, 'Claude', 'claude_desktop_config.json');
+}
+
+function defaultMcpConfigCandidates(homeDir) {
+  return [
+    path.join(homeDir, '.claude', 'mcp.json'),
+    path.join(homeDir, '.claude.json'),
+    path.join(homeDir, '.codex', 'mcp.json'),
+    path.join(homeDir, '.gemini', 'settings.json'),
+    path.join(homeDir, '.gemini', 'mcp.json'),
+    path.join(homeDir, '.gemini', 'config', 'mcp_config.json'),
+    path.join(homeDir, '.gemini', 'antigravity-cli', 'mcp_config.json'),
+    path.join(homeDir, '.gemini', 'antigravity', 'mcp_config.json'),
+    path.join(homeDir, '.gemini', 'antigravity-ide', 'mcp_config.json'),
+    path.join(homeDir, '.grok', 'mcp.json'),
+    path.join(homeDir, '.antigravity', 'mcp.json'),
+    claudeDesktopConfigPath(homeDir)
+  ];
+}
+
+function resolveNativeSoulCli(options = {}) {
+  if (process.env.NATIVESOUL_CLI) {
+    return process.env.NATIVESOUL_CLI;
+  }
+  const homeDir = process.env.HOME || process.env.USERPROFILE;
+  if (!homeDir) {
+    return 'nativesoul';
+  }
+  const candidates = options.configPaths ?? defaultMcpConfigCandidates(homeDir);
+  for (const configPath of candidates) {
+    try {
+      if (fs.existsSync(configPath)) {
+        const content = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        const mcpCommand = content?.mcpServers?.['nativesoul']?.command;
+        if (typeof mcpCommand === 'string' && mcpCommand.includes('nativesoul-mcp')) {
+          const cliCommand = mcpCommand.replace('nativesoul-mcp', 'nativesoul');
+          if (fs.existsSync(cliCommand)) {
+            return cliCommand;
+          }
+        }
+      }
+    } catch {
+      // Ignore malformed MCP config.
+    }
+  }
+  return 'nativesoul';
+}
+
+function readStdin(options = {}) {
+  const fallback = options.fallback ?? (() => ({}));
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on('end', () => {
+      if (data.trim().length === 0) {
+        resolve({});
+        return;
+      }
+      try {
+        resolve(JSON.parse(data));
+      } catch {
+        resolve(fallback(data));
+      }
+    });
+  });
+}
+
+function resolveProjectDir(input, envVarName) {
+  const common = input && !Array.isArray(input) && typeof input === 'object'
+    ? input.common
+    : null;
+  const commonWorkspace = common && !Array.isArray(common) && typeof common === 'object'
+    ? common.workspaceRoot || common.workspace_root || (Array.isArray(common.workspacePaths) ? common.workspacePaths[0] : null) || (Array.isArray(common.workspace_paths) ? common.workspace_paths[0] : null)
+    : null;
+  return input.cwd ||
+    input.workspaceRoot ||
+    input.workspace_root ||
+    input.project_dir ||
+    commonWorkspace ||
+    process.env.NATIVESOUL_CWD ||
+    process.env[envVarName] ||
+    process.env.CLAUDE_PROJECT_DIR ||
+    process.env.GROK_WORKSPACE_ROOT ||
+    process.env.GEMINI_CWD ||
+    process.env.GEMINI_PROJECT_DIR ||
+    process.cwd();
+}
+
+function appendHomeArg(args) {
+  const home = process.env.NATIVESOUL_HOME;
+  if (home && home.trim().length > 0) {
+    args.push('--home', home.trim());
+  }
+  return args;
+}
+
+function spawnNativeSoul(args, options = {}) {
+  const command = resolveNativeSoulCli(options.resolveOptions);
+  const isNodeScript = /\.(?:cjs|mjs|js)$/iu.test(command);
+  const spawnCommand = isNodeScript ? process.execPath : command;
+  const spawnArgs = isNodeScript ? [command, ...args] : args;
+  const shell = process.platform === 'win32' && /\.(?:cmd|bat)$/iu.test(spawnCommand);
+  return spawnSync(spawnCommand, spawnArgs, {
+    input: options.input,
+    encoding: 'utf8',
+    timeout: options.timeout ?? DEFAULT_HOOK_TIMEOUT_MS,
+    env: process.env,
+    stdio: options.stdio ?? ['pipe', 'pipe', 'pipe'],
+    shell
+  });
+}
+
+function projectFallbackBootstrapHome(cwd) {
+  return path.join(cwd, PROJECT_CACHE_DIR);
+}
+
+function projectBootstrapCachePath(cwd, host) {
+  return path.join(projectFallbackBootstrapHome(cwd), 'generated', host, 'last-context.md');
+}
+
+function hasCacheWriteSkippedWarning(context) {
+  return Array.isArray(context?.warnings) &&
+    context.warnings.some((warning) => typeof warning === 'string' && warning.startsWith('BOOTSTRAP_CACHE_WRITE_SKIPPED:'));
+}
+
+function removeCacheWriteSkippedWarning(content) {
+  const withoutSkipped = content.replace(/^warnings: (.+)$/mu, (_line, value) => {
+    const warnings = String(value)
+      .split(',')
+      .map((item) => item.trim())
+      .filter((item) => item.length > 0 && !item.startsWith('BOOTSTRAP_CACHE_WRITE_SKIPPED:'));
+    return warnings.length > 0 ? `warnings: ${warnings.join(', ')}` : 'warnings: none';
+  });
+  return withoutSkipped.replace(/^degraded: true$/mu, 'degraded: false');
+}
+
+function writeProjectFallbackCache(input) {
+  const { context, cwd, host } = input;
+  if (!context || typeof context.content !== 'string' || !hasCacheWriteSkippedWarning(context)) {
+    return context;
+  }
+  const sanitizedContent = removeCacheWriteSkippedWarning(context.content);
+  try {
+    const targetPath = projectBootstrapCachePath(cwd, host);
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true, mode: 0o700 });
+    const tempPath = path.join(path.dirname(targetPath), `.last-context-${Date.now()}-${process.pid}.tmp`);
+    fs.writeFileSync(tempPath, sanitizedContent, { encoding: 'utf8', mode: 0o600 });
+    fs.renameSync(tempPath, targetPath);
+    const warnings = Array.isArray(context.warnings)
+      ? context.warnings.filter((warning) => typeof warning !== 'string' || !warning.startsWith('BOOTSTRAP_CACHE_WRITE_SKIPPED:'))
+      : [];
+    return {
+      ...context,
+      degraded: false,
+      warnings,
+      content: sanitizedContent,
+      projectFallbackCachePath: targetPath
+    };
+  } catch {
+    return context;
+  }
+}
+
+function readProjectFallbackCache(input) {
+  try {
+    const targetPath = projectBootstrapCachePath(input.cwd, input.host);
+    if (!fs.existsSync(targetPath)) {
+      return null;
+    }
+    const cachedContent = fs.readFileSync(targetPath, 'utf8');
+    const content = [
+      '---',
+      'nativesoul: bootstrap-context-cache',
+      `host: ${input.host}`,
+      `generated_at: ${new Date().toISOString()}`,
+      'degraded: true',
+      'warnings: PROJECT_BOOTSTRAP_CACHE_FALLBACK',
+      '---',
+      '',
+      cachedContent
+    ].join('\n');
+    return {
+      content,
+      degraded: true,
+      warnings: ['PROJECT_BOOTSTRAP_CACHE_FALLBACK'],
+      source: 'nativesoul-project-cache',
+      targetPath
+    };
+  } catch {
+    return null;
+  }
+}
+
+function parseJsonStdout(result) {
+  if (result.status !== 0 || !result.stdout.trim()) {
+    return null;
+  }
+  try {
+    return JSON.parse(result.stdout);
+  } catch {
+    return null;
+  }
+}
+
+function buildPreToolUseHookOutput(result) {
+  if (!result || result.blocked !== true) {
+    return null;
+  }
+  return {
+    decision: 'block',
+    reason: result.message,
+    blocked: true,
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: result.message
+    },
+    nativeSoulPolicy: result
+  };
+}
+
+function runNonBlocking(main, timeoutMs = DEFAULT_HOOK_TIMEOUT_MS) {
+  const timer = setTimeout(() => {
+    process.exit(0);
+  }, timeoutMs + 1000);
+  timer.unref();
+  main()
+    .then(() => {
+      clearTimeout(timer);
+      process.exitCode = 0;
+    })
+    .catch(() => {
+      clearTimeout(timer);
+      process.exitCode = 0;
+    });
+}
+
+module.exports = {
+  DEFAULT_HOOK_TIMEOUT_MS,
+  appendHomeArg,
+  buildPreToolUseHookOutput,
+  claudeDesktopConfigPath,
+  defaultMcpConfigCandidates,
+  parseJsonStdout,
+  projectBootstrapCachePath,
+  projectFallbackBootstrapHome,
+  readStdin,
+  readProjectFallbackCache,
+  resolveNativeSoulCli,
+  resolveProjectDir,
+  runNonBlocking,
+  spawnNativeSoul,
+  writeProjectFallbackCache
+};