@adminforth/agent 2.0.10 → 2.2.0

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.2.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

package/agent/checkpointer.ts

@@ -1,329 +0,0 @@
-import type { RunnableConfig } from "@langchain/core/runnables";
-import {
-  BaseCheckpointSaver,
-  type Checkpoint,
-  type CheckpointPendingWrite,
-  type CheckpointMetadata,
-  type CheckpointTuple,
-  type PendingWrite,
-  WRITES_IDX_MAP,
-} from "@langchain/langgraph-checkpoint";
-import type { PluginOptions } from "../types.js";
-import { Filters } from "adminforth";
-
-const ROOT_CHECKPOINT_NAMESPACE = "__root__";
-type CheckpointRow = Record<string, unknown>;
-
-export class AdminForthCheckpointSaver extends BaseCheckpointSaver {
-  constructor(
-    private readonly adminforth: any,
-    private readonly pluginOptions: PluginOptions,
-  ) {
-    super();
-  }
-
-  private get resourceConfig() {
-    const resource = this.pluginOptions.checkpointResource;
-    if (!resource) {
-      throw new Error("checkpointResource is not configured");
-    }
-    return resource;
-  }
-
-  private resource() {
-    return this.adminforth.resource(this.resourceConfig.resourceId);
-  }
-
-  private serialize(value: unknown): string | null {
-    if (value === undefined || value === null) return null;
-    return JSON.stringify(value);
-  }
-
-  private deserialize<T>(value: unknown): T | null {
-    if (value === undefined || value === null) return null;
-    if (typeof value === "string") {
-      return JSON.parse(value) as T;
-    }
-    return value as T;
-  }
-
-  private now(): string {
-    return new Date().toISOString();
-  }
-
-  private encodeCheckpointNamespace(checkpointNs: string): string {
-    return checkpointNs === "" ? ROOT_CHECKPOINT_NAMESPACE : checkpointNs;
-  }
-
-  private decodeCheckpointNamespace(checkpointNs: unknown): string {
-    return checkpointNs === ROOT_CHECKPOINT_NAMESPACE ? "" : String(checkpointNs ?? "");
-  }
-
-  private getConfigValues(config: RunnableConfig) {
-    const configurable = (config.configurable ?? {}) as Record<string, unknown>;
-
-    return {
-      threadId: String(configurable.thread_id ?? ""),
-      checkpointNs: String(configurable.checkpoint_ns ?? ""),
-      checkpointId: configurable.checkpoint_id
-        ? String(configurable.checkpoint_id)
-        : null,
-    };
-  }
-
-  private buildConfig(threadId: string, checkpointNs: string, checkpointId: string): RunnableConfig {
-    return {
-      configurable: {
-        thread_id: threadId,
-        checkpoint_ns: checkpointNs,
-        checkpoint_id: checkpointId,
-      },
-    };
-  }
-
-  private buildCheckpointRowId(threadId: string, checkpointNs: string, checkpointId: string) {
-    return `cp:${threadId}:${checkpointNs}:${checkpointId}`;
-  }
-
-  private buildWritesRowId(
-    threadId: string,
-    checkpointNs: string,
-    checkpointId: string,
-    taskId: string,
-    seq: number,
-  ) {
-    return `wr:${threadId}:${checkpointNs}:${checkpointId}:${taskId}:${seq}`;
-  }
-
-  private getWriteIndex(channel: string, index: number): number {
-    return WRITES_IDX_MAP[channel] ?? index;
-  }
-
-  private isDuplicateCheckpointWriteError(error: unknown): boolean {
-    return error instanceof Error && error.message.includes("UNIQUE constraint failed");
-  }
-
-  async put(
-    config: RunnableConfig,
-    checkpoint: Checkpoint,
-    metadata: CheckpointMetadata,
-    _newVersions: Record<string, unknown>,
-  ): Promise<RunnableConfig> {
-    const r = this.resourceConfig;
-    const { threadId, checkpointNs } = this.getConfigValues(config);
-    const checkpointId = String((checkpoint as any).id);
-    const storedCheckpointNs = this.encodeCheckpointNamespace(checkpointNs);
-
-    const parentCheckpointId = this.getConfigValues(config).checkpointId;
-    const createdAt = this.now();
-
-    await this.resource().create({
-      [r.idField]: this.buildCheckpointRowId(threadId, storedCheckpointNs, checkpointId),
-      [r.threadIdField]: threadId,
-      [r.checkpointNamespaceField]: storedCheckpointNs,
-      [r.checkpointIdField]: checkpointId,
-      [r.parentCheckpointIdField]: parentCheckpointId,
-      [r.rowKindField]: "checkpoint",
-      [r.taskIdField]: null,
-      [r.sequenceField]: 0,
-      [r.createdAtField]: createdAt,
-      [r.checkpointPayloadField]: this.serialize(checkpoint),
-      [r.metadataPayloadField]: this.serialize(metadata),
-      [r.writesPayloadField]: null,
-      [r.schemaVersionField]: 1,
-    });
-
-    return this.buildConfig(threadId, checkpointNs, checkpointId);
-  }
-
-  async putWrites(
-    config: RunnableConfig,
-    writes: PendingWrite[],
-    taskId: string,
-  ): Promise<void> {
-    const r = this.resourceConfig;
-    const { threadId, checkpointNs, checkpointId } = this.getConfigValues(config);
-    const storedCheckpointNs = this.encodeCheckpointNamespace(checkpointNs);
-
-    if (!checkpointId) {
-      throw new Error("putWrites requires checkpoint_id in config");
-    }
-
-    const createdAt = this.now();
-
-    await Promise.all(
-      writes.map(async ([channel, value], index) => {
-        const writeIndex = this.getWriteIndex(channel, index);
-
-        try {
-          await this.resource().create({
-            [r.idField]: this.buildWritesRowId(
-              threadId,
-              storedCheckpointNs,
-              checkpointId,
-              taskId,
-              writeIndex,
-            ),
-            [r.threadIdField]: threadId,
-            [r.checkpointNamespaceField]: storedCheckpointNs,
-            [r.checkpointIdField]: checkpointId,
-            [r.parentCheckpointIdField]: null,
-            [r.rowKindField]: "writes",
-            [r.taskIdField]: taskId,
-            [r.sequenceField]: writeIndex,
-            [r.createdAtField]: createdAt,
-            [r.checkpointPayloadField]: null,
-            [r.metadataPayloadField]: null,
-            [r.writesPayloadField]: this.serialize([channel, value] satisfies PendingWrite),
-            [r.schemaVersionField]: 1,
-          });
-        } catch (error) {
-          if (!this.isDuplicateCheckpointWriteError(error)) {
-            throw error;
-          }
-        }
-      }),
-    );
-  }
-
-  async getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined> {
-    const r = this.resourceConfig;
-    const { threadId, checkpointNs, checkpointId } = this.getConfigValues(config);
-    const storedCheckpointNs = this.encodeCheckpointNamespace(checkpointNs);
-
-    const checkpointRows = await this.resource().list(
-      checkpointId
-        ? Filters.AND(
-            Filters.EQ(r.threadIdField, threadId),
-            Filters.EQ(r.checkpointNamespaceField, storedCheckpointNs),
-            Filters.EQ(r.checkpointIdField, checkpointId),
-            Filters.EQ(r.rowKindField, "checkpoint"),
-          )
-        : Filters.AND(
-            Filters.EQ(r.threadIdField, threadId),
-            Filters.EQ(r.checkpointNamespaceField, storedCheckpointNs),
-            Filters.EQ(r.rowKindField, "checkpoint"),
-      ),
-      1,
-      undefined,
-      [{ field: r.checkpointIdField, direction: "desc" }],
-    );
-
-    const checkpointRow = checkpointRows[0];
-    if (!checkpointRow) {
-      return undefined;
-    }
-
-    const resolvedCheckpointId = String(checkpointRow[r.checkpointIdField]);
-
-    const writesRows = await this.resource().list(
-      Filters.AND(
-        Filters.EQ(r.threadIdField, threadId),
-        Filters.EQ(r.checkpointNamespaceField, storedCheckpointNs),
-        Filters.EQ(r.checkpointIdField, resolvedCheckpointId),
-        Filters.EQ(r.rowKindField, "writes"),
-      ),
-      undefined,
-      undefined,
-      [{ field: r.sequenceField, direction: "asc" }],
-    );
-
-    const pendingWrites: CheckpointPendingWrite[] = writesRows.flatMap((row: CheckpointRow) => {
-      const taskId = String(row[r.taskIdField] ?? "");
-      const write = this.deserialize<PendingWrite>(row[r.writesPayloadField]);
-      if (!write) {
-        return [];
-      }
-
-      const [channel, value] = write;
-      return [[taskId, channel, value]];
-    });
-
-    const parentCheckpointId = checkpointRow[r.parentCheckpointIdField]
-      ? String(checkpointRow[r.parentCheckpointIdField])
-      : null;
-
-    const tuple: CheckpointTuple = {
-      config: this.buildConfig(threadId, checkpointNs, resolvedCheckpointId),
-      checkpoint: this.deserialize<Checkpoint>(
-        checkpointRow[r.checkpointPayloadField],
-      ) as Checkpoint,
-      metadata: (this.deserialize<CheckpointMetadata>(
-        checkpointRow[r.metadataPayloadField],
-      ) ?? {}) as CheckpointMetadata,
-      parentConfig: parentCheckpointId
-        ? this.buildConfig(threadId, checkpointNs, parentCheckpointId)
-        : undefined,
-      pendingWrites,
-    };
-
-    return tuple;
-  }
-
-  async *list(
-    config: RunnableConfig,
-    options?: {
-      before?: RunnableConfig;
-      limit?: number;
-    },
-  ): AsyncGenerator<CheckpointTuple> {
-    const r = this.resourceConfig;
-    const { threadId, checkpointNs } = this.getConfigValues(config);
-    const storedCheckpointNs = this.encodeCheckpointNamespace(checkpointNs);
-    const beforeCheckpointId = options?.before
-      ? this.getConfigValues(options.before).checkpointId
-      : null;
-
-    const filters: Filters[] = [
-      Filters.EQ(r.rowKindField, "checkpoint"),
-      Filters.EQ(r.threadIdField, threadId),
-      Filters.EQ(r.checkpointNamespaceField, storedCheckpointNs),
-    ];
-
-    if (beforeCheckpointId) {
-      filters.push(Filters.LT(r.checkpointIdField, beforeCheckpointId));
-    }
-
-    const rows = await this.resource().list(
-      Filters.AND(...filters),
-      options?.limit,
-      undefined,
-      [{ field: r.checkpointIdField, direction: "desc" }],
-    );
-
-    for (const row of rows) {
-      const tuple = await this.getTuple(
-        this.buildConfig(
-          String(row[r.threadIdField]),
-          this.decodeCheckpointNamespace(row[r.checkpointNamespaceField]),
-          String(row[r.checkpointIdField]),
-        ),
-      );
-
-      if (tuple) {
-        yield tuple;
-      }
-    }
-  }
-
-  async deleteThread(threadId: string, checkpointNs = ""): Promise<void> {
-    const r = this.resourceConfig;
-    const storedCheckpointNs = this.encodeCheckpointNamespace(checkpointNs);
-
-    const rows = await this.resource().list(
-      Filters.AND(
-        Filters.EQ(r.threadIdField, threadId),
-        Filters.EQ(r.checkpointNamespaceField, storedCheckpointNs),
-      ),
-      undefined,
-      undefined,
-      [{ field: r.createdAtField, direction: "desc" }],
-    );
-
-    for (const row of rows) {
-      await this.adminforth
-        .resource(this.pluginOptions.checkpointResource!.resourceId)
-        .delete(row[r.idField]);
-    }
-  }
-}

