agentskeptic 0.1.5 → 0.1.7
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 +41 -99
- package/dist/bootstrap/bootstrapReadmeTemplate.d.ts +3 -0
- package/dist/bootstrap/bootstrapReadmeTemplate.d.ts.map +1 -0
- package/dist/bootstrap/bootstrapReadmeTemplate.js +17 -0
- package/dist/bootstrap/bootstrapReadmeTemplate.js.map +1 -0
- package/dist/bootstrap/parseBootstrapPackInput.d.ts +16 -0
- package/dist/bootstrap/parseBootstrapPackInput.d.ts.map +1 -0
- package/dist/bootstrap/parseBootstrapPackInput.js +95 -0
- package/dist/bootstrap/parseBootstrapPackInput.js.map +1 -0
- package/dist/bootstrap/parseBootstrapPackInput.test.d.ts +2 -0
- package/dist/bootstrap/parseBootstrapPackInput.test.d.ts.map +1 -0
- package/dist/bootstrap/parseBootstrapPackInput.test.js +46 -0
- package/dist/bootstrap/parseBootstrapPackInput.test.js.map +1 -0
- package/dist/bootstrap/runBootstrapSubcommand.d.ts +9 -0
- package/dist/bootstrap/runBootstrapSubcommand.d.ts.map +1 -0
- package/dist/bootstrap/runBootstrapSubcommand.js +263 -0
- package/dist/bootstrap/runBootstrapSubcommand.js.map +1 -0
- package/dist/bootstrap/synthesizeQuickInputFromOpenAiV1.d.ts +6 -0
- package/dist/bootstrap/synthesizeQuickInputFromOpenAiV1.d.ts.map +1 -0
- package/dist/bootstrap/synthesizeQuickInputFromOpenAiV1.js +16 -0
- package/dist/bootstrap/synthesizeQuickInputFromOpenAiV1.js.map +1 -0
- package/dist/cli.js +139 -34
- package/dist/cli.js.map +1 -1
- package/dist/cliOperationalCodes.d.ts +7 -0
- package/dist/cliOperationalCodes.d.ts.map +1 -1
- package/dist/cliOperationalCodes.js +7 -0
- package/dist/cliOperationalCodes.js.map +1 -1
- package/dist/commercial/licensePreflight.d.ts +7 -2
- package/dist/commercial/licensePreflight.d.ts.map +1 -1
- package/dist/commercial/licensePreflight.js +6 -5
- package/dist/commercial/licensePreflight.js.map +1 -1
- package/dist/commercial/licensePreflight.test.js +70 -21
- package/dist/commercial/licensePreflight.test.js.map +1 -1
- package/dist/commercial/postVerifyOutcomeBeacon.d.ts +13 -0
- package/dist/commercial/postVerifyOutcomeBeacon.d.ts.map +1 -0
- package/dist/commercial/postVerifyOutcomeBeacon.js +33 -0
- package/dist/commercial/postVerifyOutcomeBeacon.js.map +1 -0
- package/dist/commercial/quickVerifyFunnelTerminalStatus.d.ts +5 -0
- package/dist/commercial/quickVerifyFunnelTerminalStatus.d.ts.map +1 -0
- package/dist/commercial/quickVerifyFunnelTerminalStatus.js +11 -0
- package/dist/commercial/quickVerifyFunnelTerminalStatus.js.map +1 -0
- package/dist/commercial/verifyWorkloadClassify.d.ts +17 -0
- package/dist/commercial/verifyWorkloadClassify.d.ts.map +1 -0
- package/dist/commercial/verifyWorkloadClassify.js +47 -0
- package/dist/commercial/verifyWorkloadClassify.js.map +1 -0
- package/dist/commercial/verifyWorkloadClassify.test.d.ts +2 -0
- package/dist/commercial/verifyWorkloadClassify.test.d.ts.map +1 -0
- package/dist/commercial/verifyWorkloadClassify.test.js +45 -0
- package/dist/commercial/verifyWorkloadClassify.test.js.map +1 -0
- package/dist/debugServer.d.ts +2 -0
- package/dist/debugServer.d.ts.map +1 -1
- package/dist/debugServer.js +13 -12
- package/dist/debugServer.js.map +1 -1
- package/dist/debugServer.test.js +31 -2
- package/dist/debugServer.test.js.map +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/loadEvents.d.ts +2 -0
- package/dist/loadEvents.d.ts.map +1 -1
- package/dist/loadEvents.js +11 -0
- package/dist/loadEvents.js.map +1 -1
- package/dist/operationalDisposition.d.ts +56 -0
- package/dist/operationalDisposition.d.ts.map +1 -1
- package/dist/operationalDisposition.js +56 -0
- package/dist/operationalDisposition.js.map +1 -1
- package/dist/publicDistribution.generated.d.ts +2 -0
- package/dist/publicDistribution.generated.d.ts.map +1 -1
- package/dist/publicDistribution.generated.js +2 -0
- package/dist/publicDistribution.generated.js.map +1 -1
- package/dist/quickVerify/buildQuickContractEventsNdjson.d.ts +6 -0
- package/dist/quickVerify/buildQuickContractEventsNdjson.d.ts.map +1 -1
- package/dist/quickVerify/buildQuickContractEventsNdjson.js +33 -14
- package/dist/quickVerify/buildQuickContractEventsNdjson.js.map +1 -1
- package/dist/quickVerify/buildSyntheticRowParams.d.ts +7 -0
- package/dist/quickVerify/buildSyntheticRowParams.d.ts.map +1 -0
- package/dist/quickVerify/buildSyntheticRowParams.js +13 -0
- package/dist/quickVerify/buildSyntheticRowParams.js.map +1 -0
- package/dist/quickVerify/buildSyntheticRowParams.test.d.ts +2 -0
- package/dist/quickVerify/buildSyntheticRowParams.test.d.ts.map +1 -0
- package/dist/quickVerify/buildSyntheticRowParams.test.js +19 -0
- package/dist/quickVerify/buildSyntheticRowParams.test.js.map +1 -0
- package/dist/quickVerify/exportTool.d.ts +12 -1
- package/dist/quickVerify/exportTool.d.ts.map +1 -1
- package/dist/quickVerify/exportTool.js +45 -0
- package/dist/quickVerify/exportTool.js.map +1 -1
- package/dist/quickVerify/flatKeyToJsonPointer.d.ts +16 -0
- package/dist/quickVerify/flatKeyToJsonPointer.d.ts.map +1 -0
- package/dist/quickVerify/flatKeyToJsonPointer.js +44 -0
- package/dist/quickVerify/flatKeyToJsonPointer.js.map +1 -0
- package/dist/quickVerify/flatKeyToJsonPointer.test.d.ts +2 -0
- package/dist/quickVerify/flatKeyToJsonPointer.test.d.ts.map +1 -0
- package/dist/quickVerify/flatKeyToJsonPointer.test.js +19 -0
- package/dist/quickVerify/flatKeyToJsonPointer.test.js.map +1 -0
- package/dist/quickVerify/formatQuickVerifyHumanReport.js +1 -1
- package/dist/quickVerify/formatQuickVerifyHumanReport.js.map +1 -1
- package/dist/quickVerify/formatQuickVerifyHumanReport.test.js +2 -2
- package/dist/quickVerify/formatQuickVerifyHumanReport.test.js.map +1 -1
- package/dist/quickVerify/ingest.d.ts +1 -0
- package/dist/quickVerify/ingest.d.ts.map +1 -1
- package/dist/quickVerify/ingest.js +44 -1
- package/dist/quickVerify/ingest.js.map +1 -1
- package/dist/quickVerify/planRowUnit.pointer-promotion.test.d.ts +2 -0
- package/dist/quickVerify/planRowUnit.pointer-promotion.test.d.ts.map +1 -0
- package/dist/quickVerify/planRowUnit.pointer-promotion.test.js +30 -0
- package/dist/quickVerify/planRowUnit.pointer-promotion.test.js.map +1 -0
- package/dist/quickVerify/quickParamPointerNegatives.test.d.ts +2 -0
- package/dist/quickVerify/quickParamPointerNegatives.test.d.ts.map +1 -0
- package/dist/quickVerify/quickParamPointerNegatives.test.js +25 -0
- package/dist/quickVerify/quickParamPointerNegatives.test.js.map +1 -0
- package/dist/quickVerify/quickParamPointerPromotionGoldens.test.d.ts +2 -0
- package/dist/quickVerify/quickParamPointerPromotionGoldens.test.d.ts.map +1 -0
- package/dist/quickVerify/quickParamPointerPromotionGoldens.test.js +34 -0
- package/dist/quickVerify/quickParamPointerPromotionGoldens.test.js.map +1 -0
- package/dist/quickVerify/quickParamPointerReplay.test.d.ts +2 -0
- package/dist/quickVerify/quickParamPointerReplay.test.d.ts.map +1 -0
- package/dist/quickVerify/quickParamPointerReplay.test.js +23 -0
- package/dist/quickVerify/quickParamPointerReplay.test.js.map +1 -0
- package/dist/quickVerify/quickVerifyProductTruth.d.ts +5 -1
- package/dist/quickVerify/quickVerifyProductTruth.d.ts.map +1 -1
- package/dist/quickVerify/quickVerifyProductTruth.js +6 -0
- package/dist/quickVerify/quickVerifyProductTruth.js.map +1 -1
- package/dist/quickVerify/quickVerifyScope.d.ts +2 -2
- package/dist/quickVerify/quickVerifyScope.d.ts.map +1 -1
- package/dist/quickVerify/quickVerifyScope.js +2 -2
- package/dist/quickVerify/quickVerifyScope.js.map +1 -1
- package/dist/quickVerify/rowUnit.d.ts +8 -0
- package/dist/quickVerify/rowUnit.d.ts.map +1 -1
- package/dist/quickVerify/rowUnit.js +17 -2
- package/dist/quickVerify/rowUnit.js.map +1 -1
- package/dist/quickVerify/runQuickVerify.d.ts.map +1 -1
- package/dist/quickVerify/runQuickVerify.js +102 -11
- package/dist/quickVerify/runQuickVerify.js.map +1 -1
- package/dist/quickVerify/tableScoring.d.ts.map +1 -1
- package/dist/quickVerify/tableScoring.js +6 -1
- package/dist/quickVerify/tableScoring.js.map +1 -1
- package/dist/quickVerify/verificationRequestFingerprint.d.ts +6 -0
- package/dist/quickVerify/verificationRequestFingerprint.d.ts.map +1 -0
- package/dist/quickVerify/verificationRequestFingerprint.js +23 -0
- package/dist/quickVerify/verificationRequestFingerprint.js.map +1 -0
- package/dist/quickVerify/verificationRequestFingerprint.test.d.ts +2 -0
- package/dist/quickVerify/verificationRequestFingerprint.test.d.ts.map +1 -0
- package/dist/quickVerify/verificationRequestFingerprint.test.js +26 -0
- package/dist/quickVerify/verificationRequestFingerprint.test.js.map +1 -0
- package/dist/schemaLoad.d.ts +1 -1
- package/dist/schemaLoad.d.ts.map +1 -1
- package/dist/schemaLoad.js +2 -0
- package/dist/schemaLoad.js.map +1 -1
- package/dist/standardVerifyWorkflowCli.d.ts +18 -0
- package/dist/standardVerifyWorkflowCli.d.ts.map +1 -1
- package/dist/standardVerifyWorkflowCli.js +45 -25
- package/dist/standardVerifyWorkflowCli.js.map +1 -1
- package/dist/telemetry/cliInstallId.d.ts +8 -0
- package/dist/telemetry/cliInstallId.d.ts.map +1 -0
- package/dist/telemetry/cliInstallId.js +72 -0
- package/dist/telemetry/cliInstallId.js.map +1 -0
- package/dist/telemetry/fetchWithTimeout.d.ts +6 -0
- package/dist/telemetry/fetchWithTimeout.d.ts.map +1 -0
- package/dist/telemetry/fetchWithTimeout.js +15 -0
- package/dist/telemetry/fetchWithTimeout.js.map +1 -0
- package/dist/telemetry/maybeEmitOssClaimTicketUrl.d.ts +8 -0
- package/dist/telemetry/maybeEmitOssClaimTicketUrl.d.ts.map +1 -0
- package/dist/telemetry/maybeEmitOssClaimTicketUrl.js +22 -0
- package/dist/telemetry/maybeEmitOssClaimTicketUrl.js.map +1 -0
- package/dist/telemetry/ossClaimOrigin.d.ts +6 -0
- package/dist/telemetry/ossClaimOrigin.d.ts.map +1 -0
- package/dist/telemetry/ossClaimOrigin.js +9 -0
- package/dist/telemetry/ossClaimOrigin.js.map +1 -0
- package/dist/telemetry/ossClaimOrigin.test.d.ts +2 -0
- package/dist/telemetry/ossClaimOrigin.test.d.ts.map +1 -0
- package/dist/telemetry/ossClaimOrigin.test.js +9 -0
- package/dist/telemetry/ossClaimOrigin.test.js.map +1 -0
- package/dist/telemetry/postOssClaimTicket.d.ts +14 -0
- package/dist/telemetry/postOssClaimTicket.d.ts.map +1 -0
- package/dist/telemetry/postOssClaimTicket.js +42 -0
- package/dist/telemetry/postOssClaimTicket.js.map +1 -0
- package/dist/telemetry/postProductActivationEvent.d.ts +25 -0
- package/dist/telemetry/postProductActivationEvent.d.ts.map +1 -0
- package/dist/telemetry/postProductActivationEvent.js +71 -0
- package/dist/telemetry/postProductActivationEvent.js.map +1 -0
- package/dist/telemetry/postProductActivationEvent.test.d.ts +2 -0
- package/dist/telemetry/postProductActivationEvent.test.d.ts.map +1 -0
- package/dist/telemetry/postProductActivationEvent.test.js +65 -0
- package/dist/telemetry/postProductActivationEvent.test.js.map +1 -0
- package/dist/telemetry/productActivationHeaders.d.ts +5 -0
- package/dist/telemetry/productActivationHeaders.d.ts.map +1 -0
- package/dist/telemetry/productActivationHeaders.js +5 -0
- package/dist/telemetry/productActivationHeaders.js.map +1 -0
- package/dist/telemetry/resolveTelemetrySource.d.ts +7 -0
- package/dist/telemetry/resolveTelemetrySource.d.ts.map +1 -0
- package/dist/telemetry/resolveTelemetrySource.js +10 -0
- package/dist/telemetry/resolveTelemetrySource.js.map +1 -0
- package/package.json +19 -9
- package/schemas/bootstrap-pack-input-v1.schema.json +61 -0
- package/schemas/quick-verify-report.schema.json +3 -3
package/README.md
CHANGED
|
@@ -3,9 +3,9 @@
|
|
|
3
3
|
<!-- discovery-readme-title:end -->
|
|
4
4
|
|
|
5
5
|
<!-- discovery-acquisition-fold:start -->
|
|
6
|
-
## Your
|
|
6
|
+
## Your traces say "success." Your database disagrees.
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
Verify your database state with read-only SQL before you ship, bill, or close. Not traces. Not logs. The actual database.
|
|
9
9
|
|
|
10
10
|
Teams ship agent and automation workflows where traces, tool responses, and success flags look green while the database row is missing, stale, or wrong. AgentSkeptic compares structured tool activity to read-only SQL against your SQLite or Postgres at verification time and reports whether observed state matched expectations derived from what the workflow claimed—not whether the step narrative read as successful.
|
|
11
11
|
|
|
@@ -52,10 +52,23 @@ steps:
|
|
|
52
52
|
}
|
|
53
53
|
```
|
|
54
54
|
|
|
55
|
-
[
|
|
55
|
+
[Read the product brief](https://agentskeptic.com/database-truth-vs-traces)
|
|
56
56
|
<!-- discovery-acquisition-fold:end -->
|
|
57
57
|
|
|
58
|
-
|
|
58
|
+
## Buy vs build: why not only SQL checks
|
|
59
|
+
|
|
60
|
+
**The scar (one pattern, over and over):** the trace says the tool succeeded—here **`crm.upsert_contact`** / **`contacts`**—but the row is missing or wrong. The repo demo names it **`wf_missing`** / **`ROW_ABSENT`**; **the same failure shape** applies whenever your registry maps tool activity to SQL state (ledgers, orders, tickets—not only CRM). That is not a logging problem—it is a **money and risk** problem the moment you ship, bill, close, or treat the run as audit evidence.
|
|
61
|
+
|
|
62
|
+
**Why “we’ll just write SQL checks” stops working**
|
|
63
|
+
|
|
64
|
+
- **Drift:** Scripts rot when schemas and workflows change; nobody keeps them current.
|
|
65
|
+
- **No ownership:** The author leaves; the checks become folklore.
|
|
66
|
+
- **Not an org contract:** Expectations live in heads and one-off files—not in a shared **`tools.json`** + **NDJSON** contract everyone replays.
|
|
67
|
+
- **CI and audit:** Ad-hoc checks are skipped locally and rarely ship as **repeatable artifacts**; when the issue is cross-team or compliance, scripts do not hold. Use **CI lock** / enforcement when you need pins ([`docs/ci-enforcement.md`](docs/ci-enforcement.md)).
|
|
68
|
+
|
|
69
|
+
**What you standardize on instead:** when the row backs revenue or customer promises, **you stop betting the business on whoever wrote the last script.** AgentSkeptic is how the org **owns** the check: one verifier, one replayable contract, **Quick → Contract** when stakes go up—explore with **Quick Verify** ([`docs/quick-verify-normative.md`](docs/quick-verify-normative.md)), lock with **contract** mode and a **`tools.json`** registry when “we ran a query” is not evidence ([`docs/agentskeptic.md`](docs/agentskeptic.md)). **That is the responsible default** once the failure mode hurts.
|
|
70
|
+
|
|
71
|
+
**Core mechanism:** Read-only SQL checks that your database **at verification time** matches **expectations derived from structured tool activity**—not whether a trace step “succeeded.”
|
|
59
72
|
|
|
60
73
|
<!-- public-product-anchors:start -->
|
|
61
74
|
State verification engine: read-only SQL checks that database state matches expectations from structured tool activity (not arbitrary logs)—not proof of execution
|
|
@@ -73,9 +86,11 @@ State verification engine: read-only SQL checks that database state matches expe
|
|
|
73
86
|
|
|
74
87
|
## Try it (about one minute)
|
|
75
88
|
|
|
89
|
+
This is the fastest way to see **`ROW_ABSENT`** versus **verified** on the same screen—the concrete failure mode the section above is about (bundled CRM-style demo, not your production incident yet).
|
|
90
|
+
|
|
76
91
|
**Prerequisite:** **Node.js ≥ 22.13** (built-in [`node:sqlite`](https://nodejs.org/api/sqlite.html)), or use [Docker](#docker-quickstart-optional) below.
|
|
77
92
|
|
|
78
|
-
**Fast first run on your own DB (bundled
|
|
93
|
+
**Fast first run on your own DB (bundled quickstart example):** after `npm install` and `npm run build`, run **`npm run partner-quickstart`** from the repo root (SQLite temp DB). Commands reference: **[`docs/partner-quickstart-commands.md`](docs/partner-quickstart-commands.md)**; narrative: **[`docs/first-run-integration.md`](docs/first-run-integration.md)** and **`/integrate`** on the site.
|
|
79
94
|
|
|
80
95
|
```bash
|
|
81
96
|
npm install
|
|
@@ -102,18 +117,6 @@ docker run --rm -it -v "$PWD:/work" -w /work node:22-bookworm bash -lc "npm inst
|
|
|
102
117
|
docker run --rm -it -v "${PWD}:/work" -w /work node:22-bookworm bash -lc "npm install && npm start"
|
|
103
118
|
```
|
|
104
119
|
|
|
105
|
-
## Canonical use case
|
|
106
|
-
|
|
107
|
-
**AI support or CRM-style workflows:** structured activity says the ticket or contact should look a certain way; the trace may still show success. This tool compares **expected** row shape from that activity to **observed** SQL—**inconsistent** when the row is wrong or missing, even when the narrative looked fine.
|
|
108
|
-
|
|
109
|
-
## How to run the CLI
|
|
110
|
-
|
|
111
|
-
- **After `npm install` and `npm run build` in this repo:** use **`agentskeptic`** (from `package.json` `bin`, pointing at `dist/cli.js`). Examples: `npm run agentskeptic -- --help` or `npx agentskeptic --help` from the repo root.
|
|
112
|
-
- **From a published install** (when you install the `agentskeptic` package): same command—**`agentskeptic`** on your `PATH`.
|
|
113
|
-
- **Explicit path from source:** **`node dist/cli.js`** — same entrypoint as **`agentskeptic`**; use this when you want a literal path after **`npm run build`**.
|
|
114
|
-
|
|
115
|
-
Postgres: use **`--postgres-url "postgresql://…"`** instead of **`--db <sqlitePath>`** (exactly one of the two).
|
|
116
|
-
|
|
117
120
|
## Minimal model (event → registry → result)
|
|
118
121
|
|
|
119
122
|
**One structured observation** (NDJSON line; full schema in [Event line schema](docs/agentskeptic.md#event-line-schema)):
|
|
@@ -158,13 +161,11 @@ Retries, partial failures, and race conditions mean a success flag in a trace is
|
|
|
158
161
|
| A verifier for **persisted state** after agent or automation workflows | A test runner for application code |
|
|
159
162
|
| Proof that **observed DB state matched expectations** at verification time | Proof that a tool **executed**, **wrote**, or **caused** that state |
|
|
160
163
|
|
|
161
|
-
**This is for you if** you need SQL
|
|
164
|
+
**This is for you if** you need persisted-row SQL truth after agent or automation runs when the trace looks fine but the DB might not.
|
|
162
165
|
|
|
163
|
-
**This is not for you if** you need proof a tool executed,
|
|
166
|
+
**This is not for you if** you need proof a tool executed, log search as verification, or a model where read-only SQL against your app DB is not the right check. Homepage “for you / not for you” copy lives in **`website/src/content/productCopy.ts`** (single source with the site).
|
|
164
167
|
|
|
165
|
-
**Trust boundary (once):** a green trace
|
|
166
|
-
|
|
167
|
-
**Web-facing qualification** (“for you” / “not for you” on the commercial site) is maintained in **`website/src/content/productCopy.ts`** so homepage copy does not drift from a second source in this README.
|
|
168
|
+
**Trust boundary (once):** a green trace does **not** prove the row exists with the right values—only whether **read-only `SELECT`s** matched **expected** rows under your rules, not deep causality.
|
|
168
169
|
|
|
169
170
|
**Declared → expected → observed** (how reports reason about runs):
|
|
170
171
|
|
|
@@ -174,6 +175,8 @@ Retries, partial failures, and race conditions mean a success flag in a trace is
|
|
|
174
175
|
|
|
175
176
|
## Contract path (registry + events)
|
|
176
177
|
|
|
178
|
+
**CLI:** after **`npm install`** and **`npm run build`**, use **`agentskeptic`** (or **`npx agentskeptic`**, or **`node dist/cli.js`**). Postgres: **`--postgres-url`** instead of **`--db`** (exactly one).
|
|
179
|
+
|
|
177
180
|
Typical integration:
|
|
178
181
|
|
|
179
182
|
1. Emit **one NDJSON line per tool observation** (see [Event line schema](docs/agentskeptic.md#event-line-schema)).
|
|
@@ -185,26 +188,19 @@ npm run build
|
|
|
185
188
|
agentskeptic --workflow-id <id> --events <path> --registry <path> --db <sqlitePath>
|
|
186
189
|
```
|
|
187
190
|
|
|
188
|
-
Replay the bundled demo
|
|
189
|
-
|
|
190
|
-
```bash
|
|
191
|
-
npm run build
|
|
192
|
-
agentskeptic --workflow-id wf_complete --events examples/events.ndjson --registry examples/tools.json --db examples/demo.db
|
|
193
|
-
```
|
|
191
|
+
Replay the bundled files: **`wf_complete`** / **`examples/events.ndjson`** / **`examples/tools.json`** / **`examples/demo.db`** (same flags as above).
|
|
194
192
|
|
|
195
193
|
**From source without `agentskeptic` on PATH:** `node dist/cli.js` with the same flags.
|
|
196
194
|
|
|
197
195
|
**Why SQLite in the demo:** file-backed ground truth with no extra services. The demo (re)creates **`examples/demo.db`**; verification still uses read-only SQL.
|
|
198
196
|
|
|
199
|
-
## Quick Verify (optional
|
|
197
|
+
## Quick Verify and assurance (optional)
|
|
198
|
+
|
|
199
|
+
**Quick Verify** (`agentskeptic quick`): inferred checks, **no registry file**; **provisional**, not audit-final—graduate to **contract mode** for explicit per-tool expectations. Full contract: **[`docs/quick-verify-normative.md`](docs/quick-verify-normative.md)**.
|
|
200
200
|
|
|
201
201
|
**Input contract:** We only accept **structured tool activity**—JSON or NDJSON that describes tool calls and parameters our ingest model can extract—not arbitrary logs, traces, or unstructured observability text.
|
|
202
202
|
Verification uses read-only SQL against your database; API-only or non-SQL systems are out of scope for this tool.
|
|
203
203
|
|
|
204
|
-
**Quick Verify** runs **`agentskeptic quick`** with structured tool activity and a DB: inferred checks, no registry file. It is **provisional**—rollup pass/fail/uncertain is **not** an audit-final verdict; prefer **contract mode** when you need explicit per-tool expectations.
|
|
205
|
-
|
|
206
|
-
Full behavior, stdout/stderr contracts, exit codes, and replay caveats: **[`docs/quick-verify-normative.md`](docs/quick-verify-normative.md)** and **[`docs/agentskeptic.md`](docs/agentskeptic.md)** (Quick Verify sections). Product framing: **[`docs/verification-product-ssot.md`](docs/verification-product-ssot.md)**.
|
|
207
|
-
|
|
208
204
|
```bash
|
|
209
205
|
npm run build
|
|
210
206
|
agentskeptic quick --input test/fixtures/quick-verify/pass-line.ndjson --db examples/demo.db --export-registry ./quick-export.json
|
|
@@ -212,61 +208,18 @@ agentskeptic quick --input test/fixtures/quick-verify/pass-line.ndjson --db exam
|
|
|
212
208
|
|
|
213
209
|
Use **`--postgres-url`** instead of **`--db`**; **`-`** as **`--input`** reads stdin.
|
|
214
210
|
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
**Trust over time** uses **`agentskeptic assurance run`** with a versioned **manifest** (multi-scenario sweep by spawning the CLI) and **`agentskeptic assurance stale`** to fail closed when a saved **`AssuranceRunReport`** is missing, invalid, or older than **`--max-age-hours`**. Bundled example manifest: **[`examples/assurance/manifest.json`](examples/assurance/manifest.json)**. Normative I/O and schemas: **[Assurance subsystem](docs/agentskeptic.md#assurance-subsystem-normative)** in **`docs/agentskeptic.md`**.
|
|
211
|
+
**Assurance** (`assurance run` / `assurance stale`): multi-scenario sweeps and staleness over saved reports—**[Assurance subsystem](docs/agentskeptic.md#assurance-subsystem-normative)**, **[`examples/assurance/manifest.json`](examples/assurance/manifest.json)**.
|
|
218
212
|
|
|
219
213
|
## Sample output (contract demo)
|
|
220
214
|
|
|
221
|
-
The **`npm start`** driver prints
|
|
215
|
+
The **`npm start`** driver prints human report + workflow JSON to **stdout** (one stream for the demo). Normal CLI: machine JSON on **stdout**, human report on **stderr**—[Human truth report](docs/agentskeptic.md#human-truth-report). **Full success/failure transcripts** (same strings as below) are in the [acquisition fold](#your-traces-say-success-your-database-disagrees) at the top of this README.
|
|
222
216
|
|
|
223
217
|
### Success (`wf_complete`)
|
|
224
218
|
|
|
225
|
-
```text
|
|
226
|
-
workflow_id: wf_complete
|
|
227
|
-
workflow_status: complete
|
|
228
|
-
trust: TRUSTED: Every step matched the database under the configured verification rules.
|
|
229
|
-
steps:
|
|
230
|
-
- seq=0 tool=crm.upsert_contact result=Matched the database.
|
|
231
|
-
```
|
|
232
|
-
|
|
233
|
-
```json
|
|
234
|
-
{
|
|
235
|
-
"schemaVersion": 15,
|
|
236
|
-
"workflowId": "wf_complete",
|
|
237
|
-
"status": "complete",
|
|
238
|
-
"steps": [{ "seq": 0, "toolId": "crm.upsert_contact", "status": "verified" }]
|
|
239
|
-
}
|
|
240
|
-
```
|
|
241
|
-
|
|
242
219
|
*Interpretation:* Under the configured rules, **expected** state matched **observed SQL** for this step—**state alignment**, not proof of execution.
|
|
243
220
|
|
|
244
221
|
### Failure (`wf_missing`)
|
|
245
222
|
|
|
246
|
-
```text
|
|
247
|
-
workflow_id: wf_missing
|
|
248
|
-
workflow_status: inconsistent
|
|
249
|
-
steps:
|
|
250
|
-
- seq=0 tool=crm.upsert_contact result=Expected row is missing from the database (the log implies a write that is not present).
|
|
251
|
-
reference_code: ROW_ABSENT
|
|
252
|
-
```
|
|
253
|
-
|
|
254
|
-
```json
|
|
255
|
-
{
|
|
256
|
-
"schemaVersion": 15,
|
|
257
|
-
"workflowId": "wf_missing",
|
|
258
|
-
"status": "inconsistent",
|
|
259
|
-
"steps": [
|
|
260
|
-
{
|
|
261
|
-
"seq": 0,
|
|
262
|
-
"toolId": "crm.upsert_contact",
|
|
263
|
-
"status": "missing",
|
|
264
|
-
"reasons": [{ "code": "ROW_ABSENT" }]
|
|
265
|
-
}
|
|
266
|
-
]
|
|
267
|
-
}
|
|
268
|
-
```
|
|
269
|
-
|
|
270
223
|
*Interpretation:* **Expected** state from the tool activity implied a row **observed SQL** did not find—**inconsistent**—a gap traces alone often miss. Still not proof a write was attempted or rolled back.
|
|
271
224
|
|
|
272
225
|
## How this differs from logs, tests, and observability
|
|
@@ -276,6 +229,7 @@ steps:
|
|
|
276
229
|
| **Logs / traces** | A step ran, duration, errors—not “row X has columns Y.” |
|
|
277
230
|
| **Unit / integration tests** | Code paths in your repo—not production agent runs against live DB state. |
|
|
278
231
|
| **Metrics / APM** | Health and latency—not semantic equality of persisted records. |
|
|
232
|
+
| **Ad-hoc SQL checks / one-off scripts** | Same failure mode as [**Buy vs build**](#buy-vs-build-why-not-only-sql-checks)—drift, weak ownership, not a durable contract. |
|
|
279
233
|
| **agentskeptic** | Whether **observed SQL** matches **expectations from declared tool parameters** (contract mode), via read-only SQL—not proof the tool executed. |
|
|
280
234
|
|
|
281
235
|
## When to run it
|
|
@@ -288,36 +242,28 @@ Run **after** a workflow (or CI replay of its log), **before** you treat the out
|
|
|
288
242
|
|
|
289
243
|
**CI with pinned outcomes:** **`agentskeptic enforce`** and committed **`ci-lock-v1`** fixtures—[`docs/ci-enforcement.md`](docs/ci-enforcement.md).
|
|
290
244
|
|
|
291
|
-
##
|
|
292
|
-
|
|
293
|
-
Optional capabilities; full detail in **[`docs/agentskeptic.md`](docs/agentskeptic.md)**.
|
|
245
|
+
## Further capabilities (reference)
|
|
294
246
|
|
|
295
|
-
|
|
296
|
-
|------|--------|
|
|
297
|
-
| **Cross-run compare** | `agentskeptic compare` — [Cross-run comparison](docs/agentskeptic.md#cross-run-comparison-normative) |
|
|
298
|
-
| **Execution trace** | `agentskeptic execution-trace` — [End-to-end execution visibility](docs/agentskeptic.md#end-to-end-execution-visibility-normative) |
|
|
299
|
-
| **In-process hook** | SQLite **`withWorkflowVerification`** — [Low-friction integration](docs/agentskeptic.md#low-friction-integration-in-process) |
|
|
300
|
-
| **Registry validation** | `agentskeptic validate-registry` — [Registry validation](docs/agentskeptic.md#registry-validation-validate-registry--normative) |
|
|
301
|
-
| **Run bundles / signing** | [Agent run record](docs/agentskeptic.md#agent-run-record-canonical-bundle), [Signing](docs/agentskeptic.md#cryptographic-signing-of-workflow-result-normative) |
|
|
302
|
-
| **Debug Console** | `agentskeptic debug` — [Debug Console](docs/agentskeptic.md#debug-console-normative) |
|
|
303
|
-
| **Plan transition** | `agentskeptic plan-transition` — [Plan transition validation](docs/agentskeptic.md#plan-transition-validation-normative) |
|
|
304
|
-
|
|
305
|
-
Streams, exit codes, and operational errors: [Human truth report](docs/agentskeptic.md#human-truth-report), [CLI operational errors](docs/agentskeptic.md#cli-operational-errors).
|
|
247
|
+
Everything beyond core contract verification lives in **[`docs/agentskeptic.md`](docs/agentskeptic.md)**—subcommands, hooks, bundles, debug, plan transition, human report layout, exit codes.
|
|
306
248
|
|
|
307
249
|
## Documentation map
|
|
308
250
|
|
|
309
251
|
| Doc | Purpose |
|
|
310
252
|
|-----|---------|
|
|
253
|
+
| [README — Buy vs build](#buy-vs-build-why-not-only-sql-checks) | Canonical **buy vs build** narrative (failure mode, scripts limits, Quick → Contract) |
|
|
311
254
|
| [`docs/agentskeptic.md`](docs/agentskeptic.md) | Authoritative CLI and behavior reference (SSOT) |
|
|
312
255
|
| [`docs/quick-verify-normative.md`](docs/quick-verify-normative.md) | Quick Verify normative contract |
|
|
313
|
-
| [`docs/verification-product-ssot.md`](docs/verification-product-ssot.md) | Product
|
|
256
|
+
| [`docs/verification-product-ssot.md`](docs/verification-product-ssot.md) | Product intent, trust boundary, authority matrix |
|
|
257
|
+
| [`docs/reconciliation-vocabulary-ssot.md`](docs/reconciliation-vocabulary-ssot.md) | Reconciliation dimension IDs and UI mapping |
|
|
258
|
+
| [`docs/verification-operational-notes.md`](docs/verification-operational-notes.md) | First-run runbooks, TTFV, export vs replay coverage |
|
|
259
|
+
| [`docs/langgraph-reference-boundaries-ssot.md`](docs/langgraph-reference-boundaries-ssot.md) | LangGraph reference path: emitter/CLI boundaries and test chain |
|
|
314
260
|
| [`docs/relational-verification.md`](docs/relational-verification.md) | Relational verification semantics |
|
|
315
261
|
| [`docs/ci-enforcement.md`](docs/ci-enforcement.md) | CI enforcement and lock fixtures |
|
|
316
262
|
| [`docs/correctness-definition-normative.md`](docs/correctness-definition-normative.md) | Correctness and limits (normative) |
|
|
317
263
|
|
|
318
264
|
## Development and testing
|
|
319
265
|
|
|
320
|
-
**Why SQLite
|
|
266
|
+
**Why SQLite:** same note as under [Contract path](#contract-path-registry--events) (file-backed demo DB; read-only verification SQL).
|
|
321
267
|
|
|
322
268
|
Runs build, Vitest, SQLite Node tests, first-run demo, `assurance run`, the commercial enforce test harness (minimal CI enforcement + enforce integration tests), and TTFV validation. No Postgres required.
|
|
323
269
|
|
|
@@ -325,11 +271,7 @@ Runs build, Vitest, SQLite Node tests, first-run demo, `assurance run`, the comm
|
|
|
325
271
|
|
|
326
272
|
## Commercial CLI (npm) vs OSS (this repo)
|
|
327
273
|
|
|
328
|
-
- **
|
|
329
|
-
- **Published npm (commercial profile)** is built with **`npm run build:commercial`** and **`COMMERCIAL_LICENSE_API_BASE_URL`**; it **requires** an API key, an **active subscription** (Individual, Team, or Business self-serve, or Enterprise; trial counts) for **licensed** **batch**, **`quick`**, **CI lock flags**, and **`enforce`**, and successful **`POST /api/v1/usage/reserve`** preflight. **Entitlement matrix:** **[`docs/commercial-entitlement-matrix.md`](docs/commercial-entitlement-matrix.md)** (generated). **Policy:** **[`docs/commercial-entitlement-policy.md`](docs/commercial-entitlement-policy.md)**. **Machine contracts:** **`GET /api/v1/commercial/plans`** and **`/openapi-commercial-v1.yaml`** — **[`docs/commercial-ssot.md`](docs/commercial-ssot.md)**.
|
|
330
|
-
- **Production CI** should install **`agentskeptic@latest`** from npm, set **`AGENTSKEPTIC_API_KEY`** (legacy **`WORKFLOW_VERIFIER_API_KEY`** still accepted), and use a reachable license API. Example: **[`examples/github-actions/agentskeptic-commercial.yml`](examples/github-actions/agentskeptic-commercial.yml)**.
|
|
331
|
-
- **Website + billing:** [`website/`](website/), **[`docs/commercial-ssot.md`](docs/commercial-ssot.md)**. First-run on your DB: **[`docs/first-run-integration.md`](docs/first-run-integration.md)** and **`/integrate`**.
|
|
332
|
-
- **Validation:** `npm run validate-commercial` requires **`DATABASE_URL`**, runs **`drizzle-kit migrate`**, runs website Vitest, then **`scripts/pack-smoke-commercial.mjs`** (commercial **`npm pack`** gate), then **`npm run build`** to restore OSS **`dist/`**, and writes [`artifacts/commercial-validation-verdict.json`](artifacts/commercial-validation-verdict.json). Optional: set **`COMMERCIAL_LICENSE_API_BASE_URL`** for the pack-smoke step (defaults to `https://pack-smoke.example.com`). Set **`COMMERCIAL_VALIDATE_PLAYWRIGHT=1`** for Playwright; see **`scripts/run-commercial-e2e.mjs`**. Quick pack check only: **`npm run pack-smoke`** (requires **`COMMERCIAL_LICENSE_API_BASE_URL`** for a real commercial build, or uses the script default URL).
|
|
274
|
+
Canonical write-up: **[`docs/commercial-ssot.md`](docs/commercial-ssot.md)** (npm package, Stripe, keys, telemetry, validation, entitlements; operator metrics in **[`docs/funnel-observability-ssot.md`](docs/funnel-observability-ssot.md)**—disable with **`AGENTSKEPTIC_TELEMETRY=0`**). OSS builds in this repo run contract **`verify`** without a license server; **`enforce`**, CI locks, and lock flags on **`quick`/batch** require a commercial build per **[`docs/commercial-enforce-gate-normative.md`](docs/commercial-enforce-gate-normative.md)**. Example workflow: **[`examples/github-actions/agentskeptic-commercial.yml`](examples/github-actions/agentskeptic-commercial.yml)**.
|
|
333
275
|
|
|
334
276
|
## Status, contributing, security
|
|
335
277
|
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"bootstrapReadmeTemplate.d.ts","sourceRoot":"","sources":["../../src/bootstrap/bootstrapReadmeTemplate.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAcvE"}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/** Fixed template for README.bootstrap.md (workflowId substituted). */
|
|
2
|
+
export function buildBootstrapReadmeMarkdown(workflowId) {
|
|
3
|
+
return `# Bootstrap pack (generated)
|
|
4
|
+
|
|
5
|
+
This directory was produced by \`agentskeptic bootstrap\`.
|
|
6
|
+
|
|
7
|
+
\`quick-report.json\` is a full Quick Verify report and remains **provisional** (see \`productTruth\` in that JSON). For contract verification against the same database you used for bootstrap:
|
|
8
|
+
|
|
9
|
+
\`\`\`bash
|
|
10
|
+
agentskeptic verify --workflow-id ${workflowId} --events ./events.ndjson --registry ./tools.json --db <path-to-same-sqlite.db>
|
|
11
|
+
\`\`\`
|
|
12
|
+
|
|
13
|
+
Use \`--postgres-url\` instead of \`--db\` when verifying against Postgres.
|
|
14
|
+
|
|
15
|
+
`;
|
|
16
|
+
}
|
|
17
|
+
//# sourceMappingURL=bootstrapReadmeTemplate.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"bootstrapReadmeTemplate.js","sourceRoot":"","sources":["../../src/bootstrap/bootstrapReadmeTemplate.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,MAAM,UAAU,4BAA4B,CAAC,UAAkB;IAC7D,OAAO;;;;;;;oCAO2B,UAAU;;;;;CAK7C,CAAC;AACF,CAAC"}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
export type ParsedBootstrapPackInput = {
|
|
2
|
+
workflowId: string;
|
|
3
|
+
toolCalls: Array<{
|
|
4
|
+
id: string;
|
|
5
|
+
function: {
|
|
6
|
+
name: string;
|
|
7
|
+
arguments: string;
|
|
8
|
+
};
|
|
9
|
+
}>;
|
|
10
|
+
};
|
|
11
|
+
/**
|
|
12
|
+
* Parse and validate `BootstrapPackInput` v1 per docs/bootstrap-pack-normative.md.
|
|
13
|
+
* @throws TruthLayerError with BOOTSTRAP_* codes
|
|
14
|
+
*/
|
|
15
|
+
export declare function parseBootstrapPackInputJson(rawUtf8: string): ParsedBootstrapPackInput;
|
|
16
|
+
//# sourceMappingURL=parseBootstrapPackInput.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"parseBootstrapPackInput.d.ts","sourceRoot":"","sources":["../../src/bootstrap/parseBootstrapPackInput.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,wBAAwB,GAAG;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,KAAK,CAAC;QACf,EAAE,EAAE,MAAM,CAAC;QACX,QAAQ,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAA;SAAE,CAAC;KAC/C,CAAC,CAAC;CACJ,CAAC;AAMF;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,MAAM,GAAG,wBAAwB,CAoHrF"}
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
import { CLI_OPERATIONAL_CODES } from "../cliOperationalCodes.js";
|
|
2
|
+
import { loadSchemaValidator } from "../schemaLoad.js";
|
|
3
|
+
import { TruthLayerError } from "../truthLayerError.js";
|
|
4
|
+
function isPlainObject(v) {
|
|
5
|
+
return v !== null && typeof v === "object" && !Array.isArray(v);
|
|
6
|
+
}
|
|
7
|
+
/**
|
|
8
|
+
* Parse and validate `BootstrapPackInput` v1 per docs/bootstrap-pack-normative.md.
|
|
9
|
+
* @throws TruthLayerError with BOOTSTRAP_* codes
|
|
10
|
+
*/
|
|
11
|
+
export function parseBootstrapPackInputJson(rawUtf8) {
|
|
12
|
+
let parsed;
|
|
13
|
+
try {
|
|
14
|
+
parsed = JSON.parse(rawUtf8);
|
|
15
|
+
}
|
|
16
|
+
catch (e) {
|
|
17
|
+
const msg = e instanceof Error ? e.message : String(e);
|
|
18
|
+
throw new TruthLayerError(CLI_OPERATIONAL_CODES.BOOTSTRAP_INPUT_INVALID, `Bootstrap input is not valid JSON: ${msg}`);
|
|
19
|
+
}
|
|
20
|
+
const validate = loadSchemaValidator("bootstrap-pack-input-v1");
|
|
21
|
+
if (!validate(parsed)) {
|
|
22
|
+
throw new TruthLayerError(CLI_OPERATIONAL_CODES.BOOTSTRAP_INPUT_INVALID, JSON.stringify(validate.errors ?? []));
|
|
23
|
+
}
|
|
24
|
+
const root = parsed;
|
|
25
|
+
const workflowId = root.workflowId;
|
|
26
|
+
if (typeof workflowId !== "string") {
|
|
27
|
+
throw new TruthLayerError(CLI_OPERATIONAL_CODES.BOOTSTRAP_INPUT_INVALID, "workflowId must be a string.");
|
|
28
|
+
}
|
|
29
|
+
const oc = root.openaiChatCompletion;
|
|
30
|
+
if (!isPlainObject(oc)) {
|
|
31
|
+
throw new TruthLayerError(CLI_OPERATIONAL_CODES.BOOTSTRAP_INPUT_INVALID, "openaiChatCompletion must be an object.");
|
|
32
|
+
}
|
|
33
|
+
const choices = oc.choices;
|
|
34
|
+
if (!Array.isArray(choices) || choices.length < 1) {
|
|
35
|
+
throw new TruthLayerError(CLI_OPERATIONAL_CODES.BOOTSTRAP_INPUT_INVALID, "choices must be a non-empty array.");
|
|
36
|
+
}
|
|
37
|
+
const c0 = choices[0];
|
|
38
|
+
if (!isPlainObject(c0)) {
|
|
39
|
+
throw new TruthLayerError(CLI_OPERATIONAL_CODES.BOOTSTRAP_INPUT_INVALID, "choices[0] must be an object.");
|
|
40
|
+
}
|
|
41
|
+
const message = c0.message;
|
|
42
|
+
if (!isPlainObject(message)) {
|
|
43
|
+
throw new TruthLayerError(CLI_OPERATIONAL_CODES.BOOTSTRAP_INPUT_INVALID, "choices[0].message must be an object.");
|
|
44
|
+
}
|
|
45
|
+
const toolCallsRaw = message.tool_calls;
|
|
46
|
+
if (!Array.isArray(toolCallsRaw)) {
|
|
47
|
+
throw new TruthLayerError(CLI_OPERATIONAL_CODES.BOOTSTRAP_INPUT_INVALID, "choices[0].message.tool_calls must be an array.");
|
|
48
|
+
}
|
|
49
|
+
if (toolCallsRaw.length === 0) {
|
|
50
|
+
throw new TruthLayerError(CLI_OPERATIONAL_CODES.BOOTSTRAP_NO_TOOL_CALLS, "tool_calls is empty.");
|
|
51
|
+
}
|
|
52
|
+
const toolCalls = [];
|
|
53
|
+
for (let i = 0; i < toolCallsRaw.length; i++) {
|
|
54
|
+
const tc = toolCallsRaw[i];
|
|
55
|
+
if (!isPlainObject(tc)) {
|
|
56
|
+
throw new TruthLayerError(CLI_OPERATIONAL_CODES.BOOTSTRAP_INPUT_INVALID, `tool_calls[${i}] must be an object.`);
|
|
57
|
+
}
|
|
58
|
+
if (tc.type !== "function") {
|
|
59
|
+
throw new TruthLayerError(CLI_OPERATIONAL_CODES.BOOTSTRAP_INPUT_INVALID, `tool_calls[${i}].type must be "function".`);
|
|
60
|
+
}
|
|
61
|
+
const id = tc.id;
|
|
62
|
+
if (typeof id !== "string" || id.length === 0) {
|
|
63
|
+
throw new TruthLayerError(CLI_OPERATIONAL_CODES.BOOTSTRAP_INPUT_INVALID, `tool_calls[${i}].id must be a non-empty string.`);
|
|
64
|
+
}
|
|
65
|
+
const fn = tc.function;
|
|
66
|
+
if (!isPlainObject(fn)) {
|
|
67
|
+
throw new TruthLayerError(CLI_OPERATIONAL_CODES.BOOTSTRAP_INPUT_INVALID, `tool_calls[${i}].function must be an object.`);
|
|
68
|
+
}
|
|
69
|
+
const name = fn.name;
|
|
70
|
+
const argsStr = fn.arguments;
|
|
71
|
+
if (typeof name !== "string" || name.length === 0) {
|
|
72
|
+
throw new TruthLayerError(CLI_OPERATIONAL_CODES.BOOTSTRAP_INPUT_INVALID, `tool_calls[${i}].function.name must be a non-empty string.`);
|
|
73
|
+
}
|
|
74
|
+
if (typeof argsStr !== "string") {
|
|
75
|
+
throw new TruthLayerError(CLI_OPERATIONAL_CODES.BOOTSTRAP_INPUT_INVALID, `tool_calls[${i}].function.arguments must be a string.`);
|
|
76
|
+
}
|
|
77
|
+
let argsParsed;
|
|
78
|
+
try {
|
|
79
|
+
argsParsed = JSON.parse(argsStr);
|
|
80
|
+
}
|
|
81
|
+
catch (e) {
|
|
82
|
+
const msg = e instanceof Error ? e.message : String(e);
|
|
83
|
+
throw new TruthLayerError(CLI_OPERATIONAL_CODES.BOOTSTRAP_TOOL_CALL_ARGUMENTS_INVALID, `JSON.parse(function.arguments) failed (tool_calls[i] i=${i}): ${msg}`);
|
|
84
|
+
}
|
|
85
|
+
if (argsParsed === null || typeof argsParsed !== "object" || Array.isArray(argsParsed)) {
|
|
86
|
+
throw new TruthLayerError(CLI_OPERATIONAL_CODES.BOOTSTRAP_TOOL_CALL_ARGUMENTS_INVALID, `function.arguments must parse to a JSON object, not array or primitive (tool_calls[i] i=${i}).`);
|
|
87
|
+
}
|
|
88
|
+
toolCalls.push({
|
|
89
|
+
id,
|
|
90
|
+
function: { name, arguments: argsStr },
|
|
91
|
+
});
|
|
92
|
+
}
|
|
93
|
+
return { workflowId, toolCalls };
|
|
94
|
+
}
|
|
95
|
+
//# sourceMappingURL=parseBootstrapPackInput.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"parseBootstrapPackInput.js","sourceRoot":"","sources":["../../src/bootstrap/parseBootstrapPackInput.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"parseBootstrapPackInput.test.d.ts","sourceRoot":"","sources":["../../src/bootstrap/parseBootstrapPackInput.test.ts"],"names":[],"mappings":""}
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import { readFileSync } from "node:fs";
|
|
2
|
+
import path from "node:path";
|
|
3
|
+
import { describe, expect, it } from "vitest";
|
|
4
|
+
import { CLI_OPERATIONAL_CODES } from "../cliOperationalCodes.js";
|
|
5
|
+
import { TruthLayerError } from "../truthLayerError.js";
|
|
6
|
+
import { parseBootstrapPackInputJson } from "./parseBootstrapPackInput.js";
|
|
7
|
+
import { synthesizeQuickInputUtf8FromOpenAiV1 } from "./synthesizeQuickInputFromOpenAiV1.js";
|
|
8
|
+
const root = process.cwd();
|
|
9
|
+
const goldenInput = readFileSync(path.join(root, "test", "fixtures", "bootstrap-pack", "input.json"), "utf8");
|
|
10
|
+
describe("parseBootstrapPackInputJson", () => {
|
|
11
|
+
it("parses fixture and preserves tool call arguments verbatim", () => {
|
|
12
|
+
const p = parseBootstrapPackInputJson(goldenInput);
|
|
13
|
+
expect(p.workflowId).toBe("wf_bootstrap_fixture");
|
|
14
|
+
expect(p.toolCalls).toHaveLength(1);
|
|
15
|
+
expect(p.toolCalls[0].function.name).toBe("crm.upsert_contact");
|
|
16
|
+
expect(p.toolCalls[0].function.arguments).toBe('{"recordId":"c_ok","fields":{"name":"Alice","status":"active"}}');
|
|
17
|
+
});
|
|
18
|
+
it("rejects empty tool_calls", () => {
|
|
19
|
+
const raw = readFileSync(path.join(root, "test", "fixtures", "bootstrap-pack", "input-empty-tool-calls.json"), "utf8");
|
|
20
|
+
expect(() => parseBootstrapPackInputJson(raw)).toThrow(TruthLayerError);
|
|
21
|
+
try {
|
|
22
|
+
parseBootstrapPackInputJson(raw);
|
|
23
|
+
}
|
|
24
|
+
catch (e) {
|
|
25
|
+
expect(e.code).toBe(CLI_OPERATIONAL_CODES.BOOTSTRAP_NO_TOOL_CALLS);
|
|
26
|
+
}
|
|
27
|
+
});
|
|
28
|
+
});
|
|
29
|
+
describe("synthesizeQuickInputUtf8FromOpenAiV1", () => {
|
|
30
|
+
it("emits one NDJSON line per tool call with stable key order", () => {
|
|
31
|
+
const p = parseBootstrapPackInputJson(goldenInput);
|
|
32
|
+
const utf8 = synthesizeQuickInputUtf8FromOpenAiV1(p);
|
|
33
|
+
const lines = utf8.trim().split("\n");
|
|
34
|
+
expect(lines).toHaveLength(1);
|
|
35
|
+
const line = JSON.parse(lines[0]);
|
|
36
|
+
expect(line.tool_calls).toHaveLength(1);
|
|
37
|
+
expect(line.tool_calls[0].id).toBe("call_fixture_1");
|
|
38
|
+
expect(line.tool_calls[0].type).toBe("function");
|
|
39
|
+
expect(line.tool_calls[0].function.name).toBe("crm.upsert_contact");
|
|
40
|
+
expect(JSON.parse(line.tool_calls[0].function.arguments)).toEqual({
|
|
41
|
+
recordId: "c_ok",
|
|
42
|
+
fields: { name: "Alice", status: "active" },
|
|
43
|
+
});
|
|
44
|
+
});
|
|
45
|
+
});
|
|
46
|
+
//# sourceMappingURL=parseBootstrapPackInput.test.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"parseBootstrapPackInput.test.js","sourceRoot":"","sources":["../../src/bootstrap/parseBootstrapPackInput.test.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
export type ParsedBootstrapCli = {
|
|
2
|
+
inputPath: string;
|
|
3
|
+
outPath: string;
|
|
4
|
+
dbPath: string | undefined;
|
|
5
|
+
postgresUrl: string | undefined;
|
|
6
|
+
};
|
|
7
|
+
export declare function parseBootstrapCliArgs(args: string[]): ParsedBootstrapCli;
|
|
8
|
+
export declare function runBootstrapSubcommand(args: string[]): Promise<void>;
|
|
9
|
+
//# sourceMappingURL=runBootstrapSubcommand.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"runBootstrapSubcommand.d.ts","sourceRoot":"","sources":["../../src/bootstrap/runBootstrapSubcommand.ts"],"names":[],"mappings":"AAuEA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC,CAAC;AAEF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,kBAAkB,CAiBxE;AAcD,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAmM1E"}
|