@dudousxd/nestjs-agent-store-drizzle 0.24.0 → 0.25.0

package/README.md

@@ -237,3 +237,100 @@ for the full model.
 ## License
 
 MIT © Davide Carvalho
+
+
+Action preflight confirmations persist in the nullable `agent_tool_call.confirmation` JSON column.
+The schema helper adds this column to existing databases. Hosts managing their own migrations must
+add it before upgrading (`JSONB` on PostgreSQL, `JSON` on MySQL, JSON text on SQLite). The stored
+confirmation is returned in `StoredMessage.approvals` so a reload uses the same wording.
+
+### Durable action proposals
+
+`DrizzleAgentStore` also implements the optional core `ActionProposalStore` capability.
+Its `createActionProposal`, scoped get/list, immutable decision, lease claim/renewal,
+and settlement methods persist to the independent `agent_action_proposal` table;
+no persisted thread, message, or run is required. The standalone
+`DrizzleActionProposalStore` exposes the same methods when only this capability is needed.
+Both accept an optional second constructor argument `{ clock: () => number }` for a
+trusted server clock (default `Date.now`); never pass a request timestamp as that clock.
+
+Creation is replay-safe against the original canonical JSON snapshot. A proposal ID
+is globally unique, and every read or mutation checks tenant, actor, and thread scope.
+Approval and queued execution commit together in one version-fenced SQL update.
+Claims/recovery increment a generation and issue a new token; renewal and settlement
+require both and an unexpired lease. Expiry is inclusive (`now >= expiresAt`).
+A contended caller transaction can return `conflict` after bounded CAS retries;
+retry from a fresh transaction when its repeatable-read snapshot is stale.
+The stable `idempotencyKey` survives recovery: delivery is at least once, so the tool
+must enforce idempotency for its external effect. This storage capability does not
+start a worker or change the agent loop.
+
+For existing databases, run `ensureAgentSchema(db)` to add the new table and its
+scope/creation-order index without altering existing data. Lists filter and limit in
+SQL (default 100, maximum 1000), with UTF16 lexical ID ordering for equal creation
+times. Logical proposal IDs are limited to 255 UTF16 code units by the core contract.
+If you own migrations,
+include `agent_action_proposal` from `agentSchema`, `pgAgentSchema`, or
+`mysqlAgentSchema` (or the corresponding `agentSchemaDdl(dialect)` statements).
+The physical primary key and scope key are SHA-256 digests; original identifiers
+remain in the canonical JSON text snapshot and are matched exactly, including
+trailing spaces,
+independently of MySQL collation padding. Text storage preserves valid JSON strings
+containing NUL or lone surrogates on every dialect. Decision audit and execution
+work share
+the snapshot column, fenced by the numeric `version` column. Existing table schemas
+and fixture callers remain compatible.
+
+Worker discovery is available on `DrizzleAgentStore` and `DrizzleActionProposalStore`
+through the privileged `claimNextActionProposal({ workerId, leaseMs })` and
+`expireActionProposals({ limit })` methods. Do not expose these unscoped methods on
+public routes. Discovery selects at most 32 queued or expired-lease candidates;
+expiry selects at most `limit` (1–1000) pending proposals due at the trusted store
+clock. Existing scoped, version-fenced mutations decide which worker wins.
+
+Upgrading an existing proposal table requires the additive nullable
+`execution_status`, `lease_expires_at`, and `proposal_expires_at` columns, the
+`discovery_index_version` column with default 0, and the execution/expiry indexes
+from the exported schema. `ensureAgentSchema` adds these definitions; hosts using
+Drizzle migrations must include them in their forward migration. Stop old writers,
+apply the DDL, then repeat the bounded backfill before starting new workers:
+
+```ts
+while (await store.backfillActionProposalDiscoveryIndex({ limit: 1000 })) {
+  // Each batch derives metadata from the canonical payload under its row version.
+}
+```
+
+New writes maintain index version 1 and all discovery metadata atomically with the
+proposal snapshot. Backfill increments the row version without changing the
+proposal payload, timestamps, or audit. It does not invoke transitions or execute
+tools. This upgrade does not support mixed old and new writers: old writers cannot
+maintain the new indexes. Discovery deliberately excludes rows awaiting backfill;
+it never performs an implicit, unbounded migration.
+
+### Independent approval runtime
+
+`actionApprovalMode: 'independent'` requires proposal discovery, atomic replacement,
+terminal outcome admission and the thread queue on the same database. This adapter
+advertises admission support for better-sqlite3, node-postgres, mysql2 and libSQL;
+other Drizzle drivers retain blocking behavior and fail independent configuration.
+Synchronous SQLite transaction callbacks complete synchronously, including both
+assistant insertion and the delivery compare-and-set. PostgreSQL/MySQL admission
+locks the proposal and conversation before checking the delivery lease again.
+
+The updated schemas add nullable `delivery_status`, `delivery_lease_expires_at`,
+`replacement_group_key`, `outcome_id_key` and their indexes to proposals,
+`action_proposal_outcome` to messages, `proposal_id` to tool calls and
+`ui_capabilities` to queued messages. `ensureAgentSchema` adds missing columns and
+indexes; applications owning drizzle-kit migrations must include the same additions.
+Outcomes use escaped TEXT/LONGTEXT metadata to preserve JSON strings exactly.
+
+Delivery writes one assistant fact and its UI together with its admitted marker,
+waits while a user turn owns the conversation and deduplicates retries. Replacement
+only closes pending proposals in the same exact scope, tool and replacement group.
+An existing transaction passed as the database handle remains the transaction
+owner: a caller rollback also rolls back replacement or admission. External side
+effects remain at least once; use the stable tool-context idempotency key.
+
+See [the shared setup and rollout guide](../../docs/independent-approvals.md) for
+policies, text/channel decisions, remembered approvals and component capabilities.