Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
16.0 KB
Raw Blame
import { z } from "zod";

export type OmniRushContext = {
  agent?: string;
  sessionID?: string;
  messageID?: string;
  directory?: string;
  worktree?: string;
  workspaceId?: string;
  workspaceID?: string;
};

export type OmniRushExtensionConnectState = {
  connectEnabled: boolean;
  connectCatalogEnabled: boolean;
  cloudMcpPresent: boolean;
  cloudHealth: OmniRushCloudHealthSummary | null;
  workspace?: {
    resolution?: string;
    id?: string | null;
    directory?: string | null;
    reason?: string;
  };
  googleWorkspace: {
    legacyConfigured: boolean;
  };
};

export type OmniRushCloudHealthSummary = {
  usable: boolean;
  usableByCurrentModel: boolean | null;
  phase: string;
  connectCatalogEnabled?: boolean;
  workspace: {
    id: string;
    directory: string | null;
  };
  desired: {
    present: boolean;
    revision: string | null;
  };
  delivery?: {
    appliedRevision?: string | null;
  };
  engine?: {
    status?: string;
  };
  firstFailure: {
    code: string;
    stage: string;
    recommendedAction: string;
    message: string;
  } | null;
};

type OmniRushFetch = (url: string, init?: RequestInit) => Promise<Response>;

type EngineMcpStatusRequest = {
  query?: {
    directory?: string;
  };
};

export type OmniRushEngineMcpStatusClient = {
  mcp: {
    status: (request?: EngineMcpStatusRequest) => Promise<unknown>;
  };
};

export type OmniRushEngineMcpStatusSource = {
  client?: OmniRushEngineMcpStatusClient;
  directory?: string;
};

type EngineMcpStatusResult =
  | { found: true; status: string | undefined }
  | { found: false };

type ProviderModel = {
  provider: string;
  model: string;
};

const cloudFailureSchema = z.object({
  code: z.string(),
  stage: z.string(),
  recommendedAction: z.string(),
  message: z.string(),
}).passthrough();

const cloudHealthSchema = z.object({
  usable: z.boolean(),
  usableByCurrentModel: z.boolean().nullable(),
  phase: z.string(),
  connectCatalogEnabled: z.boolean().optional(),
  workspace: z.object({
    id: z.string(),
    directory: z.string().nullable(),
  }).passthrough(),
  desired: z.object({
    present: z.boolean(),
    revision: z.string().nullable(),
  }).passthrough(),
  delivery: z.object({
    appliedRevision: z.string().nullable().optional(),
  }).passthrough().optional(),
  engine: z.object({
    status: z.string().optional(),
  }).passthrough().optional(),
  firstFailure: cloudFailureSchema.nullable(),
}).passthrough();

const connectStateResponseSchema = z.object({
  ok: z.literal(true),
  schemaVersion: z.number(),
  connectEnabled: z.boolean(),
  connectCatalogEnabled: z.boolean().optional(),
  cloudMcpPresent: z.boolean(),
  cloudHealth: cloudHealthSchema.nullable().optional(),
  workspace: z.object({
    resolution: z.string().optional(),
    id: z.string().nullable().optional(),
    directory: z.string().nullable().optional(),
    reason: z.string().optional(),
  }).passthrough().optional(),
  googleWorkspace: z.object({
    legacyConfigured: z.boolean(),
  }).passthrough(),
}).passthrough();

// Both catalogs answer with the same envelope: a rendered prompt section.
const connectCatalogResponseSchema = z.object({
  ok: z.literal(true),
  schemaVersion: z.number(),
  instruction: z.string(),
}).passthrough();

export const OMNIRUSH_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.";

export const OMNIRUSH_CLOUD_SKILL_AUTHORING_INSTRUCTION =
  "Skill creation: Cloud. When the user asks to create a skill, retrieve and follow the listed create-skill remote skill by calling the Connect server's execute_capability tool with its exact <capability>. Create the skill in Cloud as a private plugin, not in the workspace. For later steps, use share-plugin when the user wants a specific person or team to use a skill, and use add-to-marketplace or add-user-to-marketplace only when the user asks. Use a workspace-local skill only when the user explicitly requests one. Do not create both copies.";

