@adminforth/agent 2.0.10 → 2.1.0

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;

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(),
@@ -77,7 +77,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 +103,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,

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

@@ -10,7 +10,7 @@ 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(),
@@ -54,11 +54,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 +131,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 +158,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'
                 };

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, `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}

@@ -185,6 +185,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, `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* () {

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>);

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

@@ -8,8 +8,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import { 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 SpeechTurnService {
     constructor(runAndPersistAgentResponse) {
         this.runAndPersistAgentResponse = runAndPersistAgentResponse;

package/dist/types.d.ts

@@ -1,10 +1,15 @@
 import { type PluginsCommonOptions, type AdminUser, type HttpExtra, type AudioAdapter, type ChatSurfaceAdapter } from "adminforth";
-import type { AgentModeCompletionAdapter } from "./agent/simpleAgent.js";
+import type { AgentModeCompletionAdapter } from "./application/ports.js";
 interface ISessionResource {
     resourceId: string;
     idField: string;
     titleField: string;
-    turnsField: string;
+    /**
+     * @deprecated Not used by the plugin — session turns are looked up via
+     * `turnResource.sessionIdField`. Kept optional for backward compatibility;
+     * will be removed in a future major version.
+     */
+    turnsField?: string;
     askerIdField: string;
     createdAtField: string;
 }
@@ -69,8 +74,9 @@ export interface PluginOptions extends PluginsCommonOptions {
      */
     systemPrompt?: string;
     /**
-     * Response generation level.
-     * Default is low
+     * @deprecated Not applied — reasoning effort is configured on the completion
+     * adapter (e.g. `extraRequestBodyParameters.reasoning.effort`), not here.
+     * Kept for backward compatibility; will be removed in a future major version.
      */
     reasoning?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
     /**

package/package.json

@@ -1,15 +1,21 @@
 {
   "name": "@adminforth/agent",
-  "version": "2.0.10",
+  "version": "2.1.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
   "homepage": "https://adminforth.dev/docs/tutorial/Plugins/agent/",
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "tsc && rsync -av --exclude 'node_modules' custom dist/"
+    "build": "tsc && rsync -av --exclude 'node_modules' custom dist/",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js --runInBand"
   },
   "keywords": [
     "adminforth",
@@ -24,10 +30,13 @@
   "license": "MIT",
   "description": "AI agent plugin for AdminForth with tool-based workflows and persistent chat sessions",
   "devDependencies": {
+    "@types/jest": "^30.0.0",
     "@types/node": "latest",
     "adminforth": "^3.8.2",
+    "jest": "^30.3.0",
     "semantic-release": "^24.2.1",
     "semantic-release-slack-bot": "^4.0.2",
+    "ts-jest": "^29.4.6",
     "typescript": "^5.7.3"
   },
   "dependencies": {

package/.woodpecker/buildRelease.sh

@@ -1,13 +0,0 @@
-
-#!/bin/bash
-
-# write npm run output both to console and to build.log
-npm run build 2>&1 | tee build.log
-build_status=${PIPESTATUS[0]}
-
-# if exist status from the npm run build is not 0
-# then exit with the status code from the npm run build
-if [ $build_status -ne 0 ]; then
-  echo "Build failed. Exiting with status code $build_status"
-  exit $build_status
-fi

package/.woodpecker/buildSlackNotify.sh

@@ -1,46 +0,0 @@
-#!/bin/sh
-
-set -x
-
-COMMIT_SHORT_SHA=$(echo $CI_COMMIT_SHA | cut -c1-8)
-
-STATUS=${1}  
-
-
-if [ "$STATUS" = "success" ]; then
-  MESSAGE="Did a build without issues on \`$CI_REPO_NAME/$CI_COMMIT_BRANCH\`. Commit: _${CI_COMMIT_MESSAGE}_ (<$CI_COMMIT_URL|$COMMIT_SHORT_SHA>)"
-
-  curl  -s -X POST -H "Content-Type: application/json" -d '{
-    "username": "'"$CI_COMMIT_AUTHOR"'",
-    "icon_url": "'"$CI_COMMIT_AUTHOR_AVATAR"'",
-    "attachments": [
-      {
-          "mrkdwn_in": ["text", "pretext"],
-          "color": "#36a64f",
-          "text": "'"$MESSAGE"'"
-      }
-    ]
-  }' "$DEVELOPERS_SLACK_WEBHOOK"
-  exit 0
-fi
-export BUILD_LOG=$(cat ./build.log)
-
-BUILD_LOG=$(echo $BUILD_LOG | sed 's/"/\\"/g')
-
-MESSAGE="Broke \`$CI_REPO_NAME/$CI_COMMIT_BRANCH\` with commit _${CI_COMMIT_MESSAGE}_ (<$CI_COMMIT_URL|$COMMIT_SHORT_SHA>)"
-CODE_BLOCK="\`\`\`$BUILD_LOG\n\`\`\`"
-
-echo "Sending slack message to developers $MESSAGE"
-# Send the message
-curl -sS -X POST -H "Content-Type: application/json" -d '{
-  "username": "'"$CI_COMMIT_AUTHOR"'",
-  "icon_url": "'"$CI_COMMIT_AUTHOR_AVATAR"'",
-  "attachments": [
-    {
-        "mrkdwn_in": ["text", "pretext"],
-        "color": "#8A1C12",
-        "text": "'"$CODE_BLOCK"'",
-        "pretext": "'"$MESSAGE"'"
-    }
-  ]
-}' "$DEVELOPERS_SLACK_WEBHOOK" 2>&1

package/.woodpecker/release.yml

@@ -1,57 +0,0 @@
-clone:
-  git:
-    image: woodpeckerci/plugin-git
-    settings:
-      partial: false
-      depth: 5
-
-steps:
-  init-secrets:
-    when:
-      - event: push
-    image: infisical/cli
-    environment:
-      INFISICAL_TOKEN:
-        from_secret: VAULT_TOKEN
-    commands:
-      - infisical export --domain https://vault.devforth.io/api --format=dotenv-export --env="prod" > /woodpecker/deploy.vault.env
-
-  build:
-    image: devforth/node20-pnpm:latest
-    when:
-      - event: push
-    commands:
-      - apt update && apt install -y rsync
-      - . /woodpecker/deploy.vault.env   
-      - pnpm install
-      - /bin/bash ./.woodpecker/buildRelease.sh
-      - npm audit signatures
-
-  release:
-    image: devforth/node20-pnpm:latest
-    when:
-      - event:
-          - push
-        branch:
-          - main
-    commands:
-      - . /woodpecker/deploy.vault.env
-      - pnpm exec semantic-release
-
-  slack-on-failure:
-    image: curlimages/curl
-    when:
-      - event: push
-        status: [failure]
-    commands:
-      - . /woodpecker/deploy.vault.env
-      - /bin/sh ./.woodpecker/buildSlackNotify.sh failure
-      
-  slack-on-success: 
-    image: curlimages/curl
-    when:
-      - event: push
-        status: [success]
-    commands:
-      - . /woodpecker/deploy.vault.env
-      - /bin/sh ./.woodpecker/buildSlackNotify.sh success