@agent-native/core 0.203.2-nightly-20261007213109 → 0.204.0

package/dist/a2a/handlers.js

@@ -2,6 +2,8 @@ import crypto from "node:crypto";
 import { setResponseHeader, setResponseStatus } from "h3";
 import { AGENT_BACKGROUND_PROCESSOR_A2A, AGENT_BACKGROUND_PROCESSOR_FIELD, dispatchPathTargetsNetlifyBackgroundFunction, isAgentChatDurableBackgroundEnabled, resolveAgentChatProcessRunDispatchPath, } from "../agent/durable-background.js";
 import { trackingIdentityProperties } from "../observability/tracking-identity.js";
+import { parseServiceIdentityEmail } from "../org/service-identity.js";
+import { assertServicePrincipalMayRun, recordServicePrincipalDenial, ServicePrincipalRefusedError, } from "../org/service-principal-guard.js";
 import { findWorkspaceDispatchAgent } from "../server/agent-discovery.js";
 import { withConfiguredAppBasePath } from "../server/app-base-path.js";
 import { getOrigin, isConfiguredAppOrigin } from "../server/google-oauth.js";
@@ -12,7 +14,7 @@ import { track } from "../tracking/registry.js";
 import { hasConfiguredA2ASecret, isA2AProductionRuntime, } from "./auth-policy.js";
 import { callAction } from "./client.js";
 import { sanitizeA2ACorrelationMetadata } from "./correlation.js";
-import { createTask, createOrReuseTask, getTask, getTaskOwnership, updateTask, claimA2ATaskForProcessing, getA2ATaskDispatchState, failStuckA2ATask, failStuckQueuedA2ATask, settleProcessingA2ATask, touchQueuedA2ATaskDispatch, touchProcessingA2ATask, pauseProcessingA2ATask, MAX_A2A_IDEMPOTENCY_KEY_CHARS, A2A_PERSONAL_OWNER_SCOPE, A2A_ORG_ID_OWNER_SCOPE_PREFIX, } from "./task-store.js";
+import { createTask, createOrReuseTask, getTask, getTaskOwnership, updateTask, claimA2ATaskForProcessing, getA2ATaskDispatchState, failStuckA2ATask, failStuckQueuedA2ATask, settleProcessingA2ATask, resetStuckA2ATaskForRetry, touchQueuedA2ATaskDispatch, touchProcessingA2ATask, pauseProcessingA2ATask, MAX_A2A_IDEMPOTENCY_KEY_CHARS, A2A_PERSONAL_OWNER_SCOPE, A2A_ORG_ID_OWNER_SCOPE_PREFIX, } from "./task-store.js";
 const A2A_PROCESS_TASK_PATH = "/_agent-native/a2a/_process-task";
 const PORTABLE_FALLBACK_HANDOFF_TIMEOUT_MS = 1_000;
 const A2A_QUEUED_DISPATCH_STUCK_AFTER_MS = 10_000;
