@warlock.js/ai-cli 5.34.1 → 5.34.3

package/CHANGELOG.md

@@ -4,6 +4,18 @@ 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.3 - 2026-10-20
+
+### Changed
+
+- Condensed the package agent skill description to at most 450 characters, with API names and package routing guidance.
+
+## 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,7 +4,33 @@
 
 > 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.
 
-## run-cli-agents  `@warlock.js/ai-cli/run-cli-agents/SKILL.md`
+## Package orientation
+
+---
+description: 'Run installed coding-agent CLIs with `cli`, `createCliAgent`, `cliModel`, `CliAdapter` and `jsonLinesParser`. Use for "run Claude Code or Codex", "resume a CLI session", stream tool/usage events, configure permissions or write an adapter. Not this package → @warlock.js/ai for provider-neutral agents; @warlock.js/ai-workspace for embedded file/shell tools; @warlock.js/process for general child processes.'
+---
+
+# @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/skills/run-cli-agents/SKILL.md`
 
 ---
 name: run-cli-agents
@@ -194,7 +220,7 @@ How the model behaves:
 - The vendor table in the docs ("Vendor adapters") lists each CLI's flags, stream format, and the version it was verified against.
 
 
-## write-a-cli-adapter  `@warlock.js/ai-cli/write-a-cli-adapter/SKILL.md`
+## write-a-cli-adapter  `@warlock.js/ai-cli/skills/write-a-cli-adapter/SKILL.md`
 
 ---
 name: write-a-cli-adapter

package/llms.txt

@@ -6,5 +6,6 @@
 
 ## Skills
 
-- [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 orientation](@warlock.js/ai-cli/skills/index.md): Run installed coding-agent CLIs with `cli`, `createCliAgent`, `cliModel`, `CliAdapter` and `jsonLinesParser`. Use for "run Claude Code or Codex", "resume a CLI session", stream tool/usage events, configure permissions or write an adapter. Not this package → @warlock.js/ai for provider-neutral agents; @warlock.js/ai-workspace for embedded file/shell tools; @warlock.js/process for general child processes.
+- [run-cli-agents](@warlock.js/ai-cli/skills/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/skills/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.3"
   },
-  "version": "5.34.1",
+  "version": "5.34.3",
   "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 installed coding-agent CLIs with `cli`, `createCliAgent`, `cliModel`, `CliAdapter` and `jsonLinesParser`. Use for "run Claude Code or Codex", "resume a CLI session", stream tool/usage events, configure permissions or write an adapter. Not this package → @warlock.js/ai for provider-neutral agents; @warlock.js/ai-workspace for embedded file/shell tools; @warlock.js/process for general child processes.'
 ---
 
 # @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.