@warlock.js/ai-cli 5.34.1 → 5.34.2

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to `@warlock.js/ai-cli` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.34.2 - 2026-10-19
+
+### Fixed
+
+- Keep the package skill description within the recommended size, remove the redundant loose catalog, and include package orientation in LLM projections.
+
 ## 5.32.0 - 2026-10-18
 
 ### Changed

package/llms-full.txt

@@ -4,6 +4,32 @@
 
 > Generated artifact. Concatenates every SKILL.md and reference file under `@warlock.js/ai-cli/skills/`. Re-run `node scripts/generate-llms.mjs` after any change.
 
+## Package orientation
+
+---
+description: "Run vendor coding CLIs headless as Warlock AI agents. Exports `cli`, `createCliAgent`, `cliModel`, `CliError` and adapter building blocks; registers `ai.cli`. Use for: launch Claude Code, Codex, Qwen Code or another supported CLI from code, stream tool calls and text, resume or cancel a session, read usage, attach per-run MCP servers, use a CLI as an ai.agent model, or implement an adapter. Not this package: direct model calls → @warlock.js/ai plus a provider adapter; a policy-jailed file and shell workspace → @warlock.js/ai-workspace; MCP clients and servers → @warlock.js/ai-tools."
+---
+
+# @warlock.js/ai-cli
+
+Many teams run the vendors' own agent CLIs on the subscriptions they already pay for. This package launches those CLIs headless, one session per run, and reduces each vendor's JSONL stream to one event model, with resume, process-tree cancellation, usage and per-run MCP servers. Importing the package registers `ai.cli` on the shared `ai` object.
+
+## The 80% path
+
+1. Pick a vendor factory and run a prompt; read `session.events` and `await session.done()` (`run-cli-agents`).
+2. Resume with `done().sessionRef`, cancel with a `signal`, and attach MCP servers with `mcp`.
+3. To give the CLI to `ai.agent` (budgets, guardrails, observers), use `agent.model()`.
+4. For a CLI that is not built in, write an adapter (`write-a-cli-adapter`).
+
+## Conventions and pitfalls
+
+- `permission` defaults to `"standard"` (the CLI's own non-interactive rules); `"bypass"` must be opted into. Kimi Code has no standard mode and requires `"bypass"`.
+- Secrets go in `apiKey`, `env`, or MCP `env`/`headers`, never in `args`.
+- The default home is private per run: authenticate with `apiKey`/`env`, or pass a home you logged in to.
+- `run()` rejects only for setup problems (`CliError`: "not-found", `capability`, "unsupported-option", …). `done()` never rejects; check `status`.
+- The installed CLI's `--help` must list every flag the adapter uses, so a CLI release with renamed flags fails closed with the flag and version in the error.
+
+
 ## run-cli-agents  `@warlock.js/ai-cli/run-cli-agents/SKILL.md`
 
 ---

package/llms.txt

@@ -6,5 +6,6 @@
 
 ## Skills
 
+- [Package orientation](@warlock.js/ai-cli/skills/index.md): Run vendor coding CLIs headless as Warlock AI agents. Exports `cli`, `createCliAgent`, `cliModel`, `CliError` and adapter building blocks; registers `ai.cli`. Use for: launch Claude Code, Codex, Qwen Code or another supported CLI from code, stream tool calls and text, resume or cancel a session, read usage, attach per-run MCP servers, use a CLI as an ai.agent model, or implement an adapter. Not this package: direct model calls → @warlock.js/ai plus a provider adapter; a policy-jailed file and shell workspace → @warlock.js/ai-workspace; MCP clients and servers → @warlock.js/ai-tools.
 - [run-cli-agents](@warlock.js/ai-cli/run-cli-agents/SKILL.md): Run vendor coding CLIs headless as agents with @warlock.js/ai-cli. Triggers: `ai.cli`, `cli.claudeCode`, `cli.codex`, `cli.antigravity`, `cli.qwenCode`, `cli.kimi`, `cli.cursor`, `cli.copilot`, `cli.grok`, `cli.opencode`, `cli.amp`, `cli.droid`, `cli.mistralVibe`, `cli.aider`, `cli.reasonix`, `createCliAgent`, `CliSession`, `session.events`, `session.done`, `CliEvent`, `CliResult`, `sessionRef`, `resume`, `permission: "bypass"`, `CliMcpServers`, `home: "private"`, `inheritEnv`, `CliError`, `agent.model`, `cliModel`; 'run claude code from node', 'orchestrate codex / copilot / cursor as workers', 'stream a CLI agent's tool calls', 'resume a CLI session', 'cancel a coding CLI and its child processes', 'read token usage from a CLI run', 'give a CLI MCP servers without putting tokens in argv', 'use a CLI as an ai.agent model'; typical import `import { cli } from "@warlock.js/ai-cli"`. Skip: writing an adapter for another CLI — the `write-a-cli-adapter` topic; direct provider calls — the `run-ai-agent` topic of the `warlock-js-ai` skill.
 - [write-a-cli-adapter](@warlock.js/ai-cli/write-a-cli-adapter/SKILL.md): Write a CliAdapter for a coding CLI that @warlock.js/ai-cli does not ship. Triggers: `CliAdapter`, `CliLaunchContext`, `CliLaunchPlan`, `CliStreamParser`, `cli.custom`, `createCliAgent`, `jsonLinesParser`, `stringField`, `numberField`, `usageOf`, `mcpServersJson`, `jsonFile`, `toToml`, `mapEffort`, `argvPrompt`, `promptFile`, `requirePrivateHome`, `unsupportedOption`, `createClaudeStreamParser`, `helpLists`, `missingFlags`, `requires`, `verification`; 'add a new coding CLI', 'support another agent CLI', 'parse a vendor JSONL stream', 'adapter for a new CLI version'; typical import `import { cli, jsonLinesParser, type CliAdapter } from "@warlock.js/ai-cli"`. Skip: using the built-in adapters — the `run-cli-agents` topic.

package/package.json

@@ -20,9 +20,9 @@
     "directory": "packages/ai-cli"
   },
   "peerDependencies": {
-    "@warlock.js/ai": "5.34.1"
+    "@warlock.js/ai": "5.34.2"
   },
