Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
import type {
BrowserControlResult,
BrowserControlRuntime,
} from '@cindy/browser-control-runtime';
import type { AgentKind } from '@cindy/maker-core';
import type { Recipe, SiteGuide } from './browser/recipe-loader.js';
export interface LiziMcpLogger {
trace(...args: unknown[]): void;
debug(...args: unknown[]): void;
info(...args: unknown[]): void;
warn(...args: unknown[]): void;
error(...args: unknown[]): void;
fatal?(...args: unknown[]): void;
}
export interface SavedImage {
fileId: string;
filename: string;
originalPath: string;
xdtImageUrl: string;
bytes: number;
}
/**
* Inline preview target for image blocks returned to the LLM, in raw bytes
* (pre-base64). Why 140KB: Claude Code 的 stream-json 输出对 >256KiB 的行做
* 分块写,分块间隙可能被同进程的其它 stdout 写入(如 ANTHROPIC_LOG=debug 的
* 请求日志)插队,导致整行 JSON 损坏、agent-sdk 按"非 JSON 输出"静默丢弃 —
* 表现为 tool_result echo 丢失、聊天流图片卡不渲染、tool_result 不落库。
* 140KB 原始字节 ≈ 187KB base64,加上 JSON 摘要与消息包装后整行稳定
* < 256KiB(单次原子写,不可插队)。原图始终全分辨率落盘、经 xdt-image://
* 渲染,这个上限只影响给模型看的内联副本。
*/
export const INLINE_IMAGE_TARGET_BYTES = 140_000;
/**
* Host-supplied compressor for inline (LLM-facing) image copies. Returns the
* re-encoded buffer + mime, or null when the image should be inlined as-is
* (already under targetBytes / not decodable / host has no codec). Must never
* throw — degrade to null instead.
*/
export type CompressInlineImageFn = (
buffer: Buffer,
mime: string,
opts: { targetBytes: number },
) => Promise<{ buffer: Buffer; mime: string } | null>;
/**
* 带媒体(xdt_image_urls / xdt_video_urls 等)的工具结果快照,在 MCP 工具于
* host main 进程内执行完成的瞬间同步上报。用途:tool_result 的 SDK stdout
* echo 可能被日志污染损坏而丢失(见 INLINE_IMAGE_TARGET_BYTES 注释),host
* 据此在 turn 结束时把未收到 echo 的媒体结果直接落库渲染,不再依赖 echo。
* `args` 用于与对应 tool_use 的 input.args 做确定性配对(jobId / prompt 等)。
*/
export interface MediaToolResultPayload {
/** 工具入参(与 tool_use input.args 同构),配对键。 */
args: Record<string, unknown>;
/** 结果的 text block 原文(内含 xdt_image_urls 等渲染契约字段)。 */
resultText: string;
}
/** Host 注入的媒体结果上报回调。必须自吞异常,不得影响工具主流程。 */
export type OnMediaToolResultFn = (payload: MediaToolResultPayload) => void;
export interface SavedVideoRef {
fileId: string;
filename: string;
originalPath: string;
xdtVideoUrl: string;
bytes: number;
mime: string;
}
// Jira / Confluence 的 deps 与结果类型已随 lizi_jira / lizi_confluence 退役
// (2026-07-14,迁入内置意识 xd-atlassian)整体删除。
export interface FeishuBotSendFileResult {
ok: boolean;
reason?: string;
}
/**
* Result shape for the send-message channel. Kept parallel to sendFile so the
* MCP tool handler can branch on a single `ok` flag. `messageId` is what
* feishu returns on success — surfaced back to the model so it can reference
* the message in follow-ups if it needs to.
*/
export interface FeishuBotSendMessageResult {
ok: boolean;
/** Feishu message id on success. */
messageId?: string;
/** False means delivery succeeded but replies cannot resume the originating session. */
sessionLinked?: boolean;
/** Short reason on failure (e.g. 'SEND_FAIL', 'EMPTY_TEXT'). */
reason?: string;
}
/**
* 当前 tool-call 的归属 session(host 从 LiziMcpSessionContext 取)。宿主据此选出
* 这一轮真正要出站的 bot:个人设置页那份 FeishuIM,或触发本轮的伙伴自有连接。
* 没有它(hook 会话 / 桌面任务)就回落到个人 bot。
*/
export interface FeishuBotHostSession {
sessionId?: string;
sessionInstanceId?: string;
/** Trusted host session metadata; preserves an explicit Feishu reply target. */
vendorOptions?: Readonly<Record<string, unknown>>;
}
/**
* 飞书轮次内工具用到的 transport 子集(结构类型:桌面侧传的是触发本轮的那条连接自己的
* `FeishuIM`,单测可用假对象)。所有方法都以这条连接的 bot 身份出站。
*/
export interface FeishuBotLaneTransport {
getService(): 'feishu' | 'lark';
getBotAppId(): string | null;
sendText(userId: string, text: string): Promise<{ messageId: string }>;
sendMarkdownText(userId: string, markdown: string): Promise<{ messageId: string }>;
replyText(replyToMessageId: string, text: string): Promise<{ messageId: string }>;
replyMarkdownText(replyToMessageId: string, markdown: string): Promise<{ messageId: string }>;
sendFile(userId: string, absPath: string, displayName?: string): Promise<FeishuBotSendFileResult & { messageId?: string }>;
reactToMessage(messageId: string, emojiType: string): Promise<string | null>;
removeMessageReaction(messageId: string, reactionId: string): Promise<void>;
getChatInfo(chatId: string): Promise<Record<string, unknown>>;
listChatMembers(
chatId: string,
opts?: { pageToken?: string; pageSize?: number },
): Promise<{
items: Array<{ memberId: string; name: string }>;
memberTotal: number | null;
nextPageToken: string | null;
}>;
getMessage(messageId: string): Promise<Record<string, unknown> | null>;
pinMessage(messageId: string): Promise<void>;
unpinMessage(messageId: string): Promise<void>;
recallMessage(messageId: string): Promise<void>;
callApi(args: {
method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
path: string;
params?: Record<string, unknown>;
data?: unknown;
}): Promise<Record<string, unknown>>;
}
/**
* 飞书轮次的逐轮作用域(桌面 `im/shared/channelToolScope.ts` 的租约投影)。由渠道在
* provider 开始本轮前登记、终态释放;**不来自模型参数**。没有作用域的调用一律 fail closed。
*/
export interface FeishuBotLaneScope {
im: FeishuBotLaneTransport;
/** lane userId(私聊 open_id 或 `g/{chatId}[/{threadId}]`),transport 解码后出站。 */
laneUserId: string;
/** 飞书原生 chat_id(私聊是 p2p chat)。 */
chatId: string;
/** 话题 id;非话题为空串。 */
threadId: string;
chatKind: 'direct' | 'group';
/** 触发本轮的是不是主人(Main 校验过的身份)。 */
requesterIsOwner: boolean;
/** 触发消息的 message_id(回复 / 表情的默认目标)。 */
triggerMessageId: string;
/** 伙伴自有连接(true)还是设置页个人 bot(false)。 */
companion: boolean;
/**
* 当前任务工作目录(来自本次 tool-call 的 session ctx,不来自模型参数);非主人触发的
* 轮次 send_file 只能发这里面的文件,缺省时一律拒绝。
*/
workingDir?: string;
}
export interface FeishuBotMcpHostDeps {
/**
* 读取当前 session 的飞书逐轮作用域;非飞书轮次 / 轮次已结束返回 null。宿主实现
* 用 `session.sessionId` + `sessionInstanceId` 查租约(旧实例借不到新实例权限)。
*/
readLaneScope?(session: FeishuBotHostSession): FeishuBotLaneScope | null;
sendFile(
chatId: string,
absPath: string,
displayName?: string,
session?: FeishuBotHostSession,
): Promise<FeishuBotSendFileResult>;
/**
* Push a markdown text message to the given chat (private DM). Backed by
* the same feishu bot the session is already talking through — host
* implementations should never fabricate a chatId or route to a different
* bot instance. Returns `{ok:false, reason}` on any error (SDK/network),
* never throws — the MCP tool handler translates the reason into an
* errorCode without needing try/catch around the call.
*/
sendMessage(
chatId: string,
markdown: string,
/** Trusted calling session, only for notifications to the bot owner. */
notificationSessionId?: string,
session?: FeishuBotHostSession,
): Promise<FeishuBotSendMessageResult>;
/**
* Return the bot's TOFU-recorded owner openId — i.e. the person who first
* DM'd the bot, semantically "the human this bot instance belongs to".
* Used as a **fallback receiver** for tools that need to notify the current
* user from sessions that were NOT triggered by a feishu message (e.g. a
* desktop chat session where the user typed "跑完之后通过飞书通知我").
*
* Returns null when no owner has been bound yet — user must DM the bot once
* first (same precondition as scheduler feishu-completion notifications).
*/
getOwnerOpenId(session?: FeishuBotHostSession): string | null | Promise<string | null>;
logger?: LiziMcpLogger;
}
export interface WechatBotSendMessageResult {
ok: boolean;
messageId?: string;
reason?: string;
}
export interface WechatBotSendFileResult {
ok: boolean;
messageId?: string;
reason?: string;
}
/** Host bridge for the personal WeChat proactive-message MCP. */
export interface WechatBotMcpHostDeps {
getActivePeerIdForSession(
sessionId: string | undefined,
): Promise<string | null> | string | null;
getMostRecentPeerId(): Promise<string | null> | string | null;
sendMessage(peerId: string, text: string): Promise<WechatBotSendMessageResult>;
sendFile(
peerId: string,
absPath: string,
displayName?: string,
): Promise<WechatBotSendFileResult>;
logger?: LiziMcpLogger;
}
// ── cindy_slack(Slack 网关工具, 2026-07 并轨 hook 通道) ──────────────────────
/** Slack 网关工具的结构化错误(hook-control manager 定义的同构形状)。 */
export interface SlackToolBridgeError {
code: string;
message: string;
}
/** callTool 的结构化结果(桥永不 throw)。 */
export type SlackToolBridgeResult =
| { ok: true; result: unknown }
| { ok: false; error: SlackToolBridgeError };
/**
* hook-control 的 Slack 工具桥(结构性 duck type —— 本包不 import desktop
* 模块, host 侧实现为 hook-control/slackToolBridge 注册表里的桥对象)。
* multiTeam / bindings: (multi-team)多 workspace 绑定信息 —— 多绑定时非
* status 工具必须带 teamId, server 拒绝猜测(AMBIGUOUS_TEAM)。旧 host 实现
* 可能缺这两个字段, 消费方按 undefined 宽松处理。
*/
export interface SlackToolBridgeLike {
availability(): {
connected: boolean;
bound: boolean;
serverSupportsTools: boolean;
multiTeam?: boolean;
bindings?: Array<{ teamId: string; teamName: string | null }>;
};
callTool(
tool: string,
args?: Record<string, unknown>,
teamId?: string | null,
): Promise<SlackToolBridgeResult>;
}
/**
* cindy_slack 的 host 依赖: getBridge 每次现取(hook-control 未初始化 / 已
* dispose 时为 null, 工具 fail-closed); workingDir 由 provider 从 ctx 绑定
* (大结果落盘的钳制根)。
*/
export interface SlackHookMcpDeps {
compressInlineImage?: CompressInlineImageFn;
withAccountDataAccess?: import('./account-data-access.js').AccountDataAccess;
getSessionContext?: () => LiziMcpSessionContext;
getBridge(): SlackToolBridgeLike | null;
/** 当前会话工作目录(out_file 泄洪根; 空 = 不落盘只截断)。 */
workingDir?: string;
logger?: LiziMcpLogger;
}
/** Native routine service; only caller-bound companion tools expose it to agents. */
export interface RoutineToolService {
list(botId: string): Promise<import('@cindy/maker-scheduler').Routine[]>;
sources(): Promise<import('@cindy/maker-scheduler').RoutineSource[]>;
save(botId: string, input: import('@cindy/maker-scheduler').RoutineInput, id?: string): Promise<import('@cindy/maker-scheduler').Routine>;
history(botId: string, id: string): Promise<import('@cindy/maker-scheduler').RoutineRun[]>;
remove(botId: string, id: string): Promise<void>;
runNow(botId: string, id: string): Promise<void>;
}
/**
* Host injects a `getScheduler()` accessor — the cindy_scheduler MCP server
* never holds a long-lived Scheduler reference because the host may
* `resetScheduler()` on logout / 切账号. Each tool call dereferences
* fresh; reset-window calls throw `'scheduler not started'` which the MCP
* server translates to `SCHEDULER_NOT_READY` (see scheduler/errors.ts).
*
* Type imported from `@cindy/maker-scheduler` is **type-only** — runtime
* coupling stays one-way (@cindy/mcps → @cindy/maker-scheduler types only;
* @cindy/maker-scheduler still has zero runtime deps per Phase 1).
*/
export interface SchedulerMcpDeps {
withAccountDataAccess?: import('./account-data-access.js').AccountDataAccess;
/** Live per-call check (Bot main tasks may change automations only on their owner's own turn). */
authorizeCall?: import('./tool-call-authority.js').ToolCallAuthorizer;
getScheduler(): import('@cindy/maker-scheduler').Scheduler;
/**
* 同账号其它电脑上的定时任务(host 注入,desktop 经既有 `maker:schedule:*` 远程控制通道)。
* 缺省 = host 未接 → 工具的 `device` 只接受 local,其它值返 REMOTE_UNSUPPORTED。
*/
remote?: import('./scheduler/_devices.js').SchedulerRemoteDeps;
/**
* 前置检查脚本(preRunHook)统一安装服务(host 注入,desktop 实现为
* scheduler-host/hook-script-generator.installHookScript):落盘路径规范、
* 命令拼装、落盘后自测全部由 host 代码保证,agent 不允许绕开它手写脚本文件。
* 缺省 = host 未接 → schedule_set_pre_run_hook 工具不注册
* (同 MemoryMcpDeps.searchSessions 模式)。
*/
hookScript?: SchedulerHookScriptService;
/**
* 本机定时任务可选的 Agent 运行位置与各处的模型(与协同 Worker 的 list_available_models
* 同一份 host 实现)。agentDeviceId:null = 本机。缺省 = schedule_list_models 不注册。
*/
listModels?: import('./xdt-helper/list_available_models.js').ListAvailableModelsDeps['listAvailableModels'];
logger?: LiziMcpLogger;
}
/** SchedulerMcpDeps.hookScript 的服务契约。 */
export interface SchedulerHookScriptService {
/**
* 可选:解析绑定会话(heartbeat)的工作目录。传 scheduleId 且该任务绑定了会话
* 时,schedule.workingDir 通常为空(或改绑后过期),脚本落盘/自测目录应以会话
* meta.workDir 为准。未注入时回落 schedule.workingDir 旧行为。
*/
resolveSessionWorkDir?(sessionId: string): Promise<string | undefined>;
/** Bound task's current Agent location; remote-only routes cannot generate local hook scripts. */
isSessionAgentOnOtherDevice?(sessionId: string): Promise<boolean>;
/**
* 把受支持的单脚本相对命令固化为绝对路径。任意 shell 命令保持原样;相对脚本
* 缺少原 cwd 或文件不存在时必须报错,避免改绑后以 fail-open 静默绕过 hook。
*/
stabilizeCommand?(input: { command: string; workingDir?: string }): Promise<string>;
install(input: {
/** agent 写好的脚本内容(Node ESM);与 description 至少给一个,都给时 script 优先。 */
script?: string;
/** 自然语言需求,由 host 侧 utility model 生成脚本(与 UI「AI 生成」同通道)。 */
description?: string;
scheduleName?: string;
workingDir?: string;
/** 修改流:现有命令,host 识别出旧脚本路径时覆写同一文件。 */
currentCommand?: string;
/** 任务显式选择的供应商;由 MCP 从目标 schedule 透传。 */
providerId?: string;
/** 任务使用的 agent runtime;由 MCP 从目标 schedule 透传。 */
agentKind?: AgentKind;
/** 任务显式选择的模型;由 MCP 从目标 schedule 透传。 */
model?: string;
}): Promise<{
command: string;
filePath: string;
content: string;
/** 落盘后立即执行一次的自测结果。 */
test: import('@cindy/maker-scheduler').PreRunHookRunResult;
}>;
}
/**
* cindy_memory MCP server 工厂参数。Claude 路径下 workdir 在
* toClaudeSdkConfig(ctx) 时按 session 绑定到 closure;Codex HTTP bridge 路径下
* server factory 初始化时 ctx 是全局空值,tool-call 阶段通过 getSessionContext()
* 取回当前 thread 的真实 workingDir。
*
* - getManager(): 跟 SchedulerMcpDeps.getScheduler 同模式 — host 注入函数, 每次
* tool 调用 lazy 拿 manager, 避免持长生命周期引用 (mode 切换时 manager 不会被
* 重建, 但留余地)
* - workdir: 当前 session 的工作目录绝对路径 fallback, manager.getStore(workdir) 用
* - getSessionContext: 可选运行时 ctx accessor。Codex bridge 用它覆盖初始化期空
* workdir;Claude 下返回闭包 ctx,行为等价于直接读 workdir。
* - searchSessions: 历史对话 FTS5 检索. 数据在 desktop SQLite (messages 表 + messages_fts
* 虚拟表), maker-core 不可达 — 必须 host 注入。可选: host 没接 messages_fts 时
* 缺省, session_search tool 注册时跳过。
*
* 依赖 @cindy/maker-core 的类型与少量 runtime 实现(ContactsError / import 管道 /
* vCard 序列化, workspace dep 已声明), 依赖方向仍单向 @cindy/mcps → maker-core。
*/
export interface MemoryMcpDeps {
withAccountDataAccess?: import('./account-data-access.js').AccountDataAccess;
/** Host captures the source turn before storage; invoked only for a successful write. */
beginWrite?: (context: LiziMcpSessionContext | undefined) => ((receipt: { key: string; title: string; action: 'created' | 'updated' }) => void);
getManager(): import('@cindy/maker-core').MakerMemoryManager;
workdir: string;
getSessionContext?: () => LiziMcpSessionContext;
/**
* 搜历史对话 (Hermes 风格). 复用 desktop messages 表挂的 FTS5 索引。
* 缺省 = host 没启用 → session_search tool 不注册 (跟 art video registry 同模式)。
*/
searchSessions?: SessionSearchFn;
logger?: LiziMcpLogger;
}
export interface LspMcpDeps {
workdir: string;
pool: import('./lsp/server/lsp-server-pool.js').LspServerPool;
logger?: LiziMcpLogger;
}
// ── cindy_ssh MCP deps ───────────────────────────────────────────────────────
//
// 结构化鸭子类型镜像 @cindy/maker-remote-ssh 的 HostSnapshot / RemoteHost /
// ConnectionPool 子集——不 import 那个包(连 type-only 也不要):@cindy/mcps 是纯
// 工具注册层,SSH 连接生命周期归 desktop main 管,这里只消费注入的能力面。
// 字段语义以 packages/maker-remote-ssh/src/types.ts 为准。
/** ConnectionPool.list() 返回的单主机快照子集。 */
export interface SshHostSnapshotLike {
config: {
/** SSH alias(= ~/.ssh/config 的 Host 指令),也是 pool 的主键。 */
id: string;
hostname: string;
port: number;
user: string;
authMethod: 'agent' | 'key';
/** Main-only path metadata used solely to redact model-visible errors. */
identityFile?: string;
sshAuthentication?: {
identityAgent?: string;
configuredIdentityFiles?: string[];
};
source: 'ssh-config' | 'manual';
};
status:
| 'disconnected'
| 'connecting'
| 'authenticating'
| 'ready'
| 'reconnecting'
| 'failed';
lastError?: string;
lastAuthLabel?: string;
statusChangedAt: number;
}
/** RemoteHost 的 exec 子集(一次性命令,收集全量输出)。 */
export interface SshRemoteHostLike {
exec(
cmd: string,
opts?: {
input?: string;
timeoutMs?: number;
label?: string;
/** 边读边生效的 per-stream 字节上限,越界即终止远端命令(防无上限输出攒爆内存)。 */
maxOutputBytes?: number;
},
): Promise<{
stdout: string;
stderr: string;
exitCode: number | null;
signal: string | null;
/** maxOutputBytes 生效时为 true——输出不完整且命令被提前终止。 */
truncated?: boolean;
}>;
}
/** ConnectionPool 子集。 */
export interface SshPoolLike {
list(): SshHostSnapshotLike[];
get(id: string): SshRemoteHostLike | undefined;
}
/**
* cindy_ssh MCP server 工厂参数。
*
* - getPool / ensureReady 都是 async:desktop 侧必须 lazy `await import()`
* remote-ssh 模块(静态 import 会形成 mcp-providers → remote-ssh →
* maker-host → mcp-providers 的环,先例见 mcp-providers.ts 的 scheduler
* hookScript 注入)。
* - ensureReady(id):不存在 / 连接失败时抛错;错误 message 以 `[CODE] ...`
* 前缀编码(desktop throwIpcError 协议),tool 层用 classifySshError
* best-effort 提取。
* - 插件启用策略由 host 在 Agent runtime / Codex thread 创建时冻结;这里不得
* 注入调用时读取设置的门控,否则工具暴露状态与执行权限会在运行中分叉。
*/
/** 与「设置 → 远程连接」添加表单同一份字段。 */
export interface SshAddHostInput {
id: string;
hostname: string;
port?: number;
user: string;
authMethod?: 'agent' | 'key';
identityFile?: string;
displayName?: string;
}
export interface SshMcpDeps {
getPool(): Promise<SshPoolLike>;
ensureReady(id: string): Promise<void>;
/** 设置页同一添加流程:写入本机 SSH 配置并刷新连接池;失败以 `[CODE] message` 抛出。 */
addHost(input: SshAddHostInput): Promise<void>;
/** 设置页「重新读取 ~/.ssh/config」。读取失败时返回诊断类别,连接池保持上次成功的结果。 */
reloadConfig(): Promise<{ diagnostic: string | null; warningCount: number }>;
/** Host-owned synchronous boundary redactor. It must not retain its inputs. */
redactSensitiveText(snapshot: SshHostSnapshotLike, text: string): string;
logger?: LiziMcpLogger;
}
/**
* cindy_contacts(智能通讯录)MCP server 工厂参数。
*
* 与 memory 的差异: 通讯录是全局单库(人不属于 workdir),调用上下文仅供 Host
* 核验账号数据访问边界。开关由 host 设置层注入 isEnabled — provider 注册门控 +
* withContacts 工具级双重拦截(Codex host 长生命周期下 server 可能已 spawn,
* 运行期关闭靠工具级拦截兜底, 跟 memory 的 MAKER_MEMORY_NOT_READY 同模式)。
*
* 依赖 @cindy/maker-core 的类型与少量 runtime 实现(ContactsError / import 管道 /
* vCard 序列化, workspace dep 已声明), 依赖方向仍单向 @cindy/mcps → maker-core。
*/
export interface ContactsMcpDeps {
withAccountDataAccess?: import('./account-data-access.js').AccountDataAccess;
getSessionContext?: () => LiziMcpSessionContext;
getManager(): import('@cindy/maker-core').MakerContactsManager;
/** host 设置层的功能开关. 缺省视为常开(测试/独立复用场景) */
isEnabled?: () => boolean;
/**
* 系统通讯录只读拉取(macOS 由 host 注入 JXA 读取器; 其它平台缺省)。
* 缺省时 contacts_import_system 工具不注册(跟 memory 的 session_search 同模式)。
*/
readSystemContacts?: () => Promise<import('@cindy/maker-core').ImportContactRecord[]>;
/**
* 系统通讯录回写(macOS host 注入)。缺省时 contacts_export_system 不注册。
* 语义: 只增/改结构化字段, 系统侧永不删除。
*/
writeSystemContacts?: (
items: import('@cindy/maker-core').SystemContactWriteItem[],
) => Promise<import('@cindy/maker-core').SystemContactWriteResult[]>;
/**
* 系统通讯录回写的单批上限(host 侧 writeSystemContacts 一次能接收的最大条数)。
* 只接受 1..200 的整数, 缺省 200(host 硬限制);非法值/超限回退 200。
* 测试注入小值可省去大量建卡开销, 仍能验证分批边界。
*/
systemWriteBatchSize?: number;
/**
* write/manage 类工具成功后的变更通知(host 注入, 用于广播 renderer 刷新)。
* MCP 直写同进程 store 不经 IPC 层, 没有这个回调 UI 就收不到 agent 侧变更。
*/
onMutated?: () => void;
logger?: LiziMcpLogger;
}
export interface SessionSearchOptions {
/** 限定 sessionId */
sessionId?: string;
/** 限定 role */
role?: 'user' | 'assistant' | 'system';
/** 默认 10 */
limit?: number;
/**
* Host-owned caller identity used to enforce Bot history isolation. This is
* populated by the MCP adapter from the current runtime context and is never
* accepted from model tool arguments.
*/
callerSessionId?: string;
/**
* Host-owned memory namespace. A `bot:` scope without a recoverable caller
* Session must fail closed instead of falling back to cross-session search.
*/
callerMemoryScopeKey?: string;
}
export interface SessionSearchHit {
sessionId: string;
/** 宿主生成的任务深链,包含所属设备,供按需引用原对话。 */
sessionUrl: string;
messageId: string;
role: string;
/** FTS5 snippet() 高亮片段 */
snippet: string;
/** 时间戳 (ms since epoch) */
ts: number;
/** bm25 score, 越小越相关 */
score: number;
}
export type SessionSearchFn = (
query: string,
options?: SessionSearchOptions,
) => Promise<SessionSearchHit[]>;
// 'feishu' 已于 2026-07-16 摘壳(能力迁内置意识 xd-feishu;后端留任给
// scheduler capability broker,见 providers.ts 注释),不再是可注册 MCP id。
// 'lizi_slack_bot' 已于 2026-07-17 随老 SlackIM relay 渠道退役(apiBaseUrl 清理)。
// 'cindy_slack'(与老 lizi_slack_bot 无关)2026-07-19 上线: Slack 网关工具,
// 经 hook 通道由 slack-hook-server 以托管 user token 调 Slack 官方 MCP,
// 接替退役的 cindy-slack 意识。
// 'cindy_docs'(文档工坊)2026-08-19 上线: PDF / Word / Excel / PPT 的生成与
// 检查原语。**零系统依赖**——不走任何需要用户先装 LibreOffice / Office 的路径,
// 对应宿主内置能力开关 id 'docs'(不是需要安装的外置 .cindy 插件)。
export type LiziMcpId =
| 'android'
| 'browser'
| 'computer'
| 'cindy_feishu_bot'
| 'cindy_wechat'
| 'cindy_slack'
| 'cindy_scheduler'
| 'cindy_ssh'
| 'cindy_memory'
| 'cindy_contacts'
| 'cindy_helper'
| 'cindy_orca'
| 'cindy_docs'
| 'cindy_lsp';
// ── Host-callback Result pattern ────────────────────────────────────────────
//
// Several MCP tools delegate to host-side business code via injected callbacks
// (e.g. cindy_helper's sendToSession, cindy_orca's team tools, history
// readers). Those callbacks return a Result variant rather than throw — host
// can use `HOST_NOT_READY` to express "service still bootstrapping" and the
// tool handler maps it to a business errorCode + LLM hint, instead of bubbling
// raw `Error` into INTERNAL.
//
// `E` parameterizes additional error codes specific to a tool (e.g.
// send_to_session adds `NOT_FOUND / ARCHIVED / BUSY / ...`); default `never`
// gives the base shape with only `HOST_NOT_READY | INTERNAL`.
export type ControlOkResult<T extends object = object> = { ok: true } & T;
export type ControlErrResult<E extends string = never> = {
ok: false;
errorCode: E | 'HOST_NOT_READY' | 'INTERNAL';
/** Raw diagnostic / error message to pass through as a hint to the LLM. */
message: string;
};
export type ControlResult<T extends object = object, E extends string = never> =
| ControlOkResult<T>
| ControlErrResult<E>;
/**
* Worker agent literal — kept as a string literal union (not imported from
* `@cindy/maker-core`) to avoid a runtime dependency from @cindy/mcps → maker-core.
* **Keep in sync with `AgentKind` in `packages/maker-core/src/types/common.ts`** —
* adding a new vendor (e.g. 'gemini') without updating this union will cause
* LLM tool calls to fail zod enum validation.
*/
export type ControlWorkerAgent = 'claude-code' | 'codex' | 'pi';
export interface ResolvedBrowserScreenshot {
buffer: Buffer;
mimeType: 'image/png' | 'image/jpeg';
}
/** Host-wide automation targets: managed Chrome, sidebar webview, or the user's own browser via extension. */
export type BrowserBackendKind = 'external' | 'rsb-webview' | 'user-browser';
/** Per-backend capability flags consulted before dispatch; keys mirror the host's status payload. */
export interface BrowserBackendCapabilities {
evaluate?: boolean;
screenshot?: boolean;
network?: boolean;
upload?: boolean;
dialog?: boolean;
console?: boolean;
pdf?: boolean;
focus?: boolean;
close?: boolean;
trustedInput?: boolean;
/** Coordinate clicks, drags and viewport resize (synthetic events are enough). */
pointer?: boolean;
/** Raw protocol commands that recipe adapters drive (needs a debugger attachment). */
rawProtocol?: boolean;
}
/** Browser automation MCP host deps. Core browser execution is injected by host. */
export interface BrowserMcpDeps {
/** Local structural observations only; no URLs, scripts, selectors or input values. */
experienceStore?: import('./browser/experience.js').BrowserExperienceStore;
getRuntime(): BrowserControlRuntime;
/**
* Resolve the actual host profile before validation, discovery and execution.
* undefined keeps the agent's own choice (the user-browser backend picks the
* only connected browser, or asks for one when several are connected).
*/
resolveProfile?(profile?: string): string | undefined;
/** Existing host lifecycle/backend identities; changes invalidate session evidence. */
getBackendScope?(): { lifecycle: object; backend: object };
/**
* Resolve a successful screenshot runtime result into verified image bytes.
* The host owns file-system access so this package never receives a generic
* arbitrary-path reader; inline-only hosts may validate and decode in memory.
*/
resolveScreenshot?(
result: BrowserControlResult,
): Promise<ResolvedBrowserScreenshot>;
/** Shrink the LLM-facing copy to the shared stream-safe byte budget. */
compressInlineImage?: CompressInlineImageFn;
/** Switch the host-wide, persisted automation target; returns the actual mode. */
setBackend?(backend: BrowserBackendKind): Promise<BrowserBackendKind>;
/**
* Capability flags of the active backend (false = the action/kind must be
* refused before dispatch with a clear hint). Absent → everything allowed.
*/
backendCapabilities?(): BrowserBackendCapabilities;
/** Whether the active backend accepts managed resource downloads. */
supportsResourceDownloads?(): boolean;
/** Whether the active backend accepts semantic element queries. */
supportsSemanticQueries?(): boolean;
/** Trusted host-only credential IO; never exposed as a tool or page input. */
recipeSecrets?: { read(key: string): string | null; write(key: string, value: string): boolean };
/** Creates invocation-local file access using the host's existing upload policy. */
recipeFiles?: (sessionId?: string) => Promise<{ read(file: string): Buffer; open(file: string): number }>;
/**
* 代输入: true while the target tab still shows a page where the owner just
* typed a secret. Page-state reads (evaluate, requests, response bodies,
* console) are then refused.
*/
pageReadsRestricted?(target: { profile?: string; targetId?: string }): Promise<boolean>;
logger?: LiziMcpLogger;
/**
* Optional L2 (user-local) recipe layer. The host scans userData, parses with
* the @cindy/mcps `parseRecipes`/`parseSiteGuides` pure fns, and returns the
* resolved maps plus a `version` content fingerprint. @cindy/mcps stays free of
* electron/fs. Absent → only the bundled L1 catalog is used (== current behavior).
*/
getUserRecipes?(): Promise<{
recipes: Map<string, Recipe>;
siteGuides: Map<string, SiteGuide>;
version: string;
}>;
/**
* Optional self-grow write path: persist an agent/user-authored recipe (and
* optional site guide) into the L2 layer. The MCP validates the draft with the
* `RecipeSchema` before calling this; the host just writes JSON to userData.
*/
saveUserRecipe?(input: {
site: string;
recipe: Recipe;
siteGuide?: SiteGuide;
}): Promise<{ ok: boolean; path?: string; message?: string }>;
}
export type ComputerMcpToolName =
| 'status'
| 'check_permissions'
| 'get_accessibility_tree'
| 'launch_app'
| 'list_apps'
| 'list_windows'
| 'get_window_state'
| 'verify_state'
| 'click'
| 'double_click'
| 'right_click'
| 'drag'
| 'type_text'
| 'set_value'
| 'press_key'
| 'hotkey'
| 'scroll'
| 'zoom'
| 'get_screen_size'
| 'get_cursor_position'
| 'move_cursor'
| 'get_agent_cursor_state'
| 'start_recording'
| 'stop_recording'
| 'replay_trajectory'
| 'start_session'
| 'end_session';
export interface ComputerDriverStatus {
installed: boolean;
executablePath: string | null;
version: string | null;
daemonRunning: boolean;
daemonStatus?: string;
doctor?: unknown;
permissions?: unknown;
permissionState?: ComputerDriverPermissionState;
installCommand: string;
docsUrl: string;
error?: string;
}
export type ComputerDriverPermissionPlatform = 'macos' | 'windows' | 'linux' | 'unsupported';
export type ComputerDriverPermissionStatus = 'granted' | 'missing' | 'unknown' | 'not_required';
export type ComputerDriverPermissionGrant = 'granted' | 'missing' | 'unknown' | 'not_required';
export interface ComputerDriverPermissionState {
platform: ComputerDriverPermissionPlatform;
required: boolean;
status: ComputerDriverPermissionStatus;
accessibility?: ComputerDriverPermissionGrant;
screenRecording?: ComputerDriverPermissionGrant;
screenRecordingCapturable?: ComputerDriverPermissionGrant;
source?: string;
reason?: string;
canGrant: boolean;
}
export interface ComputerMcpCallContext {
sessionId?: string;
/** Host-only observation origin; automatic reads must not authorize resumed input. */
observationPurpose?: 'recovery';
/** Request cancellation stays on the host side; never serialized to the driver. */
signal?: AbortSignal;
/** Identifies the agent runtime whose MCP server dispatched this call. */
agentKind?: string;
}
export interface ComputerMcpDeps {
getStatus(): Promise<ComputerDriverStatus>;
callTool(
name: ComputerMcpToolName,
args: Record<string, unknown>,
context?: ComputerMcpCallContext,
): Promise<unknown>;
/**
* 代输入: whether typing would land in a password field — the element at a
* screen point of this app, or its focused element. Roles only, never values.
*/
isSecureTarget?(target: { pid: number; point?: { x: number; y: number } }): Promise<boolean>;
logger?: LiziMcpLogger;
}
export const ANDROID_MCP_ERROR_CODES = [
'ADB_NOT_FOUND',
'NO_DEVICE',
'MULTIPLE_DEVICES',
'DEVICE_UNAUTHORIZED',
'DEVICE_OFFLINE',
'UI_DUMP_FAILED',
'SCREENSHOT_FAILED',
'INVALID_NODE',
'ANDROID_DRIVER_ERROR',
] as const;
export type AndroidMcpErrorCode = (typeof ANDROID_MCP_ERROR_CODES)[number];
export type AndroidMcpToolName =
| 'status'
| 'list_devices'
| 'get_device_state'
| 'tap'
| 'swipe'
| 'input_text'
| 'press_key'
| 'launch_app';
export interface AndroidConnectedDevice {
device_serial: string;
state: string;
product?: string;
model?: string;
device?: string;
transport_id?: string;
usb?: string;
}
export type AndroidAdbPathSource =
| 'custom'
| 'env'
| 'prepared'
| 'bundled'
| 'sdk'
| 'path'
| 'fallback';
export interface AndroidAdbPreparationState {
supported: boolean;
ready: boolean;
platform: string;
path: string | null;
source: AndroidAdbPathSource | null;
error?: string;
}
export interface AndroidUiBounds {
x1: number;
y1: number;
x2: number;
y2: number;
}
export interface AndroidUiNode {
index: number;
text?: string;
content_desc?: string;
class_name?: string;
resource_id?: string;
package?: string;
bounds: AndroidUiBounds;
clickable: boolean;
enabled: boolean;
focusable?: boolean;
long_clickable?: boolean;
scrollable?: boolean;
checked?: boolean;
selected?: boolean;
}
export interface AndroidScreenState {
width: number;
height: number;
density: number | null;
}
export interface AndroidCurrentAppState {
package: string | null;
activity: string | null;
}
export interface AndroidStatusSummary {
adb_available: boolean;
adb_path: string | null;
adb_path_source?: AndroidAdbPathSource | null;
adb_preparation?: AndroidAdbPreparationState;
version: string | null;
devices: AndroidConnectedDevice[];
default_device_serial?: string | null;
configured_default_device_serial?: string | null;
issue?: AndroidMcpErrorCode | null;
error?: string;
}
export interface AndroidDeviceStateResult {
device_serial: string;
screen: AndroidScreenState;
current_app: AndroidCurrentAppState;
screenshot_file_path: string;
screenshot_base64: string;
screenshot_mime_type: 'image/png';
nodes: AndroidUiNode[];
nodes_truncated?: boolean;
raw_ui_dump_file_path?: string;
ui_dump_error?: string;
}
export interface AndroidMcpCallContext {
sessionId?: string;
/** Identifies the agent runtime whose MCP server dispatched this call. */
agentKind?: string;
}
export interface AndroidMcpDeps {
callTool(
name: AndroidMcpToolName,
args: Record<string, unknown>,
context?: AndroidMcpCallContext,
): Promise<unknown>;
logger?: LiziMcpLogger;
}
export type LiziMcpCallerKind = 'root' | 'descendant' | 'unknown';
export interface LiziMcpSessionContext {
agentKind: string;
workingDir: string;
/** Host-owned memory namespace override shared with the agent prompt path. */
memoryScopeKey?: string;
/**
* 当前 tool-call 的权威 session ctx accessor。
*
* Claude in-process 路径返回闭包绑定的当前 session;Codex / Pi bridge
* 路径从请求作用域恢复当前 session。只要提供了本 accessor,它就是唯一可信
* 来源:返回 undefined 表示本次调用无法确认归属,调用方必须 fail closed,
* 不能再回落到构建 server 时捕获的 ctx 或环境中的其它 AsyncLocalStorage store。
*/
getSessionContext?: () => LiziMcpSessionContext | undefined;
/**
* SSH remote 会话的 host id (本地会话缺省)。workingDir 此时是远端机器上的
* 路径字符串 — cindy_memory 等按 workdir 分区的工具必须用
* buildMemoryScopeKey(workingDir, remoteHostId) 定位 store, 不得把远端路径
* 直接当本地键 (会与本地同名路径互串)。
*/
remoteHostId?: string;
vendorOptions?: Record<string, unknown>;
/**
* Business 层 session id (host 在 createSession 时通过 opts.id 注入, maker-core
* 透传给 agent.startSession, agent 再放进 McpProviderContext)。MCP server 工厂
* 闭包绑定本字段, 控制类工具 (如 start_workflow / create_worker) 用它把回调路由到对应
* session 的业务函数。
*
* Codex HTTP MCP bridge 的 server factory 阶段走全局空 ctx;tool-call 阶段
* 会通过 AsyncLocalStorage 恢复当前 thread 对应的 session ctx。未恢复到
* ctx 时,标准范式是工具直接返业务错误码 (如 LEAD_NOT_SUPPORTED) 而不是抛异常。
*/
sessionId?: string;
/**
* 当前内存 Session 实例的唯一代号。business sessionId 在重建后可能复用,
* 权限读取方用本字段阻断旧 MCP 请求借用新实例权限。宿主可将它作为
* opaque route identity 放进 harness 的本地 MCP URL;不得把它暴露成
* 模型或插件可控的工具参数。
*/
sessionInstanceId?: string;
/** Host-owned caller provenance; never sourced from model tool arguments. */
mcpCallerKind?: LiziMcpCallerKind;
/** True only when the harness bridge has installed provenance enforcement. */
mcpCallerAttested?: boolean;
}
export interface CodexHttpMcpConfig {
type: 'http';
url: string;
/** Env var holding the RAW bearer token (no "Bearer " prefix — Codex prepends it). */
bearerTokenEnvVar?: string;
}
export interface LiziMcpProvider {
name: string;
capability?: {
title: string;
description: string;
source: 'builtin' | 'plugin' | 'custom';
discovery?: { tool: string; args?: Record<string, unknown> };
};
isEnabled?(context: LiziMcpSessionContext): boolean;
toClaudeSdkConfig(context: LiziMcpSessionContext): unknown | null;
/** Remote MCP config for Codex app-server; SDK instance providers use the host HTTP bridge instead. */
toCodexMcpConfig?(context: LiziMcpSessionContext): CodexHttpMcpConfig | null;
/** Extra env required by remote MCP configs, e.g. bearer tokens. */
getExtraEnv?(context: LiziMcpSessionContext): Promise<Record<string, string> | null> | Record<string, string> | null;
}