@open-mercato/enterprise 0.7.1-develop.7191.1.3c9346566b → 0.7.1-develop.7194.1.ab4fc81f82

package/.turbo/turbo-build.log

@@ -1,2 +1,2 @@
-[build:enterprise] found 337 entry points
+[build:enterprise] found 695 entry points
 [build:enterprise] built successfully

package/README.md

@@ -89,6 +89,7 @@ The `@open-mercato/enterprise` package delivers the proprietary modules included
 - **Record Locking** — optimistic and pessimistic mutation protection with participant presence, conflict detection/resolution, and force release
 - **Auth Login Interceptors** — MFA login gating via UMES extension points with zero core modifications
 - **System Status Overlays** — enterprise overlays and injected widgets for system status pages
+- **Agent Orchestrator** — propose-only AI agent runtime (in-process + OpenCode file-defined agents), proposal/disposition workflow integration, trace · eval · correction capture, and the operator/engineer cockpit. Enabled with `OM_ENABLE_ENTERPRISE_MODULES` + `OM_ENABLE_ENTERPRISE_MODULES_AGENTS`
 
 ## Sandboxes
 

package/dist/index.js

@@ -1,7 +1,7 @@
 const enterprisePackage = {
   id: "enterprise",
   description: "Optional enterprise overlays and modules for Open Mercato.",
-  modules: ["security", "sso", "record_locks"]
+  modules: ["security", "sso", "record_locks", "agent_orchestrator"]
 };
 var index_default = enterprisePackage;
 export {

package/dist/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/index.ts"],
-  "sourcesContent": ["export const enterprisePackage = {\n  id: 'enterprise',\n  description: 'Optional enterprise overlays and modules for Open Mercato.',\n  modules: ['security', 'sso','record_locks'],\n} as const\n\nexport default enterprisePackage\n"],
-  "mappings": "AAAO,MAAM,oBAAoB;AAAA,EAC/B,IAAI;AAAA,EACJ,aAAa;AAAA,EACb,SAAS,CAAC,YAAY,OAAM,cAAc;AAC5C;AAEA,IAAO,gBAAQ;",
+  "sourcesContent": ["export const enterprisePackage = {\n  id: 'enterprise',\n  description: 'Optional enterprise overlays and modules for Open Mercato.',\n  modules: ['security', 'sso', 'record_locks', 'agent_orchestrator'],\n} as const\n\nexport default enterprisePackage\n"],
+  "mappings": "AAAO,MAAM,oBAAoB;AAAA,EAC/B,IAAI;AAAA,EACJ,aAAa;AAAA,EACb,SAAS,CAAC,YAAY,OAAO,gBAAgB,oBAAoB;AACnE;AAEA,IAAO,gBAAQ;",
   "names": []
 }

package/dist/modules/agent_orchestrator/acl.js

@@ -0,0 +1,132 @@
+const features = [
+  { id: "agent_orchestrator.agents.view", title: "View agents and runs", module: "agent_orchestrator" },
+  {
+    // The Playground gate. Deliberately SEPARATE from `processes.run`: running
+    // one agent directly is a development, eval and diagnostics capability, and
+    // granting it is not the same decision as letting someone start durable
+    // business work.
+    id: "agent_orchestrator.agents.run",
+    title: "Run agents directly (Playground, evals, diagnostics)",
+    module: "agent_orchestrator",
+    dependsOn: ["agent_orchestrator.agents.view"]
+  },
+  {
+    id: "agent_orchestrator.agents.manage",
+    title: "Manage agent presentation settings",
+    module: "agent_orchestrator",
+    dependsOn: ["agent_orchestrator.agents.view"]
+  },
+  { id: "agent_orchestrator.proposals.view", title: "View proposals", module: "agent_orchestrator" },
+  {
+    id: "agent_orchestrator.proposals.dispose",
+    title: "Dispose proposals (approve/edit/reject)",
+    module: "agent_orchestrator",
+    dependsOn: ["agent_orchestrator.proposals.view"]
+  },
+  // Trace + eval overlay.
+  { id: "agent_orchestrator.trace.view", title: "View agent run traces", module: "agent_orchestrator" },
+  {
+    id: "agent_orchestrator.trace.correct",
+    title: "Record agent corrections",
+    module: "agent_orchestrator",
+    dependsOn: ["agent_orchestrator.trace.view"]
+  },
+  {
+    id: "agent_orchestrator.eval.manage",
+    title: "Manage evaluation cases and assertions",
+    module: "agent_orchestrator",
+    dependsOn: ["agent_orchestrator.trace.view"]
+  },
+  {
+    // Separate from eval.manage: authoring an assertion is cheap, but TRIGGERING a
+    // run performs real inference against a real model and costs real money.
+    id: "agent_orchestrator.eval.run",
+    title: "Run agent evaluations",
+    module: "agent_orchestrator",
+    dependsOn: ["agent_orchestrator.eval.manage"]
+  },
+  {
+    id: "agent_orchestrator.eval.export",
+    title: "Export the agent eval-case set",
+    module: "agent_orchestrator",
+    dependsOn: ["agent_orchestrator.eval.manage"]
+  },
+  // Runtime guardrails overlay.
+  { id: "agent_orchestrator.guardrail.read", title: "View guardrail checks", module: "agent_orchestrator" },
+  {
+    id: "agent_orchestrator.guardrail.manage",
+    title: "Manage guardrail sets",
+    module: "agent_orchestrator",
+    dependsOn: ["agent_orchestrator.guardrail.read"]
+  },
+  // Context overlay — read the assembled context bundles (trace "context assembled" panel).
+  { id: "agent_orchestrator.context.read", title: "View agent context bundles", module: "agent_orchestrator" },
+  // Identity overlay (Wave 4) — provision/manage agent principals and their scoped roles.
+  { id: "agent_orchestrator.identity.read", title: "View agent principals", module: "agent_orchestrator" },
+  {
+    id: "agent_orchestrator.identity.manage",
+    title: "Manage agent principals (provision agent users + scoped roles)",
+    module: "agent_orchestrator",
+    dependsOn: ["agent_orchestrator.identity.read"]
+  },
+  // External-agent OAuth (Wave 4 Phase 3) — mint client-credentials tokens and
+  // create/revoke delegation grants for external (`oauth_client`) principals.
+  {
+    id: "agent_orchestrator.identity.tokens",
+    title: "Manage external agent tokens and delegation grants",
+    module: "agent_orchestrator",
+    dependsOn: ["agent_orchestrator.identity.manage"]
+  },
+  // Processes (triggered process model spec, 2026-08-11). ONE `view` feature
+  // covers both surfaces the model has: the running-process projection
+  // (`/backend/processes`) and the definitions that can start one
+  // (`/backend/processes/definitions`). The retired `tasks.view` merged into
+  // this id rather than adding a fourth feature for a distinction nobody makes.
+  // Consequence recorded in the spec: `dependsOn` proposals.view is inherited by
+  // definition authors, who did not transitively read proposals before.
+  {
+    id: "agent_orchestrator.processes.view",
+    title: "View agent processes, process definitions and run history",
+    module: "agent_orchestrator",
+    dependsOn: ["agent_orchestrator.proposals.view"]
+  },
+  {
+    id: "agent_orchestrator.processes.manage",
+    title: "Create and configure process definitions",
+    module: "agent_orchestrator",
+    dependsOn: ["agent_orchestrator.processes.view"]
+  },
+  {
+    id: "agent_orchestrator.processes.run",
+    title: "Start a process run",
+    module: "agent_orchestrator",
+    dependsOn: ["agent_orchestrator.processes.view"]
+  },
+  // Web egress overlay (spec 2026-07-11-agent-web-search-tool) — gates the
+  // read-only `web_search`/`web_fetch` MCP tools. Default-OFF: intentionally NOT
+  // added to the narrower `defaultRoleFeatures` in setup.ts, so an agent must be
+  // explicitly authorized for network egress. `dependsOn` agents.run because the
+  // tools are only reachable inside an agent run.
+  {
+    id: "agent_orchestrator.web_search",
+    title: "Use agent web search",
+    module: "agent_orchestrator",
+    dependsOn: ["agent_orchestrator.agents.run"]
+  },
+  // Split from `web_search` so a tenant can be granted discovery without the
+  // ability to retrieve an arbitrary URL, which is the higher-risk half. Additive:
+  // `web_fetch` requires BOTH features, so every existing grant of `web_search`
+  // keeps working for search and only loses fetch until this is granted too.
+  {
+    id: "agent_orchestrator.web_fetch",
+    title: "Use agent web fetch (retrieve an arbitrary URL)",
+    module: "agent_orchestrator",
+    dependsOn: ["agent_orchestrator.web_search"]
+  }
+];
+var acl_default = features;
+export {
+  acl_default as default,
+  features
+};
+//# sourceMappingURL=acl.js.map