-  "version": "5.34.1",
+  "version": "5.34.2",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/index.md

@@ -1,5 +1,5 @@
 ---
-description: "Drive vendor coding-agent CLIs headless as @warlock.js/ai agents — Claude Code, Codex, Antigravity, Qwen Code, Kimi Code, Cursor, Copilot, Grok Build, OpenCode, Amp, Factory Droid, Mistral Vibe, Aider, Reasonix. Exports `cli`, `createCliAgent`, `cliModel`, `CliError`, the per-vendor adapters and the adapter building blocks; registers `ai.cli`. Use for: run a coding CLI from code, stream its tool calls and text as one event model, resume or cancel a CLI session, read its token usage, give a CLI per-run MCP servers without leaking tokens, use a CLI as an ai.agent model, add an adapter for another CLI. Not this package: direct model calls → @warlock.js/ai with a provider adapter; a policy-jailed shell/file workspace → @warlock.js/ai-workspace; MCP clients and servers → @warlock.js/ai-tools."
+description: "Run vendor coding CLIs headless as Warlock AI agents. Exports `cli`, `createCliAgent`, `cliModel`, `CliError` and adapter building blocks; registers `ai.cli`. Use for: launch Claude Code, Codex, Qwen Code or another supported CLI from code, stream tool calls and text, resume or cancel a session, read usage, attach per-run MCP servers, use a CLI as an ai.agent model, or implement an adapter. Not this package: direct model calls → @warlock.js/ai plus a provider adapter; a policy-jailed file and shell workspace → @warlock.js/ai-workspace; MCP clients and servers → @warlock.js/ai-tools."
 ---
 
 # @warlock.js/ai-cli
@@ -18,5 +18,5 @@ Many teams run the vendors' own agent CLIs on the subscriptions they already pay
 - `permission` defaults to `"standard"` (the CLI's own non-interactive rules); `"bypass"` must be opted into. Kimi Code has no standard mode and requires `"bypass"`.
 - Secrets go in `apiKey`, `env`, or MCP `env`/`headers`, never in `args`.
 - The default home is private per run: authenticate with `apiKey`/`env`, or pass a home you logged in to.
-- `run()` rejects only for setup problems (`CliError`: `not-found`, `capability`, `unsupported-option`, …). `done()` never rejects; check `status`.
+- `run()` rejects only for setup problems (`CliError`: "not-found", `capability`, "unsupported-option", …). `done()` never rejects; check `status`.
 - The installed CLI's `--help` must list every flag the adapter uses, so a CLI release with renamed flags fails closed with the flag and version in the error.

package/skills/README.md

@@ -1,13 +0,0 @@
-# `@warlock.js/ai-cli` — skills index
-
-Per-task skills. Cross-references name the topic ("the `<topic>` topic"), and for another package add its skill ("the `<topic>` topic of the `warlock-js-<pkg>` skill").
-
-## Skills
-
-### `run-cli-agents`
-
-Drive a vendor coding CLI headless with `cli.<vendor>({...})` / `ai.cli.<vendor>` — `run(prompt, { cwd, resume, signal, model, effort, permission, mcp, env })`, the unified `session.events` (`session.started`, `message`, `tool.call`, `tool.result`, `usage`, `error`, `session.ended`), `session.done()` (`status`, `text`, `usage`, `sessionRef`, `exitCode`), resume, cancellation and timeouts, the opt-in `permission: "bypass"`, per-run MCP servers, config homes, `CliError` types, and `agent.model()` to run a CLI as an `ai.agent` model. Load when orchestrating Claude Code, Codex, Copilot, Cursor, Grok, Kimi, Qwen Code, OpenCode, Amp, Droid, Antigravity, Mistral Vibe, Aider or Reasonix from code.
-
-### `write-a-cli-adapter`
-
-Implement a `CliAdapter` for a coding CLI the package does not ship — the launch plan (`args`, `tail`, `stdin`, `env`, `files`, `requires`), the stream parser (`jsonLinesParser`, `sessionRef()`, reading a result file in `end()`), the verification record, and testing against a recorded stream and `--help`. Load when adding a vendor or adjusting an adapter for a new CLI release.