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。

8.2 KB
Raw Blame
/**
 * NDJSON RPC protocol between local desktop client and remote pi-manager daemon.
 *
 * Wire: each frame is one UTF-8 JSON object on its own line, terminated by '\n'.
 * Three message kinds:
 *   - request       : client → manager, expects matching response by id
 *   - response      : manager → client, carries result OR error for a request id
 *   - notification  : either direction, no id, no response expected
 *
 * This is pi-manager's OWN protocol namespace (`pi/*` methods) — deliberately
 * separate from cc-manager's `query/*` namespace. Both daemons may coexist on
 * the same remote host without any wire-level interference.
 *
 * Versioning: every connection must start with a protocol/hello handshake.
 * If client.protocolVersion !== server.protocolVersion the server replies with
 * INVALID_PROTOCOL_VERSION.
 */

/**
 * Bump on any breaking change. Minor additive changes don't bump.
 * v1: initial pi-manager protocol.
 */
export const PROTOCOL_VERSION = 1 as const;

/**
 * pi-manager bundle version — manual bump, mirroring cc-manager's model.
 * Only bump when pi-manager functionality/protocol has a substantive change.
 * Desktop compares this (not bundle sha256) to decide whether the remote
 * daemon needs a re-upload — avoids unrelated dependency churn triggering
 * full remote reinstalls.
 */
// 轮 40-w4-t17 HIGH:0.1.0 → 0.1.1 —— 本分支对 daemon 行为有实质改动
// (idle recycle 的 attachedSocket 二次复核、atomic env-file、shutdownAll survivor
// 保留、NUL/命令校验等), 不 bump 会让存量远端按旧版本号跳过新 bundle,
// 这些修复在已安装远端上静默失效。
// 轮 22 CRITICAL:0.1.1 → 0.1.2 —— env-file 写前展开字面 $HOME 前缀
// (LAZY_CREATE_FAILED 根因: PI_CODING_AGENT_DIR 字面 $HOME → pi 找不到
// models.json → Unknown provider → 秒退)。不 bump 存量远端跳过新 bundle。
// 轮 23-H1:0.1.2 → 0.1.3 —— pi/list 返回 ageMs/lastActivityMs(daemon 时钟算,
// 修跨机器时钟比较误杀); idle 回收改单调时钟(hrtime)。
// 轮 25:0.1.3 → 0.1.4 —— spawn debug 日志(排查 Unknown provider)。
// 轮 25 CRITICAL:0.1.4 → 0.1.5 —— childEnv 用展开后值(LAZY_CREATE_FAILED
// 真正根因: spawn env 里 PI_CODING_AGENT_DIR 是字面 $HOME, pi 找不到 models.json)。
export const PI_MANAGER_BUNDLE_VERSION = '0.1.5' as const;

export type RpcId = number;

export interface RpcError {
  code: RpcErrorCode;
  message: string;
  /** Optional structured details — e.g. process spawn error. */
  data?: unknown;
}

export type RpcErrorCode =
  | 'INVALID_PROTOCOL_VERSION'
  | 'UNKNOWN_METHOD'
  | 'INVALID_PARAMS'
  | 'NOT_INITIALIZED'
  | 'SESSION_NOT_FOUND'
  | 'SESSION_ALREADY_EXISTS'
  /** pi process survived SIGKILL (uninterruptible state) — refuse to proceed. */
  | 'SESSION_KILL_SURVIVED'
  /** Session count limit reached (spawn flood DoS guard). */
  | 'SESSION_LIMIT_EXCEEDED'
  /** Per-client in-flight request limit reached (request flood guard). */
  | 'SERVER_BUSY'
  | 'INTERNAL';

export interface RpcRequest<P = unknown> {
  type: 'request';
  id: RpcId;
  method: string;
  params: P;
}

export interface RpcResponse<R = unknown> {
  type: 'response';
  id: RpcId;
  result?: R;
  error?: RpcError;
}

export interface RpcNotification<P = unknown> {
  type: 'notification';
  method: string;
  params: P;
}

export type RpcMessage = RpcRequest | RpcResponse | RpcNotification;

/* ============================== Method names ============================== */

export const METHODS = {
  // Lifecycle / handshake
  PROTOCOL_HELLO: 'protocol/hello',

  // pi session control (manager-level — ensure/kill/list/shutdown)
  PI_ENSURE: 'pi/ensure',
  PI_KILL: 'pi/kill',
  PI_LIST: 'pi/list',
  PI_SHUTDOWN: 'pi/shutdown',
} as const;

export type MethodName = (typeof METHODS)[keyof typeof METHODS];