package/dist/modules/agent_orchestrator/acl.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/modules/agent_orchestrator/acl.ts"],
+  "sourcesContent": ["// Area 01 owns `agents.view` / `agents.run`. Area 03 owns `proposals.view` /\n// `proposals.dispose`. `workflows.author` is declared by area 02 \u2014 see\n// mvp/00-overview.md \u00A7ACL features.\nexport const features = [\n  { id: 'agent_orchestrator.agents.view', title: 'View agents and runs', module: 'agent_orchestrator' },\n  {\n    // The Playground gate. Deliberately SEPARATE from `processes.run`: running\n    // one agent directly is a development, eval and diagnostics capability, and\n    // granting it is not the same decision as letting someone start durable\n    // business work.\n    id: 'agent_orchestrator.agents.run',\n    title: 'Run agents directly (Playground, evals, diagnostics)',\n    module: 'agent_orchestrator',\n    dependsOn: ['agent_orchestrator.agents.view'],\n  },\n  {\n    id: 'agent_orchestrator.agents.manage',\n    title: 'Manage agent presentation settings',\n    module: 'agent_orchestrator',\n    dependsOn: ['agent_orchestrator.agents.view'],\n  },\n  { id: 'agent_orchestrator.proposals.view', title: 'View proposals', module: 'agent_orchestrator' },\n  {\n    id: 'agent_orchestrator.proposals.dispose',\n    title: 'Dispose proposals (approve/edit/reject)',\n    module: 'agent_orchestrator',\n    dependsOn: ['agent_orchestrator.proposals.view'],\n  },\n  // Trace + eval overlay.\n  { id: 'agent_orchestrator.trace.view', title: 'View agent run traces', module: 'agent_orchestrator' },\n  {\n    id: 'agent_orchestrator.trace.correct',\n    title: 'Record agent corrections',\n    module: 'agent_orchestrator',\n    dependsOn: ['agent_orchestrator.trace.view'],\n  },\n  {\n    id: 'agent_orchestrator.eval.manage',\n    title: 'Manage evaluation cases and assertions',\n    module: 'agent_orchestrator',\n    dependsOn: ['agent_orchestrator.trace.view'],\n  },\n  {\n    // Separate from eval.manage: authoring an assertion is cheap, but TRIGGERING a\n    // run performs real inference against a real model and costs real money.\n    id: 'agent_orchestrator.eval.run',\n    title: 'Run agent evaluations',\n    module: 'agent_orchestrator',\n    dependsOn: ['agent_orchestrator.eval.manage'],\n  },\n  {\n    id: 'agent_orchestrator.eval.export',\n    title: 'Export the agent eval-case set',\n    module: 'agent_orchestrator',\n    dependsOn: ['agent_orchestrator.eval.manage'],\n  },\n  // Runtime guardrails overlay.\n  { id: 'agent_orchestrator.guardrail.read', title: 'View guardrail checks', module: 'agent_orchestrator' },\n  {\n    id: 'agent_orchestrator.guardrail.manage',\n    title: 'Manage guardrail sets',\n    module: 'agent_orchestrator',\n    dependsOn: ['agent_orchestrator.guardrail.read'],\n  },\n  // Context overlay \u2014 read the assembled context bundles (trace \"context assembled\" panel).\n  { id: 'agent_orchestrator.context.read', title: 'View agent context bundles', module: 'agent_orchestrator' },\n  // Identity overlay (Wave 4) \u2014 provision/manage agent principals and their scoped roles.\n  { id: 'agent_orchestrator.identity.read', title: 'View agent principals', module: 'agent_orchestrator' },\n  {\n    id: 'agent_orchestrator.identity.manage',\n    title: 'Manage agent principals (provision agent users + scoped roles)',\n    module: 'agent_orchestrator',\n    dependsOn: ['agent_orchestrator.identity.read'],\n  },\n  // External-agent OAuth (Wave 4 Phase 3) \u2014 mint client-credentials tokens and\n  // create/revoke delegation grants for external (`oauth_client`) principals.\n  {\n    id: 'agent_orchestrator.identity.tokens',\n    title: 'Manage external agent tokens and delegation grants',\n    module: 'agent_orchestrator',\n    dependsOn: ['agent_orchestrator.identity.manage'],\n  },\n  // Processes (triggered process model spec, 2026-08-11). ONE `view` feature\n  // covers both surfaces the model has: the running-process projection\n  // (`/backend/processes`) and the definitions that can start one\n  // (`/backend/processes/definitions`). The retired `tasks.view` merged into\n  // this id rather than adding a fourth feature for a distinction nobody makes.\n  // Consequence recorded in the spec: `dependsOn` proposals.view is inherited by\n  // definition authors, who did not transitively read proposals before.\n  {\n    id: 'agent_orchestrator.processes.view',\n    title: 'View agent processes, process definitions and run history',\n    module: 'agent_orchestrator',\n    dependsOn: ['agent_orchestrator.proposals.view'],\n  },\n  {\n    id: 'agent_orchestrator.processes.manage',\n    title: 'Create and configure process definitions',\n    module: 'agent_orchestrator',\n    dependsOn: ['agent_orchestrator.processes.view'],\n  },\n  {\n    id: 'agent_orchestrator.processes.run',\n    title: 'Start a process run',\n    module: 'agent_orchestrator',\n    dependsOn: ['agent_orchestrator.processes.view'],\n  },\n  // Web egress overlay (spec 2026-07-11-agent-web-search-tool) \u2014 gates the\n  // read-only `web_search`/`web_fetch` MCP tools. Default-OFF: intentionally NOT\n  // added to the narrower `defaultRoleFeatures` in setup.ts, so an agent must be\n  // explicitly authorized for network egress. `dependsOn` agents.run because the\n  // tools are only reachable inside an agent run.\n  {\n    id: 'agent_orchestrator.web_search',\n    title: 'Use agent web search',\n    module: 'agent_orchestrator',\n    dependsOn: ['agent_orchestrator.agents.run'],\n  },\n  // Split from `web_search` so a tenant can be granted discovery without the\n  // ability to retrieve an arbitrary URL, which is the higher-risk half. Additive:\n  // `web_fetch` requires BOTH features, so every existing grant of `web_search`\n  // keeps working for search and only loses fetch until this is granted too.\n  {\n    id: 'agent_orchestrator.web_fetch',\n    title: 'Use agent web fetch (retrieve an arbitrary URL)',\n    module: 'agent_orchestrator',\n    dependsOn: ['agent_orchestrator.web_search'],\n  },\n]\n\nexport default features\n"],
+  "mappings": "AAGO,MAAM,WAAW;AAAA,EACtB,EAAE,IAAI,kCAAkC,OAAO,wBAAwB,QAAQ,qBAAqB;AAAA,EACpG;AAAA;AAAA;AAAA;AAAA;AAAA,IAKE,IAAI;AAAA,IACJ,OAAO;AAAA,IACP,QAAQ;AAAA,IACR,WAAW,CAAC,gCAAgC;AAAA,EAC9C;AAAA,EACA;AAAA,IACE,IAAI;AAAA,IACJ,OAAO;AAAA,IACP,QAAQ;AAAA,IACR,WAAW,CAAC,gCAAgC;AAAA,EAC9C;AAAA,EACA,EAAE,IAAI,qCAAqC,OAAO,kBAAkB,QAAQ,qBAAqB;AAAA,EACjG;AAAA,IACE,IAAI;AAAA,IACJ,OAAO;AAAA,IACP,QAAQ;AAAA,IACR,WAAW,CAAC,mCAAmC;AAAA,EACjD;AAAA;AAAA,EAEA,EAAE,IAAI,iCAAiC,OAAO,yBAAyB,QAAQ,qBAAqB;AAAA,EACpG;AAAA,IACE,IAAI;AAAA,IACJ,OAAO;AAAA,IACP,QAAQ;AAAA,IACR,WAAW,CAAC,+BAA+B;AAAA,EAC7C;AAAA,EACA;AAAA,IACE,IAAI;AAAA,IACJ,OAAO;AAAA,IACP,QAAQ;AAAA,IACR,WAAW,CAAC,+BAA+B;AAAA,EAC7C;AAAA,EACA;AAAA;AAAA;AAAA,IAGE,IAAI;AAAA,IACJ,OAAO;AAAA,IACP,QAAQ;AAAA,IACR,WAAW,CAAC,gCAAgC;AAAA,EAC9C;AAAA,EACA;AAAA,IACE,IAAI;AAAA,IACJ,OAAO;AAAA,IACP,QAAQ;AAAA,IACR,WAAW,CAAC,gCAAgC;AAAA,EAC9C;AAAA;AAAA,EAEA,EAAE,IAAI,qCAAqC,OAAO,yBAAyB,QAAQ,qBAAqB;AAAA,EACxG;AAAA,IACE,IAAI;AAAA,IACJ,OAAO;AAAA,IACP,QAAQ;AAAA,IACR,WAAW,CAAC,mCAAmC;AAAA,EACjD;AAAA;AAAA,EAEA,EAAE,IAAI,mCAAmC,OAAO,8BAA8B,QAAQ,qBAAqB;AAAA;AAAA,EAE3G,EAAE,IAAI,oCAAoC,OAAO,yBAAyB,QAAQ,qBAAqB;AAAA,EACvG;AAAA,IACE,IAAI;AAAA,IACJ,OAAO;AAAA,IACP,QAAQ;AAAA,IACR,WAAW,CAAC,kCAAkC;AAAA,EAChD;AAAA;AAAA;AAAA,EAGA;AAAA,IACE,IAAI;AAAA,IACJ,OAAO;AAAA,IACP,QAAQ;AAAA,IACR,WAAW,CAAC,oCAAoC;AAAA,EAClD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA;AAAA,IACE,IAAI;AAAA,IACJ,OAAO;AAAA,IACP,QAAQ;AAAA,IACR,WAAW,CAAC,mCAAmC;AAAA,EACjD;AAAA,EACA;AAAA,IACE,IAAI;AAAA,IACJ,OAAO;AAAA,IACP,QAAQ;AAAA,IACR,WAAW,CAAC,mCAAmC;AAAA,EACjD;AAAA,EACA;AAAA,IACE,IAAI;AAAA,IACJ,OAAO;AAAA,IACP,QAAQ;AAAA,IACR,WAAW,CAAC,mCAAmC;AAAA,EACjD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA;AAAA,IACE,IAAI;AAAA,IACJ,OAAO;AAAA,IACP,QAAQ;AAAA,IACR,WAAW,CAAC,+BAA+B;AAAA,EAC7C;AAAA;AAAA;AAAA;AAAA;AAAA,EAKA;AAAA,IACE,IAAI;AAAA,IACJ,OAAO;AAAA,IACP,QAAQ;AAAA,IACR,WAAW,CAAC,+BAA+B;AAAA,EAC7C;AACF;AAEA,IAAO,cAAQ;",
+  "names": []
+}