@@ -246,6 +248,38 @@ export async function processA2ATaskFromQueue(taskId, config, event) {
     const verifiedOrgId = typeof processorMeta.verifiedOrgId === "string"
         ? processorMeta.verifiedOrgId.trim()
         : undefined;
+    let servicePrincipalAllowedActions;
+    try {
+        const admission = await assertServicePrincipalMayRun(verifiedEmail, verifiedOrgId);
+        if (parseServiceIdentityEmail(verifiedEmail)) {
+            servicePrincipalAllowedActions = admission.allowedActions;
+        }
+    }
+    catch (error) {
+        if (!(error instanceof ServicePrincipalRefusedError))
+            throw error;
+        if (error.statusCode === 503) {
+            await resetStuckA2ATaskForRetry(taskId, Date.now());
+            throw error;
+        }
+        if (error.statusCode !== 403)
+            throw error;
+        await recordServicePrincipalDenial({
+            email: verifiedEmail,
+            orgId: verifiedOrgId,
+            actionName: "a2a:process-task",
+            caller: "a2a",
+            error,
+        });
+        await settleProcessingA2ATask(taskId, {
+            state: "failed",
+            message: {
+                role: "agent",
+                parts: [{ type: "text", text: error.message }],
+            },
+        });
+        return;
+    }
     const requestOrigin = requestOriginFromMetadata(processorMeta) ?? requestOriginFromEvent(event);
     const contextId = processorMeta.contextId ?? undefined;
     const callerMetadata = processorMeta.callerMetadata ?? undefined;
@@ -261,6 +295,10 @@ export async function processA2ATaskFromQueue(taskId, config, event) {
             event.context.__a2aOrgDomain = orgDomainHint;
         if (verifiedOrgId)
             event.context.__a2aVerifiedOrgId = verifiedOrgId;
+        if (servicePrincipalAllowedActions !== undefined) {
+            event.context.__a2aServicePrincipalAllowedActions =
+                servicePrincipalAllowedActions;
+        }
         if (verifiedEmail && !resolvedOrgId)
             markExplicitPersonalOrgScope(event);
     }
@@ -294,6 +332,24 @@ export async function processA2ATaskFromQueue(taskId, config, event) {
     }
 }
 const defaultHandler = async (message, context) => {
+    const eventContext = context.event?.context;
+    const verifiedEmail = typeof eventContext?.__a2aVerifiedEmail === "string"
+        ? eventContext.__a2aVerifiedEmail
+        : undefined;
+    const serviceIdentity = parseServiceIdentityEmail(verifiedEmail);
+    if (serviceIdentity) {
+        const error = new ServicePrincipalRefusedError("service_principal_handoff_unsupported", "The default A2A chat handoff cannot preserve service-principal authorization. Use a service-aware A2A handler.");
+        await recordServicePrincipalDenial({
+            email: verifiedEmail,
+            orgId: typeof eventContext?.__a2aVerifiedOrgId === "string"
+                ? eventContext.__a2aVerifiedOrgId
+                : undefined,
+            actionName: "a2a:agent-chat-handoff",
+            caller: "a2a",
+            error,
+        });
+        throw error;
+    }
     const text = message.parts
         .filter((p) => p.type === "text")
         .map((p) => p.text)

package/dist/a2a/server.js

@@ -3,6 +3,8 @@ import * as jose from "jose";
 import "../authorization/check-action.js";
 import { redactArgsToJson } from "../audit/redact.js";
 import { extractBearerToken, verifyInternalToken, } from "../integrations/internal-token.js";
+import { parseServiceIdentityEmail } from "../org/service-identity.js";
+import { assertServicePrincipalMayRun, recordServicePrincipalDenial, ServicePrincipalRefusedError, } from "../org/service-principal-guard.js";
 import { readDeployCredentialEnv } from "../server/credential-provider.js";
 import { getH3App } from "../server/framework-request-handler.js";
 import { publicFrameworkPath } from "../server/framework-route-prefix.js";
@@ -462,7 +464,7 @@ export function mountA2A(nitroApp, config, routePrefix = "/_agent-native") {
         }
         catch (err) {
             console.error("[a2a] process-task failed:", err);
-            setResponseStatus(event, 500);
+            setResponseStatus(event, err instanceof ServicePrincipalRefusedError ? err.statusCode : 500);
             return { error: err?.message ?? "process-task failed" };
         }
     }));
@@ -480,6 +482,7 @@ export function mountA2A(nitroApp, config, routePrefix = "/_agent-native") {
         let verifiedOrgDomain = null;
         let verifiedOrgId;
         let verifiedIdentityAssurance;
+        let servicePrincipalAllowedActions;
         let verifiedAudienceBound = false;
         let legacyApiKeyAuthenticated = false;
         let bearerTokenVerified = false;
@@ -512,6 +515,35 @@ export function mountA2A(nitroApp, config, routePrefix = "/_agent-native") {
                     },
                 };
             }
