@uipath/coder-tool 1.199.0-preview.116

package/README.md

@@ -0,0 +1,104 @@
+# @uipath/coder-tool — `uip coder`
+
+An AI agent for **building UiPath automations** from your terminal. `uip coder` embeds the open-source [Pi coding agent](https://github.com/badlogic/pi-mono) and connects it to the **UiPath LLM Gateway**, so it runs against your UiPath account — no personal LLM subscription needed. Bring-your-own keys for Claude, OpenAI, Azure OpenAI, and Grok work too.
+
+> **Scope**: this tool is designed specifically for UiPath automation work — scaffolding and deploying agents, authoring processes, operating Orchestrator, querying platform data. It is not intended as a general-purpose coding assistant; its system prompt steers it toward UiPath artifacts and the `uip` CLI.
+
+> **Availability**: `uip coder` registers on **preview (prerelease) CLI builds only** until the tool-permission posture is settled. On stable builds the command is absent. For local development, the standalone bin (`node packages/coder-tool/dist/index.js`) always registers.
+
+> **Permissions and data**: the agent executes tool calls (shell commands, file edits) **without per-call approval** — treat a `uip coder` session like running a script you reviewed the prompt for, and prefer it in workspaces you can afford to change. The `uipath` provider is the only one that keeps prompts and code **in-tenant** (LLM Gateway); BYO providers send conversation data to that external provider. In restricted customer environments use `--provider uipath` and `--no-extensions`.
+
+The agent reads and edits project files, runs commands, and — because it ships with UiPath CLI guidance in its system prompt — knows how to drive `uip` itself: build and deploy agents, run Orchestrator jobs, query Data Fabric, validate solutions, and everything else the CLI exposes.
+
+## Quick start
+
+```bash
+uip login          # once — the uipath provider uses this session
+uip coder           # opens the interactive agent (TUI)
+```
+
+Pick the UiPath LLM Gateway explicitly:
+
+```bash
+uip coder --provider uipath --model gpt-4o-2024-11-20
+```
+
+Or use your own keys — export one and pick the model:
+
+| Provider | Environment variables |
+| --- | --- |
+| Anthropic (Claude) | `ANTHROPIC_API_KEY` |
+| OpenAI | `OPENAI_API_KEY` |
+| Azure OpenAI | `AZURE_OPENAI_API_KEY` + `AZURE_OPENAI_BASE_URL` (or `AZURE_OPENAI_RESOURCE_NAME`) |
+| xAI (Grok) | `XAI_API_KEY` |
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+uip coder --provider anthropic --model claude-sonnet-4-5
+```
+
+Pi ships many more providers (Google, Groq, Mistral, OpenRouter, …) — `uip coder --list-models` shows everything available.
+
+## Everyday usage
+
+```bash
+uip coder                                  # interactive TUI
+uip coder -p "explain this repository"     # one prompt, print the answer, exit
+uip coder --continue                       # resume the previous session
+uip coder --list-models                    # all providers and models
+uip coder --list-models uipath             # filter to the UiPath provider
+uip coder --help                           # full Pi option reference
+```
+
+Every argument is forwarded to Pi unchanged, so the entire Pi CLI surface applies: sessions (`--resume`, `--session`, `--no-session`), thinking levels (`--thinking high`), tool control (`--tools`, `--no-tools`), extensions (`-e`), skills (`--skill`), and output modes (`--mode json`). Inside the TUI, `Ctrl+P` cycles models.
+
+### Asking it to work with UiPath
+
+The agent's system prompt includes a guide to the `uip` CLI (see [`templates/uipath-cli.md`](templates/uipath-cli.md)), so prompts like these work out of the box:
+
+```bash
+uip coder -p "list my failed Orchestrator jobs from today and summarize why they failed"
+uip coder -p "scaffold a new agent project that triages incoming invoices, then pack it"
+uip coder "help me debug why my maestro process instance is stuck"
+```
+
+It discovers commands with `uip --help` rather than guessing, checks `uip login status` before platform calls, and asks before running destructive commands.
+
+## The `uipath` provider
+
+When a `uip login` session exists, a `uipath` provider is registered automatically at startup. It routes OpenAI-compatible chat completions through the LLM Gateway front door:
+
+```
+{baseUrl}/{org}/{tenant}/agenthub_/llm/openai/deployments/{model}/chat/completions
+```
+
+- **Auth**: the CLI's own access token — the default login scopes already include `LLMGateway`. The token is refreshed and the provider re-registered automatically when it nears expiry.
+- **Not logged in?** The provider is skipped silently; every other provider keeps working. Run `uip login` and restart `uip coder` to enable it.
+- **Models**: the gateway does not expose a model-discovery route on this path yet, so a curated list is registered. It will switch to live discovery when the gateway ships one.
+
+## Troubleshooting
+
+| Symptom | Cause / fix |
+| --- | --- |
+| No `uipath` rows in `--list-models` | Not logged in — run `uip login`. |
+| HTML "Access denied" response mid-chat on the `uipath` provider | The UiPath edge WAF rejects requests whose tool schemas contain shell/SQL-looking text. Pi's built-in tools pass; some third-party Pi extensions (e.g. context-mode) do not. Relaunch with `uip coder --no-extensions`. |
+| `SyntaxError` / startup crash on old Node | Pi requires Node.js >= 22.19. |
+| 401 after a long-idle session | Token expired and refresh failed — run `uip login` again. |
+| `{"Result": "Failure", "Message": "The coding agent exited with code N."}` | Pi failed to start or aborted — the underlying error is printed just above the envelope. |
+
+## How it fits together
+
+- `src/commands/chat.ts` — registers `uip coder`, forwards argv to Pi's `main()`, appends the UiPath CLI guide to the system prompt, and converts Pi's hard exits into the CLI's `Result: Failure` envelope.
+- `src/providers/uipath.ts` — a Pi extension that registers the LLM Gateway provider from the `uip login` session and keeps its token fresh.
+- `templates/uipath-cli.md` — the system-prompt guide that teaches the agent to use `uip` (shipped as `dist/templates/` in the published package).
+- Pi itself (`@earendil-works/pi-coding-agent`) is a runtime dependency, not bundled: it loads theme/doc assets relative to its own package directory and ships wasm/native components. Sessions and settings follow Pi's conventions (`~/.pi`, project-level `.pi/`), so an existing Pi setup carries over.
+
+## Development
+
+```bash
+bun run build                                  # bundle via tools/build-tool.ts
+bunx vitest run packages/coder-tool/src         # unit tests
+node packages/coder-tool/dist/index.js -p "hi"  # standalone smoke test
+```
+
+Scenario coverage lives in [`scenarios/coder-tool/coding-agent.md`](../../scenarios/coder-tool/coding-agent.md); the scenarios need a live gateway session or provider keys, so the e2e file carries `it.skip` placeholders and they are verified manually.