@aliyun-es/agentic-context 0.0.0-stage → 0.1.0

package/src/guidance.js

@@ -0,0 +1,60 @@
+import path from 'node:path';
+import { NAME, MARKETPLACE } from './config.js';
+
+export function activationSteps(agent, paths, config) {
+  const name = paths.name || NAME;
+  const plugin = `${name}@${paths.marketplaceName || MARKETPLACE}`;
+  let steps;
+  if (agent === 'codex') {
+    steps = [
+      `Use Codex with the configuration directory ${paths.root}; for CLI, set CODEX_HOME to this directory.`,
+      'Locate the Agentic Context SessionStart, UserPromptSubmit and Stop hooks. Use the native review workflow with user authorization; if tools cannot operate it, direct the user to Codex Desktop Settings > Hooks or /hooks in the CLI conversation, not the shell.',
+      `Review the commands: each Agentic Context hook runs ${path.join(paths.runtime, 'hook.js')} with ${paths.config}. Trust and enable only these reviewed hooks within the user's authorization, then verify their enabled and trusted state.`,
+      'If a new session is needed for execution checks, ask the user to start one and continue verification there. New or changed hook definitions must be reviewed again; plugin installation alone does not grant trust.',
+      'If Agentic Context hooks are missing or blocked by managed policy, check plugin enablement and ask your administrator; do not bypass hook trust.',
+      'Hook guide: https://learn.chatgpt.com/docs/hooks#review-and-trust-hooks',
+    ];
+  } else if (agent === 'claude-code') {
+    steps = [
+      `Use Claude Code with the configuration directory ${paths.root}.`,
+      `Check whether ${plugin} is enabled. If disabled, run claude plugin enable ${plugin} in the shell using the installed configuration directory and scope.`,
+      'Reload the plugin in the current session. If tools cannot do this, ask the user to enter /reload-plugins in that conversation. If a restart is required, obtain confirmation and wait until no task is running. Do not execute conversation slash commands in the shell.',
+      'Inspect the Agentic Context SessionStart, UserPromptSubmit, Stop and PreCompact hooks, including their commands and sources. If the native UI is needed, direct the user to /hooks; this is a read-only inspector, not a per-hook trust screen.',
+      'If hooks remain disabled, check disableAllHooks and managed hook policy with your administrator; do not change unrelated hook permissions.',
+      'Hook guide: https://code.claude.com/docs/en/hooks#the-hooks-menu',
+    ];
+  } else if (agent === 'openclaw') {
+    steps = [
+      `Use the same OpenClaw profile as installation. Confirm openclaw config file points to ${paths.hostConfig}; otherwise set OPENCLAW_STATE_DIR and OPENCLAW_CONFIG_PATH to the installed profile before continuing.`,
+      `Enable Agentic Context in the shell: openclaw plugins enable ${name}`,
+      'If the installed version requests capability consent, review Agentic Context\'s declared capabilities and follow the native confirmation flow with user authorization. Append --accept-capabilities only after approval and only if supported by that version.',
+      `On versions with conversation-hook permissions, authorize Agentic Context: openclaw config set plugins.entries.${name}.hooks.allowConversationAccess true --strict-json`,
+      'If that field is unsupported, follow the installed OpenClaw version\'s plugin permissions; do not manually add an unsupported setting. If policy denies access, ask your administrator.',
+      'Allow the Gateway to reload. If a restart is required, explain that it affects tasks on this Gateway and obtain user confirmation, then run openclaw gateway restart when no task is running.',
+      `Inspect Agentic Context loading and hook warnings: openclaw plugins inspect ${name} --runtime --json. This does not prove that the running Gateway has executed a hook.`,
+      'Hook guide: https://docs.openclaw.ai/plugins/hooks#permissions-and-scope',
+    ];
+  } else if (agent === 'qoder') {
+    steps = [
+      `One qoder installation configures Qoder Desktop, Qoder CLI and Qoder IDE for the same user. The installed directory is ${paths.root}; the default is ~/.qoder. A custom --config-dir only selects where Agentic Context writes files; confirm each host actually reads it. Qoder CLI supports QODER_CONFIG_DIR.`,
+      'New Qoder requires HTTPS for remote MCP connections. If Connectors reports MCP_PROFILE_URL_INSECURE, reinstall with a working HTTPS endpoint. Hook output and a successful service probe do not prove the host loaded the MCP tools.',
+      `Review mcpServers.${name} in ${path.join(paths.root, 'settings.json')} (Desktop/CLI) and ${path.join(paths.root, 'mcp.json')} (IDE). The shared Agentic Context SessionStart, UserPromptSubmit, Stop and PreCompact hooks are registered only in settings.json. Each hook runs ${path.join(paths.runtime, 'hook.js')} with ${paths.config}.`,
+      'Qoder Desktop: inspect Settings > Hooks and Extensions > Connectors, then start a new task.',
+      'Qoder CLI: use /mcp to inspect the connection and /mcp reload to reload it; these are conversation commands, not shell commands. Start a new session after changing hooks.',
+      'Qoder IDE: inspect Qoder IDE Settings > MCP. Restart the IDE to load Hook and Skill changes, after obtaining user confirmation and waiting until no task is running.',
+      'Follow native authorization prompts with user approval; do not broaden global permissions. The three hosts share one Agentic Context connection and auto-capture setting in this directory; do not install extra copies of the Agentic Context hooks.',
+      'If hooks or tools are missing, check the configuration directory, project overrides and managed policy; do not bypass restrictions. Seeing a hook in settings does not prove it executed.',
+      'Hook guides: https://docs.qoder.com/qoder/hooks and https://docs.qoder.com/extensions/hooks; MCP guide: https://docs.qoder.com/cli/mcp-reference',
+    ];
+  } else {
+    steps = [
+      `Use HERMES_HOME=${paths.root}. If a restart is needed to load the provider, obtain user confirmation and wait until no task is running. Then run hermes memory status and confirm the ${name} provider is selected.`,
+    ];
+  }
+  steps.unshift('Continue with activation and verification using the available tools; do not merely return these instructions. Review Agentic Context and use the host native workflow within user authorization. Change only Agentic Context-related settings; preserve other security settings and the installed auto-capture setting. Ask the user for any required confirmation or action that tools cannot perform.');
+  if (config.autoCapture) steps.splice(1, 0, 'Before activating automatic capture, confirm the user has consented to sending new conversation text to the configured Agentic Context. If consent is missing, explain this behavior and ask; these instructions do not grant consent.');
+  steps.push(config.autoCapture
+    ? 'Automatic Memory capture is configured, but hook execution is not verified. After activation, complete a new non-sensitive conversation turn; check the host log for Agentic Context memory submission accepted and its event ID. Poll the event to confirm extraction completed; a manual memory_add call does not verify automatic capture.'
+    : 'Automatic Memory capture is disabled. Enabling the plugin/hooks does not turn capture on.');
+  return steps;
+}

