@ouro.bot/cli 0.1.0-alpha.393 → 0.1.0-alpha.394

package/changelog.json

@@ -1,6 +1,16 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.394",
+      "changes": [
+        "Added `ouro vault replace --agent <agent>` for existing pre-vault agents whose bundle has vault coordinates but no saved unlock secret and no local JSON credential export.",
+        "`ouro vault status --agent <agent>` now clearly reports when an existing agent has not configured a vault locator yet and points to `ouro vault create --agent <agent>` instead of implying an unlockable vault exists.",
+        "Locked-vault repair guidance now distinguishes saved-secret unlock, no-export replacement, and JSON-export recovery across provider checks, auth, provider refresh, vault config status, and vault unlock errors.",
+        "Interactive repair prompts now warn humans to run vault unlock only when they have the saved unlock secret, and docs explain how old auth-style agents continue by replacing the vault and re-entering credentials.",
+        "`@ouro.bot/cli` and the `ouro.bot` wrapper are version-synced for the pre-vault replacement repair release."
+      ]
+    },
     {
       "version": "0.1.0-alpha.393",
       "changes": [

package/dist/heart/auth/auth-flow.js

@@ -49,6 +49,7 @@ const identity_1 = require("../identity");
 const migrate_config_1 = require("../migrate-config");
 const provider_models_1 = require("../provider-models");
 const provider_credentials_1 = require("../provider-credentials");
+const vault_unlock_1 = require("../../repertoire/vault-unlock");
 const ANTHROPIC_SETUP_TOKEN_PREFIX = "sk-ant-oat01-";
 const ANTHROPIC_SETUP_TOKEN_MIN_LENGTH = 80;
 function assertPersistentProviderCredentialsAllowed(agentName) {
@@ -358,7 +359,7 @@ async function runRuntimeAuthFlow(input, deps = {}) {
     });
     const vault = await (0, provider_credentials_1.refreshProviderCredentialPool)(input.agentName);
     if (!vault.ok && vault.reason === "unavailable") {
-        throw new Error(`${vault.error}\nRun \`ouro vault unlock --agent ${input.agentName}\`, then retry auth.`);
+        throw new Error(`${vault.error}\n${(0, vault_unlock_1.vaultUnlockReplaceRecoverFix)(input.agentName, `Then retry 'ouro auth --agent ${input.agentName} --provider ${input.provider}'.`)}`);
     }
     const credentials = await collectRuntimeAuthCredentials(input, deps);
     const { credentialPath } = await storeProviderCredentials(input.agentName, input.provider, credentials);

package/dist/heart/daemon/agent-config-check.js

@@ -44,6 +44,7 @@ const provider_models_1 = require("../provider-models");
 const machine_identity_1 = require("../machine-identity");
 const provider_state_1 = require("../provider-state");
 const provider_credentials_1 = require("../provider-credentials");
+const vault_unlock_1 = require("../../repertoire/vault-unlock");
 function isAgentProvider(value) {
     return Object.prototype.hasOwnProperty.call(identity_1.PROVIDER_CREDENTIALS, value);
 }
@@ -260,11 +261,7 @@ function isVaultLockedError(error) {
     return /(?:ouro )?credential vault is locked|vault(?: is)? locked/.test(normalized);
 }
 function vaultUnlockOrRecoverFix(agentName, nextStep = "Then run 'ouro up' again.") {
-    return [
-        `Run 'ouro vault unlock --agent ${agentName}' if you have the saved vault unlock secret.`,
-        `If nobody saved it, run 'ouro vault recover --agent ${agentName} --from <json>' with a local credential export.`,
-        nextStep,
-    ].join(" ");
+    return (0, vault_unlock_1.vaultUnlockReplaceRecoverFix)(agentName, nextStep);
 }
 function failedPingResult(agentName, lane, provider, model, result) {
     return {

package/dist/heart/daemon/cli-exec.js

@@ -686,13 +686,19 @@ function readVaultRecoverSource(sourcePath) {
         runtimeConfig: recoverRuntimeConfig(parsed),
     };
 }
-function defaultRecoveredVaultEmail(agentName, now) {
+function defaultReplacementVaultEmail(agentName, now, action) {
     const local = agentName
         .toLowerCase()
         .replace(/[^a-z0-9._-]+/g, "-")
         .replace(/^-+|-+$/g, "") || "agent";
     const stamp = now.toISOString().replace(/[-:.TZ]/g, "").slice(0, 14);
-    return `${local}+recovered-${stamp}@ouro.bot`;
+    return `${local}+${action}-${stamp}@ouro.bot`;
+}
+function defaultRecoveredVaultEmail(agentName, now) {
+    return defaultReplacementVaultEmail(agentName, now, "recovered");
+}
+function defaultReplacedVaultEmail(agentName, now) {
+    return defaultReplacementVaultEmail(agentName, now, "replaced");
 }
 function ensureVaultSecretPrompt(promptSecret, action) {
     if (promptSecret)
@@ -702,6 +708,27 @@ function ensureVaultSecretPrompt(promptSecret, action) {
 function rejectGeneratedVaultUnlockSecret(action) {
     throw new Error(`vault ${action} no longer supports --generate-unlock-secret. Re-run without that flag and enter a human-chosen unlock secret; Ouro will not print vault unlock secrets.`);
 }
+async function createReplacementVaultForAgent(input) {
+    const result = await (0, vault_setup_1.createVaultAccount)("Ouro credential vault", input.serverUrl, input.email, input.unlockSecret);
+    if (!result.success) {
+        const message = [
+            `vault ${input.action} failed for ${input.agentName}: ${result.error}`,
+            "",
+            "This creates a replacement vault. If that vault account already exists, retry with a fresh --email value.",
+        ].join("\n");
+        input.deps.writeStdout(message);
+        return { ok: false, message };
+    }
+    writeAgentVaultConfig(input.agentName, input.configPath, input.config, { email: input.email, serverUrl: input.serverUrl });
+    const store = (0, vault_unlock_1.storeVaultUnlockSecret)({
+        agentName: input.agentName,
+        email: input.email,
+        serverUrl: input.serverUrl,
+    }, input.unlockSecret, { homeDir: input.deps.homeDir, store: input.store });
+    (0, credential_access_1.resetCredentialStore)();
+    await (0, credential_access_1.getCredentialStore)(input.agentName).get("__ouro_vault_probe__");
+    return { ok: true, store };
+}
 async function executeVaultUnlock(command, deps) {
     if (command.agent === "SerpentGuide") {
         throw new Error("SerpentGuide does not have a persistent credential vault. Hatch bootstrap uses selected provider credentials in memory only.");
@@ -773,6 +800,51 @@ async function executeVaultCreate(command, deps) {
     deps.writeStdout(message);
     return message;
 }
+async function executeVaultReplace(command, deps) {
+    if (command.agent === "SerpentGuide") {
+        throw new Error("SerpentGuide does not have a persistent credential vault. Replace the hatchling agent vault, not SerpentGuide.");
+    }
+    if (command.generateUnlockSecret)
+        rejectGeneratedVaultUnlockSecret("replace");
+    const promptSecret = ensureVaultSecretPrompt(deps.promptSecret, "replace");
+    const now = providerCliNow(deps);
+    const { configPath, config } = (0, auth_flow_1.readAgentConfigForAgent)(command.agent, deps.bundlesRoot);
+    const configuredVault = (0, identity_1.resolveVaultConfig)(command.agent, config.vault);
+    const email = command.email ?? defaultReplacedVaultEmail(command.agent, now);
+    const serverUrl = command.serverUrl ?? config.vault?.serverUrl ?? configuredVault.serverUrl;
+    const unlockSecret = (await promptSecret(`Choose replacement Ouro vault unlock secret for ${email}: `)).trim();
+    if (!unlockSecret) {
+        throw new Error("vault replace requires a replacement unlock secret. Re-run in an interactive terminal and enter a human-chosen unlock secret.");
+    }
+    const replacement = await createReplacementVaultForAgent({
+        action: "replace",
+        agentName: command.agent,
+        email,
+        serverUrl,
+        unlockSecret,
+        store: command.store,
+        deps,
+        configPath,
+        config,
+    });
+    if (!replacement.ok)
+        return replacement.message;
+    const message = [
+        `vault replaced for ${command.agent}`,
+        `vault: ${email} at ${serverUrl}`,
+        `local unlock store: ${replacement.store.kind}${replacement.store.secure ? "" : " (explicit plaintext fallback)"}`,
+        "credentials imported: none",
+        "This is the no-export path for agents that predate vault auth or lost an unsaved unlock secret.",
+        "Re-auth/re-enter the credentials this agent should use:",
+        `  ouro auth --agent ${command.agent} --provider <provider>`,
+        `  ouro vault config set --agent ${command.agent} --key <field>`,
+        `  ouro provider refresh --agent ${command.agent}`,
+        `  ouro auth verify --agent ${command.agent}`,
+        "Keep the replacement vault unlock secret saved outside Ouro. Another machine will need it once.",
+    ].join("\n");
+    deps.writeStdout(message);
+    return message;
+}
 async function executeVaultRecover(command, deps) {
     if (command.agent === "SerpentGuide") {
         throw new Error("SerpentGuide does not have a persistent credential vault. Recover the hatchling agent vault, not SerpentGuide.");
@@ -790,24 +862,19 @@ async function executeVaultRecover(command, deps) {
     if (!unlockSecret) {
         throw new Error("vault recover requires a replacement unlock secret. Re-run in an interactive terminal and enter a human-chosen unlock secret.");
     }
-    const result = await (0, vault_setup_1.createVaultAccount)("Ouro credential vault", serverUrl, email, unlockSecret);
-    if (!result.success) {
-        const message = [
-            `vault recover failed for ${command.agent}: ${result.error}`,
-            "",
-            "Recovery creates a replacement vault. If that vault account already exists, retry with a fresh --email value.",
-        ].join("\n");
-        deps.writeStdout(message);
-        return message;
-    }
-    writeAgentVaultConfig(command.agent, configPath, config, { email, serverUrl });
-    const store = (0, vault_unlock_1.storeVaultUnlockSecret)({
+    const replacement = await createReplacementVaultForAgent({
+        action: "recover",
         agentName: command.agent,
         email,
         serverUrl,
-    }, unlockSecret, { homeDir: deps.homeDir, store: command.store });
-    (0, credential_access_1.resetCredentialStore)();
-    await (0, credential_access_1.getCredentialStore)(command.agent).get("__ouro_vault_probe__");
+        unlockSecret,
+        store: command.store,
+        deps,
+        configPath,
+        config,
+    });
+    if (!replacement.ok)
+        return replacement.message;
     const importedProviders = new Set();
     let mergedRuntimeConfig = {};
     for (const source of sourceImports) {
@@ -832,7 +899,7 @@ async function executeVaultRecover(command, deps) {
     const message = [
         `vault recovered for ${command.agent}`,
         `vault: ${email} at ${serverUrl}`,
-        `local unlock store: ${store.kind}${store.secure ? "" : " (explicit plaintext fallback)"}`,
+        `local unlock store: ${replacement.store.kind}${replacement.store.secure ? "" : " (explicit plaintext fallback)"}`,
         `sources imported: ${sourceImports.length}`,
         `provider credentials imported: ${providerList.length === 0 ? "none" : providerList.join(", ")}`,
         `runtime credentials imported: ${runtimeFields.length === 0 ? "none" : runtimeFields.join(", ")}`,
@@ -850,6 +917,19 @@ async function executeVaultStatus(command, deps) {
     }
     const { config } = (0, auth_flow_1.readAgentConfigForAgent)(command.agent, deps.bundlesRoot);
     const vault = (0, identity_1.resolveVaultConfig)(command.agent, config.vault);
+    if (!config.vault) {
+        const lines = [
+            `agent: ${command.agent}`,
+            `vault: ${vault.email} at ${vault.serverUrl}`,
+            "vault locator: not configured in agent.json",
+            "local unlock: not checked",
+            "",
+            `fix: Run 'ouro vault create --agent ${command.agent}' to create this agent's vault, then run 'ouro auth --agent ${command.agent} --provider <provider>' and 'ouro provider refresh --agent ${command.agent}'.`,
+        ];
+        const message = lines.join("\n");
+        deps.writeStdout(message);
+        return message;
+    }
     const status = (0, vault_unlock_1.getVaultUnlockStatus)({
         agentName: command.agent,
         email: vault.email,
@@ -858,7 +938,7 @@ async function executeVaultStatus(command, deps) {
     const lines = [
         `agent: ${command.agent}`,
         `vault: ${vault.email} at ${vault.serverUrl}`,
-        `vault locator: ${config.vault ? "agent.json" : "default"}`,
+        "vault locator: agent.json",
         `local unlock store: ${status.store ? `${status.store.kind}${status.store.secure ? "" : " (explicit plaintext fallback)"}` : "unavailable"}`,
         `local unlock: ${status.stored ? "available" : "missing"}`,
     ];
@@ -976,7 +1056,7 @@ async function executeVaultConfigStatus(command, deps) {
         lines.push(`error: ${runtime.error}`);
         lines.push(runtime.reason === "missing"
             ? `fix: Run 'ouro vault config set --agent ${command.agent} --key <field>' to store runtime credentials.`
-            : `fix: Run 'ouro vault unlock --agent ${command.agent}', then retry.`);
+            : `fix: ${(0, vault_unlock_1.vaultUnlockReplaceRecoverFix)(command.agent, "Then retry 'ouro vault config status'.")}`);
     }
     const message = lines.join("\n");
     deps.writeStdout(message);
@@ -1243,7 +1323,7 @@ async function executeProviderRefresh(command, deps) {
     }
     else {
         lines.push(`provider credential refresh failed for ${command.agent}: ${pool.error}`);
-        lines.push(`Run \`ouro vault unlock --agent ${command.agent}\`, then retry.`);
+        lines.push((0, vault_unlock_1.vaultUnlockReplaceRecoverFix)(command.agent, "Then retry 'ouro provider refresh'."));
         const message = lines.join("\n");
         deps.writeStdout(message);
         return message;
@@ -2714,6 +2794,9 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
     if (command.kind === "vault.create") {
         return executeVaultCreate(command, deps);
     }
+    if (command.kind === "vault.replace") {
+        return executeVaultReplace(command, deps);
+    }
     if (command.kind === "vault.recover") {
         return executeVaultRecover(command, deps);
     }
@@ -2761,7 +2844,7 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
     if (command.kind === "auth.verify") {
         const poolResult = await (0, provider_credentials_1.refreshProviderCredentialPool)(command.agent);
         if (!poolResult.ok) {
-            const message = `vault unavailable: ${poolResult.error}\nRun \`ouro vault unlock --agent ${command.agent}\`, then retry.`;
+            const message = `vault unavailable: ${poolResult.error}\n${(0, vault_unlock_1.vaultUnlockReplaceRecoverFix)(command.agent, "Then retry 'ouro auth verify'.")}`;
             deps.writeStdout(message);
             return message;
         }

package/dist/heart/daemon/cli-help.js

@@ -184,10 +184,10 @@ exports.COMMAND_REGISTRY = {
     },
     vault: {
         category: "Auth",
-        description: "Create, recover, unlock, inspect, and populate the agent credential vault",
-        usage: "ouro vault <create|recover|unlock|status|config> --agent <name>",
+        description: "Create, replace, recover, unlock, inspect, and populate the agent credential vault",
+        usage: "ouro vault <create|replace|recover|unlock|status|config> --agent <name>",
         example: "ouro vault status --agent ouroboros",
-        subcommands: ["create", "recover", "unlock", "status", "config set", "config status"],
+        subcommands: ["create", "replace", "recover", "unlock", "status", "config set", "config status"],
     },
     thoughts: {
         category: "Internal",
@@ -269,6 +269,11 @@ const SUBCOMMAND_HELP = {
         usage: "ouro vault create --agent <name> --email <email> [--server <url>] [--store <store>]",
         example: "ouro vault create --agent ouroboros --email ouroboros@ouro.bot",
     },
+    "vault replace": {
+        description: "Create an empty replacement agent vault when no unlock secret or JSON export exists",
+        usage: "ouro vault replace --agent <name> [--email <email>] [--server <url>] [--store <store>]",
+        example: "ouro vault replace --agent ouroboros",
+    },
     "vault recover": {
         description: "Create a replacement agent vault and import local JSON credential exports",
         usage: "ouro vault recover --agent <name> --from <json> [--from <json>] [--email <email>] [--server <url>] [--store <store>]",

package/dist/heart/daemon/cli-parse.js

@@ -85,6 +85,7 @@ function usage() {
         "  ouro auth verify --agent <name> [--provider <provider>]",
         "  ouro auth switch --agent <name> --provider <provider>",
         "  ouro vault create --agent <name> --email <email> [--server <url>] [--store <store>]",
+        "  ouro vault replace --agent <name> [--email <email>] [--server <url>] [--store <store>]",
         "  ouro vault recover --agent <name> --from <json> [--from <json>] [--email <email>] [--server <url>] [--store <store>]",
         "  ouro vault unlock --agent <name> [--store auto|macos-keychain|windows-dpapi|linux-secret-service|plaintext-file]",
         "  ouro vault status --agent <name> [--store auto|macos-keychain|windows-dpapi|linux-secret-service|plaintext-file]",
@@ -479,6 +480,9 @@ function parseVaultCommand(args) {
             continue;
         }
         if (token === "--from") {
+            if (sub !== "recover") {
+                throw new Error("--from is only valid with `ouro vault recover`; use `ouro vault replace` when there is no JSON export to import.");
+            }
             const value = rest[i + 1];
             if (!value)
                 throw new Error("Usage: ouro vault recover --agent <name> --from <json> [--from <json>]");
@@ -490,10 +494,10 @@ function parseVaultCommand(args) {
             generateUnlockSecret = true;
             continue;
         }
-        throw new Error("Usage: ouro vault create|recover|unlock|status --agent <name>");
+        throw new Error("Usage: ouro vault create|replace|recover|unlock|status --agent <name>");
     }
-    if (!agent || (sub !== "create" && sub !== "recover" && sub !== "unlock" && sub !== "status")) {
-        throw new Error("Usage: ouro vault create|recover|unlock|status --agent <name>");
+    if (!agent || (sub !== "create" && sub !== "replace" && sub !== "recover" && sub !== "unlock" && sub !== "status")) {
+        throw new Error("Usage: ouro vault create|replace|recover|unlock|status --agent <name>");
     }
     if (sub === "create") {
         return {
@@ -505,6 +509,16 @@ function parseVaultCommand(args) {
             ...(generateUnlockSecret ? { generateUnlockSecret: true } : {}),
         };
     }
+    if (sub === "replace") {
+        return {
+            kind: "vault.replace",
+            agent,
+            ...(email ? { email } : {}),
+            ...(serverUrl ? { serverUrl } : {}),
+            ...(store ? { store } : {}),
+            ...(generateUnlockSecret ? { generateUnlockSecret: true } : {}),
+        };
+    }
     if (sub === "recover") {
         if (sources.length === 0) {
             throw new Error("Usage: ouro vault recover --agent <name> --from <json> [--from <json>]");

package/dist/heart/daemon/interactive-repair.js

@@ -63,6 +63,9 @@ function isAffirmativeAnswer(answer) {
 }
 function writeDeclinedRepair(degraded, command, deps) {
     deps.writeStdout(`repair skipped for ${degraded.agent}; run \`${command}\` later.`);
+    if (degraded.fixHint.includes("ouro vault replace") || degraded.fixHint.includes("ouro vault recover")) {
+        deps.writeStdout(`repair options for ${degraded.agent}: ${degraded.fixHint}`);
+    }
 }
 function runnableRepairActionFor(degraded) {
     if (isVaultUnlockIssue(degraded)) {
@@ -106,7 +109,7 @@ async function runInteractiveRepair(degraded, deps) {
     for (const entry of degraded) {
         const action = runnableRepairActionFor(entry);
         if (action?.kind === "vault-unlock") {
-            const answer = await deps.promptInput(`run \`${action.command}\` now? [y/n] `);
+            const answer = await deps.promptInput(`run \`${action.command}\` now? Only say yes if you have the saved unlock secret. [y/n] `);
             if (isAffirmativeAnswer(answer)) {
                 try {
                     if (!deps.runVaultUnlock) {

package/dist/heart/daemon/sense-manager.js

@@ -99,7 +99,7 @@ function numberField(record, key, fallback) {
 function compactRuntimeConfigError(agent, error) {
     const compact = error.replace(/\s+/g, " ").trim();
     if (/credential vault is locked|vault locked|vault is locked/i.test(compact)) {
-        return `vault locked; run 'ouro vault unlock --agent ${agent}'`;
+        return `vault locked; run 'ouro vault unlock --agent ${agent}' if you have the saved secret, or 'ouro vault replace --agent ${agent}' if none was saved`;
     }
     return compact || "unavailable";
 }

package/dist/repertoire/vault-unlock.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.vaultUnlockReplaceRecoverFix = vaultUnlockReplaceRecoverFix;
 exports.resolveVaultUnlockStore = resolveVaultUnlockStore;
 exports.readVaultUnlockSecret = readVaultUnlockSecret;
 exports.storeVaultUnlockSecret = storeVaultUnlockSecret;
@@ -95,6 +96,23 @@ function missingSecureStoreMessage(config) {
             : "Run `ouro vault unlock --store plaintext-file` to store the vault unlock secret in a chmod 0600 local file.",
     ].join("\n");
 }
+function vaultUnlockReplaceRecoverFix(agentName, nextStep = "Then run 'ouro up' again.") {
+    return [
+        `Run 'ouro vault unlock --agent ${agentName}' if you have the saved vault unlock secret.`,
+        `If this agent predates vault auth or nobody saved the unlock secret, run 'ouro vault replace --agent ${agentName}' to create a new empty vault, then re-auth/re-enter credentials.`,
+        `If you do have a local JSON credential export, run 'ouro vault recover --agent ${agentName} --from <json>' to create a replacement vault and import it.`,
+        nextStep,
+    ].join(" ");
+}
+function lostUnlockSecretGuidance(config) {
+    if (!config.agentName) {
+        return "If nobody saved that unlock secret, run `ouro vault replace --agent <agent>` to create a new empty vault and re-enter credentials. If you do have a local JSON credential export, run `ouro vault recover --agent <agent> --from <json>` to import it.";
+    }
+    return [
+        `If nobody saved that unlock secret, run \`ouro vault replace --agent ${config.agentName}\` to create a new empty vault and re-enter credentials.`,
+        `If you do have a local JSON credential export, run \`ouro vault recover --agent ${config.agentName} --from <json>\` to import it.`,
+    ].join(" ");
+}
 function lockedMessage(config, store) {
     const agentPart = config.agentName ? ` for ${config.agentName}` : "";
     const command = config.agentName
@@ -111,9 +129,7 @@ function lockedMessage(config, store) {
         "This can happen on a new computer, after a local profile or hostname migration, or if the local unlock entry was removed.",
         "",
         `Run \`${command}\` and enter the saved agent vault unlock secret from the human/operator who controls that vault.`,
-        config.agentName
-            ? `If nobody saved that unlock secret, run \`ouro vault recover --agent ${config.agentName} --from <json>\` with a local credential export, or create a replacement vault and re-enter credentials.`
-            : "If nobody saved that unlock secret, run `ouro vault recover --agent <agent> --from <json>` with a local credential export, or create a replacement vault and re-enter credentials.",
+        lostUnlockSecretGuidance(config),
     ].join("\n");
 }
 function validateStoreKind(store) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.393",
+  "version": "0.1.0-alpha.394",
   "main": "dist/heart/daemon/ouro-entry.js",
   "bin": {
     "cli": "dist/heart/daemon/ouro-bot-entry.js",