@mastra/oracledb 0.5.4-alpha.0 → 0.5.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -3,7 +3,7 @@ name: mastra-oracledb
3
3
  description: Documentation for @mastra/oracledb. Use when working with @mastra/oracledb APIs, configuration, or implementation.
4
4
  metadata:
5
5
  package: "@mastra/oracledb"
6
- version: "0.5.4-alpha.0"
6
+ version: "0.5.4"
7
7
  ---
8
8
 
9
9
  ## When to use
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "0.5.4-alpha.0",
2
+ "version": "0.5.4",
3
3
  "package": "@mastra/oracledb",
4
4
  "exports": {},
5
5
  "modules": {}
@@ -203,7 +203,7 @@ const memory = new Memory({
203
203
 
204
204
  ### Retries and failure policy
205
205
 
206
- Observer and Reflector model calls are retried on transient provider errors, and a turn aborts if they still fail. Each stage is controlled independently by:
206
+ Observer and Reflector model calls are retried on transient provider errors. By default, a synchronous observation or reflection that still fails aborts the turn. Each stage is controlled independently by:
207
207
 
208
208
  - `maxRetries`: retries after the initial model call (default `8`).
209
209
  - `failurePolicy`: what happens once retries are exhausted, either `'abort'` (default) or `'continue'`.
@@ -231,7 +231,9 @@ With `failurePolicy: 'continue'`, Mastra retries as configured, reports the fail
231
231
 
232
232
  A provider outage usually takes out both stages, so set the policy on both if you want the turn to survive one.
233
233
 
234
- This policy applies only to Observer and Reflector model and provider failures in synchronous, resource-scoped, and buffered observation. Persistence, indexing, transform, locking, invariant, and explicit abort failures remain fatal. It doesn't prevent the underlying provider or network error, change `blockAfter`, or change attachment handling.
234
+ This policy applies only to Observer and Reflector model and provider failures when observation or reflection runs synchronously: at `blockAfter`, when async buffering is disabled, and in resource-scoped observation. In those paths, persistence, indexing, transform, locking, invariant, and explicit abort failures remain fatal. It doesn't prevent the underlying provider or network error, change `blockAfter`, or change attachment handling.
235
+
236
+ Background (async buffered) observation and reflection failures never stop the turn, whatever the policy. They're reported as `om_buffering_failed`, and the failed input stays pending. If it keeps growing, it reaches `blockAfter`, where synchronous observation applies `failurePolicy`.
235
237
 
236
238
  > **Warning:** `'continue'` has no backstop for a sustained outage. Unobserved messages stay pending and keep accruing in the main agent's context. A long outage moves the failure from the memory layer to the model's context limit.
237
239
 
@@ -403,6 +403,28 @@ Memory uses a single embedder for both storing and recalling messages, so pick o
403
403
 
404
404
  Multilingual E5 produces 1024-dimensional vectors. Your vector index must be created with matching dimensions, and E5 vectors can't be mixed with vectors from another embedder in the same index.
405
405
 
406
+ FastEmbed models embed at most 512 tokens per input (roughly 2,000 to 2,500 characters of English text). Longer inputs are truncated, so text past the limit doesn't affect the embedding and can't be found by semantic recall. The AI SDK v3 FastEmbed models return a warning when this happens. The legacy v1 and v2 models don't. If you embed long documents with FastEmbed, chunk them to fit the window, for example with `maxSize: 1500` in `MDocument.chunk()`.
407
+
408
+ ### Setting the embedding dimension
409
+
410
+ To name the vector index, Memory needs the embedder's output dimension. By default it finds the dimension by embedding a short probe string the first time semantic recall is set up, once per `Memory` instance. If you already know the dimension, set `embeddingDimension`. Memory then skips the probe, so startup makes no embedding call and doesn't depend on the embedding provider being reachable:
411
+
412
+ ```ts
413
+ import { Memory } from '@mastra/memory'
414
+
415
+ const memory = new Memory({
416
+ embedder: 'openai/text-embedding-3-small',
417
+ embeddingDimension: 1536,
418
+ options: {
419
+ semanticRecall: true,
420
+ },
421
+ })
422
+ ```
423
+
424
+ The index name is the same whether the dimension is configured or probed, so existing indexes keep working.
425
+
426
+ The value must match the vectors the embedder returns. Memory compares it with the first real embedding, and on a mismatch it throws a `MASTRA_MEMORY_EMBEDDING_DIMENSION_MISMATCH` error naming both values before creating or querying any index. Update `embeddingDimension` whenever you change the embedding model or its output dimension.
427
+
406
428
  ## PostgreSQL index optimization
407
429
 
408
430
  When using PostgreSQL as your vector store, you can optimize semantic recall performance by configuring the vector index. This is particularly important for large-scale deployments with thousands of messages.
@@ -217,7 +217,7 @@ const paragraphMemory = new Memory({
217
217
 
218
218
  Working memory can also be defined using a structured schema instead of a Markdown template. A [Standard JSON Schema](https://standardschema.dev/json-schema) ([Zod](https://zod.dev/), [Valibot](https://valibot.dev/), [ArkType](https://arktype.io/), etc.). When using a schema, the agent will see and update working memory as a JSON object matching your schema.
219
219
 
220
- **Requirement:** You must specify either `template` or `schema`, but not both.
220
+ You can specify either `template` or `schema`, but not both. If you omit both, Mastra uses the default working memory template.
221
221
 
222
222
  ### Example: Schema-Based Working Memory
223
223
 
package/dist/index.cjs CHANGED
@@ -16,7 +16,7 @@ var __copyProps = (to, from, except, desc) => {
16
16
  }
17
17
  return to;
18
18
  };
19
- var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
19
+ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
20
20
  value: mod,
21
21
  enumerable: true
22
22
  }) : target, mod));
