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。

16.7 KB
Raw Blame
/**
 * NDJSON RPC protocol between local desktop client and remote cc-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
 *
 * Designed to be a thin wrapper over the Claude Agent SDK Query surface,
 * NOT an attempt to re-abstract cc protocol — most params and event payloads
 * are passed through verbatim (SDK already gives us typed JSON-safe shapes).
 *
 * Versioning: every connection must start with a protocol/hello handshake.
 * If client.protocolVersion !== server.protocolVersion the server replies with
 * INVALID_PROTOCOL_VERSION and the client should toast "upgrade required".
 */

/**
 * Bump on any breaking change. Minor additive changes don't bump.
 *
 * v2: query/start 增加 host toolGuards,并要求 daemon 在权限规则之前重建
 * PreToolUse 闸门。旧 daemon 会无声忽略未知字段,导致 capability routing
 * fail-open,因此这项表面上的字段新增必须按不兼容协议升级处理。
 *
 * v3: toolGuards 增加 root-only,使用 SDK agent_id 阻止远端 subagent
 * 调用受保护工具。旧 daemon 无法证明调用来源,因此必须升级协议。
 *
 * v4: 增加 subagent/model-access 反向请求,并要求 daemon 在 Full access
 * 之前执行 Agent/Task 实时模型准入预检。旧 daemon 没有该执行边界,
 * 会继续发起无权限请求,因此必须升级协议。
 *
 * v5: root-only toolGuards now accept the native `AskUserQuestion` tool name.
 * Older daemons reject that exact guard as an invalid root-only tool and must
 * be upgraded before remote queries send it.
 *
 * v1 (redesign): 删除 dead-session drain/archive 握手,对齐 codex 模式。
 * reattach 只接新 events (live-only subscription),不 replay 旧 ring buffer。
 * ring buffer 降级为纯内存 fast-path(同一 daemon 进程生命周期内的 mid-turn 续流)。
 * 断开期间跑完的输出暂不自动补回 chat(follow-up: jsonl recovery 统一 cc + codex)。
 */
export const PROTOCOL_VERSION = 5 as const;

/**
 * cc-mgr bundle 版本号 — 手动 bump。
 *
 * 只在 cc-mgr 功能/协议有实质变化时递增。不随 SDK patch / esbuild 版本 /
 * 无关依赖变化而变。desktop 用这个(而非 bundle sha256)判断远端 daemon
 * 是否需要 upgrade,避免无关的 pnpm install 触发全量远端重装。
 */
// SDK 0.3 migration: explicit remote OS-env merge at the SDK boundary.
// Existing installs must pick up this runtime change; the wire stays at v5.
export const CC_MGR_BUNDLE_VERSION = '0.0.11' as const;

export type RpcId = number;

export interface RpcError {
  code: RpcErrorCode;
  message: string;
  /** Optional structured details — e.g. install log tail. */
  data?: unknown;
}

export type RpcErrorCode =
  | 'INVALID_PROTOCOL_VERSION'
  | 'UNKNOWN_METHOD'
  | 'INVALID_PARAMS'
  | 'NOT_INITIALIZED'
  | 'SESSION_NOT_FOUND'
  | 'SESSION_ALREADY_EXISTS'
  /** forceful kill 终止窗口 (inputQueue 已 end, consume loop 未退出) — 可重试。 */
  | 'SESSION_KILL_PENDING'
  /** kill + close 升级后 consume loop 仍未退出 (daemon 病态) — 需重启 daemon。 */
  | 'SESSION_KILL_TIMEOUT'
  | 'SDK_ERROR'
  | '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 ============================== */

/**
 * client → manager methods. Names are namespaced so we can group later.
 * Keep alphabetical inside each namespace.
 */
