@vess-id/vess 0.2.0-alpha.3 → 0.2.0-alpha.30

package/dist/config/version.d.ts

@@ -0,0 +1,3 @@
+export declare const CLI_VERSION: string;
+export declare const SDK_VERSION: string;
+//# sourceMappingURL=version.d.ts.map

package/dist/config/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/config/version.ts"],"names":[],"mappings":"AAyCA,eAAO,MAAM,WAAW,QAAmB,CAAA;AAC3C,eAAO,MAAM,WAAW,QAAmB,CAAA"}

package/dist/config/version.js

@@ -0,0 +1,80 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_VERSION = exports.CLI_VERSION = void 0;
+const path = __importStar(require("node:path"));
+const fs = __importStar(require("node:fs"));
+const node_module_1 = require("node:module");
+/**
+ * Read the agentd CLI version from package.json at runtime.
+ * Works in both dev (src/config) and production (dist/config).
+ */
+function readCliVersion() {
+    try {
+        const pkgPath = path.resolve(__dirname, '..', '..', 'package.json');
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        return pkg.version ?? '0.0.0-unknown';
+    }
+    catch {
+        return '0.0.0-unknown';
+    }
+}
+/**
+ * Read the SDK version from @vess-id/ai-identity package.json.
+ * Tries multiple resolution strategies for compatibility with
+ * jest (moduleNameMapper), workspace links, and production installs.
+ */
+function readSdkVersion() {
+    // Strategy 1: createRequire (works in production npm installs)
+    try {
+        const req = (0, node_module_1.createRequire)(__filename);
+        const pkg = req('@vess-id/ai-identity/package.json');
+        if (pkg.version)
+            return pkg.version;
+    }
+    catch { /* fall through */ }
+    // Strategy 2: relative path from monorepo (works in dev and jest)
+    try {
+        const pkgPath = path.resolve(__dirname, '..', '..', '..', 'sdk', 'package.json');
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        if (pkg.version)
+            return pkg.version;
+    }
+    catch { /* fall through */ }
+    return '0.0.0-unknown';
+}
+exports.CLI_VERSION = readCliVersion();
+exports.SDK_VERSION = readSdkVersion();
+//# sourceMappingURL=version.js.map

package/dist/config/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/config/version.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,gDAAiC;AACjC,4CAA6B;AAC7B,6CAA2C;AAE3C;;;GAGG;AACH,SAAS,cAAc;IACrB,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC,CAAA;QACnE,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAA;QACzD,OAAO,GAAG,CAAC,OAAO,IAAI,eAAe,CAAA;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,eAAe,CAAA;IACxB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,cAAc;IACrB,+DAA+D;IAC/D,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAA,2BAAa,EAAC,UAAU,CAAC,CAAA;QACrC,MAAM,GAAG,GAAG,GAAG,CAAC,mCAAmC,CAAwB,CAAA;QAC3E,IAAI,GAAG,CAAC,OAAO;YAAE,OAAO,GAAG,CAAC,OAAO,CAAA;IACrC,CAAC;IAAC,MAAM,CAAC,CAAC,kBAAkB,CAAC,CAAC;IAE9B,kEAAkE;IAClE,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,cAAc,CAAC,CAAA;QAChF,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAA;QACzD,IAAI,GAAG,CAAC,OAAO;YAAE,OAAO,GAAG,CAAC,OAAO,CAAA;IACrC,CAAC;IAAC,MAAM,CAAC,CAAC,kBAAkB,CAAC,CAAC;IAE9B,OAAO,eAAe,CAAA;AACxB,CAAC;AAEY,QAAA,WAAW,GAAG,cAAc,EAAE,CAAA;AAC9B,QAAA,WAAW,GAAG,cAAc,EAAE,CAAA"}

package/dist/core/execution-engine.d.ts

