grok-dev 1.0.0-rc2 → 1.0.0-rc4

package/.cursor/rules/project-overview.mdc

@@ -37,7 +37,7 @@ src/
 ├── utils/
 │   ├── settings.ts   # User and project settings
 │   ├── git-root.ts   # Resolve git repository root for AGENTS.md discovery
-│   └── instructions.ts # AGENTS.md (ecosystem) + .grok/GROK.md
+│   └── instructions.ts # AGENTS.md (ecosystem) custom instructions
 └── types/
     └── index.ts      # Shared TypeScript types
 ```
@@ -48,7 +48,7 @@ src/
 - **Bash-only tools**: The agent uses bash for everything (file editing, searching, git, builds, etc.).
 - **X Search & Web Search**: Integrated via the xAI Responses API for real-time information.
 - **Settings hierarchy**: Environment variables → User-level (`~/.grok/user-settings.json`) → Project-level (`.grok/settings.json`).
-- **Custom instructions**: `~/.grok/AGENTS.md`, then `AGENTS.override.md` / `AGENTS.md` per directory from git root through the workspace cwd (Codex-style merge), then `.grok/GROK.md` or `~/.grok/GROK.md` last.
+- **Custom instructions**: `~/.grok/AGENTS.md`, then `AGENTS.override.md` / `AGENTS.md` per directory from git root through the workspace cwd (Codex-style merge).
 - **ESM only**: The project uses `"type": "module"` — all imports use `.js` extensions for compiled output.
 
 ## Latest Grok Models

package/.grok/settings.json

@@ -1,5 +1,5 @@
 {
-  "model": "grok-code-fast-1",
+  "model": "grok-4.20-multi-agent-0309",
   "mcpServers": {
     "github": {
       "name": "GitHub",

package/README.md

@@ -46,6 +46,7 @@ grok -d /path/to/your/repo
 grok --prompt "run the test suite and summarize failures"
 grok -p "show me package.json" --directory /path/to/project
 grok --prompt "refactor X" --max-tool-rounds 30
+grok --prompt "summarize the repo state" --format json
 ```
 
 **Continue a saved session:**
@@ -57,6 +58,16 @@ grok -s <session-id>
 
 Works in interactive mode too—same flag.
 
+**Structured headless output:**
+
+```bash
+grok --prompt "summarize the repo state" --format json
+```
+
+`--format json` emits a newline-delimited JSON event stream instead of the
+default human-readable text output. Events are semantic, step-level records such
+as `step_start`, `text`, `tool_use`, `step_finish`, and `error`.
+
 **List Grok models and pricing hints:**
 
 ```bash
@@ -75,9 +86,10 @@ grok fix the flaky test in src/foo.test.ts
 
 | Thing | What it means |
 |--------|----------------|
-| **Grok-native** | Defaults tuned for Grok; models like **`grok-code-fast-1`**, **`grok-4-1-fast`**, flagship and fast variants—run `grok models` for the full menu. |
+| **Grok-native** | Defaults tuned for Grok; models like **`grok-code-fast-1`**, **`grok-4-1-fast-reasoning`**, **`grok-4.20-multi-agent-0309`**, plus flagship and fast variants—run `grok models` for the full menu. |
 | **X + web search** | **`search_x`** and **`search_web`** tools—live posts and docs without pretending the internet stopped in 2023. |
 | **Sub-agents (default behavior)** | Foreground **`task`** delegation (e.g. explore vs general) plus background **`delegate`** for read-only deep dives—parallelize like you mean it. |
+| **Custom sub-agents** | Define named agents with **`subAgents`** in **`~/.grok/user-settings.json`** and manage them from the TUI with **`/agents`**. |
 | **Remote control** | Pair **Telegram** from the TUI (`/remote-control` → Telegram): DM your bot, **`/pair`**, approve the code in-terminal. Keep the CLI running while you ping it from your phone. |
 | **No “mystery meat” UI** | OpenTUI React terminal UI—fast, keyboard-driven, not whatever glitchy thing you’re thinking of. |
 | **Skills** | Agent Skills under **`.agents/skills/<name>/SKILL.md`** (project) or **`~/.agents/skills/`** (user). Use **`/skills`** in the TUI to list what’s installed. |
@@ -118,6 +130,22 @@ grok -k your_key_here
 { "apiKey": "your_key_here" }
 ```
 
