@adminforth/agent 2.0.10 → 2.1.0

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

package/agent/middleware/apiBasedTools.ts

@@ -1,174 +0,0 @@
-import { ToolMessage } from "@langchain/core/messages";
-import { isGraphInterrupt } from "@langchain/langgraph";
-import { createMiddleware } from "langchain";
-import { logger, type AdminUser, type IAdminForth } from "adminforth";
-import {
-  formatApiBasedToolCall,
-  type ApiBasedTool,
-} from "../../apiBasedTools.js";
-import {
-  createToolCallTracker,
-  type ToolCallEventSink,
-} from "../toolCallEvents.js";
-import { ALWAYS_AVAILABLE_API_TOOL_NAMES } from "../tools/index.js";
-import { createApiTool } from "../tools/apiTool.js";
-import type { AgentEventEmitter } from "../../agentEvents.js";
-import type { SequenceDebugCollector } from "./sequenceDebug.js";
-import { isAbortError } from "../../errors.js";
-
-function getEnabledApiToolNames(messages: unknown[]) {
-  const enabledToolNames = new Set<string>();
-
-  for (const message of messages) {
-    if (!ToolMessage.isInstance(message) || message.name !== "fetch_tool_schema") {
-      continue;
-    }
-
-    const content =
-      typeof message.content === "string"
-        ? message.content
-        : Array.isArray(message.content)
-          ? message.content
-              .map((block) =>
-                typeof block === "string"
-                  ? block
-                  : "text" in block
-                    ? block.text
-                    : "",
-              )
-              .join("")
-          : "";
-
-    try {
-      const parsed = JSON.parse(content) as { status?: number; name?: string };
-
-      if (parsed.status === 200 && parsed.name) {
-        enabledToolNames.add(parsed.name);
-      }
-    } catch {}
-  }
-
-  return enabledToolNames;
-}
-
-export function createApiBasedToolsMiddleware(
-  apiBasedTools: Record<string, ApiBasedTool>,
-  adminforth: IAdminForth,
-) {
-  const alwaysAvailableApiToolNames = new Set<string>(ALWAYS_AVAILABLE_API_TOOL_NAMES);
-  const dynamicTools = Object.fromEntries(
-    Object.entries(apiBasedTools).map(([toolName, apiBasedTool]) => [
-      toolName,
-      createApiTool(toolName, apiBasedTool),
-    ]),
-  );
-
-  return createMiddleware({
-    name: "ApiBasedToolsMiddleware",
-    async wrapModelCall(request, handler) {
-      const enabledApiToolNames = getEnabledApiToolNames(request.state.messages);
-      const tools = [...enabledApiToolNames]
-        .filter((toolName) => !alwaysAvailableApiToolNames.has(toolName))
-        .map((toolName) => dynamicTools[toolName]);
-      const availableTools = [...request.tools, ...tools];
-
-      logger.info(
-        `AdminForth Agent callable tools: ${availableTools.map((tool) => tool.name).join(", ")}`,
-      );
-
-      return handler({
-        ...request,
-        tools: availableTools,
-      });
-    },
-    async wrapToolCall(request, handler) {
-      const startedAt = Date.now();
-      const toolInput = JSON.stringify(request.toolCall.args ?? {});
-      if (!request.toolCall.id) {
-        throw new Error(`Tool call "${request.toolCall.name}" has no id.`);
-      }
-
-      const toolCallId = request.toolCall.id;
-      const { adminUser, abortSignal, emit, sequenceDebugSink, userTimeZone } = request.runtime.context as {
-        adminUser: AdminUser;
-        abortSignal?: AbortSignal;
-        emit?: AgentEventEmitter;
-        sequenceDebugSink: SequenceDebugCollector;
-        userTimeZone: string;
-      };
-      const emitToolCall: ToolCallEventSink = (event) => {
-        sequenceDebugSink.handleToolCallEvent(event);
-        void emit?.({
-          type: "tool-call",
-          data: event,
-        });
-      };
-      const toolArgs = (request.toolCall.args ?? {}) as Record<string, unknown>;
-      let toolInfo: string | undefined;
-
-      if (request.toolCall.name === "fetch_skill") {
-        toolInfo = `Load ${(toolArgs.skillName as string).split("_").join(" ")} skill`;
-      } else if (request.toolCall.name === "fetch_tool_schema") {
-        toolInfo = `Load ${(toolArgs.toolName as string).split("_").join(" ")} tool `;
-      } else {
-        toolInfo = await formatApiBasedToolCall({
-          adminforth,
-          adminUser,
-          inputs: toolArgs,
-          toolName: request.toolCall.name,
-          userTimeZone,
-        });
-      }
-      const toolCallTracker = createToolCallTracker({
-        emit: emitToolCall,
-        toolCallId,
-        toolName: request.toolCall.name,
-        toolInfo,
-        input: toolArgs,
-        startedAt,
-      });
-      toolCallTracker.start();
-      logger.info(
-        `Invoking tool "${request.toolCall.name}" with input: ${toolInput}`,
-      );
-
-      try {
-
-        const result = getEnabledApiToolNames(request.state.messages).has(request.toolCall.name)
-          ? await handler({
-              ...request,
-              tool: dynamicTools[request.toolCall.name],
-            })
-          : await handler(request);
-
-        toolCallTracker.finishSuccess(result);
-        return result;
-      } catch (error) {
-        if (
-          isGraphInterrupt(error)
-          || abortSignal?.aborted
-          || isAbortError(error)
-        ) {
-          throw error;
-        }
-
-        const message = error instanceof Error ? error.message : String(error);
-
-        logger.error(
-          `Error calling tool "${request.toolCall.name}": ${error instanceof Error ? error.stack ?? error.message : String(error)}`,
-        );
-        toolCallTracker.finishError(`Error: ${message}`);
-        return new ToolMessage({
-          name: request.toolCall.name,
-          tool_call_id: toolCallId,
-          status: "error",
-          content: `Error: ${message}`,
-        })
-      } finally {
-        logger.info(
-          `Tool "${request.toolCall.name}" finished in ${Date.now() - startedAt}ms`,
-        );
-      }
-    },
-  });
-}

