Multiplayer agent harness for work.
Make the base model key a deployment secret, and document Slack sign-in (#21)
Joshua Francea2e752f25ac2
diff --git a/.codex/skills/deploy-qm/SKILL.md b/.codex/skills/deploy-qm/SKILL.mdindex e4d73d6a7..3a470a227 100644--- a/.codex/skills/deploy-qm/SKILL.md+++ b/.codex/skills/deploy-qm/SKILL.md@@ -11,6 +11,13 @@ as the authoritative workflow. Read only the selected provider reference. Readtransport and one of its steps needs the operator's DNS. Read`references/slack.md` only when Slack is requested.+A deployment needs a base model key and a way for people to sign in. Collect+both in the same pass. The base model provider is a deployment choice recorded+as `modelProvider`, not a setting to leave for the Admin page. Sign-in is either+the built-in `auth` broker, which needs an email transport, or an external OIDC+provider such as Slack, which needs no email at all — read `references/email.md`+only once the operator has chosen the broker.+Use the installed `@yc-software/qm` dependency through `npm exec qm -- <command>`. Donot require or clone the QM source repository. Complete every acceptance checkand return the handoff required by `deployment.md`.diff --git a/cli/src/backends/aws.ts b/cli/src/backends/aws.tsindex 5d34424c3..b7f87d0c4 100644--- a/cli/src/backends/aws.ts+++ b/cli/src/backends/aws.ts@@ -215,6 +215,7 @@ export function serviceEnvironment(config: QmConfig, service: ServiceName): Recoservice === "core"? {...(config.model ? { PI_MODEL: config.model } : {}),+ ...(config.modelProvider ? { MODEL_PROVIDER: config.modelProvider } : {}),...virtualServiceEnv(config.services, config.env),}: {};diff --git a/cli/src/backends/docker.ts b/cli/src/backends/docker.tsindex b0a8e3afa..232f078ab 100644--- a/cli/src/backends/docker.ts+++ b/cli/src/backends/docker.ts@@ -313,6 +313,7 @@ function serviceEnv(ctx: DockerCtx, service: ServiceName): Record<string, stringout.RUN_STORE = "postgres";out.DATABASE_URL = ctx.databaseUrl;if (config.model) out.PI_MODEL = config.model;+ if (config.modelProvider) out.MODEL_PROVIDER = config.modelProvider;const layerSubs = existingLayerSubdirs(ctx);if (layerSubs.length) out.DEPLOYMENT_LAYER = "/layer";Object.assign(out, ctx.sandboxEnv);diff --git a/cli/src/backends/doctor.ts b/cli/src/backends/doctor.tsindex d72197335..cd6db1395 100644--- a/cli/src/backends/doctor.ts+++ b/cli/src/backends/doctor.ts@@ -1,6 +1,6 @@import { existsSync, readFileSync } from "node:fs";import { join, resolve } from "node:path";-import { validatePortalTrust, type QmConfig } from "../config.ts";+import { MODEL_PROVIDER_KEYS, validatePortalTrust, type ModelProvider, type QmConfig } from "../config.ts";import { CliError, errMessage, step, warn } from "../log.ts";import { capture, deploymentSecretValue, flyBin, isInvalidSecret, readEnvFile, which } from "../util.ts";import { computedSecrets } from "../secrets.ts";@@ -189,6 +189,57 @@ export async function doctorCommon();}if (config.services.includes("auth")) await authBrokerCheck(config, secrets, opts.requiredSecretValues === true);+ await baseModelCheck(config, secrets);+}++/**+ * Prove the base-model key is accepted before the deployment is called finished. The Admin+ * page validates a key on entry; a deployment that ships its key from `.env` gets no such+ * feedback, and an unusable key would otherwise surface as a failed first chat message.+ */+async function baseModelCheck(config: QmConfig, secrets: Map<string, string>): Promise<void> {+ const provider = config.modelProvider;+ if (!provider) {+ step("base model: no modelProvider set — an administrator supplies the key from the Admin page");+ return;+ }+ const name = MODEL_PROVIDER_KEYS[provider];+ const key = deploymentSecretValue(name, secrets.get(name));+ if (!key) {+ warn(`${name} is not available locally — skipping the live ${provider} check`);+ return;+ }+ await modelProviderCheck(provider, key);+ step(`base model provider ${provider}: ${name} accepted`);+}++const MODEL_PROVIDER_PROBES: Readonly<+ Record<ModelProvider, { url: string; headers: (key: string) => Record<string, string> }>+> = {+ anthropic: {+ url: "https://api.anthropic.com/v1/models?limit=1",+ headers: (key) => ({ "x-api-key": key, "anthropic-version": "2023-06-01" }),+ },+ openai: { url: "https://api.openai.com/v1/models", headers: (key) => ({ authorization: `Bearer ${key}` }) },+ openrouter: { url: "https://openrouter.ai/api/v1/key", headers: (key) => ({ authorization: `Bearer ${key}` }) },+};++async function modelProviderCheck(provider: ModelProvider, apiKey: string): Promise<void> {+ const probe = MODEL_PROVIDER_PROBES[provider];+ let res: Response;+ try {+ res = await fetch(probe.url, { headers: probe.headers(apiKey), signal: AbortSignal.timeout(10_000) });+ } catch (e) {+ throw new CliError(+ `could not reach the ${provider} API: ${errMessage(e)} — check network access (and any proxy) and retry`,+ );+ }+ if (res.status === 401 || res.status === 403) {+ throw new CliError(+ `${provider} rejected ${MODEL_PROVIDER_KEYS[provider]} — the deployment would start but could not serve a single agent turn`,+ );+ }+ if (!res.ok) throw new CliError(`the ${provider} API returned HTTP ${res.status}; retry when it recovers`);}async function resendCheck(apiKey: string): Promise<void> {diff --git a/cli/src/backends/fly.ts b/cli/src/backends/fly.tsindex 97ee5e4c3..429b318cf 100644--- a/cli/src/backends/fly.ts+++ b/cli/src/backends/fly.ts@@ -180,7 +180,13 @@ function deriveToml(ctx: FlyCtx, service: ServiceName): string {const base = readFileSync(existsSync(nested) ? nested : join(ctx.templateRoot, `${service}.toml`), "utf8");const sandboxEnv = service === "core" ? sandboxCoreEnv(ctx.config).env : {};const virtualEnv = service === "core" ? virtualServiceEnv(ctx.config.services, ctx.config.env) : {};- const modelEnv: Record<string, string> = service === "core" && ctx.config.model ? { PI_MODEL: ctx.config.model } : {};+ const modelEnv: Record<string, string> =+ service === "core"+ ? {+ ...(ctx.config.model ? { PI_MODEL: ctx.config.model } : {}),+ ...(ctx.config.modelProvider ? { MODEL_PROVIDER: ctx.config.modelProvider } : {}),+ }+ : {};const configuredEnv = { ...ctx.config.env[service] };if (service === "core") {delete configuredEnv.FLY_ORG;diff --git a/cli/src/cli.ts b/cli/src/cli.tsindex 675457fa8..27543f8ca 100644--- a/cli/src/cli.ts+++ b/cli/src/cli.ts@@ -1,7 +1,15 @@import { spawnSync } from "node:child_process";import { dirname, join, resolve } from "node:path";import { CliError, bold, dim, errMessage, note, red } from "./log.ts";-import { findConfigPath, loadConfigAt, loadConfigInDir, readConfigOrgId } from "./config.ts";+import {+ findConfigPath,+ isModelProvider,+ loadConfigAt,+ loadConfigInDir,+ readConfigOrgId,+ MODEL_PROVIDERS,+ type ModelProvider,+} from "./config.ts";import { HOSTING_PROVIDER_IDS, hostingProviderChoices, isTarget, type Target } from "./providers.ts";import { type LogOpts } from "./services.ts";import { runInit } from "./commands/init.ts";@@ -70,6 +78,14 @@ function targetFlag(flags: Flags): Target | undefined {return target;}+function modelProviderFlag(flags: Flags): ModelProvider | undefined {+ const provider = strFlag(flags, "model-provider");+ if (provider !== undefined && !isModelProvider(provider)) {+ throw new CliError(`--model-provider must be ${MODEL_PROVIDERS.join(" | ")}`, { clause: "cli.invocation" });+ }+ return provider;+}+function version(): string {return cliVersion();}@@ -84,7 +100,10 @@ ${bold("USAGE")}${bold("DEPLOY (operator)")} ${dim("— runs in the deployment directory")}init [path] [--org <id>] [--target ${HOSTING_PROVIDER_IDS.join("|")}]- scaffold a deployment directory+ [--model-provider ${MODEL_PROVIDERS.join("|")}]+ scaffold a deployment directory (the base model+ provider defaults to anthropic; its API key is a+ required secret)setup [path] interactive wizard: scaffold if needed, then walk themissing secrets with per-provider instructionsup build images and bring the deployment up@@ -216,12 +235,18 @@ async function dispatch(argv: string[]): Promise<void> {}case "init": {- rejectUnknownFlags(flags, ["org", "target"]);+ rejectUnknownFlags(flags, ["org", "target", "model-provider"]);rejectExtraPositionals(positionals, 1);const target = targetFlag(flags);+ const modelProvider = modelProviderFlag(flags);const org = strFlag(flags, "org");const dir = positionals[0] !== undefined ? resolve(positionals[0]) : resolve(process.cwd());- runInit({ dir, ...(org ? { org } : {}), ...(target ? { target } : {}) });+ runInit({+ dir,+ ...(org ? { org } : {}),+ ...(target ? { target } : {}),+ ...(modelProvider ? { modelProvider } : {}),+ });return;}diff --git a/cli/src/commands/init.ts b/cli/src/commands/init.tsindex fee93d19a..3b704a435 100644--- a/cli/src/commands/init.ts+++ b/cli/src/commands/init.ts@@ -2,7 +2,15 @@ import { randomBytes } from "node:crypto";import { spawnSync } from "node:child_process";import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";import { dirname, isAbsolute, join, relative, resolve } from "node:path";-import { CONFIG_FILENAME, configPathInDir, loadConfigAt, validOrgId, type Target, type QmConfig } from "../config.ts";+import {+ CONFIG_FILENAME,+ configPathInDir,+ loadConfigAt,+ validOrgId,+ type ModelProvider,+ type Target,+ type QmConfig,+} from "../config.ts";import { die, note, ok, warn } from "../log.ts";import { cliPackageName, cliVersion } from "../manifest.ts";import { computedSecrets, renderEnvExample } from "../secrets.ts";@@ -246,7 +254,7 @@ function scaffoldDeploymentSkill(dir: string): void {}}-export function runInit(opts: { org?: string; target?: Target; dir?: string }): void {+export function runInit(opts: { org?: string; target?: Target; modelProvider?: ModelProvider; dir?: string }): void {const orgId = opts.org ?? "default-org";if (!validOrgId(orgId)) die(`--org must be a lowercase DNS label (a-z, 0-9, and hyphens between)`);const dir = opts.dir ?? process.cwd();@@ -261,9 +269,10 @@ export function runInit(opts: { org?: string; target?: Target; dir?: string }):}const target: Target = opts.target ?? "docker";+ const modelProvider: ModelProvider = opts.modelProvider ?? "anthropic";const provider = hostingProvider(target);- writeFileSync(configPath, provider.scaffold.renderConfig(orgId));- ok(`wrote ${CONFIG_FILENAME} (orgId=${orgId}, target=${target})`);+ writeFileSync(configPath, provider.scaffold.renderConfig(orgId, modelProvider));+ ok(`wrote ${CONFIG_FILENAME} (orgId=${orgId}, target=${target}, modelProvider=${modelProvider})`);const config = loadConfigAt(configPath).config;writePackage(dir, preparedPackage);diff --git a/cli/src/config.ts b/cli/src/config.tsindex cd3602e91..e04c443bf 100644--- a/cli/src/config.ts+++ b/cli/src/config.ts@@ -104,6 +104,25 @@ export function awsWorkloadArchitecture(config: QmConfig, workload: string): "arreturn service.architecture ?? "arm64";}+/**+ * The vendor supplying the deployment's base model. Selecting one makes that vendor's+ * API key a required deployment secret, so `qm setup` collects it and `qm up` refuses+ * to deploy a stack that cannot run a single agent turn. Leaving it unset preserves the+ * older flow, where an administrator supplies the key from the Admin page after deploy.+ */+export const MODEL_PROVIDERS = ["anthropic", "openai", "openrouter"] as const;+export type ModelProvider = (typeof MODEL_PROVIDERS)[number];++/** The API key each provider's base model is billed against. */+export const MODEL_PROVIDER_KEYS: Readonly<Record<ModelProvider, string>> = {+ anthropic: "ANTHROPIC_API_KEY",+ openai: "OPENAI_API_KEY",+ openrouter: "OPENROUTER_API_KEY",+};++export const isModelProvider = (value: unknown): value is ModelProvider =>+ typeof value === "string" && (MODEL_PROVIDERS as readonly string[]).includes(value);+export interface QmConfig {contract: typeof CONTRACT_VERSION;orgId: string;@@ -111,6 +130,7 @@ export interface QmConfig {apiUrl?: string;target: Target;model?: string;+ modelProvider?: ModelProvider;basePort?: number;services: DeclaredServiceName[];plugins: PluginEntry[];@@ -625,6 +645,14 @@ function validate(raw: unknown, path: string): QmConfig {if (typeof apiUrl === "string") out.apiUrl = apiUrl.replace(/\/$/, "");if (sandbox) out.sandbox = sandbox;if (typeof o["model"] === "string") out.model = o["model"];+ if (o["modelProvider"] !== undefined) {+ if (!isModelProvider(o["modelProvider"])) {+ throw new CliError(+ `${path}: "modelProvider" must be one of ${MODEL_PROVIDERS.join(", ")} — it selects which provider key the deployment requires; omit it to supply the base model key from the Admin page instead`,+ );+ }+ out.modelProvider = o["modelProvider"];+ }if (o["basePort"] !== undefined) {const bp = o["basePort"];if (typeof bp !== "number" || !Number.isInteger(bp) || bp <= 0) {diff --git a/cli/src/provider-scaffold.ts b/cli/src/provider-scaffold.tsindex e6fa35d58..1c718eb44 100644--- a/cli/src/provider-scaffold.ts+++ b/cli/src/provider-scaffold.ts@@ -1,6 +1,6 @@import { createHash } from "node:crypto";import { existsSync, readFileSync } from "node:fs";-import type { QmConfig } from "./config.ts";+import type { ModelProvider, QmConfig } from "./config.ts";import type { Target } from "./providers.ts";import { declaredVariables, terraformVars } from "./terraform.ts";@@ -10,7 +10,7 @@ interface ScaffoldFile {}export interface ProviderScaffold {- renderConfig(orgId: string): string;+ renderConfig(orgId: string, modelProvider: ModelProvider): string;ignores: readonly string[];agentsAppendix: string;files(config: QmConfig): ScaffoldFile[];@@ -21,6 +21,7 @@ export interface ProviderScaffold {interface ConfigValues {target: Target;+ modelProvider: ModelProvider;publicUrl: string;providerFields: string;services: string[];@@ -43,6 +44,18 @@ function renderConfig(orgId: string, values: ConfigValues): string {// Where to deploy: "docker" runs local containers, "fly" deploys Fly apps,// and "aws" runs the control plane on ECS and agent computers on Lambda MicroVMs."target": ${JSON.stringify(values.target)},++ // The vendor supplying the base model: "anthropic", "openai", or "openrouter"+ // (one key, many models). Naming one makes that vendor's API key a required+ // deployment secret: \`qm setup\` collects it, \`qm doctor\` proves the provider+ // accepts it, and \`qm up\` refuses a stack that cannot serve an agent turn.+ // Delete this line to leave the base model unset and have an administrator add+ // the key from the Admin page after deploy instead.+ "modelProvider": ${JSON.stringify(values.modelProvider)},++ // Optional base model id, passed to the harness (e.g. "claude-opus-4-6").+ // Omit it to use the harness default for the provider above.+ // "model": "",${values.providerFields}// First-party services to run. The full set: "core" (the agent runtime and API,// always required), "slack" (the Slack surface, runs inside the core process),@@ -59,9 +72,9 @@ ${values.providerFields}// Extra directories of SKILL.md files, mounted into the agent."skills": [],- // Non-secret env overrides, per service. HARNESS "pi" runs real agent turns;- // after deployment, an administrator adds its model provider key in Admin.- // "mock" runs the whole stack with fake turns and no model calls.+ // Non-secret env overrides, per service. HARNESS "pi" runs real agent turns+ // against the base model selected by "modelProvider" above. "mock" runs the+ // whole stack with fake turns and no model calls."env": ${values.env}${values.secretEnv}${values.sandbox}}`;@@ -131,9 +144,10 @@ cannot deregister or delete task definitions.const noFiles = (): ScaffoldFile[] => [];export const dockerScaffold: ProviderScaffold = {- renderConfig: (orgId) =>+ renderConfig: (orgId, modelProvider) =>renderConfig(orgId, {target: "docker",+ modelProvider,publicUrl: "http://localhost:8082",providerFields: "",services: ["core", "web-ui"],@@ -154,9 +168,10 @@ export const dockerScaffold: ProviderScaffold = {};export const flyScaffold: ProviderScaffold = {- renderConfig: (orgId) =>+ renderConfig: (orgId, modelProvider) =>renderConfig(orgId, {target: "fly",+ modelProvider,publicUrl: `https://${orgId}-portal.fly.dev`,providerFields: `// Globally unique prefix for every Fly app in this deployment.@@ -187,7 +202,7 @@ export const flyScaffold: ProviderScaffold = {};export const awsScaffold: ProviderScaffold = {- renderConfig: (orgId) => {+ renderConfig: (orgId, modelProvider) => {const cluster = clusterName(orgId);const services = Object.fromEntries([@@ -208,6 +223,7 @@ export const awsScaffold: ProviderScaffold = {);return renderConfig(orgId, {target: "aws",+ modelProvider,publicUrl: `https://${orgId}.example.com`,providerFields: `// AWS coordinates. Replace the account id and public URL before applying infra/.diff --git a/cli/src/secrets.ts b/cli/src/secrets.tsindex 84fed6ee4..c2631a8cb 100644--- a/cli/src/secrets.ts+++ b/cli/src/secrets.ts@@ -1,5 +1,5 @@import { isVirtualService, type DeclaredServiceName } from "./services.ts";-import type { QmConfig } from "./config.ts";+import type { ModelProvider, QmConfig } from "./config.ts";type SecretCondition =| { kind: "env-equals"; service: DeclaredServiceName; name: string; value: string }@@ -10,7 +10,8 @@ type SecretCondition =| { kind: "service-enabled"; service: DeclaredServiceName }| { kind: "service-absent"; service: DeclaredServiceName }| { kind: "all"; conditions: SecretCondition[] }- | { kind: "target"; target: QmConfig["target"] };+ | { kind: "target"; target: QmConfig["target"] }+ | { kind: "model-provider"; provider: ModelProvider };export interface SecretSpec {name: string;@@ -37,12 +38,34 @@ export const MINT_JWK ="node -e \"const {generateKeyPairSync}=require('node:crypto');process.stdout.write(JSON.stringify(generateKeyPairSync('ec',{namedCurve:'P-256'}).privateKey.export({format:'jwk'})))\"";export const FIRST_PARTY_SECRET_SPECS: readonly SecretSpec[] = [+ // The base-model key is required whenever the deployment names its provider, so that+ // `qm setup` collects it and `qm up` cannot produce a stack that fails its first agent+ // turn. Anthropic and OpenRouter keep an unconditional twin further down: omitting+ // `modelProvider` leaves the key an optional fallback an administrator supplies from the+ // Admin page, which is how deployments predating `modelProvider` behave. Those two stay+ // ahead of their twins — `computedSecrets` describes a secret from the first spec whose+ // condition matches, and the base-model wording is the accurate one once it applies.+ {+ name: "ANTHROPIC_API_KEY",+ service: "core",+ required: { when: { kind: "model-provider", provider: "anthropic" } },+ description: 'Anthropic API key for the deployment base model (modelProvider "anthropic").',+ },+ {+ name: "OPENROUTER_API_KEY",+ service: "core",+ required: { when: { kind: "model-provider", provider: "openrouter" } },+ description: 'OpenRouter API key for the deployment base model (modelProvider "openrouter").',+ },{name: "ANTHROPIC_API_KEY",service: "core",required: false,description: "Optional deployment fallback for Pi; admins can configure the base model key after deploy.",},+ // OPENAI_API_KEY keeps the Codex rule ahead of the base-model rule: it is the more+ // descriptive of the two, and `.env.example` documents a dormant secret from its first+ // spec. Whichever rule fires, `computedSecrets` collapses them to one required secret.{name: "OPENAI_API_KEY",service: "core",@@ -50,6 +73,12 @@ export const FIRST_PARTY_SECRET_SPECS: readonly SecretSpec[] = [description:"OpenAI API key used by the Codex harness (its CLI cannot do browser OAuth in a container); an optional deployment fallback for Pi otherwise.",},+ {+ name: "OPENAI_API_KEY",+ service: "core",+ required: { when: { kind: "model-provider", provider: "openai" } },+ description: 'OpenAI API key for the deployment base model (modelProvider "openai").',+ },{name: "OPENROUTER_API_KEY",service: "core",@@ -359,6 +388,7 @@ function conditionMatches(config: QmConfig, condition: SecretCondition): booleanif (condition.kind === "service-absent") return !config.services.includes(condition.service);if (condition.kind === "all") return condition.conditions.every((nested) => conditionMatches(config, nested));if (condition.kind === "target") return config.target === condition.target;+ if (condition.kind === "model-provider") return config.modelProvider === condition.provider;if (condition.kind === "env-all-absent") {return condition.names.every((name) => !config.env[condition.service]?.[name]?.trim());}@@ -535,6 +565,7 @@ function conditionClause(condition: SecretCondition): string {if (condition.kind === "env-present") return `env.${condition.service}.${condition.name} is set`;if (condition.kind === "env-in")return `env.${condition.service}.${condition.name} is one of ${condition.values.map((value) => JSON.stringify(value)).join(", ")}`;+ if (condition.kind === "model-provider") return `modelProvider is ${JSON.stringify(condition.provider)}`;return `env.${condition.service}.${condition.name} is ${JSON.stringify(condition.value)}`;}@@ -565,13 +596,20 @@ export function renderEnvExample(config: QmConfig): string {const inactive = FIRST_PARTY_SECRET_SPECS.filter((spec, i, all) => !activeNames.has(spec.name) && all.findIndex((s) => s.name === spec.name) === i,);- for (const spec of inactive) {- const clauses = [+ const clauseFor = (spec: SecretSpec): string =>+ [...(config.services.includes(spec.service) ? [] : [`the ${spec.service} service is enabled`]),...(typeof spec.required === "boolean" ? [] : [conditionClause(spec.required.when)]),- ];+ ].join(" and ");+ for (const spec of inactive) {+ // One secret can answer to several independent rules — an OpenAI base model or the+ // Codex harness, say. List them as alternatives so the catalog does not imply the+ // first rule is the only way the secret becomes required.+ const rules = FIRST_PARTY_SECRET_SPECS.filter((other) => other.name === spec.name);+ const clauses = [...new Set(rules.map(clauseFor).filter(Boolean))];+ const optionalEvenThen = rules.every((rule) => rule.required === false);lines.push(`# ${spec.description} (${spec.service})`);- lines.push(`# Needed when ${clauses.join(" and ")}${spec.required === false ? " (optional even then)" : ""}.`);+ lines.push(`# Needed when ${clauses.join(" or ")}${optionalEvenThen ? " (optional even then)" : ""}.`);if (spec.generate) lines.push(`# Generate with: ${generate(spec.generate)}`);lines.push(spec.managedBy === "terraform" ? `# ${spec.name}= # populated by Terraform` : `# ${spec.name}=`);lines.push("");diff --git a/cli/templates/deployment/SKILL.md b/cli/templates/deployment/SKILL.mdindex 31401698f..055743be7 100644--- a/cli/templates/deployment/SKILL.md+++ b/cli/templates/deployment/SKILL.md@@ -11,6 +11,13 @@ before collecting secrets, because sign-in needs an email transport and one ofits steps needs the operator's DNS. Read `references/slack.md` only when Slackis requested.+A deployment needs a base model key and a way for people to sign in. Collect+both in the same pass. The base model provider is a deployment choice recorded+as `modelProvider`, not a setting to leave for the Admin page. Sign-in is either+the built-in `auth` broker, which needs an email transport, or an external OIDC+provider such as Slack, which needs no email at all — read `references/email.md`+only once the operator has chosen the broker.+Use the repository's installed `@yc-software/qm` dependency through`npm exec qm -- <command>`. Do not require or clone the QM source repository.Do not stop at infrastructure health: complete the acceptance checks and returndiff --git a/cli/templates/deployment/deployment.md b/cli/templates/deployment/deployment.mdindex 65a763dec..175040af6 100644--- a/cli/templates/deployment/deployment.md+++ b/cli/templates/deployment/deployment.md@@ -19,9 +19,19 @@ it in place. If the repository has not been initialized, collect:machine, is for a quick local test drive only, and is outside thisworkflow; never present it as the recommended path for a real deployment;- the first administrator's verified work email;+- how people sign in: the built-in `auth` broker, which emails a one-time link,+ or an external OIDC provider. Ask whether the company runs on Slack before+ assuming the broker — Slack sign-in needs no email transport, no sending+ domain, and no DNS, and domain verification is the step most likely to stall+ a deploy. Recommend Slack sign-in to a Slack workspace and the broker+ otherwise;- model provider: Anthropic, OpenAI, or OpenRouter (one key that routes to- many models). The key is entered later on the Admin page, so "decide later"- is acceptable;+ many models). This is a deployment choice, not a post-deploy one: it becomes+ `modelProvider` in `qm.config.jsonc`, which makes that provider's API key a+ required secret. Collect the key in the same pass as the other credentials —+ a deployment that cannot answer one message is not finished. An operator who+ genuinely wants to defer omits `modelProvider` and adds the key from the+ Admin page later, but do not offer that as the default;- model;- region and provider account or organization;- whether the provider hostname is acceptable;@@ -51,10 +61,14 @@ and the derived slug, install an exact CLI version, and initialize its root:```bashnpm exec --yes --package=@yc-software/qm@<exact-version> -- \- qm init . --org <slug> --target <fly-or-aws>+ qm init . --org <slug> --target <fly-or-aws> --model-provider <provider>npm install```+`--model-provider` takes `anthropic`, `openai`, or `openrouter` and defaults to+`anthropic`. It writes `modelProvider` into the scaffolded config, which is what+promotes that provider's key from an optional fallback to a required secret.+For an already-initialized clone, install reproducibly. Use `npm ci` when`package-lock.json` exists; otherwise use `npm install` to create it:@@ -73,15 +87,21 @@ git check-ignore --quiet .envNever print, paste into chat, or commit `.env`. Never initialize over anexisting deployment config.-## 3. Configure the administrator and sign-in+## 3. Configure the administrator, sign-in, and the base modelSet the exact lowercased administrator email in `.env` as`ADMIN_GRANTS=<email>:org_admin`.-Sign-in is the built-in `auth` broker, which emails a one-time link. There is no-identity provider to register: the CLI generates the broker's signing key and-the portal's client credentials and derives every `OIDC_*` value from-`publicUrl`. Setting any of them by hand is refused.+Follow the sign-in route chosen in step 1. Only the `auth` broker needs an email+transport; skip to "Slack sign-in" below when the operator picked Slack, and+skip `references/email.md` entirely with it.++### The built-in broker++The `auth` broker emails a one-time link. There is no identity provider to+register: the CLI generates the broker's signing key and the portal's client+credentials and derives every `OIDC_*` value from `publicUrl`. Setting any of+them by hand is refused.What the operator supplies is a way to send those emails. Do not ask them topick a transport by name; ask what they already use for email. An existing@@ -94,7 +114,19 @@ Resend and controls DNS for a sending domain should pick `resend`. SetResend path needs DNS control you will not have, so raise it with the operatorearly. Configure services, model, and the final public origin in the same pass.-To use an external work-email OIDC provider instead, drop `"auth"` from+### Slack sign-in++A workspace that already runs on Slack can sign in with it and skip email+altogether. Drop `"auth"` from `services` and follow+`.codex/skills/deploy-qm/references/slack.md`, which covers the SSO app, the+`env.portal` endpoints, the workspace trust boundary, and the client+credentials. The bot app in that same reference is a separate decision — Slack+sign-in does not require the agent in the workspace, and the agent does not+require Slack sign-in.++### Another OIDC provider++To use a different work-email OIDC provider, drop `"auth"` from`services`, register `<publicUrl>/auth/callback` with the provider, and put itsendpoints and the email gate in `env.portal`. For Google Workspace:@@ -111,6 +143,24 @@ endpoints and the email gate in `env.portal`. For Google Workspace:}```+### The base model++Whichever sign-in route the deployment takes, the base model needs a key in the+same pass. `modelProvider` decides which one `qm setup` asks for —+`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `OPENROUTER_API_KEY` — and the wizard+prints where to mint it. The operator owns the billing relationship, so they+create the key; you only place it. It is a required secret, so `qm doctor` calls+the provider to prove the key is accepted and `qm up` refuses a deployment that+has none. Treat a rejected key exactly like a rejected sign-in credential: stop+and get a working one rather than deploying a stack that greets the+administrator and then fails their first message.++An operator may still prefer to hold the key centrally and rotate it from the+Admin page. That is a deliberate choice, not the default: drop `modelProvider`+from `qm.config.jsonc`, note in the handoff that the deployment has no base model+yet, and finish by walking them through Model provider on the Admin page. Never+leave a deployment modelless without saying so.+Read exactly one provider reference now and follow its provider-specificpreflight and setup order:@@ -127,10 +177,17 @@ npm exec qm -- conformancenpm exec qm -- outputs --json```-Open `adminOnboardingUrl` from the JSON output. In Model provider, enter and-validate the selected provider key. The write-only Admin surface stores it in-durable encrypted storage; do not put the key in `.env`, config, chat, or-terminal output.+Open `adminOnboardingUrl` from the JSON output and confirm Model provider+already reports the deployment's base model. It does when `modelProvider` is+set: the key travelled with the rest of the deployment secrets, so there is+nothing to paste here. Enter and validate a key on that page only when the+operator chose to defer, or when they are replacing the deployment key with one+they would rather rotate from Admin — the write-only surface stores it in+durable encrypted storage and takes precedence over the deployment key.++Never paste any provider key into chat or terminal output. `.env` is the one+place a deployment key belongs, and `qm secrets push` moves it without printing+it.Open `webUiUrl`, sign in as the seeded administrator, send a message, andreceive a real model response. Ask the agent to create a fresh UUID in@@ -148,31 +205,37 @@ Open `adminConnectorsUrl` from `outputs --json`. For each chosen connector:Verify configured connectors appear and unconfigured connectors remain hidden.-## 6. Add Slack+## 6. Add the Slack bot-Skip this when Slack was deferred. Otherwise read-`.codex/skills/deploy-qm/references/slack.md`, then run:+This is the agent in the workspace, not sign-in; a deployment using Slack+sign-in already created its SSO app in step 3. Skip this when the bot was+deferred. Otherwise read `.codex/skills/deploy-qm/references/slack.md`, then run:```bashnpm exec qm -- slack rendernpm exec qm -- outputs```-Create the app from the exact manifest URL. Enter its bot and app tokens in the-Admin Slack card, invite it to a test channel, mention it, and receive a reply.+Create the app from the exact bot manifest URL. Enter its bot and app tokens in+the Admin Slack card, invite it to a test channel, mention it, and receive a+reply.## 7. Return the handoffReturn:- the web, Admin onboarding, Admin connectors, and user connections URLs;-- Slack app and test-channel links when enabled;+- how people sign in, and the Slack SSO app link when that is the route;+- Slack bot app and test-channel links when enabled;- provider, account or organization, and region;+- the base model provider and where its key lives — the deployment `.env` or the+ Admin page — so the operator knows what to rotate and where;- pass/fail for health, sign-in, web chat, agent-computer proof, connectorvisibility, user OAuth, Slack reply, live check, conformance, and anidempotent deployment rerun;- `npm exec qm -- status`, logs, rollback, and teardown commands;-- recurring cost or manual work still owned by the operator.+- recurring cost or manual work still owned by the operator, including model+ usage billed directly by the provider.Do not claim completion with a missing test or placeholder. If blocked, leavethe repository resumable and name the exact next human action without exposingdiff --git a/cli/templates/deployment/references/slack.md b/cli/templates/deployment/references/slack.mdindex 36e8590f3..f218c6602 100644--- a/cli/templates/deployment/references/slack.md+++ b/cli/templates/deployment/references/slack.md@@ -1,4 +1,17 @@-# Slack app+# Slack apps++Slack does two independent jobs for a deployment, and each is its own Slack app.+Create only what the operator asked for.++| App | Job | Enabled by |+| -------- | ------------------------------------------------------------ | ------------------------------ |+| `qm` | the agent in channels, DMs, and group messages | `"slack"` in `services` |+| `qm SSO` | signs people in to the web surfaces with their Slack account | Slack OIDC instead of `"auth"` |++A workspace can have one without the other: the bot alongside email sign-in, or+Slack sign-in with no bot.++## The bot appQM uses one private Socket Mode app per deployment and workspace.@@ -14,4 +27,59 @@ Bot dashboard: https://api.slack.com/apps/<bot-app-id>Test channel: https://app.slack.com/client/<team-id>/<channel-id>```-Keep token values out of Git, chat, and terminal output.+## The SSO app++Slack sign-in replaces the built-in `auth` broker rather than supplementing it.+It needs no email transport, no verified sender, and no DNS work, which makes it+the shorter path for a workspace that already runs on Slack. Do not read+`references/email.md` for this route.++Drop `"auth"` from `services` and declare Slack's endpoints in `env.portal`:++```json+{+ "OIDC_AUTH_ENDPOINT": "https://slack.com/openid/connect/authorize",+ "OIDC_TOKEN_ENDPOINT": "https://slack.com/api/openid.connect.token",+ "OIDC_USERINFO_ENDPOINT": "https://slack.com/api/openid.connect.userInfo",+ "OIDC_ISSUER": "https://slack.com",+ "OIDC_JWKS_URI": "https://slack.com/openid/connect/keys",+ "PORTAL_EXPECTED_TEAM_ID": "<workspace-team-id>"+}+```++The portal already defaults to exactly these endpoints, so sign-in would work+without them — write them anyway. `qm slack render` and `qm outputs` decide a+deployment uses Slack sign-in by finding `slack.com` in `env.portal`, and+silently skip the SSO manifest and its links when the values are left implicit.++Every deployment needs one tenant trust boundary or the portal refuses to start:+`PORTAL_EXPECTED_TEAM_ID` (the workspace id, and Slack-only),+`OIDC_ALLOWED_EMAIL_DOMAIN`, or `OIDC_ALLOWED_EMAILS`. Copy the workspace id from+the Slack About dialog. `PORTAL_EXPECTED_TEAM_ID` is refused while `"auth"` is+enabled — the two sign-in paths are mutually exclusive, so switch fully.++`qm outputs` requires the `slack` service even when only the SSO app is wanted.+Keep `"slack"` in `services` and leave its bot tokens unset if the operator does+not want the agent in their workspace.++Then render and read the links:++```bash+npm exec qm -- slack render+npm exec qm -- outputs+```++`outputs` prints `qm SSO app` (the manifest creation URL), `Slack sign-in`+(`<publicUrl>/auth/login`), and `Slack SSO callback`+(`<publicUrl>/auth/callback`). Create the app from the exact creation URL — that+manifest already carries the callback, so there is no redirect URL to register by+hand. From Basic Information, put the client secret in `.env` as+`OIDC_CLIENT_SECRET` and the client id in either `env.portal.OIDC_CLIENT_ID` or+`.env`, then run `npm exec qm -- secrets push`.++Prove it before calling sign-in done: open the `Slack sign-in` URL, complete+Slack's consent screen, and land in the Web UI as the administrator. A portal+answering on `/healthz` has proved nothing about sign-in.++Keep token values, client secrets, and workspace ids out of Git, chat, and+terminal output.diff --git a/cli/test/init.test.ts b/cli/test/init.test.tsindex a013099b2..7d2cbded4 100644--- a/cli/test/init.test.ts+++ b/cli/test/init.test.ts@@ -58,17 +58,25 @@ test("init scaffolds a loadable config, generated local secrets, and a valid sanassert.equal(config.target, "docker");assert.equal(config.publicUrl, "http://localhost:8082");assert.equal(config.env.core?.HARNESS, "pi");+ assert.equal(config.modelProvider, "anthropic", "init names a base model provider by default");assert.deepEqual(config.sandbox, { app: "acme-sandboxes" });const env = readFileSync(join(dir, ".env.example"), "utf8");assert.equal(env, renderEnvExample(config), ".env.example is exactly renderEnvExample output");- for (const line of ["CORE_SIGNING_SECRET=", "SKILL_SIGNING_SECRET="]) {+ // The scaffold names anthropic as the base model provider, so its key is required+ // rather than deferred to Admin; the providers not selected stay optional.+ for (const line of ["CORE_SIGNING_SECRET=", "SKILL_SIGNING_SECRET=", "ANTHROPIC_API_KEY="]) {assert.ok(env.split("\n").includes(line), `.env.example should require ${line}`);}- for (const line of ["# ANTHROPIC_API_KEY= # optional", "# OPENROUTER_API_KEY= # optional"]) {+ for (const line of ["# OPENROUTER_API_KEY= # optional"]) {assert.ok(env.split("\n").includes(line), `.env.example should offer ${line}`);}- for (const line of ['# Needed when env.core.HARNESS is "codex".', "# OPENAI_API_KEY="]) {+ // OPENAI_API_KEY answers to two independent rules; the catalog lists both so neither+ // route to requiring it is hidden behind the other.+ for (const line of [+ '# Needed when env.core.HARNESS is "codex" or modelProvider is "openai".',+ "# OPENAI_API_KEY=",+ ]) {assert.ok(env.split("\n").includes(line), `.env.example should defer ${line}`);}assert.ok(env.includes("# Generate with: openssl rand -hex 32"), "mintable secrets carry their generation command");@@ -155,11 +163,11 @@ test("init --target fly scaffolds the full hosted topology and both Slack apps","AUTH_EMAIL_FROM=","RESEND_API_KEY=","PORTAL_SESSION_SECRET=",+ "ANTHROPIC_API_KEY=",]) {assert.ok(env.split("\n").includes(line), `.env.example should require ${line} for the fly scaffold`);}for (const line of [- "# ANTHROPIC_API_KEY= # optional","# OPENROUTER_API_KEY= # optional","# SLACK_APP_TOKEN= # optional","# SLACK_BOT_TOKEN= # optional",@@ -239,11 +247,11 @@ test("init --target aws scaffolds the full hosted topology, Terraform, and the o"AUTH_ALLOWED_EMAILS=","AUTH_EMAIL_FROM=","RESEND_API_KEY=",+ "ANTHROPIC_API_KEY=",]) {assert.ok(env.includes(name), `hosted AWS scaffold requires ${name}`);}for (const name of [- "# ANTHROPIC_API_KEY= # optional","# OPENROUTER_API_KEY= # optional","# SLACK_BOT_TOKEN= # optional","# SLACK_APP_TOKEN= # optional",diff --git a/cli/test/secrets.test.ts b/cli/test/secrets.test.tsindex f8b0228fa..1427cf2d9 100644--- a/cli/test/secrets.test.ts+++ b/cli/test/secrets.test.ts@@ -192,6 +192,42 @@ test("the sprites token is a catalog secret when the sandbox backend is sprites");});+test("naming a base model provider makes that provider's key a required deployment secret", () => {+ for (const [provider, key] of [+ ["anthropic", "ANTHROPIC_API_KEY"],+ ["openai", "OPENAI_API_KEY"],+ ["openrouter", "OPENROUTER_API_KEY"],+ ] as const) {+ const config = makeConfig({ modelProvider: provider });+ assert.equal(secretByName(config, key).required, true, `${provider} requires ${key}`);+ assert.match(+ renderEnvExample(config),+ new RegExp(`^${key}=$`, "m"),+ `${key} is uncommented in .env.example so setup collects it`,+ );+ }+});++test("the providers a deployment did not select stay optional", () => {+ const anthropic = makeConfig({ modelProvider: "anthropic" });+ assert.equal(secretByName(anthropic, "OPENROUTER_API_KEY").required, false);+ // OPENAI_API_KEY keeps its own Codex rule, so it is absent rather than optional here.+ assert.ok(!computedSecrets(anthropic).some((secret) => secret.name === "OPENAI_API_KEY"));+});++test("an OpenAI base model and the Codex harness agree on one required key", () => {+ const both = makeConfig({ modelProvider: "openai", env: { core: { HARNESS: "codex" } } });+ const matches = computedSecrets(both).filter((secret) => secret.name === "OPENAI_API_KEY");+ assert.equal(matches.length, 1, "overlapping rules collapse to a single secret");+ assert.equal(matches[0]!.required, true);+});++test("omitting modelProvider preserves the pre-existing deferred-to-Admin behavior", () => {+ const deferred = makeConfig();+ assert.equal(secretByName(deferred, "ANTHROPIC_API_KEY").required, false);+ assert.equal(secretByName(deferred, "OPENROUTER_API_KEY").required, false);+});+test("conditional secret values use the runtime's trimmed enum semantics", () => {const pi = makeConfig({ env: { core: { HARNESS: " pi " } } });assert.equal(secretByName(pi, "ANTHROPIC_API_KEY").required, false);diff --git a/src/deployment/secret-schema.ts b/src/deployment/secret-schema.tsindex af8151a2e..a8d5b1ccd 100644--- a/src/deployment/secret-schema.ts+++ b/src/deployment/secret-schema.ts@@ -12,7 +12,10 @@ export interface RuntimeSecretSpec {| "aws-deploy-gate"| "google-oauth"| "dropbox-oauth"- | "linear-oauth";+ | "linear-oauth"+ | "model-anthropic"+ | "model-openai"+ | "model-openrouter";}export const CORE_SECRET_SPECS: readonly RuntimeSecretSpec[] = [@@ -22,6 +25,12 @@ export const CORE_SECRET_SPECS: readonly RuntimeSecretSpec[] = [{ name: "PORTAL_IDENTITY_SECRET", requiredWhen: "production" },{ name: "SKILL_SIGNING_SECRET", requiredWhen: "production" },{ name: "OPENAI_API_KEY", requiredWhen: "codex" },+ // MODEL_PROVIDER names the vendor supplying the base model. The deployment CLI sets it+ // from `modelProvider` in qm.config.jsonc, so a stack that declares a provider refuses+ // to boot without that provider's key rather than accepting turns it cannot serve.+ { name: "ANTHROPIC_API_KEY", requiredWhen: "model-anthropic" },+ { name: "OPENAI_API_KEY", requiredWhen: "model-openai" },+ { name: "OPENROUTER_API_KEY", requiredWhen: "model-openrouter" },{ name: "DATABASE_URL", requiredWhen: "postgres" },{ name: "SPRITES_TOKEN", requiredWhen: "sprites" },{ name: "FLY_API_TOKEN", requiredWhen: "fly-sandbox" },@@ -44,11 +53,20 @@ export function validateCoreSecretEnv(env: NodeJS.ProcessEnv): string[] {if (spec.requiredWhen === "aws-deploy-gate") return Boolean(env.AWS_DEPLOY_APPS_DOMAIN);if (spec.requiredWhen === "google-oauth") return Boolean(env.GOOGLE_OAUTH_CLIENT_ID);if (spec.requiredWhen === "dropbox-oauth") return Boolean(env.DROPBOX_OAUTH_CLIENT_ID);+ if (spec.requiredWhen === "model-anthropic") return env.MODEL_PROVIDER?.trim() === "anthropic";+ if (spec.requiredWhen === "model-openai") return env.MODEL_PROVIDER?.trim() === "openai";+ if (spec.requiredWhen === "model-openrouter") return env.MODEL_PROVIDER?.trim() === "openrouter";return Boolean(env.LINEAR_OAUTH_CLIENT_ID);};- return CORE_SECRET_SPECS.filter((spec) => enabled(spec) && isInvalidSecret(spec.name, env[spec.name])).map(- (spec) => spec.name,- );+ // OPENAI_API_KEY carries two specs (the Codex harness and an OpenAI base model), so+ // deduplicate before reporting — a name should be named once however many rules want it.+ return [+ ...new Set(+ CORE_SECRET_SPECS.filter((spec) => enabled(spec) && isInvalidSecret(spec.name, env[spec.name])).map(+ (spec) => spec.name,+ ),+ ),+ ];}function isInvalidSecret(name: string, value: string | undefined): boolean {diff --git a/test/secret-schema-drift.test.ts b/test/secret-schema-drift.test.tsindex 060f2fd07..272709474 100644--- a/test/secret-schema-drift.test.ts+++ b/test/secret-schema-drift.test.ts@@ -39,6 +39,29 @@ test("AWS deployment app domains reject a missing or placeholder gate secret", ();});+test("a declared base model provider is enforced at boot, not just at deploy time", () => {+ for (const [provider, key] of [+ ["anthropic", "ANTHROPIC_API_KEY"],+ ["openai", "OPENAI_API_KEY"],+ ["openrouter", "OPENROUTER_API_KEY"],+ ] as const) {+ assert.deepEqual(validateCoreSecretEnv({ MODEL_PROVIDER: provider } as NodeJS.ProcessEnv), [key]);+ assert.deepEqual(validateCoreSecretEnv({ MODEL_PROVIDER: provider, [key]: "real-key" } as NodeJS.ProcessEnv), []);+ assert.deepEqual(validateCoreSecretEnv({ MODEL_PROVIDER: provider, [key]: "replace-me" } as NodeJS.ProcessEnv), [+ key,+ ]);+ }+ assert.deepEqual(validateCoreSecretEnv({} as NodeJS.ProcessEnv), [], "no provider declared, nothing required");+});++test("an OpenAI base model on the Codex harness reports its one missing key once", () => {+ assert.deepEqual(+ validateCoreSecretEnv({ MODEL_PROVIDER: "openai", HARNESS: "codex" } as NodeJS.ProcessEnv),+ ["OPENAI_API_KEY"],+ "two rules wanting the same key must not name it twice",+ );+});+test("production rejects weak encryption key material for managed credentials", () => {const strong = "x".repeat(32);const env = {