+            try {
+                const admission = await assertServicePrincipalMayRun(tokenPayload.email, verifiedOrgId);
+                if (parseServiceIdentityEmail(tokenPayload.email)) {
+                    servicePrincipalAllowedActions = admission.allowedActions;
+                }
+            }
+            catch (error) {
+                if (!(error instanceof ServicePrincipalRefusedError))
+                    throw error;
+                if (error.statusCode === 403) {
+                    await recordServicePrincipalDenial({
+                        email: tokenPayload.email,
+                        orgId: verifiedOrgId,
+                        actionName: "a2a:admission",
+                        caller: "a2a",
+                        error,
+                    });
+                }
+                setResponseStatus(event, error.statusCode);
+                return {
+                    jsonrpc: "2.0",
+                    id: null,
+                    error: {
+                        code: error.statusCode === 503 ? -32003 : -32001,
+                        message: error.message,
+                        data: { errorCode: error.errorCode },
+                    },
+                };
+            }
             verifiedCallerEmail = tokenPayload.email;
             verifiedOrgDomain = tokenPayload.orgDomain;
             verifiedIdentityAssurance = tokenPayload.email
@@ -601,6 +633,10 @@ export function mountA2A(nitroApp, config, routePrefix = "/_agent-native") {
         if (verifiedOrgId) {
             event.context.__a2aVerifiedOrgId = verifiedOrgId;
         }
+        if (servicePrincipalAllowedActions !== undefined) {
+            event.context.__a2aServicePrincipalAllowedActions =
+                servicePrincipalAllowedActions;
+        }
         const body = await readBody(event);
         return handleJsonRpcH3(body, event, config);
     }));

package/dist/action.d.ts

