agentloom 0.1.11 → 0.1.13

package/README.md

@@ -12,6 +12,8 @@ npx agentloom init
 
 That's all you need. Agentloom picks up your existing provider configs, migrates them into a unified `.agents/` directory, and syncs everything back out to all your tools. From here on, manage your agents, commands, rules, skills, and MCP servers in one place and run `agentloom sync` whenever you make changes.
 
+`agentloom init` is the provider-to-canonical bootstrap step. After that, `agentloom sync` is one-way: it reads from `.agents/` and writes provider-native outputs. If you intentionally want to pull provider state back into canonical `.agents/`, rerun `agentloom init`.
+
 ## Install
 
 ```bash
@@ -200,13 +202,24 @@ claude:
   model: sonnet
 codex:
   model: gpt-5-codex
-  reasoningEffort: medium
-  webSearch: true
+  model_reasoning_effort: medium
+  web_search: true
 ---
 
 You are a strict reviewer...
 ```
 
+For Codex, provider-native config keys are passed through to the generated
+`.codex/agents/<role>.toml` as a thin layer. Prefer Codex's native snake_case
+keys such as `approval_policy`, `approvals_reviewer`, or `web_search`. Existing
+camelCase aliases like `reasoningEffort` are still normalized for
+backward-compatibility.
+
+Current `codex-cli 0.121.0` exposes spawn-time controls such as `fork_context` and
+`fork_turns` only on the `spawn_agent` tool path, not in static role/config
+files, so Codex itself will warn or ignore them if you place them under
+`codex:` in canonical frontmatter today.
+
 ## Command schema
 
 Canonical commands are markdown files. Frontmatter is optional. When present,

package/dist/commands/init.js

@@ -10,5 +10,6 @@ export async function runInitCommand(argv, cwd) {
         cwd,
         target: "all",
         skipSync: Boolean(argv["no-sync"]),
+        migrateProviderState: true,
     });
 }

package/dist/commands/sync.d.ts

@@ -6,4 +6,5 @@ export declare function runScopedSyncCommand(options: {
     cwd: string;
     target: EntityType | "all";
     skipSync?: boolean;
+    migrateProviderState?: boolean;
 }): Promise<void>;

package/dist/commands/sync.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { parseProvidersFlag } from "../core/argv.js";
 import { getSyncHelpText } from "../core/copy.js";
 import { formatMigrationSummary, initializeCanonicalLayout, migrateProviderStateToCanonical, MigrationConflictError, } from "../core/migration.js";
