@zhin.js/agent 0.3.1 → 1.0.2

package/lib/turn/multimodal-message.js

@@ -0,0 +1,72 @@
+/**
+ * ContentPart[] → agentLoop UserMessage（ADR 0009 D2：image blocks）
+ */
+import { createUserMessage } from '@zhin.js/ai';
+import { normalizeContentPartsToPayloads } from '../media/media-normalize.js';
+function parseDataUri(dataUri) {
+    const m = /^data:([^;]+);base64,(.+)$/i.exec(dataUri.trim());
+    if (!m)
+        return null;
+    return { mime: m[1], base64: m[2] };
+}
+function imageUrlToContent(url) {
+    const parsed = parseDataUri(url);
+    if (parsed) {
+        return { type: 'image', data: parsed.base64, mimeType: parsed.mime };
+    }
+    if (url.startsWith('http://') || url.startsWith('https://')) {
+        return { type: 'image', data: url, mimeType: 'image/jpeg' };
+    }
+    return null;
+}
+/** 从 ContentPart 拼会话可见文本（含 [图片] 等占位） */
+export function summarizeMultimodalParts(parts, supportsVision) {
+    const fragments = [];
+    for (const p of parts) {
+        switch (p.type) {
+            case 'text':
+                fragments.push(p.text);
+                break;
+            case 'image_url':
+                fragments.push('[图片]');
+                break;
+            case 'video_url':
+                fragments.push('[视频]');
+                break;
+            case 'audio':
+                fragments.push('[音频]');
+                break;
+            case 'face':
+                fragments.push(p.face.text || `[表情:${p.face.id}]`);
+                break;
+        }
+    }
+    return fragments.join(' ') || '[多模态消息]';
+}
+/** 构建带 image blocks 的 UserMessage（vision 模型走 agentLoop） */
+export async function buildVisionUserMessage(sessionUserContent, parts, supportsVision, maxFileBytes) {
+    const images = [];
+    if (supportsVision) {
+        const payloads = await normalizeContentPartsToPayloads(parts, maxFileBytes);
+        for (const payload of payloads) {
+            if (payload.kind === 'image') {
+                images.push({
+                    type: 'image',
+                    data: payload.base64,
+                    mimeType: payload.mimeType,
+                });
+            }
+        }
+        if (images.length === 0) {
+            for (const p of parts) {
+                if (p.type !== 'image_url')
+                    continue;
+                const block = imageUrlToContent(p.image_url.url);
+                if (block)
+                    images.push(block);
+            }
+        }
+    }
+    return createUserMessage(sessionUserContent, images.length > 0 ? images : undefined);
+}
+//# sourceMappingURL=multimodal-message.js.map

package/lib/turn/multimodal-message.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"multimodal-message.js","sourceRoot":"","sources":["../../src/turn/multimodal-message.ts"],"names":[],"mappings":"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"}

package/lib/turn/persist-deferred-context.d.ts

@@ -0,0 +1,5 @@
+import type { DeferredWorkerResult } from '../deferred-worker-runner.js';
+import type { Message } from '../orchestrator/types.js';
+import type { ZhinAgentPrivate } from '../internal/agent-host.js';
+export declare function persistDeferredWorkerResultToContext(agent: ZhinAgentPrivate, commMessage: Message, taskId: string, goal: string, result: DeferredWorkerResult): Promise<boolean>;
+//# sourceMappingURL=persist-deferred-context.d.ts.map

package/lib/turn/persist-deferred-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persist-deferred-context.d.ts","sourceRoot":"","sources":["../../src/turn/persist-deferred-context.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAGzE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAGlE,wBAAsB,oCAAoC,CACxD,KAAK,EAAE,gBAAgB,EACvB,WAAW,EAAE,OAAO,EACpB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,OAAO,CAAC,CA0BlB"}

package/lib/turn/persist-deferred-context.js