package/dist/modules/agent_orchestrator/ai-agents.js

@@ -0,0 +1,57 @@
+import "./ai-skills.js";
+import { defineAgent } from "./lib/sdk/defineAgent.js";
+import { dealHealthCheckResult } from "./data/validators.js";
+const aiAgents = [
+  defineAgent({
+    id: "deals.health_check",
+    moduleId: "agent_orchestrator",
+    label: "Deal health check",
+    description: "Assess a deal\u2019s health and propose the single best next stage.",
+    instructions: [
+      "You assess the health of a sales deal and propose the single best next pipeline stage.",
+      "The input may contain the deal inline as `deal` (fields such as id, name, stage, value,",
+      "probability, daysInStage and recentActivity) OR just a `dealId`. When you are given a",
+      "`dealId` (or only an `id`) and not a full `deal`, call the `customers.get_deal` tool with",
+      "that id to fetch the deal before assessing it; pass `includeRelated: true` to also load its",
+      "recent activities and notes. This is a READ-only tool \u2014 you can look the deal up but you can",
+      "never modify it; the only way to change the deal is the proposal you return.",
+      "If the deal is already provided inline, use it directly and do not call the tool.",
+      "Always return a proposal with exactly one `set_stage` action whose payload sets",
+      'the next pipeline stage, e.g. { "type": "set_stage", "payload": { "stage": "Qualified" } }.',
+      "Set `confidence` between 0 and 1: high (>= 0.8) when the next stage is unambiguous (strong",
+      "probability, recent activity, healthy time-in-stage); lower (< 0.8) when a human should",
+      "review (stalled deal, low probability, long time in stage). Use `rationale` to briefly",
+      "explain the recommendation.",
+      "Every field is REQUIRED: always return `confidence` (a number between 0 and 1), a non-empty",
+      "`rationale`, and exactly one set_stage action whose `payload.stage` is a non-empty pipeline",
+      'stage name (e.g. "Negotiation"). Never return an empty stage or omit confidence.'
+    ].join(" "),
+    // Read-only tool: lets the agent fetch the deal by id (gated by
+    // customers.deals.view, checked against the caller's own ACL). Propose-only
+    // is preserved — the agent is declared read-only, so the runtime strips any
+    // mutation tool; the only way it can change a deal is the proposal it emits.
+    tools: ["customers.get_deal"],
+    // The skill injects the pipeline-stage playbook into the prompt AND
+    // contributes its read-only `customers.analyze_deals` tool to this agent.
+    skills: ["deals.stage_playbook"],
+    result: { kind: "proposal", schema: dealHealthCheckResult },
+    // Inline `deal` so the Playground runs deterministically (no DB lookup).
+    sampleInput: {
+      deal: {
+        id: "demo-deal-1",
+        name: "Acme Corp \u2014 Enterprise plan",
+        stage: "Proposal",
+        value: 48e3,
+        probability: 0.65,
+        daysInStage: 12,
+        recentActivity: "Sent revised pricing; awaiting procurement sign-off."
+      }
+    }
+  })
+];
+var ai_agents_default = aiAgents;
+export {
+  aiAgents,
+  ai_agents_default as default
+};
+//# sourceMappingURL=ai-agents.js.map

