@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.4

package/packages/fleet/src/managed-settings.ts

@@ -0,0 +1,278 @@
+/**
+ * Render and install the managed baseline hook artifacts (adl items 10/17,
+ * `docs/architecture/cli-design.md` §2/§3) from the committed templates in
+ * `packages/agent-settings/managed/` onto the real, per-platform system
+ * paths -- the "fleet installation" that directory's own README used to say
+ * was a separate, later item. It is this reconcile pass.
+ *
+ *   - Claude: `packages/agent-settings/managed/claude-managed-settings.json`
+ *     is installed verbatim EXCEPT for one addition: a top-level `env`
+ *     object carrying `ADL_AGENT_ID_AGENT` set to this device's
+ *     `default_agent` (packages/fleet/manifest.json), read from the
+ *     machine's default-agent file (default-agent-file.ts) at reconcile
+ *     time. `allowManagedHooksOnly` and the `PreToolUse` hooks are untouched
+ *     from the template. CONFIRMED from code.claude.com/docs/en/settings-reference
+ *     (fetched 2026-09-27): `env` -- "Set environment variables for every
+ *     session and its subprocesses" (Scope: Any file); `allowManagedHooksOnly`
+ *     -- "Run only the hooks your organization deploys" (Scope: Managed).
+ *     code.claude.com/docs/en/managed-settings confirms both the install
+ *     paths below and that managed settings "appl[y] above every other
+ *     level, so no user, project, local, or --settings value overrides
+ *     them" (with a short list of security-sensitive exceptions that does
+ *     not include `env` or `allowManagedHooksOnly`), and lists
+ *     `allowManagedHooksOnly` under "Locks": "Applies the strictest value
+ *     any source sets; a looser value applies only from the highest-ranked
+ *     source."
+ *       mac:   /Library/Application Support/ClaudeCode/managed-settings.json
+ *       linux: /etc/claude-code/managed-settings.json
+ *
+ *   - Codex gets TWO files, because the env var and the hook lockdown are on
+ *     two different footings, per
+ *     https://developers.openai.com/codex/enterprise/managed-configuration
+ *     and https://developers.openai.com/codex/config-reference (fetched
+ *     2026-09-27; both currently redirect to learn.chatgpt.com) and the
+ *     upstream source (github.com/openai/codex,
+ *     codex-rs/config/src/config_toml.rs):
+ *
+ *       1. `requirements.toml` (installed verbatim from
+ *          `packages/agent-settings/managed/codex-requirements.toml`) is the
+ *          CONFIRMED hard-constraint layer: "Admins can set top-level
+ *          allow_managed_hooks_only = true in requirements.toml ... This
+ *          setting is only supported in requirements.toml; putting it in
+ *          config.toml does not enable managed-hooks-only mode." Installed
+ *          at `/etc/codex/requirements.toml` on both platforms (the
+ *          managed-configuration reference gives one Unix path, not a
+ *          macOS/Linux split).
+ *
+ *       2. `managed_config.toml` (rendered here, not committed as a static
+ *          template -- its only content is per-device) carries
+ *          `[shell_environment_policy] set = { ADL_AGENT_ID_AGENT = "..." }`.
+ *          `shell_environment_policy` IS a genuine field of the same
+ *          `ConfigToml` struct managed_config.toml is documented to supply
+ *          startup defaults from ("Managed defaults set the configuration a
+ *          supported local client starts with. At startup, they override
+ *          the user's local config.toml ... Users can still change those
+ *          settings during the current run, and the defaults apply again the
+ *          next time the client starts.") -- but the docs' own worked
+ *          example lists only approval_policy, sandbox_mode,
+ *          sandbox_workspace_write.network_access, and [otel], and states
+ *          unsupported values are rejected ("the local runtime rejects
+ *          disallowed values") without giving a full allow-list. UNCONFIRMED
+ *          from official docs: whether shell_environment_policy specifically
+ *          is honoured (applied at all, even as an overridable default) from
+ *          managed_config.toml, the same way allow_managed_hooks_only is
+ *          confirmed for requirements.toml. This is the "if it can only be
+ *          set in user config, say so and use the managed layer that
+ *          exists" case (2026-09-27 decision 4c) taken to its honest
+ *          conclusion: even the managed layer's uptake of this specific key
+ *          is unverified, not just its overridability. Deployed anyway
+ *          because it is harmless if ignored or overridden (SOFT-default,
+ *          best-effort, never depended on) -- the actual, CONFIRMED
+ *          enforcement is `allow_managed_hooks_only` above plus the
+ *          fail-closed managed baseline hook
+ *          (`adl.session-required-for-writes`): a missing or overridden
+ *          `ADL_AGENT_ID_AGENT` denies Azure DevOps writes for that session,
+ *          exactly like a plain `codex` with no `adl run` today -- it never
+ *          grants anything by being absent. Installed at
+ *          `/etc/codex/managed_config.toml`.
+ *
+ * Ownership model, same as global-agents.ts: whole-file, always forced, no
+ * delimited region -- these are exclusively fleet-managed files under
+ * `/Library/Application Support` and `/etc`, never hand-edited. A missing
+ * target is created; a target whose bytes already match the render is left
+ * untouched; anything else (missing, stale, hand-edited) is atomically
+ * replaced. `root` is an injectable filesystem root so tests write to a
+ * disposable directory instead of the real system paths.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { dirname, isAbsolute, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { DEFAULT_AGENT_PATTERN } from './default-agent-file.ts'
+
+export type FleetPlatform = 'mac' | 'linux'
+
+const MANAGED_DIR = fileURLToPath(new URL('../../agent-settings/managed', import.meta.url))
+export const CLAUDE_TEMPLATE_PATH = join(MANAGED_DIR, 'claude-managed-settings.json')
+export const CODEX_REQUIREMENTS_TEMPLATE_PATH = join(MANAGED_DIR, 'codex-requirements.toml')
+
+export function claudeManagedSettingsPath(platform: FleetPlatform, root = ''): string {
+  switch (platform) {
+    case 'mac':
+      return join(root, '/Library/Application Support/ClaudeCode/managed-settings.json')
+    case 'linux':
+      return join(root, '/etc/claude-code/managed-settings.json')
+    default: {
+      const exhaustive: never = platform
+      throw new Error(`unsupported platform: ${exhaustive}`)
+    }
+  }
+}
+
+/** Same Unix path on both platforms -- Codex's managed-configuration reference gives one location, not a mac/linux split. */
+export function codexRequirementsPath(root = ''): string {
+  return join(root, '/etc/codex/requirements.toml')
+}
+
+export function codexManagedConfigPath(root = ''): string {
+  return join(root, '/etc/codex/managed_config.toml')
+}
+
+function assertValidAgent(agent: string): void {
+  if (!DEFAULT_AGENT_PATTERN.test(agent)) {
+    throw new Error(`default_agent must match ${DEFAULT_AGENT_PATTERN}: ${agent}`)
+  }
+}
+
+export function renderClaudeManagedSettings(agent: string): string {
+  assertValidAgent(agent)
+  const template = JSON.parse(readFileSync(CLAUDE_TEMPLATE_PATH, 'utf8')) as Record<string, unknown>
+  const rendered = { ...template, env: { ADL_AGENT_ID_AGENT: agent } }
+  return `${JSON.stringify(rendered, null, 2)}\n`
+}
+
+export function readCodexRequirementsTemplate(): string {
+  return readFileSync(CODEX_REQUIREMENTS_TEMPLATE_PATH, 'utf8')
+}
+
+export function renderCodexManagedConfig(agent: string): string {
+  assertValidAgent(agent)
+  return `# Generated by fleet reconcile (packages/fleet/src/managed-settings.ts) from
+# packages/fleet/manifest.json's device default_agent. Do not edit by hand --
+# edit the manifest and let the next reconcile re-render this file.
+#
+# adl items 10/17 (docs/architecture/cli-design.md §2/§3, "Machine default agent --
+# the one source"). This is Codex's SOFT-default managed layer, deployed
+# best-effort: OpenAI's managed-configuration reference documents
+# managed_config.toml as supplying startup defaults a user's own config.toml
+# can still change, and its own worked example lists only approval_policy,
+# sandbox_mode, sandbox_workspace_write.network_access, and [otel] --
+# shell_environment_policy is not shown there, so whether Codex actually
+# applies it from managed_config.toml at all is UNCONFIRMED from official
+# docs, not just overridable. Verified 2026-09-27:
+# https://developers.openai.com/codex/enterprise/managed-configuration,
+# https://developers.openai.com/codex/config-reference. Deployed anyway
+# because it is harmless if ignored or overridden: unsetting
+# ADL_AGENT_ID_AGENT here grants nothing -- the managed baseline hook
+# (adl.session-required-for-writes, CONFIRMED enforced from
+# allow_managed_hooks_only in requirements.toml in this same directory) then
+# denies Azure DevOps writes for that session, fail-closed, exactly like a
+# plain \`codex\` with no \`adl run\` today. That hook is the real backstop,
+# not this file.
+#
+# Sources (verified 2026-09-27):
+#   https://developers.openai.com/codex/enterprise/managed-configuration
+#   https://developers.openai.com/codex/config-reference
+
+[shell_environment_policy]
+set = { ADL_AGENT_ID_AGENT = "${agent}" }
+`
+}
+
+export interface FileWriteResult {
+  readonly path: string
+  readonly changed: boolean
+}
+
+function atomicWriteWhole(path: string, content: string, dryRun: boolean): FileWriteResult {
+  const current = existsSync(path) ? readFileSync(path, 'utf8') : null
+  const changed = current !== content
+  if (!dryRun && changed) {
+    mkdirSync(dirname(path), { recursive: true })
+    const temp = `${path}.new`
+    writeFileSync(temp, content)
+    chmodSync(temp, 0o644)
+    renameSync(temp, path)
+  }
+  return { path, changed }
+}
+
+export interface ManagedSettingsResult {
+  readonly claude: FileWriteResult
+  readonly codexRequirements: FileWriteResult
+  readonly codexManagedConfig: FileWriteResult
+}
+
+export interface ReconcileManagedSettingsOptions {
+  readonly root?: string
+  readonly dryRun?: boolean
+}
+
+export function reconcileManagedSettings(
+  agent: string,
+  platform: FleetPlatform,
+  options: ReconcileManagedSettingsOptions = {},
+): ManagedSettingsResult {
+  assertValidAgent(agent)
+  const root = options.root ?? ''
+  const dryRun = options.dryRun === true
+  return {
+    claude: atomicWriteWhole(claudeManagedSettingsPath(platform, root), renderClaudeManagedSettings(agent), dryRun),
+    codexRequirements: atomicWriteWhole(codexRequirementsPath(root), readCodexRequirementsTemplate(), dryRun),
+    codexManagedConfig: atomicWriteWhole(codexManagedConfigPath(root), renderCodexManagedConfig(agent), dryRun),
+  }
+}
+
+interface ParsedArguments {
+  readonly agent: string | null
+  readonly platform: FleetPlatform | null
+  readonly mode: 'plan' | 'apply'
+  readonly root: string
+}
+
+function parseArguments(argv: readonly string[]): ParsedArguments {
+  let agent: string | null = null
+  let platform: string | null = null
+  let mode: string | null = null
+  let root = ''
+  for (let index = 0; index < argv.length; index += 1) {
+    const flag = argv[index]
+    if (flag === '--agent') {
+      agent = argv[index + 1] ?? null
+      index += 1
+    } else if (flag === '--platform') {
+      platform = argv[index + 1] ?? null
+      index += 1
+    } else if (flag === '--mode') {
+      mode = argv[index + 1] ?? null
+      index += 1
+    } else if (flag === '--root') {
+      root = argv[index + 1] ?? ''
+      index += 1
+    } else {
+      throw new Error(`unknown argument: ${flag}`)
+    }
+  }
+  // Preserve validation order (agent, platform, mode, root) --
+  // bin-wrapper-module-paths.test.ts pins the first error a no-args invocation surfaces.
+  if (agent === null) throw new Error('--agent is required')
+  if (platform !== 'mac' && platform !== 'linux') throw new Error('--platform must be mac or linux')
+  if (mode !== 'plan' && mode !== 'apply') throw new Error('--mode must be plan or apply')
+  if (root !== '' && !isAbsolute(root)) throw new Error(`--root must be absolute: ${root}`)
+  return { agent, platform, mode, root }
+}
+
+function report(label: string, mode: 'plan' | 'apply', result: FileWriteResult): void {
+  if (!result.changed) console.log(`managed-settings: already installed: ${result.path}`)
+  else if (mode === 'plan') console.log(`managed-settings: would install ${label}: ${result.path}`)
+  else console.log(`managed-settings: installed ${label}: ${result.path}`)
+}
+
+function main(argv: readonly string[]): void {
+  const args = parseArguments(argv)
+  // parseArguments guarantees agent/platform are non-null on this path (see its own branching).
+  const agent = args.agent as string
+  const platform = args.platform as FleetPlatform
+  const result = reconcileManagedSettings(agent, platform, { root: args.root, dryRun: args.mode === 'plan' })
+  report('Claude managed-settings.json', args.mode, result.claude)
+  report('Codex requirements.toml', args.mode, result.codexRequirements)
+  report('Codex managed_config.toml', args.mode, result.codexManagedConfig)
+}
+
+if (import.meta.main) {
+  try {
+    main(process.argv.slice(2))
+  } catch (cause) {
+    console.error(`managed-settings: ${cause instanceof Error ? cause.message : String(cause)}`)
+    process.exit(1)
+  }
+}