package/agent/middleware/openAiResponsesContinuation.ts

@@ -1,92 +0,0 @@
-import { AIMessage } from "@langchain/core/messages";
-import { createMiddleware } from "langchain";
-
-type OpenAiResponsesMetadata = {
-  id?: string;
-};
-
-type OpenAiResponsesContext = {
-  sessionId: string;
-  turnId: string;
-};
-
-function getTurnKey(context: OpenAiResponsesContext) {
-  return `${context.sessionId}:${context.turnId}`;
-}
-
-function getResponseId(message: AIMessage) {
-  const metadata = message.response_metadata as OpenAiResponsesMetadata | undefined;
-  return metadata?.id ?? null;
-}
-
-function getPreviousResponseId(modelSettings?: Record<string, unknown>) {
-  return (modelSettings as { previous_response_id?: string } | undefined)
-    ?.previous_response_id;
-}
-
-function getContinuationMessages<T extends { response_metadata?: unknown }>(
-  messages: T[],
-  previousResponseId: string,
-) {
-  let continuationStartIndex: number | null = null;
-
-  for (let index = messages.length - 1; index >= 0; index -= 1) {
-    const message = messages[index];
-
-    if (
-      AIMessage.isInstance(message) &&
-      (message.response_metadata as OpenAiResponsesMetadata | undefined)?.id ===
-        previousResponseId
-    ) {
-      continuationStartIndex = index + 1;
-      break;
-    }
-  }
-
-  if (continuationStartIndex === null) {
-    return null;
-  }
-
-  return messages.slice(continuationStartIndex);
-}
-
-export function createOpenAiResponsesContinuationMiddleware() {
-  const responseIdsByTurn = new Map<string, string>();
-
-  return createMiddleware({
-    name: "OpenAiResponsesContinuationMiddleware",
-    async wrapModelCall(request, handler) {
-      const context = request.runtime.context as OpenAiResponsesContext;
-      const turnKey = getTurnKey(context);
-      const previousResponseId =
-        getPreviousResponseId(request.modelSettings) ??
-        responseIdsByTurn.get(turnKey);
-      const continuationMessages = previousResponseId
-        ? getContinuationMessages(request.messages, previousResponseId)
-        : null;
-
-      const response = await handler(
-        previousResponseId && continuationMessages
-          ? {
-              ...request,
-              messages: continuationMessages,
-              modelSettings: {
-                ...request.modelSettings,
-                previous_response_id: previousResponseId,
-              },
-            }
-          : request,
-      ) as AIMessage;
-
-      const responseId = getResponseId(response);
-
-      if (responseId) {
-        responseIdsByTurn.set(turnKey, responseId);
-      } else {
-        responseIdsByTurn.delete(turnKey);
-      }
-
-      return response;
-    },
-  });
-}