@@ -77,10 +77,24 @@ export declare class ExecutionEngine {
      */
     private handlePendingApproval;
     /**
-     * Create an OOB approval request for high/critical risk actions.
+     * Create an OOB (out-of-band) approval request.
      * Returns a URL for the user to approve in their browser.
+     *
+     * Called in two contexts:
+     * - ensureVC Step 4: for high/critical risk actions that require browser approval.
+     * - tryOOBFallbackAfterRetryExhaustion: for ANY risk level when a VC expires
+     *   mid-execution and retry is exhausted. In this case OOB is used as a fallback
+     *   because the normal in-band flow cannot recover an expired credential — the
+     *   user must re-authorize via browser regardless of risk level.
      */
     private createOOBApprovalRequest;
+    /**
+     * Revoke the stale credential and attempt to create an OOB approval request
+     * as a fallback after retry exhaustion. Returns an ExecuteResult with
+     * waitingForApproval on success, or null if OOB creation fails (caller falls
+     * through to the original error).
+     */
+    private tryOOBFallbackAfterRetryExhaustion;
     /**
      * Create an in-band approval response for low/medium risk actions.
      * Generates an approval token for the MCP client to present back.

package/dist/core/execution-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execution-engine.d.ts","sourceRoot":"","sources":["../../src/core/execution-engine.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAC5D,OAAO,EAAE,MAAM,EAAuC,MAAM,kBAAkB,CAAA;AAC9E,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACnD,OAAO,EAAE,mBAAmB,EAAuB,MAAM,2BAA2B,CAAA;AACpF,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAA;AAKjE,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,eAAe,EAAE,gBAAgB,EAA0E,MAAM,SAAS,CAAA;AAElK,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAmCrD,qBAAa,eAAe;IASxB,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;IAfjC,OAAO,CAAC,kBAAkB,CAAsB;IAChD,OAAO,CAAC,UAAU,CAAC,CAAmC;IACtD,OAAO,CAAC,eAAe,CAAQ;IAC/B,OAAO,CAAC,iBAAiB,CAA4B;IACrD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAS;IAChD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAO;gBAG5B,eAAe,EAAE,eAAe,EAChC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,EACpB,WAAW,EAAE,WAAW,GAAG,IAAI,EAC/B,aAAa,EAAE,mBAAmB,EAClC,OAAO,EAAE,gBAAgB,EACzB,YAAY,EAAE,oBAAoB,EAClC,aAAa,CAAC,EAAE,aAAa,YAAA;IAGhD;;OAEG;IACH,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIzC;;;OAGG;IACH,aAAa,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAI5D;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IA6B7B;;;OAGG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAkF9D;;;;;;;;OAQG;YACW,QAAQ;YA8GR,YAAY;IAuC1B;;;OAGG;YACW,kBAAkB;IA4IhC;;;;;;;OAOG;YACW,mBAAmB;YA2GnB,iBAAiB;YAiDjB,uBAAuB;IAwFrC;;OAEG;YACW,qBAAqB;IA8HnC;;;OAGG;YACW,wBAAwB;IAyCtC;;;OAGG;IACH,OAAO,CAAC,4BAA4B;IAgDpC;;;;OAIG;IACG,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC;IAmH7D,kBAAkB,IAAI,OAAO,CAAC,eAAe,CAAC;IAWpD;;;OAGG;YACW,iBAAiB;IA8B/B,OAAO,CAAC,kBAAkB;IAS1B,OAAO,CAAC,eAAe;YAUT,sBAAsB;IA0JpC,OAAO,CAAC,eAAe;IASvB;;;;;OAKG;IACH,OAAO,CAAC,0BAA0B;IAiBlC,OAAO,CAAC,kBAAkB;IAM1B,OAAO,CAAC,eAAe;IAavB,iHAAiH;YACnG,cAAc;YA4Bd,sBAAsB;IAsCpC,OAAO,CAAC,QAAQ;CAqCjB"}
+{"version":3,"file":"execution-engine.d.ts","sourceRoot":"","sources":["../../src/core/execution-engine.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAC5D,OAAO,EAAE,MAAM,EAAuC,MAAM,kBAAkB,CAAA;AAC9E,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACnD,OAAO,EAAE,mBAAmB,EAAuB,MAAM,2BAA2B,CAAA;AACpF,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAA;AAKjE,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,eAAe,EAAE,gBAAgB,EAA0E,MAAM,SAAS,CAAA;AAElK,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAoCrD,qBAAa,eAAe;IASxB,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;IAfjC,OAAO,CAAC,kBAAkB,CAAsB;IAChD,OAAO,CAAC,UAAU,CAAC,CAAmC;IACtD,OAAO,CAAC,eAAe,CAAQ;IAC/B,OAAO,CAAC,iBAAiB,CAA4B;IACrD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAS;IAChD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAO;gBAG5B,eAAe,EAAE,eAAe,EAChC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,EACpB,WAAW,EAAE,WAAW,GAAG,IAAI,EAC/B,aAAa,EAAE,mBAAmB,EAClC,OAAO,EAAE,gBAAgB,EACzB,YAAY,EAAE,oBAAoB,EAClC,aAAa,CAAC,EAAE,aAAa,YAAA;IAGhD;;OAEG;IACH,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIzC;;;OAGG;IACH,aAAa,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAI5D;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IA6B7B;;;OAGG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAkF9D;;;;;;;;OAQG;YACW,QAAQ;YA2HR,YAAY;IAuC1B;;;OAGG;YACW,kBAAkB;IAwJhC;;;;;;;OAOG;YACW,mBAAmB;YA2GnB,iBAAiB;YAiDjB,uBAAuB;IAqIrC;;OAEG;YACW,qBAAqB;IAmLnC;;;;;;;;;;OAUG;YACW,wBAAwB;IA+CtC;;;;;OAKG;YACW,kCAAkC;IAqChD;;;OAGG;IACH,OAAO,CAAC,4BAA4B;IAgDpC;;;;OAIG;IACG,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC;IAmH7D,kBAAkB,IAAI,OAAO,CAAC,eAAe,CAAC;IAWpD;;;OAGG;YACW,iBAAiB;IA8B/B,OAAO,CAAC,kBAAkB;IAS1B,OAAO,CAAC,eAAe;YAUT,sBAAsB;IA0JpC,OAAO,CAAC,eAAe;IASvB;;;;;OAKG;IACH,OAAO,CAAC,0BAA0B;IA0BlC,OAAO,CAAC,kBAAkB;IAM1B,OAAO,CAAC,eAAe;IAavB,iHAAiH;YACnG,cAAc;YA4Bd,sBAAsB;IAsCpC,OAAO,CAAC,QAAQ;CAqCjB"}

package/dist/core/execution-engine.js

@@ -63,8 +63,9 @@ const executor_registry_1 = require("../executor/executor-registry");
 const env_resolver_1 = require("../env/env-resolver");
 /** Policy cache staleness TTL (spec §7.6: 30 minutes) */
 const POLICY_SYNC_TTL_MS = 30 * 60 * 1000;
-/** OOB approval request expiration (seconds) */
-const OOB_APPROVAL_EXPIRES_IN_SECONDS = 300;
+/** Fallback OOB approval expiration (seconds) when the API doesn't return a value.
+ *  Kept short (5 min) so the agent doesn't wait on a possibly-expired request. */
+const OOB_APPROVAL_DEFAULT_EXPIRES_IN_SECONDS = 300;
 /** Default TTL for OOB-approved credentials (10 minutes) */
 const OOB_CREDENTIAL_DEFAULT_TTL_MS = 10 * 60 * 1000;
 class ExecutionEngine {
@@ -243,23 +244,39 @@ class ExecutionEngine {
                     return { credential: verified, decisionSource: 'cached_vc' };
             }
         }
-        // Step 2: Check Gateway for approved requests
+        // Step 2: Check Gateway for approved requests, then claim VC
         try {
             approvedRequests = await this.gatewayClient.findApprovedRequests(this.context.agentDid);
-            const matching = approvedRequests.find(r => r.actions?.includes(action) && r.credential);
-            if (matching && matching.credential) {
-                const stored = this.wallet.storeCredential({
-                    holderDid: this.context.agentDid,
-                    projectId: this.context.projectId,
-                    credentialJwt: matching.credential.jwt,
-                    actions: matching.actions,
-                    provider,
-                    expiresAt: matching.credential.expiresAt,
-                    normalizedResourceKey: resourceInfo?.normalizedResource,
-                    resourceFingerprint: resourceInfo?.fingerprint,
-                    resources: (0, wallet_1.validateResources)(matching.resources),
-                });
-                return { credential: stored, decisionSource: 'cached_vc' };
+            const matching = approvedRequests.find(r => r.actions?.includes(action));
+            if (matching) {
+                try {
+                    const claimed = await this.gatewayClient.claimVC(matching.id, this.context.agentDid);
+                    const stored = this.wallet.storeCredential({
+                        holderDid: this.context.agentDid,
+                        projectId: this.context.projectId,
+                        credentialJwt: claimed.credential.jwt,
+                        actions: claimed.actions,
+                        provider,
+                        expiresAt: claimed.credential.expiresAt,
+                        normalizedResourceKey: resourceInfo?.normalizedResource,
+                        resourceFingerprint: resourceInfo?.fingerprint,
+                        resources: (0, wallet_1.validateResources)(claimed.resources),
+                    });
+                    return { credential: stored, decisionSource: 'claimed_from_approval' };
+                }
+                catch (claimErr) {
+                    const msg = claimErr instanceof Error ? claimErr.message : String(claimErr);
+                    if (msg === 'CLAIM_CONSUMED') {
+                        process.stderr.write('[vess] claimVC: request already consumed, falling through to step 3\n');
+                    }
+                    else if (msg === 'CLAIM_EXPIRED') {
+                        process.stderr.write('[vess] claimVC: request expired, falling through to step 3\n');
+                    }
+                    else {
+                        process.stderr.write(`[vess] claimVC failed: ${msg}, falling through to step 3\n`);
+                    }
+                    // Fall through to Step 3
+                }
             }
         }
         catch {
@@ -384,6 +401,16 @@ class ExecutionEngine {
                         return { success: false, error: `VC reissuance denied: ${newVCResult.reason}` };
                     }
                 }
+                // After retry exhaustion, if still credential-invalid, fall back to OOB approval
+                // so the user gets an actionable re-authorization URL instead of a raw error.
+                if ((0, credential_errors_1.isCredentialInvalidError)(authResult.reason) && retryCount >= 1) {
+                    const resourceInfoForOOB = normalizedResource && resourceFingerprint
+                        ? { normalizedResource, fingerprint: resourceFingerprint }
+                        : undefined;
+                    const oobFallback = await this.tryOOBFallbackAfterRetryExhaustion(action, provider, vcResult.credential.id, params, resourceInfoForOOB, 'local');
+                    if (oobFallback)
+                        return oobFallback;
+                }
                 this.logAudit({
                     action, provider,
                     decision: 'deny',
@@ -615,12 +642,45 @@ class ExecutionEngine {
                 vpChallenge: nonce,
                 vpDomain: this.context.gatewayUrl,
             });
+            // Phase 2c-B — the api signaled a revoked/expired OAuth token. Do not
+            // retry: the VC is still valid locally but the upstream SaaS token is
+            // gone and won't return until the user clicks the authUrl. Surface the
+            // reauth payload so the CLI can render it.
+            //
+            // Scope note: reauth only originates here (the gateway path) because
+            // local actions (`os.*`) don't touch SaaS OAuth tokens. If a future
+            // local executor ever starts proxying SaaS calls, mirror this branch
+            // in `executeLocalWithVC` with `enforcementType: 'local'`.
+            if (!result.success && result.errorCode === ai_identity_1.GATEWAY_ERROR_CODE.REAUTH_REQUIRED && result.reauthRequired) {
+                this.logAudit({
+                    action, provider,
+                    decision: 'deny',
+                    enforcementType: 'gateway',
+                    decisionSource: 'gateway_execution',
+                    decisionReason: 'oauth_token_revoked',
+                    executionType: 'gateway',
+                    credentialId: vcResult.credential.id,
+                    grantId: vcResult.grantId,
+                    approvalMode: vcResult.approvalMode,
+                });
+                return {
+                    success: false,
+                    error: result.error,
+                    reauthRequired: {
+                        provider: result.reauthRequired.provider,
+                        reason: result.reauthRequired.reason,
+                        message: result.reauthRequired.message,
+                        authUrl: result.reauthRequired.authUrl,
+                        projectId: result.reauthRequired.projectId,
+                    },
+                };
+            }
             // Detect resource mismatch from structured error code
-            if (!result.success && result.errorCode === 'RESOURCE_MISMATCH') {
+            if (!result.success && result.errorCode === ai_identity_1.GATEWAY_ERROR_CODE.RESOURCE_MISMATCH) {
                 return this.handleResourceMismatch(action, provider, params, vcResult);
             }
             // Detect credential-invalid errors and attempt VC reissuance (max 1 retry)
-            if (!result.success && result.errorCode === 'CREDENTIAL_INVALID' && retryCount < 1) {
+            if (!result.success && result.errorCode === ai_identity_1.GATEWAY_ERROR_CODE.CREDENTIAL_INVALID && retryCount < 1) {
                 this.wallet.revokeCredential(vcResult.credential.id);
                 const newVCResult = await this.ensureVC(action, provider, undefined, params, canonicalResourceId);
                 if ('credential' in newVCResult) {
@@ -640,6 +700,15 @@ class ExecutionEngine {
                 // Could not re-acquire VC — return the original error
                 return { success: false, error: result.error };
             }
+            // After retry exhaustion, if still CREDENTIAL_INVALID, fall back to OOB approval
+            // so the user gets an actionable re-authorization URL instead of a raw error.
+            if (!result.success && result.errorCode === ai_identity_1.GATEWAY_ERROR_CODE.CREDENTIAL_INVALID && retryCount >= 1) {
+                // Gateway path does not have normalizedResource/resourceFingerprint in scope
+                // (resource resolution happens server-side), so resourceInfo is omitted.
+                const oobFallback = await this.tryOOBFallbackAfterRetryExhaustion(action, provider, vcResult.credential.id, params);
+                if (oobFallback)
+                    return oobFallback;
+            }
             this.logAudit({
                 action, provider,
                 decision: result.success ? 'allow' : 'deny',
@@ -728,7 +797,14 @@ class ExecutionEngine {
         if (statusResult.status === 'expired') {
             return { success: false, error: 'Approval request has expired. Please try again.' };
         }
+        if (statusResult.status === 'consumed') {
+            return { success: false, error: 'Approval was already claimed by another session. Please request a new approval.' };
+        }
         if (statusResult.status === 'pending') {
+            const rawExpiry = statusResult.requestExpiresAt
+                ? Math.floor((new Date(statusResult.requestExpiresAt).getTime() - Date.now()) / 1000)
+                : NaN;
+            const expiresIn = Number.isNaN(rawExpiry) ? OOB_APPROVAL_DEFAULT_EXPIRES_IN_SECONDS : Math.max(0, rawExpiry);
             return {
                 success: false,
                 waitingForApproval: {
@@ -737,45 +813,84 @@ class ExecutionEngine {
                     requestId: pendingRequestId,
                     action,
                     riskLevel: this.getActionRiskLevel(action),
-                    expiresIn: OOB_APPROVAL_EXPIRES_IN_SECONDS,
+                    expiresIn,
                     message: 'Still waiting for approval. Please approve in your browser.',
                 },
             };
         }
-        // approved — store credential and execute directly (no wallet round-trip)
-        if (statusResult.status === 'approved' && statusResult.credential) {
+        // approved — claim VC, store, and execute directly
+        if (statusResult.status === 'approved') {
             const provider = action.split('.')[0];
+            let claimed;
+            try {
+                claimed = await this.gatewayClient.claimVC(pendingRequestId, this.context.agentDid);
+            }
+            catch (claimErr) {
+                const msg = claimErr instanceof Error ? claimErr.message : String(claimErr);
+                if (msg === 'CLAIM_CONSUMED') {
+                    return { success: false, error: 'Approval was already claimed by another session' };
+                }
+                if (msg === 'CLAIM_EXPIRED') {
+                    return { success: false, error: 'Approval request has expired. Please try again.' };
+                }
+                return { success: false, error: `Failed to claim VC: ${msg}` };
+            }
+            // Restore original action parameters from approval request if not provided in retry call
+            const fallbackParams = claimed.actionParams;
+            const effectiveInput = Object.keys(request.input).length > 0
+                ? request.input
+                : fallbackParams ?? null;
+            if (!effectiveInput) {
+                return { success: false, error: 'Action parameters could not be restored. Please retry with explicit parameters.' };
+            }
+            // Security: re-validate resource constraint using effectiveInput (defense-in-depth)
+            // The pre-claim check (line 838) may have been skipped when request.input was empty.
+            if (statusResult.resources?.length) {
+                const extractedId = this.extractResourceIdFromInput(action, effectiveInput);
+                if (extractedId) {
+                    const normalizedId = (0, executor_registry_1.isLocalAction)(action) && effectiveInput.file_path
+                        ? (0, resource_canonicalizer_1.canonicalizePath)(effectiveInput.file_path)
+                        : extractedId;
+                    const approvedResources = statusResult.resources;
+                    const resourceMatch = approvedResources.some((r) => r.id === extractedId || r.id === normalizedId ||
+                        r.pattern === extractedId || r.pattern === normalizedId);
+                    if (!resourceMatch) {
+                        return {
+                            success: false,
+                            error: `Resource mismatch: approval was for [${approvedResources.map((r) => r.id || r.pattern).join(', ')}], but effective input resolves to "${extractedId}"`,
+                        };
+                    }
+                }
+            }
             const stored = this.wallet.storeCredential({
                 holderDid: this.context.agentDid,
                 projectId: this.context.projectId,
-                credentialJwt: statusResult.credential,
-                actions: [action],
+                credentialJwt: claimed.credential.jwt,
+                actions: claimed.actions.length ? claimed.actions : [action],
                 provider,
-                expiresAt: statusResult.expiresAt
-                    ? new Date(statusResult.expiresAt).getTime()
-                    : Date.now() + OOB_CREDENTIAL_DEFAULT_TTL_MS,
-                resources: (0, wallet_1.validateResources)(statusResult.resources),
+                expiresAt: claimed.credential.expiresAt,
+                resources: (0, wallet_1.validateResources)(claimed.resources),
             });
             // Build VCAcquired and execute directly (skip re-enter via this.execute)
             const vcAcquired = {
                 credential: stored,
                 approvalMode: 'one_time',
-                decisionSource: 'new_vc_from_quick_approve',
+                decisionSource: 'claimed_from_approval',
             };
             const routing = (0, executor_registry_1.determineRouting)(provider, action);
             let executeResult;
-            const normalizedResource = (0, executor_registry_1.isLocalAction)(action) && request.input.file_path
-                ? (0, resource_canonicalizer_1.canonicalizePath)(request.input.file_path)
+            const normalizedResource = (0, executor_registry_1.isLocalAction)(action) && effectiveInput.file_path
+                ? (0, resource_canonicalizer_1.canonicalizePath)(effectiveInput.file_path)
                 : undefined;
             const resourceFingerprint = normalizedResource
                 ? (0, resource_canonicalizer_1.computeFingerprint)(normalizedResource, this.context.rootDid)
                 : undefined;
             try {
                 if (routing.executor === 'local') {
-                    executeResult = await this.executeLocalWithVC(action, request.input, provider, vcAcquired, normalizedResource, resourceFingerprint, request.input.file_path);
+                    executeResult = await this.executeLocalWithVC(action, effectiveInput, provider, vcAcquired, normalizedResource, resourceFingerprint, effectiveInput.file_path);
                 }
                 else {
-                    executeResult = await this.executeViaGatewayWithVC(provider, action, request.input, vcAcquired);
+                    executeResult = await this.executeViaGatewayWithVC(provider, action, effectiveInput, vcAcquired);
                 }
             }
             finally {
@@ -789,8 +904,15 @@ class ExecutionEngine {
         return { success: false, error: `Unexpected approval status: ${statusResult.status}` };
     }
     /**
-     * Create an OOB approval request for high/critical risk actions.
+     * Create an OOB (out-of-band) approval request.
      * Returns a URL for the user to approve in their browser.
+     *
+     * Called in two contexts:
+     * - ensureVC Step 4: for high/critical risk actions that require browser approval.
+     * - tryOOBFallbackAfterRetryExhaustion: for ANY risk level when a VC expires
+     *   mid-execution and retry is exhausted. In this case OOB is used as a fallback
+     *   because the normal in-band flow cannot recover an expired credential — the
+     *   user must re-authorize via browser regardless of risk level.
      */
     async createOOBApprovalRequest(action, provider, riskLevel, resourceInfo, input) {
         const resourceType = this.getResourceType(action);
@@ -806,7 +928,12 @@ class ExecutionEngine {
                 projectId: this.context.projectId,
                 actions: [action],
                 resources,
+                actionParams: input,
             });
+            const rawExpiry = result.expiresAt
+                ? Math.floor((new Date(result.expiresAt).getTime() - Date.now()) / 1000)
+                : NaN;
+            const expiresIn = Number.isNaN(rawExpiry) ? OOB_APPROVAL_DEFAULT_EXPIRES_IN_SECONDS : Math.max(0, rawExpiry);
             return {
                 waitingForApproval: {
                     status: 'waiting_for_approval',
@@ -815,7 +942,7 @@ class ExecutionEngine {
                     action,
                     resource: resourceInfo?.normalizedResource ?? extractedId,
                     riskLevel,
-                    expiresIn: OOB_APPROVAL_EXPIRES_IN_SECONDS,
+                    expiresIn,
                     message: `This ${riskLevel}-risk action requires browser approval (login required). Open the URL to approve.`,
                 },
             };
@@ -824,6 +951,42 @@ class ExecutionEngine {
             throw new Error(`Failed to create OOB approval request: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    /**
+     * Revoke the stale credential and attempt to create an OOB approval request
+     * as a fallback after retry exhaustion. Returns an ExecuteResult with
+     * waitingForApproval on success, or null if OOB creation fails (caller falls
+     * through to the original error).
+     */
+    async tryOOBFallbackAfterRetryExhaustion(action, provider, credentialId, params, resourceInfo, executionType = 'gateway') {
+        const enforcementType = executionType === 'local' ? 'gateway_verified_local' : 'gateway';
+        this.wallet.revokeCredential(credentialId);
+        try {
+            const riskLevel = this.getActionRiskLevel(action);
+            const oobResult = await this.createOOBApprovalRequest(action, provider, riskLevel, resourceInfo, params);
+            this.logAudit({
+                action, provider,
+                decision: 'deny',
+                enforcementType,
+                decisionSource: 'gateway_execution',
+                decisionReason: `Credential expired after retry — OOB approval requested (requestId=${oobResult.waitingForApproval.requestId})`,
+                executionType,
+                credentialId,
+            });
+            return { success: false, waitingForApproval: oobResult.waitingForApproval };
+        }
+        catch (err) {
+            this.logAudit({
+                action, provider,
+                decision: 'deny',
+                enforcementType,
+                decisionSource: 'gateway_execution',
+                decisionReason: `OOB approval fallback failed after retry exhaustion: ${err instanceof Error ? err.message : String(err)}`,
+                executionType,
+                credentialId,
+            });
+            return null;
+        }
+    }
     /**
      * Create an in-band approval response for low/medium risk actions.
      * Generates an approval token for the MCP client to present back.
@@ -1180,13 +1343,21 @@ class ExecutionEngine {
         const binding = actionDef.target_bindings.resource_id;
         if (binding.source !== 'param')
             return undefined;
-        const value = input[binding.param];
+        let value = input[binding.param];
+        // Fallback: AI agents may use alternative param names (e.g., "issueKey" instead of "issueIdOrKey")
+        if (!value && binding.fallback_param) {
+            value = input[binding.fallback_param];
+        }
         if (!value || typeof value !== 'string')
             return undefined;
         // Defense-in-depth: reject control characters and excessively long values
         const MAX_RESOURCE_ID_LENGTH = 500;
         if (value.length > MAX_RESOURCE_ID_LENGTH || /[\x00-\x1f]/.test(value))
             return undefined;
+        // Apply derive transformation (e.g., "AIDENTITY-34" → "AIDENTITY" for project-level scoping)
+        if (binding.derive === 'project_key') {
+            value = (0, ai_identity_1.extractProjectKey)(value) ?? value;
+        }
         return value;
     }
     isRecentOOBRequest(action, resourceId) {