export const METHODS = {
  // Lifecycle / handshake
  PROTOCOL_HELLO: 'protocol/hello',

  // Query (1:1 with SDK Query object lifecycle)
  QUERY_START: 'query/start',
  QUERY_SEND: 'query/send',
  QUERY_SET_MODEL: 'query/setModel',
  QUERY_SET_PERMISSION_MODE: 'query/setPermissionMode',
  QUERY_APPLY_FLAG_SETTINGS: 'query/applyFlagSettings',
  QUERY_GET_CONTEXT_USAGE: 'query/getContextUsage',
  QUERY_INTERRUPT: 'query/interrupt',
  QUERY_STOP_TASK: 'query/stopTask',
  QUERY_CLOSE: 'query/close',

  // Session (manager-level — list / attach / kill independent of Query lifecycle)
  SESSION_ATTACH: 'session/attach',
  SESSION_LIST: 'session/list',
  SESSION_KILL: 'session/kill',
} as const;

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

/**
 * manager → client notification names.
 */
export const NOTIFICATIONS = {
  /** SDK message event for a session. Carries seq for replay ordering. */
  QUERY_EVENT: 'query/event',
  /** A session has been closed (terminal). */
  SESSION_CLOSED: 'session/closed',
  /** Current attach has been replaced by another client (single-attach policy). */
  CLIENT_REPLACED: 'client/replaced',
} as const;

/**
 * manager → client request methods (reverse-request: server asks, client responds).
 *
 * Used for bi-directional interactions that need a response from the desktop:
 * permission approval, ask-user-question, plan review, etc.
 */
export const SERVER_METHODS = {
  /** SDK's canUseTool fired — daemon needs desktop to approve/deny a tool use. */
  APPROVAL_REQUEST: 'approval/request',
  /** Agent/Task PreToolUse 向 desktop 查询当前账号与路由的模型准入状态。 */
  SUBAGENT_MODEL_ACCESS: 'subagent/model-access',
  /**
   * SDK's getOAuthToken fired — remote cc hit a 401 on its subscription OAuth
   * token and the daemon needs desktop to mint a fresh one
   * (auth.getFreshSubscriptionToken). Additive (protocol version unchanged):
   * old desktops answer UNKNOWN_METHOD → daemon returns null to the SDK,
   * degrading to the pre-refresh behavior (session surfaces the auth error).
   */
  OAUTH_REFRESH: 'oauth/refresh',
} as const;

export type ServerMethodName = (typeof SERVER_METHODS)[keyof typeof SERVER_METHODS];

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;
}

/**
 * Subset of SDK options we forward. canUseTool is handled via bi-directional
 * RPC (SERVER_METHODS.APPROVAL_REQUEST). Hooks are not forwarded (Phase N).
 */
export interface QueryStartParams {
  sessionId: string;
  /**
   * Resume an existing SDK session by its UUID (the SDK's internal session_id,
   * NOT our manager sessionId). Optional.
   */
  resumeSdkSessionId?: string;
  cwd: string;
  model: string;
  env: Record<string, string>;
  /**
   * MCP servers — only stdio/sse/http transport configs are accepted.
   * In-process MCP (`McpSdkServerConfigWithInstance`) is rejected because
   * `instance` is a non-serializable McpServer object.
   */
  mcpServers?: Record<string, McpServerStdioConfig | McpServerSseConfig | McpServerHttpConfig>;
  /** Permission mode forwarded to SDK. Desktop passes through user's selection. */
  permissionMode?: 'default' | 'acceptEdits' | 'plan' | 'auto' | 'bypassPermissions';
  /** SDK options.systemPrompt — string or { type: 'preset', preset: 'claude_code', append? }. */
  systemPrompt?: unknown;
  /** SDK options.additionalDirectories. */
  additionalDirectories?: string[];
  /** SDK options.allowedTools / disallowedTools. */
  allowedTools?: string[];
  disallowedTools?: string[];
  /** SDK options.tools (preset). */
  tools?: unknown;
  /**
   * Host-owned, daemon-enforced tool routing guards.
   *
   * These are materialized as in-process PreToolUse hooks on the remote
   * machine. Keeping them outside `extraOptions` prevents remote user/project
   * permission allow rules (or bypassPermissions) from silently skipping the
   * host's capability-source choice.
   */
  toolGuards?: QueryToolGuard[];
  /** Any extra SDK options we want to pass through verbatim. */
  extraOptions?: Record<string, unknown>;
}

