@pmcollab/coworkstream-engine

Headless decision-routing engine for @pmcollab/coworkstream. Dispatches items to a plurality of agents in parallel, computes inter-agent alignment, escalates to human review only on conflict, and learns per-agent trust weights from human resolutions.

Coding agents: if you are an AI assistant integrating this package on behalf of a developer, read AGENTS.md. It contains a single-page integration recipe with the four extension interfaces, the event contract, common patterns, and a complete end-to-end example.

Migrating from an existing agent system? Read MIGRATION.md. It covers the common starting points (single-agent confidence gate, multi-agent debate, Python LangChain, Copilot Studio, Azure AI Foundry, MAF) and the pattern for layering this engine on top without rewriting your agents.

Install

npm install @pmcollab/coworkstream-engine

Pick at least one agent adapter (or build a custom AgentRunner):

| Adapter | Wraps | |---|---| | @pmcollab/coworkstream-engine-anthropic | Anthropic Claude SDK | | @pmcollab/coworkstream-engine-openai | OpenAI SDK with strict JSON Schema | | @pmcollab/coworkstream-engine-langgraph | A compiled LangGraph graph | | @pmcollab/coworkstream-engine-http | Universal — any HTTP-reachable agent (covers all Python frameworks) | | @pmcollab/coworkstream-engine-msagent | Microsoft Agent Framework (in-process or HTTP) | | @pmcollab/coworkstream-engine-copilot-studio | Microsoft Copilot Studio over Direct Line | | @pmcollab/coworkstream-engine-azure-ai-agent | Azure AI Foundry hosted agents |

Quick start

import {
  createEngine,
  createMockAgent,
  createMemoryStore,
  createMemoryTrustModel,
  weightedVote,
} from '@pmcollab/coworkstream-engine'

const engine = createEngine({
  agents: [
    createMockAgent({ id: 'risk',    position: 'reject',  confidence: 0.7 }),
    createMockAgent({ id: 'finance', position: 'approve', confidence: 0.9 }),
    createMockAgent({ id: 'sales',   position: 'approve', confidence: 0.6 }),
  ],
  alignmentStrategy: weightedVote({ alignedThreshold: 0.85 }),
  trustModel: createMemoryTrustModel(),
  store: createMemoryStore(),
})

engine.on('escalate',    (item) => { /* surface in UI */ })
engine.on('autoResolve', (item, winner) => { /* engine resolved */ })

await engine.process({ id: 'i1', category: 'decision', title: 'Discount: Globex' })

// later, when the human picks an action:
await engine.resolve({ itemId: 'i1', action: 'approve', userId: 'u1' })

For a full production wiring (real agents + queue + Postgres + audit + realtime + HTTP API + auth), see the end-to-end example in AGENTS.md § 6.

The four extension points

| Interface | Replace with | Built-in | |---|---|---| | AgentRunner | Adapter for your LLM / agent SDK | createMockAgent | | AlignmentStrategy | Your routing rule | exactMatch, weightedVote, thresholdVote | | TrustStore | Persistent trust DB | createMemoryTrustModel (adaptive) | | ItemStore | Your DB | createMemoryStore |

Drop-in production replacements:

• @pmcollab/coworkstream-prisma — Postgres-backed ItemStore + TrustStore
• @pmcollab/coworkstream-audit — tamper-evident, hash-chained event log

What the engine does

1. Dispatch — selects agents whose capabilities include the item's category (or all agents if none match), runs them in parallel, captures { position, reasoning, confidence } from each.
2. Align — passes positions to the strategy. The strategy returns { status, escalate }.
3. Persist — stamps multiAgent.alignmentStatus and multiAgent.positions onto the item and upserts to the store. Audit log captures the event.
4. Branch — if escalate=true, emits 'escalate' for the UI to surface. If escalate=false, picks the highest-trust agent's position and applies it automatically.
5. Learn — when engine.resolve(...) is called with the human's action, every agent's trust weight is updated: +learningRate * (1 - trust) on agreement, -learningRate * trust on disagreement, clamped to [0, 1].

The trust update is per-(agent, category) — an agent earns trust independently for each decision category, so specialization emerges from human feedback without any operator configuration.

Alignment strategies

| Strategy | Aligned when | Use when | |---|---|---| | exactMatch() | All agents return the same position | You want strict consensus | | weightedVote({ alignedThreshold, conflictThreshold }) | Trust × confidence weighted share crosses upper threshold | Default — best behavior over time | | thresholdVote({ quorum }) | At least quorum agents agree | Fixed agent pools (e.g. always 3) |

Custom strategies: implement compute(positions, ctx) => { status, escalate }. See AGENTS.md § 3.2.

Examples

The examples/ folder has paste-ready integration files:

• 01-basic-mock.js — minimum viable engine with mock agents (no API keys).
• 02-anthropic-real.js — real Claude agents producing structured decisions.
• 03-http-bridge-python.js — universal HTTP bridge with a Python FastAPI server example.
• 04-multi-agent-vote.js — trust learning loop across many resolutions.
• 05-otel-instrumented.js — engine with OpenTelemetry tracing + metrics.

Documentation

• AGENTS.md — coding-agent integration recipe (sections 1–9, with end-to-end example).
• MIGRATION.md — adopting the engine from an existing single-agent or multi-agent setup.
• SUPPORT.md — supported runtimes, agent backends, persistence backends, versioning policy.
• CHANGELOG.md — version history.
• TypeScript declarations: src/index.d.ts — every prop, return type, and option documented.

License

Commercial. See LICENSE in the repository root.