@zhin.js/agent 1.1.3 → 1.1.6

package/lib/context/im-turn-context-adapter.js

@@ -0,0 +1,54 @@
+import { QUOTE_CONTEXT_SYSTEM_EXTRA_KEY, resolveIMSessionIdFromMessage, senderRolesFromMessage, } from '@zhin.js/core';
+import { readInboundMediaRefs } from '../media/inbound-refs.js';
+/** IM ingress-only adapter. Agent context implementation consumes TurnContextView. */
+export function turnContextViewFromMessage(message) {
+    const scope = message.$channel?.type;
+    if (scope !== 'private' && scope !== 'group' && scope !== 'channel') {
+        throw new TypeError('IM Turn context requires a private, group, or channel scope');
+    }
+    const platform = String(message.$adapter ?? '').trim();
+    const endpoint = String(message.$endpoint ?? '').trim();
+    const sceneId = String(message.$channel?.id ?? '').trim();
+    const subjectId = String(message.$sender?.id ?? '').trim();
+    if (!platform || !endpoint || !sceneId || !subjectId) {
+        throw new TypeError('IM Turn context requires platform, endpoint, scene, and sender identity');
+    }
+    return Object.freeze({
+        origin: Object.freeze({
+            kind: 'im',
+            platform,
+            endpoint,
+            scope,
+            sceneId,
+            ...(message.$id ? { messageId: String(message.$id) } : {}),
+        }),
+        principal: Object.freeze({
+            subjectId,
+            ...(message.$sender?.name ? { displayName: message.$sender.name } : {}),
+            roles: Object.freeze([...senderRolesFromMessage(message)]),
+        }),
+        session: Object.freeze({ key: resolveIMSessionIdFromMessage(message) }),
+    });
+}
+export function resolveQuoteSystemHint(message) {
+    const hint = message?.extra?.[QUOTE_CONTEXT_SYSTEM_EXTRA_KEY];
+    return typeof hint === 'string' && hint.trim() ? hint.trim() : undefined;
+}
+/** IM ingress-only projection into the canonical Turn media contract. */
+export function turnMediaFromMessage(message) {
+    return Object.freeze(readInboundMediaRefs(message).map(({ type, media }) => Object.freeze({
+        kind: normalizeMediaKind(type),
+        source: Object.freeze({
+            kind: media.kind === 'file' ? 'platform_ref' : media.kind,
+            value: media.value,
+        }),
+        ...(media.mime_type ? { mimeType: media.mime_type } : {}),
+        ...(media.file_name ? { name: media.file_name } : {}),
+    })));
+}
+function normalizeMediaKind(type) {
+    if (type === 'image' || type === 'video' || type === 'file')
+        return type;
+    return 'audio';
+}
+//# sourceMappingURL=im-turn-context-adapter.js.map

package/lib/context/im-turn-context-adapter.js.map

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

package/lib/context/index.d.ts

@@ -4,11 +4,11 @@
 export type { BuildContext, InjectContext, ContextBuilder, ContextInjector, ContextSystemConfig, } from './contracts.js';
 export type { TurnEnvelopeParts } from './envelope-parts.js';
 export type { TextTurnContextInput, TextTurnContextOutput } from './context-system.js';
-export type { TurnContextEnvelopeInput } from './turn-envelope.js';
+export type { TurnContextEnvelopeInput, TurnContextView } from './turn-envelope.js';
 export type { AgentsInstructionEntry } from './agents-instruction.js';
 export type { ModelResolverConfig } from './model-resolver.js';
 export { ContextSystem, createContextSystemForHost, ProfileContextBuilder, ToneInjector, CollaborationContextBuilder, createDefaultContextBuilders, } from './context-system.js';
