A desktop coding agent with free access to frontier models.
TypeScript
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import {
composeOmniRushExtensionDiscoveryInstruction,
composeSkillAuthoringInstruction,
composeSteeringFromEngineMcpStatus,
OMNIRUSH_CLOUD_CONNECTION_INSTRUCTION,
OMNIRUSH_CLOUD_SKILL_AUTHORING_INSTRUCTION,
OMNIRUSH_CONNECT_DISABLED_INSTRUCTION,
OMNIRUSH_CONNECT_SIGN_IN_INSTRUCTION,
OMNIRUSH_EXTENSION_DISCOVERY_INSTRUCTION,
OMNIRUSH_LOCAL_SKILL_AUTHORING_INSTRUCTION,
resetOmniRushExtensionDiscoveryInstructionCacheForTests,
resolveOmniRushExtensionDiscoveryInstruction,
type OmniRushEngineMcpStatusClient,
type OmniRushExtensionConnectState,
} from "./omnirush-extensions-preview-steering.js";
type CloudHealth = NonNullable<OmniRushExtensionConnectState["cloudHealth"]>;
type CloudFailure = NonNullable<CloudHealth["firstFailure"]>;
const originalServerUrl = process.env.OMNIRUSH_SERVER_URL;
const originalServerToken = process.env.OMNIRUSH_SERVER_TOKEN;
const UNCHANGED_EXTENSION_DISCOVERY_INSTRUCTION =
"If the user asks for something you cannot do with obvious built-in tools, check the app's extensions before saying the capability is unavailable. Use app_query with id extension.actions to inspect available extension actions, then app_execute with id extension.call for the matching action.";
beforeEach(() => {
resetOmniRushExtensionDiscoveryInstructionCacheForTests();
});
afterEach(() => {
resetOmniRushExtensionDiscoveryInstructionCacheForTests();
if (originalServerUrl === undefined) delete process.env.OMNIRUSH_SERVER_URL;
else process.env.OMNIRUSH_SERVER_URL = originalServerUrl;
if (originalServerToken === undefined) delete process.env.OMNIRUSH_SERVER_TOKEN;
else process.env.OMNIRUSH_SERVER_TOKEN = originalServerToken;
});
function health(overrides: Partial<NonNullable<OmniRushExtensionConnectState["cloudHealth"]>> = {}): NonNullable<OmniRushExtensionConnectState["cloudHealth"]> {
return {
usable: true,
usableByCurrentModel: true,
phase: "ready",
workspace: { id: "ws_1", directory: "/tmp/ws_1" },
desired: { present: true, revision: "rev_ready" },
firstFailure: null,
...overrides,
};
}
function failure(code: string, overrides: Partial<CloudFailure> = {}): CloudFailure {
return {
code,
stage: overrides.stage ?? "test",
recommendedAction: overrides.recommendedAction ?? "Check Settings → Connect.",
message: overrides.message ?? "test failure",
};
}
function expectNoDegradedSteering(instruction: string): void {
expect(instruction).not.toMatch(/not ready/i);
expect(instruction).not.toContain("Repair and test");
expect(instruction).not.toContain("Do not use OmniRush.ai documentation tools");
expect(instruction).not.toContain("Do not substitute docs");
expect(instruction).not.toContain("as a substitute for performing an action against a connected service");
expect(instruction).not.toMatch(/do NOT use/i);
expect(instruction).not.toMatch(/Do not try/);
}
function state(cloudHealth: OmniRushExtensionConnectState["cloudHealth"]): OmniRushExtensionConnectState {
return {
connectEnabled: true,
connectCatalogEnabled: true,
cloudMcpPresent: cloudHealth?.usable === true,
cloudHealth,
workspace: { resolution: "resolved", id: "ws_1", directory: "/tmp/ws_1" },
googleWorkspace: { legacyConfigured: false },
};
}
function engineMcpClient(result: unknown, requests: unknown[] = []): OmniRushEngineMcpStatusClient {
return {
mcp: {
status: async (request) => {
requests.push(request);
return result;
},
},
};
}
describe("composeSteeringFromEngineMcpStatus", () => {
test("maps engine MCP statuses to steering instructions", () => {
expect(composeSteeringFromEngineMcpStatus("connected")).toBe(OMNIRUSH_CLOUD_CONNECTION_INSTRUCTION);
expect(composeSteeringFromEngineMcpStatus("disabled")).toBe(OMNIRUSH_CONNECT_DISABLED_INSTRUCTION);
expect(composeSteeringFromEngineMcpStatus("needs_auth")).toBe(OMNIRUSH_CONNECT_SIGN_IN_INSTRUCTION);
expect(composeSteeringFromEngineMcpStatus("needs_client_registration")).toBe(OMNIRUSH_CONNECT_SIGN_IN_INSTRUCTION);
expect(composeSteeringFromEngineMcpStatus("failed")).toBe(OMNIRUSH_EXTENSION_DISCOVERY_INSTRUCTION);
expect(composeSteeringFromEngineMcpStatus("starting")).toBe(OMNIRUSH_EXTENSION_DISCOVERY_INSTRUCTION);
expect(composeSteeringFromEngineMcpStatus(undefined)).toBe(OMNIRUSH_EXTENSION_DISCOVERY_INSTRUCTION);
});
});
describe("composeOmniRushExtensionDiscoveryInstruction", () => {
test("keeps the fallback instruction byte-identical when state is unavailable or generic discovery is gated", () => {
expect(OMNIRUSH_EXTENSION_DISCOVERY_INSTRUCTION).toBe(UNCHANGED_EXTENSION_DISCOVERY_INSTRUCTION);
expect(composeOmniRushExtensionDiscoveryInstruction(null)).toBe(UNCHANGED_EXTENSION_DISCOVERY_INSTRUCTION);
expect(composeOmniRushExtensionDiscoveryInstruction({ ...state(null), connectCatalogEnabled: false })).toBe(UNCHANGED_EXTENSION_DISCOVERY_INSTRUCTION);
});
test("keeps fallback when only legacy Google Workspace is configured", () => {
expect(composeOmniRushExtensionDiscoveryInstruction({ ...state(null), googleWorkspace: { legacyConfigured: true } })).toBe(UNCHANGED_EXTENSION_DISCOVERY_INSTRUCTION);
});
test("steers ready Connect users to verified omnirush-cloud capabilities first", () => {
expect(OMNIRUSH_CLOUD_CONNECTION_INSTRUCTION).toContain("verified ready for this exact workspace/model");
// Tool mechanics and the "only name what search returns" rule live once in
// the base agent prompt; ready steering is the availability signal only.
expect(OMNIRUSH_CLOUD_CONNECTION_INSTRUCTION).not.toContain("omnirush-cloud_search_capabilities with");
expect(OMNIRUSH_CLOUD_CONNECTION_INSTRUCTION).not.toContain("available_skills");
expect(OMNIRUSH_CLOUD_CONNECTION_INSTRUCTION).not.toContain("A successful search proves");
expect(OMNIRUSH_CLOUD_CONNECTION_INSTRUCTION).not.toContain("Skill creation:");
expect(OMNIRUSH_CLOUD_CONNECTION_INSTRUCTION).not.toContain("Gmail");
expect(OMNIRUSH_CLOUD_CONNECTION_INSTRUCTION).not.toContain("image generation");
// The detailed Connect contract ships as the omnirush-cloud server's MCP
// initialize instructions, present exactly when this steering is chosen.
// Ready steering defers to it instead of restating it on every request.
expect(OMNIRUSH_CLOUD_CONNECTION_INSTRUCTION).toContain("server instructions in this prompt are authoritative for search-first discovery, MCP Apps, connection_status results, schema guidance, and retry rules");
expect(OMNIRUSH_CLOUD_CONNECTION_INSTRUCTION).not.toContain("relay connectionStatus.action exactly");
expect(OMNIRUSH_CLOUD_CONNECTION_INSTRUCTION).not.toContain("results are live, not cached");
expect(OMNIRUSH_CLOUD_CONNECTION_INSTRUCTION.length).toBeLessThan(600);
expect(composeOmniRushExtensionDiscoveryInstruction(state(health()))).toBe(OMNIRUSH_CLOUD_CONNECTION_INSTRUCTION);
expect(composeOmniRushExtensionDiscoveryInstruction({ ...state(health()), connectCatalogEnabled: false })).toBe(OMNIRUSH_CLOUD_CONNECTION_INSTRUCTION);
expect(composeOmniRushExtensionDiscoveryInstruction({ ...state(health()), googleWorkspace: { legacyConfigured: true } })).toBe(OMNIRUSH_CLOUD_CONNECTION_INSTRUCTION);
});
test("selects one compact skill-authoring prompt from verified Cloud access", () => {
expect(composeSkillAuthoringInstruction(OMNIRUSH_CLOUD_CONNECTION_INSTRUCTION)).toEqual({
mode: "cloud",
prompt: OMNIRUSH_CLOUD_SKILL_AUTHORING_INSTRUCTION,
});
expect(OMNIRUSH_CLOUD_SKILL_AUTHORING_INSTRUCTION).toContain("Skill creation: Cloud");
expect(OMNIRUSH_CLOUD_SKILL_AUTHORING_INSTRUCTION).toContain("retrieve and follow the listed create-skill remote skill");
expect(OMNIRUSH_CLOUD_SKILL_AUTHORING_INSTRUCTION).toContain("the Connect server's execute_capability tool");
expect(OMNIRUSH_CLOUD_SKILL_AUTHORING_INSTRUCTION).toContain("exact <capability>");
expect(OMNIRUSH_CLOUD_SKILL_AUTHORING_INSTRUCTION).toContain("in Cloud as a private plugin");
expect(OMNIRUSH_CLOUD_SKILL_AUTHORING_INSTRUCTION).toContain("use share-plugin when the user wants a specific person or team to use a skill");
expect(OMNIRUSH_CLOUD_SKILL_AUTHORING_INSTRUCTION).toContain("add-to-marketplace");
expect(OMNIRUSH_CLOUD_SKILL_AUTHORING_INSTRUCTION).toContain("add-user-to-marketplace");
expect(OMNIRUSH_CLOUD_SKILL_AUTHORING_INSTRUCTION).toContain("workspace-local skill");
expect(OMNIRUSH_CLOUD_SKILL_AUTHORING_INSTRUCTION).toContain("Do not create both copies");
expect(OMNIRUSH_CLOUD_SKILL_AUTHORING_INSTRUCTION).not.toContain("Skill creation: Local");
for (const instruction of [
OMNIRUSH_EXTENSION_DISCOVERY_INSTRUCTION,
OMNIRUSH_CONNECT_SIGN_IN_INSTRUCTION,
OMNIRUSH_CONNECT_DISABLED_INSTRUCTION,
]) {
expect(composeSkillAuthoringInstruction(instruction)).toEqual({
mode: "local",
prompt: OMNIRUSH_LOCAL_SKILL_AUTHORING_INSTRUCTION,
});
}
expect(OMNIRUSH_LOCAL_SKILL_AUTHORING_INSTRUCTION).toContain("Skill creation: Local");
expect(OMNIRUSH_LOCAL_SKILL_AUTHORING_INSTRUCTION).toContain("only when the user requests one");
expect(OMNIRUSH_LOCAL_SKILL_AUTHORING_INSTRUCTION).toContain(".opencode/skills/<skill-name>/SKILL.md");
expect(OMNIRUSH_LOCAL_SKILL_AUTHORING_INSTRUCTION).not.toContain("Skill creation: Cloud");
});
test("keeps neutral steering when provider projection is missing", () => {
const instruction = composeOmniRushExtensionDiscoveryInstruction(state(health({
usable: true,
usableByCurrentModel: false,
phase: "provider_projection_missing",
firstFailure: {
code: "provider_tool_projection_missing",
stage: "provider_projection",
recommendedAction: "Update OmniRush.ai",
message: "missing",
},
})));
expect(instruction).toBe(OMNIRUSH_EXTENSION_DISCOVERY_INSTRUCTION);
});
test("uses neutral, signed-out, and disabled branches", () => {
const neutral = composeOmniRushExtensionDiscoveryInstruction({ ...state(health({
usable: false,
phase: "cloud_tools_missing",
firstFailure: {
code: "cloud_tools_missing",
stage: "tool_registration",
recommendedAction: "Run reconcile",
message: "missing",
},
})), connectCatalogEnabled: false });
expect(neutral).toBe(OMNIRUSH_EXTENSION_DISCOVERY_INSTRUCTION);
expect(composeOmniRushExtensionDiscoveryInstruction({ ...state(health({
usable: false,
phase: "missing_desired",
desired: { present: false, revision: null },
firstFailure: {
code: "cloud_mcp_missing",
stage: "desired_config",
recommendedAction: "Connect OmniRush.ai Cloud",
message: "missing",
},
})), connectCatalogEnabled: false })).toBe(OMNIRUSH_CONNECT_SIGN_IN_INSTRUCTION);
expect(composeOmniRushExtensionDiscoveryInstruction({ ...state(health({
usable: false,
phase: "engine_disabled",
firstFailure: {
code: "cloud_mcp_disabled",
stage: "engine_delivery",
recommendedAction: "Enable",
message: "disabled",
},
})), connectCatalogEnabled: false })).toBe(OMNIRUSH_CONNECT_DISABLED_INSTRUCTION);
});
test("keeps neutral steering for probe-side server failures", () => {
expect(composeOmniRushExtensionDiscoveryInstruction(state(health({
usable: false,
phase: "ready",
engine: { status: "connected" },
firstFailure: {
code: "probe_unreachable",
stage: "tool_registration",
recommendedAction: "Check network",
message: "probe failed",
},
})))).toBe(OMNIRUSH_EXTENSION_DISCOVERY_INSTRUCTION);
expect(composeOmniRushExtensionDiscoveryInstruction(state(health({
usable: false,
phase: "cloud_tools_missing",
engine: { status: "connected" },
firstFailure: {
code: "cloud_tools_missing",
stage: "tool_registration",
recommendedAction: "Run reconcile",
message: "missing",
},
})))).toBe(OMNIRUSH_EXTENSION_DISCOVERY_INSTRUCTION);
});
test("keeps neutral steering for cloud_tools_missing regardless of server engine health", () => {
const withoutEngine = composeOmniRushExtensionDiscoveryInstruction(state(health({
usable: false,
phase: "cloud_tools_missing",
firstFailure: {
code: "cloud_tools_missing",
stage: "tool_registration",
recommendedAction: "Run reconcile",
message: "missing",
},
})));
const failedEngine = composeOmniRushExtensionDiscoveryInstruction(state(health({
usable: false,
phase: "cloud_tools_missing",
engine: { status: "failed" },
firstFailure: {
code: "cloud_tools_missing",
stage: "tool_registration",
recommendedAction: "Run reconcile",
message: "missing",
},
})));
expect(withoutEngine).toBe(OMNIRUSH_EXTENSION_DISCOVERY_INSTRUCTION);
expect(failedEngine).toBe(OMNIRUSH_EXTENSION_DISCOVERY_INSTRUCTION);
});
test("treats unknown workspace as neutral instead of borrowing another workspace", () => {
const instruction = composeOmniRushExtensionDiscoveryInstruction({
...state(null),
workspace: { resolution: "unknown", id: null, directory: "/tmp/unknown", reason: "No workspace has this exact OpenCode directory" },
});
expect(instruction).toBe(OMNIRUSH_EXTENSION_DISCOVERY_INSTRUCTION);
});
test("never emits degraded wording or no-tool-use guidance", () => {
const engineStatuses: Array<string | undefined> = [
"connected",
"disabled",
"needs_auth",
"needs_client_registration",
"failed",
"starting",
undefined,
];
for (const status of engineStatuses) {
expectNoDegradedSteering(composeSteeringFromEngineMcpStatus(status));
}
const fallbackStates: OmniRushExtensionConnectState[] = [
state(health()),
state(health({ usableByCurrentModel: null })),
state(health({
usableByCurrentModel: false,
phase: "provider_projection_missing",
firstFailure: failure("provider_tool_projection_missing"),
})),
state(health({
usable: false,
phase: "engine_disabled",
firstFailure: failure("cloud_mcp_disabled"),
})),
state(health({
usable: false,
phase: "missing_desired",
desired: { present: false, revision: null },
firstFailure: failure("cloud_desired_missing"),
})),
state(health({
usable: false,
phase: "missing_mcp",
firstFailure: failure("cloud_mcp_missing"),
})),
state(health({
usable: false,
phase: "probe_unreachable",
firstFailure: failure("probe_unreachable"),
})),
state(health({
usable: false,
phase: "cloud_tools_missing",
firstFailure: failure("cloud_tools_missing"),
})),
{ ...state(null), workspace: { resolution: "unknown", id: null, directory: "/tmp/unknown" } },
{ ...state(null), connectCatalogEnabled: false },
{ ...state(null), googleWorkspace: { legacyConfigured: true } },
state(null),
];
for (const fallbackState of fallbackStates) {
expectNoDegradedSteering(composeOmniRushExtensionDiscoveryInstruction(fallbackState));
}
});
});
describe("resolveOmniRushExtensionDiscoveryInstruction", () => {
test("uses engine connected status without fetching server connect state", async () => {
const requests: unknown[] = [];
const client = engineMcpClient({ data: { "omnirush-cloud": { status: "connected" } } }, requests);
let serverFetchCalls = 0;
const serverFetch = async (): Promise<Response> => {
serverFetchCalls += 1;
return Response.json({ message: "unexpected" }, { status: 500 });
};
const instruction = await resolveOmniRushExtensionDiscoveryInstruction(
{ context: { directory: "/tmp/ws_1" } },
serverFetch,
{ client, directory: "/tmp/factory" },
);
expect(instruction).toBe(OMNIRUSH_CLOUD_CONNECTION_INSTRUCTION);
expect(requests).toEqual([{ query: { directory: "/tmp/ws_1" } }]);
expect(serverFetchCalls).toBe(0);
});
test("uses engine auth-needed status without fetching server connect state", async () => {
const client = engineMcpClient({ data: { "omnirush-cloud": { status: "needs_auth" } } });
let serverFetchCalls = 0;
const serverFetch = async (): Promise<Response> => {
serverFetchCalls += 1;
return Response.json({ message: "unexpected" }, { status: 500 });
};
expect(await resolveOmniRushExtensionDiscoveryInstruction({}, serverFetch, { client })).toBe(OMNIRUSH_CONNECT_SIGN_IN_INSTRUCTION);
expect(serverFetchCalls).toBe(0);
});
test("fails open without server fetch when engine status lookup errors", async () => {
const client: OmniRushEngineMcpStatusClient = {
mcp: {
status: async () => {
throw new Error("engine unavailable");
},
},
};
let serverFetchCalls = 0;
const serverFetch = async (): Promise<Response> => {
serverFetchCalls += 1;
return Response.json({ message: "unexpected" }, { status: 500 });
};
expect(await resolveOmniRushExtensionDiscoveryInstruction({}, serverFetch, { client })).toBe(UNCHANGED_EXTENSION_DISCOVERY_INSTRUCTION);
expect(serverFetchCalls).toBe(0);
});
test("fails open without server fetch when engine has an unknown omnirush-cloud status", async () => {
const client = engineMcpClient({ data: { "omnirush-cloud": { status: "starting" } } });
let serverFetchCalls = 0;
const serverFetch = async (): Promise<Response> => {
serverFetchCalls += 1;
return Response.json({ message: "unexpected" }, { status: 500 });
};
expect(await resolveOmniRushExtensionDiscoveryInstruction({}, serverFetch, { client })).toBe(UNCHANGED_EXTENSION_DISCOVERY_INSTRUCTION);
expect(serverFetchCalls).toBe(0);
});
test("falls back to server connect state when engine has no omnirush-cloud entry", async () => {
process.env.OMNIRUSH_SERVER_URL = "http://omnirush.test";
process.env.OMNIRUSH_SERVER_TOKEN = "test-token";
const client = engineMcpClient({ data: { other: { status: "connected" } } });
let serverFetchCalls = 0;
const serverFetch = async (): Promise<Response> => {
serverFetchCalls += 1;
return Response.json({
ok: true,
schemaVersion: 1,
connectEnabled: true,
connectCatalogEnabled: true,
cloudMcpPresent: true,
cloudHealth: health(),
workspace: { resolution: "resolved", id: "ws_1", directory: "/tmp/ws_1" },
googleWorkspace: { legacyConfigured: false },
});
};
expect(await resolveOmniRushExtensionDiscoveryInstruction({ context: { directory: "/tmp/ws_1" } }, serverFetch, { client })).toBe(OMNIRUSH_CLOUD_CONNECTION_INSTRUCTION);
expect(serverFetchCalls).toBe(1);
});
test("fetches verified health for the current directory/model without caching stale failures", async () => {
process.env.OMNIRUSH_SERVER_URL = "http://omnirush.test/";
process.env.OMNIRUSH_SERVER_TOKEN = "test-token";
const urls: string[] = [];
const authorizations: Array<string | null> = [];
let calls = 0;
const fakeFetch = async (url: string, init?: RequestInit): Promise<Response> => {
calls += 1;
urls.push(url);
authorizations.push(new Headers(init?.headers).get("authorization"));
return Response.json({
ok: true,
schemaVersion: 1,
connectEnabled: true,
connectCatalogEnabled: true,
cloudMcpPresent: calls > 1,
cloudHealth: calls > 1 ? health() : health({
usable: false,
phase: "cloud_tools_missing",
firstFailure: {
code: "cloud_tools_missing",
stage: "tool_registration",
recommendedAction: "Run reconcile",
message: "missing",
},
}),
workspace: { resolution: "resolved", id: "ws_1", directory: "/tmp/ws_1" },
googleWorkspace: { legacyConfigured: false },
});
};
const input = {
context: { directory: "/tmp/ws_1" },
model: { providerID: "anthropic", modelID: "claude-sonnet-4" },
};
expect(await resolveOmniRushExtensionDiscoveryInstruction(input, fakeFetch)).toBe(UNCHANGED_EXTENSION_DISCOVERY_INSTRUCTION);
expect(await resolveOmniRushExtensionDiscoveryInstruction(input, fakeFetch)).toBe(OMNIRUSH_CLOUD_CONNECTION_INSTRUCTION);
expect(calls).toBe(2);
expect(urls).toEqual([
"http://omnirush.test/experimental/connect/state?directory=%2Ftmp%2Fws_1&provider=anthropic&model=claude-sonnet-4",
"http://omnirush.test/experimental/connect/state?directory=%2Ftmp%2Fws_1&provider=anthropic&model=claude-sonnet-4",
]);
expect(authorizations).toEqual(["Bearer test-token", "Bearer test-token"]);
});
test("passes workspace id and worktree from plugin context", async () => {
process.env.OMNIRUSH_SERVER_URL = "http://omnirush.test";
process.env.OMNIRUSH_SERVER_TOKEN = "test-token";
let requested = "";
const fakeFetch = async (url: string): Promise<Response> => {
requested = url;
return Response.json({
ok: true,
schemaVersion: 1,
connectEnabled: true,
connectCatalogEnabled: true,
cloudMcpPresent: true,
cloudHealth: health(),
workspace: { resolution: "resolved", id: "ws_2", directory: "/tmp/worktree" },
googleWorkspace: { legacyConfigured: false },
});
};
await resolveOmniRushExtensionDiscoveryInstruction({ context: { workspaceId: "ws_2", worktree: "/tmp/worktree" } }, fakeFetch);
expect(requested).toBe("http://omnirush.test/experimental/connect/state?workspaceId=ws_2&directory=%2Ftmp%2Fworktree");
});
test("fails open when connect state fetching or parsing fails", async () => {
process.env.OMNIRUSH_SERVER_URL = "http://omnirush.test";
process.env.OMNIRUSH_SERVER_TOKEN = "test-token";
const failingFetch = async (): Promise<Response> => {
throw new Error("network unavailable");
};
const invalidFetch = async (): Promise<Response> => Response.json({ ok: true });
expect(await resolveOmniRushExtensionDiscoveryInstruction({}, failingFetch)).toBe(UNCHANGED_EXTENSION_DISCOVERY_INSTRUCTION);
expect(await resolveOmniRushExtensionDiscoveryInstruction({}, invalidFetch)).toBe(UNCHANGED_EXTENSION_DISCOVERY_INSTRUCTION);
});
});