@sayknow-cli/coding-agent 0.5.20 → 0.5.22

package/src/cli/auth-gateway-cli.ts

@@ -2,15 +2,20 @@
  * `skc auth-gateway` command handlers.
  *
  * Boots a forward-proxy server that lets less-trusted clients (the macOS
- * usage widget and containerized deployments) make provider API calls without ever
- * seeing the access token. The gateway is itself a broker client and
- * resolves credentials through the configured broker (via the same
- * `SKC_AUTH_BROKER_URL` / `auth.broker.url` precedence used elsewhere).
+ * usage widget, local desktop apps and containerized deployments) make provider
+ * API calls without ever seeing the access token.
+ *
+ * Credential source mirrors `discoverAuthStorage()` in sdk/session.ts:
+ *   - broker configured (`SKC_AUTH_BROKER_URL` / `auth.broker.url`) → the
+ *     gateway is a broker client and never touches local SQLite.
+ *   - no broker → the local SQLite store at `<agentDir>/agent.db`, so a
+ *     single-machine user runs the gateway alone instead of also standing up
+ *     `skc auth-broker serve`.
  *
  * Sub-verbs:
- *   - `serve [--bind=…]` — boots the gateway against the configured broker.
+ *   - `serve [--bind=…]` — boots the gateway against the broker or local store.
  *   - `token` / `token --regenerate` — manages the gateway bearer token file.
- *   - `status` — prints the locally-stored gateway token and bind hint.
+ *   - `status` — prints the locally-stored gateway token and credential source.
  */
 import * as crypto from "node:crypto";
 import * as fs from "node:fs/promises";
@@ -28,7 +33,7 @@ import {
 	type SnapshotResponse,
 	startAuthGateway,
 } from "@sayknow-cli/ai";
-import { getConfigRootDir, isEnoent, VERSION } from "@sayknow-cli/utils";
+import { getAgentDbPath, getAgentDir, getConfigRootDir, isEnoent, VERSION } from "@sayknow-cli/utils";
 import chalk from "chalk";
 import { type AuthBrokerClientConfig, resolveAuthBrokerConfig } from "../session/auth-broker-config";
 
@@ -128,29 +133,66 @@ async function fetchBrokerSnapshot(client: AuthBrokerClient): Promise<SnapshotRe
 	return result.snapshot;
 }
 