export interface QueryToolGuard {
  /** Exact SDK tool name for root-only guards, or a tool-name prefix otherwise. */
  toolNamePrefix: string;
  /** Exact harness-owned MCP server id before Claude normalizes punctuation. */
  sourceServerId?: string;
  invocation: 'auto' | 'explicit-only' | 'disabled' | 'root-only';
  /** Explicit command tokens that select this source for the active turn. */
  explicitSelectors?: string[];
  /** Optional user-facing denial reason returned by the PreToolUse hook. */
  denialMessage?: string;
}

export interface QueryStartResult {
  sessionId: string;
  /** SDK-assigned session UUID once the first message arrives. May be empty initially. */
  sdkSessionId?: string;
}

export interface SubagentModelAccessParams {
  sessionId: string;
  /** 已按 CLAUDE_CODE_SUBAGENT_MODEL 优先级及 [1m] 后缀归一化。 */
  model: string;
}

export interface SubagentModelAccessResult {
  status: 'allowed' | 'denied' | 'unknown';
  reason?: string;
}

export interface QuerySendParams {
  sessionId: string;
  /**
   * The SDKUserMessage envelope verbatim. Manager pushes this into the
   * SDK's inputQueue → streamInput consumer.
   */
  message: unknown;
}

export interface QuerySetModelParams {
  sessionId: string;
  model: string;
}

export interface QuerySetPermissionModeParams {
  sessionId: string;
  mode: 'default' | 'acceptEdits' | 'plan' | 'auto' | 'bypassPermissions';
}

export interface QueryApplyFlagSettingsParams {
  sessionId: string;
  settings: Record<string, unknown>;
}

export interface QueryGetContextUsageParams {
  sessionId: string;
}

export interface QueryInterruptParams {
  sessionId: string;
}

/** query/stopTask — 停止会话内单个后台任务(SDK Query.stopTask 透传)。 */
export interface QueryStopTaskParams {
  sessionId: string;
  /** SDK task_notification 事件里的 task id。 */
  taskId: string;
}

export interface QueryCloseParams {
  sessionId: string;
}

export interface SessionAttachParams {
  sessionId: string;
  /** If set, manager replays events with seq > sinceSeq before switching to live. */
  sinceSeq?: number;
}

export interface SessionAttachResult {
  sessionId: string;
  /** Highest seq currently buffered. Client should update its sinceSeq to this. */
  currentSeq: number;
  /** Whether the underlying Query is still alive (false = session has exited). */
  alive: boolean;
  /** True when the retained ring buffer could not cover the requested sinceSeq. */
  replayLossy: boolean;
}

export interface SessionListParams {
  /** Empty for now. */
}

export interface SessionListEntry {
  sessionId: string;
  sdkSessionId?: string;
  cwd: string;
  model: string;
  /** seq of latest buffered event. */
  lastSeq: number;
  /** Whether the underlying Query is still alive. */
  alive: boolean;
  /** ISO timestamp when manager created this session. */
  startedAt: string;
  /** ISO timestamp of last event. */
  lastEventAt: string | null;
}

export interface SessionListResult {
  sessions: SessionListEntry[];
}

export interface SessionKillParams {
  sessionId: string;
}

/* ============================== Server → Client request shapes ============================== */

/**
 * Approval request — daemon's SDK canUseTool callback fired, needs desktop to
 * approve/deny. Maps to the same InteractionRequest kinds in maker-core:
 * 'permission' | 'ask_user_question' | 'plan_review'.
 */