package/dist/modules/agent_orchestrator/ai-agents.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/modules/agent_orchestrator/ai-agents.ts"],
+  "sourcesContent": ["import type { AiAgentDefinition } from '@open-mercato/ai-assistant/modules/ai_assistant/lib/ai-agent-definition'\n// Import skills FIRST so `defineSkill` has populated the registry before any\n// `defineAgent` below resolves its declared `skills`.\nimport './ai-skills'\nimport { defineAgent } from './lib/sdk/defineAgent'\nimport { dealHealthCheckResult } from './data/validators'\n\n// `deals.health_check` is the demo agent for the MVP end-to-end flow (area 05).\n// Authoring is code (here), not a DB seed: the ai_assistant generator discovers\n// `ai-agents.ts` and `defineAgent` emits a standard AiAgentDefinition (object\n// mode) while registering { id, resultKind, schema } in the area-01 registry.\n// The id is the STABLE contract id referenced by the demo workflow definition's\n// INVOKE_AGENT step (`examples/deals-health-check-workflow.json`) and the\n// runbook in mvp/05-seed-and-demo.md.\n//\n// Result: an `proposal` proposal carrying a single `set_stage` action plus a\n// confidence score. The disposition gate (area 03) auto-approves when\n// `confidence >= autoApproveThreshold` (0.8 on the demo node) and otherwise\n// raises a USER_TASK / proposal for an operator. The effector step applies the\n// approved `set_stage` payload to the deal via the audited customers command.\nexport const aiAgents: AiAgentDefinition[] = [\n  defineAgent({\n    id: 'deals.health_check',\n    moduleId: 'agent_orchestrator',\n    label: 'Deal health check',\n    description: 'Assess a deal\u2019s health and propose the single best next stage.',\n    instructions: [\n      'You assess the health of a sales deal and propose the single best next pipeline stage.',\n      'The input may contain the deal inline as `deal` (fields such as id, name, stage, value,',\n      'probability, daysInStage and recentActivity) OR just a `dealId`. When you are given a',\n      '`dealId` (or only an `id`) and not a full `deal`, call the `customers.get_deal` tool with',\n      'that id to fetch the deal before assessing it; pass `includeRelated: true` to also load its',\n      'recent activities and notes. This is a READ-only tool \u2014 you can look the deal up but you can',\n      'never modify it; the only way to change the deal is the proposal you return.',\n      'If the deal is already provided inline, use it directly and do not call the tool.',\n      'Always return a proposal with exactly one `set_stage` action whose payload sets',\n      'the next pipeline stage, e.g. { \"type\": \"set_stage\", \"payload\": { \"stage\": \"Qualified\" } }.',\n      'Set `confidence` between 0 and 1: high (>= 0.8) when the next stage is unambiguous (strong',\n      'probability, recent activity, healthy time-in-stage); lower (< 0.8) when a human should',\n      'review (stalled deal, low probability, long time in stage). Use `rationale` to briefly',\n      'explain the recommendation.',\n      'Every field is REQUIRED: always return `confidence` (a number between 0 and 1), a non-empty',\n      '`rationale`, and exactly one set_stage action whose `payload.stage` is a non-empty pipeline',\n      'stage name (e.g. \"Negotiation\"). Never return an empty stage or omit confidence.',\n    ].join(' '),\n    // Read-only tool: lets the agent fetch the deal by id (gated by\n    // customers.deals.view, checked against the caller's own ACL). Propose-only\n    // is preserved \u2014 the agent is declared read-only, so the runtime strips any\n    // mutation tool; the only way it can change a deal is the proposal it emits.\n    tools: ['customers.get_deal'],\n    // The skill injects the pipeline-stage playbook into the prompt AND\n    // contributes its read-only `customers.analyze_deals` tool to this agent.\n    skills: ['deals.stage_playbook'],\n    result: { kind: 'proposal', schema: dealHealthCheckResult },\n    // Inline `deal` so the Playground runs deterministically (no DB lookup).\n    sampleInput: {\n      deal: {\n        id: 'demo-deal-1',\n        name: 'Acme Corp \u2014 Enterprise plan',\n        stage: 'Proposal',\n        value: 48000,\n        probability: 0.65,\n        daysInStage: 12,\n        recentActivity: 'Sent revised pricing; awaiting procurement sign-off.',\n      },\n    },\n  }),\n]\n\nexport default aiAgents\n"],
+  "mappings": "AAGA,OAAO;AACP,SAAS,mBAAmB;AAC5B,SAAS,6BAA6B;AAe/B,MAAM,WAAgC;AAAA,EAC3C,YAAY;AAAA,IACV,IAAI;AAAA,IACJ,UAAU;AAAA,IACV,OAAO;AAAA,IACP,aAAa;AAAA,IACb,cAAc;AAAA,MACZ;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF,EAAE,KAAK,GAAG;AAAA;AAAA;AAAA;AAAA;AAAA,IAKV,OAAO,CAAC,oBAAoB;AAAA;AAAA;AAAA,IAG5B,QAAQ,CAAC,sBAAsB;AAAA,IAC/B,QAAQ,EAAE,MAAM,YAAY,QAAQ,sBAAsB;AAAA;AAAA,IAE1D,aAAa;AAAA,MACX,MAAM;AAAA,QACJ,IAAI;AAAA,QACJ,MAAM;AAAA,QACN,OAAO;AAAA,QACP,OAAO;AAAA,QACP,aAAa;AAAA,QACb,aAAa;AAAA,QACb,gBAAgB;AAAA,MAClB;AAAA,IACF;AAAA,EACF,CAAC;AACH;AAEA,IAAO,oBAAQ;",
+  "names": []
+}

