@relaycast/engine 8.8.0 → 8.9.0

package/dist/engine/action.js

@@ -83,6 +83,7 @@ function isAcceptedDeletedRegisteredActionInvocation(invocation) {
         && invocation.providerAcceptedAttempt === invocation.dispatchAttempts;
 }
 const RELEASE_GENERATION_CONFLICT_CODE = 'agent_release_generation_conflict';
+const RELEASE_IDENTITY_MISMATCH_CODE = 'agent_identity_mismatch';
 function releaseExpectedTokenHash(input) {
     const value = input.expected_token_hash;
     if (value === undefined)
@@ -92,11 +93,21 @@ function releaseExpectedTokenHash(input) {
     }
     return value;
 }
-function releaseGenerationStillCurrent(workspaceId, agentId, expectedTokenHash) {
+function releaseExpectedAgentId(input) {
+    const value = input.expected_agent_id;
+    if (value === undefined)
+        return null;
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw codedError('release action input.expected_agent_id must be a non-empty immutable agent id', 'invalid_release_request', 400);
+    }
+    return value;
+}
+function releaseGenerationStillCurrent(workspaceId, agentId, expectedTokenHash, expectedAgentId = null) {
     return sql `EXISTS (
     SELECT 1 FROM ${agents}
     WHERE ${agents.workspaceId} = ${workspaceId}
       AND ${agents.id} = ${agentId}
+      ${expectedAgentId ? sql `AND ${agents.id} = ${expectedAgentId}` : sql ``}
       ${expectedTokenHash ? sql `AND ${agents.tokenHash} = ${expectedTokenHash}` : sql ``}
   )`;
 }
