@fadhilp/stateql 0.13.3 → 0.15.0

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.
package/README.md CHANGED
@@ -1,98 +1,60 @@
1
1
  # StateQL
2
2
 
3
3
  StateQL is a stateful database CLI and TypeScript library for AI agents and
4
- automation. Query, change, and inspect databases while keeping results reusable
5
- and operations traceable across commands.
4
+ automation. It keeps query results as durable handles, so later commands can
5
+ page, filter, count, or export them without querying the database again.
6
6
 
7
7
  - **SQL:** SQLite, PostgreSQL, and MySQL.
8
8
  - **Native commands:** MongoDB (EJSON) and Redis (JSON).
9
- - **Durable handles:** reuse, filter, page, count, alias, or export stored results
10
- without rerunning the original query.
11
- - **Tracked writes:** inspect operations, review plans, and stage transactions
12
- where supported by the database.
9
+ - **Compact output:** one-line JSON with a 5-row preview and column names sent once.
10
+ - **Safe writes:** read-only by default, explicit approval for unbounded or
11
+ destructive statements, idempotency keys, plans, and staged transactions.
13
12
 
14
- Requires **Node.js 22.16 or newer** for the required `node:sqlite` APIs.
13
+ Requires **Node.js 22.16 or newer**.
15
14
 
16
- ## Quick start
17
-
18
- Install the CLI:
15
+ ## Install
19
16
 
20
17
  ```bash
21
- npm install -g @fadhilp/stateql
18
+ npm install -g @fadhilp/stateql # CLI (stql)
19
+ npm install @fadhilp/stateql # TypeScript library
22
20
  ```
23
21
 
24
- Connect to an existing SQLite database containing a `users` table. These shell
25
- examples use Bash; see the [usage guide](docs/usage.md) for connection options and
26
- SQL parameter handling.
22
+ ## Quick start
27
23
 
28
24
  ```bash
29
25
  export STQL_SESSION=audit
30
- stql profile add local ./app.sqlite --read-only
31
- stql connect local
26
+ stql connect ./app.sqlite
32
27
 
33
- stql query \
34
- "SELECT id, name, email FROM users WHERE status = ? AND created_at >= ? ORDER BY id LIMIT 50" \
35
- --param active \
36
- --param 2026-01-01
28
+ stql query "SELECT id, name FROM users WHERE status = ? ORDER BY id" --param active
37
29
  ```
38
30
 
39
- Parameters keep values separate from SQL. `ORDER BY` makes paging stable, and
40
- `LIMIT` bounds work at the database. The default `agent` output is compact,
41
- one-line JSON. An example response:
42
-
43
31
  ```json
44
- {"ok":true,"handle":"q_k7m2v5x9c3d6f8h4j2n7p5r9tw","rows":[{"id":7,"name":"Ada","email":"ada@example.com"}],"truncated":false,"cached":false,"total":1,"next_offset":null}
32
+ {"ok":true,"handle":"katcitg6un","total":333,"next_offset":5,"columns":["id","name"],"rows":[[2,"Ada"],[3,"Grace"],[5,"Linus"],[6,"Alan"],[8,"Edsger"]]}
45
33
  ```
46
34
 
47
- Use the handle returned by your query in place of the example handle below.
48
- Give the snapshot a readable alias, then work with the stored data:
35
+ Reuse the result by its handle. These commands do not access the database:
49
36
 
50
37
  ```bash
51
- stql alias set active-users q_k7m2v5x9c3d6f8h4j2n7p5r9tw
52
- stql rows active-users --offset 0 --limit 10
53
- stql count active-users
54
- stql export active-users --output active-users.csv --format csv
55
- stql filter active-users "email LIKE ?" --param "%@example.com"
38
+ stql rows katcitg6un --offset 5 --limit 20
39
+ stql filter katcitg6un "name LIKE ?" --param "A%"
40
+ stql export katcitg6un --output users.csv
56
41
  ```
57
42
 
