@adminforth/agent 2.6.0 → 2.7.1

package/dist/application/ports.d.ts

@@ -25,6 +25,7 @@ export type AgentModeCompletionAdapter = CompletionAdapter & {
  */
 export type LlmStreamInput = {
     completionAdapter: AgentModeCompletionAdapter;
+    systemPrompt: string;
     input: {
         messages: AgentMessage[];
     } | {

package/dist/application/runTurnUseCase.d.ts

@@ -60,6 +60,7 @@ export type RunTurnUseCaseDeps = {
 export declare class RunTurnUseCase {
     private readonly deps;
     private readonly pendingInterrupts;
+    private readonly lastDetectedLanguage;
     constructor(deps: RunTurnUseCaseDeps);
     private resolveMode;
     private buildContext;
@@ -69,15 +70,17 @@ export declare class RunTurnUseCase {
      * MemorySaver the in-process cache is authoritative (single process, cannot be stale).
      */
     private resolvePendingInterrupts;
+    private requiresSessionOwnership;
     /** Verify the session exists and belongs to the requesting admin user. */
     private assertSessionOwnership;
     /**
-     * Prepare an edit/branch turn: validate ownership, resolve the fork checkpoint from
-     * the previous turn, truncate the conversation after the edited turn, and reuse the
-     * edited turn's id for the regenerated response.
+     * Prepare an edit/branch turn: resolve the fork checkpoint from the previous turn,
+     * truncate the conversation after the edited turn, and reuse the edited turn's id
+     * for the regenerated response. Ownership is already asserted by `prepareTurn`.
      */
     private prepareEditTurn;
     private prepareTurn;
+    private resolveUserLanguage;
     private buildMessages;
     private handleInterrupt;
     private runAgentTurn;

package/dist/application/runTurnUseCase.js

@@ -17,7 +17,6 @@ var __asyncValues = (this && this.__asyncValues) || function (o) {
 import { logger, Filters } from "adminforth";
 import { randomUUID } from "crypto";
 import { VegaLiteStreamBuffer } from "../domain/vegaLiteStreamBuffer.js";
-import { buildAgentTurnSystemPrompt } from "../domain/systemPrompt.js";
 import { getErrorMessage, isAbortError } from "../shared/errors.js";
 function getApprovalDecision(input) {
     return "approvalDecision" in input
@@ -77,6 +76,7 @@ export class RunTurnUseCase {
     constructor(deps) {
         this.deps = deps;
         this.pendingInterrupts = new Map();
+        this.lastDetectedLanguage = new Map();
     }
     resolveMode(modeName) {
         var _a;
@@ -121,6 +121,9 @@ export class RunTurnUseCase {
             return (_a = this.pendingInterrupts.get(sessionId)) !== null && _a !== void 0 ? _a : [];
         });
     }
+    requiresSessionOwnership(input) {
+        return !input.chatSurface;
+    }
     /** Verify the session exists and belongs to the requesting admin user. */
     assertSessionOwnership(sessionId, adminUser) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -135,9 +138,9 @@ export class RunTurnUseCase {
         });
     }
     /**
-     * Prepare an edit/branch turn: validate ownership, resolve the fork checkpoint from
-     * the previous turn, truncate the conversation after the edited turn, and reuse the
-     * edited turn's id for the regenerated response.
+     * Prepare an edit/branch turn: resolve the fork checkpoint from the previous turn,
+     * truncate the conversation after the edited turn, and reuse the edited turn's id
+     * for the regenerated response. Ownership is already asserted by `prepareTurn`.
      */
     prepareEditTurn(input) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -147,7 +150,6 @@ export class RunTurnUseCase {
             if (!this.deps.turnCheckpointsEnabled) {
                 throw new Error("Edit/fork requires checkpointIdField to be configured on turnResource.");
             }
-            yield this.assertSessionOwnership(input.sessionId, input.adminUser);
             const agentTurns = yield this.deps.sessions.getAgentTurns(input.sessionId);
             const targetIndex = agentTurns.findIndex((turn) => turn.id === editTurnId);
             if (targetIndex === -1) {
@@ -175,6 +177,7 @@ export class RunTurnUseCase {
             // Editing supersedes any in-flight turn state for this session.
             this.deps.steerBuffer.clear(input.sessionId);
             this.pendingInterrupts.delete(input.sessionId);
+            this.lastDetectedLanguage.delete(input.sessionId);
             // Apply the edit + truncate (deletes later turns first, then rewrites the edited turn).
             yield this.deps.sessions.editTurnAndTruncateAfter({
                 sessionId: input.sessionId,
@@ -200,6 +203,11 @@ export class RunTurnUseCase {
             const mode = this.resolveMode(input.modeName);
             const approvalDecision = getApprovalDecision(input);
             const shouldResume = Boolean(approvalDecision);
+            console.log(`Preparing turn for session "${input.sessionId}" (resume=${shouldResume})`);
+            if (this.requiresSessionOwnership(input)) {
+                console.log(`Asserting session ownership for session "${input.sessionId}"`);
+                yield this.assertSessionOwnership(input.sessionId, input.adminUser);
+            }
             if (input.editTurnId && !shouldResume) {
                 return this.prepareEditTurn(input);
             }
@@ -239,9 +247,13 @@ export class RunTurnUseCase {
             };
         });
     }
-    buildMessages(prepared) {
+    resolveUserLanguage(prepared) {
         return __awaiter(this, void 0, void 0, function* () {
-            const userLanguage = yield this.deps.llm
+            var _a;
+            if (prepared.resume) {
+                return (_a = this.lastDetectedLanguage.get(prepared.sessionId)) !== null && _a !== void 0 ? _a : null;
+            }
+            const detected = yield this.deps.llm
                 .detectLanguage({
                 completionAdapter: prepared.mode.completionAdapter,
                 prompt: prepared.prompt,
@@ -255,20 +267,13 @@ export class RunTurnUseCase {
                 logger.warn(`Failed to detect user language: ${getErrorMessage(error)}`);
                 return null;
             });
-            const adminforth = this.deps.getAdminforth();
-            const systemPrompt = buildAgentTurnSystemPrompt({
-                agentSystemPrompt: yield this.deps.getAgentSystemPrompt(),
-                adminUser: prepared.context.adminUser,
-                usernameField: adminforth.config.auth.usernameField,
-                userLanguage,
-                chatSurface: prepared.context.chatSurface,
-            });
-            return [
-                { role: "system", content: systemPrompt },
-                { role: "user", content: prepared.prompt },
-            ];
+            this.lastDetectedLanguage.set(prepared.sessionId, detected);
+            return detected;
         });
     }
+    buildMessages(prepared) {
+        return [{ role: "user", content: prepared.prompt }];
+    }
     handleInterrupt(prepared, interrupt, descriptors) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b, _c;
@@ -290,6 +295,7 @@ export class RunTurnUseCase {
     runAgentTurn(prepared) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, e_1, _b, _c;
+            const userLanguage = yield this.resolveUserLanguage(prepared);
             const streamInput = prepared.resume
                 ? {
                     resume: buildResumeValue({
@@ -298,11 +304,12 @@ export class RunTurnUseCase {
                         prompt: prepared.prompt,
                     }),
                 }
-                : { messages: yield this.buildMessages(prepared) };
+                : { messages: this.buildMessages(prepared) };
             const stream = yield this.deps.llm.streamTurn({
                 completionAdapter: prepared.mode.completionAdapter,
+                systemPrompt: yield this.deps.getAgentSystemPrompt(),
                 input: streamInput,
-                context: prepared.context,
+                context: Object.assign(Object.assign({}, prepared.context), { userLanguage }),
                 observability: prepared.observability,
                 branchFromCheckpointId: prepared.branchFromCheckpointId,
             });
@@ -353,6 +360,9 @@ export class RunTurnUseCase {
                 // done and leftover (unconsumed) steers must not leak into the next turn.
                 if (!interrupted) {
                     this.deps.steerBuffer.clear(prepared.sessionId);
+                    // The detected language is only needed to bridge an interrupt -> resume; once
+                    // the turn is done the next one re-detects.
+                    this.lastDetectedLanguage.delete(prepared.sessionId);
                 }
                 if (!this.deps.hasPersistentCheckpointer && !interrupted) {
                     this.pendingInterrupts.delete(prepared.sessionId);

package/dist/domain/systemPrompt.d.ts

@@ -2,11 +2,10 @@ import type { AdminUser, IAdminForth } from "adminforth";
 import type { DetectedLanguage } from "./languageDetect.js";
 export declare const DEFAULT_AGENT_SYSTEM_PROMPT: string;
 export declare function appendCustomSystemPrompt(systemPrompt: string, customSystemPrompt?: string): string;
-export declare function buildAgentTurnSystemPrompt(input: {
-    agentSystemPrompt: string;
+export declare function buildDynamicSystemPrompt(input: {
     adminUser: AdminUser;
     usernameField: string;
-    userLanguage: DetectedLanguage | null;
+    userLanguage?: DetectedLanguage | null;
     chatSurface?: string;
 }): string;
 export declare function buildAgentSystemPrompt(adminforth: IAdminForth, hiddenResourceIds?: Iterable<string>): Promise<string>;

package/dist/domain/systemPrompt.js

@@ -51,14 +51,14 @@ function formatAdminUserPrompt(adminUser, usernameField) {
         "Use this admin user email when the user asks to send information to themselves, the current admin, or the logged-in user.",
     ].join("\n");
 }
-export function buildAgentTurnSystemPrompt(input) {
+export function buildDynamicSystemPrompt(input) {
+    var _a;
     return [
-        input.agentSystemPrompt,
         formatAdminUserPrompt(input.adminUser, input.usernameField),
         input.chatSurface
             ? `Current chat surface: ${input.chatSurface}. The user is not in the AdminForth web UI, so tools cannot move their browser. When navigate_user returns a link, send that link to the user.`
             : "",
-        formatLanguagePrompt(input.userLanguage),
+        formatLanguagePrompt((_a = input.userLanguage) !== null && _a !== void 0 ? _a : null),
     ].filter(Boolean).join("\n\n");
 }
 function formatResources(resources) {

package/dist/domain/turnTypes.d.ts

@@ -1,4 +1,5 @@
 import type { AdminUser, AudioAdapter } from "adminforth";
+import type { DetectedLanguage } from "./languageDetect.js";
 import type { CurrentPageContext } from "../tools/getUserLocation.js";
 import type { AgentEventEmitter } from "./agentEvents.js";
 /**
@@ -53,6 +54,7 @@ export type AgentTurnContext = {
     currentPage?: CurrentPageContext;
     chatSurface?: string;
     adminPublicOrigin?: string;
+    userLanguage?: DetectedLanguage | null;
 };
 export type AgentTurnObservability = {
     emit?: AgentEventEmitter;
@@ -76,12 +78,8 @@ export type HandleSpeechTurnInput = SpeechAgentTurnInput;
 export type HandleEditTurnInput = TextAgentTurnInput & {
     turnId: string;
 };
-/**
- * Provider-agnostic message passed from the application layer to the LLM port.
- * The infrastructure adapter maps it onto concrete LangChain messages.
- */
 export type AgentMessage = {
-    role: "system" | "user";
+    role: "user";
     content: string;
 };
 /**

package/dist/llm/agentContext.d.ts

@@ -4,6 +4,7 @@ import type { AgentEventEmitter } from "../domain/agentEvents.js";
 import type { SequenceDebugCollector } from "./middleware/sequenceDebug.js";
 import type { CurrentPageContext } from "../tools/getUserLocation.js";
 import type { AgentTurnContext } from "../domain/turnTypes.js";
+import type { DetectedLanguage } from "../domain/languageDetect.js";
 export declare const contextSchema: z.ZodObject<{
     adminUser: z.ZodCustom<AdminUser, AdminUser>;
     userTimeZone: z.ZodString;
@@ -14,9 +15,11 @@ export declare const contextSchema: z.ZodObject<{
     chatSurface: z.ZodOptional<z.ZodString>;
     adminBaseUrl: z.ZodOptional<z.ZodString>;
     adminPublicOrigin: z.ZodOptional<z.ZodString>;
+    userLanguage: z.ZodOptional<z.ZodCustom<DetectedLanguage | null, DetectedLanguage | null>>;
     emit: z.ZodOptional<z.ZodCustom<AgentEventEmitter, AgentEventEmitter>>;
     sequenceDebugSink: z.ZodCustom<SequenceDebugCollector, SequenceDebugCollector>;
 }, z.core.$strip>;
+export type AgentContext = z.infer<typeof contextSchema>;
 export declare function toLangchainAgentContext(context: AgentTurnContext & {
     adminBaseUrl: string;
     emit?: AgentEventEmitter;

package/dist/llm/agentContext.js

@@ -9,6 +9,7 @@ export const contextSchema = z.object({
     chatSurface: z.string().optional(),
     adminBaseUrl: z.string().optional(),
     adminPublicOrigin: z.string().optional(),
+    userLanguage: z.custom().optional(),
     emit: z.custom().optional(),
     sequenceDebugSink: z.custom(),
 });

package/dist/llm/agentModels.d.ts

@@ -16,6 +16,7 @@ export type AgentTurnModels = {
 };
 export type AgentRuntimeRunInput = {
     models: AgentTurnModels;
+    systemPrompt: string;
     input: {
         messages: Messages;
     } | Command;

package/dist/llm/agentRuntime.js

@@ -7,13 +7,14 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { createAgent, summarizationMiddleware, humanInTheLoopMiddleware } from "langchain";
+import { createAgent, summarizationMiddleware, humanInTheLoopMiddleware, dynamicSystemPromptMiddleware, } from "langchain";
 import { createApiBasedToolsMiddleware } from "./middleware/apiToolsMiddleware.js";
 import { createSequenceDebugMiddleware } from "./middleware/sequenceDebug.js";
 import { createSteerMiddleware } from "./middleware/steerMiddleware.js";
 import { createAgentLlmMetricsLogger } from "./agentModels.js";
 import { contextSchema, toLangchainAgentContext } from "./agentContext.js";
-import { createSystemMessagesMiddleware } from "./middleware/systemMessages.js";
+import { createLegacySystemMessagesMiddleware } from "./middleware/legacySystemMessages.js";
+import { buildDynamicSystemPrompt } from "../domain/systemPrompt.js";
 function createHumanInTheLoopInterrupts(apiBasedTools) {
     return Object.fromEntries(Object.entries(apiBasedTools)
         .filter(([, apiBasedTool]) => { var _a; return ((_a = apiBasedTool.agent) === null || _a === void 0 ? void 0 : _a.isDangerous) === true; })
@@ -44,14 +45,22 @@ export class AgentRuntime {
                 descriptionPrefix: "Tool execution pending approval",
             });
             const steerMiddleware = createSteerMiddleware(this.options.steerBuffer);
-            const systemMessagesMiddleware = createSystemMessagesMiddleware();
+            const legacySystemMessagesMiddleware = createLegacySystemMessagesMiddleware();
+            const usernameField = adminforth.config.auth.usernameField;
+            const dynamicPromptMiddleware = dynamicSystemPromptMiddleware((_state, runtime) => buildDynamicSystemPrompt({
+                adminUser: runtime.context.adminUser,
+                usernameField,
+                userLanguage: runtime.context.userLanguage,
+                chatSurface: runtime.context.chatSurface,
+            }));
             const middleware = [
                 steerMiddleware,
                 apiBasedToolsMiddleware,
                 hitlMiddleware,
+                legacySystemMessagesMiddleware,
+                dynamicPromptMiddleware,
                 ...((_a = input.models.modelMiddleware) !== null && _a !== void 0 ? _a : []),
                 sequenceDebugMiddleware,
-                systemMessagesMiddleware,
                 summarizationMiddleware({
                     model: input.models.summaryModel,
                     trigger: { tokens: 1024 * 64 },
@@ -61,6 +70,11 @@ export class AgentRuntime {
             const agent = createAgent({
                 name: this.options.name,
                 model: input.models.model,
+                // Passed as a plain string on purpose: LangChain normalizes it to a single text
+                // block, and DynamicSystemPromptMiddleware appends the per-turn half as a second
+                // one. That block split is all the agent owes the provider — whether the boundary
+                // becomes a cache breakpoint is the adapter's call.
+                systemPrompt: input.systemPrompt,
                 checkpointer: this.options.getCheckpointer(),
                 tools,
                 contextSchema,

package/dist/llm/langGraphLlm.js

@@ -8,13 +8,11 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import { Command } from "@langchain/langgraph";
-import { HumanMessage, SystemMessage } from "langchain";
+import { HumanMessage } from "langchain";
 import { detectUserLanguage } from "../domain/languageDetect.js";
 import { adaptRawStream, normalizeInterrupts } from "./streamAdapter.js";
 function toLangchainMessages(messages) {
-    return messages.map((message) => message.role === "system"
-        ? new SystemMessage(message.content)
-        : new HumanMessage(message.content));
+    return messages.map((message) => new HumanMessage(message.content));
 }
 /**
  * LangChain/LangGraph implementation of {@link LlmPort}. This is the single
@@ -34,6 +32,7 @@ export class LangGraphLlm {
                 : { messages: toLangchainMessages(input.input.messages) };
             const rawStream = yield this.runtime.stream({
                 models,
+                systemPrompt: input.systemPrompt,
                 input: runtimeInput,
                 context: input.context,
                 observability: input.observability,

package/dist/llm/middleware/legacySystemMessages.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Migration shield for threads checkpointed before the system prompt moved out of the
+ * message history.
+ *
+ * Turns used to be started with `[SystemMessage, HumanMessage]`, so every such turn left
+ * a system message inside the thread's persisted state. Those messages are still in old
+ * checkpoints and would now arrive mid-history — both an invalid shape for providers that
+ * take the system prompt out-of-band, and a stale duplicate of a prompt the agent already
+ * supplies. So they are dropped, not re-hoisted: the authoritative prompt is
+ * `createAgent({ systemPrompt })` plus DynamicSystemPromptMiddleware.
+ *
+ * Nothing writes system messages into state any more, so for new threads this is a no-op.
+ * It stays as a cheap guard (and can be deleted once no pre-refactor checkpoints remain).
+ */
+export declare function createLegacySystemMessagesMiddleware(): import("langchain").AgentMiddleware<undefined, undefined, unknown, readonly (import("@langchain/core/tools").ClientTool | import("@langchain/core/tools").ServerTool)[]>;

package/dist/llm/middleware/legacySystemMessages.js

@@ -0,0 +1,45 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { createMiddleware } from "langchain";
+function isSystemMessage(message) {
+    var _a, _b;
+    return (((_a = message._getType) === null || _a === void 0 ? void 0 : _a.call(message)) === "system" ||
+        ((_b = message.getType) === null || _b === void 0 ? void 0 : _b.call(message)) === "system" ||
+        message.type === "system");
+}
+/**
+ * Migration shield for threads checkpointed before the system prompt moved out of the
+ * message history.
+ *
+ * Turns used to be started with `[SystemMessage, HumanMessage]`, so every such turn left
+ * a system message inside the thread's persisted state. Those messages are still in old
+ * checkpoints and would now arrive mid-history — both an invalid shape for providers that
+ * take the system prompt out-of-band, and a stale duplicate of a prompt the agent already
+ * supplies. So they are dropped, not re-hoisted: the authoritative prompt is
+ * `createAgent({ systemPrompt })` plus DynamicSystemPromptMiddleware.
+ *
+ * Nothing writes system messages into state any more, so for new threads this is a no-op.
+ * It stays as a cheap guard (and can be deleted once no pre-refactor checkpoints remain).
+ */
+export function createLegacySystemMessagesMiddleware() {
+    return createMiddleware({
+        name: "LegacySystemMessagesMiddleware",
+        wrapModelCall(request, handler) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const typed = request;
+                const messages = typed.messages.filter((message) => !isSystemMessage(message));
+                if (messages.length === typed.messages.length) {
+                    return handler(request);
+                }
+                return handler(Object.assign(Object.assign({}, request), { messages }));
+            });
+        },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adminforth/agent",
-  "version": "2.6.0",
+  "version": "2.7.1",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -44,11 +44,11 @@
     "typescript": "^5.7.3"
   },
   "dependencies": {
-    "@langchain/core": "^1.1.40",
-    "@langchain/langgraph": "^1.2.8",
-    "@langchain/langgraph-checkpoint": "^1.0.1",
+    "@langchain/core": "1.2.5",
+    "@langchain/langgraph": "1.2.8",
+    "@langchain/langgraph-checkpoint": "1.0.1",
     "dayjs": "^1.11.20",
-    "langchain": "^1.3.3",
+    "langchain": "1.3.3",
     "multer": "^2.1.1",
     "vue-i18n": "^11.4.0",
     "yaml": "^2.8.3",

package/dist/llm/middleware/systemMessages.d.ts

@@ -1 +0,0 @@
-export declare function createSystemMessagesMiddleware(): import("langchain").AgentMiddleware<undefined, undefined, unknown, readonly (import("@langchain/core/tools").ClientTool | import("@langchain/core/tools").ServerTool)[]>;

package/dist/llm/middleware/systemMessages.js

@@ -1,55 +0,0 @@
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-import { createMiddleware } from "langchain";
-function isSystemMessage(message) {
-    var _a, _b;
-    return (((_a = message._getType) === null || _a === void 0 ? void 0 : _a.call(message)) === "system" ||
-        ((_b = message.getType) === null || _b === void 0 ? void 0 : _b.call(message)) === "system" ||
-        message.type === "system");
-}
-function contentToText(content, text) {
-    if (text)
-        return text;
-    if (typeof content === "string")
-        return content;
-    if (!Array.isArray(content))
-        return "";
-    return content
-        .map((block) => {
-        var _a;
-        if (typeof block === "string")
-            return block;
-        if (block && typeof block === "object" && "text" in block) {
-            return String((_a = block.text) !== null && _a !== void 0 ? _a : "");
-        }
-        return "";
-    })
-        .join("");
-}
-function normalizeSystemMessages(request) {
-    const extraSystemText = request.messages
-        .filter(isSystemMessage)
-        .map((message) => contentToText(message.content, message.text))
-        .filter(Boolean)
-        .join("\n\n");
-    return Object.assign(Object.assign({}, request), { systemMessage: extraSystemText
-            ? request.systemMessage.concat(extraSystemText)
-            : request.systemMessage, messages: request.messages.filter((message) => !isSystemMessage(message)) });
-}
-export function createSystemMessagesMiddleware() {
-    return createMiddleware({
-        name: "SystemMessagesMiddleware",
-        wrapModelCall(request, handler) {
-            return __awaiter(this, void 0, void 0, function* () {
-                return handler(normalizeSystemMessages(request));
-            });
-        },
-    });
-}