@getmagical/cli 0.10.1 → 0.12.1

package/README.md

@@ -24,10 +24,41 @@ mgcl org list
 mgcl automations list --limit 10
 mgcl automations update --id ... --input-json ...
 mgcl automation-runs list --automation-id ...
+mgcl work-items list --automation-id ... --status FAILED,STOPPED
+mgcl work-items get --id ...
+mgcl automation-runs list-page --work-item-id ...
 mgcl automations run-draft --draft-automation-id ... --agent-id ... --idempotency-key ... --config-json '{"startInTakeOverMode":true,"captureActions":true,"approvalMode":"HUMAN_APPROVAL","consistencyCheckCount":3}'
 mgcl automations publish --draft-automation-id ...   # non-production only: mgcl refuses against the production API, and the API rejects it too
 ```
 
+## Search automation runs
+
+```bash
+mgcl automation-runs list --search 'REF-123456' --automation-id <id> --json
+mgcl automation-runs list-page --search 'REF-123456' --limit 20 --page 0 --json
+```
+
+Both commands search on the server before pagination and combine `--search`
+with the existing automation, workflow, status, invocation-type, and date
+filters. Search ignores outer whitespace, matches case-insensitively, and
+looks for substrings in run IDs, automation names, run input/shared-input
+values, and current Data Store leaf values. Empty or whitespace-only search
+disables the search predicate while preserving the other filters. PostgreSQL `ILIKE` patterns apply:
+`%` matches any sequence, `_` matches one character, and backslash escapes
+pattern characters. NUL characters are rejected.
+
+Nested input values and Data Store leaves are searched in their JSON text
+representation, so escaped quotes or backslashes can cause misses. Prefer a
+simpler identifying fragment, then inspect the candidate's actual values.
+
+`list` returns an array. `list-page` returns `items`, `page`, `pageSize`,
+`hasMore`, `total`, and `isTotalTruncated`. Use `hasMore` to continue paging;
+when `isTotalTruncated` is true, `total` is only a lower bound. Searched pages
+avoid counting all matches: totals become exact on a nonempty terminal page
+or an empty first page. An empty page beyond the end cannot establish the
+exact total. Random ordering supports only page 0 and searched random samples
+always report a truncated total.
+
 ## Regression tests
 
 Choose how many historical baseline runs to test per pathway:
@@ -49,42 +80,43 @@ The count applies only when creating a regression test. Repeating the command
 for the same automation and agent version pair returns the existing test;
 changing the count does not expand or rerun it.
 
-`mgcl pathway-regression preview --runs-per-path <count>` remains a historical
-coverage lookup, accepting 1–50 with a default of 2. It does not configure a
-later regression test.
-
 ## Typed classification
 
 Use `mgcl classify` for focused typed judgments over context you already have.
-The request uses TypeSafe-shaped JSON with one shared `state` and a map of
-named `questions`. Version 1 supports `noul`, `choice`, and `score` questions.
-The backend uses `jev-latest` by default. Add `model` to the request to select
-an explicit supported model; the response reports the model actually used.
-Instructions, choice descriptions, rubric levels, and score legends may be
-structured JSON and are passed through without narrowing.
-The backend applies a 30-second total deadline, including bounded transient
-retries. Access is employee-only through normal CLI credentials or an allowed
-Magical runtime identity.
+The request has one shared `context` (text or JSON), optional `images`, and a
+map of named `questions`. Question types are `predicate`, `choice`, and
+`score`, and every question needs `instructions`. Choices are a map of value to
+description; score `levels` are an ordered list of `{label, description?}`.
+
+`--provider` selects `openai` (the default, OpenAI Decisions `gpt-6-luna`) or
+`typesafe` (TypeSafe `jev-latest`) and overrides `provider` in the request. Add
+`model` to select an explicit model for that provider; the response reports the
+provider and model actually used. Images must be base64 data URLs and are only
+supported by `openai`; `typesafe` rejects them with an input error. The backend
+applies a 30-second total deadline. Access is employee-only through normal CLI
+credentials or an allowed Magical runtime identity.
 
 ```bash
 mgcl classify --input-file request.json
-mgcl classify --input-json '{"state":"Please refund the duplicate charge.","questions":{"refund_requested":{"type":"noul","instructions":"Does the message explicitly request a refund?"}}}'
+mgcl classify --provider typesafe --input-file request.json
+mgcl classify --input-json '{"context":"Please refund the duplicate charge.","questions":{"refund_requested":{"type":"predicate","instructions":"Does the message explicitly request a refund?"}}}'
 cat request.json | mgcl classify --input-file -
 ```
 
 Pass exactly one input source. Questions in one batch are independent and
 cannot consume sibling answers. Split dependent judgments into separate calls.
-`noul` is a probability rather than a boolean; choice results retain the full
-option distribution; scores may be fractional. Confidence represents the
-returned distribution, not correctness, so include an `insufficient_evidence`
-choice when the supplied context may not establish an answer.
-
-The command evaluates only supplied text and JSON. It does not fetch URLs,
-files named in the request, run records, or media. Output is always the full
-parseable JSON response, including model, usage, probability distributions,
-score legends, and additive fields. A valid negative or uncertain answer exits
-successfully. Invalid input and backend or provider failures use the normal
-nonzero CLI error path and write diagnostics to stderr.
+Every provider returns the same answer shape: predicates return a
+`probability`; choices return the `choice`, `confidence`, and the full option
+`probabilities`; scores return a possibly fractional `score`, `confidence`, and
+per-level probabilities. Confidence represents the returned distribution, not
+correctness, so include an `insufficient_evidence` choice when the supplied
+context may not establish an answer.
+
+The command does not fetch URLs, files named in the request, run records, or
+hosted media. Output is always the full parseable JSON response, including
+provider, model, usage, and probability distributions. A valid negative or
+uncertain answer exits successfully. Invalid input and backend or provider
+failures use the normal nonzero CLI error path and write diagnostics to stderr.
 
 ## Publish checks after saving