Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

14.6 KB
Raw Blame
import type { PiRpcResponse } from './rpc-client.js';
import fs from 'node:fs';
import path from 'node:path';
import type {
  PiRuntimeCapabilityError,
  PiRuntimeCapabilityErrorStage,
  PiRuntimeCapabilityManifest,
  PiRuntimeCommand,
  PiRuntimeCommandSourceInfo,
  PiManagedPackageSkillRuntimeSnapshot,
} from '../../types/pi-runtime-capabilities.js';

const MAX_RESPONSE_BYTES = 256_000;
const MAX_COMMANDS = 4_096;
const MAX_NAME_LENGTH = 256;
const MAX_DESCRIPTION_LENGTH = 4_096;
const MAX_SOURCE_LENGTH = 128;
const MAX_SOURCE_INFO_VALUE_LENGTH = 4_096;
const MAX_ERROR_MESSAGE_LENGTH = 160;
export const PI_RUNTIME_CAPABILITY_TIMEOUT_MS = 5_000;
const PI_RPC_RESPONSE_KEYS = new Set(['type', 'id', 'command', 'success', 'data', 'error']);

type RuntimeCommandParseResult =
  | { ok: true; commands: PiRuntimeCommand[] }
  | { ok: false };

function boundedString(value: unknown, maxLength: number): string | undefined {
  if (typeof value !== 'string' || value.trim().length === 0 || value.length > maxLength) return undefined;
  return value;
}

function parseSourceInfo(value: unknown): PiRuntimeCommandSourceInfo | undefined {
  if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined;
  const raw = value as Record<string, unknown>;
  if (Object.keys(raw).some((key) => !['path', 'scope', 'baseDir', 'source', 'origin'].includes(key))) return undefined;
  for (const key of ['path', 'scope', 'baseDir', 'source', 'origin'] as const) {
    if (Object.hasOwn(raw, key) && !boundedString(raw[key], MAX_SOURCE_INFO_VALUE_LENGTH)) {
      return undefined;
    }
  }
  const path = boundedString(raw.path, MAX_SOURCE_INFO_VALUE_LENGTH);
  const scope = boundedString(raw.scope, MAX_SOURCE_INFO_VALUE_LENGTH);
  const baseDir = boundedString(raw.baseDir, MAX_SOURCE_INFO_VALUE_LENGTH);
  const source = boundedString(raw.source, MAX_SOURCE_INFO_VALUE_LENGTH);
  const origin = boundedString(raw.origin, MAX_SOURCE_INFO_VALUE_LENGTH);
  // A sourceInfo object with no recognized provenance is not trustworthy enough
  // to mark the command catalog loaded.
  if (!path && !scope && !baseDir && !source) return undefined;
  return {
    ...(path ? { path } : {}),
    ...(scope ? { scope } : {}),
    ...(baseDir ? { baseDir } : {}),
    ...(source ? { source } : {}),
    ...(origin ? { origin } : {}),
  };
}

/** Conservative parser for Pi's get_commands `data.commands` payload. */
export function parsePiRuntimeCommands(data: unknown): RuntimeCommandParseResult {
  if (data === null || typeof data !== 'object' || Array.isArray(data)) return { ok: false };
  const rawData = data as Record<string, unknown>;
  if (Object.keys(rawData).some((key) => key !== 'commands')) return { ok: false };
  const commands = rawData.commands;
  if (!Array.isArray(commands) || commands.length > MAX_COMMANDS) return { ok: false };

  let serializedLength = 0;
  try {
    const serialized = JSON.stringify(data);
    if (typeof serialized !== 'string') return { ok: false };
    serializedLength = Buffer.byteLength(serialized, 'utf8');
  } catch {
    return { ok: false };
  }
  if (serializedLength > MAX_RESPONSE_BYTES) return { ok: false };

  const parsed: PiRuntimeCommand[] = [];
  for (const value of commands) {
    if (typeof value !== 'object' || value === null || Array.isArray(value)) return { ok: false };
    const raw = value as Record<string, unknown>;
    if (Object.keys(raw).some((key) => !['name', 'description', 'source', 'sourceInfo'].includes(key))) {
      return { ok: false };
    }
    const name = boundedString(raw.name, MAX_NAME_LENGTH);
    const source = boundedString(raw.source, MAX_SOURCE_LENGTH);
    const sourceInfo = parseSourceInfo(raw.sourceInfo);
    if (!name || !source || !sourceInfo) return { ok: false };
    const description = raw.description === undefined
      ? undefined
      : boundedString(raw.description, MAX_DESCRIPTION_LENGTH);
    if (raw.description !== undefined && !description) return { ok: false };
    parsed.push({
      name,
      ...(description ? { description } : {}),
      source,
      sourceInfo,
    });
  }
  return { ok: true, commands: parsed };
}

