glm-acp-agent 1.0.0

package/README.md

@@ -0,0 +1,365 @@
+# glm-acp-agent
+
+An [Agent Client Protocol (ACP)](https://agentclientprotocol.com) agent written in TypeScript that uses the **Z.AI / Zhipu AI GLM** model family (GLM-5.1, GLM-4.7, GLM-4.6, …) as its reasoning core.
+
+The agent connects to any ACP-compatible IDE or client over **stdio**, streams responses back in real time, and can call a rich set of tools to interact with the user's file system, terminal, and the web.
+
+---
+
+## Coding Plan Only
+
+`glm-acp-agent` is intentionally built for the **Z.AI GLM Coding Plan**. It is not a general-purpose Z.AI Open Platform API client.
+
+By default, model calls use the Coding Plan endpoint:
+
+```text
+https://api.z.ai/api/coding/paas/v4
+```
+
+The same Coding Plan API key is used for the agent's GLM model calls and supported Coding Plan tools. General Z.AI API/resource-package billing surfaces, such as direct `/api/paas/v4` Tool API calls, are intentionally out of scope for this ACP agent.
+
+Built-in web tools use Coding Plan-compatible MCP endpoints, not the general `/api/paas/v4` Tool API. If you need general Z.AI API billing, separate resource packages, or non-Coding Plan endpoints, use a different provider configuration or fork this agent for that purpose.
+
+---
+
+## Features
+
+- **Full ACP compliance** – implements `initialize`, `authenticate`, `session/new`, `session/set_mode`, `session/prompt`, `session/cancel`, `session/close`, `session/list`, `session/load`, `session/fork`, `session/resume`, and `session/set_model`
+- **Streaming** – assistant text and reasoning tokens are forwarded as incremental ACP chunks
+- **Tool calling** – agentic loop with up to 20 turns of GLM function calling
+- **Thinking mode** – GLM's `reasoning_content` tokens are surfaced as `agent_thought_chunk` blocks so the client can show the model's chain of thought
+- **Per-session model switching** – `session/set_model` lets clients change the active GLM model mid-conversation; `session/new` returns the curated `availableModels` list
+- **Image input via Coding Plan Vision MCP** – `promptCapabilities.image` is advertised; pasted ACP image blocks are routed through Z.AI Vision MCP (`@z_ai/mcp-server`) and the resulting analysis is fed into the main coding model. Direct chat-image (e.g. `glm-4v-plus`) calls are intentionally not used.
+- **Session persistence** – conversations are written to `~/.local/state/glm-acp-agent/sessions/` and can be reloaded via `session/load`, branched via `session/fork`, or resumed without replay via `session/resume`
+- **Six built-in tools** (see below)
+- **Capability-aware** – every tool is gated on the client capabilities advertised at `initialize` time; tools the client can't run return a clear error to the model instead of crashing
+- **Permissioned writes / commands** – every `write_file` and `run_command` call asks the user via `session/request_permission` before doing anything
+- **Protocol-correct stop reasons** – maps model and runtime conditions to ACP `end_turn`, `max_tokens`, `max_turn_requests`, `refusal`, and `cancelled`
+- **Protocol-correct tool statuses** – `pending` → `in_progress` → `completed` / `failed`
+- **Token usage reporting** – aggregated usage is returned on the `session/prompt` response
+
+---
+
+## Architecture
+
+```text
+ACP Client (IDE plugin, CLI, …)
+        │  stdio (ndjson)
+        ▼
+  GlmAcpAgent          ← ACP protocol layer  (src/protocol/)
+        │
+        ├─ GlmClient   ← Z.AI / Zhipu AI Coding Plan Chat Completions  (src/llm/)
+        │
+        ├─ ToolExecutor ← executes tool calls  (src/tools/)
+        │    ├─ read_file / write_file       → ACP client (fs.*)
+        │    ├─ list_files / run_command     → ACP client (terminal)
+        │    ├─ web_search / web_reader      → Z.AI Coding Plan Web MCP (HTTP)
+        │    └─ image_analysis               → Z.AI Coding Plan Vision MCP (stdio)
+        │
+        └─ VisionMcpClient ← spawns `npx @z_ai/mcp-server` on demand
+```
+
+The agent process needs network access to `api.z.ai` for chat completions and Web MCP, plus `npx` available on `PATH` so it can launch `@z_ai/mcp-server` for vision. Filesystem and shell operations remain delegated to the ACP client; the agent itself only writes to the OS temp directory when it needs to materialize a pasted image for Vision MCP, and those temp files are removed once the prompt completes.
+
+---
+
+## Available Tools
+
+| Tool | Runs on | Requires client capability | Description |
+|------|---------|----------------------------|-------------|
+| `read_file` | ACP client | `fs.readTextFile` | Read the text content of a file |
+| `write_file` | ACP client | `fs.writeTextFile` | Write or overwrite a text file (asks for permission) |
+| `list_files` | ACP client | `terminal` | List a directory via `ls -la` (POSIX shell required) |
+| `run_command` | ACP client | `terminal` | Run an arbitrary shell command via `sh -c` (asks for permission) |
+| `web_search` | Agent (Z.AI Coding Plan MCP) | – | Search the web — returns titles, URLs, and summaries |
+| `web_reader` | Agent (Z.AI Coding Plan MCP) | – | Fetch and parse a web page (markdown or plain text) |
+| `image_analysis` | Agent (Z.AI Vision MCP, stdio) | – | Analyze a local image path or remote URL using `@z_ai/mcp-server` |
+
+---
+
+## Prerequisites
+
+- **Node.js** 20 or later (native `fetch` and Web Streams required)
+- **npm** 9 or later
+- A **Z.AI API key** — obtain one at <https://z.ai/manage-apikey/apikey-list>
+
+---
+
+## Installation
+
+```bash
+git clone https://github.com/stefandevo/glm-acp-agent.git
+cd glm-acp-agent
+npm install
+npm run build
+```
+
+---
+
+## Configuration
+
+The agent reads its configuration from environment variables, plus an optional credentials file written by `glm-acp-agent --setup`.
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `Z_AI_API_KEY` | One of env / `--setup` | — | API key for the Z.AI / Zhipu AI service. If unset, the credentials file is consulted. |
+| `ACP_GLM_MODEL` | No | `glm-5.1` | Default GLM model for new sessions |
+| `ACP_GLM_AVAILABLE_MODELS` | No | built-in list | Comma-separated list of model ids advertised in `session/set_model` |
+| `ACP_GLM_BASE_URL` | No | `https://api.z.ai/api/coding/paas/v4` | Override the API base URL |
+| `ACP_GLM_MAX_TOKENS` | No | `8192` | Cap on `max_tokens` for each completion |
+| `ACP_GLM_THINKING` | No | auto-detected | Force thinking mode `true` / `false` |
+| `ACP_GLM_SESSION_DIR` | No | `$XDG_STATE_HOME/glm-acp-agent/sessions` | Where session JSON files are persisted |
+| `ACP_GLM_DEBUG` | No | — | Set to `true` or `1` to enable verbose debug logging to stderr (shows model selection, API key resolution, tool calls, and usage stats) |
+| `XDG_CONFIG_HOME` | No | `~/.config` | Where the credentials file is read/written |
+
+### One-time setup
+
+If you'd rather not pass `Z_AI_API_KEY` through your ACP client's environment block, run the interactive setup once and the agent will read the key from disk on subsequent launches:
+
+```bash
+# From the project directory (after npm run build)
+node dist/index.js --setup
+
+# Or, if you installed globally
+glm-acp-agent --setup
+```
+
+The key is written to `$XDG_CONFIG_HOME/glm-acp-agent/credentials.json` (default: `~/.config/glm-acp-agent/credentials.json`) with `0600` permissions. The `Z_AI_API_KEY` environment variable, when set, always wins over the file.
+
+### Supported models
+
+The agent advertises only the models on the current Z.AI Coding Plan allowlist:
+
+| Model | Notes |
+|-------|-------|
+| `glm-5.1` | **Default.** Long-horizon coding model; thinking mode auto-enabled |
+| `glm-5-turbo` | Faster Coding Plan reasoning model |
+| `glm-4.7` | 200K-context reasoning model |
+| `glm-4.5-air` | Lightweight, lower-latency model |
+
+`ACP_GLM_AVAILABLE_MODELS` still lets you advertise custom IDs, but custom IDs sit outside the supported Coding Plan list — the Coding Plan endpoint will reject any model code Z.AI hasn't whitelisted (business code `1211`).
+
+Vision (`glm-4v-plus` etc.) is **not** advertised as a chat model: vision on the Coding Plan flows through the [Vision MCP](#vision-mcp) section below instead.
+
+When the model name matches `glm-4.5`, `glm-4.6`, `glm-4.7`, or `glm-5.x`, the agent enables Z.AI's `thinking: { type: "enabled" }` extension and forwards reasoning tokens to the client as `agent_thought_chunk` blocks. Override with `ACP_GLM_THINKING=false` if you want plain completions only.
+
+### Vision MCP
+
+Pasted ACP image blocks are not sent to the chat-completions endpoint. Instead, the agent boots `@z_ai/mcp-server` over stdio (via `npx -y @z_ai/mcp-server@latest`) and calls its `image_analysis` tool. The text result is spliced into the user message as `<image_analysis index="N">…</image_analysis>` so the regular Coding Plan model can reason about it.
+
+Prerequisites:
+
+- `npx` on `PATH` (Node 18+ / npm 9+).
+- The same `Z_AI_API_KEY` used for chat completions; the agent forwards it to the MCP server as `Z_AI_API_KEY` plus `Z_AI_MODE=ZAI`.
+
+The model can also call `image_analysis` explicitly with `{ image_source: "/path/or/url", prompt?: "…" }`. Vision failures (missing `npx`, MCP startup, quota) are surfaced as actionable errors but never abort the prompt; an inline `<image_analysis_error>` annotation is used so the conversation can continue.
+
+---
+
+## Running
+
+### Standalone (stdio)
+
+```bash
+export Z_AI_API_KEY=your_key_here
+node dist/index.js
+```
+
+The agent speaks the ACP newline-delimited JSON protocol over stdin/stdout. You can connect any ACP-compatible client to it.
+
+### As a global CLI
+
+```bash
+npm install -g .
+export Z_AI_API_KEY=your_key_here
+glm-acp-agent
+```
+
+### Development mode (watch)
+
+```bash
+export Z_AI_API_KEY=your_key_here
+npm run dev        # tsc --watch
+```
+
+---
+
+## Connecting to an ACP Client
+
+### Zed (recommended for local testing)
+
+[Zed](https://zed.dev) is currently the most polished editor for trying out ACP agents locally — it spawns the agent process over stdio and surfaces it in the agent panel. This is the fastest way to iterate on `glm-acp-agent` before publishing it to the ACP registry or to npm.
+
+#### 1. Prerequisites
+
+- A recent build of [Zed](https://zed.dev/download) that supports the `agent_servers` setting
+- Node.js 20 or later on your `PATH` (`node --version`)
+- A Z.AI API key — create one at <https://z.ai/manage-apikey/apikey-list>
+
+#### 2. Build the agent
+
+```bash
+git clone https://github.com/stefandevo/glm-acp-agent.git
+cd glm-acp-agent
+npm install
+npm run build
+```
+
+Take note of the absolute path to the freshly built entry point — Zed needs it (no `~`, no `$HOME` shortcuts):
+
+```bash
+echo "$(pwd)/dist/index.js"
+```
+
+#### 3. Wire it into Zed
+
+Open (or create) `~/.config/zed/settings.json` and add an `agent_servers` entry. Pick **one** of the two API-key strategies below.
+
+**Option A — inline `env` block (simplest):**
+
+```json
+{
+  "agent_servers": {
+    "glm": {
+      "command": "node",
+      "args": ["/absolute/path/to/glm-acp-agent/dist/index.js"],
+      "env": { "Z_AI_API_KEY": "sk-…" }
+    }
+  }
+}
+```
+
+**Option B — credentials file (no key in your editor settings):**
+
+Run the interactive setup once. From the project directory:
+
+```bash
+node dist/index.js --setup
+```
+
+…or, if you `npm install -g .`'d the package:
+
+```bash
+glm-acp-agent --setup
+```
+
+The key is written to `~/.config/glm-acp-agent/credentials.json` with `0600` permissions. Then drop the `env` block from the Zed entry — the agent will read the file on launch:
+
+```json
+{
+  "agent_servers": {
+    "glm": {
+      "command": "node",
+      "args": ["/absolute/path/to/glm-acp-agent/dist/index.js"]
+    }
+  }
+}
+```
+
+If `Z_AI_API_KEY` is set in the environment **and** a credentials file exists, the environment variable wins.
+
+#### 4. Verify it works
+
+1. Save `settings.json`. Zed reloads settings automatically.
+2. Open the **agent panel** (use the command palette: `agent panel: toggle focus`).
+3. In the agent picker, select **glm** — Zed labels external agents by their `agent_servers` key.
+4. Start a new thread and send a small prompt that exercises a tool, e.g. `Read package.json and tell me the project name.`
+5. You should see streaming text, a `read_file` tool call awaiting permission, and (with a thinking-capable model like `glm-5.1`) reasoning surfaced as a separate thought block.
+
+#### 5. Iterating on the agent
+
+After editing the source, rebuild:
+
+```bash
+npm run build
+```
+
+Zed spawns a fresh agent process per thread, so the easiest way to pick up changes is to **start a new thread** with the glm agent. If you see stale behavior, fully quit and reopen Zed — that guarantees no in-flight process is reused.
+
+For a tighter inner loop, run `npm run dev` in a terminal so `dist/` rebuilds on every save; you only need to start a new Zed thread to test the latest code.
+
+#### 6. Troubleshooting
+
+- **The "glm" agent doesn't appear in the picker.** — `settings.json` likely has a JSON parse error, or your Zed build is older than `agent_servers` support. Open the Zed log via the command palette (`zed: open log`) and look for settings errors.
+- **`Error: Cannot find module '/.../dist/index.js'`** — you skipped `npm run build`, or the path in `args` is wrong. It must be absolute and point at a file that exists.
+- **`No API key found.`** — neither `Z_AI_API_KEY` nor `~/.config/glm-acp-agent/credentials.json` is set. Use Option A or Option B in step 3.
+- **`HTTP 401: Invalid API key`** — your key is wrong, expired, or for the wrong region. Rotate it on <https://z.ai/manage-apikey/apikey-list>.
+- **`client does not advertise the … capability`** — Zed didn't expose that capability to the agent (e.g. `terminal` for `run_command`/`list_files`). Ask the model to use a different tool, or upgrade Zed.
+
+### Neovim / VS Code / JetBrains / any ACP client
+
+Any client that supports configuring an ACP agent via a `command` + `args` invocation works the same way: point it at `node /absolute/path/to/glm-acp-agent/dist/index.js` and supply `Z_AI_API_KEY` in the environment.
+
+### Authentication
+
+The agent advertises two authentication methods at `initialize` time:
+
+1. An **`agent`-default** method — the agent will read the API key itself, either from the `Z_AI_API_KEY` environment variable or from the credentials file written by `glm-acp-agent --setup`.
+2. An **`env_var`** method (experimental SDK extension) describing the `Z_AI_API_KEY` variable so capable clients can prompt the user and inject it.
+
+ACP clients that support the auth-methods proposal will use whichever method they recognise; clients that don't handle auth methods should set `Z_AI_API_KEY` themselves before launching the agent (or run `glm-acp-agent --setup` once and let the agent read it from disk).
+
+---
+
+## Project Structure
+
+```text
+src/
+├── index.ts                  # Entry point – starts stdio connection or --setup flow
+├── setup.ts                  # Interactive credential setup (`--setup`)
+├── llm/
+│   ├── glm-client.ts         # OpenAI-compatible client for Z.AI / Zhipu AI
+│   └── credentials.ts        # API-key resolution (env var > credentials.json)
+├── protocol/
+│   ├── connection.ts         # Sets up the ACP stdio connection
+│   ├── agent.ts              # GlmAcpAgent – ACP protocol implementation
+│   └── session-store.ts      # On-disk persistence for load/fork/resume
+├── tools/
+│   ├── definitions.ts        # Tool JSON schemas (function-calling format)
+│   └── executor.ts           # ToolExecutor – dispatches tool calls
+└── tests/
+    ├── agent.test.ts         # Protocol-level tests for GlmAcpAgent
+    ├── credentials.test.ts   # Credential resolution and --setup persistence
+    ├── executor.test.ts      # Tests for ToolExecutor
+    ├── glm-client.test.ts    # Tests for streaming / tool-call assembly
+    └── integration.test.ts   # End-to-end tests over the real ACP ndjson transport
+```
+
+---
+
+## Building & Testing
+
+```bash
+npm run build   # one-shot TypeScript compilation → dist/
+npm run dev     # watch mode
+npm test        # build + run unit tests with the node:test runner
+```
+
+The test suite covers:
+
+- ACP protocol-version negotiation, capability advertising, and auth method shape
+- Session lifecycle (`new` / `list` / `close`, filter by `cwd`)
+- Prompt loop streaming, tool-call assembly, max-turn cap, cancellation, stop-reason mapping (`stop` → `end_turn`, `length` → `max_tokens`, `content_filter` → `refusal`, `tool_calls` exhausted → `max_turn_requests`)
+- Content-block conversion (`text`, `resource_link`, embedded `resource`)
+- Token usage reporting on the `PromptResponse`
+- Tool call lifecycle (`pending` → `in_progress` → `completed` / `failed`)
+- Capability gating (tools refuse cleanly when the client did not advertise the required capability)
+- Permission flows for `write_file` and `run_command` (allow / reject / cancel)
+- Shell-quoted argument handling for `list_files` and `run_command`
+- GLM streaming: text deltas, `reasoning_content` deltas, multi-chunk tool-call assembly, and trailing usage
+- Image preprocessing through a mocked Vision MCP client and graceful degradation on Vision MCP failures
+
+---
+
+## Troubleshooting
+
+- **`No API key found.`** — either set `Z_AI_API_KEY` in the environment, or run `node dist/index.js --setup` (or `glm-acp-agent --setup` if installed globally) once to store the key on disk.
+- **`HTTP 401: Invalid API key`** — your key is wrong or expired; rotate it on <https://z.ai/manage-apikey/apikey-list>.
+- **The agent says "client does not advertise the … capability".** — your ACP client doesn't expose that capability (e.g. terminal). Ask the model to use a different tool, or upgrade the client.
+- **Tools never get to run.** — make sure the client is sending the `clientCapabilities` field in `initialize`; the agent uses it to decide which tools to expose to the model.
+
+---
+
+## License
+
+Apache 2.0 – see [LICENSE](LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * GLM ACP Agent entry point.
+ *
+ * Starts an ACP agent over stdio that uses the Zhipu AI GLM model family
+ * as its reasoning core. Pass `--setup` instead of starting the protocol
+ * loop to interactively store a Z.AI API key on disk.
+ *
+ * Environment variables:
+ *   Z_AI_API_KEY      - API key for the Z.AI / Zhipu AI service. If unset,
+ *                       falls back to the credentials file written by --setup.
+ *   ACP_GLM_MODEL     - (optional) Override the default model (default: glm-5.1)
+ */
+import { startConnection } from "./protocol/connection.js";
+import { runSetup } from "./setup.js";
+const args = process.argv.slice(2);
+if (args.includes("--setup")) {
+    runSetup()
+        .then(() => process.exit(0))
+        .catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`Setup failed: ${message}\n`);
+        process.exit(1);
+    });
+}
+else if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write([
+        "glm-acp-agent — ACP agent using Zhipu AI's GLM models",
+        "",
+        "Usage:",
+        "  glm-acp-agent           Start the ACP stdio loop (run by an ACP client)",
+        "  glm-acp-agent --setup   Interactively store your Z.AI API key on disk",
+        "  glm-acp-agent --help    Show this message",
+        "",
+        "Environment variables:",
+        "  Z_AI_API_KEY                   API key (overrides the stored credentials)",
+        "  ACP_GLM_MODEL                  Default model id (e.g. glm-5.1)",
+        "  ACP_GLM_AVAILABLE_MODELS       Comma-separated list of advertised models",
+        "  ACP_GLM_BASE_URL               Override the Z.AI API base URL",
+        "  ACP_GLM_MAX_TOKENS             Per-call max output tokens (default 8192)",
+        "  ACP_GLM_THINKING               Force thinking mode (true / false)",
+        "  ACP_GLM_SESSION_DIR            Where to persist sessions (default: ~/.local/state/glm-acp-agent/sessions)",
+        "  ACP_GLM_DEBUG                  Enable verbose stderr logging (true or 1)",
+        "  XDG_CONFIG_HOME                Where to read/write credentials.json (default: ~/.config)",
+        "",
+    ].join("\n"));
+    process.exit(0);
+}
+else {
+    const connection = startConnection();
+    // Keep the process alive until the connection closes
+    connection.closed
+        .then(() => {
+        process.exit(0);
+    })
+        .catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`Fatal error: ${message}\n`);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAEnC,IAAI,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;IAC7B,QAAQ,EAAE;SACP,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;SAC3B,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QACtB,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iBAAiB,OAAO,IAAI,CAAC,CAAC;QACnD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACP,CAAC;KAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;IAC1D,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB;QACE,uDAAuD;QACvD,EAAE;QACF,QAAQ;QACR,2EAA2E;QAC3E,yEAAyE;QACzE,6CAA6C;QAC7C,EAAE;QACF,wBAAwB;QACxB,6EAA6E;QAC7E,kEAAkE;QAClE,4EAA4E;QAC5E,iEAAiE;QACjE,4EAA4E;QAC5E,qEAAqE;QACrE,6GAA6G;QAC7G,4EAA4E;QAC5E,4FAA4F;QAC5F,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;KAAM,CAAC;IACN,MAAM,UAAU,GAAG,eAAe,EAAE,CAAC;IAErC,qDAAqD;IACrD,UAAU,CAAC,MAAM;SACd,IAAI,CAAC,GAAG,EAAE;QACT,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC;SACD,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QACtB,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,gBAAgB,OAAO,IAAI,CAAC,CAAC;QAClD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/llm/credentials.d.ts

@@ -0,0 +1,15 @@
+/** Path to the credentials JSON file. Honours `$XDG_CONFIG_HOME`. */
+export declare function credentialsPath(): string;
+/** Read the API key from the credentials file, returning undefined if absent. */
+export declare function readCredentialsKey(path?: string): string | undefined;
+/**
+ * Resolve the API key: env var > credentials file. Returns undefined when
+ * neither source has one set.
+ */
+export declare function resolveApiKey(): string | undefined;
+/**
+ * Write the API key to the credentials file. Restricts the file to mode 0600
+ * so it isn't world-readable on shared machines.
+ */
+export declare function writeCredentials(apiKey: string, path?: string): void;
+//# sourceMappingURL=credentials.d.ts.map

package/dist/llm/credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../../src/llm/credentials.ts"],"names":[],"mappings":"AAuBA,qEAAqE;AACrE,wBAAgB,eAAe,IAAI,MAAM,CAIxC;AAED,iFAAiF;AACjF,wBAAgB,kBAAkB,CAAC,IAAI,GAAE,MAA0B,GAAG,MAAM,GAAG,SAAS,CASvF;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,MAAM,GAAG,SAAS,CAalD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,MAA0B,GAAG,IAAI,CAOvF"}

package/dist/llm/credentials.js

@@ -0,0 +1,54 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { debug, maskSecret } from "./logger.js";
+/** Path to the credentials JSON file. Honours `$XDG_CONFIG_HOME`. */
+export function credentialsPath() {
+    const xdg = process.env["XDG_CONFIG_HOME"];
+    const base = xdg && xdg.length > 0 ? xdg : join(homedir(), ".config");
+    return join(base, "glm-acp-agent", "credentials.json");
+}
+/** Read the API key from the credentials file, returning undefined if absent. */
+export function readCredentialsKey(path = credentialsPath()) {
+    try {
+        const raw = readFileSync(path, "utf8");
+        const parsed = JSON.parse(raw);
+        const key = parsed.z_ai_api_key;
+        return typeof key === "string" && key.length > 0 ? key : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve the API key: env var > credentials file. Returns undefined when
+ * neither source has one set.
+ */
+export function resolveApiKey() {
+    const fromEnv = process.env["Z_AI_API_KEY"];
+    if (typeof fromEnv === "string" && fromEnv.length > 0) {
+        debug(`resolveApiKey: source=env key=${maskSecret(fromEnv)}`);
+        return fromEnv;
+    }
+    const fromFile = readCredentialsKey();
+    if (fromFile) {
+        debug(`resolveApiKey: source=file key=${maskSecret(fromFile)}`);
+    }
+    else {
+        debug("resolveApiKey: no key found");
+    }
+    return fromFile;
+}
+/**
+ * Write the API key to the credentials file. Restricts the file to mode 0600
+ * so it isn't world-readable on shared machines.
+ */
+export function writeCredentials(apiKey, path = credentialsPath()) {
+    if (!apiKey || apiKey.length === 0) {
+        throw new Error("Refusing to write empty API key");
+    }
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const body = { z_ai_api_key: apiKey };
+    writeFileSync(path, JSON.stringify(body, null, 2) + "\n", { mode: 0o600 });
+}
+//# sourceMappingURL=credentials.js.map

package/dist/llm/credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.js","sourceRoot":"","sources":["../../src/llm/credentials.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAoBhD,qEAAqE;AACrE,MAAM,UAAU,eAAe;IAC7B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAC3C,MAAM,IAAI,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC;IACtE,OAAO,IAAI,CAAC,IAAI,EAAE,eAAe,EAAE,kBAAkB,CAAC,CAAC;AACzD,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,kBAAkB,CAAC,OAAe,eAAe,EAAE;IACjE,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACvC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAoB,CAAC;QAClD,MAAM,GAAG,GAAG,MAAM,CAAC,YAAY,CAAC;QAChC,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IACrE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAC5C,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtD,KAAK,CAAC,iCAAiC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC9D,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,MAAM,QAAQ,GAAG,kBAAkB,EAAE,CAAC;IACtC,IAAI,QAAQ,EAAE,CAAC;QACb,KAAK,CAAC,kCAAkC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAClE,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,6BAA6B,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc,EAAE,OAAe,eAAe,EAAE;IAC/E,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IACrD,CAAC;IACD,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3D,MAAM,IAAI,GAAoB,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC;IACvD,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AAC7E,CAAC"}

package/dist/llm/glm-client.d.ts

@@ -0,0 +1,63 @@
+import type { ChatCompletionMessageParam } from "openai/resources/index.js";
+import type { ModelInfo, Usage } from "@agentclientprotocol/sdk";
+/**
+ * A single message in the GLM conversation history.
+ */
+export type GlmMessage = ChatCompletionMessageParam;
+/**
+ * A streamed chunk from the GLM API.
+ */
+export interface GlmStreamChunk {
+    /** Incremental assistant text */
+    text?: string;
+    /** Incremental reasoning/thinking text */
+    thinking?: string;
+    /** A complete tool call (assembled from streaming deltas) */
+    toolCall?: {
+        id: string;
+        name: string;
+        arguments: string;
+    };
+    /** Token usage reported when the stream finishes */
+    usage?: Usage;
+    /** Set when the stream is done */
+    done?: boolean;
+    /** Stop reason when done */
+    stopReason?: string;
+}
+/** Options applied to a single `streamChat` call. */
+export interface StreamChatOptions {
+    /** GLM model identifier to use for this call. */
+    model: string;
+}
+/** Default GLM model when neither client nor user has chosen one. */
+export declare const DEFAULT_MODEL = "glm-5.1";
+/**
+ * Resolve the list of advertised models, allowing the user to override the
+ * built-in list via `ACP_GLM_AVAILABLE_MODELS`.
+ */
+export declare function getAvailableModels(): ModelInfo[];
+/** Default model for new sessions: env override → built-in default. */
+export declare function getDefaultModel(): string;
+/**
+ * Wrapper around the OpenAI-compatible Zhipu AI (Z.AI) API.
+ *
+ * Uses the standard `openai` npm package pointed at `https://api.z.ai/api/paas/v4`
+ * so no Zhipu-specific SDK is required. The Z.AI service speaks the OpenAI
+ * Chat Completions wire format, plus a few GLM-specific extras (like the
+ * `thinking` field and `delta.reasoning_content` for reasoning tokens).
+ */
+export declare class GlmClient {
+    private client;
+    private maxTokens;
+    constructor();
+    /**
+     * Stream a chat completion from the GLM model, yielding chunks as they arrive.
+     *
+     * Reasoning/thinking tokens (from GLM "thinking" mode) are mapped to
+     * `thinking` chunks so the ACP agent can forward them as `agent_thought_chunk`
+     * blocks.
+     */
+    streamChat(messages: GlmMessage[], signal?: AbortSignal, options?: StreamChatOptions): AsyncGenerator<GlmStreamChunk>;
+}
+//# sourceMappingURL=glm-client.d.ts.map

package/dist/llm/glm-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glm-client.d.ts","sourceRoot":"","sources":["../../src/llm/glm-client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,0BAA0B,EAAsB,MAAM,2BAA2B,CAAC;AAChG,OAAO,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAKjE;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,0BAA0B,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,iCAAiC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE;QACT,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,oDAAoD;IACpD,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,kCAAkC;IAClC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,4BAA4B;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qDAAqD;AACrD,MAAM,WAAW,iBAAiB;IAChC,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;CACf;AAKD,qEAAqE;AACrE,eAAO,MAAM,aAAa,YAAY,CAAC;AAiCvC;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,SAAS,EAAE,CAYhD;AAED,uEAAuE;AACvE,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;;;;GAOG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAS;;IAgB1B;;;;;;OAMG;IACI,UAAU,CACf,QAAQ,EAAE,UAAU,EAAE,EACtB,MAAM,CAAC,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,cAAc,CAAC,cAAc,CAAC;CA6IlC"}