-export { buildTurnContextEnvelope, prependTurnContextEnvelope, formatSessionContextLine, resolveQuoteSystemHint, TURN_CONTEXT_BEGIN, TURN_CONTEXT_END, } from './turn-envelope.js';
+export { buildTurnContextEnvelope, prependTurnContextEnvelope, formatSessionContextLine, TURN_CONTEXT_BEGIN, TURN_CONTEXT_END, } from './turn-envelope.js';
 export { buildTurnUserMessages, applyTurnContextToUserMessages, prependEnvelopeToFirstUserText, } from './turn-user-message.js';
 export { buildAgentsEnvelopeContext, collectAgentsInstructionChain, clearAgentsInstructionCache, } from './agents-instruction.js';
 export { resolveModel, resolveModelCandidates } from './model-resolver.js';

package/lib/context/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EACV,YAAY,EACZ,aAAa,EACb,cAAc,EACd,eAAe,EACf,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AAExB,YAAY,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,YAAY,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACvF,YAAY,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AACnE,YAAY,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACtE,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D,OAAO,EACL,aAAa,EACb,0BAA0B,EAC1B,qBAAqB,EACrB,YAAY,EACZ,2BAA2B,EAC3B,4BAA4B,GAC7B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,wBAAwB,EACxB,0BAA0B,EAC1B,wBAAwB,EACxB,sBAAsB,EACtB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,qBAAqB,EACrB,8BAA8B,EAC9B,8BAA8B,GAC/B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,0BAA0B,EAC1B,6BAA6B,EAC7B,2BAA2B,GAC5B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAE3E,OAAO,EACL,kCAAkC,EAClC,wCAAwC,EACxC,8BAA8B,GAC/B,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EACV,YAAY,EACZ,aAAa,EACb,cAAc,EACd,eAAe,EACf,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AAExB,YAAY,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,YAAY,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACvF,YAAY,EAAE,wBAAwB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACpF,YAAY,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACtE,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D,OAAO,EACL,aAAa,EACb,0BAA0B,EAC1B,qBAAqB,EACrB,YAAY,EACZ,2BAA2B,EAC3B,4BAA4B,GAC7B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,wBAAwB,EACxB,0BAA0B,EAC1B,wBAAwB,EACxB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,qBAAqB,EACrB,8BAA8B,EAC9B,8BAA8B,GAC/B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,0BAA0B,EAC1B,6BAA6B,EAC7B,2BAA2B,GAC5B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAE3E,OAAO,EACL,kCAAkC,EAClC,wCAAwC,EACxC,8BAA8B,GAC/B,MAAM,yBAAyB,CAAC"}

package/lib/context/index.js

@@ -2,7 +2,7 @@
  * Context System — builder/injector 链 + turn 上下文构建。
  */
 export { ContextSystem, createContextSystemForHost, ProfileContextBuilder, ToneInjector, CollaborationContextBuilder, createDefaultContextBuilders, } from './context-system.js';
-export { buildTurnContextEnvelope, prependTurnContextEnvelope, formatSessionContextLine, resolveQuoteSystemHint, TURN_CONTEXT_BEGIN, TURN_CONTEXT_END, } from './turn-envelope.js';
+export { buildTurnContextEnvelope, prependTurnContextEnvelope, formatSessionContextLine, TURN_CONTEXT_BEGIN, TURN_CONTEXT_END, } from './turn-envelope.js';
 export { buildTurnUserMessages, applyTurnContextToUserMessages, prependEnvelopeToFirstUserText, } from './turn-user-message.js';
 export { buildAgentsEnvelopeContext, collectAgentsInstructionChain, clearAgentsInstructionCache, } from './agents-instruction.js';
 export { resolveModel, resolveModelCandidates } from './model-resolver.js';

