talking-stick 0.4.8 → 0.4.10

package/dist/identity.js

@@ -1,6 +1,8 @@
 import crypto from "node:crypto";
 import os from "node:os";
 import path from "node:path";
+import { findGrokSessionRecord, resolveGrokSessionLogPath } from "./grok-session-store.js";
+import { resolveContextPath } from "./path-resolution.js";
 import { createSystemProcessInspector } from "./process-utils.js";
 const HARNESS_CLI_EXPORT_ENV = "TT_HARNESS_EXPORT";
 const HARNESS_CLI_AGENT_ID_ENV = "TT_HARNESS_AGENT_ID";
@@ -41,7 +43,11 @@ export function deriveMcpHarnessIdentity(options = {}) {
     const signal = detectHarnessSignal(env);
     if (signal) {
         const processRef = resolveSignalProcessRef(signal, parentPid, parentInspection, inspector);
-        const sessionId = resolveHarnessSessionId(signal, env, processRef.pid, processRef.inspection, username, hostId, inspector);
+        const sessionId = resolveHarnessSessionId(signal, env, processRef.pid, processRef.inspection, username, hostId, inspector, {
+            contextPath: options.contextPath,
+            grokSessionLogPath: options.grokSessionLogPath,
+            now: options.now
+        });
         const harnessProcess = resolveHarnessProcessRef(signal, processRef, inspector);
         const agentId = options.agentId ?? harnessAgentId(signal.harness, sessionId, hostId, username);
         return {
@@ -100,7 +106,9 @@ export function deriveHarnessCliIdentity(options = {}) {
     }
     let signal = detectHarnessSignal(env);
     if (!signal && !isHarnessCliExportEnabled(env)) {
-        return null;
+        signal = detectGrokViaAncestry(parentPid, parentInspection, inspector);
+        if (!signal)
+            return null;
     }
     if (!signal) {
         signal = detectHarnessViaAncestry(parentPid, inspector);
@@ -109,7 +117,11 @@ export function deriveHarnessCliIdentity(options = {}) {
         return null;
     const processRef = resolveSignalProcessRef(signal, parentPid, parentInspection, inspector);
     const username = options.username ?? safeUsername();
-    const sessionId = resolveHarnessSessionId(signal, env, processRef.pid, processRef.inspection, username, hostId, inspector);
+    const sessionId = resolveHarnessSessionId(signal, env, processRef.pid, processRef.inspection, username, hostId, inspector, {
+        contextPath: options.contextPath,
+        grokSessionLogPath: options.grokSessionLogPath,
+        now: options.now
+    });
     const agentId = options.agentId ?? harnessAgentId(signal.harness, sessionId, hostId, username);
     const harnessProcess = resolveHarnessProcessRef(signal, processRef, inspector);
     return {
@@ -136,10 +148,16 @@ function harnessAgentId(harness, sessionId, hostId, username) {
         sanitizeIdentityComponent(username)
     ])}`;
 }
-function resolveHarnessSessionId(signal, env, parentPid, parentInspection, username, hostId, inspector) {
+function resolveHarnessSessionId(signal, env, parentPid, parentInspection, username, hostId, inspector, options = {}) {
     if (signal.sessionId)
         return `harness:${signal.sessionId}`;
     const harnessRoot = findHarnessRootInAncestry(signal.harness, parentPid, parentInspection, inspector);
+    if (signal.harness === "grok") {
+        const grokSessionId = resolveGrokHookSessionId(env, harnessRoot, options);
+        if (grokSessionId) {
+            return `harness:${grokSessionId}`;
+        }
+    }
     if (harnessRoot) {
         return `pid:${harnessRoot.pid}@${harnessRoot.startTime}`;
     }
@@ -165,7 +183,7 @@ function resolveHarnessProcessRef(signal, processRef, inspector) {
 // process whose command matches the named harness. Anchoring session id to
 // that root keeps `tt` invocations stable whether they're spawned directly
 // by the harness (MCP subprocess) or through intermediate shells (CLI shell-out).
-function findHarnessRootInAncestry(harness, startPid, startInspection, inspector, maxDepth = 10) {
+export function findHarnessRootInAncestry(harness, startPid, startInspection, inspector, maxDepth = 10) {
     let result = null;
     let currentPid = startPid;
     let currentInspection = startInspection;
@@ -220,6 +238,7 @@ const HARNESS_COMMAND_MAPPING = {
     "claude-code": "claude",
     codex: "codex",
     gemini: "gemini",
+    grok: "grok",
     opencode: "opencode"
 };
 function detectHarnessViaAncestry(pid, inspector, maxDepth = 10) {
@@ -231,10 +250,13 @@ function detectHarnessViaAncestry(pid, inspector, maxDepth = 10) {
         if (!inspection)
             break;
         const label = deriveCommandLabel(inspection.command);
-        if (HARNESS_COMMAND_MAPPING[label]) {
+        const harness = HARNESS_COMMAND_MAPPING[label];
+        if (harness) {
             return {
-                harness: HARNESS_COMMAND_MAPPING[label],
-                sessionId: `pid:${inspection.pid}@${inspection.startTime}`,
+                harness,
+                sessionId: harness === "grok"
+                    ? null
+                    : `pid:${inspection.pid}@${inspection.startTime}`,
                 pidHint: null
             };
         }
@@ -267,8 +289,51 @@ function detectHarnessSignal(env) {
             pidHint: null
         };
     }
+    const cmuxHarness = resolveCmuxLaunchHarness(env);
+    if (cmuxHarness) {
+        return {
+            harness: cmuxHarness,
+            sessionId: null,
+            pidHint: null
+        };
+    }
     return null;
 }
+function detectGrokViaAncestry(parentPid, parentInspection, inspector) {
+    const grokRoot = findHarnessRootInAncestry("grok", parentPid, parentInspection, inspector, 20);
+    return grokRoot
+        ? { harness: "grok", sessionId: null, pidHint: null }
+        : null;
+}
+function resolveGrokHookSessionId(env, harnessRoot, options) {
+    const workspaceRoot = resolveGrokWorkspaceRoot(env, options.contextPath);
+    const record = findGrokSessionRecord({
+        logPath: options.grokSessionLogPath ??
+            resolveGrokSessionLogPath({ env }),
+        workspaceRoot,
+        grokPid: harnessRoot?.pid ?? null,
+        grokProcessStartedAt: harnessRoot?.startTime ?? null,
+        now: options.now
+    });
+    return record?.grok_session_id ?? null;
+}
+function resolveGrokWorkspaceRoot(env, contextPath) {
+    const explicit = nonEmpty(env.GROK_WORKSPACE_ROOT) ??
+        nonEmpty(env.CLAUDE_PROJECT_DIR);
+    if (explicit)
+        return path.resolve(explicit);
+    const candidate = contextPath ?? nonEmpty(env.PWD) ?? process.cwd();
+    try {
+        return resolveContextPath(candidate).workspace_root;
+    }
+    catch {
+        return path.resolve(candidate);
+    }
+}
+function resolveCmuxLaunchHarness(env) {
+    const launchKind = normalizeEnvValue(env.CMUX_AGENT_LAUNCH_KIND);
+    return launchKind ? HARNESS_COMMAND_MAPPING[launchKind] ?? null : null;
+}
 function resolveSignalProcessRef(signal, fallbackPid, fallbackInspection, inspector) {
     if (signal.pidHint && signal.pidHint !== fallbackPid) {
         const hintedInspection = inspector.inspect(signal.pidHint);
@@ -294,6 +359,10 @@ function parsePositiveInteger(value) {
 function nonEmpty(value) {
     return value && value.trim().length > 0 ? value : null;
 }
+function normalizeEnvValue(value) {
+    const nonBlank = nonEmpty(value);
+    return nonBlank ? nonBlank.toLowerCase() : null;
+}
 function deriveCommandLabel(command) {
     if (!command) {
         return "harness";

package/dist/index.js

@@ -5,7 +5,8 @@ export { ProtocolError, isProtocolError } from "./errors.js";
 export { deriveHarnessCliIdentity, deriveHumanCliIdentity, deriveMcpHarnessIdentity } from "./identity.js";
 export { ancestorPaths, canonicalizeContextPath, resolveContextPath, resolveWorkspaceRoot } from "./path-resolution.js";
 export { DEFAULT_MAX_INSTRUCTION_FILE_BYTES, DEFAULT_INSTRUCTIONS_MARKDOWN, editInstructions, extractHarnessInstructions, normalizeInstructionHarness, parseInstructionScope, resetInstructions, resolveInstructionHarness, resolveInstructionPaths, showInstructions } from "./instructions.js";
-export { SUPPORTED_HARNESSES, MissingHarnessError, detectHarness, parseHarnessList, planUninstall, resolveHarnessConfigDir, resolveOpencodeConfigDir, resolveOpencodeConfigPath, runAction, skipAction } from "./install.js";
+export { SUPPORTED_HARNESSES, buildGrokSessionHookConfig, DEFAULT_GROK_SESSION_HOOK_COMMAND, GROK_SESSION_HOOK_EVENTS, GROK_SESSION_HOOK_FILE, MissingHarnessError, detectHarness, parseHarnessList, planGrokSessionHookInstall, planGrokSessionHookUninstall, planUninstall, resolveGrokSessionHookPath, resolveHarnessConfigDir, resolveOpencodeConfigDir, resolveOpencodeConfigPath, runAction, skipAction } from "./install.js";
+export { DEFAULT_GROK_SESSION_RECORD_MAX_AGE_MS, appendGrokSessionRecord, findGrokSessionRecord, isGrokSessionEndEvent, readGrokSessionRecords, resolveGrokSessionLogPath } from "./grok-session-store.js";
 export { DEFAULT_SKILL_NAME, planSkillInstall, planSkillUninstall, resolveBundledSkillPath, resolveSkillTargetPath, syncInstalledSkills } from "./skill-install.js";
 export { readPackageVersion, readUpdateMigrationState, resolveUpdateMigrationStatePath, runFirstRunMcpMigration, runStaleMcpCleanup, writeUpdateMigrationState } from "./update-migration.js";
 export { createSystemProcessInspector, terminateKnownProcess } from "./process-utils.js";

package/dist/install.js

@@ -2,9 +2,17 @@ import { spawn } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-export const SUPPORTED_HARNESSES = ["claude-code", "codex", "gemini", "opencode"];
+export const SUPPORTED_HARNESSES = ["claude-code", "codex", "gemini", "grok", "opencode"];
 export const DEFAULT_SERVER_NAME = "talking-stick";
 export const DEFAULT_SERVER_COMMAND = ["tt", "mcp"];
+export const GROK_SESSION_HOOK_FILE = "talking-stick-session.json";
+export const DEFAULT_GROK_SESSION_HOOK_COMMAND = ": talking-stick-grok-session-hook; if command -v tt >/dev/null 2>&1; then tt grok-session-hook >/dev/null 2>/dev/null || true; fi";
+export const GROK_SESSION_HOOK_EVENTS = [
+    "SessionStart",
+    "UserPromptSubmit",
+    "PreToolUse",
+    "SessionEnd"
+];
 export class MissingHarnessError extends Error {
     constructor(message) {
         super(message);
@@ -96,11 +104,21 @@ export function resolveHarnessConfigDir(harness, options = {}) {
     const resolved = resolveOptions(options);
     return resolveHarnessConfigDirFromResolved(harness, resolved);
 }
+export function resolveGrokSessionHookPath(options = {}) {
+    const resolved = resolveOptions(options);
+    return path.join(resolveGrokConfigDirFromResolved(resolved), "hooks", GROK_SESSION_HOOK_FILE);
+}
 function resolveOpencodeConfigDirFromResolved(resolved) {
     const xdg = resolved.env.XDG_CONFIG_HOME?.trim();
     const base = xdg && xdg.length > 0 ? xdg : path.join(resolved.homeDir, ".config");
     return path.join(base, "opencode");
 }
+function resolveGrokConfigDirFromResolved(resolved) {
+    const grokHome = resolved.env.GROK_HOME?.trim();
+    return grokHome && grokHome.length > 0
+        ? grokHome
+        : path.join(resolved.homeDir, ".grok");
+}
 function resolveHarnessConfigDirFromResolved(harness, resolved) {
     switch (harness) {
         case "claude-code":
@@ -109,6 +127,8 @@ function resolveHarnessConfigDirFromResolved(harness, resolved) {
             return path.join(resolved.homeDir, ".codex");
         case "gemini":
             return path.join(resolved.homeDir, ".gemini");
+        case "grok":
+            return resolveGrokConfigDirFromResolved(resolved);
         case "opencode":
             return resolveOpencodeConfigDirFromResolved(resolved);
         default:
@@ -157,6 +177,8 @@ export function planUninstall(harness, options = {}) {
                 operation: "uninstall",
                 serverName: resolved.serverName
             };
+        case "grok":
+            return skipAction(harness, "legacy Talking Stick cleanup is not applicable for grok");
         case "opencode": {
             const filePath = resolveOpencodeConfigPath(options);
             const configDir = path.dirname(filePath);
@@ -189,6 +211,76 @@ export function skipAction(harness, message) {
         message
     };
 }
+export function planGrokSessionHookInstall(options = {}) {
+    const resolved = resolveOptions(options);
+    const grokConfigDir = resolveGrokConfigDirFromResolved(resolved);
+    const filePath = resolveGrokSessionHookPath(options);
+    if (resolved.skipMissing && !resolved.hooks.pathExists(grokConfigDir)) {
+        return skipAction("grok", `grok config directory not found: ${grokConfigDir}`);
+    }
+    return {
+        kind: "file-patch",
+        harness: "grok",
+        filePath,
+        description: `write Grok session hook ${filePath}`,
+        inspect: () => inspectGrokSessionHook(filePath, resolved),
+        apply: () => writeGrokSessionHook(filePath, resolved)
+    };
+}
+export function planGrokSessionHookUninstall(options = {}) {
+    const resolved = resolveOptions(options);
+    const grokConfigDir = resolveGrokConfigDirFromResolved(resolved);
+    const filePath = resolveGrokSessionHookPath(options);
+    if (resolved.skipMissing && !resolved.hooks.pathExists(grokConfigDir)) {
+        return skipAction("grok", `grok config directory not found: ${grokConfigDir}`);
+    }
+    return {
+        kind: "file-patch",
+        harness: "grok",
+        filePath,
+        description: `remove Grok session hook ${filePath}`,
+        inspect: () => resolved.hooks.readFile(filePath) === null ? "absent" : "present",
+        apply: () => removeGrokSessionHook(filePath, resolved)
+    };
+}
+export function buildGrokSessionHookConfig() {
+    const hook = {
+        type: "command",
+        command: DEFAULT_GROK_SESSION_HOOK_COMMAND,
+        timeout: 5
+    };
+    const hooks = Object.fromEntries(GROK_SESSION_HOOK_EVENTS.map((event) => [
+        event,
+        [
+            {
+                hooks: [hook]
+            }
+        ]
+    ]));
+    return JSON.stringify({ hooks }, null, 2) + "\n";
+}
+function inspectGrokSessionHook(filePath, resolved) {
+    const existing = resolved.hooks.readFile(filePath);
+    if (existing === null)
+        return "absent";
+    return existing === buildGrokSessionHookConfig() ? "present" : "different";
+}
+function writeGrokSessionHook(filePath, resolved) {
+    resolved.hooks.ensureDir(path.dirname(filePath));
+    resolved.hooks.writeFile(filePath, buildGrokSessionHookConfig());
+}
+function removeGrokSessionHook(filePath, resolved) {
+    void resolved;
+    try {
+        fs.rmSync(filePath, { force: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return;
+        }
+        throw error;
+    }
+}
 function patchOpencodeConfig(filePath, resolved, mode) {
     const existing = resolved.hooks.readFile(filePath);
     if (resolved.skipMissing) {
@@ -305,6 +397,15 @@ export function detectHarness(harness, options = {}) {
                 return { harness, detected: true, evidence: configDir };
             return { harness, detected: false, evidence: "gemini not on PATH and no config directory" };
         }
+        case "grok": {
+            const bin = resolved.hooks.which("grok");
+            if (bin)
+                return { harness, detected: true, evidence: bin };
+            const configDir = resolveHarnessConfigDirFromResolved(harness, resolved);
+            if (resolved.hooks.pathExists(configDir))
+                return { harness, detected: true, evidence: configDir };
+            return { harness, detected: false, evidence: "grok not on PATH and no config directory" };
+        }
         case "opencode": {
             const bin = resolved.hooks.which("opencode");
             if (bin)
@@ -534,6 +635,8 @@ function mcpConfigLocation(action) {
             return "Codex global config";
         case "gemini":
             return "Gemini user config";
+        case "grok":
+            return "Grok config";
         case "opencode":
             return "OpenCode config";
         default:

package/dist/instructions.js

@@ -30,6 +30,10 @@ Lean into adversarial review, convergence, precise implementation, edge-case swe
 
 Use broad context review and exploration conservatively until the project has stronger Gemini-specific dogfood. Keep handoffs concrete and do not assume responsibility that the operator assigned to another harness.
 
+## Grok
+
+Use Grok Build as a first-class local coding harness. Keep coordination safety ahead of speed, rely on the native Grok skill and session hook when installed, and keep handoffs concrete when another harness is better positioned to implement or review.
+
 ## OpenCode
 
 Use terminal-native local exploration and implementation conservatively until the project has stronger OpenCode-specific dogfood. Keep coordination safety ahead of speed.
@@ -41,6 +45,8 @@ const HARNESS_ALIASES = {
     "claude-code": "claude",
     codex: "codex",
     gemini: "gemini",
+    grok: "grok",
+    "grok-build": "grok",
     opencode: "opencode"
 };
 export function resolveInstructionPaths(options = {}) {
@@ -108,7 +114,7 @@ export function resolveInstructionHarness(explicitHarness, identity) {
 export function normalizeInstructionHarness(value) {
     const normalized = HARNESS_ALIASES[normalizeKey(value)];
     if (!normalized) {
-        throw new Error(`--harness must be one of claude, codex, gemini, opencode, all (got ${value}).`);
+        throw new Error(`--harness must be one of claude, codex, gemini, grok, opencode, all (got ${value}).`);
     }
     return normalized;
 }
@@ -208,6 +214,8 @@ function parseHarnessHeader(line) {
         return "codex";
     if (key.startsWith("gemini"))
         return "gemini";
+    if (key.startsWith("grok"))
+        return "grok";
     if (key.startsWith("opencode"))
         return "opencode";
     return null;

package/dist/path-resolution.js

@@ -1,5 +1,6 @@
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 const workspaceMarkers = [
     "CLAUDE.md",
@@ -78,8 +79,12 @@ function resolveGitRoot(canonicalContextPath) {
     }
 }
 function findNearestWorkspaceMarker(startPath) {
+    const homeMarkerBoundary = resolveHomeMarkerBoundary(startPath);
     let current = startPath;
     while (true) {
+        if (homeMarkerBoundary && samePath(current, homeMarkerBoundary)) {
+            return null;
+        }
         for (const marker of workspaceMarkers) {
             if (fs.existsSync(path.join(current, marker))) {
                 return current;
@@ -92,6 +97,32 @@ function findNearestWorkspaceMarker(startPath) {
         current = parent;
     }
 }
+function resolveHomeMarkerBoundary(startPath) {
+    const homeDir = os.homedir();
+    if (!homeDir) {
+        return null;
+    }
+    const resolvedHomeDir = path.resolve(homeDir);
+    const candidateHomes = [
+        canonicalizeDirectoryPath(resolvedHomeDir),
+        path.normalize(resolvedHomeDir)
+    ];
+    for (const candidateHome of candidateHomes) {
+        if (!samePath(startPath, candidateHome) &&
+            isWithinOrSame(startPath, candidateHome)) {
+            return candidateHome;
+        }
+    }
+    return null;
+}
+function canonicalizeDirectoryPath(directoryPath) {
+    try {
+        return fs.realpathSync.native(directoryPath);
+    }
+    catch {
+        return path.normalize(directoryPath);
+    }
+}
 function samePath(left, right) {
     return path.normalize(left) === path.normalize(right);
 }