@zhin.js/agent 0.3.1 → 1.0.2

package/lib/session/branch-summarization-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-summarization-runtime.d.ts","sourceRoot":"","sources":["../../src/session/branch-summarization-runtime.ts"],"names":[],"mappings":"AAAA;;GAEG;AAUH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,MAAM,WAAW,0BAA0B;IACzC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,wBAAsB,gCAAgC,CACpD,IAAI,EAAE,gBAAgB,EACtB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACpC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC,CAmCf;AAED,wBAAsB,uCAAuC,CAC3D,IAAI,EAAE,gBAAgB,EACtB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED,wBAAsB,kCAAkC,CACtD,IAAI,EAAE,gBAAgB,EACtB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAe3C"}

package/lib/session/branch-summarization-runtime.js

@@ -0,0 +1,58 @@
+/**
+ * Branch summarization on session tree switch — ADR 0010 D3.
+ */
+import { abandonedRowsToMessages, collectAbandonedPathRows, compactAgentMessages, estimateAgentMessagesTokens, getLlmTransportModel, } from '@zhin.js/ai';
+export async function summarizeAbandonedBranchIfNeeded(host, sessionId, oldLeafId, newLeafId, options = {}) {
+    const compaction = options.compactionConfig ?? host.config.compaction;
+    if (compaction?.enabled === false)
+        return;
+    if (oldLeafId == null || oldLeafId === newLeafId)
+        return;
+    if (await host.contextRepository.hasBranchSummary(sessionId, newLeafId))
+        return;
+    const allRows = await host.contextRepository.loadMessageRows(sessionId);
+    const abandoned = collectAbandonedPathRows(allRows, oldLeafId, newLeafId);
+    if (abandoned.length === 0)
+        return;
+    const messages = abandonedRowsToMessages(abandoned);
+    const keepRecentTokens = compaction?.keepRecentTokens ?? 20_000;
+    if (estimateAgentMessagesTokens(messages) <= keepRecentTokens)
+        return;
+    const provider = host.getTurnProvider();
+    const modelId = host.config.chatModel || provider.models[0] || '';
+    const llmModel = getLlmTransportModel(provider.name, modelId);
+    const contextWindow = options.contextWindow ?? llmModel.contextWindow ?? host.config.contextTokens;
+    const result = await compactAgentMessages({
+        model: llmModel,
+        messages,
+        contextWindow,
+        keepRecentTokens: Math.min(keepRecentTokens, Math.max(500, Math.floor(messages.length * 200))),
+        minKeepCount: 1,
+        customInstructions: 'Summarize this abandoned conversation branch so it can be recalled later if the user returns to it.',
+    });
+    if (!result.summary?.trim())
+        return;
+    await host.contextRepository.saveSummary(sessionId, result.summary, {
+        branchAnchorMessageId: newLeafId,
+    });
+}
+export async function switchActiveLeafWithBranchSummarization(host, sessionId, messageId, options = {}) {
+    const session = await host.agentSessionStore.getBySessionId(sessionId);
+    const oldLeaf = session?.active_leaf_message_id;
+    if (oldLeaf === messageId)
+        return true;
+    await summarizeAbandonedBranchIfNeeded(host, sessionId, oldLeaf, messageId, options);
+    return host.contextRepository.setActiveLeaf(sessionId, messageId);
+}
+export async function jumpToBranchIndexWithSummarization(host, sessionId, index, options = {}) {
+    const points = await host.contextRepository.listBranchPoints(sessionId);
+    const point = points.find(p => p.index === index);
+    if (!point) {
+        return { ok: false, message: `未找到分支点 #${index}` };
+    }
+    const ok = await switchActiveLeafWithBranchSummarization(host, sessionId, point.messageId, options);
+    return ok
+        ? { ok: true, message: `已跳转到分支点 #${index}：${point.preview}` }
+        : { ok: false, message: '跳转失败' };
+}
+//# sourceMappingURL=branch-summarization-runtime.js.map

package/lib/session/branch-summarization-runtime.js.map

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

package/lib/session/contracts.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Session System — 模块契约（与实现同步）。
+ *
+ * 实现：`SessionSystem.registerStrategy` + `prepareTextTurn` / `touchAfterTurn`；
+ * IM/Agent 双 store 由 `ZhinAgentPrivate` 注入（`session-io` SSOT），
+ * 非本模块内 `SessionStore` 注册表。`contracts.SessionStore` 为策略层抽象。
+ */
+import type { Message } from '@zhin.js/core';
+export interface Session {
+    sessionKey: string;
+}
+export interface CreateSessionInput {
+    sessionKey: string;
+    message: Message;
+}
+export interface SessionStore {
+    findActive(sessionKey: string): Promise<Session | null>;
+    create(input: CreateSessionInput): Promise<Session>;
+    archive(sessionKey: string): Promise<void>;
+}
+export interface SessionStrategy {
+    resolveSessionKey(message: Message): string;
+    shouldArchive(message: Message): boolean;
+}
+export interface SessionSystemConfig {
+}
+//# sourceMappingURL=contracts.d.ts.map

package/lib/session/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../src/session/contracts.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C,MAAM,WAAW,OAAO;IACtB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IACxD,MAAM,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACpD,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,eAAe;IAC9B,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;IAC5C,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC;CAC1C;AAED,MAAM,WAAW,mBAAmB;CAEnC"}