export const OMNIRUSH_LOCAL_SKILL_AUTHORING_INSTRUCTION =
  "Skill creation: Local. Create or update a workspace-local skill only when the user requests one. Keep one skill in .opencode/skills/<skill-name>/SKILL.md, validate it, and re-read it after writing. Do not create a Cloud copy.";

// Availability signal only. The base agent prompt already names the two
// Connect tools and the catalog rule, and the detailed Connect contract
// (search-first discovery, MCP Apps, connection_status handling, schema
// guidance, retry semantics, "a successful search proves authorization")
// ships with the connection itself as the omnirush-cloud server's MCP
// initialize instructions — guaranteed present exactly when this "ready"
// steering is selected. Restating either here costs characters on every
// request and drifts.
export const OMNIRUSH_CLOUD_CONNECTION_INSTRUCTION =
  "The Cloud connection is verified ready for this exact workspace/model. The Connect server instructions in this prompt are authoritative for search-first discovery, MCP Apps, connection_status results, schema guidance, and retry rules; follow them instead of improvising. Local app extensions remain available through app_query/app_execute with extension.actions and extension.call.";

export const OMNIRUSH_CONNECT_SIGN_IN_INSTRUCTION =
  `${OMNIRUSH_EXTENSION_DISCOVERY_INSTRUCTION} Cloud is not signed in or no desired agent access configuration exists for this workspace. Direct the user to sign in to their account and connect the service in Settings → Connect.`;

export const OMNIRUSH_CONNECT_DISABLED_INSTRUCTION =
  `${OMNIRUSH_EXTENSION_DISCOVERY_INSTRUCTION} Cloud agent access is explicitly disabled for this workspace. Explain that the user can enable agent access in Settings → Connect.`;

const OMNIRUSH_CLOUD_MCP_NAME = "omnirush-cloud";

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

function readString(value: unknown): string | undefined {
  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
}

function getRecordProperty(value: unknown, key: string): unknown {
  return isRecord(value) ? value[key] : undefined;
}

function readNestedString(value: unknown, keys: string[]): string | undefined {
  let current = value;
  for (const key of keys) current = getRecordProperty(current, key);
  return readString(current);
}

function readContext(input: unknown): OmniRushContext {
  const context = getRecordProperty(input, "context");
  const session = getRecordProperty(input, "session");
  const directory = readNestedString(input, ["directory"]) ?? readNestedString(context, ["directory"]) ?? readNestedString(session, ["directory"]);
  const worktree = readNestedString(input, ["worktree"]) ?? readNestedString(context, ["worktree"]) ?? readNestedString(session, ["worktree"]);
  const workspaceId = readNestedString(input, ["workspaceId"]) ?? readNestedString(input, ["workspaceID"]) ?? readNestedString(context, ["workspaceId"]) ?? readNestedString(context, ["workspaceID"]);
  return {
    ...(directory ? { directory } : {}),
    ...(worktree ? { worktree } : {}),
    ...(workspaceId ? { workspaceId } : {}),
  };
}

function readProviderModel(input: unknown): ProviderModel | undefined {
  const model = getRecordProperty(input, "model");
  const provider = readNestedString(model, ["providerID"]) ?? readNestedString(model, ["provider"]) ?? readNestedString(input, ["provider"]);
  const modelId = readNestedString(model, ["modelID"]) ?? readNestedString(model, ["id"]) ?? readNestedString(input, ["modelID"]);
  if (provider && modelId) return { provider, model: modelId };
  const combined = modelId?.includes("/") ? modelId : readNestedString(input, ["model"]) ?? readNestedString(model, ["name"]);
  if (combined?.includes("/")) {
    const [providerPart, ...modelParts] = combined.split("/");
    const joinedModel = modelParts.join("/").trim();
    if (providerPart?.trim() && joinedModel) return { provider: providerPart.trim(), model: joinedModel };
  }
  return undefined;
}

function serverUrl(): string {
  return String(process.env.OMNIRUSH_SERVER_URL || "").replace(/\/$/, "");
}

function serverToken(): string {
  return String(process.env.OMNIRUSH_SERVER_TOKEN || "");
}