package/lib/context/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAgBH,OAAO,EACL,aAAa,EACb,0BAA0B,EAC1B,qBAAqB,EACrB,YAAY,EACZ,2BAA2B,EAC3B,4BAA4B,GAC7B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,wBAAwB,EACxB,0BAA0B,EAC1B,wBAAwB,EACxB,sBAAsB,EACtB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,qBAAqB,EACrB,8BAA8B,EAC9B,8BAA8B,GAC/B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,0BAA0B,EAC1B,6BAA6B,EAC7B,2BAA2B,GAC5B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAE3E,OAAO,EACL,kCAAkC,EAClC,wCAAwC,EACxC,8BAA8B,GAC/B,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAgBH,OAAO,EACL,aAAa,EACb,0BAA0B,EAC1B,qBAAqB,EACrB,YAAY,EACZ,2BAA2B,EAC3B,4BAA4B,GAC7B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,wBAAwB,EACxB,0BAA0B,EAC1B,wBAAwB,EACxB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,qBAAqB,EACrB,8BAA8B,EAC9B,8BAA8B,GAC/B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,0BAA0B,EAC1B,6BAA6B,EAC7B,2BAA2B,GAC5B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAE3E,OAAO,EACL,kCAAkC,EAClC,wCAAwC,EACxC,8BAA8B,GAC/B,MAAM,yBAAyB,CAAC"}

package/lib/context/turn-envelope.d.ts

@@ -1,8 +1,9 @@
-import { type AgentTurnMessage, type Message } from '@zhin.js/core';
+import type { TurnRequest } from '../turn/turn-ingress.js';
 export declare const TURN_CONTEXT_BEGIN = "[Turn context]";
 export declare const TURN_CONTEXT_END = "[/Turn context]";
