@gaia-ai/addon-grok 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 keytec GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# @gaia-ai/addon-grok
+
+GAIA agent plugin for xAI Grok Build, with a real session footprint.
+
+Part of the GAIA CLI. Install the meta package `@gaia-ai/gaia` to get the `gaia` CLI with all addons. Source: https://git.key-tec.de/keytec/gaia (gaia-cli/).

package/dist/src/footprint.d.ts

@@ -0,0 +1,2 @@
+import { type AgentFootprint } from '@gaia-ai/conductor/contract';
+export declare function parseGrokTranscript(log: string): AgentFootprint;

package/dist/src/footprint.js

@@ -0,0 +1,120 @@
+import { emptyAgentFootprint, } from '@gaia-ai/conductor/contract';
+function object(value) {
+    return typeof value === 'object' && value !== null
+        ? value
+        : undefined;
+}
+function count(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0
+        ? value
+        : 0;
+}
+function optionalCount(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0
+        ? value
+        : undefined;
+}
+function words(text) {
+    const trimmed = text.trim();
+    return trimmed === '' ? 0 : trimmed.split(/\s+/).length;
+}
+function jsonLines(value) {
+    if (typeof value !== 'string')
+        return [];
+    const rows = [];
+    for (const raw of value.split('\n')) {
+        if (raw.trim() === '')
+            continue;
+        try {
+            const row = object(JSON.parse(raw));
+            if (row)
+                rows.push(row);
+        }
+        catch {
+            // Grok may leave a partial final JSONL line while finalization races it.
+        }
+    }
+    return rows;
+}
+function timestampMs(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return value < 1_000_000_000_000 ? value * 1000 : value;
+    }
+    if (typeof value === 'string') {
+        const parsed = Date.parse(value);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
+export function parseGrokTranscript(log) {
+    const footprint = emptyAgentFootprint();
+    let bundle;
+    try {
+        bundle = object(JSON.parse(log)) ?? {};
+    }
+    catch {
+        return footprint;
+    }
+    const summary = object(bundle.summary);
+    const signals = object(bundle.signals);
+    const signalAgentTurns = optionalCount(signals?.assistantMessageCount);
+    const signalToolCalls = optionalCount(signals?.toolCallCount);
+    const signalUserPrompts = optionalCount(signals?.userMessageCount);
+    if (typeof summary?.current_model_id === 'string') {
+        footprint.model = summary.current_model_id;
+    }
+    let chatAgentTurns = 0;
+    let chatToolCalls = 0;
+    let chatUserPrompts = 0;
+    for (const row of jsonLines(bundle.chatHistory)) {
+        if (row.type === 'assistant') {
+            chatAgentTurns += 1;
+            if (Array.isArray(row.tool_calls)) {
+                chatToolCalls += row.tool_calls.length;
+            }
+        }
+        if (row.type === 'user' && typeof row.prompt_index === 'number') {
+            chatUserPrompts += 1;
+            if (Array.isArray(row.content)) {
+                for (const rawPart of row.content) {
+                    const part = object(rawPart);
+                    if (part?.type === 'text' && typeof part.text === 'string') {
+                        footprint.user_prompt_words += words(part.text);
+                    }
+                }
+            }
+        }
+    }
+    footprint.agent_turns = signalAgentTurns ?? chatAgentTurns;
+    footprint.tool_calls = signalToolCalls ?? chatToolCalls;
+    footprint.user_prompts = signalUserPrompts ?? chatUserPrompts;
+    let min = Number.POSITIVE_INFINITY;
+    let max = Number.NEGATIVE_INFINITY;
+    let completedTokens = 0;
+    let completedTotals = 0;
+    let latestTotalTokens = 0;
+    for (const row of jsonLines(bundle.updates)) {
+        const timestamp = timestampMs(row.timestamp);
+        if (timestamp !== undefined) {
+            min = Math.min(min, timestamp);
+            max = Math.max(max, timestamp);
+        }
+        const params = object(row.params);
+        const meta = object(params?._meta);
+        latestTotalTokens = Math.max(latestTotalTokens, count(meta?.totalTokens));
+        const update = object(params?.update);
+        if (update?.sessionUpdate === 'turn_completed') {
+            const usage = object(update.usage);
+            const totalTokens = optionalCount(usage?.totalTokens);
+            if (totalTokens !== undefined) {
+                completedTokens += totalTokens;
+                completedTotals += 1;
+            }
+        }
+    }
+    footprint.tokens = completedTotals > 0 ? completedTokens : latestTotalTokens;
+    if (Number.isFinite(min) && Number.isFinite(max) && max > min) {
+        footprint.duration_s = Math.floor((max - min) / 1000);
+    }
+    return footprint;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,19 @@
+import type { AgentFootprint, AgentPlugin, GaiaAgent } from '@gaia-ai/conductor/contract';
+export { parseGrokTranscript } from './footprint.js';
+export type GrokReasoningEffort = 'high' | 'medium' | 'low';
+export interface GrokAgentOptions {
+    model: string;
+    reasoningEffort?: GrokReasoningEffort;
+}
+export declare function encodeGrokSessionCwd(cwd: string): string;
+export declare class GrokAgent implements GaiaAgent {
+    private readonly options;
+    private readonly home;
+    readonly id = "grok";
+    constructor(options?: GrokAgentOptions, home?: string);
+    launchCommand(prompt: string): string;
+    getRunLog(worktreePath: string): Promise<string>;
+    parseFootprint(log: string): AgentFootprint;
+}
+export declare function grokAgent(options?: GrokAgentOptions): AgentPlugin;
+export default grokAgent;

package/dist/src/index.js

@@ -0,0 +1,119 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { shellQuote } from '@gaia-ai/core';
+import { parseGrokTranscript } from './footprint.js';
+export { parseGrokTranscript } from './footprint.js';
+const DEFAULT_OPTIONS = { model: 'grok-4.5' };
+export function encodeGrokSessionCwd(cwd) {
+    return encodeURIComponent(cwd);
+}
+async function readText(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+async function readJson(path) {
+    try {
+        const value = JSON.parse(await readFile(path, 'utf8'));
+        return typeof value === 'object' && value !== null
+            ? value
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export class GrokAgent {
+    options;
+    home;
+    id = 'grok';
+    constructor(options = DEFAULT_OPTIONS, home = homedir()) {
+        this.options = options;
+        this.home = home;
+    }
+    launchCommand(prompt) {
+        const parts = ['grok'];
+        if (prompt !== '') {
+            // Positional — the interactive form Grok Build documents
+            // (`grok "fix the bug"`). NOT `-p/--single`: that prints one answer to
+            // stdout and exits, so the agent would drop the herdr tab it is
+            // dispatched into instead of holding a session there.
+            parts.push(shellQuote(prompt));
+        }
+        parts.push('--permission-mode', 'bypassPermissions', '-m', this.options.model);
+        if (this.options.reasoningEffort) {
+            parts.push('--reasoning-effort', this.options.reasoningEffort);
+        }
+        return parts.join(' ');
+    }
+    async getRunLog(worktreePath) {
+        const root = join(this.home, '.grok', 'sessions', encodeGrokSessionCwd(worktreePath));
+        let names;
+        try {
+            names = await readdir(root);
+        }
+        catch {
+            return '';
+        }
+        let latest;
+        for (const name of names) {
+            const dir = join(root, name);
+            const summary = await readJson(join(dir, 'summary.json'));
+            if (!summary) {
+                continue;
+            }
+            const info = summary?.info;
+            if (typeof info !== 'object' ||
+                info === null ||
+                info.cwd !== worktreePath) {
+                continue;
+            }
+            let updated = typeof summary?.updated_at === 'string'
+                ? Date.parse(summary.updated_at)
+                : Number.NaN;
+            if (!Number.isFinite(updated)) {
+                try {
+                    updated = (await stat(dir)).mtimeMs;
+                }
+                catch {
+                    continue;
+                }
+            }
+            if (!latest || updated > latest.updated) {
+                latest = { dir, summary, updated };
+            }
+        }
+        if (!latest)
+            return '';
+        const [signals, chatHistory, updates] = await Promise.all([
+            readJson(join(latest.dir, 'signals.json')),
+            readText(join(latest.dir, 'chat_history.jsonl')),
+            readText(join(latest.dir, 'updates.jsonl')),
+        ]);
+        return JSON.stringify({
+            summary: latest.summary,
+            signals: signals ?? {},
+            chatHistory,
+            updates,
+        });
+    }
+    parseFootprint(log) {
+        return parseGrokTranscript(log);
+    }
+}
+export function grokAgent(options = DEFAULT_OPTIONS) {
+    const agent = new GrokAgent(options);
+    return {
+        kind: 'agent',
+        id: 'grok',
+        requiredModules: [],
+        async createAgent() {
+            return agent;
+        },
+    };
+}
+export default grokAgent;

package/dist/src/preset.d.ts

@@ -0,0 +1,2 @@
+import type { Preset } from '@gaia-ai/conductor/contract';
+export declare const agents: Preset['agents'];

package/dist/src/preset.js

@@ -0,0 +1,5 @@
+import grokAgent from './index.js';
+export const agents = (acc, opts) => [
+    ...acc,
+    { agent: grokAgent(opts) },
+];

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@gaia-ai/addon-grok",
+  "version": "0.9.0",
+  "description": "GAIA agent plugin for xAI Grok Build, with a real session footprint.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": "./dist/src/index.js",
+    "./preset": "./dist/src/preset.js"
+  },
+  "files": [
+    "dist/src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.key-tec.de/keytec/gaia.git",
+    "directory": "gaia-cli/addons/grok"
+  },
+  "peerDependencies": {
+    "@gaia-ai/conductor": "^0.9.0",
+    "@gaia-ai/core": "^0.9.0"
+  }
+}