@open-mercato/core 0.7.1-develop.7193.1.910a5b0a1e → 0.7.1-develop.7194.1.ab4fc81f82

package/src/modules/workflows/lib/advanced-config.ts

@@ -0,0 +1,41 @@
+/**
+ * Advanced Configuration value handling shared by the node and edge form transforms.
+ *
+ * The CrudForm dialogs render the Advanced Configuration field with JsonBuilder,
+ * which emits the PARSED OBJECT on every valid edit. Legacy callers (and tests)
+ * may still hand the transforms a JSON string. The transform boundary accepts
+ * both: objects are used directly, strings are trimmed and parsed. Invalid
+ * strings and non-object payloads surface the existing i18n validation key.
+ */
+
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+const logger = createLogger('workflows')
+
+export type AdvancedConfigValue = Record<string, unknown> | string | undefined
+
+export function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+export function parseAdvancedConfigValue(value: AdvancedConfigValue): Record<string, unknown> | undefined {
+  if (value === undefined || value === null) return undefined
+  if (typeof value === 'object') {
+    if (!isPlainRecord(value)) {
+      logger.error('Advanced Configuration must be a JSON object', { received: Array.isArray(value) ? 'array' : typeof value })
+      throw new Error('workflows.validation.invalidAdvancedConfigJson')
+    }
+    return Object.keys(value).length > 0 ? value : undefined
+  }
+  if (!value.trim()) return undefined
+  try {
+    const parsed: unknown = JSON.parse(value)
+    if (!isPlainRecord(parsed)) {
+      throw new Error('[internal] advanced configuration must parse to a JSON object')
+    }
+    return Object.keys(parsed).length > 0 ? parsed : undefined
+  } catch (error) {
+    logger.error('Invalid JSON in Advanced Configuration', { err: error })
+    throw new Error('workflows.validation.invalidAdvancedConfigJson')
+  }
+}

package/src/modules/workflows/lib/agent-disposition-task.ts

