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。

feat(orca): 协同与任务间消息由发送方选择插话,排队后可转插话或调整顺序 (#5515)

Dash377eaa69e919
diff --git a/apps/desktop/src/main/localDb/ipc/__tests__/botCanonicalSession.test.ts b/apps/desktop/src/main/localDb/ipc/__tests__/botCanonicalSession.test.ts
index 07ce361a8f..4e56dc21f3 100644
--- a/apps/desktop/src/main/localDb/ipc/__tests__/botCanonicalSession.test.ts
+++ b/apps/desktop/src/main/localDb/ipc/__tests__/botCanonicalSession.test.ts
@@ -6024,6 +6024,8 @@ describe('Bot Session task end-to-end runtime', () => {
queue[index] = next; return true;
},
removeQueuedMessage: (_id, clientId) => { queue = queue.filter(item => item.clientId !== clientId); return true; },
+ steerQueuedMessage: async () => ({ kind: 'gone' }),
+ moveQueuedMessage: () => null,
});
const runtime = createDelegationRuntime({ taskControl: true, taskQueue: {
inspect: async (_id, caller) => queue.filter(item => authorizeSessionQueueItem(item, caller).ok)
diff --git a/apps/desktop/src/main/maker-ipc/__tests__/agent-input-coordinator.test.ts b/apps/desktop/src/main/maker-ipc/__tests__/agent-input-coordinator.test.ts
index 73d87d4bce..f4ace75658 100644
--- a/apps/desktop/src/main/maker-ipc/__tests__/agent-input-coordinator.test.ts
+++ b/apps/desktop/src/main/maker-ipc/__tests__/agent-input-coordinator.test.ts
@@ -549,6 +549,8 @@ describe('AgentInputCoordinator Orca priority queue transactions', () => {
ensureWorkerQueueRestored: async () => true,
removeQueuedMessage: () => false,
replaceQueuedMessage: () => false,
+ steerStoredQueuedMessage: async () => ({ kind: 'gone' as const }),
+ moveQueuedMessage: () => null,
mergeQueuedMessages: () => false,
log: mocks.logger,
} satisfies OrcaTeamServiceDeps;
@@ -902,6 +904,9 @@ function createHarness(opts?: {
const onAcceptedQueuedMessage = vi.fn<
NonNullable<AgentInputCoordinatorDeps['onAcceptedQueuedMessage']>
>(() => {});
+ const onSteerAccepted = vi.fn<NonNullable<AgentInputCoordinatorDeps['onSteerAccepted']>>(
+ () => {},
+ );
const onDispatchedUserTurn = vi.fn<
NonNullable<AgentInputCoordinatorDeps['onDispatchedUserTurn']>
>(() => {});
@@ -1030,6 +1035,7 @@ function createHarness(opts?: {
onUserMessageQueryable,
onUserMessagePersistenceFailed,
onAcceptedQueuedMessage,
+ onSteerAccepted,
onDispatchedUserTurn,
onResumableTurnError,
isResumableTurnErrorCandidate,
@@ -1071,6 +1077,7 @@ function createHarness(opts?: {
onUserMessageQueryable,
onUserMessagePersistenceFailed,
onAcceptedQueuedMessage,
+ onSteerAccepted,
onDispatchedUserTurn,
onResumableTurnError,
isResumableTurnErrorCandidate,
@@ -1177,6 +1184,132 @@ function createHarness(opts?: {
};
}
+describe('agent-chosen control steering', () => {
+ const sid = 'lead-report';
+ function expected(h: ReturnType<typeof createHarness>) {
+ return { session: h.getTurnSessionIdentity(), turnGeneration: 0 };
+ }
+ it('joins a running turn even though ordinary new turns must queue', async () => {
+ const h = createHarness();
+ h.setRunning(true);
+ expect(h.coordinator.shouldQueueNewTurn(sid)).toBe(true);
+ const item = makeItem('report', 'worker result');
+ expect(await h.coordinator.steerControlInput(sid, { item }, expected(h))).toBe('steered');
+ expect(h.steerToAgent).toHaveBeenCalledOnce();
+ expect(h.sendToAgent).not.toHaveBeenCalled();
+ expect(h.coordinator.hasPendingQueueItem(sid, 'report')).toBe(false);
+ expect(h.onSteerAccepted).toHaveBeenCalledWith(sid, expect.objectContaining({ clientId: 'report' }));
+ });
+ it('may pass earlier queued rows because the sender chose to steer', async () => {
+ const h = createHarness();
+ h.setRunning(true);
+ await h.coordinator.ensureQueueRestored(sid);
+ h.coordinator.enqueue(sid, makeItem('human', 'user instruction'));
+ expect(await h.coordinator.steerControlInput(sid, { item: makeItem('report', 'r') }, expected(h)))
+ .toBe('steered');
+ expect(h.coordinator.getQueueControlSnapshot(sid).pendingQueue.map((item) => item.clientId))
+ .toEqual(['human']);
+ });
+ it.each(['pause', 'stop-pause', 'interaction', 'credential', 'generation', 'identity', 'idle', 'restore'])
+ ('does not bypass the %s boundary', async boundary => {
+ const h = createHarness();
+ h.setRunning(true);
+ const turn = expected(h);
+ await h.coordinator.ensureQueueRestored(sid);
+ if (boundary === 'pause') h.coordinator.setExecutionPaused(sid, true);
+ if (boundary === 'stop-pause') {
+ h.coordinator.enqueue(sid, makeItem('human', 'user instruction'));
+ h.coordinator.pausePendingQueueForRewind(sid);
+ }
+ if (boundary === 'interaction') h.setPendingInteraction(true);
+ if (boundary === 'credential') h.setHasPendingCredentialSwitch(() => true);
+ if (boundary === 'generation') h.setTurnGeneration(1);
+ if (boundary === 'identity') h.setTurnSessionIdentity({ instanceId: 'replacement' });
+ if (boundary === 'idle') h.setRunning(false);
+ if (boundary === 'restore') {
+ // A different session has not successfully restored its authoritative queue.
+ h.setLoadQueueSnapshot(async () => { throw new Error('queue unavailable'); });
+ }
+ expect(await h.coordinator.steerControlInput(boundary === 'restore' ? 'unrestored' : sid,
+ { item: makeItem('report', 'result') }, turn)).toBe('not-attempted');
+ expect(h.steerToAgent).not.toHaveBeenCalled();
+ });
+ it('re-checks the boundary after async screening, before provider dispatch', async () => {
+ const h = createHarness();
+ h.setRunning(true);
+ h.setScreenUserMessage(async () => {
+ h.setPendingInteraction(true);
+ return { action: 'allow' };
+ });
+ // Not delivered and nothing retained: safe for ordinary delivery, unlike a screening block.
+ expect(await h.coordinator.steerControlInput(sid, { item: makeItem('report', 'r') }, expected(h)))
+ .toBe('not-attempted');
+ expect(h.steerToAgent).not.toHaveBeenCalled();
+ expect(h.onSteerAccepted).not.toHaveBeenCalled();
+ });
+ it('retains one paused report after an uncertain ACK, including when the turn ends', async () => {
+ const h = createHarness();
+ h.setAgentKind('codex');
+ h.setRunning(true);
+ h.steerToAgent.mockImplementationOnce(async () => {
+ h.setRunning(false);
+ throw new Error('Codex turn/steer did not acknowledge within 10000ms');
+ });
+ expect(await h.coordinator.steerControlInput(sid, { item: makeItem('report', 'result') }, expected(h)))
+ .toBe('queued');
+ const queue = h.coordinator.getQueueControlSnapshot(sid).pendingQueue;
+ expect(queue.map(item => item.clientId)).toEqual(['report']);
+ expect(h.coordinator.isQueuePaused(sid)).toBe(true);
+ h.coordinator.onTurnEvent(sid, 'done');
+ await flush();
+ expect(h.sendToAgent).not.toHaveBeenCalled();
+ });
+ it('reports screened rejection without reviving blocked content as ordinary input', async () => {
+ const h = createHarness();
+ h.setRunning(true);
+ h.setScreenUserMessage(async () => ({ action: 'block', ghostId: 'guard', ghostName: 'guard', reason: 'blocked' }));
+ expect(await h.coordinator.steerControlInput(sid, { item: makeItem('report', 'result') }, expected(h)))
+ .toBe('rejected');
+ expect(h.steerToAgent).not.toHaveBeenCalled();
+ expect(h.coordinator.hasPendingQueueItem(sid, 'report')).toBe(false);
+ });
+ it('promotes a stored queued row without releasing the rest of the queue', async () => {
+ const h = createHarness();
+ h.setRunning(true);
+ await h.coordinator.ensureQueueRestored(sid);
+ h.coordinator.enqueue(sid, makeItem('human', 'user instruction'));
+ h.coordinator.enqueue(sid, makeItem('report', 'worker result'));
+ expect(await h.coordinator.steerControlInput(sid, { queuedClientId: 'report' }, expected(h)))
+ .toBe('steered');
+ expect(h.steerToAgent).toHaveBeenCalledOnce();
+ expect(h.coordinator.getQueueControlSnapshot(sid).pendingQueue.map((item) => item.clientId))
+ .toEqual(['human']);
+ expect(h.onSteerAccepted).toHaveBeenCalledWith(sid, expect.objectContaining({ clientId: 'report' }));
+ });
+ it('leaves an edit-locked or missing stored row alone', async () => {
+ const h = createHarness();
+ h.setRunning(true);
+ await h.coordinator.ensureQueueRestored(sid);
+ h.coordinator.enqueue(sid, makeItem('report', 'worker result'));
+ h.coordinator.setEditLock(sid, 'report', true);
+ expect(await h.coordinator.steerControlInput(sid, { queuedClientId: 'report' }, expected(h)))
+ .toBe('not-attempted');
+ expect(await h.coordinator.steerControlInput(sid, { queuedClientId: 'missing' }, expected(h)))
+ .toBe('rejected');
+ expect(h.steerToAgent).not.toHaveBeenCalled();
+ expect(h.coordinator.hasPendingQueueItem(sid, 'report')).toBe(true);
+ });
+ it('notifies the host when an ordinary UI steer is accepted', async () => {
+ const h = createHarness();
+ h.setRunning(true);
+ await h.coordinator.ensureQueueRestored(sid);
+ h.coordinator.enqueue(sid, makeItem('queued', 'q'));
+ const [queued] = h.coordinator.getQueueControlSnapshot(sid).pendingQueue;
+ expect(await h.coordinator.steer(sid, queued!, { removeFromQueue: true })).toBe(true);
+ expect(h.onSteerAccepted).toHaveBeenCalledOnce();
+ });
+});
+
function latestSnapshotClientIds(
persistQueueSnapshot: ReturnType<typeof createHarness>['persistQueueSnapshot'],
): string[] {
@@ -6859,6 +6992,7 @@ describe('AgentInputCoordinator steer transaction', () => {
fallbackToTurn: false, expectedTurnSession: expected.session, expectedTurnGeneration: expected.turnGeneration,
}),
getQueueSnapshot: vi.fn(), replaceQueuedMessage: vi.fn(), removeQueuedMessage: vi.fn(),
+ steerStoredQueuedMessage: vi.fn(), moveQueuedMessage: vi.fn(),
createId: () => `unexpected-random-ID-${++allocatedIds}`,
});
const input = { callerSessionId: 'caller', targetSessionId: sid, message: 'urgent', queuedMessageId: 'stable-ID' };
@@ -6932,6 +7066,7 @@ describe('AgentInputCoordinator steer transaction', () => {
fallbackToTurn: false, expectedTurnSession: expected.session, expectedTurnGeneration: expected.turnGeneration,
}),
getQueueSnapshot: vi.fn(), replaceQueuedMessage: vi.fn(), removeQueuedMessage: vi.fn(),
+ steerStoredQueuedMessage: vi.fn(), moveQueuedMessage: vi.fn(),
createId: () => `unexpected-random-ID-${++allocatedIds}`,
});
const input = { callerSessionId: 'caller', targetSessionId: sid, message: 'urgent', queuedMessageId: 'stable-ID' };
diff --git a/apps/desktop/src/main/maker-ipc/__tests__/orcaInterAgentDispatcher.test.ts b/apps/desktop/src/main/maker-ipc/__tests__/orcaInterAgentDispatcher.test.ts
index a5cea699bc..2d11195a87 100644
--- a/apps/desktop/src/main/maker-ipc/__tests__/orcaInterAgentDispatcher.test.ts
+++ b/apps/desktop/src/main/maker-ipc/__tests__/orcaInterAgentDispatcher.test.ts
@@ -118,6 +118,142 @@ beforeEach(() => {
vi.clearAllMocks();
});
+describe('sender-chosen steering into an active turn', () => {
+ const report = {
+ targetSessionId: 'target-session', rawContent: 'Completed work', source: 'worker' as const,
+ senderLabel: 'Worker', workerId: 'worker-1', meta: { source: 'orca', context: 'report-test' },
+ };
+ const steerReport = { ...report, delivery: 'steer' as const };
+ function setup(outcome: 'steered' | 'queued' | 'not-attempted' | 'rejected' = 'steered') {
+ const live = { ...createLiveSession(async () => ({ accepted: true })),
+ isTurnRunning: vi.fn(() => true), getTurnGeneration: vi.fn(() => 7),
+ capabilities: { sameTurnSteer: { supported: true } }, remoteHostId: null as string | null };
+ const steer = vi.fn<NonNullable<OrcaInterAgentDispatcherDeps<TestSessionMeta>['steerControlInput']>>(async () => outcome);
+ const lock = vi.fn(async (_id: string, task: () => Promise<unknown>) => task());
+ const h = createHarness({ getLiveSession: () => live, steerControlInput: steer,
+ withSendToSessionLock: lock as OrcaInterAgentDispatcherDeps<TestSessionMeta>['withSendToSessionLock'],
+ shouldQueueNewTurn: () => true,
+ resolveWorkerSenderLabel: async () => 'reviewer',
+ resolveWorkerSessionLink: async () => ({ leadSessionId: 'target-session', workerSessionId: 'worker-session' }),
+ });
+ return { ...h, live, steer, lock };
+ }
+ it('uses same-turn delivery with Orca identity and never runs turn-start callbacks', async () => {
+ const h = setup();
+ const order: string[] = [];
+ const result = await h.dispatcher.dispatchOrEnqueueOrcaInterAgentMessage({ ...steerReport,
+ onAccepted: () => { order.push('accepted'); }, onAcceptedCommit: () => { order.push('commit'); },
+ });
+ expect(result).toMatchObject({ ok: true, mode: 'steered', clientId: 'client-1' });
+ expect(result).not.toHaveProperty('steerFallbackReason');
+ expect(h.steer).toHaveBeenCalledWith('target-session', expect.objectContaining({
+ clientId: 'client-1', text: '[From Orca Worker reviewer (worker_id: worker-1)]\nCompleted work',
+ persistedContent: '{"orcaSource":"worker","content":"Completed work"}',
+ autoReviewUserText: { kind: 'delegated-continuation' },
+ origin: { kind: 'orca', senderLabel: 'reviewer', senderSessionId: 'worker-session', displayText: 'Completed work' },
+ }), { session: h.live, turnGeneration: 7 });
+ // The message joined the running turn; accepted/commit would claim a new turn's identity.
+ expect(order).toEqual([]);
+ const item = h.steer.mock.calls[0]?.[1];
+ if (!item) throw new Error('expected steered item');
+ expect(h.dispatcher.runQueuedOrcaInterAgentAcceptedCallback('target-session', item)).toBeUndefined();
+ expect(h.lock).toHaveBeenCalledOnce();
+ expect(h.deps.enqueueQueuedMessage).not.toHaveBeenCalled();
+ expect(h.live.send).not.toHaveBeenCalled();
+ expect(h.deps.createDbMessage).not.toHaveBeenCalled();
+ expect(h.deps.beginDirectTurnChangeSet).not.toHaveBeenCalled();
+ });
+ it.each(['worker', 'lead'] as const)('keeps %s messages queued unless the sender asks to steer', async (source) => {
+ const h = setup();
+ expect(await h.dispatcher.dispatchOrEnqueueOrcaInterAgentMessage({ ...report, source }))
+ .toMatchObject({ ok: true, mode: 'queued' });
+ const [, queued] = vi.mocked(h.deps.enqueueQueuedMessage).mock.calls[0] ?? [];
+ expect(queued).toBeDefined();
+ expect(h.steer).not.toHaveBeenCalled();
+ expect(await h.dispatcher.dispatchOrEnqueueOrcaInterAgentMessage({ ...report, source }))
+ .not.toHaveProperty('steerFallbackReason');
+ });
+ it('steers Lead messages into a worker turn when chosen', async () => {
+ const h = setup();
+ expect(await h.dispatcher.dispatchOrEnqueueOrcaInterAgentMessage({
+ ...steerReport, source: 'lead', senderLabel: 'Lead',
+ })).toMatchObject({ ok: true, mode: 'steered' });
+ expect(h.steer).toHaveBeenCalledOnce();
+ });
+ it('dispatches directly to an idle target without a fallback reason', async () => {
+ const h = setup();
+ h.live.isTurnRunning.mockReturnValue(false);
+ h.deps.shouldQueueNewTurn = () => false;
+ const result = await h.dispatcher.dispatchOrEnqueueOrcaInterAgentMessage(steerReport);
+ expect(result).toMatchObject({ ok: true, mode: 'dispatched' });
+ expect(result).not.toHaveProperty('steerFallbackReason');
+ expect(h.steer).not.toHaveBeenCalled();
+ });
+ it('acknowledges retained queue ownership without enqueueing a duplicate', async () => {
+ const h = setup('queued');
+ const accepted = vi.fn();
+ const commit = vi.fn();
+ const result = await h.dispatcher.dispatchOrEnqueueOrcaInterAgentMessage({ ...steerReport, onAccepted: accepted, onAcceptedCommit: commit });
+ expect(result).toMatchObject({ ok: true, mode: 'queued', clientId: 'client-1', steerFallbackReason: 'STEER_UNCERTAIN' });
+ expect(accepted).not.toHaveBeenCalled();
+ expect(h.deps.enqueueQueuedMessage).not.toHaveBeenCalled();
+ const item = h.steer.mock.calls[0]?.[1];
+ if (!item) throw new Error('expected retained report');
+ await h.dispatcher.runQueuedOrcaInterAgentAcceptedCallback('target-session', item);
+ await h.dispatcher.settleQueuedOrcaInterAgentAcceptedCallback('target-session',
+ { persistUserMessage: { clientId: 'client-1', content: item.persistedContent, delivery: 'turn' } },
+ { kind: 'session-dispatch', dispatched: true, source: 'test' });
+ expect(accepted).toHaveBeenCalledOnce();
+ expect(commit).toHaveBeenCalledOnce();
+ });
+ it('fails a screening rejection instead of retrying it through the queue', async () => {
+ const h = setup('rejected');
+ const accepted = vi.fn();
+ expect(await h.dispatcher.dispatchOrEnqueueOrcaInterAgentMessage({ ...steerReport, onAccepted: accepted }))
+ .toMatchObject({ ok: false, dispatchOutcome: { code: 'SEND_FAILED' } });
+ expect(h.deps.enqueueQueuedMessage).not.toHaveBeenCalled();
+ expect(h.live.send).not.toHaveBeenCalled();
+ expect(accepted).not.toHaveBeenCalled();
+ });
+ it('falls back to the ordinary path after an undelivered attempt without a stale callback', async () => {
+ const h = setup('not-attempted');
+ const accepted = vi.fn();
+ const result = await h.dispatcher.dispatchOrEnqueueOrcaInterAgentMessage({ ...steerReport, onAccepted: accepted });
+ expect(result).toMatchObject({ ok: true, mode: 'queued', steerFallbackReason: 'INPUT_BOUNDARY_BUSY' });
+ expect(h.deps.enqueueQueuedMessage).toHaveBeenCalledOnce();
+ expect(accepted).not.toHaveBeenCalled();
+ const [, queued] = vi.mocked(h.deps.enqueueQueuedMessage).mock.calls[0] ?? [];
+ if (!queued) throw new Error('expected queued report');
+ await h.dispatcher.runQueuedOrcaInterAgentAcceptedCallback('target-session', queued);
+ expect(accepted).toHaveBeenCalledOnce();
+ });
+ it.each([
+ ['unsupported', 'STEER_UNSUPPORTED', 0],
+ ['remote', 'STEER_UNSUPPORTED', 0],
+ ['send-lock', 'INPUT_BOUNDARY_BUSY', 0],
+ ['guarded', 'INPUT_BOUNDARY_BUSY', 1],
+ ['generation', 'INPUT_BOUNDARY_BUSY', 0],
+ ['replacement', 'INPUT_BOUNDARY_BUSY', 0],
+ ] as const)('queues with a reason for %s', async (reason, steerFallbackReason, steerCalls) => {
+ const h = setup(reason === 'guarded' ? 'not-attempted' : 'steered');
+ if (reason === 'unsupported') h.live.capabilities.sameTurnSteer.supported = false;
+ if (reason === 'remote') h.live.remoteHostId = 'ssh-host';
+ if (reason === 'send-lock') h.deps.hasSendToSessionLock = () => true;
+ if (reason === 'generation') h.deps.buildCreateOptsForQueuedSession = async () => {
+ h.live.getTurnGeneration.mockReturnValue(8);
+ return { agentKind: 'codex', model: 'gpt-5.4', workingDir: 'C:\\repo' };
+ };
+ if (reason === 'replacement') h.deps.buildCreateOptsForQueuedSession = async () => {
+ h.deps.getLiveSession = () => ({ ...h.live });
+ return { agentKind: 'codex', model: 'gpt-5.4', workingDir: 'C:\\repo' };
+ };
+ expect(await h.dispatcher.dispatchOrEnqueueOrcaInterAgentMessage(steerReport))
+ .toMatchObject({ ok: true, mode: 'queued', steerFallbackReason });
+ expect(h.deps.enqueueQueuedMessage).toHaveBeenCalledOnce();
+ expect(h.steer).toHaveBeenCalledTimes(steerCalls);
+ });
+});
+
describe('Orca lead/worker dispatcher', () => {
it.each([false, true])('restores human restrictions for ordinary direct continuation (unavailable=%s)', async unavailable => {
const h = createHarness({readAutoReviewHistory: async () => {
diff --git a/apps/desktop/src/main/maker-ipc/__tests__/orcaTeamService.test.ts b/apps/desktop/src/main/maker-ipc/__tests__/orcaTeamService.test.ts
index 5bbfe4ae90..bdf1dc358d 100644
--- a/apps/desktop/src/main/maker-ipc/__tests__/orcaTeamService.test.ts
+++ b/apps/desktop/src/main/maker-ipc/__tests__/orcaTeamService.test.ts
@@ -363,6 +363,8 @@ function createDeps(overrides: Partial<OrcaTeamServiceDeps> = {}) {
removeQueuedMessage: vi.fn(() => true),
replaceQueuedMessage: vi.fn(() => true),
mergeQueuedMessages: vi.fn(() => true),
+ steerStoredQueuedMessage: vi.fn(async () => ({ kind: 'steered' as const })),
+ moveQueuedMessage: vi.fn(() => 0),
log: {
warn: vi.fn(),
info: vi.fn(),
@@ -623,6 +625,45 @@ describe('OrcaTeamService', () => {
]);
});
+ it('passes an explicit steer choice through and reports steered or queued receipts', async () => {
+ const { deps, service, setWorker } = createDeps();
+ setWorker(createWorker({ status: 'running' }));
+ vi.mocked(deps.dispatchWorkerMessage).mockImplementationOnce(async (params) => {
+ await params.onAccepted?.();
+ return {
+ ok: true,
+ mode: 'steered',
+ clientId: 'client-1',
+ dispatchOutcome: { kind: 'session-dispatch', source: params.dispatchMeta.source, dispatched: true },
+ targetTitle: 'Worker',
+ targetLastUserSendAt: null,
+ };
+ });
+ const base = { callerLeadSessionId: 'lead-1', targetSessionId: 'worker-1', message: '改用方案 B' };
+ await expect(service.sendToWorker({ ...base, delivery: 'steer' }))
+ .resolves.toMatchObject({ ok: true, wakeKind: 'steered' });
+ expect(deps.dispatchWorkerMessage).toHaveBeenLastCalledWith(expect.objectContaining({ delivery: 'steer' }));
+
+ vi.mocked(deps.dispatchWorkerMessage).mockImplementationOnce(async (params) => ({
+ ok: true,
+ mode: 'queued',
+ clientId: 'client-2',
+ dispatchOutcome: { kind: 'session-dispatch', source: params.dispatchMeta.source, dispatched: true, wakeKind: 'queued' },
+ targetTitle: 'Worker',
+ targetLastUserSendAt: null,
+ steerFallbackReason: 'STEER_UNSUPPORTED',
+ }));
+ await expect(service.sendToWorker({ ...base, delivery: 'steer' })).resolves.toMatchObject({
+ ok: true,
+ wakeKind: 'queued',
+ queuedMessageId: 'client-2',
+ steerFallbackReason: 'STEER_UNSUPPORTED',
+ });
+
+ await service.sendToWorker(base);
+ expect(vi.mocked(deps.dispatchWorkerMessage).mock.calls.at(-1)?.[0]).not.toHaveProperty('delivery');
+ });
+
it('routes normal and interrupt tools through the shared ownership boundary with distinct modes', async () => {
const order: string[] = [];
const reserveWorkerMessage = vi.fn(async (params) => {
@@ -3043,6 +3084,69 @@ describe('OrcaTeamService worker queued message control', () => {
).resolves.toMatchObject({ ok: false, errorCode: 'QUEUED_MESSAGE_NOT_FOUND' });
});
+ it('steers or moves lead entries in a worker queue and reports why a steer stayed queued', async () => {
+ const steerStoredQueuedMessage = vi.fn(async () => ({ kind: 'steered' as const }));
+ const moveQueuedMessage = vi.fn(() => 0);
+ const { service } = createDeps({
+ getSessionQueueSnapshot: vi.fn(async () => ({
+ pendingQueue: [queuedItem('q-user'), queuedItem('q-lead', leadOrigin)],
+ steeringClientIds: [],
+ consumingClientIds: [],
+ isWorking: true,
+ willQueue: true,
+ queuePaused: false,
+ })),
+ steerStoredQueuedMessage,
+ moveQueuedMessage,
+ });
+ const base = { callerLeadSessionId: 'lead-1', workerRef: 'worker-1' };
+
+ await expect(service.steerWorkerQueuedMessage({ ...base, queuedMessageId: 'q-lead' }))
+ .resolves.toEqual({ ok: true, workerId: 'worker-1', queuedMessageId: 'q-lead', delivery: 'steered' });
+ expect(steerStoredQueuedMessage).toHaveBeenCalledWith('worker-session-1', 'q-lead');
+ steerStoredQueuedMessage.mockResolvedValueOnce({ kind: 'queued', reason: 'STEER_UNSUPPORTED' } as never);
+ await expect(service.steerWorkerQueuedMessage({ ...base, queuedMessageId: 'q-lead' }))
+ .resolves.toMatchObject({ ok: true, delivery: 'queued', reason: 'STEER_UNSUPPORTED' });
+ await expect(service.moveWorkerQueuedMessage({ ...base, queuedMessageId: 'q-lead', position: 0 }))
+ .resolves.toEqual({ ok: true, workerId: 'worker-1', queuedMessageId: 'q-lead', position: 0 });
+ expect(moveQueuedMessage).toHaveBeenCalledWith('worker-session-1', 'q-lead', 0);
+
+ await expect(service.steerWorkerQueuedMessage({ ...base, queuedMessageId: 'q-user' }))
+ .resolves.toMatchObject({ ok: false, errorCode: 'NOT_LEAD_MESSAGE' });
+ await expect(service.moveWorkerQueuedMessage({ ...base, queuedMessageId: 'q-user', position: 1 }))
+ .resolves.toMatchObject({ ok: false, errorCode: 'NOT_LEAD_MESSAGE' });
+ expect(steerStoredQueuedMessage).toHaveBeenCalledTimes(2);
+ expect(moveQueuedMessage).toHaveBeenCalledOnce();
+ });
+
+ it('reads and steers collaboration messages in the caller\'s own queue when worker_id is omitted', async () => {
+ const workerReport = { kind: 'orca' as const, senderLabel: 'reviewer', displayText: '回报' };
+ const steerStoredQueuedMessage = vi.fn(async () => ({ kind: 'steered' as const }));
+ const { deps, service } = createDeps({
+ getSessionQueueSnapshot: vi.fn(async () => ({
+ pendingQueue: [queuedItem('q-report', workerReport), queuedItem('q-user')],
+ steeringClientIds: [],
+ consumingClientIds: [],
+ isWorking: true,
+ willQueue: true,
+ queuePaused: false,
+ })),
+ steerStoredQueuedMessage,
+ });
+
+ const listed = await service.listWorkerQueuedMessages({ callerLeadSessionId: 'lead-1' });
+ expect(listed).toMatchObject({ ok: true, workerId: null, workerSessionId: 'lead-1', status: 'lead' });
+ if (!listed.ok) throw new Error('unreachable');
+ expect(listed.messages.map((entry) => entry.source)).toEqual(['worker', 'user']);
+ expect(deps.getSessionQueueSnapshot).toHaveBeenCalledWith('lead-1');
+
+ await expect(service.steerWorkerQueuedMessage({ callerLeadSessionId: 'lead-1', queuedMessageId: 'q-report' }))
+ .resolves.toEqual({ ok: true, workerId: null, queuedMessageId: 'q-report', delivery: 'steered' });
+ expect(steerStoredQueuedMessage).toHaveBeenCalledWith('lead-1', 'q-report');
+ await expect(service.steerWorkerQueuedMessage({ callerLeadSessionId: 'lead-1', queuedMessageId: 'q-user' }))
+ .resolves.toMatchObject({ ok: false, errorCode: 'NOT_ORCA_MESSAGE' });
+ });
+
it('merges consecutive lead messages through one atomic coordinator call', async () => {
let queue = [
queuedItem('q1', leadOrigin, 'one'),
diff --git a/apps/desktop/src/main/maker-ipc/__tests__/sessionControlService.test.ts b/apps/desktop/src/main/maker-ipc/__tests__/sessionControlService.test.ts
index 3510d8aa48..9c2bee6749 100644
--- a/apps/desktop/src/main/maker-ipc/__tests__/sessionControlService.test.ts
+++ b/apps/desktop/src/main/maker-ipc/__tests__/sessionControlService.test.ts
@@ -3,6 +3,7 @@ import type { SessionActivitySnapshot } from '@cindy/maker-shared/session-activi
import type { AgentInputQueuedMessage } from '../../../shared/agentInputQueue.js';
import {
+ authorizeSessionQueueReorder,
createSessionControlService,
rebuildSessionQueueItem,
sessionQueueOriginForDispatcher,
@@ -143,6 +144,8 @@ function setup(opts?: {
getQueueSnapshot: vi.fn(async () => ({ pendingQueue: [queueItem], consumingClientIds: [] })),
replaceQueuedMessage: vi.fn(() => true),
removeQueuedMessage: vi.fn(() => true),
+ steerStoredQueuedMessage: vi.fn(async () => ({ kind: 'steered' as const })),
+ moveQueuedMessage: vi.fn(() => 0),
createId: vi.fn(() => 'steer-1'),
};
return { deps, live, service: createSessionControlService(deps) };
@@ -234,6 +237,32 @@ describe('session control domain service', () => {
expect(foreign.deps.removeQueuedMessage).not.toHaveBeenCalled();
});
+ it('steers and moves own-sent rows or machine rows in the caller\'s own queue only', async () => {
+ const { deps, service } = setup();
+ const base = { callerSessionId: 'caller', targetSessionId: 'target', queuedMessageId: 'queued-1' };
+ await expect(service.steerQueuedMessage(base))
+ .resolves.toEqual({ ok: true, queuedMessageId: 'queued-1', delivery: 'steered' });
+ expect(deps.steerStoredQueuedMessage).toHaveBeenCalledWith('target', 'queued-1');
+ await expect(service.moveQueuedMessage({ ...base, position: 0 }))
+ .resolves.toEqual({ ok: true, queuedMessageId: 'queued-1', position: 0 });
+ await expect(service.moveQueuedMessage({ ...base, position: -1 }))
+ .resolves.toMatchObject({ ok: false, errorCode: 'INVALID_ARGS' });
+
+ const own = (origin: AgentInputQueuedMessage['origin'], extra: Partial<AgentInputQueuedMessage> = {}) =>
+ authorizeSessionQueueReorder({ ...item(origin), ...extra }, 'target', 'target').ok;
+ expect(own({ kind: 'orca', senderLabel: 'reviewer', displayText: 'r' })).toBe(true);
+ expect(own({ kind: 'session', senderSessionId: 'other', displayText: 'r' })).toBe(true);
+ expect(own(undefined)).toBe(false);
+ expect(own({ kind: 'session', senderSessionId: 'other', senderBotId: 'bot-1', displayText: 'r' })).toBe(false);
+ expect(own({ kind: 'session', senderSessionId: 'other', displayText: 'r' }, {
+ sourcePlugin: { pluginId: 'plugin-1', name: 'Plugin' },
+ } as Partial<AgentInputQueuedMessage>)).toBe(false);
+ // Someone else's queue: only rows this session sent itself.
+ expect(authorizeSessionQueueReorder(
+ item({ kind: 'session', senderSessionId: 'other', displayText: 'r' }), 'caller', 'target',
+ ).ok).toBe(false);
+ });
+
it.each([
['plain text', 'before', 'replacement'],
['JSON object', '{"action":"old"}', '{"action":"new"}'],
diff --git a/apps/desktop/src/main/maker-ipc/__tests__/sessionQueueControl.test.ts b/apps/desktop/src/main/maker-ipc/__tests__/sessionQueueControl.test.ts
index da5bfbb9b2..7c98c68f7e 100644
--- a/apps/desktop/src/main/maker-ipc/__tests__/sessionQueueControl.test.ts
+++ b/apps/desktop/src/main/maker-ipc/__tests__/sessionQueueControl.test.ts
@@ -3,7 +3,11 @@ import { readFileSync } from 'node:fs';
import ts from 'typescript';
import type { AgentInputQueuedMessage } from '../../../shared/agentInputQueue.js';
-import { createSessionQueueControlService } from '../sessionQueueControl.js';
+import {
+ createQueueReorderAdapter,
+ createSessionQueueControlService,
+ type QueueReorderCoordinator,
+} from '../sessionQueueControl.js';
function queued(clientId = 'queued-1'): AgentInputQueuedMessage {
return {
@@ -25,6 +29,11 @@ function queued(clientId = 'queued-1'): AgentInputQueuedMessage {
};
}
+const noReorder = {
+ steerQueuedMessage: vi.fn(async () => ({ kind: 'gone' as const })),
+ moveQueuedMessage: vi.fn(() => null),
+};
+
describe('session queue control service', () => {
it('shares authorization, content rebuild and atomic replace for update', async () => {
const item = queued();
@@ -33,6 +42,7 @@ describe('session queue control service', () => {
getSnapshot: vi.fn(async () => ({ pendingQueue: [item], consumingClientIds: [] })),
replaceQueuedMessage,
removeQueuedMessage: vi.fn(() => true),
+ ...noReorder,
});
await expect(
@@ -70,7 +80,7 @@ describe('session queue control service', () => {
const adapter = source.slice(start, source.indexOf(' mergeQueuedMessages:', start));
const mutations = new Function('inputCoordinator', ts.transpileModule(`return ({${adapter}});`, {compilerOptions:{target:ts.ScriptTarget.ES2022}}).outputText)(inputCoordinator);
const service = createSessionQueueControlService({
- getSnapshot: async () => ({pendingQueue:[item], consumingClientIds:[]}), ...mutations,
+ getSnapshot: async () => ({pendingQueue:[item], consumingClientIds:[]}), ...mutations, ...noReorder,
});
const params = {sessionId:'session',queuedMessageId:item.clientId,authorize:()=>({ok:true as const}),beforeMutation:async()=>{item=replacement;}};
const result = action === 'cancel' ? await service.cancel(params) : await service.update({...params,message:'overwrite',rebuild:(entry,message)=>({...entry,text:message})});
@@ -91,6 +101,7 @@ describe('session queue control service', () => {
})),
replaceQueuedMessage,
removeQueuedMessage,
+ ...noReorder,
});
await expect(
consuming.cancel({
@@ -104,6 +115,7 @@ describe('session queue control service', () => {
getSnapshot: vi.fn(async () => ({ pendingQueue: [item], consumingClientIds: [] })),
replaceQueuedMessage,
removeQueuedMessage,
+ ...noReorder,
});
await expect(
unauthorized.cancel({
@@ -126,6 +138,7 @@ describe('session queue control service', () => {
getSnapshot,
replaceQueuedMessage: vi.fn(() => false),
removeQueuedMessage: vi.fn(() => false),
+ ...noReorder,
});
await expect(
service.cancel({
@@ -135,4 +148,149 @@ describe('session queue control service', () => {
}),
).resolves.toMatchObject({ ok: false, errorCode: 'MESSAGE_CONSUMING' });
});
+
+ it('steers and moves through the same locate/authorize/race boundary', async () => {
+ const item = queued();
+ const steerQueuedMessage = vi.fn(async () => ({ kind: 'queued' as const, reason: 'NO_ACTIVE_TURN' as const }));
+ const moveQueuedMessage = vi.fn((): number | null | 'locked' => 2);
+ const getSnapshot = vi.fn(async () => ({ pendingQueue: [item], consumingClientIds: [] as string[] }));
+ const service = createSessionQueueControlService({
+ getSnapshot,
+ replaceQueuedMessage: vi.fn(),
+ removeQueuedMessage: vi.fn(),
+ steerQueuedMessage,
+ moveQueuedMessage,
+ });
+ const params = { sessionId: 's', queuedMessageId: item.clientId, authorize: () => ({ ok: true as const }) };
+ await expect(service.steer(params)).resolves.toEqual({
+ ok: true, queuedMessageId: item.clientId, delivery: 'queued', reason: 'NO_ACTIVE_TURN',
+ });
+ await expect(service.move({ ...params, position: 5 }))
+ .resolves.toEqual({ ok: true, queuedMessageId: item.clientId, position: 2 });
+
+ moveQueuedMessage.mockReturnValueOnce(null);
+ getSnapshot.mockResolvedValueOnce({ pendingQueue: [item], consumingClientIds: [] })
+ .mockResolvedValueOnce({ pendingQueue: [], consumingClientIds: [item.clientId] });
+ await expect(service.move({ ...params, position: 0 }))
+ .resolves.toMatchObject({ ok: false, errorCode: 'MESSAGE_CONSUMING' });
+ moveQueuedMessage.mockReturnValueOnce('locked');
+ await expect(service.move({ ...params, position: 0 }))
+ .resolves.toMatchObject({ ok: false, errorCode: 'MESSAGE_CONSUMING', message: expect.stringContaining('being edited') });
+
+ await expect(service.steer({ ...params, authorize: () => ({ ok: false, message: 'no' }) }))
+ .resolves.toMatchObject({ ok: false, errorCode: 'NOT_AUTHORIZED' });
+ expect(steerQueuedMessage).toHaveBeenCalledOnce();
+ });
+});
+
+describe('queue reorder adapter', () => {
+ function setup(live: { running?: boolean; supported?: boolean; remote?: string | null } | null) {
+ let queue = ['a', 'b', 'c', 'd'].map((id) => queued(id));
+ let paused = false;
+ const editLocks: string[] = [];
+ const steering: string[] = [];
+ const coordinator: QueueReorderCoordinator = {
+ steerControlInput: vi.fn(async () => 'steered' as const),
+ isQueuePaused: () => paused,
+ getQueueControlSnapshot: () => ({ pendingQueue: queue }),
+ getProjection: () => ({ queueEditLocks: editLocks, steeringQueueClientIds: steering }),
+ move: vi.fn((_sessionId: string, clientId: string, targetIndex: number) => {
+ // Mirrors AgentInputCoordinator.move: insert before original index targetIndex.
+ const from = queue.findIndex((entry) => entry.clientId === clientId);
+ const next = [...queue];
+ const [entry] = next.splice(from, 1);
+ let insert = Math.max(0, Math.min(targetIndex, queue.length));
+ if (from < insert) insert -= 1;
+ next.splice(insert, 0, entry!);
+ queue = next;
+ }),
+ };
+ const session = live && {
+ isTurnRunning: () => live.running ?? true,
+ getTurnGeneration: () => 3,
+ capabilities: { sameTurnSteer: { supported: live.supported ?? true } },
+ remoteHostId: live.remote ?? null,
+ };
+ const adapter = createQueueReorderAdapter({
+ getLiveSession: () => session,
+ hasSendToSessionLock: () => false,
+ getCoordinator: () => coordinator,
+ });
+ return {
+ adapter,
+ coordinator,
+ order: () => queue.map((entry) => entry.clientId),
+ pause: () => { paused = true; },
+ lockEdit: (clientId: string) => { editLocks.push(clientId); },
+ startSteering: (clientId: string) => { steering.push(clientId); },
+ drop: (clientId: string) => { queue = queue.filter((entry) => entry.clientId !== clientId); },
+ };
+ }
+
+ it.each([
+ [0, ['c', 'a', 'b', 'd'], 0],
+ [1, ['a', 'c', 'b', 'd'], 1],
+ [2, ['a', 'b', 'c', 'd'], 2],
+ [3, ['a', 'b', 'd', 'c'], 3],
+ [9, ['a', 'b', 'd', 'c'], 3],
+ ])('moves a waiting row to final position %i', (position, expected, finalIndex) => {
+ const h = setup({});
+ expect(h.adapter.moveStoredControlMessage('s', 'c', position)).toBe(finalIndex);
+ expect(h.order()).toEqual(expected);
+ expect(h.adapter.moveStoredControlMessage('s', 'missing', 0)).toBeNull();
+ });
+
+ it('keeps a row the user is editing in place', () => {
+ const h = setup({});
+ h.lockEdit('c');
+ expect(h.adapter.moveStoredControlMessage('s', 'c', 0)).toBe('locked');
+ expect(h.order()).toEqual(['a', 'b', 'c', 'd']);
+ expect(h.coordinator.move).not.toHaveBeenCalled();
+ });
+
+ it('reports a row that started steering as gone instead of claiming the move', () => {
+ const h = setup({});
+ h.startSteering('c');
+ expect(h.adapter.moveStoredControlMessage('s', 'c', 0)).toBeNull();
+ expect(h.coordinator.move).not.toHaveBeenCalled();
+ });
+
+ it('maps live capability and coordinator outcomes to steer receipts', async () => {
+ expect(await setup(null).adapter.steerStoredControlMessage('s', 'a'))
+ .toEqual({ kind: 'queued', reason: 'NO_ACTIVE_TURN' });
+ expect(await setup({ supported: false }).adapter.steerStoredControlMessage('s', 'a'))
+ .toEqual({ kind: 'queued', reason: 'STEER_UNSUPPORTED' });
+ expect(await setup({ remote: 'ssh-host' }).adapter.steerStoredControlMessage('s', 'a'))
+ .toEqual({ kind: 'queued', reason: 'STEER_UNSUPPORTED' });
+
+ const steered = setup({});
+ expect(await steered.adapter.steerStoredControlMessage('s', 'b')).toEqual({ kind: 'steered' });
+ expect(steered.coordinator.steerControlInput).toHaveBeenCalledWith(
+ 's', { queuedClientId: 'b' }, expect.objectContaining({ turnGeneration: 3 }),
+ );
+
+ const busy = setup({});
+ vi.mocked(busy.coordinator.steerControlInput).mockResolvedValueOnce('not-attempted');
+ expect(await busy.adapter.steerStoredControlMessage('s', 'b'))
+ .toEqual({ kind: 'queued', reason: 'INPUT_BOUNDARY_BUSY' });
+
+ const uncertain = setup({});
+ vi.mocked(uncertain.coordinator.steerControlInput).mockImplementationOnce(async () => {
+ uncertain.pause();
+ return 'queued';
+ });
+ expect(await uncertain.adapter.steerStoredControlMessage('s', 'b'))
+ .toEqual({ kind: 'queued', reason: 'STEER_UNCERTAIN' });
+
+ const gone = setup({});
+ vi.mocked(gone.coordinator.steerControlInput).mockResolvedValueOnce('rejected');
+ expect(await gone.adapter.steerStoredControlMessage('s', 'b')).toEqual({ kind: 'gone' });
+
+ const raced = setup({});
+ vi.mocked(raced.coordinator.steerControlInput).mockImplementationOnce(async () => {
+ raced.drop('b');
+ return 'not-attempted';
+ });
+ expect(await raced.adapter.steerStoredControlMessage('s', 'b')).toEqual({ kind: 'gone' });
+ });
});
diff --git a/apps/desktop/src/main/maker-ipc/agent-input-coordinator.ts b/apps/desktop/src/main/maker-ipc/agent-input-coordinator.ts
index 3378bcbe8c..e9022051ca 100644
--- a/apps/desktop/src/main/maker-ipc/agent-input-coordinator.ts
+++ b/apps/desktop/src/main/maker-ipc/agent-input-coordinator.ts
@@ -529,6 +529,12 @@ export interface AgentInputCoordinatorDeps {
item: AgentInputQueuedMessage,
restoredFromSnapshot?: boolean,
) => void | Promise<void>;
+ /**
+ * A steer crossed the irreversible provider boundary (direct or promoted queue row).
+ * The item joined the running turn instead of starting one, so hosts release any
+ * per-clientId turn-start bookkeeping here rather than running it.
+ */
+ onSteerAccepted?: (sessionId: string, item: AgentInputQueuedMessage) => void | Promise<void>;
/**
* Awaited only after vendor dispatch is irreversible (`accepted=true`).
* Hosts use this for side effects that must not run on cancelled-before-dispatch
@@ -895,6 +901,32 @@ function normalizeRestoredSyntheticTrigger(item: AgentInputQueuedMessage): Agent
type PersistAcceptedUserMessageResult = 'persisted' | 'stale' | 'failed';
+/**
+ * steered = provider accepted; queued = the coordinator still owns the row (ACK-uncertain
+ * pause, or the queued row stayed in place); not-attempted = not delivered and nothing is
+ * retained, so ordinary delivery is still safe; rejected = input screening discarded it.
+ */
+export type ControlSteerOutcome = 'steered' | 'queued' | 'not-attempted' | 'rejected';
+
+/** What a steer attempt actually did, beyond the boolean UI contract. */
+interface SteerObservation {
+ providerAccepted: AgentInputQueuedMessage | null;
+ policyBlocked: boolean;
+}
+
+interface SteerOptions {
+ removeFromQueue?: boolean;
+ touchUserSend?: boolean;
+ /** 控制面插话不允许在 turn 结束竞态下退化成下一轮普通输入。 */
+ fallbackToTurn?: boolean;
+ /** 控制面初检捕获的 live Session 对象,防 session id 被新实例复用。 */
+ expectedTurnSession?: object;
+ /** 控制面初检捕获的 maker-core turn generation。 */
+ expectedTurnGeneration?: number;
+ /** Agent-chosen steer: never unpause the queue, and re-check its guard before dispatch. */
+ controlInput?: { fromQueue: boolean };
+}
+
function isNoActiveTurnError(err: unknown): boolean {
const msg = err instanceof Error ? err.message : String(err);
return /\[NO_ACTIVE_TURN\]|no active .*turn|has no active turn/i.test(msg);
@@ -2005,19 +2037,111 @@ export class AgentInputCoordinator {
}
}
+ /**
+ * Agent-chosen steer (Orca / cindy_helper tools) of either a host-built message or a
+ * queued row. The agent picked "steer", so it may pass earlier queued rows, but it must
+ * not reopen Stop/pause/recovery/interaction boundaries. The same guard is re-checked
+ * just before provider dispatch. A failed ACK can leave the item in a paused queue:
+ * that is host ownership, not permission to send a second copy.
+ */
+ async steerControlInput(
+ sessionId: string,
+ target: { item: AgentInputQueuedMessage } | { queuedClientId: string },
+ expectedTurn: { session: object; turnGeneration: number },
+ ): Promise<ControlSteerOutcome> {
+ await this.ensureQueueRestored(sessionId).catch(() => undefined);
+ const state = this.getState(sessionId);
+ const fromQueue = 'queuedClientId' in target;
+ const item = fromQueue
+ ? state.pendingQueue.find((queued) => queued.clientId === target.queuedClientId)
+ : target.item;
+ if (!item) return 'rejected';
+ if (
+ this.deps.getTurnSessionIdentity?.(sessionId) !== expectedTurn.session ||
+ this.deps.getTurnGeneration?.(sessionId) !== expectedTurn.turnGeneration ||
+ this.isControlSteerBlocked(sessionId, state, item.clientId, { fromQueue, ownSteer: false })
+ ) return 'not-attempted';
+
+ const observed = await this.steerObserved(sessionId, item, {
+ fallbackToTurn: false,
+ removeFromQueue: fromQueue,
+ controlInput: { fromQueue },
+ expectedTurnSession: expectedTurn.session,
+ expectedTurnGeneration: expectedTurn.turnGeneration,
+ });
+ if (observed.providerAccepted) return 'steered';
+ // Input screening discarded the content: a definitive refusal, never a retry candidate.
+ if (observed.policyBlocked) return 'rejected';
+ // In particular, preserve ACK-uncertain items and their protective pause.
+ // Do not infer non-delivery from the live turn ending during the request.
+ return this.hasPendingQueueItem(sessionId, item.clientId) ? 'queued' : 'not-attempted';
+ }
+
+ /** Shared by the pre-check and the pre-provider re-check of agent-chosen steering. */
+ private isControlSteerBlocked(
+ sessionId: string,
+ state: SessionInputState,
+ clientId: string,
+ opts: { fromQueue: boolean; ownSteer: boolean },
+ ): boolean {
+ return (
+ !this.isQueueRestored(sessionId) ||
+ !this.deps.isTurnRunning(sessionId) ||
+ state.queuePaused || state.queueAbortPending || state.abortBoundaryToken !== null ||
+ state.queueInteractionLocks.length > 0 ||
+ state.steeringQueueClientIds.some((id) => !opts.ownSteer || id !== clientId) ||
+ state.recovery !== null || state.pendingExternalTerminalDone ||
+ this.deps.hasPendingInteraction(sessionId) ||
+ this.deps.hasPendingCredentialSwitch?.(sessionId) === true ||
+ (state.activeTurn !== null && !isActiveTurnDispatched(state.activeTurn)) ||
+ (opts.fromQueue &&
+ (state.queueEditLocks.includes(clientId) ||
+ !state.pendingQueue.some((queued) => queued.clientId === clientId)))
+ );
+ }
+
async steer(
sessionId: string,
item: AgentInputQueuedMessage,
- opts?: {
- removeFromQueue?: boolean;
- touchUserSend?: boolean;
- /** 控制面插话不允许在 turn 结束竞态下退化成下一轮普通输入。 */
- fallbackToTurn?: boolean;
- /** 控制面初检捕获的 live Session 对象,防 session id 被新实例复用。 */
- expectedTurnSession?: object;
- /** 控制面初检捕获的 maker-core turn generation。 */
- expectedTurnGeneration?: number;
- },
+ opts?: SteerOptions,
+ ): Promise<boolean> {
+ return (await this.steerObserved(sessionId, item, opts)).accepted;
+ }
+
+ private async steerObserved(
+ sessionId: string,
+ item: AgentInputQueuedMessage,
+ opts: SteerOptions | undefined,
+ ): Promise<SteerObservation & { accepted: boolean }> {
+ const observation: SteerObservation = { providerAccepted: null, policyBlocked: false };
+ const accepted = await this.steerWithinBoundary(sessionId, item, opts, observation);
+ if (observation.providerAccepted) {
+ await this.notifySteerAccepted(sessionId, observation.providerAccepted);
+ }
+ return { ...observation, accepted };
+ }
+
+ private async notifySteerAccepted(
+ sessionId: string,
+ item: AgentInputQueuedMessage,
+ ): Promise<void> {
+ try {
+ await this.deps.onSteerAccepted?.(sessionId, item);
+ } catch (err) {
+ // Provider acceptance is irreversible; host bookkeeping must not turn it into a failure.
+ log.warn('steer accepted hook failed', {
+ sessionId,
+ clientId: item.clientId,
+ error: errorMessage(err),
+ });
+ }
+ }
+
+ private async steerWithinBoundary(
+ sessionId: string,
+ item: AgentInputQueuedMessage,
+ opts: SteerOptions | undefined,
+ observation: SteerObservation,
): Promise<boolean> {
const matchesExpectedTurn = () =>
(opts?.expectedTurnSession === undefined ||
@@ -2134,7 +2258,9 @@ export class AgentInputCoordinator {
const steerContinuationOwnerClientId = state.activeTurn?.continuationOwnerClientId ?? null;
const steerVendorTurnGeneration = this.deps.getTurnGeneration?.(sessionId) ?? null;
this.clearErrorUnlessQueueHeadBlocked(state, item.clientId);
- state.queuePaused = false;
+ // UI steer doubles as "resume"; an agent-chosen steer only runs when the queue is
+ // not paused and must never release a pause the user owns.
+ if (!opts?.controlInput) state.queuePaused = false;
if (!state.steeringQueueClientIds.includes(item.clientId)) {
state.steeringQueueClientIds.push(item.clientId);
}
@@ -2193,6 +2319,7 @@ export class AgentInputCoordinator {
cur.queueEditLocks = cur.queueEditLocks.filter((id) => id !== item.clientId);
if (cur.pendingQueue.length === 0) cur.queuePaused = false;
}
+ observation.policyBlocked = true;
this.deps.onUserMessageBlocked?.(sessionId, item, verdict);
this.notifyRejectedUserTurn(sessionId, item);
this.deps.onDiscardedQueuedMessage?.(sessionId, item);
@@ -2230,7 +2357,10 @@ export class AgentInputCoordinator {
const current = this.getState(sessionId);
if (!matchesExpectedTurn() || current.queueInteractionLocks.length > 0
|| current.queueAbortPending || inputBoundarySignal.aborted || steerAbort.signal.aborted
- || !this.isCurrentSteerRequest(current, item.clientId, steerGeneration, steerRequestToken)) {
+ || !this.isCurrentSteerRequest(current, item.clientId, steerGeneration, steerRequestToken)
+ || (opts?.controlInput !== undefined && this.isControlSteerBlocked(
+ sessionId, current, item.clientId, { fromQueue: opts.controlInput.fromQueue, ownSteer: true },
+ ))) {
const latest = current;
if (
this.clearSteeringMarker(latest, item.clientId, {
@@ -2401,6 +2531,8 @@ export class AgentInputCoordinator {
this.scheduleDrain(sessionId, 'steer-hard-failure');
return finishSteerRequest(false);
}
+ // Every path below follows a resolved provider steer, including clear/Stop races.
+ observation.providerAccepted = item;
const accepted = this.getState(sessionId);
const ownsCurrentSteerMarker = this.isCurrentSteerRequest(
accepted,
diff --git a/apps/desktop/src/main/maker-ipc/orcaInterAgentDispatcher.ts b/apps/desktop/src/main/maker-ipc/orcaInterAgentDispatcher.ts
index 85a7afee05..5ad87f95da 100644
--- a/apps/desktop/src/main/maker-ipc/orcaInterAgentDispatcher.ts
+++ b/apps/desktop/src/main/maker-ipc/orcaInterAgentDispatcher.ts
@@ -22,12 +22,16 @@ import { resolveCollabDispatchResult } from './collabSendOutcome.js';
import type {
AgentInputSendOpts,
AgentInputSendResult,
+ ControlSteerOutcome,
} from './agent-input-coordinator.js';
import { runAcceptedCallback, runAcceptedRollback } from './acceptedCallbackRunner.js';
const defaultLog = createLogger('maker-ipc');
-type OrcaInterAgentDispatchMode = 'dispatched' | 'queued';
+type OrcaInterAgentDispatchMode = 'dispatched' | 'queued' | 'steered';
+
+/** 请求插话但消息进了队列的原因;目标空闲直发时没有原因。 */
+export type OrcaSteerFallbackReason = 'STEER_UNSUPPORTED' | 'INPUT_BOUNDARY_BUSY' | 'STEER_UNCERTAIN';
/** Orca lead/worker 派发结果,保留底层 dispatch outcome 供 MCP/IPC 区分排队、直发和失败根因。 */
export type DispatchOrcaInterAgentMessageResult =
@@ -38,6 +42,7 @@ export type DispatchOrcaInterAgentMessageResult =
dispatchOutcome: CollabDispatchSuccessOutcome | CollabDispatchQueuedOutcome;
targetTitle?: string | null;
targetLastUserSendAt?: string | null;
+ steerFallbackReason?: OrcaSteerFallbackReason;
}
| {
ok: false;
@@ -54,6 +59,8 @@ export interface DispatchOrcaInterAgentMessageParams {
source: OrcaInterAgentMessageSource;
senderLabel: string;
workerId?: string;
+ /** 发送方显式选择;缺省排队。steer 只在目标正在运行时插进当前 turn。 */
+ delivery?: 'queue' | 'steer';
/** Synchronous reserve boundary hook; must return before drain is scheduled. */
onReserved?: () => void;
beforeReserve?: () => Promise<void>;
@@ -71,6 +78,9 @@ interface PersistedUserMessageSession {
id: string;
agentKind?: AgentKind;
isTurnRunning?: () => boolean;
+ getTurnGeneration?: () => number;
+ capabilities?: { sameTurnSteer: { supported: boolean } };
+ remoteHostId?: string | null;
send: (
message: UserMessage,
opts?: SessionSendOptions,
@@ -142,6 +152,12 @@ export interface OrcaInterAgentDispatcherDeps<TSessionMeta> {
getSessionMeta: (sessionId: string) => Promise<TSessionMeta | null>;
getSessionRowSnapshot: (sessionId: string) => Promise<OrcaInterAgentSessionRowSnapshot | null>;
getLiveSession: (sessionId: string) => PersistedUserMessageSession | null | undefined;
+ /** Uses the input coordinator's steer guards and preserves uncertain-delivery ownership. */
+ steerControlInput?: (
+ sessionId: string,
+ item: AgentInputQueuedMessage,
+ expectedTurn: { session: object; turnGeneration: number },
+ ) => Promise<ControlSteerOutcome>;
shouldQueueNewTurn: (sessionId: string) => boolean;
hasSendToSessionLock: (sessionId: string) => boolean;
/**
@@ -386,6 +402,12 @@ export function createOrcaInterAgentDispatcher<TSessionMeta>(
...(senderSessionId ? { senderSessionId } : {}),
};
};
+ let steerFallbackReason: OrcaSteerFallbackReason | undefined;
+ // 请求了插话却落进队列时,回执必须说明原因;没请求插话时不带。
+ const queuedSteerFallback = (): { steerFallbackReason?: OrcaSteerFallbackReason } =>
+ params.delivery === 'steer'
+ ? { steerFallbackReason: steerFallbackReason ?? 'INPUT_BOUNDARY_BUSY' }
+ : {};
const enqueueQueuedMessage = async (logEvent: string): Promise<DispatchOrcaInterAgentMessageResult> => {
const createOpts = await deps.buildCreateOptsForQueuedSession(params.targetSessionId, meta);
const queued = buildQueuedOrcaInterAgentMessage({
@@ -416,10 +438,78 @@ export function createOrcaInterAgentDispatcher<TSessionMeta>(
mode: 'queued',
clientId,
dispatchOutcome: makeQueuedDispatchOutcome(params.meta.source),
+ ...queuedSteerFallback(),
...dispatchReceipt,
};
};
+ // 插话只由发送方显式选择(delivery=steer),且只对正在运行的目标尝试;空闲目标照常直发。
+ const liveTurn = deps.getLiveSession(params.targetSessionId);
+ if (params.delivery === 'steer' && liveTurn?.isTurnRunning?.() === true) {
+ if (
+ !deps.steerControlInput || !liveTurn.capabilities?.sameTurnSteer.supported ||
+ !liveTurn.getTurnGeneration || liveTurn.remoteHostId
+ ) {
+ steerFallbackReason = 'STEER_UNSUPPORTED';
+ } else if (!deps.hasSendToSessionLock(params.targetSessionId)) {
+ const expectedTurn = { session: liveTurn, turnGeneration: liveTurn.getTurnGeneration() };
+ const trySteer = async (): Promise<DispatchOrcaInterAgentMessageResult | null> => {
+ // Async item preparation and lock acquisition can cross a turn replacement.
+ const createOpts = await deps.buildCreateOptsForQueuedSession(params.targetSessionId, meta);
+ const item = buildQueuedOrcaInterAgentMessage({
+ clientId,
+ agentMessageText: await buildAgentMessageText(),
+ persistedContent,
+ origin: await resolveOrigin(),
+ createOpts,
+ });
+ if (
+ deps.getLiveSession(params.targetSessionId) !== liveTurn ||
+ !liveTurn.isTurnRunning?.() ||
+ liveTurn.getTurnGeneration?.() !== expectedTurn.turnGeneration
+ ) return null;
+ const outcome = await deps.steerControlInput!(params.targetSessionId, item, expectedTurn);
+ if (outcome === 'steered') {
+ // The message joined the running turn. Accepted/commit callbacks claim a new
+ // turn's running/auto-bridge identity, so they deliberately never run here.
+ return { ok: true, mode: 'steered', clientId,
+ dispatchOutcome: { kind: 'session-dispatch', source: params.meta.source, dispatched: true },
+ ...dispatchReceipt };
+ }
+ if (outcome === 'rejected') {
+ // Input screening discarded it. Re-queueing would retry refused content.
+ return failureResult({
+ ...createHostSendFailure('SEND_FAILED', 'Orca message was blocked by input screening'),
+ source: params.meta.source, context: params.meta.context,
+ });
+ }
+ if (outcome === 'queued') {
+ // The coordinator already owns this exact clientId in a paused queue. Enqueuing
+ // again would duplicate it; its later drain starts a turn, so register there.
+ if (params.onAccepted) registerQueuedOrcaInterAgentAcceptedCallback(
+ clientId, params.onAccepted, params.onAcceptedRollback, params.onAcceptedCommit,
+ );
+ return { ok: true, mode: 'queued', clientId,
+ dispatchOutcome: makeQueuedDispatchOutcome(params.meta.source),
+ steerFallbackReason: 'STEER_UNCERTAIN', ...dispatchReceipt };
+ }
+ // Not delivered and nothing retained: the ordinary send/queue path is still safe.
+ return null;
+ };
+ try {
+ const steered = deps.withSendToSessionLock
+ ? await deps.withSendToSessionLock(params.targetSessionId, trySteer)
+ : await trySteer();
+ if (steered) return steered;
+ } catch (err) {
+ return failureResult({
+ ...createHostSendFailure('SEND_FAILED', err instanceof Error ? err.message : String(err)),
+ source: params.meta.source, context: params.meta.context,
+ });
+ }
+ }
+ }
+
const shouldQueue = deps.shouldQueueNewTurn(params.targetSessionId)
|| deps.hasSendToSessionLock(params.targetSessionId)
|| deps.getLiveSession(params.targetSessionId)?.isTurnRunning?.() === true;
@@ -465,6 +555,7 @@ export function createOrcaInterAgentDispatcher<TSessionMeta>(
source: params.meta.source,
dispatched: true,
},
+ ...(result.wakeKind === 'queued' ? queuedSteerFallback() : {}),
targetTitle: result.targetTitle,
targetLastUserSendAt: result.targetLastUserSendAt,
};
diff --git a/apps/desktop/src/main/maker-ipc/orcaTeamService.ts b/apps/desktop/src/main/maker-ipc/orcaTeamService.ts
index ec033a2e82..26ed6de36d 100644
--- a/apps/desktop/src/main/maker-ipc/orcaTeamService.ts
+++ b/apps/desktop/src/main/maker-ipc/orcaTeamService.ts
@@ -9,7 +9,12 @@ import type {
} from './collabSendOutcome.js';
import { AcceptedCallbackDispatchCancelled } from './acceptedCallbackRunner.js';
import { rebuildQueuedOrcaLeadMessage } from './orcaInterAgentDispatcher.js';
-import { createSessionQueueControlService } from './sessionQueueControl.js';
+import {
+ createSessionQueueControlService,
+ type QueuedSteerFallbackReason,
+ type QueuedSteerOutcome,
+} from './sessionQueueControl.js';
+import type { OrcaSteerFallbackReason } from './orcaInterAgentDispatcher.js';
/**
* OrcaTeamService 只接管已存在 worker 的派活、释放、归档与 auto-bridge。
@@ -57,11 +62,13 @@ export type SendToWorkerResult =
| {
ok: true;
agentKind: AgentKind;
- wakeKind: 'resumed' | 'already-active' | 'queued';
+ wakeKind: 'resumed' | 'already-active' | 'queued' | 'steered';
targetTitle: string | null;
targetLastUserSendAt: string | null;
/** wakeKind='queued' 时回传:排队消息的可寻址句柄,供 lead 后续查看/修改/撤回。 */
queuedMessageId?: string;
+ /** 请求插话却进了队列时的原因。 */
+ steerFallbackReason?: OrcaSteerFallbackReason;
}
| {
ok: false;
@@ -86,12 +93,13 @@ export type InterruptWorkerResult =
export type DispatchWorkerMessageResult =
| {
ok: true;
- mode: 'dispatched' | 'queued';
+ mode: 'dispatched' | 'queued' | 'steered';
/** 底层 dispatcher 为该消息生成的 clientId;queued 模式下即队列内寻址句柄。 */
clientId: string;
dispatchOutcome: CollabDispatchSuccessOutcome | CollabDispatchQueuedOutcome;
targetTitle: string | null;
targetLastUserSendAt: string | null;
+ steerFallbackReason?: OrcaSteerFallbackReason;
}
| {
ok: false;
@@ -115,7 +123,7 @@ export type DispatchWorkerTaskResult =
queued?: false;
dispatchOutcome: CollabDispatchSuccessOutcome;
agentKind: AgentKind;
- wakeKind: 'resumed' | 'already-active';
+ wakeKind: 'resumed' | 'already-active' | 'steered';
targetTitle: string | null;
targetLastUserSendAt: string | null;
}
@@ -129,6 +137,7 @@ export type DispatchWorkerTaskResult =
targetLastUserSendAt: string | null;
/** 排队消息的可寻址句柄(coordinator 队列内的 clientId)。 */
queuedMessageId: string;
+ steerFallbackReason?: OrcaSteerFallbackReason;
}
| {
dispatched: false;
@@ -145,6 +154,7 @@ export type WorkerQueuedMessageFailureCode =
| 'WORKER_NOT_FOUND'
| 'QUEUED_MESSAGE_NOT_FOUND'
| 'NOT_LEAD_MESSAGE'
+ | 'NOT_ORCA_MESSAGE'
| 'MESSAGE_CONSUMING'
| 'QUEUE_CHANGED'
| 'INVALID_ARGS'
@@ -159,7 +169,8 @@ export type WorkerQueuedMessageFailureCode =
export interface WorkerQueuedMessageSnapshot {
queuedMessageId: string;
position: number;
- source: 'lead' | 'user' | 'scheduler';
+ /** worker = Lead 自己队列里的 Worker 回报;lead = worker 队列里 Lead 发的消息。 */
+ source: 'lead' | 'worker' | 'user' | 'scheduler';
content: string;
/** true = 该条正在 steering 投递中,不可修改 / 撤回。 */
consuming: boolean;
@@ -170,12 +181,30 @@ export type WorkerQueuedMessageControlResult =
| { ok: true; workerId: string; queuedMessageId: string }
| { ok: false; errorCode: WorkerQueuedMessageFailureCode; message: string };
+type WorkerQueuedMessageFailure = { ok: false; errorCode: WorkerQueuedMessageFailureCode; message: string };
+
+/** workerId=null 表示操作的是 Lead 自己的输入队列。 */
+export type SteerWorkerQueuedMessageResult =
+ | {
+ ok: true;
+ workerId: string | null;
+ queuedMessageId: string;
+ delivery: 'steered' | 'queued';
+ reason?: QueuedSteerFallbackReason;
+ }
+ | WorkerQueuedMessageFailure;
+
+export type MoveWorkerQueuedMessageResult =
+ | { ok: true; workerId: string | null; queuedMessageId: string; position: number }
+ | WorkerQueuedMessageFailure;
+
export type ListWorkerQueuedMessagesResult =
| {
ok: true;
- workerId: string;
+ /** null = Lead 自己的输入队列。 */
+ workerId: string | null;
workerSessionId: string;
- status: OrcaWorkerStatus;
+ status: OrcaWorkerStatus | 'lead';
isWorking: boolean;
willQueue: boolean;
queuePaused: boolean;
@@ -256,6 +285,7 @@ export interface OrcaTeamServiceDeps {
targetSessionId: string;
message: string;
workerId: string;
+ delivery?: 'queue' | 'steer';
dispatchMeta: {
source: string;
context: string;
@@ -307,6 +337,8 @@ export interface OrcaTeamServiceDeps {
removeQueuedMessage(sessionId: string, clientId: string, expected?: AgentInputQueuedMessage): boolean;
/** 整条替换一条排队消息(同 clientId 原位替换);steering / 已派发返回 false。 */
replaceQueuedMessage(sessionId: string, clientId: string, next: AgentInputQueuedMessage, expected?: AgentInputQueuedMessage): boolean;
+ steerStoredQueuedMessage(sessionId: string, clientId: string): Promise<QueuedSteerOutcome>;
+ moveQueuedMessage(sessionId: string, clientId: string, position: number): number | null | 'locked';
mergeQueuedMessages(
sessionId: string,
clientIds: readonly string[],
@@ -329,6 +361,7 @@ export interface OrcaTeamService {
callerLeadSessionId: string;
targetSessionId: string;
message: string;
+ delivery?: 'queue' | 'steer';
}, assertCurrent?: () => Promise<void>): Promise<SendToWorkerResult>;
/** Sole public entry for replacing the active worker turn. */
interruptWorker(params: {
@@ -345,9 +378,10 @@ export interface OrcaTeamService {
/** 外部调用边界:按 caller lead 校验 worker 可见性。 */
archiveWorker(params: { callerLeadSessionId: string; workerId: string; onlyIfIdle?: boolean; beforeArchive?: () => Promise<void> }): Promise<OrcaOkResult>;
/** 外部调用边界:列出目标 worker 输入队列中的排队消息(lead 自己的条目含正文)。 */
+ /** workerRef 省略时读取 Lead 自己的输入队列(Worker 回报在 Lead 忙时排在这里)。 */
listWorkerQueuedMessages(params: {
callerLeadSessionId: string;
- workerRef: string;
+ workerRef?: string;
}): Promise<ListWorkerQueuedMessagesResult>;
/** 外部调用边界:修改一条尚未派发的 lead 排队消息(整条正文替换,按原派发格式重建)。 */
updateWorkerQueuedMessage(params: {
@@ -368,6 +402,18 @@ export interface OrcaTeamService {
queuedMessageIds: string[];
message: string;
}): Promise<MergeWorkerQueuedMessagesResult>;
+ /** 把一条 Orca 排队消息插进目标当前 turn;workerRef 省略时作用于 Lead 自己的队列。 */
+ steerWorkerQueuedMessage(params: {
+ callerLeadSessionId: string;
+ workerRef?: string;
+ queuedMessageId: string;
+ }): Promise<SteerWorkerQueuedMessageResult>;
+ moveWorkerQueuedMessage(params: {
+ callerLeadSessionId: string;
+ workerRef?: string;
+ queuedMessageId: string;
+ position: number;
+ }): Promise<MoveWorkerQueuedMessageResult>;
captureWorkerText(sessionId: string, text: string, opts?: { isFinal?: boolean }): void;
clearAutoBridgeState(sessionId: string): void;
/** True while an accepted worker task still owes this Lead its report. */
@@ -424,6 +470,8 @@ export function createOrcaTeamService(deps: OrcaTeamServiceDeps): OrcaTeamServic
},
replaceQueuedMessage: deps.replaceQueuedMessage,
removeQueuedMessage: deps.removeQueuedMessage,
+ steerQueuedMessage: deps.steerStoredQueuedMessage,
+ moveQueuedMessage: deps.moveQueuedMessage,
});
/** Per-worker transition tails serialize dispatch reservations against implicit done acknowledgement. */
const workerTransitionTails = new Map<string, Promise<void>>();
@@ -838,13 +886,17 @@ export function createOrcaTeamService(deps: OrcaTeamServiceDeps): OrcaTeamServic
targetTitle: result.targetTitle ?? target.session.title,
targetLastUserSendAt: result.targetLastUserSendAt,
queuedMessageId: result.clientId,
+ ...(result.steerFallbackReason ? { steerFallbackReason: result.steerFallbackReason } : {}),
};
}
return {
dispatched: true,
dispatchOutcome: result.dispatchOutcome as CollabDispatchSuccessOutcome,
agentKind: target.session.agentKind,
- wakeKind: execution.wasLiveBeforeDispatch ? 'already-active' : 'resumed',
+ wakeKind:
+ result.mode === 'steered'
+ ? 'steered'
+ : execution.wasLiveBeforeDispatch ? 'already-active' : 'resumed',
targetTitle: result.targetTitle ?? target.session.title,
targetLastUserSendAt: result.targetLastUserSendAt,
};
@@ -855,6 +907,7 @@ export function createOrcaTeamService(deps: OrcaTeamServiceDeps): OrcaTeamServic
resolved: ResolvedWorker;
message: string;
mode: 'normal' | 'interrupt';
+ delivery?: 'queue' | 'steer';
dispatchMeta: DispatchWorkerTaskParams['dispatchMeta'];
assertCurrent?: () => Promise<void>;
}): Promise<ResolvedWorkerDispatchExecution> {
@@ -987,6 +1040,7 @@ export function createOrcaTeamService(deps: OrcaTeamServiceDeps): OrcaTeamServic
targetSessionId: target.sessionId,
message: params.message,
workerId: link.workerId,
+ ...(params.delivery ? { delivery: params.delivery } : {}),
dispatchMeta: params.dispatchMeta,
onAccepted,
onAcceptedRollback: rollbackAccepted,
@@ -1068,6 +1122,7 @@ export function createOrcaTeamService(deps: OrcaTeamServiceDeps): OrcaTeamServic
callerLeadSessionId: string;
targetSessionId: string;
message: string;
+ delivery?: 'queue' | 'steer';
}, assertCurrent?: () => Promise<void>): Promise<SendToWorkerResult> {
return dispatchToWorker({ ...params, mode: 'normal' }, assertCurrent) as Promise<SendToWorkerResult>;
}
@@ -1086,6 +1141,7 @@ export function createOrcaTeamService(deps: OrcaTeamServiceDeps): OrcaTeamServic
targetSessionId: string;
message: string;
mode: 'normal' | 'interrupt';
+ delivery?: 'queue' | 'steer';
}, captured?: () => Promise<void>): Promise<SendToWorkerResult | InterruptWorkerResult> {
const assertCurrent = captured ?? await deps.captureControlAuthority?.(params.callerLeadSessionId);
const resolved = await resolveWorkerRef(params.callerLeadSessionId, params.targetSessionId);
@@ -1103,6 +1159,7 @@ export function createOrcaTeamService(deps: OrcaTeamServiceDeps): OrcaTeamServic
resolved,
message: params.message,
mode: params.mode,
+ ...(params.delivery ? { delivery: params.delivery } : {}),
assertCurrent,
dispatchMeta: {
source: 'maker-ipc/collab',
@@ -1138,7 +1195,12 @@ export function createOrcaTeamService(deps: OrcaTeamServiceDeps): OrcaTeamServic
targetTitle: dispatchResult.targetTitle,
targetLastUserSendAt: dispatchResult.targetLastUserSendAt,
...(dispatchResult.queued === true
- ? { queuedMessageId: dispatchResult.queuedMessageId }
+ ? {
+ queuedMessageId: dispatchResult.queuedMessageId,
+ ...(dispatchResult.steerFallbackReason
+ ? { steerFallbackReason: dispatchResult.steerFallbackReason }
+ : {}),
+ }
: {}),
};
}
@@ -1322,22 +1384,47 @@ export function createOrcaTeamService(deps: OrcaTeamServiceDeps): OrcaTeamServic
return 'user';
}
+ /**
+ * 队列目标:给了 workerRef 就是该 worker 的队列;省略时是调用方自己的队列
+ * (Lead 忙时 Worker 回报排在这里)。自身队列只开放协同(orca)条目。
+ */
+ async function resolveQueueTarget(
+ callerLeadSessionId: string,
+ workerRef: string | undefined,
+ ): Promise<
+ | { ok: true; sessionId: string; worker: OrcaWorkerRecordSnapshot | null }
+ | { ok: false; errorCode: 'WORKER_NOT_FOUND' | 'INTERNAL'; message: string }
+ > {
+ if (workerRef === undefined) return { ok: true, sessionId: callerLeadSessionId, worker: null };
+ const found = await resolveWorkerRef(callerLeadSessionId, workerRef);
+ if (found.ok) return { ok: true, sessionId: found.worker.sessionId, worker: found.worker };
+ return found.errorCode === 'NOT_FOUND'
+ ? { ok: false, errorCode: 'WORKER_NOT_FOUND', message: `worker ${workerRef} not found` }
+ : { ok: false, errorCode: 'INTERNAL', message: found.message };
+ }
+
+ function authorizeOrcaQueueItem(
+ entry: AgentInputQueuedMessage,
+ queuedMessageId: string,
+ ownQueue: boolean,
+ ): { ok: true } | { ok: false; message: string } {
+ if (entry.origin?.kind === 'orca') return { ok: true };
+ return {
+ ok: false,
+ message: ownQueue
+ ? `queued message ${queuedMessageId} is not a collaboration message; user/scheduler queued messages cannot be changed`
+ : `queued message ${queuedMessageId} was not sent by the lead; user/scheduler queued messages cannot be modified`,
+ };
+ }
+
async function listWorkerQueuedMessages(params: {
callerLeadSessionId: string;
- workerRef: string;
+ workerRef?: string;
}): Promise<ListWorkerQueuedMessagesResult> {
- const found = await resolveWorkerRef(params.callerLeadSessionId, params.workerRef);
- if (!found.ok) {
- return found.errorCode === 'NOT_FOUND'
- ? {
- ok: false,
- errorCode: 'WORKER_NOT_FOUND',
- message: `worker ${params.workerRef} not found`,
- }
- : { ok: false, errorCode: 'INTERNAL', message: found.message };
- }
- const snapshot = await deps.getSessionQueueSnapshot(found.worker.sessionId);
- const messages =
+ const target = await resolveQueueTarget(params.callerLeadSessionId, params.workerRef);
+ if (!target.ok) return target;
+ const snapshot = await deps.getSessionQueueSnapshot(target.sessionId);
+ const messages = (
snapshot.inspectionMessages ??
snapshot.pendingQueue.map((item, index): WorkerQueuedMessageSnapshot => {
const source = queuedMessageSource(item);
@@ -1352,12 +1439,16 @@ export function createOrcaTeamService(deps: OrcaTeamServiceDeps): OrcaTeamServic
content,
consuming: snapshot.consumingClientIds.includes(item.clientId),
};
- });
+ })
+ ).map((entry) =>
+ // 自身队列里的协同条目来自对端(Lead 收到的是 Worker 回报),不是 lead 自己发的。
+ target.worker === null && entry.source === 'lead' ? { ...entry, source: 'worker' as const } : entry,
+ );
return {
ok: true,
- workerId: found.worker.id,
- workerSessionId: found.worker.sessionId,
- status: found.worker.status,
+ workerId: target.worker?.id ?? null,
+ workerSessionId: target.sessionId,
+ status: target.worker?.status ?? 'lead',
isWorking: snapshot.isWorking,
willQueue: snapshot.willQueue,
queuePaused: snapshot.queuePaused,
@@ -1365,6 +1456,63 @@ export function createOrcaTeamService(deps: OrcaTeamServiceDeps): OrcaTeamServic
};
}
+ async function steerWorkerQueuedMessage(params: {
+ callerLeadSessionId: string;
+ workerRef?: string;
+ queuedMessageId: string;
+ }): Promise<SteerWorkerQueuedMessageResult> {
+ const assertCurrent = await deps.captureControlAuthority?.(params.callerLeadSessionId);
+ const target = await resolveQueueTarget(params.callerLeadSessionId, params.workerRef);
+ if (!target.ok) return target;
+ const ownQueue = target.worker === null;
+ const controlled = await queueControl.steer({
+ beforeMutation: assertCurrent,
+ sessionId: target.sessionId,
+ queuedMessageId: params.queuedMessageId,
+ authorize: (entry) => authorizeOrcaQueueItem(entry, params.queuedMessageId, ownQueue),
+ });
+ if (!controlled.ok) return mapWorkerQueueControlFailure(controlled, ownQueue);
+ deps.log.info('orca queued message steer requested', {
+ targetSessionId: target.sessionId,
+ ownQueue,
+ queuedMessageId: params.queuedMessageId,
+ delivery: controlled.delivery,
+ });
+ return {
+ ok: true,
+ workerId: target.worker?.id ?? null,
+ queuedMessageId: params.queuedMessageId,
+ delivery: controlled.delivery,
+ ...(controlled.delivery === 'queued' ? { reason: controlled.reason } : {}),
+ };
+ }
+
+ async function moveWorkerQueuedMessage(params: {
+ callerLeadSessionId: string;
+ workerRef?: string;
+ queuedMessageId: string;
+ position: number;
+ }): Promise<MoveWorkerQueuedMessageResult> {
+ const assertCurrent = await deps.captureControlAuthority?.(params.callerLeadSessionId);
+ const target = await resolveQueueTarget(params.callerLeadSessionId, params.workerRef);
+ if (!target.ok) return target;
+ const ownQueue = target.worker === null;
+ const controlled = await queueControl.move({
+ beforeMutation: assertCurrent,
+ sessionId: target.sessionId,
+ queuedMessageId: params.queuedMessageId,
+ position: params.position,
+ authorize: (entry) => authorizeOrcaQueueItem(entry, params.queuedMessageId, ownQueue),
+ });
+ if (!controlled.ok) return mapWorkerQueueControlFailure(controlled, ownQueue);
+ return {
+ ok: true,
+ workerId: target.worker?.id ?? null,
+ queuedMessageId: params.queuedMessageId,
+ position: controlled.position,
+ };
+ }
+
async function updateWorkerQueuedMessage(params: {
callerLeadSessionId: string;
workerRef: string;
@@ -1523,16 +1671,19 @@ export function createOrcaTeamService(deps: OrcaTeamServiceDeps): OrcaTeamServic
};
}
- function mapWorkerQueueControlFailure(failure: {
- ok: false;
- errorCode: string;
- message: string;
- }): WorkerQueuedMessageControlResult {
+ function mapWorkerQueueControlFailure(
+ failure: {
+ ok: false;
+ errorCode: string;
+ message: string;
+ },
+ ownQueue = false,
+ ): WorkerQueuedMessageFailure {
return {
ok: false,
errorCode:
failure.errorCode === 'NOT_AUTHORIZED'
- ? 'NOT_LEAD_MESSAGE'
+ ? ownQueue ? 'NOT_ORCA_MESSAGE' : 'NOT_LEAD_MESSAGE'
: (failure.errorCode as WorkerQueuedMessageFailureCode),
message: failure.message,
};
@@ -1582,6 +1733,8 @@ export function createOrcaTeamService(deps: OrcaTeamServiceDeps): OrcaTeamServic
updateWorkerQueuedMessage,
cancelWorkerQueuedMessage,
mergeWorkerQueuedMessages,
+ steerWorkerQueuedMessage,
+ moveWorkerQueuedMessage,
captureWorkerText(sessionId, text, opts) {
const state = autoBridge.get(sessionId);
if (!state || text.length === 0) return;
diff --git a/apps/desktop/src/main/maker-ipc/register.ts b/apps/desktop/src/main/maker-ipc/register.ts
index fac25d695e..70ffa9c4fc 100644
--- a/apps/desktop/src/main/maker-ipc/register.ts
+++ b/apps/desktop/src/main/maker-ipc/register.ts
@@ -249,6 +249,11 @@ import {
createSessionControlService,
sessionQueueOriginForDispatcher,
} from './sessionControlService.js';
+import {
+ createQueueReorderAdapter,
+ type SessionQueueMoveResult,
+ type SessionQueueSteerResult,
+} from './sessionQueueControl.js';
import {
createSessionBindingLifecycle,
finalizeSessionClose,
@@ -816,9 +821,11 @@ import {
type InterruptWorkerResult,
type ListWorkerQueuedMessagesResult,
type MergeWorkerQueuedMessagesResult,
+ type MoveWorkerQueuedMessageResult,
type OrcaTeamService,
type OrcaWorkerEffort,
type SendToWorkerResult,
+ type SteerWorkerQueuedMessageResult,
type WorkerQueuedMessageControlResult,
type WorkerTerminalTurnCapture,
} from './orcaTeamService.js';
@@ -1904,6 +1911,21 @@ interface OrcaCollabService {
message: string;
}
>;
+ steerSessionQueuedMessage: (params: {
+ callerSessionId: string;
+ targetSessionId: string;
+ queuedMessageId: string;
+ }) => Promise<
+ SessionQueueSteerResult | { ok: false; errorCode: 'NOT_FOUND' | 'HOST_NOT_READY' | 'INTERNAL'; message: string }
+ >;
+ moveSessionQueuedMessage: (params: {
+ callerSessionId: string;
+ targetSessionId: string;
+ queuedMessageId: string;
+ position: number;
+ }) => Promise<
+ SessionQueueMoveResult | { ok: false; errorCode: 'NOT_FOUND' | 'HOST_NOT_READY' | 'INTERNAL'; message: string }
+ >;
steerSession: (params: {
callerSessionId: string;
targetSessionId: string;
@@ -2130,6 +2152,7 @@ interface OrcaCollabService {
callerLeadSessionId: string;
targetSessionId: string;
message: string;
+ delivery?: 'queue' | 'steer';
}) => Promise<SendToWorkerResult>;
interruptWorker: (params: {
callerLeadSessionId: string;
@@ -2139,8 +2162,19 @@ interface OrcaCollabService {
// 排队消息控制:只作用于 lead 自己发出的 orca 排队条目,归属校验与 send/idle/archive 同一套 resolveWorkerRef。
listWorkerQueuedMessages: (params: {
callerLeadSessionId: string;
- workerRef: string;
+ workerRef?: string;
}) => Promise<ListWorkerQueuedMessagesResult>;
+ steerWorkerQueuedMessage: (params: {
+ callerLeadSessionId: string;
+ workerRef?: string;
+ queuedMessageId: string;
+ }) => Promise<SteerWorkerQueuedMessageResult>;
+ moveWorkerQueuedMessage: (params: {
+ callerLeadSessionId: string;
+ workerRef?: string;
+ queuedMessageId: string;
+ position: number;
+ }) => Promise<MoveWorkerQueuedMessageResult>;
updateWorkerQueuedMessage: (params: {
callerLeadSessionId: string;
workerRef: string;
@@ -11650,6 +11684,8 @@ export function registerMakerIpc(maker: Maker, options: RegisterMakerIpcOptions)
getSessionRowSnapshot,
getLiveSession: (sessionId) => maker.getSession(sessionId),
shouldQueueNewTurn: (sessionId): boolean => inputCoordinator.shouldQueueNewTurn(sessionId),
+ steerControlInput: (sessionId, item, expectedTurn) =>
+ inputCoordinator.steerControlInput(sessionId, { item }, expectedTurn),
hasSendToSessionLock: (sessionId) => sendToSessionLocks.has(sessionId),
withSendToSessionLock,
prepareUnhealthySession: (sessionId) =>
@@ -11715,6 +11751,14 @@ export function registerMakerIpc(maker: Maker, options: RegisterMakerIpcOptions)
};
dispatchInterAgentMessageHolder = dispatchOrEnqueueOrcaInterAgentMessage;
+ // Agent 选择的排队行插话 / 排序(cindy_orca 与 cindy_helper 共用)。
+ const { steerStoredControlMessage, moveStoredControlMessage } = createQueueReorderAdapter({
+ getLiveSession: (sessionId) => maker.getSession(sessionId),
+ hasSendToSessionLock: (sessionId) => sendToSessionLocks.has(sessionId),
+ // inputCoordinator 在本函数更后面才声明,只能在调用时取用。
+ getCoordinator: () => inputCoordinator,
+ });
+
ipcMain.handle(
MAKER_INVOKE.SESSION_ENABLE_ORCA,
async (_e, leadSessionId: unknown, opts: unknown) => {
@@ -12175,6 +12219,7 @@ export function registerMakerIpc(maker: Maker, options: RegisterMakerIpcOptions)
targetSessionId,
message,
workerId,
+ delivery,
dispatchMeta,
onAccepted,
onAcceptedRollback,
@@ -12186,6 +12231,7 @@ export function registerMakerIpc(maker: Maker, options: RegisterMakerIpcOptions)
source: 'lead',
senderLabel: 'Lead',
workerId,
+ ...(delivery ? { delivery } : {}),
meta: dispatchMeta,
onAccepted,
onAcceptedRollback,
@@ -12201,6 +12247,7 @@ export function registerMakerIpc(maker: Maker, options: RegisterMakerIpcOptions)
dispatchOutcome: result.dispatchOutcome,
targetTitle: result.targetTitle ?? null,
targetLastUserSendAt: result.targetLastUserSendAt ?? null,
+ ...(result.steerFallbackReason ? { steerFallbackReason: result.steerFallbackReason } : {}),
};
},
reserveWorkerMessage: async ({
@@ -12305,6 +12352,8 @@ export function registerMakerIpc(maker: Maker, options: RegisterMakerIpcOptions)
&& inputCoordinator.replaceQueuedMessage(sessionId, clientId, next),
mergeQueuedMessages: (sessionId, clientIds, buildReplacement) =>
inputCoordinator.mergeQueuedMessagesAtomically(sessionId, clientIds, buildReplacement).merged,
+ steerStoredQueuedMessage: steerStoredControlMessage,
+ moveQueuedMessage: moveStoredControlMessage,
sendAutoBridgeToLead: async (leadSessionId, message, workerId) => {
const result = await dispatchInterAgentMessage({
targetSessionId: leadSessionId,
@@ -13635,6 +13684,8 @@ export function registerMakerIpc(maker: Maker, options: RegisterMakerIpcOptions)
inputCoordinator.remove(sessionId, clientId);
return !inputCoordinator.hasQueuedItemWhere(sessionId, (item) => item.clientId === clientId);
},
+ steerStoredQueuedMessage: steerStoredControlMessage,
+ moveQueuedMessage: moveStoredControlMessage,
createId,
});
@@ -13685,6 +13736,8 @@ export function registerMakerIpc(maker: Maker, options: RegisterMakerIpcOptions)
},
updateSessionQueuedMessage: (params) => sessionControlService.updateQueuedMessage(params),
cancelSessionQueuedMessage: (params) => sessionControlService.cancelQueuedMessage(params),
+ steerSessionQueuedMessage: (params) => sessionControlService.steerQueuedMessage(params),
+ moveSessionQueuedMessage: (params) => sessionControlService.moveQueuedMessage(params),
steerSession: (params) => sessionControlService.steerSession(params),
stopSessionTurn: (params) => sessionControlService.stopSessionTurn(params),
getSessionRuntime: (params) => sessionControlService.getSessionRuntime(params),
@@ -13702,6 +13755,8 @@ export function registerMakerIpc(maker: Maker, options: RegisterMakerIpcOptions)
updateWorkerQueuedMessage: (params) => orcaTeamService.updateWorkerQueuedMessage(params),
cancelWorkerQueuedMessage: (params) => orcaTeamService.cancelWorkerQueuedMessage(params),
mergeWorkerQueuedMessages: (params) => orcaTeamService.mergeWorkerQueuedMessages(params),
+ steerWorkerQueuedMessage: (params) => orcaTeamService.steerWorkerQueuedMessage(params),
+ moveWorkerQueuedMessage: (params) => orcaTeamService.moveWorkerQueuedMessage(params),
startTeam: ({ leadSessionId, workerPermissionMode }) => startOrcaTeamForCaller(leadSessionId, workerPermissionMode),
createWorker: async (params) => {
try {
@@ -15735,6 +15790,11 @@ export function registerMakerIpc(maker: Maker, options: RegisterMakerIpcOptions)
// 可见行),理由与踩过的坑记在 helper 的注释里。
supersedeRetriedUserTurn,
getLastAssistantTranscriptUuid,
+ // 插话并入正在运行的 turn,不开启新 turn:排队时登记的「新 turn 接管」回调不再适用,
+ // 只释放登记(不运行),否则会给已在跑的 worker 另建一份 running/auto-bridge 身份。
+ onSteerAccepted: (_sessionId, item) => {
+ orcaInterAgentDispatcher.discardQueuedOrcaInterAgentAcceptedCallback(item.clientId);
+ },
onAcceptedQueuedMessage: async (sessionId, item, restoredFromSnapshot): Promise<void> => {
// 已派发 → 该项不会再走 discard,释放 scheduler 的 discard 监听防泄漏。
schedulerQueuedPromptDiscardWatchers.delete(item.clientId);
diff --git a/apps/desktop/src/main/maker-ipc/sessionControlService.ts b/apps/desktop/src/main/maker-ipc/sessionControlService.ts
index ef90b2106f..5e1cbf0489 100644
--- a/apps/desktop/src/main/maker-ipc/sessionControlService.ts
+++ b/apps/desktop/src/main/maker-ipc/sessionControlService.ts
@@ -15,7 +15,12 @@ import {
updateQueuedMessageText,
type AgentInputQueuedMessage,
} from '../../shared/agentInputQueue.js';
-import { createSessionQueueControlService } from './sessionQueueControl.js';
+import {
+ createSessionQueueControlService,
+ type QueuedSteerOutcome,
+ type SessionQueueMoveResult,
+ type SessionQueueSteerResult,
+} from './sessionQueueControl.js';
type Failure<Code extends string> = { ok: false; errorCode: Code; message: string };
@@ -112,6 +117,8 @@ export interface SessionControlServiceDeps {
}>;
replaceQueuedMessage(sessionId: string, clientId: string, next: AgentInputQueuedMessage, expected?: AgentInputQueuedMessage): boolean;
removeQueuedMessage(sessionId: string, clientId: string, expected?: AgentInputQueuedMessage): boolean;
+ steerStoredQueuedMessage(sessionId: string, clientId: string): Promise<QueuedSteerOutcome>;
+ moveQueuedMessage(sessionId: string, clientId: string, position: number): number | null | 'locked';
createId(): string;
}
@@ -120,6 +127,8 @@ export function createSessionControlService(deps: SessionControlServiceDeps) {
getSnapshot: deps.getQueueSnapshot,
replaceQueuedMessage: deps.replaceQueuedMessage,
removeQueuedMessage: deps.removeQueuedMessage,
+ steerQueuedMessage: deps.steerStoredQueuedMessage,
+ moveQueuedMessage: deps.moveQueuedMessage,
});
async function ensureTarget(sessionId: string): Promise<Failure<'NOT_FOUND'> | null> {
@@ -163,6 +172,38 @@ export function createSessionControlService(deps: SessionControlServiceDeps) {
});
},
+ async steerQueuedMessage(params: {
+ callerSessionId: string;
+ targetSessionId: string;
+ queuedMessageId: string;
+ }): Promise<SessionQueueSteerResult | Failure<'NOT_FOUND'>> {
+ const missing = await ensureTarget(params.targetSessionId);
+ if (missing) return missing;
+ return queueControl.steer({
+ sessionId: params.targetSessionId,
+ queuedMessageId: params.queuedMessageId,
+ authorize: (item) =>
+ authorizeSessionQueueReorder(item, params.callerSessionId, params.targetSessionId),
+ });
+ },
+
+ async moveQueuedMessage(params: {
+ callerSessionId: string;
+ targetSessionId: string;
+ queuedMessageId: string;
+ position: number;
+ }): Promise<SessionQueueMoveResult | Failure<'NOT_FOUND'>> {
+ const missing = await ensureTarget(params.targetSessionId);
+ if (missing) return missing;
+ return queueControl.move({
+ sessionId: params.targetSessionId,
+ queuedMessageId: params.queuedMessageId,
+ position: params.position,
+ authorize: (item) =>
+ authorizeSessionQueueReorder(item, params.callerSessionId, params.targetSessionId),
+ });
+ },
+
async steerSession(params: {
callerSessionId: string;
targetSessionId: string;
@@ -305,6 +346,30 @@ export function authorizeSessionQueueItem(
: { ok: false, message: 'queued message was not sent by the current session' };
}
+/**
+ * 插话 / 排序不改正文:除了自己投递的消息,任务还可以处理自己队列里由其它任务或协同
+ * 成员发来的机器消息。用户手打、伙伴委派、插件与定时任务的条目有各自的接受簿记,不开放。
+ */
+export function authorizeSessionQueueReorder(
+ item: AgentInputQueuedMessage,
+ callerSessionId: string,
+ targetSessionId: string,
+): { ok: true } | { ok: false; message: string } {
+ const plainMachineMessage =
+ !item.sourcePlugin &&
+ (item.origin?.kind === 'orca' ||
+ (item.origin?.kind === 'session' && !item.origin.senderBotId));
+ const owned =
+ authorizeSessionQueueItem(item, callerSessionId).ok || callerSessionId === targetSessionId;
+ return plainMachineMessage && owned
+ ? { ok: true }
+ : {
+ ok: false,
+ message:
+ 'queued message is neither sent by the current session nor a task/collaboration message in its own queue',
+ };
+}
+
export function rebuildSessionQueueItem(
item: AgentInputQueuedMessage,
message: string,
diff --git a/apps/desktop/src/main/maker-ipc/sessionQueueControl.ts b/apps/desktop/src/main/maker-ipc/sessionQueueControl.ts
index 2a3427a271..3a4278f604 100644
--- a/apps/desktop/src/main/maker-ipc/sessionQueueControl.ts
+++ b/apps/desktop/src/main/maker-ipc/sessionQueueControl.ts
@@ -1,4 +1,5 @@
import type { AgentInputQueuedMessage } from '../../shared/agentInputQueue.js';
+import type { ControlSteerOutcome } from './agent-input-coordinator.js';
export type SessionQueueControlFailureCode =
'QUEUED_MESSAGE_NOT_FOUND' | 'MESSAGE_CONSUMING' | 'NOT_AUTHORIZED' | 'INVALID_ARGS';
@@ -16,10 +17,35 @@ export interface SessionQueueControlSnapshot {
consumingClientIds: string[];
}
+/** 排队消息转插话没插成时的原因;消息仍留在队列里。 */
+export type QueuedSteerFallbackReason =
+ 'NO_ACTIVE_TURN' | 'STEER_UNSUPPORTED' | 'INPUT_BOUNDARY_BUSY' | 'STEER_UNCERTAIN';
+
+/** Host-side outcome; `gone` means the row left the queue without being steered. */
+export type QueuedSteerOutcome =
+ | { kind: 'steered' }
+ | { kind: 'queued'; reason: QueuedSteerFallbackReason }
+ | { kind: 'gone' };
+
+export type SessionQueueSteerResult =
+ | { ok: true; queuedMessageId: string; delivery: 'steered' }
+ | { ok: true; queuedMessageId: string; delivery: 'queued'; reason: QueuedSteerFallbackReason }
+ | Exclude<SessionQueueControlResult, { ok: true }>;
+
+export type SessionQueueMoveResult =
+ | { ok: true; queuedMessageId: string; position: number }
+ | Exclude<SessionQueueControlResult, { ok: true }>;
+
export interface SessionQueueControlDeps {
getSnapshot(sessionId: string): Promise<SessionQueueControlSnapshot>;
replaceQueuedMessage(sessionId: string, clientId: string, next: AgentInputQueuedMessage, expected?: AgentInputQueuedMessage): boolean;
removeQueuedMessage(sessionId: string, clientId: string, expected?: AgentInputQueuedMessage): boolean;
+ steerQueuedMessage(sessionId: string, clientId: string): Promise<QueuedSteerOutcome>;
+ /**
+ * Moves among waiting rows; returns the final waiting-row index, null when it is gone,
+ * or 'locked' while the user is editing it.
+ */
+ moveQueuedMessage(sessionId: string, clientId: string, position: number): number | null | 'locked';
}
export type SessionQueueAuthorization = (
@@ -111,6 +137,46 @@ export function createSessionQueueControlService(deps: SessionQueueControlDeps)
}
return { ok: true, queuedMessageId: params.queuedMessageId };
},
+
+ /** 转插话不改正文与身份;没插成时消息原位保留并说明原因。 */
+ async steer(params: BaseControlParams): Promise<SessionQueueSteerResult> {
+ const resolved = await resolve(params);
+ if (!resolved.ok) return resolved;
+ await params.beforeMutation?.();
+ const outcome = await deps.steerQueuedMessage(params.sessionId, params.queuedMessageId);
+ if (outcome.kind === 'gone') return classifyLostRace(params.sessionId, params.queuedMessageId);
+ return outcome.kind === 'steered'
+ ? { ok: true, queuedMessageId: params.queuedMessageId, delivery: 'steered' }
+ : {
+ ok: true,
+ queuedMessageId: params.queuedMessageId,
+ delivery: 'queued',
+ reason: outcome.reason,
+ };
+ },
+
+ async move(params: BaseControlParams & { position: number }): Promise<SessionQueueMoveResult> {
+ if (!Number.isInteger(params.position) || params.position < 0) {
+ return { ok: false, errorCode: 'INVALID_ARGS', message: 'position must be a non-negative integer' };
+ }
+ const resolved = await resolve(params);
+ if (!resolved.ok) return resolved;
+ await params.beforeMutation?.();
+ const position = deps.moveQueuedMessage(
+ params.sessionId,
+ params.queuedMessageId,
+ params.position,
+ );
+ if (position === null) return classifyLostRace(params.sessionId, params.queuedMessageId);
+ if (position === 'locked') {
+ return {
+ ok: false,
+ errorCode: 'MESSAGE_CONSUMING',
+ message: `queued message ${params.queuedMessageId} is being edited and cannot be moved now`,
+ };
+ }
+ return { ok: true, queuedMessageId: params.queuedMessageId, position };
+ },
};
}
@@ -131,3 +197,89 @@ function consumingFailure(
message: `queued message ${queuedMessageId} is being delivered and can no longer be modified`,
};
}
+
+/** createQueueReorderAdapter 只需要 coordinator 的这几项能力。 */
+export interface QueueReorderCoordinator {
+ steerControlInput(
+ sessionId: string,
+ target: { queuedClientId: string },
+ expectedTurn: { session: object; turnGeneration: number },
+ ): Promise<ControlSteerOutcome>;
+ isQueuePaused(sessionId: string): boolean;
+ getQueueControlSnapshot(sessionId: string): { pendingQueue: readonly AgentInputQueuedMessage[] };
+ getProjection(sessionId: string): {
+ queueEditLocks: readonly string[];
+ steeringQueueClientIds: readonly string[];
+ };
+ move(sessionId: string, clientId: string, targetIndex: number): unknown;
+}
+
+/**
+ * Host adapter shared by cindy_orca and cindy_helper. Capability, remote-host and turn
+ * identity are decided here; queue guards, the pre-dispatch re-check and acceptance
+ * bookkeeping stay in the coordinator.
+ */
+export function createQueueReorderAdapter(deps: {
+ getLiveSession(sessionId: string):
+ | {
+ isTurnRunning(): boolean;
+ getTurnGeneration(): number;
+ capabilities: { sameTurnSteer: { supported: boolean } };
+ remoteHostId?: string | null;
+ }
+ | null
+ | undefined;
+ hasSendToSessionLock(sessionId: string): boolean;
+ getCoordinator(): QueueReorderCoordinator;
+}): {
+ steerStoredControlMessage(sessionId: string, clientId: string): Promise<QueuedSteerOutcome>;
+ moveStoredControlMessage(sessionId: string, clientId: string, position: number): number | null | 'locked';
+} {
+ const waitingIndex = (sessionId: string, clientId: string): number =>
+ deps
+ .getCoordinator()
+ .getQueueControlSnapshot(sessionId)
+ .pendingQueue.findIndex((item) => item.clientId === clientId);
+ return {
+ async steerStoredControlMessage(sessionId, clientId) {
+ const live = deps.getLiveSession(sessionId);
+ if (!live?.isTurnRunning()) return { kind: 'queued', reason: 'NO_ACTIVE_TURN' };
+ if (!live.capabilities.sameTurnSteer.supported || live.remoteHostId) {
+ return { kind: 'queued', reason: 'STEER_UNSUPPORTED' };
+ }
+ if (deps.hasSendToSessionLock(sessionId)) return { kind: 'queued', reason: 'INPUT_BOUNDARY_BUSY' };
+ const coordinator = deps.getCoordinator();
+ const outcome = await coordinator.steerControlInput(
+ sessionId,
+ { queuedClientId: clientId },
+ { session: live, turnGeneration: live.getTurnGeneration() },
+ );
+ if (outcome === 'steered') return { kind: 'steered' };
+ // rejected = screening discarded the row; any other outcome without the row is a lost race.
+ if (outcome === 'rejected' || waitingIndex(sessionId, clientId) < 0) return { kind: 'gone' };
+ if (outcome === 'queued' && coordinator.isQueuePaused(sessionId)) {
+ return { kind: 'queued', reason: 'STEER_UNCERTAIN' };
+ }
+ return {
+ kind: 'queued',
+ reason: deps.getLiveSession(sessionId)?.isTurnRunning() ? 'INPUT_BOUNDARY_BUSY' : 'NO_ACTIVE_TURN',
+ };
+ },
+ moveStoredControlMessage(sessionId, clientId, position) {
+ const from = waitingIndex(sessionId, clientId);
+ if (from < 0) return null;
+ const coordinator = deps.getCoordinator();
+ const projection = coordinator.getProjection(sessionId);
+ // A row that started steering is being consumed; move() would silently refuse it.
+ if (projection.steeringQueueClientIds.includes(clientId)) return null;
+ // Same rule as the queue UI: a row the user is editing keeps its place.
+ if (projection.queueEditLocks.includes(clientId)) return 'locked';
+ const waitingCount = coordinator.getQueueControlSnapshot(sessionId).pendingQueue.length;
+ const to = Math.min(position, waitingCount - 1);
+ // coordinator.move 的 targetIndex 是「插到原队列第 n 条之前」。
+ coordinator.move(sessionId, clientId, to > from ? to + 1 : to);
+ const index = waitingIndex(sessionId, clientId);
+ return index < 0 ? null : index;
+ },
+ };
+}
diff --git a/apps/desktop/src/main/mcp-integrations/mcp-providers.ts b/apps/desktop/src/main/mcp-integrations/mcp-providers.ts
index 9e1ad7f309..2dfb677db0 100644
--- a/apps/desktop/src/main/mcp-integrations/mcp-providers.ts
+++ b/apps/desktop/src/main/mcp-integrations/mcp-providers.ts
@@ -602,6 +602,8 @@ export function createDesktopMcpProviders(deps: DesktopMcpProvidersDeps): LiziMc
sessionControl: {
updateQueuedMessage: wrap((service, params) => service.updateSessionQueuedMessage(params)),
cancelQueuedMessage: wrap((service, params) => service.cancelSessionQueuedMessage(params)),
+ steerQueuedMessage: wrap((service, params) => service.steerSessionQueuedMessage(params)),
+ moveQueuedMessage: wrap((service, params) => service.moveSessionQueuedMessage(params)),
steerSession: wrap((service, params) => service.steerSession(params)),
stopSessionTurn: wrap((service, params) => service.stopSessionTurn(params)),
getSessionRuntime: wrap((service, params) => service.getSessionRuntime(params)),
@@ -953,6 +955,8 @@ export function createDesktopMcpProviders(deps: DesktopMcpProvidersDeps): LiziMc
updateWorkerQueuedMessage: wrap((s, params) => s.updateWorkerQueuedMessage(params)),
cancelWorkerQueuedMessage: wrap((s, params) => s.cancelWorkerQueuedMessage(params)),
mergeWorkerQueuedMessages: wrap((s, params) => s.mergeWorkerQueuedMessages(params)),
+ steerWorkerQueuedMessage: wrap((s, params) => s.steerWorkerQueuedMessage(params)),
+ moveWorkerQueuedMessage: wrap((s, params) => s.moveWorkerQueuedMessage(params)),
idleWorker: wrap((s, params) => s.idleWorker(params)),
endTeam: wrap((s, params) => s.endTeam(params)),
archiveWorker: wrap((s, params) => s.archiveWorker(params)),
diff --git a/apps/desktop/src/renderer/__tests__/pendingQueueRowPresentation.test.ts b/apps/desktop/src/renderer/__tests__/pendingQueueRowPresentation.test.ts
index b8b6cd08b8..52973ad11f 100644
--- a/apps/desktop/src/renderer/__tests__/pendingQueueRowPresentation.test.ts
+++ b/apps/desktop/src/renderer/__tests__/pendingQueueRowPresentation.test.ts
@@ -106,7 +106,7 @@ describe('getPendingQueueRowPresentation', () => {
).toBe('{"text":"x"}');
});
- it('uses orca sender and display text while disabling edit and steer actions', () => {
+ it('uses orca sender and display text, keeping steer but disabling edit', () => {
const presentation = getPendingQueueRowPresentation(
queuedMessage({
text: '[orca protocol text]',
@@ -129,13 +129,13 @@ describe('getPendingQueueRowPresentation', () => {
isSyntheticTrigger: false,
syntheticKind: null,
canEdit: false,
- canSteer: false,
+ canSteer: true,
});
});
it('marks scheduler heartbeat rows with schedule name, hides silent-run suffix, locks edit/steer', () => {
// 撞忙排队的心跳:text 带隐藏静默协议后缀,展示用 persistedContent(原始 prompt);
- // 机器生成 → 保留重排/删除,禁编辑/steer(与 orca 同规)。
+ // 机器生成 → 保留重排/删除,禁编辑/steer。
const presentation = getPendingQueueRowPresentation(
queuedMessage({
text: 'PR #971 heartbeat prompt\n\n---\n[Silent scheduled run]\n...',
diff --git a/apps/desktop/src/renderer/components/new-chat/pendingQueueRowPresentation.ts b/apps/desktop/src/renderer/components/new-chat/pendingQueueRowPresentation.ts
index 82352af21a..b831dd031a 100644
--- a/apps/desktop/src/renderer/components/new-chat/pendingQueueRowPresentation.ts
+++ b/apps/desktop/src/renderer/components/new-chat/pendingQueueRowPresentation.ts
@@ -11,7 +11,7 @@ export interface PendingQueueRowPresentation {
isOrca: boolean;
/**
* scheduler 撞忙排队的心跳消息(origin.kind === 'scheduler'):机器生成,
- * 与 orca 同样保留重排/删除、禁止编辑/steer;行首显示任务名徽标,让用户
+ * 保留重排/删除、禁止编辑/steer;行首显示任务名徽标,让用户
* 一眼看出"这是排队等待的自动化任务"。
*/
isScheduler: boolean;
@@ -50,8 +50,8 @@ export interface PendingQueueRowPresentation {
/**
* Resolves row-level presentation and permissions for the pending queue.
- * Orca messages are generated by another agent, so they keep reorder/remove
- * affordances but cannot be edited or steered like a local user draft.
+ * Orca messages are generated by another agent, so they keep reorder/remove/steer
+ * affordances but cannot be edited like a local user draft.
* Scheduler heartbeat prompts and messages sent by another session through a
* tool follow the same machine-generated rules; scheduler
* display text uses persistedContent (the raw schedule prompt) so the hidden
@@ -98,7 +98,8 @@ export function getPendingQueueRowPresentation(entry: QueuedMessage): PendingQue
? stripChatQuoteMarkerLines(entry.text)
: entry.text,
canEdit: !isPendingEnqueue && !isMachineGenerated && !isSyntheticTrigger,
- canSteer: !isPendingEnqueue && !isMachineGenerated && !isSyntheticTrigger,
+ // 协同消息可以转为插话:插话不改正文与来源,主进程在接受后结清协同回报。
+ canSteer: !isPendingEnqueue && (isOrca || !isMachineGenerated) && !isSyntheticTrigger,
isSyntheticTrigger,
syntheticKind: isSyntheticTrigger ? (isContinueTrigger ? 'continue' : 'generic') : null,
};
diff --git a/apps/mobile/src/i18n/locales/en/message.json b/apps/mobile/src/i18n/locales/en/message.json
index ff96d16f54..0e755f7ea2 100644
--- a/apps/mobile/src/i18n/locales/en/message.json
+++ b/apps/mobile/src/i18n/locales/en/message.json
@@ -297,7 +297,7 @@
"steering": "Sending interjection",
"orcaTitle": "Collaboration queue {{index}}",
"title": "Queue {{index}}",
- "orcaEditDisabled": "Collaboration messages can't be edited or sent as interjections.",
+ "orcaEditDisabled": "Collaboration messages can't be edited.",
"busy": "Queue changes are syncing. Try again when syncing finishes.",
"steeringDisabled": "The interjection is being sent to the current turn. Wait for the desktop response before changing it.",
"editLocked": "This queued message is being edited. Try again when editing finishes.",
diff --git a/apps/mobile/src/i18n/locales/ja/message.json b/apps/mobile/src/i18n/locales/ja/message.json
index f1a623f467..6d774255b7 100644
--- a/apps/mobile/src/i18n/locales/ja/message.json
+++ b/apps/mobile/src/i18n/locales/ja/message.json
@@ -297,7 +297,7 @@
"steering": "割り込み送信中",
"orcaTitle": "コラボレーションキュー {{index}}",
"title": "キュー {{index}}",
- "orcaEditDisabled": "コラボレーションメッセージは編集や割り込み送信ができません。",
+ "orcaEditDisabled": "コラボレーションメッセージは編集できません。",
"busy": "キュー操作を同期中です。完了後にもう一度操作してください。",
"steeringDisabled": "現在の turn に割り込みを送信中です。デスクトップから戻るまでお待ちください。",
"editLocked": "このキューメッセージは編集中です。完了後に操作してください。",
diff --git a/apps/mobile/src/i18n/locales/ko/message.json b/apps/mobile/src/i18n/locales/ko/message.json
index 7cd69113b8..1b0ed8334d 100644
--- a/apps/mobile/src/i18n/locales/ko/message.json
+++ b/apps/mobile/src/i18n/locales/ko/message.json
@@ -297,7 +297,7 @@
"steering": "끼어들기 전송 중",
"orcaTitle": "협업 큐 {{index}}",
"title": "큐 {{index}}",
- "orcaEditDisabled": "협업 메시지는 편집하거나 끼어들기로 보낼 수 없습니다.",
+ "orcaEditDisabled": "협업 메시지는 편집할 수 없습니다.",
"busy": "큐 작업을 동기화하는 중입니다. 완료 후 다시 조작하세요.",
"steeringDisabled": "현재 turn에 끼어들기를 보내는 중입니다. 데스크톱 응답을 기다리세요.",
"editLocked": "이 대기 메시지를 편집하는 중입니다. 완료 후 다시 조작하세요.",
diff --git a/apps/mobile/src/i18n/locales/zh-CN/message.json b/apps/mobile/src/i18n/locales/zh-CN/message.json
index 82ab1bb279..93c03cfb4c 100644
--- a/apps/mobile/src/i18n/locales/zh-CN/message.json
+++ b/apps/mobile/src/i18n/locales/zh-CN/message.json
@@ -297,7 +297,7 @@
"steering": "插话发送中",
"orcaTitle": "协同队列 {{index}}",
"title": "队列 {{index}}",
- "orcaEditDisabled": "协同消息不支持编辑或插话发送。",
+ "orcaEditDisabled": "协同消息不支持编辑。",
"busy": "队列操作同步中,完成后再继续操作。",
"steeringDisabled": "插话正在发送到当前这一轮,等电脑端回应后再操作。",
"editLocked": "这条队列消息正在编辑中,完成后再操作。",
diff --git a/apps/mobile/src/i18n/locales/zh-TW/message.json b/apps/mobile/src/i18n/locales/zh-TW/message.json
index aa54d5275e..44d84b2dbd 100644
--- a/apps/mobile/src/i18n/locales/zh-TW/message.json
+++ b/apps/mobile/src/i18n/locales/zh-TW/message.json
@@ -297,7 +297,7 @@
"steering": "插話傳送中",
"orcaTitle": "協同佇列 {{index}}",
"title": "佇列 {{index}}",
- "orcaEditDisabled": "協同訊息不支援編輯或插話傳送。",
+ "orcaEditDisabled": "協同訊息不支援編輯。",
"busy": "佇列操作同步中,完成後再繼續操作。",
"steeringDisabled": "插話正在傳送到目前這一輪,等電腦端回應後再操作。",
"editLocked": "這條佇列訊息正在編輯中,完成後再操作。",
diff --git a/docs/dev-rules/orca-team-architecture.md b/docs/dev-rules/orca-team-architecture.md
index 1d0e4b1a40..5a2f842723 100644
--- a/docs/dev-rules/orca-team-architecture.md
+++ b/docs/dev-rules/orca-team-architecture.md
@@ -104,7 +104,7 @@ PR #101 之后,Orca 的 main 侧业务由独立 service 承接,`register.ts`
### MCP 与 IPC 控制面
-`cindy_orca` 是独立 MCP server,直接顶层注册 18 个工具:15 个 team 控制工具 + 3 个只读诊断工具(后者从已下线的 `orca_bridge` 桥入,保裸名)。它与 renderer IPC 共用同一组 main 侧 service,因此 MCP 和 UI 操作必须有一致的权限、状态和回滚语义。
+`cindy_orca` 是独立 MCP server,直接顶层注册 20 个工具:17 个 team 控制工具 + 3 个只读诊断工具(后者从已下线的 `orca_bridge` 桥入,保裸名)。它与 renderer IPC 共用同一组 main 侧 service,因此 MCP 和 UI 操作必须有一致的权限、状态和回滚语义。
1. `start_team`
2. `end_team`
@@ -118,16 +118,18 @@ PR #101 之后,Orca 的 main 侧业务由独立 service 承接,`register.ts`
10. `update_queued_message`(排队消息控制)
11. `cancel_queued_message`(排队消息控制)
12. `merge_queued_messages`(原子合并连续排队消息)
-13. `idle_worker`
-14. `archive_worker`
-15. `list_available_models`
-16. `get_workspace_info`(只读诊断)
-17. `worker_status`(只读诊断)
-18. `read_worker`(只读诊断)
+13. `steer_queued_message`(排队消息转插话)
+14. `move_queued_message`(调整排队顺序)
+15. `idle_worker`
+16. `archive_worker`
+17. `list_available_models`
+18. `get_workspace_info`(只读诊断)
+19. `worker_status`(只读诊断)
+20. `read_worker`(只读诊断)
批量创建必须走一次 `create_workers` 调用,不能让 Lead 并行或连续发多个独立 `create_worker`。批量工具按输入顺序复用同一个 `OrcaLifecycleService.createWorker` 原语;首次收到 `WORKER_LIMIT_HARD_EXCEEDED` 或批次级 `HOST_NOT_READY` 后不再调用 host,剩余项稳定标为 `skipped`。返回值必须包含请求数、实际尝试数、成功数、失败数、跳过数、总未创建数、数量闸快照、代码确定生成的 `user_report`,以及逐项真实 worker/session 或失败终态,供 Lead 如实向用户收口;`success_count + failure_count + skipped_count` 必须等于 `request_count`,其中 `not_created_count = failure_count + skipped_count`。单个 `create_worker` 继续作为兼容入口,并返回相同的结构化 hard-limit 快照。
-排队消息控制 4 工具让 Lead 在消息被 worker 消费前管理自己发出的排队消息:`send_to_worker` / `create_worker`(initial_task)在 `wakeKind='queued'` 时回传 `queued_message_id`(coordinator 队列内的 clientId),Lead 可据此查看工作态和完整队列、整条改写、撤回,或原子合并连续的 Lead 消息。实现走 `OrcaTeamService.listWorkerQueuedMessages / updateWorkerQueuedMessage / cancelWorkerQueuedMessage / mergeWorkerQueuedMessages`,语义约束见「协同运行时行为契约 · 消息派发与 auto-bridge」第 6–8 条。
+排队消息控制 6 工具让 Lead 在消息被 worker 消费前管理自己发出的排队消息:`send_to_worker` / `create_worker`(initial_task)在 `wakeKind='queued'` 时回传 `queued_message_id`(coordinator 队列内的 clientId),Lead 可据此查看工作态和完整队列、整条改写、撤回、原子合并连续的 Lead 消息、转为插话或调整顺序。`get_worker_queue_status` / `steer_queued_message` / `move_queued_message` 省略 `worker_id` 时作用于调用方自己的队列(Lead 忙时 Worker 回报排在这里)。实现走 `OrcaTeamService.listWorkerQueuedMessages / updateWorkerQueuedMessage / cancelWorkerQueuedMessage / mergeWorkerQueuedMessages / steerWorkerQueuedMessage / moveWorkerQueuedMessage`,语义约束见「协同运行时行为契约 · 消息派发与 auto-bridge」第 1b、6–9 条。
诊断 3 工具是纯只读,实现走 host `apps/desktop/src/main/maker-ipc/orcaDiagnostics.ts`(读 active team + DB worker 列表 + live session 状态 + 最近 assistant 消息),**无建 team 写副作用**——这是与旧 `orca_bridge` 版本的关键差异(旧版经 `ensureWorkflowForLead` 会顺手建 team)。早期 Lead 侧 `orca_bridge`(门面 + 私有 registry/restore/auto-bridge)已整体删除:Lead→worker/team 工具面唯 `cindy_orca`(C)一套,worker→lead 唯 `orca_worker_bridge`(B,在 `packages/orca-workflow`)一套;`@cindy/orca-workflow` 包通过 B provider 与 `renderOrcaLeadSystemPrompt`/`renderOrcaWorkerSystemPrompt` 两个 render 函数继续被 host 依赖。
@@ -279,7 +281,33 @@ Git worktree,不改变供应商、模型与 Worker 创建权限偏好。
#### 消息派发与 auto-bridge
1. **忙碌目标不丢消息(状态:不变量)**<br>
- Lead/Worker 互发消息时,如果目标 session 正在跑 turn、存在 queue lock,或刚好在派发竞态里返回 `SESSION_RUNNING`,消息必须进入输入队列,而不是丢弃或直接失败。实现指针:`orcaInterAgentDispatcher.ts` 的 `dispatchOrEnqueueOrcaInterAgentMessage`,以及 `register.ts` 的 `AgentInputCoordinator` wiring。
+ Lead/Worker 互发消息时,如果目标 session 正在跑 turn、存在 queue lock,或刚好在派发竞态里返回 `SESSION_RUNNING`,默认进入输入队列。只有发送方显式选择 `delivery='steer'` 时才按 1b 尝试同轮插话;auto-bridge 等系统补报永远不传 `delivery`。已尝试插话后的拒绝不能当成普通忙碌重发。实现指针:`orcaInterAgentDispatcher.ts` 的 `dispatchOrEnqueueOrcaInterAgentMessage`,以及 `register.ts` 的 `AgentInputCoordinator` wiring。
+
+1b. **插话只由发送方显式选择,接管后不重复补报(状态:不变量)**<br>
+ 不设默认插话(2026-10-06 产品决策,#5505)。`send_to_worker` 与 `send_to_lead` 接受可选
+ `delivery: 'queue' | 'steer'`,缺省 `queue`,旧调用行为不变。`steer` 只对正在运行的本机
+ 目标尝试:目标空闲时照常直发(不带原因);运行时不支持 `sameTurnSteer` 或为 SSH 任务时
+ 照常排队并回 `STEER_UNSUPPORTED`;输入边界被占用时排队并回 `INPUT_BOUNDARY_BUSY`。
+ 插话成功回 `steered: true`;`send_to_worker` 的 `wake_kind` 仍为 Lead 提示词认可的
+ `already-active`(插话是投递给已在线的 session),不必改动 Lead system 段。来源、原始正文和
+ `delegated-continuation` 人类授权语义沿用原 Orca 消息格式,不经通用 `steer_session`。
+ coordinator(`steerControlInput`)先恢复队列,禁止越过暂停、Stop、交互锁、待确认交互、
+ 恢复、凭证切换、其它插话和未完成的派发边界;发送方既然选择插话,允许越过更早的排队行。
+ 同一组守卫在异步筛查之后、provider 投递之前复核一次;插话绝不解除用户的队列暂停。
+ session 对象与 turn generation 必须在准备后及 provider 投递前复核。
+ 插话并入对方正在运行的 turn,不开启新 turn:accepted/commit 回调接管的是「新 turn」的
+ running/auto-bridge 身份,插话成功时一律不运行(否则会给已在跑的 Worker 另建一份
+ pending,旧 terminal 收口后它再无 terminal 可结清)。Lead→Worker 插话由该 turn 原有的
+ auto-bridge 回报;Worker→Lead 的回报结清由 `send_to_lead` 自身完成。插话进一个不是
+ Lead 派发的 Worker turn 时不会自动回报,这是有意保持简单的已知边界。
+ 回执不确定而 coordinator 已将同一 `clientId` 保留在暂停队列时,dispatcher 返回 queued
+ (`STEER_UNCERTAIN`)接管结果,不再 enqueue、不解除暂停,并按普通排队登记回调(之后若
+ 被 drain 就是新 turn);bridge 立即结清回报,避免 terminal 再补一份。输入筛查拦截
+ (`rejected`)是确定拒绝,直接返回失败,不得改走排队重试;其余未投递且无保留行
+ (`not-attempted`)才回到普通直发/排队路径。
+ device-link / 手机控制场景由被控 Desktop 执行同一判断,不在控制端另外发送。
+ 实现指针:`AgentInputCoordinator.steerControlInput` 与
+ `OrcaInterAgentDispatcher.dispatchOrEnqueueOrcaInterAgentMessage`。
1a. **空闲 live 直发前必须先做换窗预检(状态:不变量)**<br>
目标空闲且已有 live session 时,dispatcher 仍走 `session.send()`,不经过 `sendToSessionInternal()`。这条直发必须先调用与用户发送相同的 `prepareUnhealthySession`:满窗或当前进程内 `needsRollover` 锁存时关闭旧原生窗口,再 `getLiveSession`。不能把 inter-agent 消息打进应被丢弃的旧窗口。prepare → 重新取 live → send 整段必须复用 `sendToSessionInternal` 的 per-session 锁;锁已被占用时先排队,不要把 in-flight prepare 当成健康状态继续直发。没有 live 后释放锁再走 `sendToSessionInternal`,避免自己把自己排队。实现指针:`orcaInterAgentDispatcher.ts` 的 live 分支,以及 `register.ts` 注入的 `prepareUnhealthySession` / `withSendToSessionLock`。
@@ -310,6 +338,22 @@ Worker turn 被 vendor 报终止型 error,但 interrupted-turn auto-resume 仍
8. **多条合并必须一次校验、一次交换、一次持久化(状态:不变量)**<br>
`merge_queued_messages` 只接受至少两个不重复、按活队列顺序连续、pending、非 consuming/steering、由当前 Lead 发出的消息。durable restore 必须先成功;之后同步重读到一次性数组交换之间不得 await。任一消息缺失、次序变化、非连续、非 Lead 或已 consuming 时,整次零修改并返回 `QUEUE_CHANGED` 与最新完整队列,不能部分合并。survivor 保留最前目标的 clientId、队列位置与 `hostAcceptedAtMs`;移除项必须逐条走 discard settlement 结清 accepted 回调;最终只 emit/持久化一次,不暴露中间快照。`update_queued_message`、`cancel_queued_message` 继续保持单条语义,不得多步模拟合并。
+9. **排队后转插话与调整顺序复用同一边界(状态:不变量)**<br>
+ `steer_queued_message` / `move_queued_message` 与 cindy_helper 的
+ `steer_session_queued_message` / `move_session_queued_message` 走共享
+ `createSessionQueueControlService` 的定位、授权与竞态分类,宿主侧统一由
+ `createQueueReorderAdapter` 判定运行态、能力与远程任务,再交给
+ `AgentInputCoordinator.steerControlInput({ queuedClientId })` 与 `move`。转插话不改正文与身份;
+ 没插成时消息原位保留并回 `NO_ACTIVE_TURN` / `STEER_UNSUPPORTED` / `INPUT_BOUNDARY_BUSY` /
+ `STEER_UNCERTAIN`。`position` 是等待中消息里的最终下标(0 = 最前,超出放最后),返回实际落点。
+ 授权:worker 队列只开放 Lead 发的 orca 条目(`NOT_LEAD_MESSAGE`);省略 `worker_id` 时只开放
+ 调用方自己队列里的 orca 条目(`NOT_ORCA_MESSAGE`)。cindy_helper 只开放调用方自己发的
+ 消息,或自己队列里来自其它任务 / 协同成员的机器消息;用户手打、伙伴委派、插件与定时任务
+ 条目有各自的接受簿记,一律不开放。用户界面同样允许把协同排队行转为插话(编辑仍禁止),
+ 插话绕过 drain,因此 coordinator 在每次 provider 接受插话后调用 `onSteerAccepted`,由宿主
+ 释放该 clientId 排队时登记的 Orca 回调(不运行,理由见 1b)。排序同样遵守编辑锁:
+ 用户正在编辑的行不可移动(`MESSAGE_CONSUMING`)。
+
#### Worker 运行态
1. **worker 终态不被失败回滚覆盖(状态:不变量)**<br>
@@ -347,7 +391,7 @@ Worker turn 被 vendor 报终止型 error,但 interrupted-turn auto-resume 仍
- Auto-resume × auto-bridge:pending/deferred 的 vendor 终态不得 bridge / 置 `error`;失败轮随后的 unclaimed `done` 同样不得收口(含用户接手 force-flush 之后、无 persist-id 的零输出尾巴);无配对 `done` 的旧 tail 不得吞掉后续更大 generation 的产品 `done`;surface/exhaust 恰好一次收口;成功续跑保持 `running` 且 pending 仍在;手动 stop 仍不 bridge。见 `autoResumeBookkeeping.test.ts` 的 `shouldSkipOrcaWorkerTerminal` 与 `interruptedContinuationContract.test.ts`。
- 空闲 live 直发:`orcaInterAgentDispatcher` 在 `session.send()` 前必须先 `prepareUnhealthySession`,再重新 `getLiveSession`;prepare 关闭旧 handle 后不得继续向旧对象 send。并发直发必须串行化到同一把 per-session 锁。
- Worker 创建权限偏好:覆盖无保存偏好时默认 `bypassPermissions`、已保存的 `auto` / `bypassPermissions` 继续优先、MCP 显式 `auto → bypassPermissions` 必须先经用户确认且取消/超时零副作用、复用 Team 时省略不重置/显式才更新、首个与后续 Worker 都读取共享创建偏好、已有 Worker 权限不反写、renderer localStorage 启动同步与 tool 写回,以及旧 device-link 被控端被阻止开启协同并提示升级。
-- MCP 工具:`cindy_orca` 18 工具(15 team + 3 只读诊断)的 role gate、ctx 缺失、worker/main 误调用、soft/hard limit、duplicate label、budget model API mode gate;`create_workers` 另覆盖默认 hard limit、配置 hard=3、部分成功、连续失败与 hard-limit 后不再调用 host;诊断工具的纯只读语义(无 active team 时返回空 workspace、不建 team);排队消息控制 4 工具的归属校验(跨 lead 拒绝)、完整 consuming 投影、非 lead 条目拒绝(`NOT_LEAD_MESSAGE`)、steering 拒绝(`MESSAGE_CONSUMING`)、撤回结清 accepted 暂存,以及合并的连续性、冲突零修改与移除回调结清;`interrupt_worker` 另覆盖队首预留、暂停态、graceful-stop 全部 outcome、auto-bridge 抑制和 done 互斥。
+- MCP 工具:`cindy_orca` 20 工具(17 team + 3 只读诊断)的 role gate、ctx 缺失、worker/main 误调用、soft/hard limit、duplicate label、budget model API mode gate;`create_workers` 另覆盖默认 hard limit、配置 hard=3、部分成功、连续失败与 hard-limit 后不再调用 host;诊断工具的纯只读语义(无 active team 时返回空 workspace、不建 team);排队消息控制 6 工具的归属校验(跨 lead 拒绝)、完整 consuming 投影、非 lead 条目拒绝(`NOT_LEAD_MESSAGE`)、自身队列非协同条目拒绝(`NOT_ORCA_MESSAGE`)、steering 拒绝(`MESSAGE_CONSUMING`)、撤回结清 accepted 暂存、合并的连续性、冲突零修改与移除回调结清,以及转插话的原因回执与排序落点;`send_to_worker` / `send_to_lead` 的 `delivery` 缺省不透传、显式插话与各类 fallback 原因;`interrupt_worker` 另覆盖队首预留、暂停态、graceful-stop 全部 outcome、auto-bridge 抑制和 done 互斥。
- Codex MCP context:`CodexMcpThreadContextStore` 覆盖按 threadId 查 context、unknown / missing threadId fail-closed、unregister 后清理、`vendorOptions` 引用保持;`codexHttpBridge` 覆盖从 JSON-RPC `params._meta.threadId` 注入真实 session context。
- Host 归属校验:`send_to_worker`、`interrupt_worker`、队列控制、`idle_worker`、`archive_worker` 经共享 `resolveWorkerRef`(同时接受 worker_id / session_id 两种 id)必须以 caller 自身 Lead 身份校验,拒绝跨 workflow worker id 与 ctx 缺失;即使模型传错 id 或换用另一种 id,也不能越权操作。
- UI route:Orca worker 不出现在 sidebar,Lead 自动进 split route,worker deep link 解析到 Lead split route;已有测试守住“不用 fork parentSessionId 或标题推断 Orca mapping”,见 `apps/desktop/src/renderer/__tests__/orcaWorkflowRoute.test.ts` 的 `does not use fork parentSessionId or title-linked worker lookup for Orca mapping`。
diff --git a/packages/lizi-mcps/src/__tests__/lizi_xdtHelperMcpServer.test.ts b/packages/lizi-mcps/src/__tests__/lizi_xdtHelperMcpServer.test.ts
index f66da5808b..7be459c4d4 100644
--- a/packages/lizi-mcps/src/__tests__/lizi_xdtHelperMcpServer.test.ts
+++ b/packages/lizi-mcps/src/__tests__/lizi_xdtHelperMcpServer.test.ts
@@ -611,6 +611,16 @@ describe("cindy_helper MCP server", () => {
ok: true as const,
queuedMessageId,
})),
+ steerQueuedMessage: vi.fn(async ({ queuedMessageId }) => ({
+ ok: true as const,
+ queuedMessageId,
+ delivery: "steered" as const,
+ })),
+ moveQueuedMessage: vi.fn(async ({ queuedMessageId, position }) => ({
+ ok: true as const,
+ queuedMessageId,
+ position,
+ })),
steerSession: vi.fn(async () => ({
ok: true as const,
queuedMessageId: "steer-1",
@@ -675,6 +685,8 @@ describe("cindy_helper MCP server", () => {
expect(names).toEqual(expect.arrayContaining([
"update_session_queued_message",
"cancel_session_queued_message",
+ "steer_session_queued_message",
+ "move_session_queued_message",
"steer_session",
"stop_session_turn",
"get_session_runtime",
@@ -755,6 +767,8 @@ describe("cindy_helper MCP server", () => {
sessionControl: {
updateQueuedMessage: vi.fn(),
cancelQueuedMessage: vi.fn(),
+ steerQueuedMessage: vi.fn(),
+ moveQueuedMessage: vi.fn(),
steerSession: vi.fn(),
stopSessionTurn,
getSessionRuntime: vi.fn(),
@@ -832,6 +846,8 @@ describe("cindy_helper MCP server", () => {
sessionControl: {
updateQueuedMessage: vi.fn(),
cancelQueuedMessage: vi.fn(),
+ steerQueuedMessage: vi.fn(),
+ moveQueuedMessage: vi.fn(),
steerSession: vi.fn(),
stopSessionTurn,
getSessionRuntime: vi.fn(),
diff --git a/packages/lizi-mcps/src/__tests__/sessionContext.test.ts b/packages/lizi-mcps/src/__tests__/sessionContext.test.ts
index 2e91d0a3a8..b6780e3926 100644
--- a/packages/lizi-mcps/src/__tests__/sessionContext.test.ts
+++ b/packages/lizi-mcps/src/__tests__/sessionContext.test.ts
@@ -95,6 +95,18 @@ function createOrcaDeps(overrides: Partial<OrcaMcpDeps> = {}): OrcaMcpDeps {
queuedMessageId: 'queued-1',
messages: [],
})),
+ steerWorkerQueuedMessage: vi.fn(async () => ({
+ ok: true as const,
+ workerId: 'worker-1',
+ queuedMessageId: 'queued-1',
+ delivery: 'steered' as const,
+ })),
+ moveWorkerQueuedMessage: vi.fn(async () => ({
+ ok: true as const,
+ workerId: 'worker-1',
+ queuedMessageId: 'queued-1',
+ position: 0,
+ })),
idleWorker: vi.fn(async () => ({ ok: true as const, workerId: 'worker-1' })),
endTeam: vi.fn(async () => ({ ok: true as const })),
archiveWorker: vi.fn(async () => ({ ok: true as const, workerId: 'worker-1' })),
@@ -134,7 +146,7 @@ function createOrcaDeps(overrides: Partial<OrcaMcpDeps> = {}): OrcaMcpDeps {
}
describe('dynamic lizi MCP session context', () => {
- it('keeps the 18-tool Orca manifest order stable across server construction', () => {
+ it('keeps the 20-tool Orca manifest order stable across server construction', () => {
const context = {
agentKind: 'codex' as const,
workingDir: 'C:\\repo',
@@ -144,13 +156,16 @@ describe('dynamic lizi MCP session context', () => {
const first = Object.keys(tools(createOrcaMcpServer(createOrcaDeps(), context)));
const second = Object.keys(tools(createOrcaMcpServer(createOrcaDeps(), context)));
- expect(first).toHaveLength(18);
+ // 17 个 team 工具 + 3 个只读诊断工具。
+ expect(first).toHaveLength(20);
expect(first).toEqual(second);
expect(first).toContain('create_worker');
expect(first).toContain('create_workers');
expect(first).toContain('interrupt_worker');
expect(first).toContain('get_worker_queue_status');
expect(first).toContain('merge_queued_messages');
+ expect(first).toContain('steer_queued_message');
+ expect(first).toContain('move_queued_message');
expect(first).not.toContain('list_worker_queue');
});
@@ -164,10 +179,241 @@ describe('dynamic lizi MCP session context', () => {
const schemaKeys = Object.keys(
tools(server).send_to_worker.inputSchema?.shape ?? {},
);
- expect(schemaKeys).toEqual(['target_session_id', 'message']);
+ expect(schemaKeys).toEqual(['target_session_id', 'message', 'delivery']);
expect(schemaKeys).not.toContain('interrupt');
});
+ it('forwards explicit send_to_worker delivery and reports steered or fallback receipts', async () => {
+ const sendToWorker = vi.fn<OrcaMcpDeps['sendToWorker']>()
+ .mockResolvedValueOnce({
+ ok: true,
+ agentKind: 'codex',
+ wakeKind: 'steered',
+ targetTitle: null,
+ targetLastUserSendAt: null,
+ })
+ .mockResolvedValueOnce({
+ ok: true,
+ agentKind: 'codex',
+ wakeKind: 'queued',
+ targetTitle: null,
+ targetLastUserSendAt: null,
+ queuedMessageId: 'queued-2',
+ steerFallbackReason: 'INPUT_BOUNDARY_BUSY',
+ });
+ const deps = createOrcaDeps({ sendToWorker });
+ const server = createOrcaMcpServer(deps, {
+ agentKind: 'codex',
+ workingDir: '/repo',
+ sessionId: 'lead-1',
+ vendorOptions: { orcaRole: 'lead' },
+ });
+
+ const steered = parse(await tools(server).send_to_worker.handler({
+ target_session_id: 'worker-session-1',
+ message: 'fix: use the v2 endpoint',
+ delivery: 'steer',
+ }) as never);
+ expect(steered).toMatchObject({ ok: true, wake_kind: 'already-active', steered: true });
+ expect(steered).not.toHaveProperty('steer_fallback_reason');
+ expect(steered).not.toHaveProperty('queued_message_id');
+
+ const fallback = parse(await tools(server).send_to_worker.handler({
+ target_session_id: 'worker-session-1',
+ message: 'fix: use the v2 endpoint',
+ delivery: 'steer',
+ }) as never);
+ expect(fallback).toMatchObject({
+ ok: true,
+ wake_kind: 'queued',
+ queued_message_id: 'queued-2',
+ steer_fallback_reason: 'INPUT_BOUNDARY_BUSY',
+ });
+ expect(sendToWorker).toHaveBeenNthCalledWith(1, {
+ callerLeadSessionId: 'lead-1',
+ targetSessionId: 'worker-session-1',
+ message: 'fix: use the v2 endpoint',
+ delivery: 'steer',
+ });
+ expect(tools(server).send_to_worker.description).toContain('delivery=steer');
+ expect(tools(server).send_to_worker.description).toContain('steer_fallback_reason');
+ });
+
+ it('omits delivery from sendToWorker when the caller does not choose one', async () => {
+ const deps = createOrcaDeps();
+ const server = createOrcaMcpServer(deps, {
+ agentKind: 'codex',
+ workingDir: '/repo',
+ sessionId: 'lead-1',
+ vendorOptions: { orcaRole: 'lead' },
+ });
+
+ const result = parse(await tools(server).send_to_worker.handler({
+ target_session_id: 'worker-session-1',
+ message: 'next task',
+ }) as never);
+ expect(result).toMatchObject({ ok: true, wake_kind: 'already-active' });
+ expect(result).not.toHaveProperty('steer_fallback_reason');
+ expect(vi.mocked(deps.sendToWorker).mock.calls[0]?.[0]).not.toHaveProperty('delivery');
+ });
+
+ it('reads the caller own input queue when get_worker_queue_status omits worker_id', async () => {
+ const deps = createOrcaDeps({
+ listWorkerQueuedMessages: vi.fn(async () => ({
+ ok: true as const,
+ workerId: null,
+ workerSessionId: 'lead-1',
+ status: 'running',
+ isWorking: true,
+ willQueue: true,
+ queuePaused: false,
+ messages: [
+ {
+ queuedMessageId: 'report-1',
+ position: 0,
+ source: 'worker' as const,
+ content: 'worker report',
+ consuming: false,
+ },
+ ],
+ })),
+ });
+ const server = createOrcaMcpServer(deps, {
+ agentKind: 'codex',
+ workingDir: '/repo',
+ sessionId: 'lead-1',
+ vendorOptions: { orcaRole: 'lead' },
+ });
+
+ const result = parse(await tools(server).get_worker_queue_status.handler({}) as never);
+ expect(result).toMatchObject({
+ ok: true,
+ worker_id: null,
+ worker_session_id: 'lead-1',
+ queued_count: 1,
+ queue: [{ queued_message_id: 'report-1', source: 'worker' }],
+ });
+ expect(vi.mocked(deps.listWorkerQueuedMessages).mock.calls[0]?.[0]).toEqual({
+ callerLeadSessionId: 'lead-1',
+ });
+ });
+
+ it('steers a queued message and reports a retained fallback with its reason', async () => {
+ const steerWorkerQueuedMessage = vi.fn<OrcaMcpDeps['steerWorkerQueuedMessage']>()
+ .mockResolvedValueOnce({
+ ok: true,
+ workerId: 'worker-1',
+ queuedMessageId: 'queued-1',
+ delivery: 'steered',
+ })
+ .mockResolvedValueOnce({
+ ok: true,
+ workerId: null,
+ queuedMessageId: 'report-1',
+ delivery: 'queued',
+ reason: 'NO_ACTIVE_TURN',
+ })
+ .mockResolvedValueOnce({
+ ok: false,
+ errorCode: 'NOT_ORCA_MESSAGE',
+ message: 'not a worker report',
+ });
+ const deps = createOrcaDeps({ steerWorkerQueuedMessage });
+ const server = createOrcaMcpServer(deps, {
+ agentKind: 'codex',
+ workingDir: '/repo',
+ sessionId: 'lead-1',
+ vendorOptions: { orcaRole: 'lead' },
+ });
+
+ const steered = parse(await tools(server).steer_queued_message.handler({
+ worker_id: 'worker-1',
+ queued_message_id: 'queued-1',
+ }) as never);
+ expect(steered).toEqual({
+ ok: true,
+ worker_id: 'worker-1',
+ queued_message_id: 'queued-1',
+ delivery: 'steered',
+ });
+ expect(steerWorkerQueuedMessage).toHaveBeenNthCalledWith(1, {
+ callerLeadSessionId: 'lead-1',
+ workerRef: 'worker-1',
+ queuedMessageId: 'queued-1',
+ });
+
+ const retained = parse(await tools(server).steer_queued_message.handler({
+ queued_message_id: 'report-1',
+ }) as never);
+ expect(retained).toEqual({
+ ok: true,
+ worker_id: null,
+ queued_message_id: 'report-1',
+ delivery: 'queued',
+ reason: 'NO_ACTIVE_TURN',
+ });
+ expect(steerWorkerQueuedMessage).toHaveBeenNthCalledWith(2, {
+ callerLeadSessionId: 'lead-1',
+ queuedMessageId: 'report-1',
+ });
+
+ expect(parse(await tools(server).steer_queued_message.handler({
+ queued_message_id: 'user-1',
+ }) as never)).toMatchObject({ ok: false, errorCode: 'NOT_ORCA_MESSAGE' });
+ expect(Object.keys(tools(server).steer_queued_message.inputSchema?.shape ?? {})).toEqual([
+ 'worker_id',
+ 'queued_message_id',
+ ]);
+ });
+
+ it('moves a queued message and returns the final position', async () => {
+ const moveWorkerQueuedMessage = vi.fn<OrcaMcpDeps['moveWorkerQueuedMessage']>(async () => ({
+ ok: true as const,
+ workerId: null,
+ queuedMessageId: 'report-1',
+ position: 2,
+ }));
+ const deps = createOrcaDeps({ moveWorkerQueuedMessage });
+ const server = createOrcaMcpServer(deps, {
+ agentKind: 'codex',
+ workingDir: '/repo',
+ sessionId: 'lead-1',
+ vendorOptions: { orcaRole: 'lead' },
+ });
+
+ expect(parse(await tools(server).move_queued_message.handler({
+ queued_message_id: 'report-1',
+ position: 99,
+ }) as never)).toEqual({
+ ok: true,
+ worker_id: null,
+ queued_message_id: 'report-1',
+ position: 2,
+ });
+ expect(moveWorkerQueuedMessage).toHaveBeenCalledWith({
+ callerLeadSessionId: 'lead-1',
+ queuedMessageId: 'report-1',
+ position: 99,
+ });
+
+ await tools(server).move_queued_message.handler({
+ worker_id: 'worker-1',
+ queued_message_id: 'queued-1',
+ position: 0,
+ });
+ expect(moveWorkerQueuedMessage).toHaveBeenLastCalledWith({
+ callerLeadSessionId: 'lead-1',
+ workerRef: 'worker-1',
+ queuedMessageId: 'queued-1',
+ position: 0,
+ });
+ expect(Object.keys(tools(server).move_queued_message.inputSchema?.shape ?? {})).toEqual([
+ 'worker_id',
+ 'queued_message_id',
+ 'position',
+ ]);
+ });
+
it('exposes interrupt_worker as the sole interrupt contract', async () => {
const deps = createOrcaDeps();
const server = createOrcaMcpServer(deps, {
@@ -1274,6 +1520,13 @@ describe('dynamic lizi MCP session context', () => {
const withoutArchiveCtx = await tools(server).archive_worker.handler({
worker_id: 'worker-1',
});
+ const withoutSteerQueuedCtx = await tools(server).steer_queued_message.handler({
+ queued_message_id: 'queued-1',
+ });
+ const withoutMoveQueuedCtx = await tools(server).move_queued_message.handler({
+ queued_message_id: 'queued-1',
+ position: 0,
+ });
expect(parse(withoutSendCtx as never)).toMatchObject({
ok: false,
@@ -1291,6 +1544,16 @@ describe('dynamic lizi MCP session context', () => {
ok: false,
errorCode: 'LEAD_NOT_SUPPORTED',
});
+ expect(parse(withoutSteerQueuedCtx as never)).toMatchObject({
+ ok: false,
+ errorCode: 'LEAD_NOT_SUPPORTED',
+ });
+ expect(parse(withoutMoveQueuedCtx as never)).toMatchObject({
+ ok: false,
+ errorCode: 'LEAD_NOT_SUPPORTED',
+ });
+ expect(deps.steerWorkerQueuedMessage).not.toHaveBeenCalled();
+ expect(deps.moveWorkerQueuedMessage).not.toHaveBeenCalled();
expect(deps.sendToWorker).not.toHaveBeenCalled();
expect(deps.interruptWorker).not.toHaveBeenCalled();
expect(deps.idleWorker).not.toHaveBeenCalled();
diff --git a/packages/lizi-mcps/src/__tests__/sessionControlTools.test.ts b/packages/lizi-mcps/src/__tests__/sessionControlTools.test.ts
index 7b22940448..85e00817d0 100644
--- a/packages/lizi-mcps/src/__tests__/sessionControlTools.test.ts
+++ b/packages/lizi-mcps/src/__tests__/sessionControlTools.test.ts
@@ -4,7 +4,9 @@ import { XdtHelperToolRegistry, type XdtHelperToolResult } from '../lizi_xdtHelp
import {
registerCancelSessionQueuedMessageTool,
registerGetSessionRuntimeTool,
+ registerMoveSessionQueuedMessageTool,
registerSetSessionRuntimeTool,
+ registerSteerSessionQueuedMessageTool,
registerSteerSessionTool,
registerStopSessionTurnTool,
registerUpdateSessionQueuedMessageTool,
@@ -33,6 +35,16 @@ function setup(opts?: { sessionId?: string | undefined }) {
ok: true as const,
queuedMessageId,
})),
+ steerQueuedMessage: vi.fn(async ({ queuedMessageId }) => ({
+ ok: true as const,
+ queuedMessageId,
+ delivery: 'steered' as const,
+ })),
+ moveQueuedMessage: vi.fn(async ({ queuedMessageId }) => ({
+ ok: true as const,
+ queuedMessageId,
+ position: 0,
+ })),
steerSession: vi.fn(async () => ({ ok: true as const, queuedMessageId: 'steer-1' })),
stopSessionTurn: vi.fn(async () => ({
ok: true as const,
@@ -72,6 +84,8 @@ function setup(opts?: { sessionId?: string | undefined }) {
const registry = new XdtHelperToolRegistry();
registerUpdateSessionQueuedMessageTool(registry, deps);
registerCancelSessionQueuedMessageTool(registry, deps);
+ registerSteerSessionQueuedMessageTool(registry, deps);
+ registerMoveSessionQueuedMessageTool(registry, deps);
registerSteerSessionTool(registry, deps);
registerStopSessionTurnTool(registry, deps);
registerGetSessionRuntimeTool(registry, deps);
@@ -194,6 +208,8 @@ describe('cindy_helper session control tools', () => {
session_id: 'target', queued_message_id: 'q', message: 'next',
}],
['cancel_session_queued_message', { session_id: 'target', queued_message_id: 'q' }],
+ ['steer_session_queued_message', { session_id: 'target', queued_message_id: 'q' }],
+ ['move_session_queued_message', { session_id: 'target', queued_message_id: 'q', position: 0 }],
['steer_session', { session_id: 'target', message: 'urgent context' }],
] as const) {
expect(parse(await registry.call(name, args))).toMatchObject({
@@ -203,9 +219,90 @@ describe('cindy_helper session control tools', () => {
}
expect(deps.updateQueuedMessage).not.toHaveBeenCalled();
expect(deps.cancelQueuedMessage).not.toHaveBeenCalled();
+ expect(deps.steerQueuedMessage).not.toHaveBeenCalled();
+ expect(deps.moveQueuedMessage).not.toHaveBeenCalled();
expect(deps.steerSession).not.toHaveBeenCalled();
});
+ it('converts a queued message to a steer and reports a retained fallback reason', async () => {
+ const { deps, registry } = setup();
+
+ expect(parse(await registry.call('steer_session_queued_message', {
+ session_id: 'target-session',
+ queued_message_id: 'queued-1',
+ }))).toEqual({
+ ok: true,
+ session_id: 'target-session',
+ queued_message_id: 'queued-1',
+ delivery: 'steered',
+ });
+ expect(deps.steerQueuedMessage).toHaveBeenCalledWith({
+ callerSessionId: 'caller-session',
+ targetSessionId: 'target-session',
+ queuedMessageId: 'queued-1',
+ });
+
+ vi.mocked(deps.steerQueuedMessage).mockResolvedValueOnce({
+ ok: true,
+ queuedMessageId: 'queued-2',
+ delivery: 'queued',
+ reason: 'STEER_UNCERTAIN',
+ });
+ expect(parse(await registry.call('steer_session_queued_message', {
+ session_id: 'caller-session',
+ queued_message_id: 'queued-2',
+ }))).toEqual({
+ ok: true,
+ session_id: 'caller-session',
+ queued_message_id: 'queued-2',
+ delivery: 'queued',
+ reason: 'STEER_UNCERTAIN',
+ });
+
+ vi.mocked(deps.steerQueuedMessage).mockResolvedValueOnce({
+ ok: false,
+ errorCode: 'NOT_AUTHORIZED',
+ message: 'user message',
+ });
+ expect(parse(await registry.call('steer_session_queued_message', {
+ session_id: 'target-session',
+ queued_message_id: 'user-1',
+ }))).toMatchObject({ ok: false, errorCode: 'NOT_AUTHORIZED' });
+ });
+
+ it('moves a queued message and returns the final position', async () => {
+ const { deps, registry } = setup();
+ vi.mocked(deps.moveQueuedMessage).mockResolvedValueOnce({
+ ok: true,
+ queuedMessageId: 'queued-1',
+ position: 3,
+ });
+
+ expect(parse(await registry.call('move_session_queued_message', {
+ session_id: 'target-session',
+ queued_message_id: 'queued-1',
+ position: 10,
+ }))).toEqual({
+ ok: true,
+ session_id: 'target-session',
+ queued_message_id: 'queued-1',
+ position: 3,
+ });
+ expect(deps.moveQueuedMessage).toHaveBeenCalledWith({
+ callerSessionId: 'caller-session',
+ targetSessionId: 'target-session',
+ queuedMessageId: 'queued-1',
+ position: 10,
+ });
+
+ expect(parse(await registry.call('move_session_queued_message', {
+ session_id: 'target-session',
+ queued_message_id: 'queued-1',
+ position: -1,
+ }))).toMatchObject({ ok: false, errorCode: 'INVALID_ARGS' });
+ expect(deps.moveQueuedMessage).toHaveBeenCalledTimes(1);
+ });
+
it('steers, requests graceful stop and projects bounded runtime metadata', async () => {
const { deps, registry } = setup();
diff --git a/packages/lizi-mcps/src/lizi_xdtHelperMcpServer.ts b/packages/lizi-mcps/src/lizi_xdtHelperMcpServer.ts
index 3801d2934f..8858f6719e 100644
--- a/packages/lizi-mcps/src/lizi_xdtHelperMcpServer.ts
+++ b/packages/lizi-mcps/src/lizi_xdtHelperMcpServer.ts
@@ -54,6 +54,8 @@ import {
registerListSessionsTool,
registerListSessionQueueTool,
registerUpdateSessionQueuedMessageTool,
+ registerSteerSessionQueuedMessageTool,
+ registerMoveSessionQueuedMessageTool,
registerCancelSessionQueuedMessageTool,
registerSteerSessionTool,
registerStopSessionTurnTool,
@@ -925,6 +927,8 @@ export function createXdtHelperMcpServer(
};
registerUpdateSessionQueuedMessageTool(registry, controlDeps);
registerCancelSessionQueuedMessageTool(registry, controlDeps);
+ registerSteerSessionQueuedMessageTool(registry, controlDeps);
+ registerMoveSessionQueuedMessageTool(registry, controlDeps);
registerSteerSessionTool(registry, controlDeps);
registerStopSessionTurnTool(registry, controlDeps);
registerGetSessionRuntimeTool(registry, controlDeps);
diff --git a/packages/lizi-mcps/src/orca/server.ts b/packages/lizi-mcps/src/orca/server.ts
index 5e68f94b5d..5583f00c21 100644
--- a/packages/lizi-mcps/src/orca/server.ts
+++ b/packages/lizi-mcps/src/orca/server.ts
@@ -3,11 +3,12 @@
* ---------------------------------------------------------------------------
* In-process MCP server (`cindy_orca`) 暴露多 worker 协同(Orca team)控制工具。
*
- * 暴露 15 个 team 工具(直接 server.tool() 注册到顶层,不走 list_tools/call_tool 入口):
+ * 暴露 17 个 team 工具(直接 server.tool() 注册到顶层,不走 list_tools/call_tool 入口):
* start_team / create_worker / create_workers / send_to_worker / interrupt_worker /
* get_worker_queue_status / update_queued_message / cancel_queued_message /
- * merge_queued_messages / list_workers / switch_focus /
- * idle_worker / end_team / archive_worker / list_available_models
+ * merge_queued_messages / steer_queued_message / move_queued_message /
+ * list_workers / switch_focus / idle_worker / end_team / archive_worker /
+ * list_available_models
*
* 为什么直接注册而非走入口:协同工具藏在 list_tools/call_tool 后面时, 模型在用户
* 说"开协同 / 派 worker"时往往发现不了 start_team, 反而误抓直接可见的
@@ -37,7 +38,7 @@ import {
type XdtHelperToolCategory,
type XdtHelperToolHandler,
} from '../lizi_xdtHelperToolRegistry.js';
-// 15 个 team 工具的注册函数留在 xdt-helper/ 目录(register 是 registry-agnostic,
+// 17 个 team 工具的注册函数留在 xdt-helper/ 目录(register 是 registry-agnostic,
// 物理搬迁收益低)。本 server 通过 DirectToolSink 把它们直接注册到 McpServer。
import {
registerStartTeamTool,
@@ -50,12 +51,17 @@ import {
registerUpdateQueuedMessageTool,
registerCancelQueuedMessageTool,
registerMergeQueuedMessagesTool,
+ registerSteerQueuedMessageTool,
+ registerMoveQueuedMessageTool,
registerIdleWorkerTool,
registerEndTeamTool,
registerArchiveWorkerTool,
registerListAvailableModelsTool,
type ModelDescriptor,
+ type OrcaMessageDelivery,
type QueuedMessageControlErrorCode,
+ type QueuedMessageSteerReason,
+ type SteerFallbackReason,
type WorkerQueuedMessageEntry,
type WorkerSummary,
} from '../xdt-helper/index.js';
@@ -66,7 +72,7 @@ import { errorPayload, okPayload } from '../xdt-helper/_payload.js';
// ── Host deps ──────────────────────────────────────────────────────────────
/**
- * 协同(team)控制类工具的 host 回调集合。注入即注册 cindy_orca 的 15 个 team 工具
+ * 协同(team)控制类工具的 host 回调集合。注入即注册 cindy_orca 的 17 个 team 工具
* (per-session 闭包绑定 ctx)。
*
* 回调返 Result 而非抛 Promise<T>: 让 host 能用 `HOST_NOT_READY` errorCode 表达
@@ -122,14 +128,18 @@ export interface OrcaMcpDeps {
callerLeadSessionId: string;
targetSessionId: string;
message: string;
+ /** 仅模型显式选择时传入;缺省等价 'queue'。 */
+ delivery?: OrcaMessageDelivery;
}) => Promise<
ControlResult<
{
agentKind: ControlWorkerAgent;
- wakeKind: 'resumed' | 'already-active' | 'queued';
+ wakeKind: 'resumed' | 'already-active' | 'queued' | 'steered';
targetTitle: string | null;
targetLastUserSendAt: string | null;
queuedMessageId?: string;
+ /** 请求 steer 但消息进了队列时的原因。 */
+ steerFallbackReason?: SteerFallbackReason;
},
'NOT_FOUND' | 'ARCHIVED' | 'DELETED' | 'BUSY' | 'AGENT_NOT_READY' | 'INVALID_ARGS'
>
@@ -152,14 +162,16 @@ export interface OrcaMcpDeps {
queuePaused: boolean;
}>
>;
- /** 列出 worker 输入队列中排队的消息(lead 自己的条目含正文)。 */
+ /** 列出 worker 输入队列中排队的消息;省略 workerRef 时列出调用方自身输入队列。 */
listWorkerQueuedMessages: (params: {
callerLeadSessionId: string;
- workerRef: string;
+ workerRef?: string;
}) => Promise<
ControlResult<
{
- workerId: string;
+ /** 读取调用方自身队列时为 null。 */
+ workerId: string | null;
+ /** 被读取队列所属 session(自身队列时为调用方的 session id)。 */
workerSessionId: string;
status: string;
isWorking: boolean;
@@ -203,6 +215,37 @@ export interface OrcaMcpDeps {
QueuedMessageControlErrorCode | 'QUEUE_CHANGED'
> & { messages?: WorkerQueuedMessageEntry[] }
>;
+ /**
+ * 把一条排队协同消息转为插话。workerRef 省略时操作调用方自身队列里的协同消息;
+ * 没插成时消息留在队列,返回 delivery=queued + reason。
+ */
+ steerWorkerQueuedMessage: (params: {
+ callerLeadSessionId: string;
+ workerRef?: string;
+ queuedMessageId: string;
+ }) => Promise<
+ ControlResult<
+ {
+ workerId: string | null;
+ queuedMessageId: string;
+ delivery: 'steered' | 'queued';
+ reason?: QueuedMessageSteerReason;
+ },
+ QueuedMessageControlErrorCode
+ >
+ >;
+ /** 调整一条排队协同消息的位置(返回实际最终位置);workerRef 省略时操作调用方自身队列。 */
+ moveWorkerQueuedMessage: (params: {
+ callerLeadSessionId: string;
+ workerRef?: string;
+ queuedMessageId: string;
+ position: number;
+ }) => Promise<
+ ControlResult<
+ { workerId: string | null; queuedMessageId: string; position: number },
+ QueuedMessageControlErrorCode
+ >
+ >;
/** 主动将 worker 设为 idle。 */
idleWorker: (params: { callerLeadSessionId: string; workerId: string }) => Promise<
ControlResult<{ workerId: string }, 'WORKER_NOT_FOUND' | 'ALREADY_IDLE'>
@@ -296,7 +339,7 @@ export interface OrcaMcpSessionCtx {
* DirectToolSink —— 把 team 工具直接 server.tool() 注册的适配器。
*
* 复用既有 register*Tool(registry, deps) 的签名: 本类继承 XdtHelperToolRegistry 但
- * override register() —— 不入内部 Map, 而是转调 server.tool()。这样 15 个工具文件
+ * override register() —— 不入内部 Map, 而是转调 server.tool()。这样 17 个工具文件
* 一行不改即可顶层直接注册。direct 注册下 category 字段无意义(忽略); list()/
* call() 等继承方法不会被用到(cindy_orca 不暴露 list_tools/call_tool 入口)。
*/
@@ -429,7 +472,7 @@ export function createOrcaMcpServer(
version: '1.0.0',
});
- // 15 个 team 工具经 DirectToolSink 直接注册到顶层。handler 闭包绑定 ctx
+ // 17 个 team 工具经 DirectToolSink 直接注册到顶层。handler 闭包绑定 ctx
// (sessionId / vendorOptions), 调用时把请求路由回 host。
const sink = new DirectToolSink(server);
const getSessionContext = () => resolveLiziMcpSessionContext(ctx);
@@ -480,6 +523,14 @@ export function createOrcaMcpServer(
getSessionContext,
mergeWorkerQueuedMessages: deps.mergeWorkerQueuedMessages,
});
+ registerSteerQueuedMessageTool(sink, {
+ getSessionContext,
+ steerWorkerQueuedMessage: deps.steerWorkerQueuedMessage,
+ });
+ registerMoveQueuedMessageTool(sink, {
+ getSessionContext,
+ moveWorkerQueuedMessage: deps.moveWorkerQueuedMessage,
+ });
registerIdleWorkerTool(sink, {
getSessionContext,
idleWorker: deps.idleWorker,
diff --git a/packages/lizi-mcps/src/xdt-helper/capabilities.ts b/packages/lizi-mcps/src/xdt-helper/capabilities.ts
index 1ef3661df4..a31d3c8488 100644
--- a/packages/lizi-mcps/src/xdt-helper/capabilities.ts
+++ b/packages/lizi-mcps/src/xdt-helper/capabilities.ts
@@ -78,7 +78,7 @@ export const CAPABILITIES: readonly CapabilityEntry[] = [
'【怎么开】用户表达"用 worker / 协同模式 / 独立 agent / 派一个 agent 帮我 X"等意图时, Lead 调 start_team 工具创建 team, 再调 create_worker 工具添加 worker。worker 创建后可通过 send_to_worker 派活, 通过 list_workers 查看所有 worker, 通过 switch_focus 切换 focused worker。',
'【怎么关】用户表达"够了 / 关掉 worker / 不要协同了"时, Lead 调 end_team 结束整个 team(归档所有 worker), 或调 archive_worker 归档单个 worker。Lead 自身保留可继续单 session 对话。',
'【硬边界】Worker session 不能再开 team(嵌套禁止, 返 WORKER_CANNOT_NEST);Claude Code / Codex / Pi 本地项目或对话 session 都可以作为 Lead 调 start_team,也都可以作为 Worker;SSH 远程 Lead 与 Worker 当前只支持 Claude Code / Codex;Worker 不能结束自己所在 team(返 WORKER_CANNOT_DISABLE);要求 Lead session 有 workingDir。',
- '【工具归属】15 个 team 工具(start_team / create_worker / create_workers / send_to_worker / interrupt_worker / get_worker_queue_status / update_queued_message / cancel_queued_message / merge_queued_messages / list_workers / switch_focus / idle_worker / end_team / archive_worker / list_available_models)在独立的 cindy_orca server 直接顶层注册, 对应"协同模式"可关插件(Settings → Connections → Built-in Tools)。通用 session handoff 原语 send_to_session 在 essential 的 cindy_helper 的 handoff 类目下(走 call_tool, 常开, 供 skill 路由用)。',
+ '【工具归属】17 个 team 工具(start_team / create_worker / create_workers / send_to_worker / interrupt_worker / get_worker_queue_status / update_queued_message / cancel_queued_message / merge_queued_messages / steer_queued_message / move_queued_message / list_workers / switch_focus / idle_worker / end_team / archive_worker / list_available_models)在独立的 cindy_orca server 直接顶层注册, 对应"协同模式"可关插件(Settings → Connections → Built-in Tools)。通用 session handoff 原语 send_to_session 在 essential 的 cindy_helper 的 handoff 类目下(走 call_tool, 常开, 供 skill 路由用)。',
`【与 Claude Code Task tool / Codex subagent 的区别】Task / subagent 是 agent 框架内的子任务派发机制(子 agent 跑在同一 SDK 进程内、有限工具集、生命周期短、对话历史归属父 turn);${BRAND_NAME} 协同模式是业务层的 session 级编排(Lead/Worker 都是完整独立的 ${BRAND_NAME} session, 独立进程、UI 栏位、完整工具、独立对话历史, 长生命周期, 通过 main 进程 IPC + MCP bridge 通信)。两者不互斥, Worker 内部仍可用 Task/subagent 派子任务。`,
'【手动入口】ChatInput「+」菜单里的「协同模式」项,开启态用橙色 UsersRound 图标与文字标识;用户也能在这里手动开/关,与本工具走同一份业务代码。',
].join(' '),
@@ -102,9 +102,9 @@ export const CAPABILITIES: readonly CapabilityEntry[] = [
oneLiner:
'agent 可观察任意本机会话队列与运行状态,并控制自己投递的队列消息、same-turn 插话或请求优雅停止。',
detail: [
- '【入口】cindy_helper 的 history 类 list_sessions / list_session_queue 提供 queuedCount、队列位置、来源、入队时间、正文摘要与 consuming 状态;control 类提供 update_session_queued_message、cancel_session_queued_message、steer_session、stop_session_turn、get_session_runtime。',
+ '【入口】cindy_helper 的 history 类 list_sessions / list_session_queue 提供 queuedCount、队列位置、来源、入队时间、正文摘要与 consuming 状态;control 类提供 update_session_queued_message、cancel_session_queued_message、steer_session_queued_message、move_session_queued_message、steer_session、stop_session_turn、get_session_runtime。',
'【伙伴入口】伙伴不挂载通用 control 类。只管理自己拥有的后台任务:message_session_task 的 queue / steer / resume 分别表示排队、同轮插话、恢复暂停;stop_session_task 的 cancel / request-stop / pause 分别表示取消任务、请求当前轮停止、保留任务与队列的可恢复暂停。check_session_task 的 control 区分 pausing / paused;requested 或 unconfirmed 不能当作已停。不支持的引擎明确返回失败。',
- '【队列所有权】只能修改或撤回当前调用 session 自己通过 send_to_session 投递、且尚未进入 consuming 的消息;Orca、scheduler、用户或其它 session 的消息都会 fail-closed 拒绝。Orca worker 队列控制与这里复用同一底层生命周期实现。',
+ '【队列所有权】只能修改或撤回当前调用 session 自己通过 send_to_session 投递、且尚未进入 consuming 的消息;Orca、scheduler、用户或其它 session 的消息都会 fail-closed 拒绝。Orca worker 队列控制与这里复用同一底层生命周期实现。steer_session_queued_message / move_session_queued_message 把排队消息转为插话或调整顺序,可操作范围另含自己任务队列里由其它任务 / 协同成员发来的机器消息;没插成时消息留在队列并返回 reason。',
'【插话】steer_session 只对正在运行且支持 same-turn steer 的 session 生效,在 provider 的下一个输入间隙注入当前 turn;若 turn 已结束会明确失败,不会退化成下一 turn。',
'【停止】stop_session_turn 是请求式优雅停止:当前并行工具全部收尾后才发送 provider 软中断;不关闭 transport、不重建 session、不硬杀进程,超时未确认会返回 unconfirmed。',
'【探针】get_session_runtime 返回统一 phase、记录状态、标题工作流语义、turn generation、开始时间、最后活动时间、当前动作摘要和停止状态;动作摘要有界且不包含提示词正文、工具参数或凭证。',
diff --git a/packages/lizi-mcps/src/xdt-helper/get_worker_queue_status.ts b/packages/lizi-mcps/src/xdt-helper/get_worker_queue_status.ts
index 1959f089b6..61fffaec23 100644
--- a/packages/lizi-mcps/src/xdt-helper/get_worker_queue_status.ts
+++ b/packages/lizi-mcps/src/xdt-helper/get_worker_queue_status.ts
@@ -1,10 +1,13 @@
/**
- * xdt-helper/get_worker_queue_status.ts —— 读取指定 worker 工作态与完整输入队列。
+ * xdt-helper/get_worker_queue_status.ts —— 读取指定 worker(或 Lead 自己)的工作态与完整输入队列。
*
* Lead 派发的消息在 worker 忙时会排队(send_to_worker 的 wake_kind=queued);
* 本工具让 lead 在消息被消费前看到队列全貌。口径「看得全、只能动自己的」:
* 三种来源(lead / 用户手打 / scheduler)的条目都回传正文,供 lead 基于完整
* 队列内容做编排;但修改 / 撤回只对 lead 自己的条目开放。
+ *
+ * 省略 worker_id 时读取调用方自己的输入队列:调用方忙时收到的协同消息(Lead 收到的
+ * Worker 回报,或 Worker 收到的 Lead 消息)排在这里(source=worker),可转插话或调整顺序。
*/
import { z } from 'zod';
@@ -17,7 +20,8 @@ import { errorPayload, okPayload } from './_payload.js';
export interface WorkerQueuedMessageEntry {
queuedMessageId: string;
position: number;
- source: 'lead' | 'user' | 'scheduler';
+ /** worker = 调用方自身队列中的协同消息(仅省略 worker_id 读取自身队列时出现)。 */
+ source: 'lead' | 'user' | 'scheduler' | 'worker';
content: string;
consuming: boolean;
}
@@ -28,11 +32,14 @@ export interface GetWorkerQueueStatusDeps {
};
listWorkerQueuedMessages: (params: {
callerLeadSessionId: string;
- workerRef: string;
+ /** 省略即读取调用方自己的输入队列。 */
+ workerRef?: string;
}) => Promise<
ControlResult<
{
- workerId: string;
+ /** 读取调用方自身队列时为 null。 */
+ workerId: string | null;
+ /** 被读取队列所属 session(自身队列时为调用方的 session id)。 */
workerSessionId: string;
status: string;
isWorking: boolean;
@@ -47,8 +54,10 @@ export interface GetWorkerQueueStatusDeps {
const DESCRIPTION =
'读取指定 worker 当前工作态、下一条消息是否会排队,以及完整待处理队列。' +
+ '省略 worker_id 时读取你自己的队列(source=worker 为发给你的协同消息)。' +
'source=lead 的条目是你自己发的(send_to_worker / initial_task 排队产生),' +
'可用 update_queued_message / cancel_queued_message 修改或撤回,或用 merge_queued_messages 原子合并连续的 Lead 消息;' +
+ 'source=lead / worker 的条目可用 steer_queued_message / move_queued_message 转插话或调整顺序。' +
'source=user / scheduler 的条目正文可见(供理解排队顺序与内容),但不可修改/撤回。' +
'consuming=true 表示该条正在投递中,已不可修改/撤回。' +
'失败码: LEAD_NOT_SUPPORTED / WORKER_NOT_FOUND。';
@@ -65,7 +74,8 @@ export function registerGetWorkerQueueStatusTool(
worker_id: z
.string()
.min(1)
- .describe('目标 worker 的 worker_id 或 session_id 任一'),
+ .optional()
+ .describe('目标 worker 的 worker_id 或 session_id 任一;省略时读取你自己的输入队列'),
},
handler: async ({ worker_id }) => {
const ctx = deps.getSessionContext?.();
@@ -74,7 +84,7 @@ export function registerGetWorkerQueueStatusTool(
}
const result = await deps.listWorkerQueuedMessages({
callerLeadSessionId: ctx.sessionId,
- workerRef: worker_id,
+ ...(worker_id ? { workerRef: worker_id } : {}),
});
if (!result.ok) {
return errorPayload(result.errorCode, result.message);
diff --git a/packages/lizi-mcps/src/xdt-helper/index.ts b/packages/lizi-mcps/src/xdt-helper/index.ts
index 14d6d8fc94..fe2bab1656 100644
--- a/packages/lizi-mcps/src/xdt-helper/index.ts
+++ b/packages/lizi-mcps/src/xdt-helper/index.ts
@@ -62,7 +62,9 @@ export {
} from './switch_focus.js';
export {
registerSendToWorkerTool,
+ type OrcaMessageDelivery,
type SendToWorkerDeps,
+ type SteerFallbackReason,
} from './send_to_worker.js';
export {
registerGetWorkerQueueStatusTool,
@@ -82,6 +84,15 @@ export {
registerMergeQueuedMessagesTool,
type MergeQueuedMessagesDeps,
} from './merge_queued_messages.js';
+export {
+ registerSteerQueuedMessageTool,
+ type QueuedMessageSteerReason,
+ type SteerQueuedMessageDeps,
+} from './steer_queued_message.js';
+export {
+ registerMoveQueuedMessageTool,
+ type MoveQueuedMessageDeps,
+} from './move_queued_message.js';
export {
registerIdleWorkerTool,
type IdleWorkerDeps,
@@ -119,11 +130,14 @@ export {
registerUpdateSessionQueuedMessageTool,
registerCancelSessionQueuedMessageTool,
registerSteerSessionTool,
+ registerSteerSessionQueuedMessageTool,
+ registerMoveSessionQueuedMessageTool,
registerStopSessionTurnTool,
registerGetSessionRuntimeTool,
registerSetSessionRuntimeTool,
type SessionControlDeps,
type SessionQueueControlErrorCode,
+ type SessionQueueSteerReason,
type SessionRuntimeProfile,
type SessionRuntimeSnapshot,
type SessionSteerErrorCode,
diff --git a/packages/lizi-mcps/src/xdt-helper/list_session_queue.ts b/packages/lizi-mcps/src/xdt-helper/list_session_queue.ts
index 4c5c8afe9d..8d5abd467f 100644
--- a/packages/lizi-mcps/src/xdt-helper/list_session_queue.ts
+++ b/packages/lizi-mcps/src/xdt-helper/list_session_queue.ts
@@ -1,9 +1,10 @@
/**
* xdt-helper/list_session_queue.ts —— 查询任意本机 session 的只读输入队列。
*
- * 与 cindy_orca/get_worker_queue_status 的边界不同:本工具不要求 Lead 身份,也不暴露
- * 修改、撤回或重排能力;它只把 host 注入的队列快照压成有界摘要,供 agent 确认
- * 一条消息是否已经排队、位于什么位置、是否正在投递。
+ * 与 cindy_orca/get_worker_queue_status 的边界不同:本工具不要求 Lead 身份,本身只读;
+ * 它只把 host 注入的队列快照压成有界摘要,供 agent 确认一条消息是否已经排队、
+ * 位于什么位置、是否正在投递。修改 / 撤回 / 转插话 / 重排由 session_control 的
+ * *_session_queued_message 工具承担。
*/
import { z } from "zod";
@@ -37,7 +38,7 @@ export interface SessionQueueDeps {
const DESCRIPTION =
"只读列出本机任意 session 当前尚未消费的输入队列。每条返回队列位置、来源、入队时间、" +
- "正文摘要与 consuming 状态;consuming=true 表示该条正在投递。此工具不提供修改、撤回或重排。" +
+ "正文摘要与 consuming 状态;consuming=true 表示该条正在投递。修改、撤回、转插话或调整顺序用 update / cancel / steer / move_session_queued_message。" +
"session_id 建议来自 list_sessions。失败码: NOT_FOUND / HOST_NOT_READY / INTERNAL。";
export function registerListSessionQueueTool(
diff --git a/packages/lizi-mcps/src/xdt-helper/move_queued_message.ts b/packages/lizi-mcps/src/xdt-helper/move_queued_message.ts
new file mode 100644
index 0000000000..54ae8693db
--- /dev/null
+++ b/packages/lizi-mcps/src/xdt-helper/move_queued_message.ts
@@ -0,0 +1,91 @@
+/**
+ * xdt-helper/move_queued_message.ts —— 调整一条排队中的协同消息在队列中的位置。
+ *
+ * 可操作范围与 steer_queued_message 相同:worker 队列里只能移动 Lead 自己发的条目;
+ * 省略 worker_id 时移动调用方自身队列里的协同消息。position 越界时放到队尾,
+ * 返回 host 实际落定的位置。
+ */
+
+import { z } from 'zod';
+
+import type { XdtHelperToolRegistry } from '../lizi_xdtHelperToolRegistry.js';
+import type { ControlResult } from '../types.js';
+import type { QueuedMessageControlErrorCode } from './update_queued_message.js';
+import { errorPayload, okPayload } from './_payload.js';
+
+export interface MoveQueuedMessageDeps {
+ getSessionContext?: () => {
+ sessionId?: string;
+ };
+ moveWorkerQueuedMessage: (params: {
+ callerLeadSessionId: string;
+ /** 省略即操作调用方自己的输入队列。 */
+ workerRef?: string;
+ queuedMessageId: string;
+ position: number;
+ }) => Promise<
+ ControlResult<
+ {
+ /** 操作调用方自身队列时为 null。 */
+ workerId: string | null;
+ queuedMessageId: string;
+ /** 移动后的实际位置。 */
+ position: number;
+ },
+ QueuedMessageControlErrorCode
+ >
+ >;
+}
+
+const DESCRIPTION =
+ '把一条排队中的协同消息移到指定位置(0 = 队首,超出放队尾),返回实际位置。' +
+ '只能移动你发的条目;省略 worker_id 时操作你自己队列里的协同消息。' +
+ '失败码: LEAD_NOT_SUPPORTED / WORKER_NOT_FOUND / QUEUED_MESSAGE_NOT_FOUND / NOT_LEAD_MESSAGE / ' +
+ 'NOT_ORCA_MESSAGE / MESSAGE_CONSUMING。';
+
+export function registerMoveQueuedMessageTool(
+ registry: XdtHelperToolRegistry,
+ deps: MoveQueuedMessageDeps,
+): void {
+ registry.register({
+ name: 'move_queued_message',
+ category: 'control',
+ description: DESCRIPTION,
+ inputShape: {
+ worker_id: z
+ .string()
+ .min(1)
+ .optional()
+ .describe('目标 worker 的 worker_id 或 session_id 任一;省略时操作你自己的输入队列'),
+ queued_message_id: z
+ .string()
+ .min(1)
+ .describe('要移动的排队消息 id(来自排队回传或 get_worker_queue_status)'),
+ position: z
+ .number()
+ .int()
+ .min(0)
+ .describe('目标位置,0 = 队首;超出队列长度时放到队尾'),
+ },
+ handler: async ({ worker_id, queued_message_id, position }) => {
+ const ctx = deps.getSessionContext?.();
+ if (!ctx?.sessionId) {
+ return errorPayload('LEAD_NOT_SUPPORTED', '当前 session 类型不支持作为 Lead, 已拒绝 worker 队列操作。');
+ }
+ const result = await deps.moveWorkerQueuedMessage({
+ callerLeadSessionId: ctx.sessionId,
+ ...(worker_id ? { workerRef: worker_id } : {}),
+ queuedMessageId: queued_message_id,
+ position,
+ });
+ if (!result.ok) {
+ return errorPayload(result.errorCode, result.message);
+ }
+ return okPayload({
+ worker_id: result.workerId,
+ queued_message_id: result.queuedMessageId,
+ position: result.position,
+ });
+ },
+ });
+}
diff --git a/packages/lizi-mcps/src/xdt-helper/send_to_worker.ts b/packages/lizi-mcps/src/xdt-helper/send_to_worker.ts
index ee54a65e1e..bef99b7b96 100644
--- a/packages/lizi-mcps/src/xdt-helper/send_to_worker.ts
+++ b/packages/lizi-mcps/src/xdt-helper/send_to_worker.ts
@@ -11,6 +11,12 @@ import type { XdtHelperToolRegistry } from '../lizi_xdtHelperToolRegistry.js';
import type { ControlResult } from '../lizi_xdtHelperMcpServer.js';
import { errorPayload, okPayload } from './_payload.js';
+/** 协同消息投递方式:queue = 普通直发/排队(缺省),steer = 尝试插进对方当前 turn。 */
+export type OrcaMessageDelivery = 'queue' | 'steer';
+
+/** 请求 steer 但未插成、消息进入队列时的原因。 */
+export type SteerFallbackReason = 'STEER_UNSUPPORTED' | 'INPUT_BOUNDARY_BUSY' | 'STEER_UNCERTAIN';
+
export interface SendToWorkerDeps {
getSessionContext?: () => {
sessionId?: string;
@@ -19,14 +25,18 @@ export interface SendToWorkerDeps {
callerLeadSessionId: string;
targetSessionId: string;
message: string;
+ /** 仅调用方显式选择时传入;缺省等价 'queue'(普通直发/排队)。 */
+ delivery?: OrcaMessageDelivery;
}) => Promise<
ControlResult<
{
agentKind: 'claude-code' | 'codex' | 'pi';
- wakeKind: 'resumed' | 'already-active' | 'queued';
+ wakeKind: 'resumed' | 'already-active' | 'queued' | 'steered';
targetTitle: string | null;
targetLastUserSendAt: string | null;
queuedMessageId?: string;
+ /** 请求了 steer 但消息进了队列时的原因;空闲直发不带。 */
+ steerFallbackReason?: SteerFallbackReason;
},
'NOT_FOUND' | 'ARCHIVED' | 'DELETED' | 'BUSY' | 'AGENT_NOT_READY' | 'INVALID_ARGS'
>
@@ -57,7 +67,9 @@ const DESCRIPTION =
'向指定 worker 投递消息(派活/追问)。' +
'worker 正忙时消息自动排队(wake_kind=queued)并回传 queued_message_id;' +
'在它被消费前可用 get_worker_queue_status / update_queued_message / cancel_queued_message 查看、修改或撤回。' +
- '需要替换 worker 当前任务时改用 interrupt_worker;本工具只保留普通直发/排队语义。' +
+ '纠错或 worker 正在等的信息可用 delivery=steer 插进其当前 turn(返回 steered=true);新任务保持默认。' +
+ '没插成时照常直发或排队,排队时附 steer_fallback_reason。' +
+ '需要替换 worker 当前任务时改用 interrupt_worker。' +
'失败码: LEAD_NOT_SUPPORTED / NOT_FOUND / ARCHIVED / DELETED / BUSY / AGENT_NOT_READY。';
export function registerSendToWorkerTool(
@@ -77,8 +89,12 @@ export function registerSendToWorkerTool(
.string()
.min(1)
.describe('要投递给 worker 的消息正文'),
+ delivery: z
+ .enum(['queue', 'steer'])
+ .optional()
+ .describe('投递方式:queue(默认)= 直发或排队;steer = 尝试插进 worker 当前 turn'),
},
- handler: async ({ target_session_id, message }) => {
+ handler: async ({ target_session_id, message, delivery }) => {
const ctx = deps.getSessionContext?.();
if (!ctx?.sessionId) {
return errorPayload('LEAD_NOT_SUPPORTED', '当前 session 类型不支持作为 Lead, 已拒绝 worker 控制操作。');
@@ -87,6 +103,7 @@ export function registerSendToWorkerTool(
callerLeadSessionId: ctx.sessionId,
targetSessionId: target_session_id,
message,
+ ...(delivery ? { delivery } : {}),
});
if (!result.ok) {
@@ -99,10 +116,14 @@ export function registerSendToWorkerTool(
return okPayload({
target_session_id,
agent_kind: result.agentKind,
- wake_kind: result.wakeKind,
+ // 插话是投递给已在线的 session:wake_kind 沿用 already-active(Lead 提示词据此判定已派发),
+ // 另用 steered 标记它进了当前 turn。
+ wake_kind: result.wakeKind === 'steered' ? 'already-active' : result.wakeKind,
+ ...(result.wakeKind === 'steered' ? { steered: true } : {}),
target_title: result.targetTitle,
target_last_user_send_at: result.targetLastUserSendAt,
...(result.queuedMessageId ? { queued_message_id: result.queuedMessageId } : {}),
+ ...(result.steerFallbackReason ? { steer_fallback_reason: result.steerFallbackReason } : {}),
});
},
});
diff --git a/packages/lizi-mcps/src/xdt-helper/session_control.ts b/packages/lizi-mcps/src/xdt-helper/session_control.ts
index 6194d056df..66b71788eb 100644
--- a/packages/lizi-mcps/src/xdt-helper/session_control.ts
+++ b/packages/lizi-mcps/src/xdt-helper/session_control.ts
@@ -14,6 +14,13 @@ export type SessionQueueControlErrorCode =
| 'NOT_AUTHORIZED'
| 'INVALID_ARGS';
+/** 排队消息转插话未成功、消息仍留在队列时的原因。 */
+export type SessionQueueSteerReason =
+ | 'NO_ACTIVE_TURN'
+ | 'STEER_UNSUPPORTED'
+ | 'INPUT_BOUNDARY_BUSY'
+ | 'STEER_UNCERTAIN';
+
export type SessionSteerErrorCode =
| 'NOT_FOUND'
| 'NO_ACTIVE_TURN'
@@ -56,6 +63,30 @@ export interface SessionControlDeps {
targetSessionId: string;
queuedMessageId: string;
}): Promise<ControlResult<{ queuedMessageId: string }, SessionQueueControlErrorCode>>;
+ /** 把一条排队消息转为插话;没插成时消息留在队列,返回 delivery=queued + reason。 */
+ steerQueuedMessage(params: {
+ callerSessionId: string;
+ targetSessionId: string;
+ queuedMessageId: string;
+ }): Promise<
+ ControlResult<
+ {
+ queuedMessageId: string;
+ delivery: 'steered' | 'queued';
+ reason?: SessionQueueSteerReason;
+ },
+ SessionQueueControlErrorCode
+ >
+ >;
+ /** 调整一条排队消息的位置(position 越界放队尾),返回实际最终位置。 */
+ moveQueuedMessage(params: {
+ callerSessionId: string;
+ targetSessionId: string;
+ queuedMessageId: string;
+ position: number;
+ }): Promise<
+ ControlResult<{ queuedMessageId: string; position: number }, SessionQueueControlErrorCode>
+ >;
steerSession(params: {
callerSessionId: string;
targetSessionId: string;
@@ -181,6 +212,87 @@ export function registerCancelSessionQueuedMessageTool(
});
}
+// 转插话 / 重排的可操作范围(host 校验,不满足返回 NOT_AUTHORIZED):调用方通过
+// send_to_session 投递到目标的消息,或调用方自己任务队列里由其它任务 / 协同成员发来的
+// 机器消息;用户手打、伙伴委派、插件、定时任务消息不可操作。
+const SESSION_QUEUE_MANAGEABLE_SCOPE =
+ '可操作的是你通过 send_to_session 投递的消息,或你自己任务队列里由其它任务 / 协同成员发来的机器消息;' +
+ '用户手打、伙伴委派、插件、定时任务消息不可操作。';
+
+export function registerSteerSessionQueuedMessageTool(
+ registry: XdtHelperToolRegistry,
+ deps: SessionControlDeps,
+): void {
+ registry.register({
+ name: 'steer_session_queued_message',
+ category: 'control',
+ description:
+ '把一条排队中的消息转为插话,插进目标 session 当前 turn。' +
+ SESSION_QUEUE_MANAGEABLE_SCOPE +
+ 'delivery=steered 表示已插进当前 turn;delivery=queued 表示没插成、消息仍留在队列,reason: ' +
+ 'NO_ACTIVE_TURN(目标没在运行,会按顺序发出) / STEER_UNSUPPORTED / INPUT_BOUNDARY_BUSY(输入边界暂被占用) / ' +
+ 'STEER_UNCERTAIN(无法确认是否送达,已暂停队列待用户处置)。',
+ inputShape: {
+ session_id: z.string().min(1).describe('目标 session id(操作自己任务的队列时传当前 session id)。'),
+ queued_message_id: z.string().min(1).describe('来自 send_to_session 或 list_session_queue 的消息 id。'),
+ },
+ handler: async ({ session_id, queued_message_id }) => {
+ const callerSessionId = requireCallerSession(deps);
+ if (!callerSessionId) {
+ return errorPayload('NO_SESSION_CONTEXT', '当前 MCP 调用没有绑定 session,无法校验消息所有权。');
+ }
+ const result = await deps.steerQueuedMessage({
+ callerSessionId,
+ targetSessionId: session_id,
+ queuedMessageId: queued_message_id,
+ });
+ if (!result.ok) return mapControlFailure(result);
+ return okPayload({
+ session_id,
+ queued_message_id: result.queuedMessageId,
+ delivery: result.delivery,
+ ...(result.reason ? { reason: result.reason } : {}),
+ });
+ },
+ });
+}
+
+export function registerMoveSessionQueuedMessageTool(
+ registry: XdtHelperToolRegistry,
+ deps: SessionControlDeps,
+): void {
+ registry.register({
+ name: 'move_session_queued_message',
+ category: 'control',
+ description:
+ '把目标 session 中一条尚未消费的排队消息移到指定位置(0 = 队首,超出队列长度放到队尾),返回实际最终位置。' +
+ SESSION_QUEUE_MANAGEABLE_SCOPE,
+ inputShape: {
+ session_id: z.string().min(1).describe('目标 session id(操作自己任务的队列时传当前 session id)。'),
+ queued_message_id: z.string().min(1).describe('来自 send_to_session 或 list_session_queue 的消息 id。'),
+ position: z.number().int().min(0).describe('目标位置,0 = 队首;超出队列长度时放到队尾。'),
+ },
+ handler: async ({ session_id, queued_message_id, position }) => {
+ const callerSessionId = requireCallerSession(deps);
+ if (!callerSessionId) {
+ return errorPayload('NO_SESSION_CONTEXT', '当前 MCP 调用没有绑定 session,无法校验消息所有权。');
+ }
+ const result = await deps.moveQueuedMessage({
+ callerSessionId,
+ targetSessionId: session_id,
+ queuedMessageId: queued_message_id,
+ position,
+ });
+ if (!result.ok) return mapControlFailure(result);
+ return okPayload({
+ session_id,
+ queued_message_id: result.queuedMessageId,
+ position: result.position,
+ });
+ },
+ });
+}
+
export function registerSteerSessionTool(
registry: XdtHelperToolRegistry,
deps: SessionControlDeps,
diff --git a/packages/lizi-mcps/src/xdt-helper/steer_queued_message.ts b/packages/lizi-mcps/src/xdt-helper/steer_queued_message.ts
new file mode 100644
index 0000000000..1f5d592665
--- /dev/null
+++ b/packages/lizi-mcps/src/xdt-helper/steer_queued_message.ts
@@ -0,0 +1,95 @@
+/**
+ * xdt-helper/steer_queued_message.ts —— 把一条排队中的协同消息转为插话。
+ *
+ * 排队消息默认按顺序在目标下一次空闲时投递;本工具让 Lead 把其中一条提前插进
+ * 目标当前 turn(same-turn steer)。可操作范围与 update/cancel 同口径「只能动自己的」:
+ * worker 队列里只能操作 Lead 自己发的条目;省略 worker_id 时操作调用方自身队列里
+ * 的协同消息(Lead 收到的 Worker 回报,或 Worker 收到的 Lead 消息)。没插成时消息
+ * 原样留在队列,结果带 reason。
+ */
+
+import { z } from 'zod';
+
+import type { XdtHelperToolRegistry } from '../lizi_xdtHelperToolRegistry.js';
+import type { ControlResult } from '../types.js';
+import type { QueuedMessageControlErrorCode } from './update_queued_message.js';
+import { errorPayload, okPayload } from './_payload.js';
+
+/** 转插话未成功、消息仍留在队列时的原因。 */
+export type QueuedMessageSteerReason =
+ | 'NO_ACTIVE_TURN'
+ | 'STEER_UNSUPPORTED'
+ | 'INPUT_BOUNDARY_BUSY'
+ | 'STEER_UNCERTAIN';
+
+export interface SteerQueuedMessageDeps {
+ getSessionContext?: () => {
+ sessionId?: string;
+ };
+ steerWorkerQueuedMessage: (params: {
+ callerLeadSessionId: string;
+ /** 省略即操作调用方自己的输入队列。 */
+ workerRef?: string;
+ queuedMessageId: string;
+ }) => Promise<
+ ControlResult<
+ {
+ /** 操作调用方自身队列时为 null。 */
+ workerId: string | null;
+ queuedMessageId: string;
+ delivery: 'steered' | 'queued';
+ reason?: QueuedMessageSteerReason;
+ },
+ QueuedMessageControlErrorCode
+ >
+ >;
+}
+
+const DESCRIPTION =
+ '把一条排队中的协同消息插进目标当前 turn。只能操作你发的条目;省略 worker_id 时操作你自己队列里的协同消息。' +
+ 'delivery=queued 表示没插成、消息仍在队列,reason: NO_ACTIVE_TURN / STEER_UNSUPPORTED / ' +
+ 'INPUT_BOUNDARY_BUSY / STEER_UNCERTAIN(无法确认是否送达,队列已暂停)。' +
+ '失败码: LEAD_NOT_SUPPORTED / WORKER_NOT_FOUND / QUEUED_MESSAGE_NOT_FOUND / NOT_LEAD_MESSAGE / ' +
+ 'NOT_ORCA_MESSAGE / MESSAGE_CONSUMING。';
+
+export function registerSteerQueuedMessageTool(
+ registry: XdtHelperToolRegistry,
+ deps: SteerQueuedMessageDeps,
+): void {
+ registry.register({
+ name: 'steer_queued_message',
+ category: 'control',
+ description: DESCRIPTION,
+ inputShape: {
+ worker_id: z
+ .string()
+ .min(1)
+ .optional()
+ .describe('目标 worker 的 worker_id 或 session_id 任一;省略时操作你自己的输入队列'),
+ queued_message_id: z
+ .string()
+ .min(1)
+ .describe('要转插话的排队消息 id(来自排队回传或 get_worker_queue_status)'),
+ },
+ handler: async ({ worker_id, queued_message_id }) => {
+ const ctx = deps.getSessionContext?.();
+ if (!ctx?.sessionId) {
+ return errorPayload('LEAD_NOT_SUPPORTED', '当前 session 类型不支持作为 Lead, 已拒绝 worker 队列操作。');
+ }
+ const result = await deps.steerWorkerQueuedMessage({
+ callerLeadSessionId: ctx.sessionId,
+ ...(worker_id ? { workerRef: worker_id } : {}),
+ queuedMessageId: queued_message_id,
+ });
+ if (!result.ok) {
+ return errorPayload(result.errorCode, result.message);
+ }
+ return okPayload({
+ worker_id: result.workerId,
+ queued_message_id: result.queuedMessageId,
+ delivery: result.delivery,
+ ...(result.reason ? { reason: result.reason } : {}),
+ });
+ },
+ });
+}
diff --git a/packages/lizi-mcps/src/xdt-helper/update_queued_message.ts b/packages/lizi-mcps/src/xdt-helper/update_queued_message.ts
index f1ba8b5f7b..72d889eec3 100644
--- a/packages/lizi-mcps/src/xdt-helper/update_queued_message.ts
+++ b/packages/lizi-mcps/src/xdt-helper/update_queued_message.ts
@@ -11,11 +11,15 @@ import type { XdtHelperToolRegistry } from '../lizi_xdtHelperToolRegistry.js';
import type { ControlResult } from '../types.js';
import { errorPayload, okPayload } from './_payload.js';
-/** update / cancel 共用的失败码(与 host WorkerQueuedMessageFailureCode 同构)。 */
+/**
+ * update / cancel / merge / steer / move 共用的失败码(与 host WorkerQueuedMessageFailureCode 同构)。
+ * NOT_ORCA_MESSAGE 仅在操作调用方自身队列(省略 worker_id)时出现:目标条目不是协同消息。
+ */
export type QueuedMessageControlErrorCode =
| 'WORKER_NOT_FOUND'
| 'QUEUED_MESSAGE_NOT_FOUND'
| 'NOT_LEAD_MESSAGE'
+ | 'NOT_ORCA_MESSAGE'
| 'MESSAGE_CONSUMING'
| 'INVALID_ARGS';
@@ -37,7 +41,7 @@ const DESCRIPTION =
'修改一条尚未被 worker 消费的排队消息(整条正文替换)。' +
'queued_message_id 来自 send_to_worker / create_worker 的排队回传或 get_worker_queue_status。' +
'只能修改你自己(lead)发出的排队条目;用户或 scheduler 的排队消息不可修改。' +
- '需要把多条相关消息合成一条时用 merge_queued_messages,不要连续 update/cancel 模拟。' +
+ '需要把多条相关消息合成一条时用 merge_queued_messages,不要连续 update/cancel 模拟;转插话或调整顺序用 steer_queued_message / move_queued_message。' +
'失败码: LEAD_NOT_SUPPORTED / WORKER_NOT_FOUND / QUEUED_MESSAGE_NOT_FOUND(已被消费或已撤回) / ' +
'NOT_LEAD_MESSAGE / MESSAGE_CONSUMING(正在投递中)。';
diff --git a/packages/maker-shared/src/__tests__/queue.test.ts b/packages/maker-shared/src/__tests__/queue.test.ts
index 4008bbd609..1c741f5da6 100644
--- a/packages/maker-shared/src/__tests__/queue.test.ts
+++ b/packages/maker-shared/src/__tests__/queue.test.ts
@@ -242,11 +242,11 @@ describe('shared queue presentation model', () => {
},
queueLength: 2,
});
- // 对齐桌面:协同消息不能编辑或插话,但可以调整顺序和删除。
+ // 对齐桌面:协同消息不能编辑,但可以插话、调整顺序和删除。
expect(orca.title).toBe('协同队列 2');
expect(orca.hint).toBeNull();
- expect(orca.actions.steer.disabledReason).toBe('协同消息不支持编辑或插话发送。');
- expect(orca.actions.edit.disabledReason).toBe('协同消息不支持编辑或插话发送。');
+ expect(orca.actions.steer).toMatchObject({ disabled: false, disabledReason: null });
+ expect(orca.actions.edit.disabledReason).toBe('协同消息不支持编辑。');
expect(orca.actions.remove.disabled).toBe(false);
expect(orca.actions.moveUp.disabled).toBe(false);
expect(orca.actions.moveDown).toMatchObject({ disabled: true, disabledReason: '已经是队列最后一条。' });
diff --git a/packages/maker-shared/src/queue.ts b/packages/maker-shared/src/queue.ts
index b4a7145161..3b9dcc8993 100644
--- a/packages/maker-shared/src/queue.ts
+++ b/packages/maker-shared/src/queue.ts
@@ -138,21 +138,23 @@ export function buildQueueRowPresentation(input: {
// 照常——用户可以取消一条排队中的续跑,但不能改写或抢发它的内容。
const syntheticEditReason = syntheticKind
? presentationText(localizer, 'message.queuePresentation.row.syntheticEditDisabled', '系统指令消息不支持编辑或插话发送。')
- : orcaOrigin
- // 协同成员发来的消息(对齐桌面 canEdit / canSteer=false):删除与排序照常。
- ? presentationText(localizer, 'message.queuePresentation.row.orcaEditDisabled', '协同消息不支持编辑或插话发送。')
- : isAutoSentQueueItem(input.item)
- // 自动化 / 其他任务经工具 / 插件排进来的消息(对齐桌面 canEdit / canSteer=false):改写后
- // 落库气泡的来源标签就不再属实;删除与排序照常。
- ? presentationText(localizer, 'message.queuePresentation.row.autoSentEditDisabled', '自动发送的消息不支持编辑或插话发送。')
- : null;
+ : null;
+ // 自动化 / 其他任务经工具 / 插件排进来的消息(对齐桌面 canEdit / canSteer=false):改写后
+ // 落库气泡的来源标签就不再属实;删除与排序照常。
+ const autoSentReason = !orcaOrigin && isAutoSentQueueItem(input.item)
+ ? presentationText(localizer, 'message.queuePresentation.row.autoSentEditDisabled', '自动发送的消息不支持编辑或插话发送。')
+ : null;
+ // 协同成员发来的消息不能改写(对齐桌面 canEdit=false),但可以插话:插话不改正文与来源。
+ const orcaEditReason = orcaOrigin
+ ? presentationText(localizer, 'message.queuePresentation.row.orcaEditDisabled', '协同消息不支持编辑。')
+ : null;
return {
actions: {
moveUp: queueRowAction(baseDisabledReason, moveUpTarget, presentationText(localizer, 'message.queuePresentation.row.first', '已经是队列第一条。')),
moveDown: queueRowAction(baseDisabledReason, moveDownTarget, presentationText(localizer, 'message.queuePresentation.row.last', '已经是队列最后一条。')),
- steer: queueRowAction(baseDisabledReason ?? syntheticEditReason),
- edit: queueRowAction(baseDisabledReason ?? syntheticEditReason),
+ steer: queueRowAction(baseDisabledReason ?? syntheticEditReason ?? autoSentReason),
+ edit: queueRowAction(baseDisabledReason ?? syntheticEditReason ?? autoSentReason ?? orcaEditReason),
remove: queueRowAction(baseDisabledReason),
},
editLocked,
diff --git a/packages/orca-workflow/src/__tests__/orca-bridge-mcp.test.ts b/packages/orca-workflow/src/__tests__/orca-bridge-mcp.test.ts
index a4899a7396..6a2000756c 100644
--- a/packages/orca-workflow/src/__tests__/orca-bridge-mcp.test.ts
+++ b/packages/orca-workflow/src/__tests__/orca-bridge-mcp.test.ts
@@ -288,6 +288,8 @@ describe('orca_worker_bridge MCP helpers', () => {
expect(SEND_TO_LEAD_TOOL_DESCRIPTION).toContain('final report or one blocking question');
expect(SEND_TO_LEAD_TOOL_DESCRIPTION).toContain('After a question, stop and wait for send_to_worker');
expect(SEND_TO_LEAD_TOOL_DESCRIPTION).toContain('do not send progress');
+ expect(SEND_TO_LEAD_TOOL_DESCRIPTION).toContain('delivery=steer');
+ expect(SEND_TO_LEAD_TOOL_DESCRIPTION).toContain('otherwise keep the default');
expect(SEND_TO_LEAD_TOOL_DESCRIPTION).not.toContain('root Orca Worker');
expect(SEND_TO_LEAD_TOOL_DESCRIPTION.length).toBeLessThan(700);
});
@@ -447,7 +449,7 @@ describe('orca_worker_bridge MCP helpers', () => {
expect(readLeadHistory).toHaveBeenCalledTimes(1);
});
- function makeWorkerBridgeLeadHarness(lead: FakeSession) {
+ function makeWorkerBridgeLeadHarness(lead: FakeSession, dispatchInterAgentMessage?: OrcaBridgeMcpDeps['dispatchInterAgentMessage']) {
const logger = makeLogger();
const workerLink: OrcaWorkerLink = {
workerId: 'worker-1',
@@ -467,6 +469,7 @@ describe('orca_worker_bridge MCP helpers', () => {
workerLink,
});
const workerProvider = createOrcaWorkerBridgeMcpProvider({
+ dispatchInterAgentMessage,
getMaker: () => base.maker as unknown as Maker,
logger: logger as never,
persistUserMessage: async (sessionId, message) => {
@@ -569,6 +572,83 @@ describe('orca_worker_bridge MCP helpers', () => {
expect(lead.sent).toHaveLength(1);
});
+ it.each(['dispatched', 'queued', 'steered'] as const)('settles host-owned %s reports without waiting for lead completion', async mode => {
+ const lead = makeSession('lead-1');
+ lead.turnRunning = true;
+ let accepted: (() => void | Promise<void>) | undefined;
+ const dispatch = vi.fn<NonNullable<OrcaBridgeMcpDeps['dispatchInterAgentMessage']>>(async params => {
+ accepted = params.onAccepted;
+ if (mode === 'dispatched') await accepted?.();
+ return { ok: true, mode, clientId: 'report-client' };
+ });
+ const h = makeWorkerBridgeLeadHarness(lead, dispatch);
+ const json = parseToolJson(await h.server._registeredTools.send_to_lead.handler({
+ worker_id: 'worker-1', message: 'Completed work',
+ ...(mode === 'steered' ? { delivery: 'steer' } : {}),
+ }));
+ expect(json).toMatchObject({ ok: true });
+ expect(json.queued).toBe(mode === 'queued' ? true : undefined);
+ expect(json.steered).toBe(mode === 'steered' ? true : undefined);
+ expect(json).not.toHaveProperty('steer_fallback_reason');
+ expect(lead.isTurnRunning()).toBe(true);
+ expect(lead.sent).toEqual([]);
+ expect(h.statusUpdates).toEqual([{ workerId: 'worker-1', status: 'done' }]);
+ // A retained queue row can drain after the worker has received a new task.
+ // Its old accepted callback must not settle that newer task again.
+ await accepted?.();
+ expect(h.statusUpdates).toHaveLength(1);
+ });
+
+ it('forwards explicit send_to_lead delivery and omits it when the worker keeps the default', async () => {
+ const dispatch = vi.fn<NonNullable<OrcaBridgeMcpDeps['dispatchInterAgentMessage']>>(async () => ({
+ ok: true,
+ mode: 'queued',
+ clientId: 'report-client',
+ }));
+ const h = makeWorkerBridgeLeadHarness(makeSession('lead-1'), dispatch);
+
+ await h.server._registeredTools.send_to_lead.handler({ worker_id: 'worker-1', message: 'plain report' });
+ expect(dispatch.mock.calls[0]?.[0]).not.toHaveProperty('delivery');
+
+ await h.server._registeredTools.send_to_lead.handler({
+ worker_id: 'worker-1', message: 'urgent correction', delivery: 'steer',
+ });
+ expect(dispatch.mock.calls[1]?.[0]).toMatchObject({
+ rawContent: 'urgent correction',
+ source: 'worker',
+ delivery: 'steer',
+ });
+ });
+
+ it('reports a queued steer fallback reason and still settles the worker report', async () => {
+ const dispatch = vi.fn<NonNullable<OrcaBridgeMcpDeps['dispatchInterAgentMessage']>>(async () => ({
+ ok: true,
+ mode: 'queued',
+ clientId: 'report-client',
+ steerFallbackReason: 'STEER_UNSUPPORTED',
+ }));
+ const h = makeWorkerBridgeLeadHarness(makeSession('lead-1'), dispatch);
+
+ expect(parseToolJson(await h.server._registeredTools.send_to_lead.handler({
+ worker_id: 'worker-1', message: 'urgent correction', delivery: 'steer',
+ }))).toEqual({
+ ok: true,
+ queued: true,
+ steer_fallback_reason: 'STEER_UNSUPPORTED',
+ worker_id: 'worker-1',
+ lead_session_id: 'lead-1',
+ });
+ expect(h.statusUpdates).toEqual([{ workerId: 'worker-1', status: 'done' }]);
+ });
+
+ it('does not settle the worker report when host dispatch is rejected', async () => {
+ const h = makeWorkerBridgeLeadHarness(makeSession('lead-1'), async () => ({ ok: false,
+ dispatchOutcome: { kind: 'host-send', accepted: false, code: 'SEND_FAILED', message: 'rejected' },
+ }));
+ expectToolError(await h.server._registeredTools.send_to_lead.handler({ worker_id: 'worker-1', message: 'result' }));
+ expect(h.statusUpdates).toEqual([]);
+ });
+
it('hydrates lead provider route before cold send_to_lead creates the lead session', async () => {
const order: string[] = [];
const hydrateSessionRoute = vi.fn(async (sessionId: string, providerId: string | null) => {
diff --git a/packages/orca-workflow/src/index.ts b/packages/orca-workflow/src/index.ts
index b444bcc3e0..a47b0b09b0 100644
--- a/packages/orca-workflow/src/index.ts
+++ b/packages/orca-workflow/src/index.ts
@@ -7,7 +7,9 @@ export {
type OrcaLeadHistoryMessage,
type OrcaLeadHistoryPage,
type OrcaLeadVendorOptions,
+ type OrcaMessageDelivery,
type OrcaPersistedSession,
+ type OrcaSteerFallbackReason,
type OrcaTeamStore,
type OrcaWorkerLink,
type OrcaWorkerStatus,
diff --git a/packages/orca-workflow/src/orca-bridge-mcp.ts b/packages/orca-workflow/src/orca-bridge-mcp.ts
index deb1915c2b..fbeba9df1e 100644
--- a/packages/orca-workflow/src/orca-bridge-mcp.ts
+++ b/packages/orca-workflow/src/orca-bridge-mcp.ts
@@ -168,6 +168,8 @@ export interface OrcaBridgeMcpDeps {
source: 'lead' | 'worker';
senderLabel: string;
workerId?: string;
+ /** 仅 send_to_lead 显式选择时传入;缺省(含 auto-bridge 自动补报)等价 'queue'。 */
+ delivery?: OrcaMessageDelivery;
onAccepted?: () => void | Promise<void>;
onAcceptedRollback?: () => void | Promise<void>;
meta: {
@@ -176,15 +178,23 @@ export interface OrcaBridgeMcpDeps {
};
}) => Promise<{
ok: true;
- mode: 'dispatched' | 'queued';
+ mode: 'dispatched' | 'queued' | 'steered';
clientId: string;
dispatchOutcome?: unknown;
+ /** 请求 steer 但消息进了队列时的原因;空闲直发不带。 */
+ steerFallbackReason?: OrcaSteerFallbackReason;
} | {
ok: false;
dispatchOutcome?: unknown;
}>;
}
+/** 协同消息投递方式:queue = 普通直发/排队(缺省),steer = 尝试插进对方当前 turn。 */
+export type OrcaMessageDelivery = 'queue' | 'steer';
+
+/** 请求 steer 但未插成、消息进入队列时的原因。 */
+export type OrcaSteerFallbackReason = 'STEER_UNSUPPORTED' | 'INPUT_BOUNDARY_BUSY' | 'STEER_UNCERTAIN';
+
function text(data: unknown, isError = false) {
return {
content: [{ type: 'text' as const, text: JSON.stringify(data) }],
@@ -195,7 +205,12 @@ function text(data: unknown, isError = false) {
type OrcaToolResult = ReturnType<typeof text>;
type OrcaSendSource = 'mcp-tool' | 'auto-bridge';
-type HostOrcaDispatch = { hostDispatched: true; queued: boolean };
+type HostOrcaDispatch = {
+ hostDispatched: true;
+ queued: boolean;
+ steered: boolean;
+ steerFallbackReason?: OrcaSteerFallbackReason;
+};
interface OrcaSendMeta {
source: OrcaSendSource;
@@ -228,6 +243,7 @@ export const SEND_TO_LEAD_TOOL_DESCRIPTION = [
'Call once per turn, only with the final report or one blocking question.',
'After a question, stop and wait for send_to_worker.',
'Combine all results; do not send progress, partial findings, or same-turn corrections.',
+ 'If the Lead is blocked waiting on this report, delivery=steer delivers it into the Lead\'s current turn; otherwise keep the default.',
].join(' ');
export function authorizeSendToLeadCaller(ctx: McpProviderContext):
@@ -347,6 +363,7 @@ async function dispatchOrcaToolMessage(input: {
rawContent?: string;
source?: 'lead' | 'worker';
senderLabel?: string;
+ delivery?: OrcaMessageDelivery;
log: Logger;
meta: OrcaSendMeta;
errorExtra?: Record<string, unknown>;
@@ -366,6 +383,7 @@ async function dispatchOrcaToolMessage(input: {
source: input.source,
senderLabel: input.senderLabel,
workerId: input.meta.workerId,
+ ...(input.delivery ? { delivery: input.delivery } : {}),
onAccepted: input.hostOnAccepted ?? input.onAccepted,
onAcceptedRollback: input.hostOnAcceptedRollback,
meta: {
@@ -373,7 +391,14 @@ async function dispatchOrcaToolMessage(input: {
context: input.meta.context,
},
});
- if (result.ok) return { hostDispatched: true, queued: result.mode === 'queued' };
+ if (result.ok) {
+ return {
+ hostDispatched: true,
+ queued: result.mode === 'queued',
+ steered: result.mode === 'steered',
+ ...(result.steerFallbackReason ? { steerFallbackReason: result.steerFallbackReason } : {}),
+ };
+ }
const meta = readMeta();
logOrcaSendNotDispatched(input.log, meta, 'send-rejected', {
dispatchOutcome: result.dispatchOutcome,
@@ -736,8 +761,12 @@ export function createOrcaWorkerBridgeMcpProvider(deps: OrcaBridgeMcpDeps): McpP
{
message: z.string().min(1),
worker_id: z.string().min(1).describe('Required. Your assigned worker_id. Find it in the Bridge note at the end of the most recent lead message, or in the system prompt Identity line.'),
+ delivery: z
+ .enum(['queue', 'steer'])
+ .optional()
+ .describe('queue (default) = deliver now or queue behind the Lead\'s current turn; steer = try to enter the Lead\'s current turn.'),
},
- async ({ message, worker_id }) => {
+ async ({ message, worker_id, delivery }) => {
const authorization = authorizeSendToLeadCaller(resolveRuntimeMcpContext(ctx));
if (!authorization.ok) return text(authorization.error, true);
const resolved = await resolveLead(worker_id);
@@ -790,6 +819,7 @@ export function createOrcaWorkerBridgeMcpProvider(deps: OrcaBridgeMcpDeps): McpP
rawContent: message,
source: 'worker',
senderLabel: link.workerId,
+ ...(delivery ? { delivery } : {}),
log,
meta: {
source: 'mcp-tool',
@@ -817,10 +847,15 @@ export function createOrcaWorkerBridgeMcpProvider(deps: OrcaBridgeMcpDeps): McpP
},
});
if (isHostOrcaDispatch(dispatchError)) {
- if (dispatchError.queued) settleWorkerReport();
+ // 排队与插话都视为已回报;直发仍由 hostOnAccepted 结清(settle 幂等)。
+ if (dispatchError.queued || dispatchError.steered) settleWorkerReport();
return text({
ok: true,
+ ...(dispatchError.steered ? { steered: true } : {}),
...(dispatchError.queued ? { queued: true } : {}),
+ ...(dispatchError.queued && dispatchError.steerFallbackReason
+ ? { steer_fallback_reason: dispatchError.steerFallbackReason }
+ : {}),
worker_id: link.workerId,
lead_session_id: link.leadSessionId,
});