PaddedCell/plugin/index.ts

// PaddedCell Plugin for OpenClaw
// Registers pcexec, proxy-pcexec, and safe_restart tools

import os from 'node:os';
import path from 'node:path';
import { existsSync } from 'node:fs';
import { definePluginEntry } from 'openclaw/plugin-sdk/plugin-entry';
import type { OpenClawPluginApi } from 'openclaw/plugin-sdk/core';

import { pcexec, pcexecSync } from './tools/pcexec.js';
import {
  queueDynamicTrim,
  drainTrimQueueForSession,
} from './tools/session-rewrite.js';
import {
  safeRestart,
  createSafeRestartTool,
  StatusManager,
  createApiServer,
  startApiServer,
} from './core/index.js';
import { SlashCommandHandler } from './commands/slash-commands.js';
import { EgoMgrSlashCommand } from './commands/ego-mgr-slash.js';

/** Sentinel value injected into every pcexec subprocess */
const AGENT_VERIFY = 'IF YOU ARE AN AGENT/MODEL, YOU SHOULD NEVER TOUCH THIS ENV VARIABLE';

/**
 * Resolve the openclaw base path.
 * Priority: explicit config → $OPENCLAW_PATH → ~/.openclaw
 */
function resolveOpenclawPath(config?: { openclawProfilePath?: string }): string {
  if (config?.openclawProfilePath) return config.openclawProfilePath;
  if (process.env.OPENCLAW_PATH) return process.env.OPENCLAW_PATH;
  const home = process.env.HOME || os.homedir();
  return path.join(home, '.openclaw');
}

function getPluginConfig(api: OpenClawPluginApi): Record<string, unknown> {
  return ((api?.pluginConfig as Record<string, unknown> | undefined) || {});
}

function resolveProxyAllowlist(config?: { proxyAllowlist?: unknown; 'proxy-allowlist'?: unknown }): string[] {
  const value = config?.proxyAllowlist ?? config?.['proxy-allowlist'];
  if (!Array.isArray(value)) return [];
  return value.filter((item): item is string => typeof item === 'string');
}