@@ -490,8 +501,10 @@ async function waitForInvocationReplayOutcome(db, workspaceId, invocation, optio
         // replay shortcut, otherwise the same idempotency key changes 409 into 201.
         if (isBuiltinReleaseInvocation(current)
             && current.status === 'failed'
-            && current.error === RELEASE_GENERATION_CONFLICT_CODE) {
-            throw codedError('Action invocation failed because the release generation changed', RELEASE_GENERATION_CONFLICT_CODE, 409);
+            && (current.error === RELEASE_GENERATION_CONFLICT_CODE || current.error === RELEASE_IDENTITY_MISMATCH_CODE)) {
+            throw codedError(current.error === RELEASE_IDENTITY_MISMATCH_CODE
+                ? 'Action invocation failed because the immutable agent identity changed'
+                : 'Action invocation failed because the release generation changed', current.error, 409);
         }
         // Registered node actions only enter action_deleted before the provider
         // accepts the frame. Surface that durable result before the route snapshot
@@ -747,11 +760,43 @@ async function dispatchRelease(args) {
         throw codedError('release action input.name is required', 'invalid_release_request', 400);
     }
     const expectedTokenHash = releaseExpectedTokenHash(input);
+    const expectedAgentId = releaseExpectedAgentId(input);
+    // Claim the operation before resolving the mutable name. A completed exact
+    // release tombstones/renames the row, so a lost-response replay must find
+    // this immutable invocation before it looks up the name again.
+    const exactClaim = expectedAgentId ? await createInvocation(args.db, args.workspaceId, null, {
+        input,
+        caller_id: args.data.caller_id,
+        caller_name: args.data.caller_name,
+        action_name: 'release',
+        invocation_id: args.invocationId ?? (args.idempotencyKey && (args.idempotencyActorId ?? args.data.caller_id)
+            ? await idempotentInvocationId(args.workspaceId, args.idempotencyActorId ?? args.data.caller_id, 'release', args.idempotencyKey)
+            : undefined),
+    }) : null;
+    if (exactClaim?.replayed) {
+        const { invocation } = exactClaim;
+        const settled = await waitForInvocationReplayOutcome(args.db, args.workspaceId, invocation);
+        return markInvocationReplay(invocationAck(settled, { actionName: 'release' }));
+    }
     const [agent] = await args.db
         .select()
         .from(agents)
-        .where(and(eq(agents.workspaceId, args.workspaceId), eq(agents.name, name), ...(expectedTokenHash ? [eq(agents.tokenHash, expectedTokenHash)] : [])));
+        .where(and(eq(agents.workspaceId, args.workspaceId), eq(agents.name, name), ...(expectedAgentId ? [eq(agents.id, expectedAgentId)] : []), ...(expectedTokenHash ? [eq(agents.tokenHash, expectedTokenHash)] : [])));
     if (!agent) {
+        if (expectedAgentId) {
+            await args.db
+                .update(actionInvocations)
+                .set({ status: 'failed', error: RELEASE_IDENTITY_MISMATCH_CODE, completedAt: new Date() })
+                .where(and(eq(actionInvocations.workspaceId, args.workspaceId), eq(actionInvocations.id, exactClaim.invocation.id), inArray(actionInvocations.status, OPEN_INVOCATION_STATUSES)));
+            const [sameName] = await args.db
+                .select({ id: agents.id })
+                .from(agents)
+                .where(and(eq(agents.workspaceId, args.workspaceId), eq(agents.name, name)));
+            if (sameName) {
+                throw codedError(`Agent "${name}" no longer matches the expected immutable identity`, RELEASE_IDENTITY_MISMATCH_CODE, 409);
+            }
+            throw codedError(`Agent "${name}" with expected identity is absent`, RELEASE_IDENTITY_MISMATCH_CODE, 409);
+        }
         if (expectedTokenHash) {
             const [sameName] = await args.db
                 .select({ id: agents.id })
@@ -763,12 +808,17 @@ async function dispatchRelease(args) {
         }
         throw codedError(`Agent "${name}" not found`, 'agent_not_found', 404);
     }
-    const { invocation, replayed } = await createInvocation(args.db, args.workspaceId, null, {
+    // Legacy requests retain their prior behavior: invalid names/generation
+    // guards fail before creating an invocation. Exact requests have already
+    // claimed so their post-release replay survives the tombstone rename.
+    const { invocation, replayed } = exactClaim ?? await createInvocation(args.db, args.workspaceId, null, {
         input,
         caller_id: args.data.caller_id,
         caller_name: args.data.caller_name,
         action_name: 'release',
-        invocation_id: args.invocationId,
+        invocation_id: args.invocationId ?? (args.idempotencyKey && (args.idempotencyActorId ?? args.data.caller_id)
+            ? await idempotentInvocationId(args.workspaceId, args.idempotencyActorId ?? args.data.caller_id, 'release', args.idempotencyKey)
+            : undefined),
     });
     if (replayed) {
         const settled = await waitForInvocationReplayOutcome(args.db, args.workspaceId, invocation);
@@ -790,7 +840,7 @@ async function dispatchRelease(args) {
         AND ${actionInvocations.id} = ${invocation.id}
         AND ${actionInvocations.status} = 'completed'
     )`;
-        const generationStillCurrent = releaseGenerationStillCurrent(args.workspaceId, agent.id, expectedTokenHash);
+        const generationStillCurrent = releaseGenerationStillCurrent(args.workspaceId, agent.id, expectedTokenHash, expectedAgentId);
         const atomicExitNodeId = sql `COALESCE(
       (
         SELECT ${agentNodeBindings.nodeId}
@@ -830,10 +880,10 @@ async function dispatchRelease(args) {
                 .update(actionInvocations)
                 .set({
                 status: 'failed',
-                error: RELEASE_GENERATION_CONFLICT_CODE,
+                error: expectedAgentId ? RELEASE_IDENTITY_MISMATCH_CODE : RELEASE_GENERATION_CONFLICT_CODE,
                 completedAt,
             })
-                .where(and(eq(actionInvocations.workspaceId, args.workspaceId), eq(actionInvocations.id, invocation.id), inArray(actionInvocations.status, OPEN_INVOCATION_STATUSES), expectedTokenHash ? sql `NOT (${generationStillCurrent})` : sql `0`))
+                .where(and(eq(actionInvocations.workspaceId, args.workspaceId), eq(actionInvocations.id, invocation.id), inArray(actionInvocations.status, OPEN_INVOCATION_STATUSES), expectedTokenHash || expectedAgentId ? sql `NOT (${generationStillCurrent})` : sql `0`))
                 .returning({ id: actionInvocations.id }));
             // Win completion and snapshot the current binding before deactivating
             // it. The returned node drives the response and agent.exited event, so a
@@ -910,12 +960,14 @@ async function dispatchRelease(args) {
             })
                 .where(and(eq(agents.workspaceId, args.workspaceId), eq(agents.id, agent.id), ...(expectedTokenHash ? [eq(agents.tokenHash, expectedTokenHash)] : []), invocationCompleted)));
             return writes;
-        }, expectedTokenHash ? { requireAtomic: true } : undefined);
+        }, expectedTokenHash || expectedAgentId ? { requireAtomic: true } : undefined);
         const generationConflict = results[0];
         const completed = results[1];
         const completedExitNodeId = completed[0]?.handlerNodeId ?? null;
-        if (expectedTokenHash && (generationConflict.length > 0 || completed.length === 0)) {
-            throw codedError(`Agent "${name}" no longer matches the expected token generation`, RELEASE_GENERATION_CONFLICT_CODE, 409);
+        if ((expectedTokenHash || expectedAgentId) && (generationConflict.length > 0 || completed.length === 0)) {
+            throw codedError(expectedAgentId
+                ? `Agent "${name}" no longer matches the expected immutable identity`
+                : `Agent "${name}" no longer matches the expected token generation`, expectedAgentId ? RELEASE_IDENTITY_MISMATCH_CODE : RELEASE_GENERATION_CONFLICT_CODE, 409);
         }
         // External completion effects belong after the durable atomic unit: an
         // aborted local reap must never publish agent.exited.
@@ -941,14 +993,14 @@ async function dispatchRelease(args) {
     };
     const failClosed = async () => {
         const completedAt = new Date();
-        if (expectedTokenHash) {
-            const generationStillCurrent = releaseGenerationStillCurrent(args.workspaceId, agent.id, expectedTokenHash);
+        if (expectedTokenHash || expectedAgentId) {
+            const generationStillCurrent = releaseGenerationStillCurrent(args.workspaceId, agent.id, expectedTokenHash, expectedAgentId);
             const results = await runAtomicWrites(args.db, (writeDb) => [
                 writeDb
                     .update(actionInvocations)
                     .set({
                     status: 'failed',
-                    error: RELEASE_GENERATION_CONFLICT_CODE,
+                    error: expectedAgentId ? RELEASE_IDENTITY_MISMATCH_CODE : RELEASE_GENERATION_CONFLICT_CODE,
                     completedAt,
                 })
                     .where(and(eq(actionInvocations.workspaceId, args.workspaceId), eq(actionInvocations.id, invocation.id), inArray(actionInvocations.status, OPEN_INVOCATION_STATUSES), sql `NOT (${generationStillCurrent})`))
@@ -961,7 +1013,9 @@ async function dispatchRelease(args) {
             ], { requireAtomic: true });
             const generationConflict = results[0];
             if (generationConflict.length > 0) {
-                throw codedError(`Agent "${name}" no longer matches the expected token generation`, RELEASE_GENERATION_CONFLICT_CODE, 409);
+                throw codedError(expectedAgentId
+                    ? `Agent "${name}" no longer matches the expected immutable identity`
+                    : `Agent "${name}" no longer matches the expected token generation`, expectedAgentId ? RELEASE_IDENTITY_MISMATCH_CODE : RELEASE_GENERATION_CONFLICT_CODE, 409);
             }
         }
         else {
@@ -1008,20 +1062,22 @@ async function dispatchRelease(args) {
     if (dispatched.settled) {
         if (dispatched.settled.status === 'failed') {
             const errorCode = dispatched.settled.error ?? 'handler_unavailable';
-            throw codedError('Release invocation failed after provider dispatch', errorCode, errorCode === RELEASE_GENERATION_CONFLICT_CODE ? 409 : 503);
+            throw codedError('Release invocation failed after provider dispatch', errorCode, errorCode === RELEASE_GENERATION_CONFLICT_CODE || errorCode === RELEASE_IDENTITY_MISMATCH_CODE ? 409 : 503);
         }
         return invocationAck(dispatched.settled, { actionName: 'release' });
     }
     // The provider can disconnect between the liveness check and send. Complete
     // the DB lifecycle locally instead of creating an ownerless pending request.
     if (!dispatched.accepted) {
-        if (expectedTokenHash) {
+        if (expectedTokenHash || expectedAgentId) {
             const [settled] = await args.db
                 .select({ error: actionInvocations.error })
                 .from(actionInvocations)
                 .where(and(eq(actionInvocations.workspaceId, args.workspaceId), eq(actionInvocations.id, invocation.id)));
-            if (settled?.error === RELEASE_GENERATION_CONFLICT_CODE) {
-                throw codedError(`Agent "${name}" no longer matches the expected token generation`, RELEASE_GENERATION_CONFLICT_CODE, 409);
+            if (settled?.error === RELEASE_GENERATION_CONFLICT_CODE || settled?.error === RELEASE_IDENTITY_MISMATCH_CODE) {
+                throw codedError(expectedAgentId
+                    ? `Agent "${name}" no longer matches the expected immutable identity`
+                    : `Agent "${name}" no longer matches the expected token generation`, expectedAgentId ? RELEASE_IDENTITY_MISMATCH_CODE : RELEASE_GENERATION_CONFLICT_CODE, 409);
             }
             if (settled?.error === 'node_dispatch_unavailable') {
                 throw codedError('Node adapter does not support generation-authorized release dispatch', 'node_dispatch_unavailable', 503);
@@ -1053,6 +1109,8 @@ export async function dispatchAgentRelease(db, workspaceId, data, options = {})
         completionDeps: options.completionDeps,
         workspaceId,
         data,
+        idempotencyKey: options.idempotencyKey,
+        idempotencyActorId: options.idempotencyActorId,
     });
 }
 function spawnResult(invocation, nodeId, dispatched) {
@@ -1532,12 +1590,13 @@ async function completeGuardedReleaseNodeInvocation(db, workspaceId, nodeId, pro
         && AGENT_TOKEN_HASH_PATTERN.test(persistedTokenHash)
         ? persistedTokenHash
         : null;
-    if (!name || !expectedTokenHash) {
+    const expectedAgentId = releaseExpectedAgentId(input);
+    if (!name || (!expectedTokenHash && !expectedAgentId)) {
         const [failed] = await db
             .update(actionInvocations)
             .set({
             status: 'failed',
-            error: RELEASE_GENERATION_CONFLICT_CODE,
+            error: expectedAgentId ? RELEASE_IDENTITY_MISMATCH_CODE : RELEASE_GENERATION_CONFLICT_CODE,
             completedAt: new Date(),
             spawnReservedAt: null,
         })
@@ -1548,13 +1607,13 @@ async function completeGuardedReleaseNodeInvocation(db, workspaceId, nodeId, pro
     const [agent] = await db
         .select()
         .from(agents)
-        .where(and(eq(agents.workspaceId, workspaceId), eq(agents.name, name)));
+        .where(and(eq(agents.workspaceId, workspaceId), eq(agents.name, name), ...(expectedAgentId ? [eq(agents.id, expectedAgentId)] : [])));
     if (!agent) {
         const [failed] = await db
             .update(actionInvocations)
             .set({
             status: 'failed',
-            error: RELEASE_GENERATION_CONFLICT_CODE,
+            error: expectedAgentId ? RELEASE_IDENTITY_MISMATCH_CODE : RELEASE_GENERATION_CONFLICT_CODE,
             completedAt: new Date(),
             spawnReservedAt: null,
         })
@@ -1563,7 +1622,7 @@ async function completeGuardedReleaseNodeInvocation(db, workspaceId, nodeId, pro
         return failed ? publicInvocation(failed) : null;
     }
     const completedAt = new Date();
-    const generationStillCurrent = releaseGenerationStillCurrent(workspaceId, agent.id, expectedTokenHash);
+    const generationStillCurrent = releaseGenerationStillCurrent(workspaceId, agent.id, expectedTokenHash, expectedAgentId);
     const activeBindingStillCurrent = sql `EXISTS (
     SELECT 1 FROM ${agentNodeBindings}
     WHERE ${agentNodeBindings.workspaceId} = ${workspaceId}
@@ -1601,7 +1660,7 @@ async function completeGuardedReleaseNodeInvocation(db, workspaceId, nodeId, pro
             .update(actionInvocations)
             .set({
             status: 'failed',
-            error: RELEASE_GENERATION_CONFLICT_CODE,
+            error: expectedAgentId ? RELEASE_IDENTITY_MISMATCH_CODE : RELEASE_GENERATION_CONFLICT_CODE,
             completedAt,
             spawnReservedAt: null,
         })
@@ -1637,7 +1696,7 @@ async function completeGuardedReleaseNodeInvocation(db, workspaceId, nodeId, pro
         })
             .where(and(eq(actionInvocations.workspaceId, workspaceId), eq(actionInvocations.id, invocation.id), eq(actionInvocations.dispatchedNodeId, nodeId), eq(actionInvocations.dispatchedProvider, providerName), inArray(actionInvocations.status, OPEN_INVOCATION_STATUSES), generationStillCurrent))
             .returning());
-        const currentAgent = and(eq(agents.workspaceId, workspaceId), eq(agents.id, agent.id), eq(agents.name, name), eq(agents.tokenHash, expectedTokenHash), invocationCompleted);
+        const currentAgent = and(eq(agents.workspaceId, workspaceId), eq(agents.id, agent.id), eq(agents.name, name), ...(expectedTokenHash ? [eq(agents.tokenHash, expectedTokenHash)] : []), invocationCompleted);
         if (input.delete_agent === true) {
             writes.push(writeDb
                 .update(agents)
@@ -2004,12 +2063,18 @@ async function dispatchNodeInvocation(args) {
     const guardedReleaseHash = args.invocationOrigin === 'builtin' && isReleaseInvocation(args.action)
         ? releaseExpectedTokenHash(args.input)
         : null;
-    if (guardedReleaseHash) {
+    const guardedReleaseAgentId = args.invocationOrigin === 'builtin' && isReleaseInvocation(args.action)
+        ? releaseExpectedAgentId(args.input)
+        : null;
+    const releaseConflictCode = guardedReleaseAgentId
+        ? RELEASE_IDENTITY_MISMATCH_CODE
+        : RELEASE_GENERATION_CONFLICT_CODE;
+    if (guardedReleaseHash || guardedReleaseAgentId) {
         const name = typeof args.input.name === 'string' ? args.input.name : '';
         const [current] = await args.db
             .select({ id: agents.id })
             .from(agents)
-            .where(and(eq(agents.workspaceId, args.workspaceId), eq(agents.name, name), eq(agents.tokenHash, guardedReleaseHash), sql `EXISTS (
+            .where(and(eq(agents.workspaceId, args.workspaceId), eq(agents.name, name), ...(guardedReleaseHash ? [eq(agents.tokenHash, guardedReleaseHash)] : []), ...(guardedReleaseAgentId ? [eq(agents.id, guardedReleaseAgentId)] : []), sql `EXISTS (
             SELECT 1 FROM ${agentNodeBindings}
             WHERE ${agentNodeBindings.workspaceId} = ${args.workspaceId}
               AND ${agentNodeBindings.agentId} = ${agents.id}
@@ -2021,7 +2086,7 @@ async function dispatchNodeInvocation(args) {
                 .update(actionInvocations)
                 .set({
                 status: 'failed',
-                error: RELEASE_GENERATION_CONFLICT_CODE,
+                error: releaseConflictCode,
                 completedAt: new Date(),
             })
                 .where(and(eq(actionInvocations.workspaceId, args.workspaceId), eq(actionInvocations.id, args.invocationId), inArray(actionInvocations.status, OPEN_INVOCATION_STATUSES)));
@@ -2099,15 +2164,19 @@ async function dispatchNodeInvocation(args) {
                 invocationActionName: registeredNodeClaim.actionName,
                 actionName: args.action,
             }) ?? false)
-            : guardedReleaseHash
+            : guardedReleaseHash || guardedReleaseAgentId
                 ? await (args.registry.sendAuthorizedActionToProvider?.(args.workspaceId, args.nodeId, args.providerName, frame, {
                     kind: 'release-generation-v1',
                     invocationId: args.invocationId,
                     agentName: typeof args.input.name === 'string' ? args.input.name : '',
-                    expectedTokenHash: guardedReleaseHash,
+                    ...(guardedReleaseHash && guardedReleaseAgentId
+                        ? { expectedTokenHash: guardedReleaseHash, expectedAgentId: guardedReleaseAgentId }
+                        : guardedReleaseHash
+                            ? { expectedTokenHash: guardedReleaseHash }
+                            : { expectedAgentId: guardedReleaseAgentId }),
                 }) ?? false)
                 : await args.registry.sendToProvider(args.workspaceId, args.nodeId, args.providerName, frame);
-    if (!sent && guardedReleaseHash) {
+    if (!sent && (guardedReleaseHash || guardedReleaseAgentId)) {
         // An adapter compiled against the older owner-authorization contract may
         // expose the method but reject the new proof kind. Settle any still-open
         // row before the caller considers local fallback, so a guarded delete can
@@ -2163,7 +2232,7 @@ async function dispatchNodeInvocation(args) {
         const settled = await settleDeletedRegisteredAction(args.db, args.workspaceId, args.invocationId);
         return { accepted: false, pending: false, sent: true, settled };
     }
-    if (!accepted && guardedReleaseHash) {
+    if (!accepted && (guardedReleaseHash || guardedReleaseAgentId)) {
         const [settled] = await args.db
             .select()
             .from(actionInvocations)
@@ -2637,7 +2706,7 @@ export async function completeNodeInvocation(db, registry, workspaceId, nodeId,
     const existingInput = recordInput(existing.input);
     if (!data.error
         && isBuiltinReleaseInvocation(existing)
-        && existingInput.expected_token_hash !== undefined) {
+        && (existingInput.expected_token_hash !== undefined || existingInput.expected_agent_id !== undefined)) {
         return completeGuardedReleaseNodeInvocation(db, workspaceId, nodeId, providerName, existing, data, deps);
     }
     const [updated] = await db