@@ -3456,10 +3456,11 @@ const MAX_CLAIM_ATTEMPTS = 5;
3456
3456
  */
3457
3457
  async function assertRunFence(client, claimsTable, fence, operation) {
3458
3458
  const row = await client.oneOrNone(`SELECT generation AS "generation", "ownerId" FROM ${claimsTable} WHERE "runId" = :runId FOR UPDATE`, { runId: fence.runId });
3459
- if (!(0, _mastra_core_storage.matchesRunFence)(row ? {
3459
+ const current = row ? {
3460
3460
  generation: Number(row.generation),
3461
3461
  ownerId: String(row.ownerId)
3462
- } : null, fence)) throw new _mastra_core_storage.RunFenceConflictError(fence, operation);
3462
+ } : null;
3463
+ if (!(0, _mastra_core_storage.matchesRunFence)(current, fence)) throw new _mastra_core_storage.RunFenceConflictError(fence, operation);
3463
3464
  }
3464
3465
  /**
3465
3466
  * Runs `write` in a transaction, behind the fence check when it carries a
@@ -5785,13 +5786,14 @@ var MemoryOracle = class MemoryOracle extends _mastra_core_storage.MemoryStorage
5785
5786
  await this.ctx.db.withConnection((connection) => backfillObservationalMemorySupersededBy(this.ctx, connection));
5786
5787
  }
5787
5788
  async prune(policies, options) {
5789
+ const targets = (0, _mastra_core_storage.resolveRetentionTargets)({
5790
+ policies,
5791
+ descriptor: MemoryOracle.retentionTables,
5792
+ order: ["runFences"]
5793
+ });
5788
5794
  return (0, _mastra_core_storage.executeRetentionPrune)({
5789
5795
  domain: "memory",
5790
- targets: (0, _mastra_core_storage.resolveRetentionTargets)({
5791
- policies,
5792
- descriptor: MemoryOracle.retentionTables,
5793
- order: ["runFences"]
5794
- }),
5796
+ targets,
5795
5797
  options,
5796
5798
  cutoffFor: (target, now) => (0, _mastra_core_storage.retentionCutoffMs)(target.policy, now),
5797
5799
  deleteBatch: (target, cutoff, limit) => this.db.pruneBatch({
@@ -7177,9 +7179,7 @@ function addStatusFilter(conditions, tableAlias, status) {
7177
7179
  case _mastra_core_storage.TraceStatus.RUNNING:
7178
7180
  conditions.push(`${qcol(tableAlias, "endedAt")} IS NULL AND ${jsonValueIsAbsent(qcol(tableAlias, "error"))}`);
7179
7181
  break;
7180
- case _mastra_core_storage.TraceStatus.SUCCESS:
7181
- conditions.push(`${qcol(tableAlias, "endedAt")} IS NOT NULL AND ${jsonValueIsAbsent(qcol(tableAlias, "error"))}`);
7182
- break;
7182
+ case _mastra_core_storage.TraceStatus.SUCCESS: conditions.push(`${qcol(tableAlias, "endedAt")} IS NOT NULL AND ${jsonValueIsAbsent(qcol(tableAlias, "error"))}`);
7183
7183
  }
7184
7184
  }
7185
7185
  function addChildErrorFilter(conditions, tableName, hasChildError) {
@@ -7238,13 +7238,14 @@ var ObservabilityOracle = class ObservabilityOracle extends _mastra_core_storage
7238
7238
  ];
7239
7239
  }
7240
7240
  async prune(policies, options) {
7241
+ const targets = (0, _mastra_core_storage.resolveRetentionTargets)({
7242
+ policies,
7243
+ descriptor: ObservabilityOracle.retentionTables,
7244
+ order: ["spans", "logs"]
7245
+ });
7241
7246
  return (0, _mastra_core_storage.executeRetentionPrune)({
7242
7247
  domain: "observability",
7243
- targets: (0, _mastra_core_storage.resolveRetentionTargets)({
7244
- policies,
7245
- descriptor: ObservabilityOracle.retentionTables,
7246
- order: ["spans", "logs"]
7247
- }),
7248
+ targets,
7248
7249
  options,
7249
7250
  cutoffFor: (target, now) => new Date((0, _mastra_core_storage.retentionCutoffMs)(target.policy, now)),
7250
7251
  deleteBatch: (target, cutoff, limit) => this.db.pruneBatch({
@@ -8423,13 +8424,14 @@ var WorkflowsOracle = class WorkflowsOracle extends _mastra_core_storage.Workflo
8423
8424
  await this.createIndexes();
8424
8425
  }
8425
8426
  async prune(policies, options) {
8427
+ const targets = (0, _mastra_core_storage.resolveRetentionTargets)({
8428
+ policies,
8429
+ descriptor: WorkflowsOracle.retentionTables,
8430
+ order: ["runOwnership"]
8431
+ });
8426
8432
  return (0, _mastra_core_storage.executeRetentionPrune)({
8427
8433
  domain: "workflows",
8428
- targets: (0, _mastra_core_storage.resolveRetentionTargets)({
8429
- policies,
8430
- descriptor: WorkflowsOracle.retentionTables,
8431
- order: ["runOwnership"]
8432
- }),
8434
+ targets,
8433
8435
  options,
8434
8436
  cutoffFor: (target, now) => (0, _mastra_core_storage.retentionCutoffMs)(target.policy, now),
8435
8437
  deleteBatch: (target, cutoff, limit) => this.db.pruneBatch({