+import { hasInitializedCanonicalLayout, resolveScopeForSync, } from "../core/scope.js";
 import { getNonInteractiveMode, resolvePathsForCommand, } from "./entity-utils.js";
 import { formatSyncSummary, resolveProvidersForSync, syncFromCanonical, } from "../sync/index.js";
 export async function runSyncCommand(argv, cwd) {
@@ -21,29 +22,42 @@ export async function runScopedSyncCommand(options) {
     const nonInteractive = getNonInteractiveMode(options.argv);
     let cleanupDryRunPaths;
     try {
-        const paths = await resolvePathsForCommand(options.argv, options.cwd);
+        const shouldMigrateProviderState = Boolean(options.migrateProviderState);
+        const paths = shouldMigrateProviderState
+            ? await resolvePathsForCommand(options.argv, options.cwd)
+            : await resolveScopeForSync({
+                cwd: options.cwd,
+                global: Boolean(options.argv.global),
+                local: Boolean(options.argv.local),
+                interactive: !nonInteractive,
+            });
         const explicitProviders = parseProvidersFlag(options.argv.providers);
         const providers = await resolveProvidersForSync({
             paths,
             explicitProviders,
             nonInteractive,
         });
+        if (!shouldMigrateProviderState) {
+            assertInitializedCanonicalStateExists(paths);
+        }
         const dryRun = Boolean(options.argv["dry-run"]);
         const effectivePaths = dryRun
             ? createDryRunCanonicalPaths(paths)
             : { paths, cleanup: undefined };
         cleanupDryRunPaths = effectivePaths.cleanup;
         initializeCanonicalLayout(effectivePaths.paths, providers);
-        const migrationSummary = await migrateProviderStateToCanonical({
-            paths: effectivePaths.paths,
-            providers,
-            target: options.target,
-            yes: Boolean(options.argv.yes),
-            nonInteractive,
-            dryRun,
-            materializeCanonical: dryRun,
-        });
-        console.log(formatMigrationSummary(migrationSummary));
+        if (shouldMigrateProviderState) {
+            const migrationSummary = await migrateProviderStateToCanonical({
+                paths: effectivePaths.paths,
+                providers,
+                target: options.target,
+                yes: Boolean(options.argv.yes),
+                nonInteractive,
+                dryRun,
+                materializeCanonical: dryRun,
+            });
+            console.log(formatMigrationSummary(migrationSummary));
+        }
         if (options.skipSync) {
             return;
         }
@@ -69,6 +83,15 @@ export async function runScopedSyncCommand(options) {
         cleanupDryRunPaths?.();
     }
 }
+function assertInitializedCanonicalStateExists(paths) {
+    if (hasInitializedCanonicalLayout(paths)) {
+        return;
+    }
+    const initCommand = paths.scope === "global"
+        ? "agentloom init --global"
+        : "agentloom init --local";
+    throw new Error(`No initialized canonical .agents state found at ${paths.agentsRoot}.\nRun \`${initCommand}\` to bootstrap from provider configs first, or use \`agentloom add\` to create canonical content before syncing.`);
+}
 function createDryRunCanonicalPaths(paths) {
     const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "agentloom-dry-run-"));
     const tempAgentsRoot = path.join(tempRoot, ".agents");

package/dist/core/codex.d.ts

@@ -0,0 +1,3 @@
+export declare function normalizeCodexConfigForToml(providerConfig: Record<string, unknown>): Record<string, unknown>;
+export declare function cloneCodexProviderConfig(providerConfig: Record<string, unknown>): Record<string, unknown>;
+export declare function stripManagedCodexInstructionKeys(providerConfig: Record<string, unknown>): Record<string, unknown>;

package/dist/core/codex.js

@@ -0,0 +1,72 @@
+import { isObject } from "./fs.js";
+const MANAGED_INSTRUCTION_KEYS = new Set([
+    "developerInstructions",
+    "developer_instructions",
+    "modelInstructionsFile",
+    "model_instructions_file",
+]);
+const LEGACY_CODEX_ALIASES = {
+    approvalPolicy: "approval_policy",
+    reasoningEffort: "model_reasoning_effort",
+    reasoningSummary: "model_reasoning_summary",
+    sandboxMode: "sandbox_mode",
+    verbosity: "model_verbosity",
+    webSearch: "web_search",
+};
+export function normalizeCodexConfigForToml(providerConfig) {
+    const normalized = normalizeCodexValueForToml(providerConfig);
+    if (!isObject(normalized)) {
+        return {};
+    }
+    for (const key of MANAGED_INSTRUCTION_KEYS) {
+        delete normalized[key];
+    }
+    return normalized;
+}
+export function cloneCodexProviderConfig(providerConfig) {
+    const cloned = cloneCodexValue(providerConfig);
+    if (!isObject(cloned)) {
+        return {};
+    }
+    return cloned;
+}
+export function stripManagedCodexInstructionKeys(providerConfig) {
+    const cleaned = cloneCodexProviderConfig(providerConfig);
+    for (const key of MANAGED_INSTRUCTION_KEYS) {
+        delete cleaned[key];
+    }
+    return cleaned;
+}
+function normalizeCodexValueForToml(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => normalizeCodexValueForToml(entry));
+    }
+    if (!isObject(value)) {
+        return value;
+    }
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+        toSnakeCase(key),
+        normalizeCodexValueForToml(entry),
+    ]));
+}
+function cloneCodexValue(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => cloneCodexValue(entry));
+    }
+    if (!isObject(value)) {
+        return value;
+    }
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, cloneCodexValue(entry)]));
+}
+function toSnakeCase(key) {
+    if (Object.prototype.hasOwnProperty.call(LEGACY_CODEX_ALIASES, key)) {
+        return LEGACY_CODEX_ALIASES[key];
+    }
+    if (!/[A-Z]/.test(key)) {
+        return key;
+    }
+    return key
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .toLowerCase();
+}

