Skip to content

A desktop coding agent with free access to frontier models.

TypeScript

Give desktop users built-in coding guides with a saved off switch (#64)

Skandeshc3a478ff8500
diff --git a/apps/app/src/app/lib/omnirush-server.ts b/apps/app/src/app/lib/omnirush-server.ts
index 12af33a8..0185e406 100644
--- a/apps/app/src/app/lib/omnirush-server.ts
+++ b/apps/app/src/app/lib/omnirush-server.ts
@@ -405,6 +405,15 @@ export type OmniRushRuntimeApprovals = {
setting: OmniRushApprovalMode | null;
};
+/** Saved only on this server/device, independent of account and workspace. */
+export type OmniRushBestPractices = { enabled: boolean };
+export type OmniRushBestPracticesChange = OmniRushBestPractices & {
+ ok: boolean;
+ changed: boolean;
+ /** Applying a choice must not interrupt a live reply. */
+ engine: { status: "applied" | "deferred" | "failed" | "unconfigured" };
+};
+
/** The sub-agent model and effort (Settings > Preferences and the composer's Sub-agents menu). */
export type OmniRushSubagentModelSetting = {
/** An omnirush.ai catalog model id; null runs sub-agents on the main agent's model. */
@@ -1889,6 +1898,16 @@ export function createOmniRushServerClient(options: { baseUrl: string; token?: s
body: { mode },
timeoutMs: timeouts.config,
}),
+ getBestPractices: () =>
+ requestJson<OmniRushBestPractices>(baseUrl, "/runtime-config/best-practices", { token, hostToken, timeoutMs: timeouts.config }),
+ setBestPractices: (enabled: boolean) =>
+ requestJson<OmniRushBestPracticesChange>(baseUrl, "/runtime-config/best-practices", {
+ token,
+ hostToken,
+ method: "PUT",
+ body: { enabled },
+ timeoutMs: ENGINE_RELOAD_TIMEOUT_MS,
+ }),
getVoiceStatus: (workspaceId?: string | null) =>
requestJson<OmniRushVoiceStatus>(
baseUrl,
diff --git a/apps/app/src/react-app/domains/settings/best-practices.ts b/apps/app/src/react-app/domains/settings/best-practices.ts
new file mode 100644
index 00000000..b0888112
--- /dev/null
+++ b/apps/app/src/react-app/domains/settings/best-practices.ts
@@ -0,0 +1,75 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import type { OmniRushBestPractices, OmniRushBestPracticesChange, OmniRushServerClient } from "@/app/lib/omnirush-server";
+
+export type BestPracticesClient = Pick<OmniRushServerClient, "getBestPractices" | "setBestPractices">;
+
+export const BEST_PRACTICES_HELP = "Built-in guides help the agent plan, build, test, and fix your work. On by default. Saved on this server.";
+
+export function bestPracticesChangeMessage(result: OmniRushBestPracticesChange): string {
+ const choice = result.enabled ? "on" : "off";
+ switch (result.engine.status) {
+ case "applied":
+ return `Best practices ${choice}. Ready for your next request.`;
+ case "deferred":
+ return `Best practices ${choice} saved. This change waits until the engine is idle.`;
+ case "failed":
+ return `Best practices ${choice} saved. The engine change could not be confirmed. Use Reload in Settings to apply it.`;
+ case "unconfigured":
+ return `Best practices ${choice} saved. The choice will apply when the engine starts.`;
+ }
+}
+
+/** A failed apply keeps the server's saved choice visible, with its warning. */
+export function useBestPractices(client: BestPracticesClient | null) {
+ const [setting, setSetting] = useState<OmniRushBestPractices | null>(null);
+ const [busy, setBusy] = useState(false);
+ const [status, setStatus] = useState("");
+ // A GET begun before a PUT must not replace the newly saved choice.
+ const sequence = useRef(0);
+
+ useEffect(() => {
+ sequence.current += 1;
+ const startedAt = sequence.current;
+ let cancelled = false;
+ setSetting(null);
+ setBusy(false);
+ setStatus("");
+ if (client) {
+ void client.getBestPractices()
+ .then((value) => {
+ if (!cancelled && sequence.current === startedAt) setSetting(value);
+ })
+ .catch(() => {
+ if (!cancelled && sequence.current === startedAt) setStatus("Best practices could not be loaded. Try opening Settings again.");
+ });
+ }
+ return () => { cancelled = true; };
+ }, [client]);
+
+ const setEnabled = useCallback(async (enabled: boolean) => {
+ if (!client || busy) return;
+ sequence.current += 1;
+ const startedAt = sequence.current;
+ setBusy(true);
+ setStatus("Saving best practices…");
+ try {
+ const result = await client.setBestPractices(enabled);
+ if (sequence.current !== startedAt) return;
+ setSetting({ enabled: result.enabled });
+ setStatus(bestPracticesChangeMessage(result));
+ } catch {
+ if (sequence.current !== startedAt) return;
+ // The server may have saved before the response was lost. Re-read the
+ // choice, but never infer that an engine reload completed.
+ const saved = await client.getBestPractices().catch(() => null);
+ if (sequence.current !== startedAt) return;
+ if (saved) setSetting(saved);
+ setStatus("Best practices could not be applied. Open Settings again to check the saved choice, then use Reload.");
+ } finally {
+ if (sequence.current === startedAt) setBusy(false);
+ }
+ }, [busy, client]);
+
+ return { setting, busy, status, setEnabled };
+}
diff --git a/apps/app/src/react-app/domains/settings/pages/general-view.tsx b/apps/app/src/react-app/domains/settings/pages/general-view.tsx
index b3c95e88..ebb5c0b6 100644
--- a/apps/app/src/react-app/domains/settings/pages/general-view.tsx
+++ b/apps/app/src/react-app/domains/settings/pages/general-view.tsx
@@ -34,12 +34,15 @@ import {
type ApprovalsClient,
} from "../approval-mode";
import { DiagnosticsSection } from "./diagnostics-section";
+import { BEST_PRACTICES_HELP, useBestPractices, type BestPracticesClient } from "../best-practices";
export type GeneralSettingsViewProps = {
onNavigateTab: (tab: SettingsTab) => void;
developerMode: boolean;
/** Server client for the Approvals card; the card is hidden without one. */
omnirushClient?: ApprovalsClient | null;
+ /** Global guides do not depend on workspace selection or history loading. */
+ bestPracticesClient?: BestPracticesClient | null;
/** Workspace whose engine is reloaded after the approval mode changes. */
runtimeWorkspaceId?: string | null;
/** Builds the sanitized diagnostics bundle with the route's context. */
@@ -176,12 +179,46 @@ export function ApprovalsCard(props: {
);
}
+export function BestPracticesCard(props: {
+ enabled: boolean | null;
+ busy: boolean;
+ status: string;
+ onToggle: (enabled: boolean) => void;
+}) {
+ return (
+ <div className="space-y-3">
+ <div className="text-[11px] font-semibold uppercase tracking-[0.15em] text-dls-secondary">Best practices</div>
+ <div className="flex items-center gap-4 rounded-2xl border border-dls-border bg-dls-surface p-4">
+ <div className="flex h-10 w-10 shrink-0 items-center justify-center rounded-xl border border-dls-border bg-dls-hover">
+ <Sparkles size={17} className="text-dls-secondary" />
+ </div>
+ <div className="min-w-0 flex-1">
+ <div className="text-[13px] font-medium text-dls-text">Best practices</div>
+ <div id="best-practices-help" className="text-[11px] text-dls-secondary">{BEST_PRACTICES_HELP}</div>
+ {props.status ? (
+ <div className="mt-0.5 text-[11px] text-dls-secondary" role="status" data-testid="best-practices-status">{props.status}</div>
+ ) : null}
+ </div>
+ <Switch
+ aria-label="Best practices"
+ aria-describedby="best-practices-help"
+ checked={props.enabled === true}
+ disabled={props.busy || props.enabled === null}
+ onCheckedChange={props.onToggle}
+ />
+ </div>
+ </div>
+ );
+}
+
export function GeneralSettingsView(props: GeneralSettingsViewProps) {
const [account, setAccount] = useState<NativeAccountStatus | null>(null);
const [accountBusy, setAccountBusy] = useState(false);
const [accountMessage, setAccountMessage] = useState("");
const approvalsClient = props.omnirushClient ?? null;
const approvalMode = useApprovalMode(approvalsClient, props.runtimeWorkspaceId ?? null);
+ const bestPracticesClient = props.bestPracticesClient ?? null;
+ const bestPractices = useBestPractices(bestPracticesClient);
useEffect(() => {
if (!isElectronRuntime()) return;
@@ -329,6 +366,15 @@ export function GeneralSettingsView(props: GeneralSettingsViewProps) {
/>
) : null}
+ {bestPracticesClient ? (
+ <BestPracticesCard
+ enabled={bestPractices.setting?.enabled ?? null}
+ busy={bestPractices.busy}
+ status={bestPractices.status}
+ onToggle={(enabled) => void bestPractices.setEnabled(enabled)}
+ />
+ ) : null}
+
<DiagnosticsSection buildBundle={props.buildDiagnosticsBundle} />
</div>
);
diff --git a/apps/app/src/react-app/shell/command-palette-settings.ts b/apps/app/src/react-app/shell/command-palette-settings.ts
index 0c05f116..8e4732cb 100644
--- a/apps/app/src/react-app/shell/command-palette-settings.ts
+++ b/apps/app/src/react-app/shell/command-palette-settings.ts
@@ -25,7 +25,7 @@ const SETTINGS_KEYWORDS: Partial<Record<SettingsTab, string[]>> = {
updates: ["version", "upgrade", "check for updates", "release"],
debug: ["logs", "diagnostics", "developer mode"],
"cloud-account": ["sign in", "log in", "login", "account", "organization", "org", "den", "cloud", "omnirush cloud"],
- general: ["settings", "preferences", "options", "configure"],
+ general: ["settings", "preferences", "options", "configure", "best practices", "guides"],
};
const LIBRARY_SECTIONS = [
diff --git a/apps/app/src/react-app/shell/settings-route.tsx b/apps/app/src/react-app/shell/settings-route.tsx
index daa0e801..4941c5ca 100644
--- a/apps/app/src/react-app/shell/settings-route.tsx
+++ b/apps/app/src/react-app/shell/settings-route.tsx
@@ -85,6 +85,7 @@ import { buildExtensionItems } from "@/react-app/domains/settings/extension-item
import { isOmniRushExtensionEnabled, OMNIRUSH_EXTENSION_STATE_CHANGED } from "@/react-app/domains/settings/extension-state";
import { PreferencesView } from "@/react-app/domains/settings/pages/preferences-view";
import { GeneralSettingsView } from "@/react-app/domains/settings/pages/general-view";
+import type { BestPracticesClient } from "@/react-app/domains/settings/best-practices";
import { AuthorizedFoldersPanel } from "@/react-app/domains/settings/panels/authorized-folders-panel";
import { BrowserLoginsPanel } from "../domains/browser-logins/browser-logins-panel";
import { EffectivePermissionsPanel } from "@/react-app/domains/settings/panels/effective-permissions-panel";
@@ -513,6 +514,7 @@ function SettingsRouteContent(props: SettingsSurfaceProps = {}) {
const [baseUrl, setBaseUrl] = useState("");
const [token, setToken] = useState("");
const [omnirushClient, setOmniRushClient] = useState<OmniRushServerClient | null>(null);
+ const [bestPracticesClient, setBestPracticesClient] = useState<BestPracticesClient | null>(null);
const [activeClient, setActiveClient] = useState<Client | null>(null);
const [busy, setBusy] = useState(false);
const [busyLabel, setBusyLabel] = useState<string | null>(null);
@@ -1289,6 +1291,7 @@ function SettingsRouteContent(props: SettingsSurfaceProps = {}) {
const refreshRouteState = useMemo(() => async (options?: { supersede?: boolean }) => {
const attempt = refreshLifecycleRef.current.begin(options);
if (!attempt) return;
+ setBestPracticesClient(null);
setLoading(true);
let desktopList: WorkspaceList | null = null;
let desktopWorkspaces = workspacesRef.current;
@@ -1315,6 +1318,7 @@ function SettingsRouteContent(props: SettingsSurfaceProps = {}) {
if (!normalizedBaseUrl || !resolvedToken) {
setOmniRushClient(null);
+ setBestPracticesClient(null);
setBaseUrl("");
setToken("");
setWorkspaces(desktopWorkspaces);
@@ -1335,6 +1339,9 @@ function SettingsRouteContent(props: SettingsSurfaceProps = {}) {
});
const list = await client.listWorkspaces();
if (!attempt.isCurrent()) return;
+ // Global guides can load once this server confirms access. Workspace
+ // selection and task history retain their existing readiness boundary.
+ setBestPracticesClient(client);
serverActiveWorkspaceIdRef.current = list.activeId ?? "";
const serverWorkspaceIds = new Set(list.items.map((workspace) => workspace.id));
const nextWorkspaces = mergeRouteWorkspaces(list.items, desktopWorkspaces);
@@ -2275,6 +2282,7 @@ function SettingsRouteContent(props: SettingsSurfaceProps = {}) {
onNavigateTab={(tab) => navigateSettingsPath(tab)}
developerMode={developerMode}
omnirushClient={omnirushClient}
+ bestPracticesClient={bestPracticesClient}
runtimeWorkspaceId={runtimeWorkspaceId}
buildDiagnosticsBundle={() => buildDiagnosticsBundleJson({
developerMode,
diff --git a/apps/app/tests/approvals-settings-card.test.tsx b/apps/app/tests/approvals-settings-card.test.tsx
index 74ef2ca9..3f25051a 100644
--- a/apps/app/tests/approvals-settings-card.test.tsx
+++ b/apps/app/tests/approvals-settings-card.test.tsx
@@ -7,7 +7,8 @@ import {
applyFullPermissions,
type ApprovalsClient,
} from "../src/react-app/domains/settings/approval-mode";
-import { ApprovalsCard } from "../src/react-app/domains/settings/pages/general-view";
+import { ApprovalsCard, BestPracticesCard, GeneralSettingsView } from "../src/react-app/domains/settings/pages/general-view";
+import { BEST_PRACTICES_HELP, bestPracticesChangeMessage, type BestPracticesClient } from "../src/react-app/domains/settings/best-practices";
function fakeClient(options: { reloadError?: Error } = {}) {
const calls: string[] = [];
@@ -96,3 +97,46 @@ describe("approvals settings card", () => {
expect(saved.tone).toBe("warning");
});
});
+
+describe("best practices settings card", () => {
+ test("shows the global guide switch while the workspace client is still loading", () => {
+ const bestPracticesClient: BestPracticesClient = {
+ getBestPractices: async () => ({ enabled: true }),
+ setBestPractices: async (enabled) => ({ ok: true, changed: true, enabled, engine: { status: "applied" } }),
+ };
+ const markup = renderToStaticMarkup(
+ <GeneralSettingsView
+ developerMode={false}
+ onNavigateTab={() => {}}
+ omnirushClient={null}
+ bestPracticesClient={bestPracticesClient}
+ />,
+ );
+ expect(switchMarkup(markup)).toContain('aria-label="Best practices"');
+ expect(switchMarkup(markup)).toContain('aria-disabled="true"');
+ expect(markup).not.toContain('aria-label="Full permissions"');
+ });
+
+ test("labels the switch, describes only guides, and waits for the server choice", () => {
+ const on = renderToStaticMarkup(<BestPracticesCard enabled={true} busy={false} status="" onToggle={() => {}} />);
+ expect(on).toContain(BEST_PRACTICES_HELP);
+ expect(switchMarkup(on)).toContain('aria-label="Best practices"');
+ expect(switchMarkup(on)).toContain('aria-describedby="best-practices-help"');
+ expect(switchMarkup(on)).toContain('aria-checked="true"');
+ expect(on.toLowerCase()).not.toContain("upload");
+ const loading = renderToStaticMarkup(<BestPracticesCard enabled={null} busy={false} status="" onToggle={() => {}} />);
+ expect(switchMarkup(loading)).toContain('aria-disabled="true"');
+ const off = renderToStaticMarkup(<BestPracticesCard enabled={false} busy={true} status="Saving best practices…" onToggle={() => {}} />);
+ expect(switchMarkup(off)).toContain('aria-checked="false"');
+ expect(switchMarkup(off)).toContain('aria-disabled="true"');
+ expect(off).toContain('role="status"');
+ });
+
+ test("distinguishes applied, deferred, failed, and not started choices", () => {
+ const result = { ok: true, changed: true, enabled: false };
+ expect(bestPracticesChangeMessage({ ...result, engine: { status: "applied" } })).toBe("Best practices off. Ready for your next request.");
+ expect(bestPracticesChangeMessage({ ...result, engine: { status: "deferred" } })).toBe("Best practices off saved. This change waits until the engine is idle.");
+ expect(bestPracticesChangeMessage({ ...result, engine: { status: "failed" } })).toBe("Best practices off saved. The engine change could not be confirmed. Use Reload in Settings to apply it.");
+ expect(bestPracticesChangeMessage({ ...result, engine: { status: "unconfigured" } })).toBe("Best practices off saved. The choice will apply when the engine starts.");
+ });
+});
diff --git a/apps/server/README.md b/apps/server/README.md
index 6fde3672..ba9d0054 100644
--- a/apps/server/README.md
+++ b/apps/server/README.md
@@ -175,6 +175,32 @@ OpenCode proxy:
All writes are gated by host approval.
+## Best practices
+
+Settings > General has a **Best practices** switch. It starts on. The local
+runtime database keeps the choice for this server across restarts. The setting
+is independent of account sign-in and workspace files.
+
+The bundled pack adds a short development prompt and nine guides the agent can
+load when needed. Off removes the pack's prompt and skill path. It preserves
+the swarm and user-installed skills. The pack is stored beside the runtime
+skills folder, outside all projects. It has no runtime download, private-note
+reader, or account-sync path.
+
+- `GET /runtime-config/best-practices` returns `{ "enabled": true }` or false.
+- `PUT /runtime-config/best-practices` accepts only `{ "enabled": boolean }`.
+ It requires client authentication and collaborator scope. Organization
+ settings restrictions still apply.
+- A write returns the saved `enabled`, `changed`, and `engine.status`:
+ `applied`, `deferred`, `failed`, or `unconfigured`. A deferred change lets
+ the current reply finish. A failed apply keeps the saved choice and the UI
+ asks for Reload. It does not claim that the engine changed.
+
+The server statically imports [the MIT pack](src/bundled-best-practices.json)
+so Node builds and compiled Bun binaries carry the same pinned source and
+license. See its `source` and per-skill `sourceSha256` fields when updating it.
+This feature does not change the app's existing account or data settings.
+
Host APIs accept either:
- `X-OmniRush-Host-Token: <token>` (legacy host token), or
diff --git a/apps/server/src/best-practices.ts b/apps/server/src/best-practices.ts
new file mode 100644
index 00000000..a4b48d48
--- /dev/null
+++ b/apps/server/src/best-practices.ts
@@ -0,0 +1,162 @@
+/** Static import: Node builds and compiled Bun binaries carry the same pack. */
+import bundle from "./bundled-best-practices.json" with { type: "json" };
+import { mkdir, readFile, realpath } from "node:fs/promises";
+import { isAbsolute, join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { writeFileAtomic } from "./atomic-write.js";
+import { runtimeStorageDir } from "./runtime-db.js";
+import type { RuntimeOpencodeConfig } from "./runtime-opencode-config-store.js";
+import type { ServerConfig, WorkspaceInfo } from "./types.js";
+import { OMNIRUSH_AGENT_PROMPT } from "./omnirush-agent-prompt.js";
+import { isRecord } from "./workspace-kv-store.js";
+
+export const OMNIRUSH_BEST_PRACTICES = bundle;
+
+export function bestPracticesEnabled(runtime: RuntimeOpencodeConfig): boolean {
+ return runtime.bestPractices !== false;
+}
+
+/** Separate from runtime `skills/`, whose recursive scan owns the swarm. */
+export function omnirushBestPracticesSkillsDir(config: ServerConfig): string {
+ return join(runtimeStorageDir(config), "best-practices");
+}
+
+type BestPracticesEngineSnapshot = { agents: unknown; skills: unknown };
+
+/** A file write precedes native cache refresh. Only observed readiness is applied. */
+export async function waitForBestPracticesReady(input: {
+ config: ServerConfig;
+ enabled: boolean;
+ read: (signal: AbortSignal) => Promise<BestPracticesEngineSnapshot[]>;
+ timeoutMs?: number;
+ intervalMs?: number;
+}): Promise<void> {
+ const deadline = Date.now() + (input.timeoutMs ?? 10_000);
+ const root = omnirushBestPracticesSkillsDir(input.config);
+ const directory = await realpath(root).catch(() => root);
+ const prompt = input.enabled ? `${OMNIRUSH_AGENT_PROMPT}\n\n${bundle.systemPrompt}` : OMNIRUSH_AGENT_PROMPT;
+ const names = new Set(bundle.skills.map((skill) => skill.name));
+ const owns = (location: string): boolean | null => {
+ let path = location;
+ if (location.startsWith("file:")) {
+ try { path = fileURLToPath(location); } catch { return null; }
+ }
+ if (!isAbsolute(path)) return null;
+ const child = relative(directory, path);
+ return child !== ".." && !child.startsWith(`..${sep}`) && !isAbsolute(child);
+ };
+ const ready = (snapshot: BestPracticesEngineSnapshot): boolean => {
+ if (!Array.isArray(snapshot.agents) || !Array.isArray(snapshot.skills)) return false;
+ const agent = snapshot.agents.find((value) => isRecord(value) && value.name === "omnirush");
+ if (!isRecord(agent) || agent.prompt !== prompt) return false;
+ const owned = new Set<string>();
+ const available = new Set<string>();
+ for (const skill of snapshot.skills) {
+ if (!isRecord(skill) || typeof skill.name !== "string" || !names.has(skill.name)) continue;
+ // A matching user-owned guide stays available. Missing ownership data
+ // cannot prove that the bundled copy disappeared.
+ if (typeof skill.location !== "string" || !skill.location) return false;
+ const ownership = owns(skill.location);
+ if (ownership === null) return false;
+ available.add(skill.name);
+ if (ownership) owned.add(skill.name);
+ }
+ // Project/user guides can override a bundled name. On restores the
+ // workflow catalog without taking those guides away from their owner.
+ return input.enabled ? available.size === names.size : owned.size === 0;
+ };
+ while (Date.now() < deadline) {
+ try {
+ const snapshots = await input.read(AbortSignal.timeout(Math.max(1, deadline - Date.now())));
+ if (snapshots.length > 0 && snapshots.every(ready)) return;
+ } catch {
+ // No raw prompt, skill body, credentials, or project metadata is logged.
+ }
+ const remaining = deadline - Date.now();
+ if (remaining <= 0) break;
+ await new Promise((resolve) => setTimeout(resolve, Math.min(input.intervalMs ?? 100, remaining)));
+ }
+ throw new Error("Best practices engine readiness was not observed");
+}
+
+/** Only bundled bytes are written; no workspace, private inputs, or network. */
+export async function writeBestPracticesSkills(config: ServerConfig): Promise<void> {
+ const root = omnirushBestPracticesSkillsDir(config);
+ await Promise.all(bundle.skills.map(async (skill) => {
+ const directory = join(root, skill.name);
+ const path = join(directory, "SKILL.md");
+ if (await readFile(path, "utf8").catch(() => undefined) === skill.content) return;
+ await mkdir(directory, { recursive: true });
+ await writeFileAtomic(path, skill.content);
+ }));
+}
+
+/** Attached engines cache an instance per folder and cannot roll over. */
+export class BestPracticesEngineReloads {
+ private readonly pending = new Map<string, WorkspaceInfo>();
+ private timer: ReturnType<typeof setTimeout> | undefined;
+ private stopped = false;
+
+ constructor(private readonly hooks: {
+ isBusy: (workspace: WorkspaceInfo) => Promise<boolean>;
+ reload: (workspace: WorkspaceInfo) => Promise<void>;
+ isPresent: (workspace: WorkspaceInfo) => boolean;
+ retryMs?: number;
+ }) {}
+
+ async apply(workspaces: WorkspaceInfo[]): Promise<"applied" | "deferred"> {
+ let deferred = false;
+ try {
+ for (const workspace of workspaces) {
+ if (this.stopped) throw new Error("Best practices reloads stopped");
+ const busy = await this.hooks.isBusy(workspace);
+ if (this.stopped) throw new Error("Best practices reloads stopped");
+ if (busy) {
+ this.pending.set(workspace.id, workspace);
+ deferred = true;
+ } else {
+ await this.hooks.reload(workspace);
+ this.pending.delete(workspace.id);
+ }
+ }
+ } finally {
+ this.schedule();
+ }
+ return deferred ? "deferred" : "applied";
+ }
+
+ stop(): void {
+ this.stopped = true;
+ clearTimeout(this.timer);
+ this.pending.clear();
+ }
+
+ private schedule(): void {
+ if (this.stopped || this.timer || this.pending.size === 0) return;
+ this.timer = setTimeout(() => {
+ this.timer = undefined;
+ void this.retry();
+ }, this.hooks.retryMs ?? 2_000);
+ this.timer.unref();
+ }
+
+ private async retry(): Promise<void> {
+ for (const [id, workspace] of this.pending) {
+ if (this.stopped) return;
+ if (!this.hooks.isPresent(workspace)) {
+ this.pending.delete(id);
+ continue;
+ }
+ try {
+ if (await this.hooks.isBusy(workspace)) continue;
+ if (this.stopped) return;
+ await this.hooks.reload(workspace);
+ this.pending.delete(id);
+ } catch {
+ // A failed or unreadable engine stays pending. No private details are
+ // emitted, and it is never disposed merely because a probe failed.
+ }
+ }
+ this.schedule();
+ }
+}
diff --git a/apps/server/src/bundled-best-practices.json b/apps/server/src/bundled-best-practices.json
new file mode 100644
index 00000000..721bf8a0
--- /dev/null
+++ b/apps/server/src/bundled-best-practices.json
@@ -0,0 +1,65 @@
+{
+ "version": 1,
+ "source": {
+ "repo": "https://github.com/omnirush-ai/omnirush-starter",
+ "commit": "4cd6fcedc62f604522db3621e5c509475ada6a0f"
+ },
+ "license": "MIT License\n\nCopyright (c) 2026 OmniRush contributors\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n",
+ "systemPrompt": "OmniRush Best practices\n\nHelp the user finish the software task they asked for. Use these guides only for relevant project work; keep ordinary chat brief.\n- Follow the user's current request and the repository's own instructions. Find the intended app folder and preserve unrelated work.\n- Keep the existing stack, tools, model, and account choices. Do not install the starter kit, create its templates, or change global settings unless requested.\n- For useful work, choose the relevant omnirush-setup, feature, debug, test, refactor, performance, build, review, or handoff guide. Load only the guides needed now.\n- Explain unfamiliar choices in small steps. Continue clear, authorized local work without repeated permission questions. Ask when a missing choice changes the result or required authority is absent.\n- Define the user-visible result, make a focused change, run the project's real checks, and use the latest feedback to finish the same task. Never call an unrun check passed.\n- Use bounded independent agent work only when it helps. Give each agent a clear scope and verify the combined result. Do not create extra turns, code, or calls to meet activity targets.\n- Keep raw private notes in their existing private location. Do not copy them into the project for these guides. Use placeholders for secrets; keep passwords, tokens, keys, and private payloads out of committed files, logs, reports, and examples. Do not read private inputs unless the authorized task needs them. Send private material elsewhere only when the user has authorized that action.\n- Summarize what changed, what was checked, how to try it, and any real gap. For longer work, use the project's existing notes or handoff location to save the next step.",
+ "skills": [
+ {
+ "name": "omnirush-build",
+ "description": "Diagnose and repair a failing build, typecheck, package step, or toolchain setup in an OmniRush project. Reproduce the exact command, isolate the cause, and verify the intended output.",
+ "content": "---\nname: omnirush-build\ndescription: \"Diagnose and repair a failing build, typecheck, package step, or toolchain setup in an OmniRush project. Reproduce the exact command, isolate the cause, and verify the intended output.\"\n---\n\n# Repair the failing build\n\nStart from the user's latest failing command and useful error output.\nUse the project's existing goal and setup notes for the required setup and target platform.\n\n## Capture the failure\n\n- Record the exact command, working folder, revision, and first relevant error.\n- Record the operating system, architecture, runtime, package manager, and build tool versions.\n- Check the relevant configuration and whether installed dependencies match the lockfile.\n- Check the current diff and preserve unrelated work.\n- Reproduce in the same relevant environment before claiming a cause.\n- Keep credentials and private data out of logs and reports.\n- If the target platform is unavailable, state that limit and investigate the files locally.\n- Do not invent a failure or force a build step on a project that does not need one.\n\n## Isolate the cause\n\n- Decide whether evidence points to source code, a dependency, the toolchain, or configuration.\n- Trace the first useful error; later errors may be caused by the same failure.\n- Inspect the relevant script and official tool documentation when its behavior is unfamiliar.\n- Use a small local experiment to test the suspected cause before changing more files.\n- Compare required and installed versions rather than upgrading everything at once.\n- Treat missing external access or credentials as a specific gap, not a proven code defect.\n- Use an independent native subagent for bounded log analysis or platform review when useful and available.\n- Give it a clear read or write scope and check its evidence before applying a result.\n\n## Repair the affected part\n\n- Make the smallest repair supported by the failure evidence.\n- Keep the user's stack, account, and model choice. Avoid changing global setup.\n- Add or replace dependencies only when the requested scope authorizes that change.\n- Use the existing package manager and keep dependency changes consistent with its lockfile.\n- Do not silence errors, disable required checks, or replace a failing command with a no-op.\n- Avoid deleting unrelated files or broad cache resets as a first step.\n- When stale generated output is proven relevant, clear only that known output and rebuild.\n- Keep platform-specific settings limited to the affected target.\n\n## Prove the repair\n\n- Rerun the original command in the recorded environment and inspect its exit status.\n- Confirm the expected artifact or output exists and can be used where practical.\n- Run the nearest related build or package check that could expose a regression.\n- Run relevant app tests when source behavior changed.\n- Update an incorrect configured check only when the new command matches the real project.\n- Report test, lint, typecheck, and build results, including unavailable or unrun checks.\n- Label every target platform that was not tested.\n- A local build does not prove release signing, deployment, or a user flow works.\n- Stop when the original failure is resolved and the affected output is checked.\n\nFinish with the cause, focused repair, exact commands, and verified target platform.\nKeep any remaining toolchain, access, or platform gap explicit.\nDo not call a proposed repair verified until the original reproduction passes.\n",
+ "sourceSha256": "c3d89918327afc3e34d3ab1929e281296ed7a74ba0cefa60f271c8fd37efbd35"
+ },
+ {
+ "name": "omnirush-debug",
+ "description": "Find and fix a reported bug in an OmniRush software project. Reproduce the failure, identify its cause, make a focused fix, and check for regression.",
+ "content": "---\nname: omnirush-debug\ndescription: \"Find and fix a reported bug in an OmniRush software project. Reproduce the failure, identify its cause, make a focused fix, and check for regression.\"\n---\n\n# Fix a bug with evidence\n\nStart from the user's latest error, logs, or reproduction steps.\nRead the project's existing goal and setup notes for the expected behavior and local setup.\n\n## Reproduce the failure\n\n- Write down the expected result and the actual result.\n- Find the smallest input or user action that shows the difference.\n- Use the same relevant runtime, configuration, and data as the failing case.\n- Capture the exact failing command or steps and the useful error output.\n- Keep passwords, tokens, and private user data out of logs and reports.\n- When reproduction is blocked, state the missing input or service precisely.\n- Continue with useful local investigation while avoiding claims of a proven cause.\n\n## Find the cause\n\n- Trace the failing action through the affected code and its callers.\n- Separate observed facts from guesses.\n- Test one plausible cause with a small experiment before changing more code.\n- Check recent edits, configuration, and dependency usage when the evidence points there.\n- Use current logs to update the diagnosis instead of defending an earlier guess.\n- Stop broad searching when the failing behavior and its cause are explained.\n- For independent possible causes, use a bounded native subagent investigation when it helps. Compare its evidence with the same reproduction and keep edits owned by one agent per file.\n\n## Make a focused fix\n\n- Read the relevant diff and preserve unrelated work.\n- Add a regression test that fails for the original bug when practical.\n- Use an existing test tool. Do not add dependencies just to reproduce the error.\n- For a UI or environment bug without a suitable test harness, save repeatable smoke steps.\n- Change the smallest part that causes the failure.\n- Avoid broad rewrites or unrelated cleanup during the repair.\n\n## Verify the repair\n\n- Repeat the original reproduction and check the expected result.\n- Run the regression test and a relevant neighboring case.\n- Run the project's applicable check commands from their actual working folders.\n- Report test, lint, typecheck, and build states, including checks not available or not run.\n- If the fix cannot be verified, describe the remaining gap and next concrete check.\n- Do not treat disappearing error text alone as proof that the user's task now works.\n- When the user supplies new logs or tries the result, update the diagnosis from that evidence. Keep the same goal until the original failure is resolved or a specific blocker remains.\n\nFinish with the cause, the fix, and the commands or steps that prove the result.\nDistinguish a verified repair from a proposed fix.\n",
+ "sourceSha256": "02f1d44993b531a59b061b4970411fad696607380489af67a7fa9e2694d7505a"
+ },
+ {
+ "name": "omnirush-feature",
+ "description": "Build a requested feature in an OmniRush software project. Turn the user outcome into acceptance criteria, implement the smallest complete flow, and verify it.",
+ "content": "---\nname: omnirush-feature\ndescription: \"Build a requested feature in an OmniRush software project. Turn the user outcome into acceptance criteria, implement the smallest complete flow, and verify it.\"\n---\n\n# Build one useful feature\n\nRead the project's existing goal and setup notes and the instructions for the affected code.\nUse the existing stack and conventions.\n\n## Define the result\n\n- Turn the request into observable acceptance criteria before editing.\n- Describe who takes the action, what they do, and what they should see.\n- Include the relevant empty, invalid, or failure state.\n- Keep the criteria within the user's request. Do not add a product roadmap.\n- For a small change, a few sentences are enough. Do not require a formal plan.\n- Ask only when an unresolved choice changes the requested behavior materially.\n- Use the relevant supplied source when requirements come from notes. Keep suggestions and open conflicts distinct from agreed behavior.\n\nExample: \"A user can save a note, reopen it, and see the same text. An empty note shows a clear error.\"\n\n## Follow the existing flow\n\n- Inspect the affected entry point, data flow, and existing tests.\n- Read `git status` and the relevant diff to preserve unrelated work.\n- Use existing components and utilities before adding new ones.\n- Keep each step usable from the real interface to the real result.\n- Do not claim a feature is complete because a button or endpoint exists alone.\n- If the requested flow stores data, verify that data can be read back.\n- Keep temporary mocks separate from claims about real application behavior.\n- For substantial work, use a bounded independent investigation, test design, or review when a native subagent can help. Give each agent a clear scope and integrate its evidence.\n- Explain a needed choice in small steps. Continue clear local implementation and checks after the explanation.\n- Add a dependency only when the requested application needs it and user scope permits it.\n\n## Prove the behavior\n\n- Add or update a test when it protects meaningful behavior changed by this feature.\n- Test the user's outcome and the relevant boundary, not the code's internal shape.\n- Use a direct smoke check for a low-impact change when a new test adds little value.\n- Run the smallest check that proves each acceptance criterion.\n- Run the project's applicable check commands from their actual working folders.\n- Report test, lint, typecheck, and build states explicitly, including missing checks.\n- If a check fails, resolve failures caused by this change and rerun that check.\n- If a failure is unrelated, give evidence and keep it visible in the result.\n- Try the real user flow when possible. Use the user's latest feedback to fix unmet criteria in this same task. Keep the project's existing notes current for work that spans chats.\n\nFinish with what works, how it was checked, and any criterion still unmet.\nName the changed files and the exact commands that produced the evidence.\nDo not call an unrun check passed.\n",
+ "sourceSha256": "e29fc2643382ed31c3f35878fee6d30d53daaf52db87285fa148f291ceaf6695"
+ },
+ {
+ "name": "omnirush-handoff",
+ "description": "Save a resumable software-project handoff. Record the goal, changed files, actual checks, open work, and the next concrete step in the project's existing handoff location.",
+ "content": "---\nname: omnirush-handoff\ndescription: \"Save a resumable software-project handoff. Record the goal, changed files, actual checks, open work, and the next concrete step in the project's existing handoff location.\"\n---\n\n# Save enough to resume work\n\nRead the project's existing notes and the current working tree first.\nUse an existing handoff location or the destination requested by the user.\nIf no file location is agreed, give a concise handoff in the reply.\nDo not create starter templates or copy raw private notes into the project.\n\n## Capture current evidence\n\n- Use the user's latest scope and decisions as the current goal.\n- Identify the repository, branch, and revision when Git is available.\n- Read `git status` and the relevant diff to identify changed files.\n- Distinguish your changes from unrelated work already present.\n- Use command output from this session for results, not remembered expectations.\n- Read an existing handoff before updating it so useful unresolved work survives.\n- Keep credentials, tokens, and private payloads out of the handoff.\n\n## Write the handoff\n\nKeep these parts brief and specific:\n\n1. **Goal:** The desired result and acceptance criteria still in scope.\n2. **State:** What works now, what is incomplete, and what is blocked.\n3. **Files:** Changed paths and the reason for each meaningful change.\n4. **Decisions:** Choices that affect the next step and their concrete reasons.\n5. **Checks:** Exact commands, working folders, results, and relevant output.\n6. **Next step:** One action the next session can start without guessing.\n\nList test, lint, typecheck, and build separately in the checks section.\nUse clear states such as passed, failed, missing, skipped, or not run.\nInclude the cause of each gap and what is needed to close it.\nRecord manual smoke steps and their observed result when they are the only evidence.\nLabel stale results with the revision or time they describe.\n\nInclude useful failed attempts, the user's latest feedback, and any source conflict\nthat affects unfinished work. For parallel work, save unresolved agent tasks and\nfile ownership so the next chat can integrate results without repeating the work.\n\n## Make the next step usable\n\n- Give an exact file, command, or reproduction step where possible.\n- Record a running process and how to inspect it if it matters to resuming work.\n- Do not stop processes, reset changes, commit, or push just to create a handoff.\n- Check that named paths still exist and that the next step follows from current state.\n- Do not mark acceptance criteria complete if their checks have not run.\n- Do not describe an uncommitted change as merged or a local build as deployed.\n\nFinish with the saved path, current result, and next action.\n",
+ "sourceSha256": "5289438f13d1e44995c6661565a1a259b2b78b94d6187d874c8ef6dd3c3e40e7"
+ },
+ {
+ "name": "omnirush-performance",
+ "description": "Measure and improve a reported speed, memory, or resource problem in an OmniRush project. Use a real workload, a recorded baseline, and fair comparisons to prove the result.",
+ "content": "---\nname: omnirush-performance\ndescription: \"Measure and improve a reported speed, memory, or resource problem in an OmniRush project. Use a real workload, a recorded baseline, and fair comparisons to prove the result.\"\n---\n\n# Improve a measured bottleneck\n\nStart from the slow or costly action the user actually needs to improve.\nUse the project's existing goal and setup notes for the user's goal and required behavior.\n\n## Choose what to measure\n\n- Define the real workload: action, input size, data, and relevant user conditions.\n- Choose a useful metric, such as elapsed time, peak memory, or requests per second.\n- Record its units and what success would mean for this task.\n- Keep the user's existing runtime, account, and model choice.\n- Check the current diff and preserve unrelated work.\n- If there is no demonstrated performance problem, measure before proposing a rewrite.\n- Use a local or isolated workload when a benchmark could change live data or services.\n\n## Record the baseline before edits\n\n- Save the exact command or steps, revision, runtime, platform, and relevant settings.\n- Keep input data and workload size fixed for the comparison.\n- State whether the test uses a cold start or a warm cache. Match the real use case.\n- Repeat the measurement enough to see normal variation; keep the individual results.\n- Use the same summary for both versions, such as the median of repeated runs.\n- Note competing work or outside services that can make the result noisy.\n- Set a cutoff before a costly measurement. Stop at that limit and keep incomplete runs separate from completed samples.\n- Save a reproducible command or small benchmark when it will be used again.\n- Run a relevant functional check so speed is not compared across broken behavior.\n\n## Find and change the costly part\n\n- Profile or trace the measured path with existing tools before choosing an edit.\n- Identify where time or memory is spent and test the likely cause with a small experiment.\n- Change the smallest part that explains the measured cost.\n- Reuse existing tools and dependencies unless the user authorized a new dependency.\n- Keep correctness, error handling, and the required output intact.\n- Check whether caching or batching changes freshness, memory use, or response order.\n- Use an independent native subagent for bounded profiling or review when useful and available.\n- Give it a clear scope and integrate its measurements without overlapping edits.\n\n## Compare fairly\n\n- Repeat the baseline workload on the changed revision with the same environment and data.\n- Record both revisions; compare only the intended change and disclose other differences.\n- Use the same warmup, measurement method, units, and summary for both runs.\n- If the environment changed, rerun a comparable baseline or label the result uncertain.\n- On a noisy shared host, a bounded alternating before/after run can reduce order bias. If comparable runs cannot finish, report an inconclusive result and the next useful measurement.\n- Report the before and after values, absolute difference, and percentage when meaningful.\n- Keep normal variation visible. A result inside that variation is not a proven improvement.\n- Run relevant functional checks and an adjacent workload that could become worse.\n- Revert an ineffective trial without discarding unrelated work.\n- Stop once the requested target is met or evidence shows the remaining limit.\n\nFinish with the workload, bottleneck, exact measurement steps, and observed result.\nState tradeoffs and untested conditions. Do not generalize beyond the measured workload.\nIf no reliable gain was found, say so and report the evidence.\n",
+ "sourceSha256": "412d138c302f026e19ca38ee401ef98d12a24201c150b7a5e002fad7643a3247"
+ },
+ {
+ "name": "omnirush-refactor",
+ "description": "Refactor existing OmniRush project code while preserving required behavior. Use for cleanup, module changes, or interface migrations that need caller checks and regression evidence.",
+ "content": "---\nname: omnirush-refactor\ndescription: \"Refactor existing OmniRush project code while preserving required behavior. Use for cleanup, module changes, or interface migrations that need caller checks and regression evidence.\"\n---\n\n# Improve code without breaking its use\n\nKeep the user's requested result and the current public behavior clear.\nUse the project's existing goal and setup notes for accepted behavior and compatibility needs.\n\n## Find the boundary\n\n- Name the problem the change should solve, such as duplicate rules or a hard-to-change module.\n- Inspect the affected code, its callers, exports, and relevant tests before editing.\n- Include callers outside the repo when a public API or saved file format is involved.\n- Identify behavior that must stay the same and any change the user already requested.\n- Check the current diff and keep unrelated edits intact.\n- For a small local cleanup, a short scope note is enough. Do not require a formal plan.\n- Do not invent a refactor need when the existing code already meets the request.\n\n## Establish useful evidence\n\n- Run the relevant existing checks and record the starting revision and result.\n- If behavior lacks coverage and the change could break it, add a focused check first.\n- Cover actual inputs and outputs, not the names or structure of private helpers.\n- Include the boundary most likely to change, such as errors, defaults, or repeated calls.\n- Use repeatable smoke steps when an automated check would add little value.\n- Record existing failures separately so they are not hidden or blamed on this change.\n\n## Make a safe change\n\n- Prefer removing duplication and reusing existing code over adding a new layer.\n- Preserve the user's stack. Add no dependency unless the requested scope authorizes it.\n- Move or replace one connected part at a time when the change crosses module boundaries.\n- Update imports, callers, and tests together so each slice remains usable.\n- Keep public compatibility until callers can move, or state the authorized breaking change.\n- Check saved data, serialization, caches, and migrations if the change touches their format.\n- Keep a recovery path for a data migration. Do not use live user data as a test fixture.\n- Separate a required behavior change from cleanup so its effect can be checked clearly.\n- Use an independent native subagent for a bounded caller search or review when useful and available.\n- Give it clear file ownership, preserve others' work, and check its evidence before use.\n\n## Verify the whole affected path\n\n- Run the baseline checks again after the change and compare their behavior.\n- Check both sides of a moved interface: the caller and the code it calls.\n- Confirm old data can still be read when compatibility is required.\n- For an authorized format change, test the migration and the intended recovery path.\n- Run relevant configured app checks and inspect their output and exit status.\n- Fix failures caused by the change. Keep unrelated failures visible with evidence.\n- Stop when the requested cleanup works and the affected behavior is checked.\n\nFinish with what became simpler, which callers or formats changed, and the checks run.\nInclude the starting evidence, final results, and any compatibility or data gap.\nDo not report preserved behavior on a platform or path that was not checked.\n",
+ "sourceSha256": "f9986ed9a86eacf54549bbcb663f5784b332e5610b3cefabf5b377c14cae225a"
+ },
+ {
+ "name": "omnirush-review",
+ "description": "Review a named change in an OmniRush software project for bugs, broken behavior, and missing checks. Report actionable findings with evidence; do not edit code unless asked.",
+ "content": "---\nname: omnirush-review\ndescription: \"Review a named change in an OmniRush software project for bugs, broken behavior, and missing checks. Report actionable findings with evidence; do not edit code unless asked.\"\n---\n\n# Review the requested change\n\nReview the user's named files, diff, branch, or pull request.\nRead the project's existing goal and setup notes for the expected product behavior.\nKeep the review read-only unless the user also requests fixes.\n\n## Establish the scope\n\n- Identify the base and changed revision when reviewing a branch or pull request.\n- Read the full changed behavior and enough surrounding code to understand its callers.\n- Check existing work so unrelated edits are not attributed to the reviewed change.\n- Compare the result with the request and its acceptance criteria.\n- Keep supplied source decisions and actual user feedback in scope. Confirm that the final flow meets them.\n- If the intended revision cannot be found, state that limit before making claims.\n\n## Look for user-visible failures\n\n- Follow changed inputs through validation, processing, storage, and output.\n- Check relevant empty, invalid, error, and repeated-action paths.\n- Examine access control or private data boundaries when the change touches them.\n- Check interface compatibility and whether callers still use the correct contract.\n- Inspect tests for assertions that could catch the likely failures.\n- Distinguish a real regression from a possible improvement outside the request.\n- Do not demand new abstractions or dependencies for a small working change.\n\n## Verify suspicious behavior\n\n- Use a small local test or reproduction when it can confirm a finding safely.\n- Inspect check commands before running them for deploy, delete, or external effects.\n- Use an isolated temporary fixture if proving a finding requires test data.\n- Record the exact command, result, and revision checked.\n- Do not edit tracked files merely to make the review pass.\n- Mark findings that depend on unverified assumptions clearly.\n\n## Report findings that can be acted on\n\nFor each finding, give the affected file and line, the trigger, the consequence,\nand the smallest useful correction. Order findings by impact.\n\n- A blocking finding must explain how the requested behavior breaks.\n- Keep optional style suggestions separate from correctness findings.\n- Include a summary of checks run and validation gaps.\n- If no actionable issue was found, say so and state what the review covered.\n- Do not turn \"no findings\" into a claim that all tests passed.\n\nFinish with whether the reviewed change meets the requested behavior and why.\n",
+ "sourceSha256": "f8879eb2491bbe2ccb3a9d4825b5de01934393ed2f61908bb517f049f62c9aae"
+ },
+ {
+ "name": "omnirush-setup",
+ "description": "Set up a new or existing software project. Find the user's goal, current stack, and real project checks before development.",
+ "content": "---\nname: omnirush-setup\ndescription: \"Set up a new or existing software project. Find the user's goal, current stack, and real project checks before development.\"\n---\n\n# Set up the project\n\nMake the project goal and its check commands clear enough to start useful work.\nRead the repository instructions and existing setup documentation.\nConfirm the required runtime before using it.\nReport a missing runtime as a setup gap; do not silently install it.\n\n## Learn what is being built\n\n- Read the user's request, repository instructions, and existing project files.\n- Find the intended application folder. A parent workspace can contain several separate repos.\n- Find the intended users, the problem to solve, and the first useful result.\n- Identify the stack from source files, manifests, and build configuration.\n- Keep the user's chosen stack. Do not pick a framework just to fill a blank.\n- For an empty project, describe the first user flow before choosing its tools.\n- Ask one short question only when a missing answer changes the product or stack.\n- State low-risk assumptions and continue work that does not depend on the answer.\n- For supplied notes, read the relevant sections and separate agreed needs, suggestions, and conflicts. Record the source of decisions; ask only about conflicts that affect the next task.\n- Explain one needed concept at a time as you do the work. Keep the first result small enough to try.\n\n## Find the real checks\n\n- Read existing scripts, CI configuration, and project documentation.\n- Locate the application root. It can differ from the parent workspace.\n- Identify separate test, lint, typecheck, and build commands where they exist.\n- Inspect commands before running them for deploy, delete, or other external effects.\n- Run available local checks from their actual working folders.\n- Record each result and any missing tool or service needed to run it.\n- Keep a failing but valid command configured. Its failure is useful evidence.\n- Do not count checks for OmniRush guides as application validation.\n- Do not invent a check or install dependencies only to make all four slots green.\n\n## Keep useful setup notes\n\nUse the project's existing documentation or a short reply to record the goal,\nusers, scope, stack, first acceptance criteria, exact checks, and remaining gaps.\nCreate or change a project document only when the task calls for it.\nDo not install a starter kit or create starter-specific configuration by default.\n\n- Record each actual check command and its working folder.\n- Keep valid failing checks visible; do not replace them with no-op commands.\n- Explain checks that do not apply and checks that cannot run.\n- A project needs meaningful checks for its changed behavior.\n- Use a bounded timeout for long checks and keep incomplete results separate.\n\nRun applicable project checks and read their output and exit status.\nMissing, skipped, and failed checks are not passes.\n\nIf the user also asked to build or fix something, continue to that task after setup.\nChoose the relevant skill and finish a useful, checked slice. Show how to try the result.\n\nFinish with the project goal, checks that ran, remaining gaps, and the first next step.\n",
+ "sourceSha256": "105aa650c0b9a94aebc4ac93bb673857d8dfe8736ceff2f52b56824f83b5714e"
+ },
+ {
+ "name": "omnirush-test",
+ "description": "Add or run meaningful tests for an OmniRush software project. Check user behavior and important boundaries with the existing test tools, and report actual coverage gaps.",
+ "content": "---\nname: omnirush-test\ndescription: \"Add or run meaningful tests for an OmniRush software project. Check user behavior and important boundaries with the existing test tools, and report actual coverage gaps.\"\n---\n\n# Test behavior that matters\n\nRead the project's existing goal and setup notes, the requested behavior, and nearby tests.\nChoose checks that could catch a real mistake in that behavior.\n\n## Choose the cases\n\n- Identify the public input, action, and observable result.\n- Test the main successful case and the boundary most likely to fail.\n- Include invalid, empty, missing, or repeated input when it affects the contract.\n- For a fixed bug, use the smallest case that exposed the original failure.\n- For stored data, check read-back or persistence when the feature requires it.\n- For access control or payments, check the relevant rejection path as well as success.\n- Do not add unrelated cases only to raise a coverage percentage.\n- Tie each case to the task's acceptance criteria. A substantial change can benefit from an independent native subagent identifying missing cases; check its evidence before adding them.\n\n## Use the right level\n\n- Reuse the project's test runner, helpers, and conventions.\n- Use a unit test for a pure rule and an integration test for connected behavior.\n- Use a browser or manual smoke check when the visible interaction is the contract.\n- Mock only boundaries that the test does not need to prove.\n- Do not mock the behavior under test and then report that the real flow passed.\n- Avoid assertions on private helper calls, file wording, or the implementation's shape.\n- Keep time, random values, and shared state controlled when they affect the result.\n- Add a test dependency only when the requested application needs it and user scope permits it.\n\n## Run and read the result\n\n- Confirm that the test command discovers the new or changed cases.\n- For a regression test, confirm it detects the old failure when feasible.\n- Run targeted tests first, then the related suite when the change needs it.\n- Inspect failures and exit status. A command that ran zero tests proves no test cases.\n- Keep skipped tests visible and explain any required service or fixture that is absent.\n- Correct a proven wrong project check using the project's existing configuration.\n- A missing test command remains a gap; use repeatable smoke steps when practical.\n- Explain inapplicable lint, typecheck, or build checks without pretending they passed.\n- Run relevant existing project checks; do not create a separate runner by default.\n- Report test, lint, typecheck, and build states separately.\n\nIf no test tool exists, use repeatable smoke steps and record the gap in the project's existing notes.\nDo not substitute checks for these guides for application tests.\n\nFinish with the behavior checked, exact commands, results, and important gaps.\n",
+ "sourceSha256": "d0bec6803dde60d6625493bfd0992438b984d353ed29cc7aa89bb09bdc1c30aa"
+ }
+ ]
+}
diff --git a/apps/server/src/engine-pool.test.ts b/apps/server/src/engine-pool.test.ts
index a33582fe..494b7025 100644
--- a/apps/server/src/engine-pool.test.ts
+++ b/apps/server/src/engine-pool.test.ts
@@ -1068,6 +1068,23 @@ describe("engine pool", () => {
const roles = pool.snapshot().generations.map((entry) => entry.role).sort();
expect(roles).toEqual(["draining", "primary"]);
+
+ // The settings API must not report a parked change as already applied.
+ // It preserves the streaming generation while the saved choice waits.
+ const server = await startServer(fixture.config);
+ try {
+ const response = await fetch(`http://127.0.0.1:${server.port}/runtime-config/best-practices`, {
+ method: "PUT",
+ headers: { authorization: `Bearer ${fixture.config.token}`, "content-type": "application/json" },
+ body: JSON.stringify({ enabled: false }),
+ });
+ expect(response.status).toBe(200);
+ expect(await response.json()).toEqual({ ok: true, changed: true, enabled: false, engine: { status: "deferred" } });
+ expect(primary.isAlive()).toBe(true);
+ expect((await fixture.logLines()).some((line) => line.includes("/abort"))).toBe(false);
+ } finally {
+ await server.stop();
+ }
});
test("leaves the live engine serving when the standby cannot start", async () => {
diff --git a/apps/server/src/managed-policy-rules.ts b/apps/server/src/managed-policy-rules.ts
index d71ea981..8563c8e7 100644
--- a/apps/server/src/managed-policy-rules.ts
+++ b/apps/server/src/managed-policy-rules.ts
@@ -153,7 +153,7 @@ export function policyRequestActions(method: string, path: string): ManagedPolic
const actions: ManagedPolicyAction[] = [];
if (/^\/workspaces\/(local|remote)$/.test(path)) actions.push("workspace");
if (/^\/runtime-config\/providers$/.test(path)) actions.push("provider");
- if (/^\/runtime-config\/approvals$/.test(path)) actions.push("settings");
+ if (/^\/runtime-config\/(?:approvals|best-practices)$/.test(path)) actions.push("settings");
if (path === "/omnirush/subagent-model") actions.push("settings");
if (/^\/workspace\/[^/]+\/(?:cloud-plugins|claude-plugins|plugins|skills|commands|mcp)(?:\/|$)/.test(path)
&& !/\/mcp\/[^/]+\/(?:auth|managed\/connect)$/.test(path)) actions.push("extensions");
diff --git a/apps/server/src/omnirush-runtime-config.test.ts b/apps/server/src/omnirush-runtime-config.test.ts
index 43839cfd..20ff7fc2 100644
--- a/apps/server/src/omnirush-runtime-config.test.ts
+++ b/apps/server/src/omnirush-runtime-config.test.ts
@@ -34,6 +34,9 @@ import {
type OmniRushModelCatalog,
} from "./omnirush-model-catalog.js";
import { gitWorkflowPermissionRules } from "./git-command-policy.js";
+import { OMNIRUSH_AGENT_PROMPT } from "./omnirush-agent-prompt.js";
+import { BestPracticesEngineReloads, OMNIRUSH_BEST_PRACTICES, omnirushBestPracticesSkillsDir, waitForBestPracticesReady } from "./best-practices.js";
+import { buildEngine2Config } from "./engine2/config.js";
import type { ServerConfig } from "./types.js";
const roots: string[] = [];
@@ -412,12 +415,115 @@ describe("omnirush runtime config file", () => {
const parsed = JSON.parse(await readFile(path, "utf8")) as { skills?: { paths?: string[] } };
const skillsDir = omnirushRuntimeSkillsDir(config);
expect(skillsDir.startsWith(root)).toBe(true);
- expect(parsed.skills?.paths).toEqual([skillsDir]);
+ expect(parsed.skills?.paths).toEqual([skillsDir, omnirushBestPracticesSkillsDir(config)]);
expect(await readFile(join(skillsDir, OMNIRUSH_SWARM_SKILL_NAME, "SKILL.md"), "utf8")).toBe(omnirushSwarmSkillMarkdown());
// Without a server config (specs, previews) nothing points at a folder.
expect(buildOmniRushRuntimeConfigObjectFromSnapshot({}).skills).toBeUndefined();
});
+ test("best practices default on, opt out without removing swarm skills, and restore after restart", async () => {
+ const { config } = await setup();
+ const swarmDir = omnirushRuntimeSkillsDir(config);
+ const bestDir = omnirushBestPracticesSkillsDir(config);
+ expect(dirname(bestDir)).toBe(dirname(swarmDir));
+ expect(bestDir.startsWith(`${swarmDir}/`)).toBe(false);
+ const prompt = `${OMNIRUSH_AGENT_PROMPT}\n\n${OMNIRUSH_BEST_PRACTICES.systemPrompt}`;
+ await writeOmniRushRuntimeConfigFile(config);
+ const on = await readConfigFile(config);
+ expect(on).toMatchObject({ skills: { paths: [swarmDir, bestDir] }, agent: { omnirush: { prompt } } });
+ expect(on.bestPractices).toBeUndefined();
+ expect(OMNIRUSH_BEST_PRACTICES.skills).toHaveLength(9);
+ expect(OMNIRUSH_BEST_PRACTICES.source.commit).toBe("4cd6fcedc62f604522db3621e5c509475ada6a0f");
+ expect(OMNIRUSH_BEST_PRACTICES.license).toContain("MIT License");
+ for (const skill of OMNIRUSH_BEST_PRACTICES.skills) {
+ expect(await readFile(join(bestDir, skill.name, "SKILL.md"), "utf8")).toBe(skill.content);
+ }
+ expect(buildEngine2Config({ v1: on })).toMatchObject({ skills: [swarmDir, bestDir], agents: { omnirush: { system: prompt } } });
+
+ await writeGlobalRuntimeOpencodeConfig(config, (current) => ({ ...current, bestPractices: false }));
+ await writeOmniRushRuntimeConfigFile(config);
+ const off = await readConfigFile(config);
+ expect(off).toMatchObject({ skills: { paths: [swarmDir] }, agent: { omnirush: { prompt: OMNIRUSH_AGENT_PROMPT } } });
+ expect(off.bestPractices).toBeUndefined();
+ expect(buildEngine2Config({ v1: off })).toMatchObject({ skills: [swarmDir], agents: { omnirush: { system: OMNIRUSH_AGENT_PROMPT } } });
+ // A fresh config object, as on startup, still reads the local persisted choice.
+ expect(JSON.parse(await buildOmniRushRuntimeConfig({ ...config }))).toEqual(off);
+ expect(await readFile(join(swarmDir, OMNIRUSH_SWARM_SKILL_NAME, "SKILL.md"), "utf8")).toBe(omnirushSwarmSkillMarkdown());
+
+ await writeGlobalRuntimeOpencodeConfig(config, (current) => ({ ...current, bestPractices: true }));
+ await writeOmniRushRuntimeConfigFile(config);
+ expect(await readConfigFile(config)).toEqual(on);
+ });
+
+ test("attached-engine changes wait for busy folders, apply idle folders, and stop retrying at shutdown", async () => {
+ const { config } = await setup();
+ const first = config.workspaces[0];
+ const second = { ...first, id: "ws_second", path: join(first.path, "second") };
+ let busy = true;
+ const reloaded: string[] = [];
+ const reloads = new BestPracticesEngineReloads({
+ isBusy: async (workspace) => workspace.id === first.id && busy,
+ reload: async (workspace) => { reloaded.push(workspace.id); },
+ isPresent: () => true,
+ retryMs: 10,
+ });
+ try {
+ expect(await reloads.apply([first, second])).toBe("deferred");
+ expect(reloaded).toEqual([second.id]);
+ await new Promise((resolve) => setTimeout(resolve, 25));
+ expect(reloaded).toEqual([second.id]);
+ busy = false;
+ const deadline = Date.now() + 3_000;
+ while (reloaded.length === 1 && Date.now() < deadline) await new Promise((resolve) => setTimeout(resolve, 10));
+ expect(reloaded).toEqual([second.id, first.id]);
+ busy = true;
+ expect(await reloads.apply([first])).toBe("deferred");
+ reloads.stop();
+ busy = false;
+ await new Promise((resolve) => setTimeout(resolve, 25));
+ expect(reloaded).toEqual([second.id, first.id]);
+ await expect(reloads.apply([first])).rejects.toThrow("Best practices reloads stopped");
+ } finally {
+ reloads.stop();
+ }
+ });
+
+ test("a saved off choice neither materializes nor repairs the bundled guide folder", async () => {
+ const { config } = await setup();
+ await writeGlobalRuntimeOpencodeConfig(config, (current) => ({ ...current, bestPractices: false }));
+ const bestDir = omnirushBestPracticesSkillsDir(config);
+ await mkdir(dirname(bestDir), { recursive: true });
+ await writeFile(bestDir, "leave this path alone while off\n", "utf8");
+ await writeOmniRushRuntimeConfigFile(config);
+ expect(await readFile(bestDir, "utf8")).toBe("leave this path alone while off\n");
+ expect(await readConfigFile(config)).toMatchObject({ skills: { paths: [omnirushRuntimeSkillsDir(config)] } });
+ });
+
+ test("live apply waits for both native prompt and owned skill readiness, and times out honestly", async () => {
+ const { root, config } = await setup();
+ const owned = OMNIRUSH_BEST_PRACTICES.skills.map((skill) => ({ name: skill.name, location: join(omnirushBestPracticesSkillsDir(config), skill.name, "SKILL.md") }));
+ const user = { name: "omnirush-feature", location: join(root, ".opencode", "skills", "omnirush-feature", "SKILL.md") };
+ const stale = { agents: [{ name: "omnirush", prompt: `${OMNIRUSH_AGENT_PROMPT}\n\n${OMNIRUSH_BEST_PRACTICES.systemPrompt}` }], skills: [...owned, user] };
+ const promptReady = { agents: [{ name: "omnirush", prompt: OMNIRUSH_AGENT_PROMPT }], skills: [...owned, user] };
+ const allReady = { agents: promptReady.agents, skills: [user] };
+ let probes = 0;
+ await waitForBestPracticesReady({
+ config, enabled: false, timeoutMs: 1_000, intervalMs: 1,
+ read: async () => { probes += 1; return [probes === 1 ? stale : probes === 2 ? promptReady : allReady]; },
+ });
+ expect(probes).toBe(3);
+ await expect(waitForBestPracticesReady({
+ config, enabled: false, timeoutMs: 20, intervalMs: 1,
+ read: async () => [promptReady],
+ })).rejects.toThrow("Best practices engine readiness was not observed");
+ const overrides = OMNIRUSH_BEST_PRACTICES.skills.map((skill) => ({ name: skill.name, location: join(root, ".opencode", "skills", skill.name, "SKILL.md") }));
+ await waitForBestPracticesReady({ config, enabled: true, timeoutMs: 1_000, read: async () => [{ agents: stale.agents, skills: overrides }] });
+ await expect(waitForBestPracticesReady({
+ config, enabled: false, timeoutMs: 20, intervalMs: 1,
+ read: async () => [{ agents: allReady.agents, skills: [{ name: user.name, location: "" }] }],
+ })).rejects.toThrow("Best practices engine readiness was not observed");
+ });
+
test("keepOmniRushRuntimeConfigFileFresh rewrites the file on ENGINE_GLOBAL writes", async () => {
const { config } = await setup();
await writeOmniRushRuntimeConfigFile(config);
diff --git a/apps/server/src/omnirush-runtime-config.ts b/apps/server/src/omnirush-runtime-config.ts
index 3f87a4d0..b07baa39 100644
--- a/apps/server/src/omnirush-runtime-config.ts
+++ b/apps/server/src/omnirush-runtime-config.ts
@@ -54,6 +54,12 @@ import {
type OmniRushModelCatalog,
} from "./omnirush-model-catalog.js";
import { writeFileAtomic } from "./atomic-write.js";
+import {
+ OMNIRUSH_BEST_PRACTICES,
+ bestPracticesEnabled,
+ omnirushBestPracticesSkillsDir,
+ writeBestPracticesSkills,
+} from "./best-practices.js";
const INTERNAL_PROVIDER_ID = "omnirush";
@@ -132,6 +138,7 @@ export async function buildOmniRushRuntimeConfigObject(
process.env,
internalGateway && config ? await readOmniRushModelCatalog(config) : undefined,
config ? omnirushRuntimeSkillsDir(config) : undefined,
+ config ? omnirushBestPracticesSkillsDir(config) : undefined,
);
}
@@ -160,11 +167,17 @@ export function buildOmniRushRuntimeConfigObjectFromSnapshot(
env: NodeJS.ProcessEnv = process.env,
catalog: OmniRushModelCatalog = builtinOmniRushModelCatalog(),
skillsDir?: string,
+ bestPracticesDir?: string,
): Record<string, unknown> {
const disabledProviders = runtimeDisabledProviderList(runtimeConfig);
// OMNIRUSH_APPROVALS in the server environment wins over the persisted setting.
const permissions = legacyExecutionPermissions(runtimeConfig.managedPolicy?.execution, resolveApprovalMode(runtimeConfig, env).mode);
- const { managedPolicy: _managedPolicy, approvals: _approvals, ...engineConfig } = runtimeConfig;
+ const { managedPolicy: _managedPolicy, approvals: _approvals, bestPractices: _bestPractices, ...engineConfig } = runtimeConfig;
+ const enabled = bestPracticesEnabled(runtimeConfig);
+ const skillPaths = [
+ ...(skillsDir ? [skillsDir] : []),
+ ...(enabled && bestPracticesDir ? [bestPracticesDir] : []),
+ ];
const provider = {
...runtimeProviderMap(runtimeConfig),
...(internalGateway
@@ -191,7 +204,7 @@ export function buildOmniRushRuntimeConfigObjectFromSnapshot(
] } : onlyOwnProviders ? { enabled_providers: ownProviders } : {}),
permission: { ...engineConfig.permission, ...permissions },
// omnirush.ai's own on-demand skills (the swarm procedure).
- ...(skillsDir ? { skills: { paths: [skillsDir] } } : {}),
+ ...(skillPaths.length ? { skills: { paths: skillPaths } } : {}),
default_agent: runtimeConfig.default_agent ?? "omnirush",
// Sub-agent swarms: sub-agents may delegate again, up to this many layers
// below the main session (the engine's default of 1 forbids nesting).
@@ -202,7 +215,7 @@ export function buildOmniRushRuntimeConfigObjectFromSnapshot(
description: "omnirush.ai default agent",
mode: "primary",
temperature: 0.2,
- prompt: OMNIRUSH_AGENT_PROMPT,
+ prompt: enabled ? `${OMNIRUSH_AGENT_PROMPT}\n\n${OMNIRUSH_BEST_PRACTICES.systemPrompt}` : OMNIRUSH_AGENT_PROMPT,
permission: {
...permissions,
skill: {
@@ -308,6 +321,9 @@ export async function writeOmniRushRuntimeConfigFile(
// The config names the skills folder: write it first, so the engine
// never loads a config whose built-in skill is missing.
await writeOmniRushRuntimeSkills(config);
+ if (bestPracticesEnabled(await readGlobalRuntimeOpencodeConfig(config))) {
+ await writeBestPracticesSkills(config);
+ }
const content = await buildOmniRushRuntimeConfig(config);
const current = await readFile(path, "utf8").catch(() => undefined);
if (current === content) return { path, changed: false };
diff --git a/apps/server/src/runtime-opencode-config-store.test.ts b/apps/server/src/runtime-opencode-config-store.test.ts
index f4800139..f9ca4758 100644
--- a/apps/server/src/runtime-opencode-config-store.test.ts
+++ b/apps/server/src/runtime-opencode-config-store.test.ts
@@ -381,4 +381,29 @@ describe("runtime OpenCode config store", () => {
}
});
});
+
+ test("best practices is a narrow authenticated local setting, independent of workspace rows", async () => {
+ await withWorkspace(async ({ config }) => {
+ const server = await startServer(config) as Served;
+ const base = `http://127.0.0.1:${server.port}`;
+ const headers = { authorization: `Bearer ${config.token}`, "content-type": "application/json" };
+ try {
+ expect((await fetch(`${base}/runtime-config/best-practices`)).status).toBe(401);
+ expect(await (await fetch(`${base}/runtime-config/best-practices`, { headers })).json()).toEqual({ enabled: true });
+ for (const payload of [{ enabled: "false" }, {}, { enabled: false, projectPath: "private-notes" }]) {
+ expect((await fetch(`${base}/runtime-config/best-practices`, { method: "PUT", headers, body: JSON.stringify(payload) })).status).toBe(400);
+ }
+ const off = await fetch(`${base}/runtime-config/best-practices`, { method: "PUT", headers, body: JSON.stringify({ enabled: false }) });
+ expect(off.status).toBe(200);
+ expect(await off.json()).toEqual({ ok: true, enabled: false, changed: true, engine: { status: "unconfigured" } });
+ expect((await readGlobalRuntimeOpencodeConfig(config)).bestPractices).toBe(false);
+ await writeRuntimeOpencodeConfig(config, WORKSPACE_ID, (current) => ({ ...current, bestPractices: true }));
+ expect((await readEffectiveRuntimeOpencodeConfig(config, WORKSPACE_ID)).bestPractices).toBe(false);
+ expect(policyRequestActions("PUT", "/runtime-config/best-practices")).toEqual(["settings"]);
+ expect(await (await fetch(`${base}/runtime-config/best-practices`, { headers })).json()).toEqual({ enabled: false });
+ } finally {
+ await server.stop(true);
+ }
+ });
+ });
});
diff --git a/apps/server/src/runtime-opencode-config-store.ts b/apps/server/src/runtime-opencode-config-store.ts
index eaca29cd..a809a8cf 100644
--- a/apps/server/src/runtime-opencode-config-store.ts
+++ b/apps/server/src/runtime-opencode-config-store.ts
@@ -17,6 +17,8 @@ export type RuntimeOpencodeConfig = {
managedPolicy?: DesktopConfig;
/** User setting for the engine approval mode; global row only, OMNIRUSH_APPROVALS overrides it. */
approvals?: { mode: ApprovalMode };
+ /** Bundled development guidance; local engine-global setting, enabled when absent. */
+ bestPractices?: boolean;
default_agent?: string;
plugin?: string[];
disabled_providers?: string[];
@@ -52,6 +54,7 @@ function normalizeRuntimeOpencodeConfig(value: unknown): RuntimeOpencodeConfig {
...(defaultAgent ? { default_agent: defaultAgent } : {}),
...(value.managedPolicy !== undefined ? { managedPolicy: desktopConfigSchema.parse(value.managedPolicy) } : {}),
...(approvalMode ? { approvals: { mode: approvalMode } } : {}),
+ ...(typeof value.bestPractices === "boolean" ? { bestPractices: value.bestPractices } : {}),
...(plugin ? { plugin } : {}),
...(disabledProviders ? { disabled_providers: disabledProviders } : {}),
...(mcp ? { mcp } : {}),
@@ -272,6 +275,7 @@ export function mergeRuntimeOpencodeConfigLayers(
...(base.managedPolicy ? { managedPolicy: base.managedPolicy } : {}),
// The approval mode is engine-global like the managed policy.
...(base.approvals ? { approvals: base.approvals } : {}),
+ ...(typeof base.bestPractices === "boolean" ? { bestPractices: base.bestPractices } : {}),
...(base.default_agent || overlay.default_agent ? { default_agent: overlay.default_agent ?? base.default_agent } : {}),
...(plugin.length ? { plugin } : {}),
...(disabledProviders.length ? { disabled_providers: disabledProviders } : {}),
diff --git a/apps/server/src/server.ts b/apps/server/src/server.ts
index f09c8272..1a0c0584 100644
--- a/apps/server/src/server.ts
+++ b/apps/server/src/server.ts
@@ -202,6 +202,7 @@ import type { ArchiveApiRequestInit } from "./session-archive/upload.js";
import { runtimeStorageDir } from "./runtime-db.js";
import pkg from "../package.json" with { type: "json" };
import constants from "../../../constants.json" with { type: "json" };
+import { BestPracticesEngineReloads, waitForBestPracticesReady } from "./best-practices.js";
export {
isSupportedWorkspaceTextFilePath,
@@ -1102,6 +1103,11 @@ export async function startServer(config: ServerConfig): Promise<ServeResult> {
if (config.workspaces.length > 0) cloudProviderSync.markReloadPending();
};
const engineV2Preview = createEngineV2Preview({ config, env, deferStart: true });
+ const bestPracticesReloads = new BestPracticesEngineReloads({
+ isBusy: (workspace) => engineHasActiveSessions(config, workspace, true),
+ reload: (workspace) => reloadOpencodeEngine(config, workspace, engineMcpServerState, { reason: "engine_reload" }),
+ isPresent: (workspace) => config.workspaces.includes(workspace),
+ });
const routes = createRoutes(
config,
approvals,
@@ -1112,6 +1118,7 @@ export async function startServer(config: ServerConfig): Promise<ServeResult> {
logger,
cloudProviderSync,
engineV2Preview,
+ bestPracticesReloads,
);
const serverOptions: {
@@ -1399,6 +1406,7 @@ export async function startServer(config: ServerConfig): Promise<ServeResult> {
idleTimeout: 120,
});
} catch (error) {
+ bestPracticesReloads.stop();
// First, and synchronously: archive part uploads in flight are aborted now, not after the other shutdown steps.
const captureStopped = capture.stop();
await taskRecovery?.stop().catch(() => undefined);
@@ -1495,6 +1503,7 @@ export async function startServer(config: ServerConfig): Promise<ServeResult> {
// The project archive packs its final archives only while the account
// is still stored (an app quit, a restart), never after a sign-out.
const captureStopped = capture.stop({ archiveFinals: accountStillStored() });
+ bestPracticesReloads.stop();
let recoveryError: unknown;
try { await taskRecovery?.stop(); } catch (error) { recoveryError = error; }
await captureStopped;
@@ -2915,6 +2924,7 @@ function createRoutes(
logger: ServerLogger,
cloudProviderSync: CloudProviderSync,
engineV2Preview: EngineV2Preview,
+ bestPracticesReloads: BestPracticesEngineReloads,
): Route[] {
const routes: Route[] = [];
// A rollover-capable pool can apply this immediately without disposing
@@ -3576,6 +3586,70 @@ function createRoutes(
return jsonResponse({ ok: true, changed: result.changed, ...resolveApprovalMode(result.config) });
});
+ addRoute(routes, "GET", "/runtime-config/best-practices", "client", async () => {
+ const runtime = await readGlobalRuntimeOpencodeConfig(config);
+ return jsonResponse({ enabled: runtime.bestPractices !== false });
+ });
+
+ addRoute(routes, "PUT", "/runtime-config/best-practices", "client", async (ctx) => {
+ ensureWritable(config);
+ requireClientScope(ctx, "collaborator");
+ const body = await readJsonBody(ctx.request);
+ if (typeof body.enabled !== "boolean" || Object.keys(body).some((key) => key !== "enabled")) {
+ throw new ApiError(400, "invalid_payload", "enabled must be a boolean and the only field");
+ }
+ const enabled = body.enabled;
+ const result = await writeGlobalRuntimeOpencodeConfig(config, (current) => ({ ...current, bestPractices: enabled }));
+ // Persist first: a failed reload keeps the user's choice for the next start.
+ // Return a separate application status so the UI never calls it applied early.
+ try {
+ const pool = enginePoolForConfig(config);
+ const write = async () => { await writeOmniRushRuntimeConfigFile(config); };
+ if (pool && await pool.applyConfigLive(write)) {
+ const primary = primaryManagedEngineConnection(config);
+ if (!primary) throw new Error("Managed engine is unavailable");
+ const authorization = buildEngineAuthProbeHeader(primary.username, primary.password);
+ const baseUrl = primary.baseUrl.replace(/\/+$/, "");
+ const directories = [...new Set(config.workspaces
+ .filter((workspace) => resolveWorkspaceOpencodeConnection(config, workspace).baseUrl?.trim().replace(/\/+$/, "") === baseUrl)
+ .map(resolveOpencodeDirectory).filter((directory): directory is string => directory !== null))];
+ await waitForBestPracticesReady({
+ config, enabled,
+ read: async (signal) => await Promise.all(directories.map(async (directory) => {
+ const read = async (path: string): Promise<unknown> => {
+ const url = new URL(path, primary.baseUrl);
+ url.searchParams.set("directory", directory);
+ const response = await loopbackFetch(url, { headers: authorization ? { Authorization: authorization } : {}, signal });
+ if (!response.ok) throw new Error("Managed engine metadata is unavailable");
+ return await response.json();
+ };
+ const [agents, skills] = await Promise.all([read("/agent"), read("/skill")]);
+ return { agents, skills };
+ })),
+ });
+ return jsonResponse({ ok: true, enabled, changed: result.changed, engine: { status: "applied" } });
+ }
+ if (!pool) await write();
+ const workspaces = config.workspaces.filter((workspace) => resolveWorkspaceOpencodeConnection(config, workspace).baseUrl?.trim());
+ const workspace = findManagedEngineWorkspace(workspaces) ?? workspaces[0];
+ if (!workspace) {
+ return jsonResponse({ ok: true, enabled, changed: result.changed, engine: { status: "unconfigured" } });
+ }
+ if (pool) {
+ const outcome = await pool.requestRollover({ reason: "best_practices", workspace, manual: true });
+ const status = outcome.action === "coalesced" ? "deferred"
+ : outcome.action === "skipped" ? "failed" : "applied";
+ return jsonResponse({ ok: true, enabled, changed: result.changed, engine: { status } });
+ }
+ // Attached engines cache one instance per folder. Apply idle folders and
+ // safely retry every busy folder, without disposing an active reply.
+ const status = await bestPracticesReloads.apply(workspaces);
+ return jsonResponse({ ok: true, enabled, changed: result.changed, engine: { status } });
+ } catch {
+ return jsonResponse({ ok: true, enabled, changed: result.changed, engine: { status: "failed" } });
+ }
+ });
+
addRoute(routes, "PUT", "/den-session", "host-token", async (ctx) => {
ensureWritable(config);
const session = parseCloudProviderDenSession(await readJsonBody(ctx.request));
diff --git a/evals/packages/cdp/src/input.ts b/evals/packages/cdp/src/input.ts
index 43e3c398..f9f23aa9 100644
--- a/evals/packages/cdp/src/input.ts
+++ b/evals/packages/cdp/src/input.ts
@@ -1,7 +1,7 @@
import { callFunctionOnSurface, evaluateOnSurface } from "./surface.ts";
import type { Surface } from "./surface.ts";
-export type TargetRole = "button" | "link" | "textbox" | "checkbox" | "menuitem" | "tab" | "option";
+export type TargetRole = "button" | "link" | "textbox" | "checkbox" | "switch" | "menuitem" | "tab" | "option";
export type TargetMatcher = string | RegExp;
export type Target = string | {
@@ -216,7 +216,7 @@ export async function locate(surface: Surface, target: Target): Promise<Located>
? '[contenteditable="true"][data-lexical-editor="true"]'
: target.text && !target.role && !target.label && !target.placeholder && !target.testId
? 'body *'
- : 'button, a[href], input, textarea, select, [role="combobox"], [role="listbox"], [contenteditable="true"], [role="button"], [role="link"], [role="textbox"], [role="checkbox"], [role="menuitem"], [role="tab"], [role="option"], [data-testid]';
+ : 'button, a[href], input, textarea, select, [role="combobox"], [role="listbox"], [contenteditable="true"], [role="button"], [role="link"], [role="textbox"], [role="checkbox"], [role="switch"], [role="menuitem"], [role="tab"], [role="option"], [data-testid]';
const candidates = [...document.querySelectorAll<HTMLElement>(selector)].filter((element: Element) => {
if (target.role && implicitRole(element) !== target.role) return false;
if (target.placeholder !== undefined && (element.getAttribute("placeholder") ?? element.getAttribute("aria-placeholder")) !== target.placeholder) return false;
diff --git a/evals/packages/cdp/test/input.test.ts b/evals/packages/cdp/test/input.test.ts
index 24c53648..57b549be 100644
--- a/evals/packages/cdp/test/input.test.ts
+++ b/evals/packages/cdp/test/input.test.ts
@@ -71,6 +71,63 @@ test("locate reports visible button and link names when no target matches", asyn
);
});
+test("locate finds an accessible switch rendered as a span and keeps its click hit test", async () => {
+ class ElementFixture {
+ tagName = "SPAN";
+ children: ElementFixture[] = [];
+ parentElement = null;
+ innerText = "";
+ textContent = "";
+ scrolled = false;
+ attributes: Record<string, string> = { role: "switch", "aria-label": "Best practices" };
+ getAttribute(name: string) { return this.attributes[name] ?? null; }
+ hasAttribute(name: string) { return name in this.attributes; }
+ closest() { return null; }
+ getBoundingClientRect() { return { left: 10, top: 20, x: 10, y: 20, width: 44, height: 20 }; }
+ scrollIntoView() { this.scrolled = true; }
+ contains(element: unknown) { return element === this; }
+ }
+ const control = new ElementFixture();
+ const surface = surfaceReturning(null);
+ surface.client.send = async (method, params) => {
+ if (method === "Runtime.evaluate") return { result: { objectId: "global" } };
+ assert.equal(method, "Runtime.callFunctionOn");
+ assert.ok(params && typeof params.functionDeclaration === "string" && Array.isArray(params.arguments));
+ const serialized = params.arguments[0].value;
+ const value = runInNewContext(`(${params.functionDeclaration})(${JSON.stringify(serialized)})`, {
+ Element: ElementFixture,
+ HTMLElement: ElementFixture,
+ HTMLInputElement: class extends ElementFixture {},
+ HTMLTextAreaElement: class extends ElementFixture {},
+ HTMLSelectElement: class extends ElementFixture {},
+ HTMLButtonElement: class extends ElementFixture {},
+ innerWidth: 1280,
+ innerHeight: 900,
+ getComputedStyle: () => ({ display: "inline-flex", visibility: "visible", opacity: "1" }),
+ document: {
+ getElementById: () => null,
+ elementFromPoint: () => control,
+ querySelectorAll(selector: string) {
+ const matches = selector.split(",").some(part => {
+ const token = part.trim();
+ if (token === control.tagName.toLowerCase()) return true;
+ const attribute = /^\[([\w-]+)(?:="([^"]*)")?\]$/.exec(token);
+ return attribute ? control.hasAttribute(attribute[1]) && (attribute[2] === undefined || control.getAttribute(attribute[1]) === attribute[2]) : false;
+ });
+ return matches ? [control] : [];
+ },
+ },
+ });
+ return { result: { value } };
+ };
+ const located = await locate(surface, { role: "switch", label: "Best practices" });
+ assert.equal(located.tag, "span");
+ assert.equal(located.name, "Best practices");
+ assert.equal(located.visible, true);
+ assert.equal(located.hitTestOk, true);
+ assert.equal(control.scrolled, true);
+});
+
test("waitForLocated identifies the element covering a visible target", async () => {
const surface = surfaceReturning({
center: { x: 50, y: 25 },
diff --git a/evals/packages/testkit/src/spec/index.ts b/evals/packages/testkit/src/spec/index.ts
index 08c1324f..5c54a789 100644
--- a/evals/packages/testkit/src/spec/index.ts
+++ b/evals/packages/testkit/src/spec/index.ts
@@ -156,7 +156,7 @@ function world<W>(worldFn: WorldFn<W>, options: SpecWorldOptions = {}) {
step: [async (
{ specRuntimeContext }: { specRuntimeContext: RuntimeContext<W> },
use: (value: Step) => Promise<void>,
- ) => use(specRuntimeContext.step), {}],
+ ) => use(specRuntimeContext.step), { auto: false }],
});
return wrapTestApi(api);
}
diff --git a/evals/specs/best-practices.e2e.test.ts b/evals/specs/best-practices.e2e.test.ts
new file mode 100644
index 00000000..f319c3ed
--- /dev/null
+++ b/evals/specs/best-practices.e2e.test.ts
@@ -0,0 +1,61 @@
+import { spec } from "@omnirush/testkit";
+import { expect } from "vitest";
+import { bestPracticesDesktop } from "../worlds/best-practices-desktop.ts";
+
+const test = spec.world(bestPracticesDesktop, {
+ needs: { commands: ["bun"], placement: "local", env: ["OMNIRUSH_OPENCODE_BIN", "OMNIRUSH_EVAL_ELECTRON_RESOURCES_PREPARED"] },
+ timeout: 240_000,
+});
+
+test("Settings > General lets a user turn Best practices off and on and keeps the choice across restart", { timeout: 600_000 }, async ({ world, user, probe, step, evidence }) => {
+ await step("the setting starts on and uses plain guide-only help", async () => {
+ await user.see({ role: "switch", label: "Best practices" });
+ const state = await probe.eventually(() => world.state(), {
+ within: 30_000, intervalMs: 250, label: "default enabled Best practices switch",
+ until: (value) => value.exists && !value.disabled,
+ });
+ expect(state.enabled).toBe(true);
+ expect(state.help).toContain("Built-in guides");
+ expect(state.help).toContain("On by default");
+ expect(state.help.toLowerCase()).not.toContain("upload");
+ expect(await probe.desktopApi("/runtime-config/best-practices")).toEqual({ status: 200, body: { enabled: true } });
+ evidence.recordJsonArtifact("default Best practices UI state", state);
+ evidence.recordAssertionEvidence("Settings > General exposes an enabled Best practices switch with accurate guide help", "The visible, enabled switch reported aria-checked=true. The local server agreed. Help described built-in guides and on-by-default behavior without an upload promise or claim.", true);
+ });
+
+ await step("turning off saves the choice and shows the actual apply result", async () => {
+ await user.click({ role: "switch", label: "Best practices" });
+ const state = await probe.eventually(() => world.state(), {
+ within: 30_000, intervalMs: 250, label: "saved disabled Best practices switch",
+ until: (value) => !value.enabled && !value.disabled && value.status.includes("Best practices off"),
+ });
+ expect(state.status).toContain("Ready for your next request");
+ expect(await probe.desktopApi("/runtime-config/best-practices")).toEqual({ status: 200, body: { enabled: false } });
+ expect(await world.canaryUnchanged()).toBe(true);
+ evidence.recordJsonArtifact("off Best practices UI state", state);
+ evidence.recordAssertionEvidence("The user can turn Best practices off without changing private project bytes", "A real click changed the switch to unchecked. Its status reported off and ready for the next request, GET returned enabled=false, and the private fixture note stayed unchanged.", true);
+ });
+
+ await step("a fresh desktop process keeps off, and the user can turn it on again", async () => {
+ await world.restart();
+ const nextUser = user.on(world.app);
+ const nextProbe = probe.on(world.app);
+ await nextUser.see({ role: "switch", label: "Best practices" });
+ const restarted = await nextProbe.eventually(() => world.state(), {
+ within: 30_000, intervalMs: 250, label: "persisted off switch after desktop restart",
+ until: (value) => value.exists && !value.disabled,
+ });
+ expect(restarted.enabled).toBe(false);
+ expect(await nextProbe.desktopApi("/runtime-config/best-practices")).toEqual({ status: 200, body: { enabled: false } });
+ await nextUser.click({ role: "switch", label: "Best practices" });
+ const enabled = await nextProbe.eventually(() => world.state(), {
+ within: 30_000, intervalMs: 250, label: "restored enabled Best practices switch",
+ until: (value) => value.enabled && !value.disabled && value.status.includes("Best practices on"),
+ });
+ expect(enabled.status).toContain("Ready for your next request");
+ expect(await nextProbe.desktopApi("/runtime-config/best-practices")).toEqual({ status: 200, body: { enabled: true } });
+ expect(await world.canaryUnchanged()).toBe(true);
+ evidence.recordJsonArtifact("restarted off and restored on UI states", { restarted, enabled });
+ evidence.recordAssertionEvidence("The saved choice survives a desktop restart and can be restored in Settings", "A fresh Electron process on the same isolated profile showed off and GET confirmed it. A real click restored on and the applied status, while the private note remained byte-identical.", true);
+ });
+});
diff --git a/evals/specs/best-practices.test.ts b/evals/specs/best-practices.test.ts
new file mode 100644
index 00000000..413665d5
--- /dev/null
+++ b/evals/specs/best-practices.test.ts
@@ -0,0 +1,207 @@
+import { spec } from "@omnirush/testkit";
+import { expect } from "vitest";
+import {
+ bestPractices, bestPracticesAttached, BEST_PRACTICES_HEADING, BUNDLED_SKILLS, MOCK_REPLY, PRIVATE_CANARY, USER_SKILL,
+} from "../worlds/best-practices.ts";
+
+const test = spec.world(bestPractices, { needs: { commands: ["bun"], placement: "local" }, timeout: 240_000 });
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+ return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function skillNames(value: unknown): string[] {
+ if (!Array.isArray(value)) throw new Error("Expected the real engine's skill catalog.");
+ return value.filter(isRecord).map((skill) => typeof skill.name === "string" ? skill.name : "");
+}
+
+function replyText(value: unknown): string {
+ if (!isRecord(value) || !Array.isArray(value.parts)) return "";
+ return value.parts.filter(isRecord).map((part) => part.type === "text" && typeof part.text === "string" ? part.text : "").join("");
+}
+
+test("Best practices default on, toggle only the bundled guides, and survive a real server restart", { timeout: 480_000 }, async ({ world, probe, step, evidence }) => {
+ try {
+ const originalFiles = await world.snapshot();
+ await step("only authenticated clients can read or change the typed setting", async () => {
+ expect((await world.config("GET", undefined, false)).status).toBe(401);
+ expect((await world.config("PUT", { enabled: false }, false)).status).toBe(401);
+ for (const body of [{}, { enabled: "false" }, { enabled: false, other: true }]) {
+ expect((await world.config("PUT", body)).status).toBe(400);
+ }
+ expect(await world.config("GET")).toEqual({ status: 200, body: { enabled: true } });
+ expect(world.requests).toHaveLength(0);
+ evidence.recordAssertionEvidence("The setting defaults on and rejects anonymous or malformed changes", "Authenticated GET returned enabled=true. Anonymous GET/PUT returned 401. Missing, non-boolean, and extra fields returned 400 without changing the saved state or making model calls.", true);
+ });
+
+ await step("the actual native engine advertises built-in, user, and swarm skills", async () => {
+ const names = await probe.eventually(async () => skillNames(await world.engine("GET", "/skill")), {
+ within: 30_000, intervalMs: 250, label: "real engine best-practices catalog",
+ until: (names) => BUNDLED_SKILLS.every((name) => names.includes(name)) && names.includes(USER_SKILL),
+ });
+ expect(names).toEqual(expect.arrayContaining([...BUNDLED_SKILLS, USER_SKILL, "omnirush-swarm"]));
+ const before = world.requests.length;
+ expect(replyText(await world.send("Reply with a short acknowledgement. Do not use tools."))).toBe(MOCK_REPLY);
+ expect(world.requests.slice(before)).toHaveLength(1);
+ const request = world.requests.at(-1);
+ expect(request?.body.includes(BEST_PRACTICES_HEADING)).toBe(true);
+ expect(request?.body.includes(USER_SKILL)).toBe(true);
+ expect(request?.body.includes("omnirush-swarm")).toBe(true);
+ for (const name of BUNDLED_SKILLS) expect(request?.body.includes(name)).toBe(true);
+ expect(request?.body.includes(PRIVATE_CANARY)).toBe(false);
+ evidence.recordAssertionEvidence("The real engine's outgoing request includes the short guide prompt and native catalog", "The engine listed all nine bundled skills plus the user-owned guide and omnirush-swarm. One requested model turn carried the Best practices heading and skill names, and returned the deterministic reply without private canary content.", true);
+ });
+
+ await step("off removes the bundled prompt and catalog without a model request or project edit", async () => {
+ const before = world.requests.length;
+ expect(await world.config("PUT", { enabled: false })).toEqual({ status: 200, body: {
+ ok: true, enabled: false, changed: true, engine: { status: "applied" },
+ } });
+ const names = await probe.eventually(async () => skillNames(await world.engine("GET", "/skill")), {
+ within: 30_000, intervalMs: 250, label: "disabled real engine best-practices catalog",
+ until: (names) => BUNDLED_SKILLS.every((name) => !names.includes(name)),
+ });
+ for (const name of BUNDLED_SKILLS) expect(names).not.toContain(name);
+ expect(names).toEqual(expect.arrayContaining([USER_SKILL, "omnirush-swarm"]));
+ expect(world.requests).toHaveLength(before);
+ expect(await world.snapshot()).toEqual(originalFiles);
+ expect(replyText(await world.send("Reply with another short acknowledgement. Do not use tools."))).toBe(MOCK_REPLY);
+ expect(world.requests.slice(before)).toHaveLength(1);
+ const request = world.requests.at(-1);
+ expect(request?.body.includes(BEST_PRACTICES_HEADING)).toBe(false);
+ for (const name of BUNDLED_SKILLS) expect(request?.body.includes(name)).toBe(false);
+ expect(request?.body.includes(USER_SKILL)).toBe(true);
+ expect(request?.body.includes("omnirush-swarm")).toBe(true);
+ evidence.recordAssertionEvidence("Off removes only the bundled guidance for subsequent engine requests", "PUT returned applied. All nine bundled names and the Best practices heading disappeared from the next real-engine model request while user and swarm skills remained. The toggle made zero model calls and changed no project files.", true);
+ });
+
+ await step("the saved off choice survives restart, and on restores the guides", async () => {
+ const before = world.requests.length;
+ await world.restart();
+ expect(await world.config("GET")).toEqual({ status: 200, body: { enabled: false } });
+ const restartedNames = await probe.eventually(async () => skillNames(await world.engine("GET", "/skill")), {
+ within: 30_000, intervalMs: 250, label: "preserved user and swarm catalog after cold restart",
+ until: (names) => names.includes(USER_SKILL) && names.includes("omnirush-swarm"),
+ });
+ for (const name of BUNDLED_SKILLS) expect(restartedNames).not.toContain(name);
+ expect(restartedNames).toEqual(expect.arrayContaining([USER_SKILL, "omnirush-swarm"]));
+ expect(world.requests).toHaveLength(before);
+ expect(await world.config("PUT", { enabled: true })).toEqual({ status: 200, body: {
+ ok: true, enabled: true, changed: true, engine: { status: "applied" },
+ } });
+ await probe.eventually(async () => skillNames(await world.engine("GET", "/skill")), {
+ within: 30_000, intervalMs: 250, label: "restored real engine best-practices catalog",
+ until: (names) => BUNDLED_SKILLS.every((name) => names.includes(name)),
+ });
+ expect(world.requests).toHaveLength(before);
+ expect(replyText(await world.send("Reply with a final short acknowledgement. Do not use tools."))).toBe(MOCK_REPLY);
+ expect(world.requests.slice(before)).toHaveLength(1);
+ expect(world.requests.at(-1)?.body.includes(BEST_PRACTICES_HEADING)).toBe(true);
+ for (const name of BUNDLED_SKILLS) expect(world.requests.at(-1)?.body.includes(name)).toBe(true);
+ expect(await world.snapshot()).toEqual(originalFiles);
+ expect(world.requests.some((request) => request.body.includes(PRIVATE_CANARY))).toBe(false);
+ evidence.recordAssertionEvidence("The saved choice survives restart and on restores guidance without leaking fixture inputs", "After a cold process restart, GET still reported off and the real engine kept only user and swarm skills. On restored all nine names and the short prompt. Toggling and restarting made no model calls; all original project bytes, including the private canary, stayed unchanged and the canary never reached the mock provider.", true);
+ });
+ } finally {
+ evidence.recordJsonArtifact("server diagnostics and model request witnesses", {
+ output: world.output().replaceAll(world.token, "<fixture-client>").replaceAll(world.workspace, "<fixture-workspace>"),
+ requests: world.requests.map((request) => ({
+ path: request.path, completed: request.completed, closedBeforeReply: request.closedBeforeReply,
+ guidancePresent: request.body.includes(BEST_PRACTICES_HEADING),
+ bundledSkills: BUNDLED_SKILLS.filter((name) => request.body.includes(name)),
+ userSkillPresent: request.body.includes(USER_SKILL), swarmPresent: request.body.includes("omnirush-swarm"),
+ privateCanaryPresent: request.body.includes(PRIVATE_CANARY),
+ })),
+ });
+ }
+});
+
+test("changing Best practices keeps an active real engine reply intact", { timeout: 300_000 }, async ({ world, probe, step, evidence }) => {
+ try {
+ await step("an in-flight model reply completes while the next request uses the saved choice", async () => {
+ const originalFiles = await world.snapshot();
+ const waiting = world.holdNextReply();
+ const running = world.send("Keep this acknowledgement pending until the witness releases it. Do not use tools.");
+ void running.catch(() => undefined);
+ const held = await probe.eventually(() => Promise.race([
+ waiting,
+ new Promise<undefined>((resolve) => setTimeout(() => resolve(undefined), 250)),
+ ]), { within: 30_000, intervalMs: 100, label: "in-flight real model request", until: (value) => value !== undefined });
+ if (!held) throw new Error("The model request did not reach the witness.");
+ try {
+ expect(held.request.body.includes(BEST_PRACTICES_HEADING)).toBe(true);
+ const before = world.requests.length;
+ expect(await world.config("PUT", { enabled: false })).toEqual({ status: 200, body: {
+ ok: true, enabled: false, changed: true, engine: { status: "applied" },
+ } });
+ expect(held.request.closedBeforeReply).toBe(false);
+ expect(held.request.completed).toBe(false);
+ expect(world.requests).toHaveLength(before);
+ held.release();
+ expect(replyText(await running)).toBe(MOCK_REPLY);
+ expect(held.request.closedBeforeReply).toBe(false);
+ expect(world.requests).toHaveLength(before);
+ expect(replyText(await world.send("Acknowledge the next request. Do not use tools."))).toBe(MOCK_REPLY);
+ expect(world.requests).toHaveLength(before + 1);
+ expect(world.requests.at(-1)?.body.includes(BEST_PRACTICES_HEADING)).toBe(false);
+ for (const name of BUNDLED_SKILLS) expect(world.requests.at(-1)?.body.includes(name)).toBe(false);
+ expect(world.requests.at(-1)?.body.includes(USER_SKILL)).toBe(true);
+ expect(world.requests.at(-1)?.body.includes("omnirush-swarm")).toBe(true);
+ expect(await world.snapshot()).toEqual(originalFiles);
+ expect(world.requests.some((request) => request.body.includes(PRIVATE_CANARY))).toBe(false);
+ evidence.recordAssertionEvidence("Toggling does not cancel active work or trigger an extra model request", "A real-engine reply was held at the loopback provider. Turning off returned applied while its connection stayed open; it then completed with the expected reply. Only the next user-requested turn omitted the guidance. No project bytes changed and no canary content reached the provider.", true);
+ } finally {
+ held.release();
+ await running.catch(() => undefined);
+ }
+ });
+ } finally {
+ evidence.recordJsonArtifact("active reply diagnostics and model request witnesses", {
+ output: world.output().replaceAll(world.token, "<fixture-client>").replaceAll(world.workspace, "<fixture-workspace>"),
+ requests: world.requests.map((request) => ({
+ path: request.path, completed: request.completed, closedBeforeReply: request.closedBeforeReply,
+ guidancePresent: request.body.includes(BEST_PRACTICES_HEADING), privateCanaryPresent: request.body.includes(PRIVATE_CANARY),
+ bundledSkills: BUNDLED_SKILLS.filter((name) => request.body.includes(name)),
+ userSkillPresent: request.body.includes(USER_SKILL), swarmPresent: request.body.includes("omnirush-swarm"),
+ })),
+ });
+ }
+});
+
+const attachedTest = spec.world(bestPracticesAttached, { needs: { commands: ["bun"], placement: "local" }, timeout: 90_000 });
+
+attachedTest("Best practices saves busy attached-engine changes and reports apply failure honestly", { timeout: 120_000 }, async ({ world, probe, step, evidence }) => {
+ const originalFiles = await world.snapshot();
+ await step("busy work is not disposed, and the saved choice applies once the engine becomes idle", async () => {
+ world.requests.length = 0;
+ expect(await world.config("PUT", { enabled: false })).toEqual({ status: 200, body: {
+ ok: true, enabled: false, changed: true, engine: { status: "deferred" },
+ } });
+ expect(world.requests).not.toContain("POST /instance/dispose");
+ expect(world.requests.some((request) => request.endsWith("/abort"))).toBe(false);
+ expect(await world.config("GET")).toEqual({ status: 200, body: { enabled: false } });
+ world.setBehavior("idle");
+ await probe.eventually(() => world.requests.filter((request) => request === "POST /instance/dispose").length, {
+ within: 10_000, intervalMs: 100, label: "deferred attached engine reload after idle", until: (count) => count === 1,
+ });
+ expect(world.requests.filter((request) => request === "POST /instance/dispose")).toHaveLength(1);
+ expect(world.requests.some((request) => request.endsWith("/abort"))).toBe(false);
+ expect(world.requests.some((request) => request.includes("/message"))).toBe(false);
+ expect(await world.snapshot()).toEqual(originalFiles);
+ evidence.recordAssertionEvidence("A busy attached engine is deferred without aborting work and retries at idle", "The real server returned deferred, persisted off, sent no dispose or abort while busy, then disposed exactly once after the witness became idle. No model-message calls or project edits occurred.", true);
+ });
+
+ await step("a failed engine apply retains the saved choice without claiming success", async () => {
+ world.setBehavior("failed");
+ world.requests.length = 0;
+ expect(await world.config("PUT", { enabled: true })).toEqual({ status: 200, body: {
+ ok: true, enabled: true, changed: true, engine: { status: "failed" },
+ } });
+ expect(await world.config("GET")).toEqual({ status: 200, body: { enabled: true } });
+ expect(world.requests).toContain("POST /instance/dispose");
+ expect(world.requests.some((request) => request.endsWith("/abort"))).toBe(false);
+ expect(world.requests.some((request) => request.includes("/message"))).toBe(false);
+ expect(await world.snapshot()).toEqual(originalFiles);
+ evidence.recordAssertionEvidence("A reload failure is reported separately from the saved choice", "The attached witness rejected reload with HTTP 500. The real server returned engine.status=failed, and subsequent GET still returned enabled=true. It made no abort or model-message request and preserved project bytes.", true);
+ });
+});
diff --git a/evals/worlds/best-practices-desktop.ts b/evals/worlds/best-practices-desktop.ts
new file mode 100644
index 00000000..cffd4528
--- /dev/null
+++ b/evals/worlds/best-practices-desktop.ts
@@ -0,0 +1,53 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { callFunctionOnSurface } from "@omnirush/cdp";
+import { go } from "@omnirush/behaviors";
+import { desktop } from "@omnirush/hosts";
+import type { Seed, Place } from "@omnirush/env";
+
+const CANARY = "PRIVATE_GUI_CANARY_BEST_PRACTICES_812b";
+
+/** Caller-owned local profile; no Den identity, account credential, or production service. */
+export async function bestPracticesDesktop(seed: Seed, { place }: { place: Place }) {
+ const profileDir = seed.tmpPath("best-practices-desktop-profile");
+ const workspacePath = join(profileDir, "workspace");
+ const canaryPath = join(workspacePath, "private-note.txt");
+ await mkdir(workspacePath, { recursive: true });
+ await writeFile(canaryPath, CANARY);
+ const env = {
+ OMNIRUSH_SESSION_UPLOAD_OPTIONAL: "1",
+ OMNIRUSH_ELECTRON_SKIP_SHARED_PREPARE: "1",
+ ...(process.env.OMNIRUSH_OPENCODE_BIN ? { OMNIRUSH_OPENCODE_BIN: process.env.OMNIRUSH_OPENCODE_BIN } : {}),
+ };
+ let active = await seed.desktop({ name: "best-practices", profileDir, env });
+ const workspace = await seed.workspace(active, workspacePath);
+ const route = `/workspace/${workspace.workspaceId}/settings/general`;
+ await go(active, route);
+ return {
+ get app() { return active; },
+ workspace,
+ async state() {
+ return callFunctionOnSurface(active, () => {
+ const control = document.querySelector('[role="switch"][aria-label="Best practices"]');
+ return {
+ exists: control !== null,
+ enabled: control?.getAttribute("aria-checked") === "true",
+ disabled: control === null || control.hasAttribute("disabled")
+ || control.getAttribute("aria-disabled") === "true" || control.hasAttribute("data-disabled"),
+ help: document.getElementById("best-practices-help")?.textContent ?? "",
+ status: document.querySelector('[data-testid="best-practices-status"]')?.textContent ?? "",
+ };
+ }, []);
+ },
+ async restart() {
+ await active.stop();
+ active = await desktop({ name: "best-practices-restart", host: place.host(), profileDir, env, prepareSharedResources: false });
+ await go(active, route);
+ },
+ canaryUnchanged: async () => await readFile(canaryPath, "utf8") === CANARY,
+ async [Symbol.asyncDispose]() {
+ await active.stop();
+ await rm(profileDir, { recursive: true, force: true });
+ },
+ };
+}
diff --git a/evals/worlds/best-practices.ts b/evals/worlds/best-practices.ts
new file mode 100644
index 00000000..a57fa329
--- /dev/null
+++ b/evals/worlds/best-practices.ts
@@ -0,0 +1,236 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, readdir, realpath, rm, writeFile } from "node:fs/promises";
+import { createServer, type ServerResponse } from "node:http";
+import { join, relative } from "node:path";
+import type { Seed } from "@omnirush/env";
+import {
+ bootManagedOmniRushServer,
+ bootServer,
+ close,
+ isRecord,
+ isolatedFixtureEnv,
+ listen,
+ readBody,
+ sendJson,
+ sendStream,
+ stopChild,
+ type ManagedOmniRushServer,
+} from "./omnirush-server-cli.ts";
+
+export const BEST_PRACTICES_HEADING = "OmniRush Best practices";
+export const PRIVATE_CANARY = "PRIVATE_CANARY_BEST_PRACTICES_7f62";
+export const USER_SKILL = "journey-user-guide";
+export const MOCK_REPLY = "BEST_PRACTICES_MOCK_OK";
+export const BUNDLED_SKILLS = [
+ "omnirush-setup", "omnirush-feature", "omnirush-debug", "omnirush-test",
+ "omnirush-refactor", "omnirush-performance", "omnirush-build", "omnirush-review", "omnirush-handoff",
+];
+
+export interface ProviderRequest {
+ path: string;
+ body: string;
+ completed: boolean;
+ closedBeforeReply: boolean;
+}
+
+/** A real server with an attached loopback engine witness for busy/failure states. */
+export async function bestPracticesAttached(seed: Seed) {
+ const root = seed.tmpPath("best-practices-attached");
+ await mkdir(root, { recursive: true });
+ const scratch = await realpath(root);
+ const workspace = join(scratch, "workspace");
+ const home = join(scratch, "home");
+ await mkdir(workspace, { recursive: true });
+ await mkdir(home, { recursive: true });
+ await writeFile(join(workspace, "notes.txt"), PRIVATE_CANARY);
+ const requests: string[] = [];
+ let behavior: "busy" | "idle" | "failed" = "busy";
+ const attached = createServer((request, response) => {
+ const path = new URL(request.url ?? "/", "http://127.0.0.1").pathname;
+ requests.push(`${request.method ?? "GET"} ${path}`);
+ if (path === "/session/status") return sendJson(response, 200,
+ behavior === "busy" ? { fixture_active_reply: { type: "busy" } } : {});
+ if (path === "/instance/dispose") return sendJson(response,
+ behavior === "failed" ? 500 : 200, behavior === "failed" ? { error: "fixture reload failed" } : { ok: true });
+ if (path === "/config") return sendJson(response, 200, {});
+ if (path === "/global/health") return sendJson(response, 200, { healthy: true, version: "fixture-attached" });
+ return sendJson(response, 200, []);
+ });
+ const attachedUrl = await listen(attached);
+ const inherited = isolatedFixtureEnv();
+ const token = "best-practices-attached-fixture-client";
+ const launched = bootServer({
+ ...inherited, HOME: home,
+ XDG_CONFIG_HOME: join(home, ".config"), XDG_DATA_HOME: join(home, ".local", "share"),
+ XDG_CACHE_HOME: join(home, ".cache"), XDG_STATE_HOME: join(home, ".local", "state"),
+ OMNIRUSH_DEV_MODE: "1", OMNIRUSH_SESSION_UPLOAD_OPTIONAL: "1",
+ }, token, workspace, () => undefined, ["--opencode-base-url", attachedUrl]);
+ const dispose = async () => {
+ await stopChild(launched.child);
+ await close(attached);
+ await rm(scratch, { recursive: true, force: true });
+ };
+ try {
+ const base = await launched.listening;
+ return {
+ requests,
+ setBehavior: (value: typeof behavior) => { behavior = value; },
+ snapshot: () => projectSnapshot(workspace),
+ async config(method: "GET" | "PUT", body?: unknown) {
+ const response = await fetch(`${base}/runtime-config/best-practices`, {
+ method, headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+ body: body === undefined ? undefined : JSON.stringify(body), signal: AbortSignal.timeout(30_000),
+ });
+ const parsed: unknown = await response.json();
+ return { status: response.status, body: parsed };
+ },
+ [Symbol.asyncDispose]: dispose,
+ };
+ } catch (error) { await dispose(); throw error; }
+}
+
+export interface HeldReply {
+ request: ProviderRequest;
+ release(): void;
+}
+
+async function projectSnapshot(root: string): Promise<Record<string, string>> {
+ const files: Record<string, string> = {};
+ const visit = async (directory: string): Promise<void> => {
+ for (const item of await readdir(directory, { withFileTypes: true })) {
+ const path = join(directory, item.name);
+ if (item.isDirectory()) await visit(path);
+ else if (item.isFile()) files[relative(root, path)] = createHash("sha256").update(await readFile(path)).digest("hex");
+ }
+ };
+ await visit(root);
+ return files;
+}
+
+function reply(response: ServerResponse, index: number): void {
+ const id = `chatcmpl-best-practices-${index}`;
+ sendStream(response, [
+ { id, object: "chat.completion.chunk", choices: [{ index: 0, delta: { role: "assistant", content: MOCK_REPLY }, finish_reason: null }] },
+ { id, object: "chat.completion.chunk", choices: [{ index: 0, delta: {}, finish_reason: "stop" }], usage: { prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 } },
+ ]);
+}
+
+/** Real local server and native engine; the only model provider is a loopback witness. */
+export async function bestPractices(seed: Seed) {
+ const root = seed.tmpPath("best-practices");
+ await mkdir(root, { recursive: true });
+ const scratch = await realpath(root);
+ const workspace = join(scratch, "workspace");
+ const userSkill = join(workspace, ".opencode", "skills", USER_SKILL);
+ await mkdir(userSkill, { recursive: true });
+ await mkdir(join(workspace, ".private"), { recursive: true });
+ await writeFile(join(workspace, ".private", "meeting.txt"), PRIVATE_CANARY);
+ await writeFile(join(workspace, "notes.txt"), "Keep this user's project file unchanged.\n");
+ await writeFile(join(userSkill, "SKILL.md"), `---\nname: ${USER_SKILL}\ndescription: User-owned guide for the isolated journey.\n---\n\nFollow the user's request.\n`);
+
+ const requests: ProviderRequest[] = [];
+ let holdNext: ((reply: HeldReply) => void) | undefined;
+ const held = new Set<() => void>();
+ const provider = createServer((request, response) => {
+ void (async () => {
+ const path = new URL(request.url ?? "/", "http://127.0.0.1").pathname;
+ if (request.method !== "POST" || !path.endsWith("/chat/completions")) return sendJson(response, 200, { data: [] });
+ const body = await readBody(request);
+ const recorded: ProviderRequest = { path, body, completed: false, closedBeforeReply: false };
+ requests.push(recorded);
+ response.on("close", () => { if (!recorded.completed) recorded.closedBeforeReply = true; });
+ const complete = () => {
+ if (recorded.completed) return;
+ recorded.completed = true;
+ held.delete(complete);
+ reply(response, requests.indexOf(recorded) + 1);
+ };
+ if (holdNext && !body.includes("Generate a title for this conversation")) {
+ const started = holdNext;
+ holdNext = undefined;
+ held.add(complete);
+ started({ request: recorded, release: complete });
+ } else complete();
+ })().catch((error: unknown) => {
+ if (!response.headersSent) sendJson(response, 500, { error: String(error) });
+ else response.destroy(error instanceof Error ? error : undefined);
+ });
+ });
+ const providerUrl = await listen(provider);
+ await writeFile(join(workspace, "opencode.json"), JSON.stringify({
+ provider: {
+ "best-practices-mock": {
+ npm: "@ai-sdk/openai-compatible",
+ name: "Best practices loopback witness",
+ options: { baseURL: `${providerUrl}/v1`, apiKey: "fixture-only" },
+ models: { mock: {
+ name: "mock", tool_call: true, reasoning: false, temperature: true,
+ modalities: { input: ["text"], output: ["text"] },
+ limit: { context: 128_000, output: 4_096 }, cost: { input: 0, output: 0 },
+ } },
+ },
+ },
+ }, null, 2));
+
+ const token = "best-practices-fixture-client";
+ let managed: ManagedOmniRushServer | undefined;
+ let output = "";
+ const boot = async () => {
+ managed = await bootManagedOmniRushServer({
+ scratch, workspace, token, sink: (chunk) => { output += chunk; }, isolatedEnv: true,
+ env: { OMNIRUSH_DEV_MODE: "1", OMNIRUSH_SESSION_UPLOAD_OPTIONAL: "1" },
+ });
+ };
+ const server = () => {
+ if (!managed) throw new Error("Best practices fixture has no running server.");
+ return managed;
+ };
+ const dispose = async () => {
+ for (const release of held) release();
+ await managed?.stop();
+ await close(provider);
+ await rm(scratch, { recursive: true, force: true });
+ };
+ try {
+ await boot();
+ return {
+ requests, workspace, token,
+ get base() { return server().base; },
+ get workspaceId() { return server().workspaceId; },
+ output: () => output,
+ async config(method: "GET" | "PUT", body?: unknown, authenticated = true) {
+ const response = await fetch(`${server().base}/runtime-config/best-practices`, {
+ method,
+ headers: { ...(authenticated ? { authorization: `Bearer ${token}` } : {}), "content-type": "application/json" },
+ body: body === undefined ? undefined : JSON.stringify(body),
+ signal: AbortSignal.timeout(30_000),
+ });
+ const parsed: unknown = await response.json();
+ return { status: response.status, body: parsed };
+ },
+ engine: (method: string, path: string, body?: unknown) => server().engine(method, path, body),
+ async send(text: string) {
+ const session = await server().engine("POST", "/session", { title: "Best practices witness" });
+ if (!isRecord(session) || typeof session.id !== "string") throw new Error("Engine did not create a session.");
+ return server().engine("POST", `/session/${encodeURIComponent(session.id)}/message`, {
+ agent: "omnirush", model: { providerID: "best-practices-mock", modelID: "mock" },
+ parts: [{ type: "text", text }],
+ });
+ },
+ async restart() {
+ await server().stop();
+ managed = undefined;
+ await boot();
+ },
+ holdNextReply() {
+ if (holdNext) throw new Error("A held reply is already armed.");
+ return new Promise<HeldReply>((resolve) => { holdNext = resolve; });
+ },
+ snapshot: () => projectSnapshot(workspace),
+ [Symbol.asyncDispose]: dispose,
+ };
+ } catch (error) {
+ await dispose();
+ throw error;
+ }
+}
diff --git a/evals/worlds/omnirush-server-cli.ts b/evals/worlds/omnirush-server-cli.ts
index 3ddc28aa..f033719e 100644
--- a/evals/worlds/omnirush-server-cli.ts
+++ b/evals/worlds/omnirush-server-cli.ts
@@ -74,7 +74,7 @@ export function stopChild(child: ChildProcess): Promise<void> {
* chunk goes to `sink`; `listening` resolves with the base URL once the server
* reports its port, or rejects when the process exits first.
*/
-export function bootServer(env: NodeJS.ProcessEnv, token: string, workspace: string, sink: (chunk: string) => void): { child: ChildProcess; listening: Promise<string> } {
+export function bootServer(env: NodeJS.ProcessEnv, token: string, workspace: string, sink: (chunk: string) => void, extraArguments: string[] = []): { child: ChildProcess; listening: Promise<string> } {
const child = spawn("bun", [
"--conditions=development",
"src/cli.ts",
@@ -85,6 +85,7 @@ export function bootServer(env: NodeJS.ProcessEnv, token: string, workspace: str
"--approval", "auto",
"--cors", "*",
"--workspace", workspace,
+ ...extraArguments,
], { cwd: serverRoot, env, stdio: ["ignore", "pipe", "pipe"] });
let seen = "";
const listening = new Promise<string>((resolveBase, reject) => {
@@ -125,12 +126,22 @@ function firstWorkspaceId(value: unknown): string | null {
return isRecord(first) && typeof first.id === "string" ? first.id : null;
}
+/** Process lookup and locale only; fixture children must not inherit credentials. */
+export function isolatedFixtureEnv(): NodeJS.ProcessEnv {
+ const allowed = new Set(["PATH", "TMPDIR", "TEMP", "TMP", "LANG", "LC_ALL", "SystemRoot", "WINDIR"]);
+ return Object.fromEntries(Object.entries(process.env).filter(([key]) => allowed.has(key)));
+}
+
export async function bootManagedOmniRushServer(options: {
scratch: string;
workspace: string;
token: string;
sink: (chunk: string) => void;
binary?: string;
+ /** Limit inheritance to process lookup and locale for local-only witnesses. */
+ isolatedEnv?: boolean;
+ /** Explicit fixture-only overrides. */
+ env?: Record<string, string>;
}): Promise<ManagedOmniRushServer> {
const binary = options.binary ?? engineBinary();
if (!binary) throw new SkipError("set OMNIRUSH_OPENCODE_BIN or install opencode");
@@ -140,7 +151,8 @@ export async function bootManagedOmniRushServer(options: {
// The spec may itself run under an OmniRush.ai or OpenCode session. The parent's
// OPENCODE_* and OMNIRUSH_* variables (config path, models URL, credentials,
// workspaces) must not reach the isolated server and engine under test.
- const inherited = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith("OPENCODE") && !key.startsWith("OMNIRUSH_")));
+ const inherited = options.isolatedEnv ? isolatedFixtureEnv()
+ : Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith("OPENCODE") && !key.startsWith("OMNIRUSH_")));
const env = {
...inherited,
HOME: home,
@@ -150,6 +162,7 @@ export async function bootManagedOmniRushServer(options: {
XDG_STATE_HOME: join(home, ".local", "state"),
OMNIRUSH_MANAGE_OPENCODE: "1",
OMNIRUSH_OPENCODE_BIN: binary,
+ ...options.env,
};
let output = "";