Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* pi-manager server — unix socket NDJSON RPC listener.
*
* Lifecycle:
* const server = new ManagerServer({ socketPath: '...' });
* await server.start();
* ...
* await server.stop();
*
* Single-process daemon; multiple clients can connect to the same socket
* (e.g. one for pi/ensure, another for session/list). Each connection is
* independent. The pi session bridge itself is NOT an RPC method — clients
* run `pi-manager bridge --socket <sockPath>` as a separate process that
* pipes stdio to the session socket.
*
* Structure mirrors packages/maker-cc-manager/src/server.ts deliberately —
* the socket dispatch skeleton is copied (not shared) to keep cc-mgr
* byte-identical and untouched. SDK-specific logic is absent here.
*/
import * as net from 'node:net';
import * as fs from 'node:fs/promises';
import * as path from 'node:path';
import { NDJSONDecoder, encodeMessage } from './codec.js';
import {
METHODS,
PROTOCOL_VERSION,
isRpcNotification,
isRpcRequest,
isRpcResponse,
makeRpcError,
type HelloParams,
type HelloResult,
type RpcError,
type RpcErrorCode,
type RpcId,
type RpcMessage,
type RpcNotification,
type RpcRequest,
type RpcResponse,
} from './protocol.js';
export interface ManagerServerOptions {
/** Absolute path to the unix socket. Parent dir is created if missing. */
socketPath: string;
/** Manager build / git SHA, returned in hello result. */
managerVersion?: string;
/** Optional logger. Defaults to console. */
logger?: ManagerLogger;
}
export interface ManagerLogger {
debug(msg: string, ctx?: Record<string, unknown>): void;
info(msg: string, ctx?: Record<string, unknown>): void;
warn(msg: string, ctx?: Record<string, unknown>): void;
error(msg: string, ctx?: Record<string, unknown>): void;
}
const defaultLogger: ManagerLogger = {
debug: () => undefined,
info: (msg, ctx) => console.error('[pi-mgr][info]', msg, ctx ?? ''),
warn: (msg, ctx) => console.error('[pi-mgr][warn]', msg, ctx ?? ''),
error: (msg, ctx) => console.error('[pi-mgr][error]', msg, ctx ?? ''),
};
export interface ClientCtx {
socket: net.Socket;
decoder: NDJSONDecoder;
/** Set true after a successful PROTOCOL_HELLO. */
initialized: boolean;
/** Optional client identifier from hello — for log correlation. */
clientId?: string;
/** 该连接当前 in-flight 的 handler 数(轮 40-w4 MEDIUM-2:per-client 限流)。 */
inflight: number;
}
/**
* Handler signature. Must return either a result payload (any JSON-serializable
* value) or throw with .code matching RpcErrorCode for typed error responses.
*/
export type MethodHandler = (params: unknown, ctx: ClientCtx) => Promise<unknown> | unknown;
interface PendingServerRequest {
resolve: (result: unknown) => void;
reject: (err: Error) => void;
timer?: NodeJS.Timeout;
ctx: ClientCtx;
}
/**
* 凭证强脱敏(corrupt line 日志样本用, 轮 40-w4-t4 CRITICAL):按常见凭证格式
* 掩码。与 session-registry 的 scrubCredentialText 同策略, 这里内联避免
* server↔session-registry 循环 import。漏掩代价 > 误掩(样本仅诊断用)。
*/
const CREDENTIAL_SCRUB_RE =
/(?<![A-Za-z0-9])(sk-(?:ant|or|proj|admin|svcacct)-[A-Za-z0-9_-]{8,}|sk-[A-Za-z0-9_-]{20,}|gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|AIza[A-Za-z0-9_-]{20,}|hf_[A-Za-z0-9]{20,}|xox[baprs]-[A-Za-z0-9-]{10,}|LTAI[A-Za-z0-9]{16,}|A(?:KIA|SIA)[A-Z0-9]{16}|Bearer\s+[A-Za-z0-9._~+/=-]{16,}|-----BEGIN [A-Z ]*PRIVATE KEY-----|-----BEGIN OPENSSH PRIVATE KEY-----|[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{20,})/g;
// 轮 40-w4-t5 CRITICAL:key-aware 敏感字段名 —— 值形状正则覆盖不了 64-hex
// sessionToken / 自定义 MCP header, 字段名命中即整体替换。
const SENSITIVE_KEY_RE =
/(^|[\s,{[])("?)([A-Za-z0-9_-]*)(token|secret|api[_-]?key|authorization|password|credential|CINDY_PI_MCP_BRIDGE|CINDY_PI_REMOTE_MCP_SECRET)([A-Za-z0-9_-]*)(\s*["]?\s*[:=]\s*)([^,\s}\]]+)/gi;
function redactSensitiveText(text: string): string {
let out = text.replace(CREDENTIAL_SCRUB_RE, '[REDACTED]');
out = out.replace(SENSITIVE_KEY_RE, (_m, pre: string, quote: string, _k1: string, _k2: string, _k3: string, sep: string) =>
`${pre}${quote}[REDACTED]${sep}[REDACTED]`);
return out;
}
function isWindowsNamedPipe(socketPath: string): boolean {
// 匹配 \\?\pipe\ 与 \\.\pipe\(轮 11 修复:原正则只匹配 \\?\pipe\ 而实际
// named pipe 前缀是 \\.\pipe\ —— 误判导致对 pipe 执行 chmod/rm, 破坏连接)。
return /^\\\\[.?]\\pipe\\/.test(socketPath);
}
/** 最大并发客户端连接数(DoS 防护 —— 退役审轮 3 M-2)。 */
const MAX_CLIENTS = 16;
/** 单客户端 in-flight 请求上限(轮 40-w4 MEDIUM-2)。正常使用单请求串行,
* 上限 32 覆盖并发 ensure/kill/list 的合理场景;超限 = 请求洪泛, 拒绝。
* handler 最长 30s(ensure), 32 个并发 handler 的堆叠是接受的天花板。 */
const MAX_INFLIGHT_PER_CLIENT = 32;
const VALID_ERROR_CODES: ReadonlySet<string> = new Set<RpcErrorCode>([
'INVALID_PROTOCOL_VERSION',
'UNKNOWN_METHOD',
'INVALID_PARAMS',
'NOT_INITIALIZED',
'SESSION_NOT_FOUND',
'SESSION_ALREADY_EXISTS',
'SESSION_KILL_SURVIVED',
'SESSION_LIMIT_EXCEEDED',
'SERVER_BUSY',
'INTERNAL',
]);
function isValidErrorCode(code: string): code is RpcErrorCode {
return VALID_ERROR_CODES.has(code);
}
export function makeServerError(code: RpcErrorCode, message: string, data?: unknown): Error & {
code: RpcErrorCode;
data?: unknown;
} {
const err = new Error(message) as Error & { code: RpcErrorCode; data?: unknown };
err.code = code;
if (data !== undefined) err.data = data;
return err;
}
export class ManagerServer {
private readonly server: net.Server;
private readonly logger: ManagerLogger;
private readonly socketPath: string;
private readonly managerVersion?: string;
private readonly handlers = new Map<string, MethodHandler>();
private readonly clients = new Set<ClientCtx>();
private readonly pendingServerRequests = new Map<RpcId, PendingServerRequest>();
private readonly clientCloseListeners: Array<(ctx: ClientCtx) => void> = [];
private nextServerRequestId: RpcId = -1;
private started = false;
constructor(opts: ManagerServerOptions) {
this.socketPath = opts.socketPath;
this.managerVersion = opts.managerVersion;
this.logger = opts.logger ?? defaultLogger;
this.server = net.createServer((socket) => this.onConnection(socket));
this.registerBuiltinHandlers();
}
/** Register or override a method handler. Used by runDaemon to plug in pi session control. */
setHandler(method: string, handler: MethodHandler): void {
this.handlers.set(method, handler);
}
/**
* Send a request FROM server TO client and await the client's response.
* Uses negative IDs to avoid collision with client→server request IDs.
* Rejects on timeout or if the client disconnects before responding.
*/
async sendRequest<R = unknown>(
ctx: ClientCtx,
method: string,
params: unknown,
opts: { timeoutMs?: number } = {},
): Promise<R> {
const id = this.nextServerRequestId--;
return await new Promise<R>((resolve, reject) => {
const entry: PendingServerRequest = {
resolve: resolve as (v: unknown) => void,
reject,
ctx,
};
const timeoutMs = opts.timeoutMs ?? 120_000;
if (timeoutMs > 0) {
entry.timer = setTimeout(() => {
if (this.pendingServerRequests.delete(id)) {
reject(new Error(`server request ${method} timed out after ${timeoutMs}ms`));
}
}, timeoutMs);
}
this.pendingServerRequests.set(id, entry);
const request: RpcRequest = { type: 'request', id, method, params };
if (ctx.socket.destroyed) {
this.pendingServerRequests.delete(id);
if (entry.timer) clearTimeout(entry.timer);
reject(new Error('client socket destroyed before request could be sent'));
return;
}
// 编码失败(params 含循环引用等)时清理 pending entry, 不留到 timer(轮 2 L-4)。
try {
ctx.socket.write(encodeMessage(request));
} catch (err) {
this.pendingServerRequests.delete(id);
if (entry.timer) clearTimeout(entry.timer);
reject(new Error(`request ${method} serialization failed: ${(err as Error).message}`));
}
});
}
/** Register a listener invoked when any client disconnects. */
onClientClose(listener: (ctx: ClientCtx) => void): void {
this.clientCloseListeners.push(listener);
}
/**
* Broadcast a notification to every connected client (used for
* session/closed fan-out).
*/
notifyAll(notification: RpcNotification): void {
// 单个客户端编码失败(理论上 payload 可被 registry 传回循环引用)不拖累
// 其余广播 —— 轮 2 L-4 防御。
let frame: string;
try {
frame = encodeMessage(notification);
} catch (err) {
this.logger.error('notifyAll encode failed', { error: (err as Error).message });
return;
}
for (const ctx of this.clients) {
if (!ctx.socket.destroyed) {
ctx.socket.write(frame);
}
}
}
async start(): Promise<void> {
if (this.started) return;
// 显式 0700(默认 umask 022 给 0755, 同机其他用户可列 socket 文件名 —
// 深挖轮 5 L-4)。
// 轮 18 MEDIUM:named pipe 无需父目录(内核 NT 命名空间直接管理), 且
// path.dirname('\\\\.\\pipe\\x') = '\\.\pipe\' 在 Windows 被解释为
// 真实文件系统路径, mkdir 会泄漏 <盘>:\pipe\ 目录 —— 与 chmod/rm 同款守卫。
if (!isWindowsNamedPipe(this.socketPath)) {
await fs.mkdir(path.dirname(this.socketPath), { recursive: true, mode: 0o700 });
}
await new Promise<void>((resolve, reject) => {
const onError = (err: Error): void => {
this.server.removeListener('listening', onListening);
reject(err);
};
const onListening = (): void => {
this.server.removeListener('error', onError);
resolve();
};
this.server.once('error', onError);
this.server.once('listening', onListening);
this.server.listen(this.socketPath);
});
// 轮 11 MEDIUM-4:socket 文件 mode 显式 0600 —— 独立于目录 0700 的第二层
// 防线(目录守卫被削弱时 socket 不暴露)。非 Windows(named pipe 无文件)。
if (!isWindowsNamedPipe(this.socketPath)) {
try {
await fs.chmod(this.socketPath, 0o600);
} catch {
/* best-effort —— 目录 0700 已兜底 */
}
}
this.started = true;
this.logger.info('pi-manager listening', { socketPath: this.socketPath });
}
async stop(): Promise<void> {
if (!this.started) return;
for (const ctx of this.clients) {
try {
ctx.socket.destroy();
} catch {
/* ignore */
}
}
this.clients.clear();
await new Promise<void>((resolve) => this.server.close(() => resolve()));
if (!isWindowsNamedPipe(this.socketPath)) {
await fs.rm(this.socketPath, { force: true });
}
this.started = false;
this.logger.info('pi-manager stopped');
}
private registerBuiltinHandlers(): void {
this.handlers.set(METHODS.PROTOCOL_HELLO, async (params, ctx) => {
// 重复 hello 拒绝:协议要求每条连接握手一次, 重复会覆盖 clientId
// 造成日志身份混淆(轮 2 M-1)。
if (ctx.initialized) {
throw makeServerError('INVALID_PARAMS', 'protocol/hello already completed on this connection');
}
const p = (params ?? {}) as Partial<HelloParams>;
if (typeof p.protocolVersion !== 'number') {
throw makeServerError('INVALID_PARAMS', 'protocolVersion is required (number)');
}
if (p.protocolVersion !== PROTOCOL_VERSION) {
throw makeServerError(
'INVALID_PROTOCOL_VERSION',
`client version ${p.protocolVersion} != server version ${PROTOCOL_VERSION}`,
);
}
ctx.initialized = true;
ctx.clientId = p.clientId;
const result: HelloResult = {
protocolVersion: PROTOCOL_VERSION,
...(this.managerVersion ? { managerVersion: this.managerVersion } : {}),
};
return result;
});
}
private onConnection(socket: net.Socket): void {
// 连接数上限:每个连接分配 NDJSONDecoder(最大 64MB buffer), 无上限会被
// 连接洪泛耗尽 daemon 内存 —— 单 daemon 服务所有会话, DoS 面更集中
// (退役审轮 3 M-2)。超限直接 destroy。
if (this.clients.size >= MAX_CLIENTS) {
this.logger.warn('connection limit reached — rejecting', { maxClients: MAX_CLIENTS });
socket.destroy();
return;
}
const ctx: ClientCtx = {
socket,
decoder: new NDJSONDecoder({
// 轮 40-w4-t4 CRITICAL:corrupt NDJSON 行**不得**记录原文 —— 请求
// (如 pi/ensure)的 params 含真实凭证(env: CINDY_PI_API_KEY 等),
// 畸形/截断行会把 secret 写进 daemon log 并经 tail 回传桌面。
// 只记错误类型与行长度, 不记内容;样本经强脱敏后才保留(截断前)。
onCorruptLine: (line, err) =>
this.logger.warn('corrupt ndjson line', {
error: err.message,
lineLength: line.length,
sample: redactSensitiveText(line).slice(0, 200),
}),
}),
initialized: false,
inflight: 0,
};
this.clients.add(ctx);
this.logger.debug('client connected', { totalClients: this.clients.size });
// 应用层 idle 超时:连接建立后完全不活动(不读不写)占住 MAX_CLIENTS 槽位
// 的挂死连接 60s 后回收(轮 2 M-4)。60s 给慢请求(pi/ensure 最长 30s +
// SSH 链路延迟)留足余量;活动(读写)自动重置计时。
socket.setTimeout(60_000, () => {
this.logger.warn('client idle timeout — destroying', { totalClients: this.clients.size });
socket.destroy();
});
socket.on('data', (chunk: Buffer) => {
for (const msg of ctx.decoder.push(chunk)) {
void this.dispatch(ctx, msg);
}
});
socket.on('close', () => {
this.clients.delete(ctx);
this.rejectPendingForCtx(ctx);
for (const listener of this.clientCloseListeners) {
try { listener(ctx); } catch { /* */ }
}
this.logger.debug('client disconnected', { totalClients: this.clients.size });
});
socket.on('error', (err) => {
// error 后 close 事件必然跟随, 但中间窗口里该连接仍占 clients 槽位
// 且参与 notifyAll —— 直接 destroy 立即走 close 清理路径(轮 2 M-2)。
this.logger.warn('client socket error', { error: err.message });
socket.destroy();
});
}
private async dispatch(ctx: ClientCtx, msg: RpcMessage): Promise<void> {
if (isRpcResponse(msg)) {
this.handleServerRequestResponse(ctx, msg);
return;
}
if (isRpcNotification(msg)) {
// Notifications from client — ignored for now.
return;
}
const request = msg as RpcRequest;
// 负数 id 是 server→client 反向请求的保留命名空间(-1, -2, ...)。
// 客户端发负数 id 请求会与 pendingServerRequests 碰撞(错误地 resolve
// 反向请求 promise)—— 拒绝(自审轮 1 M-3)。
if (request.id < 0) {
this.sendResponse(ctx, request.id, undefined, makeRpcError('INVALID_PARAMS', 'client request ids must be non-negative'));
return;
}
if (!ctx.initialized && request.method !== METHODS.PROTOCOL_HELLO) {
this.sendResponse(ctx, request.id, undefined, makeRpcError('NOT_INITIALIZED', 'send protocol/hello first'));
return;
}
const handler = this.handlers.get(request.method);
if (!handler) {
this.sendResponse(ctx, request.id, undefined, makeRpcError('UNKNOWN_METHOD', `no handler for method ${request.method}`));
return;
}
// 轮 40-w4 MEDIUM-2:per-client in-flight 限流 —— 单连接 fire-and-forget
// dispatch 无上限时, 洪泛请求会堆积 handler promise / 定时器 / 异步工作,
// 并并发触发 ensure/kill。超限直接拒绝该请求(其它请求照常完成)。
if (ctx.inflight >= MAX_INFLIGHT_PER_CLIENT) {
this.sendResponse(
ctx,
request.id,
undefined,
makeRpcError('SERVER_BUSY', `too many in-flight requests (max ${MAX_INFLIGHT_PER_CLIENT})`),
);
return;
}
ctx.inflight += 1;
try {
const result = await handler(request.params, ctx);
this.sendResponse(ctx, request.id, result, undefined);
} catch (err) {
// 防御 throw null / throw undefined / throw non-object: e.code 访问前确保是对象。
// throw null → e={} → code=undefined → fallback='INTERNAL', message → 'internal error'.
const e = (
err != null && typeof err === 'object' ? err : {}
) as { code?: RpcErrorCode; message?: string; data?: unknown };
const code: RpcErrorCode = e.code && isValidErrorCode(e.code) ? e.code : 'INTERNAL';
// data 透传是协议契约(server.test.ts 显式断言 handler 抛 makeServerError
// 带 data → 响应带 data);只有内部 handler 通过 makeServerError 构造的
// 白名单 code 错误才带 data, 自定义 throw 的裸 data 不会进入协议路径
// (轮 2 L-2 初判「无消费方」有误, 已回滚)。
this.sendResponse(ctx, request.id, undefined, makeRpcError(code, e.message ?? 'internal error', e.data));
} finally {
ctx.inflight -= 1;
}
}
private rejectPendingForCtx(ctx: ClientCtx): void {
for (const [id, entry] of this.pendingServerRequests) {
if (entry.ctx === ctx) {
this.pendingServerRequests.delete(id);
if (entry.timer) clearTimeout(entry.timer);
entry.reject(new Error('client disconnected before responding'));
}
}
}
private handleServerRequestResponse(ctx: ClientCtx, msg: RpcResponse): void {
const entry = this.pendingServerRequests.get(msg.id);
if (!entry) return;
// 来源校验(轮 2 H-1):response 必须来自当初发送 server→client 请求的
// 同一条连接, 防止其它连接猜负 id 注入伪造响应。
if (entry.ctx !== ctx) return;
this.pendingServerRequests.delete(msg.id);
if (entry.timer) clearTimeout(entry.timer);
if (msg.error) {
// 防御畸形 error shape(error 非对象/缺 code/message —— 轮 2 L-1)。
const e = msg.error as Partial<RpcError>;
const code = typeof e.code === 'string' ? e.code : 'INTERNAL';
const message = typeof e.message === 'string' ? e.message : 'malformed error response';
entry.reject(new Error(`${code}: ${message}`));
} else {
entry.resolve(msg.result);
}
}
private sendResponse(ctx: ClientCtx, id: RpcId, result: unknown, error?: RpcError): void {
if (ctx.socket.destroyed) return;
const response: RpcResponse = error !== undefined
? { type: 'response', id, error }
: { type: 'response', id, result };
// 编码失败(handler 返回循环引用等 —— 轮 2 L-4)不 crash, 回干净错误。
try {
ctx.socket.write(encodeMessage(response));
} catch (err) {
this.logger.error('sendResponse encode failed', {
id,
error: (err as Error).message,
});
const fallback: RpcResponse = { type: 'response', id, error: { code: 'INTERNAL', message: 'response serialization failed' } };
try {
ctx.socket.write(encodeMessage(fallback));
} catch {
/* socket 已死, 放弃 */
}
}
}
}