package/lib/session/contracts.js

@@ -0,0 +1,9 @@
+/**
+ * Session System — 模块契约（与实现同步）。
+ *
+ * 实现：`SessionSystem.registerStrategy` + `prepareTextTurn` / `touchAfterTurn`；
+ * IM/Agent 双 store 由 `ZhinAgentPrivate` 注入（`session-io` SSOT），
+ * 非本模块内 `SessionStore` 注册表。`contracts.SessionStore` 为策略层抽象。
+ */
+export {};
+//# sourceMappingURL=contracts.js.map

package/lib/session/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../src/session/contracts.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/lib/session/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Session System — SessionSystem + 策略 + session-io（契约见 contracts.ts）。
+ */
+export type { Session, CreateSessionInput, SessionStore, SessionStrategy, SessionSystemConfig, } from './contracts.js';
+export type { SessionIODeps } from './session-io.js';
+export type { TurnSessionPrep } from './session-system.js';
+export { SessionSystem, createSessionSystem } from './session-system.js';
+export { CollaborationSessionStrategy, SimpleSessionStrategy, } from './strategies.js';
+export { buildUserMessageExtra, prepareUserContentForSession, layerInboundUserTurnBody, resolveTurnUserMessage, formatUserContentForSession, buildSessionCreateInput, buildImTranscriptQuery, buildHistoryMessagesFromContext, resolveSessionIsNewBeforeCreate, beginTurnSession, touchSession, archiveSessionByKey, } from './session-io.js';
+export { resolveAgentTurnSessionKey, resolveAgentSessionKeyForTurn, resolveArtifactRunId, } from '../collaboration/resolve-agent-session-key.js';
+export { resolvePassiveGroupSessionKey, recordPassiveGroupMessage, consumePassiveGroupContextForTurn, appendPassiveGroupMessageToContext, } from './passive-group-session.js';
+export { pushPassiveGroupLine, drainPassiveGroupBuffer, peekPassiveGroupBuffer, formatPassiveGroupContextBlock, prunePassiveLines, MAX_PASSIVE_LINES, PASSIVE_TTL_MS, } from './passive-group-buffer.js';
+export type { PassiveGroupLine } from './passive-group-buffer.js';
+export { listSessionTreeForCommMessage, jumpSessionTreeForCommMessage, } from './session-tree-commands.js';
+export { summarizeAbandonedBranchIfNeeded, } from './branch-summarization-runtime.js';
+export type { BranchSummarizationOptions } from './branch-summarization-runtime.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EACV,OAAO,EACP,kBAAkB,EAClB,YAAY,EACZ,eAAe,EACf,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AAExB,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,EACL,4BAA4B,EAC5B,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,qBAAqB,EACrB,4BAA4B,EAC5B,wBAAwB,EACxB,sBAAsB,EACtB,2BAA2B,EAC3B,uBAAuB,EACvB,sBAAsB,EACtB,+BAA+B,EAC/B,+BAA+B,EAC/B,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,0BAA0B,EAC1B,6BAA6B,EAC7B,oBAAoB,GACrB,MAAM,+CAA+C,CAAC;AAEvD,OAAO,EACL,6BAA6B,EAC7B,yBAAyB,EACzB,iCAAiC,EACjC,kCAAkC,GACnC,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,sBAAsB,EACtB,8BAA8B,EAC9B,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,GACf,MAAM,2BAA2B,CAAC;AACnC,YAAY,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,OAAO,EACL,6BAA6B,EAC7B,6BAA6B,GAC9B,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,gCAAgC,GACjC,MAAM,mCAAmC,CAAC;AAC3C,YAAY,EAAE,0BAA0B,EAAE,MAAM,mCAAmC,CAAC"}

package/lib/session/index.js

@@ -0,0 +1,12 @@
+/**
+ * Session System — SessionSystem + 策略 + session-io（契约见 contracts.ts）。
+ */
+export { SessionSystem, createSessionSystem } from './session-system.js';
+export { CollaborationSessionStrategy, SimpleSessionStrategy, } from './strategies.js';
+export { buildUserMessageExtra, prepareUserContentForSession, layerInboundUserTurnBody, resolveTurnUserMessage, formatUserContentForSession, buildSessionCreateInput, buildImTranscriptQuery, buildHistoryMessagesFromContext, resolveSessionIsNewBeforeCreate, beginTurnSession, touchSession, archiveSessionByKey, } from './session-io.js';
+export { resolveAgentTurnSessionKey, resolveAgentSessionKeyForTurn, resolveArtifactRunId, } from '../collaboration/resolve-agent-session-key.js';
+export { resolvePassiveGroupSessionKey, recordPassiveGroupMessage, consumePassiveGroupContextForTurn, appendPassiveGroupMessageToContext, } from './passive-group-session.js';
+export { pushPassiveGroupLine, drainPassiveGroupBuffer, peekPassiveGroupBuffer, formatPassiveGroupContextBlock, prunePassiveLines, MAX_PASSIVE_LINES, PASSIVE_TTL_MS, } from './passive-group-buffer.js';
+export { listSessionTreeForCommMessage, jumpSessionTreeForCommMessage, } from './session-tree-commands.js';
+export { summarizeAbandonedBranchIfNeeded, } from './branch-summarization-runtime.js';
+//# sourceMappingURL=index.js.map