package/agent/languageDetect.ts

@@ -1,92 +0,0 @@
-import { logger } from "adminforth";
-import type { PluginOptions } from "../types.js";
-
-export type DetectedLanguage = {
-  language: string;
-  code: string; // ISO 639-1
-  ambiguous: boolean;
-};
-
-export type PreviousUserMessage = {
-  text: string;
-};
-
-const USER_LANGUAGE_OUTPUT_SCHEMA = {
-  name: "user_language",
-  strict: true,
-  schema: {
-    type: "object",
-    additionalProperties: false,
-    properties: {
-      language: {
-        type: "string",
-        description: "Full English language name, for example English, Ukrainian, French.",
-      },
-      code: {
-        type: "string",
-        description: "Uppercase ISO 639-1 two-letter language code, for example EN, UK, FR.",
-      },
-      ambiguous: {
-        type: "boolean",
-        description: "True if the user's language cannot be confidently detected from the message.",
-      },
-    },
-    required: ["language", "code", "ambiguous"],
-  },
-} as const;
-
-function parseUserLanguage(content: string | undefined): DetectedLanguage | null {
-  if (!content) {
-    return null;
-  }
-
-  try {
-    const parsed = JSON.parse(content) as DetectedLanguage;
-    return {
-      language: parsed.language,
-      code: parsed.code,
-      ambiguous: parsed.ambiguous,
-    };
-  } catch (error) {
-    logger.warn(`Failed to parse detected user language: ${error instanceof Error ? error.message : String(error)}`);
-    return null;
-  }
-}
-
-export async function detectUserLanguage(
-  completionAdapter: PluginOptions["modes"][number]["completionAdapter"],
-  prompt: string,
-  previousUserMessages: PreviousUserMessage[] = [],
-): Promise<DetectedLanguage | null> {
-  const previousMessages = previousUserMessages.length
-    ? [
-      "",
-      "Previous user messages:",
-      ...previousUserMessages.map((message) => message.text),
-    ]
-    : [];
-  const response = await completionAdapter.complete({
-    content: [
-      "Detect the language the assistant should use for the current user message.",
-      "Use recent conversation context only to resolve short or ambiguous current messages.",
-      "Return only the requested structured output.",
-      "The language must be the full English language name.",
-      "The code must be an uppercase ISO 639-1 two-letter code like UK, EN, FR.",
-      "Set ambiguous to true if the response language cannot be confidently detected from the current message or context.",
-      ...previousMessages,
-      "",
-      "Current user message:",
-      prompt,
-    ].join("\n"),
-    maxTokens: 80,
-    outputSchema: USER_LANGUAGE_OUTPUT_SCHEMA,
-    reasoningEffort: "none",
-  });
-
-  if (response.error) {
-    logger.warn(`Failed to detect user language: ${response.error}`);
-    return null;
-  }
-
-  return parseUserLanguage(response.content);
-}