@consultancy-outfit/ai-draftsman-cli 1.1.3 → 1.3.0

package/README.md

@@ -1,105 +1,179 @@
-# AI Draftsman CLI
-
-Standalone Node.js/TypeScript CLI for the AI Draftsman platform.
-
-## Requirements
-
-- Node.js 20+
-- npm
-
-## Install dependencies
-
-```bash
-npm install
-```
-
-## Run from source
-
-Interactive default flow, Claude-Code style:
-
-```bash
-npm run dev
-```
-
-The CLI now defaults to:
-- backend URL: `https://dev-api.aidraftsman.ai/`
-- frontend URL: `https://dev-b2b.aidraftsman.ai/`
-- browser login if you are not authenticated yet
-- agent/model selection launcher after login, instead of asking for a base URL
-
-Examples:
-
-```bash
-npm run dev -- auth login
-npm run dev -- auth status
-npm run dev
-npm run dev -- agents list
-npm run dev -- agents run AGENT_ID --message "Summarize this project"
-npm run dev -- chat complete --model gpt-4o-mini --message "Hello"
-npm run dev -- conversations create --agent AGENT_ID
-npm run dev -- conversations send CONVERSATION_ID --message "Continue the work"
-npm run dev -- messages list CONVERSATION_ID
-npm run dev -- session exec --model agent:AGENT_ID --message "Plan the next step"
-npm run dev -- session start --model agent:AGENT_ID --durable
-npm run dev -- session resume CONVERSATION_ID --model agent:AGENT_ID
-```
-
-## Build
-
-```bash
-npm run build
-```
-
-## Install globally on your system
-
-From npm:
-
-```bash
-npm install -g @consultancy-outfit/ai-draftsman-cli
-```
-
-Or from this project folder:
-
-```bash
-npm install
-npm run build
-npm install -g .
-```
-
-Then use either command:
-
-```bash
-aidraftsman --help
-ad --help
-```
-
-## Windows PowerShell examples
-
-```powershell
-npm install
-npm run build
-npm install -g .
-ad
-ad auth login
-ad agents list
-ad session start --model agent:AGENT_ID --durable
-```
-
-## Notes
-
-- `session start --durable` creates a durable conversation when the model is `agent:<id>`.
-- `session resume <conversationId> --model agent:<id>` continues by sending MCP messages to that conversation.
-- Current `--stream` support is terminal-style rendering built on one-shot responses, not full token streaming yet.
-
-## Images
-
-Attach images (png, jpg, gif, webp; up to 5 MB each) in any of these ways:
-
-```powershell
-ad -i screenshot.png "what is wrong with this layout?"   # interactive, first prompt
-ad -p -i a.png -i b.png "compare these two"               # print mode
-ad "match this design: @mockup.png"                       # an @path to an image is attached too
-ad chat complete --model agent:AGENT_ID --image shot.png --message "describe this"
-```
-
-The gateway must accept OpenAI-style `image_url` content parts, and the chosen model must support vision.
+# AI Draftsman CLI
+
+Standalone Node.js/TypeScript CLI for the AI Draftsman platform.
+
+## Requirements
+
+- Node.js 20+
+- npm
+
+## Install dependencies
+
+```bash
+npm install
+```
+
+## Run from source
+
+Interactive default flow, Claude-Code style:
+
+```bash
+npm run dev
+```
+
+The CLI now defaults to:
+- backend URL: `https://dev-api.aidraftsman.ai/`
+- frontend URL: `https://dev-b2b.aidraftsman.ai/`
+- browser login if you are not authenticated yet
+- agent/model selection launcher after login, instead of asking for a base URL
+
+Examples:
+
+```bash
+npm run dev -- auth login
+npm run dev -- auth status
+npm run dev
+npm run dev -- agents list
+npm run dev -- agents run AGENT_ID --message "Summarize this project"
+npm run dev -- chat complete --model gpt-4o-mini --message "Hello"
+npm run dev -- conversations create --agent AGENT_ID
+npm run dev -- conversations send CONVERSATION_ID --message "Continue the work"
+npm run dev -- messages list CONVERSATION_ID
+npm run dev -- session exec --model agent:AGENT_ID --message "Plan the next step"
+npm run dev -- session start --model agent:AGENT_ID --durable
+npm run dev -- session resume CONVERSATION_ID --model agent:AGENT_ID
+```
+
+## Build
+
+```bash
+npm run build
+```
+
+## Install globally on your system
+
+From npm:
+
+```bash
+npm install -g @consultancy-outfit/ai-draftsman-cli
+```
+
+Or from this project folder:
+
+```bash
+npm install
+npm run build
+npm install -g .
+```
+
+Then use either command:
+
+```bash
+aidraftsman --help
+ad --help
+```
+
+## Windows PowerShell examples
+
+```powershell
+npm install
+npm run build
+npm install -g .
+ad
+ad auth login
+ad agents list
+ad session start --model agent:AGENT_ID --durable
+```
+
+## Notes
+
+- `session start --durable` creates a durable conversation when the model is `agent:<id>`.
+- `session resume <conversationId> --model agent:<id>` continues by sending MCP messages to that conversation.
+- Current `--stream` support is terminal-style rendering built on one-shot responses, not full token streaming yet.
+
+## Images
+
+Attach images (png, jpg, gif, webp; up to 5 MB each) in any of these ways:
+
+```powershell
+ad -i screenshot.png "what is wrong with this layout?"   # interactive, first prompt
+ad -p -i a.png -i b.png "compare these two"               # print mode
+ad "match this design: @mockup.png"                       # an @path to an image is attached too
+ad chat complete --model agent:AGENT_ID --image shot.png --message "describe this"
+```
+
+The gateway must accept OpenAI-style `image_url` content parts, and the chosen model must support vision.
+
+## Headless runs (`-p`) for scripts and the DevOps Bot SDK
+
+`ad -p` can stand in for `claude -p`: the same flags, the same output events and the same hooks, so a
+tool that drives Claude Code headless (the DevOps Bot SDK) can drive `ad` without a second code path.
+
+```bash
+# One Claude Code-style JSON event per line: system init, assistant text / tool_use,
+# user tool_result (with tool_use_result.filePath for a write), and a final result.
+ad -p --output-format stream-json "fix the failing test" < /dev/null
+
+# Grant tools up front: nobody is there to approve a prompt in a headless run.
+# Claude Code names (Bash, Write, Edit, MultiEdit, WebFetch) or ad's own (bash, write_file …).
+ad -p --permission-mode acceptEdits --allowedTools Bash WebFetch "update the workbook from public sources"
+ad -p --allowedTools "Bash(git:*)" "WebFetch(domain:example.org)" "summarise the repo history"
+
+# Run a Claude Code settings file's PreToolUse command hooks before every tool call.
+ad -p --settings ./claude_settings.json "tidy the build output"
+
+# Continue a headless conversation by the session id a run printed.
+ad -p -r SESSION_ID "the tests still fail; fix them"
+```
+
+- **Events.** Tools are named and shaped as Claude Code names them (`Bash {command}`, `Write {file_path, content}`,
+  `Edit {file_path, old_string, new_string}`, `Read`, `Grep`, `Glob`, `WebFetch {url}`, `Task`), with absolute
+  `file_path`s. A sub-agent's own tool calls carry `parent_tool_use_id`. Every event has `session_id`. The `result`
+  event carries `usage.input_tokens` / `output_tokens` and `permission_denials` (`{tool_name, tool_use_id, tool_input}`);
+  a run that fails still ends with a `result` whose `is_error` is true.
+- **`--allowedTools`.** `Bash(prefix:*)` grants commands that start with that prefix, never a chain (`;`, `&&`, `|` …).
+  A granted write tool still asks for a path outside the working directory, and plan mode still refuses changes.
+  Reads inside the working directory never need a grant. Unknown names are reported on stderr and ignored.
+- **`--settings` hooks.** A file path or inline JSON. Each `hooks.PreToolUse[]` group's `matcher` (a regex over the
+  Claude Code tool name; empty or `*` for all) selects which `type: "command"` hooks run. A hook gets
+  `{session_id, cwd, hook_event_name: "PreToolUse", tool_name, tool_input}` on stdin. Exit code 2 blocks the call
+  (stderr is the reason); exit 0 with `hookSpecificOutput.permissionDecision` of `deny` blocks it (the reason goes
+  to the model) and `allow` lets it run without asking. A hook that fails or times out has no opinion. Hooks run for
+  sub-agents' calls too.
+- `--output-format json` keeps its old one-object shape (`result`, `session_id`, `agent`, `usage`, `permission_denials`).
+
+## Your connectors (Gmail, Slack, Jira …)
+
+The apps you connected in the AI Draftsman web app (**Connectors**) work from the CLI too: the agent gets
+`list_connectors` and `call_connector`, and you can use them yourself with `ad connectors`. The platform holds the
+credentials and performs each call **as you**, so nothing secret reaches this machine.
+
+```bash
+ad login                       # a personal key: required, a workspace API key has no connectors
+ad connectors                  # what you have connected
+ad connectors slack            # one connector and its actions (read / write)
+ad connectors call slack chat.postMessage --params '{"channel":"#dev","text":"build is green"}'
+```
+
+- **Only your connected apps are offered** — never the whole catalogue. Type `@` in the prompt and your connected
+  connectors appear first (`@slack  connector · Slack`); picking one tells the agent to use that connector. With the
+  **Auto** agent you need not pick: the agent is told which connectors you have and chooses the right one itself.
+  `@name` works in `ad -p` prompts too. Set `AD_CONNECTORS=off` to hide them.
+- Sign in again with `ad login` if you signed in before connectors were available: older keys are not tied to you.
+- **Approvals.** Listing is free. A connector action asks first, per action (`Yes, and don't ask again for
+  slack/chat.postMessage`); `acceptEdits` does not cover it, plan mode refuses it, and `bypass` runs it.
+- **Headless.** The tools appear in stream-json as `mcp__aidraftsman__list_connectors` /
+  `mcp__aidraftsman__call_connector`. Grant actions with `--allowedTools mcp__aidraftsman` (or
+  `mcp__aidraftsman__call_connector`, or `call_connector`).
+
+## Load and limits
+
+The agent is shaped to be light on the shared gateway:
+
+- **Sub-agents** run at most 3 at a time (`ad config set maxParallelSubagents 2`, or `AD_MAX_PARALLEL_SUBAGENTS`). A server that returns `capabilities.max_parallel` on `/v1/agents` caps it.
+- **Sub-agent model:** under Auto, built-in sub-agents use `aidraftsman/auto-fast` when the server lists it in `/v1/models` (checked once per session), and Auto otherwise. Choose one yourself with `ad config set subagentModel <slug>` (or `AD_SUBAGENT_MODEL`); `inherit` keeps the main agent's model.
+- **Step limits:** 40 model steps per turn (`maxSteps` / `AD_MAX_STEPS`) and 15 per sub-agent (`subagentMaxSteps` / `AD_SUBAGENT_MAX_STEPS`). An interactive session asks whether to continue; `ad -p` stops cleanly.
+- **Headless runs** (`-p`, `--output-format json`, or stdout not a terminal) send `x-ad-automation: headless` and `x-ad-client-class: cli-automated`; interactive sessions send `x-ad-client-class: cli-interactive`. Every step of a turn sends the same `x-ad-run-id`; sub-agents add `x-ad-parent-run-id`.
+- **Timing:** while a request has produced nothing the session shows how long it has waited for the first token, and any status the server sends. `/status` shows time to first token; `--debug` (or `AD_DEBUG=1`) prints it per request.
+- **Updates:** an interactive session checks npm for a newer version at most once a day, in the background, and prints one line if there is one. Turn it off with `AD_NO_UPDATE_CHECK=1`.
+- The server address lives in one place, `src/lib/config/defaults.ts`. `/doctor` prints it, with the region and served model when the gateway forwards them.