package/lib/session/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAaH,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,EACL,4BAA4B,EAC5B,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,qBAAqB,EACrB,4BAA4B,EAC5B,wBAAwB,EACxB,sBAAsB,EACtB,2BAA2B,EAC3B,uBAAuB,EACvB,sBAAsB,EACtB,+BAA+B,EAC/B,+BAA+B,EAC/B,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,0BAA0B,EAC1B,6BAA6B,EAC7B,oBAAoB,GACrB,MAAM,+CAA+C,CAAC;AAEvD,OAAO,EACL,6BAA6B,EAC7B,yBAAyB,EACzB,iCAAiC,EACjC,kCAAkC,GACnC,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,sBAAsB,EACtB,8BAA8B,EAC9B,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,GACf,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EACL,6BAA6B,EAC7B,6BAA6B,GAC9B,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,gCAAgC,GACjC,MAAM,mCAAmC,CAAC"}

package/lib/session/passive-group-buffer.d.ts

@@ -0,0 +1,15 @@
+export interface PassiveGroupLine {
+    senderId: string;
+    senderName?: string;
+    text: string;
+    at: number;
+}
+export declare const MAX_PASSIVE_LINES = 50;
+export declare const PASSIVE_TTL_MS: number;
+export declare function prunePassiveLines(lines: PassiveGroupLine[]): PassiveGroupLine[];
+export declare function pushPassiveGroupLine(sessionKey: string, line: PassiveGroupLine): void;
+export declare function drainPassiveGroupBuffer(sessionKey: string): PassiveGroupLine[];
+/** 测试 / 诊断 */
+export declare function peekPassiveGroupBuffer(sessionKey: string): readonly PassiveGroupLine[];
+export declare function formatPassiveGroupContextBlock(lines: readonly PassiveGroupLine[]): string | null;
+//# sourceMappingURL=passive-group-buffer.d.ts.map

package/lib/session/passive-group-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"passive-group-buffer.d.ts","sourceRoot":"","sources":["../../src/session/passive-group-buffer.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAID,eAAO,MAAM,iBAAiB,KAAK,CAAC;AACpC,eAAO,MAAM,cAAc,QAAiB,CAAC;AAE7C,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,EAAE,GAAG,gBAAgB,EAAE,CAK/E;AAED,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAIrF;AAED,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAI9E;AAED,cAAc;AACd,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,gBAAgB,EAAE,CAEtF;AAED,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,GAAG,MAAM,GAAG,IAAI,CAchG"}

package/lib/session/passive-group-buffer.js

@@ -0,0 +1,45 @@
+/**
+ * 群/频道旁听缓冲：未 @ 的消息先入内存，@ 触发时再与当前 @ 合并发给 LLM。
+ */
+import { HISTORY_CONTEXT_MARKER } from '../config/index.js';
+const buffers = new Map();
+export const MAX_PASSIVE_LINES = 50;
+export const PASSIVE_TTL_MS = 30 * 60 * 1000;
+export function prunePassiveLines(lines) {
+    const cutoff = Date.now() - PASSIVE_TTL_MS;
+    const fresh = lines.filter((line) => line.at >= cutoff);
+    if (fresh.length <= MAX_PASSIVE_LINES)
+        return fresh;
+    return fresh.slice(fresh.length - MAX_PASSIVE_LINES);
+}
+export function pushPassiveGroupLine(sessionKey, line) {
+    const list = buffers.get(sessionKey) ?? [];
+    list.push(line);
+    buffers.set(sessionKey, prunePassiveLines(list));
+}
+export function drainPassiveGroupBuffer(sessionKey) {
+    const list = buffers.get(sessionKey) ?? [];
+    buffers.delete(sessionKey);
+    return list;
+}
+/** 测试 / 诊断 */
+export function peekPassiveGroupBuffer(sessionKey) {
+    return buffers.get(sessionKey) ?? [];
+}
+export function formatPassiveGroupContextBlock(lines) {
+    if (lines.length === 0)
+        return null;
+    const body = lines
+        .map((line) => {
+        const name = (line.senderName?.trim() || line.senderId).replace(/[\]\s]+/g, '_').slice(0, 64);
+        const id = line.senderId.trim() || 'unknown';
+        return `[sender:id=${id} name=${name} roles=user] ${line.text}`;
+    })
+        .join('\n');
+    return [
+        HISTORY_CONTEXT_MARKER,
+        'Group messages since your last reply (not @mentions; background only — respond to the current @ message below).',
+        body,
+    ].join('\n');
+}
+//# sourceMappingURL=passive-group-buffer.js.map