package/dist/modules/agent_orchestrator/ai-skills.js

@@ -0,0 +1,48 @@
+import * as fs from "fs";
+import * as path from "path";
+import { fileURLToPath } from "node:url";
+import { createLogger } from "@open-mercato/shared/lib/logger";
+import { defineSkill } from "./lib/sdk/defineSkill.js";
+import { parseSkillMarkdown } from "./lib/sdk/skillMarkdown.js";
+const logger = createLogger("agent_orchestrator").child({ component: "ai-skills" });
+const __esmDirname = path.dirname(fileURLToPath(import.meta.url));
+function resolveSkillsDir() {
+  const candidates = [
+    // Colocated: source execution (tsx) or a build that copies skills into dist.
+    path.join(__esmDirname, "skills"),
+    // Dist execution (e.g. mcp:serve runs the compiled package): walk from
+    // `<pkg>/dist/modules/agent_orchestrator` back to the source `skills` dir.
+    path.join(__esmDirname, "..", "..", "..", "src", "modules", "agent_orchestrator", "skills"),
+    // Repo-root cwd (this module lives in @open-mercato/enterprise, not core).
+    path.join(process.cwd(), "packages", "enterprise", "src", "modules", "agent_orchestrator", "skills"),
+    // Standalone app cwd.
+    path.join(process.cwd(), "src", "modules", "agent_orchestrator", "skills")
+  ];
+  return candidates.find((candidate) => fs.existsSync(candidate)) ?? null;
+}
+function loadSkillsFromDisk() {
+  const dir = resolveSkillsDir();
+  if (!dir) {
+    logger.warn("skills directory not found; no skills loaded");
+    return [];
+  }
+  const files = fs.readdirSync(dir).filter((file) => file.endsWith(".md")).sort((a, b) => a.localeCompare(b));
+  const entries = [];
+  for (const file of files) {
+    const raw = fs.readFileSync(path.join(dir, file), "utf8");
+    const parsed = parseSkillMarkdown(raw);
+    if (!parsed) {
+      logger.warn("skill is missing required frontmatter (id/moduleId/label); skipping", { file });
+      continue;
+    }
+    entries.push(defineSkill(parsed));
+  }
+  return entries;
+}
+const aiSkills = loadSkillsFromDisk();
+var ai_skills_default = aiSkills;
+export {
+  aiSkills,
+  ai_skills_default as default
+};
+//# sourceMappingURL=ai-skills.js.map

