@augmentworks/cli 0.4.0

[0.4.0] - 2026-10-17

Major release. Requires Node.js 22.12 or newer. Hosted authorized real-data
tests work end to end: register your own agent as a workspace target, verify
it, create a test scope, and run test --suite, in four CLI commands or from
the portal. @augmentworks/cli@0.3.9 stays the last version for Node.js 20
and is not overwritten.

Breaking

• The CLI now requires Node.js 22.12 or newer (engines.node is
  >=22.12). Node.js 20 reached end of life in April 2026 and no longer
  gets security fixes, and the CLI's own dependencies (commander@15,
  vitest@5) already need 22.12. Upgrade Node.js before installing this
  release. @augmentworks/cli@0.3.9 stays the last version for Node.js 20.
  CI now tests Node.js 22.12.0, 22, 24 and 26, with an engine-strict install
  on the 22.12.0 lane. The build targets node22.

Added

• target add --env <environment> registers the agent in augmentworks.yaml
  (its name, base_url and every operation) as a workspace target, so the
  address and endpoints are never typed twice. It asks whether the agent is
  yours or a client's (with a written-permission reference), and shows the
  workspace real-data statement once for a typed yes if the workspace hasn't
  accepted it. In CI there's no prompt: pass --attest owned or
  --attest written --permission-ref <ref>, and accept the statement in the
  portal first; --yes never answers either. It needs a workspace owner's
  login, refuses machine keys, and ends with augmentworks target verify <name>.
• target verify <name> verifies a target you added. For a public address
  it prints the value to serve at /.well-known/augmentworks-target (or the
  TXT record for _augmentworks-target.<host> when the target was added with
  --method dns) and when the code expires, checks for it every 15 seconds,
  and prints "verified until …". The server is asked at the start, as soon as
  the CLI first sees the code, and then at most every few minutes, so waiting
  stays inside its attempt limits. Ctrl+C stops it, and running it again
  resumes with the same code; an expired code is replaced. A private address
  is confirmed from this machine with one connection probe (no credits) and
  recorded as the owner's statement. A client's agent records the written
  permission (--client-ref names the client). Needs an owner's login.
• scope create --target <name> --suite <file> creates a test scope for a
  verified target and writes its id into the aw-suite/3 file, changing only
  execution_scope.scope_id and revision (comments and formatting stay as
  they were). It uses the workspace's current data policy unless --policy
  is given, and shows the policy, data origin (--data-origin, default
  constructed), expiry (30 days, or when the target's verification ends;
  --expires to choose) and budget before asking, or --yes in CI. A
  workspace without the real-data statement, or an unverified target, stops
  with the step that's missing. Needs an owner's login. Ends with
  augmentworks test --suite <file>.
• target list shows each target's status, verification expiry and test
  scopes (scopes for owners only), and marks a scope that expires within 7
  days. --suite <file> also checks that file's scope and says how to
  replace it.
• target pull <name> brings a target added in the portal into
  augmentworks.yaml: its name, address and endpoints. Mappings and auth
  aren't touched, and an operation that calls an endpoint the target doesn't
  have stops without writing. With no file, it creates one whose unknown
  values are marked FILL_IN. doctor now reports any FILL_IN value left
  in the configuration as an error (PLACEHOLDER_UNFILLED).

Fixed

• gate reads the server's decision from the aw-release-gate-read/1
document, so it no longer answers unknown_evaluation_state (exit 11)
  for every graded run. The CLI accepts the server's coverage-change values,
  the running and cancelled evaluation statuses, and a null build commit.
  Only a removed required case counts as missing coverage.
• compare reads the server's aw-semantic-comparison-read/1 comparison
  and reports regressions, fixes and coverage without deciding the release;
  it exits 0 once both runs are graded. Use gate for the decision.
• test and run wait wait for grading after the target finishes and take
  pass or fail from the run report. Until now test said "passed" when the
  target finished even if required checks failed, and run wait could never
  exit 0 or 10 because the server's run status has no outcome. The hosted
  GitHub Actions examples drop their null-outcome workaround.