package/lib/session/passive-group-buffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"passive-group-buffer.js","sourceRoot":"","sources":["../../src/session/passive-group-buffer.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAS5D,MAAM,OAAO,GAAG,IAAI,GAAG,EAA8B,CAAC;AAEtD,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AACpC,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAE7C,MAAM,UAAU,iBAAiB,CAAC,KAAyB;IACzD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,cAAc,CAAC;IAC3C,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI,MAAM,CAAC,CAAC;IACxD,IAAI,KAAK,CAAC,MAAM,IAAI,iBAAiB;QAAE,OAAO,KAAK,CAAC;IACpD,OAAO,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,iBAAiB,CAAC,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,UAAkB,EAAE,IAAsB;IAC7E,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;IAC3C,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChB,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,UAAkB;IACxD,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;IAC3C,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAC3B,OAAO,IAAI,CAAC;AACd,CAAC;AAED,cAAc;AACd,MAAM,UAAU,sBAAsB,CAAC,UAAkB;IACvD,OAAO,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,8BAA8B,CAAC,KAAkC;IAC/E,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACpC,MAAM,IAAI,GAAG,KAAK;SACf,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACZ,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC9F,MAAM,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,SAAS,CAAC;QAC7C,OAAO,cAAc,EAAE,SAAS,IAAI,gBAAgB,IAAI,CAAC,IAAI,EAAE,CAAC;IAClE,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,OAAO;QACL,sBAAsB;QACtB,iHAAiH;QACjH,IAAI;KACL,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/lib/session/passive-group-session.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 群/频道 Passive Group 上下文 — session key SSOT + buffer record/drain。
+ */
+import type { Message } from '@zhin.js/core';
+import type { CollaborationScene } from '../collaboration/types.js';
+import type { ZhinAgentPrivate } from '../internal/agent-host.js';
+export declare function resolvePassiveGroupSessionKey(message: Message, cell?: CollaborationScene): string;
+export declare function recordPassiveGroupMessage(agent: ZhinAgentPrivate, message: Message, rawText: string, cell?: CollaborationScene): Promise<void>;
+export declare function consumePassiveGroupContextForTurn(message: Message): string | null;
+/** @deprecated use recordPassiveGroupMessage */
+export declare function appendPassiveGroupMessageToContext(agent: ZhinAgentPrivate, message: Message, rawText: string, cell?: CollaborationScene): Promise<void>;
+//# sourceMappingURL=passive-group-session.d.ts.map

package/lib/session/passive-group-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"passive-group-session.d.ts","sourceRoot":"","sources":["../../src/session/passive-group-session.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAQpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AASlE,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,kBAAkB,GACxB,MAAM,CAER;AAED,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,gBAAgB,EACvB,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,kBAAkB,GACxB,OAAO,CAAC,IAAI,CAAC,CAcf;AAED,wBAAgB,iCAAiC,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAGjF;AAED,gDAAgD;AAChD,wBAAsB,kCAAkC,CACtD,KAAK,EAAE,gBAAgB,EACvB,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,kBAAkB,GACxB,OAAO,CAAC,IAAI,CAAC,CAEf"}

package/lib/session/passive-group-session.js

@@ -0,0 +1,36 @@
+import { resolveAgentTurnSessionKey } from '../collaboration/resolve-agent-session-key.js';
+import { buildSessionCreateInput, prepareUserContentForSession } from './session-io.js';
+import { drainPassiveGroupBuffer, formatPassiveGroupContextBlock, pushPassiveGroupLine, } from './passive-group-buffer.js';
+function resolveSenderDisplayName(message) {
+    if (!message?.$sender)
+        return 'unknown';
+    const sender = message.$sender;
+    const raw = sender.nickname || sender.name || sender.id;
+    return raw != null ? String(raw).trim().slice(0, 64) : 'unknown';
+}
+export function resolvePassiveGroupSessionKey(message, cell) {
+    return resolveAgentTurnSessionKey(message, cell);
+}
+export async function recordPassiveGroupMessage(agent, message, rawText, cell) {
+    const { content } = prepareUserContentForSession(message, rawText);
+    if (!content.trim())
+        return;
+    const sessionKey = resolvePassiveGroupSessionKey(message, cell);
+    const sessionInput = buildSessionCreateInput(sessionKey, message);
+    await agent.agentSessionStore.getOrCreateActive(sessionInput);
+    pushPassiveGroupLine(sessionKey, {
+        senderId: String(message.$sender?.id ?? 'unknown'),
+        senderName: resolveSenderDisplayName(message),
+        text: content,
+        at: Date.now(),
+    });
+}
+export function consumePassiveGroupContextForTurn(message) {
+    const sessionKey = resolvePassiveGroupSessionKey(message);
+    return formatPassiveGroupContextBlock(drainPassiveGroupBuffer(sessionKey));
+}
+/** @deprecated use recordPassiveGroupMessage */
+export async function appendPassiveGroupMessageToContext(agent, message, rawText, cell) {
+    await recordPassiveGroupMessage(agent, message, rawText, cell);
+}
+//# sourceMappingURL=passive-group-session.js.map

package/lib/session/passive-group-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"passive-group-session.js","sourceRoot":"","sources":["../../src/session/passive-group-session.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,0BAA0B,EAAE,MAAM,+CAA+C,CAAC;AAC3F,OAAO,EAAE,uBAAuB,EAAE,4BAA4B,EAAE,MAAM,iBAAiB,CAAC;AACxF,OAAO,EACL,uBAAuB,EACvB,8BAA8B,EAC9B,oBAAoB,GACrB,MAAM,2BAA2B,CAAC;AAGnC,SAAS,wBAAwB,CAAC,OAAgB;IAChD,IAAI,CAAC,OAAO,EAAE,OAAO;QAAE,OAAO,SAAS,CAAC;IACxC,MAAM,MAAM,GAAG,OAAO,CAAC,OAA4D,CAAC;IACpF,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,EAAE,CAAC;IACxD,OAAO,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,6BAA6B,CAC3C,OAAgB,EAChB,IAAyB;IAEzB,OAAO,0BAA0B,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AACnD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,KAAuB,EACvB,OAAgB,EAChB,OAAe,EACf,IAAyB;IAEzB,MAAM,EAAE,OAAO,EAAE,GAAG,4BAA4B,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACnE,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE;QAAE,OAAO;IAE5B,MAAM,UAAU,GAAG,6BAA6B,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAChE,MAAM,YAAY,GAAG,uBAAuB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAClE,MAAM,KAAK,CAAC,iBAAiB,CAAC,iBAAiB,CAAC,YAAY,CAAC,CAAC;IAE9D,oBAAoB,CAAC,UAAU,EAAE;QAC/B,QAAQ,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,IAAI,SAAS,CAAC;QAClD,UAAU,EAAE,wBAAwB,CAAC,OAAO,CAAC;QAC7C,IAAI,EAAE,OAAO;QACb,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE;KACf,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,iCAAiC,CAAC,OAAgB;IAChE,MAAM,UAAU,GAAG,6BAA6B,CAAC,OAAO,CAAC,CAAC;IAC1D,OAAO,8BAA8B,CAAC,uBAAuB,CAAC,UAAU,CAAC,CAAC,CAAC;AAC7E,CAAC;AAED,gDAAgD;AAChD,MAAM,CAAC,KAAK,UAAU,kCAAkC,CACtD,KAAuB,EACvB,OAAgB,EAChB,OAAe,EACf,IAAyB;IAEzB,MAAM,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;AACjE,CAAC"}

package/lib/session/session-io.d.ts

@@ -0,0 +1,43 @@
+import { type MemoryIMSessionStore, type IMSessionStore, type MemoryAgentSessionStore, type AgentSessionStore, type ContextRepository, type CreateIMSessionInput, type CreateAgentSessionInput, type AgentMessage, type AgentMessageExtra, type UserMessage } from '@zhin.js/ai';
+import { type AgentTurnMessage, type Message } from '@zhin.js/core';
+export interface SessionIODeps {
+    imSessionStore: IMSessionStore | MemoryIMSessionStore;
+    agentSessionStore: AgentSessionStore | MemoryAgentSessionStore;
+    contextRepository: ContextRepository;
+}
+/** 群/频道 user 消息的 sender 元数据（写入 `agent_messages.extra`） */
+export declare function buildUserMessageExtra(commMessage: Message): AgentMessageExtra | undefined;
+/** 剥离伪造前缀后的用户正文 + 可选 extra（入库 payload 用） */
+export declare function prepareUserContentForSession(commMessage: Message, rawContent: string): {
+    content: string;
+    extra?: AgentMessageExtra;
+};
+/** 旁听块 + 引用块 + 当前 @ 正文分层（仅 LLM 侧；入库 payload 仍为干净正文） */
+export declare function layerInboundUserTurnBody(body: string, opts?: {
+    passiveBlock?: string | null;
+    quoteBlock?: string | null;
+}): string;
+/** 本轮 user 消息：干净正文 + extra + LLM 渲染（引用/sender 仅 extra + 加载时拼接） */
+export declare function resolveTurnUserMessage(commMessage: AgentTurnMessage, rawContent: string, options?: {
+    passiveBlock?: string | null;
+}): {
+    content: string;
+    extra?: AgentMessageExtra;
+    llmMessage: UserMessage;
+};
+/** @deprecated 使用 `resolveTurnUserMessage` */
+export declare function formatUserContentForSession(commMessage: AgentTurnMessage, rawContent: string): string;
+export declare function buildSessionCreateInput(sessionKey: string, commMessage: Message): CreateIMSessionInput & CreateAgentSessionInput;
+export declare function buildImTranscriptQuery(commMessage: Message): import('@zhin.js/ai').ImTranscriptQuery;
+export declare function buildHistoryMessagesFromContext(deps: SessionIODeps, sessionId: string, currentUserContent: string): Promise<AgentMessage[]>;
+/**
+ * 在 `getOrCreateActive` 之前调用：是否视为新会话纪元（用于 ai.session.new）。
+ */
+export declare function resolveSessionIsNewBeforeCreate(deps: SessionIODeps, sessionKey: string): Promise<boolean>;
+export declare function beginTurnSession(deps: SessionIODeps, sessionKey: string, commMessage: Message): Promise<{
+    sessionKey: string;
+    sessionId: string;
+}>;
+export declare function touchSession(deps: SessionIODeps, sessionId: string): Promise<void>;
+export declare function archiveSessionByKey(deps: SessionIODeps, sessionKey: string): Promise<boolean>;
+//# sourceMappingURL=session-io.d.ts.map

package/lib/session/session-io.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-io.d.ts","sourceRoot":"","sources":["../../src/session/session-io.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,oBAAoB,EAAE,KAAK,cAAc,EAAE,KAAK,uBAAuB,EAAE,KAAK,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,KAAK,oBAAoB,EAAE,KAAK,uBAAuB,EAAE,KAAK,YAAY,EAA8C,KAAK,iBAAiB,EAAgC,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAC3V,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,OAAO,EAAiJ,MAAM,eAAe,CAAC;AAEnN,MAAM,WAAW,aAAa;IAC5B,cAAc,EAAE,cAAc,GAAG,oBAAoB,CAAC;IACtD,iBAAiB,EAAE,iBAAiB,GAAG,uBAAuB,CAAC;IAC/D,iBAAiB,EAAE,iBAAiB,CAAC;CACtC;AA+BD,0DAA0D;AAC1D,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,OAAO,GAAG,iBAAiB,GAAG,SAAS,CAWzF;AAED,4CAA4C;AAC5C,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,OAAO,EACpB,UAAU,EAAE,MAAM,GACjB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,iBAAiB,CAAA;CAAE,CAIhD;AAED,uDAAuD;AACvD,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAClE,MAAM,CAMR;AAED,kEAAkE;AAClE,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,gBAAgB,EAC7B,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GACzC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAAC,UAAU,EAAE,WAAW,CAAA;CAAE,CAqBzE;AAED,8CAA8C;AAC9C,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,gBAAgB,EAC7B,UAAU,EAAE,MAAM,GACjB,MAAM,CAKR;AAED,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,OAAO,GACnB,oBAAoB,GAAG,uBAAuB,CAShD;AAED,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,OAAO,GACnB,OAAO,aAAa,EAAE,iBAAiB,CAOzC;AAED,wBAAsB,+BAA+B,CACnD,IAAI,EAAE,aAAa,EACnB,SAAS,EAAE,MAAM,EACjB,kBAAkB,EAAE,MAAM,GACzB,OAAO,CAAC,YAAY,EAAE,CAAC,CAIzB;AAED;;GAEG;AACH,wBAAsB,+BAA+B,CACnD,IAAI,EAAE,aAAa,EACnB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC,CAGlB;AAED,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,aAAa,EACnB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,OAAO,GACnB,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAIpD;AAED,wBAAsB,YAAY,CAChC,IAAI,EAAE,aAAa,EACnB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,aAAa,EACnB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC,CAGlB"}

package/lib/session/session-io.js

@@ -0,0 +1,135 @@
+import { createUserMessage, renderUserMessageForLlm } from '@zhin.js/ai';
+import { formatSenderRolesForLabel, QUOTE_CONTEXT_BLOCK_EXTRA_KEY, resolveSceneFieldsFromMessage, senderRolesFromMessage, stripUserSpoofedSenderPrefix } from '@zhin.js/core';
+import { CURRENT_MESSAGE_MARKER } from '../config/index.js';
+function sanitizeSenderAttr(value) {
+    const trimmed = value.trim().replace(/[\]\s]+/g, '_');
+    return trimmed.length > 0 ? trimmed.slice(0, 64) : 'unknown';
+}
+function resolveSenderDisplayName(message) {
+    if (!message?.$sender)
+        return 'unknown';
+    const sender = message.$sender;
+    const raw = sender.nickname || sender.name || sender.id;
+    return raw != null ? sanitizeSenderAttr(String(raw)) : 'unknown';
+}
+function mapPlatformRoleForLabel(role) {
+    if (!role || role === 'member')
+        return undefined;
+    if (role === 'owner')
+        return 'scene_owner';
+    if (role === 'admin')
+        return 'scene_admin';
+    return role;
+}
+function resolveSenderRoleLabels(commMessage) {
+    const labels = formatSenderRolesForLabel([...senderRolesFromMessage(commMessage)])
+        .split(',')
+        .map((r) => r.trim())
+        .filter((r) => r && r !== 'user');
+    const platform = mapPlatformRoleForLabel(commMessage.$sender.role);
+    if (platform && !labels.includes(platform))
+        labels.push(platform);
+    return labels.length > 0 ? labels : ['user'];
+}
+/** 群/频道 user 消息的 sender 元数据（写入 `agent_messages.extra`） */
+export function buildUserMessageExtra(commMessage) {
+    const scope = commMessage.$channel?.type || 'private';
+    if (scope !== 'group' && scope !== 'channel')
+        return undefined;
+    const roleLabels = resolveSenderRoleLabels(commMessage);
+    const sender = {
+        id: sanitizeSenderAttr(String(commMessage.$sender.id || 'unknown')),
+        name: resolveSenderDisplayName(commMessage),
+        roles: roleLabels.length > 0 ? roleLabels : ['user'],
+        scope,
+    };
+    return { sender };
+}
+/** 剥离伪造前缀后的用户正文 + 可选 extra（入库 payload 用） */
+export function prepareUserContentForSession(commMessage, rawContent) {
+    const content = stripUserSpoofedSenderPrefix(rawContent);
+    const extra = buildUserMessageExtra(commMessage);
+    return { content, extra };
+}
+/** 旁听块 + 引用块 + 当前 @ 正文分层（仅 LLM 侧；入库 payload 仍为干净正文） */
+export function layerInboundUserTurnBody(body, opts) {
+    const parts = [];
+    if (opts?.passiveBlock?.trim())
+        parts.push(opts.passiveBlock.trim());
+    if (opts?.quoteBlock?.trim())
+        parts.push(opts.quoteBlock.trim());
+    if (parts.length === 0)
+        return body;
+    return `${parts.join('\n\n')}\n\n${CURRENT_MESSAGE_MARKER}\n${body}`;
+}
+/** 本轮 user 消息：干净正文 + extra + LLM 渲染（引用/sender 仅 extra + 加载时拼接） */
+export function resolveTurnUserMessage(commMessage, rawContent, options) {
+    const { content, extra: senderExtra } = prepareUserContentForSession(commMessage, rawContent);
+    const quoteBlock = commMessage.extra?.[QUOTE_CONTEXT_BLOCK_EXTRA_KEY];
+    const quoteText = typeof quoteBlock === 'string' && quoteBlock.trim() ? quoteBlock.trim() : undefined;
+    const extra = {
+        ...senderExtra,
+        ...(quoteText ? { quote: { block: quoteText, messageId: commMessage.$quote_id } } : {}),
+    };
+    const hasExtra = !!(extra.sender || extra.quote);
+    const layered = layerInboundUserTurnBody(content, {
+        passiveBlock: options?.passiveBlock,
+        quoteBlock: quoteText,
+    });
+    const inlinedContext = layered !== content;
+    const llmMessage = renderUserMessageForLlm(createUserMessage(layered), inlinedContext
+        ? (senderExtra?.sender ? { sender: senderExtra.sender } : undefined)
+        : (hasExtra ? extra : undefined));
+    return { content, extra: hasExtra ? extra : undefined, llmMessage };
+}
+/** @deprecated 使用 `resolveTurnUserMessage` */
+export function formatUserContentForSession(commMessage, rawContent) {
+    const { llmMessage } = resolveTurnUserMessage(commMessage, rawContent);
+    if (llmMessage.role !== 'user')
+        return rawContent;
+    const block = llmMessage.content.find((b) => b.type === 'text');
+    return block?.type === 'text' ? block.text : rawContent;
+}
+export function buildSessionCreateInput(sessionKey, commMessage) {
+    const { platform, endpointId, sceneId, sceneType } = resolveSceneFieldsFromMessage(commMessage);
+    return {
+        session_key: sessionKey,
+        platform,
+        endpoint_id: endpointId,
+        scene_id: sceneId,
+        scene_type: sceneType,
+    };
+}
+export function buildImTranscriptQuery(commMessage) {
+    const { platform, endpointId, sceneId } = resolveSceneFieldsFromMessage(commMessage);
+    return {
+        platform,
+        endpointId,
+        sceneId,
+    };
+}
+export async function buildHistoryMessagesFromContext(deps, sessionId, currentUserContent) {
+    const loaded = await deps.contextRepository.loadContext(sessionId);
+    const timestamp = Date.now();
+    return [...loaded.messages, { role: 'user', content: [{ type: 'text', text: currentUserContent }], timestamp }];
+}
+/**
+ * 在 `getOrCreateActive` 之前调用：是否视为新会话纪元（用于 ai.session.new）。
+ */
+export async function resolveSessionIsNewBeforeCreate(deps, sessionKey) {
+    const active = await deps.agentSessionStore.findActive(sessionKey);
+    return !active;
+}
+export async function beginTurnSession(deps, sessionKey, commMessage) {
+    const input = buildSessionCreateInput(sessionKey, commMessage);
+    const record = await deps.agentSessionStore.getOrCreateActive(input);
+    return { sessionKey, sessionId: record.session_id };
+}
+export async function touchSession(deps, sessionId) {
+    await deps.agentSessionStore.touch(sessionId);
+}
+export async function archiveSessionByKey(deps, sessionKey) {
+    await deps.contextRepository.archiveSession(sessionKey);
+    return deps.agentSessionStore.archiveByKey(sessionKey);
+}
+//# sourceMappingURL=session-io.js.map

