@raybase/core 0.0.2 → 0.3.3

package/dist/actions.js

@@ -0,0 +1,661 @@
+import { disabledRaybaseAI } from "./ai.js";
+import { authSecret, createRaybaseAuthContextRuntime, unsupportedRaybaseAuthContextRuntime } from "./auth.js";
+import { normalizeNamedDefinitions } from "./internal.js";
+import { jsonSchemaFor, parseWithSchema, restoreStrictModelValue, strictToolParameters } from "./json-schema.js";
+import { unsupportedRaybaseJobsRuntime } from "./jobs.js";
+import { evaluatePolicy, serializePolicyExpression } from "./policies.js";
+import { principalOnBehalfOf } from "./principal.js";
+/**
+ * Normalizes an agent's `actions` entries to
+ * `{ action, offerWhen?, disclosure? }`. Every consumer of an agent's
+ * registered actions routes through this, so no call site sees a binding
+ * where it expects a bare action. Registry, admin, and permission consumers
+ * use the full set; only model-facing tool assembly applies presentation
+ * rules. Malformed entries throw here, which surfaces at `defineAgent` time
+ * through the tool-name validators.
+ */
+export function agentActionRegistrations(actions) {
+    return (actions ?? []).map((entry) => {
+        if (entry && typeof entry === "object" && typeof entry.handler === "function") {
+            return { action: entry };
+        }
+        const binding = entry;
+        const action = binding && typeof binding === "object" ? binding.action : undefined;
+        if (!action || typeof action !== "object" || typeof action.name !== "string" || typeof action.handler !== "function") {
+            throw new Error("Raybase agent actions entries must be defined actions or { action, offerWhen?, disclosure? } bindings");
+        }
+        if (binding.offerWhen === undefined && binding.disclosure === undefined) {
+            throw new Error(`Raybase agent action binding for ${action.name} requires offerWhen or disclosure`);
+        }
+        if (binding.offerWhen !== undefined && typeof binding.offerWhen !== "function") {
+            throw new Error(`Raybase agent action binding for ${action.name} offerWhen must be a function`);
+        }
+        if (binding.disclosure !== undefined
+            && binding.disclosure !== "full"
+            && binding.disclosure !== "stub"
+            && typeof binding.disclosure !== "function") {
+            throw new Error(`Raybase agent action binding for ${action.name} disclosure must be "full", "stub", or a function`);
+        }
+        return {
+            action,
+            ...(binding.offerWhen ? { offerWhen: binding.offerWhen } : {}),
+            ...(binding.disclosure !== undefined ? { disclosure: binding.disclosure } : {})
+        };
+    });
+}
+const actionNamePattern = /^[A-Za-z][A-Za-z0-9_.:-]{0,127}$/;
+export const unsupportedRaybaseAgentInvocationRuntime = {
+    memory: {
+        async list() {
+            throw new Error("ctx.agents is not available from this Raybase action adapter");
+        },
+        async read() {
+            throw new Error("ctx.agents is not available from this Raybase action adapter");
+        },
+        async readMany() {
+            throw new Error("ctx.agents is not available from this Raybase action adapter");
+        }
+    },
+    runs: {
+        async recent() {
+            throw new Error("ctx.agents is not available from this Raybase action adapter");
+        }
+    },
+    async run() {
+        throw new Error("ctx.agents is not available from this Raybase action adapter");
+    },
+    async enqueue() {
+        throw new Error("ctx.agents is not available from this Raybase action adapter");
+    },
+    async compose() {
+        throw new Error("ctx.agents is not available from this Raybase action adapter");
+    },
+    async wake() {
+        throw new Error("ctx.agents is not available from this Raybase action adapter");
+    },
+    async cancelWake() {
+        throw new Error("ctx.agents is not available from this Raybase action adapter");
+    },
+    followUps() {
+        throw new Error("ctx.agents is not available from this Raybase action adapter");
+    },
+    conversations: {
+        async readState() {
+            throw new Error("ctx.agents is not available from this Raybase action adapter");
+        },
+        async resume() {
+            throw new Error("ctx.agents is not available from this Raybase action adapter");
+        },
+        async composeOutcome() {
+            throw new Error("ctx.agents is not available from this Raybase action adapter");
+        },
+        async removeMessage() {
+            throw new Error("ctx.agents is not available from this Raybase action adapter");
+        },
+        async rewind() {
+            throw new Error("ctx.agents is not available from this Raybase action adapter");
+        },
+        async rerun() {
+            throw new Error("ctx.agents is not available from this Raybase action adapter");
+        }
+    },
+    rooms: {
+        async create() { throw new Error("ctx.agents is not available from this Raybase action adapter"); },
+        async addMember() { throw new Error("ctx.agents is not available from this Raybase action adapter"); },
+        async removeMember() { throw new Error("ctx.agents is not available from this Raybase action adapter"); },
+        async leave() { throw new Error("ctx.agents is not available from this Raybase action adapter"); },
+        async redactMember() { throw new Error("ctx.agents is not available from this Raybase action adapter"); },
+        async transferOwner() { throw new Error("ctx.agents is not available from this Raybase action adapter"); },
+        async members() { throw new Error("ctx.agents is not available from this Raybase action adapter"); }
+    }
+};
+export class ActionDeniedError extends Error {
+    status = 403;
+    constructor(message) {
+        super(message);
+        this.name = "ActionDeniedError";
+    }
+}
+export class ActionInputValidationError extends Error {
+    status = 400;
+    constructor(actionName, cause) {
+        super(`Invalid input for action ${actionName}`);
+        this.name = "ActionInputValidationError";
+        this.cause = cause;
+    }
+}
+export class ActionOutputValidationError extends Error {
+    status = 500;
+    constructor(actionName, cause) {
+        super(`Action ${actionName} returned invalid output`);
+        this.name = "ActionOutputValidationError";
+        this.cause = cause;
+    }
+}
+export class RaybaseActionError extends Error {
+    code;
+    status;
+    guidance;
+    retryable;
+    details;
+    constructor(message, options = {}) {
+        super(message);
+        this.name = "RaybaseActionError";
+        this.code = sanitizeActionErrorCode(options.code ?? "action_failed");
+        this.status = sanitizeStatus(options.status, 400);
+        this.guidance = options.guidance;
+        this.retryable = options.retryable;
+        this.details = options.details;
+        this.cause = options.cause;
+    }
+}
+export function actionError(message, options = {}) {
+    return new RaybaseActionError(message, options);
+}
+const ACTION_INPUT_ISSUE_LIMIT = 12;
+const ACTION_INPUT_ISSUE_MESSAGE_LIMIT = 240;
+function issuePath(path) {
+    if (!Array.isArray(path) || !path.length)
+        return "(root)";
+    return path.reduce((joined, segment) => {
+        if (typeof segment === "number")
+            return `${joined}[${segment}]`;
+        return joined ? `${joined}.${String(segment)}` : String(segment);
+    }, "");
+}
+/**
+ * Why an input was refused, in a shape a caller can act on.
+ *
+ * A validation failure used to be reported as the bare sentence "Invalid input
+ * for action X" plus `retryable: true` — which tells a caller that something is
+ * wrong, that it should try again, and nothing whatsoever about what to change.
+ * An agent handed that has one move: guess. Birch spent six and a half minutes
+ * and nine model turns guessing at one rejected argument, on a request its
+ * schema could never have accepted, and the conversation grew by 84,000
+ * characters while it did (2026-08-25).
+ *
+ * So the issues travel. The validator throws either a zod error, whose
+ * `issues` already carry a path and a sentence each, or a plain `Error` from
+ * the JSON-schema walker, whose message names the path itself — both become the
+ * same list. It is capped in count and in length on purpose: this rides back
+ * into a model's context on a path that is already the tightest budget in the
+ * house, and a nested union can otherwise produce hundreds of them.
+ *
+ * Nothing here reads the *values* that were rejected, only where they sat and
+ * what the schema said. The caller supplied them; it does not need them back.
+ */
+export function actionInputIssues(cause) {
+    const raw = cause?.issues;
+    const issues = Array.isArray(raw)
+        ? raw.flatMap((issue) => {
+            const value = issue;
+            return typeof value?.message === "string" && value.message.trim()
+                ? [{ path: issuePath(value.path), message: value.message.trim().slice(0, ACTION_INPUT_ISSUE_MESSAGE_LIMIT) }]
+                : [];
+        })
+        : cause instanceof Error && cause.message.trim()
+            ? [{ path: "(root)", message: cause.message.trim().slice(0, ACTION_INPUT_ISSUE_MESSAGE_LIMIT) }]
+            : [];
+    const seen = new Set();
+    return issues
+        .filter((issue) => {
+        const key = `${issue.path}:${issue.message}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    })
+        .slice(0, ACTION_INPUT_ISSUE_LIMIT);
+}
+export function actionErrorPayload(actionName, error) {
+    if (error instanceof RaybaseActionError) {
+        return compactActionErrorPayload({
+            ok: false,
+            action: actionName,
+            code: error.code,
+            message: error.message,
+            guidance: error.guidance,
+            retryable: error.retryable,
+            details: error.details
+        });
+    }
+    if (error instanceof ActionInputValidationError) {
+        const issues = actionInputIssues(error.cause);
+        return compactActionErrorPayload({
+            ok: false,
+            action: actionName,
+            code: "invalid_input",
+            message: `Invalid input for action ${actionName}.`,
+            guidance: issues.length
+                ? "Fix the fields listed in details and call again. If the schema has no shape for what was asked, say so instead of trying another arrangement of the same request."
+                : "Retry the action with arguments that match the input schema.",
+            retryable: true,
+            details: issues.length ? { issues } : undefined
+        });
+    }
+    if (error instanceof ActionDeniedError) {
+        return {
+            ok: false,
+            action: actionName,
+            code: "action_denied",
+            message: "The caller is not allowed to run this action.",
+            guidance: "Do not retry this action unless the caller changes permissions or signs in with an allowed account.",
+            retryable: false
+        };
+    }
+    return null;
+}
+export function defineAction(definition) {
+    validateActionName(definition.name);
+    validateActionPolicy(definition.policy, definition.name, definition.audience);
+    return { ...definition };
+}
+export function defineActions(actions) {
+    const normalized = normalizeNamedDefinitions("action", actions, validateActionName);
+    for (const action of Object.values(normalized)) {
+        validateActionPolicy(action.policy, action.name, action.audience);
+    }
+    return normalized;
+}
+export function validateActionName(name) {
+    if (!actionNamePattern.test(name)) {
+        throw new Error(`Invalid Raybase action name "${name}". Use letters, numbers, "_", "-", ".", or ":".`);
+    }
+}
+export function validateActionPolicy(policy, actionName = "action", audience = "signed-in") {
+    if (!policy) {
+        if (actionAudienceAllows(audience, "signed-in"))
+            throw new Error(`Raybase action ${actionName} must declare a policy`);
+        return;
+    }
+    switch (policy.kind) {
+        case "allowAll":
+        case "denyAll":
+        case "role":
+            return;
+        case "owns":
+            throw new Error(`Raybase action ${actionName} cannot use owns(); action policies must be row-independent`);
+        case "operator":
+        case "servicePrincipal":
+            throw new Error(`Raybase action ${actionName} cannot use ${policy.kind} policy in user-facing AI`);
+        case "anyOf":
+        case "allOf":
+            for (const candidate of policy.policies)
+                validateActionPolicy(candidate, actionName);
+            return;
+        case "not":
+            validateActionPolicy(policy.policy, actionName);
+            return;
+    }
+}
+export function validateActionExposure(action, options = {}) {
+    validateActionName(action.name);
+    if (action.requiresInternalControl && !options.allowInternalControl) {
+        throw new Error(`Raybase action ${action.name} requires internal control storage and cannot be adapted to this surface`);
+    }
+    const effectivePolicy = options.policy ?? action.policy;
+    if (options.requirePolicy && !effectivePolicy)
+        throw new Error(`Raybase action ${action.name} must declare an effective policy for this surface`);
+    validateActionPolicy(effectivePolicy, action.name, action.audience);
+    if (options.rowAuthorization) {
+        if (!options.rowAuthorization.table)
+            throw new Error(`Raybase action ${action.name} rowAuthorization.table is required`);
+        if (!options.rowAuthorization.action)
+            throw new Error(`Raybase action ${action.name} rowAuthorization.action is required`);
+    }
+}
+export function evaluateActionPolicy(policy, user) {
+    return evaluatePolicy(policy, { user, action: "create" });
+}
+export function actionAudienceAllows(audience, kind) {
+    const normalized = audience ?? "signed-in";
+    return Array.isArray(normalized) ? normalized.includes(kind) : normalized === kind;
+}
+export function parseActionInput(action, raw) {
+    return parseWithSchema(action.input, raw ?? {}, action.name);
+}
+export function parseActionOutput(action, raw) {
+    if (!action.output)
+        return raw;
+    return parseWithSchema(action.output, raw, `${action.name}.output`);
+}
+/**
+ * The schema an agent tool advertises for this action.
+ *
+ * Strict providers validate every tool's `parameters` and refuse the whole
+ * request over one offender, with no indication of which — so a green build and
+ * a passing suite still produce a turn that never happens. An action may
+ * declare the exact schema to publish; otherwise the validator's schema is
+ * conformed to the strict subset, which changes nothing about validation.
+ */
+export function actionInputJsonSchema(action) {
+    return strictToolParameters(action.inputJsonSchema ?? jsonSchemaFor(action.input, { reused: "ref" }));
+}
+export function actionOutputJsonSchema(action) {
+    return action.output ? jsonSchemaFor(action.output) : undefined;
+}
+/**
+ * Model-supplied input with the strict wire form undone.
+ *
+ * What a strict provider will carry is not what an action accepts: an omitted
+ * optional arrives as an explicit `null`, an open record arrives as a string of
+ * JSON, and a discriminated union arrives flattened into one object holding
+ * every branch's properties with the other branch's padded out. Each of those
+ * is refused by the action's own schema a moment later, so the padding comes
+ * off here — against the schema the action *declared*, which still knows which
+ * properties were optional and which shape belongs to which branch.
+ *
+ * Anything not padded passes through untouched, so this is safe on input from
+ * any surface. It runs on the agent tool path only, because that is the only
+ * surface whose input had to be squeezed through the subset.
+ */
+export function restoreStrictActionInput(action, raw) {
+    if (raw === undefined || raw === null)
+        return raw;
+    try {
+        return restoreStrictModelValue(raw, action.inputJsonSchema ?? jsonSchemaFor(action.input));
+    }
+    catch {
+        // A schema Core cannot read is the action's own problem to report: let its
+        // validator produce the message rather than failing here with none.
+        return raw;
+    }
+}
+export function actionManifestDescriptor(action) {
+    const requiredInputKeys = actionRequiredInputKeys(action);
+    return compactActionManifestDescriptor({
+        name: action.name,
+        policy: serializePolicyExpression(action.policy),
+        annotations: compactActionAnnotations(action.annotations),
+        resource: compactActionResource(action.resource),
+        requiredInputKeys: requiredInputKeys?.length ? requiredInputKeys : undefined,
+        hasOutputSchema: Boolean(action.output)
+    });
+}
+function actionRequiredInputKeys(action) {
+    try {
+        const inputSchema = actionInputJsonSchema(action);
+        return Array.isArray(inputSchema.required)
+            ? inputSchema.required.filter((key) => typeof key === "string").sort()
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function compactActionManifestDescriptor(descriptor) {
+    const compacted = { name: descriptor.name };
+    if (descriptor.policy)
+        compacted.policy = descriptor.policy;
+    if (descriptor.annotations)
+        compacted.annotations = descriptor.annotations;
+    if (descriptor.resource)
+        compacted.resource = descriptor.resource;
+    if (descriptor.requiredInputKeys?.length)
+        compacted.requiredInputKeys = descriptor.requiredInputKeys;
+    if (descriptor.hasOutputSchema !== undefined)
+        compacted.hasOutputSchema = descriptor.hasOutputSchema;
+    return compacted;
+}
+function compactActionAnnotations(annotations) {
+    if (!annotations)
+        return undefined;
+    const compacted = {};
+    if (annotations.readOnlyHint === true)
+        compacted.readOnlyHint = true;
+    if (annotations.destructiveHint === true)
+        compacted.destructiveHint = true;
+    if (annotations.idempotentHint === true)
+        compacted.idempotentHint = true;
+    return Object.keys(compacted).length ? compacted : undefined;
+}
+function compactActionResource(resource) {
+    if (!resource?.name)
+        return undefined;
+    const compacted = { name: resource.name };
+    if (resource.operation)
+        compacted.operation = resource.operation;
+    if (resource.inputRefs && Object.keys(resource.inputRefs).length)
+        compacted.inputRefs = resource.inputRefs;
+    return compacted;
+}
+export function rowAuthorization(definition) {
+    return definition;
+}
+export async function executeAction(action, rawInput, ctx, options = {}) {
+    const surface = options.surface ?? ctx.surface ?? "action";
+    let input;
+    try {
+        input = parseActionInput(action, rawInput);
+    }
+    catch (error) {
+        await actionAudit(ctx, "action.error", action.name, { surface, stage: "input", error: errorMessage(error) });
+        await options.onAccounting?.({ status: "error", actionName: action.name, actionInput: rawInput, error: errorMessage(error) });
+        throw new ActionInputValidationError(action.name, error);
+    }
+    const audience = options.audience ?? audienceFromPrincipal(ctx.principal);
+    if (!actionAudienceAllows(action.audience, audience)) {
+        await recordDenied(action, input, ctx, options, "Audience denied", surface);
+        throw new ActionDeniedError(`Audience denied action ${action.name}`);
+    }
+    const effectivePolicy = options.policy ?? action.policy;
+    if (options.requirePolicy && !effectivePolicy) {
+        await recordDenied(action, input, ctx, options, "Missing policy", surface);
+        throw new ActionDeniedError(`Missing policy for action ${action.name}`);
+    }
+    const authority = principalOnBehalfOf(ctx.principal);
+    if (authority.kind === "user" && !evaluateActionPolicy(effectivePolicy, authority.user)) {
+        await recordDenied(action, input, ctx, options, "Policy denied", surface);
+        throw new ActionDeniedError(`Policy denied action ${action.name}`);
+    }
+    await authorizeRow(action, input, ctx, options, surface);
+    const idempotencyKey = await resolveIdempotencyKey(action, input, ctx, options);
+    await actionAudit(ctx, "action.invoke", action.name, { surface, idempotencyKey });
+    try {
+        const result = await action.handler(ctx, input);
+        let output;
+        try {
+            output = parseActionOutput(action, result);
+        }
+        catch (error) {
+            await actionAudit(ctx, "action.error", action.name, { surface, stage: "output", idempotencyKey, error: errorMessage(error) });
+            await options.onAccounting?.({ status: "error", actionName: action.name, actionInput: input, error: "Invalid action output" });
+            throw new ActionOutputValidationError(action.name, error);
+        }
+        await actionAudit(ctx, "action.success", action.name, { surface, idempotencyKey });
+        await options.onAccounting?.({ status: "ok", actionName: action.name, actionInput: input });
+        return output;
+    }
+    catch (error) {
+        if (error instanceof ActionOutputValidationError)
+            throw error;
+        await actionAudit(ctx, "action.error", action.name, { surface, idempotencyKey, error: errorMessage(error) });
+        await options.onAccounting?.({ status: "error", actionName: action.name, actionInput: input, error: errorMessage(error) });
+        throw error;
+    }
+}
+export function mcpToolFromAction(action, options = {}) {
+    validateActionExposure(action, { policy: options.policy, rowAuthorization: options.rowAuthorization, requirePolicy: true, allowInternalControl: options.allowInternalControl });
+    return {
+        name: action.name,
+        description: action.description,
+        inputSchema: action.input,
+        annotations: action.annotations,
+        scopes: options.scopes ?? (action.annotations?.readOnlyHint ? ["mcp:read", `mcp:tool:${action.name}`] : ["mcp:write", `mcp:tool:${action.name}`]),
+        raybase: {
+            action: actionManifestDescriptor(action)
+        },
+        handler: async (args, ctx) => {
+            try {
+                const extraContext = await options.context?.(ctx);
+                const result = await executeAction(action, args, {
+                    request: ctx.request,
+                    env: ctx.env,
+                    user: ctx.user,
+                    principal: { kind: "user", user: ctx.user, userId: ctx.user.id, roles: ctx.user.appRoles },
+                    db: ctx.db,
+                    control: ctx.control,
+                    auth: ctx.control
+                        ? createRaybaseAuthContextRuntime({
+                            db: ctx.control,
+                            secret: authSecret(ctx.env),
+                            config: ctx.config,
+                            sessionAuthenticated: false,
+                            principal: { kind: "user", user: ctx.user, userId: ctx.user.id, roles: ctx.user.appRoles },
+                            request: ctx.request,
+                            audit: (event) => ctx.audit(event.action, {
+                                target: event.target,
+                                metadata: event.metadata,
+                                source: event.source
+                            })
+                        })
+                        : unsupportedRaybaseAuthContextRuntime,
+                    agents: ctx.agents ?? unsupportedRaybaseAgentInvocationRuntime,
+                    ai: ctx.ai ?? disabledRaybaseAI,
+                    jobs: ctx.jobs ?? unsupportedRaybaseJobsRuntime,
+                    route: "/mcp",
+                    surface: "mcp",
+                    audit: (event) => ctx.audit(event.action, { target: event.target, metadata: event.metadata, source: event.source }),
+                    ...extraContext
+                }, {
+                    surface: "mcp",
+                    policy: options.policy,
+                    requirePolicy: true,
+                    rowAuthorization: options.rowAuthorization
+                });
+                return actionResultToMcp(action.name, result);
+            }
+            catch (error) {
+                return actionErrorToMcp(action.name, error);
+            }
+        }
+    };
+}
+export function actionRoute(action, options = {}) {
+    validateActionExposure(action, { policy: options.policy, rowAuthorization: options.rowAuthorization, requirePolicy: true });
+    return {
+        action,
+        path: options.path ?? `/api/actions/${encodeURIComponent(action.name)}`,
+        policy: options.policy,
+        audience: options.audience,
+        rowAuthorization: options.rowAuthorization
+    };
+}
+export function serverFnFromAction(action, options = {}) {
+    const endpoint = options.endpoint ?? `/api/actions/${encodeURIComponent(action.name)}`;
+    return async (input, callOptions = {}) => {
+        const runFetch = callOptions.fetch ?? options.fetch ?? fetch;
+        const headers = new Headers(options.headers);
+        for (const [key, value] of new Headers(callOptions.headers))
+            headers.set(key, value);
+        if (!headers.has("content-type"))
+            headers.set("content-type", "application/json");
+        const response = await runFetch(endpoint, {
+            method: "POST",
+            headers,
+            credentials: options.credentials,
+            signal: callOptions.signal,
+            body: JSON.stringify(input ?? {})
+        });
+        const body = await response.json().catch(() => ({}));
+        const bodyRecord = body && typeof body === "object" ? body : {};
+        if (!response.ok) {
+            const actionError = actionErrorFromResponseBody(bodyRecord, response.status);
+            if (actionError)
+                throw actionError;
+            throw new Error(typeof bodyRecord.error === "string" ? bodyRecord.error : `Action ${action.name} failed`);
+        }
+        return body;
+    };
+}
+function actionResultToMcp(actionName, result) {
+    const text = typeof result === "string" ? result : `Action ${actionName} completed.`;
+    return { content: [{ type: "text", text }], structuredContent: result };
+}
+function actionErrorToMcp(actionName, error) {
+    const payload = actionErrorPayload(actionName, error) ?? {
+        ok: false,
+        action: actionName,
+        code: "action_failed",
+        message: `Action ${actionName} failed.`,
+        guidance: "The action failed before returning a usable result. Inspect server logs or retry later.",
+        retryable: false
+    };
+    return {
+        content: [{ type: "text", text: payload.message }],
+        structuredContent: payload,
+        isError: true
+    };
+}
+function audienceFromPrincipal(principal) {
+    return principalOnBehalfOf(principal).kind === "public" ? "public" : "signed-in";
+}
+async function authorizeRow(action, input, ctx, options, surface) {
+    const rowAuth = options.rowAuthorization;
+    if (!rowAuth)
+        return;
+    const id = rowAuth.id(input, ctx);
+    if (!id && rowAuth.action !== "create") {
+        await recordDenied(action, input, ctx, options, "Row authorization id missing", surface);
+        throw new ActionDeniedError(`Policy denied action ${action.name}`);
+    }
+    const rowPayload = input && typeof input === "object" && !Array.isArray(input)
+        ? input
+        : undefined;
+    const authorized = await ctx.db.authorize(rowAuth.table, rowAuth.action, id ? String(id) : undefined, rowPayload);
+    if (!authorized) {
+        await recordDenied(action, input, ctx, options, "Row authorization denied", surface);
+        throw new ActionDeniedError(`Policy denied action ${action.name}`);
+    }
+}
+async function resolveIdempotencyKey(action, input, ctx, options) {
+    const source = options.idempotencyKey ?? action.idempotencyKey;
+    if (typeof source === "string")
+        return source || null;
+    if (!source)
+        return null;
+    return (await source(input, ctx)) ?? null;
+}
+async function recordDenied(action, input, ctx, options, reason, surface) {
+    await actionAudit(ctx, "action.denied", action.name, { surface, reason });
+    await options.onAccounting?.({ status: "denied", actionName: action.name, actionInput: input, error: reason });
+}
+async function actionAudit(ctx, auditAction, actionName, metadata) {
+    // An agent-driven call is attributed to the agent, with the person it ran
+    // for as runAs, so the trail never confuses the two.
+    const agent = ctx.principal.kind === "agent" ? ctx.principal : null;
+    await ctx.audit({
+        action: auditAction,
+        target: { type: "raybase_action", id: actionName },
+        metadata: agent ? { ...metadata, agentName: agent.agent, ...(agent.runId ? { runId: agent.runId } : {}) } : metadata,
+        ...(agent ? { actor: agent, runAs: agent.onBehalfOf.kind === "public" ? null : agent.onBehalfOf } : {})
+    }).catch(() => undefined);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function actionErrorFromResponseBody(body, status) {
+    const payload = body.actionError && typeof body.actionError === "object" && !Array.isArray(body.actionError)
+        ? body.actionError
+        : null;
+    if (!payload || typeof payload.message !== "string")
+        return null;
+    return new RaybaseActionError(payload.message, {
+        code: typeof payload.code === "string" ? payload.code : undefined,
+        status,
+        guidance: typeof payload.guidance === "string" ? payload.guidance : undefined,
+        retryable: typeof payload.retryable === "boolean" ? payload.retryable : undefined,
+        details: payload.details
+    });
+}
+function sanitizeActionErrorCode(value) {
+    const code = value.trim().toLowerCase().replace(/[^a-z0-9_.:-]+/g, "_").replace(/^_+|_+$/g, "");
+    return code || "action_failed";
+}
+function sanitizeStatus(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 400 && value <= 599 ? Math.floor(value) : fallback;
+}
+function compactActionErrorPayload(payload) {
+    return Object.fromEntries(Object.entries(payload).filter(([, value]) => value !== undefined));
+}
+//# sourceMappingURL=actions.js.map