package/dist/core/copy.js

@@ -9,11 +9,11 @@ Usage:
 
 Aggregate commands:
   add <source>               Import agents/commands/mcp/rules/skills from a source
-  init                       Bootstrap canonical files, migrate providers, then sync
+  init                       Bootstrap canonical files from provider configs, then sync
   find <query>               Search remote + local entities
   update [source]            Refresh lockfile-managed imports
   upgrade                    Install the latest CLI release
-  sync                       Migrate provider configs then generate provider outputs
+  sync                       Generate provider outputs from canonical .agents
   delete <source|name...>    Delete imported entities by source or name(s)
 
 Entity commands:
@@ -134,7 +134,9 @@ Behavior:
 `;
 }
 export function getSyncHelpText() {
-    return `Migrate provider configs into canonical .agents data, then generate provider-specific outputs.
+    return `Generate provider-specific outputs from canonical .agents data.
+
+Use \`agentloom init\` when you want to bootstrap or re-import provider configs into canonical state.
 
 Usage:
   agentloom sync [options]
@@ -148,7 +150,7 @@ Options:
 `;
 }
 export function getInitHelpText() {
-    return `Bootstrap canonical .agents files, migrate provider configs into canonical state, and sync providers.
+    return `Bootstrap canonical .agents files from existing provider configs, then sync providers.
 
 Usage:
   agentloom init [options]

package/dist/core/migration.js

@@ -6,6 +6,7 @@ import TOML from "@iarna/toml";
 import matter from "gray-matter";
 import YAML from "yaml";
 import { buildAgentMarkdown, parseAgentsDir } from "./agents.js";
+import { cloneCodexProviderConfig, stripManagedCodexInstructionKeys, } from "./codex.js";
 import { normalizeCommandArgumentsForCanonical, parseCommandsDir, } from "./commands.js";
 import { ensureDir, isObject, readJsonIfExists, slugify } from "./fs.js";
 import { readLockfile, writeLockfile } from "./lockfile.js";
@@ -394,33 +395,7 @@ function readCodexProviderAgents(paths) {
         const description = isObject(roleEntry) && typeof roleEntry.description === "string"
             ? roleEntry.description.trim()
             : roleName;
-        const providerConfig = {};
-        if (typeof roleToml.model === "string") {
-            providerConfig.model = roleToml.model;
-        }
-        if (typeof roleToml.model_reasoning_effort === "string") {
-            providerConfig.reasoningEffort = roleToml.model_reasoning_effort;
-        }
-        if (typeof roleToml.model_reasoning_summary === "string") {
-            providerConfig.reasoningSummary = roleToml.model_reasoning_summary;
-        }
-        if (typeof roleToml.model_verbosity === "string") {
-            providerConfig.verbosity = roleToml.model_verbosity;
-        }
-        if (typeof roleToml.approval_policy === "string") {
-            providerConfig.approvalPolicy = roleToml.approval_policy;
-        }
-        if (typeof roleToml.sandbox_mode === "string") {
-            providerConfig.sandboxMode = roleToml.sandbox_mode;
-        }
-        if (typeof roleToml.web_search === "boolean") {
-            providerConfig.webSearch = roleToml.web_search;
-        }
-        if (typeof providerConfig.webSearch !== "boolean" &&
-            isObject(roleToml.tools) &&
-            typeof roleToml.tools.web_search === "boolean") {
-            providerConfig.webSearch = roleToml.tools.web_search;
-        }
+        const providerConfig = stripManagedCodexInstructionKeys(cloneCodexProviderConfig(roleToml));
         records.push({
             provider: "codex",
             sourcePath: roleTomlPath,

package/dist/core/scope.d.ts

@@ -5,5 +5,7 @@ export interface ScopeResolutionOptions {
     local?: boolean;
     interactive?: boolean;
 }
+export declare function hasInitializedCanonicalLayout(paths: Pick<ScopePaths, "agentsRoot" | "agentsDir" | "commandsDir" | "rulesDir" | "skillsDir" | "mcpPath" | "lockPath" | "manifestPath">): boolean;
 export declare function buildScopePaths(cwd: string, scope: Scope, homeDir?: string): ScopePaths;
 export declare function resolveScope(options: ScopeResolutionOptions): Promise<ScopePaths>;
+export declare function resolveScopeForSync(options: ScopeResolutionOptions): Promise<ScopePaths>;

package/dist/core/scope.js

@@ -3,6 +3,24 @@ import os from "node:os";
 import path from "node:path";
 import { cancel, isCancel, select } from "@clack/prompts";
 import { getGlobalSettingsPath, readSettings } from "./settings.js";
+function directoryHasEntries(dirPath) {
+    return fs.existsSync(dirPath) && fs.readdirSync(dirPath).length > 0;
+}
+export function hasInitializedCanonicalLayout(paths) {
+    if (!fs.existsSync(paths.agentsRoot) ||
+        !fs.statSync(paths.agentsRoot).isDirectory()) {
+        return false;
+    }
+    if (fs.existsSync(paths.mcpPath) ||
+        fs.existsSync(paths.lockPath) ||
+        fs.existsSync(paths.manifestPath)) {
+        return true;
+    }
+    return (directoryHasEntries(paths.agentsDir) ||
+        directoryHasEntries(paths.commandsDir) ||
+        directoryHasEntries(paths.rulesDir) ||
+        directoryHasEntries(paths.skillsDir));
+}
 export function buildScopePaths(cwd, scope, homeDir = os.homedir()) {
     const workspaceRoot = cwd;
     const agentsRoot = scope === "local"
@@ -37,33 +55,76 @@ export async function resolveScope(options) {
     if (!interactive) {
         return buildScopePaths(cwd, hasLocalAgents ? "local" : "global");
     }
-    const globalSettings = readSettings(getGlobalSettingsPath());
-    const defaultScope = globalSettings.lastScope === "local" ? "local" : "global";
+    const defaultScope = getDefaultScope();
+    const selected = await promptForScopeSelection({
+        hasLocalAgents,
+        defaultScope,
+    });
+    return buildScopePaths(cwd, selected);
+}
+export async function resolveScopeForSync(options) {
+    const { cwd } = options;
+    if (options.global && options.local) {
+        throw new Error("Use either --global or --local, not both.");
+    }
+    if (options.global)
+        return buildScopePaths(cwd, "global");
+    if (options.local)
+        return buildScopePaths(cwd, "local");
+    const localPaths = buildScopePaths(cwd, "local");
+    const globalPaths = buildScopePaths(cwd, "global");
+    const hasLocalAgents = fs.existsSync(localPaths.agentsRoot);
+    const hasLocalCanonical = hasInitializedCanonicalLayout(localPaths);
+    const hasGlobalCanonical = hasInitializedCanonicalLayout(globalPaths);
+    const interactive = options.interactive ?? (process.stdin.isTTY && process.stdout.isTTY);
+    if (!interactive) {
+        return hasLocalAgents ? localPaths : globalPaths;
+    }
+    if (hasLocalAgents && hasGlobalCanonical) {
+        const selected = await promptForScopeSelection({
+            hasLocalAgents: true,
+            defaultScope: getDefaultScope(globalPaths.homeDir),
+        });
+        return buildScopePaths(cwd, selected, globalPaths.homeDir);
+    }
+    if (hasLocalCanonical)
+        return localPaths;
+    if (hasGlobalCanonical)
+        return globalPaths;
+    if (hasLocalAgents)
+        return localPaths;
+    throw new Error(`No initialized canonical .agents state found at ${localPaths.agentsRoot} or ${globalPaths.agentsRoot}.\nRun \`agentloom init --local\` or \`agentloom init --global\` to bootstrap from provider configs first, or use \`agentloom add\` to create canonical content before syncing.`);
+}
+function getDefaultScope(homeDir = os.homedir()) {
+    const globalSettings = readSettings(getGlobalSettingsPath(homeDir));
+    return globalSettings.lastScope === "local" ? "local" : "global";
+}
+async function promptForScopeSelection(options) {
     const selected = await select({
         message: "Choose scope for this command",
         options: [
             {
                 value: "local",
                 label: ".agents in this repository",
-                hint: hasLocalAgents
-                    ? defaultScope === "local"
+                hint: options.hasLocalAgents
+                    ? options.defaultScope === "local"
                         ? "default"
                         : undefined
-                    : defaultScope === "local"
+                    : options.defaultScope === "local"
                         ? "default (creates .agents)"
                         : "creates .agents",
             },
             {
                 value: "global",
                 label: "~/.agents shared config",
-                hint: defaultScope === "global" ? "default" : undefined,
+                hint: options.defaultScope === "global" ? "default" : undefined,
             },
         ],
-        initialValue: defaultScope,
+        initialValue: options.defaultScope,
     });
     if (isCancel(selected)) {
         cancel("Operation cancelled.");
         process.exit(1);
     }
-    return buildScopePaths(cwd, selected);
+    return selected;
 }

package/dist/sync/index.js

@@ -6,6 +6,7 @@ import YAML from "yaml";
 import { ALL_PROVIDERS } from "../types.js";
 import { getProviderConfig, isProviderEnabled, parseAgentsDir, } from "../core/agents.js";
 import { parseCommandsDir, renderCommandForProvider, } from "../core/commands.js";
+import { normalizeCodexConfigForToml } from "../core/codex.js";
 import { parseRulesDir, renderRuleForCursor, upsertManagedRuleBlocks, } from "../core/rules.js";
 import { ensureDir, isObject, readJsonIfExists, readTextIfExists, relativePosix, removeFileIfExists, slugify, toPosixPath, writeJsonAtomic, writeTextAtomic, } from "../core/fs.js";
 import { readManifest, writeManifest } from "../core/manifest.js";
@@ -869,33 +870,15 @@ function resolveCodexDeveloperInstructions(agentBody, providerConfig) {
         providerConfig.developerInstructions.trim() !== "") {
         return providerConfig.developerInstructions.trim();
     }
+    if (typeof providerConfig.developer_instructions === "string" &&
+        providerConfig.developer_instructions.trim() !== "") {
+        return providerConfig.developer_instructions.trim();
+    }
     return agentBody.trimStart().trimEnd();
 }
 function buildCodexRoleToml(developerInstructions, providerConfig) {
-    const roleToml = {
-        developer_instructions: developerInstructions,
-    };
-    if (typeof providerConfig.model === "string") {
-        roleToml.model = providerConfig.model;
-    }
-    if (typeof providerConfig.reasoningEffort === "string") {
-        roleToml.model_reasoning_effort = providerConfig.reasoningEffort;
-    }
-    if (typeof providerConfig.reasoningSummary === "string") {
-        roleToml.model_reasoning_summary = providerConfig.reasoningSummary;
-    }
-    if (typeof providerConfig.verbosity === "string") {
-        roleToml.model_verbosity = providerConfig.verbosity;
-    }
-    if (typeof providerConfig.approvalPolicy === "string") {
-        roleToml.approval_policy = providerConfig.approvalPolicy;
-    }
-    if (typeof providerConfig.sandboxMode === "string") {
-        roleToml.sandbox_mode = providerConfig.sandboxMode;
-    }
-    if (typeof providerConfig.webSearch === "boolean") {
-        roleToml.web_search = providerConfig.webSearch;
-    }
+    const roleToml = normalizeCodexConfigForToml(providerConfig);
+    roleToml.developer_instructions = developerInstructions;
     return roleToml;
 }
 function mapMcpServers(servers, allowedKeys) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentloom",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Unified agent and MCP sync CLI for multi-provider AI tooling",
   "type": "module",
   "bin": {