@@ -0,0 +1,35 @@
+/**
+ * Deferred worker 完成后将结果写入主会话 ContextRepository，
+ * 避免下一轮主 Agent 仍只看到 run_deferred_task 的 delegated 占位。
+ */
+import { EMPTY_TOKEN_USAGE, } from '@zhin.js/ai';
+import { resolveAgentTurnSessionKey } from '../collaboration/resolve-agent-session-key.js';
+import { resolveSubagentDisplayLabel } from '../subagent-goal-notify.js';
+import { packageSubagentResult } from '../subagent-artifact.js';
+import { extractDeferredBody } from './deferred-delivery.js';
+export async function persistDeferredWorkerResultToContext(agent, commMessage, taskId, goal, result) {
+    const body = extractDeferredBody(result);
+    if (!body.trim())
+        return false;
+    const sessionKey = resolveAgentTurnSessionKey(commMessage);
+    const active = await agent.agentSessionStore.findActive(sessionKey);
+    const sessionId = active?.session_id;
+    if (!sessionId)
+        return false;
+    const label = resolveSubagentDisplayLabel(undefined, goal);
+    const packaged = packageSubagentResult(body, taskId);
+    const text = `[Deferred worker 完成 · task:${taskId} · ${label}]\n\n${packaged.text}`;
+    const assistantMessage = {
+        role: 'assistant',
+        content: [{ type: 'text', text }],
+        api: 'openai-completions',
+        provider: 'deferred-worker',
+        model: 'worker',
+        usage: EMPTY_TOKEN_USAGE,
+        stopReason: 'stop',
+        timestamp: Date.now(),
+    };
+    await agent.contextRepository.appendMessages(sessionId, [assistantMessage]);
+    return true;
+}
+//# sourceMappingURL=persist-deferred-context.js.map

package/lib/turn/persist-deferred-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persist-deferred-context.js","sourceRoot":"","sources":["../../src/turn/persist-deferred-context.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACL,iBAAiB,GAElB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,0BAA0B,EAAE,MAAM,+CAA+C,CAAC;AAE3F,OAAO,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAGhE,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAE7D,MAAM,CAAC,KAAK,UAAU,oCAAoC,CACxD,KAAuB,EACvB,WAAoB,EACpB,MAAc,EACd,IAAY,EACZ,MAA4B;IAE5B,MAAM,IAAI,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;IACzC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;QAAE,OAAO,KAAK,CAAC;IAE/B,MAAM,UAAU,GAAG,0BAA0B,CAAC,WAAW,CAAC,CAAC;IAC3D,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,iBAAiB,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;IACpE,MAAM,SAAS,GAAG,MAAM,EAAE,UAAU,CAAC;IACrC,IAAI,CAAC,SAAS;QAAE,OAAO,KAAK,CAAC;IAE7B,MAAM,KAAK,GAAG,2BAA2B,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAC3D,MAAM,QAAQ,GAAG,qBAAqB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACrD,MAAM,IAAI,GAAG,8BAA8B,MAAM,MAAM,KAAK,QAAQ,QAAQ,CAAC,IAAI,EAAE,CAAC;IAEpF,MAAM,gBAAgB,GAAqB;QACzC,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;QACjC,GAAG,EAAE,oBAAoB;QACzB,QAAQ,EAAE,iBAAiB;QAC3B,KAAK,EAAE,QAAQ;QACf,KAAK,EAAE,iBAAiB;QACxB,UAAU,EAAE,MAAM;QAClB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;KACtB,CAAC;IAEF,MAAM,KAAK,CAAC,iBAAiB,CAAC,cAAc,CAAC,SAAS,EAAE,CAAC,gBAAgB,CAAC,CAAC,CAAC;IAC5E,OAAO,IAAI,CAAC;AACd,CAAC"}

package/lib/turn/persist-subagent-context.d.ts

@@ -0,0 +1,5 @@
+import type { SubagentCompletePayload } from '../subagent/index.js';
+import type { Message } from '../orchestrator/types.js';
+import type { ZhinAgentPrivate } from '../internal/agent-host.js';
+export declare function persistSubagentResultToContext(agent: ZhinAgentPrivate, commMessage: Message, payload: SubagentCompletePayload): Promise<boolean>;
+//# sourceMappingURL=persist-subagent-context.d.ts.map

package/lib/turn/persist-subagent-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persist-subagent-context.d.ts","sourceRoot":"","sources":["../../src/turn/persist-subagent-context.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAEpE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,wBAAsB,8BAA8B,CAClD,KAAK,EAAE,gBAAgB,EACvB,WAAW,EAAE,OAAO,EACpB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,OAAO,CAAC,CA8BlB"}

package/lib/turn/persist-subagent-context.js

