@open-mercato/ai-assistant 0.5.1-develop.3036.f02c281f23 → 0.5.1-develop.3045.b4b3320cc2

package/dist/modules/ai_assistant/lib/pending-action-recheck.js

@@ -0,0 +1,246 @@
+import { findWithDecryption } from "@open-mercato/shared/lib/encryption/find";
+import { Attachment } from "@open-mercato/core/modules/attachments/data/entities";
+import { resolveEffectiveMutationPolicy } from "./agent-policy.js";
+import { hasRequiredFeatures } from "./auth.js";
+function checkStatusAndExpiry(action, options = {}) {
+  const now = options.now ?? /* @__PURE__ */ new Date();
+  if (action.status !== "pending") {
+    return {
+      ok: false,
+      status: 409,
+      code: "invalid_status",
+      message: `Pending action is in status "${action.status}"; expected "pending".`
+    };
+  }
+  const expiresAt = action.expiresAt instanceof Date ? action.expiresAt : new Date(action.expiresAt);
+  if (expiresAt.getTime() <= now.getTime()) {
+    return {
+      ok: false,
+      status: 409,
+      code: "expired",
+      message: "Pending action has expired. The model must re-propose the mutation."
+    };
+  }
+  return { ok: true };
+}
+function checkAgentAndFeatures(agent, ctx) {
+  if (!agent) {
+    return {
+      ok: false,
+      status: 404,
+      code: "agent_unknown",
+      message: "Agent is no longer registered."
+    };
+  }
+  const required = agent.requiredFeatures ?? [];
+  if (!hasRequiredFeatures(required, ctx.userFeatures, ctx.isSuperAdmin)) {
+    return {
+      ok: false,
+      status: 403,
+      code: "agent_features_denied",
+      message: `Caller lacks one of the agent's required features: ${required.join(", ")}`
+    };
+  }
+  return { ok: true };
+}
+function checkToolWhitelist(agent, tool, action, options = {}) {
+  if (!tool) {
+    return {
+      ok: false,
+      status: 403,
+      code: "tool_not_whitelisted",
+      message: `Tool "${action.toolName}" is not registered.`
+    };
+  }
+  if (!agent.allowedTools.includes(tool.name) || tool.isMutation !== true) {
+    return {
+      ok: false,
+      status: 403,
+      code: "tool_not_whitelisted",
+      message: `Tool "${tool.name}" is no longer whitelisted as a mutation tool for agent "${agent.id}".`
+    };
+  }
+  const effective = resolveEffectiveMutationPolicy(
+    agent.mutationPolicy,
+    options.mutationPolicyOverride ?? null,
+    agent.id
+  );
+  if (effective === "read-only") {
+    return {
+      ok: false,
+      status: 403,
+      code: "read_only_agent",
+      message: `Agent "${agent.id}" effective mutationPolicy=read-only; mutation tool "${tool.name}" cannot be executed.`
+    };
+  }
+  return { ok: true };
+}
+async function checkAttachmentScope(action, ctx) {
+  const ids = Array.isArray(action.attachmentIds) ? action.attachmentIds : [];
+  if (ids.length === 0) return { ok: true };
+  const em = ctx.em;
+  if (!em) {
+    return {
+      ok: false,
+      status: 500,
+      code: "attachment_cross_tenant",
+      message: "Attachment scope check requires an EntityManager."
+    };
+  }
+  const rows = await findWithDecryption(
+    em,
+    Attachment,
+    { id: { $in: ids } },
+    {},
+    { tenantId: ctx.tenantId, organizationId: ctx.organizationId }
+  );
+  if (rows.length !== ids.length) {
+    return {
+      ok: false,
+      status: 403,
+      code: "attachment_cross_tenant",
+      message: "One or more attachments are not accessible to the caller."
+    };
+  }
+  for (const row of rows) {
+    if ((row.tenantId ?? null) !== ctx.tenantId) {
+      return {
+        ok: false,
+        status: 403,
+        code: "attachment_cross_tenant",
+        message: "One or more attachments belong to a different tenant."
+      };
+    }
+    if (ctx.organizationId !== null && row.organizationId && row.organizationId !== ctx.organizationId) {
+      return {
+        ok: false,
+        status: 403,
+        code: "attachment_cross_tenant",
+        message: "One or more attachments belong to a different organization."
+      };
+    }
+  }
+  return { ok: true };
+}
+async function checkRecordVersion(action, tool, ctx) {
+  const parseResult = tool.inputSchema.safeParse(action.normalizedInput ?? {});
+  if (!parseResult.success) {
+    return {
+      ok: false,
+      status: 412,
+      code: "schema_drift",
+      message: "Pending input no longer satisfies the tool schema.",
+      extra: { issues: parseResult.error.issues }
+    };
+  }
+  const handlerContext = toHandlerContext(ctx);
+  const records = Array.isArray(action.records) ? action.records : null;
+  if (records && records.length > 0) {
+    if (!tool.loadBeforeRecords) {
+      return { ok: true };
+    }
+    const currentRows = await tool.loadBeforeRecords(parseResult.data, handlerContext);
+    const currentVersionById = /* @__PURE__ */ new Map();
+    for (const row of currentRows ?? []) {
+      currentVersionById.set(row.recordId, row.recordVersion ?? null);
+    }
+    const stale = [];
+    for (const record of records) {
+      const current2 = currentVersionById.get(record.recordId);
+      const captured2 = record.recordVersion ?? null;
+      if (current2 === void 0) {
+        stale.push({
+          recordId: record.recordId,
+          error: { code: "stale_version", message: "Record no longer exists." }
+        });
+        continue;
+      }
+      if (captured2 !== null && current2 !== captured2) {
+        stale.push({
+          recordId: record.recordId,
+          error: { code: "stale_version", message: "Record version changed since preview." }
+        });
+      }
+    }
+    if (stale.length === records.length) {
+      return {
+        ok: false,
+        status: 412,
+        code: "stale_version",
+        message: "All pending records are stale; the model must re-propose the batch.",
+        extra: { staleRecords: stale.map((entry) => entry.recordId) }
+      };
+    }
+    if (stale.length > 0) {
+      return { ok: true, failedRecords: stale };
+    }
+    return { ok: true };
+  }
+  if (!tool.loadBeforeRecord) {
+    return { ok: true };
+  }
+  const before = await tool.loadBeforeRecord(parseResult.data, handlerContext);
+  if (!before) return { ok: true };
+  const captured = action.recordVersion ?? null;
+  const current = before.recordVersion ?? null;
+  if (captured !== null && current !== captured) {
+    return {
+      ok: false,
+      status: 412,
+      code: "stale_version",
+      message: "Record version changed since preview; re-propose the mutation.",
+      extra: { recordId: before.recordId }
+    };
+  }
+  return { ok: true };
+}
+function toHandlerContext(ctx) {
+  return {
+    tenantId: ctx.tenantId,
+    organizationId: ctx.organizationId,
+    userId: ctx.userId,
+    container: ctx.container,
+    userFeatures: ctx.userFeatures,
+    isSuperAdmin: ctx.isSuperAdmin
+  };
+}
+async function runPendingActionRechecks(input) {
+  const { action, agent, tool, ctx, now, mutationPolicyOverride } = input;
+  const statusCheck = checkStatusAndExpiry(action, { now });
+  if (!statusCheck.ok) return statusCheck;
+  const agentCheck = checkAgentAndFeatures(agent, ctx);
+  if (!agentCheck.ok) return agentCheck;
+  const whitelistCheck = checkToolWhitelist(agent, tool, action, {
+    mutationPolicyOverride: mutationPolicyOverride ?? null
+  });
+  if (!whitelistCheck.ok) return whitelistCheck;
+  const attachmentCheck = await checkAttachmentScope(action, ctx);
+  if (!attachmentCheck.ok) return attachmentCheck;
+  const versionCheck = await checkRecordVersion(action, tool, ctx);
+  return versionCheck;
+}
+const PENDING_ACTION_RECHECK_CODES = [
+  "invalid_status",
+  "expired",
+  "agent_unknown",
+  "agent_features_denied",
+  "tool_not_whitelisted",
+  "read_only_agent",
+  "attachment_cross_tenant",
+  "stale_version",
+  "schema_drift"
+];
+function isPendingActionRecheckCode(value) {
+  return typeof value === "string" && PENDING_ACTION_RECHECK_CODES.includes(value);
+}
+export {
+  PENDING_ACTION_RECHECK_CODES,
+  checkAgentAndFeatures,
+  checkAttachmentScope,
+  checkRecordVersion,
+  checkStatusAndExpiry,
+  checkToolWhitelist,
+  isPendingActionRecheckCode,
+  runPendingActionRechecks
+};
+//# sourceMappingURL=pending-action-recheck.js.map