package/lib/session/session-io.js.map

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

package/lib/session/session-system.d.ts

@@ -0,0 +1,31 @@
+import type { Message } from '@zhin.js/core';
+import type { ZhinAgentPrivate } from '../internal/agent-host.js';
+import { buildTurnUserMessages } from '../context/turn-user-message.js';
+import type { SessionStrategy, SessionSystemConfig } from './contracts.js';
+import { type SessionIODeps } from './session-io.js';
+export type { SessionIODeps } from './session-io.js';
+export interface TurnSessionPrep {
+    sessionKey: string;
+    userId: string;
+    sessionId: string;
+    isNewSession: boolean;
+    passiveBlock: string | null;
+    turnUser: ReturnType<typeof buildTurnUserMessages>;
+}
+export declare class SessionSystem {
+    private readonly _config;
+    private readonly strategies;
+    constructor(_config?: SessionSystemConfig);
+    registerStrategy(name: string, strategy: SessionStrategy): void;
+    resolveSessionKey(message: Message, strategyName?: string): string;
+    resolvePassiveBlock(message: Message): string | null;
+    sessionDeps(host: ZhinAgentPrivate): SessionIODeps;
+    prepareTextTurn(host: ZhinAgentPrivate, commMessage: Message, content: string, options?: {
+        deferredAutoContinue?: boolean;
+        strategyName?: string;
+    }): Promise<TurnSessionPrep>;
+    touchAfterTurn(host: ZhinAgentPrivate, sessionId: string): Promise<void>;
+    archiveByKey(host: ZhinAgentPrivate, sessionKey: string): Promise<boolean>;
+}
+export declare function createSessionSystem(config?: SessionSystemConfig): SessionSystem;
+//# sourceMappingURL=session-system.d.ts.map