package/dist/modules/agent_orchestrator/ai-skills.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/modules/agent_orchestrator/ai-skills.ts"],
+  "sourcesContent": ["import * as fs from 'fs'\nimport * as path from 'path'\nimport { fileURLToPath } from 'node:url'\nimport { createLogger } from '@open-mercato/shared/lib/logger'\nimport { defineSkill, type SkillRegistryEntry } from './lib/sdk/defineSkill'\nimport { parseSkillMarkdown } from './lib/sdk/skillMarkdown'\n\nconst logger = createLogger('agent_orchestrator').child({ component: 'ai-skills' })\n\n// Skills are authored as SKILL.md files under `./skills`. Each file carries\n// frontmatter (id, moduleId, label, description, tools) and a markdown body that\n// becomes the skill's instructions. They are loaded here and registered via\n// `defineSkill`, so the registry is populated by importing this module \u2014 exactly\n// like `ai-agents.ts`. Path resolution mirrors `lib/seeds.ts` `readExampleJson`\n// so it works from the import.meta location and from the repo cwd.\n\nconst __esmDirname = path.dirname(fileURLToPath(import.meta.url))\n\nfunction resolveSkillsDir(): string | null {\n  const candidates = [\n    // Colocated: source execution (tsx) or a build that copies skills into dist.\n    path.join(__esmDirname, 'skills'),\n    // Dist execution (e.g. mcp:serve runs the compiled package): walk from\n    // `<pkg>/dist/modules/agent_orchestrator` back to the source `skills` dir.\n    path.join(__esmDirname, '..', '..', '..', 'src', 'modules', 'agent_orchestrator', 'skills'),\n    // Repo-root cwd (this module lives in @open-mercato/enterprise, not core).\n    path.join(process.cwd(), 'packages', 'enterprise', 'src', 'modules', 'agent_orchestrator', 'skills'),\n    // Standalone app cwd.\n    path.join(process.cwd(), 'src', 'modules', 'agent_orchestrator', 'skills'),\n  ]\n  return candidates.find((candidate) => fs.existsSync(candidate)) ?? null\n}\n\nfunction loadSkillsFromDisk(): SkillRegistryEntry[] {\n  const dir = resolveSkillsDir()\n  if (!dir) {\n    logger.warn('skills directory not found; no skills loaded')\n    return []\n  }\n  const files = fs\n    .readdirSync(dir)\n    .filter((file) => file.endsWith('.md'))\n    .sort((a, b) => a.localeCompare(b))\n  const entries: SkillRegistryEntry[] = []\n  for (const file of files) {\n    const raw = fs.readFileSync(path.join(dir, file), 'utf8')\n    const parsed = parseSkillMarkdown(raw)\n    if (!parsed) {\n      logger.warn('skill is missing required frontmatter (id/moduleId/label); skipping', { file })\n      continue\n    }\n    entries.push(defineSkill(parsed))\n  }\n  return entries\n}\n\nexport const aiSkills: SkillRegistryEntry[] = loadSkillsFromDisk()\n\nexport default aiSkills\n"],
+  "mappings": "AAAA,YAAY,QAAQ;AACpB,YAAY,UAAU;AACtB,SAAS,qBAAqB;AAC9B,SAAS,oBAAoB;AAC7B,SAAS,mBAA4C;AACrD,SAAS,0BAA0B;AAEnC,MAAM,SAAS,aAAa,oBAAoB,EAAE,MAAM,EAAE,WAAW,YAAY,CAAC;AASlF,MAAM,eAAe,KAAK,QAAQ,cAAc,YAAY,GAAG,CAAC;AAEhE,SAAS,mBAAkC;AACzC,QAAM,aAAa;AAAA;AAAA,IAEjB,KAAK,KAAK,cAAc,QAAQ;AAAA;AAAA;AAAA,IAGhC,KAAK,KAAK,cAAc,MAAM,MAAM,MAAM,OAAO,WAAW,sBAAsB,QAAQ;AAAA;AAAA,IAE1F,KAAK,KAAK,QAAQ,IAAI,GAAG,YAAY,cAAc,OAAO,WAAW,sBAAsB,QAAQ;AAAA;AAAA,IAEnG,KAAK,KAAK,QAAQ,IAAI,GAAG,OAAO,WAAW,sBAAsB,QAAQ;AAAA,EAC3E;AACA,SAAO,WAAW,KAAK,CAAC,cAAc,GAAG,WAAW,SAAS,CAAC,KAAK;AACrE;AAEA,SAAS,qBAA2C;AAClD,QAAM,MAAM,iBAAiB;AAC7B,MAAI,CAAC,KAAK;AACR,WAAO,KAAK,8CAA8C;AAC1D,WAAO,CAAC;AAAA,EACV;AACA,QAAM,QAAQ,GACX,YAAY,GAAG,EACf,OAAO,CAAC,SAAS,KAAK,SAAS,KAAK,CAAC,EACrC,KAAK,CAAC,GAAG,MAAM,EAAE,cAAc,CAAC,CAAC;AACpC,QAAM,UAAgC,CAAC;AACvC,aAAW,QAAQ,OAAO;AACxB,UAAM,MAAM,GAAG,aAAa,KAAK,KAAK,KAAK,IAAI,GAAG,MAAM;AACxD,UAAM,SAAS,mBAAmB,GAAG;AACrC,QAAI,CAAC,QAAQ;AACX,aAAO,KAAK,uEAAuE,EAAE,KAAK,CAAC;AAC3F;AAAA,IACF;AACA,YAAQ,KAAK,YAAY,MAAM,CAAC;AAAA,EAClC;AACA,SAAO;AACT;AAEO,MAAM,WAAiC,mBAAmB;AAEjE,IAAO,oBAAQ;",
+  "names": []
+}