function requireOmniRushServer(): { url: string; token: string } {
  const url = serverUrl();
  const token = serverToken();
  if (!url || !token) {
    throw new Error("App extension tools are only available when the engine is launched by the app.");
  }
  return { url, token };
}

async function parseResponse(response: Response): Promise<unknown> {
  const text = await response.text();
  if (!text) return null;
  try {
    return JSON.parse(text);
  } catch {
    return { message: text };
  }
}

function getStringProperty(value: unknown, key: string): string | null {
  if (!isRecord(value)) return null;
  const property = value[key];
  return typeof property === "string" ? property : null;
}

function errorMessage(payload: unknown, fallback: string): string {
  return getStringProperty(payload, "message") ?? getStringProperty(payload, "code") ?? fallback;
}

function readEngineDirectory(input: unknown, fallback?: string): string | undefined {
  const context = readContext(input);
  return context.directory ?? context.worktree ?? readString(fallback);
}

function engineStatusPayload(result: unknown): unknown {
  if (!isRecord(result)) return result;
  const data = result.data;
  if (data !== undefined) return data;
  if (result.error !== undefined) throw new Error("OmniRush MCP status request failed");
  const responseOk = getRecordProperty(result.response, "ok");
  if (responseOk === false) throw new Error("OmniRush MCP status request failed");
  return result;
}

function readEngineMcpStatus(result: unknown): EngineMcpStatusResult {
  const entry = getRecordProperty(engineStatusPayload(result), OMNIRUSH_CLOUD_MCP_NAME);
  if (entry === undefined) return { found: false };
  if (typeof entry === "string") return { found: true, status: readString(entry) };
  return { found: true, status: readNestedString(entry, ["status"]) };
}

async function fetchEngineMcpStatus(input: unknown, engine: OmniRushEngineMcpStatusSource): Promise<EngineMcpStatusResult> {
  if (!engine.client) return { found: false };
  const directory = readEngineDirectory(input, engine.directory);
  const request = directory ? { query: { directory } } : undefined;
  return readEngineMcpStatus(await engine.client.mcp.status(request));
}

async function fetchOmniRushConnectState(input: unknown, fetcher: OmniRushFetch): Promise<OmniRushExtensionConnectState> {
  const { url, token } = requireOmniRushServer();
  const context = readContext(input);
  const providerModel = readProviderModel(input);
  const query = new URLSearchParams();
  const workspaceId = context.workspaceId ?? context.workspaceID;
  const directory = context.worktree ?? context.directory;
  if (workspaceId) query.set("workspaceId", workspaceId);
  if (directory) query.set("directory", directory);
  if (providerModel) {
    query.set("provider", providerModel.provider);
    query.set("model", providerModel.model);
  }
  const suffix = query.size ? `?${query.toString()}` : "";
  const response = await fetcher(`${url}/experimental/connect/state${suffix}`, {
    headers: { Authorization: `Bearer ${token}` },
  });
  const payload = await parseResponse(response);
  if (!response.ok) throw new Error(errorMessage(payload, "OmniRush.ai connect state request failed"));
  const parsed = connectStateResponseSchema.parse(payload);
  return {
    connectEnabled: parsed.connectEnabled,
    connectCatalogEnabled: parsed.connectCatalogEnabled ?? parsed.connectEnabled,
    cloudMcpPresent: parsed.cloudMcpPresent,
    cloudHealth: parsed.cloudHealth ?? null,
    ...(parsed.workspace ? { workspace: parsed.workspace } : {}),
    googleWorkspace: {
      legacyConfigured: parsed.googleWorkspace.legacyConfigured,
    },
  };
}

export async function resolveOmniRushConnectSkillInstruction(_input?: unknown, fetcher: OmniRushFetch = fetch): Promise<string> {
  try {
    const { url, token } = requireOmniRushServer();
    // Connect skills are server-scoped; workspace/directory query params are unused.
    const response = await fetcher(`${url}/experimental/connect/skills`, {
      headers: { Authorization: `Bearer ${token}` },
    });
    if (!response.ok) return "";
    return connectCatalogResponseSchema.parse(await parseResponse(response)).instruction;
  } catch {
    return "";
  }
}

