@open-mercato/core 0.7.1-develop.7193.1.910a5b0a1e → 0.7.1-develop.7195.1.b5efd1d51a

package/src/modules/workflows/acl.ts

@@ -44,6 +44,30 @@ export const features = [
     module: moduleId,
     dependsOn: ['workflows.definitions.view'],
   },
+  {
+    // Declaring a definition's own execution grant is strictly broader than
+    // editing it: the grant decides which ACL features EVERY run of that
+    // version executes with, so folding it into `definitions.edit` would let
+    // any workflow author mint a principal with powers they were never given.
+    // It is additionally bounded at save time — a grant can never exceed the
+    // saving user's own current features.
+    id: 'workflows.definitions.grant_features',
+    title: 'Grant execution features to workflow definitions',
+    module: moduleId,
+    dependsOn: ['workflows.definitions.edit'],
+  },
+  {
+    id: 'workflows.definitions.test_run',
+    title: 'Test workflow definition steps',
+    module: moduleId,
+    dependsOn: ['workflows.definitions.edit'],
+  },
+  {
+    id: 'workflows.definitions.publish',
+    title: 'Publish workflow definition versions',
+    module: moduleId,
+    dependsOn: ['workflows.definitions.edit'],
+  },
   {
     id: 'workflows.instances.view',
     title: 'View workflow instances',
@@ -74,6 +98,34 @@ export const features = [
     module: moduleId,
     dependsOn: ['workflows.instances.view'],
   },
+  {
+    // Writing arbitrary run context is strictly broader than sending a named
+    // signal, so it is deliberately NOT folded into workflows.instances.signal.
+    id: 'workflows.instances.update_context',
+    title: 'Update workflow instance context',
+    module: moduleId,
+    dependsOn: ['workflows.instances.view'],
+  },
+  {
+    // Spec 8.4 ACL appendix: `workflows.instances.rerun_step` (admins/devs).
+    // Replaying a step re-executes real side effects with possibly EDITED
+    // context, which `workflows.instances.retry` (replay the run as it stands)
+    // does not authorise — hence its own feature rather than an implication.
+    id: 'workflows.instances.rerun_step',
+    title: 'Rerun a workflow instance from a step',
+    module: moduleId,
+    dependsOn: ['workflows.instances.retry', 'workflows.instances.update_context'],
+  },
+  {
+    // Spec 8.4 ACL appendix: `workflows.instances.bulk_ops` (admins). Retrying
+    // or cancelling a page of instances at once is strictly broader than doing
+    // it one row at a time — a misfire re-executes hundreds of real workflows —
+    // so it is its own feature rather than an implication of `retry`/`cancel`.
+    id: 'workflows.instances.bulk_ops',
+    title: 'Bulk retry or cancel workflow instances',
+    module: moduleId,
+    dependsOn: ['workflows.instances.retry', 'workflows.instances.cancel'],
+  },
   {
     id: 'workflows.tasks.view',
     title: 'View user tasks',
@@ -92,6 +144,38 @@ export const features = [
     module: moduleId,
     dependsOn: ['workflows.tasks.view'],
   },
+  {
+    // Administration, per spec §6.4: `workflows.tasks.*` gates viewing OTHER
+    // people's work, never one's own. Reading a task you have no relationship
+    // to still passes the same entity gate — this widens WHOSE rows you see,
+    // not WHICH entities you may see them about. It deliberately grants no act:
+    // an administrator reassigns a task to themselves (audited) before they can
+    // complete it, which is what keeps "who approved this?" answerable.
+    //
+    // `dependsOn: ['workflows.tasks.view']` keeps the older id load-bearing
+    // rather than leaving it a stored-but-unconsulted grant: it still admits a
+    // caller to the task API, and this feature decides which rows come back.
+    id: 'workflows.tasks.view_all',
+    title: 'View all workflow tasks',
+    module: moduleId,
+    dependsOn: ['workflows.tasks.view'],
+  },
+  {
+    // The ONLY supported route from "I can see this task" to "I can act on it".
+    // Writes the reassignment audit columns plus a WorkflowEvent.
+    id: 'workflows.tasks.reassign',
+    title: 'Reassign workflow tasks',
+    module: moduleId,
+    dependsOn: ['workflows.tasks.view_all'],
+  },
+  {
+    // Administrative mutations that are not reassignment: force-unclaim, cancel,
+    // bulk operations, and writing the tenant task-permission setting.
+    id: 'workflows.tasks.manage',
+    title: 'Administer workflow tasks',
+    module: moduleId,
+    dependsOn: ['workflows.tasks.view_all'],
+  },
   {
     id: 'workflows.signals.send',
     title: 'Send workflow signals',
@@ -104,6 +188,18 @@ export const features = [
     module: moduleId,
     dependsOn: ['workflows.view'],
   },
+  {
+    // Spec §8.5 operations KPIs. Its own feature rather than an implication of
+    // `definitions.view`: a rollup states how often a process fails and how
+    // long it takes across every run in the organization, which is an
+    // aggregate over runs the caller may not be entitled to open one by one.
+    // `dependsOn: ['workflows.definitions.view']` because a KPI without the
+    // definition it belongs to names nothing the reader can act on.
+    id: 'workflows.metrics.view',
+    title: 'View workflow operational metrics',
+    module: moduleId,
+    dependsOn: ['workflows.definitions.view'],
+  },
   // Note: Event triggers are now embedded in workflow definitions.
   // Trigger management permissions are covered by workflows.definitions.edit
 ]

package/src/modules/workflows/ai-agents.ts

@@ -0,0 +1,80 @@
+/**
+ * Module-root AI agent contribution for the workflows module (spec §9,
+ * "prompt-to-draft").
+ *
+ * ONE agent, and its shape IS the trust boundary:
+ *
+ *  - `executionMode: 'object'` — it emits a structured draft against
+ *    `workflowDraftGenerationSchema`, not prose. Generation targets schemas.
+ *    Its one tool runs inside the runtime's object-mode tool loop
+ *    (`runAiAgentObject({ enableTools: true })`), which still finalizes through
+ *    `Output.object`, so the emitted result stays a validated draft.
+ *  - `allowedTools: ['workflows.validate_workflow_definition']` — exactly ONE
+ *    READ-ONLY tool. It reads no tenant rows and writes nothing; it re-runs the
+ *    real definition schema + Problems pass so the agent can self-correct a
+ *    draft (e.g. a partial INVOKE_AGENT config) before returning. This is a
+ *    deliberate, bounded relaxation of the former empty allowlist — the broader
+ *    `workflows.*` authoring/write tools (create/update/test-run) remain out of
+ *    reach; this in-Studio path reaches only the validator.
+ *  - `readOnly: true` + `mutationPolicy: 'read-only'` — belt and braces, so a
+ *    later tool addition cannot quietly become write-capable (the runtime
+ *    strips any `isMutation` tool from a read-only agent).
+ *
+ * The route that calls it (`api/definitions/generate`) persists NOTHING. A
+ * generated definition becomes real only after a human applies it to the canvas
+ * AND saves AND enables it — three separate deliberate acts.
+ *
+ * Requires `yarn generate` to be discovered; until then the runtime answers
+ * `agent_unknown` and the Studio reports that AI authoring is unavailable.
+ */
+import type { AiAgentDefinition } from '@open-mercato/ai-assistant/modules/ai_assistant/lib/ai-agent-definition'
+import {
+  WORKFLOW_DRAFT_AGENT_ID,
+  workflowDraftGenerationSchema,
+} from './lib/ai-authoring'
+
+const SYSTEM_PROMPT = [
+  'ROLE: You author Open Mercato workflow definitions from a plain-language request.',
+  '',
+  'SCOPE: You produce a DRAFT for a human to review in the workflow Studio. You never publish, enable or execute anything. Your only tool is workflows.validate_workflow_definition, a read-only validator; the request carries every identifier you are allowed to use.',
+  '',
+  'SELF-CHECK: Before you return, call workflows.validate_workflow_definition with your draft and fix every reported error. Re-validate until it reports no errors.',
+  '',
+  'DATA: The request contains a catalog of the step types, transition triggers, activity types (with their JSON-Schema config contracts), safe command ids, registered function names and declared event ids this installation actually has. Any identifier outside that catalog does not exist. If the request cannot be satisfied with the catalog, author the closest workflow you can and describe the gap in `summary`.',
+  '',
+  'STRUCTURE: Exactly one START step and at least one END step. Every step except END has an outgoing transition; every step except START is reachable from START. Ids use lowercase letters, numbers, hyphens and underscores only. Activities run on the transition LEAVING the step whose work they perform.',
+  '',
+  'CONTEXT: Reference run data as {{context.<path>}} and declare every referenced path in contextSchema.input.fields. Do not invent context paths no trigger or earlier step could produce.',
+  '',
+  'RESPONSE STYLE: Emit only the structured object. `summary` is one plain sentence an operator can read; it is not a restatement of the JSON.',
+].join('\n')
+
+const workflowAuthorAgent: AiAgentDefinition = {
+  id: WORKFLOW_DRAFT_AGENT_ID,
+  moduleId: 'workflows',
+  label: 'Workflow author',
+  description:
+    'Turns a plain-language request into a draft workflow definition, authored against this installation\'s real activity, command, function and event catalogs. Proposes only — never publishes.',
+  systemPrompt: SYSTEM_PROMPT,
+  allowedTools: ['workflows.validate_workflow_definition'],
+  executionMode: 'object',
+  readOnly: true,
+  mutationPolicy: 'read-only',
+  requiredFeatures: ['workflows.definitions.create'],
+  // A validate loop needs only a couple of round-trips; keep it tight so a
+  // model that never converges cannot burn tokens or wall-clock unbounded.
+  loop: {
+    budget: { maxToolCalls: 4, maxWallClockMs: 20_000, maxTokens: 120_000 },
+  },
+  output: {
+    schemaName: 'WorkflowDraft',
+    schema: workflowDraftGenerationSchema,
+    mode: 'generate',
+  },
+  keywords: ['workflow', 'process', 'automation', 'draft', 'authoring'],
+  domain: 'workflows',
+}
+
+export const aiAgents: AiAgentDefinition[] = [workflowAuthorAgent]
+
+export default aiAgents