/**
 * manager → client notification names.
 */
export const NOTIFICATIONS = {
  /** A session has been closed (terminal) — pi exited / killed / recycled. */
  SESSION_CLOSED: 'session/closed',
} as const;

export type NotificationName = (typeof NOTIFICATIONS)[keyof typeof NOTIFICATIONS];

/* ============================== Param shapes ============================== */

export interface HelloParams {
  protocolVersion: number;
  /** Optional client identifier (logs / debugging). */
  clientId?: string;
}

export interface HelloResult {
  protocolVersion: number;
  /** Manager build / git SHA, surfaced for diagnostics. */
  managerVersion?: string;
}

/**
 * pi/ensure — ensure a pi session exists (spawn if missing, conditional
 * restart if env changed, pure attach if env unchanged).
 */
export interface PiEnsureParams {
  /** Maker sessionId — the daemon-side session key. */
  sessionId: string;
  /** Full pi launch command (`bash -c` form, same as python daemon --cmd). */
  cmd: string;
  /** Env values written to the session's env-file before spawn. */
  env: Record<string, string>;
  /** sha256 of the env content — matched against the retained envHash for
   *  conditional restart (pure attach when unchanged). */
  envHash: string;
  /**
   * true = allow rebuild when envHash mismatches (kill old pi + respawn);
   * false = return existing socket even if envHash differs (pure attach).
   */
  restart: boolean;
}

export interface PiEnsureResult {
  sessionId: string;
  /** Absolute path to the session's unix socket (client bridges to it). */
  sockPath: string;
  /** true = attached to an existing pi without killing it; false = new spawn. */
  isReattach: boolean;
}

export interface PiKillParams {
  sessionId: string;
}

export interface PiListEntry {
  sessionId: string;
  pid: number;
  sockPath: string;
  envHash: string;
  /** Epoch ms of last activity (stdout output / bridge stdin). */
  lastActivity: number;
  /** Epoch ms of session spawn(轮 12 MEDIUM-4 —— cleanup 用年龄过滤新生会话)。 */
  startedAt: number;
  isAttached: boolean;
  /** 轮 23-H1 HIGH:daemon 侧算好的年龄 ms(本机时钟)—— desktop 不跨机器减
   *  epoch(时钟偏移会让 30s 新生保护失效)。 */
  ageMs: number;
  /** 轮 23-H1:daemon 侧算好的空闲时长 ms(本机时钟)。 */
  lastActivityMs: number;
}

export interface PiListResult {
  sessions: PiListEntry[];
}

/* ============================== Notification shapes ============================== */

export interface SessionClosedNotification {
  sessionId: string;
  /** Why the session ended. */
  reason: 'completed' | 'killed' | 'idle_timeout' | 'error';
  /** Optional human-readable detail. */
  detail?: string;
}

/* ============================== Type guards ============================== */

export function isRpcMessage(value: unknown): value is RpcMessage {
  if (typeof value !== 'object' || value === null) return false;
  const v = value as Record<string, unknown>;
  if (v.type === 'request') {
    // Number.isSafeInteger:NaN/Infinity/float 通过 typeof number 但 Map.get(NaN)
    // 永不命中(NaN !== NaN), 会让响应静默落空(自审轮 1 M-2)。
    // 不在此处拒绝负数 id:server→client 反向请求使用负数 id 命名空间(-1,-2,…),
    // 客户端响应这些反向请求时需带负数 id 回传;若 isRpcMessage 全局拒绝负数 id,
    // 则服务端的 decoder 无法识别客户端对反向请求的响应(自审轮 9 补).
    // 客户端发负数 id 请求的拒绝在 ManagerServer.dispatch 层做(server.ts:301).
    return Number.isSafeInteger(v.id) && typeof v.method === 'string';
  }
  if (v.type === 'response') {
    return Number.isSafeInteger(v.id);
  }
  if (v.type === 'notification') {
    return typeof v.method === 'string';
  }
  return false;
}

export function isRpcRequest(value: RpcMessage): value is RpcRequest {
  return value.type === 'request';
}

export function isRpcResponse(value: RpcMessage): value is RpcResponse {
  return value.type === 'response';
}

export function isRpcNotification(value: RpcMessage): value is RpcNotification {
  return value.type === 'notification';
}

/* ============================== Helpers ============================== */

/** Construct a typed error result. Caller passes this as RpcResponse.error. */
export function makeRpcError(code: RpcErrorCode, message: string, data?: unknown): RpcError {
  return { code, message, ...(data !== undefined ? { data } : {}) };
}