@withgauge/cli 0.18.0 → 0.19.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.
Files changed (3) hide show
  1. package/README.md +52 -58
  2. package/dist/index.js +172 -69
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -159,7 +159,7 @@ For automatic checks, connect the Gauge GitHub App with repository access and
159
159
  Actions read permission. Set `org` and enable the repository and target branches
160
160
  in **Settings → GitHub**. Waiting for inputs starts no sessions and spends no
161
161
  session credits.
162
- Fork pull requests are disabled by default. Choose **Require approval** to let
162
+ Fork pull requests are disabled by default. Check **Allow fork pull requests** to let
163
163
  workspace members authorize an evaluation from its GitHub check. Authorization
164
164
  covers one PR revision and uses workspace credits; new revisions and explicit
165
165
  reruns require fresh approval. Configured inputs determine when an authorized
@@ -391,75 +391,69 @@ funding by default, like Run Now in the web UI; `--bill-to-org` uses that org's
391
391
  credits instead. Other users always use org credits and can launch only in orgs
392
392
  they belong to.
393
393
 
394
- ## Optimizations: Gauge measures, you author
394
+ ## Optimizations
395
395
 
396
- `gauge optimizations` improves one surface you own — a docs page or a skill —
397
- against an eval or a preference prompt. Gauge measures a baseline, runs the
398
- trials you author, judges them, and tells you which change won. It never writes
399
- the change itself, and it never touches your repository. You edit on disk and
400
- send the text; Gauge serves it to the sandboxed agent in place of the live page
401
- or skill version.
402
-
403
- A scripted or agent-driven loop:
396
+ Start by finding runs that encountered the surface you want to improve:
404
397
 
405
398
  ```sh
406
- gauge optimizations diagnose --eval es_1 # where the sessions fail
407
- gauge optimizations start --eval es_1 --target claude-code:claude-opus-4-8 --yes
408
- gauge optimizations watch cl_1 # exit 4 = your turn
409
-
410
- gauge optimizations page cl_1 --url https://docs.acme.dev/start > start.md
411
- $EDITOR start.md
412
- gauge optimizations trials add cl_1 \
413
- --title "Lead with the env var" --page https://docs.acme.dev/start \
414
- --body-file start.md --launch --idempotency-key start-env-var --yes
415
-
399
+ gauge instructions optimization
400
+ gauge optimizations baselines --eval ev_1 -o json
401
+ gauge runs insight run_1 -o json
402
+ gauge runs logs run_1 -o json
403
+ gauge optimizations start --eval ev_1 --from-run run_1 --yes
416
404
  gauge optimizations watch cl_1
417
- gauge optimizations trial cl_1 R1 # score, verdict, sessions, errors
418
- gauge optimizations change cl_1 R1 --body # the winning text, to paste
419
- gauge optimizations adopt cl_1 R1 --yes # mark the winner; baseline stays fixed
420
- gauge optimizations handoff cl_1 # instructions to land the winner in your source
421
- gauge optimizations complete cl_1 --yes
422
405
  ```
423
406
 