@@ -0,0 +1,36 @@
+/**
+ * Persist async subagent result into main session context before auto-continue.
+ */
+import { EMPTY_TOKEN_USAGE, } from '@zhin.js/ai';
+import { resolveAgentTurnSessionKey } from '../collaboration/resolve-agent-session-key.js';
+import { packageSubagentResult } from '../subagent-artifact.js';
+export async function persistSubagentResultToContext(agent, commMessage, payload) {
+    const body = payload.result.trim();
+    if (!body)
+        return false;
+    const sessionKey = resolveAgentTurnSessionKey(commMessage);
+    const active = await agent.agentSessionStore.findActive(sessionKey);
+    const sessionId = active?.session_id;
+    if (!sessionId)
+        return false;
+    const packaged = packageSubagentResult(body, payload.taskId);
+    const text = [
+        `[Subagent completed · task:${payload.taskId} · ${payload.label}]`,
+        `status: ${payload.status}`,
+        '',
+        packaged.text,
+    ].join('\n');
+    const assistantMessage = {
+        role: 'assistant',
+        content: [{ type: 'text', text }],
+        api: 'openai-completions',
+        provider: 'subagent',
+        model: payload.agent ?? 'subagent',
+        usage: EMPTY_TOKEN_USAGE,
+        stopReason: 'stop',
+        timestamp: Date.now(),
+    };
+    await agent.contextRepository.appendMessages(sessionId, [assistantMessage]);
+    return true;
+}
+//# sourceMappingURL=persist-subagent-context.js.map

package/lib/turn/persist-subagent-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persist-subagent-context.js","sourceRoot":"","sources":["../../src/turn/persist-subagent-context.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EACL,iBAAiB,GAElB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,0BAA0B,EAAE,MAAM,+CAA+C,CAAC;AAE3F,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAIhE,MAAM,CAAC,KAAK,UAAU,8BAA8B,CAClD,KAAuB,EACvB,WAAoB,EACpB,OAAgC;IAEhC,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACnC,IAAI,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IAExB,MAAM,UAAU,GAAG,0BAA0B,CAAC,WAAW,CAAC,CAAC;IAC3D,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,iBAAiB,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;IACpE,MAAM,SAAS,GAAG,MAAM,EAAE,UAAU,CAAC;IACrC,IAAI,CAAC,SAAS;QAAE,OAAO,KAAK,CAAC;IAE7B,MAAM,QAAQ,GAAG,qBAAqB,CAAC,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7D,MAAM,IAAI,GAAG;QACX,8BAA8B,OAAO,CAAC,MAAM,MAAM,OAAO,CAAC,KAAK,GAAG;QAClE,WAAW,OAAO,CAAC,MAAM,EAAE;QAC3B,EAAE;QACF,QAAQ,CAAC,IAAI;KACd,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEb,MAAM,gBAAgB,GAAqB;QACzC,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;QACjC,GAAG,EAAE,oBAAoB;QACzB,QAAQ,EAAE,UAAU;QACpB,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,UAAU;QAClC,KAAK,EAAE,iBAAiB;QACxB,UAAU,EAAE,MAAM;QAClB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;KACtB,CAAC;IAEF,MAAM,KAAK,CAAC,iBAAiB,CAAC,cAAc,CAAC,SAAS,EAAE,CAAC,gBAAgB,CAAC,CAAC,CAAC;IAC5E,OAAO,IAAI,CAAC;AACd,CAAC"}

package/lib/turn/process-stream.d.ts

@@ -0,0 +1,14 @@
+import type { Message, Tool } from '../orchestrator/types.js';
+import type { TurnEvent } from '../event/turn-event.js';
+import type { InboundTurnQueue } from '../turn/inbound-turn-queue.js';
+import type { ResolvedInboundQueueConfig } from '../turn/inbound-queue-config.js';
+import type { ZhinAgentPrivate } from '../internal/agent-host.js';
+export declare function processTextTurnStream(agent: ZhinAgentPrivate, opts: {
+    content: string;
+    commMessage: Message;
+    externalTools: Tool[];
+    inboundQueueConfig: ResolvedInboundQueueConfig;
+    inboundTurnQueue: InboundTurnQueue;
+    runInTurnContext: <T>(turnId: string, fn: () => Promise<T>) => Promise<T>;
+}): AsyncGenerator<TurnEvent, void, undefined>;
+//# sourceMappingURL=process-stream.d.ts.map

package/lib/turn/process-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-stream.d.ts","sourceRoot":"","sources":["../../src/turn/process-stream.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAGlF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,wBAAuB,qBAAqB,CAC1C,KAAK,EAAE,gBAAgB,EACvB,IAAI,EAAE;IACJ,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,EAAE,IAAI,EAAE,CAAC;IACtB,kBAAkB,EAAE,0BAA0B,CAAC;IAC/C,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,gBAAgB,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CAC3E,GACA,cAAc,CAAC,SAAS,EAAE,IAAI,EAAE,SAAS,CAAC,CA0D5C"}

package/lib/turn/process-stream.js

