@zhin.js/agent 1.1.36 → 1.1.39

package/lib/context/contracts.d.ts

@@ -31,4 +31,3 @@ export interface ContextInjector {
 }
 export interface ContextSystemConfig {
 }
-//# sourceMappingURL=contracts.d.ts.map

package/lib/context/contracts.js.map

@@ -1 +1 @@
-{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../src/context/contracts.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../src/context/contracts.ts"],"names":[],"mappings":"AAAA;;;;;GAKG","sourcesContent":["/**\n * Context System — 模块契约（与实现同步）。\n *\n * 实现：builder/injector 链 + `buildTextTurnContext`（turn 级编排入口）。\n * `BuildContext.host` 为生产路径注入的 `ZhinAgentPrivate` 只读面。\n */\n\nimport type { AgentMessage } from '@zhin.js/ai';\nimport type { ZhinAgentPrivate } from '../internal/agent-host.js';\nimport type { TurnEnvelopeParts } from './envelope-parts.js';\nimport type { TurnContextView } from './turn-envelope.js';\n\nexport interface BuildContext {\n  turn: TurnContextView;\n  inboundContent?: string;\n  sessionKey?: string;\n  /** 生产 turn 路径注入；builder 写入 envelope 片段 */\n  host?: ZhinAgentPrivate;\n  envelope?: Partial<TurnEnvelopeParts>;\n}\n\nexport interface InjectContext {\n  turn: TurnContextView;\n  inboundContent?: string;\n  envelope?: Partial<TurnEnvelopeParts>;\n}\n\nexport interface ContextBuilder {\n  name: string;\n  build(context: BuildContext): Promise<AgentMessage[]>;\n}\n\nexport interface ContextInjector {\n  name: string;\n  inject(messages: AgentMessage[], context: InjectContext): AgentMessage[];\n}\n\nexport interface ContextSystemConfig {\n  /** 预留扩展面 */\n}\n"]}

package/lib/context/default-builders.d.ts

@@ -17,4 +17,3 @@ export declare function createDefaultContextBuilders(host: ZhinAgentPrivate): {
     builders: ContextBuilder[];
     injectors: ContextInjector[];
 };
-//# sourceMappingURL=default-builders.d.ts.map

package/lib/context/default-builders.js.map

@@ -1 +1 @@
-{"version":3,"file":"default-builders.js","sourceRoot":"","sources":["../../src/context/default-builders.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,UAAU,EAAE,MAAM,aAAa,CAAC;AAG5D,MAAM,OAAO,qBAAqB;IAGH;IAF7B,IAAI,GAAG,SAAS,CAAC;IAEjB,YAA6B,IAAsB;QAAtB,SAAI,GAAJ,IAAI,CAAkB;IAAG,CAAC;IAEvD,KAAK,CAAC,KAAK,CAAC,OAAqB;QAC/B,IAAI,CAAC,OAAO,CAAC,QAAQ;YAAE,OAAO,EAAE,CAAC;QACjC,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC;QAChD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC;QACzE,IAAI,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC;YACpB,OAAO,CAAC,QAAQ,CAAC,cAAc,GAAG,OAAO,CAAC;QAC5C,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC;CACF;AAED,MAAM,OAAO,YAAY;IAGM;IAF7B,IAAI,GAAG,MAAM,CAAC;IAEd,YAA6B,IAAsB;QAAtB,SAAI,GAAJ,IAAI,CAAkB;IAAG,CAAC;IAEvD,MAAM,CAAC,QAAwB,EAAE,OAAsB;QACrD,IAAI,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;YAC7D,OAAO,CAAC,QAAQ,CAAC,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa;gBACxD,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,IAAI;gBACzC,CAAC,CAAC,EAAE,CAAC;QACT,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF;AAED,MAAM,UAAU,4BAA4B,CAAC,IAAsB;IAIjE,OAAO;QACL,QAAQ,EAAE;YACR,IAAI,qBAAqB,CAAC,IAAI,CAAC;SAChC;QACD,SAAS,EAAE,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;KACpC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"default-builders.js","sourceRoot":"","sources":["../../src/context/default-builders.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,UAAU,EAAE,MAAM,aAAa,CAAC;AAG5D,MAAM,OAAO,qBAAqB;IAGH;IAF7B,IAAI,GAAG,SAAS,CAAC;IAEjB,YAA6B,IAAsB;QAAtB,SAAI,GAAJ,IAAI,CAAkB;IAAG,CAAC;IAEvD,KAAK,CAAC,KAAK,CAAC,OAAqB;QAC/B,IAAI,CAAC,OAAO,CAAC,QAAQ;YAAE,OAAO,EAAE,CAAC;QACjC,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC;QAChD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC;QACzE,IAAI,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC;YACpB,OAAO,CAAC,QAAQ,CAAC,cAAc,GAAG,OAAO,CAAC;QAC5C,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC;CACF;AAED,MAAM,OAAO,YAAY;IAGM;IAF7B,IAAI,GAAG,MAAM,CAAC;IAEd,YAA6B,IAAsB;QAAtB,SAAI,GAAJ,IAAI,CAAkB;IAAG,CAAC;IAEvD,MAAM,CAAC,QAAwB,EAAE,OAAsB;QACrD,IAAI,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;YAC7D,OAAO,CAAC,QAAQ,CAAC,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa;gBACxD,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,IAAI;gBACzC,CAAC,CAAC,EAAE,CAAC;QACT,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF;AAED,MAAM,UAAU,4BAA4B,CAAC,IAAsB;IAIjE,OAAO;QACL,QAAQ,EAAE;YACR,IAAI,qBAAqB,CAAC,IAAI,CAAC;SAChC;QACD,SAAS,EAAE,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;KACpC,CAAC;AACJ,CAAC","sourcesContent":["import { type AgentMessage, detectTone } from '@zhin.js/ai';\nimport type { ZhinAgentPrivate } from '../internal/agent-host.js';\nimport type { BuildContext, ContextBuilder, ContextInjector, InjectContext } from './contracts.js';\nexport class ProfileContextBuilder implements ContextBuilder {\n  name = 'profile';\n\n  constructor(private readonly host: ZhinAgentPrivate) {}\n\n  async build(context: BuildContext): Promise<AgentMessage[]> {\n    if (!context.envelope) return [];\n    const userId = context.turn.principal.subjectId;\n    const summary = await this.host.userProfiles.buildProfileSummary(userId);\n    if (summary?.trim()) {\n      context.envelope.profileSummary = summary;\n    }\n    return [];\n  }\n}\n\nexport class ToneInjector implements ContextInjector {\n  name = 'tone';\n\n  constructor(private readonly host: ZhinAgentPrivate) {}\n\n  inject(messages: AgentMessage[], context: InjectContext): AgentMessage[] {\n    if (context.envelope && context.inboundContent !== undefined) {\n      context.envelope.toneHint = this.host.config.toneAwareness\n        ? detectTone(context.inboundContent).hint\n        : '';\n    }\n    return messages;\n  }\n}\n\nexport function createDefaultContextBuilders(host: ZhinAgentPrivate): {\n  builders: ContextBuilder[];\n  injectors: ContextInjector[];\n} {\n  return {\n    builders: [\n      new ProfileContextBuilder(host),\n    ],\n    injectors: [new ToneInjector(host)],\n  };\n}\n"]}

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

@@ -9,4 +9,3 @@ export interface TurnEnvelopeParts {
     sdk?: string;
     agentsContext?: string;
 }
-//# sourceMappingURL=envelope-parts.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"envelope-parts.js","sourceRoot":"","sources":["../../src/context/envelope-parts.ts"],"names":[],"mappings":""}
+{"version":3,"file":"envelope-parts.js","sourceRoot":"","sources":["../../src/context/envelope-parts.ts"],"names":[],"mappings":"","sourcesContent":["/** Turn envelope 片段 — builder/injector pipeline 写入，buildTextTurnContext 读取。 */\nexport interface TurnEnvelopeParts {\n  profileSummary?: string;\n  toneHint?: string;\n  deferredStats?: string;\n  activeSkillsContext?: string;\n  quoteSystemHint?: string;\n  modelLine?: string;\n  sdk?: string;\n  agentsContext?: string;\n}\n"]}

package/lib/context/im-turn-context-adapter.d.ts

@@ -5,4 +5,3 @@ import type { TurnMedia } from '../turn/turn-ingress.js';
 export declare function turnContextViewFromMessage(message: Message): TurnContextView;
 /** IM ingress-only projection into the canonical Turn media contract. */
 export declare function turnMediaFromMessage(message: Message): readonly TurnMedia[];
-//# sourceMappingURL=im-turn-context-adapter.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"im-turn-context-adapter.js","sourceRoot":"","sources":["../../src/context/im-turn-context-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,EAC7B,sBAAsB,GAEvB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAGhE,sFAAsF;AACtF,MAAM,UAAU,0BAA0B,CAAC,OAAgB;IACzD,MAAM,KAAK,GAAG,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC;IACxC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,OAAO,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACpE,MAAM,IAAI,SAAS,CAAC,6DAA6D,CAAC,CAAC;IACrF,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,aAAa,IAAI,OAAO,CAAC,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;IAC/F,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACvF,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7D,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC1D,IAAI,CAAC,QAAQ,IAAI,CAAC,QAAQ,IAAI,CAAC,OAAO,IAAI,CAAC,SAAS,EAAE,CAAC;QACrD,MAAM,IAAI,SAAS,CAAC,yEAAyE,CAAC,CAAC;IACjG,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;YACpB,IAAI,EAAE,IAAI;YACV,QAAQ;YACR,QAAQ;YACR,KAAK;YACL,OAAO;YACP,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzD,CAAC;QACF,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC;YACvB,SAAS;YACT,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrE,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,sBAAsB,CAAC,OAAO,CAAC,CAAC,CAAC;SAC3D,CAAC;QACF,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,6BAA6B,CAAC,OAAO,CAAC,EAAE,CAAC;KACxE,CAAC,CAAC;AACL,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,oBAAoB,CAAC,OAAgB;IACnD,OAAO,MAAM,CAAC,MAAM,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC;QACxF,IAAI,EAAE,kBAAkB,CAAC,IAAI,CAAC;QAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;YACpB,IAAI,EAAE,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,cAAuB,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI;YAClE,KAAK,EAAE,KAAK,CAAC,KAAK;SACnB,CAAC;QACF,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzD,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACtD,CAAC,CAAC,CAAC,CAAC;AACP,CAAC;AAED,SAAS,kBAAkB,CAAC,IAAY;IACtC,IAAI,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IACzE,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"im-turn-context-adapter.js","sourceRoot":"","sources":["../../src/context/im-turn-context-adapter.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  resolveIMSessionIdFromMessage,\n  senderRolesFromMessage,\n  type Message,\n} from '@zhin.js/core';\nimport type { TurnContextView } from './turn-envelope.js';\nimport { readInboundMediaRefs } from '../media/inbound-refs.js';\nimport type { TurnMedia } from '../turn/turn-ingress.js';\n\n/** IM ingress-only adapter. Agent context implementation consumes TurnContextView. */\nexport function turnContextViewFromMessage(message: Message): TurnContextView {\n  const scope = message.conversation.kind;\n  if (scope !== 'private' && scope !== 'group' && scope !== 'channel') {\n    throw new TypeError('IM Turn context requires a private, group, or channel scope');\n  }\n  const platform = String(message.clientAdapter ?? message.conversation.endpoint.adapter).trim();\n  const endpoint = String(message.endpointId ?? message.conversation.endpoint.id).trim();\n  const sceneId = String(message.conversation.id ?? '').trim();\n  const subjectId = String(message.sender?.id ?? '').trim();\n  if (!platform || !endpoint || !sceneId || !subjectId) {\n    throw new TypeError('IM Turn context requires platform, endpoint, scene, and sender identity');\n  }\n  return Object.freeze({\n    origin: Object.freeze({\n      kind: 'im',\n      platform,\n      endpoint,\n      scope,\n      sceneId,\n      ...(message.id ? { messageId: String(message.id) } : {}),\n    }),\n    principal: Object.freeze({\n      subjectId,\n      ...(message.sender?.name ? { displayName: message.sender.name } : {}),\n      roles: Object.freeze([...senderRolesFromMessage(message)]),\n    }),\n    session: Object.freeze({ key: resolveIMSessionIdFromMessage(message) }),\n  });\n}\n\n/** IM ingress-only projection into the canonical Turn media contract. */\nexport function turnMediaFromMessage(message: Message): readonly TurnMedia[] {\n  return Object.freeze(readInboundMediaRefs(message).map(({ type, media }) => Object.freeze({\n    kind: normalizeMediaKind(type),\n    source: Object.freeze({\n      kind: media.kind === 'file' ? 'platform_ref' as const : media.kind,\n      value: media.value,\n    }),\n    ...(media.mime_type ? { mimeType: media.mime_type } : {}),\n    ...(media.file_name ? { name: media.file_name } : {}),\n  })));\n}\n\nfunction normalizeMediaKind(type: string): TurnMedia['kind'] {\n  if (type === 'image' || type === 'video' || type === 'file') return type;\n  return 'audio';\n}\n"]}

package/lib/context/index.d.ts

@@ -8,9 +8,8 @@ export type { TurnContextEnvelopeInput, TurnContextView } from './turn-envelope.
 export type { AgentsInstructionEntry } from './agents-instruction.js';
 export type { ModelResolverConfig } from './model-resolver.js';
 export { ContextSystem, createContextSystemForHost, ProfileContextBuilder, ToneInjector, createDefaultContextBuilders, } from './context-system.js';
-export { buildTurnContextEnvelope, prependTurnContextEnvelope, formatSessionContextLine, TURN_CONTEXT_BEGIN, TURN_CONTEXT_END, } from './turn-envelope.js';
+export { buildTurnContextEnvelope, prependTurnContextEnvelope, formatSessionContextLine, TURN_CONTEXT_BEGIN, TURN_CONTEXT_END, AMBIENT_ENGAGEMENT_METADATA_KEY, } from './turn-envelope.js';
 export { buildTurnUserMessages, applyTurnContextToUserMessages, prependEnvelopeToFirstUserText, } from './turn-user-message.js';
 export { buildAgentsEnvelopeContext, collectAgentsInstructionChain, } from './agents-instruction.js';
 export { resolveModel, resolveModelCandidates } from './model-resolver.js';
 export { DEFAULT_CONTEXT_TAIL_MESSAGE_LIMIT, resolveContextTailMessageLimit, } from './context-tail-limit.js';
-//# sourceMappingURL=index.d.ts.map

package/lib/context/index.js

@@ -2,7 +2,7 @@
  * Context System — builder/injector 链 + turn 上下文构建。
  */
 export { ContextSystem, createContextSystemForHost, ProfileContextBuilder, ToneInjector, createDefaultContextBuilders, } from './context-system.js';
-export { buildTurnContextEnvelope, prependTurnContextEnvelope, formatSessionContextLine, TURN_CONTEXT_BEGIN, TURN_CONTEXT_END, } from './turn-envelope.js';
+export { buildTurnContextEnvelope, prependTurnContextEnvelope, formatSessionContextLine, TURN_CONTEXT_BEGIN, TURN_CONTEXT_END, AMBIENT_ENGAGEMENT_METADATA_KEY, } from './turn-envelope.js';
 export { buildTurnUserMessages, applyTurnContextToUserMessages, prependEnvelopeToFirstUserText, } from './turn-user-message.js';
 export { buildAgentsEnvelopeContext, collectAgentsInstructionChain, } 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,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,GAC9B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAE3E,OAAO,EACL,kCAAkC,EAClC,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,4BAA4B,GAC7B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,wBAAwB,EACxB,0BAA0B,EAC1B,wBAAwB,EACxB,kBAAkB,EAClB,gBAAgB,EAChB,+BAA+B,GAChC,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,qBAAqB,EACrB,8BAA8B,EAC9B,8BAA8B,GAC/B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,0BAA0B,EAC1B,6BAA6B,GAC9B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAE3E,OAAO,EACL,kCAAkC,EAClC,8BAA8B,GAC/B,MAAM,yBAAyB,CAAC","sourcesContent":["/**\n * Context System — builder/injector 链 + turn 上下文构建。\n */\n\nexport type {\n  BuildContext,\n  InjectContext,\n  ContextBuilder,\n  ContextInjector,\n  ContextSystemConfig,\n} from './contracts.js';\n\nexport type { TurnEnvelopeParts } from './envelope-parts.js';\nexport type { TextTurnContextInput, TextTurnContextOutput } from './context-system.js';\nexport type { TurnContextEnvelopeInput, TurnContextView } from './turn-envelope.js';\nexport type { AgentsInstructionEntry } from './agents-instruction.js';\nexport type { ModelResolverConfig } from './model-resolver.js';\n\nexport {\n  ContextSystem,\n  createContextSystemForHost,\n  ProfileContextBuilder,\n  ToneInjector,\n  createDefaultContextBuilders,\n} from './context-system.js';\n\nexport {\n  buildTurnContextEnvelope,\n  prependTurnContextEnvelope,\n  formatSessionContextLine,\n  TURN_CONTEXT_BEGIN,\n  TURN_CONTEXT_END,\n  AMBIENT_ENGAGEMENT_METADATA_KEY,\n} from './turn-envelope.js';\n\nexport {\n  buildTurnUserMessages,\n  applyTurnContextToUserMessages,\n  prependEnvelopeToFirstUserText,\n} from './turn-user-message.js';\n\nexport {\n  buildAgentsEnvelopeContext,\n  collectAgentsInstructionChain,\n} from './agents-instruction.js';\n\nexport { resolveModel, resolveModelCandidates } from './model-resolver.js';\n\nexport {\n  DEFAULT_CONTEXT_TAIL_MESSAGE_LIMIT,\n  resolveContextTailMessageLimit,\n} from './context-tail-limit.js';\n"]}

package/lib/context/model-resolver.d.ts

@@ -6,4 +6,3 @@ export interface ModelResolverConfig {
 }
 export declare function resolveModel(providerModels: string[], modelRegistry: ModelRegistry | null, providerName: string, config: ModelResolverConfig, task?: 'chat' | 'vision' | 'tool_call' | 'summary', preferred?: string): string;
 export declare function resolveModelCandidates(providerModels: string[], modelRegistry: ModelRegistry | null, providerName: string, config: ModelResolverConfig, task?: 'chat' | 'vision' | 'tool_call' | 'summary', preferred?: string): string[];
-//# sourceMappingURL=model-resolver.d.ts.map

package/lib/context/model-resolver.js.map

@@ -1 +1 @@
-{"version":3,"file":"model-resolver.js","sourceRoot":"","sources":["../../src/context/model-resolver.ts"],"names":[],"mappings":"AAQA,MAAM,UAAU,YAAY,CAC1B,cAAwB,EACxB,aAAmC,EACnC,YAAoB,EACpB,MAA2B,EAC3B,OAAoD,MAAM,EAC1D,SAAkB;IAElB,OAAO,sBAAsB,CAAC,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;AACzG,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,cAAwB,EACxB,aAAmC,EACnC,YAAoB,EACpB,MAA2B,EAC3B,OAAoD,MAAM,EAC1D,SAAkB;IAElB,MAAM,UAAU,GAAa,EAAE,CAAC;IAEhC,IAAI,SAAS;QAAE,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC1C,0FAA0F;IAC1F,0FAA0F;IAC1F,gFAAgF;IAChF,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,QAAQ,CAAC,IAAI,MAAM,CAAC,SAAS,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC;QACzG,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpC,CAAC;IACD,IAAI,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,WAAW,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;QACxF,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IACtC,CAAC;IAED,IAAI,aAAa,EAAE,CAAC;QAClB,KAAK,MAAM,EAAE,IAAI,aAAa,CAAC,YAAY,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;YACnE,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAAE,SAAS;YACxE,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAAE,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACpD,CAAC;IACH,CAAC;IAED,KAAK,MAAM,EAAE,IAAI,cAAc,EAAE,CAAC;QAChC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAAE,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpD,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC"}
+{"version":3,"file":"model-resolver.js","sourceRoot":"","sources":["../../src/context/model-resolver.ts"],"names":[],"mappings":"AAQA,MAAM,UAAU,YAAY,CAC1B,cAAwB,EACxB,aAAmC,EACnC,YAAoB,EACpB,MAA2B,EAC3B,OAAoD,MAAM,EAC1D,SAAkB;IAElB,OAAO,sBAAsB,CAAC,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;AACzG,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,cAAwB,EACxB,aAAmC,EACnC,YAAoB,EACpB,MAA2B,EAC3B,OAAoD,MAAM,EAC1D,SAAkB;IAElB,MAAM,UAAU,GAAa,EAAE,CAAC;IAEhC,IAAI,SAAS;QAAE,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC1C,0FAA0F;IAC1F,0FAA0F;IAC1F,gFAAgF;IAChF,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,QAAQ,CAAC,IAAI,MAAM,CAAC,SAAS,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC;QACzG,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpC,CAAC;IACD,IAAI,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,WAAW,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;QACxF,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IACtC,CAAC;IAED,IAAI,aAAa,EAAE,CAAC;QAClB,KAAK,MAAM,EAAE,IAAI,aAAa,CAAC,YAAY,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;YACnE,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAAE,SAAS;YACxE,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAAE,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACpD,CAAC;IACH,CAAC;IAED,KAAK,MAAM,EAAE,IAAI,cAAc,EAAE,CAAC;QAChC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAAE,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpD,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC","sourcesContent":["import type { ModelRegistry } from '@zhin.js/ai';\n\nexport interface ModelResolverConfig {\n  chatModel?: string;\n  /** @deprecated See `ZhinAgentConfig.visionModel`; removed in the next minor. */\n  visionModel?: string;\n}\n\nexport function resolveModel(\n  providerModels: string[],\n  modelRegistry: ModelRegistry | null,\n  providerName: string,\n  config: ModelResolverConfig,\n  task: 'chat' | 'vision' | 'tool_call' | 'summary' = 'chat',\n  preferred?: string,\n): string {\n  return resolveModelCandidates(providerModels, modelRegistry, providerName, config, task, preferred)[0];\n}\n\nexport function resolveModelCandidates(\n  providerModels: string[],\n  modelRegistry: ModelRegistry | null,\n  providerName: string,\n  config: ModelResolverConfig,\n  task: 'chat' | 'vision' | 'tool_call' | 'summary' = 'chat',\n  preferred?: string,\n): string[] {\n  const candidates: string[] = [];\n\n  if (preferred) candidates.push(preferred);\n  // The bound model (`ai.agents.<name>.model`) stays first for image turns too: a text-only\n  // bound model gets the image through the perception pre-pass or a placeholder, instead of\n  // the turn silently switching to whichever registry model looks vision-capable.\n  if ((task === 'chat' || task === 'vision') && config.chatModel && !candidates.includes(config.chatModel)) {\n    candidates.push(config.chatModel);\n  }\n  if (task === 'vision' && config.visionModel && !candidates.includes(config.visionModel)) {\n    candidates.push(config.visionModel);\n  }\n\n  if (modelRegistry) {\n    for (const id of modelRegistry.selectModels(providerName, task, 5)) {\n      if (providerModels.length > 0 && !providerModels.includes(id)) continue;\n      if (!candidates.includes(id)) candidates.push(id);\n    }\n  }\n\n  for (const id of providerModels) {\n    if (!candidates.includes(id)) candidates.push(id);\n  }\n\n  return candidates;\n}\n"]}

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

@@ -1,7 +1,9 @@
 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'> & Partial<Pick<TurnRequest, 'policy'>>;
+export type TurnContextView = Pick<TurnRequest, 'origin' | 'principal' | 'session'> & Partial<Pick<TurnRequest, 'policy' | 'input'>>;
+/** Trusted turn metadata key the IM ingress sets for a turn nobody addressed. */
+export declare const AMBIENT_ENGAGEMENT_METADATA_KEY = "zhinEngagement";
 export interface TurnContextEnvelopeInput {
     turn?: TurnContextView;
     profileSummary?: string;
@@ -21,4 +23,3 @@ 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.js

@@ -1,6 +1,10 @@
 import { getFileMemoryContext, formatMemoryPathsHint } from '../memory-layers.js';
 export const TURN_CONTEXT_BEGIN = '[Turn context]';
 export const TURN_CONTEXT_END = '[/Turn context]';
+/** Trusted turn metadata key the IM ingress sets for a turn nobody addressed. */
+export const AMBIENT_ENGAGEMENT_METADATA_KEY = 'zhinEngagement';
+const AMBIENT_ENGAGEMENT_LINE = 'Engagement: ambient. Nobody called you; you are reading the group chat and chose to look. '
+    + 'Reply only if a group member like you would naturally chime in here; otherwise return {"messages":[]} and stay quiet.';
 export function formatSessionContextLine(turn) {
     const origin = turn.origin;
     if (origin.kind === 'im') {
@@ -34,6 +38,8 @@ export function buildTurnContextEnvelope(input) {
     if (input.turn) {
         lines.push(formatSessionContextLine(input.turn));
         lines.push(formatSenderContextLine(input.turn));
+        if (input.turn.input?.metadata?.[AMBIENT_ENGAGEMENT_METADATA_KEY] === 'ambient')
+            lines.push(AMBIENT_ENGAGEMENT_LINE);
         if (input.turn.policy?.filesystem) {
             const filesystem = input.turn.policy.filesystem;
             lines.push(`Workspace: ${filesystem.workingDirectory ?? filesystem.workspaceRoot} | access:${filesystem.access ?? 'workspace-write'}`);

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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","sourcesContent":["import { getFileMemoryContext, formatMemoryPathsHint } from '../memory-layers.js';\nimport type { TurnRequest } from '../turn/turn-ingress.js';\n\nexport const TURN_CONTEXT_BEGIN = '[Turn context]';\nexport const TURN_CONTEXT_END = '[/Turn context]';\n\nexport type TurnContextView = Pick<TurnRequest, 'origin' | 'principal' | 'session'>\n  & Partial<Pick<TurnRequest, 'policy' | 'input'>>;\n\n/** Trusted turn metadata key the IM ingress sets for a turn nobody addressed. */\nexport const AMBIENT_ENGAGEMENT_METADATA_KEY = 'zhinEngagement';\n\nconst AMBIENT_ENGAGEMENT_LINE = 'Engagement: ambient. Nobody called you; you are reading the group chat and chose to look. '\n  + 'Reply only if a group member like you would naturally chime in here; otherwise return {\"messages\":[]} and stay quiet.';\n\nexport interface TurnContextEnvelopeInput {\n  turn?: TurnContextView;\n  profileSummary?: string;\n  toneHint?: string;\n  deferredStats?: string;\n  activeSkillsContext?: string;\n  quoteSystemHint?: string;\n  modelLine?: string;\n  sdk?: string;\n  agentsContext?: string;\n  /** Rendered \"already told the user\" ledger (#730). */\n  toldLedger?: string;\n  /** BM25-recalled semantic memory for this message (#734). */\n  relevantMemory?: string;\n}\n\nexport function formatSessionContextLine(turn: TurnContextView): string {\n  const origin = turn.origin;\n  if (origin.kind === 'im') {\n    return `Session: platform:${origin.platform} | endpoint:${origin.endpoint} | ${origin.scope}_id:${origin.sceneId}`;\n  }\n  if (origin.kind === 'http') return `Session: origin:http | session_id:${origin.sessionId}`;\n  if (origin.kind === 'a2a') return `Session: origin:a2a | task_id:${origin.taskId}`;\n  if (origin.kind === 'schedule') return `Session: origin:schedule | job_id:${origin.jobId}`;\n  return `Session: origin:internal | source:${origin.source}`;\n}\n\nexport function formatSenderContextLine(turn: TurnContextView): string {\n  const { principal } = turn;\n  const roles = principal.roles.length > 0 ? principal.roles.join(',') : 'user';\n  return principal.displayName?.trim()\n    ? `Sender: id=${principal.subjectId} name=${principal.displayName.trim()} roles=${roles}`\n    : `Sender: id=${principal.subjectId} roles=${roles}`;\n}\n\nexport function buildTurnContextEnvelope(input: TurnContextEnvelopeInput): string | null {\n  const lines: string[] = [];\n  const now = new Date();\n  const tz = Intl.DateTimeFormat().resolvedOptions().timeZone;\n  const timeStr = now.toLocaleString('zh-CN', { timeZone: tz });\n  lines.push(`Time: ${timeStr} (${tz})`);\n\n  if (input.modelLine?.trim()) lines.push(`Model: ${input.modelLine.trim()}`);\n  if (input.sdk?.trim()) lines.push(`Sdk: ${input.sdk.trim()}`);\n\n  if (input.turn) {\n    lines.push(formatSessionContextLine(input.turn));\n    lines.push(formatSenderContextLine(input.turn));\n    if (input.turn.input?.metadata?.[AMBIENT_ENGAGEMENT_METADATA_KEY] === 'ambient') lines.push(AMBIENT_ENGAGEMENT_LINE);\n    if (input.turn.policy?.filesystem) {\n      const filesystem = input.turn.policy.filesystem;\n      lines.push(`Workspace: ${filesystem.workingDirectory ?? filesystem.workspaceRoot} | access:${filesystem.access ?? 'workspace-write'}`);\n    }\n    if (input.turn.origin.kind === 'im') {\n      const platform = input.turn.origin.platform;\n      const sessionKey = input.turn.session.key;\n      const memoryPaths = formatMemoryPathsHint(platform, sessionKey);\n      if (memoryPaths) lines.push(`Memory paths: ${memoryPaths}`);\n      const fileMemory = getFileMemoryContext(undefined, platform, sessionKey);\n      if (fileMemory?.trim()) {\n        lines.push('Memory snapshot:');\n        lines.push(fileMemory.trim());\n      }\n    }\n  }\n\n  if (input.deferredStats?.trim()) lines.push(`Deferred catalog: ${input.deferredStats.trim()}`);\n  if (input.profileSummary?.trim()) lines.push(input.profileSummary.trim());\n  if (input.toneHint?.trim()) lines.push(`[Tone hint] ${input.toneHint.trim()}`);\n  if (input.activeSkillsContext?.trim()) lines.push(input.activeSkillsContext.trim());\n  if (input.quoteSystemHint?.trim()) lines.push(input.quoteSystemHint.trim());\n  if (input.agentsContext?.trim()) lines.push(input.agentsContext.trim());\n  if (input.toldLedger?.trim()) lines.push(input.toldLedger.trim());\n  if (input.relevantMemory?.trim()) lines.push(input.relevantMemory.trim());\n\n  return lines.length === 0\n    ? null\n    : `${TURN_CONTEXT_BEGIN}\\n${lines.join('\\n')}\\n${TURN_CONTEXT_END}`;\n}\n\nexport function prependTurnContextEnvelope(content: string, envelope: string | null | undefined): string {\n  if (!envelope?.trim()) return content;\n  return `${envelope.trim()}\\n\\n${content}`;\n}\n"]}

package/lib/context/turn-user-message.d.ts

@@ -7,4 +7,3 @@ export declare function buildTurnUserMessages(commMessage: Message, rawContent:
 };
 export declare function applyTurnContextToUserMessages(messages: UserMessage[], envelope: string | null | undefined): UserMessage[];
 export declare function prependEnvelopeToFirstUserText(messages: AgentMessage[], envelope: string | null | undefined): AgentMessage[];
-//# sourceMappingURL=turn-user-message.d.ts.map

package/lib/context/turn-user-message.js.map

@@ -1 +1 @@
-{"version":3,"file":"turn-user-message.js","sourceRoot":"","sources":["../../src/context/turn-user-message.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"turn-user-message.js","sourceRoot":"","sources":["../../src/context/turn-user-message.ts"],"names":[],"mappings":"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","sourcesContent":["import { type AgentMessageExtra, type AgentMessage, type UserMessage, createUserMessage, userMessagePlainText } from '@zhin.js/ai';\nimport type { Message } from '@zhin.js/core';\nimport { resolveTurnUserMessage } from '../session/session-io.js';\nimport { prependTurnContextEnvelope } from './turn-envelope.js';\nexport function buildTurnUserMessages(\n  commMessage: Message,\n  rawContent: string,\n): {\n  rawContent: string;\n  userMessageExtra?: AgentMessageExtra;\n  promptMessages: UserMessage[];\n} {\n  const { content, llmMessage } = resolveTurnUserMessage(\n    commMessage as import('@zhin.js/core').AgentTurnMessage,\n    rawContent,\n  );\n  return {\n    rawContent: content,\n    promptMessages: [llmMessage],\n  };\n}\n\nexport function applyTurnContextToUserMessages(\n  messages: UserMessage[],\n  envelope: string | null | undefined,\n): UserMessage[] {\n  if (!envelope?.trim() || messages.length === 0) return messages;\n  return messages.map((msg, i) => {\n    if (i !== 0 || msg.role !== 'user') return msg;\n    const text = userMessagePlainText(msg);\n    return createUserMessage(\n      prependTurnContextEnvelope(text, envelope),\n      msg.media,\n      msg.timestamp,\n      msg.actor,\n      msg.cause,\n    );\n  });\n}\n\nexport function prependEnvelopeToFirstUserText(\n  messages: AgentMessage[],\n  envelope: string | null | undefined,\n): AgentMessage[] {\n  if (!envelope?.trim() || messages.length === 0) return messages;\n  const first = messages[0];\n  if (!first || first.role !== 'user') return messages;\n\n  const content = first.content;\n  if (!Array.isArray(content)) return messages;\n\n  const textIdx = content.findIndex((b) => b?.type === 'text');\n  if (textIdx < 0) {\n    return [\n      { ...first, content: [{ type: 'text', text: envelope.trim() }, ...content] },\n      ...messages.slice(1),\n    ];\n  }\n\n  const block = content[textIdx];\n  if (block.type !== 'text') return messages;\n  const nextText = prependTurnContextEnvelope(block.text, envelope);\n  if (nextText === block.text) return messages;\n\n  const nextContent = [...content];\n  nextContent[textIdx] = { type: 'text', text: nextText };\n  return [{ ...first, content: nextContent }, ...messages.slice(1)];\n}\n"]}

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

@@ -1,6 +1,7 @@
 /**
  * agentLoop turn runner (ADR 0009) — used when ContextRepository is wired.
  */
+import type { AiOutboundSegmentProfile } from '@zhin.js/core';
 import { type AgentOutputElement } from '../outbound/agent-output.js';
 import { type AgentTool, type Usage, type AgentMessage, type ModelInputModality } from '@zhin.js/ai';
 import type { AgentRunJournal } from '@zhin.js/ai/agent-stream';
@@ -25,6 +26,8 @@ export interface AgentLoopTurnInput {
     rawContent: string;
     promptProfile: AgentPromptProfile;
     turnContext: TurnContextView;
+    /** What the IM reply endpoint lets the model author (ReplyPort.segments). */
+    replySegments?: AiOutboundSegmentProfile;
     allTools: AgentTool[];
     resolvedTools: AgentTool[];
     toolExecution: ToolExecutionAuthority;
@@ -119,4 +122,3 @@ 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>;
-//# sourceMappingURL=agent-core-run.d.ts.map

package/lib/core/agent-core-run.js

@@ -1,8 +1,7 @@
 /**
  * agentLoop turn runner (ADR 0009) — used when ContextRepository is wired.
  */
-import { aiOutboundJsonSchema } from '@zhin.js/core';
-import { decodeStructuredReply, STRUCTURED_REPLY_INSTRUCTION } from '../outbound/structured-reply.js';
+import { decodeStructuredReply, structuredReplyInstruction, structuredReplySchema } from '../outbound/structured-reply.js';
 import { renderAgentOutput } from '../outbound/agent-output.js';
 import { mergeToolOutboundElements } from '../media/media-tool-bridge.js';
 import { formatCompact, truncatePreview, getLogger } from '@zhin.js/logger';
@@ -16,7 +15,7 @@ import { planToolRun } from '../tool/runtime.js';
 import { sanitizeAssistantReply, unwrapJsonStringLayers } from './text-sanitize.js';
 import { formatToolCallsForUser } from './tool-calls-user-format.js';
 import { summarizeExhaustedTurn } from './exhausted-turn-reply.js';
-import { recoverStructuredReply } from './structured-reply-recovery.js';
+import { decodeLenientStructuredReply, recoverStructuredReply, STRUCTURED_REPLY_FAILURE } from './structured-reply-recovery.js';
 import { trackTurnCompletionUsage } from './turn-completion-usage.js';
 import { shouldSuppressReplyForSpawnDelegation } from './spawn-delegation.js';
 import { logPhase, tokenUsageLogFields, logAgentLoopIterationEnd } from '../internal/phase-trace.js';
@@ -24,7 +23,7 @@ import { buildAgentPromptCacheStreamOptions } from '../config/index.js';
 import { buildLlmToolsForProvider } from '../tool/deferred-resolution.js';
 import { applyToolToModelOutput } from '../tool/tool-model-output.js';
 import { resolveAlwaysLoadedSet } from '../tool-catalog/resolve-config.js';
-import { resolveDeferredApiTools } from '../tool-catalog/tool-catalog.js';
+import { resolveDeferredApiTools, residentToolNames } from '../tool-catalog/tool-catalog.js';
 import { createTurnEventMapperState, mapAgentEventToTurnEvents, turnUsageEvent, } from './turn-event-mapper.js';
 import { TurnJournalCommitError } from '../turn/journal-integrity.js';
 import { ExecutableToolRegistry } from '../tool/executable-tool-registry.js';
@@ -133,14 +132,6 @@ function logAssistantIterationFailure(assistant, modelId, sessionId) {
         error: truncatePreview(assistant.errorMessage, 500),
     }));
 }
-/** ai.agent.outputSchema 配置 → 传给 LLM 的 JSON Schema（true/'segments' 用 zhin 出站契约）。 */
-function resolveAgentOutputSchema(value) {
-    if (!value)
-        return undefined;
-    if (value === true || value === 'segments')
-        return aiOutboundJsonSchema;
-    return value;
-}
 function toolResultToAgentMessage(toolCall, result, isError) {
     const text = typeof result === 'string'
         ? result
@@ -340,13 +331,13 @@ export async function* runAgentLoopTextTurnRun(input) {
     const preData = toolRun.preExecution.data;
     // IM conversations get a message contract. Detached/programmatic turns keep
     // their text/custom-schema contract and never inherit the IM preset.
+    // ai.agent.outputSchema: true / 'segments' → zhin message contract; an object → caller's own schema.
     const configuredSchema = host.config.outputSchema ?? 'segments';
-    const imReply = input.turnContext.origin.kind === 'im'
-        && input.conversationPersistence !== 'none'
-        && (configuredSchema === true || configuredSchema === 'segments');
-    const outputSchema = resolveAgentOutputSchema(configuredSchema === true || configuredSchema === 'segments'
-        ? (imReply ? 'segments' : false)
-        : configuredSchema);
+    const messagePreset = configuredSchema === true || configuredSchema === 'segments';
+    const imReply = messagePreset && input.turnContext.origin.kind === 'im'
+        && input.conversationPersistence !== 'none';
+    const outputSchema = imReply ? structuredReplySchema(input.replySegments)
+        : messagePreset || !configuredSchema ? undefined : configuredSchema;
     const turnShellPolicy = input.turnContext.policy?.shell;
     const execPolicyConfig = turnShellPolicy
         ? {
@@ -371,7 +362,7 @@ export async function* runAgentLoopTextTurnRun(input) {
         : buildChatPathSystemPrompt(host, personaEnhanced, input.promptProfile, input.promptRuntime);
     const proseSystemPrompt = systemPrompt;
     if (imReply) {
-        systemPrompt = `${systemPrompt}\n\n${STRUCTURED_REPLY_INSTRUCTION}`;
+        systemPrompt = `${systemPrompt}\n\n${structuredReplyInstruction(input.replySegments)}`;
     }
     const agentTools = hasTools
         ? turnShellPolicy
@@ -385,10 +376,12 @@ export async function* runAgentLoopTextTurnRun(input) {
     if (!directTools && hasTools && (!deferredController || catalog.length === 0)) {
         throw new Error('Deferred tool loading requires a turn-owned controller and catalog');
     }
+    // Config names plus tools the capability plan pinned (platform tools, `alwaysLoaded` plugin tools).
+    const turnResidentTools = () => residentToolNames(catalog, resolveAlwaysLoadedSet(host.config));
     const refreshResolvedTools = () => {
         if (directTools)
             return resolvedTools;
-        const alwaysLoaded = resolveAlwaysLoadedSet(host.config);
+        const alwaysLoaded = turnResidentTools();
         const loaded = deferredController.loadedToolNames();
         return resolveDeferredApiTools(catalog, alwaysLoaded, loaded);
     };
@@ -448,7 +441,7 @@ export async function* runAgentLoopTextTurnRun(input) {
     const executableTools = new ExecutableToolRegistry(agentTools);
     let llmTools = directTools
         ? agentToolsToLlmTools(agentTools)
-        : buildLlmToolsForProvider(llmModel.sdk, catalog, agentTools, resolveAlwaysLoadedSet(host.config), deferredController?.loadedToolNames() ?? []);
+        : buildLlmToolsForProvider(llmModel.sdk, catalog, agentTools, turnResidentTools(), deferredController?.loadedToolNames() ?? []);
     if (hasTools) {
         noteTurnTrace(traceTurnId(input.turnContext), {
             kind: 'context_budget',
@@ -491,7 +484,7 @@ export async function* runAgentLoopTextTurnRun(input) {
         executableTools.replace(nextAgentTools);
         llmTools = directTools
             ? agentToolsToLlmTools(nextAgentTools)
-            : buildLlmToolsForProvider(llmModel.sdk, catalog, nextAgentTools, resolveAlwaysLoadedSet(host.config), deferredController?.loadedToolNames() ?? []);
+            : buildLlmToolsForProvider(llmModel.sdk, catalog, nextAgentTools, turnResidentTools(), deferredController?.loadedToolNames() ?? []);
         return llmTools;
     };
     const contextWindow = llmModel.contextWindow ?? host.config.contextTokens;
@@ -907,7 +900,8 @@ export async function* runAgentLoopTextTurnRun(input) {
         hostReply = !summary.assistant;
     }
     const structuredReply = imReply && !hostReply;
-    const continuationPrefix = continuations > 0
+    // A chat member does not announce how many steps a task took; only non-IM callers get the notice.
+    const continuationPrefix = continuations > 0 && input.turnContext.origin.kind !== 'im'
         ? `（任务步骤较多，已自动续跑 ${continuations} 次）\n\n` : '';
     const proseReply = structuredReply ? ''
         : sanitizeAssistantReply(rawReply, { toolSummary: formatToolCallsForUser(toolCalls) });
@@ -915,25 +909,35 @@ export async function* runAgentLoopTextTurnRun(input) {
     let output = delegatedOnly || structuredReply ? [] : parseOutput(textReply);
     if (!delegatedOnly && structuredReply) {
         try {
-            output = decodeStructuredReply(rawReply);
+            output = decodeStructuredReply(rawReply, input.replySegments);
         }
         catch (error) {
-            const recovery = await recoverStructuredReply({
-                transport: completionUsage.transport, model: llmModel, raw: rawReply,
-                error: error instanceof Error ? error : new Error('Invalid structured reply'), signal,
-            });
-            output = recovery.output;
-            const lastBatch = conversationBatches.at(-1);
-            if (recovery.exchange) {
-                lastBatch?.messages.push(...recovery.exchange);
-                lastBatch?.messageExtras.push(undefined, undefined);
+            const messages = conversationBatches.at(-1)?.messages;
+            const rejected = messages?.at(-1);
+            const lenient = decodeLenientStructuredReply(rawReply, input.replySegments);
+            if (lenient) {
+                output = lenient.output;
+                if (messages && rejected?.role === 'assistant') {
+                    messages[messages.length - 1] = { ...rejected, content: [{ type: 'text', text: lenient.text }] };
+                }
+            }
+            else {
+                const recovery = await recoverStructuredReply({
+                    transport: completionUsage.transport, model: llmModel, raw: rawReply,
+                    error: error instanceof Error ? error : new Error('Invalid structured reply'), signal,
+                    segments: input.replySegments,
+                });
+                output = recovery.output;
+                // History must match what the user saw: the corrected reply, or the failure text. Never the
+                // correction prompt (it embeds the rejected raw text) and never the rejected raw reply.
+                if (messages && rejected?.role === 'assistant') {
+                    messages[messages.length - 1] = recovery.assistant
+                        ?? { ...rejected, content: [{ type: 'text', text: STRUCTURED_REPLY_FAILURE }] };
+                }
             }
         }
     }
     if (!delegatedOnly) {
-        if (structuredReply && continuationPrefix && output[0]?.type === 'message') {
-            output[0].segments.unshift({ type: 'text', data: { text: continuationPrefix } });
-        }
         output = mergeToolOutboundElements(output, toolCalls);
     }
     const finalReply = imReply ? renderAgentOutput(output) : textReply;