export interface ApprovalRequestParams {
  sessionId: string;
  /** Unique request ID (SDK's toolUseID). Used to correlate response. */
  requestId: string;
  /** Interaction kind — matches maker-core InteractionRequest.kind. */
  kind: 'permission' | 'ask_user_question' | 'plan_review';
  /** Tool name (for 'permission' kind). */
  toolName?: string;
  /** Tool input (for 'permission' kind). */
  input?: Record<string, unknown>;
  /** Display title (for 'permission' kind). */
  title?: string;
  /** Display name override (for 'permission' kind). */
  displayName?: string;
  /** Description (for 'permission' kind). */
  description?: string;
  /** Permission suggestions (for 'permission' kind). */
  suggestions?: unknown[];
  /** Metadata (for 'permission' kind). */
  metadata?: Record<string, unknown>;
  /** Questions (for 'ask_user_question' kind). */
  questions?: unknown[];
  /** Plan text (for 'plan_review' kind). */
  plan?: string;
  /** Plan file path (for 'plan_review' kind). */
  planFilePath?: string;
}

/**
 * OAuth refresh request — daemon's SDK getOAuthToken callback fired (remote cc
 * got a 401 on the spawn-time subscription token). Desktop should return a
 * fresh access token, or null when refresh is impossible (logged out, refresh
 * token revoked) — the SDK then surfaces the auth error to the session.
 */
export interface OAuthRefreshParams {
  /**
   * Session asking for the refresh. Deliberately the only field: desktop's own
   * env/credential store is the source of truth for the stale-token baseline,
   * and echoing the daemon-side token back over the wire would widen the
   * token's exposure surface for no consumer.
   */
  sessionId: string;
}

export interface OAuthRefreshResult {
  /** Fresh subscription access token, or null when refresh failed. */
  token: string | null;
}

/**
 * Response from desktop for an approval request.
 */
export interface ApprovalRequestResult {
  /** Decision kind — must match the request's kind. */
  kind: 'permission' | 'ask_user_question' | 'plan_review';
  /** For 'permission': 'allow' | 'deny'. */
  behavior?: 'allow' | 'deny';
  /** For 'permission': updated input if user modified. */
  updatedInput?: Record<string, unknown>;
  /** For 'permission': permission rule updates. */
  permissionUpdates?: unknown[];
  /** For 'permission'/'plan_review': denial reason. */
  reason?: string;
  /** For 'ask_user_question': user answers. */
  answers?: Record<string, string>;
  /** For 'plan_review': edited plan text. */
  editedPlan?: string;
  /** System dismissal rather than user-authored plan feedback. */
  dismissed?: boolean;
}

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

export interface QueryEventNotification {
  sessionId: string;
  /** Manager-assigned monotonic seq within the session. Used for replay. */
  seq: number;
  /** ISO timestamp when manager observed this event. */
  ts: string;
  /** SDKMessage verbatim (JSON-serializable per SDK design). */
  message: unknown;
}

export interface SessionClosedNotification {
  sessionId: string;
  /** Why the session ended — exit normally, killed, crashed, etc. */
  reason: 'completed' | 'closed' | 'killed' | 'error';
  /** Optional human-readable detail. */
  detail?: string;
}

export interface ClientReplacedNotification {
  sessionId: string;
  /** Always 'another-client-attached' for now — kept open for future reasons. */
  reason: 'another-client-attached';
}

/* ============================== MCP server config (cross-process safe) ============================== */

export interface McpServerStdioConfig {
  type?: 'stdio';
  command: string;
  args?: string[];
  env?: Record<string, string>;
}

export interface McpServerSseConfig {
  type: 'sse';
  url: string;
  headers?: Record<string, string>;
}

export interface McpServerHttpConfig {
  type: 'http';
  url: string;
  headers?: Record<string, 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') {
    return typeof v.id === 'number' && typeof v.method === 'string';
  }
  if (v.type === 'response') {
    return typeof v.id === 'number';
  }
  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 } : {}) };
}