package/dist/modules/ai_assistant/lib/pending-action-recheck.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/ai_assistant/lib/pending-action-recheck.ts"],
+  "sourcesContent": ["/**\n * Pending-action re-check contract (spec \u00A79.4 / Step 5.8).\n *\n * The operator presses \"Confirm\" on a `mutation-preview-card`. The server\n * MUST re-verify every invariant before executing the wrapped tool \u2014 the\n * pending row was created at propose-time and agents / policies / record\n * versions can all drift between then and confirm. This module is the\n * single source of truth for that contract.\n *\n * The individual `check*` helpers are exported independently so the Step\n * 5.8 unit suite can exercise each guard in isolation. The orchestrator\n * {@link runPendingActionRechecks} stops at the first failure and returns\n * a structured denial the route turns into a JSON error envelope.\n *\n * This module is pure aside from DB reads; the caller owns the transaction\n * boundary. The Step 5.9 cancel route reuses {@link checkStatusAndExpiry}.\n */\nimport type { EntityManager } from '@mikro-orm/postgresql'\nimport { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'\nimport { Attachment } from '@open-mercato/core/modules/attachments/data/entities'\nimport type { AiAgentDefinition } from './ai-agent-definition'\nimport type { AiToolDefinition, McpToolContext } from './types'\nimport type { AiPendingAction } from '../data/entities'\nimport type {\n  AiPendingActionFailedRecord,\n  AiPendingActionRecordDiff,\n  AiPendingActionStatus,\n} from './pending-action-types'\nimport { resolveEffectiveMutationPolicy } from './agent-policy'\nimport { hasRequiredFeatures } from './auth'\nimport type { AiAgentMutationPolicy } from './ai-agent-definition'\n\nexport type PendingActionRecheckCode =\n  | 'invalid_status'\n  | 'expired'\n  | 'agent_unknown'\n  | 'agent_features_denied'\n  | 'tool_not_whitelisted'\n  | 'read_only_agent'\n  | 'attachment_cross_tenant'\n  | 'stale_version'\n  | 'schema_drift'\n\nexport interface PendingActionRecheckOkResult {\n  ok: true\n  /**\n   * Per-record stale list for batch mutations when only some records were\n   * stale. Present only when the batch path produced a partial-stale set;\n   * the caller should persist these via `repo.setStatus(..., { failedRecords })`\n   * and proceed with the remaining records.\n   */\n  failedRecords?: AiPendingActionFailedRecord[]\n}\n\nexport interface PendingActionRecheckFailResult {\n  ok: false\n  status: number\n  code: PendingActionRecheckCode\n  message: string\n  extra?: Record<string, unknown>\n}\n\nexport type PendingActionRecheckResult =\n  | PendingActionRecheckOkResult\n  | PendingActionRecheckFailResult\n\nexport interface PendingActionAuthContext {\n  tenantId: string\n  organizationId: string | null\n  userId: string\n  userFeatures: string[]\n  isSuperAdmin: boolean\n  /**\n   * Optional DI container used by `checkRecordVersion` to hand the tool's\n   * `loadBeforeRecord` resolver an `McpToolContext`.\n   */\n  container?: import('awilix').AwilixContainer\n  em?: EntityManager\n}\n\nexport interface PendingActionRecheckInput {\n  action: AiPendingAction\n  agent: AiAgentDefinition | null | undefined\n  tool: AiToolDefinition | null | undefined\n  ctx: PendingActionAuthContext\n  /** Explicit clock for deterministic tests. */\n  now?: Date\n  /**\n   * Optional tenant-scoped mutation-policy downgrade resolved by the caller\n   * (Step 5.4). Missing / null \u2192 agent's code-declared policy stands alone.\n   */\n  mutationPolicyOverride?: AiAgentMutationPolicy | null\n}\n\n/**\n * Guards 3 + 2: pending action is still in `pending` and has not expired.\n * Returns a structured 409 on mismatch. Reused by the cancel route (which\n * only runs 1-3 of the re-check list).\n */\nexport function checkStatusAndExpiry(\n  action: AiPendingAction,\n  options: { now?: Date } = {},\n): PendingActionRecheckResult {\n  const now = options.now ?? new Date()\n  if (action.status !== 'pending') {\n    return {\n      ok: false,\n      status: 409,\n      code: 'invalid_status',\n      message: `Pending action is in status \"${action.status}\"; expected \"pending\".`,\n    }\n  }\n  const expiresAt =\n    action.expiresAt instanceof Date ? action.expiresAt : new Date(action.expiresAt)\n  if (expiresAt.getTime() <= now.getTime()) {\n    return {\n      ok: false,\n      status: 409,\n      code: 'expired',\n      message: 'Pending action has expired. The model must re-propose the mutation.',\n    }\n  }\n  return { ok: true }\n}\n\n/**\n * Guard 4: the agent is still registered AND the caller still carries the\n * agent's `requiredFeatures`. Missing agent \u2192 404. Missing features \u2192 403.\n */\nexport function checkAgentAndFeatures(\n  agent: AiAgentDefinition | null | undefined,\n  ctx: PendingActionAuthContext,\n): PendingActionRecheckResult {\n  if (!agent) {\n    return {\n      ok: false,\n      status: 404,\n      code: 'agent_unknown',\n      message: 'Agent is no longer registered.',\n    }\n  }\n  const required = agent.requiredFeatures ?? []\n  if (!hasRequiredFeatures(required, ctx.userFeatures, ctx.isSuperAdmin)) {\n    return {\n      ok: false,\n      status: 403,\n      code: 'agent_features_denied',\n      message: `Caller lacks one of the agent's required features: ${required.join(', ')}`,\n    }\n  }\n  return { ok: true }\n}\n\n/**\n * Guards 5 + 6: effective mutation policy still allows mutation, AND the\n * tool is still whitelisted + still declared `isMutation: true`. Read-only\n * policy or whitelist drop \u2192 403.\n */\nexport function checkToolWhitelist(\n  agent: AiAgentDefinition,\n  tool: AiToolDefinition | null | undefined,\n  action: AiPendingAction,\n  options: { mutationPolicyOverride?: AiAgentMutationPolicy | null } = {},\n): PendingActionRecheckResult {\n  if (!tool) {\n    return {\n      ok: false,\n      status: 403,\n      code: 'tool_not_whitelisted',\n      message: `Tool \"${action.toolName}\" is not registered.`,\n    }\n  }\n  if (!agent.allowedTools.includes(tool.name) || tool.isMutation !== true) {\n    return {\n      ok: false,\n      status: 403,\n      code: 'tool_not_whitelisted',\n      message: `Tool \"${tool.name}\" is no longer whitelisted as a mutation tool for agent \"${agent.id}\".`,\n    }\n  }\n  const effective = resolveEffectiveMutationPolicy(\n    agent.mutationPolicy,\n    options.mutationPolicyOverride ?? null,\n    agent.id,\n  )\n  if (effective === 'read-only') {\n    return {\n      ok: false,\n      status: 403,\n      code: 'read_only_agent',\n      message: `Agent \"${agent.id}\" effective mutationPolicy=read-only; mutation tool \"${tool.name}\" cannot be executed.`,\n    }\n  }\n  return { ok: true }\n}\n\n/**\n * Guard 7: every attachment id referenced by the pending row belongs to the\n * caller's tenant/org. Any cross-tenant id short-circuits with 403 \u2014 we do\n * not leak which specific id was rejected.\n */\nexport async function checkAttachmentScope(\n  action: AiPendingAction,\n  ctx: PendingActionAuthContext,\n): Promise<PendingActionRecheckResult> {\n  const ids = Array.isArray(action.attachmentIds) ? action.attachmentIds : []\n  if (ids.length === 0) return { ok: true }\n  const em = ctx.em\n  if (!em) {\n    return {\n      ok: false,\n      status: 500,\n      code: 'attachment_cross_tenant',\n      message: 'Attachment scope check requires an EntityManager.',\n    }\n  }\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const rows = (await findWithDecryption<any>(\n    em,\n    Attachment as any,\n    { id: { $in: ids } } as any,\n    {},\n    { tenantId: ctx.tenantId, organizationId: ctx.organizationId },\n  )) as Array<{ id: string; tenantId?: string | null; organizationId?: string | null }>\n  if (rows.length !== ids.length) {\n    return {\n      ok: false,\n      status: 403,\n      code: 'attachment_cross_tenant',\n      message: 'One or more attachments are not accessible to the caller.',\n    }\n  }\n  for (const row of rows) {\n    if ((row.tenantId ?? null) !== ctx.tenantId) {\n      return {\n        ok: false,\n        status: 403,\n        code: 'attachment_cross_tenant',\n        message: 'One or more attachments belong to a different tenant.',\n      }\n    }\n    if (ctx.organizationId !== null && row.organizationId && row.organizationId !== ctx.organizationId) {\n      return {\n        ok: false,\n        status: 403,\n        code: 'attachment_cross_tenant',\n        message: 'One or more attachments belong to a different organization.',\n      }\n    }\n  }\n  return { ok: true }\n}\n\n/**\n * Guard 8: record version matches the row's captured `recordVersion`. For\n * single-record actions a mismatch is a hard 412. For batch actions we\n * compute per-record and return a `failedRecords[]` entry for each stale\n * record; the caller proceeds with the remaining records. If the batch\n * has NO remaining records (every one is stale) the function returns 412.\n *\n * Also acts as the schema-drift guard: re-parses `action.normalizedInput`\n * through the tool's current zod schema. A shape change between propose\n * and confirm surfaces as 412 `schema_drift` so the model re-proposes.\n */\nexport async function checkRecordVersion(\n  action: AiPendingAction,\n  tool: AiToolDefinition,\n  ctx: PendingActionAuthContext,\n): Promise<PendingActionRecheckResult> {\n  const parseResult = tool.inputSchema.safeParse(action.normalizedInput ?? {})\n  if (!parseResult.success) {\n    return {\n      ok: false,\n      status: 412,\n      code: 'schema_drift',\n      message: 'Pending input no longer satisfies the tool schema.',\n      extra: { issues: parseResult.error.issues },\n    }\n  }\n\n  const handlerContext = toHandlerContext(ctx)\n\n  const records = Array.isArray(action.records) ? action.records : null\n  if (records && records.length > 0) {\n    if (!tool.loadBeforeRecords) {\n      return { ok: true }\n    }\n    const currentRows = await tool.loadBeforeRecords(parseResult.data as never, handlerContext)\n    const currentVersionById = new Map<string, string | null>()\n    for (const row of currentRows ?? []) {\n      currentVersionById.set(row.recordId, row.recordVersion ?? null)\n    }\n    const stale: AiPendingActionFailedRecord[] = []\n    for (const record of records as AiPendingActionRecordDiff[]) {\n      const current = currentVersionById.get(record.recordId)\n      const captured = record.recordVersion ?? null\n      if (current === undefined) {\n        stale.push({\n          recordId: record.recordId,\n          error: { code: 'stale_version', message: 'Record no longer exists.' },\n        })\n        continue\n      }\n      if (captured !== null && current !== captured) {\n        stale.push({\n          recordId: record.recordId,\n          error: { code: 'stale_version', message: 'Record version changed since preview.' },\n        })\n      }\n    }\n    if (stale.length === records.length) {\n      return {\n        ok: false,\n        status: 412,\n        code: 'stale_version',\n        message: 'All pending records are stale; the model must re-propose the batch.',\n        extra: { staleRecords: stale.map((entry) => entry.recordId) },\n      }\n    }\n    if (stale.length > 0) {\n      return { ok: true, failedRecords: stale }\n    }\n    return { ok: true }\n  }\n\n  if (!tool.loadBeforeRecord) {\n    return { ok: true }\n  }\n  const before = await tool.loadBeforeRecord(parseResult.data as never, handlerContext)\n  if (!before) return { ok: true }\n  const captured = action.recordVersion ?? null\n  const current = before.recordVersion ?? null\n  if (captured !== null && current !== captured) {\n    return {\n      ok: false,\n      status: 412,\n      code: 'stale_version',\n      message: 'Record version changed since preview; re-propose the mutation.',\n      extra: { recordId: before.recordId },\n    }\n  }\n  return { ok: true }\n}\n\nfunction toHandlerContext(ctx: PendingActionAuthContext): McpToolContext {\n  return {\n    tenantId: ctx.tenantId,\n    organizationId: ctx.organizationId,\n    userId: ctx.userId,\n    container: ctx.container as never,\n    userFeatures: ctx.userFeatures,\n    isSuperAdmin: ctx.isSuperAdmin,\n  }\n}\n\n/**\n * Orchestrator: runs every guard in spec \u00A79.4 order and returns the first\n * failure. Callers receive either `{ ok: true, failedRecords? }` \u2014 where a\n * non-empty `failedRecords` indicates a partial-stale batch that should\n * proceed with the non-stale subset \u2014 or `{ ok: false, status, code, ... }`\n * ready to serialize as an HTTP error envelope.\n */\nexport async function runPendingActionRechecks(\n  input: PendingActionRecheckInput,\n): Promise<PendingActionRecheckResult> {\n  const { action, agent, tool, ctx, now, mutationPolicyOverride } = input\n\n  const statusCheck = checkStatusAndExpiry(action, { now })\n  if (!statusCheck.ok) return statusCheck\n\n  const agentCheck = checkAgentAndFeatures(agent, ctx)\n  if (!agentCheck.ok) return agentCheck\n\n  const whitelistCheck = checkToolWhitelist(agent!, tool, action, {\n    mutationPolicyOverride: mutationPolicyOverride ?? null,\n  })\n  if (!whitelistCheck.ok) return whitelistCheck\n\n  const attachmentCheck = await checkAttachmentScope(action, ctx)\n  if (!attachmentCheck.ok) return attachmentCheck\n\n  const versionCheck = await checkRecordVersion(action, tool!, ctx)\n  return versionCheck\n}\n\n/**\n * Test-only helper shadowed here to let the route unit tests assert the\n * exhaustive set of codes without importing each guard individually.\n */\nexport const PENDING_ACTION_RECHECK_CODES: ReadonlyArray<PendingActionRecheckCode> = [\n  'invalid_status',\n  'expired',\n  'agent_unknown',\n  'agent_features_denied',\n  'tool_not_whitelisted',\n  'read_only_agent',\n  'attachment_cross_tenant',\n  'stale_version',\n  'schema_drift',\n]\n\nexport function isPendingActionRecheckCode(\n  value: unknown,\n): value is PendingActionRecheckCode {\n  return typeof value === 'string' && (PENDING_ACTION_RECHECK_CODES as readonly string[]).includes(value)\n}\n\nexport type { AiPendingActionFailedRecord } from './pending-action-types'\n\nexport type PendingActionRecheckStatus = AiPendingActionStatus\n"],
+  "mappings": "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",
+  "names": ["current", "captured"]
+}