+export type TurnContextView = Pick<TurnRequest, 'origin' | 'principal' | 'session'>;
 export interface TurnContextEnvelopeInput {
-    commMessage?: Message;
+    turn?: TurnContextView;
     profileSummary?: string;
     toneHint?: string;
     deferredStats?: string;
@@ -13,8 +14,8 @@ export interface TurnContextEnvelopeInput {
     sdk?: string;
     agentsContext?: string;
 }
-export declare function formatSessionContextLine(commMessage: Message): string | null;
-export declare function resolveQuoteSystemHint(commMessage?: AgentTurnMessage): string | undefined;
+export declare function formatSessionContextLine(turn: TurnContextView): string;
+export declare function formatSenderContextLine(turn: TurnContextView): string;
 export declare function buildTurnContextEnvelope(input: TurnContextEnvelopeInput): string | null;
 export declare function prependTurnContextEnvelope(content: string, envelope: string | null | undefined): string;
 //# sourceMappingURL=turn-envelope.d.ts.map

package/lib/context/turn-envelope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"turn-envelope.d.ts","sourceRoot":"","sources":["../../src/context/turn-envelope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,OAAO,EAAiE,MAAM,eAAe,CAAC;AAEnI,eAAO,MAAM,kBAAkB,mBAAmB,CAAC;AACnD,eAAO,MAAM,gBAAgB,oBAAoB,CAAC;AAElD,MAAM,WAAW,wBAAwB;IACvC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAS5E;AAED,wBAAgB,sBAAsB,CAAC,WAAW,CAAC,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS,CAIzF;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,wBAAwB,GAAG,MAAM,GAAG,IAAI,CA0DvF;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAGvG"}
+{"version":3,"file":"turn-envelope.d.ts","sourceRoot":"","sources":["../../src/context/turn-envelope.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D,eAAO,MAAM,kBAAkB,mBAAmB,CAAC;AACnD,eAAO,MAAM,gBAAgB,oBAAoB,CAAC;AAElD,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,WAAW,EAAE,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC,CAAC;AAEpF,MAAM,WAAW,wBAAwB;IACvC,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAStE;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAMrE;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,wBAAwB,GAAG,MAAM,GAAG,IAAI,CAqCvF;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAGvG"}

package/lib/context/turn-envelope.js

@@ -1,25 +1,25 @@
-import { QUOTE_CONTEXT_SYSTEM_EXTRA_KEY, resolveIMSessionIdFromMessage } from '@zhin.js/core';
 import { getFileMemoryContext, formatMemoryPathsHint } from '../memory-layers.js';
 export const TURN_CONTEXT_BEGIN = '[Turn context]';
 export const TURN_CONTEXT_END = '[/Turn context]';
-export function formatSessionContextLine(commMessage) {
-    const parts = [];
-    if (commMessage.$adapter)
-        parts.push(`platform:${commMessage.$adapter}`);
-    if (commMessage.$endpoint)
-        parts.push(`endpoint:${commMessage.$endpoint}`);
-    if (commMessage.$channel?.type && commMessage.$channel?.id) {
-        parts.push(`${commMessage.$channel.type}_id:${commMessage.$channel.id}`);
+export function formatSessionContextLine(turn) {
+    const origin = turn.origin;
+    if (origin.kind === 'im') {
+        return `Session: platform:${origin.platform} | endpoint:${origin.endpoint} | ${origin.scope}_id:${origin.sceneId}`;
     }
-    if (parts.length === 0)
-        return null;
-    return `Session: ${parts.join(' | ')}`;
+    if (origin.kind === 'http')
+        return `Session: origin:http | session_id:${origin.sessionId}`;
+    if (origin.kind === 'a2a')
+        return `Session: origin:a2a | task_id:${origin.taskId}`;
+    if (origin.kind === 'schedule')
+        return `Session: origin:schedule | job_id:${origin.jobId}`;
+    return `Session: origin:internal | source:${origin.source}`;
 }
-export function resolveQuoteSystemHint(commMessage) {
-    const hint = commMessage?.extra?.[QUOTE_CONTEXT_SYSTEM_EXTRA_KEY];
-    if (typeof hint !== 'string' || !hint.trim())
-        return undefined;
-    return hint.trim();
+export function formatSenderContextLine(turn) {
+    const { principal } = turn;
+    const roles = principal.roles.length > 0 ? principal.roles.join(',') : 'user';
+    return principal.displayName?.trim()
+        ? `Sender: id=${principal.subjectId} name=${principal.displayName.trim()} roles=${roles}`
+        : `Sender: id=${principal.subjectId} roles=${roles}`;
 }
 export function buildTurnContextEnvelope(input) {
     const lines = [];
@@ -27,50 +27,43 @@ export function buildTurnContextEnvelope(input) {
     const tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
     const timeStr = now.toLocaleString('zh-CN', { timeZone: tz });
     lines.push(`Time: ${timeStr} (${tz})`);
-    if (input.modelLine?.trim()) {
+    if (input.modelLine?.trim())
         lines.push(`Model: ${input.modelLine.trim()}`);
-    }
-    if (input.sdk?.trim()) {
+    if (input.sdk?.trim())
         lines.push(`Sdk: ${input.sdk.trim()}`);
-    }
-    if (input.commMessage) {
-        const sessionLine = formatSessionContextLine(input.commMessage);
-        if (sessionLine)
-            lines.push(sessionLine);
-        const sessionKey = resolveIMSessionIdFromMessage(input.commMessage);
-        const memoryPaths = formatMemoryPathsHint(String(input.commMessage.$adapter), sessionKey);
-        if (memoryPaths)
-            lines.push(`Memory paths: ${memoryPaths}`);
-        const fileMemory = getFileMemoryContext(undefined, String(input.commMessage.$adapter), sessionKey);
-        if (fileMemory?.trim()) {
-            lines.push('Memory snapshot:');
-            lines.push(fileMemory.trim());
+    if (input.turn) {
+        lines.push(formatSessionContextLine(input.turn));
+        lines.push(formatSenderContextLine(input.turn));
+        if (input.turn.origin.kind === 'im') {
+            const platform = input.turn.origin.platform;
+            const sessionKey = input.turn.session.key;
+            const memoryPaths = formatMemoryPathsHint(platform, sessionKey);
+            if (memoryPaths)
+                lines.push(`Memory paths: ${memoryPaths}`);
+            const fileMemory = getFileMemoryContext(undefined, platform, sessionKey);
+            if (fileMemory?.trim()) {
+                lines.push('Memory snapshot:');
+                lines.push(fileMemory.trim());
+            }
         }
     }
-    if (input.deferredStats?.trim()) {
+    if (input.deferredStats?.trim())
         lines.push(`Deferred catalog: ${input.deferredStats.trim()}`);
-    }
-    if (input.profileSummary?.trim()) {
+    if (input.profileSummary?.trim())
         lines.push(input.profileSummary.trim());
-    }
-    if (input.toneHint?.trim()) {
+    if (input.toneHint?.trim())
         lines.push(`[Tone hint] ${input.toneHint.trim()}`);
-    }
-    if (input.activeSkillsContext?.trim()) {
+    if (input.activeSkillsContext?.trim())
         lines.push(input.activeSkillsContext.trim());
-    }
-    if (input.quoteSystemHint?.trim()) {
+    if (input.quoteSystemHint?.trim())
         lines.push(input.quoteSystemHint.trim());
-    }
-    if (input.collaborationHint?.trim()) {
+    if (input.collaborationHint?.trim())
         lines.push(input.collaborationHint.trim());
-    }
-    if (input.agentsContext?.trim()) {
+    if (input.agentsContext?.trim())
         lines.push(input.agentsContext.trim());
-    }
-    if (lines.length === 0)
-        return null;
-    return `${TURN_CONTEXT_BEGIN}\n${lines.join('\n')}\n${TURN_CONTEXT_END}`;
+    return lines.length === 0
+        ? null
+        : `${TURN_CONTEXT_BEGIN}\n${lines.join('\n')}\n${TURN_CONTEXT_END}`;
 }
 export function prependTurnContextEnvelope(content, envelope) {
     if (!envelope?.trim())

package/lib/context/turn-envelope.js.map

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

package/lib/core/agent-core-run.d.ts

@@ -6,8 +6,13 @@ import type { AgentRunJournal } from '@zhin.js/ai/agent-stream';
 import { type ToolCallRecord } from './tool-calls-user-format.js';
 import type { HostPromptTurnHooks } from '../internal/host-types.js';
 import type { AgentCore } from './agent-core.js';
-import type { ZhinAgentPrivate, OnChunkCallback, Message } from '../internal/agent-host.js';
+import type { ZhinAgentPrivate, OnChunkCallback } from '../internal/agent-host.js';
+import type { ToolCatalogItem } from '../tool-catalog/types.js';
 import type { TurnEvent } from '../event/turn-event.js';
+import type { AgentPromptProfile } from '../prompt/turn-prompt-profile.js';
+import type { TurnContextView } from '../context/turn-envelope.js';
+import type { ToolExecutionAuthority } from './tool-execution-authority.js';
+import type { PluginAILoopHookRegistry } from '../plugin-loop-hooks.js';
 export interface AgentLoopTurnInput {
     host: ZhinAgentPrivate;
     core?: AgentCore;
@@ -15,10 +20,21 @@ export interface AgentLoopTurnInput {
     /** 本轮 user 消息 extra（入库 agent_messages.extra） */
     userMessageExtra?: import('@zhin.js/ai').AgentMessageExtra;
     rawContent: string;
-    commMessage: Message;
-    contextForTools: Message;
+    promptProfile: AgentPromptProfile;
+    turnContext: TurnContextView;
     allTools: AgentTool[];
     resolvedTools: AgentTool[];
+    toolExecution: ToolExecutionAuthority;
+    /** Canonical capability authority journals tool facts itself; classic loops map them. */
+    toolEventSource?: 'loop' | 'authority';
+    loopHooks?: PluginAILoopHookRegistry;
+    promptRuntime?: Readonly<{
+        bootstrapContext?: string;
+        activeSkillsContext?: string;
+        agentNickname?: string;
+        modelId?: string;
+        providerAlias?: string;
+    }>;
     personaEnhanced: string;
     modelId: string;
     modelCandidates: string[];
@@ -27,22 +43,29 @@ export interface AgentLoopTurnInput {
     promptHooks?: HostPromptTurnHooks;
     signal?: AbortSignal;
     deferredStats?: string;
+    /** Turn-owned deferred selection authority. Required for deferred loading. */
+    deferredController?: Readonly<{
+        loadedToolNames(): string[];
+    }>;
+    /** Catalog paired with deferredController for this exact Turn. */
+    toolCatalog?: readonly ToolCatalogItem[];
+    /** Direct tool sets bypass deferred catalog/snapshot/meta-tool machinery. */
+    toolLoading?: 'deferred' | 'direct';
+    /** Isolated executions neither load nor append conversational history. */
+    conversationPersistence?: 'session' | 'none';
     /** Tool name aliases: LLM-facing name → actual tool name */
     toolAliases?: Record<string, string>;
     /** Optional TurnEvent tap (processStream / diagnostics) */
     onTurnEvent?: (event: TurnEvent) => void;
     /** Ordered public event journal for this stream turn. */
     journal?: AgentRunJournal;
+    /**
+     * Snapshot generation for ToolRuntime validation.
+     * Plugin Runtime hosts pass SnapshotStore / AgentCapabilities.generation;
+     * legacy paths keep the `0` placeholder.
+     */
+    generation?: number;
 }
-/** Optional second argument for tools that support cooperative cancellation. */
-export interface AgentToolExecutionContext {
-    readonly signal?: AbortSignal;
-    readonly sessionId: string;
-    readonly toolCallId: string;
-    readonly toolName: string;
-}
-type CancellableToolExecute<TResult = unknown> = (args: Record<string, unknown>, legacyContext?: Message, executionContext?: AgentToolExecutionContext) => TResult | Promise<TResult>;
-export declare function executeCancellableTool<TResult>(execute: CancellableToolExecute<TResult>, args: Record<string, unknown>, legacyContext: Message, context: AgentToolExecutionContext): Promise<TResult>;
 export interface AgentLoopTurnResult {
     reply: string;
     usage: Usage;
@@ -51,12 +74,13 @@ export interface AgentLoopTurnResult {
     model: string;
     toolCalls: ToolCallRecord[];
     thinking?: string;
+    /** Conversation projection applied only after the durable terminal commits. */
+    projectConversation?: () => Promise<void>;
 }
 export interface AgentLoopVisionTurnInput {
     host: ZhinAgentPrivate;
     core?: AgentCore;
     sessionId: string;
-    commMessage: Message;
     visionSystemPrompt: string;
     userMessages: AgentMessage[];
     modelCandidates: string[];
@@ -71,5 +95,4 @@ export type AgentLoopVisionTurnResult = AgentLoopTurnResult & {
 export declare function runAgentLoopVisionTurnRun(input: AgentLoopVisionTurnInput): AsyncGenerator<TurnEvent, AgentLoopVisionTurnResult>;
 export declare function collectAgentLoopTurnRun<R>(gen: AsyncGenerator<TurnEvent, R>, onTurnEvent?: (event: TurnEvent) => void): Promise<R>;
 export declare function runAgentLoopTextTurnRun(input: AgentLoopTurnInput): AsyncGenerator<TurnEvent, AgentLoopTurnResult>;
-export {};
 //# sourceMappingURL=agent-core-run.d.ts.map

package/lib/core/agent-core-run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-core-run.d.ts","sourceRoot":"","sources":["../../src/core/agent-core-run.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent-core-run.d.ts","sourceRoot":"","sources":["../../src/core/agent-core-run.ts"],"names":[],"mappings":"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"}