Merge branch 'main' of github.com:devforth/adminforth into next

Author: yaroslav8765

adminforth/commands/createApp/.env.hbs

@@ -0,0 +1 @@
+# Add only sensitive local environment variables here; non-sensitive local variables should go to .env.local

adminforth/commands/createApp/templates/.env.hbs

@@ -1,3 +1,6 @@
+# Add only non-sensitive local environment variables here so all team members can use them with minimal setup
+# For sensitive local environment variables, use .env and explain to team members how to set them, ideally with a .env.example
+
 ADMINFORTH_SECRET=123
 NODE_ENV=development
 DEBUG_LEVEL=info

adminforth/commands/createApp/templates/.env.local.hbs

@@ -1,3 +1,6 @@
+# Add only non-sensitive production environment variables here so deployed applications can use them
+# Deliver sensitive production environment variables via your deployment platform's process environment
+
 NODE_ENV=production
 DATABASE_URL={{dbUrlProd}}
 {{#if prismaDbUrlProd}}

adminforth/commands/createApp/templates/.env.prod.hbs

@@ -296,6 +296,8 @@ async function writeTemplateFiles(dirname, cwd, useNpm, includePrismaMigrations,
     dbUrlProd, prismaDbUrlProd, sqliteFile
    } = options;
   const packageManagerTemplateData = getPackageManagerTemplateData(useNpm, nodeMajor);
+  const resolvedPrismaDbUrl = includePrismaMigrations ? prismaDbUrl : null;
+  const resolvedPrismaDbUrlProd = includePrismaMigrations ? prismaDbUrlProd : null;
 
   // Build a list of files to generate
   const templateTasks = [
@@ -322,22 +324,22 @@ async function writeTemplateFiles(dirname, cwd, useNpm, includePrismaMigrations,
     {
       src: '.env.local.hbs',
       dest: '.env.local',
-      data: { dbUrl: checkIfDatabaseLocal(dbUrl) ? dbUrl : null, prismaDbUrl },
+      data: { dbUrl: checkIfDatabaseLocal(dbUrl) ? dbUrl : null, prismaDbUrl: resolvedPrismaDbUrl },
     },
     {
       src: '.env.prod.hbs',
       dest: '.env.prod',
-      data: { prismaDbUrlProd, dbUrlProd },
+      data: { prismaDbUrlProd: resolvedPrismaDbUrlProd, dbUrlProd },
     },
     {
       src: 'readme.md.hbs',
       dest: 'README.md',
-      data: { dbUrl, prismaDbUrl, appName, sqliteFile },
+      data: { dbUrl, prismaDbUrl: resolvedPrismaDbUrl, appName, sqliteFile },
     },
     {
       src: 'AGENTS.md.hbs',
       dest: 'AGENTS.md',
-      data: { prismaDbUrl },
+      data: { prismaDbUrl: resolvedPrismaDbUrl },
     },
     {
       src: 'CLAUDE.md.hbs',
@@ -347,7 +349,7 @@ async function writeTemplateFiles(dirname, cwd, useNpm, includePrismaMigrations,
     {
       src: '.agents/skills/adminforth/SKILL.md.hbs',
       dest: '.agents/skills/adminforth/SKILL.md',
-      data: { prismaDbUrl },
+      data: { prismaDbUrl: resolvedPrismaDbUrl },
     },
     {
       src: '.agents/skills/adminforth-permissions/SKILL.md.hbs',
@@ -368,7 +370,7 @@ async function writeTemplateFiles(dirname, cwd, useNpm, includePrismaMigrations,
       // We'll write .env using the same content as .env.sample
       src: '.env.hbs',
       dest: '.env',
-      data: {dbUrl, prismaDbUrl},
+      data: { dbUrl, prismaDbUrl: resolvedPrismaDbUrl },
     },
     {
       src: 'adminuser.ts.hbs',
@@ -504,6 +506,7 @@ function generateFinalInstructionsPnpm(skipPrismaSetup, options) {
   ${chalk.dim('// Go to the project directory')}
   ${chalk.dim('$')}${chalk.cyan(` cd ${options.appName}`)}\n`;
 
+  if (options.includePrismaMigrations)
     instruction += `
   ${chalk.dim('// Generate and apply initial migration')}
   ${chalk.dim('$')}${chalk.cyan(' pnpm makemigration --name init && pnpm migrate:local')}\n`;
@@ -525,6 +528,7 @@ function generateFinalInstructionsNpm(skipPrismaSetup, options) {
   ${chalk.dim('// Go to the project directory')}
   ${chalk.dim('$')}${chalk.cyan(` cd ${options.appName}`)}\n`;
 
+  if (options.includePrismaMigrations)
     instruction += `
   ${chalk.dim('// Generate and apply initial migration')}
   ${chalk.dim('$')}${chalk.cyan(' npm run makemigration -- --name init && npm run migrate:local')}\n`;

adminforth/commands/createApp/utils.js

@@ -205,8 +205,14 @@ class PostgresConnector extends AdminForthBaseConnector implements IAdminForthDa
             if (!value) {
                 return null;
             }
-            if (field._underlineType == 'timestamp' || field._underlineType == 'int') {
-                return dayjs(value.replace(' ', 'T') + 'Z').toISOString();
+            if (field._underlineType == 'timestamp') {
+                if (typeof value == 'string') {
+                    const normalizedValue = value.includes(' ') ? `${value.replace(' ', 'T')}Z` : value;
+                    return dayjs(normalizedValue).toISOString();
+                }
+                return dayjs(value).toISOString();
+            } else if (field._underlineType == 'int') {
+                return dayjs.unix(+value).toISOString();
             } else if (field._underlineType == 'varchar') {
                 return dayjs(value).toISOString();
             } else {

adminforth/dataConnectors/postgres.ts

@@ -284,6 +284,216 @@ Each item in `modes` defines a user-selectable preset in the chat UI. The select
 
 The plugin adds a chat surface to the admin UI, keeps session history per admin user, and shows a mode picker when `modes` are configured.
 
+## Debugging agent turns
+
+Agent debug traces are optional and are intended for auditability and debugging. When enabled, they let you reconstruct why an agent produced a response or made a change by storing the full execution sequence for the turn: LLM steps, tool calls, tool inputs and outputs, token usage, and cache information.
+
+By default, only the user prompt and agent response are persisted. Full debug traces are not stored unless you configure a `debugField`, because they can be large and may significantly increase database size.
+
+Add a `debug` JSON column to the turns resource:
+
+```ts title="./resources/agent_resources/turns.ts"
+import AdminForth, { AdminForthDataTypes } from 'adminforth';
+import type { AdminForthResourceInput, AdminUser } from 'adminforth';
+import { randomUUID } from 'crypto';
+
+async function allowedForSuperAdmins({ adminUser }: { adminUser: AdminUser }): Promise<boolean> {
+  return adminUser.dbUser.role === 'superadmin';
+}
+
+export default {
+  dataSource: 'maindb',
+  table: 'turns',
+  resourceId: 'turns',
+  label: 'Turns',
+  columns: [
+    {
+      name: 'id',
+      primaryKey: true,
+      type: AdminForthDataTypes.STRING,
+      fillOnCreate: () => randomUUID(),
+      showIn: {
+        edit: false,
+        create: false,
+      },
+    },
+    {
+      name: 'session_id',
+      type: AdminForthDataTypes.STRING,
+    },
+    {
+      name: 'created_at',
+      type: AdminForthDataTypes.DATETIME,
+      fillOnCreate: () => (new Date()).toISOString(),
+      showIn: {
+        edit: false,
+        create: false,
+      },
+    },
+    {
+      name: 'prompt',
+      type: AdminForthDataTypes.TEXT,
+    },
+    {
+      name: 'response',
+      type: AdminForthDataTypes.TEXT,
+    },
+    //diff-add
+    {
+      //diff-add
+      name: 'debug',
+      //diff-add
+      type: AdminForthDataTypes.JSON,
+      //diff-add
+      components: {
+        //diff-add
+        show: {
+          //diff-add
+          file: '@@/TurnDebugShow.vue',
+        //diff-add
+        },
+      //diff-add
+      },
+      //diff-add
+      showIn: {
+        //diff-add
+        list: false,
+        //diff-add
+        show: true,
+        //diff-add
+        edit: false,
+        //diff-add
+        create: false,
+        //diff-add
+        filter: false,
+      //diff-add
+      },
+    //diff-add
+    },
+  ],
+  options: {
+    allowedActions: {
+      list: allowedForSuperAdmins,
+      show: allowedForSuperAdmins,
+      create: false,
+      edit: false,
+      delete: false,
+    },
+  },
+} as AdminForthResourceInput;
+```
+
+Add the matching field to your schema:
+
+```prisma title="./schema.prisma"
+model turns {
+  id         String   @id
+  session_id String
+  created_at DateTime
+  prompt     String?
+  response   String?
+  debug      Json? //diff-add
+}
+```
+
+If you use SQLite with Prisma, store the same field as text:
+
+```prisma title="./schema.prisma"
+model turns {
+  id         String   @id
+  session_id String
+  created_at DateTime
+  prompt     String?
+  response   String?
+  debug      String? //diff-add
+}
+```
+
+AdminForth should still define this resource column as `AdminForthDataTypes.JSON`; the SQLite connector serializes it into the text column and parses it back for the renderer.
+
+Run migration:
+
+```bash
+pnpm makemigration --name add-adminforth-agent-turn-debug ; pnpm migrate:local
+```
+
+Tell the plugin where to store debug data:
+
+```ts title="./resources/adminuser.ts"
+new AdminForthAgent({
+  modes: [
+    ...
+  ],
+  sessionResource: {
+    resourceId: 'sessions',
+    idField: 'id',
+    titleField: 'title',
+    turnsField: 'turns',
+    askerIdField: 'asker_id',
+    createdAtField: 'created_at',
+  },
+  turnResource: {
+    resourceId: 'turns',
+    idField: 'id',
+    sessionIdField: 'session_id',
+    createdAtField: 'created_at',
+    promptField: 'prompt',
+    responseField: 'response',
+    //diff-add
+    debugField: 'debug',
+  },
+})
+```
+
+The `debugField` value must match the turns resource column name. You can use another column name, but then use the same name in the resource, database schema, and `debugField`.
+
+Create a renderer in your app custom folder:
+
+```vue title="./custom/TurnDebugShow.vue"
+<template>
+  <div class="space-y-3">
+    <div class="rounded-lg bg-slate-50 p-3 text-sm text-slate-700 dark:bg-slate-800 dark:text-slate-200">
+      <div class="font-semibold text-slate-900 dark:text-white">Agent Debug</div>
+      <div class="mt-1">
+        {{ debugSequences.length }} sequences,
+        {{ totalToolCalls }} tool calls,
+        {{ totalCachedTokens.toLocaleString() }} cached prompt tokens
+      </div>
+    </div>
+
+    <JsonViewer :value="debugSequences" :expandDepth="2" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { JsonViewer } from '@/afcl';
+import type { AdminForthResourceColumnCommon } from '@/types/Common';
+
+type DebugToolCall = {
+  toolName: string;
+};
+
+type DebugSequence = {
+  cachedTokens: number;
+  toolCalls: DebugToolCall[];
+};
+
+const props = defineProps<{
+  column: AdminForthResourceColumnCommon;
+  record: Record<string, DebugSequence[]>;
+}>();
+
+const debugSequences = computed(() => props.record[props.column.name] ?? []);
+const totalToolCalls = computed(() =>
+  debugSequences.value.reduce((sum, sequence) => sum + sequence.toolCalls.length, 0),
+);
+const totalCachedTokens = computed(() =>
+  debugSequences.value.reduce((sum, sequence) => sum + sequence.cachedTokens, 0),
+);
+</script>
+```
+
 # Using with self-hosted models
 
 `CompletionAdapterOpenAIResponses` when works with agent plugin, under the hood uses the LangChain internal proxy called `OpenAIChat` (in LangChain they call it "provider"). This proxy is capable with a fresh versions of OpenAI-compatible Responses APIs, for example [self-hosted latest versions of vLLM installations](https://devforth.io/insights/self-hosted-gpt-real-response-time-token-throughput-and-cost-on-l4-l40s-and-h100-for-gpt-oss-20b/)
@@ -793,4 +1003,3 @@ services:
   If Cloudflare returns a 403 response with `cf-mitigated: challenge` for `<baseURL>/adminapi/v1/agent/speech-response`, the request was blocked before it reached AdminForth. Create a WAF or bot rule exception for authenticated requests to this endpoint, because browser `fetch` calls with `multipart/form-data` cannot complete an HTML challenge page.
 
 ![alt text](image-6.png)
-