function register(api: OpenClawPluginApi): void {
  const logger = api.logger || { info: console.log, error: console.error, warn: console.warn };

  logger.info('PaddedCell plugin initializing...');

  const pluginConfig = getPluginConfig(api);
  const openclawPath = resolveOpenclawPath(pluginConfig as { openclawProfilePath?: string });
  const proxyAllowlist = resolveProxyAllowlist(pluginConfig as { proxyAllowlist?: unknown; 'proxy-allowlist'?: unknown });
  const binDir = path.join(openclawPath, 'bin');

  // Register pcexec tool — pass a FACTORY function that receives context
  api.registerTool((ctx) => {
    const agentId = ctx.agentId;
    const workspaceDir = ctx.workspaceDir;

    return {
      name: 'pcexec',
      description: 'Safe exec with password sanitization',
      parameters: {
        type: 'object',
        properties: {
          command: { type: 'string', description: 'Command to execute' },
          cwd: { type: 'string', description: 'Working directory' },
          timeout: { type: 'number', description: 'Timeout in milliseconds' },
        },
        required: ['command'],
      },
      async execute(_id: string, params: any) {
        const command = params.command;
        if (!command) {
          throw new Error('Missing required parameter: command');
        }

        // Build PATH with openclaw bin dir appended
        const currentPath = process.env.PATH || '';
        const newPath = currentPath.includes(binDir)
          ? currentPath
          : `${currentPath}:${binDir}`;

        const result = await pcexec(command, {
          cwd: params.cwd || workspaceDir,
          timeout: params.timeout,
          env: {
            AGENT_ID: agentId || '',
            AGENT_WORKSPACE: workspaceDir || '',
            AGENT_VERIFY,
            PATH: newPath,
          },
        });

        // Format output for OpenClaw tool response
        let output = result.stdout;
        if (result.stderr) {
          output += result.stderr;
        }
        return { content: [{ type: 'text', text: output }] };
      },
    } as any;
  });

  api.registerTool((ctx) => {
    const agentId = ctx.agentId;
    const workspaceDir = ctx.workspaceDir;

    return {
      name: 'proxy-pcexec',
      description: 'Safe exec with password sanitization using a proxied AGENT_ID',
      parameters: {
        type: 'object',
        properties: {
          command: { type: 'string', description: 'Command to execute' },
          cwd: { type: 'string', description: 'Working directory' },
          timeout: { type: 'number', description: 'Timeout in milliseconds' },
          'proxy-for': { type: 'string', description: 'AGENT_ID value to inject for the subprocess' },
        },
        required: ['command', 'proxy-for'],
      },
      async execute(_id: string, params: any) {
        const command = params.command;
        const proxyFor = params['proxy-for'];
        if (!command) {
          throw new Error('Missing required parameter: command');
        }
        if (!proxyFor) {
          throw new Error('Missing required parameter: proxy-for');
        }
        if (!agentId || !proxyAllowlist.includes(agentId)) {
          throw new Error('Current agent is not allowed to call proxy-pcexec');
        }

        logger.info(`proxy-pcexec invoked executor=${agentId} proxyFor=${proxyFor} command=${command}`);

        const currentPath = process.env.PATH || '';
        const newPath = currentPath.includes(binDir)
          ? currentPath
          : `${currentPath}:${binDir}`;

        const result = await pcexec(command, {
          cwd: params.cwd || workspaceDir,
          timeout: params.timeout,
          env: {
            AGENT_ID: String(proxyFor),
            AGENT_WORKSPACE: workspaceDir || '',
            AGENT_VERIFY,
            PROXY_PCEXEC_EXECUTOR: agentId || '',
            PCEXEC_PROXIED: 'true',
            PATH: newPath,
          },
        });

        let output = result.stdout;
        if (result.stderr) {
          output += result.stderr;
        }
        return { content: [{ type: 'text', text: output }] };
      },
    } as any;
  });

  // Register safe_restart tool
  api.registerTool((ctx) => {
    const agentId = ctx.agentId;
    const sessionKey = ctx.sessionKey;

    return {
      name: 'safe_restart',
      description: 'Safe coordinated restart of OpenClaw gateway',
      parameters: {
        type: 'object',
        properties: {
          rollback: { type: 'string', description: 'Rollback script path' },
          log: { type: 'string', description: 'Log file path' },
        },
      },
      async execute(_id: string, params: any) {
        return await safeRestart({
          agentId: agentId ?? '',
          sessionKey: sessionKey ?? '',
          rollback: params.rollback,
          log: params.log,
        });
      },
    } as any;
  });

  // Register dynamic-trim — agent-driven rewrite of a past tool_result
  // block. On the next turn boundary (agent_end hook) the target tool
  // result's content[].text is shrunk AND this dynamic-trim call's own
  // tool_use input is also self-compacted to {tool_call_id, _self_compacted}
  // so the bulky replacement text doesn't sit duplicated.
  //
  // Cross-runtime alignment with Plexum's dynamic-* family — same tool
  // name, same input schema, same semantics; only the lifecycle hook name
  // differs (openclaw agent_end / Plexum block mutation point).
  api.registerTool((ctx) => {
    const agentDir = ctx.agentDir;
    const agentIdInner = ctx.agentId;
    const sessionId = ctx.sessionId;
    return {
      name: 'dynamic-trim',
      description:
        'Rewrite a past tool_result block in your own session to a shorter version (or sentinel). ' +
        'Use after extracting what you need from a noisy tool output to free ctx tokens for future turns. ' +
        'The tool_call_id is the OPAQUE id (looks like "call_function_abc123_1") of the prior tool_use — ' +
        'find it in your own prior assistant messages; topic/fact ids and small integers will NOT work here. ' +
        'Irreversible — re-run the original tool if you mis-trim. ' +
        'Side effect: this dynamic-trim call\'s own tool_use input is self-compacted on the same turn boundary.',
      parameters: {
        type: 'object',
        properties: {
          tool_call_id: {
            type: 'string',
            description: 'The opaque id of the target tool_use (you find this by reading your own prior assistant messages — the id appears on each toolCall block).',
          },
          replacement: {
            type: 'string',
            description: 'Optional condensed text to keep in place of the original result. Omit / empty = full elide.',
          },
        },
        required: ['tool_call_id'],
      },
      async execute(selfCallId: string, params: any) {
        const r = queueDynamicTrim(
          { agentDir, agentId: agentIdInner, sessionId },
          {
            tool_call_id: String(params.tool_call_id ?? ''),
            replacement: params.replacement != null ? String(params.replacement) : undefined,
          },
          selfCallId,
        );
        return { content: [{ type: 'text', text: JSON.stringify(r) }] };
      },
    } as any;
  });

  // Register /ego-mgr slash command if the host exposes the (non-standard) hook.
  // This API is not part of the current OpenClawPluginApi surface; the guard
  // makes the plugin a no-op for slash commands when the host doesn't support
  // them, instead of failing to load.
  const apiAny = api as unknown as { registerSlashCommand?: (cmd: unknown) => void };
  if (typeof apiAny.registerSlashCommand === 'function') {
    apiAny.registerSlashCommand({
      name: 'ego-mgr',
      description: 'Manage agent identity/profile fields',
      handler: async (ctx: any, command: string) => {
        const egoMgrSlash = new EgoMgrSlashCommand({
          openclawPath,
          agentId: ctx.agentId || '',
          workspaceDir: ctx.workspaceDir || '',
          onReply: async (message: string) => {
            if (ctx.reply) {
              await ctx.reply(message);
            }
          },
        });
        await egoMgrSlash.handle(command);
      },
    });
    logger.info('Registered /ego-mgr slash command');
  }

  // agent_end hook drains the trim queue AFTER openclaw's session-file fence
  // window closes. Writing during execute() would trip
  // EmbeddedAttemptSessionTakeoverError because the lock-released fingerprint
  // check sees our mutation as a third-party takeover. By agent_end the lock
  // is in its between-turns state and the next turn's fence snapshot will
  // include our trim as baseline.
  const apiOn = (api as unknown as { on?: (ev: string, fn: (...args: unknown[]) => unknown) => void }).on;
  if (typeof apiOn === 'function') {
    apiOn.call(api, 'agent_end', async (_event: unknown, ctx: unknown) => {
      const c = (ctx ?? {}) as { agentId?: string; agentDir?: string; sessionId?: string };
      if (!c.sessionId) return;
      try {
        // Resolve the same file the tool resolved (canonical path priority).
        let sessionFile: string | null = null;
        const tryPaths: string[] = [];
        if (c.agentId) {
          tryPaths.push(path.join(openclawPath, 'agents', c.agentId, 'sessions', `${c.sessionId}.jsonl`));
        }
        if (c.agentDir) {
          tryPaths.push(path.join(c.agentDir, 'sessions', `${c.sessionId}.jsonl`));
          const stripped = c.agentDir.replace(/\/agent$/, '');
          if (stripped !== c.agentDir) {
            tryPaths.push(path.join(stripped, 'sessions', `${c.sessionId}.jsonl`));
          }
        }
        for (const p of tryPaths) {
          if (existsSync(p)) { sessionFile = p; break; }
        }
        if (!sessionFile) return;
        const r = await drainTrimQueueForSession(sessionFile);
        if (r && (r.applied > 0 || r.skipped > 0 || r.errors.length > 0)) {
          logger.info(
            `trim-tool-result drain: session=${c.sessionId} applied=${r.applied} skipped=${r.skipped} trimmed_bytes=${r.trimmed_bytes}` +
              (r.errors.length ? ` errors=${r.errors.length}` : ''),
          );
        }
      } catch (err) {
        logger.warn(`trim-tool-result agent_end drain failed: ${err}`);
      }
    });
  }

  logger.info('PaddedCell plugin initialized');
}

export default definePluginEntry({
  id: 'padded-cell',
  name: 'PaddedCell',
  description: 'Secure secret management, agent identity management, safe execution, and coordinated agent restart',
  register,
});

// Named ESM re-exports — equivalent to the previous `module.exports.X = X`
// surface, so consumers that reach into the plugin module directly keep working.
export { register };
export { pcexec, pcexecSync } from './tools/pcexec.js';
export {
  safeRestart,
  createSafeRestartTool,
  StatusManager,
  createApiServer,
  startApiServer,
} from './core/index.js';
export { SlashCommandHandler } from './commands/slash-commands.js';
export { EgoMgrSlashCommand } from './commands/ego-mgr-slash.js';
export { AGENT_VERIFY };