424
- `page` and `skill-files` print the exact frozen content a trial starts from.
425
- Edit a skill with `--edit-skill <versionId> --skill-dir <path>`: the directory
426
- holds the complete bundle, `SKILL.md` included. `trials template --kind <kind>`
427
- prints a skeleton for the `--file` form.
428
-
429
- A chat-guided round, such as a CLI change, goes through preview and save. Save
430
- replaces the pending drafts, so it can fix a draft that is wrong:
407
+ `baselines` returns observed owned surfaces grouped by run, source evidence,
408
+ judging status, eligibility (including the baseline's complete run set), and a
409
+ `nextCursor` for `--cursor`. It uses the UI baseline picker's compatibility rules
410
+ and recent 100-batch eligibility window. Missing evidence is unknown; the list
411
+ is an analysis summary, not an exhaustive inventory of every trace event.
412
+ `--from-run` inherits the eligible baseline's harness/model and reuses its runs.
413
+ A stale choice fails instead of silently buying a new baseline. `--target` is
414
+ an alternative when you need to establish a baseline; do not combine it with
415
+ `--from-run`. Use `--preference` instead of `--eval` for preference prompts.
431
416
 
432
417
  ```sh
433
- gauge optimizations authoring cl_1 > context.json # revision, CLI targets, invocations
434
- gauge optimizations invocation cl_1 inv_1 # one recorded baseline invocation
435
- gauge optimizations cli-change cl_1 --file change.json > bundle.json
436
- # round.json: {"revision": "...", "trials": [{"trial": {"title": "...",
437
- # "lever": "CLI", "intervention": {"kind": "CLI_INTERVENTION", "after": <bundle.json>}}}]}
438
- gauge optimizations round preview cl_1 --file round.json # prints previewDigest
418
+ gauge optimizations authoring cl_1 > context.json
419
+ gauge optimizations page cl_1 --url https://docs.acme.dev/auth -o json
420
+ # Author round.json using context.revision and the observed baseline evidence.
421
+ gauge optimizations round preview cl_1 --file round.json -o json
439
422
  gauge optimizations round save cl_1 --file round.json --digest <previewDigest>
440
- gauge optimizations trials remove cl_1 R1.2 --yes # drop one draft
441
423
  gauge optimizations launch cl_1 --yes
424
+ gauge optimizations watch cl_1
425
+ gauge optimizations trial cl_1 R1.1 -o json
426
+ gauge optimizations adopt cl_1 R1.1 --yes
427
+ gauge optimizations handoff cl_1
428
+ gauge optimizations complete cl_1 --yes
442
429
  ```
443
430
 
444
- A `completeOutput` literal matcher is an exact, case-sensitive match. Copy it
445
- from the recorded command output.
446
-
447
- Every detail carries `nextAction` — `START`, `WAIT`, `AUTHOR_TRIAL`,
448
- `LAUNCH_ROUND`, `ADOPT`, `RESUME`, or `NONE`. Read it (`get -o json`) instead of
449
- inferring whose turn it is from round and trial statuses. `watch` exits `4` when
450
- the answer is you.
451
-
452
- `--idempotency-key` makes `trials add` safe to retry: the same key returns the
453
- trial the first call created, and never buys a second set of sessions.
454
-
455
- There is no round limit or credit budget. Each round waits for you; `complete`
456
- ends the optimization. Adoption marks the winner and leaves the baseline fixed.
457
- It does not open a pull request. `handoff` prints the same instructions as the
458
- web app's "Copy instructions for agent"; follow them in your own source.
459
-
460
- A failed or timed-out session drops out of the score. `trial`, `get`, and
461
- `watch` print a `WARNING` line for each one, with its failure reason; in JSON,
462
- read `failedSessions` on the trial and `failureReason` on each run.
431
+ A round is `{revision, trials: [{trial: {title, hypothesis, lever, intervention}}]}`.
432
+ Docs `REWRITE_DOCS` proposals supply `after.pages` with URL and exact `edits`
433
+ (`find`/`replace`), or a complete `body` and `rewriteReason`. Check the page's
434
+ `source`: `scrape` means current fetched content, not the captured response.
435
+
436
+ For CLI trials, inspect `cliIntervention.guidance` and `targets` in authoring
437
+ and use `runs logs` for the cited command evidence. `cli-change --file change.json`
438
+ accepts v3 `{schemaVersion:3, target, rules, shippingIntent}` and returns a sealed
439
+ bundle to put in `CLI_INTERVENTION.after`. It does not save or launch. The old
440
+ catalog/invocation-ID workflow is retired. Skills use `skill-files` and the
441
+ complete edited file bundle.
442
+
443
+ A checkpoint is a saved state of a baseline run. Resuming it avoids repeating
444
+ earlier work. Gauge automatically selects a compatible checkpoint before the
445
+ affected interaction for docs and CLI candidates, or starts fresh with a reason.
446
+ You do not select a checkpoint; omit checkpoint choices and fork flags. Skills
447
+ start fresh. Inspect
448
+ `runs[].candidateExecution` for actual starting mode and `candidateDelivery`
449
+ for exposure, observed artifacts, and evidence completeness. A score improvement
450
+ does not prove the change was exercised. Report sample counts and failed sessions.
451
+
452
+ Read `nextAction` on optimization detail; `watch` exits 4 when input is needed.
453
+ Round save replaces pending drafts but never launches. Use `--yes` for approved
454
+ spending and `trials add --idempotency-key` when retrying single-trial writes.
455
+ Adoption selects a winner without changing the baseline or deploying the change;
456
+ `handoff` supplies instructions to implement it in your source repository.
463
457
 
464
458
  ## Models, reports, and scripting
465
459
 
package/dist/index.js CHANGED
@@ -577,6 +577,8 @@ var billingStatusSchema = z6.object({
577
577
  holdsPerRun: workloadCreditStateSchema(z6.number()),
578
578
  /** Can the org fund at least one more run of each workload right now. */
579
579
  canRunByWorkload: workloadCreditStateSchema(z6.boolean()),
580
+ /** Invoiced subscriptions only: how far below zero the org may spend. */
581
+ creditLine: z6.object({ limitUsd: z6.number(), usedUsd: z6.number() }).nullable().optional(),
580
582
  // --- Deprecated. Retained for v1 compatibility; removal needs an API-version
581
583
  // decision. Overage is retired, so these are always inert.
582
584
  /** @deprecated Use `currentSku.tierLabel`. */
@@ -597,7 +599,9 @@ var LEDGER_KINDS = [
597
599
  "RUN_REFUND",
598
600
  "OVERAGE_DEBIT",
599
601
  "ADMIN_ADJUST",
600
- "EXPIRY"
602
+ "EXPIRY",
603
+ "CREDIT_LINE_SETTLE",
604
+ "CREDIT_LINE_CARRY"
601
605
  ];
602
606
  var ledgerKindSchema = z6.enum(LEDGER_KINDS);
603
607
  var usageEntrySchema = z6.object({
@@ -3439,6 +3443,48 @@ var optimizationSummarySchema = z35.object({
3439
3443
  var listOptimizationsResponseSchema = z35.object({
3440
3444
  items: z35.array(optimizationSummarySchema)
3441
3445
  });
3446
+ var baselineDiscoveryQuerySchema = z35.object({
3447
+ subjectKind: climbSubjectKindSchema,
3448
+ subjectId: z35.string().min(1),
3449
+ limit: z35.coerce.number().int().min(1).max(100).default(50),
3450
+ cursor: z35.string().min(1).optional()
3451
+ }).strict();
3452
+ var baselineRunSchema = z35.object({
3453
+ resolvedModel: z35.string().nullable(),
3454
+ runId: z35.string(),
3455
+ agent: z35.string(),
3456
+ model: z35.string(),
3457
+ status: z35.string(),
3458
+ createdAt: z35.string(),
3459
+ outcome: z35.object({
3460
+ passedCriteria: z35.number(),
3461
+ totalCriteria: z35.number(),
3462
+ judgingStatus: z35.string().nullable()
3463
+ }),
3464
+ surfaces: z35.array(
3465
+ z35.object({
3466
+ lever: z35.string(),
3467
+ label: z35.string(),
3468
+ targetRef: z35.unknown(),
3469
+ evidence: z35.unknown(),
3470
+ command: z35.unknown().optional()
3471
+ })
3472
+ ),
3473
+ evidenceStatus: z35.object({
3474
+ surfaces: z35.string().nullable(),
3475
+ cli: z35.string().nullable()
3476
+ }),
3477
+ eligibility: z35.object({
3478
+ eligible: z35.boolean(),
3479
+ reason: z35.string().nullable(),
3480
+ baselineRunIds: z35.array(z35.string())
3481
+ })
3482
+ });
3483
+ var baselineDiscoveryResponseSchema = z35.object({
3484
+ items: z35.array(baselineRunSchema),
3485
+ nextCursor: z35.string().nullable(),
3486
+ note: z35.string()
3487
+ });
3442
3488
  var targetSchema = z35.object({
3443
3489
  agent: schedulableAgentSchema.optional(),
3444
3490
  /** Empty or omitted means the agent's default model. */
@@ -3471,8 +3517,16 @@ var startOptimizationBodySchema = z35.object({
3471
3517
  ...planShape,
3472
3518
  creditCap: z35.number().int().nonnegative().optional(),
3473
3519
  targetScore: z35.number().min(0).max(1).optional(),
3474
- target: targetSchema.extend({ agent: schedulableAgentSchema })
3475
- }).strict().superRefine(refinePlan);
3520
+ target: targetSchema.extend({ agent: schedulableAgentSchema }).optional(),
3521
+ fromRun: z35.string().min(1).optional()
3522
+ }).strict().superRefine(refinePlan).superRefine((value, ctx) => {
3523
+ if (!!value.target === !!value.fromRun)
3524
+ ctx.addIssue({
3525
+ code: "custom",
3526
+ message: "Pass target or fromRun, not both",
3527
+ path: ["target"]
3528
+ });
3529
+ });
3476
3530
  var estimateOptimizationBodySchema = z35.object({
3477
3531
  subjectKind: climbSubjectKindSchema,
3478
3532
  subjectId: z35.string().min(1),
@@ -3671,6 +3725,7 @@ var skillFilesResponseSchema = z35.object({
3671
3725
  files: overrideFilesSchema
3672
3726
  });
3673
3727
  var pageBodyResponseSchema = z35.object({
3728
+ source: z35.string().optional(),
3674
3729
  url: z35.string(),
3675
3730
  body: z35.string(),
3676
3731
  contentType: z35.string().optional()
@@ -8060,7 +8115,7 @@ description: Create and review Gauge eval prompts, model selections, and judging
8060
8115
  - Native command inputs use \`type: "binary"\`, \`platform: "linux-x64"\`, selected \`paths\`, and a \`commands\` map from command names to explicit relative ELF executable files. CI must upload already unpacked files. Gauge restores executable permissions and exposes declared commands on PATH; compatible system libraries are required, nested archives and arbitrary installers are unsupported.
8061
8116
  - Automatic GitHub PR checks support root \`gauge.json\` \`checks.paths\` as a suite gate and per-case frontmatter \`config.checks.paths\` as a narrower filter. Both accept positive repository-relative globs. Cases without filters run when the suite gate passes; changes to \`gauge.json\` select all cases and edits to a case select that case. Explicit CLI launches and GitHub reruns ignore both filters. Failed/unfinished previous checks, changed target branches, and unavailable diffs run conservatively. \`config.inputs\` selects inputs, not triggers.
8062
8117
  - Pilot before scaling; confirm before spending credits. Creating definitions does not authorize launching runs. Report sample counts and distinguish incorrect behavior, missing evidence, environment failures, and budget exhaustion.
8063
- - Gauge tests artifacts from the PR's successful build; preserve CI's existing checkout settings, including the default merge checkout. Fork PRs are disabled by default. In Gauge's GitHub settings, choose **Require approval**; a workspace member then follows the GitHub check link to authorize that revision using workspace credits and connections. New revisions and explicit reruns need fresh approval. Inputs still determine readiness.
8118
+ - Gauge tests artifacts from the PR's successful build; preserve CI's existing checkout settings, including the default merge checkout. Fork PRs are disabled by default. In Gauge's GitHub settings, check **Allow fork pull requests**; a workspace member then follows the GitHub check link to authorize that revision using workspace credits and connections. New revisions and explicit reruns need fresh approval. Inputs still determine readiness.
8064
8119
  - For authenticated MCP access, connect the account in Gauge, complete OAuth in the browser when required, and put the versioned server reference in case \`config.mcpRefs\`. Gauge manages session credentials; keep tokens out of prompts and Git.
8065
8120
  - To test local build output without the GitHub App, use \`gauge evals run --input name=path --yes -o json\`. Repeat \`--input\` for each input. This uses current evaluation files, including edits; other inputs keep their configured sources. Skills accept directories or archives, npm packages accept .tgz files, and file/binary inputs accept directories. Use \`gauge run-requests wait <id> -o json\` for the verdict, criterion results, and session links; failed checks exit nonzero while still returning JSON.
8066
8121
  - Before committing setup changes, run \`gauge evals verify -o json\` for an offline working-tree checklist. Only attempted static checks are scored yes, no, or unknown; unknown means a specific declaration could not be resolved. Informational findings (such as zero cases) are separate. JSON includes a version, static status (passed/failed/incomplete), summary counts, global/per-input checks with stable IDs, facts, info, and excluded capabilities in notChecked. Exit 1 means a definite problem; exit 0 can still contain unknowns. Live delivery, account settings, and sandbox execution are outside this command's scope. It requires no login or PR and launches no sessions.
@@ -8168,7 +8223,7 @@ Gauge helps you understand and improve how coding agents discover and use your
8168
8223
  product. It runs real agents in sandboxes under reproducible conditions, then
8169
8224
  judges their work. Evals measure successful product use; Agent Preference
8170
8225
  measures which tools agents choose and why. Optimizations test improvements to
8171
- your docs and skills against those measurements.
8226
+ your docs, CLI, and skills against those measurements.
8172
8227
 
8173
8228
  ## Use Gauge and the CLI
8174
8229
 
@@ -8224,64 +8279,64 @@ Full guidance: \`gauge instructions preference\`.
8224
8279
 
8225
8280
  ### Optimization
8226
8281
 
8227
- Gauge measures trials; you author the changes. Start from an eval or preference
8228
- prompt, diagnose friction, and write a hypothesis. Change one variable per trial
8229
- against the frozen baseline; keep the measurement and its criteria fixed. Read
8230
- \`nextAction\` on every detail and follow the named step. Use
8231
- \`gauge optimizations watch <id>\` to track progress; exit 4 means your input is
8232
- needed. Submit changes with an idempotency key and confirm paid launches.
8233
- Inspect scores and session evidence before adopting. A WARNING line means
8234
- sessions errored; tell the user before you trust the score. To ship the winner,
8235
- follow \`gauge optimizations handoff <id>\` in your source repository.
8282
+ Gauge measures trials; you author changes. First run \`gauge optimizations baselines\`
8283
+ for an eval or preference prompt to discover observed surfaces and eligible runs.
8284
+ Inspect source evidence, then start with \`--from-run\` to reuse the chosen baseline.
8285
+ Read authoring context, write a hypothesis, preview the complete change, save,
8286
+ and launch. Gauge resumes saved baseline states (checkpoints) when compatible, or starts fresh.
8287
+ Follow \`nextAction\`; watch exits 4 when input is needed. Verify actual change
8288
+ exposure, task scores, sample counts, and failed sessions separately. Keep the
8289
+ measurement fixed, confirm paid launches, and retry writes safely. Adopt the
8290
+ winner; use \`handoff\` for implementation in your source repository.
8236
8291
 
8237
8292
  Full guidance: \`gauge instructions optimization\`.
8238
8293
  `;
8239
8294
  var OPTIMIZATIONS = `---
8240
8295
  name: gauge-optimizations
8241
- description: Improve how coding agents handle your docs and skills, measured by
8242
- a Gauge eval or preference prompt. Read before running \`gauge optimizations\`.
8296
+ description: Discover observed surfaces, choose a baseline, and test docs, CLI,
8297
+ or skill changes against a Gauge eval or preference prompt.
8243
8298
  ---
8244
8299
 
8245
8300
  # Optimizations
8246
8301
 
8247
- Gauge measures. You author. An optimization runs an eval or preference prompt
8248
- against one change you wrote, judges the sessions, and reports which won.
8249
-
8250
- Nothing touches your repository. A docs trial serves your text to the sandboxed
8251
- agent in place of the live page. A skill trial swaps the version.
8302
+ Gauge measures; you author. Use -o json on reads. Discover before starting.
8252
8303
 
8253
8304
  ## The loop
8254
8305
 
8255
- gauge optimizations diagnose --eval <id> # clusters and a lever
8256
- gauge optimizations start --eval <id> --target <agent:model> --yes
8257
- gauge optimizations watch <id> # exit 4 = your turn
8258
-
8259
- Read \`nextAction\` on every detail. It names the one next step.
8260
-
8261
- WAIT poll \`watch\`
8262
- AUTHOR_TRIAL read the base, edit, \`trials add\`; or \`complete <id>\`
8263
- LAUNCH_ROUND \`launch <id>\`
8264
- NONE finished
8265
-
8266
- Author against the frozen base, never your local copy: \`page <id> --url <url>\`
8267
- or \`skill-files <versionId>\`. Send it back with \`trials add --page <url>
8268
- --body-file <path>\`, or \`--edit-skill <versionId> --skill-dir <path>\`. Pass
8269
- \`--idempotency-key <key>\` so a retry cannot buy a second set of sessions.
8270
-
8271
- ## Rules
8272
-
8273
- - One variable per trial. Two edits teach you nothing about either.
8274
- - Write the hypothesis first. No hypothesis means you spend credits to guess.
8275
- - Change the smallest thing that could move the score: the order, the first
8276
- sentence, a named value.
8277
- - Keep what works. A rewrite that drops the code example loses for a reason you
8278
- did not intend.
8279
- - Never edit the eval, its criteria, or the prompt to make a trial pass.
8280
- - The score drops failed sessions (\`failedSessions\`). Name each one and its
8281
- \`failureReason\` to the user; never call that trial "no change".
8282
-
8283
- Finish: \`handoff <id>\` prints the web app's "Copy instructions for agent" text.
8284
- Follow it in your source repo, open a pull request, and cite the trial and score.
8306
+ gauge optimizations baselines --eval <id> -o json
8307
+ gauge runs insight <run-id> -o json
8308
+ gauge runs logs <run-id> -o json
8309
+ gauge optimizations start --eval <id> --from-run <run-id> --yes
8310
+
8311
+ Discovery returns observed owned surfaces, evidence, judging, eligibility, and nextCursor.
8312
+ Choose a run that encountered the surface you want to improve. Missing evidence is unknown.
8313
+ --from-run reuses its eligible baseline (possibly several runs) and inherits its model.
8314
+ Use --preference for preference prompts, or --target <agent:model> to establish a baseline.
8315
+ A new baseline may spend credits. Only use --yes for approved spending.
8316
+
8317
+ gauge optimizations watch <id> # exit 4 = your turn, not failure
8318
+ gauge optimizations authoring <id> # targets, guidance, revision
8319
+ gauge optimizations page <id> --url <url> -o json
8320
+
8321
+ Follow nextAction: WAIT \u2192 watch; AUTHOR_TRIAL \u2192 author; LAUNCH_ROUND \u2192 launch.
8322
+ Check page.source: scrape is current content, not the captured baseline response.
8323
+ Write one hypothesis and the complete change in round.json, using the authoring revision.
8324
+ Docs use exact find/replace edits or body with rewriteReason; skills use the complete bundle.
8325
+ CLI: cli-change --file takes v3 {schemaVersion:3,target,rules,shippingIntent}; put its output in intervention.after.
8326
+
8327
+ gauge optimizations round preview <id> --file round.json -o json
8328
+ gauge optimizations round save <id> --file round.json --digest <previewDigest>
8329
+ gauge optimizations launch <id> --yes
8330
+ gauge optimizations watch <id>
8331
+ gauge optimizations trial <id> <trial> -o json
8332
+
8333
+ Checkpoints are saved states of baseline runs: resuming one avoids repeating earlier work.
8334
+ Gauge selects checkpoints automatically before the affected interaction, or starts fresh with a reason.
8335
+ Omit startingPoints and fork flags; you do not select a checkpoint. Check candidateExecution,
8336
+ candidateDelivery (exposure, observedArtifacts, evidenceComplete), scores, counts, and failed sessions.
8337
+ Better scores alone are not proof. Keep eval/prompt/criteria fixed; repeat if inconclusive.
8338
+ Adopt <id> <trial> selects the winner; handoff <id> gives source instructions; complete <id> finishes.
8339
+ Neither deploys. Single-trial retries: trials add --idempotency-key. Optional: gauge optimizations diagnose.
8285
8340
  `;
8286
8341
  var TOPICS = {
8287
8342
  root: { name: "gauge", markdown: ROOT },
@@ -9256,6 +9311,46 @@ function register19(program2) {
9256
9311
  else printItems(res.items.map(toRow3), "table");
9257
9312
  }
9258
9313
  );
9314
+ addSubjectOptions(
9315
+ group.command("baselines").description(
9316
+ "Discover which ordinary runs exposed which owned surfaces, and whether they can seed an optimization"
9317
+ )
9318
+ ).option("--limit <n>", "page size (1\u2013100)", "50").option("--cursor <cursor>", "nextCursor from the previous page").action(
9319
+ async (opts, cmd) => {
9320
+ const response = await createClient().get(
9321
+ `${basePath(resolveOrg(cmd))}/baselines`,
9322
+ {
9323
+ ...parseSubject(opts),
9324
+ limit: parseCount(opts.limit, "--limit"),
9325
+ cursor: opts.cursor
9326
+ }
9327
+ );
9328
+ if (resolveOutput(cmd) === "json") printJson(response);
9329
+ else {
9330
+ printItems(
9331
+ response.items.flatMap(
9332
+ (run) => (run.surfaces.length ? run.surfaces : [{ lever: "\u2014", label: "No recorded surface evidence" }]).map((surface) => ({
9333
+ run: run.runId,
9334
+ model: run.model || run.resolvedModel || run.agent,
9335
+ date: run.createdAt.slice(0, 10),
9336
+ criteria: run.outcome.totalCriteria ? `${run.outcome.passedCriteria}/${run.outcome.totalCriteria}` : "\u2014",
9337
+ status: run.status,
9338
+ surface: surface.lever,
9339
+ target: surface.label,
9340
+ eligible: run.eligibility.eligible ? "yes" : "no"
9341
+ }))
9342
+ ),
9343
+ "table"
9344
+ );
9345
+ for (const run of response.items)
9346
+ if (run.eligibility.reason)
9347
+ console.log(`${run.runId}: ${run.eligibility.reason}`);
9348
+ console.log(response.note);
9349
+ if (response.nextCursor)
9350
+ console.log(`More: --cursor ${response.nextCursor}`);
9351
+ }
9352
+ }
9353
+ );
9259
9354
  group.command("get <id>").description("One optimization: settings, score, and its trial ladder").action(async (id2, _opts, cmd) => {
9260
9355
  const org = resolveOrg(cmd);
9261
9356
  const detail = await createClient().get(itemPath(org, id2));
@@ -9278,25 +9373,29 @@ function register19(program2) {
9278
9373
  addTargetOption(
9279
9374
  addSubjectOptions(
9280
9375
  group.command("start").description(
9281
- "Measure a baseline; author and launch each round afterward"
9376
+ "Reuse a selected baseline with --from-run, or establish one with --target"
9282
9377
  )
9283
9378
  )
9379
+ ).option(
9380
+ "--from-run <runId>",
9381
+ "reuse the eligible baseline containing this run; inherits its model"
9284
9382
  ).option("--name <name>", "optimization name (default: from the subject)").option("--yes", "skip the confirmation").action(
9285
9383
  async (opts, cmd) => {
9286
9384
  const org = resolveOrg(cmd);
9287
- if (!opts.target)
9385
+ if (!!opts.target === !!opts.fromRun)
9288
9386
  throw new CliError(
9289
9387
  "usage",
9290
- "--target <agent[:model]> is required; see `gauge models list`"
9388
+ "pass --from-run <runId> or --target <agent[:model]>, not both; discover runs with `gauge optimizations baselines`"
9291
9389
  );
9292
9390
  const subject = parseSubject(opts);
9293
9391
  await confirmOrAbort(
9294
- `Start an optimization on ${subjectLabel(subject.subjectKind)} ${subject.subjectId}? The baseline starts now and spends credits.`,
9392
+ opts.fromRun ? `Start an optimization from the baseline containing ${opts.fromRun}?` : `Start an optimization on ${subjectLabel(subject.subjectKind)} ${subject.subjectId}? A new baseline may spend credits.`,
9295
9393
  opts.yes
9296
9394
  );
9297
9395
  const detail = await createClient().post(basePath(org), {
9298
9396
  ...subject,
9299
9397
  ...targetFromOpts(opts),
9398
+ ...opts.fromRun ? { fromRun: opts.fromRun } : {},
9300
9399
  name: opts.name
9301
9400
  });
9302
9401
  if (resolveOutput(cmd) === "json") printJson(detail);
@@ -9514,26 +9613,22 @@ function register19(program2) {
9514
9613
  }
9515
9614
  );
9516
9615
  group.command("authoring <id>").description(
9517
- "What the next round may change: kinds, CLI targets and commands, baseline invocations, revision"
9616
+ "What the next round may change: exposed surfaces, CLI targets, baseline run evidence, revision"
9518
9617
  ).action(async (id2, _opts, cmd) => {
9519
9618
  printJson(
9520
9619
  await createClient().get(`${itemPath(resolveOrg(cmd), id2)}/authoring`)
9521
9620
  );
9522
9621
  });
9523
9622
  group.command("invocation <id> <invocationId>").description(
9524
- "One baseline CLI invocation from `authoring`, with its recorded command evidence"
9525
- ).action(
9526
- async (id2, invocationId, _opts, cmd) => {
9527
- printJson(
9528
- await createClient().get(
9529
- `${itemPath(resolveOrg(cmd), id2)}/authoring/target`,
9530
- { cliInvocationId: invocationId }
9531
- )
9532
- );
9533
- }
9534
- );
9623
+ "Retired: use authoring source run references and gauge runs logs"
9624
+ ).action(() => {
9625
+ throw new CliError(
9626
+ "usage",
9627
+ "The invocation catalog is retired. Read `gauge optimizations authoring <id>` and `gauge runs logs <runId> --output json` for observed command evidence."
9628
+ );
9629
+ });
9535
9630
  group.command("cli-change <id>").description(
9536
- "Build a CLI_INTERVENTION bundle from {targetId, commandId, selector, operations, shippingIntent}; use the output as intervention.after in a round file. Saves nothing"
9631
+ "Validate and seal v3 {schemaVersion:3, target, rules, shippingIntent}; use the output as intervention.after in a round file. Saves nothing"
9537
9632
  ).requiredOption("--file <path>", "the change JSON; '-' for stdin").action(async (id2, opts, cmd) => {
9538
9633
  printJson(
9539
9634
  await createClient().post(
@@ -9724,7 +9819,15 @@ function register19(program2) {
9724
9819
  { url: opts.url }
9725
9820
  );
9726
9821
  if (resolveOutput(cmd) === "json") printJson(res);
9727
- else console.log(res.body);
9822
+ else {
9823
+ if (res.source === "scrape")
9824
+ console.error(
9825
+ "Source: fresh scrape; this is not the captured baseline response."
9826
+ );
9827
+ else if (res.source === "none")
9828
+ console.error("No page body is available.");
9829
+ console.log(res.body);
9830
+ }
9728
9831
  });
9729
9832
  }
9730
9833
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@withgauge/cli",
3
- "version": "0.18.0",
3
+ "version": "0.19.0",
4
4
  "description": "Gauge customer CLI — Agent Preference, evals, runs, and organization settings over the Gauge API",
5
5
  "private": false,
6
6
  "author": "Gauge <support@withgauge.com> (https://withgauge.com)",