@@ -0,0 +1,343 @@
+/**
+ * Workflows Module — the implicit agent-disposition task (spec §7.5).
+ *
+ * When an INVOKE_AGENT step's confidence gate routes to a human, the enterprise
+ * `dispositionService` raises a workflows `USER_TASK` for that decision. Until
+ * now it built that row itself, inline, with no assignee, no role queue, no
+ * deadline, no audit event and no assignment event — which under the §6.4
+ * visibility model produces a task that is visible only to administrative
+ * oversight and ACTABLE BY NOBODY (`currentTaskOwnerId` is null, so
+ * `ownsTheRow` is false for every principal), and which never reaches the
+ * notification subscriber at all.
+ *
+ * The disposition task is supposed to be "a real Work Inbox task" (§7.5), so
+ * the row is built HERE, by the module that owns the entity, the audit log, the
+ * assignment event and the SLA scheduler — and the enterprise service passes
+ * the authored Review descriptor in. `agent_orchestrator` stays an optional
+ * peer in both directions: it reaches this module through a dynamic import
+ * guarded by its own try/catch, exactly as `lib/disposition/resume.ts` reaches
+ * `sendSignal`.
+ */
+
+import type { EntityManager } from '@mikro-orm/core'
+import type { AwilixContainer } from 'awilix'
+import { StepInstance, UserTask, WorkflowInstance } from '../data/entities'
+import { calculateDueDate } from './duration'
+import { scheduleUserTaskSla } from './task-sla'
+import { emitWorkflowsEvent } from '../events'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+const logger = createLogger('workflows')
+
+/**
+ * The already-resolved Review section: assignment interpolated against the run
+ * context and the deadline still expressed as a DURATION, because a disposition
+ * deadline is anchored to when the task is created — not to when the agent was
+ * enqueued, which can be minutes earlier.
+ */
+export interface AgentDispositionReview {
+  assignedTo?: string | null
+  assignedToRoles?: string[] | null
+  priority?: string | null
+  deadlineDuration?: string | null
+  reminders?: { offset: string }[] | null
+}
+
+export interface CreateAgentDispositionTaskOptions {
+  workflowInstanceId: string
+  stepId: string
+  proposalId: string
+  agentId: string
+  proposalPayload: unknown
+  confidence: number | null
+  taskName: string
+  description: string
+  review?: AgentDispositionReview | null
+  tenantId: string
+  organizationId: string
+  userId?: string
+  now?: Date
+}
+
+export interface CreatedAgentDispositionTask {
+  userTaskId: string
+  stepInstanceId: string
+  assignedTo: string | null
+  assignedToRoles: string[] | null
+  dueDate: Date | null
+}
+
+function resolveDueDate(
+  duration: string | null | undefined,
+  now: Date,
+  proposalId: string,
+): Date | null {
+  if (typeof duration !== 'string' || !duration.length) return null
+  try {
+    return calculateDueDate(duration, now)
+  } catch (error) {
+    // An unparseable deadline must not cost the operator the task. A USER_TASK
+    // step fails the step here; a disposition task cannot, because the agent has
+    // already run and its proposal is already pending — losing the review task
+    // would strand the proposal with nobody able to see it.
+    logger.warn('Agent review deadline skipped because it is not a valid duration', {
+      component: 'agent-disposition-task',
+      proposalId,
+      duration,
+    })
+    return null
+  }
+}
+
+/**
+ * Create the disposition task for a pending proposal.
+ *
+ * Returns the created task; throws only when the workflow instance the caller
+ * named cannot be read, which is the caller's signal to fall back to its
+ * synthetic id.
+ */
+export async function createAgentDispositionTask(
+  em: EntityManager,
+  container: AwilixContainer,
+  options: CreateAgentDispositionTaskOptions,
+): Promise<CreatedAgentDispositionTask> {
+  const { tenantId, organizationId } = options
+  const now = options.now ?? new Date()
+
+  const instance = await em.findOne(WorkflowInstance, {
+    id: options.workflowInstanceId,
+    tenantId,
+    organizationId,
+  })
+  if (!instance) {
+    throw new Error(
+      `[internal] workflow instance ${options.workflowInstanceId} not found for agent disposition task`,
+    )
+  }
+
+  const stepInstance = await em.findOne(StepInstance, {
+    workflowInstanceId: options.workflowInstanceId,
+    stepId: options.stepId,
+    status: 'ACTIVE',
+    tenantId,
+    organizationId,
+  })
+
+  const review = options.review ?? null
+  const assignedTo = review?.assignedTo?.length ? review.assignedTo : null
+  const assignedToRoles = review?.assignedToRoles?.length ? review.assignedToRoles : null
+  const dueDate = resolveDueDate(review?.deadlineDuration, now, options.proposalId)
+
+  const task = em.create(UserTask, {
+    workflowInstanceId: options.workflowInstanceId,
+    // The step instance is what the SLA scheduler, the run view and the §6.4
+    // gate address. Falling back to the workflow instance id (as the inline
+    // version did) writes a value that is not a step instance at all.
+    stepInstanceId: stepInstance?.id ?? options.workflowInstanceId,
+    branchInstanceId: stepInstance?.branchInstanceId ?? null,
+    taskName: options.taskName,
+    description: options.description,
+    status: 'PENDING',
+    formSchema: {
+      proposalId: options.proposalId,
+      payload: options.proposalPayload,
+      confidence: options.confidence,
+    },
+    assignedTo,
+    // Always the backoffice namespace: a proposal is disposed from the operator
+    // caseload, and no portal surface can dispose one.
+    assigneeKind: 'user',
+    assignedToRoles,
+    priority: review?.priority ?? null,
+    dueDate,
+    tenantId,
+    organizationId,
+    createdAt: now,
+    updatedAt: now,
+  })
+
+  em.persist(task)
+  await em.flush()
+
+  await logDispositionTaskEvent(em, container, {
+    workflowInstanceId: options.workflowInstanceId,
+    stepInstanceId: task.stepInstanceId,
+    branchInstanceId: task.branchInstanceId ?? null,
+    eventType: 'USER_TASK_CREATED',
+    eventData: {
+      userTaskId: task.id,
+      taskName: task.taskName,
+      assignedTo: task.assignedTo,
+      assignedToRoles: task.assignedToRoles,
+      proposalId: options.proposalId,
+      agentId: options.agentId,
+      ...(task.priority ? { priority: task.priority } : {}),
+      ...(dueDate ? { dueDate: dueDate.toISOString() } : {}),
+    },
+    userId: options.userId,
+    tenantId,
+    organizationId,
+  })
+
+  await emitDispositionTaskAssigned(task, instance)
+
+  // Reminders and the deadline breach ride the SAME queue-backed scheduler a
+  // USER_TASK's do — one job per authored offset plus one for the deadline, all
+  // enqueued here with the deadline ABSOLUTE on the payload. A task with no
+  // deadline schedules nothing. What the breach then DOES is escalate-only
+  // (`lib/task-sla.ts` → `applyBreachHandling`): it never disposes the proposal
+  // and never routes the run past it.
+  await scheduleUserTaskSla({
+    workflowInstanceId: options.workflowInstanceId,
+    stepInstanceId: task.stepInstanceId,
+    branchInstanceId: task.branchInstanceId ?? null,
+    userTaskId: task.id,
+    dueDate,
+    reminders: review?.reminders ?? null,
+    tenantId,
+    organizationId,
+    userId: options.userId,
+    now,
+  })
+
+  return {
+    userTaskId: task.id,
+    stepInstanceId: task.stepInstanceId,
+    assignedTo,
+    assignedToRoles,
+    dueDate,
+  }
+}
+
+export interface CloseAgentDispositionTaskOptions {
+  userTaskId: string
+  /** The verdict that closed it — audit only; it never decides anything here. */
+  disposition: string
+  closedBy?: string | null
+  tenantId: string
+  organizationId: string
+  now?: Date
+}
+
+/** Statuses a disposition task is still open in — anything else is already closed. */
+const OPEN_TASK_STATUSES = ['PENDING', 'IN_PROGRESS'] as const
+
+/**
+ * Close the review task a disposed proposal no longer needs (A7).
+ *
+ * The decision has already been made and committed by the caller; this only
+ * clears the work item so the operator's inbox stops offering a decision that
+ * has already been taken. It deliberately does NOT complete the task through
+ * `completeUserTask`: that would ADVANCE the run, and the run resumes on
+ * `agent_orchestrator.proposal.ready` instead. Closing a task and advancing a
+ * workflow are different acts, and only the second one belongs to the engine.
+ *
+ * Idempotent by construction: the status change is claimed with a conditional
+ * UPDATE, so a redelivered close (or a task a human already completed) updates
+ * zero rows and returns `noop`.
+ */
+export async function closeAgentDispositionTask(
+  em: EntityManager,
+  container: AwilixContainer,
+  options: CloseAgentDispositionTaskOptions,
+): Promise<'closed' | 'noop'> {
+  const { tenantId, organizationId } = options
+  const now = options.now ?? new Date()
+
+  const task = await em.findOne(UserTask, {
+    id: options.userTaskId,
+    tenantId,
+    organizationId,
+  })
+  if (!task) return 'noop'
+
+  const claimed = await em.nativeUpdate(
+    UserTask,
+    {
+      id: task.id,
+      tenantId,
+      organizationId,
+      status: { $in: [...OPEN_TASK_STATUSES] },
+    },
+    {
+      status: 'COMPLETED',
+      completedAt: now,
+      completedBy: options.closedBy ?? null,
+      updatedAt: now,
+    },
+  )
+  if (claimed === 0) return 'noop'
+
+  await logDispositionTaskEvent(em, container, {
+    workflowInstanceId: task.workflowInstanceId,
+    stepInstanceId: task.stepInstanceId,
+    ...(task.branchInstanceId ? { branchInstanceId: task.branchInstanceId } : {}),
+    eventType: 'USER_TASK_COMPLETED',
+    eventData: {
+      userTaskId: task.id,
+      taskName: task.taskName,
+      closedBy: 'agent_disposition',
+      disposition: options.disposition,
+    },
+    tenantId,
+    organizationId,
+  })
+
+  return 'closed'
+}
+
+/**
+ * Publish `workflows.task.assigned` for a disposition task, so it reaches the
+ * notification subscriber the same way every other task does. Best-effort by
+ * contract: the proposal is already pending and the task row already committed,
+ * so a bus failure must never turn into a failed disposition.
+ */
+async function emitDispositionTaskAssigned(
+  task: UserTask,
+  instance: WorkflowInstance,
+): Promise<void> {
+  try {
+    await emitWorkflowsEvent(
+      'workflows.task.assigned',
+      {
+        taskId: task.id,
+        taskName: task.taskName,
+        workflowInstanceId: instance.id,
+        workflowId: instance.workflowId,
+        workflowName: instance.workflowId,
+        assignedUserId: task.assignedTo ?? null,
+        assignedToRoles: task.assignedToRoles ?? null,
+        dueDate: task.dueDate ? task.dueDate.toISOString() : null,
+        entityBindings: task.entityBindings ?? null,
+        tenantId: instance.tenantId,
+        organizationId: instance.organizationId ?? null,
+      },
+      { persistent: true },
+    )
+  } catch (error) {
+    logger.error('Failed to emit workflows.task.assigned for an agent disposition task', {
+      component: 'agent-disposition-task',
+      taskId: task.id,
+      err: error,
+    })
+  }
+}
+
+async function logDispositionTaskEvent(
+  em: EntityManager,
+  container: AwilixContainer,
+  event: Record<string, unknown>,
+): Promise<void> {
+  try {
+    const eventLogger = container.resolve<{
+      logWorkflowEvent: (em: EntityManager, event: Record<string, unknown>) => Promise<unknown>
+    }>('eventLogger')
+    await eventLogger.logWorkflowEvent(em, event)
+  } catch (error) {
+    logger.error('Failed to log an agent disposition task workflow event', {
+      component: 'agent-disposition-task',
+      eventType: event.eventType,
+      err: error,
+    })
+  }
+}