package/lib/session/session-system.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-system.d.ts","sourceRoot":"","sources":["../../src/session/session-system.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AAExE,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,EAAE,KAAK,aAAa,EAAwF,MAAM,iBAAiB,CAAC;AAG3I,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;IACtB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,EAAE,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAC;CACpD;AAED,qBAAa,aAAa;IAGZ,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsC;gBAEpC,OAAO,GAAE,mBAAwB;IAI9D,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI;IAI/D,iBAAiB,CACf,OAAO,EAAE,OAAO,EAChB,YAAY,GAAE,MAAwB,GACrC,MAAM;IAMT,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI;IAMpD,WAAW,CAAC,IAAI,EAAE,gBAAgB,GAAG,aAAa;IAQ5C,eAAe,CACnB,IAAI,EAAE,gBAAgB,EACtB,WAAW,EAAE,OAAO,EACpB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,oBAAoB,CAAC,EAAE,OAAO,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,GAClE,OAAO,CAAC,eAAe,CAAC;IA2BrB,cAAc,CAAC,IAAI,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxE,YAAY,CAAC,IAAI,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAGjF;AAED,wBAAgB,mBAAmB,CAAC,MAAM,GAAE,mBAAwB,GAAG,aAAa,CAEnF"}

package/lib/session/session-system.js