@@ -0,0 +1,56 @@
+import { randomUUID } from 'node:crypto';
+import { resolveIMSessionIdFromMessage } from '@zhin.js/core';
+import { runWithInboundQueue } from '../turn/inbound-queue-runtime.js';
+import { processTextTurn } from './turn-pipeline.js';
+export async function* processTextTurnStream(agent, opts) {
+    const { content, commMessage, externalTools, inboundQueueConfig, inboundTurnQueue, runInTurnContext } = opts;
+    const turnId = randomUUID();
+    const sessionId = resolveIMSessionIdFromMessage(commMessage);
+    yield { type: 'turn_start', sessionId, turnId };
+    const eventQueue = [];
+    let resolveWaiting;
+    let done = false;
+    let sawTurnEnd = false;
+    let finalOutput = [];
+    let finalError;
+    const onTurnEvent = (event) => {
+        if (event.type === 'turn_end')
+            sawTurnEnd = true;
+        eventQueue.push(event);
+        resolveWaiting?.();
+    };
+    const runPromise = runInTurnContext(turnId, () => runWithInboundQueue(commMessage, inboundQueueConfig, inboundTurnQueue, {
+        content,
+        run: (mergedContent) => processTextTurn(agent, mergedContent, commMessage, externalTools, undefined, { onTurnEvent }),
+    })).then((output) => {
+        finalOutput = output;
+        done = true;
+        resolveWaiting?.();
+    }).catch((err) => {
+        finalError = err instanceof Error ? err : new Error(String(err));
+        done = true;
+        resolveWaiting?.();
+    });
+    while (!done || eventQueue.length > 0) {
+        if (eventQueue.length > 0) {
+            yield eventQueue.shift();
+            continue;
+        }
+        if (!done) {
+            await new Promise((resolve) => { resolveWaiting = resolve; });
+            resolveWaiting = undefined;
+        }
+    }
+    if (finalError) {
+        yield { type: 'error', error: finalError, recoverable: false };
+    }
+    else if (!sawTurnEnd) {
+        yield {
+            type: 'turn_end',
+            output: finalOutput,
+            usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+        };
+    }
+    await runPromise.catch(() => { });
+}
+//# sourceMappingURL=process-stream.js.map

package/lib/turn/process-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-stream.js","sourceRoot":"","sources":["../../src/turn/process-stream.ts"],"names":[],"mappings":"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"}

package/lib/turn/prompt-access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-access.d.ts","sourceRoot":"","sources":["../../src/turn/prompt-access.ts"],"names":[],"mappings":"AAAA,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM;CAI5B"}

package/lib/turn/prompt-access.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-access.js","sourceRoot":"","sources":["../../src/turn/prompt-access.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAChD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF"}

package/lib/turn/prompt-api.d.ts

@@ -0,0 +1,14 @@
+import type { AgentMessage, ImageContent, OutputElement } from '@zhin.js/ai';
+import type { Message } from '../orchestrator/types.js';
+import type { OnChunkCallback } from '../config/index.js';
+import type { PromptController } from '../turn/prompt-controller.js';
+import type { ZhinAgentEventEmitter } from '../event/event-emitter.js';
+import type { ZhinAgentPrivate } from '../internal/agent-host.js';
+export declare function assertMasterForPromptControl(emitter: ZhinAgentEventEmitter, commMessage: Message): void;
+export declare function runPromptTurn(agent: ZhinAgentPrivate, input: string | AgentMessage | AgentMessage[], commMessage: Message, runInTurnContext: <T>(turnId: string, fn: () => Promise<T>) => Promise<T>, options?: {
+    images?: ImageContent[];
+    onChunk?: OnChunkCallback;
+}): Promise<OutputElement[]>;
+export declare function steerMessage(promptController: PromptController, emitter: ZhinAgentEventEmitter, message: AgentMessage, commMessage: Message): void;
+export declare function followUpMessage(promptController: PromptController, emitter: ZhinAgentEventEmitter, message: AgentMessage, commMessage: Message): void;
+//# sourceMappingURL=prompt-api.d.ts.map

package/lib/turn/prompt-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-api.d.ts","sourceRoot":"","sources":["../../src/turn/prompt-api.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAe,MAAM,aAAa,CAAC;AAC1F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAKxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClE,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,qBAAqB,EAC9B,WAAW,EAAE,OAAO,GACnB,IAAI,CAcN;AAED,wBAAsB,aAAa,CACjC,KAAK,EAAE,gBAAgB,EACvB,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,YAAY,EAAE,EAC7C,WAAW,EAAE,OAAO,EACpB,gBAAgB,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EACzE,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,YAAY,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,eAAe,CAAA;CAAE,GAC/D,OAAO,CAAC,aAAa,EAAE,CAAC,CAiB1B;AAED,wBAAgB,YAAY,CAC1B,gBAAgB,EAAE,gBAAgB,EAClC,OAAO,EAAE,qBAAqB,EAC9B,OAAO,EAAE,YAAY,EACrB,WAAW,EAAE,OAAO,GACnB,IAAI,CAIN;AAED,wBAAgB,eAAe,CAC7B,gBAAgB,EAAE,gBAAgB,EAClC,OAAO,EAAE,qBAAqB,EAC9B,OAAO,EAAE,YAAY,EACrB,WAAW,EAAE,OAAO,GACnB,IAAI,CAIN"}