• baseline promote sends runId, as the server's promote route reads it,
  and refuses an --expected-revision below 1 before calling the server.
  Until now production rejected every promote with "runId must be a UUID".
  New baseline create --run <run-id> --name <name> --application <name> --environment <name> creates a workspace's first pin, so a new workspace
  no longer needs a direct POST /v1/baselines call.
• Authorized hosted runs (--suite with an execution scope, a saved
  revision that names one, and investigation reruns) now quote and create
  with the scope's registered boundary hash, so admission accepts them. The
  scope is fetched and augmentworks.yaml is checked against its boundary
  before the suite is uploaded or quoted. recover --resume and
  recover --cancel accept the scope's hash recorded for such a run.
• Windows file-identity checks work on Node.js 22.12.0 through 22.16.x
  (and 24.0.0 through 24.1.x). Those releases ship a libuv that reports
  dev: 0 from path stat/lstat and the volume serial from fstat, so
  opening a config, packet, lock, or journal looked like the file had been
  replaced. The file index still has to match. Two nonzero device ids still
  have to match.
• The CLI reads the server's real-data documents as aw-real-data/1
  defines them: aw-capabilities/1, aw-execution-scope-response/1,
  aw-target-boundary/1, the authorized-1 report and
  aw-local-execution-scope/1. Until now every hosted real-data run failed
  before any target call. The vendored contract is re-pinned to
  augmentworks-org/augmentworks@16d7679, with releaseEnabled and
  runtimeEnforced true. A /v1/capabilities response that doesn't parse
  is now an error, not a silent "real data disabled"; a 404 still means
  disabled. Configured operations must be endpoints of the admitted target
  boundary, and a local scope's boundary is rebuilt from augmentworks.yaml
  and checked against its targetBoundaryHash.
• Before any call, an authorized run checks augmentworks.yaml against the
  scope's target boundary: direct HTTP only, base_url at the registered
  origin, every configured operation a registered endpoint, and only send
  and observe for informational scopes. Each failure names the origin,
  endpoint or operation that didn't match and what to change. The admitted
  boundary is saved with the run, so a resumed run checks against it.

Changed

• On Node.js older than 22.12, the CLI prints a one-line warning to stderr
  with a link to the current LTS release, then runs the command as before.
• Real-data errors now say what happened, then what to do, naming the
  command or the Settings → Targets page that fixes it, and print the code
  last: Error: <message> (<CODE>). This covers a target or endpoint that
  doesn't match the scope, an expired scope or verification, a revoked
  target, a used-up run allowance, a workspace that hasn't accepted the
  real-data statement, an unverified target, a machine key used for setup,
  and the server not accepting real-data tests. The codes are unchanged, and
  --json output carries the same advice in fix. Other errors keep the
  Error [CODE]: <message> form.
• The docs, agent resources, starters and init guidance no longer call
  hosted real data release-disabled. They describe the real-data setup
  (target add, target verify, scope create, then test --suite), and
  docs/customer-suites.md documents the aw-suite/3 rules, including how a
  local scope's boundary is rebuilt from augmentworks.yaml.
  docs/troubleshooting.md lists each real-data error and its fix.
• The README is rewritten for users: install, first local test, first hosted
  test, real-data test, commands, troubleshooting. It pins one version and
  states the Node.js 22.12 minimum. The version history, integrity hashes,
  gitHeads and publishing rules moved to docs/distribution-runbook.md, and
  the node dist/index.js source-build commands to
  docs/command-examples.md.
• Recorded the independent inspection of npm @augmentworks/cli@0.3.9.
  The published tarball is unchanged and still embeds the prior 0.3.8
  LAST_VERIFIED snapshot.

@augmentworks/cli 0.3.9

0.3.9

Immutable patch so customers get the hosted run-scope lookup hardening. This does not replace @augmentworks/cli@0.3.8.

Highlights