@@ -0,0 +1,70 @@
+import { resolveAgentTurnSessionKey } from '../collaboration/resolve-agent-session-key.js';
+import { buildTurnUserMessages } from '../context/turn-user-message.js';
+import { logPhase } from '../internal/phase-trace.js';
+import { beginTurnSession, resolveSessionIsNewBeforeCreate, touchSession, archiveSessionByKey } from './session-io.js';
+import { consumePassiveGroupContextForTurn } from './passive-group-session.js';
+import { CollaborationSessionStrategy } from './strategies.js';
+export class SessionSystem {
+    _config;
+    strategies = new Map();
+    constructor(_config = {}) {
+        this._config = _config;
+        this.registerStrategy('collaboration', new CollaborationSessionStrategy());
+    }
+    registerStrategy(name, strategy) {
+        this.strategies.set(name, strategy);
+    }
+    resolveSessionKey(message, strategyName = 'collaboration') {
+        const strategy = this.strategies.get(strategyName);
+        if (strategy)
+            return strategy.resolveSessionKey(message);
+        return resolveAgentTurnSessionKey(message);
+    }
+    resolvePassiveBlock(message) {
+        const channelScope = message.$channel?.type;
+        if (channelScope !== 'group' && channelScope !== 'channel')
+            return null;
+        return consumePassiveGroupContextForTurn(message);
+    }
+    sessionDeps(host) {
+        return {
+            imSessionStore: host.imSessionStore,
+            agentSessionStore: host.agentSessionStore,
+            contextRepository: host.contextRepository,
+        };
+    }
+    async prepareTextTurn(host, commMessage, content, options) {
+        const deps = this.sessionDeps(host);
+        const sessionKey = this.resolveSessionKey(commMessage, options?.strategyName);
+        const userId = commMessage.$sender.id || 'unknown';
+        const passiveBlock = this.resolvePassiveBlock(commMessage);
+        const turnUser = buildTurnUserMessages(commMessage, content, passiveBlock);
+        const isNewSession = await resolveSessionIsNewBeforeCreate(deps, sessionKey);
+        if (options?.deferredAutoContinue) {
+            logPhase(host.phaseConfig, 'turn.deferred_auto_continue', sessionKey, {});
+        }
+        else {
+            host.resetDeferredAutoContinueDepth(sessionKey);
+        }
+        await host.waitForMemoryPersistence();
+        const { sessionId } = await beginTurnSession(deps, sessionKey, commMessage);
+        return {
+            sessionKey,
+            userId,
+            sessionId,
+            isNewSession,
+            passiveBlock,
+            turnUser,
+        };
+    }
+    async touchAfterTurn(host, sessionId) {
+        await touchSession(this.sessionDeps(host), sessionId);
+    }
+    async archiveByKey(host, sessionKey) {
+        return archiveSessionByKey(this.sessionDeps(host), sessionKey);
+    }
+}
+export function createSessionSystem(config = {}) {
+    return new SessionSystem(config);
+}
+//# sourceMappingURL=session-system.js.map

package/lib/session/session-system.js.map

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

package/lib/session/session-tree-commands.d.ts

@@ -0,0 +1,5 @@
+import { type Message } from '@zhin.js/core';
+import type { ZhinAgentPrivate } from '../internal/agent-host.js';
+export declare function listSessionTreeForCommMessage(host: ZhinAgentPrivate, commMessage: Message): Promise<string>;
+export declare function jumpSessionTreeForCommMessage(host: ZhinAgentPrivate, commMessage: Message, index: number): Promise<string>;
+//# sourceMappingURL=session-tree-commands.d.ts.map

package/lib/session/session-tree-commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-tree-commands.d.ts","sourceRoot":"","sources":["../../src/session/session-tree-commands.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiC,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AAG5E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAQlE,wBAAsB,6BAA6B,CACjD,IAAI,EAAE,gBAAgB,EACtB,WAAW,EAAE,OAAO,GACnB,OAAO,CAAC,MAAM,CAAC,CAUjB;AAED,wBAAsB,6BAA6B,CACjD,IAAI,EAAE,gBAAgB,EACtB,WAAW,EAAE,OAAO,EACpB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,CAUjB"}