@xopcai/xopc 0.0.82 → 0.0.84

package/dist/src/agent/session/session-config-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-config-service.js","names":[],"sources":["../../../../src/agent/session/session-config-service.ts"],"sourcesContent":["/**\n * SessionConfigService — owns the \"write side\" of per-session agent settings\n * (model override, thinking level, reasoning level, working directory).\n *\n * Previously these lived as four sibling methods on `AgentService`:\n *   - `patchSessionAgentConfig` (96 lines of validation + persistence)\n *   - `applyCronJobWorkingDirectory` (cron-specific working dir update)\n *   - `clearCronSessionWorkingDirectoryOverride` (private helper)\n *   - `clearSessionModelOverride` (private helper)\n *\n * Extracted so `AgentService` no longer mixes \"session bag\" concerns with\n * \"session config write\" concerns, and so future additions to the patch API\n * (e.g. new per-session overrides) only touch this file.\n */\n\nimport { mkdir } from 'node:fs/promises';\nimport type { ThinkingLevel } from '@earendil-works/pi-agent-core';\n\nimport type { Config } from '../../config/schema.js';\nimport { normalizeWorkingDirectoryInput } from '../../session/index.js';\nimport type { SessionConfigStore, SessionStore } from '../../session/index.js';\nimport {\n  normalizeThinkLevel,\n  normalizeReasoningLevel,\n} from '../transcript/thinking-types.js';\nimport type { AgentInstanceGateway } from '../agent-instance-gateway.js';\nimport type { ModelManager } from '../models/index.js';\nimport { createLogger } from '../../utils/logger.js';\n\nconst log = createLogger('SessionConfigService');\n\nexport interface SessionConfigServiceOptions {\n  sessionStore: SessionStore;\n  sessionConfigStore: SessionConfigStore;\n  modelManager: ModelManager;\n  agentManager: AgentInstanceGateway;\n  /** Effective config snapshot accessor. */\n  getConfig: () => Config | undefined;\n}\n\nexport interface PatchSessionAgentConfigInput {\n  thinkingLevel?: string;\n  model?: string | null;\n  reasoningLevel?: string;\n  workingDirectory?: string;\n}\n\nexport interface PatchSessionAgentConfigResult {\n  ok: boolean;\n  error?: string;\n}\n\nexport class SessionConfigService {\n  private readonly opts: SessionConfigServiceOptions;\n\n  constructor(opts: SessionConfigServiceOptions) {\n    this.opts = opts;\n  }\n\n  /**\n   * Apply a partial patch (model / thinking / reasoning / working directory) to\n   * a session's persisted config. Returns `{ ok: false, error }` on the first\n   * invalid field — earlier fields that succeeded are NOT rolled back, matching\n   * the previous behaviour.\n   */\n  async patch(\n    sessionKey: string,\n    partial: PatchSessionAgentConfigInput,\n  ): Promise<PatchSessionAgentConfigResult> {\n    if (partial.model !== undefined) {\n      if (partial.model === null || partial.model === '') {\n        await this.clearModelOverride(sessionKey);\n      } else {\n        const ok = await this.opts.modelManager.switchModelForSession(sessionKey, partial.model);\n        if (!ok) {\n          return { ok: false, error: 'Invalid model' };\n        }\n        await this.opts.sessionConfigStore.update(sessionKey, { modelOverride: partial.model });\n        this.opts.agentManager.setModelForSession(sessionKey, partial.model);\n      }\n    }\n\n    if (partial.thinkingLevel !== undefined) {\n      const normalized = normalizeThinkLevel(partial.thinkingLevel);\n      if (!normalized) {\n        return { ok: false, error: 'Invalid thinking level' };\n      }\n      await this.opts.sessionConfigStore.update(sessionKey, { thinkingLevel: normalized });\n      this.opts.agentManager.setThinkingLevel(sessionKey, normalized as ThinkingLevel);\n    }\n\n    if (partial.reasoningLevel !== undefined) {\n      const normalized = normalizeReasoningLevel(partial.reasoningLevel);\n      if (!normalized) {\n        return { ok: false, error: 'Invalid reasoning level' };\n      }\n      await this.opts.sessionConfigStore.update(sessionKey, { reasoningLevel: normalized });\n    }\n\n    if (partial.workingDirectory !== undefined) {\n      const cfg = this.opts.getConfig();\n      if (!cfg) {\n        return { ok: false, error: 'Config not loaded' };\n      }\n      const result = await this.patchWorkingDirectory(sessionKey, partial.workingDirectory);\n      if (!result.ok) return result;\n    }\n\n    return { ok: true };\n  }\n\n  /**\n   * Sync persisted session working directory for an isolated cron run. Runs\n   * may change when the job is edited; an empty/missing input clears the\n   * override so the session uses the effective agent default.\n   */\n  async applyCronJobWorkingDirectory(\n    sessionKey: string,\n    workingDirectory: string | undefined,\n  ): Promise<void> {\n    const raw = workingDirectory?.trim();\n    if (raw) {\n      const wdNorm = normalizeWorkingDirectoryInput(raw);\n      if (wdNorm.ok === false) {\n        log.warn(\n          { sessionKey, error: wdNorm.error },\n          'Cron job working directory invalid; using agent default',\n        );\n        await this.clearCronWorkingDirectoryOverride(sessionKey);\n        return;\n      }\n      await mkdir(wdNorm.path, { recursive: true });\n      await this.opts.sessionConfigStore.update(sessionKey, { workingDirectoryOverride: wdNorm.path });\n      this.opts.agentManager.setSessionWorkspaceOverride(sessionKey, wdNorm.path);\n      return;\n    }\n    await this.clearCronWorkingDirectoryOverride(sessionKey);\n  }\n\n  /**\n   * Clear the session's model override (back to agent default). Used both by\n   * {@link patch} and by `AgentService.resetSessionModelToAgentDefault`.\n   */\n  async clearModelOverride(sessionKey: string): Promise<void> {\n    this.opts.modelManager.clearSessionModelOverride(sessionKey);\n    await this.opts.sessionConfigStore.update(sessionKey, { modelOverride: undefined });\n    const agent = this.opts.agentManager.getAgent(sessionKey);\n    if (agent) {\n      await this.opts.modelManager.applyModelForSession(agent, sessionKey);\n    }\n  }\n\n  // ── Internal helpers ───────────────────────────────────────────────────\n\n  private async clearCronWorkingDirectoryOverride(sessionKey: string): Promise<void> {\n    const existing = await this.opts.sessionConfigStore.get(sessionKey);\n    if (existing?.workingDirectoryOverride) {\n      const { workingDirectoryOverride: _removed, ...rest } = existing;\n      await this.opts.sessionConfigStore.set(sessionKey, rest);\n    }\n    this.opts.agentManager.setSessionWorkspaceOverride(sessionKey, null);\n  }\n\n  /**\n   * Apply the workingDirectory branch of `patch`. Returns the next-step result\n   * (`ok: true` to keep going, `ok: false, error` to short-circuit the patch).\n   *\n   * Working directory has the strictest semantics: once a session has any\n   * messages, it cannot move to a different directory — only re-setting the\n   * same path is idempotent.\n   */\n  private async patchWorkingDirectory(\n    sessionKey: string,\n    workingDirectory: string,\n  ): Promise<PatchSessionAgentConfigResult> {\n    const existing = await this.opts.sessionConfigStore.get(sessionKey);\n    const existingRaw = existing?.workingDirectoryOverride?.trim();\n    const incoming = workingDirectory.trim();\n\n    const priorMessages = await this.opts.sessionStore.load(sessionKey);\n\n    if (priorMessages.length > 0) {\n      if (!incoming) {\n        return { ok: false, error: 'workingDirectory is empty' };\n      }\n      if (!existingRaw) {\n        return {\n          ok: false,\n          error: 'Working directory can only be set before the first message in this conversation',\n        };\n      }\n      const prev = normalizeWorkingDirectoryInput(existingRaw);\n      const next = normalizeWorkingDirectoryInput(incoming);\n      if (prev.ok && next.ok && prev.path === next.path) {\n        // idempotent\n        return { ok: true };\n      }\n      return { ok: false, error: 'Working directory is already set for this session' };\n    }\n\n    if (!incoming) {\n      return { ok: false, error: 'workingDirectory is empty' };\n    }\n    const wdNorm = normalizeWorkingDirectoryInput(incoming);\n    switch (wdNorm.ok) {\n      case true: {\n        if (existingRaw) {\n          const prev = normalizeWorkingDirectoryInput(existingRaw);\n          if (prev.ok && prev.path === wdNorm.path) {\n            return { ok: true };\n          }\n        }\n        await mkdir(wdNorm.path, { recursive: true });\n        await this.opts.sessionConfigStore.update(sessionKey, {\n          workingDirectoryOverride: wdNorm.path,\n        });\n        this.opts.agentManager.setSessionWorkspaceOverride(sessionKey, wdNorm.path);\n        this.opts.agentManager.removeAgent(sessionKey);\n        return { ok: true };\n      }\n      case false:\n        return { ok: false, error: wdNorm.error };\n      default:\n        return { ok: false, error: 'Invalid working directory' };\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;aA2BqD;AAErD,MAAM,MAAM,aAAa,uBAAuB;AAuBhD,IAAa,uBAAb,MAAkC;CAChC;CAEA,YAAY,MAAmC;AAC7C,OAAK,OAAO;;;;;;;;CASd,MAAM,MACJ,YACA,SACwC;AACxC,MAAI,QAAQ,UAAU,KAAA,EACpB,KAAI,QAAQ,UAAU,QAAQ,QAAQ,UAAU,GAC9C,OAAM,KAAK,mBAAmB,WAAW;OACpC;AAEL,OAAI,CAAC,MADY,KAAK,KAAK,aAAa,sBAAsB,YAAY,QAAQ,MAAM,CAEtF,QAAO;IAAE,IAAI;IAAO,OAAO;IAAiB;AAE9C,SAAM,KAAK,KAAK,mBAAmB,OAAO,YAAY,EAAE,eAAe,QAAQ,OAAO,CAAC;AACvF,QAAK,KAAK,aAAa,mBAAmB,YAAY,QAAQ,MAAM;;AAIxE,MAAI,QAAQ,kBAAkB,KAAA,GAAW;GACvC,MAAM,aAAa,oBAAoB,QAAQ,cAAc;AAC7D,OAAI,CAAC,WACH,QAAO;IAAE,IAAI;IAAO,OAAO;IAA0B;AAEvD,SAAM,KAAK,KAAK,mBAAmB,OAAO,YAAY,EAAE,eAAe,YAAY,CAAC;AACpF,QAAK,KAAK,aAAa,iBAAiB,YAAY,WAA4B;;AAGlF,MAAI,QAAQ,mBAAmB,KAAA,GAAW;GACxC,MAAM,aAAa,wBAAwB,QAAQ,eAAe;AAClE,OAAI,CAAC,WACH,QAAO;IAAE,IAAI;IAAO,OAAO;IAA2B;AAExD,SAAM,KAAK,KAAK,mBAAmB,OAAO,YAAY,EAAE,gBAAgB,YAAY,CAAC;;AAGvF,MAAI,QAAQ,qBAAqB,KAAA,GAAW;AAE1C,OAAI,CADQ,KAAK,KAAK,WACd,CACN,QAAO;IAAE,IAAI;IAAO,OAAO;IAAqB;GAElD,MAAM,SAAS,MAAM,KAAK,sBAAsB,YAAY,QAAQ,iBAAiB;AACrF,OAAI,CAAC,OAAO,GAAI,QAAO;;AAGzB,SAAO,EAAE,IAAI,MAAM;;;;;;;CAQrB,MAAM,6BACJ,YACA,kBACe;EACf,MAAM,MAAM,kBAAkB,MAAM;AACpC,MAAI,KAAK;GACP,MAAM,SAAS,+BAA+B,IAAI;AAClD,OAAI,OAAO,OAAO,OAAO;AACvB,QAAI,KACF;KAAE;KAAY,OAAO,OAAO;KAAO,EACnC,0DACD;AACD,UAAM,KAAK,kCAAkC,WAAW;AACxD;;AAEF,SAAM,MAAM,OAAO,MAAM,EAAE,WAAW,MAAM,CAAC;AAC7C,SAAM,KAAK,KAAK,mBAAmB,OAAO,YAAY,EAAE,0BAA0B,OAAO,MAAM,CAAC;AAChG,QAAK,KAAK,aAAa,4BAA4B,YAAY,OAAO,KAAK;AAC3E;;AAEF,QAAM,KAAK,kCAAkC,WAAW;;;;;;CAO1D,MAAM,mBAAmB,YAAmC;AAC1D,OAAK,KAAK,aAAa,0BAA0B,WAAW;AAC5D,QAAM,KAAK,KAAK,mBAAmB,OAAO,YAAY,EAAE,eAAe,KAAA,GAAW,CAAC;EACnF,MAAM,QAAQ,KAAK,KAAK,aAAa,SAAS,WAAW;AACzD,MAAI,MACF,OAAM,KAAK,KAAK,aAAa,qBAAqB,OAAO,WAAW;;CAMxE,MAAc,kCAAkC,YAAmC;EACjF,MAAM,WAAW,MAAM,KAAK,KAAK,mBAAmB,IAAI,WAAW;AACnE,MAAI,UAAU,0BAA0B;GACtC,MAAM,EAAE,0BAA0B,UAAU,GAAG,SAAS;AACxD,SAAM,KAAK,KAAK,mBAAmB,IAAI,YAAY,KAAK;;AAE1D,OAAK,KAAK,aAAa,4BAA4B,YAAY,KAAK;;;;;;;;;;CAWtE,MAAc,sBACZ,YACA,kBACwC;EAExC,MAAM,eAAc,MADG,KAAK,KAAK,mBAAmB,IAAI,WAAW,GACrC,0BAA0B,MAAM;EAC9D,MAAM,WAAW,iBAAiB,MAAM;AAIxC,OAAI,MAFwB,KAAK,KAAK,aAAa,KAAK,WAAW,EAEjD,SAAS,GAAG;AAC5B,OAAI,CAAC,SACH,QAAO;IAAE,IAAI;IAAO,OAAO;IAA6B;AAE1D,OAAI,CAAC,YACH,QAAO;IACL,IAAI;IACJ,OAAO;IACR;GAEH,MAAM,OAAO,+BAA+B,YAAY;GACxD,MAAM,OAAO,+BAA+B,SAAS;AACrD,OAAI,KAAK,MAAM,KAAK,MAAM,KAAK,SAAS,KAAK,KAE3C,QAAO,EAAE,IAAI,MAAM;AAErB,UAAO;IAAE,IAAI;IAAO,OAAO;IAAqD;;AAGlF,MAAI,CAAC,SACH,QAAO;GAAE,IAAI;GAAO,OAAO;GAA6B;EAE1D,MAAM,SAAS,+BAA+B,SAAS;AACvD,UAAQ,OAAO,IAAf;GACE,KAAK;AACH,QAAI,aAAa;KACf,MAAM,OAAO,+BAA+B,YAAY;AACxD,SAAI,KAAK,MAAM,KAAK,SAAS,OAAO,KAClC,QAAO,EAAE,IAAI,MAAM;;AAGvB,UAAM,MAAM,OAAO,MAAM,EAAE,WAAW,MAAM,CAAC;AAC7C,UAAM,KAAK,KAAK,mBAAmB,OAAO,YAAY,EACpD,0BAA0B,OAAO,MAClC,CAAC;AACF,SAAK,KAAK,aAAa,4BAA4B,YAAY,OAAO,KAAK;AAC3E,SAAK,KAAK,aAAa,YAAY,WAAW;AAC9C,WAAO,EAAE,IAAI,MAAM;GAErB,KAAK,MACH,QAAO;IAAE,IAAI;IAAO,OAAO,OAAO;IAAO;GAC3C,QACE,QAAO;IAAE,IAAI;IAAO,OAAO;IAA6B"}

package/dist/src/agent/session/session-context.d.ts

@@ -1,7 +1,18 @@
 /**
- * Session Context - Types and manager for session context
+ * Session Context — types + an `AsyncLocalStorage`-backed manager.
  *
- * Manages session context state and provides utilities for context extraction.
+ * The previous implementation kept the "current" session context in a single
+ * mutable field on the class. That meant bus-inbound and direct-stream paths
+ * concurrently handling different sessions could overwrite each other's view
+ * of "current session", with tools reading the wrong sessionKey at execution
+ * time (the only thing masking it was the inbound consumer being serial).
+ *
+ * The new manager uses `AsyncLocalStorage`, so each async chain sees its own
+ * context. Callers establish a scope via {@link SessionContextManager.runWith}
+ * (preferred for `async` functions) or {@link SessionContextManager.enter}
+ * (used at the top of `async function*` generators where callback-wrapping is
+ * awkward; the context leaks into the rest of the current async resource by
+ * design).
  */
 import type { InboundMessage } from '../../infra/bus/index.js';
 export interface SessionContext {
@@ -14,29 +25,26 @@ export interface SessionContext {
     metadata?: Record<string, unknown>;
 }
 export declare class SessionContextManager {
-    private currentContext;
+    private readonly als;
     /**
-     * Set the current session context
+     * Run `fn` with `ctx` exposed via {@link getContext} for every async branch
+     * it launches. The context is automatically dropped when `fn` resolves or
+     * throws — there is no manual `clearContext` needed.
      */
-    setContext(context: SessionContext): void;
+    runWith<T>(ctx: SessionContext, fn: () => Promise<T>): Promise<T>;
     /**
-     * Get the current session context
+     * Establish a context for the current async resource and its descendants.
+     * Use this at the top of an `async function*` body where wrapping the whole
+     * generator in {@link runWith} is impractical. The context leaks into the
+     * rest of the current async tree by design — call from the start of an
+     * isolated generator so it does not bleed across requests.
      */
+    enter(ctx: SessionContext): void;
+    /** Returns the session context for the current async chain, or null. */
     getContext(): SessionContext | null;
-    /**
-     * Clear the current session context
-     */
-    clearContext(): void;
-    /**
-     * Check if a context is currently set
-     */
     hasContext(): boolean;
-    /**
-     * Extract session context from an inbound message
-     */
+    /** Extract session context from an inbound bus message. */
     static extractFromMessage(msg: InboundMessage): SessionContext;
-    /**
-     * Create a clone of the current context with optional overrides
-     */
+    /** Create a clone of the current context with optional overrides. */
     cloneContext(overrides?: Partial<SessionContext>): SessionContext | null;
 }

package/dist/src/agent/session/session-context.js

@@ -1,33 +1,49 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/agent/session/session-context.ts
+/**
+* Session Context — types + an `AsyncLocalStorage`-backed manager.
+*
+* The previous implementation kept the "current" session context in a single
+* mutable field on the class. That meant bus-inbound and direct-stream paths
+* concurrently handling different sessions could overwrite each other's view
+* of "current session", with tools reading the wrong sessionKey at execution
+* time (the only thing masking it was the inbound consumer being serial).
+*
+* The new manager uses `AsyncLocalStorage`, so each async chain sees its own
+* context. Callers establish a scope via {@link SessionContextManager.runWith}
+* (preferred for `async` functions) or {@link SessionContextManager.enter}
+* (used at the top of `async function*` generators where callback-wrapping is
+* awkward; the context leaks into the rest of the current async resource by
+* design).
+*/
 var SessionContextManager = class {
-	currentContext = null;
+	als = new AsyncLocalStorage();
 	/**
-	* Set the current session context
+	* Run `fn` with `ctx` exposed via {@link getContext} for every async branch
+	* it launches. The context is automatically dropped when `fn` resolves or
+	* throws — there is no manual `clearContext` needed.
 	*/
-	setContext(context) {
-		this.currentContext = context;
+	async runWith(ctx, fn) {
+		return this.als.run(ctx, fn);
 	}
 	/**
-	* Get the current session context
+	* Establish a context for the current async resource and its descendants.
+	* Use this at the top of an `async function*` body where wrapping the whole
+	* generator in {@link runWith} is impractical. The context leaks into the
+	* rest of the current async tree by design — call from the start of an
+	* isolated generator so it does not bleed across requests.
 	*/
-	getContext() {
-		return this.currentContext;
+	enter(ctx) {
+		this.als.enterWith(ctx);
 	}
-	/**
-	* Clear the current session context
-	*/
-	clearContext() {
-		this.currentContext = null;
+	/** Returns the session context for the current async chain, or null. */
+	getContext() {
+		return this.als.getStore() ?? null;
 	}
-	/**
-	* Check if a context is currently set
-	*/
 	hasContext() {
-		return this.currentContext !== null;
+		return this.als.getStore() !== void 0;
 	}
-	/**
-	* Extract session context from an inbound message
-	*/
+	/** Extract session context from an inbound bus message. */
 	static extractFromMessage(msg) {
 		const metadata = msg.metadata || {};
 		return {
@@ -40,13 +56,12 @@ var SessionContextManager = class {
 			metadata
 		};
 	}
-	/**
-	* Create a clone of the current context with optional overrides
-	*/
+	/** Create a clone of the current context with optional overrides. */
 	cloneContext(overrides) {
-		if (!this.currentContext) return null;
+		const current = this.getContext();
+		if (!current) return null;
 		return {
-			...this.currentContext,
+			...current,
 			...overrides
 		};
 	}

package/dist/src/agent/session/session-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-context.js","names":[],"sources":["../../../../src/agent/session/session-context.ts"],"sourcesContent":["/**\n * Session Context - Types and manager for session context\n *\n * Manages session context state and provides utilities for context extraction.\n */\n\nimport type { InboundMessage } from '../../infra/bus/index.js';\n\nexport interface SessionContext {\n  sessionKey: string;\n  channel: string;\n  chatId: string;\n  senderId: string;\n  isGroup: boolean;\n  model?: string;\n  metadata?: Record<string, unknown>;\n}\n\nexport class SessionContextManager {\n  private currentContext: SessionContext | null = null;\n\n  /**\n   * Set the current session context\n   */\n  setContext(context: SessionContext): void {\n    this.currentContext = context;\n  }\n\n  /**\n   * Get the current session context\n   */\n  getContext(): SessionContext | null {\n    return this.currentContext;\n  }\n\n  /**\n   * Clear the current session context\n   */\n  clearContext(): void {\n    this.currentContext = null;\n  }\n\n  /**\n   * Check if a context is currently set\n   */\n  hasContext(): boolean {\n    return this.currentContext !== null;\n  }\n\n  /**\n   * Extract session context from an inbound message\n   */\n  static extractFromMessage(msg: InboundMessage): SessionContext {\n    const metadata = msg.metadata || {};\n    \n    return {\n      sessionKey: (metadata.sessionKey as string) || `${msg.channel}:${msg.chat_id}`,\n      channel: msg.channel,\n      chatId: msg.chat_id,\n      senderId: (metadata.senderId as string) || '',\n      isGroup: (metadata.isGroup as boolean) || false,\n      model: metadata.model as string | undefined,\n      metadata,\n    };\n  }\n\n  /**\n   * Create a clone of the current context with optional overrides\n   */\n  cloneContext(overrides?: Partial<SessionContext>): SessionContext | null {\n    if (!this.currentContext) return null;\n    \n    return {\n      ...this.currentContext,\n      ...overrides,\n    };\n  }\n}\n"],"mappings":";AAkBA,IAAa,wBAAb,MAAmC;CACjC,iBAAgD;;;;CAKhD,WAAW,SAA+B;AACxC,OAAK,iBAAiB;;;;;CAMxB,aAAoC;AAClC,SAAO,KAAK;;;;;CAMd,eAAqB;AACnB,OAAK,iBAAiB;;;;;CAMxB,aAAsB;AACpB,SAAO,KAAK,mBAAmB;;;;;CAMjC,OAAO,mBAAmB,KAAqC;EAC7D,MAAM,WAAW,IAAI,YAAY,EAAE;AAEnC,SAAO;GACL,YAAa,SAAS,cAAyB,GAAG,IAAI,QAAQ,GAAG,IAAI;GACrE,SAAS,IAAI;GACb,QAAQ,IAAI;GACZ,UAAW,SAAS,YAAuB;GAC3C,SAAU,SAAS,WAAuB;GAC1C,OAAO,SAAS;GAChB;GACD;;;;;CAMH,aAAa,WAA4D;AACvE,MAAI,CAAC,KAAK,eAAgB,QAAO;AAEjC,SAAO;GACL,GAAG,KAAK;GACR,GAAG;GACJ"}
+{"version":3,"file":"session-context.js","names":[],"sources":["../../../../src/agent/session/session-context.ts"],"sourcesContent":["/**\n * Session Context — types + an `AsyncLocalStorage`-backed manager.\n *\n * The previous implementation kept the \"current\" session context in a single\n * mutable field on the class. That meant bus-inbound and direct-stream paths\n * concurrently handling different sessions could overwrite each other's view\n * of \"current session\", with tools reading the wrong sessionKey at execution\n * time (the only thing masking it was the inbound consumer being serial).\n *\n * The new manager uses `AsyncLocalStorage`, so each async chain sees its own\n * context. Callers establish a scope via {@link SessionContextManager.runWith}\n * (preferred for `async` functions) or {@link SessionContextManager.enter}\n * (used at the top of `async function*` generators where callback-wrapping is\n * awkward; the context leaks into the rest of the current async resource by\n * design).\n */\n\nimport { AsyncLocalStorage } from 'node:async_hooks';\n\nimport type { InboundMessage } from '../../infra/bus/index.js';\n\nexport interface SessionContext {\n  sessionKey: string;\n  channel: string;\n  chatId: string;\n  senderId: string;\n  isGroup: boolean;\n  model?: string;\n  metadata?: Record<string, unknown>;\n}\n\nexport class SessionContextManager {\n  private readonly als = new AsyncLocalStorage<SessionContext>();\n\n  /**\n   * Run `fn` with `ctx` exposed via {@link getContext} for every async branch\n   * it launches. The context is automatically dropped when `fn` resolves or\n   * throws — there is no manual `clearContext` needed.\n   */\n  async runWith<T>(ctx: SessionContext, fn: () => Promise<T>): Promise<T> {\n    return this.als.run(ctx, fn);\n  }\n\n  /**\n   * Establish a context for the current async resource and its descendants.\n   * Use this at the top of an `async function*` body where wrapping the whole\n   * generator in {@link runWith} is impractical. The context leaks into the\n   * rest of the current async tree by design — call from the start of an\n   * isolated generator so it does not bleed across requests.\n   */\n  enter(ctx: SessionContext): void {\n    this.als.enterWith(ctx);\n  }\n\n  /** Returns the session context for the current async chain, or null. */\n  getContext(): SessionContext | null {\n    return this.als.getStore() ?? null;\n  }\n\n  hasContext(): boolean {\n    return this.als.getStore() !== undefined;\n  }\n\n  /** Extract session context from an inbound bus message. */\n  static extractFromMessage(msg: InboundMessage): SessionContext {\n    const metadata = msg.metadata || {};\n    return {\n      sessionKey: (metadata.sessionKey as string) || `${msg.channel}:${msg.chat_id}`,\n      channel: msg.channel,\n      chatId: msg.chat_id,\n      senderId: (metadata.senderId as string) || '',\n      isGroup: (metadata.isGroup as boolean) || false,\n      model: metadata.model as string | undefined,\n      metadata,\n    };\n  }\n\n  /** Create a clone of the current context with optional overrides. */\n  cloneContext(overrides?: Partial<SessionContext>): SessionContext | null {\n    const current = this.getContext();\n    if (!current) return null;\n    return { ...current, ...overrides };\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AA+BA,IAAa,wBAAb,MAAmC;CACjC,MAAuB,IAAI,mBAAmC;;;;;;CAO9D,MAAM,QAAW,KAAqB,IAAkC;AACtE,SAAO,KAAK,IAAI,IAAI,KAAK,GAAG;;;;;;;;;CAU9B,MAAM,KAA2B;AAC/B,OAAK,IAAI,UAAU,IAAI;;;CAIzB,aAAoC;AAClC,SAAO,KAAK,IAAI,UAAU,IAAI;;CAGhC,aAAsB;AACpB,SAAO,KAAK,IAAI,UAAU,KAAK,KAAA;;;CAIjC,OAAO,mBAAmB,KAAqC;EAC7D,MAAM,WAAW,IAAI,YAAY,EAAE;AACnC,SAAO;GACL,YAAa,SAAS,cAAyB,GAAG,IAAI,QAAQ,GAAG,IAAI;GACrE,SAAS,IAAI;GACb,QAAQ,IAAI;GACZ,UAAW,SAAS,YAAuB;GAC3C,SAAU,SAAS,WAAuB;GAC1C,OAAO,SAAS;GAChB;GACD;;;CAIH,aAAa,WAA4D;EACvE,MAAM,UAAU,KAAK,YAAY;AACjC,MAAI,CAAC,QAAS,QAAO;AACrB,SAAO;GAAE,GAAG;GAAS,GAAG;GAAW"}

package/dist/src/agent/session/session-hydrator.d.ts

@@ -0,0 +1,42 @@
+/**
+ * SessionHydrator — read persisted per-session config and push it into the
+ * in-memory runtime (AgentManager + ModelManager).
+ *
+ * These three operations were three sibling private methods on `AgentService`
+ * with subtly different signatures. They are the mirror image of
+ * {@link SessionConfigService} — the latter writes user choices into the
+ * config store, this hydrator reads them back out before a turn runs.
+ *
+ *   - `workspace()`  — apply persisted `workingDirectoryOverride` to AgentManager
+ *                       and ensure the directory exists on disk
+ *   - `model()`      — apply persisted `modelOverride` via ModelManager
+ *   - `thinking()`   — resolve effective thinking level (request override >
+ *                       per-session override > agent default) and apply
+ */
+import type { Config } from '../../config/schema.js';
+import { type SessionConfigStore } from '../../session/index.js';
+import type { AgentInstanceGateway } from '../agent-instance-gateway.js';
+import type { ModelManager } from '../models/index.js';
+export interface SessionHydratorOptions {
+    sessionConfigStore: SessionConfigStore;
+    agentManager: AgentInstanceGateway;
+    modelManager: ModelManager;
+    /** Effective config snapshot accessor (honours runtime overrides). */
+    getConfig: () => Config | undefined;
+}
+export declare class SessionHydrator {
+    private readonly opts;
+    constructor(opts: SessionHydratorOptions);
+    /**
+     * Load persisted workingDirectory override into AgentManager and `mkdir -p`
+     * the effective workspace path. Safe to call before `getOrCreateAgent`.
+     */
+    workspace(sessionKey: string): Promise<void>;
+    /** Apply persisted `modelOverride` to ModelManager (no-op when none stored). */
+    model(sessionKey: string): Promise<void>;
+    /**
+     * Resolve the effective thinking level (request override > per-session
+     * override > agent default) and apply it to the live agent instance.
+     */
+    thinking(sessionKey: string, requestOverride?: string | null): Promise<void>;
+}

package/dist/src/agent/session/session-hydrator.js

@@ -0,0 +1,66 @@
+import { createLogger } from "../../utils/logger/index.js";
+import { init_logger } from "../../utils/logger.js";
+import { resolveEffectiveThinkingLevel } from "../../session/thinking-resolve.js";
+import { effectiveWorkspacePathForSession, normalizeWorkingDirectoryInput } from "../../session/session-workspace.js";
+import "../../session/index.js";
+import { mkdir } from "node:fs/promises";
+//#region src/agent/session/session-hydrator.ts
+/**
+* SessionHydrator — read persisted per-session config and push it into the
+* in-memory runtime (AgentManager + ModelManager).
+*
+* These three operations were three sibling private methods on `AgentService`
+* with subtly different signatures. They are the mirror image of
+* {@link SessionConfigService} — the latter writes user choices into the
+* config store, this hydrator reads them back out before a turn runs.
+*
+*   - `workspace()`  — apply persisted `workingDirectoryOverride` to AgentManager
+*                       and ensure the directory exists on disk
+*   - `model()`      — apply persisted `modelOverride` via ModelManager
+*   - `thinking()`   — resolve effective thinking level (request override >
+*                       per-session override > agent default) and apply
+*/
+init_logger();
+const log = createLogger("SessionHydrator");
+var SessionHydrator = class {
+	opts;
+	constructor(opts) {
+		this.opts = opts;
+	}
+	/**
+	* Load persisted workingDirectory override into AgentManager and `mkdir -p`
+	* the effective workspace path. Safe to call before `getOrCreateAgent`.
+	*/
+	async workspace(sessionKey) {
+		const cfg = this.opts.getConfig();
+		if (!cfg) return;
+		const loaded = await this.opts.sessionConfigStore.get(sessionKey);
+		if (loaded?.workingDirectoryOverride?.trim()) {
+			const wdStored = normalizeWorkingDirectoryInput(loaded.workingDirectoryOverride);
+			if (wdStored.ok) this.opts.agentManager.setSessionWorkspaceOverride(sessionKey, wdStored.path);
+			else {
+				log.warn({ sessionKey }, "Invalid stored workingDirectoryOverride; ignoring");
+				this.opts.agentManager.setSessionWorkspaceOverride(sessionKey, null);
+			}
+		} else this.opts.agentManager.setSessionWorkspaceOverride(sessionKey, null);
+		await mkdir(effectiveWorkspacePathForSession(cfg, sessionKey, loaded), { recursive: true });
+	}
+	/** Apply persisted `modelOverride` to ModelManager (no-op when none stored). */
+	async model(sessionKey) {
+		const cfg = await this.opts.sessionConfigStore.get(sessionKey);
+		if (cfg?.modelOverride) await this.opts.modelManager.switchModelForSession(sessionKey, cfg.modelOverride);
+	}
+	/**
+	* Resolve the effective thinking level (request override > per-session
+	* override > agent default) and apply it to the live agent instance.
+	*/
+	async thinking(sessionKey, requestOverride) {
+		const def = this.opts.getConfig()?.agents?.defaults?.thinkingDefault;
+		const level = await resolveEffectiveThinkingLevel(this.opts.sessionConfigStore, sessionKey, requestOverride, def);
+		this.opts.agentManager.setThinkingLevel(sessionKey, level);
+	}
+};
+//#endregion
+export { SessionHydrator };
+
+//# sourceMappingURL=session-hydrator.js.map

package/dist/src/agent/session/session-hydrator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-hydrator.js","names":[],"sources":["../../../../src/agent/session/session-hydrator.ts"],"sourcesContent":["/**\n * SessionHydrator — read persisted per-session config and push it into the\n * in-memory runtime (AgentManager + ModelManager).\n *\n * These three operations were three sibling private methods on `AgentService`\n * with subtly different signatures. They are the mirror image of\n * {@link SessionConfigService} — the latter writes user choices into the\n * config store, this hydrator reads them back out before a turn runs.\n *\n *   - `workspace()`  — apply persisted `workingDirectoryOverride` to AgentManager\n *                       and ensure the directory exists on disk\n *   - `model()`      — apply persisted `modelOverride` via ModelManager\n *   - `thinking()`   — resolve effective thinking level (request override >\n *                       per-session override > agent default) and apply\n */\n\nimport { mkdir } from 'node:fs/promises';\n\nimport type { Config } from '../../config/schema.js';\nimport {\n  effectiveWorkspacePathForSession,\n  normalizeWorkingDirectoryInput,\n  resolveEffectiveThinkingLevel,\n  type SessionConfigStore,\n} from '../../session/index.js';\nimport type { AgentInstanceGateway } from '../agent-instance-gateway.js';\nimport type { ModelManager } from '../models/index.js';\nimport { createLogger } from '../../utils/logger.js';\n\nconst log = createLogger('SessionHydrator');\n\nexport interface SessionHydratorOptions {\n  sessionConfigStore: SessionConfigStore;\n  agentManager: AgentInstanceGateway;\n  modelManager: ModelManager;\n  /** Effective config snapshot accessor (honours runtime overrides). */\n  getConfig: () => Config | undefined;\n}\n\nexport class SessionHydrator {\n  private readonly opts: SessionHydratorOptions;\n\n  constructor(opts: SessionHydratorOptions) {\n    this.opts = opts;\n  }\n\n  /**\n   * Load persisted workingDirectory override into AgentManager and `mkdir -p`\n   * the effective workspace path. Safe to call before `getOrCreateAgent`.\n   */\n  async workspace(sessionKey: string): Promise<void> {\n    const cfg = this.opts.getConfig();\n    if (!cfg) {\n      return;\n    }\n    const loaded = await this.opts.sessionConfigStore.get(sessionKey);\n    if (loaded?.workingDirectoryOverride?.trim()) {\n      const wdStored = normalizeWorkingDirectoryInput(loaded.workingDirectoryOverride);\n      if (wdStored.ok) {\n        this.opts.agentManager.setSessionWorkspaceOverride(sessionKey, wdStored.path);\n      } else {\n        log.warn({ sessionKey }, 'Invalid stored workingDirectoryOverride; ignoring');\n        this.opts.agentManager.setSessionWorkspaceOverride(sessionKey, null);\n      }\n    } else {\n      this.opts.agentManager.setSessionWorkspaceOverride(sessionKey, null);\n    }\n    const effective = effectiveWorkspacePathForSession(cfg, sessionKey, loaded);\n    await mkdir(effective, { recursive: true });\n  }\n\n  /** Apply persisted `modelOverride` to ModelManager (no-op when none stored). */\n  async model(sessionKey: string): Promise<void> {\n    const cfg = await this.opts.sessionConfigStore.get(sessionKey);\n    if (cfg?.modelOverride) {\n      await this.opts.modelManager.switchModelForSession(sessionKey, cfg.modelOverride);\n    }\n  }\n\n  /**\n   * Resolve the effective thinking level (request override > per-session\n   * override > agent default) and apply it to the live agent instance.\n   */\n  async thinking(sessionKey: string, requestOverride?: string | null): Promise<void> {\n    const def = this.opts.getConfig()?.agents?.defaults?.thinkingDefault;\n    const level = await resolveEffectiveThinkingLevel(\n      this.opts.sessionConfigStore,\n      sessionKey,\n      requestOverride,\n      def,\n    );\n    this.opts.agentManager.setThinkingLevel(sessionKey, level);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;aA2BqD;AAErD,MAAM,MAAM,aAAa,kBAAkB;AAU3C,IAAa,kBAAb,MAA6B;CAC3B;CAEA,YAAY,MAA8B;AACxC,OAAK,OAAO;;;;;;CAOd,MAAM,UAAU,YAAmC;EACjD,MAAM,MAAM,KAAK,KAAK,WAAW;AACjC,MAAI,CAAC,IACH;EAEF,MAAM,SAAS,MAAM,KAAK,KAAK,mBAAmB,IAAI,WAAW;AACjE,MAAI,QAAQ,0BAA0B,MAAM,EAAE;GAC5C,MAAM,WAAW,+BAA+B,OAAO,yBAAyB;AAChF,OAAI,SAAS,GACX,MAAK,KAAK,aAAa,4BAA4B,YAAY,SAAS,KAAK;QACxE;AACL,QAAI,KAAK,EAAE,YAAY,EAAE,oDAAoD;AAC7E,SAAK,KAAK,aAAa,4BAA4B,YAAY,KAAK;;QAGtE,MAAK,KAAK,aAAa,4BAA4B,YAAY,KAAK;AAGtE,QAAM,MADY,iCAAiC,KAAK,YAAY,OAC/C,EAAE,EAAE,WAAW,MAAM,CAAC;;;CAI7C,MAAM,MAAM,YAAmC;EAC7C,MAAM,MAAM,MAAM,KAAK,KAAK,mBAAmB,IAAI,WAAW;AAC9D,MAAI,KAAK,cACP,OAAM,KAAK,KAAK,aAAa,sBAAsB,YAAY,IAAI,cAAc;;;;;;CAQrF,MAAM,SAAS,YAAoB,iBAAgD;EACjF,MAAM,MAAM,KAAK,KAAK,WAAW,EAAE,QAAQ,UAAU;EACrD,MAAM,QAAQ,MAAM,8BAClB,KAAK,KAAK,oBACV,YACA,iBACA,IACD;AACD,OAAK,KAAK,aAAa,iBAAiB,YAAY,MAAM"}

package/dist/src/agent/session/session-inspector.d.ts

@@ -0,0 +1,80 @@
+/**
+ * SessionInspector — read-only / introspection-oriented operations on a session.
+ *
+ * Owns the five methods previously scattered across `AgentService` that all
+ * compute a "summary view" of one session:
+ *   - `compact` (manual user-triggered compaction)
+ *   - `btwQuery` (one-shot LLM answer with transcript as background)
+ *   - `report` (Markdown / JSON `/context` summary)
+ *   - `agentConfig` (resolved thinking + model + workspace for the Web UI)
+ *   - `contextUsage` (rough token budget vs estimated transcript)
+ *
+ * The shared helper `computeStats` keeps the three callsites that need
+ * `getWindowStats` / `getCompactionStats` / `estimateTokenUsage` in lockstep.
+ */
+import type { AgentMessage } from '@earendil-works/pi-agent-core';
+import type { ThinkingLevel } from '@earendil-works/pi-agent-core';
+import type { Config } from '../../config/schema.js';
+import { type SessionConfigStore } from '../../session/index.js';
+import type { SessionStore } from '../../session/store.js';
+import type { CompactionResult } from '../memory/compaction.js';
+import type { ModelManager } from '../models/index.js';
+import type { AgentInstanceGateway } from '../agent-instance-gateway.js';
+import type { ReasoningLevel } from '../transcript/thinking-types.js';
+import type { SessionHydrator } from './session-hydrator.js';
+export interface SessionInspectorOptions {
+    sessionStore: SessionStore;
+    sessionConfigStore: SessionConfigStore;
+    modelManager: ModelManager;
+    agentManager: AgentInstanceGateway;
+    sessionHydrator: SessionHydrator;
+    /** Effective config snapshot accessor (honours runtime overrides). */
+    getConfig: () => Config | undefined;
+    /**
+     * Nominal context window the session is budgeted against. Currently derived
+     * from `agents.defaults.maxTokens * 4`, defaulting to 128k.
+     */
+    getContextWindow: () => number;
+}
+export interface SessionContextUsage {
+    estimatedTokens: number;
+    contextWindow: number;
+    usagePercent: number | null;
+}
+export interface SessionAgentConfigView {
+    thinkingLevel: ThinkingLevel;
+    model: string;
+    reasoningLevel: ReasoningLevel;
+    effectiveWorkspacePath: string;
+    workingDirectoryLocked: boolean;
+}
+export declare class SessionInspector {
+    private readonly opts;
+    constructor(opts: SessionInspectorOptions);
+    /**
+     * Manual compaction triggered by a user / API. Always forces a compaction
+     * pass (`force: true` by default) and evicts the in-memory agent so the
+     * next turn reloads from the compacted transcript.
+     */
+    compact(sessionKey: string, options?: {
+        instructions?: string;
+        force?: boolean;
+    }): Promise<CompactionResult>;
+    /** One-shot LLM answer for `/btw`: transcript as background, not persisted. */
+    btwQuery(sessionKey: string, question: string): Promise<{
+        text: string;
+        error?: string;
+    }>;
+    /** Cheap stats used by both the report and other callers. */
+    stats(sessionKey: string, messages: AgentMessage[]): {
+        windowStats: ReturnType<SessionStore['getWindowStats']>;
+        compactionStats: ReturnType<SessionStore['getCompactionStats']>;
+        tokenEstimate: ReturnType<SessionStore['estimateTokenUsage']>;
+    };
+    /** Rough context usage for TUI footer (estimated tokens vs nominal budget). */
+    contextUsage(sessionKey: string): Promise<SessionContextUsage>;
+    /** Markdown or JSON summary for `/context`. */
+    report(sessionKey: string, mode: 'list' | 'detail' | 'json'): Promise<string>;
+    /** Resolved thinking / model / workspace for the Web UI. */
+    agentConfig(sessionKey: string): Promise<SessionAgentConfigView>;
+}

package/dist/src/agent/session/session-inspector.js

@@ -0,0 +1,119 @@
+import { createLogger } from "../../utils/logger/index.js";
+import { init_logger } from "../../utils/logger.js";
+import { resolveEffectiveAgentProfileForSession } from "../../config/agent-profile.js";
+import { resolveEffectiveReasoningLevel, resolveEffectiveThinkingLevel } from "../../session/thinking-resolve.js";
+import { effectiveWorkspacePathForSession } from "../../session/session-workspace.js";
+import "../../session/index.js";
+import { runBtwQuery } from "../service/btw-query.js";
+import { formatSessionContextReport } from "../service/session-context-report.js";
+//#region src/agent/session/session-inspector.ts
+init_logger();
+const log = createLogger("SessionInspector");
+var SessionInspector = class {
+	opts;
+	constructor(opts) {
+		this.opts = opts;
+	}
+	/**
+	* Manual compaction triggered by a user / API. Always forces a compaction
+	* pass (`force: true` by default) and evicts the in-memory agent so the
+	* next turn reloads from the compacted transcript.
+	*/
+	async compact(sessionKey, options) {
+		const messages = await this.opts.sessionStore.load(sessionKey);
+		const contextWindow = this.opts.getContextWindow();
+		const result = await this.opts.sessionStore.compact(sessionKey, messages, contextWindow, options?.instructions, options?.force ?? true);
+		if (result.compacted) this.opts.agentManager.removeAgent(sessionKey);
+		log.info({
+			sessionKey,
+			result
+		}, "Manual compaction complete");
+		return result;
+	}
+	/** One-shot LLM answer for `/btw`: transcript as background, not persisted. */
+	btwQuery(sessionKey, question) {
+		return runBtwQuery({
+			sessionKey,
+			question,
+			sessionStore: this.opts.sessionStore,
+			modelForSession: this.opts.modelManager.getModelForSession(sessionKey),
+			log
+		});
+	}
+	/** Cheap stats used by both the report and other callers. */
+	stats(sessionKey, messages) {
+		return {
+			windowStats: this.opts.sessionStore.getWindowStats(messages),
+			compactionStats: this.opts.sessionStore.getCompactionStats(sessionKey),
+			tokenEstimate: this.opts.sessionStore.estimateTokenUsage(sessionKey, messages)
+		};
+	}
+	/** Rough context usage for TUI footer (estimated tokens vs nominal budget). */
+	async contextUsage(sessionKey) {
+		const messages = await this.opts.sessionStore.load(sessionKey);
+		const contextWindow = this.opts.getContextWindow();
+		const estimatedTokens = await this.opts.sessionStore.estimateTokenUsage(sessionKey, messages);
+		return {
+			estimatedTokens,
+			contextWindow,
+			usagePercent: contextWindow > 0 ? Math.min(100, Math.round(estimatedTokens / contextWindow * 100)) : null
+		};
+	}
+	/** Markdown or JSON summary for `/context`. */
+	async report(sessionKey, mode) {
+		const cfg = this.opts.getConfig();
+		if (!cfg) throw new Error("SessionInspector requires a config snapshot to render report");
+		const messages = await this.opts.sessionStore.load(sessionKey);
+		const cw = this.opts.getContextWindow();
+		const computed = this.stats(sessionKey, messages);
+		const model = this.opts.modelManager.getModelForSession(sessionKey);
+		const workspace = effectiveWorkspacePathForSession(cfg, sessionKey, await this.opts.sessionConfigStore.get(sessionKey));
+		const estTokens = await this.opts.sessionStore.estimateTokenUsage(sessionKey, messages);
+		const profile = resolveEffectiveAgentProfileForSession(cfg, sessionKey);
+		const defaults = cfg.agents?.defaults;
+		const compaction = defaults?.compaction;
+		const tools = defaults?.tools;
+		const toolsSummary = tools && typeof tools === "object" ? Object.entries(tools).filter(([, v]) => v === true).map(([k]) => k).slice(0, 16).join(", ") || "(none explicitly true)" : "(see agents.defaults.tools in config)";
+		return formatSessionContextReport({
+			sessionKey,
+			mode,
+			model,
+			workspacePath: workspace,
+			agentId: profile.agentId,
+			messageCount: messages.length,
+			contextWindowNominal: cw,
+			estimatedTranscriptTokens: estTokens,
+			thinkingDefault: defaults?.thinkingDefault,
+			reasoningDefault: defaults?.reasoningDefault,
+			verboseDefault: defaults?.verboseDefault,
+			compaction,
+			toolsFlagsSummary: toolsSummary,
+			windowStats: computed.windowStats,
+			compactionRunStats: computed.compactionStats
+		});
+	}
+	/** Resolved thinking / model / workspace for the Web UI. */
+	async agentConfig(sessionKey) {
+		await this.opts.sessionHydrator.model(sessionKey);
+		const cfg = this.opts.getConfig();
+		if (!cfg) throw new Error("SessionInspector requires a config snapshot to resolve agent config");
+		const sc = await this.opts.sessionConfigStore.get(sessionKey);
+		const profileModelRef = resolveEffectiveAgentProfileForSession(cfg, sessionKey).primaryModelRef?.trim();
+		if (profileModelRef) this.opts.modelManager.setSessionProfileDefault(sessionKey, profileModelRef);
+		const defThink = cfg.agents?.defaults?.thinkingDefault ?? "medium";
+		const level = await resolveEffectiveThinkingLevel(this.opts.sessionConfigStore, sessionKey, null, defThink);
+		const defReason = cfg.agents?.defaults?.reasoningDefault ?? "stream";
+		const reasoningLevel = await resolveEffectiveReasoningLevel(this.opts.sessionConfigStore, sessionKey, defReason);
+		return {
+			thinkingLevel: level,
+			model: this.opts.modelManager.getModelForSession(sessionKey),
+			reasoningLevel,
+			effectiveWorkspacePath: effectiveWorkspacePathForSession(cfg, sessionKey, sc),
+			workingDirectoryLocked: Boolean(sc?.workingDirectoryOverride?.trim())
+		};
+	}
+};
+//#endregion
+export { SessionInspector };
+
+//# sourceMappingURL=session-inspector.js.map

package/dist/src/agent/session/session-inspector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-inspector.js","names":[],"sources":["../../../../src/agent/session/session-inspector.ts"],"sourcesContent":["/**\n * SessionInspector — read-only / introspection-oriented operations on a session.\n *\n * Owns the five methods previously scattered across `AgentService` that all\n * compute a \"summary view\" of one session:\n *   - `compact` (manual user-triggered compaction)\n *   - `btwQuery` (one-shot LLM answer with transcript as background)\n *   - `report` (Markdown / JSON `/context` summary)\n *   - `agentConfig` (resolved thinking + model + workspace for the Web UI)\n *   - `contextUsage` (rough token budget vs estimated transcript)\n *\n * The shared helper `computeStats` keeps the three callsites that need\n * `getWindowStats` / `getCompactionStats` / `estimateTokenUsage` in lockstep.\n */\n\nimport type { AgentMessage } from '@earendil-works/pi-agent-core';\nimport type { ThinkingLevel } from '@earendil-works/pi-agent-core';\n\nimport type { Config } from '../../config/schema.js';\nimport { resolveEffectiveAgentProfileForSession } from '../../config/agent-profile.js';\nimport {\n  effectiveWorkspacePathForSession,\n  resolveEffectiveReasoningLevel,\n  resolveEffectiveThinkingLevel,\n  type SessionConfigStore,\n} from '../../session/index.js';\nimport type { SessionStore } from '../../session/store.js';\nimport type { CompactionResult } from '../memory/compaction.js';\nimport type { ModelManager } from '../models/index.js';\nimport type { AgentInstanceGateway } from '../agent-instance-gateway.js';\nimport { runBtwQuery } from '../service/btw-query.js';\nimport { formatSessionContextReport } from '../service/session-context-report.js';\nimport type { ReasoningLevel } from '../transcript/thinking-types.js';\nimport { createLogger } from '../../utils/logger.js';\nimport type { SessionHydrator } from './session-hydrator.js';\n\nconst log = createLogger('SessionInspector');\n\nexport interface SessionInspectorOptions {\n  sessionStore: SessionStore;\n  sessionConfigStore: SessionConfigStore;\n  modelManager: ModelManager;\n  agentManager: AgentInstanceGateway;\n  sessionHydrator: SessionHydrator;\n  /** Effective config snapshot accessor (honours runtime overrides). */\n  getConfig: () => Config | undefined;\n  /**\n   * Nominal context window the session is budgeted against. Currently derived\n   * from `agents.defaults.maxTokens * 4`, defaulting to 128k.\n   */\n  getContextWindow: () => number;\n}\n\nexport interface SessionContextUsage {\n  estimatedTokens: number;\n  contextWindow: number;\n  usagePercent: number | null;\n}\n\nexport interface SessionAgentConfigView {\n  thinkingLevel: ThinkingLevel;\n  model: string;\n  reasoningLevel: ReasoningLevel;\n  effectiveWorkspacePath: string;\n  workingDirectoryLocked: boolean;\n}\n\nexport class SessionInspector {\n  private readonly opts: SessionInspectorOptions;\n\n  constructor(opts: SessionInspectorOptions) {\n    this.opts = opts;\n  }\n\n  /**\n   * Manual compaction triggered by a user / API. Always forces a compaction\n   * pass (`force: true` by default) and evicts the in-memory agent so the\n   * next turn reloads from the compacted transcript.\n   */\n  async compact(\n    sessionKey: string,\n    options?: { instructions?: string; force?: boolean },\n  ): Promise<CompactionResult> {\n    const messages = await this.opts.sessionStore.load(sessionKey);\n    const contextWindow = this.opts.getContextWindow();\n    const result = await this.opts.sessionStore.compact(\n      sessionKey,\n      messages,\n      contextWindow,\n      options?.instructions,\n      options?.force ?? true,\n    );\n    if (result.compacted) {\n      this.opts.agentManager.removeAgent(sessionKey);\n    }\n    log.info({ sessionKey, result }, 'Manual compaction complete');\n    return result;\n  }\n\n  /** One-shot LLM answer for `/btw`: transcript as background, not persisted. */\n  btwQuery(sessionKey: string, question: string): Promise<{ text: string; error?: string }> {\n    return runBtwQuery({\n      sessionKey,\n      question,\n      sessionStore: this.opts.sessionStore,\n      modelForSession: this.opts.modelManager.getModelForSession(sessionKey),\n      log,\n    });\n  }\n\n  /** Cheap stats used by both the report and other callers. */\n  stats(sessionKey: string, messages: AgentMessage[]): {\n    windowStats: ReturnType<SessionStore['getWindowStats']>;\n    compactionStats: ReturnType<SessionStore['getCompactionStats']>;\n    tokenEstimate: ReturnType<SessionStore['estimateTokenUsage']>;\n  } {\n    return {\n      windowStats: this.opts.sessionStore.getWindowStats(messages),\n      compactionStats: this.opts.sessionStore.getCompactionStats(sessionKey),\n      tokenEstimate: this.opts.sessionStore.estimateTokenUsage(sessionKey, messages),\n    };\n  }\n\n  /** Rough context usage for TUI footer (estimated tokens vs nominal budget). */\n  async contextUsage(sessionKey: string): Promise<SessionContextUsage> {\n    const messages = await this.opts.sessionStore.load(sessionKey);\n    const contextWindow = this.opts.getContextWindow();\n    const estimatedTokens = await this.opts.sessionStore.estimateTokenUsage(sessionKey, messages);\n    const usagePercent =\n      contextWindow > 0 ? Math.min(100, Math.round((estimatedTokens / contextWindow) * 100)) : null;\n    return { estimatedTokens, contextWindow, usagePercent };\n  }\n\n  /** Markdown or JSON summary for `/context`. */\n  async report(sessionKey: string, mode: 'list' | 'detail' | 'json'): Promise<string> {\n    const cfg = this.opts.getConfig();\n    if (!cfg) {\n      throw new Error('SessionInspector requires a config snapshot to render report');\n    }\n    const messages = await this.opts.sessionStore.load(sessionKey);\n    const cw = this.opts.getContextWindow();\n    const computed = this.stats(sessionKey, messages);\n    const model = this.opts.modelManager.getModelForSession(sessionKey);\n    const sc = await this.opts.sessionConfigStore.get(sessionKey);\n    const workspace = effectiveWorkspacePathForSession(cfg, sessionKey, sc);\n    const estTokens = await this.opts.sessionStore.estimateTokenUsage(sessionKey, messages);\n    const profile = resolveEffectiveAgentProfileForSession(cfg, sessionKey);\n    const defaults = cfg.agents?.defaults;\n    const compaction = defaults?.compaction;\n    const tools = defaults?.tools;\n\n    const toolsSummary =\n      tools && typeof tools === 'object'\n        ? Object.entries(tools as Record<string, unknown>)\n            .filter(([, v]) => v === true)\n            .map(([k]) => k)\n            .slice(0, 16)\n            .join(', ') || '(none explicitly true)'\n        : '(see agents.defaults.tools in config)';\n\n    return formatSessionContextReport({\n      sessionKey,\n      mode,\n      model,\n      workspacePath: workspace,\n      agentId: profile.agentId,\n      messageCount: messages.length,\n      contextWindowNominal: cw,\n      estimatedTranscriptTokens: estTokens,\n      thinkingDefault: defaults?.thinkingDefault,\n      reasoningDefault: defaults?.reasoningDefault,\n      verboseDefault: defaults?.verboseDefault,\n      compaction,\n      toolsFlagsSummary: toolsSummary,\n      windowStats: computed.windowStats,\n      compactionRunStats: computed.compactionStats,\n    });\n  }\n\n  /** Resolved thinking / model / workspace for the Web UI. */\n  async agentConfig(sessionKey: string): Promise<SessionAgentConfigView> {\n    await this.opts.sessionHydrator.model(sessionKey);\n    const cfg = this.opts.getConfig();\n    if (!cfg) {\n      throw new Error('SessionInspector requires a config snapshot to resolve agent config');\n    }\n    const sc = await this.opts.sessionConfigStore.get(sessionKey);\n\n    // Ensure model display matches the effective agent profile even before an Agent instance exists.\n    // Otherwise `ModelManager.getModelForSession()` falls back to the global default until the first turn creates the agent.\n    const profile = resolveEffectiveAgentProfileForSession(cfg, sessionKey);\n    const profileModelRef = profile.primaryModelRef?.trim();\n    if (profileModelRef) {\n      this.opts.modelManager.setSessionProfileDefault(sessionKey, profileModelRef);\n    }\n\n    const defThink = cfg.agents?.defaults?.thinkingDefault ?? 'medium';\n    const level = await resolveEffectiveThinkingLevel(this.opts.sessionConfigStore, sessionKey, null, defThink);\n    const defReason = (cfg.agents?.defaults?.reasoningDefault ?? 'stream') as ReasoningLevel;\n    const reasoningLevel = await resolveEffectiveReasoningLevel(this.opts.sessionConfigStore, sessionKey, defReason);\n    const model = this.opts.modelManager.getModelForSession(sessionKey);\n    return {\n      thinkingLevel: level,\n      model,\n      reasoningLevel,\n      effectiveWorkspacePath: effectiveWorkspacePathForSession(cfg, sessionKey, sc),\n      workingDirectoryLocked: Boolean(sc?.workingDirectoryOverride?.trim()),\n    };\n  }\n}\n"],"mappings":"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"}

package/dist/src/agent/session/session-state-bag.d.ts

@@ -0,0 +1,83 @@
+/**
+ * SessionStateBag — typed container for the per-session state previously held
+ * as private fields on `AgentService` (six `Map<sessionKey, …>` instances with
+ * no shared cleanup path).
+ *
+ * Goals:
+ * - Single `disposeSession(sessionKey)` entry that clears every slot for a key
+ *   (and runs the event unsubscriber, which was easy to forget previously).
+ * - Optional TTL sweep for slots whose lifecycle is not bound to an explicit
+ *   register/unregister pair, so long-running Gateways do not accumulate stale
+ *   per-session entries from disconnected webchat clients or finished turns.
+ * - Hard upper bound for the same TTL'd slots to bound worst-case memory.
+ *
+ * Slots whose lifetime is fully owned by explicit lifecycle calls
+ * (`inboundTurnDepth`, `directStreamOutcome`, `embeddedStreamText`,
+ * `sessionEventUnsubscribers`) are still cleared via `disposeSession`, but they
+ * are NOT subject to TTL — sweeping them would race with their owners.
+ */
+export type WebchatSsePublisher = (event: {
+    type: string;
+    [key: string]: unknown;
+}) => void;
+export interface PersistentGoalStreamOutcome {
+    skipPersistentGoalPostTurn: boolean;
+}
+export interface SessionStateBagOptions {
+    /** Idle TTL for TTL-managed slots. Defaults to 1 hour. Set to 0 to disable sweeping. */
+    ttlMs?: number;
+    /** Sweep cadence. Defaults to 10 minutes. */
+    sweepIntervalMs?: number;
+    /** Hard upper bound on entries for TTL-managed slots. Defaults to 5000. */
+    maxEntries?: number;
+    /** Inject a clock for tests. */
+    now?: () => number;
+}
+export declare class SessionStateBag {
+    /** Webchat SSE publisher (register/unregister + TTL fallback). */
+    private readonly webchatPublishers;
+    /** Last assistant plain text (TTL + LRU). */
+    private readonly lastAssistantText;
+    /** Stream text for the in-flight embedded turn (managed by turn). */
+    private readonly embeddedStreamText;
+    /** Persistent-goal stream outcome (take-and-delete). */
+    private readonly directStreamOutcome;
+    /** Concurrent inbound turn depth (counter). */
+    private readonly inboundTurnDepth;
+    /** Agent-event subscription tear-downs (run on dispose). */
+    private readonly sessionEventUnsubscribers;
+    private readonly ttlMs;
+    private readonly maxEntries;
+    private readonly now;
+    private readonly sweepTimer;
+    constructor(opts?: SessionStateBagOptions);
+    registerWebchatPublisher(sessionKey: string, publisher: WebchatSsePublisher): void;
+    unregisterWebchatPublisher(sessionKey: string): void;
+    getWebchatPublisher(sessionKey: string): WebchatSsePublisher | undefined;
+    setLastAssistantText(sessionKey: string, text: string): void;
+    getLastAssistantText(sessionKey: string): string | undefined;
+    appendEmbeddedStreamText(sessionKey: string, chunk: string): string;
+    clearEmbeddedStreamText(sessionKey: string): void;
+    recordPersistentGoalStreamOutcome(sessionKey: string, outcome: PersistentGoalStreamOutcome): void;
+    takePersistentGoalStreamOutcome(sessionKey: string): PersistentGoalStreamOutcome | undefined;
+    beginInboundTurn(sessionKey: string): void;
+    endInboundTurn(sessionKey: string): void;
+    getInboundTurnDepth(sessionKey: string): number;
+    setSessionEventUnsubscriber(sessionKey: string, unsubscribe: () => void): void;
+    hasSessionEventUnsubscriber(sessionKey: string): boolean;
+    /** Clear every slot for `sessionKey`, invoking the unsubscriber if registered. */
+    disposeSession(sessionKey: string): void;
+    /** Tear down every session (process stop / hot reload). */
+    disposeAll(): void;
+    /** Test helper. */
+    size(): {
+        webchatPublishers: number;
+        lastAssistantText: number;
+        embeddedStreamText: number;
+        directStreamOutcome: number;
+        inboundTurnDepth: number;
+        sessionEventUnsubscribers: number;
+    };
+    private sweepStaleEntries;
+    private enforceCap;
+}