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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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")(funcenabled: grokSettings.enabled,checkedAt,models,+ skills,probe: {installed: true,version,@@ -393,6 +400,7 @@ export const checkGrokProviderStatus = Effect.fn("checkGrokProviderStatus")(funcenabled: grokSettings.enabled,checkedAt,models,+ skills,probe: {installed: true,version,diff --git a/apps/server/src/provider/ProviderDriver.ts b/apps/server/src/provider/ProviderDriver.tsindex 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.mdindex 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 waiwrite before returning so a replacement prompt cannot race ahead of it. Grok mid-turn sends cancelthe 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 observationThe [ACP protocol](../../packages/effect-acp/src/protocol.ts) and