package/src/modules/workflows/lib/agent-outcome-paths.ts

@@ -0,0 +1,153 @@
+/**
+ * Workflows Module - INVOKE_AGENT source-path vocabulary (spec
+ * 2026-07-26-workflows-ux-redesign.md sections 3.4 / 7.1).
+ *
+ * Pure translation of an agent's declared OUTCOME JSON-Schema (served by the
+ * optional agent_orchestrator peer on `/api/agent_orchestrator/agents`) into
+ * the dot paths an `outputMapping` row may read from. The vocabulary is the
+ * normalized result envelope `mapAgentResultToContext` builds: the platform's
+ * own `kind`/`disposition`/`agentId`/`proposalId` keys, plus the agent's OUTCOME
+ * under `data` (researcher agents) or `proposalPayload` (proposal ones).
+ *
+ * No React, no network, no registry — the editor feeds it the fetched schema and
+ * gets back plain data, so the same helper backs the source picker, the
+ * author-time path check, and the "Insert sample" rows.
+ */
+
+export type AgentResultKind = 'research' | 'proposal'
+
+export interface AgentOutcomeSchemaNode {
+  type?: string
+  properties?: Record<string, AgentOutcomeSchemaNode>
+  items?: AgentOutcomeSchemaNode
+}
+
+export interface AgentSourcePath {
+  path: string
+  type: string
+  /**
+   * True only for an object whose properties this vocabulary does NOT describe
+   * (declared without `properties`, or nested past the depth cap). Deeper paths
+   * below such a node stay valid; a fully described object is closed, so an
+   * undeclared property under it is an author error.
+   */
+  container: boolean
+}
+
+export interface AgentInputRow {
+  key: string
+  value: string
+}
+
+const MAX_OUTCOME_DEPTH = 3
+
+const ENVELOPE_PATHS: ReadonlyArray<AgentSourcePath> = [
+  { path: 'kind', type: 'text', container: false },
+  { path: 'disposition', type: 'text', container: false },
+  { path: 'agentId', type: 'text', container: false },
+  { path: 'proposalId', type: 'text', container: false },
+]
+
+const JSON_TYPE_LABELS: Record<string, string> = {
+  string: 'text',
+  number: 'number',
+  integer: 'number',
+  boolean: 'boolean',
+  object: 'object',
+  array: 'array',
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function labelFor(node: AgentOutcomeSchemaNode | undefined): string {
+  const type = node?.type
+  return typeof type === 'string' ? JSON_TYPE_LABELS[type] ?? 'unknown' : 'unknown'
+}
+
+export function agentOutcomeRootKey(resultKind: AgentResultKind): 'data' | 'proposalPayload' {
+  return resultKind === 'research' ? 'data' : 'proposalPayload'
+}
+
+function describesProperties(node: AgentOutcomeSchemaNode): boolean {
+  const properties = node.properties
+  return isPlainObject(properties) && Object.keys(properties).length > 0
+}
+
+function collectOutcomePaths(
+  node: AgentOutcomeSchemaNode,
+  prefix: string,
+  depth: number,
+  collected: AgentSourcePath[],
+): void {
+  const properties = node.properties
+  if (!isPlainObject(properties)) return
+  for (const [name, child] of Object.entries(properties)) {
+    if (!name || !isPlainObject(child)) continue
+    const childNode = child as AgentOutcomeSchemaNode
+    const path = `${prefix}.${name}`
+    const expandable =
+      childNode.type === 'object' && describesProperties(childNode) && depth < MAX_OUTCOME_DEPTH
+    collected.push({ path, type: labelFor(childNode), container: !expandable && childNode.type === 'object' })
+    if (expandable) collectOutcomePaths(childNode, path, depth + 1, collected)
+  }
+}
+
+/**
+ * Every source path an outputMapping row may reference for the selected agent.
+ * Returns an empty list when the agent declares no usable OUTCOME shape — the
+ * caller then keeps free text and skips the author-time check rather than
+ * flagging paths it cannot verify.
+ */
+export function buildAgentSourcePaths(
+  resultKind: AgentResultKind | undefined,
+  outcomeSchema: unknown,
+): AgentSourcePath[] {
+  if (!resultKind || !isPlainObject(outcomeSchema)) return []
+  const rootKey = agentOutcomeRootKey(resultKind)
+  const root = outcomeSchema as AgentOutcomeSchemaNode
+  const paths: AgentSourcePath[] = [
+    ...ENVELOPE_PATHS,
+    { path: rootKey, type: 'object', container: !describesProperties(root) },
+  ]
+  collectOutcomePaths(root, rootKey, 1, paths)
+  return paths
+}
+
+export function isTemplateExpression(value: string): boolean {
+  return /\{\{.*\}\}/.test(value)
+}
+
+/**
+ * A source path resolves when it names a declared path or descends into an
+ * object this vocabulary does not describe. A blank path (a row still being
+ * written) and an agent with no declared OUTCOME both resolve — the check only
+ * fires where the schema can actually prove the path wrong.
+ */
+export function isKnownAgentSourcePath(paths: ReadonlyArray<AgentSourcePath>, value: string): boolean {
+  const trimmed = value.trim()
+  if (trimmed.length === 0) return true
+  if (paths.length === 0) return true
+  return paths.some(
+    (candidate) =>
+      candidate.path === trimmed || (candidate.container && trimmed.startsWith(`${candidate.path}.`)),
+  )
+}
+
+export function agentSampleInputKeys(sampleInput: unknown): string[] {
+  return isPlainObject(sampleInput) ? Object.keys(sampleInput) : []
+}
+
+/**
+ * The `input` rows an agent's SAMPLE input fills in. String values are inserted
+ * verbatim (they may already be `{{context.*}}` pills); anything else is
+ * serialized so the author sees the exact literal the step will send.
+ */
+export function agentSampleInputRows(sampleInput: unknown): AgentInputRow[] {
+  if (!isPlainObject(sampleInput)) return []
+  return Object.entries(sampleInput).map(([key, value]) => ({
+    key,
+    value: typeof value === 'string' ? value : JSON.stringify(value) ?? '',
+  }))
+}

package/src/modules/workflows/lib/agent-result-mapping.ts

@@ -0,0 +1,88 @@
+/**
+ * Maps an INVOKE_AGENT result into a workflow-context patch.
+ *
+ * An INVOKE_AGENT activity may declare an optional `outputMapping` (mirroring
+ * SUB_WORKFLOW). When present, the agent's result is routed into the chosen
+ * context keys instead of the legacy fixed keys. The mapping reads from a
+ * normalized envelope so authors address a stable contract regardless of the
+ * runtime (in-process vs OpenCode) or the resolution path (inline branch vs
+ * parked-and-resumed worker).
+ *
+ * Returns the mapped patch when a non-empty mapping is provided, otherwise
+ * `null` to signal the caller should fall back to its legacy fixed-key payload —
+ * keeping existing definitions byte-for-byte backward compatible.
+ */
+
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+const logger = createLogger('workflows').child({ component: 'agent-result-mapping' })
+
+export type AgentResultEnvelope = {
+  kind: 'auto_approved' | 'research' | 'user_task' | 'none_proposed' | 'artifact'
+  agentId?: string
+  proposalId?: string
+  proposalPayload?: unknown
+  data?: unknown
+  /** Set for an `artifact` result: the files the run produced, by reference. */
+  artifacts?: unknown[]
+}
+
+function getNestedValue(obj: any, path: string): any {
+  return path.split('.').reduce((current, key) => current?.[key], obj)
+}
+
+function setNestedValue(obj: Record<string, any>, path: string, value: any): void {
+  const keys = path.split('.')
+  const lastKey = keys.pop()!
+  const target = keys.reduce<Record<string, any>>((current, key) => {
+    if (!(key in current)) current[key] = {}
+    return current[key]
+  }, obj)
+  target[lastKey] = value
+}
+
+function warnOnTemplateMapping(sourcePath: string): void {
+  if (/\{\{.*\}\}/.test(sourcePath)) {
+    logger.warn(
+      'INVOKE_AGENT outputMapping value looks like a {{ }} template, but mapping values are plain ' +
+        'dot-paths into the agent result envelope (e.g. "proposalPayload.riskScore"). This entry ' +
+        'will not resolve and is being ignored.',
+      { sourcePath }
+    )
+  }
+}
+
+export function mapAgentResultToContext(
+  envelope: AgentResultEnvelope,
+  outputMapping: Record<string, string> | undefined | null
+): Record<string, any> | null {
+  if (!outputMapping || Object.keys(outputMapping).length === 0) return null
+
+  const source = {
+    kind: envelope.kind,
+    // `artifact` reports as `researcher` here for the same reason it routes onto
+    // that handle: the disposition vocabulary describes DECISIONS, and producing
+    // a file is not one. The `kind` above still says what actually came back.
+    //
+    // Note the two spellings are deliberate: `research` is the agent RESULT kind
+    // (unification spec §7), `researcher` the core-owned outcome handle it routes
+    // to. Renaming the handle would rewrite persisted workflow graphs.
+    disposition:
+      envelope.kind === 'research' || envelope.kind === 'artifact' ? 'researcher' : envelope.kind,
+    agentId: envelope.agentId,
+    proposalId: envelope.proposalId,
+    proposalPayload: envelope.proposalPayload,
+    data: envelope.data,
+    artifacts: envelope.artifacts,
+  }
+
+  const result: Record<string, any> = {}
+  for (const [targetKey, sourcePath] of Object.entries(outputMapping)) {
+    warnOnTemplateMapping(sourcePath)
+    const value = getNestedValue(source, sourcePath)
+    if (value !== undefined) {
+      setNestedValue(result, targetKey, value)
+    }
+  }
+  return result
+}