package/dist/modules/agent_orchestrator/ai-tools.js

@@ -0,0 +1,254 @@
+import { z } from "zod";
+import { DELEGATE_TOOL_ID, getAgentEntry, ensureAgentsLoaded } from "./lib/sdk/defineAgent.js";
+import { getAgentSkill, getAgentSkillScript } from "./lib/runtime/fileAgentSkills.js";
+import { runSandboxedScript } from "./lib/runtime/sandboxedScript.js";
+import { getCurrentRunId, getCurrentRunSource } from "./lib/runtime/runContext.js";
+import { webSearchTool, webFetchTool } from "./lib/webSearch/tools.js";
+const SUBMIT_OUTCOME_TOOL_ID = "agent_orchestrator.submit_outcome";
+const LOAD_SKILL_TOOL_ID = "agent_orchestrator.load_skill";
+const RUN_SKILL_SCRIPT_TOOL_ID = "agent_orchestrator.run_skill_script";
+const delegateInput = z.object({
+  agentId: z.string().min(1).describe("Id of the sub-agent to run (must be a researcher agent)."),
+  input: z.unknown().describe("Input payload passed to the sub-agent (shape is sub-agent specific).")
+});
+const DEFAULT_DELEGATE_RUN_TIMEOUT_MS = 3 * 6e4;
+function resolveDelegateRunTimeoutMs() {
+  const raw = process.env.OM_AGENT_DELEGATE_RUN_TIMEOUT_MS;
+  if (raw != null && raw !== "") {
+    const parsed = Number(raw);
+    if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  }
+  return DEFAULT_DELEGATE_RUN_TIMEOUT_MS;
+}
+async function resolveParentRunIdFromSession(ctx) {
+  const sessionToken = ctx.sessionId;
+  if (!sessionToken) return void 0;
+  try {
+    const store = ctx.container.resolve("agentRunSessionStore");
+    return await store.resolveActiveRunId(sessionToken) ?? void 0;
+  } catch {
+    return void 0;
+  }
+}
+const delegateAgentTool = {
+  name: DELEGATE_TOOL_ID,
+  displayName: "Delegate to sub-agent",
+  description: "Run another agent as a read-only sub-agent and return its result. Only researcher, non-delegating agents may be targeted. Call multiple times in one step to fan out in parallel.",
+  inputSchema: delegateInput,
+  requiredFeatures: ["agent_orchestrator.agents.run"],
+  isMutation: false,
+  tags: ["read", "agent_orchestrator"],
+  async handler(rawInput, ctx) {
+    const { agentId, input } = delegateInput.parse(rawInput);
+    if (!ctx.tenantId || !ctx.organizationId || !ctx.userId) {
+      return { ok: false, agentId, error: "missing tenant/org/user scope" };
+    }
+    await ensureAgentsLoaded();
+    const entry = getAgentEntry(agentId);
+    if (!entry) {
+      return { ok: false, agentId, error: `unknown sub-agent "${agentId}"` };
+    }
+    if (entry.resultKind !== "research") {
+      return { ok: false, agentId, error: "only research sub-agents may be delegated to" };
+    }
+    if (entry.subAgents.length > 0) {
+      return { ok: false, agentId, error: "sub-agents may not delegate further (depth capped at 1)" };
+    }
+    try {
+      const agentRuntime = ctx.container.resolve("agentRuntime");
+      const parentRunId = getCurrentRunId() ?? await resolveParentRunIdFromSession(ctx);
+      const delegatedSource = getCurrentRunSource();
+      const result = await agentRuntime.run(agentId, input, {
+        tenantId: ctx.tenantId,
+        organizationId: ctx.organizationId,
+        userId: ctx.userId,
+        // Bound the delegated run well below the top-level budget so a hung
+        // sub-agent tool (e.g. a wedged web_search navigation) fails fast and
+        // returns an error to the orchestrator instead of blocking it for an hour.
+        runTimeoutMs: resolveDelegateRunTimeoutMs(),
+        ...parentRunId ? { parentRunId } : {},
+        // Inherit the parent's origin so an eval replay's sub-agent runs are not
+        // counted as production traffic in the agent's metric rollups.
+        ...delegatedSource ? { source: delegatedSource } : {}
+      });
+      const data = result.kind === "research" ? result.data : result.kind === "proposal" ? result.proposal : { artifacts: result.artifacts, summary: result.summary };
+      return { ok: true, agentId, data };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return { ok: false, agentId, error: message };
+    }
+  }
+};
+const submitOutcomeInput = z.object({
+  outcome: z.unknown().describe(
+    "The structured result, matching the active agent OUTCOME contract. The active agent and its schema are resolved server-side from the run session \u2014 never trusted from this call."
+  ),
+  // File plane (#12): ADVISORY captions for files the agent wrote into the sandbox
+  // `out/` dir. Additive + optional (existing single-`outcome` callers stay valid).
+  // The collector is FILESYSTEM-authoritative: it captures whatever is on disk and
+  // uses these only to attach a caption (matched by relative path) — it never
+  // trusts this list to invent, hide, or rename a file.
+  artifacts: z.array(
+    z.object({
+      path: z.string().max(255).describe("Path of the produced file, relative to the sandbox out/ dir."),
+      caption: z.string().max(500).optional().describe("Short human description of the file.")
+    })
+  ).max(20).optional().describe("Optional captions for files written to the sandbox out/ directory.")
+});
+const submitOutcomeTool = {
+  name: SUBMIT_OUTCOME_TOOL_ID,
+  displayName: "Submit agent outcome",
+  description: "Finish the current agent run by submitting its structured outcome (as the `outcome` argument object). The server validates it against the agent OUTCOME contract; on failure it returns the validation errors so you can correct and resubmit.",
+  inputSchema: submitOutcomeInput,
+  requiredFeatures: ["agent_orchestrator.agents.run"],
+  isMutation: false,
+  tags: ["read", "agent_orchestrator"],
+  async handler(rawInput, ctx) {
+    const { outcome } = submitOutcomeInput.parse(rawInput);
+    const sessionToken = ctx.sessionId;
+    if (!sessionToken) {
+      return { ok: false, code: "no_active_run", error: "no run session in context" };
+    }
+    const store = ctx.container.resolve("agentRunSessionStore");
+    const agentId = await store.resolveActiveAgentId(sessionToken);
+    if (!agentId) {
+      return { ok: false, code: "no_active_run", error: "no active run for this session" };
+    }
+    await ensureAgentsLoaded();
+    const entry = getAgentEntry(agentId);
+    if (!entry) {
+      return { ok: false, code: "no_active_run", error: "active agent is no longer registered" };
+    }
+    let outcomeValue = outcome;
+    if (typeof outcomeValue === "string") {
+      try {
+        outcomeValue = JSON.parse(outcomeValue);
+      } catch {
+        return {
+          ok: false,
+          code: "outcome_invalid",
+          errors: [{ path: "", message: "outcome must be a JSON object, not an unparseable string" }]
+        };
+      }
+    }
+    const parsed = entry.schema.safeParse(outcomeValue);
+    if (!parsed.success) {
+      return {
+        ok: false,
+        code: "outcome_invalid",
+        errors: parsed.error.issues.map((issue) => ({
+          path: issue.path.join("."),
+          message: issue.message
+        }))
+      };
+    }
+    const completion = await store.completeOutcome(sessionToken, parsed.data);
+    if (completion !== "completed") {
+      return { ok: false, code: "no_active_run", error: `run ${completion}` };
+    }
+    return { ok: true };
+  }
+};
+const loadSkillInput = z.object({
+  skillId: z.string().min(1).describe("Id of the skill to load. Must be one of the active agent allowed skills.")
+});
+const loadSkillTool = {
+  name: LOAD_SKILL_TOOL_ID,
+  displayName: "Load agent skill",
+  description: "Load the full instructions (and optional template + examples) of one of the current agent skills, by skill id.",
+  inputSchema: loadSkillInput,
+  requiredFeatures: ["agent_orchestrator.agents.run"],
+  isMutation: false,
+  tags: ["read", "agent_orchestrator"],
+  async handler(rawInput, ctx) {
+    const { skillId } = loadSkillInput.parse(rawInput);
+    const sessionToken = ctx.sessionId;
+    if (!sessionToken) {
+      return { ok: false, code: "no_active_run", error: "no run session in context" };
+    }
+    const store = ctx.container.resolve("agentRunSessionStore");
+    const agentId = await store.resolveActiveAgentId(sessionToken);
+    if (!agentId) {
+      return { ok: false, code: "no_active_run", error: "no active run for this session" };
+    }
+    await ensureAgentsLoaded();
+    const skill = getAgentSkill(agentId, skillId);
+    if (!skill) {
+      return {
+        ok: false,
+        code: "skill_not_allowed",
+        error: `skill "${skillId}" is not available to the active agent`
+      };
+    }
+    return {
+      ok: true,
+      instructions: skill.instructions,
+      ...skill.template != null ? { template: skill.template } : {},
+      examples: skill.examples
+    };
+  }
+};
+const runSkillScriptInput = z.object({
+  skillId: z.string().min(1).describe("Id of the skill the script belongs to (one of the current agent skills)."),
+  scriptName: z.string().min(1).describe('Script basename without extension (e.g. `scripts/score.ts` \u2192 "score").'),
+  args: z.unknown().optional().describe("Arguments passed to the script `run(args)` function.")
+});
+const runSkillScriptTool = {
+  name: RUN_SKILL_SCRIPT_TOOL_ID,
+  displayName: "Run agent skill script",
+  description: "Run one of the current agent sandboxed helper scripts by skill id + script name and return its result. Scripts are pure functions of their args (no fs/net/side effects) executed in a sandbox.",
+  inputSchema: runSkillScriptInput,
+  requiredFeatures: ["agent_orchestrator.agents.run"],
+  isMutation: false,
+  tags: ["read", "agent_orchestrator"],
+  async handler(rawInput, ctx) {
+    const { skillId, scriptName, args } = runSkillScriptInput.parse(rawInput);
+    const sessionToken = ctx.sessionId;
+    if (!sessionToken) {
+      return { ok: false, code: "no_active_run", error: "no run session in context" };
+    }
+    const store = ctx.container.resolve("agentRunSessionStore");
+    const agentId = await store.resolveActiveAgentId(sessionToken);
+    if (!agentId) {
+      return { ok: false, code: "no_active_run", error: "no active run for this session" };
+    }
+    await ensureAgentsLoaded();
+    if (!getAgentSkill(agentId, skillId)) {
+      return {
+        ok: false,
+        code: "skill_not_allowed",
+        error: `skill "${skillId}" is not available to the active agent`
+      };
+    }
+    const script = getAgentSkillScript(agentId, skillId, scriptName);
+    if (!script) {
+      return {
+        ok: false,
+        code: "script_not_found",
+        error: `script "${scriptName}" not found in skill "${skillId}"`
+      };
+    }
+    const outcome = await runSandboxedScript({ source: script.source, args });
+    if (!outcome.ok) {
+      return { ok: false, code: outcome.code, error: outcome.error };
+    }
+    return { ok: true, result: outcome.result };
+  }
+};
+const aiTools = [
+  delegateAgentTool,
+  submitOutcomeTool,
+  loadSkillTool,
+  runSkillScriptTool,
+  webSearchTool,
+  webFetchTool
+];
+var ai_tools_default = aiTools;
+export {
+  LOAD_SKILL_TOOL_ID,
+  RUN_SKILL_SCRIPT_TOOL_ID,
+  SUBMIT_OUTCOME_TOOL_ID,
+  aiTools,
+  ai_tools_default as default
+};
+//# sourceMappingURL=ai-tools.js.map