@xopcai/xopc 0.0.82 → 0.0.84

package/dist/src/agent/goals/persistent-goal-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistent-goal-service.js","names":["parseRoutingSessionKey"],"sources":["../../../../src/agent/goals/persistent-goal-service.ts"],"sourcesContent":["/**\n * PersistentGoalService — owns the \"/goal\" runtime: continuation scheduling,\n * the `PersistentGoalApis` bag that command handlers receive, and the post-turn\n * verdict hook called from `OutboundCoordinator`.\n *\n * Previously this logic was scattered across `AgentService`:\n *   - `setPersistentGoalWebchatContinuationScheduler` + a private callback field\n *   - `schedulePersistentGoalContinuation` (bus vs webchat fork)\n *   - `getPersistentGoalApisForCommand` (~40-line API factory)\n *   - `recordPersistentGoalStreamOutcome` / `takePersistentGoalStreamOutcome`\n *   - the `/goal` half of `emitSessionTurnComplete` (delegated to\n *     `handlePersistentGoalPostTurn`)\n *\n * Concentrating it here gives the rest of `AgentService` a cleaner surface\n * (one collaborator instead of five methods) and makes the goal runtime\n * unit-testable in isolation.\n */\n\nimport type { AgentMessage } from '@earendil-works/pi-agent-core';\n\nimport type { Config } from '../../config/schema.js';\nimport type { MessageBus } from '../../infra/bus/index.js';\nimport type { ModelManager } from '../models/index.js';\nimport type { SessionStore } from '../../session/store.js';\nimport type { SessionStateBag } from '../session/index.js';\nimport { parseSessionKey as parseRoutingSessionKey } from '../../routing/session-key.js';\nimport { appendPiTranscriptMessage } from '../../session/parity/jsonl-transcript-io.js';\nimport { createLogger } from '../../utils/logger.js';\nimport type { PersistentGoalApis } from './persistent-goal-apis.js';\nimport { handlePersistentGoalPostTurn } from './post-turn.js';\n\nconst log = createLogger('PersistentGoalService');\n\nexport interface PersistentGoalRouting {\n  sessionKey: string;\n  channel: string;\n  chatId: string;\n  inboundMetadata?: Record<string, unknown>;\n}\n\nexport interface SessionTurnCompletionForGoal {\n  sessionKey: string;\n  channel: string;\n  chatId: string;\n  assistantPlainText: string;\n  aborted: boolean;\n  streamError?: string;\n  skipPersistentGoalPostTurn?: boolean;\n  outboundMetadata?: Record<string, unknown>;\n}\n\nexport interface PersistentGoalServiceOptions {\n  bus: MessageBus;\n  sessionStore: SessionStore;\n  modelManager: ModelManager;\n  sessionState: SessionStateBag;\n  /** Effective config snapshot accessor. */\n  getConfig: () => Config | undefined;\n  /** Resolve the workspace directory for `appendAssistantReceipt` writes. */\n  getResolvedWorkspaceForSession: (sessionKey: string) => string;\n  /** Notify the gateway UI after a metadata change (replaces the in-bag emit). */\n  onSessionMetadataUpdated?: (sessionKey: string) => void;\n  /** Push an assistant token + transcript refresh into a live webchat stream. */\n  notifyWebchatTranscriptAppend: (sessionKey: string, assistantText: string) => void;\n}\n\nexport class PersistentGoalService {\n  private readonly opts: PersistentGoalServiceOptions;\n  /** Gateway only: webchat continuations bypass the bus and reuse `runGatewayAgent`. */\n  private webchatContinuationScheduler?: (sessionKey: string, message: string) => void;\n\n  constructor(opts: PersistentGoalServiceOptions) {\n    this.opts = opts;\n  }\n\n  /** Register the gateway-side webchat continuation hook (set from `web-agent` wiring). */\n  setWebchatContinuationScheduler(\n    fn: ((sessionKey: string, message: string) => void) | undefined,\n  ): void {\n    this.webchatContinuationScheduler = fn;\n  }\n\n  /**\n   * Continue a session after `/goal` decides the previous turn needs follow-up.\n   * Webchat sessions go through the scheduler; bus-driven channels re-publish the\n   * follow-up message as an inbound bus event so the existing inbound loop picks it up.\n   */\n  scheduleContinuation(\n    sessionKey: string,\n    message: string,\n    routing: { channel: string; chatId: string; inboundMetadata?: Record<string, unknown> },\n  ): void {\n    const parsed = parseRoutingSessionKey(sessionKey);\n    if (parsed?.source === 'webchat' && this.webchatContinuationScheduler) {\n      this.webchatContinuationScheduler(sessionKey, message);\n      return;\n    }\n    queueMicrotask(() => {\n      void this.opts.bus\n        .publishInbound({\n          channel: routing.channel,\n          chat_id: routing.chatId,\n          sender_id: 'persistent-goal',\n          content: message,\n          metadata: { sessionKey, ...routing.inboundMetadata },\n        })\n        .catch((err) => {\n          log.warn({ err, sessionKey }, 'Persistent goal: publishInbound failed');\n        });\n    });\n  }\n\n  /** Build the per-command `PersistentGoalApis` bag (transcript writers + scheduler closures). */\n  buildApisForRouting(routing: PersistentGoalRouting): PersistentGoalApis {\n    return {\n      getSessionMetadata: (k) => this.opts.sessionStore.getMetadata(k),\n      updateSessionMetadata: async (k, u) => {\n        await this.opts.sessionStore.updateMetadata(k, u);\n        this.opts.onSessionMetadataUpdated?.(k);\n      },\n      loadMessages: (k) => this.opts.sessionStore.loadMessages(k),\n      saveMessages: (k, m) => this.opts.sessionStore.saveMessages(k, m),\n      appendAssistantReceipt: async (k, text) => {\n        const trimmed = text.trim();\n        if (!trimmed) return;\n        const { absPath } = await this.opts.sessionStore.resolveTranscriptPath(k);\n        const workspaceDir = this.opts.getResolvedWorkspaceForSession(k);\n        await appendPiTranscriptMessage({\n          absPath,\n          cwd: workspaceDir,\n          message: {\n            role: 'assistant',\n            content: [{ type: 'text', text: trimmed }],\n            timestamp: Date.now(),\n          } as AgentMessage,\n          sessionKey: k,\n        });\n        this.opts.notifyWebchatTranscriptAppend(k, trimmed);\n      },\n      scheduleContinuation: (sk, msg) => {\n        this.scheduleContinuation(sk, msg, {\n          channel: routing.channel,\n          chatId: routing.chatId,\n          inboundMetadata: routing.inboundMetadata,\n        });\n      },\n      inboundConcurrentDepth: (sk) => this.opts.sessionState.getInboundTurnDepth(sk),\n    };\n  }\n\n  recordStreamOutcome(sessionKey: string, outcome: { skipPersistentGoalPostTurn: boolean }): void {\n    this.opts.sessionState.recordPersistentGoalStreamOutcome(sessionKey, outcome);\n  }\n\n  takeStreamOutcome(sessionKey: string): { skipPersistentGoalPostTurn: boolean } | undefined {\n    return this.opts.sessionState.takePersistentGoalStreamOutcome(sessionKey);\n  }\n\n  /**\n   * Run the `/goal` post-turn verdict for a completed user turn (called from\n   * `OutboundCoordinator.emitSessionTurnComplete`).\n   */\n  async runPostTurn(payload: SessionTurnCompletionForGoal): Promise<void> {\n    const apis = this.buildApisForRouting({\n      sessionKey: payload.sessionKey,\n      channel: payload.channel,\n      chatId: payload.chatId,\n      inboundMetadata: payload.outboundMetadata,\n    });\n\n    const src = parseRoutingSessionKey(payload.sessionKey)?.source;\n    const isWebchat = src === 'webchat';\n    const publishVerdict =\n      !isWebchat && payload.channel !== 'cli'\n        ? async (text: string) => {\n            await this.opts.bus.publishOutbound({\n              channel: payload.channel,\n              chat_id: payload.chatId,\n              content: text,\n              type: 'message',\n              metadata: {\n                accountId: payload.outboundMetadata?.accountId,\n                threadId: payload.outboundMetadata?.threadId,\n              },\n            });\n          }\n        : undefined;\n\n    let runtimeSessionModelRef: string | undefined;\n    try {\n      runtimeSessionModelRef = this.opts.modelManager.getModelForSession(payload.sessionKey);\n    } catch {\n      runtimeSessionModelRef = undefined;\n    }\n\n    await handlePersistentGoalPostTurn({\n      apis,\n      sessionKey: payload.sessionKey,\n      assistantPlainText: payload.assistantPlainText,\n      aborted: payload.aborted,\n      ...(payload.streamError !== undefined ? { streamError: payload.streamError } : {}),\n      skipPersistentGoalPostTurn: payload.skipPersistentGoalPostTurn ?? false,\n      config: this.opts.getConfig(),\n      runtimeSessionModelRef,\n      publishVerdictToChannel: publishVerdict,\n    });\n  }\n}\n"],"mappings":"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"}

package/dist/src/agent/goals/post-turn.js

@@ -1,7 +1,7 @@
-import { getAgentDefaultModelRef, init_schema } from "../../config/schema.js";
-import { resolveEffectiveAgentProfileForSession } from "../../config/agent-profile.js";
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
+import { getAgentDefaultModelRef, init_schema } from "../../config/schema.js";
+import { resolveEffectiveAgentProfileForSession } from "../../config/agent-profile.js";
 import { PERSISTENT_GOAL_CUSTOM_KEY, mergeCustomDataPatch, readPersistentGoal, serializePersistentGoal } from "./state.js";
 import { resolveGoalUiLocale } from "./goal-locale.js";
 import { evaluateAfterTurnHermesLike } from "./evaluate-turn.js";

