@mastra/pg 1.1.0-alpha.1 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,113 @@
 # @mastra/pg
 
+## 1.1.0
+
+### Minor Changes
+
+- Restructured stored agents to use a thin metadata record with versioned configuration snapshots. ([#12488](https://github.com/mastra-ai/mastra/pull/12488))
+
+  The agent record now only stores metadata fields (id, status, activeVersionId, authorId, metadata, timestamps). All configuration fields (name, instructions, model, tools, etc.) live exclusively in version snapshot rows, enabling full version history and rollback.
+
+  **Key changes:**
+  - Stored Agent records are now thin metadata-only (StorageAgentType)
+  - All config lives in version snapshots (StorageAgentSnapshotType)
+  - New resolved type (StorageResolvedAgentType) merges agent record + active version config
+  - Renamed `ownerId` to `authorId` for multi-tenant filtering
+  - Changed `memory` field type from `string` to `Record<string, unknown>`
+  - Added `status` field ('draft' | 'published') to agent records
+  - Flattened CreateAgent/UpdateAgent input types (config fields at top level, no nested snapshot)
+  - Version config columns are top-level in the agent_versions table (no single snapshot jsonb column)
+  - List endpoints return resolved agents (thin record + active version config)
+  - Auto-versioning on update with retention limits and race condition handling
+
+- Added dynamic agent management with CRUD operations and version tracking ([#12038](https://github.com/mastra-ai/mastra/pull/12038))
+
+  **New Features:**
+  - Create, edit, and delete agents directly from the Mastra Studio UI
+  - Full version history for agents with compare and restore capabilities
+  - Visual diff viewer to compare agent configurations across versions
+  - Agent creation modal with comprehensive configuration options (model selection, instructions, tools, workflows, sub-agents, memory)
+  - AI-powered instruction enhancement
+
+  **Storage:**
+  - New storage interfaces for stored agents and agent versions
+  - PostgreSQL, LibSQL, and MongoDB implementations included
+  - In-memory storage for development and testing
+
+  **API:**
+  - RESTful endpoints for agent CRUD operations
+  - Version management endpoints (create, list, activate, restore, delete, compare)
+  - Automatic versioning on agent updates when enabled
+
+  **Client SDK:**
+  - JavaScript client with full support for stored agents and versions
+  - Type-safe methods for all CRUD and version operations
+
+  **Usage Example:**
+
+  ```typescript
+  // Server-side: Configure storage
+  import { Mastra } from '@mastra/core';
+  import { PgAgentsStorage } from '@mastra/pg';
+
+  const mastra = new Mastra({
+    agents: { agentOne },
+    storage: {
+      agents: new PgAgentsStorage({
+        connectionString: process.env.DATABASE_URL,
+      }),
+    },
+  });
+
+  // Client-side: Use the SDK
+  import { MastraClient } from '@mastra/client-js';
+
+  const client = new MastraClient({ baseUrl: 'http://localhost:3000' });
+
+  // Create a stored agent
+  const agent = await client.createStoredAgent({
+    name: 'Customer Support Agent',
+    description: 'Handles customer inquiries',
+    model: { provider: 'ANTHROPIC', name: 'claude-sonnet-4-5' },
+    instructions: 'You are a helpful customer support agent...',
+    tools: ['search', 'email'],
+  });
+
+  // Create a version snapshot
+  await client.storedAgent(agent.id).createVersion({
+    name: 'v1.0 - Initial release',
+    changeMessage: 'First production version',
+  });
+
+  // Compare versions
+  const diff = await client.storedAgent(agent.id).compareVersions('version-1', 'version-2');
+  ```
+
+  **Why:**
+  This feature enables teams to manage agents dynamically without code changes, making it easier to iterate on agent configurations and maintain a complete audit trail of changes.
+
+- Added `status` field to `listTraces` response. The status field indicates the trace state: `success` (completed without error), `error` (has error), or `running` (still in progress). This makes it easier to filter and display traces by their current state without having to derive it from the `error` and `endedAt` fields. ([#12213](https://github.com/mastra-ai/mastra/pull/12213))
+
+### Patch Changes
+
+- Stored agent edits no longer fail silently. PATCH requests now save changes correctly. ([#12504](https://github.com/mastra-ai/mastra/pull/12504))
+
+- Fix PATCH request JSON-body handling in `@mastra/client-js` so stored agent edit flows work correctly. Fix stored agent schema migration in `@mastra/libsql` and `@mastra/pg` to drop and recreate the versions table when the old snapshot-based schema is detected, clean up stale draft records from partial create failures, and remove lingering legacy tables. Restores create and edit flows for stored agents. ([#12504](https://github.com/mastra-ai/mastra/pull/12504))
+
+- Updated dependencies [[`90fc0e5`](https://github.com/mastra-ai/mastra/commit/90fc0e5717cb280c2d4acf4f0410b510bb4c0a72), [`1cf5d2e`](https://github.com/mastra-ai/mastra/commit/1cf5d2ea1b085be23e34fb506c80c80a4e6d9c2b), [`b99ceac`](https://github.com/mastra-ai/mastra/commit/b99ceace2c830dbdef47c8692d56a91954aefea2), [`deea43e`](https://github.com/mastra-ai/mastra/commit/deea43eb1366d03a864c5e597d16a48592b9893f), [`833ae96`](https://github.com/mastra-ai/mastra/commit/833ae96c3e34370e58a1e979571c41f39a720592), [`943772b`](https://github.com/mastra-ai/mastra/commit/943772b4378f625f0f4e19ea2b7c392bd8e71786), [`b5c711b`](https://github.com/mastra-ai/mastra/commit/b5c711b281dd1fb81a399a766bc9f86c55efc13e), [`3efbe5a`](https://github.com/mastra-ai/mastra/commit/3efbe5ae20864c4f3143457f4f3ee7dc2fa5ca76), [`1e49e7a`](https://github.com/mastra-ai/mastra/commit/1e49e7ab5f173582154cb26b29d424de67d09aef), [`751eaab`](https://github.com/mastra-ai/mastra/commit/751eaab4e0d3820a94e4c3d39a2ff2663ded3d91), [`69d8156`](https://github.com/mastra-ai/mastra/commit/69d81568bcf062557c24471ce26812446bec465d), [`60d9d89`](https://github.com/mastra-ai/mastra/commit/60d9d899e44b35bc43f1bcd967a74e0ce010b1af), [`5c544c8`](https://github.com/mastra-ai/mastra/commit/5c544c8d12b08ab40d64d8f37b3c4215bee95b87), [`771ad96`](https://github.com/mastra-ai/mastra/commit/771ad962441996b5c43549391a3e6a02c6ddedc2), [`2b0936b`](https://github.com/mastra-ai/mastra/commit/2b0936b0c9a43eeed9bef63e614d7e02ee803f7e), [`3b04f30`](https://github.com/mastra-ai/mastra/commit/3b04f3010604f3cdfc8a0674731700ad66471cee), [`97e26de`](https://github.com/mastra-ai/mastra/commit/97e26deaebd9836647a67b96423281d66421ca07), [`ac9ec66`](https://github.com/mastra-ai/mastra/commit/ac9ec6672779b2e6d4344e415481d1a6a7d4911a), [`10523f4`](https://github.com/mastra-ai/mastra/commit/10523f4882d9b874b40ce6e3715f66dbcd4947d2), [`cb72d20`](https://github.com/mastra-ai/mastra/commit/cb72d2069d7339bda8a0e76d4f35615debb07b84), [`42856b1`](https://github.com/mastra-ai/mastra/commit/42856b1c8aeea6371c9ee77ae2f5f5fe34400933), [`66f33ff`](https://github.com/mastra-ai/mastra/commit/66f33ff68620018513e499c394411d1d39b3aa5c), [`ab3c190`](https://github.com/mastra-ai/mastra/commit/ab3c1901980a99910ca9b96a7090c22e24060113), [`d4f06c8`](https://github.com/mastra-ai/mastra/commit/d4f06c85ffa5bb0da38fb82ebf3b040cc6b4ec4e), [`0350626`](https://github.com/mastra-ai/mastra/commit/03506267ec41b67add80d994c0c0fcce93bbc75f), [`bc9fa00`](https://github.com/mastra-ai/mastra/commit/bc9fa00859c5c4a796d53a0a5cae46ab4a3072e4), [`f46a478`](https://github.com/mastra-ai/mastra/commit/f46a4782f595949c696569e891f81c8d26338508), [`90fc0e5`](https://github.com/mastra-ai/mastra/commit/90fc0e5717cb280c2d4acf4f0410b510bb4c0a72), [`f05a3a5`](https://github.com/mastra-ai/mastra/commit/f05a3a5cf2b9a9c2d40c09cb8c762a4b6cd5d565), [`a291da9`](https://github.com/mastra-ai/mastra/commit/a291da9363efd92dafd8775dccb4f2d0511ece7a), [`c5d71da`](https://github.com/mastra-ai/mastra/commit/c5d71da1c680ce5640b1a7f8ca0e024a4ab1cfed), [`07042f9`](https://github.com/mastra-ai/mastra/commit/07042f9f89080f38b8f72713ba1c972d5b1905b8), [`0423442`](https://github.com/mastra-ai/mastra/commit/0423442b7be2dfacba95890bea8f4a810db4d603)]:
+  - @mastra/core@1.1.0
+
+## 1.1.0-alpha.2
+
+### Patch Changes
+
+- Stored agent edits no longer fail silently. PATCH requests now save changes correctly. ([#12504](https://github.com/mastra-ai/mastra/pull/12504))
+
+- Fix PATCH request JSON-body handling in `@mastra/client-js` so stored agent edit flows work correctly. Fix stored agent schema migration in `@mastra/libsql` and `@mastra/pg` to drop and recreate the versions table when the old snapshot-based schema is detected, clean up stale draft records from partial create failures, and remove lingering legacy tables. Restores create and edit flows for stored agents. ([#12504](https://github.com/mastra-ai/mastra/pull/12504))
+
+- Updated dependencies:
+  - @mastra/core@1.1.0-alpha.2
+
 ## 1.1.0-alpha.1
 
 ### Minor Changes

package/dist/docs/README.md

@@ -33,4 +33,4 @@ docs/
 ## Version
 
 Package: @mastra/pg
-Version: 1.1.0-alpha.1
+Version: 1.1.0

package/dist/docs/SKILL.md

@@ -5,7 +5,7 @@ description: Documentation for @mastra/pg. Includes links to type definitions an
 
 # @mastra/pg Documentation
 
-> **Version**: 1.1.0-alpha.1
+> **Version**: 1.1.0
 > **Package**: @mastra/pg
 
 ## Quick Navigation

package/dist/docs/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1.0-alpha.1",
+  "version": "1.1.0",
   "package": "@mastra/pg",
   "exports": {},
   "modules": {}

package/dist/index.cjs

@@ -3143,10 +3143,124 @@ var AgentsPG = class _AgentsPG extends storage.AgentsStorage {
     }
   }
   async init() {
+    await this.#migrateFromLegacySchema();
+    await this.#migrateVersionsSchema();
     await this.#db.createTable({ tableName: storage.TABLE_AGENTS, schema: storage.TABLE_SCHEMAS[storage.TABLE_AGENTS] });
     await this.#db.createTable({ tableName: storage.TABLE_AGENT_VERSIONS, schema: storage.TABLE_SCHEMAS[storage.TABLE_AGENT_VERSIONS] });
+    await this.#db.alterTable({
+      tableName: storage.TABLE_AGENTS,
+      schema: storage.TABLE_SCHEMAS[storage.TABLE_AGENTS],
+      ifNotExists: ["status", "authorId"]
+    });
     await this.createDefaultIndexes();
     await this.createCustomIndexes();
+    await this.#cleanupStaleDrafts();
+  }
+  /**
+   * Migrates from the legacy flat agent schema (where config fields like name, instructions, model
+   * were stored directly on mastra_agents) to the new versioned schema (thin agent record + versions table).
+   */
+  async #migrateFromLegacySchema() {
+    const fullTableName = getTableName2({ indexName: storage.TABLE_AGENTS, schemaName: getSchemaName2(this.#schema) });
+    const fullVersionsTableName = getTableName2({
+      indexName: storage.TABLE_AGENT_VERSIONS,
+      schemaName: getSchemaName2(this.#schema)
+    });
+    const legacyTableName = getTableName2({
+      indexName: `${storage.TABLE_AGENTS}_legacy`,
+      schemaName: getSchemaName2(this.#schema)
+    });
+    const hasLegacyColumns = await this.#db.hasColumn(storage.TABLE_AGENTS, "name");
+    if (hasLegacyColumns) {
+      await this.#db.client.none(`ALTER TABLE ${fullTableName} RENAME TO "${storage.TABLE_AGENTS}_legacy"`);
+      await this.#db.client.none(`DROP TABLE IF EXISTS ${fullVersionsTableName}`);
+    }
+    const legacyExists = await this.#db.hasColumn(`${storage.TABLE_AGENTS}_legacy`, "name");
+    if (!legacyExists) return;
+    const oldAgents = await this.#db.client.manyOrNone(`SELECT * FROM ${legacyTableName}`);
+    await this.#db.createTable({ tableName: storage.TABLE_AGENTS, schema: storage.TABLE_SCHEMAS[storage.TABLE_AGENTS] });
+    await this.#db.createTable({ tableName: storage.TABLE_AGENT_VERSIONS, schema: storage.TABLE_SCHEMAS[storage.TABLE_AGENT_VERSIONS] });
+    for (const row of oldAgents) {
+      const agentId = row.id;
+      if (!agentId) continue;
+      const versionId = crypto.randomUUID();
+      const now = /* @__PURE__ */ new Date();
+      await this.#db.client.none(
+        `INSERT INTO ${fullTableName} (id, status, "activeVersionId", "authorId", metadata, "createdAt", "updatedAt")
+         VALUES ($1, $2, $3, $4, $5, $6, $7)
+         ON CONFLICT (id) DO NOTHING`,
+        [
+          agentId,
+          "published",
+          versionId,
+          row.ownerId ?? row.authorId ?? null,
+          row.metadata ? JSON.stringify(row.metadata) : null,
+          row.createdAt ?? now,
+          row.updatedAt ?? now
+        ]
+      );
+      await this.#db.client.none(
+        `INSERT INTO ${fullVersionsTableName}
+         (id, "agentId", "versionNumber", name, description, instructions, model, tools,
+          "defaultOptions", workflows, agents, "integrationTools", "inputProcessors",
+          "outputProcessors", memory, scorers, "changedFields", "changeMessage", "createdAt")
+         VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19)
+         ON CONFLICT (id) DO NOTHING`,
+        [
+          versionId,
+          agentId,
+          1,
+          row.name ?? agentId,
+          row.description ?? null,
+          row.instructions ?? "",
+          row.model ? JSON.stringify(row.model) : "{}",
+          row.tools ? JSON.stringify(row.tools) : null,
+          row.defaultOptions ? JSON.stringify(row.defaultOptions) : null,
+          row.workflows ? JSON.stringify(row.workflows) : null,
+          row.agents ? JSON.stringify(row.agents) : null,
+          row.integrationTools ? JSON.stringify(row.integrationTools) : null,
+          row.inputProcessors ? JSON.stringify(row.inputProcessors) : null,
+          row.outputProcessors ? JSON.stringify(row.outputProcessors) : null,
+          row.memory ? JSON.stringify(row.memory) : null,
+          row.scorers ? JSON.stringify(row.scorers) : null,
+          null,
+          "Migrated from legacy schema",
+          row.createdAt ?? now
+        ]
+      );
+    }
+    await this.#db.client.none(`DROP TABLE IF EXISTS ${legacyTableName}`);
+  }
+  /**
+   * Migrates the agent_versions table from the old snapshot-based schema (single `snapshot` JSON column)
+   * to the new flat schema (individual config columns). This handles the case where the agents table
+   * was already migrated but the versions table still has the old schema.
+   */
+  async #migrateVersionsSchema() {
+    const hasSnapshotColumn = await this.#db.hasColumn(storage.TABLE_AGENT_VERSIONS, "snapshot");
+    if (!hasSnapshotColumn) return;
+    const fullVersionsTableName = getTableName2({
+      indexName: storage.TABLE_AGENT_VERSIONS,
+      schemaName: getSchemaName2(this.#schema)
+    });
+    const legacyTableName = getTableName2({
+      indexName: `${storage.TABLE_AGENTS}_legacy`,
+      schemaName: getSchemaName2(this.#schema)
+    });
+    await this.#db.client.none(`DROP TABLE IF EXISTS ${fullVersionsTableName}`);
+    await this.#db.client.none(`DROP TABLE IF EXISTS ${legacyTableName}`);
+  }
+  /**
+   * Removes stale draft agent records that have no activeVersionId.
+   * These are left behind when createAgent partially fails (inserts thin record
+   * but fails to create the version due to schema mismatch).
+   */
+  async #cleanupStaleDrafts() {
+    try {
+      const fullTableName = getTableName2({ indexName: storage.TABLE_AGENTS, schemaName: getSchemaName2(this.#schema) });
+      await this.#db.client.none(`DELETE FROM ${fullTableName} WHERE status = 'draft' AND "activeVersionId" IS NULL`);
+    } catch {
+    }
   }
   /**
    * Creates custom user-defined indexes for this domain's tables.