function isPathWithin(root: string, candidate: string): boolean {
  if (!path.isAbsolute(root) || !path.isAbsolute(candidate)) return false;
  const relative = path.relative(path.resolve(root), path.resolve(candidate));
  return relative === '' || (!relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
}

function commandSourcePaths(sourceInfo: PiRuntimeCommandSourceInfo): string[] {
  const values = [sourceInfo.path, sourceInfo.source, sourceInfo.origin]
    .filter((value): value is string => typeof value === 'string' && path.isAbsolute(value));
  if (sourceInfo.baseDir && path.isAbsolute(sourceInfo.baseDir)) {
    values.push(sourceInfo.baseDir);
    if (sourceInfo.path && !path.isAbsolute(sourceInfo.path)) {
      values.push(path.resolve(sourceInfo.baseDir, sourceInfo.path));
    }
  }
  return values;
}

/**
 * Mark only commands whose Pi-owned provenance points inside an enabled
 * Cindy-managed package root. The result is later used both by the palette and
 * by the prompt escape boundary; static filenames alone never authorize an
 * extension command.
 */
export function identifyManagedPiPackageCommandNames(
  commands: readonly PiRuntimeCommand[],
  packageRoots: readonly string[],
): string[] {
  const roots = packageRoots.filter(path.isAbsolute).map((root) => path.resolve(root));
  if (roots.length === 0) return [];
  const provenanceByName = new Map<string, boolean[]>();
  for (const command of commands) {
    const managed = commandSourcePaths(command.sourceInfo)
      .some((candidate) => roots.some((root) => isPathWithin(root, candidate)));
    const provenance = provenanceByName.get(command.name) ?? [];
    provenance.push(managed);
    provenanceByName.set(command.name, provenance);
  }
  // Pi may legitimately expose an Extension command and a Prompt with the
  // same name. Authorize that name only when every colliding catalog entry is
  // from a managed package; mixed provenance could dispatch a Cindy internal
  // or user command instead of the package command shown in the menu.
  return [...provenanceByName.entries()].flatMap(([name, provenance]) => (
    provenance.length > 0 && provenance.every(Boolean) ? [name] : []
  ));
}

function canonicalRuntimePath(value: string): string {
  const resolved = path.resolve(value);
  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
}

function managedSkillCommandMatchesSource(command: PiRuntimeCommand, sourcePath: string): boolean {
  if (command.source !== 'skill' || !command.name.startsWith('skill:') || !path.isAbsolute(sourcePath)) return false;
  const expectedFile = canonicalRuntimePath(sourcePath);
  const commandFile = command.sourceInfo.path;
  if (commandFile && path.isAbsolute(commandFile) && canonicalRuntimePath(commandFile) === expectedFile) return true;
  const commandBaseDir = command.sourceInfo.baseDir;
  return path.basename(sourcePath).toLowerCase() === 'skill.md'
    && typeof commandBaseDir === 'string'
    && path.isAbsolute(commandBaseDir)
    && canonicalRuntimePath(commandBaseDir) === canonicalRuntimePath(path.dirname(sourcePath));
}

function canonicalExistingRuntimePath(value: string): string {
  let resolved: string;
  try {
    resolved = fs.realpathSync.native(value);
  } catch {
    resolved = path.resolve(value);
  }
  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
}

function piSkillCommandMatchesPinnedPath(command: PiRuntimeCommand, skillFile: string): boolean {
  if (command.source !== 'skill' || !path.isAbsolute(skillFile)) return false;
  const expected = canonicalExistingRuntimePath(skillFile);
  const candidates = [
    command.sourceInfo.path,
    typeof command.sourceInfo.baseDir === 'string'
      ? path.join(command.sourceInfo.baseDir, 'SKILL.md')
      : undefined,
  ];
  return candidates.some((candidate) => (
    typeof candidate === 'string'
    && path.isAbsolute(candidate)
    && canonicalExistingRuntimePath(candidate) === expected
  ));
}

/**
 * Bind one Host-attested invocation to Pi's frozen runtime catalog. Pi only
 * executes Skills through /skill:name, so normalize Cindy's /name alias after
 * proving that the sole runtime winner has the same physical SKILL.md path.
 */
export function preparePinnedPiSkillInvocation(
  text: string,
  pinnedSkill: { readonly name: string; readonly path: string },
  manifest: PiRuntimeCapabilityManifest | undefined,
): string {
  const invocation = /^\/(?:skill:)?([^\s/]+)([\s\S]*)$/i.exec(text.trim());
  if (!invocation?.[1] || invocation[1].toLowerCase() !== pinnedSkill.name.toLowerCase()) {
    throw new Error('The pinned Skill does not match the Pi command');
  }
  if (manifest?.status !== 'loaded') {
    throw new Error('Pi runtime Skill provenance is unavailable');
  }
  const runtimeName = `skill:${pinnedSkill.name}`.toLowerCase();
  const winners = manifest.commands.filter((command) => command.name.toLowerCase() === runtimeName);
  if (
    winners.length !== 1
    || !piSkillCommandMatchesPinnedPath(winners[0]!, pinnedSkill.path)
  ) {
    throw new Error('The pinned Skill does not match the Pi runtime winner');
  }
  return `/${winners[0]!.name}${invocation[2] ?? ''}`;
}

/**
 * Freeze the managed-skill roster passed to one runtime and attach a command
 * name only when that runtime's own catalog proves an unambiguous loaded match.
 */
export function snapshotManagedPiPackageSkills(
  skills: readonly { path: string; name: string; description?: string }[],
  commands: readonly PiRuntimeCommand[],
  managedPackageCommandNames: readonly string[],
): PiManagedPackageSkillRuntimeSnapshot[] {
  const managedNames = new Set(managedPackageCommandNames);
  return skills.map((skill) => {
    const matches = [...new Set(commands.flatMap((command) => (
      managedNames.has(command.name) && managedSkillCommandMatchesSource(command, skill.path)
        ? [command.name]
        : []
    )))];
    return {
      sourcePath: skill.path,
      name: skill.name,
      ...(skill.description ? { description: skill.description } : {}),
      ...(matches.length === 1 ? { runtimeCommandName: matches[0] } : {}),
    };
  });
}

function classifyExplicitRpcFailure(raw: string): Pick<PiRuntimeCapabilityError, 'code' | 'message'> {
  const text = raw.toLowerCase();
  if (text.includes('unknown command') || text.includes('unsupported') || text.includes('not supported')) {
    return { code: 'unsupported', message: 'Pi does not support runtime command discovery' };
  }
  return { code: 'rpc_failed', message: 'Pi runtime command discovery was rejected' };
}

function classifyTransportFailure(raw: string): Pick<PiRuntimeCapabilityError, 'code' | 'message'> {
  const text = raw.toLowerCase();
  if (text.startsWith('pi rpc timeout after ')) {
    return { code: 'timeout', message: 'Pi runtime command discovery timed out' };
  }
  if (
    text.startsWith('pi process already exited')
    || text.startsWith('pi process exited (')
    || text.startsWith('pi process error:')
    || text.startsWith('pi rpc write failed:')
  ) {
    return { code: 'process_unavailable', message: 'Pi process was unavailable for runtime command discovery' };
  }
  return { code: 'rpc_failed', message: 'Pi runtime command discovery was rejected' };
}

function statusForFailureCode(code: PiRuntimeCapabilityError['code']): 'unknown' | 'failed' {
  return code === 'unsupported' || code === 'timeout' || code === 'process_unavailable'
    ? 'unknown'
    : 'failed';
}

function errorManifest(
  identity: { sessionId?: string; sdkSessionId?: string },
  generation: number,
  stage: PiRuntimeCapabilityErrorStage,
  failure: Pick<PiRuntimeCapabilityError, 'code' | 'message'>,
  status: 'unknown' | 'failed',
): PiRuntimeCapabilityManifest {
  return {
    ...(identity.sessionId ? { sessionId: identity.sessionId } : {}),
    ...(identity.sdkSessionId ? { sdkSessionId: identity.sdkSessionId } : {}),
    capturedAt: new Date().toISOString(),
    generation,
    status,
    source: 'pi:get_commands',
    commands: [],
    error: { stage, ...failure, message: failure.message.slice(0, MAX_ERROR_MESSAGE_LENGTH) },
  };
}

export async function capturePiRuntimeCapabilityManifest(
  requester: {
    request(
      command: Record<string, unknown>,
      options?: { timeoutMs?: number },
    ): Promise<PiRpcResponse>;
  },
  identity: { sessionId?: string; sdkSessionId?: string },
  generation: number,
  stage: PiRuntimeCapabilityErrorStage,
): Promise<PiRuntimeCapabilityManifest> {
  try {
    const response = await requester.request(
      { type: 'get_commands' },
      { timeoutMs: PI_RUNTIME_CAPABILITY_TIMEOUT_MS },
    );
    const rawResponse = response as unknown;
    if (
      typeof rawResponse !== 'object'
      || rawResponse === null
      || Array.isArray(rawResponse)
    ) {
      return errorManifest(identity, generation, stage, {
        code: 'malformed_response',
        message: 'Pi returned an invalid runtime command response',
      }, 'failed');
    }
    const responseRecord = rawResponse as Record<string, unknown>;
    if (
      Object.keys(responseRecord).some((key) => !PI_RPC_RESPONSE_KEYS.has(key))
      || responseRecord.type !== 'response'
      || responseRecord.command !== 'get_commands'
      || typeof responseRecord.success !== 'boolean'
      || (responseRecord.id !== undefined && typeof responseRecord.id !== 'string')
      || (responseRecord.error !== undefined && typeof responseRecord.error !== 'string')
    ) {
      return errorManifest(identity, generation, stage, {
        code: 'malformed_response',
        message: 'Pi returned an invalid runtime command response',
      }, 'failed');
    }
    const typedResponse = responseRecord as unknown as PiRpcResponse;
    if (!typedResponse.success) {
      const failure = classifyExplicitRpcFailure(typeof typedResponse.error === 'string' ? typedResponse.error : 'rpc rejected');
      return errorManifest(identity, generation, stage, failure, statusForFailureCode(failure.code));
    }
    const parsed = parsePiRuntimeCommands(typedResponse.data);
    if (!parsed.ok) {
      return errorManifest(identity, generation, stage, {
        code: 'malformed_response',
        message: 'Pi returned an invalid runtime command catalog',
      }, 'failed');
    }
    return {
      ...(identity.sessionId ? { sessionId: identity.sessionId } : {}),
      ...(identity.sdkSessionId ? { sdkSessionId: identity.sdkSessionId } : {}),
      capturedAt: new Date().toISOString(),
      generation,
      status: 'loaded',
      source: 'pi:get_commands',
      commands: parsed.commands,
    };
  } catch (error) {
    const failure = classifyTransportFailure(error instanceof Error ? error.message : 'rpc failed');
    return errorManifest(identity, generation, stage, failure, statusForFailureCode(failure.code));
  }
}