• Hosted runs no longer crash when the server returns an HTML error page (AUG-335). Synthetic and saved-suite v2 bindings do not request an execution scope. A looked-up scope uses the same usability checks as the pinned path, except the revision and hash comparison when there is no suite reference. A 404 from that lookup on a packet that requires a scope stays INVALID_EXECUTION_SCOPE. Other lookup failures propagate. A non-JSON error body keeps http_status instead of INVALID_CLOUD_RESPONSE; a non-JSON success body still fails as INVALID_CLOUD_RESPONSE.
• Documented a reproducible support/FAQ example at examples/faq-chatbot/ (AUG-282). The same response-quality server accepts AW_FAQ_POLICY=stale so one local aw-packet/0.1 check exits 0 or 10. No CLI command was added. Published npm 0.3.8 and 0.3.7 do not contain the example directory or that switch.
• Recorded the independent inspection of npm @augmentworks/cli@0.3.8. The published tarball is unchanged and still embeds the prior 0.3.7 LAST_VERIFIED snapshot.

published_package_verified is published-line identity, not a live registry probe of this tarball. Independently inspected npm 0.3.8 remains the previous pin. Do not overwrite @augmentworks/cli@0.3.8.

@augmentworks/cli 0.3.8

0.3.8

Immutable patch so customers get the hosted report consistency check. This does not replace @augmentworks/cli@0.3.7.

Highlights

• run report exits 11 instead of 0 when a claimed pass contradicts a completed required failure, or when known coverage exceeds the evidence that was retrieved (AUG-272)
• Dev-only source-map-js resolves to 1.2.2 so the high-severity release audit passes (AUG-273)
• Coherent passes stay exit 0 and coherent assessed failures stay exit 10

published_package_verified is published-line identity, not a live registry probe of this tarball. Independently inspected npm 0.3.7 remains the previous pin. Do not overwrite @augmentworks/cli@0.3.7.

@augmentworks/cli 0.3.7

0.3.7

Published-line package for native customer-suite upload translation, saved-suite v2 binding, authoritative v2 whole-suite gate receipts, durable execution IDs, cross-shard quote uniqueness, and non-destructive generated .env guidance. published_package_verified is published-line identity, not a live registry probe of this tarball. Do not overwrite @augmentworks/cli@0.3.6.

Highlights

• Saved-suite assessments negotiate aw-suite-selection/2 and carry suite_id / suite_revision_id / suite_content_hash through estimate, quote, and create
• selection compile still forwards declared connector capabilities; a lifecycle-free connector does not overstate prepare, observation, or cleanup
• --estimate does not create a run; --max-credits bounds the explicit create
• run status and run report read the original run
• npm init next steps pin this package version

npx --yes @augmentworks/cli@0.3.7 init --agent
npx --yes @augmentworks/cli@0.3.7 selection compile -c augmentworks.yaml --assessment ./policy.assessment.yaml

Do not use @latest. See CHANGELOG.md for the full 0.3.7 notes. AUG-87 owns registry verification; AUG-250 owns website adoption.

@augmentworks/cli 0.3.6

0.3.6

Published-line patch for the AUG-82 suite-selection capability fix. published_package_verified is published-line identity, not a live registry probe of this tarball. Do not overwrite @augmentworks/cli@0.3.5.

Highlights

• selection compile and assessment-driven hosted selection forward the connector's prepare/observation/tool-event/cleanup snapshot (sorted observation keys and truthful multi-turn) on POST /v1/suite-selections/compile
• A missing default augmentworks.yaml stays an explicit capability-free single-turn mode
• Malformed or unresolved --config paths fail with the existing config diagnostic before authentication or quoting

npx --yes @augmentworks/cli@0.3.6 demo
npx --yes @augmentworks/cli@0.3.6 login
npx --yes @augmentworks/cli@0.3.6 selection compile -c augmentworks.yaml --assessment ./augmentworks.assessment.yaml --out ./suite-selection.manifest.json

Do not use @latest. See CHANGELOG.md for the full 0.3.6 notes.

@augmentworks/cli 0.3.5

0.3.5

Corrective published-line package for 0.3.4's stale candidate/unverified packaged metadata. published_package_verified is published-line identity, not a live registry probe of this tarball. Do not overwrite @augmentworks/cli@0.3.4.