58
- These commands do not access the original database. `filter` creates a new
59
- snapshot with its own handle. Repeating a query can reuse a valid cached result;
60
- use `--cache bypass` when a fresh database read is required.
61
-
62
- ## Safety and state
63
-
64
- - Connections are **read-only by default**. Writes require a read-write connection.
65
- - Destructive and unbounded SQL/MongoDB operations require independent
66
- `--allow-destructive` and `--allow-unbounded` approvals, respectively.
67
- - `plan` stores a write for review; `apply` never adds authorization. Use
68
- idempotency keys to protect retryable writes from duplicate execution.
69
- - A write reported as `OUTCOME_UNKNOWN` must be inspected at the database before
70
- replaying it. Transactions are staged locally, not live interactive SQL
71
- transactions.
72
- - Supply credential-bearing URLs through environment variables or a trusted
73
- library credential resolver, not literal command arguments or profiles.
74
- - Results and history persist under `STQL_HOME` (or the platform data directory).
75
- Treat that state as database data; retention and size limits are configurable.
76
-
77
- See [write safety](docs/usage.md#write-safety),
78
- [credentials](docs/usage.md#environment-backed-credentials), and
79
- [database restrictions](docs/databases.md) before using production data.
80
-
81
43
  ## Documentation
82
44
 
83
- | Guide | Contents |
45
+ | Page | Contents |
84
46
  | --- | --- |
85
- | [Usage](docs/usage.md) | Connections, CLI reference, results, sessions, limits, writes, transactions, batch and pipes |
86
- | [Database support](docs/databases.md) | SQL dialects, diagnostics, maintenance, native MongoDB and Redis commands |
87
- | [TypeScript library](docs/library.md) | Connection setup, response handling, cleanup, actors, workspaces, and credential resolution |
88
-
89
- Run `stql --help` for command syntax or `stql capabilities` for capability details.
47
+ | [Agent guide](docs/agents.md) | The short version for agents: connect, query, reuse, save tokens |
48
+ | [Connections](docs/connections.md) | Targets, environment credentials, profiles |
49
+ | [CLI reference](docs/cli.md) | Commands, parameters, catalog, output modes, deadlines |
50
+ | [Results and state](docs/results.md) | Sessions, actors, limits, caching, local filtering |
51
+ | [Write safety](docs/writes.md) | Approvals, plans, idempotency, transactions |
52
+ | [Batch and pipes](docs/batch.md) | Run many commands in one call |
53
+ | [Database support](docs/databases.md) | Dialects, diagnostics, MongoDB and Redis commands |
54
+ | [TypeScript library](docs/library.md) | API, responses, actors, credential resolution |
90
55
 
91
- ## TypeScript installation
56
+ Run `stql help` for command syntax and `stql capabilities` for feature details.
92
57
 
93
- ```bash
94
- npm install @fadhilp/stateql
95
- ```
58
+ ## License
96
59
 
97
- The package exports `StateQL` and public TypeScript types. Start with the
98
- [connected, cleanup-safe example](docs/library.md#getting-started).
60
+ [MIT](LICENSE)
@@ -0,0 +1,3 @@
1
+ import type { Response } from "./types.js";
2
+ /** Compacts a response for model context, as the CLI `agent` output mode does. */
3
+ export declare function agentResponse(result: Response<unknown>, commandName: string): Record<string, unknown>;
@@ -0,0 +1,213 @@
1
+ import { isColumns, isRecord } from "./util.js";
2
+ const RESULT_COMMANDS = new Set(["query", "mongo.query", "redis.query", "filter", "show"]);
3
+ const FALSE_DEFAULT_KEYS = ["cached", "duplicate", "duplicate_override"];
4
+ const SHARED_HISTORY_KEYS = ["session_id", "actor_id", "actor_name", "origin"];
5
+ // The caller already holds the handle it passed to these commands.
6
+ const HANDLE_ECHO_COMMANDS = new Set(["rows", "count", "columns"]);
7
+ const WRITE_COMMANDS = new Set(["exec", "mongo.exec", "redis.exec", "apply"]);
8
+ const COMMAND_ALIASES = {
9
+ "objects.list": "objects",
10
+ "object.describe": "object",
11
+ };
12
+ /** Compacts a response for model context, as the CLI `agent` output mode does. */
13
+ export function agentResponse(result, commandName) {
14
+ const currentCommand = COMMAND_ALIASES[commandName] ?? commandName;
15
+ if (!result.ok)
16
+ return { ok: false, error: result.error };
17
+ if (!isRecord(result.data))
18
+ return { ok: true, data: result.data };
19
+ const data = { ...result.data };
20
+ const handleKey = primaryHandleKey(currentCommand);
21
+ let handle = handleKey && typeof data[handleKey] === "string" && data[handleKey]
22
+ ? data[handleKey]
23
+ : undefined;
24
+ if (handle && handleKey)
25
+ delete data[handleKey];
26
+ const generatedAlias = data.display_alias;
27
+ delete data.display_alias;
28
+ // Generated aliases cannot be reassigned, so they are stable short result handles.
29
+ if (RESULT_COMMANDS.has(currentCommand) && typeof generatedAlias === "string") {
30
+ handle = generatedAlias;
31
+ if (data.alias === generatedAlias)
32
+ delete data.alias;
33
+ }
34
+ const isResult = RESULT_COMMANDS.has(currentCommand) &&
35
+ typeof data.rows === "number" &&
36
+ Array.isArray(data.preview);
37
+ if (isResult) {
38
+ data.total = data.rows;
39
+ data.next_offset = data.truncated ? data.preview.length : null;
40
+ data.rows = data.preview;
41
+ delete data.preview;
42
+ delete data.preview_count;
43
+ delete data.truncated;
44
+ delete data.storage;
45
+ delete data.state_version;
46
+ delete data.duplicate_of;
47
+ }
48
+ else if (currentCommand === "rows") {
49
+ delete data.offset;
50
+ delete data.limit;
51
+ delete data.returned;
52
+ delete data.truncated;
53
+ }
54
+ else if (currentCommand === "count" && typeof data.rows === "number") {
55
+ data.total = data.rows;
56
+ delete data.rows;
57
+ }
58
+ else if (WRITE_COMMANDS.has(currentCommand)) {
59
+ delete data.actor_id;
60
+ delete data.plan_id;
61
+ delete data.state_version_before;
62
+ if (typeof data.status === "string")
63
+ delete data.committed;
64
+ }
65
+ else if (currentCommand === "history" &&
66
+ Array.isArray(data.history) &&
67
+ data.history.every(isRecord)) {
68
+ Object.assign(data, compactHistory(data.history));
69
+ }
70
+ else if (currentCommand === "inspect" && Array.isArray(data.columns)) {
71
+ data.columns = data.columns.map(withoutFalsePrimaryKey);
72
+ }
73
+ else if (currentCommand === "capabilities" && isRecord(data.features)) {
74
+ const features = data.features;
75
+ data.features = Object.keys(features).filter((key) => features[key] === true);
76
+ }
77
+ else if (currentCommand === "objects" &&
78
+ Array.isArray(data.objects) &&
79
+ data.objects.every(isRecord)) {
80
+ const objects = data.objects.every(hasDerivedIdentity)
81
+ ? data.objects.map(withoutIdentity)
82
+ : data.objects;
83
+ const table = columnarRows(objects, undefined);
84
+ delete data.objects;
85
+ Object.assign(data, { columns: table.columns, objects: table.rows });
86
+ }
87
+ else if (currentCommand === "object" &&
88
+ isRecord(data.object) &&
89
+ hasDerivedIdentity(data.object)) {
90
+ data.object = withoutIdentity(data.object);
91
+ }
92
+ if (isResult || (currentCommand === "rows" && Array.isArray(data.rows))) {
93
+ const table = columnarRows(data.rows, data.columns);
94
+ delete data.columns;
95
+ delete data.rows;
96
+ Object.assign(data, table);
97
+ }
98
+ const hasMoreRows = data.next_offset !== null && data.next_offset !== undefined;
99
+ const warnings = result.warnings.filter((warning) => warning.code !== "NON_DETERMINISTIC_PAGINATION" || hasMoreRows);
100
+ dropFalseDefaults(data);
101
+ for (const key of ["ok", "error", "handle", "warnings"]) {
102
+ if (!(key in data))
103
+ continue;
104
+ data[`data_${key}`] = data[key];
105
+ delete data[key];
106
+ }
107
+ return {
108
+ ok: true,
109
+ ...(handle && !HANDLE_ECHO_COMMANDS.has(currentCommand) ? { handle } : {}),
110
+ ...withoutNulls(data),
111
+ ...(warnings.length ? { warnings } : {}),
112
+ };
113
+ }
114
+ // Rows with differing keys (e.g. MongoDB documents) stay objects so missing and null remain distinct.
115
+ function columnarRows(rows, columns) {
116
+ const names = isColumns(columns)
117
+ ? columns.map((column) => column.name)
118
+ : Object.keys(rows[0] ?? {});
119
+ if (names.length === 0)
120
+ return { rows };
121
+ const nameSet = new Set(names);
122
+ const hasColumnKeys = (row) => {
123
+ if (!isRecord(row))
124
+ return false;
125
+ const keys = Object.keys(row);
126
+ return keys.length === names.length && keys.every((key) => nameSet.has(key));
127
+ };
128
+ if (!rows.every(hasColumnKeys))
129
+ return { rows };
130
+ return {
131
+ columns: names,
132
+ rows: rows.map((row) => names.map((name) => row[name])),
133
+ };
134
+ }
135
+ function compactHistory(entries) {
136
+ const shared = {};
137
+ for (const key of SHARED_HISTORY_KEYS) {
138
+ const value = entries[0]?.[key];
139
+ if (value === undefined)
140
+ continue;
141
+ if (entries.every((entry) => entry[key] === value))
142
+ shared[key] = value;
143
+ }
144
+ const history = entries.map((entry) => {
145
+ const compact = withoutNulls(entry);
146
+ dropFalseDefaults(compact);
147
+ for (const key of Object.keys(shared))
148
+ delete compact[key];
149
+ return compact;
150
+ });
151
+ return { ...shared, history };
152
+ }
153
+ function hasDerivedIdentity(object) {
154
+ const qualifiedName = typeof object.schema === "string"
155
+ ? `${object.schema}.${String(object.name)}`
156
+ : object.name;
157
+ return object.identity === undefined || object.identity === qualifiedName;
158
+ }
159
+ function withoutIdentity(object) {
160
+ const compact = { ...object };
161
+ delete compact.identity;
162
+ return compact;
163
+ }
164
+ function withoutFalsePrimaryKey(column) {
165
+ if (!isRecord(column) || column.primary_key !== false)
166
+ return column;
167
+ const compact = { ...column };
168
+ delete compact.primary_key;
169
+ return compact;
170
+ }
171
+ function dropFalseDefaults(record) {
172
+ for (const key of FALSE_DEFAULT_KEYS) {
173
+ if (record[key] === false)
174
+ delete record[key];
175
+ }
176
+ }
177
+ function withoutNulls(record) {
178
+ return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== null));
179
+ }
180
+ function primaryHandleKey(currentCommand) {
181
+ const keys = {
182
+ query: "result_id",
183
+ "mongo.query": "result_id",
184
+ "redis.query": "result_id",
185
+ filter: "result_id",
186
+ show: "result_id",
187
+ rows: "result_id",
188
+ count: "result_id",
189
+ columns: "result_id",
190
+ export: "result_id",
191
+ alias: "result_id",
192
+ "alias.set": "result_id",
193
+ exec: "operation_id",
194
+ "mongo.exec": "operation_id",
195
+ "redis.exec": "operation_id",
196
+ receipt: "operation_id",
197
+ apply: "operation_id",
198
+ plan: "plan_id",
199
+ "mongo.plan": "plan_id",
200
+ "redis.plan": "plan_id",
201
+ connect: "connection_id",
202
+ transaction: "transaction_id",
203
+ "transaction.begin": "transaction_id",
204
+ "transaction.status": "transaction_id",
205
+ "transaction.commit": "transaction_id",
206
+ "transaction.rollback": "transaction_id",
207
+ session: "session_id",
208
+ "session.start": "session_id",
209
+ "session.show": "session_id",
210
+ "session.close": "session_id",
211
+ };
212
+ return keys[currentCommand];
213
+ }
package/dist/src/cli.js CHANGED
@@ -6,6 +6,7 @@ import { parseArgs } from "node:util";
6
6
  import { BSON } from "mongodb";
7
7
  import { exitCodeFor } from "./errors.js";
8
8
  import { StateQL } from "./stateql.js";
9
+ import { agentResponse } from "./agent-response.js";
9
10
  const parsed = parseArgs({
10
11
  allowPositionals: true,
11
12
  strict: true,
@@ -21,6 +22,7 @@ const parsed = parseArgs({
21
22
  "params-file": { type: "string" },
22
23
  cache: { type: "string" },
23
24
  "preview-rows": { type: "string" },
25
+ "max-cell-characters": { type: "string" },
24
26
  replay: { type: "boolean" },
25
27
  "idempotency-key": { type: "string" },
26
28
  "allow-unbounded": { type: "boolean" },
@@ -51,7 +53,7 @@ if (values.version) {
51
53
  console.log(packageVersion());
52
54
  process.exit(0);
53
55
  }
54
- if (values.help || !command) {
56
+ if (values.help || !command || command === "help") {
55
57
  console.log(helpText());
56
58
  process.exit(0);
57
59
  }
@@ -71,6 +73,9 @@ const stateql = new StateQL({
71
73
  ...(values["result-ttl-seconds"] === undefined
72
74
  ? {}
73
75
  : { resultTtlSeconds: Number(values["result-ttl-seconds"]) }),
76
+ ...(values["max-cell-characters"] === undefined
77
+ ? {}
78
+ : { maxCellCharacters: Number(values["max-cell-characters"]) }),
74
79
  signal: abortController.signal,
75
80
  });
76
81
  try {
@@ -94,8 +99,8 @@ async function runSingle() {
94
99
  catch (error) {
95
100
  response = cliFailure(error);
96
101
  }
97
- const responseCommand = command === "mongo" && subcommand
98
- ? `mongo.${subcommand}`
102
+ const responseCommand = (command === "mongo" || command === "redis") && subcommand
103
+ ? `${command}.${subcommand}`
99
104
  : command ?? "";
100
105
  print(response, mode, responseCommand);
101
106
  if (!response.ok)
@@ -526,98 +531,11 @@ function print(result, mode, currentCommand) {
526
531
  return;
527
532
  }
528
533
  if (mode === "agent") {
529
- console.log(JSON.stringify(toAgentResponse(result, currentCommand)));
534
+ console.log(JSON.stringify(agentResponse(result, currentCommand)));
530
535
  return;
531
536
  }
532
537
  console.log(mode === "json" ? JSON.stringify(result, null, 2) : JSON.stringify(result));
533
538
  }
534
- function toAgentResponse(result, currentCommand) {
535
- if (!result.ok)
536
- return { ok: false, error: result.error };
537
- if (!result.data ||
538
- typeof result.data !== "object" ||
539
- Array.isArray(result.data)) {
540
- return { ok: true, data: result.data };
541
- }
542
- const data = { ...result.data };
543
- const handleKey = primaryHandleKey(currentCommand);
544
- const handle = handleKey && typeof data[handleKey] === "string" && data[handleKey]
545
- ? data[handleKey]
546
- : undefined;
547
- if (handle && handleKey)
548
- delete data[handleKey];
549
- if ((currentCommand === "query" ||
550
- currentCommand === "mongo.query" ||
551
- currentCommand === "filter" ||
552
- currentCommand === "show") &&
553
- typeof data.rows === "number" &&
554
- Array.isArray(data.preview)) {
555
- const total = data.rows;
556
- const rows = data.preview;
557
- const truncated = Boolean(data.truncated);
558
- data.rows = rows;
559
- data.total = total;
560
- data.next_offset = truncated ? rows.length : null;
561
- delete data.preview;
562
- delete data.preview_count;
563
- delete data.columns;
564
- delete data.storage;
565
- delete data.state_version;
566
- delete data.duplicate_of;
567
- }
568
- else if (currentCommand === "rows") {
569
- delete data.offset;
570
- delete data.limit;
571
- delete data.returned;
572
- }
573
- else if (currentCommand === "count" && typeof data.rows === "number") {
574
- data.total = data.rows;
575
- delete data.rows;
576
- }
577
- for (const key of ["ok", "error", "handle", "warnings"]) {
578
- if (!(key in data))
579
- continue;
580
- data[`data_${key}`] = data[key];
581
- delete data[key];
582
- }
583
- return {
584
- ok: true,
585
- ...(handle ? { handle } : {}),
586
- ...data,
587
- ...(result.warnings.length ? { warnings: result.warnings } : {}),
588
- };
589
- }
590
- function primaryHandleKey(currentCommand) {
591
- const keys = {
592
- query: "result_id",
593
- "mongo.query": "result_id",
594
- filter: "result_id",
595
- show: "result_id",
596
- rows: "result_id",
597
- count: "result_id",
598
- columns: "result_id",
599
- export: "result_id",
600
- alias: "result_id",
601
- "alias.set": "result_id",
602
- exec: "operation_id",
603
- "mongo.exec": "operation_id",
604
- receipt: "operation_id",
605
- apply: "operation_id",
606
- plan: "plan_id",
607
- "mongo.plan": "plan_id",
608
- connect: "connection_id",
609
- transaction: "transaction_id",
610
- "transaction.begin": "transaction_id",
611
- "transaction.status": "transaction_id",
612
- "transaction.commit": "transaction_id",
613
- "transaction.rollback": "transaction_id",
614
- session: "session_id",
615
- "session.start": "session_id",
616
- "session.show": "session_id",
617
- "session.close": "session_id",
618
- };
619
- return keys[currentCommand];
620
- }
621
539
  function cliFailure(error) {
622
540
  return {
623
541
  ok: false,
@@ -674,10 +592,13 @@ Commands:
674
592
 
675
593
  SQL parameters: --params JSON, repeated --param VALUE, or --params-file FILE.
676
594
  Query preview: --preview-rows N (default: 5, maximum: 200).
595
+ Long cells: --max-cell-characters N (default: 200); use export for full values.
677
596
  Deadline: --timeout-ms N (default: 30000). Ctrl+C cancels database work.
678
597
  Credential refs require a trusted host CredentialResolver; the standalone CLI cannot resolve them.
679
598
  State: --max-state-bytes N, --cache-ttl-seconds N, --result-ttl-seconds N.
680
599
  Output: --output agent|json|jsonl|text|silent (default: agent).
600
+ Agent rows: arrays in "columns" order (objects when shapes differ). next_offset only when more rows exist.
601
+ Agent output omits null fields and false cached/duplicate flags. Guide: docs/agents.md.
681
602
  Batch/pipe accept JSON array files or JSONL streams. Stop on first error.`;
682
603
  }
683
604
  function packageVersion() {
@@ -14,4 +14,5 @@ export declare class StateQLError extends Error {
14
14
  });
15
15
  }
16
16
  export declare function exitCodeFor(code: string): number;
17
+ export declare function isTransientDatabaseError(error: unknown): boolean;
17
18
  export declare function asStateQLError(error: unknown): StateQLError;
@@ -49,6 +49,46 @@ export function exitCodeFor(code) {
49
49
  return 9;
50
50
  return 1;
51
51
  }
52
+ const TRANSIENT_NETWORK_CODES = new Set([
53
+ "ECONNRESET",
54
+ "ECONNREFUSED",
55
+ "ETIMEDOUT",
56
+ "EPIPE",
57
+ "EAI_AGAIN",
58
+ "PROTOCOL_CONNECTION_LOST",
59
+ ]);
60
+ // SQLSTATE classes: connection, transaction rollback, resources, operator intervention, system.
61
+ const TRANSIENT_SQLSTATE_CLASSES = new Set(["08", "40", "53", "57", "58"]);
62
+ // MySQL: too many connections, lock wait timeout, deadlock.
63
+ const TRANSIENT_MYSQL_ERRNOS = new Set([1040, 1205, 1213]);
64
+ const TRANSIENT_ERROR_NAMES = new Set([
65
+ "MongoNetworkError",
66
+ "MongoNetworkTimeoutError",
67
+ "MongoServerSelectionError",
68
+ "SocketClosedUnexpectedlyError",
69
+ "ConnectionTimeoutError",
70
+ ]);
71
+ const TRANSIENT_SQLITE_MESSAGE = /database (table )?is locked|SQLITE_BUSY/i;
72
+ // Permanent failures such as a missing table must not invite retries; unknown errors are not retryable.
73
+ export function isTransientDatabaseError(error) {
74
+ if (!(error instanceof Error))
75
+ return false;
76
+ const details = error;
77
+ if (typeof details.code === "string" && TRANSIENT_NETWORK_CODES.has(details.code))
78
+ return true;
79
+ if (TRANSIENT_ERROR_NAMES.has(error.name))
80
+ return true;
81
+ if (typeof details.errno === "number" && TRANSIENT_MYSQL_ERRNOS.has(details.errno))
82
+ return true;
83
+ if (Array.isArray(details.errorLabels) && details.errorLabels.includes("TransientTransactionError")) {
84
+ return true;
85
+ }
86
+ const sqlState = typeof details.sqlState === "string" ? details.sqlState : details.code;
87
+ if (typeof sqlState === "string" && /^[0-9A-Z]{5}$/.test(sqlState)) {
88
+ return TRANSIENT_SQLSTATE_CLASSES.has(sqlState.slice(0, 2));
89
+ }
90
+ return TRANSIENT_SQLITE_MESSAGE.test(error.message);
91
+ }
52
92
  export function asStateQLError(error) {
53
93
  if (error instanceof StateQLError)
54
94
  return error;
@@ -1,4 +1,5 @@
1
1
  export { StateQL } from "./stateql.js";
2
+ export { agentResponse } from "./agent-response.js";
2
3
  export { CredentialResolutionError, StateQLError, exitCodeFor, } from "./errors.js";
3
4
  export type { CredentialResolutionFailure } from "./errors.js";
4
5
  export type { TableChange, TableIdentity, TableUpdate } from "./table-editor.js";
package/dist/src/index.js CHANGED
@@ -1,2 +1,3 @@
1
1
  export { StateQL } from "./stateql.js";
2
+ export { agentResponse } from "./agent-response.js";
2
3
  export { CredentialResolutionError, StateQLError, exitCodeFor, } from "./errors.js";
package/dist/src/sql.js CHANGED
@@ -58,7 +58,13 @@ function parseSqlStatement(sql, driver) {
58
58
  ? "MySQL"
59
59
  : "Sqlite";
60
60
  const parserSql = driver === "postgres" ? postgresParserSql(sql) : sql;
61
- const parsed = parser.astify(parserSql, { database });
61
+ let parsed;
62
+ try {
63
+ parsed = parser.astify(parserSql, { database });
64
+ }
65
+ catch (error) {
66
+ throw new StateQLError("INVALID_SQL", syntaxErrorMessage(error, parserSql));
67
+ }
62
68
  if (Array.isArray(parsed) && parsed.length !== 1) {
63
69
  throw new StateQLError("INVALID_SQL", "Exactly one SQL statement is required.");
64
70
  }
@@ -1073,6 +1079,17 @@ function postgresBlockCommentEnd(sql, start) {
1073
1079
  }
1074
1080
  return undefined;
1075
1081
  }
1082
+ // The parser lists every expected token (often 500+ characters); position and nearby text are enough to fix the SQL.
1083
+ function syntaxErrorMessage(error, sql) {
1084
+ const start = error.location?.start;
1085
+ if (!start)
1086
+ return error instanceof Error ? error.message : "Invalid SQL.";
1087
+ const near = sql.slice(start.offset, start.offset + 20).split("\n")[0];
1088
+ const position = `line ${start.line}, column ${start.column}`;
1089
+ return near
1090
+ ? `Syntax error at ${position} near "${near}".`
1091
+ : `Syntax error at ${position}: unexpected end of input.`;
1092
+ }
1076
1093
  function postgresParserSql(sql) {
1077
1094
  const output = sql.split("");
1078
1095
  const orderDepths = new Set();
@@ -6,7 +6,7 @@ import { basename, resolve } from "node:path";
6
6
  import { env } from "node:process";
7
7
  import { AdapterExecutionError, AdapterWriteError, BatchWriteError, createAdapter, createAdapterContext, } from "./adapters.js";
8
8
  import { confidence, credentialSource, databaseIdentity, databaseUrlHasSecret, detectDriver, isEnvironmentName, injectPassword, mongoDatabaseName, redisDatabaseName, normalizeSqliteSource, validateCredentialRef, validatePasswordReferenceTarget, validateProfileName, version, } from "./connection.js";
9
- import { asStateQLError, CredentialResolutionError, StateQLError, } from "./errors.js";
9
+ import { asStateQLError, CredentialResolutionError, isTransientDatabaseError, StateQLError, } from "./errors.js";
10
10
  import { analyzeMongoWriteSafety, deserializeMongoWriteCommand, serializeMongoCommand, validateMongoReadCommand, validateMongoWriteCommand, MongoAdapter, } from "./mongodb.js";
11
11
  import { deserializeRedisCommand, RedisAdapter, serializeRedisCommand, validateRedisReadCommand, validateRedisWriteCommand, } from "./redis.js";
12
12
  import { filterMaterializedRows, prepareFilterStatement, validateFilterParameters, } from "./filter.js";
@@ -811,7 +811,7 @@ export class StateQL {
811
811
  throw stoppedStateQLError(error, true);
812
812
  }
813
813
  throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), {
814
- retryable: true,
814
+ retryable: isTransientDatabaseError(error),
815
815
  executed: true,
816
816
  });
817
817
  }
@@ -902,7 +902,7 @@ export class StateQL {
902
902
  if (error instanceof AdapterExecutionError) {
903
903
  throw stoppedStateQLError(error, true);
904
904
  }
905
- throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { retryable: true, executed: true });
905
+ throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { retryable: isTransientDatabaseError(error), executed: true });
906
906
  }
907
907
  finally {
908
908
  await closeAdapterQuietly(adapter);
@@ -947,7 +947,7 @@ export class StateQL {
947
947
  throw error;
948
948
  if (error instanceof AdapterExecutionError)
949
949
  throw stoppedStateQLError(error, true);
950
- throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, source), { retryable: true, executed: true });
950
+ throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, source), { retryable: isTransientDatabaseError(error), executed: true });
951
951
  }
952
952
  finally {
953
953
  await closeAdapterQuietly(adapter);
@@ -1694,7 +1694,7 @@ export class StateQL {
1694
1694
  if (error instanceof AdapterExecutionError) {
1695
1695
  throw stoppedStateQLError(error, true);
1696
1696
  }
1697
- throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { retryable: true, executed: true });
1697
+ throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { retryable: isTransientDatabaseError(error), executed: true });
1698
1698
  }
1699
1699
  finally {
1700
1700
  await closeAdapterQuietly(adapter);
@@ -1759,7 +1759,7 @@ export class StateQL {
1759
1759
  if (error instanceof AdapterExecutionError) {
1760
1760
  throw stoppedStateQLError(error, true);
1761
1761
  }
1762
- throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { retryable: true, executed: true });
1762
+ throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { retryable: isTransientDatabaseError(error), executed: true });
1763
1763
  }
1764
1764
  finally {
1765
1765
  await closeAdapterQuietly(adapter);
@@ -1886,7 +1886,7 @@ export class StateQL {
1886
1886
  if (error instanceof AdapterExecutionError) {
1887
1887
  throw stoppedStateQLError(error, true);
1888
1888
  }
1889
- throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { retryable: true, executed: true });
1889
+ throw new StateQLError("QUERY_FAILED", safeCredentialErrorMessage(error, adapterSource), { retryable: isTransientDatabaseError(error), executed: true });
1890
1890
  }
1891
1891
  finally {
1892
1892
  await closeAdapterQuietly(adapter);