Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* RemoteQuery — a "fake SDK Query" that fulfils the @anthropic-ai/claude-agent-sdk
* Query interface by translating each call into NDJSON RPC against a remote
* cc-manager daemon.
*
* Lifecycle:
* const remote = await createRemoteQuery({ client, sessionId, startParams });
* for await (const message of remote) { ... }
* await remote.setModel('claude-haiku-4-5');
* await remote.interrupt();
* await remote.close();
*
* Threading model: events arrive as RpcNotifications and are queued; the
* AsyncIterator pulls them in FIFO order. setModel/etc. issue RPC requests
* and await the matching response.
*
* The returned object intentionally narrows the SDK Query interface to what
* ClaudeCodeAgent's consumer loop actually needs. Methods like rewindFiles
* / supportedModels / mcpServerStatus are not exposed (not MVP).
*/
import { createAsyncQueue } from './async-queue.js';
import { NOTIFICATIONS, METHODS } from './protocol.js';
import type {
QueryEventNotification,
QueryStartParams,
QueryStartResult,
SessionAttachResult,
SessionClosedNotification,
} from './protocol.js';
import type { RpcClient } from './client.js';
export interface RemoteQueryOptions {
/** Connected + hello'd RpcClient. Caller owns lifecycle. */
client: RpcClient;
/** Session id (manager-side). Must match the one used at create / attach. */
sessionId: string;
}
export interface CreateRemoteQueryOptions extends RemoteQueryOptions {
/**
* If set, calls `query/start` to create a new session before yielding the
* remote query. Mutually exclusive with `attach`.
*/
startParams?: Omit<QueryStartParams, 'sessionId'>;
/**
* If set, calls `session/attach` to resume an existing session. Mutually
* exclusive with `startParams`. Optional `sinceSeq` is forwarded so the
* server can replay missed events (Phase 5).
*/
attach?: { sinceSeq?: number };
/**
* Per-request RPC timeout (ms). Applied to query/start, query/send,
* setModel/setPermissionMode/applyFlagSettings/interrupt, query/close.
* 不传 = 无 timeout (request 永远等); 强烈建议传, 否则 daemon hang 时
* client send 路径无限等。RPC 默认 timeoutMs=15_000 跟 cc-manager-client
* 顶层 RPC_REQUEST_TIMEOUT_MS 对齐。
*/
rpcTimeoutMs?: number;
/** Called when the manager reports that ring-buffer replay lost events
* (mid-turn reattach 超出内存 buffer 容量)。jsonl recovery 会兜底, 仅用于日志。 */
onReplayLossy?: (result: SessionAttachResult) => void;
}
export interface RemoteQuery extends AsyncIterable<unknown> {
/** Session id. */
readonly sessionId: string;
/** Push a user message into the session's input queue (transports to query/send RPC). */
send(message: unknown): Promise<void>;
/** Forward to query/setModel. */
setModel(model?: string): Promise<void>;
/** Forward to query/setPermissionMode. */
setPermissionMode(mode: string): Promise<void>;
/** Forward to query/applyFlagSettings. */
applyFlagSettings(settings: Record<string, unknown>): Promise<void>;
/** Forward to query/getContextUsage. */
getContextUsage(): Promise<unknown>;
/** Forward to query/interrupt. */
interrupt(): Promise<void>;
/**
* Forward to query/stopTask — stop a single background task (subagent /
* workflow). Old daemons without this method reject the RPC; callers should
* degrade gracefully (maker-core catches and warns).
*/
stopTask(taskId: string): Promise<void>;
/**
* Close: ends the local iterator and calls query/close on manager.
* After close, send/setModel/etc. all reject. Iterator yields done.
*/
close(): Promise<void>;
/**
* Detach: ends the local iterator without query/close, preserving the
* daemon-side session for later reattach.
*/
detach(): Promise<void>;
}
export async function createRemoteQuery(opts: CreateRemoteQueryOptions): Promise<RemoteQuery> {
if (opts.startParams && opts.attach) {
throw new Error('createRemoteQuery: startParams and attach are mutually exclusive');
}
if (!opts.startParams && !opts.attach) {
throw new Error('createRemoteQuery: must specify either startParams or attach');
}
const messageQueue = createAsyncQueue<{ seq: number; message: unknown }>();
let closed = false;
// round-14: 所有内部 RPC 走同款 timeout 兜底, 跟 cc-manager-client 顶层 RPC
// 一致 (greptile P2 finding remote-query.ts:172)。daemon hang 时 send/control
// 路径不会无限等。
const rpcOpts = opts.rpcTimeoutMs !== undefined ? { timeoutMs: opts.rpcTimeoutMs } : {};
// Subscribe to notifications for this session BEFORE start/attach to avoid
// racing the first event (init message arrives immediately after start).
const unsubscribe = opts.client.subscribe((n) => {
if (n.method === NOTIFICATIONS.QUERY_EVENT) {
const evt = n.params as QueryEventNotification;
if (evt.sessionId === opts.sessionId) {
messageQueue.push({ seq: evt.seq, message: evt.message });
}
return;
}
if (n.method === NOTIFICATIONS.SESSION_CLOSED) {
const evt = n.params as SessionClosedNotification;
if (evt.sessionId === opts.sessionId) {
if (!closed) {
closed = true;
messageQueue.end();
}
}
return;
}
if (n.method === NOTIFICATIONS.CLIENT_REPLACED) {
const evt = n.params as { sessionId: string };
if (evt.sessionId === opts.sessionId) {
if (!closed) {
closed = true;
messageQueue.end();
}
}
return;
}
});
// Lifecycle: when the underlying RPC stream closes (peer hung up — daemon
// killed by force-upgrade / SIGKILL / network blip / restart), treat it as
// an implicit session end. Without this, the async iterator wedges on an
// empty queue forever — SESSION_CLOSED notification may have been lost in
// the truncated write buffer of a dying daemon.
// The U2 fallback in ClaudeCodeAgent's startForwardLoop relies on the
// iterator actually returning to push its error event; we deliver that
// signal here.
const unsubscribeClose = opts.client.subscribeClose(() => {
if (!closed) {
closed = true;
messageQueue.end();
}
});
// Perform start or attach.
if (opts.startParams) {
const params: QueryStartParams = {
sessionId: opts.sessionId,
...opts.startParams,
};
await opts.client.request<QueryStartResult>(METHODS.QUERY_START, params, rpcOpts);
} else if (opts.attach) {
const params = {
sessionId: opts.sessionId,
...(opts.attach.sinceSeq !== undefined ? { sinceSeq: opts.attach.sinceSeq } : {}),
};
const result = await opts.client.request<SessionAttachResult>(METHODS.SESSION_ATTACH, params, rpcOpts);
if (result.replayLossy) {
closed = true;
unsubscribe();
unsubscribeClose();
messageQueue.end();
opts.onReplayLossy?.(result);
throw new Error(
`RemoteQuery(${opts.sessionId}) replay buffer is lossy; start a new remote session`,
);
}
if (!result.alive) {
closed = true;
messageQueue.end();
}
}
async function send(message: unknown): Promise<void> {
if (closed) throw new Error(`RemoteQuery(${opts.sessionId}) is closed`);
await opts.client.request(METHODS.QUERY_SEND, {
sessionId: opts.sessionId,
message,
}, rpcOpts);
}
async function setModel(model?: string): Promise<void> {
if (closed) throw new Error(`RemoteQuery(${opts.sessionId}) is closed`);
await opts.client.request(METHODS.QUERY_SET_MODEL, {
sessionId: opts.sessionId,
model: model ?? '',
}, rpcOpts);
}
async function setPermissionMode(mode: string): Promise<void> {
if (closed) throw new Error(`RemoteQuery(${opts.sessionId}) is closed`);
await opts.client.request(METHODS.QUERY_SET_PERMISSION_MODE, {
sessionId: opts.sessionId,
mode,
}, rpcOpts);
}
async function applyFlagSettings(settings: Record<string, unknown>): Promise<void> {
if (closed) throw new Error(`RemoteQuery(${opts.sessionId}) is closed`);
await opts.client.request(METHODS.QUERY_APPLY_FLAG_SETTINGS, {
sessionId: opts.sessionId,
settings,
}, rpcOpts);
}
async function getContextUsage(): Promise<unknown> {
if (closed) throw new Error(`RemoteQuery(${opts.sessionId}) is closed`);
return opts.client.request(METHODS.QUERY_GET_CONTEXT_USAGE, {
sessionId: opts.sessionId,
}, rpcOpts);
}
async function interrupt(): Promise<void> {
if (closed) throw new Error(`RemoteQuery(${opts.sessionId}) is closed`);
await opts.client.request(METHODS.QUERY_INTERRUPT, {
sessionId: opts.sessionId,
}, rpcOpts);
}
async function stopTask(taskId: string): Promise<void> {
if (closed) throw new Error(`RemoteQuery(${opts.sessionId}) is closed`);
await opts.client.request(METHODS.QUERY_STOP_TASK, {
sessionId: opts.sessionId,
taskId,
}, rpcOpts);
}
async function close(): Promise<void> {
if (closed) return;
closed = true;
unsubscribe();
unsubscribeClose();
try {
await opts.client.request(METHODS.QUERY_CLOSE, {
sessionId: opts.sessionId,
}, rpcOpts);
} catch {
/* manager may be unreachable — best effort */
}
messageQueue.end();
}
async function detach(): Promise<void> {
if (closed) return;
closed = true;
unsubscribe();
unsubscribeClose();
messageQueue.end();
}
return {
sessionId: opts.sessionId,
send,
setModel,
setPermissionMode,
applyFlagSettings,
getContextUsage,
interrupt,
stopTask,
close,
detach,
[Symbol.asyncIterator]: async function* (): AsyncGenerator<unknown> {
// live 事件直接透传 — 持久化由 desktop 的 message DB 收口(register.ts
// onEvent → broadcaster)。RemoteQuery 不承担 cursor / prefill / ack 职责。
// **MVP**:断开期间(dead session)的历史不恢复;基于 SDK jsonl 的
// read-since-lineNo recovery 是 follow-up,尚未实现。
for await (const evt of messageQueue) {
yield evt.message;
}
},
};
}