package/lib/turn/prompt-api.js

@@ -0,0 +1,51 @@
+import { randomUUID } from 'node:crypto';
+import { resolveIMSessionIdFromMessage } from '@zhin.js/core';
+import { PromptAccessDeniedError } from './prompt-access.js';
+import { resolveToolRequesterRole } from '../security/owner-approve-always-store.js';
+import { normalizePromptMessages } from './prompt-input.js';
+import { processTextTurn } from '../turn/turn-pipeline.js';
+export function assertMasterForPromptControl(emitter, commMessage) {
+    const plugin = emitter.getHostPlugin();
+    if (!plugin) {
+        throw new PromptAccessDeniedError('steer/followUp 需要有效的 master 上下文');
+    }
+    try {
+        const role = resolveToolRequesterRole(plugin, commMessage);
+        if (role !== 'master') {
+            throw new PromptAccessDeniedError('steer/followUp 仅 master 可用');
+        }
+    }
+    catch (error) {
+        if (error instanceof PromptAccessDeniedError)
+            throw error;
+        throw new PromptAccessDeniedError('steer/followUp 需要有效的 master 上下文');
+    }
+}
+export async function runPromptTurn(agent, input, commMessage, runInTurnContext, options) {
+    const messages = normalizePromptMessages(input, options?.images);
+    const text = messages
+        .flatMap((message) => {
+        if (message.role !== 'user')
+            return [];
+        const user = message;
+        return user.content
+            .filter((block) => block.type === 'text')
+            .map((block) => block.text);
+    })
+        .join('\n')
+        .trim();
+    return runInTurnContext(randomUUID(), () => processTextTurn(agent, text, commMessage, [], options?.onChunk, {
+        prebuiltMessages: messages,
+    }));
+}
+export function steerMessage(promptController, emitter, message, commMessage) {
+    assertMasterForPromptControl(emitter, commMessage);
+    const sessionKey = resolveIMSessionIdFromMessage(commMessage);
+    promptController.steer(sessionKey, message);
+}
+export function followUpMessage(promptController, emitter, message, commMessage) {
+    assertMasterForPromptControl(emitter, commMessage);
+    const sessionKey = resolveIMSessionIdFromMessage(commMessage);
+    promptController.followUp(sessionKey, message);
+}
+//# sourceMappingURL=prompt-api.js.map

package/lib/turn/prompt-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-api.js","sourceRoot":"","sources":["../../src/turn/prompt-api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,6BAA6B,EAAe,MAAM,eAAe,CAAC;AAG3E,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,wBAAwB,EAAE,MAAM,2CAA2C,CAAC;AACrF,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAK3D,MAAM,UAAU,4BAA4B,CAC1C,OAA8B,EAC9B,WAAoB;IAEpB,MAAM,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IACvC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,uBAAuB,CAAC,iCAAiC,CAAC,CAAC;IACvE,CAAC;IACD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,wBAAwB,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;QAC3D,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACtB,MAAM,IAAI,uBAAuB,CAAC,4BAA4B,CAAC,CAAC;QAClE,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,uBAAuB;YAAE,MAAM,KAAK,CAAC;QAC1D,MAAM,IAAI,uBAAuB,CAAC,iCAAiC,CAAC,CAAC;IACvE,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,KAAuB,EACvB,KAA6C,EAC7C,WAAoB,EACpB,gBAAyE,EACzE,OAAgE;IAEhE,MAAM,QAAQ,GAAG,uBAAuB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IACjE,MAAM,IAAI,GAAG,QAAQ;SAClB,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QACnB,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM;YAAE,OAAO,EAAc,CAAC;QACnD,MAAM,IAAI,GAAG,OAAsB,CAAC;QACpC,OAAO,IAAI,CAAC,OAAO;aAChB,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC;aACxC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC;SACV,IAAI,EAAE,CAAC;IACV,OAAO,gBAAgB,CAAC,UAAU,EAAE,EAAE,GAAG,EAAE,CACzC,eAAe,CAAC,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE;QAC9D,gBAAgB,EAAE,QAAQ;KAC3B,CAAC,CACH,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,gBAAkC,EAClC,OAA8B,EAC9B,OAAqB,EACrB,WAAoB;IAEpB,4BAA4B,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IACnD,MAAM,UAAU,GAAG,6BAA6B,CAAC,WAAW,CAAC,CAAC;IAC9D,gBAAgB,CAAC,KAAK,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,gBAAkC,EAClC,OAA8B,EAC9B,OAAqB,EACrB,WAAoB;IAEpB,4BAA4B,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IACnD,MAAM,UAAU,GAAG,6BAA6B,CAAC,WAAW,CAAC,CAAC;IAC9D,gBAAgB,CAAC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;AACjD,CAAC"}

