@zaowu-labs/ai
v1.2.1
Published
ZaoWu AI integration
Readme
@zaowu-labs/ai
AI provider boundary for ZaoWu.
This package defines provider metadata, preview behavior, local echo responses, and streaming/non-streaming Ollama, OpenAI Responses, and Anthropic adapters used by the CLI. Feature packages should depend on this boundary instead of calling providers directly.
Safety:
- Every HTTP-backed provider, including Ollama, previews by default.
- Provider requests require explicit confirmation from the CLI path.
- Operation plans disclose the resolved provider endpoint, including configured base URLs.
- Requests reject HTTP redirects so prompts and credentials cannot be sent to another endpoint without a new preview.
- Each request attempt has a bounded timeout covering both response headers and JSON/streaming body reads. Failed attempts and timed-out bodies are aborted.
- Secrets must come from environment variables, not config files.
- Provider HTTP failures are classified so authentication, timeout, rate-limit, bad-request, and provider-side problems get different fixes.
- Ollama, OpenAI, and Anthropic response shapes are validated before generated text is returned; malformed or empty provider output is rejected.
- Provider failure summaries use HTTP status metadata only; response bodies are not exposed in user-facing fixes.
- Retryable provider failures can carry retry-delay metadata when providers send
Retry-After. - Model resolution is shared across preview, operation-plan subjects, and
confirmed provider requests: explicit
--modelwins, then provider-specific environment defaults, then the provider default.
Streaming and cancellation
onChunk opts library callers into streaming; without it requests remain JSON.
Human CLI answers stream by default; --json returns one complete envelope.
Pass an AbortSignal as signal to cancel headers, a body, or retry backoff.
Ctrl+C in the CLI cancels with AI_REQUEST_CANCELLED and exit code 130.
The transport makes at most three attempts before body consumption; 429/408/5xx
responses honor a capped Retry-After delay. It never retries incomplete output.
UTF-8 is decoded across byte boundaries. Ollama NDJSON requires done: true;
OpenAI SSE requires a successful response.completed; Anthropic SSE requires a
final end_turn/stop_sequence reason followed by message_stop.
Malformed JSON, incomplete stop reasons, empty answers, invalid UTF-8, and EOF
without completion are errors. Metadata, thinking, and tool blocks are not text.
JSON-compatible proxies may return a complete JSON body instead of a stream.
JSON responses also reject explicit errors, unfinished statuses, output limits,
tool-use/continuation stops, and unfinished Ollama generation. Compatible JSON
proxies may omit completion metadata; explicit failure is never ignored.
Usage counts must be nonnegative safe integers; Ollama JSON counts are normalized
to the same input/output/total fields as other providers.
Limits: 200,000 input characters, 30 seconds per attempt including body reads, 8 MiB response bytes, one MiB per stream event, two million output characters. Use a smaller staged diff or file when a limit is reached. No live model keys are needed for the local HTTP integration tests.
Anthropic defaults to claude-sonnet-4-6, replacing the retired Sonnet 3.5 alias.
Explicit --model / ANTHROPIC_MODEL still win. Availability is account-specific;
see Anthropic model lifecycle.
Protocol references: OpenAI Docs,
Anthropic,
and Ollama.
Confirmation execution also checks the freshly prepared content against the
already verified plan immediately before the write/request. Changes between
reads fail with OPERATION_PLAN_MISMATCH and produce no write or network call.
Saved answers
zw ai ask --output actions.md previews answer creation even with Echo. Confirm
the input/provider/destination plan to generate and save the complete raw UTF-8
answer. Output parents must exist and be writable; their physical path is
disclosed. Existing files, directories, and links are conflicts before generation.
prepareAIOutputPath and saveAIAnswer provide explicit artifact handling for
composing callers; askAI itself still performs no file write. Saving stages a
private complete sibling, flushes it, and exclusively creates the final target.
Cancellation, provider errors, and incomplete answers create no final output.
A target created during generation is preserved. A failed save may follow a paid
generation; there is no automatic retry. CLI JSON adds outputPath/wroteFile
only when saving was requested. Terminal output escapes controls; files keep the
original answer, with no CLI headings or appended newline.
Private file mode is 0600 on POSIX; Windows uses the destination directory ACLs.