package/dist/modules/ai_assistant/lib/pending-action-types.js

@@ -0,0 +1,70 @@
+const AI_PENDING_ACTION_STATUSES = [
+  "pending",
+  "confirmed",
+  "cancelled",
+  "expired",
+  "executing",
+  "failed"
+];
+const AI_PENDING_ACTION_QUEUE_MODES = ["inline", "stack"];
+const AI_PENDING_ACTION_ALLOWED_TRANSITIONS = {
+  pending: ["confirmed", "cancelled", "expired"],
+  confirmed: ["executing"],
+  executing: ["confirmed", "failed"],
+  cancelled: [],
+  expired: [],
+  failed: []
+};
+const AI_PENDING_ACTION_TERMINAL_STATUSES = [
+  "confirmed",
+  "cancelled",
+  "expired",
+  "failed"
+];
+class AiPendingActionStateError extends Error {
+  constructor(from, to) {
+    super(`Illegal AiPendingAction status transition: ${from} \u2192 ${to}`);
+    this.from = from;
+    this.to = to;
+    this.code = "ai_pending_action_invalid_transition";
+    this.name = "AiPendingActionStateError";
+  }
+}
+function isAiPendingActionStatus(value) {
+  return typeof value === "string" && AI_PENDING_ACTION_STATUSES.includes(value);
+}
+function isAiPendingActionQueueMode(value) {
+  return typeof value === "string" && AI_PENDING_ACTION_QUEUE_MODES.includes(value);
+}
+function isTerminalAiPendingActionStatus(status) {
+  return AI_PENDING_ACTION_TERMINAL_STATUSES.includes(status);
+}
+function isAllowedAiPendingActionTransition(from, to) {
+  return (AI_PENDING_ACTION_ALLOWED_TRANSITIONS[from] ?? []).includes(to);
+}
+const AI_PENDING_ACTION_DEFAULT_TTL_SECONDS = 900;
+const AI_PENDING_ACTION_TTL_ENV_VAR = "AI_PENDING_ACTION_TTL_SECONDS";
+function resolveAiPendingActionTtlSeconds(env = process.env) {
+  const raw = env[AI_PENDING_ACTION_TTL_ENV_VAR];
+  if (raw == null) return AI_PENDING_ACTION_DEFAULT_TTL_SECONDS;
+  const parsed = Number.parseInt(String(raw), 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return AI_PENDING_ACTION_DEFAULT_TTL_SECONDS;
+  }
+  return parsed;
+}
+export {
+  AI_PENDING_ACTION_ALLOWED_TRANSITIONS,
+  AI_PENDING_ACTION_DEFAULT_TTL_SECONDS,
+  AI_PENDING_ACTION_QUEUE_MODES,
+  AI_PENDING_ACTION_STATUSES,
+  AI_PENDING_ACTION_TERMINAL_STATUSES,
+  AI_PENDING_ACTION_TTL_ENV_VAR,
+  AiPendingActionStateError,
+  isAiPendingActionQueueMode,
+  isAiPendingActionStatus,
+  isAllowedAiPendingActionTransition,
+  isTerminalAiPendingActionStatus,
+  resolveAiPendingActionTtlSeconds
+};
+//# sourceMappingURL=pending-action-types.js.map

