@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
1,324 lines • 62.7 kB
text/typescript
/**
* Management routes for the client-integration toggle.
*
* This module is an HTTP adapter and nothing more: every policy decision —
* what counts as ownership, when a mutation is refused, what gets journaled —
* belongs to src/integrations/writer.ts. Duplicating any of it here is how the
* API and the writer would start disagreeing about what happened to a file.
*
* Design of record: devlog/_fin/260802_client_toggle_api/040_wp4_management_api.md.
*/
import { readFileSync } from "node:fs";
import { LinkApplyBusyError, withLinkApply } from "../../client/link-home";
import { saveConfigPreservingClaudeCode } from "../../config";
import { listAsideProfileStates, type AsideProfilesInput } from "../../integrations/aside-profiles";
import {
handleAsideProfileRoutes, asideJournalResponse, asideRestoreResponse,
asideJournalDeleteResponse, type AsideProfileRouteOptions,
} from "./aside-profile-routes";
import { hermesProfileListResponse, hermesRequestScope, scopeHermesProfileRequest } from "./hermes-profile-routes";
import { HermesProfileError } from "../../integrations/hermes-profiles";
import type { IntegrationIO } from "../../integrations/config-io";
import { createClineIO } from "../../integrations/cline-io";
import { matchesOperationResult } from "../../integrations/journal";
import {
INTEGRATION_CLIENT_IDS,
isIntegrationClientId,
type IntegrationClientId,
} from "../../integrations/registry";
import { detectRaycast, type RaycastInstall } from "../../integrations/raycast-detect";
import { readIntegrationState, readOwnedDroidReasoningDefaults } from "../../integrations/state";
import { droidReasoningModels, validateDroidReasoningDefaults } from "../../clients/config-export";
import { isExportModelNames, supportsAliasModelNames, type ExportModelNames } from "../../clients/config-export/model-names";
import { createIntegrationStateStore, type IntegrationStateStore } from "../../integrations/store";
import {
applyIntegrationCoordinated,
disableIntegrationCoordinated,
overwriteIntegrationCoordinated,
restoreIntegrationCoordinated,
type CoordinatedIntegrationOptions,
type IntegrationRestoreInput,
type IntegrationWriteInput,
type WriteRefused,
} from "../../integrations/writer";
import { IntegrationWriterLockBusyError, type IntegrationWriterLockSeams } from "../../integrations/writer-lock";
import {
INTEGRATION_MUTATION_TERMINAL_MS,
IntegrationMutationBusyError,
runIntegrationMutationFlight,
setIntegrationMutationFlightTestHook,
} from "../../integrations/mutation-flight";
import { jsonResponse } from "../auth-cors";
import { isRouteClientId, type RouteClientIntent } from "../../link/route-intent";
import { prepareHomeIntegrationDecision, recordHomeIntegrationDecision } from "./home-integration-decision";
import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
import { managementInferencePort, type ManagementContext } from "./context";
import { exportSnapshotIdentity, loadExportModels, previewExportSnapshot } from "./model-rows";
import {
previewIntegration,
type IntegrationMutationPlan,
type IntegrationPlanOperation,
type PreviewRequest,
} from "../../integrations/mutation-plan";
const INTEGRATION_ROUTE_PREFIX = "/api/client-integrations/";
const INTEGRATION_COLLECTION_PATH = "/api/client-integrations";
const INTEGRATION_HISTORY_PATHS = ["/api/client-integrations/journal", "/api/client-integrations/restore"];
export { INTEGRATION_MUTATION_TERMINAL_MS };
type IntegrationStateRecord = Awaited<ReturnType<typeof readIntegrationState>>;
type ApplyResult = Awaited<ReturnType<typeof applyIntegrationCoordinated>>;
type DisableResult = Awaited<ReturnType<typeof disableIntegrationCoordinated>>;
type RestoreResult = Awaited<ReturnType<typeof restoreIntegrationCoordinated>>;
export type IntegrationStateEnvelope = {
clientId: IntegrationClientId;
/**
* Raycast only, and only on the single-client read. Custom Providers is a
* Pro feature, so a file that is `current` can still be one Raycast ignores;
* this is the fact that lets status and the GUI say so. It is not part of
* the shared `IntegrationStatus`, which describes the file, not the app.
*/
raycast?: RaycastInstall;
droidReasoning?: {
models: Array<{ model: string; label: string; efforts: string[] }>;
defaults: Record<string, string>;
};
/** The Hermes profile a profile-scoped read describes (#7674). */
hermesProfile?: string;
} & IntegrationStateRecord;
export interface IntegrationStateListEnvelope {
clients: IntegrationStateEnvelope[];
}
export type IntegrationToggleEnvelope =
| ({ clientId: IntegrationClientId } & ApplyResult)
| ({ clientId: IntegrationClientId } & DisableResult);
export type IntegrationRestoreEnvelope = {
clientId: IntegrationClientId;
} & RestoreResult;
export interface IntegrationJournalEnvelope {
operations: IntegrationJournalRow[];
}
export interface IntegrationJournalRow {
opId: string;
clientId: IntegrationClientId;
kind: "apply" | "disable" | "refresh" | "restore" | "overwrite";
at: string;
configPath: string;
snapshot: "none" | "stored" | "expired";
undoable: boolean;
/**
* May the operator retire this row?
*
* Computed HERE, not in the GUI, because the DELETE route enforces the same
* rule and two copies of it would drift. False for a client newest row: it
* is the undo entry point (`undoable` above keys off exactly this), and it
* is what a user reaches for right after the mistake.
*/
deletable: boolean;
profileId?: number;
}
export interface IntegrationToggleBody {
enabled: boolean;
modelNames?: ExportModelNames;
/**
* Opt in to replacing a conflicted block with the one opencodex would write.
*
* Absent and `false` behave identically and are the only states a caller
* reaches by accident, which is the point: the conflict refusal protects work
* we did not author, so it can only be waived by asking for it by name.
*/
overwriteConflict?: boolean;
}
export interface IntegrationRestoreBody {
opId: string;
confirmDrift?: boolean;
}
let integrationMutationTestHooks: {
io?: IntegrationIO;
lockSeams?: IntegrationWriterLockSeams;
/**
* Bind every read and write in the request to one store. Without this a
* route test could isolate the writer but not the journal listing or the
* restore preflight (A-gate round 12).
*/
store?: IntegrationStateStore;
run?: (operation: () => Promise<unknown>) => Promise<unknown>;
afterWriterStart?: () => void;
afterBoundSnapshot?: () => Promise<void>;
} | null = null;
/**
* Home and environment overrides for tests.
*
* Bun's `os.homedir()` snapshots the real home at startup and ignores a later
* `process.env.HOME` assignment, so a test that only rewrites `HOME` still
* resolves the DEVELOPER'S client configs — which is exactly how a route test
* wrote a real `~/.hermes/config.yaml` during this work package. The writer
* and the state reader both already take `env`/`home` explicitly; the route
* simply had no way to pass them. It does now, and production leaves it unset.
*/
let integrationPathTestHooks: { env?: NodeJS.ProcessEnv; home?: string } | null = null;
export function setIntegrationPathTestHooks(hooks: { env?: NodeJS.ProcessEnv; home?: string } | null): void {
integrationPathTestHooks = hooks;
}
/**
* Raycast detection override for tests. The real detector spawns `defaults` and
* reads the developer's own subscription state, which is exactly the kind of
* host fact a route test must not depend on.
*/
let raycastDetectTestHook: (() => RaycastInstall) | null = null;
export function setRaycastDetectTestHook(hook: (() => RaycastInstall) | null): void {
raycastDetectTestHook = hook;
}
/** The `env`/`home` overrides, spread into every registry-resolving call. */
function pathOverrides(): { env?: NodeJS.ProcessEnv; home?: string } {
return {
...(integrationPathTestHooks?.env ? { env: integrationPathTestHooks.env } : {}),
...(integrationPathTestHooks?.home ? { home: integrationPathTestHooks.home } : {}),
};
}
/** A selected Hermes profile's environment and explicit target; nothing for any other request. */
function scopedPathOverrides(ctx: ManagementContext, clientId: IntegrationClientId): Pick<IntegrationWriteInput, "env" | "home" | "resolvedPaths"> {
const scope = clientId === "hermes" ? hermesRequestScope(ctx.req) : undefined;
return scope?.resolvedPaths ? { ...pathOverrides(), env: scope.env, resolvedPaths: { ...scope.resolvedPaths } } : pathOverrides();
}
/** Flight keys carry the profile, so a second profile is busy instead of joining the first one's write. */
function scopedFlightKey(ctx: ManagementContext, key: string): string {
const scope = hermesRequestScope(ctx.req);
return scope?.resolvedPaths ? `hermes-profile:${scope.profile.name}:${key}` : key;
}
/** A Hermes-scoped request may only ever see Hermes operations. */
function outsideHermesScope(ctx: ManagementContext, clientId: IntegrationClientId): boolean {
return hermesRequestScope(ctx.req) !== undefined && clientId !== "hermes";
}
/** The selected profile's boundary, as a writer refusal; null when it holds or nothing is pinned. */
function hermesBoundaryRefusal(ctx: ManagementContext): WriteRefused | null {
const scope = hermesRequestScope(ctx.req);
try {
scope?.assertBoundary();
return null;
} catch (error) {
return {
ok: false, reason: "unsafe", state: "unsafe", clientId: "hermes",
message: error instanceof Error ? error.message : "Hermes profile cannot be changed safely",
};
}
}
function isPlainRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null && !Array.isArray(value);
}
function decodeClientPath(pathname: string): string | null {
if (!pathname.startsWith(INTEGRATION_ROUTE_PREFIX)) return null;
const encoded = pathname.slice(INTEGRATION_ROUTE_PREFIX.length);
if (!encoded || encoded.includes("/")) return null;
try {
return decodeURIComponent(encoded);
} catch {
return encoded;
}
}
export function setIntegrationMutationFlightTestHooks(
hooks: {
io?: IntegrationIO;
lockSeams?: IntegrationWriterLockSeams;
/** Binds the WHOLE request — reads, writes and journal — to one store. */
store?: IntegrationStateStore;
run?: (operation: () => Promise<unknown>) => Promise<unknown>;
afterWriterStart?: () => void;
afterBoundSnapshot?: () => Promise<void>;
} | null,
): void {
integrationMutationTestHooks = hooks;
setIntegrationMutationFlightTestHook(hooks?.run ?? null);
// Path overrides are part of the same isolation contract: clearing flights
// while leaving a temp home bound would let the next suite write real files.
if (hooks === null) {
integrationPathTestHooks = null;
raycastDetectTestHook = null;
}
}
/**
* ONE store per request, used by every read and every write in that request.
* The route previously called module-level `listOperations`/`readSnapshot`
* while handing the writer a separate default store, so a test could not bind
* the whole operation to a temp root (A-gate round 12).
*/
function integrationStore(ctx?: ManagementContext): IntegrationStateStore {
// A selected Hermes profile owns its own store; every other request keeps the root.
return (ctx ? hermesRequestScope(ctx.req)?.store : undefined)
?? integrationMutationTestHooks?.store ?? createIntegrationStateStore();
}
function asideOptions(ctx: ManagementContext): AsideProfileRouteOptions {
let input: AsideProfilesInput | undefined;
return {
input: () => input ??= {
config: ctx.config,
port: managementInferencePort(ctx),
models: () => loadExportModels(ctx.config),
store: integrationStore(),
...pathOverrides(),
io: integrationMutationTestHooks?.io,
lockSeams: integrationMutationTestHooks?.lockSeams,
persistConfig: ctx.deps.saveConfigPreservingClaudeCode ?? saveConfigPreservingClaudeCode,
},
failure: result => writerFailureResponse("aside", result, ctx),
};
}
/**
* Which Aside requests are a Home decision, and the profiles each may enable: a toggle of one
* profile or all of them, or a profile restore. Undefined for reads, previews, journal and sync.
*/
async function asideDecisionScope(ctx: ManagementContext, known: unknown): Promise<readonly number[] | "all" | undefined> {
// The paths handleAsideProfileRoutes owns: the whole set, the profile collection, one profile,
// and one profile's restore.
const match = /^\/api\/client-integrations\/aside(?:\/profiles(?:\/(0|[1-9][0-9]*)(\/restore)?)?)?$/.exec(ctx.url.pathname);
if (!match) return undefined;
const restore = match[2] !== undefined && ctx.req.method === "POST";
const toggle = match[2] === undefined && ctx.req.method === "PUT";
if (!toggle && !restore) return undefined;
const raw = match[1] ?? ctx.url.searchParams.get("profile");
const id = raw !== null && /^(0|[1-9][0-9]*)$/.test(raw) && Number.isSafeInteger(Number(raw)) ? Number(raw) : undefined;
if (restore) return id === undefined ? [] : [id];
const body = known !== undefined ? known : await readJsonBody({ ...ctx, req: ctx.req.clone() });
if (!isPlainRecord(body) || body.enabled !== true) return [];
return id === undefined ? "all" : [id];
}
/** A file client's Home decision as its ownership record stands after a restore. */
function ownedIntent(store: IntegrationStateStore, clientId: IntegrationClientId): RouteClientIntent {
const owner = store.readRecords()[clientId];
return { enabled: Boolean(owner),
...(owner?.modelNames && (clientId === "hermes" || clientId === "commandcode") ? { modelNames: owner.modelNames } : {}) };
}
async function buildIntegrationWriteInput(
clientId: IntegrationClientId,
ctx: ManagementContext,
store: IntegrationStateStore,
droidReasoningDefaults?: Record<string, string>,
modelNames?: ExportModelNames,
): Promise<IntegrationWriteInput> {
return {
clientId,
models: await loadExportModels(ctx.config),
config: ctx.config,
port: managementInferencePort(ctx),
...(droidReasoningDefaults === undefined ? {} : { droidReasoningDefaults: { ...droidReasoningDefaults } }),
...(modelNames === undefined ? {} : { modelNames }),
store,
io: integrationMutationTestHooks?.io,
...scopedPathOverrides(ctx, clientId),
};
}
/**
* The same input a mutation would build, from the read-only roster.
*
* It differs from the mutation's in exactly one way, and the difference is deliberate: the roster
* comes from `previewExportModels`, which gathers without running the initial-selection finalizer
* that persists configuration. Everything else is shared, so a preview and the commit that follows
* it cannot disagree for any reason except the state genuinely moving.
*/
function buildIntegrationPreviewInput(
clientId: IntegrationClientId,
ctx: ManagementContext,
store: IntegrationStateStore,
droidReasoningDefaults?: Record<string, string>,
modelNames?: ExportModelNames,
): { input: IntegrationWriteInput; identity: string } | null {
const snapshot = previewExportSnapshot(ctx.config);
// No cached roster means no honest snapshot to plan against. Gathering one here would make a
// read refresh credentials and write the provider cache, which is the thing preview must not do.
if (snapshot === null) return null;
return {
identity: snapshot.identity,
input: {
clientId,
models: snapshot.models,
config: ctx.config,
port: managementInferencePort(ctx),
...(droidReasoningDefaults === undefined ? {} : { droidReasoningDefaults: { ...droidReasoningDefaults } }),
...(modelNames === undefined ? {} : { modelNames }),
store,
io: integrationMutationTestHooks?.io,
...scopedPathOverrides(ctx, clientId),
},
};
}
/**
* The file's current bytes, or `null` when it is missing.
*
* `null` is NOT the same as `""`: an absent file and an empty one are
* different states, and collapsing them is what made this route disagree with
* the writer about whether an absence-result operation had drifted.
* `undefined` means we could not read it at all, which is neither.
*/
function currentConfigText(configPath: string): string | null | undefined {
try {
return readFileSync(configPath, "utf8");
} catch (error) {
if (isPlainRecord(error) && error.code === "ENOENT") return null;
return undefined;
}
}
function invalidClientResponse(ctx: ManagementContext): Response {
return jsonResponse({
error: "invalid integration client",
code: "invalid_integration_client",
validClients: INTEGRATION_CLIENT_IDS,
}, 400, ctx.req, ctx.config);
}
/** Bind an explicitly scoped restore before profile delegation or mutation. */
function restoreClientScopeResponse(ctx: ManagementContext, opId: string, expectedClientId: unknown, pathClientId?: IntegrationClientId): Response | null {
if (pathClientId !== undefined) {
if (expectedClientId !== undefined && (typeof expectedClientId !== "string" || !isIntegrationClientId(expectedClientId))) return invalidClientResponse(ctx);
if (expectedClientId !== undefined && expectedClientId !== pathClientId) return jsonResponse({ error: "restore identity does not match the client path", code: "integration_client_mismatch" }, 409, ctx.req, ctx.config);
expectedClientId = pathClientId;
}
if (expectedClientId === undefined) return null;
if (typeof expectedClientId !== "string" || !isIntegrationClientId(expectedClientId)) return invalidClientResponse(ctx);
try {
const operation = integrationStore(ctx).findOperation(opId);
if (!operation) return jsonResponse({ error: "integration operation not found", code: "integration_operation_not_found", opId }, 404, ctx.req, ctx.config);
if (operation.clientId !== expectedClientId) return jsonResponse({ error: "integration operation belongs to a different client", code: "integration_client_mismatch" }, 409, ctx.req, ctx.config);
return null;
} catch (error) {
return internalErrorResponse(error, ctx);
}
}
function isStringRecord(value: unknown): value is Record<string, string> {
return value !== null && typeof value === "object" && !Array.isArray(value)
&& Object.values(value).every(item => typeof item === "string");
}
function invalidDroidDefaultsResponse(ctx: ManagementContext, message: string): Response {
return jsonResponse({ error: message, code: "invalid_droid_reasoning_defaults" }, 400, ctx.req, ctx.config);
}
function readModelNames(ctx: ManagementContext, body: Record<string, unknown>, client: string, operation: string): ExportModelNames | Response | undefined {
if (!Object.hasOwn(body, "modelNames")) return undefined;
if (!isExportModelNames(body.modelNames) || !supportsAliasModelNames(client)
|| (operation !== "apply" && operation !== "overwrite")) {
return jsonResponse({ error: "modelNames must be alias or routed and requires Hermes or Command Code apply or overwrite", code: "invalid_model_names" }, 400, ctx.req, ctx.config);
}
return body.modelNames;
}
function readDroidReasoningDefaults(
ctx: ManagementContext,
body: Record<string, unknown>,
clientId: string,
operation: IntegrationPlanOperation,
): Record<string, string> | Response | undefined {
if (!Object.hasOwn(body, "droidReasoningDefaults")) return undefined;
if (clientId !== "droid" || (operation !== "apply" && operation !== "overwrite")) {
return invalidDroidDefaultsResponse(ctx, "droidReasoningDefaults is allowed only for Droid apply or overwrite");
}
const defaults = body.droidReasoningDefaults;
return isStringRecord(defaults)
? defaults
: invalidDroidDefaultsResponse(ctx, "droidReasoningDefaults must map model names to effort strings");
}
/**
* No cached model roster, so there is nothing honest to plan against.
*
* Answered as a bounded refusal rather than by gathering one: discovery refreshes credentials and
* writes the provider cache, and a preview that did either would be a write wearing a read's name.
* The caller opens the models view or performs the mutation directly.
*/
function previewUnavailableResponse(ctx: ManagementContext): Response {
return jsonResponse({
error: "no model roster is cached yet, so this change cannot be planned",
code: "integration_preview_unavailable",
}, 409, ctx.req, ctx.config);
}
/**
* A confirmed plan, or a reason the request cannot carry one.
*
* Both fields or neither. A half-bound request is rejected rather than quietly treated as
* unbound, because dropping one half would answer 200 to a caller who believed their
* confirmation was being checked.
*/
function planBindingOf(
body: Record<string, unknown>,
): { operation: IntegrationPlanOperation; fingerprint: string } | "none" | "half" | "unknown-operation" {
const { operation, planFingerprint } = body;
if (operation === undefined && planFingerprint === undefined) return "none";
if (operation === undefined || typeof planFingerprint !== "string" || planFingerprint.length === 0) return "half";
if (operation !== "apply" && operation !== "overwrite" && operation !== "disable" && operation !== "restore") {
return "unknown-operation";
}
return { operation, fingerprint: planFingerprint };
}
function halfBoundResponse(ctx: ManagementContext): Response {
return jsonResponse({
error: "operation and planFingerprint must be sent together",
code: "invalid_preview_binding",
}, 400, ctx.req, ctx.config);
}
/**
* Re-plan and compare before the mutation runs.
*
* The fingerprint is an optimistic token, never authorization: management authentication and
* every ownership rule still apply. What it adds is that a confirmation stops meaning anything
* the moment the state it described moved, and the refusal carries a fresh plan so the operator
* decides again against what is true now.
*/
function stalePlanGuard(
clientId: IntegrationClientId,
ctx: ManagementContext,
store: IntegrationStateStore,
request: PreviewRequest,
fingerprint: string,
capturedIdentity: string | null,
droidReasoningDefaults?: Record<string, string>,
modelNames?: ExportModelNames,
): {
revalidate: NonNullable<CoordinatedIntegrationOptions["revalidate"]>;
response: () => Response | null;
} {
let stale: IntegrationMutationPlan | "unavailable" | null = null;
return {
revalidate: async frozen => {
/*
* Plan the coordinator's OWN frozen input, never a freshly built one. Rebuilding here let
* the check validate against one roster while the mutation wrote from another, because an
* ordinary load can replace the snapshot at any time and nothing serialises that against
* this lock. The captured identity is verified separately, so a replacement is detected
* without ever swapping the roster this mutation is about to use.
*/
if (exportSnapshotIdentity(ctx.config) !== capturedIdentity) {
const refreshed = await buildIntegrationPreviewInput(clientId, ctx, store, droidReasoningDefaults, modelNames);
stale = refreshed === null ? "unavailable" : previewIntegration(refreshed.input, request);
return { ok: false, reason: "conflict", state: "conflict", clientId, message: "the model roster changed while confirming" };
}
const plan = previewIntegration(frozen, request);
if (plan.canApply && plan.fingerprint === fingerprint) return null;
stale = plan;
return { ok: false, reason: "conflict", state: plan.state, clientId, message: "that confirmation no longer describes this file" };
},
response: () => {
if (stale === null) return null;
if (stale === "unavailable") return previewUnavailableResponse(ctx);
return jsonResponse({
error: "integration preview is stale",
code: "integration_preview_stale",
plan: stale,
}, 409, ctx.req, ctx.config);
},
};
}
function internalErrorResponse(error: unknown, ctx: ManagementContext): Response {
// A selected Hermes profile whose boundary stopped holding is a refusal, not a server fault.
if (error instanceof HermesProfileError) {
return jsonResponse({ error: error.message, code: error.code, clientId: "hermes" }, error.status, ctx.req, ctx.config);
}
return jsonResponse({
error: error instanceof Error ? error.message : String(error),
code: "integration_internal_error",
}, 500, ctx.req, ctx.config);
}
async function readJsonBody(ctx: ManagementContext): Promise<unknown | Response> {
try {
return await readManagementJsonBody(ctx.req);
} catch (error) {
rethrowManagementBodyTooLarge(error);
return jsonResponse({
error: "invalid JSON body",
code: "invalid_json_body",
}, 400, ctx.req, ctx.config);
}
}
/**
* `ocx sync` refreshes an already-connected Pi file through this route instead of rebuilding it
* in the CLI process. Pi may carry raw nested selectors, and a raw selector is only safe when the
* proxy that will serve it proves it routes to the same model (#8172). Proving it against the
* CLI's own saved configuration and router cache could write a selector this proxy routes
* elsewhere, so the refresh runs here, against this process's config, router and roster.
*/
export const PI_SYNC_PATH = "/api/client-integrations/pi/sync";
async function piSyncResponse(ctx: ManagementContext): Promise<Response> {
const body = await readJsonBody(ctx);
if (body instanceof Response) return body;
if (!isPlainRecord(body) || Object.keys(body).length !== 0) {
return jsonResponse({ error: "Pi sync expects an empty object", code: "invalid_pi_sync_body" }, 400, ctx.req, ctx.config);
}
const { refreshOwnedCatalogIntegrations } = await import("../../integrations/catalog-refresh");
const results = await refreshOwnedCatalogIntegrations({
config: ctx.config,
port: managementInferencePort(ctx),
models: () => loadExportModels(ctx.config),
store: integrationStore(),
...pathOverrides(),
...(integrationMutationTestHooks?.io ? { io: integrationMutationTestHooks.io } : {}),
}, ["pi"]);
const ok = results.every(result => result.ok);
return jsonResponse({ ok, clientId: "pi", results }, ok ? 200 : 207, ctx.req, ctx.config);
}
function writerFailureResponse(
clientId: IntegrationClientId,
/*
* The writer's own refusal type, not a structural echo of it.
*
* A local shape with an optional `message` accepted a refusal that had lost
* its message on the way here, which is exactly how the drift branch shipped
* without one. `WriteRefused` requires it, so the compiler now objects.
*/
result: WriteRefused,
ctx: ManagementContext,
): Response {
/*
* Routed by `reason`, never by `state` (006 §5). A `write_failed` that
* happens to occur while the file is in a `conflict` state is still a write
* failure, and mapping on state first silently dropped its message,
* snapshotPath, and residual — the recovery information the flag exists to
* carry (A-gate round 5, blocker 3).
*/
const recovery = {
message: result.message,
...(result.snapshotPath ? { snapshotPath: result.snapshotPath } : {}),
...(result.residual ? { residual: true } : {}),
};
if (result.reason === "unsafe") {
return jsonResponse({
error: "integration config is unsafe",
code: "integration_unsafe",
clientId, state: result.state, reason: result.reason, ...recovery,
}, 409, ctx.req, ctx.config);
}
if (result.reason === "conflict") {
return jsonResponse({
error: "integration config conflicts with ownership record",
code: "integration_conflict",
clientId, state: result.state, reason: result.reason, ...recovery,
}, 409, ctx.req, ctx.config);
}
if (result.reason === "drift_requires_confirm") {
return jsonResponse({
error: "restore requires drift confirmation",
code: "integration_drift_confirmation_required",
clientId, state: result.state, reason: result.reason, ...recovery,
}, 409, ctx.req, ctx.config);
}
if (result.reason === "snapshot_expired") {
return jsonResponse({
error: "integration snapshot expired",
code: "integration_snapshot_expired",
clientId, state: result.state, reason: result.reason, ...recovery,
}, 410, ctx.req, ctx.config);
}
// not_installed, non_loopback, write_failed — always carry recovery fields.
return jsonResponse({
error: "integration mutation failed",
code: "integration_mutation_failed",
clientId, state: result.state, reason: result.reason, ...recovery,
}, 500, ctx.req, ctx.config);
}
/**
* Who asked for this deletion, as an audit value that is safe to persist.
*
* The tombstone lives in an append-only log the user can read, so this must be
* a principal NAME and nothing else -- never the admin token, a session id, or
* a filesystem path. `principal` is undefined only in direct-dispatch tests,
* which the auth gate documents as the untrusted admin-token case.
*/
function journalDeletePrincipal(ctx: ManagementContext): string {
return ctx.principal ?? "admin-token";
}
/**
* Retire one journal row at the operator request.
*
* The opId travels in the QUERY STRING, matching DELETE
* /api/codex-auth/accounts?id= -- the repository other DELETE-by-identifier. A
* body on DELETE is legal but unevenly handled by intermediaries, and there is
* nothing here a query cannot carry.
*/
async function handleJournalDelete(ctx: ManagementContext): Promise<Response> {
const { req, url } = ctx;
const opId = url.searchParams.get("opId")?.trim();
if (!opId) {
return jsonResponse({
error: "opId must be a non-empty string",
code: "invalid_op_id",
}, 400, req, ctx.config);
}
if (!hermesRequestScope(ctx.req)) {
const aside = await asideJournalDeleteResponse(ctx, opId, asideOptions(ctx));
if (aside) return aside;
}
try {
const store = integrationStore(ctx);
const operation = store.findOperation(opId);
if (!operation || outsideHermesScope(ctx, operation.clientId)) {
// Already retired, or never existed. Both are 404: the tombstone hides
// the row from findOperation, so a double-click is idempotent here
// rather than a second deletion of something.
return jsonResponse({
error: "integration operation not found",
code: "integration_operation_not_found",
opId,
}, 404, req, ctx.config);
}
/*
* The newest row per client is refused, and refused by the SERVER even
* though the GUI already hides its button. The button is a courtesy; this
* is the rule. An admin-token caller has no GUI at all.
*
* Re-read immediately before the write: a restore that landed while the
* dialog was open appends a new row and changes which opId is newest.
*/
const newest = store.listOperations(operation.clientId, 1)[0];
if (newest?.opId === opId) {
return jsonResponse({
error: "the newest operation for a client cannot be deleted",
code: "integration_journal_newest_protected",
clientId: operation.clientId,
opId,
}, 409, req, ctx.config);
}
store.retireOperation({
tombstone: opId,
at: new Date().toISOString(),
by: journalDeletePrincipal(ctx),
});
/*
* Snapshot bytes go too, and go AFTER the tombstone -- the same post-commit
* ordering appendOperation uses (journal.ts rule 1). If this fails, the row
* is still retired and retentionDegraded discloses the leftover file; the
* reverse order would delete a user backup for a deletion that then failed
* to record.
*/
const pruned = store.pruneSnapshots(operation.clientId);
if (pruned.ok) store.clearPruneFailure(operation.clientId);
else store.markPruneFailure(operation.clientId, pruned.error);
return jsonResponse({
ok: true,
opId,
clientId: operation.clientId,
snapshotRemoved: pruned.ok,
}, 200, req, ctx.config);
} catch (error) {
return internalErrorResponse(error, ctx);
}
}
export async function handleIntegrationRoutes(ctx: ManagementContext): Promise<Response | null> {
// The Antigravity app and agy CLI connectors are only read by their dashboard tab and CLI; load on demand.
if (ctx.url.pathname === "/api/gateway-clients" || ctx.url.pathname.startsWith("/api/gateway-clients/")) {
const { handleGatewayClientRoutes } = await import("./gateway-client-routes");
return handleGatewayClientRoutes(ctx);
}
// Aside delegates before the ordinary client handler. Reject unsupported intent before that
// delegation can enumerate profiles, load catalogs, or write a different preference.
let asideBody: unknown;
if (/^\/api\/client-integrations\/aside\/profiles(?:\/|$)/.test(ctx.url.pathname)
&& (ctx.req.method === "PUT" || ctx.req.method === "POST")) {
const body = await readJsonBody({ ...ctx, req: ctx.req.clone() });
if (body instanceof Response) return body;
asideBody = body;
if (isPlainRecord(body)) {
const naming = readModelNames(ctx, body, "aside", "apply");
if (naming instanceof Response) return naming;
}
}
const hermesBase = { store: integrationStore(), ...pathOverrides() };
const hermesProfiles = await hermesProfileListResponse(ctx, hermesBase, () => loadExportModels(ctx.config),
(scope, models) => readIntegrationState({
clientId: "hermes", models, config: ctx.config,
port: managementInferencePort(ctx), store: scope?.store ?? hermesBase.store, ...pathOverrides(),
...(scope?.resolvedPaths ? { env: scope.env, resolvedPaths: { ...scope.resolvedPaths } } : {}),
}));
if (hermesProfiles) return hermesProfiles;
const hermesScoped = scopeHermesProfileRequest(ctx, hermesBase);
if (hermesScoped instanceof Response) return hermesScoped;
if (hermesScoped) ctx = hermesScoped;
const { req, url } = ctx;
const profileOptions = asideOptions(ctx);
// An Aside profile change is the Home's decision (home-integration-decision.ts).
const asideDecision = ctx.config.runtimeRole === "client" ? undefined : await asideDecisionScope(ctx, asideBody);
let aside: Response | null;
try {
aside = asideDecision === undefined ? await handleAsideProfileRoutes(ctx, profileOptions) : await withLinkApply(async () => {
const refused = prepareHomeIntegrationDecision(ctx, "aside", asideDecision);
if (refused) return refused;
const response = await handleAsideProfileRoutes(ctx, profileOptions);
return response && response.status >= 200 && response.status < 300 ? recordHomeIntegrationDecision(ctx, "aside", response) : response;
});
} catch (error) {
if (error instanceof LinkApplyBusyError) return jsonResponse({ error: "integration mutation busy", code: "integration_mutation_busy", clientId: "aside" }, 409, req, ctx.config);
throw error;
}
if (aside) return aside;
if (url.pathname === PI_SYNC_PATH && req.method === "POST") return piSyncResponse(ctx);
if (url.searchParams.has("profile")
&& (url.pathname === INTEGRATION_COLLECTION_PATH || url.pathname.startsWith(INTEGRATION_ROUTE_PREFIX))
&& !INTEGRATION_HISTORY_PATHS.includes(url.pathname)) {
return jsonResponse({ error: "profile applies only to Aside", code: "invalid_aside_profile" }, 400, req, ctx.config);
}
if (url.pathname === "/api/client-integrations" && req.method === "GET") {
try {
const models = await loadExportModels(ctx.config);
const port = managementInferencePort(ctx);
// One store for the whole collection read: without it this route retried
// maintenance and counted snapshots in the default store even when the
// caller had bound everything else to a temp root (A-gate round 13).
const store = integrationStore();
/*
* The envelope carries `clientId`, but it is not restated here: WP2 and
* WP3 both echo `input.clientId` back in their result, and `input`
* IS this route's client. Writing it twice made the compiler pick the
* later one silently — a duplicate that could only ever hide a
* disagreement, never surface it.
*/
const clients = await Promise.all(INTEGRATION_CLIENT_IDS.map(async clientId => {
if (clientId === "aside") {
try { return await listAsideProfileStates({ ...profileOptions.input(), models }); }
catch { /* Existing status projection retains a safe unresolved-path diagnostic. */ }
}
return readIntegrationState({ clientId, models, config: ctx.config, port, store, ...pathOverrides() });
}));
return jsonResponse({ clients } satisfies IntegrationStateListEnvelope, 200, req, ctx.config);
} catch (error) {
return internalErrorResponse(error, ctx);
}
}
if (url.pathname === "/api/client-integrations/journal" && req.method === "DELETE") {
return handleJournalDelete(ctx);
}
if (url.pathname === "/api/client-integrations/journal") {
if (req.method !== "GET") return null;
const requestedClient = url.searchParams.get("client");
if (requestedClient !== null && !isIntegrationClientId(requestedClient)) {
return invalidClientResponse(ctx);
}
const asideJournal = hermesRequestScope(req) ? null : await asideJournalResponse(ctx, requestedClient, profileOptions);
if (asideJournal) return asideJournal;
try {
const store = integrationStore(ctx);
const storedOperations = store.listOperations(requestedClient ?? undefined);
const newestByClient = new Map<IntegrationClientId, string>();
for (const operation of storedOperations) {
if (!newestByClient.has(operation.clientId)) {
newestByClient.set(operation.clientId, operation.opId);
}
}
let operations: IntegrationJournalRow[] = storedOperations.map(operation => {
/*
* Resolved against the DISK, not read off the row.
*
* Retention deletes snapshot files and deliberately leaves the row's
* persisted tag saying `stored`, so copying that tag advertised undo
* for bytes that no longer exist — the GUI would offer the button and
* the restore route would answer 410. `readSnapshot` is the same
* resolver that preflight uses, which is what keeps the two agreeing.
*/
const snapshot = store.readSnapshot(operation).kind;
return {
opId: operation.opId,
clientId: operation.clientId,
kind: operation.kind,
at: operation.at,
configPath: operation.configPath,
snapshot,
/*
* The SAME resolution decides `undoable`. Reporting the tag honestly
* and then offering undo anyway is the identical defect one field
* over: restore would answer 410 for a row the GUI drew a button on.
* `none` stays undoable — restoring an op that created a file means
* deleting it, and that needs no snapshot bytes.
*/
/*
* Eligibility goes through the SAME matcher restore uses. This route
* used to represent a missing file as `""` and call that a match,
* while restore hashed `""` into a real digest — so the row was
* offered as Undo and then refused as drift.
*/
undoable: (() => {
if (snapshot === "expired") return false;
if (newestByClient.get(operation.clientId) !== operation.opId) return false;
const current = operation.clientId === "cline" ? (() => {
const io = createClineIO(integrationMutationTestHooks?.io ?? store.io(), operation.configPath, store);
const read = io.readText(operation.configPath);
return read.kind === "text" ? read.text : read.kind === "missing" ? null : undefined;
})() : currentConfigText(operation.configPath);
return current === undefined ? false : matchesOperationResult(operation, current);
})(),
/*
* Deliberately NOT an `undoable` derivative. The two axes are
* independent: an expired row is undoable-false and deletable-true,
* which is the pairing this route exists to produce -- a row whose
* bytes are gone previously carried no action at all.
*/
deletable: newestByClient.get(operation.clientId) !== operation.opId,
};
});
if (requestedClient === null) {
const profiles = await asideJournalResponse(ctx, "aside", profileOptions);
if (profiles?.ok) {
const body = await profiles.json() as IntegrationJournalEnvelope;
operations = [...operations.filter(row => row.clientId !== "aside"), ...body.operations]
.sort((a, b) => b.at.localeCompare(a.at));
}
}
return jsonResponse({ operations } satisfies IntegrationJournalEnvelope, 200, req, ctx.config);
} catch (error) {
return internalErrorResponse(error, ctx);
}
}
if (url.pathname === "/api/client-integrations/preview") {
if (req.method !== "POST") return null;
const parsed = await readJsonBody(ctx);
if (parsed instanceof Response) return parsed;
if (!isPlainRecord(parsed)) {
return jsonResponse({ error: "preview body must be an object", code: "invalid_preview_body" }, 400, req, ctx.config);
}
const previewClient = parsed.clientId;
if (typeof previewClient !== "string"
|| !(INTEGRATION_CLIENT_IDS as readonly string[]).includes(previewClient)) {
return invalidClientResponse(ctx);
}
/*
* Aside is a set of profiles, not one file, and every mutation it has requires a profile. A
* plan built here would describe the legacy single-account location and no bound mutation
* would accept it, so an operator could confirm something nothing can carry out. The canonical
* per-profile preview answers this question properly, and the mutation routes already refuse
* the unscoped spelling the same way.
*/
if (previewClient === "aside") {
return jsonResponse({ error: "Use the canonical Aside profile path", code: "invalid_aside_profile_path" }, 400, req, ctx.config);
}
if (outsideHermesScope(ctx, previewClient as IntegrationClientId)) {
return jsonResponse({ error: "A Hermes profile plan must name the Hermes client", code: "invalid_hermes_profile" }, 400, req, ctx.config);
}
const operation = parsed.operation;
if (operation !== "apply" && operation !== "overwrite" && operation !== "disable") {
return jsonResponse({
error: "operation must be apply, overwrite or disable",
code: "invalid_preview_operation",
}, 400, req, ctx.config);
}
const droidDefaults = readDroidReasoningDefaults(ctx, parsed, previewClient, operation);
if (droidDefaults instanceof Response) return droidDefaults;
const modelNames = readModelNames(ctx, parsed, previewClient, operation);
if (modelNames instanceof Response) return modelNames;
try {
const captured = await buildIntegrationPreviewInput(
previewClient as IntegrationClientId, ctx, integrationStore(ctx), droidDefaults, modelNames,
);
if (!captured) return previewUnavailableResponse(ctx);
if (droidDefaults !== undefined) {
const invalid = validateDroidReasoningDefaults(captured.input.models, droidDefaults);
if (invalid) return invalidDroidDefaultsResponse(ctx, invalid);
}
return jsonResponse(previewIntegration(captured.input, { operation }), 200, req, ctx.config);
} catch (error) {
return internalErrorResponse(error, ctx);
}
}
if (url.pathname === "/api/client-integrations/restore/preview" || url.pathname === "/api/client-integrations/commandcode/restore/preview") {
if (req.method !== "POST") return null;
const parsed = await readJsonBody(ctx);
if (parsed instanceof Response) return parsed;
if (isPlainRecord(parsed)) {
const naming = readModelNames(ctx, parsed, "", "restore");
if (naming instanceof Response) return naming;
}
if (!isPlainRecord(parsed) || typeof parsed.opId !== "string" || parsed.opId.trim().length === 0) {
return jsonResponse({ error: "opId must be a non-empty string", code: "invalid_op_id" }, 400, req, ctx.config);
}
if (parsed.confirmDrift !== undefined && typeof parsed.confirmDrift !== "boolean") {
return jsonResponse({ error: "confirmDrift must be a boolean", code: "invalid_confirm_drift" }, 400, req, ctx.config);
}
const opId = parsed.opId.trim();
const scopeResponse = restoreClientScopeResponse(ctx, opId, parsed.expectedClientId, url.pathname === "/api/client-integrations/commandcode/restore/preview" ? "commandcode" : undefined);
if (scopeResponse) return scopeResponse;
try {
const store = integrationStore(ctx);
const operation = store.findOperation(opId);
/*
* Answered as "not found" rather than by reading the row back to the caller. A preview is
* reached before any confirmation, so it is the cheapest place to probe journal contents,
* and it declines to be one.
*/
if (!operation || outsideHermesScope(ctx, operation.clientId)) {
return jsonResponse({
error: "integration operation not found",
code: "integration_operation_not_found",
opId,
}, 404, req, ctx.config);
}
// Same rule, decided after the row is found so an unscoped undo of an Aside operation is
// refused for what it is rather than answered as a missing operation.
if (operation.clientId === "aside") {
return jsonResponse({ error: "Use the canonical Aside profile path", code: "invalid_aside_profile_path" }, 400, req, ctx.config);
}
const captured = await buildIntegrationPreviewInput(operation.clientId, ctx, store);
if (!captured) return previewUnavailableResponse(ctx);
const plan = previewIntegration(captured.input, {
operation: "restore",
opId,
confirmDrift: parsed.confirmDrift ?? false,
});
return jsonResponse(plan, 200, req, ctx.config);
} catch (error) {
return internalErrorResponse(error, ctx);
}
}
if (url.pathname === "/api/client-integrations/restore" || url.pathname === "/api/client-integrations/commandcode/restore") {
if (req.method !== "POST") return null;
const parsed = await readJsonBody(ctx);
if (parsed instanceof Response) return parsed;
if (isPlainRecord(parsed)) {
const naming = readModelNames(ctx, parsed, "", "restore");
if (naming instanceof Response) return naming;
}
if (!isPlainRecord(parsed) || typeof parsed.opId !== "string" || parsed.opId.trim().length === 0) {
return jsonResponse({
error: "opId must be a non-empty string",
code: "invalid_op_id",
}, 400, req, ctx.config);
}
if (parsed.confirmDrift !== undefined && typeof parsed.confirmDrift !== "boolean") {
return jsonResponse({
error: "confirmDrift must be a boolean",
code: "invalid_confirm_drift",
}, 400, req, ctx.config);
}
const opId = parsed.opId.trim();
const scopeResponse = restoreClientScopeResponse(ctx, opId, parsed.expectedClientId, url.pathname === "/api/client-integrations/commandcode/restore" ? "commandcode" : undefined);
if (scopeResponse) return scopeResponse;
const confirmDrift = parsed.confirmDrift ?? false;
const restoreBinding = planBindingOf(parsed);
if (restoreBinding === "half") return halfBoundResponse(ctx);
if (restoreBinding === "unknown-operation" || (restoreBinding !== "none" && restoreBinding.operation !== "restore")) {
return jsonResponse({
error: "operation does not match the requested change",
code: "invalid_preview_operation",
}, 400, req, ctx.config);
}
// The binding travels with the request. Dropping it here routed a bound Aside restore into
// the unbound path, which executed the mutation while its confirmation went unexamined.
// A Hermes-scoped restore never delegates: its operation lives in the selected Hermes store.
// A restore on the Home is its decision (home-integration-decision.ts); a Hermes profile's is not.
const restoreDecides = ctx.config.runtimeRole !== "client" && !hermesRequestScope(req)?.resolvedPaths;
const restoreAside = () => asideRestoreResponse(ctx, {
opId,
confirmDrift,
...(parsed.operation === undefined ? {} : { operation: parsed.operation }),
...(parsed.planFingerprint === undefined ? {} : { planFingerprint: parsed.planFingerprint }),
}, profileOptions);
let asideRestore: Response | null;
try {
const rootEntry = integrationStore(ctx).findOperation(opId);
asideRestore = hermesRequestScope(req) ? null : rootEntry && rootEntry.clientId !== "aside" ? await restoreAside() : restoreDecides ? await withLinkApply(async () => {
const refused = prepareHomeIntegrationDecision(ctx, undefined);
if (refused) return refused;
const response = await restoreAside();
return response && response.status >= 200 && response.status < 300 ? recordHomeIntegrationDecision(ctx, "aside", response) : response;
}) : await restoreAside();
} catch (error) {
if (error instanceof LinkApplyBusyError) return jsonResponse({ error: "integration mutation busy", code: "integration_mutation_busy" }, 409, req, ctx.config);
return internalErrorResponse(error, ctx);
}
if (asideRestore) return asideRestore;
let restoreClientId: IntegrationClientId | undefined;
try {
const store = integrationStore(ctx);
const operation = store.findOperation(opId);
if (!operation || outsideHermesScope(ctx, operation.clientId)) {
return jsonResponse({
error: "integration operation not found",
code: "integration_operation_not_found",
opId,
}, 404, req, ctx.config);
}
restoreClientId = operation.clientId;
const snapshot = store.readSnapshot(operation);
if (snapshot.kind === "expired") {
return jsonResponse({
error: "integration snapshot expired",
code: "integration_snapshot_expired",
opId,
}, 410, req, ctx.config);
}
// Every caller must hold a current passive roster before it can join a flight.
const boundRestore = restoreBinding === "none"
? null
: await buildIntegrationPreviewInput(operation.clientId, ctx, store);
if (restoreBinding !== "none" && boundRestore === null) return previewUnavailableResponse(ctx);
if (boundRestore && integrationMutationTestHooks?.afterBoundSnapshot) await integrationMutationTestHooks.afterBoundSnapshot();
if (boundRestore && exportSnapshotIdentity(ctx.config) !== boundRestore.identity) {
const current = buildIntegrationPreviewInput(operation.clientId, ctx, store);
return current === null ? previewUnavailableResponse(ctx) : jsonResponse({
error: "integration preview is stale", code: "integration_preview_stale",
plan: previewIntegration(current.input, { operation: "restore", opId, confirmDrift }),
}, 409, req, ctx.config);
}
const response = await runIntegrationMutationFlight(
operation.clientId,
scopedFlightKey(ctx, `restore:${opId}:${confirmDrift}:${restoreBinding === "none" ? "unbound" : JSON.stringify([restoreBinding.fingerprint, boundRestore?.identity])}`),
integrationMutationTestHooks?.io?.now ?? Date.now,
async () => {
const apply = async () => {
if (restoreDecides) {
const refused = prepareHomeIntegrationDecision(ctx, operation.clientId);
if (refused) return refused;
}
const writeInput = boundRestore
? boundRestore.input
: await buildIntegrationWriteInput(operation.clientId, ctx, store);
const restoreGuard = restoreBinding === "none" ? null : stalePlanGuard(
operation.clientId,
ctx,
store,
{ operation: "restore", opId, confirmDrift },
restoreBinding.fingerprint,
boundRestore === null ? null : boundRestore.identity,
);
const restoreInput: IntegrationRestoreInput = {
...writeInput,
opId,
confirmDrift,
};
const result = await restoreIntegrationCoordinated(restoreInput, {
lockSeams: integrationMutationTestHooks?.lockSeams,
...(restoreGuard ? { revalidate: restoreGuard.revalidate } : {}),
restoreGuard: () => hermesBoundaryRefusal(ctx),
});
const stale = restoreGuard?.response();
if (stale) return stale;
if (!result.ok) return writerFailureResponse(operation.clientId, result, ctx);
const restored = jsonResponse(result satisfies IntegrationRestoreEnvelope, 200, req, ctx.config);
return restoreDecides ? recordHomeIntegrationDecision(ctx, operation.clientId, restored, () => ownedIntent(store, operation.clientId)) : restored;
};
return restoreDecides ? withLinkApply(apply) : apply();
},
);
return jsonResponse(await response.clone().json(), response.status, req, ctx.config);
} catch (error) {
if (error instanceof IntegrationMutationBusyError || error instanceof IntegrationWriterLockBusyError || error instanceof LinkApplyBusyError) {
return jsonResponse({
error: "integration mutation busy",
code: "integration_mutation_busy",
clientId: restoreClientId ?? (error instanceof IntegrationMutationBusyError ? error.clientId : undefined),
}, 409, req, ctx.config);
}
return internalErrorResponse(error, ctx);
}
}
if (req.method !== "GET" && req.method !== "PUT") return null;
const requestedClient = decodeClientPath(url.pathname);
if (requestedClient === null) return null;
if (!isIntegrationClientId(requestedClient)) return invalidClientResponse(ctx);
// Canonical Aside paths are owned above. Never decode an alternate spelling
// into the legacy single-account writer or bypass profile policy/guards.
if (requestedClient === "aside") {
return jsonResponse({ error: "Use the canonical Aside profile path", code: "invalid_aside_profile_path" }, 400, req, ctx.config);
}
if (req.method === "GET") {
try {
const input = await buildIntegrationWriteInput(requestedClient, ctx, integrationStore(ctx));
const state = readIntegrationState(input);
const scope = hermesRequestScope(req);
// Detection runs only for the client that needs it: `defaults` is a
// process spawn, and no other client's read should pay for it.
const envelope: IntegrationStateEnvelope = requestedClient === "raycast"
? { ...state, raycast: (raycastDetectTestHook ?? detectRaycast)() }
: requestedClient === "droid"
? {
...state,
droidReasoning: {
models: droidReasoningModels(input.models),
defaults: readOwnedDroidReasoningDefaults(input),
},
}
: scope ? { ...state, hermesProfile: scope.profile.name } : state;
return jsonResponse(envelope, 200, req, ctx.config);
} catch (error) {
return internalErrorResponse(error, ctx);
}
}
const parsed = await readJsonBody(ctx);
if (parsed instanceof Response) return parsed;
if (!isPlainRecord(parsed) || typeof parsed.enabled !== "boolean") {
return jsonResponse({
error: "enabled must be a boolean",
code: "invalid_enabled",
}, 400, req, ctx.config);
}
if (parsed.overwriteConflict !== undefined && typeof parsed.overwriteConflict !== "boolean") {
return jsonResponse({
error: "overwriteConflict must be a boolean",
code: "invalid_overwrite_conflict",
}, 400, req, ctx.config);
}
/*
* Rejected rather than ignored. Disabling a block we do not own is precisely
* the deletion this subsystem exists to prevent, so a caller sending this
* combination has misunderstood the field, and silently dropping it would
* answer 200 for a request whose intent we refused.
*/
if (parsed.overwriteConflict === true && parsed.enabled === false) {
return jsonResponse({
error: "overwriteConflict applies only to enabling an integration",
code: "invalid_overwrite_conflict",
}, 400, req, ctx.config);
}
const requestedOperation: IntegrationPlanOperation = parsed.enabled
? (parsed.overwriteConflict === true ? "overwrite" : "apply")
: "disable";
const droidDefaults = readDroidReasoningDefaults(ctx, parsed, requestedClient, requestedOperation);
if (droidDefaults instanceof Response) return droidDefaults;
const modelNames = readModelNames(ctx, parsed, requestedClient, requestedOperation);
if (modelNames instanceof Response) return modelNames;
const binding = planBindingOf(parsed);
if (binding === "half") return halfBoundResponse(ctx);
if (binding === "unknown-operation" || (binding !== "none" && binding.operation !== requestedOperation)) {
// A confirmation that names a different operation than the request performs is not a
// confirmation of this request.
return jsonResponse({
error: "operation does not match the requested change",
code: "invalid_preview_operation",
}, 400, req, ctx.config);
}
try {
// The toggle is the Home's decision (home-integration-decision.ts): Children's defaults are
// saved first, an unreadable route-intent.json refuses while nothing has changed, and the
// result is recorded below. A selected Hermes profile is not the Home's client.
const recordsDecision = ctx.config.runtimeRole !== "client" && isRouteClientId(requestedClient) && !hermesRequestScope(req)?.resolvedPaths;
const boundToggle = binding === "none"
? null
: await buildIntegrationPreviewInput(requestedClient, ctx, integrationStore(ctx), droidDefaults, modelNames);
if (binding !== "none" && boundToggle === null) return previewUnavailableResponse(ctx);
if (boundToggle && integrationMutationTestHooks?.afterBoundSnapshot) await integrationMutationTestHooks.afterBoundSnapshot();
/*
* A bound request is built from the same passive roster the guard re-plans against, and an
* unbound one keeps its existing refreshing path. Building the refreshing input first would
* have had the mutation and its own confirmation check disagree about the roster by
* construction, which is the disagreement this binding exists to detect.
*/
if (boundToggle && exportSnapshotIdentity(ctx.config) !== boundToggle.identity) {
const current = buildIntegrationPreviewInput(requestedClient, ctx, integrationStore(ctx), droidDefaults, modelNames);
return current === null ? previewUnavailableResponse(ctx) : jsonResponse({
error: "integration preview is stale", code: "integration_preview_stale",
plan: previewIntegration(current.input, { operation: requestedOperation }),
}, 409, req, ctx.config);
}
const response = await runIntegrationMutationFlight(
requestedClient,
scopedFlightKey(ctx, `${requestedOperation}:modelNames:${modelNames ?? "omitted"}:binding:${binding === "none" ? "unbound" : JSON.stringify([binding.fingerprint, boundToggle?.identity])}:defaults:${JSON.stringify(droidDefaults ?? null)}`),
integrationMutationTestHooks?.io?.now ?? Date.now,
async () => {
const apply = async () => {
if (recordsDecision) {
const refused = prepareHomeIntegrationDecision(ctx, requestedClient);
if (refused) return refused;
}
const input = boundToggle
? boundToggle.input
: await buildIntegrationWriteInput(requestedClient, ctx, integrationStore(ctx), droidDefaults, modelNames);
if (droidDefaults !== undefined) {
const invalid = validateDroidReasoningDefaults(input.models, droidDefaults);
if (invalid) return invalidDroidDefaultsResponse(ctx, invalid);
}
const guard = binding === "none" ? null : stalePlanGuard(
requestedClient,
ctx,
integrationStore(ctx),
{ operation: binding.operation },
binding.fingerprint,
boundToggle === null ? null : boundToggle.identity,
droidDefaults,
modelNames,
);
const options = {
lockSeams: integrationMutationTestHooks?.lockSeams,
...(guard ? { revalidate: guard.revalidate } : {}),
guard: () => hermesBoundaryRefusal(ctx),
};
const pending = !parsed.enabled ? disableIntegrationCoordinated(input, options)
: parsed.overwriteConflict === true ? overwriteIntegrationCoordinated(input, options)
: applyIntegrationCoordinated(input, options);
// Coordinators freeze their input synchronously before returning the promise.
integrationMutationTestHooks?.afterWriterStart?.();
const result = await pending;
const stale = guard?.response();
if (stale) return stale;
if (!result.ok) return writerFailureResponse(requestedClient, result, ctx);
const toggled = jsonResponse(result satisfies IntegrationToggleEnvelope, 200, req, ctx.config);
return recordsDecision ? recordHomeIntegrationDecision(ctx, requestedClient, toggled, () => ({ enabled: parsed.enabled === true,
...(modelNames !== undefined && (requestedClient === "hermes" || requestedClient === "commandcode") ? { modelNames } : {}) })) : toggled;
};
return recordsDecision ? withLinkApply(apply) : apply();
},
);
return jsonResponse(await response.clone().json(), response.status, req, ctx.config);
} catch (error) {
if (error instanceof IntegrationMutationBusyError || error instanceof IntegrationWriterLockBusyError || error instanceof LinkApplyBusyError) {
return jsonResponse({
error: "integration mutation busy",
code: "integration_mutation_busy",
clientId: requestedClient,
}, 409, req, ctx.config);
}
return internalErrorResponse(error, ctx);
}
}