Skip to content

Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.

fix(grok): discover skills with grok inspect and fail workspace probes loudly (#225)

Leo3756d35cf7f1
diff --git a/apps/server/src/provider/Drivers/GrokDriver.test.ts b/apps/server/src/provider/Drivers/GrokDriver.test.ts
new file mode 100644
index 000000000..a6c3a3c8a
--- /dev/null
+++ b/apps/server/src/provider/Drivers/GrokDriver.test.ts
@@ -0,0 +1,226 @@
+// @effect-diagnostics nodeBuiltinImport:off preferSchemaOverJson:off
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { describe, expect, it } from "@effect/vitest";
+import { ProviderInstanceId } from "@t3tools/contracts";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import * as Stream from "effect/Stream";
+import { HttpClient, HttpClientResponse } from "effect/unstable/http";
+
+import * as BackgroundPolicy from "../../background/BackgroundPolicy.ts";
+import { ServerConfig } from "../../config.ts";
+import { layerTest as serverSettingsLayerTest } from "../../serverSettings.ts";
+import { ProviderDriverError } from "../Errors.ts";
+import { NoOpProviderEventLoggers, ProviderEventLoggers } from "../Layers/ProviderEventLoggers.ts";
+import { GrokDriver } from "./GrokDriver.ts";
+import { GrokSkillsProbeError } from "./GrokSkills.ts";
+
+const TEST_EPOCH = DateTime.makeUnsafe("1970-01-01T00:00:00.000Z");
+
+const TestHttpClientLive = Layer.succeed(
+ HttpClient.HttpClient,
+ HttpClient.make((request) =>
+ Effect.succeed(HttpClientResponse.fromWeb(request, Response.json({ version: "0.0.0" }))),
+ ),
+);
+
+const BackgroundPolicyAlwaysRunLayer = Layer.mock(BackgroundPolicy.BackgroundPolicy)({
+ reportClientActivity: () => Effect.void,
+ removeRpcClient: () => Effect.void,
+ reportHostPowerState: () => Effect.void,
+ snapshot: Effect.succeed({
+ hostPower: {
+ source: "unknown",
+ idle: "unknown",
+ idleSeconds: null,
+ locked: "unknown",
+ suspended: false,
+ onBattery: "unknown",
+ lowPowerMode: "unknown",
+ thermalState: "unknown",
+ stale: true,
+ updatedAt: TEST_EPOCH,
+ },
+ leases: [],
+ activeForegroundLeaseCount: 0,
+ activeScopeKeys: [],
+ shouldRunOpportunisticWork: true,
+ updatedAt: TEST_EPOCH,
+ }),
+ streamChanges: Stream.empty,
+ hasDemand: () => Effect.succeed(true),
+ shouldRunScopeWork: () => Effect.succeed(true),
+ shouldRunOpportunisticWork: Effect.succeed(true),
+});
+
+const grokDriverTestLayer = Layer.mergeAll(
+ ServerConfig.layerTest(process.cwd(), { prefix: "akeru-grok-driver-test-" }).pipe(
+ Layer.provideMerge(NodeServices.layer),
+ ),
+ serverSettingsLayerTest(),
+ TestHttpClientLive,
+ Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers),
+ BackgroundPolicyAlwaysRunLayer,
+);
+
+const LOGGED_IN_MODELS_OUTPUT = [
+ "You are logged in with grok.com.",
+ "",
+ "Default model: grok-4.6",
+ "",
+ "Available models:",
+ " * grok-4.6 (default)",
+ "",
+].join("\n");
+
+const shellQuote = (value: string) => `'${value.replaceAll("'", `'\\''`)}'`;
+
+const writeFakeGrokCli = (input: {
+ readonly workspaceCwd: string;
+ readonly inspect: "skills" | "fail";
+}) =>
+ Effect.gen(function* () {
+ const fs = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ const dir = yield* fs.makeTempDirectoryScoped({ prefix: "akeru-grok-driver-cli-" });
+ const modelsPath = path.join(dir, "models.txt");
+ const machineSkillsPath = path.join(dir, "machine-skills.json");
+ const workspaceSkillsPath = path.join(dir, "workspace-skills.json");
+ const grokPath = path.join(dir, "grok");
+ yield* fs.writeFileString(modelsPath, LOGGED_IN_MODELS_OUTPUT);
+ yield* fs.writeFileString(
+ machineSkillsPath,
+ JSON.stringify({
+ skills: [
+ {
+ name: "machine-skill",
+ source: { type: "user", path: "/home/dev/.grok/skills/machine-skill/SKILL.md" },
+ },
+ ],
+ }),
+ );
+ yield* fs.writeFileString(
+ workspaceSkillsPath,
+ JSON.stringify({
+ skills: [
+ {
+ name: "project-skill",
+ source: {
+ type: "project",
+ path: `${input.workspaceCwd}/.grok/skills/project-skill/SKILL.md`,
+ },
+ },
+ ],
+ }),
+ );
+ const inspectCase =
+ input.inspect === "fail"
+ ? " inspect) exit 1;;"
+ : [
+ " inspect)",
+ ` if [ "$PWD" = ${shellQuote(input.workspaceCwd)} ]; then`,
+ ` cat ${shellQuote(workspaceSkillsPath)}; exit 0`,
+ " fi",
+ ` cat ${shellQuote(machineSkillsPath)}; exit 0;;`,
+ ].join("\n");
+ yield* fs.writeFileString(
+ grokPath,
+ [
+ "#!/bin/sh",
+ 'case "$1" in',
+ ' --version) printf "grok 1.0.13\\n"; exit 0;;',
+ ` models) cat ${shellQuote(modelsPath)}; exit 0;;`,
+ inspectCase,
+ " agent) exit 3;;",
+ "esac",
+ "exit 1",
+ "",
+ ].join("\n"),
+ );
+ yield* fs.chmod(grokPath, 0o755);
+ return grokPath;
+ });
+
+const createGrokInstance = (input: { readonly enabled: boolean; readonly binaryPath: string }) =>
+ GrokDriver.create({
+ instanceId: ProviderInstanceId.make("grok"),
+ displayName: undefined,
+ environment: [],
+ enabled: input.enabled,
+ config: { ...GrokDriver.defaultConfig(), binaryPath: input.binaryPath },
+ });
+
+it.layer(grokDriverTestLayer)("GrokDriver.snapshotForCwd", (it) => {
+ describe("workspace snapshots", () => {
+ it.effect("skips inspect and returns the machine snapshot when Grok is disabled", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const fs = yield* FileSystem.FileSystem;
+ const workspaceCwd = yield* fs.makeTempDirectoryScoped({
+ prefix: "akeru-grok-disabled-workspace-",
+ });
+ const grokPath = yield* writeFakeGrokCli({ workspaceCwd, inspect: "fail" });
+ const instance = yield* createGrokInstance({ enabled: false, binaryPath: grokPath });
+ expect(instance.snapshotForCwd).toBeTypeOf("function");
+
+ const machine = yield* instance.snapshot.getSnapshot;
+ const workspace = yield* instance.snapshotForCwd!(workspaceCwd);
+
+ expect(workspace).toEqual(machine);
+ expect(workspace.skills ?? []).toEqual([]);
+ }),
+ ),
+ );
+
+ it.effect("replaces machine skills with workspace inspect results", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const fs = yield* FileSystem.FileSystem;
+ const workspaceCwd = yield* fs.makeTempDirectoryScoped({
+ prefix: "akeru-grok-workspace-",
+ });
+ const grokPath = yield* writeFakeGrokCli({ workspaceCwd, inspect: "skills" });
+ const instance = yield* createGrokInstance({ enabled: true, binaryPath: grokPath });
+ const machine = yield* instance.snapshot.refresh;
+ const workspace = yield* instance.snapshotForCwd!(workspaceCwd);
+
+ expect(machine.skills?.map((skill) => skill.name)).toEqual(["machine-skill"]);
+ expect(workspace.skills).toEqual([
+ {
+ name: "project-skill",
+ path: `${workspaceCwd}/.grok/skills/project-skill/SKILL.md`,
+ scope: "project",
+ enabled: true,
+ },
+ ]);
+ }),
+ ),
+ );
+
+ it.effect("propagates inspect failures as ProviderDriverError", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const fs = yield* FileSystem.FileSystem;
+ const workspaceCwd = yield* fs.makeTempDirectoryScoped({
+ prefix: "akeru-grok-failed-workspace-",
+ });
+ const grokPath = yield* writeFakeGrokCli({ workspaceCwd, inspect: "fail" });
+ const instance = yield* createGrokInstance({ enabled: true, binaryPath: grokPath });
+
+ const machine = yield* instance.snapshot.refresh;
+ expect(machine.skills ?? []).toEqual([]);
+
+ const error = yield* instance.snapshotForCwd!(workspaceCwd).pipe(Effect.flip);
+ expect(error._tag).toBe("ProviderDriverError");
+ expect(error).toBeInstanceOf(ProviderDriverError);
+ expect(error.detail).toContain(`Failed to discover Grok skills for '${workspaceCwd}'`);
+ expect(error.cause).toBeInstanceOf(GrokSkillsProbeError);
+ expect((error.cause as GrokSkillsProbeError).stage).toBe("exit");
+ }),
+ ),
+ );
+ });
+});
diff --git a/apps/server/src/provider/Drivers/GrokDriver.ts b/apps/server/src/provider/Drivers/GrokDriver.ts
index 280a24d21..e5f05588f 100644
--- a/apps/server/src/provider/Drivers/GrokDriver.ts
+++ b/apps/server/src/provider/Drivers/GrokDriver.ts
@@ -18,6 +18,7 @@ import {
checkGrokProviderStatus,
enrichGrokSnapshot,
} from "../Layers/GrokProvider.ts";
+import { discoverGrokSkills } from "./GrokSkills.ts";
import { ProviderEventLoggers } from "../Layers/ProviderEventLoggers.ts";
import { makeManagedServerProvider } from "../makeManagedServerProvider.ts";
import {
@@ -149,6 +150,25 @@ export const GrokDriver: ProviderDriver<GrokSettings, GrokDriverEnv> = {
),
);
+ const snapshotForCwd = (workspaceCwd: string) =>
+ !effectiveConfig.enabled
+ ? snapshot.getSnapshot
+ : Effect.all([
+ snapshot.getSnapshot,
+ discoverGrokSkills(effectiveConfig, processEnv, workspaceCwd).pipe(
+ Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
+ Effect.mapError(
+ (cause) =>
+ new ProviderDriverError({
+ driver: DRIVER_KIND,
+ instanceId,
+ detail: `Failed to discover Grok skills for '${workspaceCwd}'`,
+ cause,
+ }),
+ ),
+ ),
+ ]).pipe(Effect.map(([machineSnapshot, skills]) => ({ ...machineSnapshot, skills })));
+
return {
instanceId,
driverKind: DRIVER_KIND,
@@ -157,6 +177,7 @@ export const GrokDriver: ProviderDriver<GrokSettings, GrokDriverEnv> = {
accentColor,
enabled,
snapshot,
+ snapshotForCwd,
adapter,
textGeneration,
} satisfies ProviderInstance;
diff --git a/apps/server/src/provider/Drivers/GrokSkills.test.ts b/apps/server/src/provider/Drivers/GrokSkills.test.ts
new file mode 100644
index 000000000..13415bc35
--- /dev/null
+++ b/apps/server/src/provider/Drivers/GrokSkills.test.ts
@@ -0,0 +1,143 @@
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Sink from "effect/Sink";
+import * as Stream from "effect/Stream";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import { discoverGrokSkills, parseGrokInspectSkills } from "./GrokSkills.ts";
+
+const inspectPayload = (skills: ReadonlyArray<unknown>) => JSON.stringify({ skills });
+
+describe("parseGrokInspectSkills", () => {
+ it("maps inspect entries onto provider skills, sorted by name", () => {
+ const skills = parseGrokInspectSkills(
+ inspectPayload([
+ {
+ name: "writing-docs",
+ description: "Write user docs.",
+ source: { type: "user", path: "/home/dev/.grok/skills/writing-docs/SKILL.md" },
+ userInvocable: true,
+ },
+ {
+ name: "deploy",
+ description: "Deploy the app.",
+ source: {
+ type: "plugin",
+ path: "/home/dev/.grok/installed-plugins/pkg/plug/skills/deploy/SKILL.md",
+ },
+ userInvocable: true,
+ },
+ ]),
+ );
+
+ expect(skills).toEqual([
+ {
+ name: "deploy",
+ description: "Deploy the app.",
+ path: "/home/dev/.grok/installed-plugins/pkg/plug/skills/deploy/SKILL.md",
+ scope: "plugin",
+ enabled: true,
+ },
+ {
+ name: "writing-docs",
+ description: "Write user docs.",
+ path: "/home/dev/.grok/skills/writing-docs/SKILL.md",
+ scope: "user",
+ enabled: true,
+ },
+ ]);
+ });
+
+ it("disables skills the CLI marks as not user-invocable", () => {
+ const skills = parseGrokInspectSkills(
+ inspectPayload([
+ {
+ name: "internal-helper",
+ source: { type: "bundled", path: "/opt/grok/bundled/skills/internal-helper/SKILL.md" },
+ userInvocable: false,
+ },
+ ]),
+ );
+
+ expect(skills).toEqual([
+ {
+ name: "internal-helper",
+ path: "/opt/grok/bundled/skills/internal-helper/SKILL.md",
+ scope: "bundled",
+ enabled: false,
+ },
+ ]);
+ });
+
+ it("skips entries without a name or a filesystem path", () => {
+ const skills = parseGrokInspectSkills(
+ inspectPayload([
+ { name: " ", source: { type: "user", path: "/tmp/skills/a/SKILL.md" } },
+ { name: "no-path", source: { type: "user" } },
+ { name: "no-source" },
+ "not-an-object",
+ { name: "kept", source: { type: "project", path: "/repo/.grok/skills/kept/SKILL.md" } },
+ ]),
+ );
+
+ expect(skills.map((skill) => skill.name)).toEqual(["kept"]);
+ });
+
+ it("returns an empty list for malformed or unexpected output", () => {
+ expect(parseGrokInspectSkills("not json")).toEqual([]);
+ expect(parseGrokInspectSkills("null")).toEqual([]);
+ expect(parseGrokInspectSkills(JSON.stringify({ skills: "nope" }))).toEqual([]);
+ expect(parseGrokInspectSkills(JSON.stringify({}))).toEqual([]);
+ });
+});
+
+describe("discoverGrokSkills", () => {
+ it.effect("spawns in the configured cwd and rejects a failed probe", () => {
+ const spawnCwds: Array<string | undefined> = [];
+ let exitCode = 0;
+ const spawner = ChildProcessSpawner.make((command) => {
+ spawnCwds.push(command._tag === "StandardCommand" ? command.options.cwd : undefined);
+ return Effect.succeed(
+ ChildProcessSpawner.makeHandle({
+ pid: ChildProcessSpawner.ProcessId(1),
+ exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(exitCode)),
+ isRunning: Effect.succeed(false),
+ kill: () => Effect.void,
+ unref: Effect.succeed(Effect.void),
+ stdin: Sink.drain,
+ stdout: Stream.encodeText(
+ Stream.make(
+ inspectPayload([
+ {
+ name: "kept",
+ source: { type: "project", path: "/workspaces/demo/.grok/skills/kept/SKILL.md" },
+ },
+ ]),
+ ),
+ ),
+ stderr: Stream.empty,
+ all: Stream.empty,
+ getInputFd: () => Sink.drain,
+ getOutputFd: () => Stream.empty,
+ }),
+ );
+ });
+
+ return Effect.gen(function* () {
+ const skills = yield* discoverGrokSkills({ binaryPath: "grok" }, {}, "/workspaces/demo").pipe(
+ Effect.provide(Layer.succeed(ChildProcessSpawner.ChildProcessSpawner, spawner)),
+ );
+
+ expect(spawnCwds).toEqual(["/workspaces/demo"]);
+ expect(skills.map((skill) => skill.name)).toEqual(["kept"]);
+
+ exitCode = 1;
+ const failed = yield* discoverGrokSkills({ binaryPath: "grok" }).pipe(
+ Effect.result,
+ Effect.provide(Layer.succeed(ChildProcessSpawner.ChildProcessSpawner, spawner)),
+ );
+ expect(failed._tag).toBe("Failure");
+ });
+ });
+});
diff --git a/apps/server/src/provider/Drivers/GrokSkills.ts b/apps/server/src/provider/Drivers/GrokSkills.ts
new file mode 100644
index 000000000..24f8aa069
--- /dev/null
+++ b/apps/server/src/provider/Drivers/GrokSkills.ts
@@ -0,0 +1,155 @@
+/**
+ * GrokSkills — skill discovery for the `$` picker via `grok inspect --json`.
+ *
+ * Unlike Claude Code, the Grok CLI reports its full skill catalog itself:
+ * `grok inspect --json` returns `skills[]` with `name`, `description`,
+ * `source.type` (`user` / `project` / `bundled` / `plugin`), `source.path`
+ * (the absolute `SKILL.md` path), and `userInvocable`. Asking the CLI beats
+ * scanning the filesystem because the catalog honors Grok's own skill config
+ * (ignore lists, disabled skills) and includes plugin skills, which live
+ * three levels deep under `~/.grok/installed-plugins/` where a flat scan
+ * cannot see them. This mirrors how the Codex app-server reports skills over
+ * `skills/list`. Probe failures stay typed so workspace snapshots do not
+ * cache an empty catalog; machine-level discovery recovers them to an empty
+ * list without degrading the provider.
+ *
+ * @module provider/Drivers/GrokSkills
+ */
+import type { GrokSettings, ServerProviderSkill } from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { ChildProcess } from "effect/unstable/process";
+import { resolveSpawnCommand } from "@t3tools/shared/shell";
+
+import { spawnAndCollect } from "../providerSnapshot.ts";
+
+const GROK_SKILLS_PROBE_TIMEOUT_MS = 4_000;
+
+export class GrokSkillsProbeError extends Schema.TaggedErrorClass<GrokSkillsProbeError>()(
+ "GrokSkillsProbeError",
+ {
+ stage: Schema.Literals(["spawn", "timeout", "exit", "decode"]),
+ cwd: Schema.optional(Schema.String),
+ exitCode: Schema.optional(Schema.Number),
+ cause: Schema.optional(Schema.Defect()),
+ },
+) {
+ override get message(): string {
+ const location = this.cwd === undefined ? "" : ` for '${this.cwd}'`;
+ const exitCode = this.exitCode === undefined ? "" : ` with exit code ${this.exitCode}`;
+ return `\`grok inspect --json\` failed during ${this.stage}${location}${exitCode}.`;
+ }
+}
+
+/**
+ * Map `grok inspect --json` output onto provider skills. Entries without a
+ * name or a filesystem path are skipped; `userInvocable: false` skills are
+ * kept but disabled so pickers that filter on `enabled` hide them.
+ */
+function decodeGrokInspectSkills(stdout: string): ReadonlyArray<ServerProviderSkill> | undefined {
+ let parsed: unknown;
+ try {
+ parsed = JSON.parse(stdout);
+ } catch {
+ return undefined;
+ }
+ if (typeof parsed !== "object" || parsed === null) {
+ return undefined;
+ }
+ const entries = (parsed as Record<string, unknown>).skills;
+ if (!Array.isArray(entries)) {
+ return undefined;
+ }
+
+ const skillsByName = new Map<string, ServerProviderSkill>();
+ for (const entry of entries) {
+ if (typeof entry !== "object" || entry === null) {
+ continue;
+ }
+ const record = entry as Record<string, unknown>;
+ const name = typeof record.name === "string" ? record.name.trim() : "";
+ const source =
+ typeof record.source === "object" && record.source !== null
+ ? (record.source as Record<string, unknown>)
+ : undefined;
+ const path = typeof source?.path === "string" ? source.path.trim() : "";
+ if (!name || !path) {
+ continue;
+ }
+ const scope = typeof source?.type === "string" ? source.type.trim() : "";
+ const description = typeof record.description === "string" ? record.description.trim() : "";
+ skillsByName.set(name, {
+ name,
+ path,
+ enabled: record.userInvocable !== false,
+ ...(scope ? { scope } : {}),
+ ...(description ? { description } : {}),
+ });
+ }
+
+ return [...skillsByName.values()].sort((left, right) => left.name.localeCompare(right.name));
+}
+
+export function parseGrokInspectSkills(stdout: string): ReadonlyArray<ServerProviderSkill> {
+ return decodeGrokInspectSkills(stdout) ?? [];
+}
+
+/**
+ * Run `grok inspect --json` and map the reported catalog onto provider
+ * skills. Callers that need best-effort discovery can recover this effect to
+ * an empty list; workspace callers leave failures typed so they are not cached.
+ */
+export const discoverGrokSkills = Effect.fn("discoverGrokSkills")(function* (
+ grokSettings: Pick<GrokSettings, "binaryPath">,
+ environment: NodeJS.ProcessEnv = process.env,
+ cwd?: string,
+) {
+ const command = grokSettings.binaryPath || "grok";
+ const inspectResult = yield* Effect.gen(function* () {
+ const spawnCommand = yield* resolveSpawnCommand(command, ["inspect", "--json"], {
+ env: environment,
+ });
+ return yield* spawnAndCollect(
+ command,
+ ChildProcess.make(spawnCommand.command, spawnCommand.args, {
+ ...(cwd ? { cwd } : {}),
+ env: environment,
+ shell: spawnCommand.shell,
+ }),
+ );
+ }).pipe(
+ Effect.mapError(
+ (cause) =>
+ new GrokSkillsProbeError({
+ stage: "spawn",
+ ...(cwd ? { cwd } : {}),
+ cause,
+ }),
+ ),
+ Effect.timeoutOption(GROK_SKILLS_PROBE_TIMEOUT_MS),
+ );
+
+ if (Option.isNone(inspectResult)) {
+ return yield* new GrokSkillsProbeError({
+ stage: "timeout",
+ ...(cwd ? { cwd } : {}),
+ });
+ }
+ const output = inspectResult.value;
+ if (output.code !== 0) {
+ return yield* new GrokSkillsProbeError({
+ stage: "exit",
+ ...(cwd ? { cwd } : {}),
+ exitCode: output.code,
+ });
+ }
+ const skills = decodeGrokInspectSkills(output.stdout);
+ if (!skills) {
+ return yield* new GrokSkillsProbeError({
+ stage: "decode",
+ ...(cwd ? { cwd } : {}),
+ });
+ }
+ return skills;
+});
diff --git a/apps/server/src/provider/Layers/GrokProvider.ts b/apps/server/src/provider/Layers/GrokProvider.ts
index 84405891e..1a8327bf7 100644
--- a/apps/server/src/provider/Layers/GrokProvider.ts
+++ b/apps/server/src/provider/Layers/GrokProvider.ts
@@ -32,6 +32,7 @@ import {
type ProviderMaintenanceCapabilities,
} from "../providerMaintenance.ts";
import { sessionModelStateFromInitialize } from "../acp/AcpRuntimeModel.ts";
+import { discoverGrokSkills } from "../Drivers/GrokSkills.ts";
import {
GROK_DEFAULT_MODEL_SLUG,
makeGrokAcpRuntime,
@@ -354,6 +355,11 @@ export const checkGrokProviderStatus = Effect.fn("checkGrokProviderStatus")(func
? { status: "unauthenticated" }
: { status: "unknown" };
+ const skills = yield* discoverGrokSkills(grokSettings, environment).pipe(
+ Effect.tapError((cause) => Effect.logDebug("Grok skill discovery failed.", { cause })),
+ Effect.orElseSucceed(() => []),
+ );
+
const acpExit = yield* discoverGrokModelsViaAcpInitialize(grokSettings, environment).pipe(
Effect.timeoutOption(GROK_ACP_INITIALIZE_TIMEOUT_MS),
Effect.exit,
@@ -378,6 +384,7 @@ export const checkGrokProviderStatus = Effect.fn("checkGrokProviderStatus")(func
enabled: grokSettings.enabled,
checkedAt,
models,
+ skills,
probe: {
installed: true,
version,
@@ -393,6 +400,7 @@ export const checkGrokProviderStatus = Effect.fn("checkGrokProviderStatus")(func
enabled: grokSettings.enabled,
checkedAt,
models,
+ skills,
probe: {
installed: true,
version,
diff --git a/apps/server/src/provider/ProviderDriver.ts b/apps/server/src/provider/ProviderDriver.ts
index c01e374e1..866e418c3 100644
--- a/apps/server/src/provider/ProviderDriver.ts
+++ b/apps/server/src/provider/ProviderDriver.ts
@@ -25,6 +25,7 @@ import type {
ProviderDriverKind,
ProviderInstanceEnvironment,
ProviderInstanceId,
+ ServerProvider,
} from "@t3tools/contracts";
import type * as Effect from "effect/Effect";
import type * as Schema from "effect/Schema";
@@ -69,6 +70,13 @@ export interface ProviderInstance {
readonly accentColor?: string | undefined;
readonly enabled: boolean;
readonly snapshot: ServerProviderShape;
+ /**
+ * Optional workspace-scoped snapshot. Grok uses this to probe `grok inspect --json`
+ * in the thread cwd so project skills are not cached as an empty machine catalog.
+ */
+ readonly snapshotForCwd?: (
+ workspaceCwd: string,
+ ) => Effect.Effect<ServerProvider, ProviderDriverError>;
/** Present for legacy/provider-native session transports. Mastra-native drivers omit it. */
readonly adapter: ProviderAdapterShape<ProviderAdapterError> | undefined;
/** Present when the provider supports app-level title and source-control writing. */
diff --git a/docs/internals/providers.md b/docs/internals/providers.md
index e843d72ae..4c16c9684 100644
--- a/docs/internals/providers.md
+++ b/docs/internals/providers.md
@@ -102,6 +102,12 @@ agent was previously lenient and hid the bug. `AcpSessionRuntime.cancel` now wai
write before returning so a replacement prompt cannot race ahead of it. Grok mid-turn sends cancel
the in-flight prompt and continue the same turn instead of queueing.
+Grok skill discovery uses `grok inspect --json`. Machine-level health checks recover probe
+failures to an empty skill list. `ProviderInstance.snapshotForCwd` re-runs inspect in the
+thread workspace so a failed probe is not cached as empty. Composer cwd refresh still uses the
+machine snapshot until a client calls `snapshotForCwd`. Cursor composer wiring from the same
+upstream PR is not in this change.
+
## Raw protocol observation
The [ACP protocol](../../packages/effect-acp/src/protocol.ts) and