-async function runServe(flags: AuthGatewayCommandArgs["flags"]): Promise<void> {
+/**
+ * Credential source the gateway is serving from. `broker` mirrors the previous
+ * behaviour; `local` is the single-machine path that makes `skc auth-broker
+ * serve` optional.
+ */
+export interface GatewayCredentialSource {
+	storage: AuthStorage;
+	kind: "broker" | "local";
+	/** Broker URL in broker mode, `null` in local mode. */
+	brokerUrl: string | null;
+	/** `<agentDir>/agent.db` in local mode, `null` in broker mode. */
+	dbPath: string | null;
+	/** `broker <url>` / `local <dbPath>` — also used as the AuthStorage sourceLabel. */
+	label: string;
+}
+
+/**
+ * Open the credential store the gateway should serve from.
+ *
+ * Same precedence as `discoverAuthStorage()` in sdk/session.ts: a configured
+ * broker wins, otherwise fall back to the local SQLite store. Callers own the
+ * returned `storage` and must `close()` it.
+ */
+export async function openGatewayCredentialSource(): Promise<GatewayCredentialSource> {
 	const brokerConfig = await resolveAuthBrokerConfig();
-	if (!brokerConfig) {
-		throw new Error(
-			"`skc auth-gateway serve` requires SKC_AUTH_BROKER_URL (or `auth.broker.url`/`auth.broker.token` in config.yml). The gateway is itself a broker client.",
-		);
+	if (brokerConfig) {
+		// Refresh + usage both flow through the store's broker hooks automatically —
+		// `RemoteAuthCredentialStore.refreshOAuthCredential` and `.fetchUsageReports`.
+		// AuthStorage discovers them when no explicit option overrides them, so the
+		// gateway only needs to construct the store and pass it in.
+		const client = createBrokerClient(brokerConfig);
+		const initialSnapshot = await fetchBrokerSnapshot(client);
+		const store = new RemoteAuthCredentialStore({ client, initialSnapshot });
+		const label = `broker ${brokerConfig.url}`;
+		const storage = new AuthStorage(store, { sourceLabel: label });
+		try {
+			await storage.reload();
+		} catch (error) {
+			try {
+				storage.close();
+			} catch {
+				// Preserve the initial reload failure.
+			}
+			throw error;
+		}
+		return { storage, kind: "broker", brokerUrl: brokerConfig.url, dbPath: null, label };
 	}
+	const dbPath = getAgentDbPath(getAgentDir());
+	const label = `local ${dbPath}`;
+	// `AuthStorage.create` opens the store and reloads it in one step.
+	const storage = await AuthStorage.create(dbPath, { sourceLabel: label });
+	return { storage, kind: "local", brokerUrl: null, dbPath, label };
+}
+
+async function runServe(flags: AuthGatewayCommandArgs["flags"]): Promise<void> {
 	const bind = flags.bind ?? DEFAULT_AUTH_GATEWAY_BIND;
 	const gatewayToken = flags.noAuth ? null : await ensureToken();
 
-	// Build a broker-backed AuthStorage — same pattern as discoverAuthStorage()
-	// in sdk/session.ts. The gateway never touches local SQLite.
-	const client = createBrokerClient(brokerConfig);
-	const initialSnapshot = await fetchBrokerSnapshot(client);
-	const store = new RemoteAuthCredentialStore({ client, initialSnapshot });
-	// Refresh + usage both flow through the store's broker hooks automatically —
-	// `RemoteAuthCredentialStore.refreshOAuthCredential` and `.fetchUsageReports`.
-	// AuthStorage discovers them when no explicit option overrides them, so the
-	// gateway only needs to construct the store and pass it in.
-	const storage = new AuthStorage(store, {
-		sourceLabel: `broker ${brokerConfig.url}`,
-	});
-	await storage.reload();
+	const source = await openGatewayCredentialSource();
+	const storage = source.storage;
 
 	// Build the model resolver + catalog from pi-ai's bundled metadata, scoped
 	// to providers we hold credentials for. Format handlers ask `resolveModel`
@@ -183,7 +225,11 @@ async function runServe(flags: AuthGatewayCommandArgs["flags"]): Promise<void> {
 	} else {
 		process.stdout.write(`auth: disabled (--no-auth) — any client can call this gateway\n`);
 	}
-	process.stdout.write(`upstream broker: ${brokerConfig.url}\n`);
+	if (source.kind === "broker") {
+		process.stdout.write(`upstream broker: ${source.brokerUrl}\n`);
+	} else {
+		process.stdout.write(`credentials: local ${source.dbPath}\n`);
+	}
 
 	const stopped = Promise.withResolvers<void>();
 	let shutdownStarted = false;
@@ -243,24 +289,35 @@ async function runToken(flags: AuthGatewayCommandArgs["flags"]): Promise<void> {
 
 async function runStatus(flags: AuthGatewayCommandArgs["flags"]): Promise<void> {
 	const token = await readToken();
-	const brokerConfig = await resolveAuthBrokerConfig();
 	const tokenFile = getTokenFilePath();
-	if (!brokerConfig) {
+	const tokenPresent = token !== null;
+
+	let source: GatewayCredentialSource;
+	try {
+		source = await openGatewayCredentialSource();
+	} catch (error) {
+		// Broker unreachable, or the local SQLite store failed to open.
+		const message = error instanceof Error ? error.message : String(error);
+		const brokerConfig = await resolveAuthBrokerConfig().catch(() => null);
 		const status = {
 			ready: false,
-			reason: "not_configured",
+			reason: brokerConfig ? "broker_unavailable" : "local_store_unavailable",
+			source: brokerConfig ? "broker" : "local",
 			tokenFile,
-			tokenPresent: token !== null,
-			broker: null,
-			brokerConfigured: false,
+			tokenPresent,
+			broker: brokerConfig?.url ?? null,
+			brokerConfigured: brokerConfig !== null,
 			brokerAuthenticated: false,
+			dbPath: brokerConfig ? null : getAgentDbPath(getAgentDir()),
+			error: message,
 		};
 		if (flags.json) {
 			process.stdout.write(`${JSON.stringify(status)}\n`);
 		} else {
-			process.stdout.write(`${chalk.yellow("No broker configured.")} Set SKC_AUTH_BROKER_URL.\n`);
+			const what = brokerConfig ? `upstream broker: ${brokerConfig.url}` : `local store: ${status.dbPath}`;
+			process.stdout.write(`${chalk.red("FAILED")} ${what}: ${message}\n`);
 			process.stdout.write(
-				`token: ${status.tokenPresent ? chalk.green("present") : chalk.red("missing")} at ${status.tokenFile}\n`,
+				`token: ${tokenPresent ? chalk.green("present") : chalk.red("missing")} at ${tokenFile}\n`,
 			);
 		}
 		process.exitCode = 1;
@@ -268,56 +325,50 @@ async function runStatus(flags: AuthGatewayCommandArgs["flags"]): Promise<void>
 	}
 
 	try {
-		const snapshot = await fetchBrokerSnapshot(createBrokerClient(brokerConfig));
-		const tokenPresent = token !== null;
+		const credentialCount = source.storage.exportSnapshot().credentials.length;
+		// Ready means a client can actually get an answer: it needs a bearer
+		// token to present, and we need at least one provider credential to serve.
+		const ready = tokenPresent && credentialCount > 0;
 		const status = {
-			ready: tokenPresent,
-			reason: tokenPresent ? null : "token_missing",
+			ready,
+			reason: !tokenPresent ? "token_missing" : credentialCount === 0 ? "no_credentials" : null,
+			source: source.kind,
 			tokenFile,
 			tokenPresent,
-			broker: brokerConfig.url,
-			brokerConfigured: true,
-			brokerAuthenticated: true,
-			credentialCount: snapshot.credentials.length,
+			broker: source.brokerUrl,
+			brokerConfigured: source.kind === "broker",
+			brokerAuthenticated: source.kind === "broker",
+			dbPath: source.dbPath,
+			credentialCount,
 		};
 		if (flags.json) {
 			process.stdout.write(`${JSON.stringify(status)}\n`);
 		} else {
-			const brokerLine = `upstream broker: ${brokerConfig.url} (${snapshot.credentials.length} credential${
-				snapshot.credentials.length === 1 ? "" : "s"
-			})`;
-			process.stdout.write(`${tokenPresent ? chalk.green("ready") : chalk.yellow("not ready")} ${brokerLine}\n`);
+			const plural = credentialCount === 1 ? "" : "s";
+			const sourceLine =
+				source.kind === "broker"
+					? `upstream broker: ${source.brokerUrl} (${credentialCount} credential${plural})`
+					: `local store: ${source.dbPath} (${credentialCount} credential${plural})`;
+			process.stdout.write(`${ready ? chalk.green("ready") : chalk.yellow("not ready")} ${sourceLine}\n`);
 			process.stdout.write(
-				`token: ${tokenPresent ? chalk.green("present") : chalk.red("missing")} at ${status.tokenFile}\n`,
+				`token: ${tokenPresent ? chalk.green("present") : chalk.red("missing")} at ${tokenFile}\n`,
 			);
 			if (!tokenPresent) {
 				process.stdout.write(
 					"Run `skc auth-gateway token` or `skc auth-gateway serve` to create a bearer token.\n",
 				);
 			}
+			if (credentialCount === 0) {
+				process.stdout.write(
+					source.kind === "broker"
+						? "The broker holds no credentials. Log in on the broker host.\n"
+						: "No local credentials. Run `skc auth-broker login <provider>` (e.g. anthropic).\n",
+				);
+			}
 		}
-		if (!tokenPresent) process.exitCode = 1;
-	} catch (error) {
-		const message = error instanceof Error ? error.message : String(error);
-		const status = {
-			ready: false,
-			reason: "broker_unavailable",
-			tokenFile,
-			tokenPresent: token !== null,
-			broker: brokerConfig.url,
-			brokerConfigured: true,
-			brokerAuthenticated: false,
-			error: message,
-		};
-		if (flags.json) {
-			process.stdout.write(`${JSON.stringify(status)}\n`);
-		} else {
-			process.stdout.write(`${chalk.red("FAILED")} upstream broker: ${brokerConfig.url}: ${message}\n`);
-			process.stdout.write(
-				`token: ${status.tokenPresent ? chalk.green("present") : chalk.red("missing")} at ${status.tokenFile}\n`,
-			);
-		}
-		process.exitCode = 1;
+		if (!ready) process.exitCode = 1;
+	} finally {
+		source.storage.close();
 	}
 }
 
@@ -343,30 +394,22 @@ export async function runAuthGatewayCommand(cmd: AuthGatewayCommandArgs): Promis
 }
 
 /**
- * `skc auth-gateway check` — probe each broker-supplied credential and print
- * per-credential auth health. Use this when the gateway is returning 401s and
+ * `skc auth-gateway check` — probe each credential the gateway would serve and
+ * print per-credential auth health. Use this when the gateway is returning 401s
  * you need to find which row in a multi-account pool is the bad one. The
  * aggregate `/v1/usage` endpoint silently drops failed credentials, so a
  * dedicated diagnostic is the only way to see which credentials failed.
  */
 async function runCheck(flags: AuthGatewayCommandArgs["flags"]): Promise<void> {
-	const brokerConfig = await resolveAuthBrokerConfig();
-	if (!brokerConfig) {
-		throw new Error(
-			"`skc auth-gateway check` requires SKC_AUTH_BROKER_URL (or `auth.broker.url`/`auth.broker.token` in config.yml). It probes the same credentials the gateway would serve.",
-		);
-	}
-
-	const client = createBrokerClient(brokerConfig);
-	const initialSnapshot = await fetchBrokerSnapshot(client);
-	const store = new RemoteAuthCredentialStore({ client, initialSnapshot });
-	const storage = new AuthStorage(store, { sourceLabel: `broker ${brokerConfig.url}` });
+	const source = await openGatewayCredentialSource();
+	const storage = source.storage;
 	try {
-		await storage.reload();
 		const results = await storage.checkCredentials();
 
 		if (flags.json) {
-			process.stdout.write(`${JSON.stringify({ broker: brokerConfig.url, credentials: results }, null, 2)}\n`);
+			process.stdout.write(
+				`${JSON.stringify({ source: source.kind, broker: source.brokerUrl, dbPath: source.dbPath, credentials: results }, null, 2)}\n`,
+			);
 		} else {
 			const grouped = new Map<string, typeof results>();
 			for (const row of results) {
@@ -375,7 +418,7 @@ async function runCheck(flags: AuthGatewayCommandArgs["flags"]): Promise<void> {
 				grouped.set(row.provider, list);
 			}
 			const providers = [...grouped.keys()].sort();
-			process.stdout.write(`broker: ${brokerConfig.url}\n`);
+			process.stdout.write(`${source.label}\n`);
 			for (const provider of providers) {
 				const rows = grouped.get(provider) ?? [];
 				process.stdout.write(`\n${chalk.bold(provider)} (${rows.length})\n`);

package/src/cli/setup-cli.ts

@@ -48,6 +48,7 @@ export type SetupComponent =
 	| "provider"
 	| "python"
 	| "stt"
+	| "typesafe"
 	| "ui-skills";
 
 export interface SetupCommandArgs {
@@ -81,6 +82,8 @@ export interface SetupCommandArgs {
 		yes?: boolean;
 		dryRun?: boolean;
 		keychain?: boolean;
+		skipVerify?: boolean;
+		remove?: boolean;
 	};
 }
 
@@ -94,6 +97,7 @@ const VALID_COMPONENTS: SetupComponent[] = [
 	"provider",
 	"python",
 	"stt",
+	"typesafe",
 ];
 
 function hasProviderSetupFlags(flags: SetupCommandArgs["flags"]): boolean {
@@ -188,8 +192,12 @@ export function parseSetupArgs(args: string[]): SetupCommandArgs | undefined {
 		} else if (arg === "--base-url") {
 			flags.baseUrl = args[++i];
 		} else if (arg === "--api-key") {
-			console.error(chalk.red("Provider setup rejects raw --api-key values; use --api-key-env <ENV> instead."));
+			console.error(chalk.red("Setup rejects raw --api-key values; pass the key through an environment variable."));
 			process.exit(1);
+		} else if (arg === "--skip-verify") {
+			flags.skipVerify = true;
+		} else if (arg === "--remove") {
+			flags.remove = true;
 		} else if (arg === "--api-key-env") {
 			flags.apiKeyEnv = args[++i];
 		} else if (arg === "--model" || arg === "--models") {
@@ -289,6 +297,9 @@ export async function runSetupCommand(cmd: SetupCommandArgs): Promise<void> {
 		case "stt":
 			await handleSttSetup(cmd.flags);
 			break;
+		case "typesafe":
+			await handleTypeSafeSetup(cmd.flags);
+			break;
 		case "credentials":
 			await handleCredentialsSetup(cmd.flags);
 			break;
@@ -802,3 +813,44 @@ ${chalk.bold("Examples:")}
   ${APP_NAME} setup credentials --yes      Import without an interactive prompt
 `);
 }
+
+/**
+ * `skc setup typesafe` — enable the hosted System One model for typed decisions.
+ *
+ * The key is read from `TYPESAFE_API_KEY`, never from a flag: this repo already refuses
+ * raw `--api-key` values because they land in shell history and in the process list of
+ * every user on the machine. Same rule applies here.
+ *
+ * Verified against the live API before storing. The decision service fails open, so an
+ * unverified bad key would be swallowed forever — the user would believe TypeSafe was
+ * active while every decision quietly came from their own model.
+ */
+export async function handleTypeSafeSetup(flags: SetupCommandArgs["flags"]): Promise<void> {
+	const { formatTypeSafeKeyResult, removeTypeSafeKey, setTypeSafeKey } = await import("../setup/decision-provider");
+
+	if (flags.remove) {
+		await removeTypeSafeKey();
+		process.stdout.write("TypeSafe key removed. Typed decisions fall back to your logged-in model.\n");
+		return;
+	}
+
+	const apiKey = process.env.TYPESAFE_API_KEY?.trim();
+	if (!apiKey) {
+		process.stdout.write(
+			`Usage: TYPESAFE_API_KEY=<key> ${APP_NAME} setup typesafe [--skip-verify]\n` +
+				`       ${APP_NAME} setup typesafe --remove\n\n` +
+				"The key is taken from the environment on purpose: a flag would leak it into\n" +
+				"shell history and the process list.\n",
+		);
+		process.exitCode = 1;
+		return;
+	}
+
+	const result = await setTypeSafeKey({ apiKey, skipVerify: flags.skipVerify });
+	if (flags.json) {
+		process.stdout.write(`${JSON.stringify(result)}\n`);
+	} else {
+		process.stdout.write(`${formatTypeSafeKeyResult(result)}\n`);
+	}
+	if (result.error) process.exitCode = 1;
+}

package/src/commands/auth-gateway.ts

@@ -1,5 +1,6 @@
 /**
- * `skc auth-gateway` — run a forward proxy that injects auth from the broker.
+ * `skc auth-gateway` — run a forward proxy that injects auth from the broker,
+ * or from the local credential store when no broker is configured.
  */
 import { Args, Command, Flags, renderCommandHelp } from "@sayknow-cli/utils/cli";
 import {
@@ -11,7 +12,8 @@ import {
 import { initTheme } from "../modes/theme/theme";
 
 export default class AuthGateway extends Command {
-	static description = "Run an auth-gateway forward proxy backed by the configured broker";
+	static description =
+		"Run an auth-gateway forward proxy backed by the configured broker, or local credentials when no broker is set";
 
 	static args = {
 		action: Args.string({
@@ -32,13 +34,13 @@ export default class AuthGateway extends Command {
 	};
 
 	static examples = [
-		"# Boot the gateway against the configured broker\n  skc auth-gateway serve",
+		"# Boot the gateway (broker when configured, else local credentials)\n  skc auth-gateway serve",
 		"# Boot on a non-default port\n  skc auth-gateway serve --bind=127.0.0.1:4000",
 		"# Print the gateway bearer token (creates one on first run)\n  skc auth-gateway token",
 		"# Rotate the gateway bearer token\n  skc auth-gateway token --regenerate",
 		"# Run on loopback without any bearer (anyone on this host can call)\n  skc auth-gateway serve --no-auth",
-		"# Show local gateway + broker config status\n  skc auth-gateway status",
-		"# Probe each broker credential to see which one is producing 401s\n  skc auth-gateway check",
+		"# Show gateway token + credential source status\n  skc auth-gateway status",
+		"# Probe each credential to see which one is producing 401s\n  skc auth-gateway check",
 		"# Same, machine-readable for scripts\n  skc auth-gateway check --json",
 	];
 

package/src/commands/setup.ts

@@ -15,6 +15,7 @@ const COMPONENTS: SetupComponent[] = [
 	"provider",
 	"python",
 	"stt",
+	"typesafe",
 	"ui-skills",
 ];
 
@@ -60,6 +61,8 @@ export default class Setup extends Command {
 		"models-path": Flags.string({ description: "Override models config path" }),
 		yes: Flags.boolean({ char: "y", description: "Import discovered credentials without an interactive prompt" }),
 		"dry-run": Flags.boolean({ description: "Preview discovered credentials without importing" }),
+		"skip-verify": Flags.boolean({ description: "Store the TypeSafe key without checking it against the live API" }),
+		remove: Flags.boolean({ description: "Remove the stored TypeSafe key" }),
 	};
 
 	async run(): Promise<void> {
@@ -94,6 +97,8 @@ export default class Setup extends Command {
 				profileDir: flags["profile-dir"],
 				yes: flags.yes,
 				dryRun: flags["dry-run"],
+				skipVerify: flags["skip-verify"],
+				remove: flags.remove,
 			},
 		};
 		await initTheme();

package/src/config/settings-schema.ts

@@ -1999,6 +1999,18 @@ export const SETTINGS_SCHEMA = {
 	"hindsight.mentalModelRefreshIntervalMs": { type: "number", default: 5 * 60 * 1000 },
 	"hindsight.mentalModelMaxRenderChars": { type: "number", default: 16_000 },
 
+	// Typed decisions
+	"decisions.enabled": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "context",
+			label: "Typed decisions",
+			description:
+				"Let a cheap model answer typed questions the deterministic rules cannot. Currently routes workflow skills when the keyword table finds nothing — which is every non-English phrasing. Costs one small model call on those prompts; every failure falls back to today's behaviour.",
+		},
+	},
+
 	// TTSR
 	"ttsr.enabled": {
 		type: "boolean",

package/src/decisions/index.ts

@@ -0,0 +1,84 @@
+/**
+ * Typed decisions — entry point.
+ *
+ * Call sites ask for a judgment and get a typed answer or nothing. They never learn
+ * which backend answered, and they never have to handle a transport error: every
+ * failure path resolves `null`. That is deliberate — a decision service is an
+ * *enhancement* to code that already works, so an outage must degrade behaviour to
+ * the previous default rather than break the turn.
+ */
+import { logger } from "@sayknow-cli/utils";
+import { createLlmDecisionBackend, type LlmBackendDeps } from "./llm-backend";
+import type { DecisionBackend, DecisionRequest, DecisionResult } from "./types";
+import { createTypeSafeDecisionBackend } from "./typesafe-backend";
+
+export { createLlmDecisionBackend } from "./llm-backend";
+export * from "./types";
+export { createTypeSafeDecisionBackend, TYPESAFE_PROVIDER } from "./typesafe-backend";
+
+/** Hard ceiling. A decision that takes longer than this is worthless to the caller. */
+const DEFAULT_TIMEOUT_MS = 8_000;
+
+export interface DecisionServiceOptions extends LlmBackendDeps {
+	/** Off by default; callers opt in per feature. */
+	enabled?: boolean;
+	timeoutMs?: number;
+	/** Injection point for tests and for the self-hosted/hosted backends. */
+	backends?: DecisionBackend[];
+}
+
+export interface DecisionService {
+	readonly enabled: boolean;
+	/** Resolves null when disabled, unavailable, timed out, or the model misbehaved. */
+	decide(request: DecisionRequest): Promise<DecisionResult | null>;
+}
+
+export function createDecisionService(options: DecisionServiceOptions): DecisionService {
+	const enabled = options.enabled ?? false;
+	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	/**
+	 * Order matters and is not configurable by accident.
+	 *
+	 * TypeSafe first *when a key exists*: it is the only backend that returns calibrated
+	 * probabilities, and it resolves `null` immediately when no key is stored, so users
+	 * who never added one pay nothing for it being in the list.
+	 *
+	 * The user's logged-in model is the fallback and the default experience: no extra
+	 * vendor, no extra key, works offline of TypeSafe entirely.
+	 */
+	const backends = options.backends ?? [createTypeSafeDecisionBackend(options), createLlmDecisionBackend(options)];
+
+	return {
+		enabled,
+		async decide(request: DecisionRequest): Promise<DecisionResult | null> {
+			if (!enabled || backends.length === 0) return null;
+			for (const backend of backends) {
+				const controller = new AbortController();
+				const abortOnCallerSignal = () => controller.abort();
+				request.signal?.addEventListener("abort", abortOnCallerSignal, { once: true });
+				let timer: ReturnType<typeof setTimeout> | undefined;
+				try {
+					// The deadline must be a race, not just an abort. A provider that ignores
+					// its signal would otherwise hang the caller's turn forever — and the
+					// caller here is the user's prompt, so "forever" means a frozen session.
+					const deadline = new Promise<null>(resolve => {
+						timer = setTimeout(() => {
+							controller.abort();
+							resolve(null);
+						}, timeoutMs);
+					});
+					const result = await Promise.race([backend.decide({ ...request, signal: controller.signal }), deadline]);
+					if (result) return result;
+				} catch (error) {
+					// Fail open: log and try the next backend, then give up quietly.
+					logger.debug("decisions: backend failed", { backend: backend.name, error: String(error) });
+				} finally {
+					if (timer) clearTimeout(timer);
+					controller.abort();
+					request.signal?.removeEventListener("abort", abortOnCallerSignal);
+				}
+			}
+			return null;
+		},
+	};
+}