Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* Session.send 视觉桥集成测试。
*
* 验证层 B 钩子在 session.send 的真实调用语义:
* - hook 被调用且 applied → 消息被替换后派发;
* - hook 返回 applied:false + note → 消息原样派发、note 上报(不阻塞);
* - hook 抛错 → 消息原样派发(防御性兜底,零干扰契约)。
*/
import path from 'node:path';
import { describe, expect, it, vi } from 'vitest';
import { Session } from './session.js';
import { AUTO_REVIEW_SOURCE_CONTENT, AUTO_REVIEW_USER_INTENT, MAIN_OWNED_SEND_CONTEXT, type AgentSessionHandle, type SendOptions } from './agents/base-agent.js';
import { appendAutoReviewUserIntent } from './agents/shared/auto-review-decision.js';
import type { UserMessage } from './types/common.js';
import type { VisionBridgeHook } from './types/vision-bridge.js';
/** 与 session.origin.test.ts 同款的 mock logger(Session 构造必需)。debug 是 vi.fn 供断言取消留痕。 */
function createLogger() {
const logger = {
trace() {}, debug: vi.fn(), info() {}, warn() {}, error() {}, fatal() {},
child() { return logger; },
};
return logger;
}
/** 记录 send 收到的消息,便于断言视觉桥替换效果。 */
function makeRecordingHandle() {
const sent: UserMessage[] = [];
let turnRunning = false;
const handle: AgentSessionHandle = {
id: 'thread-1',
agentKind: 'claude-code',
model: 'deepseek-v4',
async send(msg: UserMessage) {
sent.push(msg);
turnRunning = true;
},
async steer() {},
async abort() {},
async close() {
turnRunning = false;
},
async *events() {
// 无事件流:send 后直接结束 turn(避免 await events 卡住)。
await new Promise<void>((resolve) => setTimeout(resolve, 0));
turnRunning = false;
},
getUsageSnapshot: () => ({ tokenUsage: 0, contextTokens: 0, contextWindow: 0, costUsd: 0 }),
setInteractionResolver: () => undefined,
isTurnRunning: () => turnRunning,
} as unknown as AgentSessionHandle;
return { handle, sent };
}
function makeSession(
handle: AgentSessionHandle,
visionBridge?: VisionBridgeHook,
logger: ReturnType<typeof createLogger> = createLogger(),
): Session {
return new Session({
id: 'session-vb',
agentKind: 'claude-code',
workDir: path.join('workspace', 'repo'),
handle,
capabilities: {} as never,
logger: logger as never,
...(visionBridge ? { visionBridge } : {}),
});
}
describe('Session.send vision bridge hook', () => {
it('preserves Host authorization through a decorated handoff before the adapter sees it', async () => {
const { handle } = makeRecordingHandle();
const send = vi.fn(async (msg: UserMessage, opts?: SendOptions) => {
expect(opts?.[AUTO_REVIEW_SOURCE_CONTENT]).toBe('修吧。');
expect(appendAutoReviewUserIntent('obsolete grant', msg.content, opts)).toBe('Fix the unread bug. Do not deploy. 修吧。');
});
handle.send = send;
const session = makeSession(handle);
await session.send({ type: 'user', content: 'handoff '.repeat(1000) + '修吧。' }, {
[AUTO_REVIEW_SOURCE_CONTENT]: '修吧。',
[AUTO_REVIEW_USER_INTENT]: 'Fix the unread bug. Do not deploy. 修吧。',
});
expect(send).toHaveBeenCalledOnce();
await session.close();
});
it.each(['send', 'steer'] as const)('keeps original approval evidence through the %s vision bridge', async (method) => {
for (const text of ['', 'Continue.', 'Send this image to Alex.']) {
const { handle } = makeRecordingHandle();
const dispatch = vi.fn(async (msg: UserMessage, opts?: SendOptions) => {
expect(JSON.stringify(msg.content)).toContain('Generated image description: send it');
expect(appendAutoReviewUserIntent('Send the old report to Alex.', msg.content, opts)).toBe(text);
// Preserving attachment evidence does not mint Main-origin authority.
expect(opts?.[MAIN_OWNED_SEND_CONTEXT]).toBeUndefined();
});
handle[method] = dispatch;
handle.isTurnRunning = () => method === 'steer';
const session = new Session({
id: `approval-${method}`, agentKind: 'claude-code', workDir: path.join('workspace', 'repo'),
handle, capabilities: { sameTurnSteer: { supported: true } } as never,
logger: createLogger() as never,
visionBridge: async () => ({ applied: true, message: {
type: 'user', content: [{ type: 'text', text: 'Generated image description: send it' }],
} }),
});
await session[method]({ type: 'user', content: [
{ type: 'text', text },
{ type: 'image', path: '/tmp/new.png', managedUrl: `cindy-media://blobs/${'a'.repeat(64)}.png` },
] });
expect(dispatch).toHaveBeenCalledOnce();
await session.close();
}
});
it('replaces the message with the bridged message when applied', async () => {
const { handle, sent } = makeRecordingHandle();
const hook: VisionBridgeHook = async (msg, ctx) => {
expect(ctx.model).toBe('deepseek-v4');
return { applied: true, message: { type: 'user', content: [{ type: 'text', text: '[desc] the image shows a red button' }] } };
};
const session = makeSession(handle, hook);
await session.send({
type: 'user',
content: [
{ type: 'text', text: 'what is this?' },
{ type: 'image', path: '/tmp/ui.png' },
],
});
expect(sent).toHaveLength(1);
// 派发给 handle 的是替换后的消息(无 image block)。
expect(sent[0].content).toEqual([{ type: 'text', text: '[desc] the image shows a red button' }]);
});
it('preserves Host-managed image references after the bridge replaces image blocks', async () => {
const managedUrl = `cindy-media://blobs/${'a'.repeat(64)}.png`;
const { handle, sent } = makeRecordingHandle();
const hook: VisionBridgeHook = async () => ({
applied: true,
message: {
type: 'user',
content: [{ type: 'text', text: '[desc] the image shows a red button' }],
},
});
const session = makeSession(handle, hook);
await session.send({
type: 'user',
content: [{ type: 'image', path: '/tmp/ui.png', managedUrl }],
});
expect(sent).toHaveLength(1);
expect(sent[0].content).toEqual([
{ type: 'text', text: '[desc] the image shows a red button' },
{
type: 'text',
text: expect.stringContaining(JSON.stringify({ image: 1, uri: managedUrl })),
},
]);
});
it('passes through unchanged when applied=false with note (note not blocking)', async () => {
const { handle, sent } = makeRecordingHandle();
const hook: VisionBridgeHook = async (msg) => ({ applied: false, message: msg, note: 'vision backend down' });
const session = makeSession(handle, hook);
const msg: UserMessage = { type: 'user', content: [{ type: 'image', path: '/tmp/a.png' }] };
await session.send(msg);
expect(sent).toHaveLength(1);
// applied=false → 原样派发(image block 保留),note 不影响 send 流程。
expect(sent[0]).toBe(msg);
});
it('does not block send when the hook throws (defensive passthrough)', async () => {
const { handle, sent } = makeRecordingHandle();
const hook: VisionBridgeHook = async () => {
throw new Error('boom');
};
const session = makeSession(handle, hook);
const msg: UserMessage = { type: 'user', content: [{ type: 'text', text: 'hi' }] };
await session.send(msg);
expect(sent).toHaveLength(1);
expect(sent[0]).toBe(msg);
});
it('rejects a concurrent send while vision hook is in-flight (sendReservation guard)', async () => {
// send1 的视觉 hook 挂起(永不 resolve)→ 视觉阶段 isTurnRunning 仍 false,
// 但 sendReservation 已建立。send2 并发必须被 SESSION_RUNNING 拒绝,
// 不能覆盖 sendReservation 让 send1 白调视觉。
let releaseVision!: () => void;
const visionGate = new Promise<void>((resolve) => {
releaseVision = resolve;
});
const { handle } = makeRecordingHandle();
const hook: VisionBridgeHook = async () => {
await visionGate;
return { applied: false, message: { type: 'user', content: [{ type: 'text', text: 'late' }] } };
};
const session = makeSession(handle, hook);
const send1 = session.send({
type: 'user',
content: [{ type: 'image', path: '/tmp/a.png' }],
});
// 等 send1 进入视觉 hook(await visionGate)。
await new Promise<void>((resolve) => setTimeout(resolve, 10));
// send2 并发:应被 sendReservation guard 拒绝(SESSION_RUNNING)。
await expect(
session.send({ type: 'user', content: [{ type: 'text', text: 'second' }] }),
).rejects.toThrow(/running/i);
// 释放 send1 的视觉 hook,让它完成(applied=false → 原样透传,handle.send 收到原消息)。
releaseVision();
const r1 = await send1;
expect(r1.accepted).toBe(true);
});
it('returns cancelled-before-dispatch when external signal aborts during vision hook', async () => {
// send 带外部 signal;视觉 hook 挂起时 abort signal → hook 感知 ctx.signal.aborted,
// 返回后 session 复查取消,send 返回 cancelled-before-dispatch(不 dispatch handle)。
const controller = new AbortController();
let released = false;
const hook: VisionBridgeHook = async (_msg, ctx) => {
// 等 abort(signal 触发)或 200ms 兜底。
await new Promise<void>((resolve) => {
ctx.signal?.addEventListener('abort', () => {
released = true;
resolve();
});
setTimeout(resolve, 200);
});
return { applied: false, message: { type: 'user', content: [{ type: 'text', text: 'x' }] } };
};
const { handle, sent } = makeRecordingHandle();
const session = makeSession(handle, hook);
const p = session.send({ type: 'user', content: [{ type: 'image', path: '/tmp/a.png' }] }, { signal: controller.signal });
await new Promise<void>((resolve) => setTimeout(resolve, 10));
controller.abort();
const r = await p;
expect(released).toBe(true);
// toEqual 收窄联合类型:accepted=false + reason 为 cancelled-before-dispatch。
expect(r).toEqual({ accepted: false, reason: 'cancelled-before-dispatch' });
// handle 未被 dispatch(视觉阶段就取消了)。
expect(sent).toHaveLength(0);
});
it('aborts in-flight vision hook reservation when session detaches', async () => {
// 视觉 hook 挂起(await ctx.signal.abort);send 进入视觉阶段后 session.detach()
// 应立即 abort reservation signal → hook 感知取消,handle.send 不被 dispatch。
let abortedByDetach = false;
let releaseHook: (() => void) | undefined;
const hook: VisionBridgeHook = async (_msg, ctx) => {
await new Promise<void>((resolve) => {
ctx.signal?.addEventListener('abort', () => {
abortedByDetach = true;
resolve();
});
releaseHook = resolve;
});
return { applied: false, message: { type: 'user', content: [{ type: 'text', text: 'late' }] } };
};
const { handle, sent } = makeRecordingHandle();
const session = makeSession(handle, hook);
const p = session.send({ type: 'user', content: [{ type: 'image', path: '/tmp/a.png' }] });
// 等 send 进入视觉 hook(reservation 已建立)。
await new Promise<void>((resolve) => setTimeout(resolve, 10));
// detach 应立即 abort 视觉 fetch(不再等 handle.detach/超时)。
await session.detach();
expect(abortedByDetach).toBe(true);
// send 因 reservation abort → cancelled-before-dispatch,handle.send 未 dispatch。
const r = await p;
expect(r).toEqual({ accepted: false, reason: 'cancelled-before-dispatch' });
expect(sent).toHaveLength(0);
// 兜底 release(若 hook 未被 abort,避免悬挂)。
releaseHook?.();
});
it('logs debug when vision bridge cancellation is caught before dispatch', async () => {
const logger = createLogger();
const controller = new AbortController();
const hook: VisionBridgeHook = async (_msg, ctx) => {
await new Promise<void>((resolve) => {
ctx.signal?.addEventListener('abort', () => resolve());
setTimeout(resolve, 200);
});
return { applied: false, message: { type: 'user', content: [{ type: 'text', text: 'x' }] } };
};
const { handle, sent } = makeRecordingHandle();
const session = makeSession(handle, hook, logger);
const p = session.send({ type: 'user', content: [{ type: 'image', path: '/tmp/a.png' }] }, { signal: controller.signal });
await new Promise<void>((resolve) => setTimeout(resolve, 10));
controller.abort();
const r = await p;
expect(r).toEqual({ accepted: false, reason: 'cancelled-before-dispatch' });
expect(sent).toHaveLength(0);
// 取消留痕:session debug 记录 vision bridge cancelled before dispatch + reason。
expect(logger.debug).toHaveBeenCalledWith(
'vision bridge cancelled before dispatch',
expect.objectContaining({ reason: 'cancelled-before-dispatch' }),
);
});
});
describe('Session.steer vision bridge hook', () => {
function guardedSteerSession(visionBridge?: VisionBridgeHook) {
const { handle } = makeRecordingHandle();
handle.isTurnRunning = () => true;
const steer = vi.fn(async (_message: UserMessage, _options?: SendOptions) => {});
handle.steer = steer;
const session = new Session({
id: 'guarded-steer', agentKind: 'claude-code', workDir: path.join('workspace', 'repo'),
handle, capabilities: { sameTurnSteer: { supported: true } } as never,
logger: createLogger() as never, visionBridge,
});
return { session, handle, steer };
}
it('runs the Host grant at final steer dispatch without forwarding it to the provider', async () => {
const { session, steer } = guardedSteerSession();
const grant = vi.fn(async () => {});
await session.steer('App-authored text', { beforeProviderStart: grant, messageUuid: 'app-input' });
expect(grant).toHaveBeenCalledOnce();
expect(steer).toHaveBeenCalledWith(
{ type: 'user', content: 'App-authored text' }, expect.objectContaining({ messageUuid: 'app-input' }),
);
expect(steer.mock.calls[0][1]).not.toHaveProperty('beforeProviderStart');
await session.close();
});
it('rejects a Host grant revoked during asynchronous steer preparation', async () => {
let visible = true;
const bridge: VisionBridgeHook = async message => {
await Promise.resolve();
visible = false;
return { applied: false, message };
};
const { session, steer } = guardedSteerSession(bridge);
const grant = vi.fn(async () => { if (!visible) throw new Error('MCP_APP_CARD_UNAVAILABLE'); });
await expect(session.steer({
type: 'user', content: [{ type: 'image', path: path.join('fixture', 'app.png') }],
}, { beforeProviderStart: grant })).rejects.toThrow('MCP_APP_CARD_UNAVAILABLE');
expect(grant).toHaveBeenCalledOnce();
expect(steer).not.toHaveBeenCalled();
await session.close();
});
it.each(['ended', 'replaced', 'closed'] as const)('rechecks a turn %s while awaiting the Host steer grant', async (change) => {
const { session, handle, steer } = guardedSteerSession();
const generation = vi.spyOn(session, 'getTurnGeneration').mockReturnValue(1);
await expect(session.steer('App-authored text', {
beforeProviderStart: async () => {
await Promise.resolve();
if (change === 'ended') handle.isTurnRunning = () => false;
else if (change === 'replaced') generation.mockReturnValue(2);
else await session.close();
},
})).rejects.toThrow(change === 'closed' ? 'closed' : 'has no active turn to steer');
expect(steer).not.toHaveBeenCalled();
generation.mockRestore();
await session.close();
});
it('replaces the image message with the bridged text before steering', async () => {
const steered: UserMessage[] = [];
const handle = {
id: 'thread-1',
agentKind: 'claude-code',
model: 'deepseek-v4',
async send() {},
async steer(msg: UserMessage) {
steered.push(msg);
},
async abort() {},
async close() {},
async *events() {},
getUsageSnapshot: () => ({ tokenUsage: 0, contextTokens: 0, contextWindow: 0, costUsd: 0 }),
setInteractionResolver: () => undefined,
isTurnRunning: () => true,
} as unknown as AgentSessionHandle;
const hook: VisionBridgeHook = async (msg) => ({
applied: true,
message: { type: 'user', content: [{ type: 'text', text: '[desc] the image shows a chat list' }] },
});
// steer 需要 sameTurnSteer capability;这里构造带该 capability 的 session。
const session = new Session({
id: 'session-vb-steer',
agentKind: 'claude-code',
workDir: path.join('workspace', 'repo'),
handle,
capabilities: { sameTurnSteer: { supported: true } } as never,
logger: createLogger() as never,
visionBridge: hook,
});
await session.steer({
type: 'user',
content: [
{ type: 'text', text: 'steer this' },
{ type: 'image', path: '/tmp/a.png' },
],
});
// 视觉桥把 image block 替换为描述文本后交给 handle.steer。
expect(steered).toHaveLength(1);
expect(steered[0].content).toEqual([{ type: 'text', text: '[desc] the image shows a chat list' }]);
});
it('preserves Host-managed image references when steering through the vision bridge', async () => {
const managedUrl = 'xdt-image://vision-steer/screenshot.png';
const steered: UserMessage[] = [];
const handle = {
id: 'thread-1',
agentKind: 'claude-code',
model: 'deepseek-v4',
async send() {},
async steer(msg: UserMessage) {
steered.push(msg);
},
async abort() {},
async close() {},
async *events() {},
getUsageSnapshot: () => ({ tokenUsage: 0, contextTokens: 0, contextWindow: 0, costUsd: 0 }),
setInteractionResolver: () => undefined,
isTurnRunning: () => true,
} as unknown as AgentSessionHandle;
const hook: VisionBridgeHook = async () => ({
applied: true,
message: {
type: 'user',
content: [{ type: 'text', text: '[desc] bridged screenshot' }],
},
});
const session = new Session({
id: 'session-vb-steer-reference',
agentKind: 'claude-code',
workDir: path.join('workspace', 'repo'),
handle,
capabilities: { sameTurnSteer: { supported: true } } as never,
logger: createLogger() as never,
visionBridge: hook,
});
await session.steer({
type: 'user',
content: [{ type: 'image', path: '/tmp/a.png', managedUrl }],
});
expect(steered).toHaveLength(1);
expect(steered[0].content).toEqual([
{ type: 'text', text: '[desc] bridged screenshot' },
{
type: 'text',
text: expect.stringContaining(JSON.stringify({ image: 1, uri: managedUrl })),
},
]);
});
it('does not steer when the turn ends during async vision conversion', async () => {
// turn 在视觉转换期间结束:steer 必须先复查生命周期再调 handle.steer,
// 否则底层以「No active turn to steer」拒绝或 Pi 把迟到消息交给已结束的 turn。
const steered: UserMessage[] = [];
const handle = {
id: 'thread-1',
agentKind: 'claude-code',
model: 'deepseek-v4',
async send() {},
async steer(msg: UserMessage) {
steered.push(msg);
},
async abort() {},
async close() {},
async *events() {},
getUsageSnapshot: () => ({ tokenUsage: 0, contextTokens: 0, contextWindow: 0, costUsd: 0 }),
setInteractionResolver: () => undefined,
// 第一次检查为 true(视觉转换前),转换完成后变为 false(turn 已结束)。
isTurnRunning: vi
.fn()
.mockReturnValueOnce(true)
.mockReturnValue(false),
} as unknown as AgentSessionHandle;
const hook: VisionBridgeHook = async (msg) => {
// 模拟视觉转换耗时:期间 turn 结束。
await new Promise((r) => setTimeout(r, 5));
return {
applied: true,
message: { type: 'user', content: [{ type: 'text', text: '[desc] slow bridge' }] },
};
};
const session = new Session({
id: 'session-vb-steer-stale',
agentKind: 'claude-code',
workDir: path.join('workspace', 'repo'),
handle,
capabilities: { sameTurnSteer: { supported: true } } as never,
logger: createLogger() as never,
visionBridge: hook,
});
await expect(
session.steer({
type: 'user',
content: [
{ type: 'text', text: 'steer this' },
{ type: 'image', path: '/tmp/a.png' },
],
}),
).rejects.toThrow('has no active turn to steer');
// 底层 handle.steer 绝不能被调用(迟到消息不交给已结束的 turn)。
expect(steered).toHaveLength(0);
});
it('does not steer when a new turn started during async vision conversion', async () => {
// 原 turn 在视觉转换期间结束、同 Session 随后启动新 turn:isTurnRunning 会因
// 新 turn 而通过(恒 true),但 generation 已变化——迟到 steer 若投出会串到
// 错误的新 turn。必须校验 generation 仍一致才投递(Greptile P1)。
const steered: UserMessage[] = [];
const handle = {
id: 'thread-1',
agentKind: 'claude-code',
model: 'deepseek-v4',
async send() {},
async steer(msg: UserMessage) {
steered.push(msg);
},
async abort() {},
async close() {},
async *events() {},
getUsageSnapshot: () => ({ tokenUsage: 0, contextTokens: 0, contextWindow: 0, costUsd: 0 }),
setInteractionResolver: () => undefined,
// 新 turn 在跑:isTurnRunning 始终 true。
isTurnRunning: () => true,
} as unknown as AgentSessionHandle;
const hook: VisionBridgeHook = async (msg) => {
// 模拟视觉转换耗时:期间新 turn 已启动。
await new Promise((r) => setTimeout(r, 5));
return {
applied: true,
message: { type: 'user', content: [{ type: 'text', text: '[desc] slow bridge' }] },
};
};
const session = new Session({
id: 'session-vb-steer-new-turn',
agentKind: 'claude-code',
workDir: path.join('workspace', 'repo'),
handle,
capabilities: { sameTurnSteer: { supported: true } } as never,
logger: createLogger() as never,
visionBridge: hook,
});
// 发起时 generation = 1,转换后 = 2(模拟新 turn 递增)→ 拒绝投递。
const genSpy = vi
.spyOn(session, 'getTurnGeneration')
.mockReturnValueOnce(1)
.mockReturnValue(2);
await expect(
session.steer({
type: 'user',
content: [
{ type: 'text', text: 'steer this' },
{ type: 'image', path: '/tmp/a.png' },
],
}),
).rejects.toThrow('has no active turn to steer');
expect(steered).toHaveLength(0);
genSpy.mockRestore();
});
});