package/lib/turn/prompt-controller.d.ts

@@ -0,0 +1,59 @@
+import type { AgentEvent, AgentMessage, QueueMode } from '@zhin.js/ai';
+import type { Message } from '../orchestrator/types.js';
+import type { OnChunkCallback } from '../config/index.js';
+import type { AgentLoopTurnResult } from '../core/agent-loop-turn.js';
+export interface PromptTurnHooks {
+    getSteeringMessages: () => Promise<AgentMessage[]>;
+    getFollowUpMessages: () => Promise<AgentMessage[]>;
+}
+export interface PromptTurnRequest {
+    sessionKey: string;
+    sessionId: string;
+    userMessages: AgentMessage[];
+    commMessage: Message;
+    onChunk?: OnChunkCallback;
+    execute: (initialMessages: AgentMessage[], hooks: PromptTurnHooks, signal: AbortSignal, turnId: string) => Promise<AgentLoopTurnResult>;
+}
+/** 同 session 新入站消息取代仍在执行的旧 turn 时抛出；调用方应跳过出站回复。 */
+export declare class TurnSupersededError extends Error {
+    readonly sessionKey: string;
+    constructor(sessionKey: string);
+}
+type PromptSubscriber = (event: AgentEvent, signal: AbortSignal) => void | Promise<void>;
+export declare class PromptController {
+    private readonly steeringMode;
+    private readonly followUpMode;
+    private readonly subscribers;
+    private readonly activeTurns;
+    private readonly latestTurnBySession;
+    private idleWaiters;
+    private lastResult;
+    constructor(steeringMode: QueueMode, followUpMode: QueueMode);
+    isIdle(): boolean;
+    isBusy(): boolean;
+    getActiveTurnCount(): number;
+    getActiveSessionKey(): string | null;
+    getActiveContext(): Message | null;
+    getLastResult(): AgentLoopTurnResult | null;
+    subscribe(listener: PromptSubscriber): () => void;
+    waitForIdle(): Promise<void>;
+    /** Abort all active turns (optionally scoped to one session). */
+    abort(sessionKey?: string): void;
+    clearSteeringQueue(sessionKey?: string): void;
+    clearFollowUpQueue(sessionKey?: string): void;
+    /** Master-only: inject into the latest active turn on this session. */
+    steer(sessionKey: string, message: AgentMessage | AgentMessage[]): void;
+    /** Master-only: queue continuation on the latest active turn. */
+    followUp(sessionKey: string, message: AgentMessage | AgentMessage[]): void;
+    /** 同 session 串行：新 turn 开始前 abort 仍在执行的旧 turn，避免过期回复污染群上下文。 */
+    schedule(request: PromptTurnRequest): Promise<AgentLoopTurnResult>;
+    private resolveLatestTurn;
+    private notifyIdle;
+    private emitEvent;
+    private promoteLatestTurn;
+    private demoteLatestTurn;
+    private runTurn;
+    dispose(): void;
+}
+export {};
+//# sourceMappingURL=prompt-controller.d.ts.map

