runtime-adapters.js

/**
 * Runtime Mount adapters: write Trusted Agent context into host workspaces.
 */

import fs from 'node:fs';
import path from 'node:path';
import { RUNTIME_MOUNT_SCHEMA } from './runtime-mount.js';

export const MOUNT_MANIFEST_RELATIVE = path.join('.proofable', 'mount.json');
export const RUNTIME_POINTER_SCHEMA = 'proofable.runtime-pointer.v1';
export const APPLY_HOSTS = Object.freeze(['cursor', 'claude', 'codex', 'hermes', 'openclaw', 'opencode']);
export const APPLY_HOST_ALIASES = Object.freeze({ vscode: 'cursor' });
/** ACP-native project runtimes share one sidecar: `{dir}/proofable.json` → `.proofable/mount.json`. */
export const ACP_POINTER_DIRS = Object.freeze({
  hermes: '.hermes',
  openclaw: '.openclaw',
  opencode: '.opencode'
});

export function normalizeApplyHost(value) {
  const raw = String(value || '').trim().toLowerCase();
  if (!raw) return null;
  const mapped = APPLY_HOST_ALIASES[raw] || raw;
  return APPLY_HOSTS.includes(mapped) ? mapped : null;
}

/**
 * @param {string} agentId
 */
export function sanitizeAgentIdForFilename(agentId) {
  return String(agentId || 'agent')
    .trim()
    .toLowerCase()
    .replace(/[^a-z0-9_-]+/g, '-')
    .replace(/^-+|-+$/g, '')
    .slice(0, 64) || 'agent';
}

/**
 * @param {import('./runtime-mount.js').RuntimeBundle} bundle
 */
export function bundleToCursorRules(bundle) {
  const id = bundle.identity.agentId;
  const label = bundle.identity.agentLabel || id;
  const skillsBlock = (bundle.identity.skills || [])
    .map(skill => {
      if (typeof skill === 'string') return `- ${skill}`;
      const labelText = skill.label || skill.id || 'skill';
      const kind = skill.kind || 'skill';
      const provider = skill.provider ? ` / ${skill.provider}` : '';
      return `- ${labelText} (${kind}${provider})`;
    })
    .join('\n');

  const denied = (bundle.enforce.deniedActions || []).map(action => `- ${action}`).join('\n');
  const capabilities = (bundle.identity.capabilities || []).map(cap => `- ${cap}`).join('\n');
  const services = (bundle.identity.services || [])
    .map(svc => `- ${svc.name}: ${svc.endpoint}${svc.version ? ` (v${svc.version})` : ''}`)
    .join('\n');

  return `---
description: Verified Proofable agent. ${label}
globs:
alwaysApply: true
---

# Proofable Agent. ${label}

You are **${label}** (\`${id}\`). This project loaded your current Proofable identity and permissions.

## Identity
${bundle.identity.description || bundle.identity.instructions || 'Follow the agent instructions below.'}

## Instructions
${bundle.identity.instructions || 'Use Proofable before taking sensitive actions.'}

## Capabilities
${capabilities || '- General purpose'}

## Skills
${skillsBlock || '- None configured'}

## Services
${services || '- None configured'}

## Permission limits
${denied ? `Denied actions (do not perform without new approval):\n${denied}` : '- Follow the current permission proof through Proofable MCP.'}

## Trust workflow
1. Call \`proofable_context\` once per session when Proofable MCP is available.
2. Before a sensitive action, call \`proofable_verify_or_guide\` directly.
3. Use \`proofable_proofs_check\` only for a yes/no eligibility, gate, or access question.
4. Do not invent proof IDs, accounts, or proof fields.
5. Summarize the result as Passed, Action needed, or Blocked. Do not show raw tool output.

## Proof references
- Identity: ${bundle.trust.identityProofUrl}
${bundle.trust.delegationProofUrl ? `- Permissions: ${bundle.trust.delegationProofUrl}` : '- Permissions: not on file. Call `proofable_agent_link` before acting as this agent.'}
`;
}

/**
 * @param {import('./runtime-mount.js').RuntimeBundle} bundle
 */
export function bundleToClaudeMd(bundle) {
  const id = bundle.identity.agentId;
  const label = bundle.identity.agentLabel || id;
  return `# Proofable Agent. ${label}

Loaded from Proofable agent context (\`${RUNTIME_MOUNT_SCHEMA}\`).

## Identity
- **Agent ID:** ${id}
- **Label:** ${label}

## Description
${bundle.identity.description || 'Verified agent on Proofable.'}

## Instructions
${bundle.identity.instructions || 'Use Proofable before taking sensitive actions.'}

## Portable proofs
- Identity: \`${bundle.trust.identityQHash}\`. ${bundle.trust.identityProofUrl}
${bundle.trust.delegationQHash ? `- Permissions: \`${bundle.trust.delegationQHash}\`. ${bundle.trust.delegationProofUrl}` : ''}

