pi-grok-agent 0.1.1 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +27 -275
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -6,196 +6,27 @@ Grok's agent. Pi's workflow.
|
|
|
6
6
|
pi install npm:pi-grok-agent
|
|
7
7
|
```
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
Run [Grok Build](https://docs.x.ai/build/overview) as an additional model provider in [Pi coding agent](https://github.com/earendil-works/pi). Grok keeps its native environment, tools, and session history. Pi provides the DIY harness, turn control, permission requests, and extensions.
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
Two things this package is not:
|
|
14
|
-
|
|
15
|
-
- It connects the Grok Build agent over ACP, not the xAI chat-completions API. You need the Grok Build CLI and its own login.
|
|
16
|
-
- Its tool gates are not an operating-system sandbox. Grok runs with your user's permissions.
|
|
17
|
-
|
|
18
|
-
Version 0.1.1 on [npm](https://www.npmjs.com/package/pi-grok-agent) and as a [GitHub release](https://github.com/JangMan-J/pi-grok-agent/releases/tag/v0.1.1). Developed and tested on Linux with Node.js 26.10.0, Pi 0.87.1, and Grok Build 1.0.41. Other versions and platforms are untested. The recorded runs are in [docs/launch-verification.md](docs/launch-verification.md).
|
|
19
|
-
|
|
20
|
-
[Requirements](#requirements) · [Quick start](#quick-start) · [First result](#first-result) · [What Pi adds](#what-pi-adds) · [Models](#models) · [Limitations](#limitations) · [Safety](#safety) · [Reference](docs/usage.md)
|
|
21
|
-
|
|
22
|
-
## Requirements
|
|
23
|
-
|
|
24
|
-
| Item | Requirement |
|
|
25
|
-
| --- | --- |
|
|
26
|
-
| Grok account | A [grok.com](https://grok.com) account, any membership tier. A free account works: verified live on 2026-09-28 with Grok Build 1.0.41, where headless turns returned `PONG` and a read-only tool turn answered correctly ([docs/launch-verification.md](docs/launch-verification.md)). Grok usage counts against that account. |
|
|
27
|
-
| Grok Build CLI | `grok` on `PATH`, or its path in `PI_GROK_BINARY`. |
|
|
28
|
-
| Grok login | Only if Grok Build is not signed in yet. Run `/grok login` in Pi, or `grok login` in a terminal. Both use Grok's own device-code sign-in, and Grok keeps the credential in `~/.grok/auth.json`; Pi stores nothing (`src/login.ts`). Pi's `/login` xAI entry is a separate login and does not sign in Grok Build, and `XAI_API_KEY` does not replace it. |
|
|
29
|
-
| Pi | Tested with 0.87.1. Other versions are untested. [Install Pi first](https://github.com/earendil-works/pi#quick-start). |
|
|
30
|
-
| Node.js | 22.19 or later, Pi's minimum (`engines` in `package.json`). Only 26.10.0 is tested here. |
|
|
31
|
-
| Optional | A terminal with inline image support. ImageMagick 7 (`magick`) shows JPEG, WebP, and GIF inline; PNG needs no converter. |
|
|
32
|
-
|
|
33
|
-
Pi shows the cost Grok reports for each turn. Which models your account may use is Grok's decision, not this package's — see [Models](#models).
|
|
34
|
-
|
|
35
|
-
## Quick start
|
|
36
|
-
|
|
37
|
-
1. Install the package:
|
|
38
|
-
|
|
39
|
-
```sh
|
|
40
|
-
pi install npm:pi-grok-agent
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
2. Start Pi in your project and pick a Grok model in `/models`: Grok 4.7, Grok 4.7 Build Fast, Grok 4.6, or Grok 4.5.
|
|
44
|
-
3. If Grok Build is not signed in, run `/grok login` and approve the code in your browser. Grok runs its own device-code sign-in and stores the credential in `~/.grok/auth.json`; Pi stores nothing (`src/login.ts`).
|
|
45
|
-
4. Send a message and watch the `grok-tool` lines appear. See [First result](#first-result) for what a healthy first turn looks like.
|
|
46
|
-
|
|
47
|
-
The first Grok turn starts the local gateway that ships with the package and waits for it, about 5 seconds. The gateway listens on loopback at `127.0.0.1:2419`; `GROK_ACP_URL` picks another loopback port.
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
<details>
|
|
52
|
-
<summary>Diagram source (mermaid)</summary>
|
|
53
|
-
|
|
54
|
-
```mermaid
|
|
55
|
-
flowchart LR
|
|
56
|
-
subgraph PI["Pi process (one per terminal)"]
|
|
57
|
-
direction TB
|
|
58
|
-
UI["Pi TUI<br/>transcript, dialogs, /models"]
|
|
59
|
-
EXT["pi-grok-agent extension<br/>provider grok/*"]
|
|
60
|
-
TOOLS["Pi extension tools"]
|
|
61
|
-
UI --- EXT
|
|
62
|
-
EXT --- TOOLS
|
|
63
|
-
end
|
|
64
|
-
|
|
65
|
-
subgraph GW["Gateway (one per machine, 127.0.0.1:2419)"]
|
|
66
|
-
direction TB
|
|
67
|
-
WS["WebSocket /ws<br/>bearer secret"]
|
|
68
|
-
GUARD["Reverse-request guard<br/>ack deadlines, fail closed"]
|
|
69
|
-
MCP["MCP relay<br/>HTTP /mcp/<token>"]
|
|
70
|
-
end
|
|
71
|
-
|
|
72
|
-
subgraph GROK["Grok Build"]
|
|
73
|
-
direction TB
|
|
74
|
-
BRIDGE["grok agent --leader stdio<br/>one bridge per Pi connection"]
|
|
75
|
-
LEADER["grok agent leader<br/>harness, native tools, subagents"]
|
|
76
|
-
STORE[("~/.grok<br/>login, sessions")]
|
|
77
|
-
BRIDGE --- LEADER
|
|
78
|
-
LEADER --- STORE
|
|
79
|
-
end
|
|
80
|
-
|
|
81
|
-
EXT == "ACP over WebSocket" ==> WS
|
|
82
|
-
WS == "stdio" ==> BRIDGE
|
|
83
|
-
WS -.- GUARD
|
|
84
|
-
LEADER -. "lent-tool calls (HTTP)" .-> MCP
|
|
85
|
-
MCP -. "_x.ai/mcp/sdk_call" .-> EXT
|
|
86
|
-
EXT -. "starts it if nothing listens" .-> GW
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
</details>
|
|
90
|
-
|
|
91
|
-
Pi drives the turn and Grok drives the callbacks, both over the Agent Client Protocol. [How it works →](docs/usage.md#components) · [Gateway guard →](docs/usage.md#gateway-guard) · [Design notes →](docs/first-class-model.md)
|
|
92
|
-
|
|
93
|
-
There is no global install and no gateway to start by hand: the recorded install runs used only `pi install npm:pi-grok-agent`, with nothing listening on that port and no `pi-grok-gateway` on `PATH` ([docs/launch-verification.md](docs/launch-verification.md), rows `G2, npm, one command` and `G2, public npm`).
|
|
94
|
-
|
|
95
|
-
The gateway keeps running after Pi exits, and every Pi process on the machine shares it. Its first start creates the shared secret `~/.pi/agent/grok-ws.secret` with mode 0600 and logs to `~/.pi/agent/grok-ws.log` (`src/launch.ts`, `src/config.ts`). To stop it, disable auto-start, or run it yourself under a service manager, see [gateway auto-start](docs/usage.md#gateway-auto-start).
|
|
96
|
-
|
|
97
|
-
Pi loads the extension at every start, for every model. To remove it, run `pi remove npm:pi-grok-agent`.
|
|
98
|
-
|
|
99
|
-
## First result
|
|
100
|
-
|
|
101
|
-
Start Pi in any project directory that has a `package.json`, and send this prompt:
|
|
11
|
+
## How it connects
|
|
102
12
|
|
|
103
13
|
```text
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
- Thinking text that contains `[grok <tool>]` lines.
|
|
111
|
-
- An answer that names the package and its scripts, with no edits.
|
|
112
|
-
- A footer cost that comes from Grok's usage report.
|
|
113
|
-
|
|
114
|
-
This is a check for your installation, not a saved transcript. These display paths have source support in `src/model.ts` and `src/model/session.ts` and unit tests in `test/model.test.ts`.
|
|
115
|
-
|
|
116
|
-
Then run `/grok debug`. It shows the gateway connection, the Grok session ID, the permission modes, token usage, and the lent Pi tools.
|
|
117
|
-
|
|
118
|
-
If the result is different, see [Troubleshooting](docs/usage.md#troubleshooting). If the model is missing from `/models`, inspect Pi's extension load error. If sign-in fails, use `/grok login`, not Pi's xAI login. Please report what you saw, as described in [Feedback](#feedback).
|
|
119
|
-
|
|
120
|
-
## What Pi adds
|
|
121
|
-
|
|
122
|
-
Grok Build already runs an agent with tools, and it can serve ACP to any client. What this package adds is the rest of Pi around that agent:
|
|
123
|
-
|
|
124
|
-
| You want to… | What happens | Basis |
|
|
125
|
-
| --- | --- | --- |
|
|
126
|
-
| Keep Grok's native tools | Grok executes the tools its own harness offers — file, shell, search, web, subagent, media. Pi records each call in the transcript and executes none of them. | `test/model.test.ts` |
|
|
127
|
-
| See Grok's work as you go | Each native call becomes thinking text plus a `grok-tool` entry, with its status and duration. | `src/model/session.ts` |
|
|
128
|
-
| Control edits from Pi | Pi gates Grok's tools before they run through a `pre_tool_use` hook. A read-only Pi session denies Grok's edits and shell; `/grok perms ask` confirms each call. | `src/model/hooks.ts`, `test/hooks.test.ts` |
|
|
129
|
-
| Decide inside Pi | Grok's permission prompts become Pi dialogs, and Grok's `ask_user_question` becomes one Pi dialog per question. | `src/model/permissions.ts`, `src/model/questions.ts`, `test/questions.test.ts` |
|
|
130
|
-
| Reuse Pi extension tools | Pi lends extension tools to Grok over MCP. Grok calls them as `pi__<name>`, Pi executes the call, and the result continues the same Grok turn. | `src/model/session.ts`, `evidence/model-probe.json` |
|
|
131
|
-
| Feed checks back to Grok | After a Grok edit, a syntax check runs on the file and a failure goes back to Grok in the same turn. A configured `stopCheck` can hold the end of a turn. | `src/model/hooks.ts`, `evidence/hooks-live.json` |
|
|
132
|
-
|
|
133
|
-
### One turn
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
<details>
|
|
138
|
-
<summary>Diagram source (mermaid)</summary>
|
|
139
|
-
|
|
140
|
-
```mermaid
|
|
141
|
-
sequenceDiagram
|
|
142
|
-
autonumber
|
|
143
|
-
participant P as Pi (extension)
|
|
144
|
-
participant G as Gateway
|
|
145
|
-
participant L as Grok leader
|
|
146
|
-
|
|
147
|
-
P->>L: initialize, authenticate (cached_token), through the gateway
|
|
148
|
-
alt first turn of this Pi session
|
|
149
|
-
P->>L: session/new: rules = Pi system prompt, client hooks, MCP server "pi"
|
|
150
|
-
else after a reconnect
|
|
151
|
-
P->>L: session/load (same Grok session)
|
|
152
|
-
end
|
|
153
|
-
P->>L: session/set_config_option: model, reasoning_effort
|
|
154
|
-
P->>L: session/prompt: only the new messages
|
|
155
|
-
|
|
156
|
-
loop while Grok works
|
|
157
|
-
L-->>P: session/update: text, thinking, tool calls
|
|
158
|
-
Note over P: Grok's own tools become thinking lines<br/>and grok-tool entries, never Pi tool calls
|
|
159
|
-
L->>G: _x.ai/hooks/run (pre_tool_use)
|
|
160
|
-
G->>P: forwarded, with an ack deadline
|
|
161
|
-
P-->>G: pi/gate-ack, then allow or deny from Pi's tool gate
|
|
162
|
-
G-->>L: answer, or deny if Pi missed the deadline
|
|
163
|
-
opt Grok asks
|
|
164
|
-
L->>P: session/request_permission or _x.ai/ask_user_question (guarded like hooks)
|
|
165
|
-
P-->>L: answer from a Pi dialog, or cancelled if Pi is gone
|
|
166
|
-
end
|
|
167
|
-
opt Grok calls a lent Pi tool
|
|
168
|
-
L->>G: MCP tools/call over HTTP
|
|
169
|
-
G->>P: _x.ai/mcp/sdk_call
|
|
170
|
-
P-->>G: result from the Pi tool
|
|
171
|
-
G-->>L: HTTP response
|
|
172
|
-
end
|
|
173
|
-
opt you press Enter mid-turn
|
|
174
|
-
P->>L: _x.ai/interject
|
|
175
|
-
end
|
|
176
|
-
end
|
|
177
|
-
L->>G: _x.ai/hooks/run (stop)
|
|
178
|
-
G->>P: forwarded
|
|
179
|
-
P-->>L: continue, or block until the stop check passes
|
|
180
|
-
L-->>P: prompt result: stop reason, usage, cost
|
|
14
|
+
┌─────────────────────┐ ┌──────────────────┐ ┌─────────────────────┐
|
|
15
|
+
│ PI — drives turn │ │ GATEWAY │ │ GROK BUILD — works │
|
|
16
|
+
│ transcript, gates, │ ACP │ one per machine │ stdio │ own tools, agents, │
|
|
17
|
+
│ dialogs │ over WS │ 127.0.0.1:2419 │ │ own history │
|
|
18
|
+
│ grok provider ext │◄───────►│ guard + MCP │◄───────►│ ~/.grok login │
|
|
19
|
+
└─────────────────────┘ └──────────────────┘ └─────────────────────┘
|
|
181
20
|
```
|
|
182
21
|
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
### Gates, checks, and lent tools
|
|
22
|
+
Pi drives the session using [Agent Client Protocol](https://agentclientprotocol.com) over WebSockets. Grok returns streaming responses, thinking blocks, as well as image and video requests. All of Grok's tool requests are routed back to Pi through callbacks over an MCP loopback. The first Grok turn auto-starts the local gateway (`127.0.0.1:2419` by default) ; every Pi process on the machine attaches to it. Details: [docs/architecture-diagram.md](docs/architecture-diagram.md) · [docs/usage.md](docs/usage.md).
|
|
186
23
|
|
|
187
|
-
|
|
188
|
-
- Gate precedence is fixed: a `denyGrokTools` entry always wins, an explicit `allowGrokTools` entry then allows — including past the read-only mirror — and only then does the capability mirror apply. By default, a Pi session without `edit` or `write` denies Grok's edit tools, and a session without `bash` denies Grok's shell (`capabilityGate` in `src/model/hooks.ts`).
|
|
189
|
-
- `/grok perms read-only`, `ask`, `auto`, and `yolo` change Pi's gate. Grok's own permission prompts are a separate layer ([details](docs/usage.md#grok-permission-prompts)).
|
|
190
|
-
- The default lent-tool policy is `extensions`, which excludes Pi's core tools — `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls` (`PI_CORE_TOOLS` in `src/config.ts`).
|
|
191
|
-
- The built-in post-edit syntax check covers TypeScript, JavaScript, Python, JSON, and Rust, chosen by file extension; anything else needs a configured `postEditCheck` (`BUILTIN_CHECKS` in `src/model/hooks.ts`).
|
|
24
|
+
## Function
|
|
192
25
|
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
- Pi's
|
|
196
|
-
-
|
|
197
|
-
- Grok plan mode, `/goal`, and `/compact` are available through `/grok plan`, `/grok goal`, and `/grok compact`. Send a normal prompt first so a Grok session exists ([commands](docs/usage.md#slash-command-grok)).
|
|
198
|
-
- After a switch from `grok/*` to another model in the same Pi session, mid-turn Enter goes to that model. The stored Grok session is used again when you switch back (`test/extension.test.ts`).
|
|
26
|
+
- **Pi sets permissions and boundaries.** Read-only, ask, auto, and YOLO permission modes are supported.
|
|
27
|
+
- **Pi makes decisions.** Grok's tool call requests, turn order, user_ask_question prompts are delegated to Pi.
|
|
28
|
+
- **Grok can use Pi's extension tools** Lent over MCP as `pi__<name>`, with the result continuing the same Grok turn.
|
|
29
|
+
- **Grok keeps all of his tools and extensions.** My own observations have been that Grok performs better with his native toolset, so this project's purpose is to keep his tools without buying the shed.
|
|
199
30
|
|
|
200
31
|
## Models
|
|
201
32
|
|
|
@@ -204,111 +35,32 @@ sequenceDiagram
|
|
|
204
35
|
| `grok/grok-4.7` | Grok 4.7 | low, medium, high, xhigh | 500,000 tokens |
|
|
205
36
|
| `grok/grok-4.7-build-fast` | Grok 4.7 Build Fast | low, medium, high, xhigh | 500,000 tokens |
|
|
206
37
|
| `grok/grok-4.6` | Grok 4.6 | low, medium, high, xhigh | 500,000 tokens |
|
|
207
|
-
| `grok/grok-4.5` | Grok 4.5 | low, medium, high | 500,000 tokens |
|
|
208
|
-
|
|
209
|
-
These are the IDs the extension registers (`MODEL_IDS` in `src/model.ts`), not a claim that your account may use all of them. Which models an account has is Grok's decision: `grok models` lists them, and the free account tested here lists only `grok-4.7`. The saved probes used `grok/grok-4.7`.
|
|
38
|
+
| `grok/grok-4.5` | Grok 4.5 | low, medium, high, xhigh | 500,000 tokens |
|
|
210
39
|
|
|
211
|
-
In 0.1.0 the model picked in Pi was never sent to Grok, so every `grok/*` choice ran Grok's default. Fixed in 0.1.1: Pi sets Grok's `model` config option, and a model the account lacks fails the turn with the list of available models instead of quietly running another one.
|
|
212
40
|
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
## Generated images and video
|
|
216
|
-
|
|
217
|
-
When a Grok tool result has the type `ImageGen`, `ImageEdit`, `ImageToVideo`, `ReferenceToVideo`, or `VideoGen`, Pi copies the file to `.pi/grok-images/` in the Pi working directory. That directory gets a `.gitignore` that ignores everything in it. If the copy fails or copying is off, the entry keeps Grok's original path (`copyMedia` in `src/model/session.ts`).
|
|
218
|
-
|
|
219
|
-
After the turn, Pi shows a `grok-media` message with the file path. PNG, JPEG, WebP, and GIF images also show inline when the terminal supports images: PNG shows directly, and Pi converts JPEG, WebP, and GIF to PNG with `magick` first. Without `magick`, you see only the path for those formats. Video files show as a path only; Pi does not play video.
|
|
220
|
-
|
|
221
|
-
Live probes cover `image_gen` only ([evidence/image-probe.json](evidence/image-probe.json)). The image-edit and video result types are recognized in code but not yet probed with a live Grok run. The media message is for display only: the provider removes it from the prompt, so Grok does not receive its own image back.
|
|
222
|
-
|
|
223
|
-
Images that you attach in Pi go to Grok as a temporary file under `pi-grok-images` in the system temp directory, written with mode 0600 (`src/model/provider.ts`). Grok reads the file with its own tools. The path route is the one that works: the probe also sent an ACP image block directly, and Grok did not see it.
|
|
224
|
-
|
|
225
|
-
## Limitations
|
|
226
|
-
|
|
227
|
-
- The auto-started gateway runs until you stop it or log out. With auto-start off, the gateway must run before the first Grok turn; until it has created its secret file, Grok turns fail with a message that names the file and the command.
|
|
228
|
-
- Run one gateway for each port and leader socket. A second default launch exits with `EADDRINUSE` and leaves the running gateway and its leader alone. [Run a separate gateway](docs/usage.md#run-a-second-isolated-gateway) for a demo or a test.
|
|
229
|
-
- Grok's native tool calls are not Pi tool calls. Pi records them as thinking text and `grok-tool` entries, and no model receives those entries.
|
|
230
|
-
- Pi compaction and Grok compaction are separate. Pi sends only the new messages of each turn, and only a new Grok session also receives the earlier Pi transcript as text, cut to the last 60,000 characters. Pi's `/compact` does not compact Grok's history; use `/grok compact`.
|
|
231
|
-
- Grok reads the lent Pi tool list once for each Grok session. A changed tool set needs a new Pi session.
|
|
232
|
-
- A gateway restart loses the turn in progress. The next turn reconnects and loads the same Grok session. No saved probe covers that restart, so live recovery is unverified ([docs/launch-verification.md](docs/launch-verification.md) lists reconnect as not run).
|
|
233
|
-
- Hashline edits (`hashline_read`, `hashline_edit`, `hashline_grep`) occur only when `~/.grok/config.toml` sets `[toolset] file_toolset = "hashline"`. Otherwise Grok uses tools such as `read_file` and `search_replace`. That switch is Grok's own configuration; this repository does not test it, though `evidence/hooks-probe.json` does show hashline calls.
|
|
234
|
-
- The provider does not call Pi's `onPayload` and `onResponse` stream hooks.
|
|
235
|
-
- Cost per token is zero in the model metadata. The per-turn cost comes from Grok's report, converted at 1e9 ticks per US dollar. That ratio is inferred by cross-check against SuperGrok rates and is not documented by Grok (`src/model/session.ts`). Without a usage report, usage and cost read as zero — that is not evidence of free usage.
|
|
41
|
+
Model availability in Pi is determined by your [account access](https://grok.com).
|
|
236
42
|
|
|
237
43
|
## Safety
|
|
238
44
|
|
|
239
|
-
-
|
|
240
|
-
- The gateway listens on loopback only
|
|
241
|
-
- `/grok perms yolo`, `grokMode: "yolo"` or `"auto"`, and `headlessPermissions: "allow"` each remove a different check. Use them only in a workspace you can lose. [usage.md](docs/usage.md#grok-permission-prompts) explains how they differ.
|
|
242
|
-
- Headless use does not imply approval. By default, headless Pi cancels Grok's permission prompts and returns a cancelled answer to questions (`src/model/permissions.ts`, `src/model/questions.ts`).
|
|
243
|
-
- Hook-handler errors fail open: a throwing handler continues the turn (`src/model/session.ts`). On timeout the gateway guard is stricter and differs by tier — it denies an unanswered pre-tool gate and rejects an unanswered permission prompt, but continues post-tool and stop hooks past their deadlines (`scripts/server.ts`). These are not equivalent guarantees.
|
|
244
|
-
- Pi sends its system prompt to Grok as session rules, plus user messages and, for a new Grok session, the earlier Pi transcript.
|
|
245
|
-
- `postEditCheck` and `stopCheck` run as shell commands (`bash -lc`) in the working directory. Treat those settings as executable code.
|
|
246
|
-
|
|
247
|
-
Files and network endpoints are listed in [docs/usage.md](docs/usage.md#files-and-network).
|
|
248
|
-
|
|
249
|
-
## What the saved probes establish
|
|
45
|
+
- This package connects the Grok Build agent over ACP, not the xAI chat-completions API. The ACP protocol does not provide complete visibility or control of an agent, and not all functions or extensions of Grok Build have been tested for safety in this configuration. The tool gates are not an operating-system sandbox: Grok runs with your user's permissions.
|
|
46
|
+
- The gateway listens on loopback only, requires a bearer secret, and never starts Grok with `--always-approve`. Headless use does not imply approval: by default, headless Pi cancels Grok's permission prompts. The `postEditCheck` and `stopCheck` settings run as shell commands — treat them as executable code.
|
|
250
47
|
|
|
251
|
-
|
|
48
|
+
## Notes
|
|
252
49
|
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
| Native execution | Grok read a token and wrote a file. Pi executed zero tools. This run used `headlessPermissions: "allow"`. | [model-live-gateway-extensions.json](evidence/model-live-gateway-extensions.json) |
|
|
256
|
-
| Pi controls | Read-only denial, post-edit repair, and a stop check passed. | [hooks-live.json](evidence/hooks-live.json) |
|
|
257
|
-
| Lent tools | Grok called a Pi-only tool and answered with the token it returned. | [model-probe.json](evidence/model-probe.json) |
|
|
258
|
-
| Gateway guard | No acknowledgment denied a write. Disconnect prevented a write. An acknowledged dialog accepted a later answer. | [gateway-guard-probe.json](evidence/gateway-guard-probe.json) |
|
|
259
|
-
| MCP gate | A tool marked read-only reached its server. An unmarked tool was denied. | [mcp-gate-probe.json](evidence/mcp-gate-probe.json) |
|
|
260
|
-
| Questions | The answer from a Pi dialog reached Grok. | [question-probe.json](evidence/question-probe.json) |
|
|
261
|
-
| Images | `image_gen` produced a JPEG. An attached image worked by file path, and did not work as an ACP image block. | [image-probe.json](evidence/image-probe.json) |
|
|
262
|
-
|
|
263
|
-
One caveat worth stating plainly: [hooks-probe.json](evidence/hooks-probe.json) records injected `additionalContext` and reports that it was not reflected in the answer. Context delivery alone does not prove that Grok follows it.
|
|
264
|
-
|
|
265
|
-
Live steering, restart recovery, image editing, and video generation remain unverified here. The saved results do not establish those capabilities.
|
|
50
|
+
- Not compatible with API key access. A Grok account is required, any membership tier. If your OAuth token expires you can '/login' from either Grok Build or Pi with '/grok login' to renew credentials.
|
|
51
|
+
- Token read, token write, cache read and cache hit % displayed in Pi are taken from Grok Build. Pi may occasionally report inaccurate data during long multistep tool calls, but will correct onn the next turn.
|
|
266
52
|
|
|
267
53
|
## Documentation
|
|
268
54
|
|
|
269
|
-
- [docs/usage.md](docs/usage.md) — settings, lent tools, permissions, the gateway guard, hooks, `/grok` commands,
|
|
270
|
-
- [docs/
|
|
271
|
-
- [docs/
|
|
272
|
-
- [docs/launch-verification.md](docs/launch-verification.md) —
|
|
273
|
-
- [AGENTS.md](AGENTS.md) — the source map, invariants, test commands, and the documentation-claim rule for changes to this repository.
|
|
274
|
-
|
|
275
|
-
On npmjs.com, relative links like these are rewritten to the matching file on GitHub, so they resolve on both pages. In an installed `node_modules` copy only `README.md`, `LICENSE`, `docs/usage.md`, and `docs/first-class-model.md` are present.
|
|
276
|
-
|
|
277
|
-
## Checks
|
|
278
|
-
|
|
279
|
-
These commands run from a clone of the repository, not from the installed package:
|
|
280
|
-
|
|
281
|
-
```sh
|
|
282
|
-
npm install # development dependencies, including TypeScript
|
|
283
|
-
npm run check # tsc --noEmit
|
|
284
|
-
npm test # unit tests plus gateway tests against a fake grok binary, no Grok calls
|
|
285
|
-
```
|
|
286
|
-
|
|
287
|
-
`test/gateway.test.ts` starts the real gateway with `test/fixtures/fake-grok.ts` as the Grok binary, in a scratch `HOME`. It checks leader ownership at startup and shutdown, and the guard's answers on Pi's wire: one answer per request, the deadline for each tier, and fail-closed on disconnect. Nothing in `npm test` contacts Grok.
|
|
288
|
-
|
|
289
|
-
The rest of the unit tests cover the turn split around a lent tool call, abort and resend, prompt tail selection, display-only messages, usage mapping, tool classification and gates, `/grok perms` modes, guard tier validation, question dialogs, `/grok login` output parsing, steering against a mocked Grok, the steer handler across a model switch, `/grok` command timeout, and media copies.
|
|
290
|
-
|
|
291
|
-
Before packaging, run `npm pack --dry-run`: the `files` list in `package.json` decides the tarball. The live probes in `scripts/` use your Grok login, spend Grok usage, and write to `evidence/`, which you must create first. Run them only intentionally — see [live probes](docs/usage.md#live-probes). `scripts/reconnect-probe.ts` hardcodes the default port and stops that gateway, so it never runs isolated.
|
|
292
|
-
|
|
293
|
-
## For coding agents
|
|
294
|
-
|
|
295
|
-
To evaluate or set up this package, use [Requirements](#requirements), [Quick start](#quick-start), and the [first-result check](#first-result). The [reference](docs/usage.md) lists exact settings and commands.
|
|
296
|
-
|
|
297
|
-
Select a model by ID when you drive Pi non-interactively; the IDs are in [Models](#models). Headless use needs attention: the default policy cancels Grok permission prompts, and questions receive a cancelled answer. Read [headless permission behavior](docs/usage.md#grok-permission-prompts) before unattended use. Do not assume automatic approval.
|
|
298
|
-
|
|
299
|
-
For changes to this repository, read [AGENTS.md](AGENTS.md). It contains the source map, the invariants, and the rule that every documentation claim points to source, a unit test, or a probe result.
|
|
55
|
+
- [docs/usage.md](docs/usage.md) — settings, lent tools, permissions, the gateway guard, hooks, `/grok` commands, troubleshooting
|
|
56
|
+
- [docs/architecture-diagram.md](docs/architecture-diagram.md) — the diagram in mermaid and ASCII
|
|
57
|
+
- [docs/first-class-model.md](docs/first-class-model.md) — design and turn mapping
|
|
58
|
+
- [docs/launch-verification.md](docs/launch-verification.md) — recorded live runs behind the verified claims
|
|
300
59
|
|
|
301
60
|
## Feedback
|
|
302
61
|
|
|
303
|
-
[
|
|
304
|
-
|
|
305
|
-
- the output of `node --version`, `pi --version`, and `grok --version`;
|
|
306
|
-
- the model ID, the prompt, and the last setup step that succeeded;
|
|
307
|
-
- what you expected and what you saw;
|
|
308
|
-
- a redacted excerpt of `/grok debug`, if you have one.
|
|
309
|
-
|
|
310
|
-
Before you post, remove secrets, tokens, session IDs, and private paths from all output. Do not attach raw logs or session files. Post a short excerpt that you have read, preferably from a synthetic demo project.
|
|
62
|
+
- [Open an issue](https://github.com/JangMan-J/pi-grok-agent/issues) with the output of `node --version`, `pi --version`, and `grok --version`, the model ID, and a short redacted excerpt of `/grok debug`.
|
|
311
63
|
|
|
312
64
|
## License
|
|
313
65
|
|
|
314
|
-
[Apache License 2.0](LICENSE).
|
|
66
|
+
- [Apache License 2.0](LICENSE).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-grok-agent",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
4
4
|
"license": "Apache-2.0",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"description": "Pi model provider for Grok Build: Grok keeps its native harness and tools while Pi drives the session over a local WebSocket ACP gateway",
|