71 lines
2.8 KiB
Markdown
71 lines
2.8 KiB
Markdown
# 05-cli-docs — `sift batch`, skill, README, config
|
|
|
|
Expose the batch endpoint from the CLI and document it for agents. No Hermes plugin — the CLI is
|
|
the agent surface, same rationale as `sift fetch`/`sift search`.
|
|
|
|
## CLI
|
|
|
|
Add a `sift batch` subcommand with three verbs. It reads `url` and `key_file` from `client.toml`
|
|
exactly as `fetch`/`search` do, and never puts a key on the command line.
|
|
|
|
```
|
|
sift batch submit <targets.json> # '-' reads stdin; prints the job_id (and reused) as JSON
|
|
sift batch status <job_id> # prints status + per-target results as JSON
|
|
sift batch cancel <job_id> # prints the cancelled status as JSON
|
|
```
|
|
|
|
`submit` takes the same JSON as `POST /v1/batch` (a `{"targets":[…]}` object) and prints
|
|
`{"job_id": …, "reused": …}`. `status` prints the full `GET /v1/batch/{id}` body. All three
|
|
propagate the server's error envelope and exit non-zero on a non-2xx.
|
|
|
|
The dispatch/validation is a pure function pinned by the given test:
|
|
|
|
```go
|
|
func parseBatchArgs(args []string) (verb, arg string, err error)
|
|
```
|
|
|
|
`verb` is `submit`/`status`/`cancel`; `arg` is the targets file (submit, `-` for stdin) or the
|
|
`job_id` (status/cancel). No verb, a missing arg, an extra arg, or an unknown verb is an error.
|
|
|
|
## Config
|
|
|
|
Add a `[batch]` block to `internal/config` (`File`), with:
|
|
|
|
```toml
|
|
[batch]
|
|
targets_per_job = 32
|
|
jobs_per_caller = 1
|
|
jobs_total = 8
|
|
ttl = "24h"
|
|
max_bytes = "64MiB"
|
|
```
|
|
|
|
The runner and API read these instead of hard-coding; the defaults match the settled caps. The
|
|
body-cap knob for `/v1/batch` (256 KiB) is a constant, not config.
|
|
|
|
## Docs
|
|
|
|
- `README.md`: add a short "Batch" section (the three endpoints, the serial/background model, caps,
|
|
idempotency, lease/TTL semantics, restricted-caller redaction, and the `sift_batch_*` metrics).
|
|
- `skill/SKILL.md`: add a batch section telling agents to use `sift batch submit` for a list of
|
|
targets rather than a loop of `sift fetch`, and to `sift batch status` to collect.
|
|
- `dist/sift.toml.example`: add the `[batch]` block with its defaults and a comment.
|
|
|
|
## Rules
|
|
|
|
1. The CLI reuses the existing client plumbing (`client.toml`, bearer header, JSON envelope
|
|
handling) — no new HTTP client.
|
|
2. `submit` validates its input locally (a non-empty `targets` array) before calling the server.
|
|
3. `status`/`cancel` require exactly one `job_id` argument.
|
|
4. Keep each verb a small function; do not grow `main.go` — add `cmd/sift/batchcmd.go`.
|
|
|
|
## Given
|
|
|
|
Copy `_files/cmd_sift/batch_test.go` → `cmd/sift/batch_test.go`. It pins `parseBatchArgs` — the
|
|
valid verb+arg pairs (including `-` as a stdin target file) and the error cases (no verb, missing
|
|
arg, extra arg, unknown verb).
|
|
|
|
## Gate
|
|
|
|
`make gate` green; `go test ./cmd/sift/` green under `-race`; `go test ./internal/config/` green.
|