## Policy
- Do not invent proof IDs or check outcomes.
- Call \`proofable_context\` once; use profile context when signed in.
`;
}

/**
 * @param {import('./runtime-mount.js').RuntimeBundle} bundle
 */
export function bundleToCodexJson(bundle) {
  return JSON.stringify(
    {
      schema: RUNTIME_MOUNT_SCHEMA,
      name: bundle.identity.agentLabel,
      agentId: bundle.identity.agentId,
      agentWallet: bundle.identity.agentWallet,
      description: bundle.identity.description,
      instructions: bundle.identity.instructions,
      capabilities: bundle.identity.capabilities,
      skills: bundle.identity.skills,
      services: bundle.identity.services,
      effectiveRuntime: bundle.effectiveRuntime,
      enforce: bundle.enforce,
      trust: bundle.trust,
      mountedAt: bundle.mountedAt
    },
    null,
    2
  );
}

/**
 * @param {string} cwd
 */
export function readMountManifest(cwd) {
  const manifestPath = path.join(cwd, MOUNT_MANIFEST_RELATIVE);
  if (!fs.existsSync(manifestPath)) return null;
  try {
    const parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
    return parsed?.schema === RUNTIME_MOUNT_SCHEMA ? parsed : null;
  } catch {
    return null;
  }
}

/**
 * @param {import('./runtime-mount.js').RuntimeBundle} bundle
 * @param {string} cwd
 */
export function writeMountManifest(bundle, cwd) {
  const dir = path.join(cwd, '.proofable');
  fs.mkdirSync(dir, { recursive: true });
  const manifestPath = path.join(dir, 'mount.json');
  fs.writeFileSync(manifestPath, `${JSON.stringify(bundle, null, 2)}\n`, 'utf8');
  return manifestPath;
}

function writeRuntimePointer(flavor, cwd, dryRun) {
  const dirName = ACP_POINTER_DIRS[flavor];
  if (!dirName) throw new Error(`Unsupported ACP pointer host: ${flavor}`);
  const sidecarPath = path.join(cwd, dirName, 'proofable.json');
  if (!dryRun) {
    fs.mkdirSync(path.join(cwd, dirName), { recursive: true });
    fs.writeFileSync(
      sidecarPath,
      `${JSON.stringify(
        {
          schema: RUNTIME_POINTER_SCHEMA,
          mount: '.proofable/mount.json',
          origin: flavor
        },
        null,
        2
      )}\n`
    );
  }
  return sidecarPath;
}

/**
 * @param {'cursor' | 'claude' | 'codex' | 'hermes' | 'openclaw' | 'opencode' | 'vscode'} flavor
 * @param {import('./runtime-mount.js').RuntimeBundle} bundle
 * @param {string} cwd
 * @param {{ dryRun?: boolean }} [options]
 */
export function applyRuntimeBundle(flavor, bundle, cwd, options = {}) {
  const dryRun = Boolean(options.dryRun);
  const host = normalizeApplyHost(flavor);
  if (!host) throw new Error(`Unsupported runtime adapter: ${flavor}`);
  const safeId = sanitizeAgentIdForFilename(bundle.identity.agentId);
  const written = [];

  const manifestPath = dryRun
    ? path.join(cwd, MOUNT_MANIFEST_RELATIVE)
    : writeMountManifest(bundle, cwd);
  written.push(manifestPath);

  if (ACP_POINTER_DIRS[host]) {
    const sidecarPath = writeRuntimePointer(host, cwd, dryRun);
    written.push(sidecarPath);
    return { flavor: host, written, primary: sidecarPath, manifestPath };
  }

  if (host === 'cursor') {
    const rulesDir = path.join(cwd, '.cursor', 'rules');
    const rulesPath = path.join(rulesDir, `proofable-agent-${safeId}.mdc`);
    if (!dryRun) {
      fs.mkdirSync(rulesDir, { recursive: true });
      fs.writeFileSync(rulesPath, bundleToCursorRules(bundle), 'utf8');
    }
    written.push(rulesPath);
    return { flavor: host, written, primary: rulesPath, manifestPath };
  }

  if (host === 'claude') {
    const claudePath = path.join(cwd, '.claude', 'PROOFABLE_AGENT.md');
    if (!dryRun) {
      fs.mkdirSync(path.join(cwd, '.claude'), { recursive: true });
      fs.writeFileSync(claudePath, bundleToClaudeMd(bundle), 'utf8');
    }
    written.push(claudePath);
    return { flavor: host, written, primary: claudePath, manifestPath };
  }

  if (host === 'codex') {
    const codexPath = path.join(cwd, '.proofable', `codex-agent-${safeId}.json`);
    if (!dryRun) {
      fs.mkdirSync(path.join(cwd, '.proofable'), { recursive: true });
      fs.writeFileSync(codexPath, bundleToCodexJson(bundle), 'utf8');
    }
    written.push(codexPath);
    return { flavor: host, written, primary: codexPath, manifestPath };
  }

  throw new Error(`Unsupported runtime adapter: ${flavor}`);
}