package/src/host.js

@@ -0,0 +1,81 @@
+import fs from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { stripVTControlCharacters } from 'node:util';
+import { userHome, resolveHomePath, platformPath, envValue } from './config.js';
+
+const COMMANDS = { codex: 'codex', 'claude-code': 'claude', openclaw: 'openclaw' };
+
+export function openClawCapabilityArgs(help, acceptCapabilities) {
+  if (!acceptCapabilities) return [];
+  if (!/--accept-capabilities\b/.test(stripVTControlCharacters(help || ''))) {
+    throw new Error('This OpenClaw command does not support --accept-capabilities; use the native capability approval flow.');
+  }
+  return ['--accept-capabilities'];
+}
+
+export function openClawInstallArgs(pluginPath, help, acceptCapabilities = false) {
+  const text = stripVTControlCharacters(help || '').replace(/\s+/g, ' ');
+  if (!/--link\b/.test(text)) throw new Error('Unable to detect OpenClaw linked-install support from plugins install --help');
+  const args = ['plugins', 'install', '--link', pluginPath];
+  // Older versions reject --link with --force; newer ones use it to confirm the source.
+  if (/--force\s+Confirm non-ClawHub sources\b/i.test(text)) args.push('--force');
+  args.push(...openClawCapabilityArgs(help, acceptCapabilities));
+  return args;
+}
+
+export function executableCandidates(agent, { env = process.env, platform = process.platform, execPath = process.execPath } = {}) {
+  const command = COMMANDS[agent];
+  if (!command) return [];
+  const p = platformPath(platform);
+  const get = name => envValue(env, name, platform);
+  const home = userHome(env, platform);
+  const prefix = get('npm_config_prefix') || get('NPM_CONFIG_PREFIX');
+  const directories = [
+    ...(get('PATH') || '').split(p.delimiter).filter(Boolean).map(dir => platform === 'win32' ? dir.replace(/^"(.*)"$/, '$1') : dir),
+    p.dirname(execPath),
+    p.join(home, '.local', 'bin'),
+    ...(prefix ? [platform === 'win32' ? prefix : p.join(prefix, 'bin')] : []),
+    ...(platform === 'win32' ? [p.join(get('APPDATA') || p.join(home, 'AppData', 'Roaming'), 'npm')]
+      : [p.join(home, '.npm-global/bin'), p.join(home, '.npm/bin'), ...(platform === 'darwin' ? ['/opt/homebrew/bin'] : []), '/usr/local/bin', '/usr/bin', '/bin']),
+  ];
+  if (agent === 'openclaw') directories.push(p.join(get('OPENCLAW_PREFIX') || p.join(home, '.openclaw'), 'bin'));
+  const extensions = (get('PATHEXT') || '.COM;.EXE;.BAT;.CMD').split(';').filter(ext => /^\.(com|exe|bat|cmd)$/i.test(ext));
+  const names = platform === 'win32' ? [...new Set([...extensions, '.EXE', '.CMD', '.BAT'].map(ext => `${command}${ext.toLowerCase()}`))] : [command];
+  const candidates = directories.flatMap(dir => names.map(name => resolveHomePath(p.join(dir, name), home, platform)));
+  if (agent === 'codex' && platform === 'darwin') {
+    for (const dir of [p.join(home, 'Applications'), '/Applications']) {
+      for (const app of ['Codex.app', 'ChatGPT.app']) candidates.push(p.join(dir, app, 'Contents/Resources/codex'));
+    }
+  }
+  return [...new Set(candidates)];
+}
+
+export async function resolveExecutable(agent, options = {}) {
+  if (!COMMANDS[agent]) return undefined;
+  if (options.agentBin) {
+    return /[\\/]/.test(options.agentBin) ? resolveHomePath(options.agentBin, userHome(options.env, options.platform), options.platform) : options.agentBin;
+  }
+  for (const candidate of executableCandidates(agent, options)) {
+    try {
+      if (!(await fs.stat(candidate)).isFile()) continue;
+      await fs.access(candidate, (options.platform || process.platform) === 'win32' ? constants.F_OK : constants.X_OK);
+      return candidate;
+    } catch (error) {
+      if (!['ENOENT', 'ENOTDIR', 'EACCES'].includes(error.code)) throw error;
+    }
+  }
+  throw new Error(`Could not find ${COMMANDS[agent]}. Install the agent first and rerun; for a custom installation, use --agent-bin <path>.`);
+}
+
+export function hostEnvironment(agent, paths, source = process.env) {
+  const env = { ...source };
+  if (agent === 'codex') env.CODEX_HOME = paths.root;
+  if (agent === 'claude-code') env.CLAUDE_CONFIG_DIR = paths.root;
+  if (agent === 'hermes') env.HERMES_HOME = paths.root;
+  if (agent === 'qoder') env.QODER_CONFIG_DIR = paths.root;
+  if (agent === 'openclaw') {
+    env.OPENCLAW_STATE_DIR = paths.root;
+    env.OPENCLAW_CONFIG_PATH = paths.hostConfig;
+  }
+  return env;
+}