package/dist/src/agent/goals/state.d.ts

@@ -1,5 +1,5 @@
 import { type ChecklistItemStatus, type GoalChecklistItem } from './checklist-types.js';
-import type { GoalUiLocale } from './goal-locale.js';
+import type { ServerLocale as GoalUiLocale } from '../../i18n/locale.js';
 /** Persisted under `SessionMetadata.customData.persistentGoal`. */
 export declare const PERSISTENT_GOAL_CUSTOM_KEY = "persistentGoal";
 export type PersistentGoalStatus = 'active' | 'paused' | 'done' | 'cleared';

package/dist/src/agent/goals/state.js.map

@@ -1 +1 @@
-{"version":3,"file":"state.js","names":[],"sources":["../../../../src/agent/goals/state.ts"],"sourcesContent":["import {\n  CHECKLIST_ITEM_PENDING,\n  TERMINAL_CHECKLIST_STATUSES,\n  type ChecklistItemAddedBy,\n  type ChecklistItemStatus,\n  type GoalChecklistItem,\n} from './checklist-types.js';\n\nimport type { GoalUiLocale } from './goal-locale.js';\n\n/** Persisted under `SessionMetadata.customData.persistentGoal`. */\nexport const PERSISTENT_GOAL_CUSTOM_KEY = 'persistentGoal';\n\nexport type PersistentGoalStatus = 'active' | 'paused' | 'done' | 'cleared';\n\nexport interface PersistentGoalState {\n  goal: string;\n  status: PersistentGoalStatus;\n  turnsUsed: number;\n  maxTurns: number;\n  createdAt: number;\n  lastTurnAt: number;\n  lastVerdict?: 'done' | 'continue' | 'skipped' | 'decompose';\n  lastReason?: string;\n  pausedReason?: string;\n  judgeModelRef?: string;\n  /** Hermes-style: judge JSON parse failures in a row (API errors do not increment). */\n  consecutiveParseFailures?: number;\n  /** After first successful decomposition, checklist drives Phase-B judging. */\n  decomposed?: boolean;\n  checklist?: GoalChecklistItem[];\n  /** Gateway console language: drives judge `reason` language and system messages. */\n  uiLocale?: GoalUiLocale;\n}\n\nexport function defaultMaxTurns(cfg: { maxTurns?: number } | undefined): number {\n  const n = cfg?.maxTurns;\n  if (typeof n === 'number' && Number.isFinite(n)) {\n    return Math.max(1, Math.min(500, Math.floor(n)));\n  }\n  return 20;\n}\n\nfunction coerceStatus(s: unknown): PersistentGoalStatus | undefined {\n  if (s === 'active' || s === 'paused' || s === 'done' || s === 'cleared') return s;\n  return undefined;\n}\n\nfunction coerceChecklistItem(raw: unknown): GoalChecklistItem | null {\n  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;\n  const r = raw as Record<string, unknown>;\n  const text = typeof r.text === 'string' ? r.text.trim() : '';\n  if (!text) return null;\n  const st = typeof r.status === 'string' ? r.status.trim().toLowerCase() : '';\n  const status: ChecklistItemStatus =\n    st === 'completed' || st === 'impossible' || st === 'pending' ? st : CHECKLIST_ITEM_PENDING;\n  const ab = typeof r.addedBy === 'string' ? r.addedBy.trim().toLowerCase() : '';\n  const addedBy: ChecklistItemAddedBy = ab === 'user' ? 'user' : 'judge';\n  const addedAt =\n    typeof r.addedAt === 'number' && Number.isFinite(r.addedAt) ? Math.floor(r.addedAt) : Date.now();\n  const completedAt =\n    typeof r.completedAt === 'number' && Number.isFinite(r.completedAt) ? Math.floor(r.completedAt) : undefined;\n  const evidence = typeof r.evidence === 'string' ? r.evidence : undefined;\n  return { text, status, addedBy, addedAt, completedAt, evidence };\n}\n\nexport function readPersistentGoal(customData: Record<string, unknown> | undefined): PersistentGoalState | null {\n  if (!customData || typeof customData !== 'object') return null;\n\n  const raw = customData[PERSISTENT_GOAL_CUSTOM_KEY];\n  if (raw && typeof raw === 'object' && !Array.isArray(raw)) {\n    const o = raw as Record<string, unknown>;\n    const goal = typeof o.goal === 'string' ? o.goal.trim() : '';\n    if (!goal) return null;\n    const status = coerceStatus(o.status) ?? 'active';\n    const maxTurns =\n      typeof o.maxTurns === 'number' && Number.isFinite(o.maxTurns)\n        ? Math.max(1, Math.min(500, Math.floor(o.maxTurns)))\n        : 20;\n    const turnsUsed =\n      typeof o.turnsUsed === 'number' && Number.isFinite(o.turnsUsed)\n        ? Math.max(0, Math.floor(o.turnsUsed))\n        : 0;\n    const createdAt =\n      typeof o.createdAt === 'number' && Number.isFinite(o.createdAt) ? o.createdAt : Date.now();\n    const lastTurnAt =\n      typeof o.lastTurnAt === 'number' && Number.isFinite(o.lastTurnAt) ? o.lastTurnAt : 0;\n    const lastVerdict =\n      o.lastVerdict === 'done' ||\n      o.lastVerdict === 'continue' ||\n      o.lastVerdict === 'skipped' ||\n      o.lastVerdict === 'decompose'\n        ? o.lastVerdict\n        : undefined;\n    const lastReason = typeof o.lastReason === 'string' ? o.lastReason : undefined;\n    const pausedReason = typeof o.pausedReason === 'string' ? o.pausedReason : undefined;\n    const judgeModelRef = typeof o.judgeModelRef === 'string' ? o.judgeModelRef.trim() : undefined;\n    const consecutiveParseFailures =\n      typeof o.consecutiveParseFailures === 'number' && Number.isFinite(o.consecutiveParseFailures)\n        ? Math.max(0, Math.floor(o.consecutiveParseFailures))\n        : 0;\n    const decomposed = Boolean(o.decomposed);\n    const uiLocale = o.uiLocale === 'zh' || o.uiLocale === 'en' ? o.uiLocale : undefined;\n    const checklistRaw = o.checklist;\n    const checklist: GoalChecklistItem[] = [];\n    if (Array.isArray(checklistRaw)) {\n      for (const row of checklistRaw) {\n        const it = coerceChecklistItem(row);\n        if (it) checklist.push(it);\n      }\n    }\n    return {\n      goal,\n      status,\n      turnsUsed,\n      maxTurns,\n      createdAt,\n      lastTurnAt,\n      lastVerdict,\n      lastReason,\n      pausedReason,\n      judgeModelRef: judgeModelRef || undefined,\n      consecutiveParseFailures,\n      decomposed: decomposed || undefined,\n      checklist: checklist.length ? checklist : undefined,\n      uiLocale,\n    };\n  }\n\n  return null;\n}\n\nexport function serializePersistentGoal(s: PersistentGoalState): Record<string, unknown> {\n  return {\n    goal: s.goal,\n    status: s.status,\n    turnsUsed: s.turnsUsed,\n    maxTurns: s.maxTurns,\n    createdAt: s.createdAt,\n    lastTurnAt: s.lastTurnAt,\n    ...(s.lastVerdict ? { lastVerdict: s.lastVerdict } : {}),\n    ...(s.lastReason ? { lastReason: s.lastReason } : {}),\n    ...(s.pausedReason ? { pausedReason: s.pausedReason } : {}),\n    ...(s.judgeModelRef ? { judgeModelRef: s.judgeModelRef } : {}),\n    ...(s.consecutiveParseFailures ? { consecutiveParseFailures: s.consecutiveParseFailures } : {}),\n    ...(s.decomposed ? { decomposed: true } : {}),\n    ...(s.uiLocale ? { uiLocale: s.uiLocale } : {}),\n    ...(s.checklist?.length\n      ? {\n          checklist: s.checklist.map((it) => ({\n            text: it.text,\n            status: it.status,\n            addedBy: it.addedBy,\n            addedAt: it.addedAt,\n            ...(it.completedAt !== undefined ? { completedAt: it.completedAt } : {}),\n            ...(it.evidence ? { evidence: it.evidence } : {}),\n          })),\n        }\n      : {}),\n  };\n}\n\n/** Render checklist for continuation prompt (Hermes-style, no numbers in body). */\nexport function renderChecklistPlain(items: GoalChecklistItem[]): string {\n  if (!items.length) return '(empty)';\n  const lines: string[] = [];\n  for (const it of items) {\n    const marker =\n      it.status === 'completed' ? '[x]' : it.status === 'impossible' ? '[!]' : '[ ]';\n    let line = `${marker} ${it.text}`;\n    if (it.status === 'impossible' && it.evidence) line += ` (impossible: ${it.evidence})`;\n    lines.push(line);\n  }\n  return lines.join('\\n');\n}\n\n/** Numbered checklist for judge user prompts (1-based indices). */\nexport function renderChecklistNumbered(items: GoalChecklistItem[]): string {\n  if (!items.length) return '(empty)';\n  const lines: string[] = [];\n  for (let i = 0; i < items.length; i++) {\n    const it = items[i]!;\n    const n = i + 1;\n    const marker =\n      it.status === 'completed' ? '[x]' : it.status === 'impossible' ? '[!]' : '[ ]';\n    let line = `${n}. ${marker} ${it.text}`;\n    if (it.status === 'impossible' && it.evidence) line += ` (impossible: ${it.evidence})`;\n    lines.push(line);\n  }\n  return lines.join('\\n');\n}\n\n/**\n * After LLM decomposition, keep existing checklist rows (e.g. user-added acceptance criteria)\n * and append judge-generated items, skipping duplicate text (case-insensitive trim).\n */\nexport function mergeDecomposedChecklistItems(\n  existing: GoalChecklistItem[],\n  decomposedTexts: { text: string }[],\n): GoalChecklistItem[] {\n  const now = Date.now();\n  const next = existing.map((it) => ({ ...it }));\n  const seen = new Set(next.map((it) => it.text.trim().toLowerCase()));\n  for (const row of decomposedTexts) {\n    const t = row.text.trim();\n    if (!t) continue;\n    const key = t.toLowerCase();\n    if (seen.has(key)) continue;\n    seen.add(key);\n    next.push({\n      text: t,\n      status: CHECKLIST_ITEM_PENDING,\n      addedBy: 'judge',\n      addedAt: now,\n    });\n  }\n  return next;\n}\n\nexport function applyJudgeChecklistUpdates(\n  items: GoalChecklistItem[],\n  parsed: {\n    updates: { index: number; status: ChecklistItemStatus; evidence?: string | null }[];\n    newItems: { text: string }[];\n  },\n): GoalChecklistItem[] {\n  const next = items.map((it) => ({ ...it }));\n  const now = Date.now();\n  for (const upd of parsed.updates) {\n    const idx = upd.index;\n    if (idx < 0 || idx >= next.length) continue;\n    const item = next[idx]!;\n    if (TERMINAL_CHECKLIST_STATUSES.has(item.status)) continue;\n    if (!TERMINAL_CHECKLIST_STATUSES.has(upd.status)) continue;\n    item.status = upd.status;\n    item.completedAt = now;\n    if (upd.evidence?.trim()) item.evidence = upd.evidence.trim();\n  }\n  for (const ni of parsed.newItems) {\n    const t = ni.text.trim();\n    if (!t) continue;\n    next.push({\n      text: t,\n      status: CHECKLIST_ITEM_PENDING,\n      addedBy: 'judge',\n      addedAt: now,\n    });\n  }\n  return next;\n}\n\n\nexport function mergeCustomDataPatch(\n  existingCustom: Record<string, unknown> | undefined,\n  patch: Record<string, unknown>,\n): Record<string, unknown> {\n  return { ...(existingCustom ?? {}), ...patch };\n}\n"],"mappings":"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"}
+{"version":3,"file":"state.js","names":[],"sources":["../../../../src/agent/goals/state.ts"],"sourcesContent":["import {\n  CHECKLIST_ITEM_PENDING,\n  TERMINAL_CHECKLIST_STATUSES,\n  type ChecklistItemAddedBy,\n  type ChecklistItemStatus,\n  type GoalChecklistItem,\n} from './checklist-types.js';\n\n// Direct import of the underlying locale type — `goal-locale.ts` aliases this as\n// `GoalUiLocale` AND imports values from `state.ts`, so going through `./goal-locale.js`\n// would create a circular module cycle.\nimport type { ServerLocale as GoalUiLocale } from '../../i18n/locale.js';\n\n/** Persisted under `SessionMetadata.customData.persistentGoal`. */\nexport const PERSISTENT_GOAL_CUSTOM_KEY = 'persistentGoal';\n\nexport type PersistentGoalStatus = 'active' | 'paused' | 'done' | 'cleared';\n\nexport interface PersistentGoalState {\n  goal: string;\n  status: PersistentGoalStatus;\n  turnsUsed: number;\n  maxTurns: number;\n  createdAt: number;\n  lastTurnAt: number;\n  lastVerdict?: 'done' | 'continue' | 'skipped' | 'decompose';\n  lastReason?: string;\n  pausedReason?: string;\n  judgeModelRef?: string;\n  /** Hermes-style: judge JSON parse failures in a row (API errors do not increment). */\n  consecutiveParseFailures?: number;\n  /** After first successful decomposition, checklist drives Phase-B judging. */\n  decomposed?: boolean;\n  checklist?: GoalChecklistItem[];\n  /** Gateway console language: drives judge `reason` language and system messages. */\n  uiLocale?: GoalUiLocale;\n}\n\nexport function defaultMaxTurns(cfg: { maxTurns?: number } | undefined): number {\n  const n = cfg?.maxTurns;\n  if (typeof n === 'number' && Number.isFinite(n)) {\n    return Math.max(1, Math.min(500, Math.floor(n)));\n  }\n  return 20;\n}\n\nfunction coerceStatus(s: unknown): PersistentGoalStatus | undefined {\n  if (s === 'active' || s === 'paused' || s === 'done' || s === 'cleared') return s;\n  return undefined;\n}\n\nfunction coerceChecklistItem(raw: unknown): GoalChecklistItem | null {\n  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;\n  const r = raw as Record<string, unknown>;\n  const text = typeof r.text === 'string' ? r.text.trim() : '';\n  if (!text) return null;\n  const st = typeof r.status === 'string' ? r.status.trim().toLowerCase() : '';\n  const status: ChecklistItemStatus =\n    st === 'completed' || st === 'impossible' || st === 'pending' ? st : CHECKLIST_ITEM_PENDING;\n  const ab = typeof r.addedBy === 'string' ? r.addedBy.trim().toLowerCase() : '';\n  const addedBy: ChecklistItemAddedBy = ab === 'user' ? 'user' : 'judge';\n  const addedAt =\n    typeof r.addedAt === 'number' && Number.isFinite(r.addedAt) ? Math.floor(r.addedAt) : Date.now();\n  const completedAt =\n    typeof r.completedAt === 'number' && Number.isFinite(r.completedAt) ? Math.floor(r.completedAt) : undefined;\n  const evidence = typeof r.evidence === 'string' ? r.evidence : undefined;\n  return { text, status, addedBy, addedAt, completedAt, evidence };\n}\n\nexport function readPersistentGoal(customData: Record<string, unknown> | undefined): PersistentGoalState | null {\n  if (!customData || typeof customData !== 'object') return null;\n\n  const raw = customData[PERSISTENT_GOAL_CUSTOM_KEY];\n  if (raw && typeof raw === 'object' && !Array.isArray(raw)) {\n    const o = raw as Record<string, unknown>;\n    const goal = typeof o.goal === 'string' ? o.goal.trim() : '';\n    if (!goal) return null;\n    const status = coerceStatus(o.status) ?? 'active';\n    const maxTurns =\n      typeof o.maxTurns === 'number' && Number.isFinite(o.maxTurns)\n        ? Math.max(1, Math.min(500, Math.floor(o.maxTurns)))\n        : 20;\n    const turnsUsed =\n      typeof o.turnsUsed === 'number' && Number.isFinite(o.turnsUsed)\n        ? Math.max(0, Math.floor(o.turnsUsed))\n        : 0;\n    const createdAt =\n      typeof o.createdAt === 'number' && Number.isFinite(o.createdAt) ? o.createdAt : Date.now();\n    const lastTurnAt =\n      typeof o.lastTurnAt === 'number' && Number.isFinite(o.lastTurnAt) ? o.lastTurnAt : 0;\n    const lastVerdict =\n      o.lastVerdict === 'done' ||\n      o.lastVerdict === 'continue' ||\n      o.lastVerdict === 'skipped' ||\n      o.lastVerdict === 'decompose'\n        ? o.lastVerdict\n        : undefined;\n    const lastReason = typeof o.lastReason === 'string' ? o.lastReason : undefined;\n    const pausedReason = typeof o.pausedReason === 'string' ? o.pausedReason : undefined;\n    const judgeModelRef = typeof o.judgeModelRef === 'string' ? o.judgeModelRef.trim() : undefined;\n    const consecutiveParseFailures =\n      typeof o.consecutiveParseFailures === 'number' && Number.isFinite(o.consecutiveParseFailures)\n        ? Math.max(0, Math.floor(o.consecutiveParseFailures))\n        : 0;\n    const decomposed = Boolean(o.decomposed);\n    const uiLocale = o.uiLocale === 'zh' || o.uiLocale === 'en' ? o.uiLocale : undefined;\n    const checklistRaw = o.checklist;\n    const checklist: GoalChecklistItem[] = [];\n    if (Array.isArray(checklistRaw)) {\n      for (const row of checklistRaw) {\n        const it = coerceChecklistItem(row);\n        if (it) checklist.push(it);\n      }\n    }\n    return {\n      goal,\n      status,\n      turnsUsed,\n      maxTurns,\n      createdAt,\n      lastTurnAt,\n      lastVerdict,\n      lastReason,\n      pausedReason,\n      judgeModelRef: judgeModelRef || undefined,\n      consecutiveParseFailures,\n      decomposed: decomposed || undefined,\n      checklist: checklist.length ? checklist : undefined,\n      uiLocale,\n    };\n  }\n\n  return null;\n}\n\nexport function serializePersistentGoal(s: PersistentGoalState): Record<string, unknown> {\n  return {\n    goal: s.goal,\n    status: s.status,\n    turnsUsed: s.turnsUsed,\n    maxTurns: s.maxTurns,\n    createdAt: s.createdAt,\n    lastTurnAt: s.lastTurnAt,\n    ...(s.lastVerdict ? { lastVerdict: s.lastVerdict } : {}),\n    ...(s.lastReason ? { lastReason: s.lastReason } : {}),\n    ...(s.pausedReason ? { pausedReason: s.pausedReason } : {}),\n    ...(s.judgeModelRef ? { judgeModelRef: s.judgeModelRef } : {}),\n    ...(s.consecutiveParseFailures ? { consecutiveParseFailures: s.consecutiveParseFailures } : {}),\n    ...(s.decomposed ? { decomposed: true } : {}),\n    ...(s.uiLocale ? { uiLocale: s.uiLocale } : {}),\n    ...(s.checklist?.length\n      ? {\n          checklist: s.checklist.map((it) => ({\n            text: it.text,\n            status: it.status,\n            addedBy: it.addedBy,\n            addedAt: it.addedAt,\n            ...(it.completedAt !== undefined ? { completedAt: it.completedAt } : {}),\n            ...(it.evidence ? { evidence: it.evidence } : {}),\n          })),\n        }\n      : {}),\n  };\n}\n\n/** Render checklist for continuation prompt (Hermes-style, no numbers in body). */\nexport function renderChecklistPlain(items: GoalChecklistItem[]): string {\n  if (!items.length) return '(empty)';\n  const lines: string[] = [];\n  for (const it of items) {\n    const marker =\n      it.status === 'completed' ? '[x]' : it.status === 'impossible' ? '[!]' : '[ ]';\n    let line = `${marker} ${it.text}`;\n    if (it.status === 'impossible' && it.evidence) line += ` (impossible: ${it.evidence})`;\n    lines.push(line);\n  }\n  return lines.join('\\n');\n}\n\n/** Numbered checklist for judge user prompts (1-based indices). */\nexport function renderChecklistNumbered(items: GoalChecklistItem[]): string {\n  if (!items.length) return '(empty)';\n  const lines: string[] = [];\n  for (let i = 0; i < items.length; i++) {\n    const it = items[i]!;\n    const n = i + 1;\n    const marker =\n      it.status === 'completed' ? '[x]' : it.status === 'impossible' ? '[!]' : '[ ]';\n    let line = `${n}. ${marker} ${it.text}`;\n    if (it.status === 'impossible' && it.evidence) line += ` (impossible: ${it.evidence})`;\n    lines.push(line);\n  }\n  return lines.join('\\n');\n}\n\n/**\n * After LLM decomposition, keep existing checklist rows (e.g. user-added acceptance criteria)\n * and append judge-generated items, skipping duplicate text (case-insensitive trim).\n */\nexport function mergeDecomposedChecklistItems(\n  existing: GoalChecklistItem[],\n  decomposedTexts: { text: string }[],\n): GoalChecklistItem[] {\n  const now = Date.now();\n  const next = existing.map((it) => ({ ...it }));\n  const seen = new Set(next.map((it) => it.text.trim().toLowerCase()));\n  for (const row of decomposedTexts) {\n    const t = row.text.trim();\n    if (!t) continue;\n    const key = t.toLowerCase();\n    if (seen.has(key)) continue;\n    seen.add(key);\n    next.push({\n      text: t,\n      status: CHECKLIST_ITEM_PENDING,\n      addedBy: 'judge',\n      addedAt: now,\n    });\n  }\n  return next;\n}\n\nexport function applyJudgeChecklistUpdates(\n  items: GoalChecklistItem[],\n  parsed: {\n    updates: { index: number; status: ChecklistItemStatus; evidence?: string | null }[];\n    newItems: { text: string }[];\n  },\n): GoalChecklistItem[] {\n  const next = items.map((it) => ({ ...it }));\n  const now = Date.now();\n  for (const upd of parsed.updates) {\n    const idx = upd.index;\n    if (idx < 0 || idx >= next.length) continue;\n    const item = next[idx]!;\n    if (TERMINAL_CHECKLIST_STATUSES.has(item.status)) continue;\n    if (!TERMINAL_CHECKLIST_STATUSES.has(upd.status)) continue;\n    item.status = upd.status;\n    item.completedAt = now;\n    if (upd.evidence?.trim()) item.evidence = upd.evidence.trim();\n  }\n  for (const ni of parsed.newItems) {\n    const t = ni.text.trim();\n    if (!t) continue;\n    next.push({\n      text: t,\n      status: CHECKLIST_ITEM_PENDING,\n      addedBy: 'judge',\n      addedAt: now,\n    });\n  }\n  return next;\n}\n\n\nexport function mergeCustomDataPatch(\n  existingCustom: Record<string, unknown> | undefined,\n  patch: Record<string, unknown>,\n): Record<string, unknown> {\n  return { ...(existingCustom ?? {}), ...patch };\n}\n"],"mappings":"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"}

