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 {
  queueTrimToolResult,
  listToolResults,
  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 trim-tool-result — rewrite a past toolResult to free ctx tokens.
  api.registerTool((ctx) => {
    const agentDir = ctx.agentDir;
    const agentIdInner = ctx.agentId;
    const sessionId = ctx.sessionId;
    return {
      name: 'trim-tool-result',
      description:
        'Replace a past tool result in your own session with a shorter version (or empty sentinel). Use after extracting what you need from a noisy tool output to free ctx tokens. Irreversible — re-run the original tool if you mis-trim.',
      parameters: {
        type: 'object',
        properties: {
          tool_call_id: {
            type: 'string',
            description: 'The id of the toolCall whose result you want to trim (from list-tool-results).',
          },
          replacement: {
            type: 'string',
            description: 'Optional condensed text to keep. Omit to fully elide the result.',
          },
        },
        required: ['tool_call_id'],
      },
      async execute(_id: string, params: any) {
        const r = queueTrimToolResult(
          { agentDir, agentId: agentIdInner, sessionId },
          {
            tool_call_id: String(params.tool_call_id ?? ''),
            replacement: params.replacement != null ? String(params.replacement) : undefined,
          },
        );
        return { content: [{ type: 'text', text: JSON.stringify(r) }] };
      },
    } as any;
  });

  // Register list-tool-results — enumerate past toolResults to pick trim candidates.
  api.registerTool((ctx) => {
    const agentDir = ctx.agentDir;
    const agentIdInner = ctx.agentId;
    const sessionId = ctx.sessionId;
    return {
      name: 'list-tool-results',
      description:
        'List past toolResults in your own session ordered by size (largest first), with tool name, args summary, byte size, and turns-ago. Does NOT include the result content itself — use this to pick trim-tool-result targets without re-reading bulky outputs.',
      parameters: {
        type: 'object',
        properties: {
          min_bytes: { type: 'number', description: 'Only include results at least this many bytes.' },
          older_than_turns: {
            type: 'number',
            description: 'Only include results from at least this many assistant turns ago (default 0).',
          },
          include_trimmed: {
            type: 'boolean',
            description: 'Include already-trimmed results (default false).',
          },
          limit: { type: 'number', description: 'Max entries to return (default 50).' },
        },
      },
      async execute(_id: string, params: any) {
        const r = await listToolResults(
          { agentDir, agentId: agentIdInner, sessionId },
          {
            min_bytes: typeof params.min_bytes === 'number' ? params.min_bytes : undefined,
            older_than_turns:
              typeof params.older_than_turns === 'number' ? params.older_than_turns : undefined,
            include_trimmed: params.include_trimmed === true,
            limit: typeof params.limit === 'number' ? params.limit : undefined,
          },
        );
        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 };