@adminforth/agent 1.43.28 → 1.44.0

package/agent/checkpointer.ts

@@ -12,6 +12,7 @@ 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(
@@ -227,7 +228,7 @@ export class AdminForthCheckpointSaver extends BaseCheckpointSaver {
       [{ field: r.sequenceField, direction: "asc" }],
     );
 
-    const pendingWrites: CheckpointPendingWrite[] = writesRows.flatMap((row) => {
+    const pendingWrites: CheckpointPendingWrite[] = writesRows.flatMap((row: CheckpointRow) => {
       const taskId = String(row[r.taskIdField] ?? "");
       const write = this.deserialize<PendingWrite>(row[r.writesPayloadField]);
       if (!write) {

package/agent/systemPrompt.ts

@@ -95,8 +95,9 @@ export async function buildAgentSystemPrompt(
   adminforth: IAdminForth,
   hiddenResourceIds: Iterable<string> = [],
 ) {
+  const customComponentsDir = adminforth.config.customization.customComponentsDir ?? "custom";
   const [primarySkills, defaultSkills] = await Promise.all([
-    listProjectSkillManifests(adminforth.config.customization.customComponentsDir),
+    listProjectSkillManifests(customComponentsDir),
     listBundledSkillManifests(),
   ]);
   const adminBasePath = adminforth.config.baseUrlSlashed;

package/agentEvents.ts

@@ -0,0 +1,61 @@
+import type { ToolCallEvent } from "./agent/toolCallEvents.js";
+
+export type AgentEvent =
+  | {
+      type: "turn-started";
+      messageId: string;
+    }
+  | {
+      type: "text-delta";
+      delta: string;
+    }
+  | {
+      type: "reasoning-delta";
+      delta: string;
+    }
+  | {
+      type: "tool-call";
+      data: ToolCallEvent;
+    }
+  | {
+      type: "transcript";
+      text: string;
+      language?: string;
+    }
+  | {
+      type: "response";
+      text: string;
+      sessionId: string;
+      turnId: string;
+    }
+  | {
+      type: "speech-response";
+      transcript: { text: string; language?: string };
+      response: { text: string };
+      sessionId: string;
+      turnId: string;
+    }
+  | {
+      type: "audio-start";
+      mimeType: string;
+      format: string;
+      sampleRate: number;
+      channelCount: number;
+      bitsPerSample: number;
+    }
+  | {
+      type: "audio-delta";
+      value: Uint8Array;
+    }
+  | {
+      type: "audio-done";
+    }
+  | {
+      type: "error";
+      error: string;
+    }
+  | {
+      type: "finish";
+    };
+
+export type AgentEventEmitter = (event: AgentEvent) => void | Promise<void>;

package/agentResponseEvents.ts

@@ -1,206 +1 @@
-import { randomUUID } from "crypto";
-
-import type { ToolCallEvent } from "./agent/toolCallEvents.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;
-};
-
-export function createAgentEventStream(
-  res: AgentEventStreamResponse,
-  options: AgentEventStreamOptions = {},
-) {
-  let isStreamClosed = false;
-  let activeBlock: { type: "text" | "reasoning"; id: string } | null = null;
-
-  res.writeHead(200, {
-    "Content-Type": "text/event-stream",
-    "Cache-Control": "no-cache",
-    "Connection": "keep-alive",
-    ...(options.vercelAiUiMessageStream
-      ? { "x-vercel-ai-ui-message-stream": "v1" }
-      : {}),
-  });
-
-  const stream = {
-    send(obj: unknown) {
-      if (isStreamClosed || res.writableEnded || res.destroyed) {
-        return;
-      }
-
-      res.write(`data: ${JSON.stringify(obj)}\n\n`);
-    },
-
-    endActiveBlock() {
-      if (!activeBlock) {
-        return;
-      }
-
-      stream.send({
-        type: `${activeBlock.type}-end`,
-        id: activeBlock.id,
-      });
-
-      activeBlock = null;
-    },
-
-    startBlock(type: "text" | "reasoning") {
-      if (activeBlock?.type === type) {
-        return activeBlock.id;
-      }
-
-      stream.endActiveBlock();
-
-      const id = randomUUID();
-      activeBlock = { type, id };
-
-      stream.send({
-        type: `${type}-start`,
-        id,
-      });
-
-      return id;
-    },
-
-    start(messageId: string) {
-      stream.send({
-        type: "start",
-        messageId,
-      });
-    },
-
-    textDelta(delta: string) {
-      const textId = stream.startBlock("text");
-      stream.send({
-        type: "text-delta",
-        id: textId,
-        delta,
-      });
-    },
-
-    reasoningDelta(delta: string) {
-      const reasoningId = stream.startBlock("reasoning");
-      stream.send({
-        type: "reasoning-delta",
-        id: reasoningId,
-        delta,
-      });
-    },
-
-    toolCall(event: ToolCallEvent) {
-      if (options.closeActiveBlockOnToolStart && event.phase === "start") {
-        stream.endActiveBlock();
-      }
-
-      stream.send({
-        type: "data-tool-call",
-        data: event,
-      });
-    },
-
-    transcript(text: string, language?: string) {
-      stream.send({
-        type: "transcript",
-        data: {
-          text,
-          language,
-        },
-      });
-    },
-
-    response(text: string, sessionId: string, turnId: string) {
-      stream.send({
-        type: "response",
-        data: {
-          text,
-          sessionId,
-          turnId,
-        },
-      });
-    },
-
-    speechResponse(
-      transcript: { text: string; language?: string },
-      response: { text: string },
-      sessionId: string,
-      turnId: string,
-    ) {
-      stream.send({
-        type: "speech-response",
-        data: {
-          transcript,
-          response,
-          sessionId,
-          turnId,
-        },
-      });
-    },
-
-    audioStart(
-      mimeType: string,
-      format: string,
-      sampleRate: number,
-      channelCount: number,
-      bitsPerSample: number,
-    ) {
-      stream.send({
-        type: "audio-start",
-        data: {
-          mimeType,
-          format,
-          sampleRate,
-          channelCount,
-          bitsPerSample,
-        },
-      });
-    },
-
-    audioDelta(value: Uint8Array) {
-      stream.send({
-        type: "audio-delta",
-        data: {
-          base64: Buffer.from(value).toString("base64"),
-        },
-      });
-    },
-
-    audioDone() {
-      stream.send({
-        type: "audio-done",
-      });
-    },
-
-    error(error: string) {
-      stream.send({
-        type: "error",
-        error,
-      });
-    },
-
-    end() {
-      if (isStreamClosed || res.writableEnded || res.destroyed) {
-        return;
-      }
-
-      stream.endActiveBlock();
-      stream.send({
-        type: "finish",
-      });
-
-      res.write("data: [DONE]\n\n");
-      isStreamClosed = true;
-      res.end();
-    },
-  };
-
-  return stream;
-}
+export { createSseEventEmitter } from "./surfaces/web-sse/createSseEventEmitter.js";

package/apiBasedTools.ts

@@ -169,6 +169,7 @@ export type ApiBasedToolCallParams = {
   abortSignal?: AbortSignal;
   inputs?: Record<string, unknown>;
   userTimeZone?: string;
+  acceptLanguage?: string;
 };
 
 export type ApiBasedTool = {
@@ -516,8 +517,9 @@ async function callOpenApiSchema(params: {
   schema: RegisteredApiToolSchema;
   toolName: string;
   userTimeZone?: string;
+  acceptLanguage?: string;
 }) {
-  const { adminforth, adminUser, abortSignal, inputs, schema, toolName, userTimeZone } = params;
+  const { adminforth, adminUser, abortSignal, inputs, schema, toolName, userTimeZone, acceptLanguage } = params;
   const method = schema.method.toUpperCase();
   const normalizedInputs = normalizeDateTimeInputsToUtc(
     (inputs ?? {}) as Record<string, unknown>,
@@ -535,12 +537,13 @@ async function callOpenApiSchema(params: {
 
   const response = createDirectToolResponse();
   logger.info(`Calling OpenAPI tool "${toolName}" with direct handler`);
+  const lang = acceptLanguage ?? "en";
   const tr = (
     msg: string,
     category: string,
     trParams: unknown,
     pluralizationNumber?: number,
-  ) => adminforth.tr(msg, category, undefined, trParams, pluralizationNumber);
+  ) => adminforth.tr(msg, category, lang, trParams, pluralizationNumber);
   const output = await schema.handler({
     body,
     query,
@@ -614,7 +617,7 @@ export function prepareApiBasedTools(
       description: schema.description,
       input_schema: schema.request_schema,
       output_schema: schema.response_schema,
-      call: async ({ adminUser, adminuser, abortSignal, inputs, userTimeZone } = {}) => {
+      call: async ({ adminUser, adminuser, abortSignal, inputs, userTimeZone, acceptLanguage } = {}) => {
         if (isHiddenResourceCall(hiddenResourceIdSet, inputs)) {
           return YAML.stringify({
             error: 'RESOURCE_NOT_AVAILABLE',
@@ -630,6 +633,7 @@ export function prepareApiBasedTools(
           toolName,
           inputs,
           userTimeZone,
+          acceptLanguage,
         });
 
         const processedOutput = await applyToolOverride({

package/dist/agent/checkpointer.d.ts

@@ -0,0 +1,29 @@
+import type { RunnableConfig } from "@langchain/core/runnables";
+import { BaseCheckpointSaver, type Checkpoint, type CheckpointMetadata, type CheckpointTuple, type PendingWrite } from "@langchain/langgraph-checkpoint";
+import type { PluginOptions } from "../types.js";
+export declare class AdminForthCheckpointSaver extends BaseCheckpointSaver {
+    private readonly adminforth;
+    private readonly pluginOptions;
+    constructor(adminforth: any, pluginOptions: PluginOptions);
+    private get resourceConfig();
+    private resource;
+    private serialize;
+    private deserialize;
+    private now;
+    private encodeCheckpointNamespace;
+    private decodeCheckpointNamespace;
+    private getConfigValues;
+    private buildConfig;
+    private buildCheckpointRowId;
+    private buildWritesRowId;
+    private getWriteIndex;
+    private isDuplicateCheckpointWriteError;
+    put(config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata, _newVersions: Record<string, unknown>): Promise<RunnableConfig>;
+    putWrites(config: RunnableConfig, writes: PendingWrite[], taskId: string): Promise<void>;
+    getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined>;
+    list(config: RunnableConfig, options?: {
+        before?: RunnableConfig;
+        limit?: number;
+    }): AsyncGenerator<CheckpointTuple>;
+    deleteThread(threadId: string, checkpointNs?: string): Promise<void>;
+}

package/dist/agent/languageDetect.d.ts

@@ -0,0 +1,10 @@
+import type { PluginOptions } from "../types.js";
+export type DetectedLanguage = {
+    language: string;
+    code: string;
+    ambiguous: boolean;
+};
+export type PreviousUserMessage = {
+    text: string;
+};
+export declare function detectUserLanguage(completionAdapter: PluginOptions["modes"][number]["completionAdapter"], prompt: string, previousUserMessages?: PreviousUserMessage[]): Promise<DetectedLanguage | null>;

package/dist/agent/middleware/apiBasedTools.d.ts

@@ -0,0 +1,3 @@
+import { type IAdminForth } from "adminforth";
+import { type ApiBasedTool } from "../../apiBasedTools.js";
+export declare function createApiBasedToolsMiddleware(apiBasedTools: Record<string, ApiBasedTool>, adminforth: IAdminForth): import("langchain").AgentMiddleware<undefined, undefined, unknown, readonly (import("@langchain/core/tools").ClientTool | import("@langchain/core/tools").ServerTool)[]>;

package/dist/agent/middleware/openAiResponsesContinuation.d.ts

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

package/dist/agent/middleware/sequenceDebug.d.ts

@@ -0,0 +1,46 @@
+import type { ToolCallEvent } from "../toolCallEvents.js";
+export type SequenceDebugResultType = "tool_calls" | "final_text";
+type SequenceDebugToolCall = {
+    toolCallId: string;
+    toolName: string;
+    input: string;
+    output: string | null;
+    error: string | null;
+};
+export type SequenceDebug = {
+    sequenceId: number;
+    startedAt: string;
+    prompt: string;
+    promptTokens: number;
+    reasoning: string;
+    reasoningTokens: number;
+    text: string;
+    textTokens: number;
+    cachedTokens: number;
+    responseId: string | null;
+    toolCalls: SequenceDebugToolCall[];
+    endedAt: string;
+    resultType: SequenceDebugResultType;
+};
+type SequenceDebugModelCall = {
+    promptTokens: number;
+    reasoning: string;
+    reasoningTokens: number;
+    text: string;
+    textTokens: number;
+    cachedTokens: number;
+    responseId: string | null;
+    resultType: SequenceDebugResultType;
+};
+export type SequenceDebugModelCallSink = {
+    handleModelCallStart: (prompt: string) => void;
+    handleModelCallComplete: (params: SequenceDebugModelCall) => void;
+};
+export type SequenceDebugCollector = SequenceDebugModelCallSink & {
+    handleToolCallEvent: (event: ToolCallEvent) => void;
+    flush: () => void;
+    getHistory: () => SequenceDebug[];
+};
+export declare function createSequenceDebugCollector(): SequenceDebugCollector;
+export declare function createSequenceDebugMiddleware(sink: SequenceDebugModelCallSink): import("langchain").AgentMiddleware<undefined, undefined, unknown, readonly (import("@langchain/core/tools").ClientTool | import("@langchain/core/tools").ServerTool)[]>;
+export {};

package/dist/agent/simpleAgent.d.ts

@@ -0,0 +1,61 @@
+import type { BaseChatModel } from "@langchain/core/language_models/chat_models";
+import { type AdminUser, type CompletionAdapter, type IAdminForth } from "adminforth";
+import { type BaseCheckpointSaver, type Messages } from "@langchain/langgraph";
+import { z } from "zod";
+import { createSequenceDebugMiddleware, type SequenceDebugModelCallSink } from "./middleware/sequenceDebug.js";
+import type { ApiBasedTool } from "../apiBasedTools.js";
+import type { ToolCallEventSink } from "./toolCallEvents.js";
+import type { CurrentPageContext } from "./tools/getUserLocation.js";
+export declare const contextSchema: z.ZodObject<{
+    adminUser: z.ZodCustom<AdminUser, AdminUser>;
+    userTimeZone: z.ZodString;
+    sessionId: z.ZodString;
+    turnId: z.ZodString;
+    abortSignal: z.ZodOptional<z.ZodCustom<AbortSignal, AbortSignal>>;
+    currentPage: z.ZodOptional<z.ZodCustom<CurrentPageContext, CurrentPageContext>>;
+    emitToolCallEvent: z.ZodCustom<ToolCallEventSink, ToolCallEventSink>;
+}, z.core.$strip>;
+export type AgentChatModel = BaseChatModel<any, any>;
+export type AgentModelPurpose = "primary" | "summary";
+export type AgentModeCompletionAdapter = CompletionAdapter & {
+    getLangChainAgentSpec(params: {
+        maxTokens: number;
+        purpose: AgentModelPurpose;
+    }): Promise<{
+        model: unknown;
+        middleware?: unknown[];
+    }> | {
+        model: unknown;
+        middleware?: unknown[];
+    };
+};
+type AgentMiddleware = ReturnType<typeof createSequenceDebugMiddleware>;
+type AgentChatModelSpec = {
+    model: AgentChatModel;
+    middleware: AgentMiddleware[];
+};
+export declare function createAgentChatModel(params: {
+    adapter: CompletionAdapter;
+    maxTokens: number;
+    purpose: AgentModelPurpose;
+}): Promise<AgentChatModelSpec>;
+export declare function callAgent(params: {
+    name: string;
+    model: AgentChatModel;
+    summaryModel: AgentChatModel;
+    modelMiddleware?: AgentMiddleware[];
+    checkpointer?: BaseCheckpointSaver;
+    messages: Messages;
+    adminUser: AdminUser;
+    adminforth: IAdminForth;
+    apiBasedTools: Record<string, ApiBasedTool>;
+    customComponentsDir: string;
+    sessionId: string;
+    turnId: string;
+    currentPage?: CurrentPageContext;
+    userTimeZone: string;
+    abortSignal?: AbortSignal;
+    emitToolCallEvent: ToolCallEventSink;
+    sequenceDebugSink: SequenceDebugModelCallSink;
+}): Promise<import("@langchain/core/utils/stream").IterableReadableStream<[import("langchain").BaseMessage<import("@langchain/core/messages").MessageStructure<import("@langchain/core/messages").MessageToolSet>, import("@langchain/core/messages").MessageType>, Record<string, any>]>>;
+export {};

package/dist/agent/skills/registry.d.ts

@@ -0,0 +1,13 @@
+export interface AgentSkillManifest {
+    directoryName: string;
+    name: string;
+    description: string;
+    instructions: string;
+}
+export declare function getProjectSkillsDirectoryPath(customComponentsDir: string): string;
+export declare function getProjectPluginSkillsDirectoryPath(customComponentsDir: string): string;
+export declare function listBundledSkillManifests(): Promise<AgentSkillManifest[]>;
+export declare function listProjectSkillManifests(customComponentsDir: string): Promise<AgentSkillManifest[]>;
+export declare function listSkillManifests(customComponentsDir: string): Promise<AgentSkillManifest[]>;
+export declare function loadSkillManifest(skillName: string, customComponentsDir: string): Promise<AgentSkillManifest | null>;
+export declare function loadSkillMarkdown(skillName: string, customComponentsDir: string): Promise<string | null>;

package/dist/agent/systemPrompt.d.ts

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

package/dist/agent/systemPrompt.js

@@ -73,8 +73,10 @@ function formatSkills(skills, label) {
 }
 export function buildAgentSystemPrompt(adminforth_1) {
     return __awaiter(this, arguments, void 0, function* (adminforth, hiddenResourceIds = []) {
+        var _a;
+        const customComponentsDir = (_a = adminforth.config.customization.customComponentsDir) !== null && _a !== void 0 ? _a : "custom";
         const [primarySkills, defaultSkills] = yield Promise.all([
-            listProjectSkillManifests(adminforth.config.customization.customComponentsDir),
+            listProjectSkillManifests(customComponentsDir),
             listBundledSkillManifests(),
         ]);
         const adminBasePath = adminforth.config.baseUrlSlashed;

package/dist/agent/toolCallEvents.d.ts

@@ -0,0 +1,27 @@
+export type ToolCallEvent = {
+    toolCallId: string;
+    toolName: string;
+    toolInfo?: string;
+    phase: "start";
+    input: string;
+} | {
+    toolCallId: string;
+    toolName: string;
+    phase: "end";
+    durationMs: number;
+    output: string | null;
+    error: string | null;
+};
+export type ToolCallEventSink = (event: ToolCallEvent) => void;
+export declare function createToolCallTracker(params: {
+    emit: ToolCallEventSink;
+    toolCallId?: string;
+    toolName: string;
+    toolInfo?: string;
+    input?: Record<string, unknown>;
+    startedAt?: number;
+}): {
+    start(): void;
+    finishSuccess(output: unknown): void;
+    finishError(error: unknown): void;
+};

package/dist/agent/tools/apiTool.d.ts

@@ -0,0 +1,6 @@
+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: {};
+    readonly additionalProperties: true;
+}, unknown, unknown, string, unknown, string>;

package/dist/agent/tools/fetchSkill.d.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+export declare function createFetchSkillTool(customComponentsDir: string): Promise<import("langchain").DynamicStructuredTool<z.ZodObject<{
+    skillName: z.ZodString;
+}, z.core.$strip>, {
+    skillName: string;
+}, {
+    skillName: string;
+}, string, unknown, "fetch_skill">>;

package/dist/agent/tools/fetchToolSchema.d.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+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>, {
+    toolName: string;
+}, {
+    toolName: string;
+}, string, unknown, "fetch_tool_schema">>;

package/dist/agent/tools/getUserLocation.d.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+export type CurrentPageContext = {
+    path: string;
+    fullPath: string;
+    title: string;
+    url: string;
+};
+export declare function createGetUserLocationTool(): import("langchain").DynamicStructuredTool<z.ZodObject<{}, z.core.$strip>, Record<string, never>, Record<string, never>, string, unknown, "get_user_location">;

package/dist/agent/tools/index.d.ts

@@ -0,0 +1,4 @@
+import type { ClientTool } from "@langchain/core/tools";
+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>): Promise<ClientTool[]>;

package/dist/agentEvents.d.ts

@@ -0,0 +1,52 @@
+import type { ToolCallEvent } from "./agent/toolCallEvents.js";
+export type AgentEvent = {
+    type: "turn-started";
+    messageId: string;
+} | {
+    type: "text-delta";
+    delta: string;
+} | {
+    type: "reasoning-delta";
+    delta: string;
+} | {
+    type: "tool-call";
+    data: ToolCallEvent;
+} | {
+    type: "transcript";
+    text: string;
+    language?: string;
+} | {
+    type: "response";
+    text: string;
+    sessionId: string;
+    turnId: string;
+} | {
+    type: "speech-response";
+    transcript: {
+        text: string;
+        language?: string;
+    };
+    response: {
+        text: string;
+    };
+    sessionId: string;
+    turnId: string;
+} | {
+    type: "audio-start";
+    mimeType: string;
+    format: string;
+    sampleRate: number;
+    channelCount: number;
+    bitsPerSample: number;
+} | {
+    type: "audio-delta";
+    value: Uint8Array;
+} | {
+    type: "audio-done";
+} | {
+    type: "error";
+    error: string;
+} | {
+    type: "finish";
+};
+export type AgentEventEmitter = (event: AgentEvent) => void | Promise<void>;

package/dist/agentEvents.js

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

package/dist/agentResponseEvents.d.ts

@@ -0,0 +1 @@
+export { createSseEventEmitter } from "./surfaces/web-sse/createSseEventEmitter.js";