@adminforth/agent 1.0.0

package/dist/agent/tools/fetchSkill.js

@@ -0,0 +1,51 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { tool } from "langchain";
+import { z } from "zod";
+import { listSkillManifests, loadSkillMarkdown, } from "../skills/registry.js";
+const fetchSkillSchema = z.object({
+    skillName: z
+        .string()
+        .describe("Name of the custom AdminForth skill to load, for example fetch_data or mutate_data."),
+});
+function serializeSkillManifests(skillManifests) {
+    return skillManifests.map((skill) => ({
+        name: skill.name,
+        description: skill.description,
+    }));
+}
+export function createFetchSkillTool(customComponentsDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const availableSkills = yield listSkillManifests(customComponentsDir);
+        const availableSkillNames = availableSkills.map((skill) => skill.name);
+        return tool((_a) => __awaiter(this, [_a], void 0, function* ({ skillName }) {
+            try {
+                const skillMarkdown = yield loadSkillMarkdown(skillName, customComponentsDir);
+                if (!skillMarkdown) {
+                    return [
+                        `Skill "${skillName}" not found.`,
+                        "Available skills:",
+                        JSON.stringify(serializeSkillManifests(availableSkills), null, 2),
+                    ].join("\n");
+                }
+                return skillMarkdown;
+            }
+            catch (error) {
+                return `Failed to load skill "${skillName}": ${error instanceof Error ? error.message : String(error)}`;
+            }
+        }), {
+            name: "fetch_skill",
+            description: `Fetch the raw SKILL.md content for a custom AdminForth skill by name.${availableSkillNames.length > 0
+                ? ` Available skills: ${availableSkillNames.join(", ")}.`
+                : ""}`,
+            schema: fetchSkillSchema,
+        });
+    });
+}

package/dist/agent/tools/fetchToolSchema.js

@@ -0,0 +1,36 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { tool } from "langchain";
+import { z } from "zod";
+import { serializeApiBasedTool, } from "../../apiBasedTools.js";
+const fetchToolSchemaSchema = z.object({
+    toolName: z
+        .string()
+        .describe("Name of the API-based tool to load, for example get_resource."),
+});
+export function createFetchToolSchemaTool(apiBasedTools) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return tool((_a) => __awaiter(this, [_a], void 0, function* ({ toolName }) {
+            const toolDefinition = apiBasedTools[toolName];
+            if (!toolDefinition) {
+                return JSON.stringify({
+                    status: 404,
+                    error: "TOOL_NOT_FOUND",
+                    message: `Tool "${toolName}" not found.`,
+                }, null, 2);
+            }
+            return JSON.stringify(Object.assign({ status: 200, name: toolName }, serializeApiBasedTool(toolDefinition)), null, 2);
+        }), {
+            name: "fetch_tool_schema",
+            description: "Fetch the schema for an API-based AdminForth tool by name and load it for later use.",
+            schema: fetchToolSchemaSchema,
+        });
+    });
+}

package/dist/agent/tools/index.js

@@ -0,0 +1,28 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { createFetchSkillTool } from "./fetchSkill.js";
+import { createFetchToolSchemaTool } from "./fetchToolSchema.js";
+import { createApiTool } from "./apiTool.js";
+export const ALWAYS_AVAILABLE_API_TOOL_NAMES = ["get_resource"];
+export function createAgentTools(customComponentsDir, apiBasedTools) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return [
+            ...ALWAYS_AVAILABLE_API_TOOL_NAMES.map((toolName) => {
+                const apiBasedTool = apiBasedTools[toolName];
+                if (!apiBasedTool) {
+                    throw new Error(`Required base API tool "${toolName}" is missing.`);
+                }
+                return createApiTool(toolName, apiBasedTool);
+            }),
+            yield createFetchSkillTool(customComponentsDir),
+            yield createFetchToolSchemaTool(apiBasedTools),
+        ];
+    });
+}

