@adminforth/agent 2.0.10 → 2.2.0

package/dist/llm/streamAdapter.js

@@ -0,0 +1,117 @@
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+// Only tokens emitted by the model node(s) are surfaced to the user; other
+// graph nodes (tools, summarization, etc.) are internal.
+const STREAMABLE_NODES = ["model", "model_request"];
+function getInterruptItems(interrupt) {
+    return Array.isArray(interrupt) ? interrupt : [interrupt];
+}
+/**
+ * Normalize raw LangGraph interrupt object(s) into provider-agnostic descriptors.
+ * Kept in the llm layer so the LangGraph interrupt shape never reaches the app.
+ */
+export function normalizeInterrupts(interrupt) {
+    return getInterruptItems(interrupt).flatMap((item) => {
+        const value = item && typeof item === "object" && "value" in item
+            ? item.value
+            : item;
+        const actionRequests = value && typeof value === "object"
+            ? value.actionRequests
+            : undefined;
+        const interruptId = item && typeof item === "object"
+            ? item.id
+            : undefined;
+        return typeof interruptId === "string" && Array.isArray(actionRequests)
+            ? [{ id: interruptId, count: actionRequests.length }]
+            : [];
+    });
+}
+function extractBlocks(token) {
+    if (Array.isArray(token === null || token === void 0 ? void 0 : token.contentBlocks)) {
+        return token.contentBlocks;
+    }
+    if (Array.isArray(token === null || token === void 0 ? void 0 : token.content)) {
+        return token.content;
+    }
+    return [];
+}
+/**
+ * Convert one raw LangGraph stream entry into zero or more normalized chunks.
+ * Pure and synchronous so the parsing rules can be unit-tested in isolation.
+ */
+export function parseRawStreamChunk(entry) {
+    const [mode, chunk] = entry;
+    if (mode === "updates") {
+        if (chunk && typeof chunk === "object" && "__interrupt__" in chunk) {
+            const interrupt = chunk.__interrupt__;
+            return [{ kind: "interrupt", interrupt, descriptors: normalizeInterrupts(interrupt) }];
+        }
+        return [];
+    }
+    const [token, metadata] = chunk;
+    const nodeName = typeof (metadata === null || metadata === void 0 ? void 0 : metadata.langgraph_node) === "string" ? metadata.langgraph_node : "";
+    if (nodeName && !STREAMABLE_NODES.includes(nodeName)) {
+        return [];
+    }
+    const blocks = extractBlocks(token);
+    const chunks = [];
+    const reasoning = blocks
+        .filter((block) => (block === null || block === void 0 ? void 0 : block.type) === "reasoning")
+        .map((block) => { var _a; return String((_a = block.reasoning) !== null && _a !== void 0 ? _a : ""); })
+        .join("");
+    const text = blocks
+        .filter((block) => (block === null || block === void 0 ? void 0 : block.type) === "text")
+        .map((block) => { var _a; return String((_a = block.text) !== null && _a !== void 0 ? _a : ""); })
+        .join("");
+    if (reasoning) {
+        chunks.push({ kind: "reasoning", delta: reasoning });
+    }
+    if (text) {
+        chunks.push({ kind: "text", delta: text });
+    }
+    return chunks;
+}
+/**
+ * Adapt the raw LangGraph `["messages" | "updates", ...]` stream into a typed
+ * `AgentStreamChunk` stream for the application layer.
+ */
+export function adaptRawStream(raw) {
+    return __asyncGenerator(this, arguments, function* adaptRawStream_1() {
+        var _a, e_1, _b, _c;
+        try {
+            for (var _d = true, raw_1 = __asyncValues(raw), raw_1_1; raw_1_1 = yield __await(raw_1.next()), _a = raw_1_1.done, !_a; _d = true) {
+                _c = raw_1_1.value;
+                _d = false;
+                const entry = _c;
+                for (const chunk of parseRawStreamChunk(entry)) {
+                    yield yield __await(chunk);
+                }
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (!_d && !_a && (_b = raw_1.return)) yield __await(_b.call(raw_1));
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+    });
+}

package/dist/{sessionStore.d.ts → persistence/sessionStore.d.ts}

@@ -1,14 +1,21 @@
 import type { AdminUser, IAdminForth } from "adminforth";
 import type { ChatSurfaceIncomingMessage } from "adminforth";
-import type { PreviousUserMessage } from "./agent/languageDetect.js";
-import type { PluginOptions } from "./types.js";
+import type { PreviousUserMessage } from "../domain/languageDetect.js";
+import type { PluginOptions } from "../types.js";
 export declare const AGENT_SYSTEM_TURN_PROMPT = "__adminforth_system_message__";
+export declare const STEER_PROMPT_MARKER = "__adminforth_steer__:";
 export declare class AgentSessionStore {
     private getAdminforth;
     private options;
     constructor(getAdminforth: () => IAdminForth, options: PluginOptions);
     createNewTurn(sessionId: string, prompt: string, response?: string): Promise<any>;
     createSystemTurn(sessionId: string, systemMessage: string): Promise<any>;
+    /**
+     * Append a mid-turn steer to the current (running) turn's prompt instead of creating a
+     * new record. Targets the latest non-system turn so a steer attaches to the real
+     * conversation turn, never an audio/system note.
+     */
+    appendSteerToCurrentTurn(sessionId: string, steerText: string): Promise<void>;
     getSessionTurns(sessionId: string): Promise<{
         prompt: any;
         response: any;
@@ -17,4 +24,14 @@ export declare class AgentSessionStore {
     getLatestTurn(sessionId: string): Promise<any>;
     getChatSurfaceSessionId(incoming: ChatSurfaceIncomingMessage): string;
     getOrCreateChatSurfaceSession(incoming: ChatSurfaceIncomingMessage, adminUser: AdminUser): Promise<string>;
+    touchSession(sessionId: string): Promise<void>;
+    saveTurnResponse(input: {
+        turnId: string;
+        responseText: string;
+        debugHistory?: unknown;
+    }): Promise<void>;
+    getResumeState(sessionId: string): Promise<{
+        turnId: string;
+        initialResponse: string;
+    }>;
 }

package/dist/{sessionStore.js → persistence/sessionStore.js}

@@ -10,6 +10,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 import { Filters, Sorts } from "adminforth";
 import { randomUUID } from "crypto";
 export const AGENT_SYSTEM_TURN_PROMPT = "__adminforth_system_message__";
+export const STEER_PROMPT_MARKER = "__adminforth_steer__:";
 export class AgentSessionStore {
     constructor(getAdminforth, options) {
         this.getAdminforth = getAdminforth;
@@ -41,6 +42,25 @@ export class AgentSessionStore {
             return newTurn.createdRecord[this.options.turnResource.idField];
         });
     }
+    /**
+     * Append a mid-turn steer to the current (running) turn's prompt instead of creating a
+     * new record. Targets the latest non-system turn so a steer attaches to the real
+     * conversation turn, never an audio/system note.
+     */
+    appendSteerToCurrentTurn(sessionId, steerText) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const turns = yield this.getAdminforth().resource(this.options.turnResource.resourceId).list([Filters.EQ(this.options.turnResource.sessionIdField, sessionId)], undefined, undefined, [Sorts.DESC(this.options.turnResource.createdAtField)]);
+            const turn = turns.find((candidate) => candidate[this.options.turnResource.promptField] !== AGENT_SYSTEM_TURN_PROMPT);
+            if (!turn) {
+                return;
+            }
+            const currentPrompt = (_a = turn[this.options.turnResource.promptField]) !== null && _a !== void 0 ? _a : "";
+            yield this.getAdminforth().resource(this.options.turnResource.resourceId).update(turn[this.options.turnResource.idField], {
+                [this.options.turnResource.promptField]: `${currentPrompt}${STEER_PROMPT_MARKER}${steerText}`,
+            });
+        });
+    }
     getSessionTurns(sessionId) {
         return __awaiter(this, void 0, void 0, function* () {
             const turns = yield this.getAdminforth().resource(this.options.turnResource.resourceId).list([Filters.EQ(this.options.turnResource.sessionIdField, sessionId)], undefined, undefined, [Sorts.ASC(this.options.turnResource.createdAtField)]);
@@ -86,4 +106,37 @@ export class AgentSessionStore {
             return sessionId;
         });
     }
+    touchSession(sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.getAdminforth().resource(this.options.sessionResource.resourceId).update(sessionId, {
+                [this.options.sessionResource.createdAtField]: new Date().toISOString(),
+            });
+        });
+    }
+    saveTurnResponse(input) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const turnUpdates = {
+                [this.options.turnResource.responseField]: input.responseText,
+            };
+            if (this.options.turnResource.debugField) {
+                turnUpdates[this.options.turnResource.debugField] = input.debugHistory;
+            }
+            yield this.getAdminforth()
+                .resource(this.options.turnResource.resourceId)
+                .update(input.turnId, turnUpdates);
+        });
+    }
+    getResumeState(sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const latestTurn = yield this.getLatestTurn(sessionId);
+            if (!latestTurn) {
+                throw new Error(`No agent turn found for session "${sessionId}".`);
+            }
+            const response = latestTurn[this.options.turnResource.responseField];
+            return {
+                turnId: latestTurn[this.options.turnResource.idField],
+                initialResponse: response === "not_finished" ? "" : String(response),
+            };
+        });
+    }
 }

