A desktop coding agent with free access to frontier models.
TypeScript
/** Offer an account-level quota wrap in the desktop GUI.
*
* The backend decides when a grant needs wrapping and publishes a private
* response header on the model response. The engine sends model requests
* through the global fetch, which this plugin wraps to read that header on
* requests it marked (`chat.headers`). Once the engine reports the session
* idle it asks the desktop window for an explicit, persistent choice. Only an
* accepted offer asks the engine to compact on the model it last ran on.
* The compaction record itself contains the generated handoff summary; no
* warning or synthetic prompt is written to the session trace.
*
* The question rules are shared with the CLI (`budget-wrap-rules.ts`): asked
* only while the session is idle, once per offer, and a failed wrap turns
* into a notice with a retry action instead of the question again.
*/
import { replacesWrapOffer, startWrapNow, wrapFinished } from "./budget-wrap-rules.js";
const REQUIRED_HEADER = "x-omnirush-wrap-required";
const WRAP_UP_HEADER = "x-omnirush-wrap-up";
const OFFER_HEADER = "x-omnirush-wrap-offer-id";
const SESSION_HEADER = "x-omnirush-session-id";
type ModelRef = { providerID: string; modelID: string };
type Offer = { id: string; scopes: string; watching: boolean; inFlight: boolean; approved: boolean; backendWrapped: boolean; compacted: boolean; failedAt?: number };
/** How long a failed wrap's Retry stays available (the window's notice). */
const RETRY_WINDOW_MS = 30_000;
/** How long an idle session waits before the question shows. */
const idleSettleMs = () => Number(process.env.OMNIRUSH_WRAP_IDLE_SETTLE_MS ?? 600);
const pending = new Map<string, Offer>();
/** Sessions with a turn running (`session.status` busy until idle). */
const busy = new Set<string>();
/** The model each session last sent a request on (the compaction runs on it). */
const models = new Map<string, ModelRef>();
const MAX_TRACKED_SESSIONS = 256;
type BudgetFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
type BudgetClient = {
tui?: { showToast?: (input: { query?: { directory?: string }; body: { title: string; message: string; variant: string; duration: number } }) => Promise<unknown> };
};
type RecordValue = Record<string, unknown>;
function record(value: unknown): value is RecordValue {
return typeof value === "object" && value !== null && !Array.isArray(value);
}
function sessionIDFromEvent(event: unknown): string {
if (!record(event) || !record(event.properties)) return "";
const properties = event.properties;
return typeof properties.sessionID === "string" ? properties.sessionID : "";
}
function remember<T>(map: Map<string, T>, key: string, value: T): void {
map.delete(key);
map.set(key, value);
while (map.size > MAX_TRACKED_SESSIONS) map.delete(map.keys().next().value as string);
}
let installed = false;
const listeners = new Set<(sessionID: string, headers: Headers) => void>();
/** Wraps the global fetch once: a marked model request's response headers are read, nothing else changes. */
function install(): void {
if (installed) return;
installed = true;
const base = globalThis.fetch;
const patched = async (input: Parameters<typeof fetch>[0], init?: RequestInit): Promise<Response> => {
const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
const sessionID = headers.get(SESSION_HEADER)?.trim() ?? "";
const response = await base(input, init);
if (sessionID) for (const listener of listeners) listener(sessionID, response.headers);
return response;
};
globalThis.fetch = Object.assign(patched, base);
}
function basicAuthorization(): string {
const password = process.env.OPENCODE_SERVER_PASSWORD?.trim() ?? "";
if (!password) return "";
const username = process.env.OPENCODE_SERVER_USERNAME?.trim() || "opencode";
return `Basic ${Buffer.from(`${username}:${password}`).toString("base64")}`;
}
export const OmniRushBudgetWrap = async (input: {
directory?: string;
/** The engine's own server (the plugin input's `serverUrl`). */
serverUrl?: URL | string;
fetch?: BudgetFetch;
client?: BudgetClient;
}) => {
install();
const baseUrl = String(input.serverUrl ?? "").replace(/\/+$/, "");
const authorization = basicAuthorization();
const fetcher = input.fetch ?? globalThis.fetch;
let disposed = false;
const server = (process.env.OMNIRUSH_SERVER_URL ?? "").trim().replace(/\/+$/, "");
const token = (process.env.OMNIRUSH_SERVER_TOKEN ?? process.env.OMNIRUSH_POLICY_TOKEN ?? "").trim();
async function control(id: string, args: Record<string, string>): Promise<string> {
if (!server || !token) return "unavailable";
try {
const response = await fetcher(server + "/experimental/ui-control/request", {
method: "POST",
headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
body: JSON.stringify({ kind: "query", input: { id, args } }),
});
if (!response.ok) return "unavailable";
const result: unknown = await response.json();
if (!record(result) || result.ok !== true || !record(result.result)) return "unavailable";
const choice = result.result.choice;
return typeof choice === "string" ? choice : "ok";
} catch {
return "unavailable";
}
}
const update = (sessionID: string, entry: Offer, operation: string) =>
control("budget.wrap.update", { sessionID, offerID: entry.id, scopes: entry.scopes, operation });
const noteBudgetResponse = (sessionID: string, headers: Headers) => {
const current = pending.get(sessionID);
if (headers.get(WRAP_UP_HEADER) === "1") {
if (current?.approved) current.backendWrapped = true;
return;
}
if (headers.get(REQUIRED_HEADER) !== "1") {
if (current && !current.inFlight) {
pending.delete(sessionID);
void update(sessionID, current, "clear");
}
return;
}
const id = headers.get(OFFER_HEADER) || `legacy:${headers.get("x-omnirush-wrap-scopes") ?? ""}`;
if (!replacesWrapOffer(current ? { offerID: current.id } : undefined, id)) return;
if (current?.inFlight) return;
if (current) void update(sessionID, current, "clear");
remember(pending, sessionID, {
id, scopes: headers.get("x-omnirush-wrap-scopes") || "token", watching: false,
inFlight: false, approved: false, backendWrapped: false, compacted: false,
});
};
listeners.add(noteBudgetResponse);
async function notify(title: string, message: string, variant: "info" | "warning"): Promise<void> {
const body = { title, message, variant, duration: 12_000 };
try {
await input.client?.tui?.showToast?.({
...(input.directory ? { query: { directory: input.directory } } : {}),
body,
});
} catch {
// The headless adapter may not implement the native TUI endpoint.
}
// The desktop shell shows its own local toast when the person accepts and
// when the offer settles. It needs no Control Mode command here.
}
async function compact(sessionID: string): Promise<void> {
const entry = pending.get(sessionID);
const model = models.get(sessionID);
if (!entry || entry.inFlight || !baseUrl || !model) return;
entry.inFlight = true;
entry.approved = true;
await notify("Wrapping up", "Saving this session's handoff now.", "info");
try {
const response = await fetcher(
baseUrl + "/session/" + encodeURIComponent(sessionID) + "/summarize",
{
method: "POST",
headers: {
"content-type": "application/json",
...(authorization ? { authorization } : {}),
...(input.directory ? { "x-opencode-directory": encodeURIComponent(input.directory) } : {}),
},
body: JSON.stringify({ providerID: model.providerID, modelID: model.modelID }),
},
);
// The engine's `session.compacted` event may land just after summarize answers.
for (let waited = 0; response.ok && !entry.compacted && waited < 5_000; waited += 100) {
await new Promise<void>((resolve) => setTimeout(resolve, 100));
}
if (!wrapFinished({ ok: response.ok, compacted: entry.compacted })) {
throw new Error("the wrap did not finish (" + response.status + ")");
}
await notify(
"Wrap up complete",
"Your handoff is saved. You can keep working while tokens remain.",
"info",
);
await update(sessionID, entry, "finish");
pending.delete(sessionID);
} catch {
// A failed wrap is final for this offer: the window shows a notice
// with a retry action, never the question again, and nothing retries
// on the next idle unless the person asks.
entry.approved = false;
entry.inFlight = false;
entry.compacted = false;
entry.backendWrapped = false;
entry.failedAt = Date.now();
await update(sessionID, entry, "fail");
await notify("Wrap up did not finish", "Your session is unchanged. You can retry, or keep working.", "warning");
}
}
async function watch(sessionID: string): Promise<void> {
const entry = pending.get(sessionID);
if (!entry || entry.watching || entry.inFlight) return;
entry.watching = true;
// A prompt queued behind the turn starts right after its idle: give its
// busy event a moment, so the question never flashes over it.
await new Promise<void>((resolve) => setTimeout(resolve, idleSettleMs()));
// Only while the session is idle: a new turn hides the question and
// ends this loop; the next idle starts it again.
while (!disposed && pending.get(sessionID) === entry && !entry.inFlight && !busy.has(sessionID)) {
const offered = await update(sessionID, entry, "offer");
if (offered === "decline" || offered === "done") { pending.delete(sessionID); break; }
// A failed wrap is retried only from its notice, while it is shown.
if (offered === "failed" && Date.now() - (entry.failedAt ?? 0) > RETRY_WINDOW_MS) { pending.delete(sessionID); break; }
if (busy.has(sessionID)) break;
if (startWrapNow({ choice: offered, busy: busy.has(sessionID), inFlight: entry.inFlight })) { await compact(sessionID); continue; }
// "pending" (unanswered) or "failed" (a retry may come from the notice).
await new Promise<void>((resolve) => setTimeout(resolve, 3_000));
}
entry.watching = false;
if (busy.has(sessionID) && pending.get(sessionID) === entry && !entry.inFlight) void update(sessionID, entry, "hold");
}
return {
"chat.headers": async (input: { sessionID?: string; agent?: string; model?: { providerID?: string; id?: string; modelID?: string } }, output: { headers: Record<string, string> }) => {
const sessionID = input?.sessionID?.trim() ?? "";
if (!sessionID || input.model?.providerID !== "omnirush") return;
output.headers[SESSION_HEADER] = sessionID;
if (input.agent === "compaction" && pending.get(sessionID)?.approved) output.headers["x-omnirush-context-wrap"] = "1";
const modelID = input.model.id ?? input.model.modelID;
if (modelID) remember(models, sessionID, { providerID: input.model.providerID, modelID });
},
event: async ({ event }: { event: unknown }) => {
if (!record(event)) return;
const sessionID = sessionIDFromEvent(event);
if (!sessionID) return;
if (event.type === "session.compacted") {
const entry = pending.get(sessionID);
if (entry?.inFlight) entry.compacted = true;
}
if (event.type === "session.status" && record(event.properties) && record(event.properties.status)) {
const type = event.properties.status.type;
if (type === "busy" || type === "retry") {
// Always busy, the compaction too: a prompt sent while it runs
// follows it with no new busy event, so a Retry must still wait.
// The compaction's own idle clears it.
busy.add(sessionID);
const entry = pending.get(sessionID);
if (entry && !entry.inFlight) void update(sessionID, entry, "hold");
} else if (type === "idle") busy.delete(sessionID);
}
if (event.type === "session.idle") {
busy.delete(sessionID);
void watch(sessionID);
}
},
dispose: async () => {
disposed = true;
listeners.delete(noteBudgetResponse);
pending.clear();
models.clear();
busy.clear();
},
};
};