package/dist/apiBasedTools.js

@@ -0,0 +1,412 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { AdminForthDataTypes, } from 'adminforth';
+import dayjs from 'dayjs';
+import timezone from 'dayjs/plugin/timezone.js';
+import utc from 'dayjs/plugin/utc.js';
+import { PassThrough } from 'stream';
+import { inspect } from 'util';
+import YAML from 'yaml';
+dayjs.extend(utc);
+dayjs.extend(timezone);
+const DEFAULT_USER_TIME_ZONE = 'UTC';
+const TOOL_OVERRIDES = {
+    get_resource: {
+        wipe_frontend_specific_data: [
+            'resource.columns[].filterOptions',
+            'resource.columns[].components',
+            'resource.options.actions[].customComponent',
+            'resource.options.pageInjections',
+        ],
+    },
+    get_resource_data: {
+        post_process_response: (_a) => __awaiter(void 0, [_a], void 0, function* ({ output, inputs, invokeTool, userTimeZone }) {
+            if (hasToolError(output)) {
+                return output;
+            }
+            const resourceId = inputs === null || inputs === void 0 ? void 0 : inputs.resourceId;
+            const getResourceOutput = yield invokeTool('get_resource', {
+                inputs: { resourceId },
+            });
+            const dateTimeColumnNames = getDateTimeColumnNames(getResourceOutput);
+            if (dateTimeColumnNames.length === 0) {
+                return output;
+            }
+            const localizedTimeZone = userTimeZone !== null && userTimeZone !== void 0 ? userTimeZone : DEFAULT_USER_TIME_ZONE;
+            const response = output;
+            formatDateTimeColumns(response.data, dateTimeColumnNames, localizedTimeZone);
+            return response;
+        }),
+    },
+};
+function sanitizeForYaml(value) {
+    const traversalStack = [];
+    const serialized = JSON.stringify(value, function (_key, nestedValue) {
+        if (typeof nestedValue === 'function' || typeof nestedValue === 'symbol' || nestedValue === undefined) {
+            return undefined;
+        }
+        if (typeof nestedValue === 'bigint') {
+            return nestedValue.toString();
+        }
+        if (typeof nestedValue !== 'object' || nestedValue === null) {
+            return nestedValue;
+        }
+        if (nestedValue instanceof Map) {
+            return Object.fromEntries(nestedValue);
+        }
+        if (nestedValue instanceof Set) {
+            return Array.from(nestedValue.values());
+        }
+        while (traversalStack.length > 0 && traversalStack[traversalStack.length - 1] !== this) {
+            traversalStack.pop();
+        }
+        if (traversalStack.includes(nestedValue)) {
+            return undefined;
+        }
+        traversalStack.push(nestedValue);
+        return nestedValue;
+    });
+    if (serialized === undefined) {
+        return null;
+    }
+    return JSON.parse(serialized);
+}
+export function serializeUnknownError(error) {
+    var _a, _b;
+    if (error instanceof Error) {
+        const errorWithCause = error;
+        const errorRecord = error;
+        const serialized = {
+            name: error.name,
+            message: error.message,
+            stack: error.stack,
+        };
+        if (errorWithCause.cause !== undefined) {
+            serialized.cause = serializeUnknownError(errorWithCause.cause);
+        }
+        for (const key of Object.getOwnPropertyNames(error)) {
+            if (key in serialized) {
+                continue;
+            }
+            serialized[key] = errorRecord[key];
+        }
+        return serialized;
+    }
+    if (typeof error === 'object' && error !== null) {
+        return {
+            type: (_b = (_a = error.constructor) === null || _a === void 0 ? void 0 : _a.name) !== null && _b !== void 0 ? _b : 'Object',
+            inspected: inspect(error, { depth: 6, breakLength: 120 }),
+        };
+    }
+    return {
+        type: typeof error,
+        value: error,
+    };
+}
+function wipePath(target, pathParts) {
+    if (!target || typeof target !== 'object' || pathParts.length === 0) {
+        return;
+    }
+    const [currentPart, ...rest] = pathParts;
+    const isArrayTraversal = currentPart.endsWith('[]');
+    const key = isArrayTraversal ? currentPart.slice(0, -2) : currentPart;
+    const targetRecord = target;
+    if (!(key in targetRecord)) {
+        return;
+    }
+    if (rest.length === 0) {
+        delete targetRecord[key];
+        return;
+    }
+    const nextValue = targetRecord[key];
+    if (isArrayTraversal) {
+        if (!Array.isArray(nextValue)) {
+            return;
+        }
+        for (const item of nextValue) {
+            wipePath(item, rest);
+        }
+        return;
+    }
+    wipePath(nextValue, rest);
+}
+function hasToolError(output) {
+    return typeof output === 'object' && output !== null && 'error' in output;
+}
+function getDateTimeColumnNames(output) {
+    const resource = output.resource;
+    return resource.columns
+        .filter((column) => column.type === AdminForthDataTypes.DATETIME)
+        .map((column) => column.name);
+}
+function formatGmtOffset(offsetMinutes) {
+    const sign = offsetMinutes >= 0 ? '+' : '-';
+    const absoluteOffsetMinutes = Math.abs(offsetMinutes);
+    const hours = Math.floor(absoluteOffsetMinutes / 60);
+    const minutes = absoluteOffsetMinutes % 60;
+    if (minutes === 0) {
+        return `GMT${sign}${hours}`;
+    }
+    return `GMT${sign}${hours}:${String(minutes).padStart(2, '0')}`;
+}
+function formatDateTimeValue(value, userTimeZone) {
+    const localizedValue = dayjs.utc(value).tz(userTimeZone);
+    return `${localizedValue.format('DD MMM YYYY, HH:mm:ss.SSS')} (${formatGmtOffset(localizedValue.utcOffset())})`;
+}
+function formatDateTimeColumns(rows, dateTimeColumnNames, userTimeZone) {
+    for (const row of rows) {
+        for (const columnName of dateTimeColumnNames) {
+            const value = row[columnName];
+            if (typeof value === 'string' && value) {
+                row[columnName] = formatDateTimeValue(value, userTimeZone);
+            }
+        }
+    }
+}
+function applyToolOverride(params) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const { adminforth, adminUser, capturedEndpointsByToolName, httpExtra, inputs, output, toolName, userTimeZone, } = params;
+        const sanitizedOutput = sanitizeForYaml(output);
+        const override = TOOL_OVERRIDES[toolName];
+        if (!override) {
+            return sanitizedOutput;
+        }
+        for (const path of (_a = override.wipe_frontend_specific_data) !== null && _a !== void 0 ? _a : []) {
+            wipePath(sanitizedOutput, path.split('.'));
+        }
+        if (!override.post_process_response) {
+            return sanitizedOutput;
+        }
+        const postProcessedOutput = yield override.post_process_response({
+            output: sanitizedOutput,
+            adminUser,
+            httpExtra,
+            inputs,
+            userTimeZone,
+            invokeTool: (nestedToolName_1, ...args_1) => __awaiter(this, [nestedToolName_1, ...args_1], void 0, function* (nestedToolName, nestedParams = {}) {
+                var _a, _b, _c;
+                const nestedEndpoint = capturedEndpointsByToolName[nestedToolName];
+                if (!nestedEndpoint) {
+                    throw new Error(`Tool ${nestedToolName} is not registered`);
+                }
+                const nestedInputs = (_a = nestedParams.inputs) !== null && _a !== void 0 ? _a : inputs;
+                const nestedHttpExtra = (_b = nestedParams.httpExtra) !== null && _b !== void 0 ? _b : httpExtra;
+                const nestedUserTimeZone = (_c = nestedParams.userTimeZone) !== null && _c !== void 0 ? _c : userTimeZone;
+                const nestedOutput = yield callCapturedEndpoint({
+                    adminforth,
+                    endpoint: nestedEndpoint,
+                    adminUser,
+                    inputs: nestedInputs,
+                    httpExtra: nestedHttpExtra,
+                });
+                return applyToolOverride({
+                    adminforth,
+                    adminUser,
+                    capturedEndpointsByToolName,
+                    httpExtra: nestedHttpExtra,
+                    inputs: nestedInputs,
+                    output: nestedOutput,
+                    toolName: nestedToolName,
+                    userTimeZone: nestedUserTimeZone,
+                });
+            }),
+        });
+        return sanitizeForYaml(postProcessedOutput);
+    });
+}
+function endpointPathToToolName(path) {
+    return path
+        .replace(/^\/+/, '')
+        .replace(/[^a-zA-Z0-9_]+/g, '_')
+        .replace(/^_+|_+$/g, '');
+}
+function normalizeCookies(cookies) {
+    if (!cookies) {
+        return [];
+    }
+    if (Array.isArray(cookies)) {
+        return cookies;
+    }
+    return Object.entries(cookies).map(([key, value]) => ({ key, value }));
+}
+function createToolResponse(baseResponse) {
+    return {
+        headers: [],
+        status: 200,
+        message: undefined,
+        setHeader(name, value) {
+            this.headers.push([name, value]);
+            baseResponse === null || baseResponse === void 0 ? void 0 : baseResponse.setHeader(name, value);
+        },
+        setStatus(code, message) {
+            this.status = code;
+            this.message = message;
+            baseResponse === null || baseResponse === void 0 ? void 0 : baseResponse.setStatus(code, message);
+        },
+        blobStream() {
+            var _a;
+            return (_a = baseResponse === null || baseResponse === void 0 ? void 0 : baseResponse.blobStream()) !== null && _a !== void 0 ? _a : new PassThrough();
+        },
+    };
+}
+function createRawExpressRequest(params) {
+    const cookieHeader = params.cookies
+        .map(({ key, value }) => `${key}=${value}`)
+        .join('; ');
+    return {
+        adminUser: params.adminUser,
+        body: params.body,
+        destroyed: false,
+        headers: Object.assign(Object.assign({}, params.headers), (cookieHeader ? { cookie: cookieHeader } : {})),
+        method: params.method.toUpperCase(),
+        on: () => undefined,
+        query: params.query,
+        url: params.requestUrl,
+    };
+}
+function createRawExpressResponse(response) {
+    const rawResponse = {
+        destroyed: false,
+        on: () => undefined,
+        setHeader(name, value) {
+            response.setHeader(name, value);
+            return rawResponse;
+        },
+        status(code) {
+            response.status = code;
+            return rawResponse;
+        },
+        send(message) {
+            response.message = message;
+            return rawResponse;
+        },
+        json(payload) {
+            response.jsonPayload = payload;
+            response.message = JSON.stringify(payload);
+            return rawResponse;
+        },
+        write: () => true,
+        writeHead: () => rawResponse,
+        writableEnded: false,
+        end: () => rawResponse,
+    };
+    return rawResponse;
+}
+function callCapturedEndpoint(params) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c, _d;
+        const { adminforth, adminUser, endpoint, httpExtra, inputs } = params;
+        const response = createToolResponse(httpExtra === null || httpExtra === void 0 ? void 0 : httpExtra.response);
+        const headers = Object.assign({ 'content-type': 'application/json' }, ((_a = httpExtra === null || httpExtra === void 0 ? void 0 : httpExtra.headers) !== null && _a !== void 0 ? _a : {}));
+        const body = ((_b = inputs !== null && inputs !== void 0 ? inputs : httpExtra === null || httpExtra === void 0 ? void 0 : httpExtra.body) !== null && _b !== void 0 ? _b : {});
+        const query = (_c = httpExtra === null || httpExtra === void 0 ? void 0 : httpExtra.query) !== null && _c !== void 0 ? _c : {};
+        const cookies = normalizeCookies(httpExtra === null || httpExtra === void 0 ? void 0 : httpExtra.cookies);
+        const requestUrl = (_d = httpExtra === null || httpExtra === void 0 ? void 0 : httpExtra.requestUrl) !== null && _d !== void 0 ? _d : `${adminforth.config.baseUrl}/adminapi/v1${endpoint.path}`;
+        const abortController = new AbortController();
+        const rawRequest = createRawExpressRequest({
+            adminUser,
+            body,
+            cookies,
+            headers,
+            method: endpoint.method,
+            query,
+            requestUrl,
+        });
+        const rawResponse = createRawExpressResponse(response);
+        const acceptLanguage = headers['accept-language'];
+        const tr = (msg, category = 'default', translationParams, pluralizationNumber) => adminforth.tr(msg, category, acceptLanguage, translationParams, pluralizationNumber);
+        const output = yield endpoint.handler({
+            body,
+            adminUser,
+            query,
+            headers,
+            cookies,
+            response,
+            requestUrl,
+            abortSignal: abortController.signal,
+            _raw_express_req: rawRequest,
+            _raw_express_res: rawResponse,
+            tr,
+        });
+        if (output !== undefined && output !== null) {
+            return output;
+        }
+        if (response.jsonPayload !== undefined) {
+            return response.jsonPayload;
+        }
+        if (response.message !== undefined) {
+            return response.message;
+        }
+        return {
+            headers: response.headers,
+            status: response.status,
+        };
+    });
+}
+export function prepareApiBasedTools(adminforth) {
+    const capturedEndpoints = [];
+    const captureServer = {
+        setupSpaServer() { },
+        endpoint: ((options) => {
+            var _a;
+            const normalizedResponseSchema = (_a = options.response_schema) !== null && _a !== void 0 ? _a : options.responce_schema;
+            if (!options.request_schema && !normalizedResponseSchema) {
+                return;
+            }
+            capturedEndpoints.push(Object.assign(Object.assign({}, options), { response_schema: normalizedResponseSchema, normalizedResponseSchema }));
+        }),
+    };
+    adminforth.setupEndpoints(captureServer);
+    const apiBasedTools = {};
+    const capturedEndpointsByToolName = Object.fromEntries(capturedEndpoints.map((endpoint) => [endpointPathToToolName(endpoint.path), endpoint]));
+    for (const endpoint of capturedEndpoints) {
+        const toolName = endpointPathToToolName(endpoint.path);
+        apiBasedTools[toolName] = {
+            description: endpoint.description,
+            input_schema: endpoint.request_schema,
+            input_schma: endpoint.request_schema,
+            output_schema: endpoint.normalizedResponseSchema,
+            call: (...args_1) => __awaiter(this, [...args_1], void 0, function* ({ adminUser, adminuser, inputs, httpExtra, userTimeZone } = {}) {
+                const output = yield callCapturedEndpoint({
+                    adminforth,
+                    endpoint,
+                    adminUser: adminUser !== null && adminUser !== void 0 ? adminUser : adminuser,
+                    inputs,
+                    httpExtra,
+                });
+                const processedOutput = yield applyToolOverride({
+                    adminforth,
+                    adminUser: adminUser !== null && adminUser !== void 0 ? adminUser : adminuser,
+                    capturedEndpointsByToolName,
+                    httpExtra,
+                    inputs,
+                    output,
+                    toolName,
+                    userTimeZone,
+                });
+                return YAML.stringify(processedOutput);
+            }),
+        };
+    }
+    return apiBasedTools;
+}
+export function serializeApiBasedTool(tool) {
+    if (!tool) {
+        return null;
+    }
+    return {
+        description: tool.description,
+        input_schema: tool.input_schema,
+        input_schma: tool.input_schma,
+        output_schema: tool.output_schema,
+        call: '[Function]',
+    };
+}