package/lib/turn/prompt-controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-controller.d.ts","sourceRoot":"","sources":["../../src/turn/prompt-controller.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAGtE,MAAM,WAAW,eAAe;IAC9B,mBAAmB,EAAE,MAAM,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IACnD,mBAAmB,EAAE,MAAM,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,YAAY,EAAE,CAAC;IAC7B,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,OAAO,EAAE,CACP,eAAe,EAAE,YAAY,EAAE,EAC/B,KAAK,EAAE,eAAe,EACtB,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,KACX,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACnC;AAED,mDAAmD;AACnD,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,UAAU,EAAE,MAAM;CAK/B;AAED,KAAK,gBAAgB,GAAG,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAUzF,qBAAa,gBAAgB;IAQzB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAR/B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA+B;IAC3D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAiC;IAC7D,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAA6B;IACjE,OAAO,CAAC,WAAW,CAAyB;IAC5C,OAAO,CAAC,UAAU,CAAoC;gBAGnC,YAAY,EAAE,SAAS,EACvB,YAAY,EAAE,SAAS;IAG1C,MAAM,IAAI,OAAO;IAIjB,MAAM,IAAI,OAAO;IAIjB,kBAAkB,IAAI,MAAM;IAI5B,mBAAmB,IAAI,MAAM,GAAG,IAAI;IAKpC,gBAAgB,IAAI,OAAO,GAAG,IAAI;IAMlC,aAAa,IAAI,mBAAmB,GAAG,IAAI;IAI3C,SAAS,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,IAAI;IAO3C,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAOlC,iEAAiE;IACjE,KAAK,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI;IAOhC,kBAAkB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI;IAO7C,kBAAkB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI;IAO7C,uEAAuE;IACvE,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,YAAY,EAAE,GAAG,IAAI;IAQvE,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,YAAY,EAAE,GAAG,IAAI;IAQ1E,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAKlE,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,UAAU;YAQJ,SAAS;IAMvB,OAAO,CAAC,iBAAiB;IAIzB,OAAO,CAAC,gBAAgB;YAWV,OAAO;IAoDrB,OAAO,IAAI,IAAI;CAWhB"}

package/lib/turn/prompt-controller.js