export async function resolveOmniRushAutomationInstruction(_input?: unknown, fetcher: OmniRushFetch = fetch): Promise<string> {
  try {
    const { url, token } = requireOmniRushServer();
    // Automations are account-scoped like Connect skills, not per-workspace.
    const response = await fetcher(`${url}/experimental/connect/automations`, {
      headers: { Authorization: `Bearer ${token}` },
    });
    if (!response.ok) return "";
    return connectCatalogResponseSchema.parse(await parseResponse(response)).instruction;
  } catch {
    return "";
  }
}

export function composeOmniRushExtensionDiscoveryInstruction(state: OmniRushExtensionConnectState | null): string {
  if (!state) return OMNIRUSH_EXTENSION_DISCOVERY_INSTRUCTION;
  if (state.workspace?.resolution && state.workspace.resolution !== "resolved") return OMNIRUSH_EXTENSION_DISCOVERY_INSTRUCTION;
  const health = state.cloudHealth;
  if (health?.usable === true && health.usableByCurrentModel !== false) return OMNIRUSH_CLOUD_CONNECTION_INSTRUCTION;
  if (health?.phase === "engine_disabled" || health?.firstFailure?.code === "engine_disabled" || health?.firstFailure?.code === "cloud_mcp_disabled") return OMNIRUSH_CONNECT_DISABLED_INSTRUCTION;
  if (health) {
    if (!health.desired.present || health.firstFailure?.code === "cloud_mcp_missing") return OMNIRUSH_CONNECT_SIGN_IN_INSTRUCTION;
    return OMNIRUSH_EXTENSION_DISCOVERY_INSTRUCTION;
  }
  if (!state.connectCatalogEnabled || state.googleWorkspace.legacyConfigured) return OMNIRUSH_EXTENSION_DISCOVERY_INSTRUCTION;
  return OMNIRUSH_CONNECT_SIGN_IN_INSTRUCTION;
}

export function composeSteeringFromEngineMcpStatus(status: string | undefined): string {
  if (status === "connected") return OMNIRUSH_CLOUD_CONNECTION_INSTRUCTION;
  if (status === "disabled") return OMNIRUSH_CONNECT_DISABLED_INSTRUCTION;
  if (status === "needs_auth" || status === "needs_client_registration") return OMNIRUSH_CONNECT_SIGN_IN_INSTRUCTION;
  return OMNIRUSH_EXTENSION_DISCOVERY_INSTRUCTION;
}

export function composeSkillAuthoringInstruction(extensionInstruction: string): {
  mode: "cloud" | "local";
  prompt: string;
} {
  if (extensionInstruction === OMNIRUSH_CLOUD_CONNECTION_INSTRUCTION) {
    return { mode: "cloud", prompt: OMNIRUSH_CLOUD_SKILL_AUTHORING_INSTRUCTION };
  }
  return { mode: "local", prompt: OMNIRUSH_LOCAL_SKILL_AUTHORING_INSTRUCTION };
}

export function resetOmniRushExtensionDiscoveryInstructionCacheForTests(): void {
  // Retained for older tests; steering is deliberately uncached so repair is observed immediately.
}

export async function resolveOmniRushExtensionDiscoveryInstruction(
  input?: unknown,
  fetcher: OmniRushFetch = fetch,
  engine: OmniRushEngineMcpStatusSource = {},
): Promise<string> {
  if (engine.client) {
    try {
      // Invariant: the OpenCode engine owns MCP registration and builds the
      // prompt tool list, so tool-availability steering must come from that
      // same in-process MCP state. Server health probes may fail for reasons
      // (for example corporate TLS trust) that do not affect engine tools.
      const engineStatus = await fetchEngineMcpStatus(input, engine);
      if (engineStatus.found) return composeSteeringFromEngineMcpStatus(engineStatus.status);
    } catch {
      return OMNIRUSH_EXTENSION_DISCOVERY_INSTRUCTION;
    }
  }
  try {
    return composeOmniRushExtensionDiscoveryInstruction(await fetchOmniRushConnectState(input, fetcher));
  } catch {
    return OMNIRUSH_EXTENSION_DISCOVERY_INSTRUCTION;
  }
}