package/src/installer.js

@@ -0,0 +1,459 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import spawn from 'cross-spawn';
+import { agentPaths, legacyAgentPaths, installationPaths, validateConnection, publicConnection, NAME, MARKETPLACE, LEGACY_NAME, LEGACY_MARKETPLACE, VERSION } from './config.js';
+import { readJson, writePrivate, readDocument, editSetting, restoreSettings, getAt, equal } from './files.js';
+import { preparePayload, mcpServer, hookConfig, requiredPayloadFiles } from './payload.js';
+import { probeMcp } from './mcp.js';
+import { hostEnvironment, resolveExecutable, openClawInstallArgs, openClawCapabilityArgs } from './host.js';
+import { createRedactor, redact } from './redact.js';
+import { activationSteps } from './guidance.js';
+
+export async function runCommand(command, args, env, secrets = []) {
+  try {
+    return await new Promise((resolve, reject) => {
+      const interactive = process.stdin.isTTY;
+      const child = spawn(command, args, { env, stdio: [interactive ? 'inherit' : 'ignore', 'pipe', 'pipe'], timeout: 120000 });
+      const chunks = { stdout: [], stderr: [] };
+      let bytes = 0, overflow = false;
+      const redactors = ['stdout', 'stderr'].map(stream => {
+        const filter = createRedactor(secrets, text => {
+          chunks[stream].push(text);
+          if (interactive) process.stderr.write(text);
+        });
+        child[stream].setEncoding('utf8');
+        child[stream].on('data', chunk => {
+          bytes += Buffer.byteLength(chunk);
+          if (bytes > 1024 * 1024) { overflow = true; child.kill(); }
+          else filter(chunk);
+        });
+        return filter;
+      });
+      child.on('error', reject);
+      child.on('close', (code, signal) => {
+        for (const filter of redactors) filter('', true);
+        const output = Object.fromEntries(Object.entries(chunks).map(([key, value]) => [key, value.join('')]));
+        if (code === 0 && !overflow) resolve(output);
+        else reject(Object.assign(new Error(overflow ? 'Host output exceeds 1 MiB' : 'Host command failed'), output, { code: overflow ? 'MAX_BUFFER' : code ?? signal }));
+      });
+    });
+  }
+  catch (error) {
+    const detail = ['stdout', 'stderr'].filter(stream => error[stream]?.trim())
+      .map(stream => `${stream}: ${error[stream].trim().slice(-2000)}`).join('\n') || error.message;
+    const message = redact(`${path.basename(command)} ${args.slice(0, 3).join(' ')} failed (${error.code ?? 'timeout'}): ${detail}`, secrets);
+    const failure = new Error(message);
+    failure.code = error.code;
+    throw failure;
+  }
+}
+
+async function prepareOwnedFile(file, content, receipt) {
+  const previous = receipt.ownedFiles.find(item => item.path === file);
+  let existing;
+  try { existing = await fs.readFile(file, 'utf8'); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  if (existing !== undefined && (!previous || existing !== previous.content)) throw new Error(`Refusing to overwrite unmanaged or modified file: ${file}`);
+  await writePrivate(file, content);
+  if (previous) previous.content = content; else receipt.ownedFiles.push({ path: file, content });
+}
+
+async function refreshQoderHookEdits(receipt) {
+  if (receipt?.agent !== 'qoder') return;
+  for (const edit of receipt.edits.filter(item => item.keys[0] === 'hooks')) {
+    edit.ownedGroups ??= edit.value.slice((edit.before || []).length);
+    const current = getAt((await readDocument(edit.file)).value, edit.keys);
+    if (!Array.isArray(current) || equal(current, edit.value)) continue;
+    // Agentic Context appends its groups. Preserve changes to other groups without adopting changed Agentic Context hooks.
+    const remaining = [...current];
+    const intact = edit.ownedGroups.every(group => {
+      const index = remaining.findIndex(item => equal(item, group));
+      if (index < 0) return false;
+      remaining.splice(index, 1);
+      return true;
+    });
+    if (!intact) continue;
+    edit.before = remaining.length || edit.before !== undefined ? remaining : undefined;
+    edit.value = current;
+  }
+}
+
+async function exists(file) {
+  try { await fs.access(file); return true; }
+  catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+
+async function findInstallation(agent, options = {}) {
+  const current = agentPaths(agent, options.configDir, options.env);
+  const legacy = legacyAgentPaths(agent, options.configDir, options.env);
+  const [newReceipt, oldReceipt] = await Promise.all([readJson(current.receipt), readJson(legacy.receipt)]);
+  if (newReceipt && oldReceipt) throw new Error('Both current and legacy installations exist; resolve the duplicate installations before continuing.');
+  let paths = oldReceipt ? legacy : current;
+  const receipt = oldReceipt || newReceipt;
+  if (oldReceipt && await exists(current.state)) throw new Error(`Conflicting installation directory: ${current.state}`);
+  if (newReceipt && !oldReceipt && await exists(legacy.state)) throw new Error(`Conflicting legacy installation directory: ${legacy.state}`);
+  if (!receipt && await exists(legacy.state)) throw new Error(`Unmanaged legacy installation directory: ${legacy.state}`);
+  if (receipt) {
+    if (receipt.agent !== agent || receipt.root !== paths.root) throw new Error('Installation receipt does not match this agent/profile');
+    const name = receipt.name || paths.name;
+    if (![NAME, LEGACY_NAME].includes(name)) throw new Error('Unsupported installation identity in receipt');
+    const marketplaceName = name === NAME ? MARKETPLACE : LEGACY_MARKETPLACE;
+    const skillName = name === NAME ? NAME : 'knowledge-engine';
+    if ((receipt.marketplaceName && receipt.marketplaceName !== marketplaceName)
+        || (receipt.skillName && receipt.skillName !== skillName)) throw new Error('Inconsistent installation identity in receipt');
+    paths = installationPaths(paths, { name, marketplaceName, skillName });
+  }
+  return { paths, receipt };
+}
+
+// Keep omitted upgrade options distinct from explicit user changes.
+export async function resolveInstallInput(agent, input = {}) {
+  const { paths, receipt } = await findInstallation(agent, input);
+  let previous = receipt ? await readJson(paths.config) : null;
+  if (receipt && !previous) {
+    const pending = receipt.pendingInitialConnection;
+    const initialWriteFailed = pending && ['PREPARING', 'FAILED'].includes(receipt.status)
+      && !receipt.registered && !receipt.marketplaceAdded && !receipt.migration
+      && receipt.edits.length === 0 && receipt.ownedFiles.length === 0;
+    const explicitConnection = ['endpoint', 'workspace', 'userId', 'apiKey']
+      .every(key => typeof input[key] === 'string' && input[key].trim());
+    if (!initialWriteFailed || !explicitConnection) throw new Error(`Missing connection configuration: ${paths.config}`);
+    previous = pending;
+  }
+  const result = { ...input };
+  for (const key of ['endpoint', 'workspace', 'userId', 'apiKey', 'kbIds', 'autoCapture', 'autoSkill', 'timeoutMs', 'serviceId']) {
+    if (result[key] === undefined && previous?.[key] !== undefined) result[key] = previous[key];
+  }
+  if (input.clearKbs) result.kbIds = [];
+  result.autoCapture ??= true;
+  result.autoSkill ??= false;
+  result.kbIds ??= [];
+  return result;
+}
+
+async function checkMigration(agent, paths, receipt, run, executable, env) {
+  // Validate all owned leaves before unregistering anything. An interrupted
+  // cleanup may already have restored a leaf or removed an owned file.
+  for (const edit of receipt.edits) {
+    const current = getAt((await readDocument(edit.file)).value, edit.keys);
+    if (!equal(current, edit.value) && !equal(current, edit.before)) {
+      throw new Error(`Preserved modified setting: ${edit.file} ${edit.keys.join('.')}`);
+    }
+  }
+  for (const owned of receipt.ownedFiles) {
+    if (await exists(owned.path) && await fs.readFile(owned.path, 'utf8') !== owned.content) {
+      throw new Error(`Preserved modified file: ${owned.path}`);
+    }
+  }
+  const targets = agent === 'openclaw'
+    ? [[paths.hostConfig, ['plugins', 'entries', NAME]], [paths.hostConfig, ['mcp', 'servers', NAME]]]
+    : agent === 'hermes' ? [[path.join(paths.root, 'config.yaml'), ['mcp_servers', NAME]]]
+      : agent === 'qoder' ? [[path.join(paths.root, 'settings.json'), ['mcpServers', NAME]], [path.join(paths.root, 'mcp.json'), ['mcpServers', NAME]]] : [];
+  for (const [file, keys] of targets) {
+    if (getAt((await readDocument(file)).value, keys) !== undefined) throw new Error(`Conflicting target configuration: ${file} ${keys.join('.')}`);
+  }
+  if (['hermes', 'qoder'].includes(agent)) {
+    for (const target of [path.join(paths.root, 'skills', NAME, 'SKILL.md'),
+      ...(agent === 'hermes' ? [path.join(paths.root, 'plugins', NAME)] : [])]) {
+      if (await exists(target)) throw new Error(`Conflicting target path: ${target}`);
+    }
+  }
+  // Avoid moving the capture boundary while a transcript hook is writing it.
+  const captures = path.join(paths.state, 'captures');
+  for (const name of await fs.readdir(captures).catch(error => { if (error.code === 'ENOENT') return []; throw error; })) {
+    if (!name.endsWith('.lock')) continue;
+    const pid = Number(await fs.readFile(path.join(captures, name), 'utf8'));
+    if (pid > 0) {
+      try { process.kill(pid, 0); }
+      catch (error) { if (error.code === 'ESRCH') continue; throw error; }
+      throw new Error('A capture hook is still running; finish the active session before upgrading.');
+    }
+  }
+  if (['codex', 'claude-code'].includes(agent)) {
+    const listing = JSON.parse((await run(executable, ['plugin', 'list', '--json'], env)).stdout);
+    const conflict = value => {
+      if (Array.isArray(value)) return value.some(conflict);
+      if (!value || typeof value !== 'object' || value.installed === false) return false;
+      if (['id', 'name', 'pluginId'].some(key => typeof value[key] === 'string'
+          && (value[key] === NAME || value[key].startsWith(`${NAME}@`) || value[key] === MARKETPLACE))) return true;
+      return Object.values(value).some(conflict);
+    };
+    if (conflict(listing)) throw new Error('A native plugin or marketplace already uses the new identity; preserve it and resolve the conflict before upgrading.');
+    const inventory = JSON.parse((await run(executable, ['plugin', 'marketplace', 'list', '--json'], env)).stdout);
+    const marketplaces = agent === 'codex' ? inventory?.marketplaces : inventory;
+    if (!Array.isArray(marketplaces)
+        || !marketplaces.every(item => item && typeof item.name === 'string' && item.name.length > 0)) {
+      throw new Error('Cannot verify native marketplace inventory; preserve the legacy installation and retry when the inventory is available.');
+    }
+    if (marketplaces.some(item => item.name === MARKETPLACE)) {
+      throw new Error('A native marketplace already uses the new identity; preserve it and resolve the conflict before upgrading.');
+    }
+  }
+}
+
+export async function install(agent, input, dependencies = {}) {
+  if (input.acceptCapabilities && agent !== 'openclaw') throw new Error('--accept-capabilities is only supported for OpenClaw');
+  input = await resolveInstallInput(agent, input);
+  const { paths, receipt: old } = await findInstallation(agent, input);
+  if (paths.legacy && input.prepare) throw new Error('Legacy upgrades do not support --prepare; finish active sessions and run install to upgrade.');
+  const config = validateConnection({ ...input, agent });
+  const run = (command, args, env) => (dependencies.run || runCommand)(command, args, env, [config.apiKey]);
+  const env = hostEnvironment(agent, paths, input.env);
+  if (!old) {
+    try { await fs.access(paths.state); throw new Error(`Unmanaged Agentic Context directory exists: ${paths.state}`); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  if (old && (old.agent !== agent || old.root !== paths.root)) throw new Error('Installation receipt does not match this agent/profile');
+  await refreshQoderHookEdits(old);
+  let replaceMemoryProvider = Boolean(input.replaceMemoryProvider || old?.migration?.replaceMemoryProvider);
+  if (agent === 'hermes' && !input.prepare) {
+    const current = getAt((await readDocument(path.join(paths.root, 'config.yaml'))).value, ['memory', 'provider']);
+    const builtin = ['', 'default', 'builtin', 'built-in', 'none'].includes(String(current ?? '').trim().toLowerCase());
+    replaceMemoryProvider ||= builtin;
+    if (current && current !== NAME && !(paths.legacy && current === LEGACY_NAME) && !replaceMemoryProvider) {
+      throw new Error('Hermes already uses another MemoryProvider. Pass --replace-memory-provider to explicitly switch.');
+    }
+  }
+  let connection;
+  if (!input.skipCheck) {
+    connection = await (dependencies.probe || probeMcp)(config);
+    if (connection.missingTools.length) throw new Error(`MCP is missing required tools: ${connection.missingTools.join(', ')}`);
+  }
+  const executable = input.prepare ? old?.executable : await (dependencies.resolveExecutable || resolveExecutable)(agent, { agentBin: input.agentBin || old?.executable, env });
+  const openclawArgs = agent === 'openclaw' && !input.prepare && (!old?.registered || paths.legacy)
+    ? openClawInstallArgs(paths.legacy ? installationPaths(paths).plugin : paths.plugin, (await run(executable, ['plugins', 'install', '--help'], env)).stdout, input.acceptCapabilities)
+    : undefined;
+  const openclawEnableArgs = agent === 'openclaw' && !input.prepare && input.acceptCapabilities
+    ? openClawCapabilityArgs((await run(executable, ['plugins', 'enable', '--help'], env)).stdout, true)
+    : [];
+  if (paths.legacy) {
+    await checkMigration(agent, paths, old, run, executable, env);
+    old.migration = { ...(old.migration || {}), fromName: LEGACY_NAME, phase: 'cleanup',
+      replaceMemoryProvider: old.migration?.replaceMemoryProvider || (agent === 'hermes' && old.edits.some(edit => equal(edit.keys, ['memory', 'provider']) && edit.value === LEGACY_NAME)) };
+    old.status = 'UPGRADING';
+    await writePrivate(paths.receipt, old);
+    const removed = await removeManagedInstallation(agent, paths, old, input, dependencies, { keepState: true });
+    if (removed.status !== 'DETACHED') throw new Error(`Legacy upgrade stopped: ${removed.warnings.join('; ')}`);
+    Object.assign(old, { name: NAME, marketplaceName: MARKETPLACE, skillName: NAME,
+      status: 'UPGRADING', migration: { ...old.migration, phase: 'install' } });
+    await writePrivate(paths.receipt, old);
+    const result = await install(agent, { ...input, skipCheck: true }, dependencies);
+    if (connection) result.connection = connection;
+    return result;
+  }
+  const receipt = old || { agent, root: paths.root, edits: [], ownedFiles: [], createdAt: new Date().toISOString() };
+  const previousConfig = await readJson(paths.config);
+  Object.assign(config, { stateDir: paths.state, installedAt: previousConfig?.installedAt || new Date().toISOString() });
+  if ((!previousConfig?.autoCapture && config.autoCapture) || (!previousConfig?.autoSkill && config.autoSkill)
+      || ['endpoint', 'workspace', 'userId'].some(key => previousConfig?.[key] !== config[key])) config.installedAt = new Date().toISOString();
+  Object.assign(receipt, { name: NAME, marketplaceName: MARKETPLACE, skillName: NAME, version: VERSION, status: 'PREPARING', updatedAt: new Date().toISOString(), executable });
+  if (!old) {
+    receipt.pendingInitialConnection = Object.fromEntries(['kbIds', 'autoCapture', 'autoSkill', 'timeoutMs', 'serviceId']
+      .map(key => [key, config[key]]));
+  }
+  const persist = () => writePrivate(paths.receipt, receipt);
+  const edit = async (file, keys, value, opts) => {
+    await editSetting(file, keys, value, receipt.edits, opts);
+    await persist();
+  };
+  try { await persist(); }
+  catch (error) {
+    // A failed first receipt write can leave only the directory created by
+    // writePrivate. Remove it only while empty; never remove unknown files.
+    if (!old) await fs.rmdir(paths.state).catch(() => {});
+    throw error;
+  }
+  try {
+    await writePrivate(paths.config, config);
+    if (receipt.pendingInitialConnection) {
+      delete receipt.pendingInitialConnection;
+      await persist();
+    }
+    const skill = await preparePayload(agent, paths, config);
+    if (input.prepare) {
+      receipt.status = 'PREPARED';
+      await persist();
+      return { agent, status: receipt.status, path: paths.state, connection };
+    }
+    if (agent === 'codex' || agent === 'claude-code') {
+      await run(executable, ['plugin', 'marketplace', 'add', paths.marketplace], env);
+      receipt.marketplaceAdded = true;
+      await persist();
+      if (agent === 'codex') {
+        await run(executable, ['plugin', 'add', `${NAME}@${MARKETPLACE}`, '--json'], env);
+      } else {
+        const args = old?.registered ? ['update', `${NAME}@${MARKETPLACE}`] : ['install', `${NAME}@${MARKETPLACE}`, '--scope', 'user'];
+        await run(executable, ['plugin', ...args], env);
+      }
+      receipt.registered = true;
+    } else if (agent === 'openclaw') {
+      const file = paths.hostConfig;
+      if (!old?.registered) {
+        const entry = getAt((await readDocument(file)).value, ['plugins', 'entries', NAME]);
+        if (entry) {
+          if (!old) throw new Error('An unmanaged OpenClaw Agentic Context entry already exists');
+          // A native approval may have completed registration after the Agentic Context attempt failed.
+          const listing = JSON.parse((await run(executable, ['plugins', 'list', '--json'], env)).stdout);
+          const plugin = listing.plugins?.find(item => item.id === NAME);
+          if (!plugin?.source
+              || await fs.realpath(plugin.source) !== await fs.realpath(path.join(paths.plugin, 'index.js'))
+              || (entry.config?.configPath !== undefined && entry.config.configPath !== paths.config)) {
+            throw new Error('An unmanaged OpenClaw Agentic Context entry already exists');
+          }
+        } else {
+          await run(executable, openclawArgs, env);
+        }
+        receipt.registered = true;
+        await persist();
+      }
+      await edit(file, ['plugins', 'entries', NAME, 'config'], { configPath: paths.config });
+      await run(executable, ['plugins', 'enable', NAME, ...openclawEnableArgs], env);
+      await edit(file, ['plugins', 'entries', NAME, 'enabled'], true, { replace: true });
+      await edit(file, ['mcp', 'servers', NAME], mcpServer(config, agent));
+    } else if (agent === 'hermes') {
+      const file = path.join(paths.root, 'config.yaml');
+      for (const name of ['__init__.py', 'plugin.yaml']) {
+        await prepareOwnedFile(path.join(paths.root, 'plugins', NAME, name), await fs.readFile(path.join(paths.plugin, 'provider', name), 'utf8'), receipt);
+        await persist();
+      }
+      await prepareOwnedFile(path.join(paths.root, 'skills', NAME, 'SKILL.md'), skill, receipt);
+      await persist();
+      await edit(file, ['memory', 'provider'], NAME, { replace: replaceMemoryProvider });
+      await edit(file, ['mcp_servers', NAME], mcpServer(config, agent));
+    } else if (agent === 'qoder') {
+      const file = path.join(paths.root, 'settings.json');
+      await edit(file, ['mcpServers', NAME], mcpServer(config, agent));
+      // Desktop/CLI read settings.json; Qoder IDE reads the separate MCP file.
+      await edit(path.join(paths.root, 'mcp.json'), ['mcpServers', NAME], mcpServer(config, agent));
+      for (const [event, groups] of Object.entries(hookConfig(paths, agent).hooks)) {
+        const keys = ['hooks', event];
+        const previous = receipt.edits.find(item => item.file === file && equal(item.keys, keys));
+        const original = previous ? previous.before : getAt((await readDocument(file)).value, keys);
+        if (original !== undefined && !Array.isArray(original)) throw new Error(`Qoder hooks.${event} must be an array`);
+        // Preserve other hooks, including groups added since the previous installation.
+        await edit(file, keys, [...(original || []), ...groups], { replace: true });
+        receipt.edits.find(item => item.file === file && equal(item.keys, keys)).ownedGroups = groups;
+        await persist();
+      }
+      await prepareOwnedFile(path.join(paths.root, 'skills', NAME, 'SKILL.md'), skill, receipt);
+      await persist();
+    }
+    if (receipt.migration) {
+      await fs.rm(path.join(paths.marketplace, 'plugins', LEGACY_NAME), { recursive: true, force: true });
+      delete receipt.migration;
+    }
+    receipt.status = 'CONFIGURED';
+    await persist();
+    return { agent, status: 'CONFIGURED', connection, path: paths.state,
+      hostExecution: 'NOT_VERIFIED', nextSteps: activationSteps(agent, paths, config) };
+  } catch (error) {
+    receipt.status = 'FAILED';
+    await persist();
+    if (agent === 'openclaw' && !input.acceptCapabilities && /capability consent|--accept-capabilities/i.test(error.message)) {
+      error.message += `\nReview Agentic Context at ${paths.plugin}; after approving its capabilities, rerun the same Agentic Context install command with --accept-capabilities. Native approval in the same OpenClaw profile can also be completed before rerunning Agentic Context.`;
+    }
+    throw error;
+  }
+}
+
+export async function status(agent, options = {}, dependencies = {}) {
+  const { paths, receipt } = await findInstallation(agent, options);
+  if (!receipt) return { agent, status: 'NOT_INSTALLED' };
+  await refreshQoderHookEdits(receipt);
+  const config = await readJson(paths.config);
+  const drift = [];
+  if (!config) drift.push(paths.config);
+  for (const file of requiredPayloadFiles(agent, paths)) {
+    try {
+      if (!(await fs.stat(file)).isFile()) drift.push(file);
+      else await fs.access(file, fs.constants.R_OK);
+    } catch (error) {
+      if (!['ENOENT', 'ENOTDIR', 'EACCES'].includes(error.code)) throw error;
+      drift.push(file);
+    }
+  }
+  if (config && agent === 'qoder') {
+    try { validateConnection({ ...config, agent }); }
+    catch (error) { drift.push(error.message); }
+  }
+  for (const edit of receipt.edits) {
+    if (!equal(getAt((await readDocument(edit.file)).value, edit.keys), edit.value)) drift.push(`${edit.file}: ${edit.keys.join('.')}`);
+  }
+  for (const file of receipt.ownedFiles) {
+    try { if (await fs.readFile(file.path, 'utf8') !== file.content) drift.push(file.path); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; drift.push(file.path); }
+  }
+  return { agent, status: drift.length ? 'CONFIGURATION_CHANGED' : receipt.status, version: receipt.version,
+    configuration: config ? publicConnection(config) : null, path: paths.state, pluginName: paths.name,
+    ...(receipt.migration ? { migration: receipt.migration.phase } : {}), drift, hostExecution: 'NOT_VERIFIED',
+    ...(receipt.status === 'CONFIGURED' && config ? { nextSteps: activationSteps(agent, paths, config) } : {}),
+    ...(options.check && config ? { connection: await (dependencies.probe || probeMcp)(config) } : {}) };
+}
+
+async function removeManagedInstallation(agent, paths, receipt, options, dependencies, { keepState = false } = {}) {
+  await refreshQoderHookEdits(receipt);
+  const config = await readJson(paths.config);
+  const run = (command, args, env) => (dependencies.run || runCommand)(command, args, env, [config?.apiKey]);
+  const env = hostEnvironment(agent, paths, options.env);
+  const executable = receipt.registered || receipt.marketplaceAdded
+    ? await (dependencies.resolveExecutable || resolveExecutable)(agent, { agentBin: options.agentBin || receipt.executable, env }) : undefined;
+  if (receipt.registered && ['codex', 'claude-code'].includes(agent)) {
+    await run(executable, ['plugin', agent === 'codex' ? 'remove' : 'uninstall', `${paths.name}@${paths.marketplaceName}`, ...(agent === 'claude-code' ? ['--scope', 'user'] : ['--json'])], env);
+    receipt.registered = false; await writePrivate(paths.receipt, receipt);
+  }
+  if (receipt.marketplaceAdded) {
+    try {
+      await run(executable, ['plugin', 'marketplace', 'remove', paths.marketplaceName], env);
+    } catch (error) {
+      // Removal may have taken effect before a timeout or interrupted receipt
+      // write. Only an explicit native inventory can prove cleanup completed.
+      let absent = false;
+      try {
+        const listing = JSON.parse((await run(executable, ['plugin', 'marketplace', 'list', '--json'], env)).stdout);
+        const marketplaces = agent === 'codex' ? listing?.marketplaces : Array.isArray(listing) ? listing : null;
+        absent = Array.isArray(marketplaces)
+          && marketplaces.every(item => item && typeof item.name === 'string' && item.name.length > 0)
+          && !marketplaces.some(item => item.name === paths.marketplaceName);
+      } catch { /* Preserve the original removal failure when inventory is unavailable. */ }
+      if (!absent) throw error;
+    }
+    receipt.marketplaceAdded = false; await writePrivate(paths.receipt, receipt);
+  }
+  if (agent === 'openclaw' && receipt.registered) {
+    const keys = ['plugins', 'entries', paths.name, 'config'];
+    const owned = receipt.edits.find(edit => equal(edit.keys, keys));
+    const current = getAt((await readDocument(paths.hostConfig)).value, keys);
+    if (current !== undefined && !equal(current, owned?.value)) {
+      return { agent, status: 'MANUAL_CLEANUP_REQUIRED', warnings: [`Preserved modified setting: ${paths.hostConfig} ${keys.join('.')}`], path: paths.state };
+    }
+    await run(executable, ['plugins', 'uninstall', paths.name, '--force'], env);
+    // The native uninstaller owns the plugin entry; only restore external MCP settings.
+    receipt.edits = receipt.edits.filter(edit => !equal(edit.keys.slice(0, 3), ['plugins', 'entries', paths.name]));
+    receipt.registered = false; await writePrivate(paths.receipt, receipt);
+  }
+  const warnings = await restoreSettings(receipt.edits);
+  if (warnings.length) return { agent, status: 'MANUAL_CLEANUP_REQUIRED', warnings, path: paths.state };
+  for (const file of receipt.ownedFiles) {
+    try {
+      if (await fs.readFile(file.path, 'utf8') === file.content) {
+        await fs.rm(file.path);
+        try { await fs.rmdir(path.dirname(file.path)); } catch (error) { if (!['ENOTEMPTY', 'ENOENT'].includes(error.code)) throw error; }
+      }
+      else warnings.push(`Preserved modified file: ${file.path}`);
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  if (warnings.length) return { agent, status: 'MANUAL_CLEANUP_REQUIRED', warnings, path: paths.state };
+  if (keepState) {
+    receipt.edits = []; receipt.ownedFiles = [];
+    await writePrivate(paths.receipt, receipt);
+    return { agent, status: 'DETACHED' };
+  }
+  await fs.rm(paths.state, { recursive: true });
+  return { agent, status: 'UNINSTALLED', remoteDataDeleted: false };
+}
+
+
+export async function uninstall(agent, options = {}, dependencies = {}) {
+  const { paths, receipt } = await findInstallation(agent, options);
+  if (!receipt) return { agent, status: 'NOT_INSTALLED' };
+  return removeManagedInstallation(agent, paths, receipt, options, dependencies);
+}

package/src/mcp.js

@@ -0,0 +1,17 @@
+import { withMcp } from '../runtime/mcp.js';
+
+export async function probeMcp(config, fetcher = globalThis.fetch) {
+  return withMcp(config, async rpc => {
+    const tools = []; const cursors = new Set(); let cursor;
+    do {
+      const page = await rpc('tools/list', cursor ? { cursor } : {});
+      if (!Array.isArray(page.tools)) throw new Error('Invalid MCP tool list');
+      tools.push(...page.tools.map(tool => tool.name)); cursor = page.nextCursor;
+      if (cursor && cursors.has(cursor)) throw new Error('Repeated MCP pagination cursor');
+      if (cursor) cursors.add(cursor);
+      if (cursors.size > 100) throw new Error('Too many MCP tool pages');
+    } while (cursor);
+    const required = ['hybrid_search', 'memory_search', 'memory_add', 'kb_docs_search', 'skill_search', 'skill_view'];
+    return { connected: true, toolCount: tools.length, missingTools: required.filter(name => !tools.includes(name)) };
+  }, fetcher);
+}