@@ -230,6 +230,7 @@ export interface ActionMcpToolAnnotations {
     readOnlyHint: boolean;
     destructiveHint: boolean;
     openWorldHint: boolean;
+    idempotentHint?: boolean;
 }
 interface DefineActionWithSchema<TSchema extends StandardSchemaV1, TReturn = any, TOutputSchema extends StandardSchemaV1 | undefined = undefined> {
     title?: string;

package/dist/action.js

@@ -1,6 +1,7 @@
 import { normalizeActionChatUIConfig, } from "./action-ui.js";
 import { normalizeAuditConfig, resolveAuditAttach } from "./audit/config.js";
 import { assertRegisteredActionAccess, } from "./authorization/action-access-runtime.js";
+import { parseServiceIdentityEmail } from "./org/service-identity.js";
 import { wrapRunWithActionTracking } from "./tracking/action-lifecycle.js";
 export class ActionContractError extends Error {
     actionContractError = true;
@@ -136,7 +137,7 @@ export function defineAction(options) {
     const finalRun = resolveAuditAttach(auditConfig, readOnly)
         ? wrapRunWithAudit(run, auditConfig)
         : run;
-    const trackedRun = wrapRunWithActionTracking(finalRun, readOnly);
+    const trackedRun = wrapRunWithServicePrincipalGrant(wrapRunWithActionTracking(finalRun, readOnly));
     const toolCallable = typeof options.toolCallable === "boolean"
         ? options.toolCallable
         : undefined;
@@ -149,10 +150,12 @@ export function defineAction(options) {
             !Array.isArray(options.mcpAnnotations) &&
             typeof options.mcpAnnotations.readOnlyHint === "boolean" &&
             typeof options.mcpAnnotations.destructiveHint === "boolean" &&
-            typeof options.mcpAnnotations.openWorldHint === "boolean"
+            typeof options.mcpAnnotations.openWorldHint === "boolean" &&
+            (options.mcpAnnotations.idempotentHint === undefined ||
+                typeof options.mcpAnnotations.idempotentHint === "boolean")
             ? options.mcpAnnotations
             : (() => {
-                throw new TypeError("mcpAnnotations must define boolean readOnlyHint, destructiveHint, and openWorldHint values.");
+                throw new TypeError("mcpAnnotations must define boolean readOnlyHint, destructiveHint, and openWorldHint values; idempotentHint is an optional boolean.");
             })();
     const deferLoading = typeof options.deferLoading === "boolean"
         ? options.deferLoading
@@ -302,6 +305,26 @@ function wrapRunWithAccess(run, access, authorize) {
         return run(args, ctx);
     };
 }
+/**
+ * Outermost wrapper, so a refused call is audited once as a denial and never
+ * as a failed run of the action. Every route to running an action as a service
+ * identity (MCP, HTTP, delegated agent runs, sandbox bridges) passes here.
+ */
+function wrapRunWithServicePrincipalGrant(run) {
+    return function grantCheckedRun(args, ctx) {
+        if (!parseServiceIdentityEmail(ctx?.userEmail))
+            return run(args, ctx);
+        return import("./org/service-principal-guard.js")
+            .then(({ enforceServicePrincipalActionGrant }) => enforceServicePrincipalActionGrant({
+            email: ctx.userEmail,
+            orgId: ctx.orgId,
+            // A missing name only passes an unrestricted grant.
+            actionName: ctx.actionName ?? "",
+            caller: ctx.caller,
+        }))
+            .then(() => run(args, ctx));
+    };
+}
 function wrapRunWithAudit(run, auditConfig) {
     return async function auditedRun(args, ctx) {
         let result;

package/dist/agent/contain-principal.d.ts

@@ -0,0 +1,9 @@
+/** Terminal reason recorded on the aborted runs; the client shows it as a stopped run. */
+export declare const PRINCIPAL_SUSPENDED_ABORT_REASON = "principal-suspended";
+export interface ContainmentResult {
+    abortedRuns: number;
+    /** One entry per run that could not be confirmed stopped. Empty means contained. */
+    containmentErrors: string[];
+}
+export declare function prepareServicePrincipalContainment(): Promise<void>;
+export declare function containServicePrincipal(orgId: string, serviceName: string, reason?: string): Promise<ContainmentResult>;

package/dist/agent/contain-principal.js

@@ -0,0 +1,53 @@
+/**
+ * Stop the in-flight agent runs a service principal owns.
+ *
+ * Suspending a principal blocks NEW work at admission, but a run that started
+ * before the suspend keeps spending its tool budget until it ends. Containment
+ * aborts those runs so "suspended" means stopped, not "stops eventually".
+ *
+ * A run's owner is its chat thread's `owner_email`. `abortRunDurably` logs and
+ * swallows a failed SQL write, so the outcome is re-read from `agent_runs`:
+ * only a confirmed `aborted` status counts as aborted.
+ */
+import { ensureChatThreadTables } from "../chat-threads/store.js";
+import { getDbExec } from "../db/client.js";
+import { serviceIdentityEmail } from "../mcp/connect-store.js";
+import { abortRunDurably } from "./run-manager.js";
+import { ensureRunTables, getRunStatus } from "./run-store.js";
+/** Terminal reason recorded on the aborted runs; the client shows it as a stopped run. */
+export const PRINCIPAL_SUSPENDED_ABORT_REASON = "principal-suspended";
+export async function prepareServicePrincipalContainment() {
+    await ensureRunTables();
+    await ensureChatThreadTables();
+}
+export async function containServicePrincipal(orgId, serviceName, reason = PRINCIPAL_SUSPENDED_ABORT_REASON) {
+    const email = serviceIdentityEmail(serviceName, orgId).toLowerCase();
+    await prepareServicePrincipalContainment();
+    const { rows } = await getDbExec().execute({
+        sql: `SELECT r.id FROM agent_runs r
+          JOIN chat_threads t ON t.id = r.thread_id
+          WHERE r.status = 'running' AND LOWER(t.owner_email) = ?`,
+        args: [email],
+    });
+    const result = { abortedRuns: 0, containmentErrors: [] };
+    for (const row of rows) {
+        const runId = String(row.id);
+        try {
+            await abortRunDurably(runId, reason);
+            const status = await getRunStatus(runId);
+            if (status === "aborted") {
+                result.abortedRuns += 1;
+            }
+            else if (status === "running") {
+                result.containmentErrors.push(`${runId}: still running after abort`);
+            }
+            else {
+                result.containmentErrors.push(`${runId}: ${status ?? "unknown"} after abort; not confirmed aborted`);
+            }
+        }
+        catch (error) {
+            result.containmentErrors.push(`${runId}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return result;
+}

package/dist/agent/production-agent.js

@@ -24,6 +24,8 @@ import { isMcpToolAllowedForRequest } from "../mcp-client/visibility.js";
 import { isObjectOnly } from "../mcp/tool-input-schema.js";
 import { describeSettingsViewForAgent, SETTINGS_VIEW_STATE_KEY, } from "../navigation/settings-redirects.js";
 import { shouldInferSentimentForTurn } from "../observability/sentiment.js";
+import { parseServiceIdentityEmail } from "../org/service-identity.js";
+import { ServicePrincipalRefusedError } from "../org/service-principal-guard.js";
 import { completeRun as completeProgressRun, startRun as startProgressRun, updateRunProgress, } from "../progress/registry.js";
 import { readOptionalKeyCache, writeOptionalKeyCache, } from "../secrets/optional-key-cache.js";
 import { COMPACT_PROMPT_RESOURCES_TOTAL_MAX_CHARS, preloadJevContextForPrompt, } from "../server/agent-chat/prompt-resources.js";
@@ -4696,6 +4698,28 @@ export async function runAgentLoop(opts) {
                     isError: true,
                 };
             }
+            // Before approval, so a human is never asked to approve a call the
+            // principal's grant already forbids. Covers framework tools that bypass
+            // `defineAction`, which enforces the same grant for the actions.
+            const userEmail = opts.ownerEmail ?? getRequestUserEmail();
+            if (parseServiceIdentityEmail(userEmail)) {
+                const { enforceServicePrincipalActionGrant, ServicePrincipalRefusedError, } = await import("../org/service-principal-guard.js");
+                try {
+                    await enforceServicePrincipalActionGrant({
+                        email: userEmail,
+                        orgId: opts.orgId ?? getRequestOrgId() ?? null,
+                        actionName: toolCall.name,
+                        caller: opts.actionCaller ?? "tool",
+                    });
+                }
+                catch (error) {
+                    if (!(error instanceof ServicePrincipalRefusedError) ||
+                        error.statusCode !== 403) {
+                        throw error;
+                    }
+                    return declineToolCall(error.message);
+                }
+            }
             const approvalKey = toolCallCacheKey(toolCall.name, toolCall.input);
             const approvalBinding = {
                 toolName: toolCall.name,
@@ -6401,7 +6425,8 @@ export async function chainServerDrivenContinuation(opts) {
         }
         catch (insertErr) {
             if (insertErr instanceof AgentTurnInitiatorMismatchError ||
-                insertErr instanceof AgentTurnInitiatorUnavailableError) {
+                insertErr instanceof AgentTurnInitiatorUnavailableError ||
+                insertErr instanceof ServicePrincipalRefusedError) {
                 throw insertErr;
             }
             await d
@@ -7785,6 +7810,8 @@ export function createProductionAgentHandler(options) {
                     backgroundRowInserted = true;
                 }
                 catch (err) {
+                    if (err instanceof ServicePrincipalRefusedError)
+                        throw err;
                     console.error("[agent-chat] background insertRun failed; falling back to inline:", err instanceof Error ? err.message : err);
                 }
             }
@@ -8042,7 +8069,10 @@ export function createProductionAgentHandler(options) {
                     await insertRun(runId, effectiveThreadId, effectiveTurnId, {
                         dispatchMode: "background",
                         ...(turnInitiator ? { turnInitiator } : {}),
-                    }).catch(() => { });
+                    }).catch((error) => {
+                        if (error instanceof ServicePrincipalRefusedError)
+                            throw error;
+                    });
                 }
                 const won = await claimBackgroundRun(runId);
                 if (!won) {

package/dist/agent/run-manager.js

@@ -1,6 +1,8 @@
 import { getAppConfig } from "../app-config/index.js";
 import { BACKGROUND_AUTOMATION_SOFT_TIMEOUT_HEADROOM_MS, BACKGROUND_SOFT_TIMEOUT_CEILING_MS, RUN_NO_PROGRESS_HARD_TIMEOUT_MS, } from "../app-config/run-lifecycle-invariants.js";
 import { recordAgentRun } from "../observability/metrics.js";
+import { parseServiceIdentityEmail } from "../org/service-identity.js";
+import { ServicePrincipalRefusedError } from "../org/service-principal-guard.js";
 import { captureError } from "../server/capture-error.js";
 import { isLlmCredentialError, LLM_MISSING_CREDENTIALS_ERROR_CODE, LLM_MISSING_CREDENTIALS_MESSAGE, } from "./engine/credential-errors.js";
 import { classifyTerminalErrorCode, describeErrorWithCauses, isProviderConnectionError, } from "./engine/error-detail.js";
@@ -556,12 +558,16 @@ export function startRun(runId, threadId, runFn, onComplete, options) {
                 : {}),
         }
         : undefined;
-    const insertRunPromise = (options?.runRowAlreadyInserted
+    const servicePrincipalRunStart = Boolean(options?.turnInitiator &&
+        parseServiceIdentityEmail(options.turnInitiator.email));
+    const insertRunPromise = (options?.runRowAlreadyInserted && !servicePrincipalRunStart
         ? Promise.resolve()
         : insertOptions
             ? insertRun(runId, threadId, options?.turnId, insertOptions)
             : insertRun(runId, threadId, options?.turnId)).catch((error) => {
         captureRunPersistenceError(error, "insert-run");
+        if (error instanceof ServicePrincipalRefusedError)
+            throw error;
     });
     let persistenceChain = Promise.resolve();
     const PROGRESS_BUMP_INTERVAL_MS = 1_000;
@@ -1068,7 +1074,13 @@ export function startRun(runId, threadId, runFn, onComplete, options) {
         }
         void emitRunEvent(runEvent);
     };
-    const runPromise = runFn(send, runControl.chunkSignal, runControl)
+    const runPromise = (servicePrincipalRunStart
+        ? insertRunPromise.then(() => {
+            if (!abort.signal.aborted) {
+                return runFn(send, runControl.chunkSignal, runControl);
+            }
+        })
+        : runFn(send, runControl.chunkSignal, runControl))
         .then(() => {
         settleBoundary(false);
         if (abort.signal.aborted) {

package/dist/agent/run-store.js

@@ -3,6 +3,7 @@ import { isArtifactReceipt, } from "../artifacts/detect.js";
 import { getDbExec } from "../db/client.js";
 import { ensureColumnExists, ensureTableExists } from "../db/ddl-guard.js";
 import { widenIntColumnsToBigInt } from "../db/widen-columns.js";
+import { lockAndAssertServicePrincipalMayStartRun, prepareServicePrincipalRunStart, recordServicePrincipalDenial, } from "../org/service-principal-guard.js";
 import { captureError } from "../server/capture-error.js";
 import { isRequestedStopAbortReason } from "./abort-reasons.js";
 import { admitAutoContinue, } from "./auto-continue.js";
@@ -435,11 +436,34 @@ export async function insertRun(id, threadId, turnId, options) {
             (await nextContinuationOrder(client, threadId, logicalTurnId)));
         return;
     }
-    await client.transaction(async (tx) => {
+    if (options?.turnInitiator) {
+        await prepareServicePrincipalRunStart(options.turnInitiator);
+    }
+    const refusal = await client.transaction(async (tx) => {
+        if (options?.turnInitiator) {
+            const denied = await lockAndAssertServicePrincipalMayStartRun(tx, {
+                email: options.turnInitiator.email,
+                orgId: options.turnInitiator.orgId,
+            });
+            if (denied)
+                return denied;
+        }
         await lockContinuationOrder(tx, threadId, logicalTurnId);
         await insert(tx, explicitContinuationOrder ??
             (await nextContinuationOrder(tx, threadId, logicalTurnId)));
+        return undefined;
     });
+    if (refusal) {
+        if (options?.turnInitiator) {
+            await recordServicePrincipalDenial({
+                ...options.turnInitiator,
+                actionName: "agent-run:start",
+                caller: "agent-run",
+                error: refusal,
+            });
+        }
+        throw refusal;
+    }
 }
 function normalizeContinuationOrder(value) {
     if (value === undefined)
@@ -790,7 +814,18 @@ export async function tryClaimRunSlot(threadId, runId, maxStaleMs, options) {
     if (!client.transaction) {
         throw new Error("Atomic run-slot claims require transaction support");
     }
-    return client.transaction(async (tx) => {
+    if (options?.turnInitiator) {
+        await prepareServicePrincipalRunStart(options.turnInitiator);
+    }
+    const transactionResult = await client.transaction(async (tx) => {
+        if (options?.turnInitiator) {
+            const denied = await lockAndAssertServicePrincipalMayStartRun(tx, {
+                email: options.turnInitiator.email,
+                orgId: options.turnInitiator.orgId,
+            });
+            if (denied)
+                return { refused: denied };
+        }
         await tx.execute({
             sql: "SELECT pg_advisory_xact_lock(hashtextextended(?, 0::bigint))",
             args: [`agent-native:run-slot:${threadId}`],
@@ -801,14 +836,17 @@ export async function tryClaimRunSlot(threadId, runId, maxStaleMs, options) {
             args: [threadId, turnId],
         });
         if (abortMarker.rows.length > 0) {
-            return { claimed: false, activeRunId: null, turnAborted: true };
+            return {
+                result: { claimed: false, activeRunId: null, turnAborted: true },
+            };
         }
         if (options?.turnInitiator) {
             await bindTurnInitiator(tx, threadId, turnId, runId, options.turnInitiator);
         }
         const activeRunId = await selectSlotHoldingRunId(tx, threadId, now, maxStaleMs);
-        if (activeRunId)
-            return { claimed: false, activeRunId };
+        if (activeRunId) {
+            return { result: { claimed: false, activeRunId } };
+        }
         if (replayCompletedTurn) {
             const latest = await tx.execute({
                 sql: `SELECT id,
@@ -837,9 +875,11 @@ export async function tryClaimRunSlot(threadId, runId, maxStaleMs, options) {
             const latestRun = latest.rows[0];
             if (latestRun?.id && latestRun.has_terminal_event === true) {
                 return {
-                    claimed: false,
-                    activeRunId: null,
-                    completedRunId: latestRun.id,
+                    result: {
+                        claimed: false,
+                        activeRunId: null,
+                        completedRunId: latestRun.id,
+                    },
                 };
             }
         }
@@ -875,9 +915,11 @@ export async function tryClaimRunSlot(threadId, runId, maxStaleMs, options) {
             });
             if (!admission.admit) {
                 return {
-                    claimed: false,
-                    activeRunId: null,
-                    autoContinueRefused: admission.code,
+                    result: {
+                        claimed: false,
+                        activeRunId: null,
+                        autoContinueRefused: admission.code,
+                    },
                 };
             }
         }
@@ -901,8 +943,20 @@ export async function tryClaimRunSlot(threadId, runId, maxStaleMs, options) {
         if ((inserted.rowsAffected ?? 0) !== 1) {
             throw new Error(`Failed to insert claimed run ${runId}`);
         }
-        return { claimed: true, activeRunId: null };
+        return { result: { claimed: true, activeRunId: null } };
     });
+    if ("refused" in transactionResult && transactionResult.refused) {
+        if (options?.turnInitiator) {
+            await recordServicePrincipalDenial({
+                ...options.turnInitiator,
+                actionName: "agent-run:start",
+                caller: "agent-run",
+                error: transactionResult.refused,
+            });
+        }
+        throw transactionResult.refused;
+    }
+    return transactionResult.result;
 }
 export async function setRunError(runId, errorCode, errorDetail) {
     if (!errorCode && !errorDetail)

package/dist/audit/actions/export-audit-events.d.ts

@@ -2,7 +2,7 @@ declare const _default: import("../../action.js").ActionDefinition<{
     scope?: "accessible" | "organization";
     targetType?: string;
     targetId?: string;
-    actorKind?: "agent" | "human" | "system";
+    actorKind?: "agent" | "human" | "service" | "system";
     actorEmail?: string;
     status?: "denied" | "error" | "success";
     threadId?: string;

package/dist/audit/actions/export-audit-events.js

@@ -56,9 +56,9 @@ export default defineAction({
             .optional()
             .describe("Filter to one resource id (pair with targetType)."),
         actorKind: z
-            .enum(["agent", "human", "system"])
+            .enum(["agent", "human", "service", "system"])
             .optional()
-            .describe("Filter to changes made by the agent, a human, or the system."),
+            .describe("Filter to changes made by an agent, human, service principal, or the system."),
         actorEmail: z.string().optional().describe("Filter to one actor's email."),
         status: z
             .enum(["success", "error", "denied"])

package/dist/audit/actions/export-audit-ocsf.d.ts

@@ -0,0 +1,11 @@
+declare const _default: import("../../action.js").ActionDefinition<{
+    since?: string | number;
+    until?: string | number;
+    cursor?: string;
+    limit?: number;
+}, {
+    events: import("../ocsf.js").OcsfApiActivity[];
+    hasMore: boolean;
+    nextCursor: string;
+}>;
+export default _default;