package/dist/src/agent/image/load-image-media.js

@@ -1,8 +1,8 @@
 import { checkFileSafety } from "../prompt/safety.js";
 import { decodeDataUrl } from "./image-helpers.js";
+import { promises } from "node:fs";
 import path from "node:path";
 import { homedir } from "node:os";
-import { promises } from "node:fs";
 //#region src/agent/image/load-image-media.ts
 function expandUser(p) {
 	if (p.startsWith("~/") || p === "~") return path.join(homedir(), p.slice(1));

package/dist/src/agent/inbound/inbound-loop.d.ts

@@ -0,0 +1,77 @@
+/**
+ * InboundLoop — owns the bus-driven inbound pipeline.
+ *
+ * Replaces the previous `AgentService.start()` while-loop, `handleInboundMessage`,
+ * and `handleSystemMessage` methods. Everything that "a message arrives, run the
+ * agent turn, publish the reply" needs is concentrated here; the parent
+ * `AgentService` now just constructs the loop with collaborators and forwards
+ * start/stop to it.
+ *
+ * The constructor takes a fairly wide config because handling a single inbound
+ * message touches almost every subsystem (router, command handler, lifecycle
+ * manager, agent orchestrator, outbound coordinator, session state, etc.). All
+ * dependencies are injected so this class is unit-testable and the inbound
+ * pipeline can evolve without touching `AgentService`.
+ */
+import type { AgentMessage } from '@earendil-works/pi-agent-core';
+import type { MessageBus } from '../../infra/bus/index.js';
+import type { Config } from '../../config/schema.js';
+import type { ChannelManager } from '../../channels/manager.js';
+import type { ContextualLogger } from '../../utils/logger/types.js';
+import type { AgentManager } from '../agent-manager.js';
+import type { AgentOrchestrator } from '../orchestration/index.js';
+import type { CommandHandler, OutboundCoordinator, StreamManager } from '../messaging/index.js';
+import type { MessageRouter } from '../messaging/message-router.js';
+import type { ModelManager } from '../models/index.js';
+import type { SessionContextManager, SessionHydrator, SessionLifecycleManager, SessionStateBag } from '../session/index.js';
+import type { FeedbackCoordinator } from '../feedback/index.js';
+import type { HookHandler } from '../lifecycle/hook-handler.js';
+import type { SessionStore } from '../../session/store.js';
+import type { StreamHandle } from '../service.types.js';
+export interface InboundLoopConfig {
+    log: ContextualLogger;
+    agentId: string;
+    bus: MessageBus;
+    hookHandler: HookHandler;
+    messageRouter: MessageRouter;
+    commandHandler: CommandHandler;
+    sessionContextManager: SessionContextManager;
+    feedbackCoordinator: FeedbackCoordinator;
+    agentManager: AgentManager;
+    sessionLifecycleManager: SessionLifecycleManager;
+    agentOrchestrator: AgentOrchestrator;
+    outboundCoordinator: OutboundCoordinator;
+    streamManager: StreamManager;
+    sessionState: SessionStateBag;
+    sessionStore: SessionStore;
+    modelManager: ModelManager;
+    /** Register a per-session agent-event subscription (idempotent). */
+    setupSessionEventHandling: (sessionKey: string) => void;
+    /** Per-session config hydration (workspace + model override) before a turn runs. */
+    sessionHydrator: SessionHydrator;
+    /** Returns the visible last assistant text used for outbound + persistent-goal hook. */
+    getLastAssistantPlainText: (sessionKey: string) => string;
+    /** Pre-turn auto-compaction (only used by system messages). */
+    checkAndCompact: (sessionKey: string, messages: AgentMessage[]) => Promise<void>;
+    /** Fire-and-forget auto-title (no-ops for cron/heartbeat keys). */
+    enqueueMaybeAutoTitleAfterPersist: (sessionKey: string) => void;
+    /** Effective merged config snapshot. */
+    getConfig: () => Config | undefined;
+    /** Connect a channel stream handle for partial assistant text rendering. */
+    setStreamHandle: (handle: StreamHandle) => void;
+}
+export declare class InboundLoop {
+    private readonly cfg;
+    private readonly log;
+    private running;
+    private channelManagerRef;
+    constructor(cfg: InboundLoopConfig);
+    setChannelManager(channelManager: ChannelManager | null): void;
+    isRunning(): boolean;
+    /** Begin consuming inbound messages from the bus until {@link stop} or shutdown. */
+    start(): Promise<void>;
+    /** Cooperatively stop the loop; the current message (if any) is allowed to finish. */
+    stop(): void;
+    private handleInboundMessage;
+    private handleSystemMessage;
+}

package/dist/src/agent/inbound/inbound-loop.js

@@ -0,0 +1,226 @@
+import { runWithLogContext, updateAsyncLogContext } from "../../utils/logger/context.js";
+import { init_logger } from "../../utils/logger.js";
+import { MessageBusShutdownError } from "../../infra/bus/queue.js";
+import "../../infra/bus/index.js";
+import { inboundMessageLogRequestId } from "../service-inbound-utils.js";
+import { runEmbeddedTurnForSession } from "../embedded/run-for-session.js";
+//#region src/agent/inbound/inbound-loop.ts
+init_logger();
+/** Initial back-off when bus consume fails. Doubles each consecutive failure. */
+const INBOUND_CONSUME_BASE_BACKOFF_MS = 1e3;
+/** Hard cap on back-off so a long bus outage settles at one retry per 30s. */
+const INBOUND_CONSUME_MAX_BACKOFF_MS = 3e4;
+var InboundLoop = class {
+	cfg;
+	log;
+	running = false;
+	channelManagerRef = null;
+	constructor(cfg) {
+		this.cfg = cfg;
+		this.log = cfg.log;
+	}
+	setChannelManager(channelManager) {
+		this.channelManagerRef = channelManager;
+	}
+	isRunning() {
+		return this.running;
+	}
+	/** Begin consuming inbound messages from the bus until {@link stop} or shutdown. */
+	async start() {
+		this.running = true;
+		await this.cfg.hookHandler.trigger("session_start", { sessionId: this.cfg.agentId });
+		let consecutiveConsumeFailures = 0;
+		while (this.running) {
+			let msg;
+			try {
+				msg = await this.cfg.bus.consumeInbound();
+				consecutiveConsumeFailures = 0;
+			} catch (error) {
+				if (error instanceof MessageBusShutdownError) break;
+				consecutiveConsumeFailures += 1;
+				const delayMs = Math.min(INBOUND_CONSUME_MAX_BACKOFF_MS, INBOUND_CONSUME_BASE_BACKOFF_MS * 2 ** (consecutiveConsumeFailures - 1));
+				const em = error instanceof Error ? error.message : String(error);
+				this.log.error({
+					err: error,
+					errorMessage: em,
+					phase: "inbound_consume",
+					consecutiveFailures: consecutiveConsumeFailures,
+					backoffMs: delayMs
+				}, `Bus consume failed (backing off ${delayMs}ms): ${em}`);
+				await new Promise((resolve) => setTimeout(resolve, delayMs));
+				continue;
+			}
+			try {
+				await this.handleInboundMessage(msg);
+			} catch (error) {
+				const em = error instanceof Error ? error.message : String(error);
+				this.log.error({
+					err: error,
+					errorMessage: em,
+					phase: "inbound_handle",
+					channel: msg.channel,
+					chatId: msg.chat_id
+				}, `Inbound message handler failed: ${em}`);
+			}
+		}
+		await this.cfg.hookHandler.trigger("session_end", {
+			sessionId: this.cfg.agentId,
+			messageCount: 0
+		});
+	}
+	/** Cooperatively stop the loop; the current message (if any) is allowed to finish. */
+	stop() {
+		this.running = false;
+	}
+	async handleInboundMessage(msg) {
+		await runWithLogContext({ requestId: inboundMessageLogRequestId(msg) }, async () => {
+			const { context, isCommand, command, commandArgs } = await this.cfg.messageRouter.routeMessage(msg);
+			const sessionContext = {
+				sessionKey: context.sessionKey,
+				channel: context.channel,
+				chatId: context.chatId,
+				senderId: context.senderId || "",
+				isGroup: context.isGroup || false,
+				metadata: { transcribedVoice: msg.metadata?.transcribedVoice === true }
+			};
+			updateAsyncLogContext({ sessionId: sessionContext.sessionKey });
+			await this.cfg.sessionContextManager.runWith(sessionContext, async () => {
+				this.cfg.feedbackCoordinator.setContext(sessionContext);
+				this.cfg.agentManager.getOrCreateAgent(sessionContext.sessionKey);
+				this.cfg.setupSessionEventHandling(sessionContext.sessionKey);
+				await this.cfg.sessionLifecycleManager.startSession(sessionContext);
+				let typingController = null;
+				let inboundTurnArmed = false;
+				let busProcessFailed;
+				try {
+					if (msg.channel === "system") {
+						await this.handleSystemMessage(msg, sessionContext);
+						return;
+					}
+					if (this.channelManagerRef && msg.channel !== "cli") await this.channelManagerRef.dispatchInboundMessageAction(msg);
+					if (isCommand && command) {
+						if (await this.cfg.commandHandler.executeCommand(command, commandArgs || "", {
+							sessionKey: sessionContext.sessionKey,
+							channel: sessionContext.channel,
+							chatId: sessionContext.chatId,
+							senderId: sessionContext.senderId,
+							isGroup: sessionContext.isGroup,
+							inboundMetadata: msg.metadata
+						})) return;
+					}
+					typingController = this.cfg.outboundCoordinator.createTypingControllerForInbound(msg);
+					typingController?.start();
+					if (this.channelManagerRef && msg.channel !== "cli") {
+						const meta = msg.metadata;
+						const streamHandle = this.channelManagerRef.startStream(msg.channel, msg.chat_id, meta?.accountId, {
+							threadId: meta?.threadId,
+							replyToMessageId: meta?.messageId
+						});
+						if (streamHandle) this.cfg.setStreamHandle(streamHandle);
+					}
+					this.cfg.sessionState.beginInboundTurn(sessionContext.sessionKey);
+					inboundTurnArmed = true;
+					try {
+						await this.cfg.agentOrchestrator.process(msg, sessionContext);
+					} catch (procErr) {
+						busProcessFailed = procErr instanceof Error ? procErr.message : String(procErr);
+						throw procErr;
+					}
+				} finally {
+					await this.cfg.sessionLifecycleManager.endSession(sessionContext);
+					await this.cfg.streamManager.end();
+					try {
+						await this.cfg.outboundCoordinator.sendFinalResponse(msg, sessionContext);
+					} finally {
+						await typingController?.stop();
+					}
+					if (inboundTurnArmed) {
+						const meta = msg.metadata;
+						const assistantPlainText = this.cfg.getLastAssistantPlainText(sessionContext.sessionKey) ?? "";
+						try {
+							await this.cfg.outboundCoordinator.emitSessionTurnComplete({
+								sessionKey: sessionContext.sessionKey,
+								channel: sessionContext.channel,
+								chatId: sessionContext.chatId,
+								inboundUserText: msg.content,
+								assistantPlainText,
+								aborted: false,
+								...busProcessFailed !== void 0 ? { streamError: busProcessFailed } : {},
+								skipPersistentGoalPostTurn: false,
+								outboundMetadata: {
+									accountId: meta?.accountId,
+									threadId: meta?.threadId
+								}
+							});
+						} catch (turnErr) {
+							const em = turnErr instanceof Error ? turnErr.message : String(turnErr);
+							this.log.warn({
+								err: turnErr,
+								sessionKey: sessionContext.sessionKey
+							}, `Session turn complete failed: ${em}`);
+						}
+						this.cfg.sessionState.endInboundTurn(sessionContext.sessionKey);
+					}
+					this.cfg.feedbackCoordinator.endTask();
+					this.cfg.feedbackCoordinator.clearContext();
+				}
+			});
+		});
+	}
+	async handleSystemMessage(msg, context) {
+		this.log.debug({ sessionKey: context.sessionKey }, "Processing system message");
+		await this.cfg.sessionHydrator.workspace(context.sessionKey);
+		await this.cfg.sessionHydrator.model(context.sessionKey);
+		const messages = await this.cfg.sessionStore.load(context.sessionKey);
+		await this.cfg.checkAndCompact(context.sessionKey, messages);
+		const systemMessage = {
+			role: "user",
+			content: [{
+				type: "text",
+				text: `[System: ${msg.sender_id}] ${msg.content}`
+			}],
+			timestamp: Date.now()
+		};
+		try {
+			const finalContent = (await runEmbeddedTurnForSession({
+				sessionKey: context.sessionKey,
+				userMessage: systemMessage,
+				sessionStore: this.cfg.sessionStore,
+				agentManager: this.cfg.agentManager,
+				modelManager: this.cfg.modelManager,
+				getConfig: this.cfg.getConfig
+			})).lastAssistantText ?? this.cfg.getLastAssistantPlainText(context.sessionKey);
+			if (finalContent) {
+				this.cfg.sessionState.setLastAssistantText(context.sessionKey, finalContent);
+				const hookResult = await this.cfg.hookHandler.runMessageSending(context.chatId, finalContent, context.channel);
+				if (hookResult.send) await this.cfg.bus.publishOutbound({
+					channel: context.channel,
+					chat_id: context.chatId,
+					content: hookResult.content || finalContent,
+					type: "message"
+				});
+			}
+			this.cfg.enqueueMaybeAutoTitleAfterPersist(context.sessionKey);
+		} catch (error) {
+			const em = error instanceof Error ? error.message : String(error);
+			this.log.error({
+				err: error,
+				errorMessage: em,
+				sessionKey: context.sessionKey,
+				channel: context.channel,
+				chatId: context.chatId,
+				senderId: msg.sender_id
+			}, `System message handling failed: ${em}`);
+			await this.cfg.bus.publishOutbound({
+				channel: context.channel,
+				chat_id: context.chatId,
+				content: "❌ An error occurred while processing the system message.",
+				type: "message"
+			});
+		}
+	}
+};
+//#endregion
+export { InboundLoop };
+
+//# sourceMappingURL=inbound-loop.js.map

package/dist/src/agent/inbound/inbound-loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbound-loop.js","names":[],"sources":["../../../../src/agent/inbound/inbound-loop.ts"],"sourcesContent":["/**\n * InboundLoop — owns the bus-driven inbound pipeline.\n *\n * Replaces the previous `AgentService.start()` while-loop, `handleInboundMessage`,\n * and `handleSystemMessage` methods. Everything that \"a message arrives, run the\n * agent turn, publish the reply\" needs is concentrated here; the parent\n * `AgentService` now just constructs the loop with collaborators and forwards\n * start/stop to it.\n *\n * The constructor takes a fairly wide config because handling a single inbound\n * message touches almost every subsystem (router, command handler, lifecycle\n * manager, agent orchestrator, outbound coordinator, session state, etc.). All\n * dependencies are injected so this class is unit-testable and the inbound\n * pipeline can evolve without touching `AgentService`.\n */\n\nimport type { AgentMessage } from '@earendil-works/pi-agent-core';\n\nimport type { MessageBus, InboundMessage } from '../../infra/bus/index.js';\nimport { MessageBusShutdownError } from '../../infra/bus/index.js';\nimport type { Config } from '../../config/schema.js';\nimport type { ChannelManager } from '../../channels/manager.js';\nimport { runWithLogContext, updateAsyncLogContext } from '../../utils/logger.js';\nimport type { ContextualLogger } from '../../utils/logger/types.js';\n\nimport type { AgentManager } from '../agent-manager.js';\nimport type { AgentOrchestrator } from '../orchestration/index.js';\nimport type { CommandHandler, OutboundCoordinator, StreamManager } from '../messaging/index.js';\nimport type { MessageRouter } from '../messaging/message-router.js';\nimport type { ModelManager } from '../models/index.js';\nimport type {\n  SessionContext,\n  SessionContextManager,\n  SessionHydrator,\n  SessionLifecycleManager,\n  SessionStateBag,\n} from '../session/index.js';\nimport type { FeedbackCoordinator } from '../feedback/index.js';\nimport type { HookHandler } from '../lifecycle/hook-handler.js';\nimport type { SessionStore } from '../../session/store.js';\nimport type { StreamHandle } from '../service.types.js';\nimport { runEmbeddedTurnForSession } from '../embedded/run-for-session.js';\nimport { inboundMessageLogRequestId } from '../service-inbound-utils.js';\n\n/** Initial back-off when bus consume fails. Doubles each consecutive failure. */\nconst INBOUND_CONSUME_BASE_BACKOFF_MS = 1_000;\n/** Hard cap on back-off so a long bus outage settles at one retry per 30s. */\nconst INBOUND_CONSUME_MAX_BACKOFF_MS = 30_000;\n\nexport interface InboundLoopConfig {\n  log: ContextualLogger;\n  agentId: string;\n  bus: MessageBus;\n  hookHandler: HookHandler;\n  messageRouter: MessageRouter;\n  commandHandler: CommandHandler;\n  sessionContextManager: SessionContextManager;\n  feedbackCoordinator: FeedbackCoordinator;\n  agentManager: AgentManager;\n  sessionLifecycleManager: SessionLifecycleManager;\n  agentOrchestrator: AgentOrchestrator;\n  outboundCoordinator: OutboundCoordinator;\n  streamManager: StreamManager;\n  sessionState: SessionStateBag;\n  sessionStore: SessionStore;\n  modelManager: ModelManager;\n\n  /** Register a per-session agent-event subscription (idempotent). */\n  setupSessionEventHandling: (sessionKey: string) => void;\n  /** Per-session config hydration (workspace + model override) before a turn runs. */\n  sessionHydrator: SessionHydrator;\n  /** Returns the visible last assistant text used for outbound + persistent-goal hook. */\n  getLastAssistantPlainText: (sessionKey: string) => string;\n  /** Pre-turn auto-compaction (only used by system messages). */\n  checkAndCompact: (sessionKey: string, messages: AgentMessage[]) => Promise<void>;\n  /** Fire-and-forget auto-title (no-ops for cron/heartbeat keys). */\n  enqueueMaybeAutoTitleAfterPersist: (sessionKey: string) => void;\n  /** Effective merged config snapshot. */\n  getConfig: () => Config | undefined;\n  /** Connect a channel stream handle for partial assistant text rendering. */\n  setStreamHandle: (handle: StreamHandle) => void;\n}\n\nexport class InboundLoop {\n  private readonly cfg: InboundLoopConfig;\n  private readonly log: ContextualLogger;\n  private running = false;\n  private channelManagerRef: ChannelManager | null = null;\n\n  constructor(cfg: InboundLoopConfig) {\n    this.cfg = cfg;\n    this.log = cfg.log;\n  }\n\n  setChannelManager(channelManager: ChannelManager | null): void {\n    this.channelManagerRef = channelManager;\n  }\n\n  isRunning(): boolean {\n    return this.running;\n  }\n\n  /** Begin consuming inbound messages from the bus until {@link stop} or shutdown. */\n  async start(): Promise<void> {\n    this.running = true;\n    await this.cfg.hookHandler.trigger('session_start', { sessionId: this.cfg.agentId });\n\n    // Errors fall into two buckets:\n    //   1. `bus.consumeInbound()` itself threw → infrastructure problem; back off\n    //      exponentially so a flapping bus does not pin the CPU at 100%.\n    //   2. `handleInboundMessage(msg)` threw → per-message handler bug. The\n    //      message is already lost; do NOT sleep, just log and move on so\n    //      legitimate traffic is not held hostage.\n    // Shutdown (`MessageBusShutdownError`) is the only signal that breaks the loop.\n    let consecutiveConsumeFailures = 0;\n\n    while (this.running) {\n      let msg: InboundMessage;\n      try {\n        msg = await this.cfg.bus.consumeInbound();\n        consecutiveConsumeFailures = 0;\n      } catch (error) {\n        if (error instanceof MessageBusShutdownError) {\n          break;\n        }\n        consecutiveConsumeFailures += 1;\n        const delayMs = Math.min(\n          INBOUND_CONSUME_MAX_BACKOFF_MS,\n          INBOUND_CONSUME_BASE_BACKOFF_MS * 2 ** (consecutiveConsumeFailures - 1),\n        );\n        const em = error instanceof Error ? error.message : String(error);\n        this.log.error(\n          {\n            err: error,\n            errorMessage: em,\n            phase: 'inbound_consume',\n            consecutiveFailures: consecutiveConsumeFailures,\n            backoffMs: delayMs,\n          },\n          `Bus consume failed (backing off ${delayMs}ms): ${em}`,\n        );\n        await new Promise((resolve) => setTimeout(resolve, delayMs));\n        continue;\n      }\n\n      try {\n        await this.handleInboundMessage(msg);\n      } catch (error) {\n        const em = error instanceof Error ? error.message : String(error);\n        this.log.error(\n          {\n            err: error,\n            errorMessage: em,\n            phase: 'inbound_handle',\n            channel: msg.channel,\n            chatId: msg.chat_id,\n          },\n          `Inbound message handler failed: ${em}`,\n        );\n        // Per-message failure: keep consuming. The next message is independent.\n      }\n    }\n\n    await this.cfg.hookHandler.trigger('session_end', {\n      sessionId: this.cfg.agentId,\n      messageCount: 0,\n    });\n  }\n\n  /** Cooperatively stop the loop; the current message (if any) is allowed to finish. */\n  stop(): void {\n    this.running = false;\n  }\n\n  private async handleInboundMessage(msg: InboundMessage): Promise<void> {\n    const requestId = inboundMessageLogRequestId(msg);\n\n    await runWithLogContext({ requestId }, async () => {\n      const routing = await this.cfg.messageRouter.routeMessage(msg);\n      const { context, isCommand, command, commandArgs } = routing;\n\n      const sessionContext: SessionContext = {\n        sessionKey: context.sessionKey,\n        channel: context.channel,\n        chatId: context.chatId,\n        senderId: context.senderId || '',\n        isGroup: context.isGroup || false,\n        metadata: {\n          transcribedVoice: msg.metadata?.transcribedVoice === true,\n        },\n      };\n\n      updateAsyncLogContext({ sessionId: sessionContext.sessionKey });\n\n      await this.cfg.sessionContextManager.runWith(sessionContext, async () => {\n        this.cfg.feedbackCoordinator.setContext(sessionContext);\n\n        // `subscribeToSession` requires an Agent instance; without this the first inbound never\n        // registers `message_update` streaming (second turn behaved differently).\n        this.cfg.agentManager.getOrCreateAgent(sessionContext.sessionKey);\n        this.cfg.setupSessionEventHandling(sessionContext.sessionKey);\n\n        await this.cfg.sessionLifecycleManager.startSession(sessionContext);\n\n        let typingController: ReturnType<OutboundCoordinator['createTypingControllerForInbound']> = null;\n        let inboundTurnArmed = false;\n        let busProcessFailed: string | undefined;\n\n        try {\n          if (msg.channel === 'system') {\n            await this.handleSystemMessage(msg, sessionContext);\n            return;\n          }\n\n          if (this.channelManagerRef && msg.channel !== 'cli') {\n            await this.channelManagerRef.dispatchInboundMessageAction(msg);\n          }\n\n          if (isCommand && command) {\n            const handled = await this.cfg.commandHandler.executeCommand(command, commandArgs || '', {\n              sessionKey: sessionContext.sessionKey,\n              channel: sessionContext.channel,\n              chatId: sessionContext.chatId,\n              senderId: sessionContext.senderId,\n              isGroup: sessionContext.isGroup,\n              inboundMetadata: msg.metadata,\n            });\n            if (handled) {\n              return;\n            }\n          }\n\n          // Continuous typing indicator (renews every 5 seconds); stopped only AFTER outbound.\n          typingController = this.cfg.outboundCoordinator.createTypingControllerForInbound(msg);\n          typingController?.start();\n\n          if (this.channelManagerRef && msg.channel !== 'cli') {\n            const meta = msg.metadata as Record<string, unknown> | undefined;\n            const streamHandle = this.channelManagerRef.startStream(\n              msg.channel,\n              msg.chat_id,\n              meta?.accountId as string | undefined,\n              {\n                threadId: meta?.threadId as string | undefined,\n                replyToMessageId: meta?.messageId as string | undefined,\n              },\n            );\n            if (streamHandle) {\n              this.cfg.setStreamHandle(streamHandle as StreamHandle);\n            }\n          }\n\n          this.cfg.sessionState.beginInboundTurn(sessionContext.sessionKey);\n          inboundTurnArmed = true;\n          try {\n            await this.cfg.agentOrchestrator.process(msg, sessionContext);\n          } catch (procErr) {\n            busProcessFailed = procErr instanceof Error ? procErr.message : String(procErr);\n            throw procErr;\n          }\n        } finally {\n          await this.cfg.sessionLifecycleManager.endSession(sessionContext);\n          await this.cfg.streamManager.end();\n          try {\n            await this.cfg.outboundCoordinator.sendFinalResponse(msg, sessionContext);\n          } finally {\n            // Clear typing AFTER outbound (incl. TTS); otherwise Weixin shows typing_off before the message.\n            await typingController?.stop();\n          }\n          if (inboundTurnArmed) {\n            const meta = msg.metadata as Record<string, unknown> | undefined;\n            const assistantPlainText = this.cfg.getLastAssistantPlainText(sessionContext.sessionKey) ?? '';\n            try {\n              await this.cfg.outboundCoordinator.emitSessionTurnComplete({\n                sessionKey: sessionContext.sessionKey,\n                channel: sessionContext.channel,\n                chatId: sessionContext.chatId,\n                inboundUserText: msg.content,\n                assistantPlainText,\n                aborted: false,\n                ...(busProcessFailed !== undefined ? { streamError: busProcessFailed } : {}),\n                skipPersistentGoalPostTurn: false,\n                outboundMetadata: {\n                  accountId: meta?.accountId,\n                  threadId: meta?.threadId,\n                },\n              });\n            } catch (turnErr) {\n              const em = turnErr instanceof Error ? turnErr.message : String(turnErr);\n              this.log.warn(\n                { err: turnErr, sessionKey: sessionContext.sessionKey },\n                `Session turn complete failed: ${em}`,\n              );\n            }\n            this.cfg.sessionState.endInboundTurn(sessionContext.sessionKey);\n          }\n          this.cfg.feedbackCoordinator.endTask();\n          this.cfg.feedbackCoordinator.clearContext();\n        }\n      });\n    });\n  }\n\n  private async handleSystemMessage(msg: InboundMessage, context: SessionContext): Promise<void> {\n    this.log.debug({ sessionKey: context.sessionKey }, 'Processing system message');\n\n    await this.cfg.sessionHydrator.workspace(context.sessionKey);\n    await this.cfg.sessionHydrator.model(context.sessionKey);\n\n    const messages = await this.cfg.sessionStore.load(context.sessionKey);\n    await this.cfg.checkAndCompact(context.sessionKey, messages);\n\n    const systemMessage: AgentMessage = {\n      role: 'user',\n      content: [{ type: 'text', text: `[System: ${msg.sender_id}] ${msg.content}` }],\n      timestamp: Date.now(),\n    };\n\n    try {\n      const result = await runEmbeddedTurnForSession({\n        sessionKey: context.sessionKey,\n        userMessage: systemMessage,\n        sessionStore: this.cfg.sessionStore,\n        agentManager: this.cfg.agentManager,\n        modelManager: this.cfg.modelManager,\n        getConfig: this.cfg.getConfig,\n      });\n\n      const finalContent = result.lastAssistantText ?? this.cfg.getLastAssistantPlainText(context.sessionKey);\n      if (finalContent) {\n        this.cfg.sessionState.setLastAssistantText(context.sessionKey, finalContent);\n        const hookResult = await this.cfg.hookHandler.runMessageSending(\n          context.chatId,\n          finalContent,\n          context.channel,\n        );\n        if (hookResult.send) {\n          await this.cfg.bus.publishOutbound({\n            channel: context.channel,\n            chat_id: context.chatId,\n            content: hookResult.content || finalContent,\n            type: 'message',\n          });\n        }\n      }\n      this.cfg.enqueueMaybeAutoTitleAfterPersist(context.sessionKey);\n    } catch (error) {\n      const em = error instanceof Error ? error.message : String(error);\n      this.log.error(\n        {\n          err: error,\n          errorMessage: em,\n          sessionKey: context.sessionKey,\n          channel: context.channel,\n          chatId: context.chatId,\n          senderId: msg.sender_id,\n        },\n        `System message handling failed: ${em}`,\n      );\n      await this.cfg.bus.publishOutbound({\n        channel: context.channel,\n        chat_id: context.chatId,\n        content: '❌ An error occurred while processing the system message.',\n        type: 'message',\n      });\n    }\n  }\n}\n"],"mappings":";;;;;;;aAsBiF;;AAuBjF,MAAM,kCAAkC;;AAExC,MAAM,iCAAiC;AAoCvC,IAAa,cAAb,MAAyB;CACvB;CACA;CACA,UAAkB;CAClB,oBAAmD;CAEnD,YAAY,KAAwB;AAClC,OAAK,MAAM;AACX,OAAK,MAAM,IAAI;;CAGjB,kBAAkB,gBAA6C;AAC7D,OAAK,oBAAoB;;CAG3B,YAAqB;AACnB,SAAO,KAAK;;;CAId,MAAM,QAAuB;AAC3B,OAAK,UAAU;AACf,QAAM,KAAK,IAAI,YAAY,QAAQ,iBAAiB,EAAE,WAAW,KAAK,IAAI,SAAS,CAAC;EASpF,IAAI,6BAA6B;AAEjC,SAAO,KAAK,SAAS;GACnB,IAAI;AACJ,OAAI;AACF,UAAM,MAAM,KAAK,IAAI,IAAI,gBAAgB;AACzC,iCAA6B;YACtB,OAAO;AACd,QAAI,iBAAiB,wBACnB;AAEF,kCAA8B;IAC9B,MAAM,UAAU,KAAK,IACnB,gCACA,kCAAkC,MAAM,6BAA6B,GACtE;IACD,MAAM,KAAK,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;AACjE,SAAK,IAAI,MACP;KACE,KAAK;KACL,cAAc;KACd,OAAO;KACP,qBAAqB;KACrB,WAAW;KACZ,EACD,mCAAmC,QAAQ,OAAO,KACnD;AACD,UAAM,IAAI,SAAS,YAAY,WAAW,SAAS,QAAQ,CAAC;AAC5D;;AAGF,OAAI;AACF,UAAM,KAAK,qBAAqB,IAAI;YAC7B,OAAO;IACd,MAAM,KAAK,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;AACjE,SAAK,IAAI,MACP;KACE,KAAK;KACL,cAAc;KACd,OAAO;KACP,SAAS,IAAI;KACb,QAAQ,IAAI;KACb,EACD,mCAAmC,KACpC;;;AAKL,QAAM,KAAK,IAAI,YAAY,QAAQ,eAAe;GAChD,WAAW,KAAK,IAAI;GACpB,cAAc;GACf,CAAC;;;CAIJ,OAAa;AACX,OAAK,UAAU;;CAGjB,MAAc,qBAAqB,KAAoC;AAGrE,QAAM,kBAAkB,EAAE,WAFR,2BAA2B,IAEV,EAAE,EAAE,YAAY;GAEjD,MAAM,EAAE,SAAS,WAAW,SAAS,gBAAgB,MAD/B,KAAK,IAAI,cAAc,aAAa,IAAI;GAG9D,MAAM,iBAAiC;IACrC,YAAY,QAAQ;IACpB,SAAS,QAAQ;IACjB,QAAQ,QAAQ;IAChB,UAAU,QAAQ,YAAY;IAC9B,SAAS,QAAQ,WAAW;IAC5B,UAAU,EACR,kBAAkB,IAAI,UAAU,qBAAqB,MACtD;IACF;AAED,yBAAsB,EAAE,WAAW,eAAe,YAAY,CAAC;AAE/D,SAAM,KAAK,IAAI,sBAAsB,QAAQ,gBAAgB,YAAY;AACvE,SAAK,IAAI,oBAAoB,WAAW,eAAe;AAIvD,SAAK,IAAI,aAAa,iBAAiB,eAAe,WAAW;AACjE,SAAK,IAAI,0BAA0B,eAAe,WAAW;AAE7D,UAAM,KAAK,IAAI,wBAAwB,aAAa,eAAe;IAEnE,IAAI,mBAAwF;IAC5F,IAAI,mBAAmB;IACvB,IAAI;AAEJ,QAAI;AACF,SAAI,IAAI,YAAY,UAAU;AAC5B,YAAM,KAAK,oBAAoB,KAAK,eAAe;AACnD;;AAGF,SAAI,KAAK,qBAAqB,IAAI,YAAY,MAC5C,OAAM,KAAK,kBAAkB,6BAA6B,IAAI;AAGhE,SAAI,aAAa;UASX,MARkB,KAAK,IAAI,eAAe,eAAe,SAAS,eAAe,IAAI;OACvF,YAAY,eAAe;OAC3B,SAAS,eAAe;OACxB,QAAQ,eAAe;OACvB,UAAU,eAAe;OACzB,SAAS,eAAe;OACxB,iBAAiB,IAAI;OACtB,CAAC,CAEA;;AAKJ,wBAAmB,KAAK,IAAI,oBAAoB,iCAAiC,IAAI;AACrF,uBAAkB,OAAO;AAEzB,SAAI,KAAK,qBAAqB,IAAI,YAAY,OAAO;MACnD,MAAM,OAAO,IAAI;MACjB,MAAM,eAAe,KAAK,kBAAkB,YAC1C,IAAI,SACJ,IAAI,SACJ,MAAM,WACN;OACE,UAAU,MAAM;OAChB,kBAAkB,MAAM;OACzB,CACF;AACD,UAAI,aACF,MAAK,IAAI,gBAAgB,aAA6B;;AAI1D,UAAK,IAAI,aAAa,iBAAiB,eAAe,WAAW;AACjE,wBAAmB;AACnB,SAAI;AACF,YAAM,KAAK,IAAI,kBAAkB,QAAQ,KAAK,eAAe;cACtD,SAAS;AAChB,yBAAmB,mBAAmB,QAAQ,QAAQ,UAAU,OAAO,QAAQ;AAC/E,YAAM;;cAEA;AACR,WAAM,KAAK,IAAI,wBAAwB,WAAW,eAAe;AACjE,WAAM,KAAK,IAAI,cAAc,KAAK;AAClC,SAAI;AACF,YAAM,KAAK,IAAI,oBAAoB,kBAAkB,KAAK,eAAe;eACjE;AAER,YAAM,kBAAkB,MAAM;;AAEhC,SAAI,kBAAkB;MACpB,MAAM,OAAO,IAAI;MACjB,MAAM,qBAAqB,KAAK,IAAI,0BAA0B,eAAe,WAAW,IAAI;AAC5F,UAAI;AACF,aAAM,KAAK,IAAI,oBAAoB,wBAAwB;QACzD,YAAY,eAAe;QAC3B,SAAS,eAAe;QACxB,QAAQ,eAAe;QACvB,iBAAiB,IAAI;QACrB;QACA,SAAS;QACT,GAAI,qBAAqB,KAAA,IAAY,EAAE,aAAa,kBAAkB,GAAG,EAAE;QAC3E,4BAA4B;QAC5B,kBAAkB;SAChB,WAAW,MAAM;SACjB,UAAU,MAAM;SACjB;QACF,CAAC;eACK,SAAS;OAChB,MAAM,KAAK,mBAAmB,QAAQ,QAAQ,UAAU,OAAO,QAAQ;AACvE,YAAK,IAAI,KACP;QAAE,KAAK;QAAS,YAAY,eAAe;QAAY,EACvD,iCAAiC,KAClC;;AAEH,WAAK,IAAI,aAAa,eAAe,eAAe,WAAW;;AAEjE,UAAK,IAAI,oBAAoB,SAAS;AACtC,UAAK,IAAI,oBAAoB,cAAc;;KAE7C;IACF;;CAGJ,MAAc,oBAAoB,KAAqB,SAAwC;AAC7F,OAAK,IAAI,MAAM,EAAE,YAAY,QAAQ,YAAY,EAAE,4BAA4B;AAE/E,QAAM,KAAK,IAAI,gBAAgB,UAAU,QAAQ,WAAW;AAC5D,QAAM,KAAK,IAAI,gBAAgB,MAAM,QAAQ,WAAW;EAExD,MAAM,WAAW,MAAM,KAAK,IAAI,aAAa,KAAK,QAAQ,WAAW;AACrE,QAAM,KAAK,IAAI,gBAAgB,QAAQ,YAAY,SAAS;EAE5D,MAAM,gBAA8B;GAClC,MAAM;GACN,SAAS,CAAC;IAAE,MAAM;IAAQ,MAAM,YAAY,IAAI,UAAU,IAAI,IAAI;IAAW,CAAC;GAC9E,WAAW,KAAK,KAAK;GACtB;AAED,MAAI;GAUF,MAAM,gBAAe,MATA,0BAA0B;IAC7C,YAAY,QAAQ;IACpB,aAAa;IACb,cAAc,KAAK,IAAI;IACvB,cAAc,KAAK,IAAI;IACvB,cAAc,KAAK,IAAI;IACvB,WAAW,KAAK,IAAI;IACrB,CAAC,EAE0B,qBAAqB,KAAK,IAAI,0BAA0B,QAAQ,WAAW;AACvG,OAAI,cAAc;AAChB,SAAK,IAAI,aAAa,qBAAqB,QAAQ,YAAY,aAAa;IAC5E,MAAM,aAAa,MAAM,KAAK,IAAI,YAAY,kBAC5C,QAAQ,QACR,cACA,QAAQ,QACT;AACD,QAAI,WAAW,KACb,OAAM,KAAK,IAAI,IAAI,gBAAgB;KACjC,SAAS,QAAQ;KACjB,SAAS,QAAQ;KACjB,SAAS,WAAW,WAAW;KAC/B,MAAM;KACP,CAAC;;AAGN,QAAK,IAAI,kCAAkC,QAAQ,WAAW;WACvD,OAAO;GACd,MAAM,KAAK,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;AACjE,QAAK,IAAI,MACP;IACE,KAAK;IACL,cAAc;IACd,YAAY,QAAQ;IACpB,SAAS,QAAQ;IACjB,QAAQ,QAAQ;IAChB,UAAU,IAAI;IACf,EACD,mCAAmC,KACpC;AACD,SAAM,KAAK,IAAI,IAAI,gBAAgB;IACjC,SAAS,QAAQ;IACjB,SAAS,QAAQ;IACjB,SAAS;IACT,MAAM;IACP,CAAC"}

package/dist/src/agent/inbound/turn-dispatcher.d.ts

@@ -0,0 +1,80 @@
+/**
+ * TurnDispatcher — single entry point for direct (non-bus) agent turns.
+ *
+ * Wraps the two existing direct-turn runners (one-shot and streaming) so the
+ * parent `AgentService` no longer carries a pair of huge `createXxxDeps()`
+ * factories. The public surface — `processDirect`, `processDirectStreaming`,
+ * `steerWebchatSession`, `enqueueWebchatSseEvent`,
+ * `notifyWebchatTranscriptAppend` — matches what `AgentService` exposed
+ * previously, so callers (gateway, CLI) are unchanged.
+ *
+ * Like `OutboundCoordinator` and `InboundLoop`, this class accepts a wide
+ * dependency bag in its constructor (the direct-turn pipeline touches almost
+ * every other subsystem). The win is that AgentService becomes the only place
+ * that wires those dependencies together; individual responsibilities now live
+ * in their own classes and are unit-testable.
+ */
+import type { Config } from '../../config/schema.js';
+import type { ContextualLogger } from '../../utils/logger/types.js';
+import type { AgentManager } from '../agent-manager.js';
+import type { CommandHandler } from '../messaging/command-handler.js';
+import type { ModelManager } from '../models/index.js';
+import type { SessionConfigStore } from '../../session/index.js';
+import type { SessionStore } from '../../session/store.js';
+import type { SessionContext, SessionHydrator, SessionStateBag } from '../session/index.js';
+import type { InternalAttachmentRoots } from '../../channels/attachments/inbound-persist.js';
+import { type DirectInboundAttachment } from '../service/build-direct-message-content.js';
+import { type ProcessDirectStreamingSseEvent } from '../service/process-direct-streaming.js';
+export interface TurnDispatcherConfig {
+    log: ContextualLogger;
+    agentManager: AgentManager;
+    sessionStore: SessionStore;
+    modelManager: ModelManager;
+    sessionConfigStore: SessionConfigStore;
+    sessionState: SessionStateBag;
+    commandHandler: CommandHandler;
+    getConfig: () => Config | undefined;
+    /** Strict accessor — required for direct-turn paths that must have a config. */
+    requireConfig: () => Config;
+    parseSessionKey: (sessionKey: string) => {
+        channel: string;
+        chatId: string;
+    };
+    /** Establish per-session context (also creates the Agent + subscribes to events). */
+    initSessionContext: (sessionKey: string, channel: string, chatId: string) => SessionContext;
+    /** Per-session config hydration: workspace, model, thinking. */
+    sessionHydrator: SessionHydrator;
+    attachmentRootsForSession: (sessionKey: string) => InternalAttachmentRoots;
+    prepareInboundAttachments: (sessionKey: string, attachments?: DirectInboundAttachment[]) => Promise<DirectInboundAttachment[] | undefined>;
+    enqueueMaybeAutoTitleAfterPersist: (sessionKey: string) => void;
+    endDirectRequestContext: () => void;
+    /** Gateway hook fired after assistant text lands on disk (UI refetch). */
+    onSessionTranscriptUpdated?: (sessionKey: string) => void;
+}
+export type DirectAttachment = DirectInboundAttachment;
+export declare class TurnDispatcher {
+    private readonly cfg;
+    private readonly log;
+    constructor(cfg: TurnDispatcherConfig);
+    /** One-shot direct turn (CLI / embedded TUI). */
+    processDirect(content: string, sessionKey?: string, attachments?: DirectAttachment[], thinking?: string): Promise<string>;
+    /** Streaming direct turn (webchat SSE / CLI streaming). */
+    processDirectStreaming(content: string, sessionKey?: string, attachments?: DirectAttachment[], thinking?: string, options?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<ProcessDirectStreamingSseEvent, void, unknown>;
+    /** Push an out-of-band event into the live webchat stream for a session. */
+    enqueueWebchatSseEvent(sessionKey: string, event: {
+        type: string;
+        [key: string]: unknown;
+    }): void;
+    /** Stream assistant text to live webchat session + notify transcript listeners. */
+    notifyWebchatTranscriptAppend(sessionKey: string, assistantText: string): void;
+    /**
+     * Queue a steering user message into pi-agent's in-flight run (delivered
+     * after current tool work, before the next LLM call). See `Agent.steer`
+     * in `@earendil-works/pi-agent-core`.
+     */
+    steerWebchatSession(sessionKey: string, text: string): Promise<boolean>;
+    private buildStreamingDeps;
+    private buildOneShotDeps;
+}