+Optional **`subAgents`** — custom foreground sub-agents. Each entry needs **`name`**, **`model`**, and **`instruction`**:
+
+```json
+{
+  "subAgents": [
+    {
+      "name": "security-review",
+      "model": "grok-code-fast-1",
+      "instruction": "Prioritize security implications and suggest concrete fixes."
+    }
+  ]
+}
+```
+
+Names cannot be `general` or `explore` because those are reserved for the built-in sub-agents.
+
 Optional: **`GROK_BASE_URL`** (default `https://api.x.ai/v1`), **`GROK_MODEL`**, **`GROK_MAX_TOKENS`**.
 
 ---
@@ -136,13 +164,12 @@ Treat the bot token like a password.
 ## Instructions & project brain
 
 - **`AGENTS.md`** — merged from git root down to your cwd (Codex-style; see repo docs). **`AGENTS.override.md`** wins per directory when present.
-- **`.grok/GROK.md`** or **`~/.grok/GROK.md`** — Grok-only rules, applied last.
 
 ---
 
-## MCP & project settings
+## Project settings
 
-Project file: **`.grok/settings.json`** — e.g. current model, **`mcpServers`** for stdio/http/sse MCP servers. Manage interactively with **`/mcps`** in the TUI.
+Project file: **`.grok/settings.json`** — e.g. the current model for this project.
 
 ---
 

package/dist/agent/agent.d.ts

@@ -1,8 +1,44 @@
-import type { AgentMode, ChatEntry, SessionInfo, SessionSnapshot, StreamChunk, SubagentStatus, TaskRequest, ToolResult } from "../types/index";
+import type { AgentMode, ChatEntry, SessionInfo, SessionSnapshot, StreamChunk, SubagentStatus, TaskRequest, ToolCall, ToolResult } from "../types/index";
 interface AgentOptions {
     persistSession?: boolean;
     session?: string;
 }
+type ProcessMessageFinishReason = "stop" | "length" | "content-filter" | "tool-calls" | "error" | "other";
+export interface ProcessMessageUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+}
+export interface ProcessMessageStepStart {
+    stepNumber: number;
+    timestamp: number;
+}
+export interface ProcessMessageStepFinish {
+    stepNumber: number;
+    timestamp: number;
+    finishReason: ProcessMessageFinishReason;
+    usage: ProcessMessageUsage;
+}
+export interface ProcessMessageToolStart {
+    toolCall: ToolCall;
+    timestamp: number;
+}
+export interface ProcessMessageToolFinish {
+    toolCall: ToolCall;
+    toolResult: ToolResult;
+    timestamp: number;
+}
+export interface ProcessMessageError {
+    message: string;
+    timestamp: number;
+}
+export interface ProcessMessageObserver {
+    onStepStart?(info: ProcessMessageStepStart): void;
+    onStepFinish?(info: ProcessMessageStepFinish): void;
+    onToolStart?(info: ProcessMessageToolStart): void;
+    onToolFinish?(info: ProcessMessageToolFinish): void;
+    onError?(info: ProcessMessageError): void;
+}
 export declare class Agent {
     private provider;
     private apiKey;
@@ -13,7 +49,7 @@ export declare class Agent {
     private workspace;
     private session;
     private messages;
-    private recordedTokens;
+    private messageSeqs;
     private abortController;
     private maxToolRounds;
     private mode;
@@ -56,7 +92,10 @@ export declare class Agent {
     private runDelegation;
     private readDelegation;
     private listDelegations;
-    processMessage(userMessage: string): AsyncGenerator<StreamChunk, void, unknown>;
+    private getCompactionSettings;
+    private compactForContext;
+    private appendCompletedTurn;
+    processMessage(userMessage: string, observer?: ProcessMessageObserver): AsyncGenerator<StreamChunk, void, unknown>;
     private requireProvider;
 }
 export {};