package/dist/modules/ai_assistant/lib/pending-action-types.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/ai_assistant/lib/pending-action-types.ts"],
+  "sourcesContent": ["/**\n * Shared enums + error type for the Phase 3 WS-C mutation approval gate\n * (spec \u00A78 `AiPendingAction` + \u00A79 server contract).\n *\n * These values are referenced by the entity, the repository, the\n * `/api/ai/actions/*` routes (Steps 5.7 / 5.8 / 5.9), and the cleanup\n * worker (Step 5.12). Colocated here so every consumer shares the same\n * source of truth.\n */\n\nexport const AI_PENDING_ACTION_STATUSES = [\n  'pending',\n  'confirmed',\n  'cancelled',\n  'expired',\n  'executing',\n  'failed',\n] as const\n\nexport type AiPendingActionStatus = (typeof AI_PENDING_ACTION_STATUSES)[number]\n\nexport const AI_PENDING_ACTION_QUEUE_MODES = ['inline', 'stack'] as const\n\nexport type AiPendingActionQueueMode = (typeof AI_PENDING_ACTION_QUEUE_MODES)[number]\n\n/**\n * Allowed state-machine edges for `AiPendingAction.status`:\n *\n * ```\n *     pending \u2500\u2500\u252C\u2500\u25B6 confirmed \u2500\u2500\u25B6 executing \u2500\u2500\u25B6 failed\n *               \u2502                        \u2514\u2500\u2500\u25B6 (terminal success keeps status = 'confirmed'\n *               \u2502                               and stores executionResult.recordId)\n *               \u251C\u2500\u25B6 cancelled\n *               \u2514\u2500\u25B6 expired\n * ```\n *\n * Every other transition is rejected with `AiPendingActionStateError`.\n */\nexport const AI_PENDING_ACTION_ALLOWED_TRANSITIONS: Record<\n  AiPendingActionStatus,\n  ReadonlyArray<AiPendingActionStatus>\n> = {\n  pending: ['confirmed', 'cancelled', 'expired'],\n  confirmed: ['executing'],\n  executing: ['confirmed', 'failed'],\n  cancelled: [],\n  expired: [],\n  failed: [],\n}\n\nexport const AI_PENDING_ACTION_TERMINAL_STATUSES: ReadonlyArray<AiPendingActionStatus> = [\n  'confirmed',\n  'cancelled',\n  'expired',\n  'failed',\n]\n\n/**\n * Per-record batch diff entry, mirrored in `AiPendingAction.records`.\n *\n * When present, the batch diff is authoritative and `fieldDiff` at the\n * top level is ignored by every consumer (spec \u00A78 rule 2).\n */\nexport type AiPendingActionRecordDiff = {\n  recordId: string\n  entityType: string\n  label: string\n  fieldDiff: Array<{ field: string; before: unknown; after: unknown }>\n  recordVersion: string | null\n  attachmentIds?: string[]\n}\n\n/**\n * Per-record failure shape populated by the confirm handler (Step 5.8)\n * when partial success occurs inside a batch.\n */\nexport type AiPendingActionFailedRecord = {\n  recordId: string\n  error: { code: string; message: string }\n}\n\nexport type AiPendingActionFieldDiff = {\n  field: string\n  before: unknown\n  after: unknown\n}\n\n/**\n * Structured error context the confirm-executor stamps on\n * `executionResult.error` when a tool handler throws. Additive \u2014 every\n * field is optional so older serialized snapshots remain valid.\n *\n *  - `details`: free-form structured payload extracted from the thrown\n *    error (e.g. ZodError `issues`, `cause`, custom error properties).\n *    Forwarded verbatim to the operator's \"Fix with AI\" prompt so the\n *    model can correct the call instead of staring at \"Invalid input\".\n *  - `input`: a JSON-serializable echo of the arguments the handler was\n *    invoked with. Lets the model compare what it sent vs. what the\n *    schema expected. PII-redaction is the caller's responsibility (the\n *    confirm-executor passes through `normalizedInput` which has already\n *    been Zod-parsed and stripped of unknown keys).\n *  - `name`: the constructor name of the thrown error (e.g. `ZodError`,\n *    `TypeError`) \u2014 useful when the message is generic.\n *  - `stack`: short stack snippet for handler-side diagnostics. Kept off\n *    by default (only populated when `OM_AI_INCLUDE_HANDLER_STACK=1`).\n */\nexport type AiPendingActionExecutionErrorDetails = {\n  issues?: Array<{ path?: (string | number)[]; message?: string; code?: string }>\n  fieldErrors?: Record<string, string[]>\n  cause?: unknown\n  [key: string]: unknown\n}\n\nexport type AiPendingActionExecutionResult = {\n  recordId?: string\n  commandName?: string\n  error?: {\n    code: string\n    message: string\n    name?: string\n    details?: AiPendingActionExecutionErrorDetails\n    input?: unknown\n    stack?: string\n  }\n}\n\n/**\n * Thrown by the repository when a caller attempts an illegal status\n * transition (e.g. `confirmed \u2192 pending`). Callers at the route layer\n * turn this into a `409 Conflict` response.\n */\nexport class AiPendingActionStateError extends Error {\n  public readonly code = 'ai_pending_action_invalid_transition'\n\n  constructor(\n    public readonly from: AiPendingActionStatus,\n    public readonly to: AiPendingActionStatus,\n  ) {\n    super(`Illegal AiPendingAction status transition: ${from} \u2192 ${to}`)\n    this.name = 'AiPendingActionStateError'\n  }\n}\n\nexport function isAiPendingActionStatus(\n  value: unknown,\n): value is AiPendingActionStatus {\n  return (\n    typeof value === 'string' &&\n    (AI_PENDING_ACTION_STATUSES as readonly string[]).includes(value)\n  )\n}\n\nexport function isAiPendingActionQueueMode(\n  value: unknown,\n): value is AiPendingActionQueueMode {\n  return (\n    typeof value === 'string' &&\n    (AI_PENDING_ACTION_QUEUE_MODES as readonly string[]).includes(value)\n  )\n}\n\nexport function isTerminalAiPendingActionStatus(\n  status: AiPendingActionStatus,\n): boolean {\n  return AI_PENDING_ACTION_TERMINAL_STATUSES.includes(status)\n}\n\nexport function isAllowedAiPendingActionTransition(\n  from: AiPendingActionStatus,\n  to: AiPendingActionStatus,\n): boolean {\n  return (AI_PENDING_ACTION_ALLOWED_TRANSITIONS[from] ?? []).includes(to)\n}\n\n/**\n * Default TTL for a pending action (spec \u00A78 rule `expiresAt defaults to 10 min;\n * overridable per agent`). The runtime default is 15 min here because the\n * Step 5.5 brief pins it there; the repo reads `AI_PENDING_ACTION_TTL_SECONDS`\n * from the environment to allow override without a code change.\n */\nexport const AI_PENDING_ACTION_DEFAULT_TTL_SECONDS = 900\nexport const AI_PENDING_ACTION_TTL_ENV_VAR = 'AI_PENDING_ACTION_TTL_SECONDS'\n\nexport function resolveAiPendingActionTtlSeconds(\n  env: NodeJS.ProcessEnv = process.env,\n): number {\n  const raw = env[AI_PENDING_ACTION_TTL_ENV_VAR]\n  if (raw == null) return AI_PENDING_ACTION_DEFAULT_TTL_SECONDS\n  const parsed = Number.parseInt(String(raw), 10)\n  if (!Number.isFinite(parsed) || parsed <= 0) {\n    return AI_PENDING_ACTION_DEFAULT_TTL_SECONDS\n  }\n  return parsed\n}\n"],
+  "mappings": "AAUO,MAAM,6BAA6B;AAAA,EACxC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAIO,MAAM,gCAAgC,CAAC,UAAU,OAAO;AAiBxD,MAAM,wCAGT;AAAA,EACF,SAAS,CAAC,aAAa,aAAa,SAAS;AAAA,EAC7C,WAAW,CAAC,WAAW;AAAA,EACvB,WAAW,CAAC,aAAa,QAAQ;AAAA,EACjC,WAAW,CAAC;AAAA,EACZ,SAAS,CAAC;AAAA,EACV,QAAQ,CAAC;AACX;AAEO,MAAM,sCAA4E;AAAA,EACvF;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AA4EO,MAAM,kCAAkC,MAAM;AAAA,EAGnD,YACkB,MACA,IAChB;AACA,UAAM,8CAA8C,IAAI,WAAM,EAAE,EAAE;AAHlD;AACA;AAJlB,SAAgB,OAAO;AAOrB,SAAK,OAAO;AAAA,EACd;AACF;AAEO,SAAS,wBACd,OACgC;AAChC,SACE,OAAO,UAAU,YAChB,2BAAiD,SAAS,KAAK;AAEpE;AAEO,SAAS,2BACd,OACmC;AACnC,SACE,OAAO,UAAU,YAChB,8BAAoD,SAAS,KAAK;AAEvE;AAEO,SAAS,gCACd,QACS;AACT,SAAO,oCAAoC,SAAS,MAAM;AAC5D;AAEO,SAAS,mCACd,MACA,IACS;AACT,UAAQ,sCAAsC,IAAI,KAAK,CAAC,GAAG,SAAS,EAAE;AACxE;AAQO,MAAM,wCAAwC;AAC9C,MAAM,gCAAgC;AAEtC,SAAS,iCACd,MAAyB,QAAQ,KACzB;AACR,QAAM,MAAM,IAAI,6BAA6B;AAC7C,MAAI,OAAO,KAAM,QAAO;AACxB,QAAM,SAAS,OAAO,SAAS,OAAO,GAAG,GAAG,EAAE;AAC9C,MAAI,CAAC,OAAO,SAAS,MAAM,KAAK,UAAU,GAAG;AAC3C,WAAO;AAAA,EACT;AACA,SAAO;AACT;",
+  "names": []
+}