The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
Add built-in grok_local adapter (#6087)
Devin Foleyab8b471685bf
diff --git a/Dockerfile b/Dockerfileindex e367910e5e..ece9d86b87 100644--- a/Dockerfile+++ b/Dockerfile@@ -28,6 +28,7 @@ COPY packages/adapters/codex-local/package.json packages/adapters/codex-local/COPY packages/adapters/cursor-cloud/package.json packages/adapters/cursor-cloud/COPY packages/adapters/cursor-local/package.json packages/adapters/cursor-local/COPY packages/adapters/gemini-local/package.json packages/adapters/gemini-local/+COPY packages/adapters/grok-local/package.json packages/adapters/grok-local/COPY packages/adapters/openclaw-gateway/package.json packages/adapters/openclaw-gateway/COPY packages/adapters/opencode-local/package.json packages/adapters/opencode-local/COPY packages/adapters/pi-local/package.json packages/adapters/pi-local/diff --git a/cli/package.json b/cli/package.jsonindex 2dffbeeeb6..b60dde4d97 100644--- a/cli/package.json+++ b/cli/package.json@@ -43,6 +43,7 @@"@paperclipai/adapter-cursor-cloud": "workspace:*","@paperclipai/adapter-cursor-local": "workspace:*","@paperclipai/adapter-gemini-local": "workspace:*",+ "@paperclipai/adapter-grok-local": "workspace:*","@paperclipai/adapter-opencode-local": "workspace:*","@paperclipai/adapter-pi-local": "workspace:*","@paperclipai/adapter-openclaw-gateway": "workspace:*",diff --git a/cli/src/adapters/registry.ts b/cli/src/adapters/registry.tsindex d7d16f1792..31dfe0d0af 100644--- a/cli/src/adapters/registry.ts+++ b/cli/src/adapters/registry.ts@@ -5,6 +5,7 @@ import { printCodexStreamEvent } from "@paperclipai/adapter-codex-local/cli";import { printCursorStreamEvent } from "@paperclipai/adapter-cursor-local/cli";import { printCursorCloudEvent } from "@paperclipai/adapter-cursor-cloud/cli";import { printGeminiStreamEvent } from "@paperclipai/adapter-gemini-local/cli";+import { printGrokStreamEvent } from "@paperclipai/adapter-grok-local/cli";import { printOpenCodeStreamEvent } from "@paperclipai/adapter-opencode-local/cli";import { printPiStreamEvent } from "@paperclipai/adapter-pi-local/cli";import { printOpenClawGatewayStreamEvent } from "@paperclipai/adapter-openclaw-gateway/cli";@@ -51,6 +52,11 @@ const geminiLocalCLIAdapter: CLIAdapterModule = {formatStdoutEvent: printGeminiStreamEvent,};+const grokLocalCLIAdapter: CLIAdapterModule = {+ type: "grok_local",+ formatStdoutEvent: printGrokStreamEvent,+};+const openclawGatewayCLIAdapter: CLIAdapterModule = {type: "openclaw_gateway",formatStdoutEvent: printOpenClawGatewayStreamEvent,@@ -66,6 +72,7 @@ const adaptersByType = new Map<string, CLIAdapterModule>(cursorLocalCLIAdapter,cursorCloudCLIAdapter,geminiLocalCLIAdapter,+ grokLocalCLIAdapter,openclawGatewayCLIAdapter,processCLIAdapter,httpCLIAdapter,diff --git a/packages/adapters/grok-local/package.json b/packages/adapters/grok-local/package.jsonnew file mode 100644index 0000000000..466a6d4995--- /dev/null+++ b/packages/adapters/grok-local/package.json@@ -0,0 +1,60 @@+{+ "name": "@paperclipai/adapter-grok-local",+ "version": "0.3.1",+ "license": "MIT",+ "homepage": "https://github.com/paperclipai/paperclip",+ "bugs": {+ "url": "https://github.com/paperclipai/paperclip/issues"+ },+ "repository": {+ "type": "git",+ "url": "https://github.com/paperclipai/paperclip",+ "directory": "packages/adapters/grok-local"+ },+ "type": "module",+ "exports": {+ ".": "./src/index.ts",+ "./server": "./src/server/index.ts",+ "./ui": "./src/ui/index.ts",+ "./cli": "./src/cli/index.ts"+ },+ "publishConfig": {+ "access": "public",+ "exports": {+ ".": {+ "types": "./dist/index.d.ts",+ "import": "./dist/index.js"+ },+ "./server": {+ "types": "./dist/server/index.d.ts",+ "import": "./dist/server/index.js"+ },+ "./ui": {+ "types": "./dist/ui/index.d.ts",+ "import": "./dist/ui/index.js"+ },+ "./cli": {+ "types": "./dist/cli/index.d.ts",+ "import": "./dist/cli/index.js"+ }+ },+ "main": "./dist/index.js",+ "types": "./dist/index.d.ts"+ },+ "files": [+ "dist"+ ],+ "scripts": {+ "build": "tsc",+ "clean": "rm -rf dist",+ "typecheck": "tsc --noEmit"+ },+ "dependencies": {+ "@paperclipai/adapter-utils": "workspace:*",+ "picocolors": "^1.1.1"+ },+ "devDependencies": {+ "@types/node": "^24.6.0",+ "typescript": "^5.7.3"+ }+}diff --git a/packages/adapters/grok-local/src/cli/format-event.test.ts b/packages/adapters/grok-local/src/cli/format-event.test.tsnew file mode 100644index 0000000000..81ab879eee--- /dev/null+++ b/packages/adapters/grok-local/src/cli/format-event.test.ts@@ -0,0 +1,24 @@+import { afterEach, describe, expect, it, vi } from "vitest";+import { printGrokStreamEvent } from "./format-event.js";++describe("printGrokStreamEvent", () => {+ const spy = vi.spyOn(console, "log").mockImplementation(() => {});++ afterEach(() => {+ spy.mockClear();+ });++ it("prints thought/text/end events", () => {+ printGrokStreamEvent(JSON.stringify({ type: "thought", data: "Plan" }), false);+ printGrokStreamEvent(JSON.stringify({ type: "text", data: "hello" }), false);+ printGrokStreamEvent(JSON.stringify({ type: "end", stopReason: "EndTurn", sessionId: "sess-1" }), false);++ expect(spy.mock.calls.flat()).toEqual(+ expect.arrayContaining([+ expect.stringContaining("thinking: Plan"),+ expect.stringContaining("assistant: hello"),+ expect.stringContaining("Grok run completed"),+ ]),+ );+ });+});diff --git a/packages/adapters/grok-local/src/cli/format-event.ts b/packages/adapters/grok-local/src/cli/format-event.tsnew file mode 100644index 0000000000..951e5737bd--- /dev/null+++ b/packages/adapters/grok-local/src/cli/format-event.ts@@ -0,0 +1,59 @@+import pc from "picocolors";++function asRecord(value: unknown): Record<string, unknown> | null {+ if (typeof value !== "object" || value === null || Array.isArray(value)) return null;+ return value as Record<string, unknown>;+}++function asString(value: unknown, fallback = ""): string {+ return typeof value === "string" ? value : fallback;+}++export function printGrokStreamEvent(raw: string, _debug: boolean): void {+ const line = raw.trim();+ if (!line) return;++ let parsed: Record<string, unknown> | null = null;+ try {+ parsed = JSON.parse(line) as Record<string, unknown>;+ } catch {+ console.log(line);+ return;+ }++ const type = asString(parsed.type).trim();+ if (type === "thought") {+ const text = asString(parsed.data);+ if (text) console.log(pc.gray(`thinking: ${text}`));+ return;+ }++ if (type === "text") {+ const text = asString(parsed.data);+ if (text) console.log(pc.green(`assistant: ${text}`));+ return;+ }++ if (type === "end") {+ const stopReason = asString(parsed.stopReason);+ const sessionId = asString(parsed.sessionId);+ const details = [stopReason ? `stopReason=${stopReason}` : "", sessionId ? `session=${sessionId}` : ""]+ .filter(Boolean)+ .join(" ");+ console.log(pc.blue(`Grok run completed${details ? ` (${details})` : ""}`));+ return;+ }++ if (type === "error") {+ const text =+ asString(parsed.data) ||+ asString(parsed.message) ||+ asString(parsed.error) ||+ "Grok error";+ console.log(pc.red(`error: ${text}`));+ return;+ }++ const payload = asRecord(parsed);+ console.log(pc.gray(`event: ${type || "unknown"} ${payload ? JSON.stringify(payload) : line}`));+}diff --git a/packages/adapters/grok-local/src/cli/index.ts b/packages/adapters/grok-local/src/cli/index.tsnew file mode 100644index 0000000000..c6bdf98829--- /dev/null+++ b/packages/adapters/grok-local/src/cli/index.ts@@ -0,0 +1 @@+export { printGrokStreamEvent } from "./format-event.js";diff --git a/packages/adapters/grok-local/src/index.ts b/packages/adapters/grok-local/src/index.tsnew file mode 100644index 0000000000..7e12bd1d99--- /dev/null+++ b/packages/adapters/grok-local/src/index.ts@@ -0,0 +1,45 @@+export const type = "grok_local";+export const label = "Grok Build (local)";++export const DEFAULT_GROK_LOCAL_MODEL = "grok-build";++export const models = [+ { id: DEFAULT_GROK_LOCAL_MODEL, label: DEFAULT_GROK_LOCAL_MODEL },+];++export const agentConfigurationDoc = `# grok_local agent configuration++Adapter: grok_local++Use when:+- You want Paperclip to run the native Grok Build CLI locally on the host machine+- You want resumable Grok sessions across heartbeats via \`--resume\`+- You want Paperclip-managed instructions and skills staged into the execution workspace using Grok's native discovery paths (\`Agents.md\` and \`.claude/skills\`)++Don't use when:+- You need a webhook-style external invocation (use http or openclaw_gateway)+- You only need a one-shot script without an AI coding agent loop (use process)+- Grok CLI is not installed or authenticated on the machine that runs Paperclip++Core fields:+- cwd (string, optional): default absolute working directory fallback for the agent process (created if missing when possible)+- instructionsFilePath (string, optional): absolute path to a markdown instructions file. Paperclip stages it into the execution workspace as \`Agents.md\` when safe, otherwise falls back to \`--rules @file\`+- promptTemplate (string, optional): run prompt template+- model (string, optional): Grok model id. Defaults to grok-build.+- permissionMode (string, optional): Grok permission mode. Defaults to \`dontAsk\`+- reasoningEffort (string, optional): Grok reasoning effort passed via \`--reasoning-effort\`+- maxTurns (number, optional): maximum agent turns for the run+- command (string, optional): defaults to "grok"+- extraArgs (string[], optional): additional CLI args+- env (object, optional): KEY=VALUE environment variables++Operational fields:+- timeoutSec (number, optional): run timeout in seconds+- graceSec (number, optional): SIGTERM grace period in seconds++Notes:+- Runs use \`grok --single\` with \`--output-format streaming-json\`.+- Sessions resume with \`--resume <sessionId>\` when the saved session cwd matches the current cwd.+- Paperclip stages desired runtime skills into \`.claude/skills\` inside the execution workspace so Grok discovers them as project skills.+- Use \`grok models\` to inspect authentication and available models on the host.+`;diff --git a/packages/adapters/grok-local/src/server/execute.test.ts b/packages/adapters/grok-local/src/server/execute.test.tsnew file mode 100644index 0000000000..b520bf13e6--- /dev/null+++ b/packages/adapters/grok-local/src/server/execute.test.ts@@ -0,0 +1,187 @@+import fs from "node:fs/promises";+import os from "node:os";+import path from "node:path";+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import type { AdapterExecutionContext } from "@paperclipai/adapter-utils";++const ensureRuntimeInstalledMock = vi.hoisted(() => vi.fn(async () => {}));+const ensureCommandMock = vi.hoisted(() => vi.fn(async () => {}));+const prepareRuntimeMock = vi.hoisted(() => vi.fn(async () => ({+ workspaceRemoteDir: null,+ restoreWorkspace: async () => {},+})));+const resolveCommandForLogsMock = vi.hoisted(() => vi.fn(async () => "grok"));+const runProcessMock = vi.hoisted(() => vi.fn());++vi.mock("@paperclipai/adapter-utils/execution-target", () => ({+ adapterExecutionTargetIsRemote: () => false,+ adapterExecutionTargetRemoteCwd: (_target: unknown, cwd: string) => cwd,+ overrideAdapterExecutionTargetRemoteCwd: (target: unknown, _cwd: string) => target,+ adapterExecutionTargetSessionIdentity: () => ({ kind: "local" }),+ adapterExecutionTargetSessionMatches: () => true,+ describeAdapterExecutionTarget: () => "local",+ ensureAdapterExecutionTargetCommandResolvable: ensureCommandMock,+ ensureAdapterExecutionTargetRuntimeCommandInstalled: ensureRuntimeInstalledMock,+ prepareAdapterExecutionTargetRuntime: prepareRuntimeMock,+ readAdapterExecutionTarget: ({ executionTarget }: { executionTarget?: unknown }) => executionTarget ?? { kind: "local" },+ resolveAdapterExecutionTargetCommandForLogs: resolveCommandForLogsMock,+ resolveAdapterExecutionTargetTimeoutSec: (_target: unknown, timeoutSec: number) => timeoutSec,+ runAdapterExecutionTargetProcess: runProcessMock,+}));++import { execute } from "./execute.js";++const tempRoots: string[] = [];++async function makeTempRoot() {+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-grok-local-"));+ tempRoots.push(root);+ return root;+}++async function pathExists(candidate: string): Promise<boolean> {+ return fs.access(candidate).then(() => true).catch(() => false);+}++describe("grok_local execute", () => {+ beforeEach(() => {+ ensureRuntimeInstalledMock.mockClear();+ ensureCommandMock.mockClear();+ prepareRuntimeMock.mockClear();+ resolveCommandForLogsMock.mockClear();+ runProcessMock.mockReset();+ });++ afterEach(async () => {+ await Promise.all(tempRoots.splice(0).map((root) => fs.rm(root, { recursive: true, force: true })));+ });++ it("stages Grok-native instructions and skills into the workspace for the run and cleans them up afterward", async () => {+ const root = await makeTempRoot();+ const instructionsPath = path.join(root, "managed", "AGENTS.md");+ const skillSource = path.join(root, "runtime-skills", "paperclip");+ await fs.mkdir(path.dirname(instructionsPath), { recursive: true });+ await fs.writeFile(instructionsPath, "You are Grok.\n", "utf8");+ await fs.mkdir(skillSource, { recursive: true });+ await fs.writeFile(path.join(skillSource, "SKILL.md"), "---\nname: paperclip\ndescription: test\n---\n", "utf8");++ runProcessMock.mockImplementation(async (_runId, _target, _command, args, options) => {+ expect(args).toEqual(+ expect.arrayContaining([+ "--output-format",+ "streaming-json",+ "--always-approve",+ "--permission-mode",+ "dontAsk",+ ]),+ );+ expect(await fs.readFile(path.join(root, "Agents.md"), "utf8")).toContain("You are Grok.");+ expect(await pathExists(path.join(root, ".claude", "skills", "paperclip", "SKILL.md"))).toBe(true);+ await options.onLog?.("stdout", '{"type":"text","data":"done"}\n');+ return {+ exitCode: 0,+ signal: null,+ timedOut: false,+ stdout: [+ JSON.stringify({ type: "text", data: "done" }),+ JSON.stringify({ type: "end", stopReason: "EndTurn", sessionId: "sess-1", requestId: "req-1" }),+ ].join("\n"),+ stderr: "",+ };+ });++ const logs: Array<{ stream: "stdout" | "stderr"; chunk: string }> = [];+ const ctx: AdapterExecutionContext = {+ runId: "run-1",+ agent: {+ id: "agent-1",+ companyId: "company-1",+ name: "Grok Agent",+ adapterType: "grok_local",+ adapterConfig: {},+ },+ runtime: {+ sessionId: null,+ sessionParams: null,+ sessionDisplayId: null,+ taskKey: null,+ },+ config: {+ cwd: root,+ instructionsFilePath: instructionsPath,+ paperclipRuntimeSkills: [{+ key: "paperclip",+ runtimeName: "paperclip",+ source: skillSource,+ required: false,+ }],+ paperclipSkillSync: { desiredSkills: ["paperclip"] },+ },+ context: {},+ authToken: "run-token",+ onLog: async (stream: "stdout" | "stderr", chunk: string) => {+ logs.push({ stream, chunk });+ },+ };++ const result = await execute(ctx);++ expect(result).toMatchObject({+ exitCode: 0,+ errorMessage: null,+ summary: "done",+ sessionId: "sess-1",+ sessionDisplayId: "sess-1",+ });+ expect(await pathExists(path.join(root, "Agents.md"))).toBe(false);+ expect(await pathExists(path.join(root, ".claude", "skills", "paperclip"))).toBe(false);+ expect(logs.map((entry) => entry.chunk)).not.toEqual([]);+ });++ it("cleans up staged assets when setup fails before the Grok process starts", async () => {+ const root = await makeTempRoot();+ const instructionsPath = path.join(root, "managed", "AGENTS.md");+ const skillSource = path.join(root, "runtime-skills", "paperclip");+ await fs.mkdir(path.dirname(instructionsPath), { recursive: true });+ await fs.writeFile(instructionsPath, "You are Grok.\n", "utf8");+ await fs.mkdir(skillSource, { recursive: true });+ await fs.writeFile(path.join(skillSource, "SKILL.md"), "---\nname: paperclip\ndescription: test\n---\n", "utf8");+ ensureCommandMock.mockRejectedValueOnce(new Error("grok not installed"));++ const ctx: AdapterExecutionContext = {+ runId: "run-setup-fail",+ agent: {+ id: "agent-1",+ companyId: "company-1",+ name: "Grok Agent",+ adapterType: "grok_local",+ adapterConfig: {},+ },+ runtime: {+ sessionId: null,+ sessionParams: null,+ sessionDisplayId: null,+ taskKey: null,+ },+ config: {+ cwd: root,+ instructionsFilePath: instructionsPath,+ paperclipRuntimeSkills: [{+ key: "paperclip",+ runtimeName: "paperclip",+ source: skillSource,+ required: false,+ }],+ paperclipSkillSync: { desiredSkills: ["paperclip"] },+ },+ context: {},+ authToken: "run-token",+ onLog: async () => {},+ };++ await expect(execute(ctx)).rejects.toThrow("grok not installed");+ expect(runProcessMock).not.toHaveBeenCalled();+ expect(await pathExists(path.join(root, "Agents.md"))).toBe(false);+ expect(await pathExists(path.join(root, ".claude", "skills", "paperclip"))).toBe(false);+ });+});diff --git a/packages/adapters/grok-local/src/server/execute.ts b/packages/adapters/grok-local/src/server/execute.tsnew file mode 100644index 0000000000..0d25845ada--- /dev/null+++ b/packages/adapters/grok-local/src/server/execute.ts@@ -0,0 +1,583 @@+import fs from "node:fs/promises";+import path from "node:path";+import { fileURLToPath } from "node:url";+import type { AdapterExecutionContext, AdapterExecutionResult } from "@paperclipai/adapter-utils";+import {+ adapterExecutionTargetIsRemote,+ adapterExecutionTargetRemoteCwd,+ adapterExecutionTargetSessionIdentity,+ adapterExecutionTargetSessionMatches,+ describeAdapterExecutionTarget,+ ensureAdapterExecutionTargetCommandResolvable,+ ensureAdapterExecutionTargetRuntimeCommandInstalled,+ overrideAdapterExecutionTargetRemoteCwd,+ prepareAdapterExecutionTargetRuntime,+ readAdapterExecutionTarget,+ resolveAdapterExecutionTargetCommandForLogs,+ resolveAdapterExecutionTargetTimeoutSec,+ runAdapterExecutionTargetProcess,+} from "@paperclipai/adapter-utils/execution-target";+import {+ asBoolean,+ asNumber,+ asString,+ asStringArray,+ buildInvocationEnvForLogs,+ buildPaperclipEnv,+ ensureAbsoluteDirectory,+ ensurePathInEnv,+ joinPromptSections,+ materializePaperclipSkillCopy,+ parseObject,+ readPaperclipIssueWorkModeFromContext,+ readPaperclipRuntimeSkillEntries,+ renderTemplate,+ renderPaperclipWakePrompt,+ resolvePaperclipDesiredSkillNames,+ stringifyPaperclipWakePayload,+ refreshPaperclipWorkspaceEnvForExecution,+ DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,+} from "@paperclipai/adapter-utils/server-utils";+import { DEFAULT_GROK_LOCAL_MODEL } from "../index.js";+import { isGrokUnknownSessionError, parseGrokJsonl } from "./parse.js";++const __moduleDir = path.dirname(fileURLToPath(import.meta.url));++function firstNonEmptyLine(text: string): string {+ return (+ text+ .split(/\r?\n/)+ .map((line) => line.trim())+ .find(Boolean) ?? ""+ );+}++function hasNonEmptyEnvValue(env: Record<string, string>, key: string): boolean {+ const raw = env[key];+ return typeof raw === "string" && raw.trim().length > 0;+}++function renderPaperclipEnvNote(env: Record<string, string>): string {+ const paperclipKeys = Object.keys(env)+ .filter((key) => key.startsWith("PAPERCLIP_"))+ .sort();+ if (paperclipKeys.length === 0) return "";+ return [+ "Paperclip runtime note:",+ `The following PAPERCLIP_* environment variables are available in this run: ${paperclipKeys.join(", ")}`,+ "Do not assume these variables are missing without checking your shell environment.",+ "",+ "",+ ].join("\n");+}++function renderApiAccessNote(env: Record<string, string>): string {+ if (!hasNonEmptyEnvValue(env, "PAPERCLIP_API_URL") || !hasNonEmptyEnvValue(env, "PAPERCLIP_API_KEY")) return "";+ return [+ "Paperclip API access note:",+ "Use shell commands with curl to make Paperclip API requests when needed.",+ "Include X-Paperclip-Run-Id on mutating requests.",+ "",+ "",+ ].join("\n");+}++type StageCleanup = {+ kind: "file" | "dir";+ path: string;+};++type StagedGrokAssets = {+ cleanup: () => Promise<void>;+ stagedSkillsCount: number;+ stagedInstructionsPath: string | null;+ rulesFilePath: string | null;+};++async function pathExists(candidate: string): Promise<boolean> {+ return fs.access(candidate).then(() => true).catch(() => false);+}++async function stageGrokProjectAssets(input: {+ cwd: string;+ instructionsFilePath: string;+ skillEntries: Array<{ key: string; runtimeName: string; source: string }>;+ desiredSkillNames: string[];+ onLog: AdapterExecutionContext["onLog"];+}): Promise<StagedGrokAssets> {+ const cleanup: StageCleanup[] = [];+ const ensureCleanupDir = (candidate: string) => {+ cleanup.push({ kind: "dir", path: candidate });+ };+ const ensureCleanupFile = (candidate: string) => {+ cleanup.push({ kind: "file", path: candidate });+ };++ let stagedInstructionsPath: string | null = null;+ let rulesFilePath: string | null = null;+ let stagedSkillsCount = 0;++ const instructionsTarget = path.join(input.cwd, "Agents.md");+ if (input.instructionsFilePath) {+ if (!await pathExists(instructionsTarget)) {+ await fs.copyFile(input.instructionsFilePath, instructionsTarget);+ ensureCleanupFile(instructionsTarget);+ stagedInstructionsPath = instructionsTarget;+ } else if (path.resolve(instructionsTarget) !== path.resolve(input.instructionsFilePath)) {+ rulesFilePath = input.instructionsFilePath;+ await input.onLog(+ "stdout",+ `[paperclip] Grok workspace already contains ${instructionsTarget}; using --rules @${input.instructionsFilePath} instead of overwriting it.\n`,+ );+ }+ } else {+ const canonicalAgents = path.join(input.cwd, "AGENTS.md");+ if (!await pathExists(instructionsTarget) && await pathExists(canonicalAgents)) {+ await fs.copyFile(canonicalAgents, instructionsTarget);+ ensureCleanupFile(instructionsTarget);+ stagedInstructionsPath = instructionsTarget;+ }+ }++ const desiredSet = new Set(input.desiredSkillNames);+ const selectedSkills = input.skillEntries.filter((entry) => desiredSet.has(entry.key));+ if (selectedSkills.length > 0) {+ const claudeDir = path.join(input.cwd, ".claude");+ const skillsRoot = path.join(claudeDir, "skills");+ if (!await pathExists(claudeDir)) {+ await fs.mkdir(claudeDir, { recursive: true });+ ensureCleanupDir(claudeDir);+ }+ if (!await pathExists(skillsRoot)) {+ await fs.mkdir(skillsRoot, { recursive: true });+ ensureCleanupDir(skillsRoot);+ }++ for (const skill of selectedSkills) {+ const target = path.join(skillsRoot, skill.runtimeName);+ if (await pathExists(target)) {+ await input.onLog(+ "stdout",+ `[paperclip] Grok skill target already exists at ${target}; leaving it unchanged.\n`,+ );+ continue;+ }+ await materializePaperclipSkillCopy(skill.source, target);+ ensureCleanupDir(target);+ stagedSkillsCount += 1;+ }+ }++ return {+ stagedSkillsCount,+ stagedInstructionsPath,+ rulesFilePath,+ cleanup: async () => {+ for (const entry of [...cleanup].reverse()) {+ if (entry.kind === "file") {+ await fs.rm(entry.path, { force: true }).catch(() => undefined);+ continue;+ }+ await fs.rm(entry.path, { recursive: true, force: true }).catch(() => undefined);+ }+ },+ };+}++function resolveBillingType(env: Record<string, string>): "api" | "subscription" {+ return hasNonEmptyEnvValue(env, "XAI_API_KEY") ? "api" : "subscription";+}++export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult> {+ const { runId, agent, runtime, config, context, onLog, onMeta, onSpawn, authToken } = ctx;+ const executionTarget = readAdapterExecutionTarget({+ executionTarget: ctx.executionTarget,+ legacyRemoteExecution: ctx.executionTransport?.remoteExecution,+ });+ const executionTargetIsRemote = adapterExecutionTargetIsRemote(executionTarget);++ const promptTemplate = asString(+ config.promptTemplate,+ DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,+ );+ const command = asString(config.command, "grok");+ const model = asString(config.model, DEFAULT_GROK_LOCAL_MODEL).trim();+ const permissionMode = asString(config.permissionMode, "dontAsk").trim() || "dontAsk";+ const reasoningEffort = asString(config.reasoningEffort, "").trim();+ const maxTurns = asNumber(config.maxTurns, 0);+ const alwaysApprove = asBoolean(config.alwaysApprove, true);+ const disableWebSearch = asBoolean(config.disableWebSearch, true);++ const workspaceContext = parseObject(context.paperclipWorkspace);+ const workspaceCwd = asString(workspaceContext.cwd, "");+ const workspaceSource = asString(workspaceContext.source, "");+ const workspaceId = asString(workspaceContext.workspaceId, "");+ const workspaceRepoUrl = asString(workspaceContext.repoUrl, "");+ const workspaceRepoRef = asString(workspaceContext.repoRef, "");+ const agentHome = asString(workspaceContext.agentHome, "");+ const workspaceHints = Array.isArray(context.paperclipWorkspaces)+ ? context.paperclipWorkspaces.filter(+ (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null,+ )+ : [];+ const configuredCwd = asString(config.cwd, "");+ const useConfiguredInsteadOfAgentHome = workspaceSource === "agent_home" && configuredCwd.length > 0;+ const effectiveWorkspaceCwd = useConfiguredInsteadOfAgentHome ? "" : workspaceCwd;+ const cwd = effectiveWorkspaceCwd || configuredCwd || process.cwd();+ let effectiveExecutionCwd = adapterExecutionTargetRemoteCwd(executionTarget, cwd);+ await ensureAbsoluteDirectory(cwd, { createIfMissing: true });++ const grokSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);+ const desiredGrokSkillNames = resolvePaperclipDesiredSkillNames(config, grokSkillEntries);+ const instructionsFilePath = asString(config.instructionsFilePath, "").trim();+ const stagedAssets = await stageGrokProjectAssets({+ cwd,+ instructionsFilePath,+ skillEntries: grokSkillEntries,+ desiredSkillNames: desiredGrokSkillNames,+ onLog,+ });+ let restoreRemoteWorkspace: (() => Promise<void>) | null = null;++ try {+ const envConfig = parseObject(config.env);+ const hasExplicitApiKey =+ typeof envConfig.PAPERCLIP_API_KEY === "string" && envConfig.PAPERCLIP_API_KEY.trim().length > 0;+ const env: Record<string, string> = { ...buildPaperclipEnv(agent) };+ env.PAPERCLIP_RUN_ID = runId;+ const wakeTaskId =+ (typeof context.taskId === "string" && context.taskId.trim().length > 0 && context.taskId.trim()) ||+ (typeof context.issueId === "string" && context.issueId.trim().length > 0 && context.issueId.trim()) ||+ null;+ const wakeReason =+ typeof context.wakeReason === "string" && context.wakeReason.trim().length > 0+ ? context.wakeReason.trim()+ : null;+ const wakeCommentId =+ (typeof context.wakeCommentId === "string" && context.wakeCommentId.trim().length > 0 && context.wakeCommentId.trim()) ||+ (typeof context.commentId === "string" && context.commentId.trim().length > 0 && context.commentId.trim()) ||+ null;+ const approvalId =+ typeof context.approvalId === "string" && context.approvalId.trim().length > 0+ ? context.approvalId.trim()+ : null;+ const approvalStatus =+ typeof context.approvalStatus === "string" && context.approvalStatus.trim().length > 0+ ? context.approvalStatus.trim()+ : null;+ const linkedIssueIds = Array.isArray(context.issueIds)+ ? context.issueIds.filter((value: unknown): value is string => typeof value === "string" && value.trim().length > 0)+ : [];+ const wakePayloadJson = stringifyPaperclipWakePayload(context.paperclipWake);+ const issueWorkMode = readPaperclipIssueWorkModeFromContext(context);+ if (wakeTaskId) env.PAPERCLIP_TASK_ID = wakeTaskId;+ if (issueWorkMode) env.PAPERCLIP_ISSUE_WORK_MODE = issueWorkMode;+ if (wakeReason) env.PAPERCLIP_WAKE_REASON = wakeReason;+ if (wakeCommentId) env.PAPERCLIP_WAKE_COMMENT_ID = wakeCommentId;+ if (approvalId) env.PAPERCLIP_APPROVAL_ID = approvalId;+ if (approvalStatus) env.PAPERCLIP_APPROVAL_STATUS = approvalStatus;+ if (linkedIssueIds.length > 0) env.PAPERCLIP_LINKED_ISSUE_IDS = linkedIssueIds.join(",");+ if (wakePayloadJson) env.PAPERCLIP_WAKE_PAYLOAD_JSON = wakePayloadJson;+ refreshPaperclipWorkspaceEnvForExecution({+ env,+ envConfig,+ workspaceCwd: effectiveWorkspaceCwd,+ workspaceSource,+ workspaceId,+ workspaceRepoUrl,+ workspaceRepoRef,+ workspaceHints,+ agentHome,+ executionTargetIsRemote,+ executionCwd: effectiveExecutionCwd,+ });+ if (!hasExplicitApiKey && authToken) {+ env.PAPERCLIP_API_KEY = authToken;+ }++ const timeoutSec = resolveAdapterExecutionTargetTimeoutSec(+ executionTarget,+ asNumber(config.timeoutSec, 0),+ );+ const graceSec = asNumber(config.graceSec, 20);+ await ensureAdapterExecutionTargetRuntimeCommandInstalled({+ runId,+ target: executionTarget,+ installCommand: ctx.runtimeCommandSpec?.installCommand,+ detectCommand: ctx.runtimeCommandSpec?.detectCommand,+ cwd,+ env,+ timeoutSec,+ graceSec,+ onLog,+ });++ if (executionTargetIsRemote) {+ await onLog(+ "stdout",+ `[paperclip] Syncing Grok workspace to ${describeAdapterExecutionTarget(executionTarget)}.\n`,+ );+ const preparedExecutionTargetRuntime = await prepareAdapterExecutionTargetRuntime({+ runId,+ target: executionTarget,+ adapterKey: "grok",+ workspaceLocalDir: cwd,+ timeoutSec,+ installCommand: ctx.runtimeCommandSpec?.installCommand ?? null,+ detectCommand: ctx.runtimeCommandSpec?.detectCommand ?? command,+ });+ restoreRemoteWorkspace = () => preparedExecutionTargetRuntime.restoreWorkspace();+ effectiveExecutionCwd = preparedExecutionTargetRuntime.workspaceRemoteDir ?? effectiveExecutionCwd;+ refreshPaperclipWorkspaceEnvForExecution({+ env,+ envConfig,+ workspaceCwd: effectiveWorkspaceCwd,+ workspaceSource,+ workspaceId,+ workspaceRepoUrl,+ workspaceRepoRef,+ workspaceHints,+ agentHome,+ executionTargetIsRemote,+ executionCwd: effectiveExecutionCwd,+ });+ }++ const runtimeExecutionTarget = overrideAdapterExecutionTargetRemoteCwd(executionTarget, effectiveExecutionCwd);+ const effectiveEnv = Object.fromEntries(+ Object.entries({ ...process.env, ...env }).filter(+ (entry): entry is [string, string] => typeof entry[1] === "string",+ ),+ );+ const runtimeEnv = ensurePathInEnv(effectiveEnv);+ await ensureAdapterExecutionTargetCommandResolvable(command, executionTarget, cwd, runtimeEnv, {+ installCommand: ctx.runtimeCommandSpec?.installCommand ?? null,+ timeoutSec,+ });+ const resolvedCommand = await resolveAdapterExecutionTargetCommandForLogs(command, executionTarget, cwd, runtimeEnv);+ const loggedEnv = buildInvocationEnvForLogs(env, {+ runtimeEnv,+ includeRuntimeKeys: ["HOME"],+ resolvedCommand,+ });+ const billingType = resolveBillingType(effectiveEnv);++ const runtimeSessionParams = parseObject(runtime.sessionParams);+ const runtimeSessionId = asString(runtimeSessionParams.sessionId, runtime.sessionId ?? "");+ const runtimeSessionCwd = asString(runtimeSessionParams.cwd, "");+ const runtimeRemoteExecution = parseObject(runtimeSessionParams.remoteExecution);+ const canResumeSession =+ runtimeSessionId.length > 0 &&+ (runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(effectiveExecutionCwd)) &&+ adapterExecutionTargetSessionMatches(runtimeRemoteExecution, runtimeExecutionTarget);+ const sessionId = canResumeSession ? runtimeSessionId : null;+ if (executionTargetIsRemote && runtimeSessionId && !canResumeSession) {+ await onLog(+ "stdout",+ `[paperclip] Grok session "${runtimeSessionId}" does not match the current remote execution identity and will not be resumed in "${effectiveExecutionCwd}". Starting a fresh remote session.\n`,+ );+ } else if (runtimeSessionId && !canResumeSession) {+ await onLog(+ "stdout",+ `[paperclip] Grok session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${effectiveExecutionCwd}".\n`,+ );+ }++ const commandNotes = (() => {+ const notes: string[] = ["Prompt is passed to Grok via --single in headless mode."];+ if (alwaysApprove) notes.push("Added --always-approve for unattended execution.");+ if (stagedAssets.stagedInstructionsPath) {+ notes.push(`Staged project instructions at ${stagedAssets.stagedInstructionsPath} for native Grok discovery.`);+ }+ if (stagedAssets.rulesFilePath) {+ notes.push(`Applied fallback instructions via --rules @${stagedAssets.rulesFilePath}.`);+ }+ if (stagedAssets.stagedSkillsCount > 0) {+ notes.push(`Staged ${stagedAssets.stagedSkillsCount} Paperclip skill(s) into .claude/skills for native Grok discovery.`);+ }+ return notes;+ })();++ const templateData = {+ agentId: agent.id,+ companyId: agent.companyId,+ runId,+ company: { id: agent.companyId },+ agent,+ run: { id: runId, source: "on_demand" },+ context,+ };+ const wakePrompt = renderPaperclipWakePrompt(context.paperclipWake, { resumedSession: Boolean(sessionId) });+ const shouldUseResumeDeltaPrompt = Boolean(sessionId) && wakePrompt.length > 0;+ const renderedPrompt = shouldUseResumeDeltaPrompt ? "" : renderTemplate(promptTemplate, templateData);+ const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim();+ const paperclipEnvNote = renderPaperclipEnvNote(env);+ const apiAccessNote = renderApiAccessNote(env);+ const prompt = joinPromptSections([+ wakePrompt,+ sessionHandoffNote,+ paperclipEnvNote,+ apiAccessNote,+ renderedPrompt,+ ]);+ const promptMetrics = {+ promptChars: prompt.length,+ wakePromptChars: wakePrompt.length,+ sessionHandoffChars: sessionHandoffNote.length,+ runtimeNoteChars: paperclipEnvNote.length + apiAccessNote.length,+ heartbeatPromptChars: renderedPrompt.length,+ };++ const buildArgs = (resumeSessionId: string | null) => {+ const args = ["--cwd", effectiveExecutionCwd, "--output-format", "streaming-json"];+ if (resumeSessionId) args.push("--resume", resumeSessionId);+ if (model && model !== DEFAULT_GROK_LOCAL_MODEL) args.push("--model", model);+ if (reasoningEffort) args.push("--reasoning-effort", reasoningEffort);+ if (maxTurns > 0) args.push("--max-turns", String(maxTurns));+ if (permissionMode) args.push("--permission-mode", permissionMode);+ if (alwaysApprove) args.push("--always-approve");+ if (disableWebSearch) args.push("--disable-web-search");+ if (stagedAssets.rulesFilePath) args.push("--rules", `@${stagedAssets.rulesFilePath}`);+ const extraArgs = (() => {+ const fromExtraArgs = asStringArray(config.extraArgs);+ if (fromExtraArgs.length > 0) return fromExtraArgs;+ return asStringArray(config.args);+ })();+ if (extraArgs.length > 0) args.push(...extraArgs);+ args.push("--single", prompt);+ return args;+ };++ const runAttempt = async (resumeSessionId: string | null) => {+ const args = buildArgs(resumeSessionId);+ if (onMeta) {+ await onMeta({+ adapterType: "grok_local",+ command: resolvedCommand,+ cwd: effectiveExecutionCwd,+ commandNotes,+ commandArgs: args.map((value, index) => (+ index === args.length - 1 ? `<prompt ${prompt.length} chars>` : value+ )),+ env: loggedEnv,+ prompt,+ promptMetrics,+ context,+ });+ }++ const proc = await runAdapterExecutionTargetProcess(runId, runtimeExecutionTarget, command, args, {+ cwd,+ env,+ timeoutSec,+ graceSec,+ onSpawn,+ onLog,+ });+ return {+ proc,+ parsed: parseGrokJsonl(proc.stdout),+ };+ };++ const toResult = (+ attempt: {+ proc: {+ exitCode: number | null;+ signal: string | null;+ timedOut: boolean;+ stdout: string;+ stderr: string;+ };+ parsed: ReturnType<typeof parseGrokJsonl>;+ },+ clearSessionOnMissingSession = false,+ isRetry = false,+ ): AdapterExecutionResult => {+ if (attempt.proc.timedOut) {+ return {+ exitCode: attempt.proc.exitCode,+ signal: attempt.proc.signal,+ timedOut: true,+ errorMessage: `Timed out after ${timeoutSec}s`,+ clearSession: clearSessionOnMissingSession,+ };+ }++ const failed = (attempt.proc.exitCode ?? 0) !== 0;+ const parsedError = typeof attempt.parsed.errorMessage === "string" ? attempt.parsed.errorMessage.trim() : "";+ const stderrLine = firstNonEmptyLine(attempt.proc.stderr);+ const fallbackErrorMessage =+ parsedError ||+ stderrLine ||+ `Grok exited with code ${attempt.proc.exitCode ?? -1}`;++ const canFallbackToRuntimeSession = !isRetry;+ const resolvedSessionId = attempt.parsed.sessionId+ ?? (canFallbackToRuntimeSession ? (runtimeSessionId ?? runtime.sessionId ?? null) : null);+ const resolvedSessionParams = resolvedSessionId+ ? ({+ sessionId: resolvedSessionId,+ cwd: effectiveExecutionCwd,+ ...(workspaceId ? { workspaceId } : {}),+ ...(workspaceRepoUrl ? { repoUrl: workspaceRepoUrl } : {}),+ ...(workspaceRepoRef ? { repoRef: workspaceRepoRef } : {}),+ ...(executionTargetIsRemote+ ? {+ remoteExecution: adapterExecutionTargetSessionIdentity(runtimeExecutionTarget),+ }+ : {}),+ } as Record<string, unknown>)+ : null;++ return {+ exitCode: attempt.proc.exitCode,+ signal: attempt.proc.signal,+ timedOut: false,+ errorMessage: failed ? fallbackErrorMessage : null,+ usage: {+ inputTokens: 0,+ outputTokens: 0,+ cachedInputTokens: 0,+ },+ sessionId: resolvedSessionId,+ sessionParams: resolvedSessionParams,+ sessionDisplayId: resolvedSessionId,+ provider: "xai",+ biller: billingType === "api" ? "xai" : "grok",+ model,+ billingType,+ costUsd: null,+ resultJson: {+ stopReason: attempt.parsed.stopReason,+ requestId: attempt.parsed.requestId,+ ...(failed ? { stderr: attempt.proc.stderr } : {}),+ },+ summary: attempt.parsed.summary,+ clearSession: Boolean(clearSessionOnMissingSession && !resolvedSessionId),+ };+ };++ const initial = await runAttempt(sessionId);+ if (+ sessionId &&+ !initial.proc.timedOut &&+ (initial.proc.exitCode ?? 0) !== 0 &&+ isGrokUnknownSessionError(initial.proc.stdout, initial.proc.stderr)+ ) {+ await onLog(+ "stdout",+ `[paperclip] Grok resume session "${sessionId}" is unavailable; retrying with a fresh session.\n`,+ );+ const retry = await runAttempt(null);+ return toResult(retry, true, true);+ }++ return toResult(initial);+ } finally {+ await Promise.all([+ restoreRemoteWorkspace?.(),+ stagedAssets.cleanup(),+ ]);+ }+}diff --git a/packages/adapters/grok-local/src/server/index.ts b/packages/adapters/grok-local/src/server/index.tsnew file mode 100644index 0000000000..127128cfd7--- /dev/null+++ b/packages/adapters/grok-local/src/server/index.ts@@ -0,0 +1,66 @@+import type { AdapterSessionCodec } from "@paperclipai/adapter-utils";++function readNonEmptyString(value: unknown): string | null {+ return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;+}++export const sessionCodec: AdapterSessionCodec = {+ deserialize(raw: unknown) {+ if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;+ const record = raw as Record<string, unknown>;+ const sessionId =+ readNonEmptyString(record.sessionId) ??+ readNonEmptyString(record.session_id) ??+ readNonEmptyString(record.sessionID);+ if (!sessionId) return null;+ const cwd =+ readNonEmptyString(record.cwd) ??+ readNonEmptyString(record.workdir) ??+ readNonEmptyString(record.folder);+ const workspaceId = readNonEmptyString(record.workspaceId) ?? readNonEmptyString(record.workspace_id);+ const repoUrl = readNonEmptyString(record.repoUrl) ?? readNonEmptyString(record.repo_url);+ const repoRef = readNonEmptyString(record.repoRef) ?? readNonEmptyString(record.repo_ref);+ return {+ sessionId,+ ...(cwd ? { cwd } : {}),+ ...(workspaceId ? { workspaceId } : {}),+ ...(repoUrl ? { repoUrl } : {}),+ ...(repoRef ? { repoRef } : {}),+ };+ },+ serialize(params: Record<string, unknown> | null) {+ if (!params) return null;+ const sessionId =+ readNonEmptyString(params.sessionId) ??+ readNonEmptyString(params.session_id) ??+ readNonEmptyString(params.sessionID);+ if (!sessionId) return null;+ const cwd =+ readNonEmptyString(params.cwd) ??+ readNonEmptyString(params.workdir) ??+ readNonEmptyString(params.folder);+ const workspaceId = readNonEmptyString(params.workspaceId) ?? readNonEmptyString(params.workspace_id);+ const repoUrl = readNonEmptyString(params.repoUrl) ?? readNonEmptyString(params.repo_url);+ const repoRef = readNonEmptyString(params.repoRef) ?? readNonEmptyString(params.repo_ref);+ return {+ sessionId,+ ...(cwd ? { cwd } : {}),+ ...(workspaceId ? { workspaceId } : {}),+ ...(repoUrl ? { repoUrl } : {}),+ ...(repoRef ? { repoRef } : {}),+ };+ },+ getDisplayId(params: Record<string, unknown> | null) {+ if (!params) return null;+ return (+ readNonEmptyString(params.sessionId) ??+ readNonEmptyString(params.session_id) ??+ readNonEmptyString(params.sessionID)+ );+ },+};++export { execute } from "./execute.js";+export { listGrokSkills, syncGrokSkills } from "./skills.js";+export { testEnvironment } from "./test.js";+export { parseGrokJsonl, isGrokUnknownSessionError } from "./parse.js";diff --git a/packages/adapters/grok-local/src/server/parse.test.ts b/packages/adapters/grok-local/src/server/parse.test.tsnew file mode 100644index 0000000000..5b31cf88d1--- /dev/null+++ b/packages/adapters/grok-local/src/server/parse.test.ts@@ -0,0 +1,38 @@+import { describe, expect, it } from "vitest";+import { isGrokUnknownSessionError, parseGrokJsonl } from "./parse.js";++describe("parseGrokJsonl", () => {+ it("collects streamed thought/text content and final session metadata", () => {+ const parsed = parseGrokJsonl([+ JSON.stringify({ type: "thought", data: "Plan" }),+ JSON.stringify({ type: "thought", data: " first." }),+ JSON.stringify({ type: "text", data: "hel" }),+ JSON.stringify({ type: "text", data: "lo" }),+ JSON.stringify({ type: "end", stopReason: "EndTurn", sessionId: "sess-1", requestId: "req-1" }),+ ].join("\n"));++ expect(parsed).toEqual({+ sessionId: "sess-1",+ summary: "hello",+ thought: "Plan first.",+ errorMessage: null,+ stopReason: "EndTurn",+ requestId: "req-1",+ });+ });++ it("reads structured error payloads", () => {+ const parsed = parseGrokJsonl([+ JSON.stringify({ type: "error", error: { message: "Authentication required" } }),+ ].join("\n"));++ expect(parsed.errorMessage).toBe("Authentication required");+ });+});++describe("isGrokUnknownSessionError", () => {+ it("detects stale resume failures", () => {+ expect(isGrokUnknownSessionError("", "session not found")).toBe(true);+ expect(isGrokUnknownSessionError("", "everything fine")).toBe(false);+ });+});diff --git a/packages/adapters/grok-local/src/server/parse.ts b/packages/adapters/grok-local/src/server/parse.tsnew file mode 100644index 0000000000..eb5ab92d94--- /dev/null+++ b/packages/adapters/grok-local/src/server/parse.ts@@ -0,0 +1,87 @@+import { asString, parseJson, parseObject } from "@paperclipai/adapter-utils/server-utils";++export interface ParsedGrokJsonl {+ sessionId: string | null;+ summary: string;+ thought: string;+ errorMessage: string | null;+ stopReason: string | null;+ requestId: string | null;+}++function errorText(value: unknown): string {+ if (typeof value === "string") return value;+ const rec = parseObject(value);+ const message =+ asString(rec.message, "").trim() ||+ asString(rec.error, "").trim() ||+ asString(rec.detail, "").trim() ||+ asString(rec.code, "").trim();+ if (message) return message;+ try {+ return JSON.stringify(rec);+ } catch {+ return "";+ }+}++export function parseGrokJsonl(stdout: string): ParsedGrokJsonl {+ let sessionId: string | null = null;+ let stopReason: string | null = null;+ let requestId: string | null = null;+ let errorMessage: string | null = null;+ const thoughtParts: string[] = [];+ const textParts: string[] = [];++ for (const rawLine of stdout.split(/\r?\n/)) {+ const line = rawLine.trim();+ if (!line) continue;++ const event = parseJson(line);+ if (!event) continue;++ const type = asString(event.type, "").trim();+ if (type === "thought") {+ const text = asString(event.data, "");+ if (text) thoughtParts.push(text);+ continue;+ }++ if (type === "text") {+ const text = asString(event.data, "");+ if (text) textParts.push(text);+ continue;+ }++ if (type === "end") {+ sessionId = asString(event.sessionId, "").trim() || sessionId;+ stopReason = asString(event.stopReason, "").trim() || stopReason;+ requestId = asString(event.requestId, "").trim() || requestId;+ continue;+ }++ if (type === "error") {+ const text = errorText(event.error ?? event.message ?? event.detail ?? event.data).trim();+ if (text) errorMessage = text;+ }+ }++ return {+ sessionId,+ summary: textParts.join("").trim(),+ thought: thoughtParts.join("").trim(),+ errorMessage,+ stopReason,+ requestId,+ };+}++export function isGrokUnknownSessionError(stdout: string, stderr: string): boolean {+ const haystack = `${stdout}\n${stderr}`+ .split(/\r?\n/)+ .map((line) => line.trim())+ .filter(Boolean)+ .join("\n");++ return /unknown\s+session|session(?:\s+.*)?\s+not\s+found|resume\s+.*\s+not\s+found|invalid\s+session/i.test(haystack);+}diff --git a/packages/adapters/grok-local/src/server/skills.ts b/packages/adapters/grok-local/src/server/skills.tsnew file mode 100644index 0000000000..fdbbb5489b--- /dev/null+++ b/packages/adapters/grok-local/src/server/skills.ts@@ -0,0 +1,80 @@+import path from "node:path";+import { fileURLToPath } from "node:url";+import type {+ AdapterSkillContext,+ AdapterSkillEntry,+ AdapterSkillSnapshot,+} from "@paperclipai/adapter-utils";+import {+ readPaperclipRuntimeSkillEntries,+ resolvePaperclipDesiredSkillNames,+} from "@paperclipai/adapter-utils/server-utils";++const __moduleDir = path.dirname(fileURLToPath(import.meta.url));++async function buildGrokSkillSnapshot(+ config: Record<string, unknown>,+): Promise<AdapterSkillSnapshot> {+ const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);+ const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));+ const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);+ const desiredSet = new Set(desiredSkills);+ const entries: AdapterSkillEntry[] = availableEntries.map((entry) => ({+ key: entry.key,+ runtimeName: entry.runtimeName,+ desired: desiredSet.has(entry.key),+ managed: true,+ state: desiredSet.has(entry.key) ? "configured" : "available",+ origin: entry.required ? "paperclip_required" : "company_managed",+ originLabel: entry.required ? "Required by Paperclip" : "Managed by Paperclip",+ readOnly: false,+ sourcePath: entry.source,+ targetPath: null,+ detail: desiredSet.has(entry.key)+ ? "Will be copied into `.claude/skills` in the execution workspace on the next run."+ : null,+ required: Boolean(entry.required),+ requiredReason: entry.requiredReason ?? null,+ }));+ const warnings: string[] = [];++ for (const desiredSkill of desiredSkills) {+ if (availableByKey.has(desiredSkill)) continue;+ warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);+ entries.push({+ key: desiredSkill,+ runtimeName: null,+ desired: true,+ managed: true,+ state: "missing",+ origin: "external_unknown",+ originLabel: "External or unavailable",+ readOnly: false,+ sourcePath: null,+ targetPath: null,+ detail: "Paperclip cannot find this skill in the local runtime skills directory.",+ });+ }++ entries.sort((left, right) => left.key.localeCompare(right.key));++ return {+ adapterType: "grok_local",+ supported: true,+ mode: "ephemeral",+ desiredSkills,+ entries,+ warnings,+ };+}++export async function listGrokSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {+ return buildGrokSkillSnapshot(ctx.config);+}++export async function syncGrokSkills(+ ctx: AdapterSkillContext,+ _desiredSkills: string[],+): Promise<AdapterSkillSnapshot> {+ return buildGrokSkillSnapshot(ctx.config);+}diff --git a/packages/adapters/grok-local/src/server/test.test.ts b/packages/adapters/grok-local/src/server/test.test.tsnew file mode 100644index 0000000000..6800744b6f--- /dev/null+++ b/packages/adapters/grok-local/src/server/test.test.ts@@ -0,0 +1,142 @@+import { describe, expect, it, vi, beforeEach } from "vitest";++const ensureDirectoryMock = vi.hoisted(() => vi.fn(async () => {}));+const ensureCommandMock = vi.hoisted(() => vi.fn(async () => {}));+const runProcessMock = vi.hoisted(() => vi.fn());++vi.mock("@paperclipai/adapter-utils/execution-target", () => ({+ describeAdapterExecutionTarget: () => "local",+ ensureAdapterExecutionTargetCommandResolvable: ensureCommandMock,+ ensureAdapterExecutionTargetDirectory: ensureDirectoryMock,+ resolveAdapterExecutionTargetCwd: (_target: unknown, configuredCwd: string, fallbackCwd: string) =>+ configuredCwd || fallbackCwd,+ runAdapterExecutionTargetProcess: runProcessMock,+}));++import { parseGrokModelsOutput, testEnvironment } from "./test.js";++describe("parseGrokModelsOutput", () => {+ it("extracts auth state and models from `grok models` output", () => {+ expect(parseGrokModelsOutput([+ "You are logged in with grok.com.",+ "",+ "Default model: grok-build",+ "",+ "Available models:",+ " * grok-build (default)",+ " * grok-code",+ ].join("\n"))).toEqual({+ authenticated: true,+ defaultModel: "grok-build",+ models: ["grok-build", "grok-code"],+ });+ });+});++describe("grok_local testEnvironment", () => {+ beforeEach(() => {+ ensureDirectoryMock.mockClear();+ ensureCommandMock.mockClear();+ runProcessMock.mockReset();+ });++ it("reports a healthy authenticated host with a working hello probe", async () => {+ runProcessMock+ .mockResolvedValueOnce({+ exitCode: 0,+ signal: null,+ timedOut: false,+ stdout: [+ "You are logged in with grok.com.",+ "",+ "Default model: grok-build",+ "",+ "Available models:",+ " * grok-build (default)",+ ].join("\n"),+ stderr: "",+ })+ .mockResolvedValueOnce({+ exitCode: 0,+ signal: null,+ timedOut: false,+ stdout: [+ JSON.stringify({ type: "text", data: "hello" }),+ JSON.stringify({ type: "end", stopReason: "EndTurn", sessionId: "sess-1", requestId: "req-1" }),+ ].join("\n"),+ stderr: "",+ });++ const result = await testEnvironment({+ companyId: "company-1",+ adapterType: "grok_local",+ config: {+ command: "grok",+ cwd: "/tmp/project",+ model: "grok-build",+ },+ });++ expect(result.status).toBe("pass");+ expect(result.checks.map((check: { code: string }) => check.code)).toEqual(+ expect.arrayContaining([+ "grok_command_resolvable",+ "grok_models_probe_passed",+ "grok_model_configured",+ "grok_hello_probe_passed",+ ]),+ );+ expect(runProcessMock).toHaveBeenNthCalledWith(+ 2,+ expect.any(String),+ null,+ "grok",+ expect.arrayContaining([+ "--output-format",+ "streaming-json",+ "--always-approve",+ "--permission-mode",+ "dontAsk",+ "--disable-web-search",+ "--single",+ "Respond with exactly hello.",+ ]),+ expect.any(Object),+ );+ });++ it("downgrades auth failures to warnings", async () => {+ runProcessMock+ .mockResolvedValueOnce({+ exitCode: 1,+ signal: null,+ timedOut: false,+ stdout: "",+ stderr: "Not logged in. Run `grok login`.",+ })+ .mockResolvedValueOnce({+ exitCode: 1,+ signal: null,+ timedOut: false,+ stdout: "",+ stderr: "Not logged in. Run `grok login`.",+ });++ const result = await testEnvironment({+ companyId: "company-1",+ adapterType: "grok_local",+ config: {+ command: "grok",+ cwd: "/tmp/project",+ },+ });++ expect(result.status).toBe("warn");+ expect(result.checks.map((check: { code: string }) => check.code)).toEqual(+ expect.arrayContaining([+ "grok_auth_required",+ "grok_hello_probe_auth_required",+ ]),+ );+ });+});diff --git a/packages/adapters/grok-local/src/server/test.ts b/packages/adapters/grok-local/src/server/test.tsnew file mode 100644index 0000000000..b69ad7ff6c--- /dev/null+++ b/packages/adapters/grok-local/src/server/test.ts@@ -0,0 +1,313 @@+import type {+ AdapterEnvironmentCheck,+ AdapterEnvironmentTestContext,+ AdapterEnvironmentTestResult,+} from "@paperclipai/adapter-utils";+import {+ asNumber,+ asString,+ asStringArray,+ ensurePathInEnv,+ parseObject,+} from "@paperclipai/adapter-utils/server-utils";+import {+ describeAdapterExecutionTarget,+ ensureAdapterExecutionTargetCommandResolvable,+ ensureAdapterExecutionTargetDirectory,+ resolveAdapterExecutionTargetCwd,+ runAdapterExecutionTargetProcess,+} from "@paperclipai/adapter-utils/execution-target";+import { DEFAULT_GROK_LOCAL_MODEL } from "../index.js";+import { parseGrokJsonl } from "./parse.js";++export interface GrokModelsProbe {+ authenticated: boolean;+ defaultModel: string | null;+ models: string[];+}++function summarizeStatus(checks: AdapterEnvironmentCheck[]): AdapterEnvironmentTestResult["status"] {+ if (checks.some((check) => check.level === "error")) return "fail";+ if (checks.some((check) => check.level === "warn")) return "warn";+ return "pass";+}++function firstNonEmptyLine(text: string): string {+ return (+ text+ .split(/\r?\n/)+ .map((line) => line.trim())+ .find(Boolean) ?? ""+ );+}++function summarizeProbeDetail(stdout: string, stderr: string, parsedError: string | null): string | null {+ const raw = parsedError?.trim() || firstNonEmptyLine(stderr) || firstNonEmptyLine(stdout);+ if (!raw) return null;+ const clean = raw.replace(/\s+/g, " ").trim();+ const max = 240;+ return clean.length > max ? `${clean.slice(0, max - 3)}...` : clean;+}++function normalizeEnv(input: unknown): Record<string, string> {+ if (typeof input !== "object" || input === null || Array.isArray(input)) return {};+ const env: Record<string, string> = {};+ for (const [key, value] of Object.entries(input as Record<string, unknown>)) {+ if (typeof value === "string") env[key] = value;+ }+ return env;+}++const GROK_AUTH_REQUIRED_RE =+ /(?:not\s+logged\s+in|login\s+required|run\s+`?grok\s+login`?|authentication\s+required|unauthorized|invalid\s+credentials)/i;++export function parseGrokModelsOutput(stdout: string): GrokModelsProbe {+ const trimmedLines = stdout+ .split(/\r?\n/)+ .map((line) => line.trim())+ .filter(Boolean);+ const models: string[] = [];+ let defaultModel: string | null = null;+ let authenticated = false;+ let inModelsBlock = false;++ for (const line of trimmedLines) {+ if (/logged in/i.test(line)) authenticated = true;+ const defaultMatch = /^Default model:\s*(.+)$/i.exec(line);+ if (defaultMatch?.[1]) {+ defaultModel = defaultMatch[1].trim();+ continue;+ }+ if (/^Available models:/i.test(line)) {+ inModelsBlock = true;+ continue;+ }+ if (!inModelsBlock) continue;+ const bulletMatch = /^[*-]\s*(.+?)(?:\s+\(default\))?$/.exec(line);+ if (bulletMatch?.[1]) {+ models.push(bulletMatch[1].trim());+ continue;+ }+ if (line.length > 0) {+ models.push(line.replace(/\s+\(default\)$/, "").trim());+ }+ }++ return {+ authenticated,+ defaultModel,+ models: Array.from(new Set(models.filter(Boolean))),+ };+}++export async function testEnvironment(+ ctx: AdapterEnvironmentTestContext,+): Promise<AdapterEnvironmentTestResult> {+ const checks: AdapterEnvironmentCheck[] = [];+ const config = parseObject(ctx.config);+ const command = asString(config.command, "grok");+ const target = ctx.executionTarget ?? null;+ const targetIsRemote = target?.kind === "remote";+ const cwd = resolveAdapterExecutionTargetCwd(target, asString(config.cwd, ""), process.cwd());+ const targetLabel = targetIsRemote+ ? ctx.environmentName ?? describeAdapterExecutionTarget(target)+ : null;+ const runId = `grok-envtest-${Date.now()}-${Math.random().toString(16).slice(2)}`;++ if (targetLabel) {+ checks.push({+ code: "grok_environment_target",+ level: "info",+ message: `Probing inside environment: ${targetLabel}`,+ });+ }++ try {+ await ensureAdapterExecutionTargetDirectory(runId, target, cwd, {+ cwd,+ env: {},+ createIfMissing: true,+ });+ checks.push({+ code: "grok_cwd_valid",+ level: "info",+ message: `Working directory is valid: ${cwd}`,+ });+ } catch (err) {+ checks.push({+ code: "grok_cwd_invalid",+ level: "error",+ message: err instanceof Error ? err.message : "Invalid working directory",+ detail: cwd,+ });+ }++ const env = normalizeEnv(config.env);+ const runtimeEnv = ensurePathInEnv({ ...process.env, ...env });++ try {+ await ensureAdapterExecutionTargetCommandResolvable(command, target, cwd, runtimeEnv);+ checks.push({+ code: "grok_command_resolvable",+ level: "info",+ message: `Command is executable: ${command}`,+ });+ } catch (err) {+ checks.push({+ code: "grok_command_unresolvable",+ level: "error",+ message: err instanceof Error ? err.message : "Command is not executable",+ detail: command,+ });+ }++ const canRunProbe =+ checks.every((check) => check.code !== "grok_cwd_invalid" && check.code !== "grok_command_unresolvable");++ const configuredModel = asString(config.model, DEFAULT_GROK_LOCAL_MODEL).trim();++ if (canRunProbe) {+ const modelsProbe = await runAdapterExecutionTargetProcess(+ runId,+ target,+ command,+ ["models"],+ {+ cwd,+ env,+ timeoutSec: Math.max(1, asNumber(config.helloProbeTimeoutSec, 45)),+ graceSec: 5,+ onLog: async () => {},+ },+ );++ const probeOutput = `${modelsProbe.stdout}\n${modelsProbe.stderr}`;+ const parsedModels = parseGrokModelsOutput(modelsProbe.stdout);+ const authRequired = GROK_AUTH_REQUIRED_RE.test(probeOutput);++ if (modelsProbe.timedOut) {+ checks.push({+ code: "grok_models_probe_timed_out",+ level: "warn",+ message: "`grok models` timed out.",+ hint: "Retry the probe. If this persists, run `grok models` manually from the target environment.",+ });+ } else if ((modelsProbe.exitCode ?? 1) !== 0) {+ checks.push({+ code: authRequired ? "grok_auth_required" : "grok_models_probe_failed",+ level: authRequired ? "warn" : "error",+ message: authRequired+ ? "Grok CLI is not authenticated."+ : "`grok models` failed.",+ detail: summarizeProbeDetail(modelsProbe.stdout, modelsProbe.stderr, null),+ hint: authRequired ? "Run `grok login` on the target host, then retry." : undefined,+ });+ } else {+ checks.push({+ code: "grok_models_probe_passed",+ level: "info",+ message: parsedModels.authenticated+ ? "Grok CLI authentication is configured."+ : "`grok models` completed.",+ detail: parsedModels.defaultModel ? `Default model: ${parsedModels.defaultModel}` : undefined,+ });+ if (parsedModels.models.length > 0) {+ checks.push({+ code: "grok_models_discovered",+ level: "info",+ message: `Discovered ${parsedModels.models.length} Grok model(s).`,+ });+ } else {+ checks.push({+ code: "grok_models_empty",+ level: "warn",+ message: "Grok returned no available models.",+ hint: "Run `grok models` manually and verify the account has access to a model.",+ });+ }+ if (configuredModel) {+ checks.push({+ code: parsedModels.models.includes(configuredModel) ? "grok_model_configured" : "grok_model_not_found",+ level: parsedModels.models.includes(configuredModel) ? "info" : "warn",+ message: parsedModels.models.includes(configuredModel)+ ? `Configured model: ${configuredModel}`+ : `Configured model "${configuredModel}" not found in available models.`,+ hint: parsedModels.models.includes(configuredModel)+ ? undefined+ : "Run `grok models` and choose an available model id.",+ });+ }+ }+ }++ if (canRunProbe) {+ const probeArgs = [+ "--output-format",+ "streaming-json",+ "--always-approve",+ "--permission-mode",+ "dontAsk",+ "--disable-web-search",+ ];+ if (configuredModel && configuredModel !== DEFAULT_GROK_LOCAL_MODEL) {+ probeArgs.push("--model", configuredModel);+ }+ probeArgs.push("--single", "Respond with exactly hello.");++ const helloProbe = await runAdapterExecutionTargetProcess(+ runId,+ target,+ command,+ probeArgs,+ {+ cwd,+ env,+ timeoutSec: Math.max(1, asNumber(config.helloProbeTimeoutSec, 45)),+ graceSec: 5,+ onLog: async () => {},+ },+ );+ const parsed = parseGrokJsonl(helloProbe.stdout);+ const detail = summarizeProbeDetail(helloProbe.stdout, helloProbe.stderr, parsed.errorMessage);+ const authRequired = GROK_AUTH_REQUIRED_RE.test(`${helloProbe.stdout}\n${helloProbe.stderr}`);++ if (helloProbe.timedOut) {+ checks.push({+ code: "grok_hello_probe_timed_out",+ level: "warn",+ message: "Grok hello probe timed out.",+ hint: "Retry the probe. If this persists, verify Grok can run a simple `--single` prompt manually.",+ });+ } else if ((helloProbe.exitCode ?? 1) !== 0) {+ checks.push({+ code: authRequired ? "grok_hello_probe_auth_required" : "grok_hello_probe_failed",+ level: authRequired ? "warn" : "error",+ message: authRequired+ ? "Grok CLI could not answer the hello probe because authentication is missing."+ : "Grok hello probe failed.",+ ...(detail ? { detail } : {}),+ hint: authRequired ? "Run `grok login` on the target host, then retry." : undefined,+ });+ } else if (/\bhello\b/i.test(parsed.summary)) {+ checks.push({+ code: "grok_hello_probe_passed",+ level: "info",+ message: "Grok hello probe succeeded.",+ });+ } else {+ checks.push({+ code: "grok_hello_probe_unexpected_output",+ level: "warn",+ message: "Grok hello probe succeeded but returned unexpected output.",+ ...(detail ? { detail } : {}),+ });+ }+ }++ return {+ adapterType: "grok_local",+ status: summarizeStatus(checks),+ checks,+ testedAt: new Date().toISOString(),+ };+}diff --git a/packages/adapters/grok-local/src/ui/build-config.test.ts b/packages/adapters/grok-local/src/ui/build-config.test.tsnew file mode 100644index 0000000000..118a7494d3--- /dev/null+++ b/packages/adapters/grok-local/src/ui/build-config.test.ts@@ -0,0 +1,26 @@+import { describe, expect, it } from "vitest";+import { buildGrokLocalConfig } from "./build-config.js";++describe("buildGrokLocalConfig", () => {+ it("maps create-form values into adapter config", () => {+ expect(buildGrokLocalConfig({+ cwd: "/tmp/project",+ instructionsFilePath: "/tmp/AGENTS.md",+ model: "grok-build",+ thinkingEffort: "high",+ envVars: "XAI_API_KEY=secret\n",+ extraArgs: "--check, --verbatim",+ } as never)).toEqual({+ cwd: "/tmp/project",+ instructionsFilePath: "/tmp/AGENTS.md",+ model: "grok-build",+ timeoutSec: 0,+ graceSec: 20,+ reasoningEffort: "high",+ env: {+ XAI_API_KEY: { type: "plain", value: "secret" },+ },+ extraArgs: ["--check", "--verbatim"],+ });+ });+});diff --git a/packages/adapters/grok-local/src/ui/build-config.ts b/packages/adapters/grok-local/src/ui/build-config.tsnew file mode 100644index 0000000000..6c9e9a66d5--- /dev/null+++ b/packages/adapters/grok-local/src/ui/build-config.ts@@ -0,0 +1,74 @@+import type { CreateConfigValues } from "@paperclipai/adapter-utils";+import { DEFAULT_GROK_LOCAL_MODEL } from "../index.js";++function parseCommaArgs(value: string): string[] {+ return value+ .split(",")+ .map((item) => item.trim())+ .filter(Boolean);+}++function parseEnvVars(text: string): Record<string, string> {+ const env: Record<string, string> = {};+ for (const line of text.split(/\r?\n/)) {+ const trimmed = line.trim();+ if (!trimmed || trimmed.startsWith("#")) continue;+ const eq = trimmed.indexOf("=");+ if (eq <= 0) continue;+ const key = trimmed.slice(0, eq).trim();+ const value = trimmed.slice(eq + 1);+ if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;+ env[key] = value;+ }+ return env;+}++function parseEnvBindings(bindings: unknown): Record<string, unknown> {+ if (typeof bindings !== "object" || bindings === null || Array.isArray(bindings)) return {};+ const env: Record<string, unknown> = {};+ for (const [key, raw] of Object.entries(bindings)) {+ if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;+ if (typeof raw === "string") {+ env[key] = { type: "plain", value: raw };+ continue;+ }+ if (typeof raw !== "object" || raw === null || Array.isArray(raw)) continue;+ const rec = raw as Record<string, unknown>;+ if (rec.type === "plain" && typeof rec.value === "string") {+ env[key] = { type: "plain", value: rec.value };+ continue;+ }+ if (rec.type === "secret_ref" && typeof rec.secretId === "string") {+ env[key] = {+ type: "secret_ref",+ secretId: rec.secretId,+ ...(typeof rec.version === "number" || rec.version === "latest"+ ? { version: rec.version }+ : {}),+ };+ }+ }+ return env;+}++export function buildGrokLocalConfig(v: CreateConfigValues): Record<string, unknown> {+ const ac: Record<string, unknown> = {};+ if (v.cwd) ac.cwd = v.cwd;+ if (v.instructionsFilePath) ac.instructionsFilePath = v.instructionsFilePath;+ ac.model = v.model || DEFAULT_GROK_LOCAL_MODEL;+ ac.timeoutSec = 0;+ ac.graceSec = 20;+ if (v.thinkingEffort) ac.reasoningEffort = v.thinkingEffort;+ const env = parseEnvBindings(v.envBindings);+ const legacy = parseEnvVars(v.envVars);+ for (const [key, value] of Object.entries(legacy)) {+ if (!Object.prototype.hasOwnProperty.call(env, key)) {+ env[key] = { type: "plain", value };+ }+ }+ if (Object.keys(env).length > 0) ac.env = env;++ if (v.command) ac.command = v.command;+ if (v.extraArgs) ac.extraArgs = parseCommaArgs(v.extraArgs);+ return ac;+}diff --git a/packages/adapters/grok-local/src/ui/index.ts b/packages/adapters/grok-local/src/ui/index.tsnew file mode 100644index 0000000000..a37e3d825d--- /dev/null+++ b/packages/adapters/grok-local/src/ui/index.ts@@ -0,0 +1,2 @@+export { parseGrokStdoutLine } from "./parse-stdout.js";+export { buildGrokLocalConfig } from "./build-config.js";diff --git a/packages/adapters/grok-local/src/ui/parse-stdout.test.ts b/packages/adapters/grok-local/src/ui/parse-stdout.test.tsnew file mode 100644index 0000000000..d60b5b619a--- /dev/null+++ b/packages/adapters/grok-local/src/ui/parse-stdout.test.ts@@ -0,0 +1,27 @@+import { describe, expect, it } from "vitest";+import { parseGrokStdoutLine } from "./parse-stdout.js";++describe("parseGrokStdoutLine", () => {+ const ts = "2026-05-15T00:00:00.000Z";++ it("maps thought/text/end events into transcript entries", () => {+ expect(parseGrokStdoutLine(JSON.stringify({ type: "thought", data: "Plan first." }), ts)).toEqual([+ { kind: "thinking", ts, text: "Plan first.", delta: true },+ ]);+ expect(parseGrokStdoutLine(JSON.stringify({ type: "text", data: "hello" }), ts)).toEqual([+ { kind: "assistant", ts, text: "hello", delta: true },+ ]);+ expect(parseGrokStdoutLine(JSON.stringify({ type: "end", stopReason: "EndTurn", sessionId: "sess-1" }), ts)).toEqual([+ { kind: "system", ts, text: "stop_reason=EndTurn session=sess-1" },+ ]);+ });++ it("surfaces structured Grok error payload text", () => {+ expect(parseGrokStdoutLine(JSON.stringify({+ type: "error",+ error: { message: "Authentication required" },+ }), ts)).toEqual([+ { kind: "stderr", ts, text: "Authentication required" },+ ]);+ });+});diff --git a/packages/adapters/grok-local/src/ui/parse-stdout.ts b/packages/adapters/grok-local/src/ui/parse-stdout.tsnew file mode 100644index 0000000000..b82a36b464--- /dev/null+++ b/packages/adapters/grok-local/src/ui/parse-stdout.ts@@ -0,0 +1,61 @@+import type { TranscriptEntry } from "@paperclipai/adapter-utils";++function safeJsonParse(text: string): unknown {+ try {+ return JSON.parse(text);+ } catch {+ return null;+ }+}++function asRecord(value: unknown): Record<string, unknown> | null {+ if (typeof value !== "object" || value === null || Array.isArray(value)) return null;+ return value as Record<string, unknown>;+}++function asString(value: unknown, fallback = ""): string {+ return typeof value === "string" ? value : fallback;+}++function extractErrorText(value: unknown): string {+ if (typeof value === "string") return value;+ const record = asRecord(value);+ if (!record) return "";+ return asString(record.message) || asString(record.detail) || asString(record.code);+}++export function parseGrokStdoutLine(line: string, ts: string): TranscriptEntry[] {+ const parsed = asRecord(safeJsonParse(line));+ if (!parsed) {+ return [{ kind: "stdout", ts, text: line }];+ }++ const type = asString(parsed.type).trim();++ if (type === "thought") {+ const text = asString(parsed.data);+ return text ? [{ kind: "thinking", ts, text, delta: true }] : [];+ }++ if (type === "text") {+ const text = asString(parsed.data);+ return text ? [{ kind: "assistant", ts, text, delta: true }] : [];+ }++ if (type === "error") {+ const text = asString(parsed.data) || asString(parsed.message) || extractErrorText(parsed.error);+ return text ? [{ kind: "stderr", ts, text }] : [{ kind: "stderr", ts, text: "Grok error" }];+ }++ if (type === "end") {+ const stopReason = asString(parsed.stopReason).trim();+ const sessionId = asString(parsed.sessionId).trim();+ const parts = [+ stopReason ? `stop_reason=${stopReason}` : "",+ sessionId ? `session=${sessionId}` : "",+ ].filter(Boolean);+ return [{ kind: "system", ts, text: parts.join(" ") || "run completed" }];+ }++ return [{ kind: "system", ts, text: `event: ${type || "unknown"}` }];+}diff --git a/packages/adapters/grok-local/tsconfig.json b/packages/adapters/grok-local/tsconfig.jsonnew file mode 100644index 0000000000..2f355cfeeb--- /dev/null+++ b/packages/adapters/grok-local/tsconfig.json@@ -0,0 +1,8 @@+{+ "extends": "../../../tsconfig.json",+ "compilerOptions": {+ "outDir": "dist",+ "rootDir": "src"+ },+ "include": ["src"]+}diff --git a/scripts/release-package-manifest.json b/scripts/release-package-manifest.jsonindex 954c258e71..81bb12f22c 100644--- a/scripts/release-package-manifest.json+++ b/scripts/release-package-manifest.json@@ -34,6 +34,11 @@"name": "@paperclipai/adapter-gemini-local","publishFromCi": true},+ {+ "dir": "packages/adapters/grok-local",+ "name": "@paperclipai/adapter-grok-local",+ "publishFromCi": false+ },{"dir": "packages/adapters/opencode-local","name": "@paperclipai/adapter-opencode-local",diff --git a/server/package.json b/server/package.jsonindex 2ea875b836..6855ba6bed 100644--- a/server/package.json+++ b/server/package.json@@ -50,6 +50,7 @@"@paperclipai/adapter-cursor-cloud": "workspace:*","@paperclipai/adapter-cursor-local": "workspace:*","@paperclipai/adapter-gemini-local": "workspace:*",+ "@paperclipai/adapter-grok-local": "workspace:*","@paperclipai/adapter-openclaw-gateway": "workspace:*","@paperclipai/adapter-opencode-local": "workspace:*","@paperclipai/adapter-pi-local": "workspace:*",diff --git a/server/src/__tests__/adapter-routes.test.ts b/server/src/__tests__/adapter-routes.test.tsindex 06c25c7fb8..b90869e664 100644--- a/server/src/__tests__/adapter-routes.test.ts+++ b/server/src/__tests__/adapter-routes.test.ts@@ -174,6 +174,15 @@ describe("adapter routes", () => {expect(cursorAdapter.capabilities.requiresMaterializedRuntimeSkills).toBe(true);expect(cursorAdapter.capabilities.supportsInstructionsBundle).toBe(true);+ const grokAdapter = res.body.find((a: any) => a.type === "grok_local");+ expect(grokAdapter).toBeDefined();+ expect(grokAdapter.capabilities).toMatchObject({+ supportsInstructionsBundle: true,+ supportsSkills: true,+ supportsLocalAgentJwt: true,+ requiresMaterializedRuntimeSkills: true,+ });+// hermes_local currently supports skills + local JWT, but not the managed// instructions bundle flow because the bundled adapter does not consume// instructionsFilePath at runtime.diff --git a/server/src/adapters/builtin-adapter-types.ts b/server/src/adapters/builtin-adapter-types.tsindex a30ed5cc43..bb96eb9962 100644--- a/server/src/adapters/builtin-adapter-types.ts+++ b/server/src/adapters/builtin-adapter-types.ts@@ -8,6 +8,7 @@ export const BUILTIN_ADAPTER_TYPES = new Set(["cursor_cloud","cursor","gemini_local",+ "grok_local","openclaw_gateway","opencode_local","pi_local",diff --git a/server/src/adapters/registry.ts b/server/src/adapters/registry.tsindex 32a748b646..abe73ea03a 100644--- a/server/src/adapters/registry.ts+++ b/server/src/adapters/registry.ts@@ -78,6 +78,17 @@ import {models as geminiModels,modelProfiles as geminiModelProfiles,} from "@paperclipai/adapter-gemini-local";+import {+ execute as grokExecute,+ listGrokSkills,+ syncGrokSkills,+ testEnvironment as grokTestEnvironment,+ sessionCodec as grokSessionCodec,+} from "@paperclipai/adapter-grok-local/server";+import {+ agentConfigurationDoc as grokAgentConfigurationDoc,+ models as grokModels,+} from "@paperclipai/adapter-grok-local";import {execute as openCodeExecute,listOpenCodeSkills,@@ -349,6 +360,27 @@ const geminiLocalAdapter: ServerAdapterModule = {agentConfigurationDoc: geminiAgentConfigurationDoc,};+const grokLocalAdapter: ServerAdapterModule = {+ type: "grok_local",+ execute: grokExecute,+ testEnvironment: grokTestEnvironment,+ listSkills: listGrokSkills,+ syncSkills: syncGrokSkills,+ sessionCodec: grokSessionCodec,+ sessionManagement: getAdapterSessionManagement("grok_local") ?? undefined,+ models: grokModels,+ supportsLocalAgentJwt: true,+ supportsInstructionsBundle: true,+ instructionsPathKey: "instructionsFilePath",+ requiresMaterializedRuntimeSkills: true,+ getRuntimeCommandSpec: (config) => ({+ command: readConfiguredCommand(config, "grok"),+ detectCommand: readConfiguredCommand(config, "grok"),+ installCommand: null,+ }),+ agentConfigurationDoc: grokAgentConfigurationDoc,+};+const openclawGatewayAdapter: ServerAdapterModule = {type: "openclaw_gateway",execute: openclawGatewayExecute,@@ -486,6 +518,7 @@ function registerBuiltInAdapters() {cursorCloudAdapter,cursorLocalAdapter,geminiLocalAdapter,+ grokLocalAdapter,openclawGatewayAdapter,hermesLocalAdapter,processAdapter,diff --git a/ui/package.json b/ui/package.jsonindex 7286053f52..4c3acec4de 100644--- a/ui/package.json+++ b/ui/package.json@@ -40,6 +40,7 @@"@paperclipai/adapter-cursor-cloud": "workspace:*","@paperclipai/adapter-cursor-local": "workspace:*","@paperclipai/adapter-gemini-local": "workspace:*",+ "@paperclipai/adapter-grok-local": "workspace:*","@paperclipai/adapter-openclaw-gateway": "workspace:*","@paperclipai/adapter-opencode-local": "workspace:*","@paperclipai/adapter-pi-local": "workspace:*",diff --git a/ui/src/adapters/adapter-display-registry.ts b/ui/src/adapters/adapter-display-registry.tsindex 948a3c8d69..ddd5dacbda 100644--- a/ui/src/adapters/adapter-display-registry.ts+++ b/ui/src/adapters/adapter-display-registry.ts@@ -78,6 +78,11 @@ const adapterDisplayMap: Record<string, AdapterDisplayInfo> = {description: "Local Gemini agent",icon: Gem,},+ grok_local: {+ label: "Grok Build",+ description: "Local Grok Build agent",+ icon: Bot,+ },opencode_local: {label: "OpenCode",description: "Local multi-provider agent",diff --git a/ui/src/adapters/grok-local/config-fields.tsx b/ui/src/adapters/grok-local/config-fields.tsxnew file mode 100644index 0000000000..13ab66a01c--- /dev/null+++ b/ui/src/adapters/grok-local/config-fields.tsx@@ -0,0 +1,51 @@+import type { AdapterConfigFieldsProps } from "../types";+import {+ DraftInput,+ Field,+} from "../../components/agent-config-primitives";+import { ChoosePathButton } from "../../components/PathInstructionsModal";++const inputClass =+ "w-full rounded-md border border-border px-2.5 py-1.5 bg-transparent outline-none text-sm font-mono placeholder:text-muted-foreground/40";+const instructionsFileHint =+ "Absolute path to a markdown file (e.g. AGENTS.md) that defines this agent's behavior. Paperclip stages it into the Grok workspace as Agents.md when possible.";++export function GrokLocalConfigFields({+ isCreate,+ values,+ set,+ config,+ eff,+ mark,+ hideInstructionsFile,+}: AdapterConfigFieldsProps) {+ if (hideInstructionsFile) return null;+ return (+ <>+ <Field label="Agent instructions file" hint={instructionsFileHint}>+ <div className="flex items-center gap-2">+ <DraftInput+ value={+ isCreate+ ? values!.instructionsFilePath ?? ""+ : eff(+ "adapterConfig",+ "instructionsFilePath",+ String(config.instructionsFilePath ?? ""),+ )+ }+ onCommit={(v) =>+ isCreate+ ? set!({ instructionsFilePath: v })+ : mark("adapterConfig", "instructionsFilePath", v || undefined)+ }+ immediate+ className={inputClass}+ placeholder="/absolute/path/to/AGENTS.md"+ />+ <ChoosePathButton />+ </div>+ </Field>+ </>+ );+}diff --git a/ui/src/adapters/grok-local/index.ts b/ui/src/adapters/grok-local/index.tsnew file mode 100644index 0000000000..13c579a0a2--- /dev/null+++ b/ui/src/adapters/grok-local/index.ts@@ -0,0 +1,12 @@+import type { UIAdapterModule } from "../types";+import { parseGrokStdoutLine } from "@paperclipai/adapter-grok-local/ui";+import { buildGrokLocalConfig } from "@paperclipai/adapter-grok-local/ui";+import { GrokLocalConfigFields } from "./config-fields";++export const grokLocalUIAdapter: UIAdapterModule = {+ type: "grok_local",+ label: "Grok Build (local)",+ parseStdoutLine: parseGrokStdoutLine,+ ConfigFields: GrokLocalConfigFields,+ buildAdapterConfig: buildGrokLocalConfig,+};diff --git a/ui/src/adapters/registry.ts b/ui/src/adapters/registry.tsindex 0e2f27a3a3..9b2476d3c8 100644--- a/ui/src/adapters/registry.ts+++ b/ui/src/adapters/registry.ts@@ -5,6 +5,7 @@ import { codexLocalUIAdapter } from "./codex-local";import { cursorCloudUIAdapter } from "./cursor-cloud";import { cursorLocalUIAdapter } from "./cursor";import { geminiLocalUIAdapter } from "./gemini-local";+import { grokLocalUIAdapter } from "./grok-local";import { openCodeLocalUIAdapter } from "./opencode-local";import { piLocalUIAdapter } from "./pi-local";import { openClawGatewayUIAdapter } from "./openclaw-gateway";@@ -56,6 +57,7 @@ function registerBuiltInUIAdapters() {codexLocalUIAdapter,cursorCloudUIAdapter,geminiLocalUIAdapter,+ grokLocalUIAdapter,hermesLocalUIAdapter,openCodeLocalUIAdapter,piLocalUIAdapter,diff --git a/ui/src/adapters/transcript.test.ts b/ui/src/adapters/transcript.test.tsindex ddd164a54d..56627f328a 100644--- a/ui/src/adapters/transcript.test.ts+++ b/ui/src/adapters/transcript.test.ts@@ -1,5 +1,6 @@import { describe, expect, it } from "vitest";import { buildTranscript, type RunLogChunk } from "./transcript";+import { grokLocalUIAdapter } from "./grok-local";import type { UIAdapterModule } from "./types";describe("buildTranscript", () => {@@ -182,4 +183,20 @@ describe("buildTranscript", () => {},]);});++ it("coalesces grok_local streaming text fragments into one assistant entry", () => {+ const entries = buildTranscript(+ [+ { ts, stream: "stdout", chunk: `${JSON.stringify({ type: "text", data: "Hello " })}\n` },+ { ts, stream: "stdout", chunk: `${JSON.stringify({ type: "text", data: "world" })}\n` },+ { ts, stream: "stdout", chunk: `${JSON.stringify({ type: "end", stopReason: "EndTurn", sessionId: "sess-1" })}\n` },+ ],+ grokLocalUIAdapter,+ );++ expect(entries).toEqual([+ { kind: "assistant", ts, text: "Hello world", delta: true },+ { kind: "system", ts, text: "stop_reason=EndTurn session=sess-1" },+ ]);+ });});diff --git a/ui/src/adapters/use-adapter-capabilities.ts b/ui/src/adapters/use-adapter-capabilities.tsindex 786776fe75..89f2c2b6c4 100644--- a/ui/src/adapters/use-adapter-capabilities.ts+++ b/ui/src/adapters/use-adapter-capabilities.ts@@ -21,6 +21,7 @@ const KNOWN_DEFAULTS: Record<string, AdapterCapabilities> = {codex_local: { supportsInstructionsBundle: true, supportsSkills: true, supportsLocalAgentJwt: true, requiresMaterializedRuntimeSkills: false, supportsModelProfiles: true },cursor: { supportsInstructionsBundle: true, supportsSkills: true, supportsLocalAgentJwt: true, requiresMaterializedRuntimeSkills: true, supportsModelProfiles: true },gemini_local: { supportsInstructionsBundle: true, supportsSkills: true, supportsLocalAgentJwt: true, requiresMaterializedRuntimeSkills: true, supportsModelProfiles: true },+ grok_local: { supportsInstructionsBundle: true, supportsSkills: true, supportsLocalAgentJwt: true, requiresMaterializedRuntimeSkills: true, supportsModelProfiles: false },opencode_local: { supportsInstructionsBundle: true, supportsSkills: true, supportsLocalAgentJwt: true, requiresMaterializedRuntimeSkills: true, supportsModelProfiles: true },pi_local: { supportsInstructionsBundle: true, supportsSkills: true, supportsLocalAgentJwt: true, requiresMaterializedRuntimeSkills: true, supportsModelProfiles: false },hermes_local: { supportsInstructionsBundle: false, supportsSkills: true, supportsLocalAgentJwt: true, requiresMaterializedRuntimeSkills: false, supportsModelProfiles: false },diff --git a/vitest.config.ts b/vitest.config.tsindex f27929e74f..3fe5677998 100644--- a/vitest.config.ts+++ b/vitest.config.ts@@ -12,6 +12,7 @@ export default defineConfig({"packages/adapters/cursor-cloud","packages/adapters/cursor-local","packages/adapters/gemini-local",+ "packages/adapters/grok-local","packages/adapters/opencode-local","packages/adapters/pi-local","packages/plugins/sdk",