package/dist/{agent/tools/AgentToolProvider.d.ts → tools/agentToolProvider.d.ts}

@@ -1,5 +1,5 @@
 import type { IAdminForth } from "adminforth";
-import type { ApiBasedTool } from "../../apiBasedTools.js";
+import type { ApiBasedTool } from "./apiBasedTools.js";
 export declare class AgentToolProvider {
     private readonly getAdminforth;
     private readonly getInternalAgentResourceIds;

package/dist/{agent/tools/AgentToolProvider.js → tools/agentToolProvider.js}

@@ -7,7 +7,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { prepareApiBasedTools } from "../../apiBasedTools.js";
+import { prepareApiBasedTools } from "./apiBasedTools.js";
 import { createAgentTools } from "./index.js";
 export class AgentToolProvider {
     constructor(getAdminforth, getInternalAgentResourceIds) {

package/dist/{apiBasedTools.js → tools/apiBasedTools.js}

@@ -385,7 +385,6 @@ function callOpenApiSchema(params) {
             return validationErrorResponse('REQUEST_VALIDATION_FAILED', requestValidation.errors);
         }
         const response = createDirectToolResponse();
-        logger.info(`Calling OpenAPI tool "${toolName}" with direct handler`);
         const lang = acceptLanguage !== null && acceptLanguage !== void 0 ? acceptLanguage : "en";
         const tr = (msg, category, trParams, pluralizationNumber) => adminforth.tr(msg, category, lang, trParams, pluralizationNumber);
         const output = yield withToolHandlerTimeout((handlerAbortSignal) => schema.handler({
@@ -449,8 +448,6 @@ export function prepareApiBasedTools(adminforth, hiddenResourceIds = []) {
             openApiSchemasByToolName.set(toolName, schema);
         }
     }
-    logger.info(`AdminForth Agent OpenAPI APIs: ${formatLogNameList(adminforth.openApi.registeredSchemas.map((schema) => openApiSchemaPathToToolName(schema.path, adminforth)))}`);
-    logger.info(`AdminForth Agent OpenAPI tools connected: ${formatLogNameList([...openApiSchemasByToolName.keys()])}`);
     for (const [toolName, schema] of openApiSchemasByToolName.entries()) {
         apiBasedTools[toolName] = {
             description: schema.description,

package/dist/{agent/tools → tools}/apiTool.d.ts

@@ -1,4 +1,4 @@
-import type { ApiBasedTool } from "../../apiBasedTools.js";
+import type { ApiBasedTool } from "./apiBasedTools.js";
 export declare function createApiTool(toolName: string, apiBasedTool: ApiBasedTool): import("langchain").DynamicStructuredTool<Record<string, unknown> | {
     readonly type: "object";
     readonly properties: {};

package/dist/{agent/tools → tools}/fetchSkill.js

@@ -9,7 +9,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 import { tool } from "langchain";
 import { z } from "zod";
-import { listSkillManifests, loadSkillMarkdown, } from "../skills/registry.js";
+import { listSkillManifests, loadSkillMarkdown, } from "./skills/registry.js";
 const fetchSkillSchema = z.object({
     skillName: z
         .string()

package/dist/{agent/tools → tools}/fetchToolSchema.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { ApiBasedTool } from "../../apiBasedTools.js";
+import type { ApiBasedTool } from "./apiBasedTools.js";
 export declare function createFetchToolSchemaTool(apiBasedTools: Record<string, ApiBasedTool>): Promise<import("langchain").DynamicStructuredTool<z.ZodObject<{
     toolName: z.ZodString;
 }, z.core.$strip>, {

package/dist/{agent/tools → tools}/index.d.ts

@@ -1,4 +1,4 @@
 import type { ClientTool } from "@langchain/core/tools";
-import type { ApiBasedTool } from "../../apiBasedTools.js";
+import type { ApiBasedTool } from "./apiBasedTools.js";
 export declare const ALWAYS_AVAILABLE_API_TOOL_NAMES: readonly ["get_resource"];
 export declare function createAgentTools(customComponentsDir: string, apiBasedTools: Record<string, ApiBasedTool>, pluginCustomFolderPaths?: string[]): Promise<ClientTool[]>;

package/dist/{agent/tools → tools}/navigateUser.d.ts

@@ -17,8 +17,8 @@ export declare function createNavigateUserTool(): import("langchain").DynamicStr
     sort: z.ZodOptional<z.ZodObject<{
         column: z.ZodString;
         direction: z.ZodEnum<{
-            asc: "asc";
             desc: "desc";
+            asc: "asc";
         }>;
     }, z.core.$strip>>;
     query: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
@@ -34,7 +34,7 @@ export declare function createNavigateUserTool(): import("langchain").DynamicStr
     }[] | undefined;
     sort?: {
         column: string;
-        direction: "asc" | "desc";
+        direction: "desc" | "asc";
     } | undefined;
     query?: Record<string, string | number | boolean> | undefined;
 }, {
@@ -49,7 +49,7 @@ export declare function createNavigateUserTool(): import("langchain").DynamicStr
     }[] | undefined;
     sort?: {
         column: string;
-        direction: "asc" | "desc";
+        direction: "desc" | "asc";
     } | undefined;
     query?: Record<string, string | number | boolean> | undefined;
 }, string, unknown, "navigate_user">;

package/dist/{endpoints → transport/http}/context.d.ts

@@ -1,6 +1,6 @@
 import type { ChatSurfaceAdapter, ChatSurfaceEventSink, ChatSurfaceIncomingMessage, IAdminForth } from "adminforth";
-import type { HandleSpeechTurnInput, HandleTurnInput, RunAndPersistAgentResponseInput, RunAndPersistAgentResponseResult } from "../agentTurnService.js";
-import type { PluginOptions } from "../types.js";
+import type { HandleSpeechTurnInput, HandleTurnInput, RunAndPersistAgentResponseInput, RunAndPersistAgentResponseResult } from "../../domain/turnTypes.js";
+import type { PluginOptions } from "../../types.js";
 export type SessionTurn = {
     prompt: string;
     response: string;
@@ -10,12 +10,20 @@ export type AgentEndpointsContext = {
     options: PluginOptions;
     handleTurn(input: HandleTurnInput): Promise<RunAndPersistAgentResponseResult>;
     handleSpeechTurn(input: HandleSpeechTurnInput): Promise<RunAndPersistAgentResponseResult | null>;
+    steer(input: {
+        sessionId: string;
+        message: string;
+    }): {
+        id: string;
+        queued: number;
+    };
     runAndPersistAgentResponse(input: RunAndPersistAgentResponseInput): Promise<RunAndPersistAgentResponseResult>;
     getSessionTurns(sessionId: string): Promise<SessionTurn[]>;
     createNewTurn(sessionId: string, prompt: string, response?: string): Promise<string>;
     createSystemTurn(sessionId: string, systemMessage: string): Promise<string>;
+    appendSteerToCurrentTurn(sessionId: string, steerText: string): Promise<void>;
     handleChatSurfaceMessage(adapter: ChatSurfaceAdapter, incoming: ChatSurfaceIncomingMessage, sink: ChatSurfaceEventSink): Promise<void>;
 };
-export type CoreEndpointsContext = Pick<AgentEndpointsContext, "options" | "handleTurn" | "handleSpeechTurn">;
-export type SessionEndpointsContext = Pick<AgentEndpointsContext, "adminforth" | "options" | "getSessionTurns" | "createNewTurn" | "createSystemTurn">;
+export type CoreEndpointsContext = Pick<AgentEndpointsContext, "options" | "handleTurn" | "handleSpeechTurn" | "steer">;
+export type SessionEndpointsContext = Pick<AgentEndpointsContext, "adminforth" | "options" | "getSessionTurns" | "createNewTurn" | "createSystemTurn" | "appendSteerToCurrentTurn">;
 export type ChatSurfaceEndpointsContext = Pick<AgentEndpointsContext, "adminforth" | "options" | "handleChatSurfaceMessage">;

package/dist/transport/http/context.js

@@ -0,0 +1 @@
+export {};

package/dist/{endpoints/core.js → transport/http/coreEndpoints.js}

@@ -8,7 +8,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import { z } from "zod";
-import { createSseEventEmitter } from "../surfaces/web-sse/createSseEventEmitter.js";
+import { createSseEventEmitter } from "../sse/sseWriter.js";
 const currentPageContextSchema = z.object({
     path: z.string(),
     fullPath: z.string(),
@@ -26,6 +26,10 @@ const agentApprovalBodySchema = z.object({
     sessionId: z.string(),
     decision: z.enum(["approve", "reject"]),
 }).strict();
+const agentSteerBodySchema = z.object({
+    sessionId: z.string(),
+    message: z.string().min(1),
+}).strict();
 // Sent as multipart/form-data (via multer), so every field arrives as a plain string on the wire.
 // `currentPage` is JSON.stringify'd by the client into a form field and must be parsed back into
 // an object. Zod -> JSON-Schema conversion cannot represent `.transform()` at all (it throws), so
@@ -77,7 +81,7 @@ export function setupCoreEndpoints(ctx, server) {
         method: 'POST',
         path: `/agent/response`,
         request_schema: agentResponseBodySchema,
-        handler: (_a) => __awaiter(this, [_a], void 0, function* ({ body, adminUser, response, _raw_express_res, abortSignal }) {
+        handler: (_a) => __awaiter(this, [_a], void 0, function* ({ body, adminUser, _raw_express_res, abortSignal }) {
             var _b;
             const data = body;
             const emit = createSseEventEmitter(_raw_express_res, {
@@ -103,7 +107,7 @@ export function setupCoreEndpoints(ctx, server) {
         method: 'POST',
         path: `/agent/approval`,
         request_schema: agentApprovalBodySchema,
-        handler: (_a) => __awaiter(this, [_a], void 0, function* ({ body, adminUser, response, _raw_express_res, abortSignal }) {
+        handler: (_a) => __awaiter(this, [_a], void 0, function* ({ body, adminUser, _raw_express_res, abortSignal }) {
             const data = body;
             const emit = createSseEventEmitter(_raw_express_res, {
                 vercelAiUiMessageStream: true,
@@ -122,6 +126,22 @@ export function setupCoreEndpoints(ctx, server) {
             return null;
         })
     });
+    server.endpoint({
+        method: 'POST',
+        path: `/agent/steer`,
+        request_schema: agentSteerBodySchema,
+        handler: (_a) => __awaiter(this, [_a], void 0, function* ({ body }) {
+            const data = body;
+            // Fire-and-forget: the steer is buffered and folded into the running turn by the
+            // beforeModel steer middleware, which signals `data-steer-applied` on that turn's
+            // SSE stream once consumed. This endpoint only confirms it was received/queued.
+            const { id, queued } = ctx.steer({
+                sessionId: data.sessionId,
+                message: data.message,
+            });
+            return { ok: true, id, queued };
+        })
+    });
     server.endpoint({
         method: 'POST',
         path: `/agent/speech-response`,

package/dist/{endpoints/sessions.js → transport/http/sessionEndpoints.js}

@@ -10,11 +10,15 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 import { Filters, Sorts } from "adminforth";
 import { randomUUID } from "crypto";
 import { z } from "zod";
-import { AGENT_SYSTEM_TURN_PROMPT } from "../sessionStore.js";
+import { AGENT_SYSTEM_TURN_PROMPT } from "../../persistence/sessionStore.js";
 const addSystemMessageBodySchema = z.object({
     sessionId: z.string(),
     systemMessage: z.string(),
 }).strict();
+const appendSteerBodySchema = z.object({
+    sessionId: z.string(),
+    message: z.string().min(1),
+}).strict();
 const getSessionsBodySchema = z.object({
     limit: z.number().int().min(1).max(100).optional(),
 }).strict();
@@ -54,11 +58,13 @@ export function setupSessionEndpoints(ctx, server) {
             const sessionId = data.sessionId;
             const session = yield ctx.adminforth.resource(ctx.options.sessionResource.resourceId).get([Filters.EQ(ctx.options.sessionResource.idField, sessionId)]);
             if (!session) {
+                response.setStatus(404, 'Session not found');
                 return {
                     error: 'Session not found'
                 };
             }
             if (session[ctx.options.sessionResource.askerIdField] !== userId) {
+                response.setStatus(403, 'Unauthorized');
                 return {
                     error: 'Unauthorized'
                 };
@@ -129,11 +135,13 @@ export function setupSessionEndpoints(ctx, server) {
             const userId = adminUser.pk;
             const session = yield ctx.adminforth.resource(ctx.options.sessionResource.resourceId).get([Filters.EQ(ctx.options.sessionResource.idField, sessionId)]);
             if (!session) {
+                response.setStatus(404, 'Session not found');
                 return {
                     error: 'Session not found'
                 };
             }
             if (session[ctx.options.sessionResource.askerIdField] !== userId) {
+                response.setStatus(403, 'Unauthorized');
                 return {
                     error: 'Unauthorized'
                 };
@@ -154,11 +162,13 @@ export function setupSessionEndpoints(ctx, server) {
             const data = body;
             const session = yield ctx.adminforth.resource(ctx.options.sessionResource.resourceId).get([Filters.EQ(ctx.options.sessionResource.idField, data.sessionId)]);
             if (!session) {
+                response.setStatus(404, 'Session not found');
                 return {
                     error: 'Session not found'
                 };
             }
             if (session[ctx.options.sessionResource.askerIdField] !== adminUser.pk) {
+                response.setStatus(403, 'Unauthorized');
                 return {
                     error: 'Unauthorized'
                 };
@@ -169,4 +179,29 @@ export function setupSessionEndpoints(ctx, server) {
             };
         })
     });
+    server.endpoint({
+        method: 'POST',
+        path: `/agent/append-steer-to-turn`,
+        request_schema: appendSteerBodySchema,
+        handler: (_a) => __awaiter(this, [_a], void 0, function* ({ body, adminUser, response }) {
+            const data = body;
+            const session = yield ctx.adminforth.resource(ctx.options.sessionResource.resourceId).get([Filters.EQ(ctx.options.sessionResource.idField, data.sessionId)]);
+            if (!session) {
+                response.setStatus(404, 'Session not found');
+                return {
+                    error: 'Session not found'
+                };
+            }
+            if (session[ctx.options.sessionResource.askerIdField] !== adminUser.pk) {
+                response.setStatus(403, 'Unauthorized');
+                return {
+                    error: 'Unauthorized'
+                };
+            }
+            yield ctx.appendSteerToCurrentTurn(data.sessionId, data.message);
+            return {
+                ok: true
+            };
+        })
+    });
 }

package/dist/transport/sse/sseWriter.d.ts

@@ -0,0 +1,29 @@
+import type { AgentEventEmitter } from "../../domain/agentEvents.js";
+type AgentEventStreamResponse = {
+    writeHead: (statusCode: number, headers: Record<string, string>) => void;
+    write: (chunk: string) => unknown;
+    end: () => unknown;
+    writableEnded: boolean;
+    destroyed: boolean;
+};
+type AgentEventStreamOptions = {
+    vercelAiUiMessageStream?: boolean;
+    closeActiveBlockOnToolStart?: boolean;
+};
+/**
+ * Maps the internal {@link AgentEvent} vocabulary onto the two Server-Sent-Events
+ * wire dialects the frontend consumes. Both dialects are HARD external contracts —
+ * do not change frame names/shapes without updating the corresponding consumer:
+ *
+ * - `vercelAiUiMessageStream: true` (used by `/agent/response` and `/agent/approval`):
+ *   the Vercel AI SDK message-stream v1 format (`start`, `text-start`/`text-delta`/
+ *   `text-end`, `reasoning-*`, `data-*` parts including `data-steer-applied`,
+ *   `error` with `errorText`, `finish`, `[DONE]`). Consumed by `DefaultChatTransport`
+ *   and the manual approval parser in `custom/composables/agentStore/useAgentChat.ts`.
+ * - default (used by `/agent/speech-response`): bare event names
+ *   (`transcript`, `speech-response`, `audio-start`/`audio-delta`/`audio-done`,
+ *   `open-page`, `error`) plus the Vercel-shaped `data-tool-call`. Consumed by
+ *   `custom/composables/useAgentAudio.ts`.
+ */
+export declare function createSseEventEmitter(res: AgentEventStreamResponse, options?: AgentEventStreamOptions): AgentEventEmitter;
+export {};

package/dist/{surfaces/web-sse/createSseEventEmitter.js → transport/sse/sseWriter.js}

@@ -98,6 +98,15 @@ function createAgentEventStream(res, options = {}) {
                 },
             });
         },
+        steerApplied(count, ids) {
+            stream.send({
+                type: isAiUiMessageStream ? "data-steer-applied" : "steer-applied",
+                data: {
+                    count,
+                    ids,
+                },
+            });
+        },
         openPage(targetPath) {
             stream.send({
                 type: isAiUiMessageStream ? "data-open-page" : "open-page",
@@ -185,6 +194,21 @@ function createAgentEventStream(res, options = {}) {
     };
     return stream;
 }
+/**
+ * Maps the internal {@link AgentEvent} vocabulary onto the two Server-Sent-Events
+ * wire dialects the frontend consumes. Both dialects are HARD external contracts —
+ * do not change frame names/shapes without updating the corresponding consumer:
+ *
+ * - `vercelAiUiMessageStream: true` (used by `/agent/response` and `/agent/approval`):
+ *   the Vercel AI SDK message-stream v1 format (`start`, `text-start`/`text-delta`/
+ *   `text-end`, `reasoning-*`, `data-*` parts including `data-steer-applied`,
+ *   `error` with `errorText`, `finish`, `[DONE]`). Consumed by `DefaultChatTransport`
+ *   and the manual approval parser in `custom/composables/agentStore/useAgentChat.ts`.
+ * - default (used by `/agent/speech-response`): bare event names
+ *   (`transcript`, `speech-response`, `audio-start`/`audio-delta`/`audio-done`,
+ *   `open-page`, `error`) plus the Vercel-shaped `data-tool-call`. Consumed by
+ *   `custom/composables/useAgentAudio.ts`.
+ */
 export function createSseEventEmitter(res, options = {}) {
     const stream = createAgentEventStream(res, options);
     return (event) => __awaiter(this, void 0, void 0, function* () {
@@ -207,6 +231,9 @@ export function createSseEventEmitter(res, options = {}) {
             case "interrupt":
                 stream.interrupt(event.sessionId, event.interrupt);
                 break;
+            case "steer-applied":
+                stream.steerApplied(event.count, event.ids);
+                break;
             case "open-page":
                 stream.openPage(event.targetPath);
                 break;

package/dist/{chatSurfaceService.d.ts → transport/surfaces/chatSurfaceService.d.ts}

@@ -1,7 +1,7 @@
 import type { ChatSurfaceAdapter, ChatSurfaceEventSink, ChatSurfaceIncomingMessage, IAdminForth } from "adminforth";
-import type { HandleTurnInput, RunAndPersistAgentResponseInput, RunAndPersistAgentResponseResult } from "./agentTurnService.js";
-import type { AgentSessionStore } from "./sessionStore.js";
-import type { PluginOptions } from "./types.js";
+import type { HandleTurnInput, RunAndPersistAgentResponseInput, RunAndPersistAgentResponseResult } from "../../domain/turnTypes.js";
+import type { AgentSessionStore } from "../../persistence/sessionStore.js";
+import type { PluginOptions } from "../../types.js";
 export declare class ChatSurfaceService {
     private getAdminforth;
     private options;

package/dist/{chatSurfaceService.js → transport/surfaces/chatSurfaceService.js}

@@ -8,8 +8,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import { Filters, logger } from "adminforth";
-import { getErrorMessage, isAbortError } from "./errors.js";
-import { sanitizeSpeechText } from "./sanitizeSpeechText.js";
+import { getErrorMessage, isAbortError } from "../../shared/errors.js";
+import { sanitizeSpeechText } from "../../shared/sanitizeSpeechText.js";
 export class ChatSurfaceService {
     constructor(getAdminforth, options, sessionStore, handleTurn, runAndPersistAgentResponse) {
         this.getAdminforth = getAdminforth;
@@ -35,9 +35,11 @@ export class ChatSurfaceService {
                 return;
             }
             if (event.type === "error") {
+                // Full error detail is logged server-side (see runAndPersistAgentResponse);
+                // external chat users receive a generic message to avoid leaking internals.
                 yield sink.emit({
                     type: "error",
-                    message: event.error,
+                    message: "Agent response failed. Check server logs for details.",
                 });
             }
         });
@@ -122,7 +124,7 @@ export class ChatSurfaceService {
                 logger.error(`Agent ${incoming.surface} surface speech synthesis failed:\n${getErrorMessage(error)}`);
                 yield sink.emit({
                     type: "error",
-                    message: getErrorMessage(error),
+                    message: "Speech synthesis failed. Check server logs for details.",
                 });
             }
         });
@@ -165,7 +167,7 @@ export class ChatSurfaceService {
             if (agentResponse.failed) {
                 yield sink.emit({
                     type: "error",
-                    message: agentResponse.text,
+                    message: "Agent response failed. Check server logs for details.",
                 });
             }
             return agentResponse;

package/dist/{agent/speech/SpeechTurnService.d.ts → transport/surfaces/speechTurnService.d.ts}

@@ -1,4 +1,4 @@
-import type { RunAndPersistAgentResponseInput, RunAndPersistAgentResponseResult, SpeechAgentTurnInput } from "../turn/turnTypes.js";
+import type { RunAndPersistAgentResponseInput, RunAndPersistAgentResponseResult, SpeechAgentTurnInput } from "../../domain/turnTypes.js";
 export declare class SpeechTurnService {
     private readonly runAndPersistAgentResponse;
     constructor(runAndPersistAgentResponse: (input: RunAndPersistAgentResponseInput) => Promise<RunAndPersistAgentResponseResult>);