@@ -0,0 +1,190 @@
+import { randomUUID } from 'node:crypto';
+import { SessionMessageQueue } from './session-message-queue.js';
+/** 同 session 新入站消息取代仍在执行的旧 turn 时抛出；调用方应跳过出站回复。 */
+export class TurnSupersededError extends Error {
+    sessionKey;
+    constructor(sessionKey) {
+        super(`Turn superseded on session ${sessionKey}`);
+        this.name = 'TurnSupersededError';
+        this.sessionKey = sessionKey;
+    }
+}
+export class PromptController {
+    steeringMode;
+    followUpMode;
+    subscribers = new Set();
+    activeTurns = new Map();
+    latestTurnBySession = new Map();
+    idleWaiters = [];
+    lastResult = null;
+    constructor(steeringMode, followUpMode) {
+        this.steeringMode = steeringMode;
+        this.followUpMode = followUpMode;
+    }
+    isIdle() {
+        return this.activeTurns.size === 0;
+    }
+    isBusy() {
+        return this.activeTurns.size > 0;
+    }
+    getActiveTurnCount() {
+        return this.activeTurns.size;
+    }
+    getActiveSessionKey() {
+        const latest = [...this.latestTurnBySession.entries()].at(-1);
+        return latest?.[0] ?? null;
+    }
+    getActiveContext() {
+        const turnId = [...this.latestTurnBySession.values()].at(-1);
+        if (!turnId)
+            return null;
+        return this.activeTurns.get(turnId)?.commMessage ?? null;
+    }
+    getLastResult() {
+        return this.lastResult;
+    }
+    subscribe(listener) {
+        this.subscribers.add(listener);
+        return () => {
+            this.subscribers.delete(listener);
+        };
+    }
+    async waitForIdle() {
+        if (this.isIdle())
+            return;
+        await new Promise((resolve) => {
+            this.idleWaiters.push(resolve);
+        });
+    }
+    /** Abort all active turns (optionally scoped to one session). */
+    abort(sessionKey) {
+        for (const turn of this.activeTurns.values()) {
+            if (sessionKey && turn.sessionKey !== sessionKey)
+                continue;
+            turn.abortController.abort();
+        }
+    }
+    clearSteeringQueue(sessionKey) {
+        for (const turn of this.activeTurns.values()) {
+            if (sessionKey && turn.sessionKey !== sessionKey)
+                continue;
+            turn.queue.clearSteering();
+        }
+    }
+    clearFollowUpQueue(sessionKey) {
+        for (const turn of this.activeTurns.values()) {
+            if (sessionKey && turn.sessionKey !== sessionKey)
+                continue;
+            turn.queue.clearFollowUp();
+        }
+    }
+    /** Master-only: inject into the latest active turn on this session. */
+    steer(sessionKey, message) {
+        const turn = this.resolveLatestTurn(sessionKey);
+        if (!turn) {
+            throw new Error('steer requires an active turn on the same session');
+        }
+        turn.queue.pushSteering(message);
+    }
+    /** Master-only: queue continuation on the latest active turn. */
+    followUp(sessionKey, message) {
+        const turn = this.resolveLatestTurn(sessionKey);
+        if (!turn) {
+            throw new Error('followUp requires an active turn on the same session');
+        }
+        turn.queue.pushFollowUp(message);
+    }
+    /** 同 session 串行：新 turn 开始前 abort 仍在执行的旧 turn，避免过期回复污染群上下文。 */
+    schedule(request) {
+        this.abort(request.sessionKey);
+        return this.runTurn(request);
+    }
+    resolveLatestTurn(sessionKey) {
+        const turnId = this.latestTurnBySession.get(sessionKey);
+        if (!turnId)
+            return undefined;
+        return this.activeTurns.get(turnId);
+    }
+    notifyIdle() {
+        if (!this.isIdle())
+            return;
+        const waiters = this.idleWaiters.splice(0);
+        for (const resolve of waiters) {
+            resolve();
+        }
+    }
+    async emitEvent(event, signal) {
+        for (const listener of this.subscribers) {
+            await listener(event, signal);
+        }
+    }
+    promoteLatestTurn(sessionKey, turnId) {
+        this.latestTurnBySession.set(sessionKey, turnId);
+    }
+    demoteLatestTurn(sessionKey, turnId) {
+        if (this.latestTurnBySession.get(sessionKey) !== turnId)
+            return;
+        this.latestTurnBySession.delete(sessionKey);
+        for (const [id, turn] of this.activeTurns) {
+            if (turn.sessionKey === sessionKey) {
+                this.latestTurnBySession.set(sessionKey, id);
+                return;
+            }
+        }
+    }
+    async runTurn(request) {
+        const turnId = randomUUID();
+        const abortController = new AbortController();
+        const signal = abortController.signal;
+        const queue = new SessionMessageQueue(this.steeringMode, this.followUpMode);
+        const activeTurn = {
+            turnId,
+            sessionKey: request.sessionKey,
+            commMessage: request.commMessage,
+            queue,
+            abortController,
+        };
+        this.activeTurns.set(turnId, activeTurn);
+        this.promoteLatestTurn(request.sessionKey, turnId);
+        let lastResult = null;
+        try {
+            await this.emitEvent({ type: 'agent_start' }, signal);
+            const hooks = {
+                getSteeringMessages: async () => queue.drainSteering(),
+                getFollowUpMessages: async () => queue.drainFollowUp(),
+            };
+            lastResult = await request.execute(request.userMessages, hooks, signal, turnId);
+            while (queue.hasFollowUp() && !signal.aborted) {
+                const batch = queue.drainFollowUp();
+                lastResult = await request.execute(batch, hooks, signal, turnId);
+            }
+            if (signal.aborted) {
+                throw new TurnSupersededError(request.sessionKey);
+            }
+            await this.emitEvent({ type: 'agent_end', messages: request.userMessages }, signal);
+            if (!lastResult) {
+                throw new Error('Prompt turn produced no result');
+            }
+            this.lastResult = lastResult;
+            return lastResult;
+        }
+        finally {
+            this.activeTurns.delete(turnId);
+            this.demoteLatestTurn(request.sessionKey, turnId);
+            this.notifyIdle();
+        }
+    }
+    dispose() {
+        for (const turn of this.activeTurns.values()) {
+            turn.abortController.abort();
+        }
+        this.activeTurns.clear();
+        this.latestTurnBySession.clear();
+        this.subscribers.clear();
+        const waiters = this.idleWaiters.splice(0);
+        for (const resolve of waiters)
+            resolve();
+        this.lastResult = null;
+    }
+}
+//# sourceMappingURL=prompt-controller.js.map

package/lib/turn/prompt-controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-controller.js","sourceRoot":"","sources":["../../src/turn/prompt-controller.ts"],"names":[],"mappings":"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"}

package/lib/turn/prompt-input.d.ts

@@ -0,0 +1,3 @@
+import { type AgentMessage, type ImageContent } from '@zhin.js/ai';
+export declare function normalizePromptMessages(input: string | AgentMessage | AgentMessage[], images?: ImageContent[]): AgentMessage[];
+//# sourceMappingURL=prompt-input.d.ts.map

package/lib/turn/prompt-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-input.d.ts","sourceRoot":"","sources":["../../src/turn/prompt-input.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAqB,MAAM,aAAa,CAAC;AACtF,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,YAAY,EAAE,EAC7C,MAAM,CAAC,EAAE,YAAY,EAAE,GACtB,YAAY,EAAE,CAKhB"}

package/lib/turn/prompt-input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-input.js","sourceRoot":"","sources":["../../src/turn/prompt-input.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwC,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACtF,MAAM,UAAU,uBAAuB,CACrC,KAA6C,EAC7C,MAAuB;IAEvB,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,CAAC,iBAAiB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AAChD,CAAC"}