Highlights

• Packaged cli-release.json, README, test --help, and discovery last-inspected snapshot no longer describe this line as a candidate or last-verified 0.3.2
• Quoted aw-relay/0.3 help from HOSTED_ASSESSMENT_OPTION_HELP
• Catalog listing, suite-selection shards, hosted GitHub Actions own-target recipe, and investigation inspect/repro (landed on main after 0.3.4)

npx --yes @augmentworks/cli@0.3.5 demo
npx --yes @augmentworks/cli@0.3.5 login
npx --yes @augmentworks/cli@0.3.5 doctor -c augmentworks.yaml --assessment ./augmentworks.assessment.yaml --profile quick

Do not use @latest. See CHANGELOG.md for the full 0.3.5 notes.

@augmentworks/cli 0.3.4

0.3.4

Customer-owned hosted assessments, quoted billing, complete hosted run report --json, and packaged demo. This tarball preserves nested producer aw-criterion-detail/1 documents on report export (occurrence, criterion kind, stored rationale).

Highlights

• Hosted test --suite, suite validate / preview, own-target starters, and bounded probe
• Quoted aw-relay/0.3 create, --estimate / --max-credits, run wait / run status / run report --json
• Packaged augmentworks demo (fail-then-pass loopback fixture)
• run report --json keeps producer criterion document instead of flattening it away

npx --yes @augmentworks/cli@0.3.4 demo
npx --yes @augmentworks/cli@0.3.4 login
npx --yes @augmentworks/cli@0.3.4 doctor -c augmentworks.yaml --assessment ./augmentworks.assessment.yaml --profile quick

Do not use @latest. See CHANGELOG.md for the full 0.3.4 notes.

@augmentworks/cli 0.3.2

0.3.2

Packaged local demo and a discovery contract. No account, API key, or extra clone is required for the synthetic demo after install.

Added

• augmentworks demo: isolated 127.0.0.1 refund target, real test --local runner/scorer, fail-then-pass policy story, AW-DEMO-SUMMARY-1 JSON
• Runtime assets under assets/demo/ (the npm tarball still omits examples/)
• contracts/discovery-manifest.json (schemaVersion: 1)
• Opt-in agent-resources/ in the git repository; init --agent is unchanged and those wrappers are not in the npm tarball

Fixed

• Packed-tarball smoke invokes npm/npx as node *-cli.js so Windows Node 22 does not fail with spawnSync npm.cmd EINVAL

Changed

• Package version is 0.3.2

npx --yes @augmentworks/cli@0.3.2 demo
npx --yes @augmentworks/cli@0.3.2 demo --json

The demo is a deterministic loopback fixture (amount 80 vs maximum_refund 50). It is not a production chatbot, accuracy benchmark, or hosted evidence record.

See CHANGELOG.md for related notes.

@augmentworks/cli 0.3.1

0.3.1

Hosted hybrid --assessment now matches the portal OpenAI judging disclosure.

Fixed

• Hybrid --assessment sends aw-judge-disclosure/2 so portal acknowledgment matches admission
• test --help describes --assessment as published in this package

Changed

• Source and published package version is 0.3.1
• Hosted and local npx examples pin @augmentworks/cli@0.3.1

See CHANGELOG.md for the full notes.

@augmentworks/cli 0.3.0

0.3.0

Hosted --assessment compiler plus the 0.2.1 recover/reconcile path.

Added

• Hosted --assessment / --profile compiler for augmentworks.assessment.yaml (aw-assessment-file/1)
• Relay protocol aw-relay/0.2 create-run assessment metadata, optional multi_turn, and hosted evaluation_status
• Grading exit codes 11 (incomplete) and 12 (evaluation error)
• Local-mode rejection of hybrid/aw-packet/0.2 packets before any target call
• Merged 0.2.1 recover and create-intent reconciliation so interrupted creates are not dropped

Changed

• Source and published package version is 0.3.0
• Hosted npx pin updates after this GitHub Release publishes to npm

See CHANGELOG.md for the full notes.