# Boss Loops - Full Documentation
> https://bossloops.io
 | Apache-2.0 Licensed | Created by Better Data (https://betterdata.co)
> Generated: 2026-07-30T17:52:58.612Z
> Source: https://github.com/loopengine/loopengine.io

This file contains the complete Boss Loops documentation in a single
plain-text file optimized for LLM context windows.
Structured summary: https://bossloops.io
/llms.txt

---
## Quick Start
URL: https://bossloops.io
/docs/getting-started/quick-start
Summary: Install @loop-engine/sdk, define a loop, and run it in under 5 minutes.
Section: Getting Started


Install the **OSS governance runtime** locally, define a decision loop, and run a governed transition in minutes. For vocabulary (Providers, Channels, Integrations, guards, evidence), read [Runtime Taxonomy](/docs/concepts/runtime-taxonomy) first — or continue here and return to [Architecture](/docs/getting-started/architecture) for the full runtime model. For self-host direction vs hosted Cloud (and roadmap-only services), see [Runtime Platform Direction](/docs/concepts/runtime-platform-direction).

## Prerequisites

Node.js 18+ and npm or pnpm.

## Install

```bash
npm install @loop-engine/sdk
```

## Define a loop and run it

```ts
// @no-typecheck
import { aggregateId, transitionId } from '@loop-engine/core'
import { LoopBuilder, createLoopSystem } from '@loop-engine/sdk'

const approval = LoopBuilder
  .create('expense.approval', 'finance')
  .description('Expense report approval')
  .state('SUBMITTED')
  .state('UNDER_REVIEW')
  .state('APPROVED', { isTerminal: true })
  .state('REJECTED', { isTerminal: true })
  .initialState('SUBMITTED')
  .transition({
    id: 'start_review',
    from: 'SUBMITTED',
    to: 'UNDER_REVIEW',
    actors: ['automation']
  })
  .transition({
    id: 'approve',
    from: 'UNDER_REVIEW',
    to: 'APPROVED',
    actors: ['human']
  })
  .transition({
    id: 'reject',
    from: 'UNDER_REVIEW',
    to: 'REJECTED',
    actors: ['human']
  })
  .outcome({
    id: 'expense_approved',
    description: 'Expense report approved',
    valueUnit: 'expense_approved',
    businessMetrics: [
      { id: 'm_expense_approved', label: 'Expense report approved', unit: 'count' }
    ]
  })
  .build()

const { engine, eventBus } = await createLoopSystem({ loops: [approval] })
eventBus.subscribe(async (event) => console.log(event.type))

await engine.start({
  loopId: 'expense.approval',
  aggregateId: aggregateId('EXP-2026-001'),
  actor: { type: 'automation', id: 'system:intake', serviceId: 'intake' }
})

await engine.transition({
  aggregateId: aggregateId('EXP-2026-001'),
  transitionId: transitionId('start_review'),
  actor: { type: 'automation', id: 'system:router', serviceId: 'router' }
})

await engine.transition({
  aggregateId: aggregateId('EXP-2026-001'),
  transitionId: transitionId('approve'),
  actor: { type: 'human', id: 'manager@acme.com', userId: 'manager-1', displayName: 'Manager' },
  evidence: { comment: 'Approved for Q1 budget' }
})

const state = await engine.getState(aggregateId('EXP-2026-001'))
console.log(state?.currentState) // APPROVED
console.log(state?.status)       // completed
```

## What just happened

<Callout variant="info" title="Execution summary">
- The loop moved through 3 states (`SUBMITTED -> UNDER_REVIEW -> APPROVED`)
- 2 actor types were used (`automation`, `human`)
- Each successful transition emitted `loop.transition.executed`
- Reaching a terminal state sets loop status to `completed`
</Callout>

## Next steps

- [Runtime Taxonomy](/docs/concepts/runtime-taxonomy)
- [Architecture](/docs/getting-started/architecture)
- [Installation](/docs/getting-started/installation)
- [Your First Loop](/docs/getting-started/your-first-loop)
- [Runtime connections](/docs/integrations)
- [Decision Governance](/docs/concepts/decision-governance)


---

## Installation
URL: https://bossloops.io
/docs/getting-started/installation
Summary: Install the Boss Loops SDK or individual packages and configure TypeScript for strict, modern builds.
Section: Getting Started


## Install @loop-engine/sdk

```bash
npm install @loop-engine/sdk
```

This is the entire required install. Every other package is additive.

<Callout variant="info" title="Version cohorts">
Most of the `@loop-engine/*` family is published in the `1.0.0-rc.0` cohort. A small number of adapters may remain pre-1.0 while their API shape stabilizes (for example, `@loop-engine/adapter-kafka@0.1.7` and `@loop-engine/adapter-postgres@0.2.0`). Install the capability you need; cohort boundaries are explicit in the docs where they matter.
</Callout>

```bash
pnpm add @loop-engine/sdk
```

```bash
yarn add @loop-engine/sdk
```

## TypeScript configuration

Use at least:

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "moduleResolution": "bundler",
    "strict": true
  }
}
```

`moduleResolution: "node16"` also works.

## Install packages individually

If you do not want the SDK aggregate package, install only what you need.

Core primitives:

- `@loop-engine/core` - domain model types and branded IDs
- `@loop-engine/loop-definition` - `LoopBuilder`, parser, schema validation
- `@loop-engine/runtime` - `LoopEngine` and runtime interfaces
- `@loop-engine/events` - event types, schemas, and `InMemoryEventBus`
- `@loop-engine/guards` - guard registry and built-in guards
- `@loop-engine/actors` - actor types, constraints, evidence helpers
- `@loop-engine/signals` - signal engine and built-in rules
- `@loop-engine/observability` - metrics, timelines, replay
- `@loop-engine/registry-client` - remote/local **loop catalog** client (package name retains `registry-client`)
- `@loop-engine/ui-devtools` - React devtools components

Stores:

- `@loop-engine/adapter-memory` - in-memory `LoopStore`
- `@loop-engine/adapter-postgres` - PostgreSQL `LoopStore` adapter
- `@loop-engine/adapter-kafka` - Kafka `EventBus` adapter
- `@loop-engine/adapter-http` - HTTP webhook `EventBus` adapter

AI adapters:

- `@loop-engine/adapter-anthropic` - Claude actor adapter
- `@loop-engine/adapter-openai` - GPT actor adapter
- `@loop-engine/adapter-gemini` - Gemini actor adapter
- `@loop-engine/adapter-grok` - Grok actor adapter
- `@loop-engine/adapter-perplexity` - Sonar grounded-search adapter

Routing and framework adapters:

- `@loop-engine/adapter-pagerduty` - PagerDuty approval routing
- `@loop-engine/adapter-openclaw` - OpenClaw skill / approval bridge
- `@loop-engine/adapter-vercel-ai` - Vercel AI SDK tool-call governance
- `@loop-engine/adapter-commerce-gateway` - Commerce Gateway tool routing

## Runtime requirements

- Node.js 18+ is required.

## Browser support

Works in browser:

- `@loop-engine/core`
- `@loop-engine/loop-definition`
- `@loop-engine/events`
- `@loop-engine/actors`
- `@loop-engine/guards`
- `@loop-engine/observability`
- `@loop-engine/signals`
- `@loop-engine/adapter-memory`

Notes:

- `@loop-engine/runtime` needs a `LoopStore` implementation.
- `@loop-engine/adapter-postgres` and `@loop-engine/adapter-kafka` are server-side adapters.


---

## Your First Loop
URL: https://bossloops.io
/docs/getting-started/your-first-loop
Summary: Build an expense approval loop step by step, with states, actors, guards, and outcomes.
Section: Getting Started


## 1) Design the loop before writing code

Start with outcome first:

- Outcome ID: `expense_approved`
- Value unit: `expense_approved`
- States: `SUBMITTED -> UNDER_REVIEW -> APPROVED` (or `REJECTED`)
- Actors: `system`, `automation`, `human`

```text
SUBMITTED -> UNDER_REVIEW -> APPROVED
                        \-> REJECTED
```

## 2) States and transitions

`StateSpec` fields from `@loop-engine/core`:

- `id` (required)
- `isTerminal?: boolean` (default false)
- `isError?: boolean` (default false)

Terminal states close the loop (`status: "completed"`).  
Error states set `status: "failed"`.

## 3) Actors

Boss Loops supports 5 actor types:

- `human`
- `automation`
- `ai-agent`
- `webhook`
- `system`

Actor authorization is checked against each transition's `allowedActors`.

See [The Actor Model](/docs/concepts/actor-model) for full details.

## 4) Start and run the loop

```ts
// @no-typecheck
import { aggregateId, transitionId } from '@loop-engine/core'
import { LoopBuilder, createLoopSystem } from '@loop-engine/sdk'

const approval = LoopBuilder
  .create('expense.approval', 'finance')
  .description('Expense report approval')
  .state('SUBMITTED')
  .state('UNDER_REVIEW')
  .state('APPROVED', { isTerminal: true })
  .state('REJECTED', { isTerminal: true })
  .initialState('SUBMITTED')
  .transition({
    id: 'start_review',
    from: 'SUBMITTED',
    to: 'UNDER_REVIEW',
    actors: ['automation']
  })
  .transition({
    id: 'approve',
    from: 'UNDER_REVIEW',
    to: 'APPROVED',
    actors: ['human'],
    guards: [
      {
        id: 'approval_obtained',
        severity: 'hard',
        evaluatedBy: 'runtime',
        description: 'Approval must be present',
        failureMessage: 'Approval not obtained'
      }
    ]
  })
  .transition({
    id: 'reject',
    from: 'UNDER_REVIEW',
    to: 'REJECTED',
    actors: ['human']
  })
  .outcome({
    id: 'expense_approved',
    description: 'Expense report approved',
    valueUnit: 'expense_approved',
    businessMetrics: [
      { id: 'm_expense_approved', label: 'Expense report approved', unit: 'count' }
    ]
  })
  .build()

const aggregate = aggregateId('EXP-2026-001')
const { engine } = await createLoopSystem({ loops: [approval] })

await engine.start({
  loopId: 'expense.approval',
  aggregateId: aggregate,
  actor: { type: 'system', id: 'system:intake' }, // StartOptions.actor
  metadata: { source: 'expense_form' } // optional application correlation (neutral keys only)
})

const reviewResult = await engine.transition({
  aggregateId: aggregate,
  transitionId: transitionId('start_review'),
  actor: { type: 'automation', id: 'system:router' }
})

const approveResult = await engine.transition({
  aggregateId: aggregate,
  transitionId: transitionId('approve'),
  actor: { type: 'human', id: 'manager@acme.com' },
  evidence: { approved: true, comment: 'Within policy' }
})
```

## 5) Inspect the result

```ts
const instance = await engine.getState(aggregate)
const history = await engine.getHistory(aggregate)

console.log(instance?.currentState) // branded StateId
console.log(instance?.status)       // pending | active | completed | failed | cancelled | suspended

// TransitionRecord fields
for (const row of history) {
  console.log(row.transitionId, row.fromState, row.toState, row.actor.type, row.occurredAt)
}
```

`engine.getState()` returns `Promise<LoopInstance | null>`.  
`engine.getHistory()` returns `Promise<TransitionRecord[]>`.

## 6) Guard failure example

If `approval_obtained` fails (for example `evidence.approved !== true`), `transition()` returns:

```ts
{
  status: "guard_failed",
  fromState: "UNDER_REVIEW",
  guardFailures: [
    { guardId: "approval_obtained", message: "Approval not obtained", severity: "hard" }
  ]
}
```

The state does not advance, and `loop.guard.failed` is emitted.

## 7) Next steps

- [What is a Loop?](/docs/concepts/what-is-a-loop)
- [Guards and Policy](/docs/concepts/guards-and-policy)
- [Transitions](/docs/running-loops/transitions)


---

## Architecture
URL: https://bossloops.io
/docs/getting-started/architecture
Summary: Boss Loops runtime architecture — governance boundaries, evidence flow, Providers, Channels, Integrations, and runtime vs Cloud.
Section: Getting Started


Boss Loops is a **governance runtime**, not a generic workflow orchestrator or AI automation builder. This page describes how the runtime composes **decision loops**, **deterministic guards**, and **evidence** with external **Providers**, **Channels**, and **Integrations**.

→ Full glossary: [Runtime Taxonomy](/docs/concepts/runtime-taxonomy)

## Governance runtime (center of the model)

Every operational change that Boss Loops owns passes through the same boundary:

1. A named **actor** requests a transition.
2. **Guards** evaluate policy in the runtime (hard failures block; soft failures may warn).
3. **Evidence** is attached to the allowed transition.
4. An immutable **event** is emitted for audit and learning.

AI does not “run the business” inside Boss Loops — it operates **inside** deterministic governance boundaries. Orchestration frameworks may run elsewhere; **loops govern the transitions**.

```text
Providers          ← intelligence enters (LLMs, retrieval tools)
        ↓
Decision loops + Guards   ← GOVERNANCE: Boss Loops (policy before commit)
        ↓
Channels           ← humans participate (Slack, Teams, approvals)
        ↓
Integrations       ← systems of record execute (CRM, tickets, APIs)
        ↓
Evidence + learning ← audit + operational improvement
```

| Stage | What enters | What exits | Who participates |
| --- | --- | --- | --- |
| Providers | Context, signals | Structured AI/human submissions | Models as governed actors |
| Loops + Guards | Transition requests | Allow / block / escalate | Runtime policy (deterministic) |
| Channels | `PENDING_HUMAN_*` events | Human actor transitions | Operators in Slack, email, etc. |
| Integrations | Approved transitions | CRM rows, webhooks, staged applies | Enterprise systems |
| Evidence | Each commit | Audit + learning signals | Compliance, RevOps, SRE |

### Evidence flow

Evidence is produced **at transition time**:

- Inputs the actor used (scores, documents, approval notes)
- Guard outcomes and soft warnings
- Provider metadata (`modelId`, `provider`, `promptHash` for AI actors)

Downstream analytics and learning signals consume events — they do not replace the runtime evidence contract.

### Runtime boundaries

| Boundary | Inside Boss Loops | Outside (but connected) |
| --- | --- | --- |
| Policy | Guards, allowed actors, transition graph | Prompt content alone is not policy |
| State | Loop instance state, transition history | ERP/CRM records update via Integrations after approval |
| Humans | Attribution + channel routing | Slack/Teams UIs are Channels |
| Intelligence | Provider adapters submit decisions | Models do not call integrations directly |

## Runtime platform vs Boss Loops Cloud

**Boss Loops can run inside your infrastructure, or connect to hosted governance services from Better Data.** Full positioning constraints and roadmap language: **[Runtime Platform Direction](/docs/concepts/runtime-platform-direction)**.

### OSS runtime platform (today)

- **Local-first** — your Node.js process runs `createLoopSystem` with chosen stores and adapters (not a required multi-service mesh today).
- **Self-host substrate** — operational governance in your stack: loops, guards, evidence, events via `@loop-engine/sdk`.
- **Adapters** — Providers, Channels, and Integrations you wire and operate.

→ [Quick Start](/docs/getting-started/quick-start) · [Runtime Platform Direction](/docs/concepts/runtime-platform-direction)

### Boss Loops Cloud (hosted)

- **Governance control plane** — multi-tenant HTTP API, connector credentials, documented `/api/v1` contract.
- **Adds** — managed connector paths (e.g. Slack, Google) and fleet-style operations **without** replacing the OSS runtime model.
- **Not claimed** — full OSS parity with every Cloud feature; Studio; docker compose kit; multi-service runtime **today**.

→ [Boss Loops Cloud HTTP API](/docs/cloud/api-reference)

**Better Data company and application docs:** [docs.betterdata.co](https://docs.betterdata.co) — not loopengine.io.

## Connection types (taxonomy summary)

| Type | Role in architecture | Examples |
| --- | --- | --- |
| **Provider** | Intelligence into the loop | Claude, GPT-4o, Gemini, Grok |
| **Channel** | Human approval / escalation surface | Slack, Teams, OpenClaw routing |
| **Integration** | Systems and persistence after governance | Postgres, Kafka, PagerDuty, Commerce Gateway |

See [Runtime Taxonomy](/docs/concepts/runtime-taxonomy) for definitions and disambiguation (e.g. DCM “channels” vs human Channels).

## Runtime primitives (implementation layer)

These packages implement the governance runtime. They are **not** the product category names — they are how the engine executes loops.

### Loops

Loops are governed decision cycles: states, transitions, signals, and terminal outcomes. Transitions are triggered by **signals** and authorized by **actors** subject to **guards**.

```ts
type LoopDefinition = {
  loopId: string;
  states: Array<{ stateId: string; terminal?: boolean }>;
  initialState: string;
  transitions: Array<{ transitionId: string; from: string; to: string; signal: string }>;
};
```

### Signals

Signals name the intent to move between states. They carry actor context into guard evaluation.

### Actors

```ts
type ActorType = "human" | "automation" | "ai-agent";
```

→ [Actor Model](/docs/concepts/actor-model)

### Guards

```ts
type GuardSpec = {
  guardId: string;
  severity: "hard" | "soft";
  evaluatedBy: "runtime" | "module" | "external";
};
```

Hard guard failure emits `loop.guard.failed` and does not advance state.

→ [Guards and Policy](/docs/concepts/guards-and-policy)

### Events

```ts
type LoopTransitionExecutedEvent = {
  type: "loop.transition.executed";
  loopId: string;
  aggregateId: string;
  transitionId: string;
  fromState: string;
  toState: string;
  actor: { type: ActorType; id: string };
  evidence?: Record<string, unknown>;
};
```

### Learning signals

When a loop completes, learning signals compare predicted vs actual outcomes for improvement loops.

→ [Learning Signals](/docs/concepts/learning-signals)

## End-to-end example (Provider → guards → Channel → Integration)

```ts
// @no-typecheck
import { createLoopSystem } from "@loop-engine/sdk";
import { createAnthropicActorAdapter } from "@loop-engine/adapter-anthropic";

const { engine } = await createLoopSystem({ loops: [/* procurement loop */] });
const ai = createAnthropicActorAdapter({
  apiKey: process.env.ANTHROPIC_API_KEY!,
  model: "claude-opus-4-6"
});

// Integration may have created the aggregate; automation opens the loop.
await engine.start({
  loopId: "procurement" as never,
  aggregateId: "PO-2001" as never,
  actor: { type: "automation", id: "system:intake" }
});

// Provider: AI recommends a transition (does not bypass guards).
const { actor, decision } = await ai.createSubmission({
  loopId: "procurement",
  loopName: "SCM Procurement",
  currentState: "pending_analysis",
  availableSignals: [{ signalId: "submit_recommendation", name: "Submit Recommendation" }],
  instruction: "Recommend order action",
  evidence: { forecast: 0.83 }
});

await engine.transition({
  aggregateId: "PO-2001" as never,
  transitionId: "submit_recommendation" as never,
  actor,
  evidence: decision
});

// Guards run in runtime — e.g. confidence threshold.
// Channel: human approval transition (Slack/OpenClaw/PagerDuty routing).
// Integration: ERP/Commerce Gateway executes only after approved transition.
// Terminal state emits loop.completed + learning signal.
```

## What Boss Loops is not

- **Not** a replacement for Temporal, n8n, or BPM suites — use [Boss Loops vs Workflow Engines](/docs/concepts/loop-engine-vs-workflow-engines).
- **Not** an AI automation builder that skips policy.
- **Not** a Slack bot product — Slack is a **Channel** when used for human approval.

## Next steps

- [Runtime Taxonomy](/docs/concepts/runtime-taxonomy)
- [Quick Start](/docs/getting-started/quick-start)
- [Runtime connections](/docs/integrations)
- [Decision Governance](/docs/concepts/decision-governance)


---

## Boss Loops Cloud
URL: https://bossloops.io
/docs/cloud
Summary: Boss Loops Cloud — the managed distribution of Boss Loops. Governed decision loops, user management scoped by location, outcome-based metering, and audit exports, operated by Better Data.
Section: Boss Loops Cloud


<div className="docs-quick-links">
  <span className="docs-status-badge tier-cloud">Cloud</span>
  <span className="docs-status-badge attr-built-in">Production: loops.betterdata.co</span>
</div>

**Boss Loops Cloud** is the **managed** distribution of Boss Loops — run governed,
observable decision loops without operating the runtime yourself. Same engine, same
governance model as [Boss Loops OSS](/docs/getting-started/quick-start); Better Data
operates scale, isolation, metering, and upgrades. Commercial tiers and early access:
[Pricing](/pricing).

## See the product: the governed Decision Record

The canonical product demo is the **Alpine demo Decision Record** — a supplier invoice
decision (`INV-2026-004521`) carrying frozen evidence, the policy that applied, the approval
captured with the evidence presented, and preview semantic evidence from
[Looker](/docs/concepts/evidence-providers#looker-semantic-evidence-preview). It shows what Boss Loops sells: a
decision you can defend a year later.

## Start

- **<CtaLink cta="start_cloud" location="boss-loops/cloud" href="https://betterdata.co/company/contact?intent=loop-engine">Talk to us about Boss Loops Cloud</CtaLink>** — we'll set up your organization and tenant with you

Prefer to reach out directly?

- <CtaLink cta="early_access" location="boss-loops/cloud" href="https://betterdata.co/company/contact?intent=loop-engine">Request early access</CtaLink>
- <CtaLink cta="waitlist" location="boss-loops/cloud" href="https://betterdata.co/company/contact?intent=loop-engine">Join the waitlist</CtaLink>
- <CtaLink cta="sales" location="boss-loops/cloud" href="https://betterdata.co/company/contact?intent=loop-engine">Contact sales</CtaLink>

> **OSS proves the loop. Cloud runs the workflow.**
>
> The [OSS quickstart](/docs/getting-started/quick-start) proves the loop state machine on
> your machine. Boss Loops Cloud runs live workflows — managed connectors (Slack, Google, …),
> tenancy, and audit exports. See [Cloud getting started](/docs/cloud/getting-started).

## What is Boss Loops Cloud?

Boss Loops Cloud, hosted at **[loops.betterdata.co](https://loops.betterdata.co)**, runs the
Boss Loops model as a **managed service**. You integrate via APIs and module manifests;
Better Data operates scale, isolation, and upgrades. The runtime technology underneath is the
**Boss Loops runtime** (`@loop-engine/*`) — see [Architecture](/docs/getting-started/architecture).

**Self-hosted alternative:** Boss Loops OSS — start with the
[quick start](/docs/getting-started/quick-start) and the engine docs on this site.

## What you get

See [Cloud operations](/docs/cloud/operations) for the full capability list — org isolation,
outcome-based metering, capability enforcement, tamper-evident audit trail, drift detection,
and Industry Pack policy overlays.

## API

The hosted runtime exposes a versioned HTTP API — see the
[Cloud API reference](/docs/cloud/api-reference), which also links the generated OpenAPI
reference and the monorepo contract.

## Boss Loops OSS vs Boss Loops Cloud

| | Boss Loops OSS (`@loop-engine/sdk`) | Boss Loops Cloud ([loops.betterdata.co](https://loops.betterdata.co)) |
| - | ------------------------- | ----------------------------------------------------------- |
| Cost | Free (Apache-2.0) | See [Pricing](/pricing) |
| Setup | You operate | No infrastructure setup |
| User management & location scopes | Your implementation | Built in |
| Industry Packs | No | Yes |
| Audit / compliance exports | Your pipelines | Platform aggregation + reports |
| SLA | Self-managed | Better Data SLA |


---

## Getting started with Boss Loops Cloud
URL: https://bossloops.io
/docs/cloud/getting-started
Summary: Choose your path — prove the loop mechanics locally with Boss Loops OSS in five minutes, or start Boss Loops Cloud for live connectors, tenancy, and audit exports.
Section: Boss Loops Cloud


<div className="docs-quick-links">
  <span className="docs-status-badge tier-cloud">Cloud</span>
</div>

Two ways to experience Boss Loops:

| | **Run locally in 5 minutes** | **Run live with integrations** |
| - | --- | --- |
| Product | **Boss Loops OSS** | **Boss Loops Cloud** |
| What you get | dry-run of the Spreadsheet Approval loop over seeded evidence | live **Slack** approval + live **Google Sheets** apply |
| Credentials | **none** | Slack app + Google OAuth |
| Where | [OSS quick start](/docs/getting-started/quick-start) | [Start Boss Loops Cloud](/docs/cloud) |

## The OSS 5-minute proof

```bash
# Boss Loops OSS — local, credential-free 5-minute proof
pnpm boss-loops:demo --dry-run
```

<Callout variant="info">
The `boss-loops:demo` script runs from the Better Data monorepo checkout. If you are
starting from the published packages instead, follow the
[quick start](/docs/getting-started/quick-start) — same loop model, SDK-first.
</Callout>

The dry-run walks the real loop state machine and prints the staged change, the approval,
the applied result, and an audit trail — no Slack or Google credentials required.

## The Cloud path

Live connectors (Slack approvals, Google Sheets apply) are **Cloud-only** — the OSS
self-host runtime intentionally excludes hosted connectors:

```txt
Slack approval request → Google Sheets staged update → Approve in Slack
→ Sheet updated → confirmation → execution history
```

Start from the [Cloud overview](/docs/cloud) — organization and tenant are created in
seconds, no payment required. Commercial tiers: [Pricing](/pricing).


---

## Cloud operations
URL: https://bossloops.io
/docs/cloud/operations
Summary: What Boss Loops Cloud operates for you — tenancy and isolation, outcome-based metering, capability enforcement, audit exports, drift detection, and the canonical loop types.
Section: Boss Loops Cloud


<div className="docs-quick-links">
  <span className="docs-status-badge tier-cloud">Cloud</span>
</div>

## What you get with Boss Loops Cloud

- **User management** — roles and approval authority scoped by location (plants, regions, business units)
- **Outcome-based metering** (billing tied to loop completions — see [Pricing](/pricing))
- **TenantCapabilitySnapshot**-style capability enforcement for RBAC
- Tamper-evident **loop audit trail** and export paths for compliance workflows
- **Drift detection** (scheduled validation of expected vs observed state)
- **Outbox relay** for cross-module event delivery
- **Industry Pack** policy overlays (hosted-only; not published as OSS)

## Loop types (canonical)

| Loop | Module | What it governs |
| ---- | ------ | ---------------- |
| `scm.procurement` | SCM | AI-assisted PO recommendation + human approval gates |
| `scm.fulfillment` | SCM | Multi-step order fulfillment |
| `scm.quality` | SCM | Inspection, deviation, CAPA-style disposition |
| `scm.replenishment` | SCM | Demand signal → reorder / replenishment |
| `dcm.demand` | DCM | Demand signal detection and replenishment triggers |
| `dcm.order` | DCM | Channel order routing and lifecycle |
| `dcm.returns` | DCM | Return authorization and reverse logistics |

For the platform conceptual model behind these loop types, see
[Loops on the Better Data platform](https://docs.betterdata.co/docs/platform/loops).

## Hosted services

The running hosted stack includes **hosted-loops** (runtime + loops database API) and the
published loop definitions catalog. For how these relate to the wider Better Data platform
apps, see
[Hosted platform apps](https://docs.betterdata.co/docs/developer-resources/reference/hosted-platform-apps).

## API

Versioned HTTP routes for loop lifecycle, runs, baselines, and connector health are
documented in the [Cloud API reference](/docs/cloud/api-reference).


---

## Boss Loops Cloud API reference
URL: https://bossloops.io
/docs/cloud/api-reference
Summary: The Boss Loops Cloud HTTP API — auth, versioned routes, the generated OpenAPI reference, and the canonical contract in the monorepo.
Section: Boss Loops Cloud


<div className="docs-quick-links">
  <span className="docs-status-badge tier-cloud">Cloud</span>
  <span className="docs-status-badge attr-built-in">Production: loops.betterdata.co</span>
  <span className="docs-status-badge attr-built-in">Taxonomy: Integration (hosted control plane)</span>
</div>

## What this is

This site documents the **OSS governed engine** (`@loop-engine/*`). **Boss Loops Cloud** is
the **hosted Integration** path: same loop/guard/evidence model, operated by Better Data
with tenancy, API keys, and managed connectors (Slack, Google, …).

| Surface | Where to read |
| --- | --- |
| Boss Loops engine, taxonomy, adapters | This site (bossloops.io/docs) |
| Boss Loops Cloud HTTP contract | This page + the references below |
| Better Data platform, SCM, CCO applications | **[docs.betterdata.co](https://docs.betterdata.co)** |

**The OSS engine** defines states, signals, guards, transitions, and events in **your**
infrastructure. **Boss Loops Cloud** exposes the execution contract over **HTTPS** when you
want managed governance operations.

- **Developers & integrations** → **`https://loops.betterdata.co`** (Bearer JWT for first-party services, **`le_` API keys** for external automation).
- **Operators** → **Automation** at **`app.betterdata.co/automation`** (product UX; same loops conceptually).

We document **shipped** Cloud capabilities here and in the references below. We do not imply
undelivered OSS parity, Studio, docker compose runtime, or a multi-service mesh **today** —
see [Runtime Platform Direction](/docs/concepts/runtime-platform-direction) and
[changelog](/docs/changelog).

## Routes at a glance

The **hosted-loops** service exposes versioned HTTP routes under **`/api/v1/...`**.
**Production base URL** mapping (for example **`loops.betterdata.co`**) is
environment-specific — confirm with your deployment or support.

| Prefix | Purpose (high level) |
| --- | --- |
| **`/api/v1/loops`** | List/create loop concerns; catalog, start, transition, cancel, events, history, and integration helpers |
| **`/api/v1/loops/runs`** | Run detail and comparison |
| **`/api/v1/loops/definitions`** | Definition-scoped run listings |
| **`/api/v1/baselines`** | Baselines CRUD, transitions, true-ups, delivery routes |
| **`/api/v1/connectors/*`** | Connector health and OAuth/event surfaces (e.g. Slack, Google) |

External callers should use the service's **authenticated API** only; **exact auth header
and tenancy claims** are defined by the hosted-loops implementation — treat field names and
JWT contracts as **implementation details** to verify in the references below.

## Canonical references

- **[Generated OpenAPI reference](https://docs.betterdata.co/docs/developer-resources/api-reference/boss-loops)** —
  the route-by-route generated reference (from `apps/hosted-loops/openapi.yaml`, DP-07). It
  lives on the Better Data platform docs and stays there.
- **[Boss Loops Cloud HTTP API contract (source)](https://github.com/betterdata-platform/bd-forge-main/blob/main/apps/hosted-loops/docs/api.md)** —
  the developer contract maintained alongside the implementation. Pull requests that change
  route handlers should update it in the same change-set when the public JSON contract moves.

## Related OSS docs

- [HTTP adapter](/docs/integrations/http) — webhook-style **outbound** adapter from the OSS runtime; not the same as Boss Loops Cloud ingress.
- [Architecture](/docs/getting-started/architecture) — core Boss Loops concepts reused by the hosted service.

## Pricing

See [Pricing](/pricing) — open core plus Starter, Team, and Enterprise tiers. Launch pricing is being
finalized; all commercial tiers are in early access. (Do not hardcode prices in integration guides.)


---

## Runtime Taxonomy
URL: https://bossloops.io
/docs/concepts/runtime-taxonomy
Summary: Canonical terms for Boss Loops — Providers, Channels, Integrations, Loops, Guards, Evidence, and Actors — plus runtime vs Boss Loops Cloud.
Section: Core Concepts


Boss Loops is a **governed operational runtime platform**. This page is the canonical glossary for public docs on [loopengine.io](https://loopengine.io). Package names (`@loop-engine/*`) and developer types (`ActorAdapter`, `ToolAdapter`) are implementation details — see [IntegrationAdapter archetype](/docs/concepts/integration-adapter) for the implementer map.

## Runtime flow (read this first)

```text
Providers          → intelligence in (analyze, recommend, classify)
        ↓
Decision loops + Guards   → governance (who may transition, under what policy)
        ↓
Channels           → human coordination (approve, reject, escalate)
        ↓
Integrations       → operational execution (CRM, tickets, apply writes)
        ↓
Evidence + learning → audit trail and improvement
```

**Rules this model enforces:**

- **Channels are not integrations.** Slack approves; Salesforce updates.
- **Providers are not workflow systems.** Temporal executes paths; loops govern commits.
- **Integrations are not governance.** Guards run in the runtime, not in your CRM.
- Providers do **not** bypass guards or write directly to integrations.
- Integrations do **not** call models without a governed loop transition.
- Durable workflow engines may **execute** approved work; **loops govern** whether transitions commit.

## Public taxonomy

| Public term | Meaning |
| --- | --- |
| **Provider** | **Intelligence system** — generates analysis and recommendations; does not commit operational state. |
| **Channel** | **Human coordination surface** — where people approve, reject, or escalate; not a system of record. |
| **Integration** | **System of record / operational system** — executes actions and persists state after policy passes. |
| **Loop** | Governed decision cycle — explicit states, transitions, signals, and outcomes (not a generic BPM template). |
| **Guard** | Deterministic runtime policy — evaluated before a transition commits; not prompt instructions. |
| **Evidence** | Auditability layer — structured context explaining why a transition was allowed. |
| **Actor** | Participant — human, automation, or AI agent (and engineering types such as webhook where documented). |

## Providers

**Providers** supply intelligence into a loop: recommendations, classifications, draft decisions, or research steps.

**Includes:** Anthropic, OpenAI, Gemini, Grok, Vercel AI SDK–backed models.

**Research steps:** Perplexity Sonar acts as a **tool** step (`ToolAdapter`) for grounded retrieval with citations — still governed by the same loop and guards.

**Excludes:** MCP as a Provider. MCP is a [protocol/connectivity layer](#mcp-and-commerce-gateway) used with Commerce Gateway; Boss Loops governs whether operational transitions proceed.

**npm adapters (examples):** `@loop-engine/adapter-anthropic`, `adapter-openai`, `adapter-gemini`, `adapter-grok`, `adapter-vercel-ai`, `adapter-perplexity`.

## Channels

**Channels** are where **humans** interact with a governed loop — not where ERP writes occur.

**Includes:** Slack, Microsoft Teams, email, Discord/Telegram via OpenClaw routing, in-app approval UIs.

**Not Boss Loops “Channels” (disambiguation):**

| Term elsewhere | What it means |
| --- | --- |
| **DCM commerce channel** | Sales/marketplace channel in Commerce Chain (Shopify, Amazon, etc.) |
| **Event-bus channel** | Internal module queue name in workers — engineering only |
| **`@betterdata/dcm-channels`** | Commerce Chain package — not this taxonomy |

**npm adapters (examples):** `@loop-engine/adapter-openclaw` (routing). Slack/Teams adapters are planned; hosted connectors may use Boss Loops Cloud APIs.

## Integrations

**Integrations** are operational systems and persistence layers that connect **after** governance:

- Trigger or enrich loops (PagerDuty incidents, webhooks)
- Persist state and events (Postgres, Kafka, memory store)
- Execute commerce or tool calls (Commerce Gateway)
- Apply approved writes (Google Workspace APIs in hosted patterns)

Browse the [runtime connections index](/docs/integrations) grouped by this taxonomy.

**npm adapters (examples):** `adapter-postgres`, `adapter-kafka`, `adapter-pagerduty`, `adapter-commerce-gateway`, `adapter-http`, `adapter-memory`.

## Loops, guards, evidence, actors

### Loop

A **loop** is a versioned **governed decision cycle** with `LoopDefinition` states and transitions. Finite-state machinery is the runtime implementation — the product unit is the **decision loop**.

→ [What is a Loop?](/docs/concepts/what-is-a-loop)

### Guard

**Guards** enforce policy at runtime: constrain execution, require evidence fields, escalate to humans, and block transitions that fail hard checks.

→ [Guards and Policy](/docs/concepts/guards-and-policy)

### Evidence

**Evidence** is attached to transitions to support audit, dispute resolution, and operational learning. It is captured when the transition is evaluated — not assembled later from scattered logs.

→ [Confidence + Evidence](/docs/ai-and-automation/confidence-evidence)

### Actor

Every transition names an **actor** (`human`, `automation`, `ai-agent`). Attribution is mandatory for governance.

→ [Actor Model](/docs/concepts/actor-model)

## MCP and Commerce Gateway

**MCP (Model Context Protocol)** is a **protocol and controlled connectivity** pattern — not a Boss Loops Provider and not the runtime itself.

Typical stack:

1. **Registry / Gateway** — discover and execute tools against operational data.
2. **Boss Loops** — govern whether operational **state** may change.
3. **Integrations** — systems of record that receive approved side effects.

→ [Commerce Gateway integration](/docs/integrations/commerce-gateway) · [Decision Governance](/docs/concepts/decision-governance)

## Runtime platform vs Boss Loops Cloud

Boss Loops can run **inside your infrastructure**, or connect to **hosted governance services** from Better Data.

### Runtime platform (OSS)

| Aspect | Description |
| --- | --- |
| **What** | Open governed operational runtime (`@loop-engine/sdk` and adapters) |
| **Where** | Local execution in your environment — processes, containers, or services you operate |
| **Primitives** | Loops, guards, actors, evidence, events, signals |
| **Direction** | Self-host first; add Providers, Channels, and Integrations via adapters |
| **Docs** | You are reading them on loopengine.io |

Install and run:

```bash
npm install @loop-engine/sdk
```

→ [Quick Start](/docs/getting-started/quick-start) · [Architecture](/docs/getting-started/architecture)

### Boss Loops Cloud (hosted)

| Aspect | Description |
| --- | --- |
| **What** | Better Data hosted **governance control plane** |
| **Where** | Multi-tenant service at [loops.betterdata.co](https://loops.betterdata.co) |
| **Adds** | Tenant isolation, connector OAuth (e.g. Slack, Google), API keys, metering, retention/compliance-oriented operations |
| **Direction** | Optional path when you want managed connectors and fleet-style operations without operating every adapter yourself |
| **Contract** | [Boss Loops Cloud HTTP API](/docs/cloud/api-reference) |

We document **what is available today** on the Cloud API page. We do not imply undelivered surfaces (Studio, docker compose runtime, multi-service mesh, or full self-host parity with Cloud) — see [Runtime Platform Direction](/docs/concepts/runtime-platform-direction) and [changelog](/docs/changelog).

## Workflows vs loops

| | Workflows (Temporal, n8n, app code) | Loops (Boss Loops) |
| --- | --- | --- |
| **Job** | Coordinate durable steps and retries | Govern **whether** a transition may commit |
| **Policy** | Often external or implicit | **Guards** in the runtime |
| **Audit** | Reconstructed from logs | **Evidence** on each transition |

→ [Boss Loops vs Workflow Engines](/docs/concepts/loop-engine-vs-workflow-engines)

## Next steps

- [Runtime Platform Direction](/docs/concepts/runtime-platform-direction) — self-host direction, roadmap-only services, forbidden claims
- [Architecture](/docs/getting-started/architecture) — how primitives compose in one system
- [Integrations](/docs/integrations) — Providers, Channels, and Integrations index
- [IntegrationAdapter archetype](/docs/concepts/integration-adapter) — developer interface map


---

## Runtime Platform Direction
URL: https://bossloops.io
/docs/concepts/runtime-platform-direction
Summary: Self-host operational runtime direction — what ships in OSS today, what Boss Loops Cloud adds, and roadmap-only extensions (constrained language).
Section: Core Concepts


Boss Loops is evolving toward a **self-host operational runtime platform**: a **local-first** stack and **operational governance substrate** you run in your infrastructure. This page states that direction honestly — what exists on npm **today**, what **Boss Loops Cloud** adds, and which components are **roadmap-only**.

→ [Runtime Taxonomy](/docs/concepts/runtime-taxonomy) · [Architecture](/docs/getting-started/architecture) · [Boss Loops Cloud API](/docs/cloud/api-reference)

## Positioning (locked)

| Phrase | Meaning |
| --- | --- |
| **Self-host runtime platform** | You operate the governance runtime (`@loop-engine/sdk`, adapters, stores) in your processes or containers |
| **Operational governance substrate** | Loops + guards + evidence sit **under** AI and workflow layers — they authorize transitions |
| **Local-first runtime stack** | Default path is install SDK, wire adapters, run in your environment — not a required multi-tenant SaaS |

We describe Boss Loops as infrastructure for **governed operational decisions**, not as a generic cloud suite or workflow marketplace.

## What you can run today (OSS)

| Capability | Status | How |
| --- | --- | --- |
| Loop definitions (YAML / TypeScript) | **Shipped** | `@loop-engine/sdk`, `@loop-engine/dsl` |
| Transition execution + guards | **Shipped** | `@loop-engine/runtime`, `@loop-engine/guards` |
| Actors, evidence, events | **Shipped** | `@loop-engine/actors`, `@loop-engine/events` |
| Provider / Channel / Integration adapters | **Shipped** (per adapter) | See [runtime connections](/docs/integrations) |
| In-process observability helpers | **Shipped** | `@loop-engine/observability`, `@loop-engine/ui-devtools` |
| Remote registry client | **Shipped** | `@loop-engine/registry-client` (`localRegistry`, `httpRegistry`, …) |

Typical **today** topology: one or more **application processes** embedding `createLoopSystem` with chosen `LoopStore` and `EventBus` adapters — not a mandatory multi-service mesh.

```bash
npm install @loop-engine/sdk
```

→ [Quick Start](/docs/getting-started/quick-start)

## Runtime platform vs Boss Loops Cloud

| | **OSS runtime (self-host)** | **Boss Loops Cloud (hosted)** |
| --- | --- | --- |
| **Runs where** | Your infrastructure | Better Data operated (`loops.betterdata.co`) |
| **Primary job** | Govern transitions in **your** apps | Hosted governance API + managed connectors |
| **Tenancy** | Your app’s isolation model | Multi-tenant control plane |
| **Connectors** | You implement OAuth/secrets | Documented hosted connector paths (Slack, Google, …) |
| **Docs surface** | **loopengine.io** (this site) | Cloud API page + **[docs.betterdata.co](https://docs.betterdata.co)** for company/apps |

**Boss Loops Cloud does not replace the OSS runtime model** — it hosts governance operations when you want managed connectors and fleet-style control. **Better Data application documentation** (SCM, CCO, company products) lives on **docs.betterdata.co**, not loopengine.io.

We do **not** claim **full self-host parity** with every Cloud connector or operator feature on day one.

## Roadmap-only extensions (not available today)

The following are **directional** components — **runtime extensions** and **governance layers**, not a sprawling separate cloud product. They may ship as optional services you run beside your app processes:

| Component | Role (when shipped) | Category |
| --- | --- | --- |
| **Registry service** | Central loop catalog resolution (versioned definitions) | Runtime extension |
| **Audit / event store** | Durable, queryable transition and guard history | Governance layer |
| **Observability collector** | Fleet-wide metrics and timelines from loop events | Operational infrastructure |
| **Replay service** | Reconstruct and analyze past transitions for audit | Governance layer |
| **Studio** | Operator UI for loop inspection (scope TBD) | Governance layer |
| **Docker Compose runtime** | Opinionated local/self-host bundle of OSS + optional services | Local-first stack |

Until each item appears in [changelog](/docs/changelog) with a released version, treat it as **planned** — do not plan production dependencies on it.

```text
Today (typical)                 Direction (optional self-host services)
─────────────────               ─────────────────────────────────────
Your app + @loop-engine/sdk  →   + registry service (roadmap)
       │                        + audit/event store (roadmap)
       ├─ adapters              + observability collector (roadmap)
       └─ your Postgres/Kafka    + replay (roadmap)
                                 + Studio (roadmap, not announced GA)
                                 + compose kit (roadmap)
```

## Language we avoid

| Do not say | Why |
| --- | --- |
| “The Supabase for AI workflows” | Implies hosted DB + auth + realtime product parity we do not ship |
| “Full self-host parity with Cloud” | Connectors and control-plane features differ by design |
| “Multi-service runtime **today**” | OSS is embeddable; mesh is roadmap-only |
| “Studio is available” | Unless changelog documents a release |
| “X for Y” competitor mimicry | e.g. “Temporal for AI”, “Zapier for governance” — obscures the governance substrate |

Prefer **concrete primitives**: loops, guards, evidence, Providers, Channels, Integrations.

## How future services should read

**Do** frame additions as:

- **Runtime extensions** — optional processes that help definitions, events, or replay
- **Governance layers** — audit, policy visibility, operator tooling
- **Operational infrastructure** — collectors and stores **you** operate

**Do not** frame as:

- A second “AI workflow cloud” unrelated to transition governance
- Mandatory microservices for every deployment
- Replacement for your existing data plane or identity system

## Choosing a path

```text
Need governed loops in your app now?
    → OSS SDK + adapters (self-host)

Need managed Slack/Google connectors + tenancy API?
    → Boss Loops Cloud (hosted Integration path)

Need company / SCM / CCO product docs?
    → docs.betterdata.co (not loopengine.io)
```

## Related

- [Architecture](/docs/getting-started/architecture) — evidence flow and boundaries
- [Runtime Taxonomy](/docs/concepts/runtime-taxonomy) — Providers, Channels, Integrations
- [Boss Loops vs Workflow Engines](/docs/concepts/loop-engine-vs-workflow-engines) — execution vs governance
- [Package taxonomy](/docs/packages) — what to install today


---

## What is a Loop?
URL: https://bossloops.io
/docs/concepts/what-is-a-loop
Summary: A loop tracks operational outcomes with named states, attributed actors, and structured feedback - not task completion.
Section: Core Concepts


A **loop** is a **governed decision cycle** in the [runtime taxonomy](/docs/concepts/runtime-taxonomy). This page explains the loop as a product unit; finite states are the mechanism underneath.

## The problem

Enterprise AI systems fail when actions are not bounded by explicit state, policy, and traceability.  
Boss Loops provides finite states, deterministic transition checks, and event traces that make decisions auditable.

## Workflow vs. State Machine vs. Decision Loop

When designing operational processes, mixing up execution pipelines with governance models leads to brittle systems and decisions that cannot be defended later.

| Dimension | Workflow Engine (e.g. Temporal, n8n) | Finite State Machine (pattern) | Boss Loops (Decision Loop) |
|---|---|---|---|
| Primary focus | Tasks & execution — orchestrating sequences, API calls, data pipelines | Status & transitions — ensuring an entity moves legally between named states | Governance & evidence — proving why a transition was authorized |
| Progression | Linear / forward-moving pipelines | Cyclical, event-driven, multi-directional | Cyclical execution with strict policy and authority guardrails |
| Core unit | The task (what runs next?) | The state (where are we right now?) | The Decision Record (what is the immutable proof?) |
| Triggers | Completion of the previous programmatic step | External raw events or inputs | Signals paired with runtime evidence evaluation |
| Handling rejection | Complex error branching or manual exception code | State reset (e.g. back to draft) | Attributed rejections, guard failures, and historical loop resets |

**One-liner:** Workflow engines excel at sequential execution; state machines excel at status, events, and legal transitions; Boss Loops uses state-machine enforcement to govern decisions with durable evidence — and composes with workflow engines for everything that runs after approval.

### Reclaim approval chains from workflows

Traditional guides classify document approvals as workflows. Boss Loops treats them as state-driven decisions. A sequential pipeline treats approval as another API step; an auditor asking why a $10M invoice was paid needs more than step completion logs.

In Boss Loops, the invoice sits in `PENDING_APPROVAL` protected by active guards. It cannot transition to `APPROVED` without the required C10 authority and a frozen snapshot of the evidence as it was seen at that moment.

### Active governance, not passive status

Generic explainers describe state machines as passive — waiting for external events. Boss Loops is an active gatekeeper: while it waits for signals (temperature excursion, invoice over threshold), invariant enforcement and authority configuration deny illegal transitions — for example `COMMIT_AUTHORITY_NOT_CONFIGURED`.

### Composition, not replacement

Boss Loops does not replace your workflow engine. It governs the commit; the workflow engine executes the approved work.

```text
Signal → Boss Loops (govern decision) → transition approved → Workflow engine (execute sequential APIs)
```

Example: AI drafts a proposal → Boss Loops governs draft → approved → Salesforce or Temporal runs the downstream pipeline. See [Workflow + Boss Loops](/docs/examples/workflow-plus-loop).

:::note Alpine supplier invoice
While naive tooling models invoice approvals as sequential workflows, the [Alpine demo](https://demo.bossloops.io) treats invoices as an FSM pattern — reset, exception handling, and strict state-based guardrails that a linear pipeline cannot enforce without brittle branching.
:::

## Anatomy of a loop (`LoopDefinition`)

- `id: LoopId`
- `version: string`
- `description: string`
- `domain: string`
- `states: StateSpec[]`
- `initialState: StateId`
- `transitions: TransitionSpec[]`
- `outcome: OutcomeSpec`
- `participants?: string[]`
- `spawnableLoops?: LoopId[]`
- `metadata?: Record<string, unknown>`

Use optional fields (`participants`, `spawnableLoops`, `metadata`) only when needed by your platform model.

## Lifecycle (`LoopStatus`)

`LoopStatus` values: `pending | active | completed | failed | cancelled | suspended`.

```text
pending -> active -> completed
pending -> active -> failed
pending -> active -> cancelled
```

User-defined state IDs (like `OPEN`, `PO_CONFIRMED`, `SETTLED` below) are independent of `LoopStatus` — `LoopStatus` tracks the lifecycle of the instance itself, while state IDs track position within a specific loop definition.

## Real example (abbreviated from `loops/scm/procurement.yaml`)

```yaml
id: scm.procurement
version: 1.0.0
domain: scm
description: Purchase order lifecycle from requisition through settlement
states:
  - id: OPEN
  - id: PO_CONFIRMED
  - id: RECEIVED
  - id: INVOICE_MATCHED
  - id: SETTLED
    isTerminal: true
initialState: OPEN
transitions:
  - id: confirm_po
    from: OPEN
    to: PO_CONFIRMED
    allowedActors: [human, automation, ai-agent]
    guards:
      - id: approval_obtained
        severity: hard
        evaluatedBy: external
        description: PO must be approved before confirmation
        failureMessage: PO confirmation requires explicit approval
outcome:
  id: po_settled
  description: Purchase order fully settled
  valueUnit: po_settled
  measurable: true
```

## Related

- [Decision Governance](/docs/concepts/decision-governance)
- [When to Use Boss Loops](/docs/concepts/when-to-use)
- [Boss Loops vs workflow engines](/docs/concepts/loop-engine-vs-workflow-engines)


---

## IntegrationAdapter Archetype
URL: https://bossloops.io
/docs/concepts/integration-adapter
Summary: A package that implements a pluggable runtime interface and slots into LoopEngineOptions. Four canonical archetypes — Store, Registry, AI, EventBus.
Section: Core Concepts


<Callout variant="info" title="Buyer-facing taxonomy">
Public docs use [Runtime Taxonomy](/docs/concepts/runtime-taxonomy) terms — **Providers**, **Channels**, and **Integrations**. This page maps **developer** adapter archetypes (`Store`, `Registry`, `AI`, `EventBus`) to those surfaces.
</Callout>

## Public taxonomy ↔ developer adapters

Developer terminology remains valid in code and package APIs. Public taxonomy sits **above** these types:

| Public (loopengine.io) | Developer type / archetype | Typical npm surface |
| --- | --- | --- |
| **Provider** | `ActorAdapter` — `createSubmission(...)` → governed AI transition | `@loop-engine/adapter-anthropic`, `adapter-openai`, … |
| **Provider** (research step) | `ToolAdapter` — `invoke(...)` for grounded retrieval | `@loop-engine/adapter-perplexity` |
| **Channel** | Human-surface routing on `EventBus` / approval delivery | `@loop-engine/adapter-openclaw` (Slack/Teams via [Boss Loops Cloud](/docs/cloud/api-reference)) |
| **Integration** | `IntegrationAdapter` archetypes — `LoopStore`, `LoopRegistry`, `EventBus`, operational connectors | `adapter-postgres`, `adapter-kafka`, `adapter-pagerduty`, `adapter-commerce-gateway`, … |

Browse the [runtime connections index](/docs/integrations) — each page is listed under **exactly one** public category. Package selection by role: [Package taxonomy](/docs/packages).

## What is an IntegrationAdapter?

An **IntegrationAdapter** is a package that implements one of Boss Loops' pluggable interfaces and slots into `LoopEngineOptions` (or the matching registry-client option). Every adapter preserves the same governance model — guards enforced, actors attributed, audit trail intact — and is swappable without changing loop definitions or business logic.

At rc.0 there are four canonical archetypes. All four share the same shape:

1. An **interface contract** exported from a runtime package.
2. An **options slot** on `LoopEngineOptions` (or `createLoopSystem` options) that accepts an implementation of that interface.
3. One or more **shipped adapters** that fulfill the interface.
4. A **"build your own"** path if the shipped adapters don't cover your backend.

```ts
interface LoopEngineOptions {
  registry: LoopRegistry   // Registry archetype
  store: LoopStore         // Store archetype
  eventBus?: EventBus      // EventBus archetype
  guardEvaluator?: GuardEvaluator
  clock?: () => string
}
```

The AI archetype sits slightly outside this shape — AI adapters are invoked from transition execution paths rather than slotted into `LoopEngineOptions` directly — but follows the same "interface + shipped implementations + build-your-own" pattern.

## The four archetypes

### Store adapter

| | |
|---|---|
| Interface | `LoopStore` from `@loop-engine/runtime` |
| Slot | `options.store` |
| Shipped | `memoryStore()` from `@loop-engine/adapter-memory`; PlanetScale store from `betterdata-loops` (proprietary) |
| Docs | [`@loop-engine/adapter-memory`](/docs/packages/adapter-memory) · [In-Memory integration](/docs/integrations/memory) · [Postgres integration](/docs/integrations/postgres) |

Store adapters persist loop instances and transition history. Swap backends without changing loop definitions.

### Registry adapter

| | |
|---|---|
| Interface | `LoopRegistry` from `@loop-engine/registry-client` |
| Slot | `options.registry` |
| Shipped | `localRegistry`, `httpRegistry`, `betterDataRegistry` (from `@loop-engine/registry-client` and its `/betterdata` subpath) |
| Docs | [`@loop-engine/registry-client`](/docs/packages/registry-client) |

Registry adapters load `LoopDefinition` objects. Use `localRegistry` for in-process registration, `httpRegistry` for remote JSON catalogs, or `betterDataRegistry` for the Better Data catalog API.

### AI / LLM adapter

| | |
|---|---|
| Interface | LLM-step contract — `AIActorAdapter.createSubmission(...)` returning `{ actor: AIAgentActor, decision: AIActorDecision }`; tool adapters implement `ToolAdapter.invoke(...)` |
| Slot | Invoked from transition execution paths (not a `LoopEngineOptions` field) |
| Shipped | `@loop-engine/adapter-anthropic`, `@loop-engine/adapter-openai`, `@loop-engine/adapter-gemini`, `@loop-engine/adapter-grok`, `@loop-engine/adapter-perplexity` (tool/retrieval) |
| Docs | [AI as Actor](/docs/ai-and-automation/ai-as-actor) · [`createAIActor`](/docs/packages/sdk#createaiactor) · per-provider integration pages |

Actor adapters return a structured decision that the runtime submits through `engine.transition(...)`. Guards evaluate after submission — an AI actor cannot bypass policy.

### EventBus adapter

| | |
|---|---|
| Interface | `EventBus` from `@loop-engine/runtime` |
| Slot | `options.eventBus` |
| Shipped | `InMemoryEventBus` from `@loop-engine/events`; `OpenClawEventBus` from `@loop-engine/adapter-openclaw`; Kafka adapter (`@loop-engine/adapter-kafka`) |
| Docs | [Event subscriptions](/docs/running-loops/event-subscriptions) · [Events package](/docs/packages/events) |

EventBus adapters route lifecycle events (`loop.started`, `loop.transition.executed`, `loop.completed`, ...) to downstream consumers. The in-memory bus is the default; swap it for Kafka, OpenClaw, or a custom sink.

## Choosing between adapters

| Situation | Store | Registry | EventBus |
|---|---|---|---|
| Local dev, tests | `memoryStore()` | `localRegistry` | `InMemoryEventBus` (default) |
| Single-service prod | `PostgresAdapter` | `localRegistry` (definitions in code) | `InMemoryEventBus` or Kafka |
| Multi-service catalog | `PostgresAdapter` | `httpRegistry` or `betterDataRegistry` | Kafka or OpenClaw |
| Audit streaming | — | — | Kafka, OpenClaw |

For AI adapters, switch on the provider API you have access to and whether you need tool-style grounding (Perplexity) or open-ended reasoning (Anthropic/OpenAI/Gemini/Grok).

## Cross-archetype patterns

- **Zero-config dev**: `memoryStore()` + `localRegistry` + default `InMemoryEventBus` — no persistence, no network, fast feedback loop.
- **Production single-service**: Postgres store + local registry + Kafka event bus — durable state, definitions live in code, events stream to analytics.
- **Multi-tenant catalog**: Postgres store + `betterDataRegistry` + Kafka — definitions centrally managed, per-tenant loops, events replayable.
- **Governed AI workflow**: any Store + any Registry + any AI adapter + Kafka or OpenClaw EventBus — AI decisions become governed transitions with full audit trail.

## Build your own

Each archetype's interface is documented as the single-point-of-truth contract:

- [`LoopStore` interface](/docs/running-loops/adapters#loopstore-interface)
- [`LoopRegistry` and shipped registries](/docs/packages/registry-client)
- [`EventBus` and event subscription model](/docs/running-loops/event-subscriptions)
- AI actor adapter shape — see any of the provider integration pages; the per-provider `createXActorAdapter(...)` + `createSubmission(...)` contract is uniform across Anthropic, OpenAI, Gemini, and Grok.

Implement the interface, pass your implementation into `createLoopSystem` or construct a `LoopEngine` directly with `createLoopEngine`.

## Related

- [Adapters reference](/docs/running-loops/adapters) — interface signatures with code examples
- [Runtime connections index](/docs/integrations) — every shipped connection, grouped by Providers / Channels / Integrations
- [`createLoopSystem`](/docs/running-loops/create-loop-system) — the factory that wires options into a running engine


---

## Actor Model
URL: https://bossloops.io
/docs/concepts/actor-model
Summary: Human, automation, and AI actors are first-class in Boss Loops - every transition is attributed and every action leaves evidence.
Section: Core Concepts


## Why actors matter

Every transition is attributed to an actor in the transition record and emitted events.  
Nothing executes anonymously.

## Actor types

### `human`

Use when a person executes a transition.

```ts
const actor = { type: 'human', id: actorId('drew@acme.com'), sessionId: 'sess_abc' }
```

### `automation`

Use for jobs, integrations, and rule engines.

```ts
const actor = { type: 'automation', id: actorId('system:po-router'), serviceId: 'po-service' }
```

### `ai-agent`

Use for model-driven recommendations or execution.

```ts
const actor = {
  type: 'ai-agent',
  id: actorId('agent:forecaster'),
  agentId: 'claude-3-5-sonnet',
  gatewaySessionId: 'gw_123'
}
```

### `system`

Use for internal runtime/platform initiated actions.

```ts
const actor = { type: 'system', id: actorId('system:loop-engine') }
```

## Actor evidence

Use `buildActorEvidence(actor, baseEvidence)` to normalize actor-attributed evidence.

For all actors, the helper adds:

- `actor_type`
- `actor_id`

For `ai-agent`, it also adds:

- `ai_agent_id`
- optional `ai_confidence` and `ai_reasoning` (when present in base evidence)

## Authorization checks

`canActorExecuteTransition(actor, transition, constraints?)` returns:

```ts
{ authorized: boolean; requiresApproval: boolean; reason?: string }
```

```ts
import { canActorExecuteTransition } from '@loop-engine/actors'

const auth = canActorExecuteTransition(actor, transition)
if (!auth.authorized) {
  console.log(auth.reason)
}
```

<Callout variant="important" title="AI actor rule">
Do not make `ai-agent` the only allowed actor on a critical transition.
Include `human` or `automation` as a fallback execution path.
</Callout>

## Related

- [AI as Actor](/docs/ai-and-automation/ai-as-actor)
- [Agents and RAG](/docs/concepts/agents-and-rag)


---

## Guards and Policy
URL: https://bossloops.io
/docs/concepts/guards-and-policy
Summary: Guards are deterministic policy checks that run before a transition executes - hard guards block, soft guards warn.
Section: Core Concepts


## What guards are

Guards are deterministic policy checks evaluated before state advancement.  
In this runtime, a guard is a `GuardFunction` returning `{ passed, code?, message?, metadata? }`.

## Hard vs soft

| | Hard | Soft |
|---|---|---|
| Blocks transition | Yes | No |
| State advances | No | Yes |
| Emitted event on failure | `loop.guard.failed` | Failure warning is attached to `_softGuardWarnings` evidence |
| Typical use | Mandatory policy | Warning and monitoring |

## `evaluatedBy`

`GuardSpec.evaluatedBy`:

- `runtime` - evaluated by registered `GuardFunction`
- `module` - declared for module-level policy contract
- `external` - caller provides result context in evidence contract

## Built-in guards

### `actor_has_permission`

- Reads: `required_role`, `roles`
- Fails when `required_role` is missing from `roles`

### `approval_obtained`

- Reads: `approved`
- Fails when `approved !== true`

### `deadline_not_exceeded`

- Reads: `deadline_iso`
- Fails when deadline format is invalid or current time exceeds deadline

### `duplicate_check_passed`

- Reads: `duplicate_found`
- Fails when `duplicate_found === true`

### `field_value_constraint`

- Reads: `constraint` plus referenced field
- Supported operators: `eq`, `gt`, `lt`, `in`

## Add a custom guard

```ts
// @no-typecheck
import { guardId } from '@loop-engine/core'
import { createGuardRegistry } from '@loop-engine/guards'

const registry = createGuardRegistry()
registry.register(guardId('my_custom_guard'), async (context) => {
  const passed = context.evidence.budget_available === true
  return {
    passed,
    message: passed ? 'Budget available' : 'Insufficient budget'
  }
})
```

Use this registry in `createLoopSystem({ loops, guards: registry })`.

## Related

- [Decision Governance](/docs/concepts/decision-governance)
- [Human Approval Gates](/docs/ai-and-automation/human-approval-gates)


---

## Signals
URL: https://bossloops.io
/docs/concepts/signals
Summary: Signals detect meaningful patterns in loop events and trigger governed workflows when configured conditions match.
Section: Core Concepts


## What signals are

Signals are detected patterns derived from loop events.  
A `SignalRule` evaluates event streams and returns a detection result when matched.

## `SignalRule` anatomy

```ts
interface SignalRule {
  id: string
  name: string
  description: string
  targetLoopId?: LoopId
  evaluate: (events: LoopEvent[]) => SignalDetectionResult | null
}
```

## Built-in signal rules

### `threshold-breach`

- Signal type: `THRESHOLD_BREACH`
- Detects numeric evidence crossing configured threshold
- Config: `field`, `operator`, `threshold`

### `state-dwell`

- Signal type: `STATE_DWELL_EXCEEDED`
- Detects prolonged dwell in a target state
- Config: `state`, `maxDwellMinutes`

### `repeated-guard-failure`

- Signal type: `GUARD_FAILURE_PATTERN`
- Detects repeated `loop.guard.failed` events for one guard ID
- Config: `guardId`, `maxFailures`

### `loop-not-started`

- Signal type: `LOOP_TRIGGER_DELAYED`
- Detects when a signal is received but no loop started in time window
- Config: `maxDelayMinutes`

## Create a signal engine

```ts
// @no-typecheck
// SR-024 will replace this block with the published `SignalRegistry` + event-bus flow. F-38 marker: legacy actor fields in related pages.
import { createSignalEngine } from '@loop-engine/sdk'

const signals = createSignalEngine()
signals.subscribe((signal) => {
  console.log(signal.type, signal.subject, signal.confidence)
})
```

## Connect signal detection to loop creation

```ts
// @no-typecheck
signals.subscribe(async (signal) => {
  if (signal.type !== 'THRESHOLD_BREACH') return
  await engine.start({
    loopId: 'scm.replenishment',
    aggregateId: aggregateId(`repl-${Date.now()}`),
    actor: { type: 'system', id: 'system:signal-router' },
    metadata: { triggeredBy: signal.id, source: 'signal-router' }
  })
})
```


---

## Observability
URL: https://bossloops.io
/docs/concepts/observability
Summary: Boss Loops observability surfaces metrics, timelines, and replay diagnostics from runtime state and history.
Section: Core Concepts


## What Boss Loops tracks

Runtime state comes from:

- `LoopInstance` records (`currentState`, `status`, timestamps)
- `TransitionRecord[]` history (who did what, when, and with what evidence)

The observability package computes aggregate metrics and timelines from that data.

## `LoopMetrics`

`computeMetrics(instances, history, period)` returns:

- `loopId`
- `period`
- `totalInstances`
- `openInstances`
- `closedInstances`
- `errorInstances`
- `avgDurationMs`
- `medianDurationMs`
- `p95DurationMs`
- `completionRate`
- `guardFailureRate`
- `aiActorRate`
- `humanActorRate`
- `avgTransitionCount`

```ts
import { computeMetrics } from '@loop-engine/observability'
```

## Timelines and state residency

Use `buildTimeline(instance, history)` for a normalized timeline view.

Use `getStateResidency(timeline)` to see dwell per state:

```ts
// @no-typecheck
import { buildTimeline, getStateResidency } from '@loop-engine/observability'

const timeline = buildTimeline(instance, history)
const residency = getStateResidency(timeline)
```

State residency highlights bottlenecks (for example loops spending excessive time in `OPEN` or `INVOICE_MATCHED`).

## Replay and validation

`replayLoop(definition, history)` validates transition history against a definition:

```ts
// @no-typecheck
import { replayLoop } from '@loop-engine/observability'

const replay = replayLoop(definition, history)
if (!replay.valid) {
  console.error(replay.errors)
}
```

Use replay for:

- audits
- debugging invalid transitions
- migration validation after definition updates

## Devtools

`@loop-engine/ui-devtools` exports components for local diagnostics:

- `DevtoolsPanel`
- `LoopTimeline`
- `EventStream`
- `StateDiagram`
- `MetricsCard`


---

## Learning Signals
URL: https://bossloops.io
/docs/concepts/learning-signals
Summary: Learning signals capture predicted-versus-actual outcomes so loop performance can improve over time.
Section: Core Concepts


## What learning signals are

`LearningSignal` captures predicted vs actual outcome data at loop completion boundaries.
It is produced by `extractLearningSignal()` in `@loop-engine/events`.

## `LearningSignal` fields

- `loopId`
- `aggregateId`
- `outcomeId`
- `predicted: Record<string, unknown>`
- `actual: Record<string, unknown>`
- `delta: Record<string, number>`
- `occurredAt`
- `confidence?`

## `extractLearningSignal` signature

```ts
extractLearningSignal(
  completed: LoopCompletedEvent,
  history: TransitionRecord[],
  predicted?: Record<string, unknown>
): LearningSignal
```

Current implementation behavior:

- derives `actual.cycle_time_days` from completion time minus first history timestamp
- computes numeric deltas where both `predicted[key]` and `actual[key]` are numbers
- returns empty `delta` when keys do not numerically align

## Business metrics

`BusinessMetric` (from `@loop-engine/core`):

- `id`
- `label`
- `unit`
- `improvableByAI`

Example metrics from `loops/scm/procurement.yaml`:

- `cycle_time_days`
- `three_way_match_first_attempt`
- `supplier_lead_time_accuracy`

Marking `improvableByAI: true` identifies metrics appropriate for model optimization loops.

## Feedback cycle

```text
Loop completes
  -> extractLearningSignal()
  -> store signal in training dataset
  -> retrain/tune model
  -> deploy improved agent behavior
  -> faster, safer loop completion
```


---

## AI as Actor
URL: https://bossloops.io
/docs/ai-and-automation/ai-as-actor
Summary: AI is one actor among several in Boss Loops - it can recommend and execute transitions within defined bounds, never outside them.
Section: Core Concepts


## AI as an actor, not the controller

Boss Loops treats AI the same way it treats humans and automation: as an attributed actor constrained by transitions and guards.

## What AI can do

- inspect loop state in your application layer
- recommend transitions with evidence
- execute transitions where `allowedActors` includes `ai-agent`

## What AI cannot do

- bypass `allowedActors`
- bypass hard guards
- modify loop definitions at runtime
- execute indefinitely if circuit-breaker constraints block it

## `AIAgentActor` shape

```ts
interface AIAgentActor extends ActorRef {
  type: "ai-agent"
  agentId: string
  gatewaySessionId: string
  recommendedBy?: string
}
```

## AI submission flow

```ts
// @no-typecheck
// F-38: canonical `AIAgentActor` + submission types are being realigned in SR-024; this block stays illustrative.
import { actorId, transitionId } from '@loop-engine/core'
import { canActorExecuteTransition, buildActorEvidence, type AIAgentActor } from '@loop-engine/actors'

const agent: AIAgentActor = {
  type: 'ai-agent',
  id: actorId('agent:demand-forecaster'),
  agentId: 'claude-3-5-sonnet',
  gatewaySessionId: session.id
}

const auth = canActorExecuteTransition(agent, transition)
if (auth.authorized) {
  const evidence = buildActorEvidence(agent, {
    ai_confidence: 0.94,
    ai_reasoning: 'Stock level below reorder point; lead time elevated',
    recommended_qty: 500
  })

  await engine.transition({
    aggregateId,
    transitionId: transitionId('trigger_po'),
    actor: { type: agent.type, id: String(agent.id) },
    evidence
  })
}
```

## Provider implementations

The actor contract stays constant across providers. Only SDK wiring changes.

```ts
// Anthropic path (Claude)
const claudeActor: AIAgentActor = {
  type: "ai-agent",
  id: actorId("agent:demand-forecaster"),
  agentId: "claude-sonnet-4-20250514",
  gatewaySessionId: "claude-session-123"
}

// OpenAI path (GPT-4o)
const openAiActor: AIAgentActor = {
  type: "ai-agent",
  id: actorId("agent:demand-forecaster"),
  agentId: "gpt-4o",
  gatewaySessionId: "openai-session-123"
}
```

Anthropic and OpenAI both submit through the same transition path and evidence schema:

- `ai_confidence`
- `ai_reasoning`
- `recommended_action`
- `recommended_qty`

## Safety constraints

- Confidence `0.58` on `recommend_replenishment` returns `guard_failed` and holds state at `AI_ANALYSIS`.
- Confidence `0.82` passes `confidence_threshold` and advances to `PENDING_BUYER_APPROVAL`.
- AI attempts on `approve_replenishment` are rejected when transition `allowedActors` is `["human"]`.

## Deep-dive example

The full dual-provider walkthrough is in `/docs/examples/ai-replenishment`, with source links for both provider adapters:

- [Anthropic actor example](https://github.com/loopengine/loop-examples/tree/main/ai-actors/claude)
- [OpenAI actor example](https://github.com/loopengine/loop-examples/tree/main/ai-actors/openai)

## Available AI adapters

| Package | Models |
|---|---|
| [`@loop-engine/adapter-anthropic`](/docs/packages/adapter-anthropic) | Claude (`claude-opus-4-6`, `claude-sonnet-4-6`) |
| [`@loop-engine/adapter-openai`](/docs/packages/adapter-openai) | OpenAI (`gpt-4o`, o-series) |
| [`@loop-engine/adapter-grok`](/docs/packages/adapter-grok) | Grok (`grok-3`, `grok-2`) via xAI |
| [`@loop-engine/adapter-gemini`](/docs/packages/adapter-gemini) | Gemini (`gemini-1.5-pro`, `gemini-2.0-flash`) |
| [`@loop-engine/adapter-perplexity`](/docs/packages/adapter-perplexity) | Perplexity Sonar (`sonar`, `sonar-pro`, …) — `ToolAdapter` with citations for research steps |

The Perplexity package implements `ToolAdapter.invoke()` (text + citations), not the actor `createSubmission` flow. Use it where you need grounded retrieval inside a loop; use the actor adapters above for structured signal decisions.

## Related

- [Agents and RAG](/docs/concepts/agents-and-rag)
- [Decision Governance](/docs/concepts/decision-governance)
- [@loop-engine/adapter-grok](/docs/packages/adapter-grok)
- [@loop-engine/adapter-gemini](/docs/packages/adapter-gemini)
- [@loop-engine/adapter-perplexity](/docs/packages/adapter-perplexity)


---

## Confidence and Evidence
URL: https://bossloops.io
/docs/ai-and-automation/confidence-evidence
Summary: Evidence captures why actions happened, and confidence values power explicit policy thresholds for AI-driven transitions.
Section: Core Concepts


## Why evidence matters

Evidence is persisted in every `TransitionRecord`.  
For AI actions, evidence is the audit answer to: _why was this recommendation accepted?_.

## `buildActorEvidence()`

From `@loop-engine/actors`:

```ts
buildActorEvidence(actor: Actor, baseEvidence: Evidence): Evidence
```

For all actor types, it merges:

- `actor_type`
- `actor_id`

For `ai-agent`, it also merges:

- `ai_agent_id`
- `ai_confidence` (if present in base evidence)
- `ai_reasoning` (if present in base evidence)

## Confidence policy

Boss Loops stores confidence but does not enforce policy thresholds itself.  
Implement thresholds in your app layer:

- `>= 0.90`: can auto-execute when authorized
- `0.70 - 0.89`: execute with review workflow
- `< 0.70`: recommend only, require human gate

## Reasoning best practices

- include concrete numeric drivers
- include threshold context
- keep concise for audit readability

Good:

```text
Stock 18% below reorder point (82 units). Lead time 12d. Trigger threshold: 95 units.
```

## Reading AI evidence from history

```ts
const history = await engine.getHistory(aggregateId)

for (const row of history) {
  if (row.actor.type !== 'ai-agent') continue
  console.log(row.evidence.ai_confidence, row.evidence.ai_reasoning)
}
```


---

## Human Approval Gates
URL: https://bossloops.io
/docs/ai-and-automation/human-approval-gates
Summary: Human approval gates keep high-impact actions controlled by policy and runtime authorization, not prompt wording.
Section: Core Concepts


## When to require human approval

Use human gates for:

- high-value financial commitments
- irreversible actions
- regulated or compliance-heavy decisions

## Pattern A: exclude `ai-agent` from `allowedActors`

```yaml
- id: settle_invoice
  from: MATCHED
  to: SETTLED
  allowedActors: [human, automation]
```

If an AI actor attempts this transition, authorization returns `requiresApproval: true`.

## Pattern B: AI constraints in authorization

`AIActorConstraints` in `@loop-engine/actors`:

```ts
interface AIActorConstraints {
  requiresHumanApprovalFor?: TransitionId[]
}
```

When an `ai-agent` actor attempts a transition whose ID appears in `requiresHumanApprovalFor`, `canActorExecuteTransition()` returns unauthorized with `requiresApproval: true`.

## Pending approval sequence

```ts
const aiAuth = canActorExecuteTransition(aiActor, transition, constraints)
if (!aiAuth.authorized && aiAuth.requiresApproval) {
  // Create human review task using ai evidence
}

// Later, human executes same transition:
await engine.transition({
  aggregateId,
  transitionId,
  actor: { type: 'human', id: 'approver@acme.com' },
  evidence: { approved: true, approval_ticket: 'APR-123' }
})
```

<Callout variant="important" title="Per-transition gating only">
`AIActorConstraints` ships with a single field, `requiresHumanApprovalFor`. Boss Loops does not provide a built-in consecutive-AI-transition circuit breaker. Track that policy in your application and translate it into per-transition entries on this list (or into `allowedActors` exclusions).
</Callout>


---

## Decision Governance
URL: https://bossloops.io
/docs/concepts/decision-governance
Summary: Why governed decision loops exist - the problem Boss Loops solves that workflow engines and agent frameworks leave open.
Section: Core Concepts


## The Problem

In modern enterprise systems, AI agents retrieve context, reason over it, and recommend or execute actions. This works well in development.

In production, three requirements emerge that most stacks do not address:

- Decisions must be attributable - who or what made each decision, and why
- Policies must be enforced at the runtime level, not in prompts
- Audit trails must be reconstructable - not reassembled from scattered logs

Without an explicit governance layer, teams discover that decision trails are spread across prompt logs, API traces, application logs, and database records. Reconstructing the reasoning behind a decision after the fact is fragile.

## What Boss Loops Adds

Boss Loops sits between AI reasoning and operational execution. Its job is to govern the decision lifecycle.

```text
Enterprise Knowledge Sources
          ↓
RAG / Agent Reasoning Layer
          ↓
Boss Loops - Decision Governance
          ↓
Workflow / Execution Systems
```

Every transition through a loop:

- Names the actor responsible (human, automation, or AI agent)
- Evaluates guard policies before allowing the transition
- Attaches evidence - what information the actor used
- Emits a structured event with full attribution

This creates a decision record at runtime, not a best-effort reconstruction later.

## What This Is Not

Boss Loops is not a workflow engine. It does not schedule jobs, manage retries, or handle durable execution. Systems like Temporal or Prefect own those concerns.

Boss Loops is not an agent framework. It does not orchestrate tool calls or manage model context. LangGraph, OpenAI Assistants, and your own agent runtime own that layer.

Boss Loops governs the boundary between reasoning and action. It enforces who can do what, under what conditions, with what evidence.

## How the governance weighting works

Boss Loops uses three types of weighting in sequence — all must pass for a transition to execute.

1. **Confidence threshold (numeric gate)**  
   Every AI actor submission carries a `0–1` confidence score. The guard blocks the transition if the score falls below the configured threshold. In the fraud review example, `0.60` triggers escalation to human review and `0.80` allows auto-dismiss — two thresholds, two different outcomes from the same loop state.

2. **Guard priority (hard vs soft)**  
   Guards have a failure mode: `hard` or `soft`. Hard failures block the transition regardless of everything else. Soft failures warn and continue. A human-only guard on an approval transition is an absolute block — no confidence score overrides it. This is intentional: policy is enforced at the runtime level, not in prompts.

3. **Evidence completeness (structural gate)**  
   The evidence-required guard checks for the presence of specific fields before allowing a transition. The infrastructure change example requires `blast_radius_score`, `affected_services`, and `rollback_plan` — missing any one field blocks the transition. This ensures AI actors cannot submit incomplete reasoning.

### Evaluation order

1. Actor authorized for this signal?
2. Required evidence fields present?
3. Confidence score above threshold?
4. All hard guards pass?

Any failure stops the sequence. The transition only executes when all checks pass.

The key design principle is compositional governance. You stack guards, each with its own failure mode and parameters. Simple loops use one or two. Complex regulated workflows use four or five.

## Related

- [Boss Loops vs Workflow Engines](/docs/concepts/loop-engine-vs-workflow-engines)
- [Agents and RAG](/docs/concepts/agents-and-rag)
- [Guards and Policy](/docs/concepts/guards-and-policy)
- [Learning Signals](/docs/concepts/learning-signals)


---

## Evidence Providers
URL: https://bossloops.io
/docs/concepts/evidence-providers
Summary: How Looker, Snowflake, and Samsara attach governed evidence to the Decision Record — frozen at capture, with qualification inherited from the source.
Section: Core Concepts


## What an Evidence Provider is

An **Evidence Provider** attaches governed evidence to a Decision Record. It is
not a Model Provider (it supplies no intelligence) and not an Integration (it
executes no side effects). It supplies one thing: **what was true, from a
governed source, at the moment it informed the decision** — frozen into an
immutable snapshot the record carries forever.

Two archetypes:

```
Semantic evidence     →  governed definitions from your warehouse and BI stack
                          (e.g. Snowflake semantic views, Looker explores)
Operational evidence  →  live readings from fleet and field systems
                          (e.g. Samsara telemetry at decision time)
```

Three properties make this different from linking to a dashboard:

- **Frozen at capture.** The Decision Record holds the value, definition,
  source, and timestamp as they were when the decision was made — not a link
  that may have changed since. The vendor UI remains an optional live surface;
  the record is the frozen one.
- **Qualification is inherited, never asserted.** How governed a definition is,
  how attestable its provenance, how fresh the reading — these come from the
  source's own mapping, not from whoever built the loop.
- **Conformance is verifiable.** The provider contract and conformance suite
  live in Boss Loops OSS, so "every evidence source in this decision conformed
  to the contract" is a statement an auditor can check — not a marketing claim.

## Status legend

| Badge | Meaning |
|---|---|
| **Preview** | A fixture/seed illustrates the architecture on the demo Decision Record; not a live vendor connection |
| **Contract-validated** | The evidence shape passes the OSS contract exemplars and conformance checks |
| **Conformant Provider** | Future — a production adapter that passes the public OSS conformance suite |
| **Boss Loops Cloud** | Future hosted connector path, managed auth included |

## Looker — semantic evidence (Preview)

Approvers see a number in Slack; nobody remembers which Explore, which band,
as of when. With Looker as an Evidence Provider, the **certified metric
definition** travels with the decision: the demo Alpine invoice record carries
vendor spend vs. a 12-month band as a preview snapshot — definition, value, and
qualification frozen on the record.

**Today:** preview snapshot on the Alpine demo Decision Record. It
illustrates qualification inherited from the provider — not asserted by the
loop. There is no live Looker API connection yet.

**Next:** a live connector with LookML mapping, an optional rendered tile, and
two-clock freshness (when the value was bound vs. when it was observed).

## Snowflake — semantic evidence (Planned)

Warehouse truth exists; decisions happen in email with screenshots and stale
exports. With Snowflake as an Evidence Provider, **governed semantic views**
become Evidence Snapshots with lineage and qualification.

**Today:** the evidence shape is contract-validated in Boss Loops OSS
(governed semantic metric exemplar); a reference JSON provider exercises it.
There is no live warehouse connection on the demo.

**Next:** a production semantic provider for semantic views and governed
metrics. Ad-hoc SQL stays unreviewed — it must not map to governed. We document
the governed path first.

## Samsara — operational evidence (Planned)

Operational decisions need what was true on the ground — not a dashboard
someone refreshed later. With Samsara as an Evidence Provider, **telemetry is
captured at decision time**, with provenance up to origin-attested where
hardware and process support it.

**Today:** the evidence shapes are contract-validated in Boss Loops OSS
(telemetry and origin-attested exemplars). There is no live fleet connection on
the demo. Operational evidence is captured, not streamed as a live widget on
the record.

**Next:** a production operational provider with real-time freshness and
origin attestation where warranted.

## Where the line sits (OSS vs. hosted)

The **contract, reference providers, and conformance suite are open** in
Boss Loops OSS — you can validate an evidence shape and verify the invariants
yourself. **Production adapters** (managed auth, live vendor connections, full
qualification presentation) ship in the hosted tier. Consuming your existing
semantics — not re-modeling them — is the point: Boss Loops opens what Looker,
Snowflake, and Samsara already govern; it does not replace them.


---

## Boss Loops vs Workflow Engines
URL: https://bossloops.io
/docs/concepts/loop-engine-vs-workflow-engines
Summary: How Boss Loops and workflow engines like Temporal complement each other - execution vs decision governance.
Section: Core Concepts


## Two Different Problems

Workflow engines like Temporal solve durable execution: retries, timers, distributed coordination, and fault tolerance.

Boss Loops solves decision governance: actor authorization, policy enforcement, evidence capture, and decision audit trail.

These are different problems. Both can exist in the same system.

## Temporal's Responsibilities

- Durable workflow execution
- Activity retries with backoff
- Long-running process coordination
- Saga pattern and distributed transactions
- Timer and scheduling primitives

## Boss Loops' Responsibilities

- Defining who can trigger each transition
- Enforcing guard policies before allowing state changes
- Capturing evidence attached to each decision
- Attributing every action to a named actor
- Emitting structured events for audit and learning

## When to Use Each

Use Temporal when: you need fault-tolerant execution of multi-step operations.

Use Boss Loops when: you need governed, attributable decision checkpoints.

Use both when: AI agents make recommendations inside durable workflows that require human approval, policy enforcement, and audit trail.

## Combined Architecture

```text
AI Agent
   ↓
Boss Loops    <- decision governance layer
   ↓
Temporal       <- durable execution layer
   ↓
Infrastructure
```

The agent proposes an action. Boss Loops governs whether it is allowed and by whom. Temporal durably executes the approved action.

## Code Example

```ts
import { createLoopSystem } from "@loop-engine/sdk";
import type { ActorRef, TransitionId } from "@loop-engine/core";

type TemporalActivityInput = {
  aggregateId: string;
  transitionId: TransitionId;
  actor: ActorRef;
};

export async function runApprovedOperation(input: TemporalActivityInput) {
  const { engine } = await createLoopSystem({ loops: [/* registered loop definitions */] });

  const decision = await engine.transition({
    aggregateId: input.aggregateId as never,
    transitionId: input.transitionId,
    actor: input.actor,
    evidence: { source: "temporal-activity" }
  });

  if (decision.status !== "executed") {
    throw new Error(`Operation blocked by governance: ${decision.status}`);
  }

  // Durable execution happens in workflow engine after approval.
}
```

## Related

- [Decision Governance](/docs/concepts/decision-governance)
- [AI as Actor](/docs/ai-and-automation/ai-as-actor)
- [Guards and Policy](/docs/concepts/guards-and-policy)


---

## Agents and RAG
URL: https://bossloops.io
/docs/concepts/agents-and-rag
Summary: How Boss Loops governs the decision boundary in AI agent systems and RAG pipelines.
Section: Core Concepts


## What Agent Frameworks Do

Agent frameworks like LangGraph, OpenAI Assistants, and custom agent loops focus on retrieving context, selecting tools, chaining operations, and generating recommendations from retrieved information.

They are excellent at reasoning. They are not designed to govern whether the resulting action is authorized, attributable, or auditable.

## The Governance Gap

A typical agentic flow:

```text
Knowledge Base
     ↓
RAG Retrieval           <- context retrieval
     ↓
LLM / Agent Reasoning   <- recommendation
     ↓
Tool / API Execution    <- action
```

This works for low-risk autonomous tasks.

In enterprise production - supply chain, financial approvals, healthcare, infrastructure - the gap between "agent recommends" and "system executes" needs an explicit governance layer.

## Where Boss Loops Fits

```text
Knowledge Base
     ↓
RAG Retrieval
     ↓
LLM / Agent Reasoning
     ↓
Boss Loops       <- decision governance
     ↓
Workflow Execution
```

The agent's recommendation becomes a proposed transition in a decision loop. Guards evaluate it. A human approves when policy requires. The action executes only after the loop allows it.

## RAG Outputs as Evidence

RAG systems already produce high-value evidence: retrieved documents, confidence scores, and graph relationships.

Boss Loops attaches this context directly to transitions as structured evidence, creating a permanent record of what the model used, what it recommended, and why the system allowed the action.

## Code Example

```ts
// @no-typecheck
import Anthropic from "@anthropic-ai/sdk";
import { createAnthropicActorAdapter } from "@loop-engine/adapter-anthropic";
import { createLoopSystem } from "@loop-engine/sdk";

const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
const adapter = createAnthropicActorAdapter(anthropic, { modelId: "claude-opus-4-6" });
const { engine } = await createLoopSystem({ loops: [/* procurement loop */] });

const ragResults = {
  retrievedDocs: 12,
  confidence: 0.84,
  ragSource: "vendor-policy-kb"
};

const { actor, decision } = await adapter.createSubmission({
  loopId: "procurement",
  loopName: "SCM Procurement",
  currentState: "pending_analysis",
  availableSignals: [{ signalId: "submit_recommendation", name: "Submit Recommendation" }],
  instruction: "Recommend whether to proceed with purchase order issuance.",
  evidence: { ...ragResults }
});

await engine.transition({
  aggregateId: "PO-10042" as never,
  transitionId: "submit_recommendation" as never,
  actor,
  evidence: { ...decision, ragResults }
});
```

## Commerce Chain and Boss Loops

Boss Loops is the runtime that powers the [Commerce Chain](https://commercechain.io) platform. Each `@betterdata/scm-*` and `@betterdata/dcm-*` module declares how it participates in loops using a **`LoopParticipantManifest`** from `@betterdata/loop-definitions`—a typed map of which domain events the module handles and which loop IDs it joins.

Canonical loop IDs and domain event names live in **`@betterdata/loop-definitions`** (`LoopIds`, `EventNames`) so modules and the host runtime stay aligned.

- [Commerce Chain](https://commercechain.io)
- [Loop participation guide](https://commercechain.io/docs/getting-started/loop-participation)
- [Architecture](https://commercechain.io/docs/getting-started/architecture)

## Related

- [AI as Actor](/docs/ai-and-automation/ai-as-actor)
- [Confidence + Evidence](/docs/ai-and-automation/confidence-evidence)
- [Decision Governance](/docs/concepts/decision-governance)
- [Boss Loops vs Workflow Engines](/docs/concepts/loop-engine-vs-workflow-engines)


---

## When to Use Boss Loops
URL: https://bossloops.io
/docs/concepts/when-to-use
Summary: Is Boss Loops right for your use case? Use this page to decide quickly.
Section: Core Concepts


## Use Boss Loops When

- AI agents make recommendations that affect operational systems
- Human approvals are required at defined checkpoints
- Policies must be enforced consistently, not through prompt instructions
- Decisions must carry an attributable audit trail
- Multiple actor types (human + AI + automation) participate in one flow
- Your industry requires demonstrable decision governance (healthcare, finance, pharma, regulated manufacturing)

## You Probably Don't Need It When

- Your workflow has a single actor and no approval gates
- The operation is fully deterministic with no AI or human decision points
- You only need retry logic and scheduling (use a workflow engine)
- You are building a prototype or exploration system

## Good Fits by Industry

- Healthcare and pharma: governed clinical and supply workflows with audit trails
- Financial services: fraud review, credit decisions, and change approvals
- Supply chain: AI-assisted procurement and demand signal response
- Infrastructure: change management and deployment gates
- Content and trust: moderation escalation and editorial approval

## Combined With Other Tools

Boss Loops works alongside workflow engines and agent frameworks - it does not replace them.

- [Boss Loops vs Workflow Engines](/docs/concepts/loop-engine-vs-workflow-engines)
- [Agents and RAG](/docs/concepts/agents-and-rag)

## Not Sure?

If you are asking, "can the AI just do this without approval?" that is usually the signal that you need Boss Loops.


---

## YAML Format
URL: https://bossloops.io
/docs/defining-loops/yaml-format
Summary: Boss Loops YAML definitions map to the LoopDefinition schema and are validated before runtime use.
Section: Defining Loops


## Loop definition YAML reference

This format is validated by `LoopDefinitionSchema` in `@loop-engine/loop-definition`.

### Top-level fields

- `id: string` (required)
- `version: string` semver `x.y.z` (required)
- `description: string` (required)
- `domain: string` (required)
- `states: StateSpec[]` (required, at least 1)
- `initialState: string` (required, must exist in `states`)
- `transitions: TransitionSpec[]` (required)
- `outcome: OutcomeSpec` (required)
- `participants?: string[]`
- `spawnableLoops?: string[]`
- `metadata?: Record<string, unknown>`

### `StateSpec`

- `id: string` (required)
- `description?: string`
- `isTerminal?: boolean`
- `isError?: boolean`

### `TransitionSpec`

- `id: string`
- `from: string`
- `to: string`
- `allowedActors: ("human" | "automation" | "ai-agent" | "system")[]`
- `guards?: GuardSpec[]`
- `sideEffects?: SideEffectSpec[]`
- `description?: string`

### `GuardSpec`

- `id: string`
- `description: string`
- `failureMessage: string`
- `severity: "hard" | "soft"`
- `evaluatedBy: "runtime" | "module" | "external"`

### `OutcomeSpec`

- `id: string`
- `description: string`
- `valueUnit: string`
- `measurable: boolean`
- `businessMetrics?: BusinessMetric[]`

## Annotated example (`scm.procurement`)

```yaml
id: scm.procurement
version: 1.0.0
domain: scm
description: Purchase order lifecycle through settlement

states:
  - id: OPEN
  - id: PO_CONFIRMED
  - id: RECEIVED
  - id: INVOICE_MATCHED
  - id: SETTLED
    isTerminal: true
  - id: DISPUTED
    isError: true

initialState: OPEN

transitions:
  - id: confirm_po
    from: OPEN
    to: PO_CONFIRMED
    allowedActors: [human, automation, ai-agent]
    guards:
      - id: approval_obtained
        severity: hard
        evaluatedBy: external
        description: PO must be approved before confirmation
        failureMessage: PO confirmation requires explicit approval

outcome:
  id: po_settled
  description: Purchase order settled with matched invoice
  valueUnit: po_settled
  measurable: true
  businessMetrics:
    - id: cycle_time_days
      label: PO cycle time (days)
      unit: days
      improvableByAI: true
```

## Common validation errors

- `initialState` not found in `states`
- transition `from`/`to` references unknown state
- empty `allowedActors`
- duplicate state IDs
- invalid `version` format (must be semver)


---

## TypeScript Builder
URL: https://bossloops.io
/docs/defining-loops/typescript-builder
Summary: LoopBuilder provides a fluent, type-guided way to define loops with runtime validation on build.
Section: Defining Loops


## `LoopBuilder` API (`@loop-engine/sdk`)

`LoopBuilder` is a fluent authoring API that validates on `.build()`.

### Signatures

```ts
LoopBuilder.create(id: string, domain: string): LoopBuilder
version(v: string): LoopBuilder
description(d: string): LoopBuilder
state(id: string, options?: { isTerminal?: boolean; isError?: boolean }): LoopBuilder
initialState(id: string): LoopBuilder
transition(spec: {
  id: string
  from: string
  to: string
  actors: ActorType[]
  guards?: Partial<GuardSpec>[]
}): LoopBuilder
outcome(spec: {
  id?: string
  description?: string
  valueUnit?: string
  measurable?: boolean
  businessMetrics?: Array<{ id: string; label: string; unit: string; improvableByAI: boolean }>
}): LoopBuilder
build(): LoopDefinition
```

### Runtime behavior notes

- `.transition()` throws if `actors` is empty.
- `.build()` throws if outcome is missing.
- `.build()` validates via `validateLoopDefinition()`.

## Example: procurement-style loop in TypeScript

```ts
import { LoopBuilder } from '@loop-engine/sdk'

const procurement = LoopBuilder
  .create('scm.procurement', 'scm')
  .version('1.0.0')
  .description('Purchase order lifecycle through settlement')
  .state('OPEN')
  .state('PO_CONFIRMED')
  .state('RECEIVED')
  .state('INVOICE_MATCHED')
  .state('SETTLED', { isTerminal: true })
  .initialState('OPEN')
  .transition({
    id: 'confirm_po',
    from: 'OPEN',
    to: 'PO_CONFIRMED',
    actors: ['human', 'automation', 'ai-agent'],
    guards: [
      {
        id: 'approval_obtained',
        severity: 'hard',
        evaluatedBy: 'external',
        description: 'PO must be approved',
        failureMessage: 'PO confirmation requires explicit approval'
      }
    ]
  })
  .outcome({
    id: 'po_settled',
    description: 'Purchase order settled',
    valueUnit: 'po_settled',
    measurable: true,
    businessMetrics: [
      { id: 'm_po_settled', label: 'PO settled', unit: 'count' }
    ]
  })
  .build()
```

Use YAML when loop definitions are owned by ops/product teams; use builder when you prefer type-guided code review and composition.


---

## Loop Library
URL: https://bossloops.io
/docs/defining-loops/loop-library
Summary: The loop library provides canonical YAML definitions you can run directly or use as patterns.
Section: Defining Loops


## Canonical loop definitions

Boss Loops currently ships these canonical definitions from `loops/`:

| Loop ID | Domain | States | Terminal states | Business metrics |
|---|---|---:|---:|---:|
| `scm.procurement` | `scm` | 8 | 2 | 3 |
| `scm.replenishment` | `scm` | 5 | 2 | 2 |
| `crm.lead_qualification` | `crm` | 6 | 2 | 2 |
| `finance.invoice_collection` | `finance` | 6 | 2 | 2 |
| `support.ticket_resolution` | `support` | 6 | 2 | 2 |
| `erp.purchase_approval` | `erp` | 6 | 2 | 2 |

## Featured definition: `scm.procurement`

```yaml
id: scm.procurement
version: 1.0.0
domain: scm
description: >
  Purchase order lifecycle from requisition through receipt and settlement.
states:
  - id: OPEN
  - id: PO_CONFIRMED
  - id: RECEIPT_SCHEDULED
  - id: RECEIVED
  - id: INVOICE_MATCHED
  - id: SETTLED
    isTerminal: true
  - id: CANCELLED
    isTerminal: true
  - id: DISPUTED
    isError: true
initialState: OPEN
transitions:
  - id: confirm_po
    from: OPEN
    to: PO_CONFIRMED
    allowedActors: [human, automation, ai-agent]
outcome:
  id: po_settled
  description: Purchase order fully settled with matched invoice and inventory updated
  valueUnit: po_settled
  measurable: true
```

Raw files:

- [procurement.yaml](https://github.com/loopengine/loop-engine/blob/main/loops/scm/procurement.yaml)
- [replenishment.yaml](https://github.com/loopengine/loop-engine/blob/main/loops/scm/replenishment.yaml)
- [lead-qualification.yaml](https://github.com/loopengine/loop-engine/blob/main/loops/crm/lead-qualification.yaml)

## Contributing a loop definition

- Add YAML under `loops/{domain}/{name}.yaml`
- Validate with `pnpm validate-loops`
- Include a concrete `outcome`
- Add `businessMetrics` when measurable
- Prefer at least one non-human actor option (`automation`, `system`, or `ai-agent`) where domain-appropriate

See [Contributing](/docs/governance/contributing) for full workflow.

## Naming conventions

- Loop ID: `{domain}.{noun}` (for example `scm.procurement`)
- State IDs: `SCREAMING_SNAKE_CASE`
- Transition IDs: `snake_case` verbs (for example `confirm_po`, `receive_goods`)


---

## Guards Reference
URL: https://bossloops.io
/docs/defining-loops/guards-reference
Summary: Built-in guards enforce policy checks before transitions execute, with deterministic failure behavior.
Section: Defining Loops


## Built-in guard reference

All built-ins are in `packages/guards/src/built-in/*` and are registered by default in `defaultRegistry`.

### `actor_has_permission`

- Evaluated by: `runtime`
- Implementation: checks `evidence.required_role` against `evidence.roles`
- Failure message: `Missing actor roles in evidence` or `Actor missing required role: <role>`

Required evidence fields:

| Field | Type | Required | Description |
|---|---|---|---|
| `required_role` | `string` | conditional | role to require |
| `roles` | `unknown[]` | conditional | actor role set |

### `approval_obtained`

- Evaluated by: `runtime`
- Check: `evidence.approved === true`
- Failure message: `Approval not obtained`

| Field | Type | Required | Description |
|---|---|---|---|
| `approved` | `boolean` | yes | explicit approval flag |

### `deadline_not_exceeded`

- Evaluated by: `runtime`
- Check: current time before `Date.parse(evidence.deadline_iso)`
- Failures: `Invalid deadline format` or `Deadline exceeded`

| Field | Type | Required | Description |
|---|---|---|---|
| `deadline_iso` | `string` | conditional | ISO deadline timestamp |

### `duplicate_check_passed`

- Evaluated by: `runtime`
- Check: `evidence.duplicate_found !== true`
- Failure message: `Duplicate detected`

| Field | Type | Required | Description |
|---|---|---|---|
| `duplicate_found` | `boolean` | conditional | duplicate marker |

### `field_value_constraint`

- Evaluated by: `runtime`
- Reads `evidence.constraint`:
  - `field`
  - `operator: "eq" | "gt" | "lt" | "in"`
  - `value`
- Failure message: `Field constraint failed for <field>`

| Field | Type | Required | Description |
|---|---|---|---|
| `constraint` | object | yes | rule descriptor |
| `<constraint.field>` | unknown | yes | value to compare |

## Loop definition usage

```yaml
guards:
  - id: approval_obtained
    severity: hard
    evaluatedBy: runtime
    description: Approval must be present
    failureMessage: Approval not obtained
```

## Failure behavior

- Hard guard failure returns `TransitionResult.status: "guard_failed"`
- Runtime emits `loop.guard.failed`
- State does not advance
- Soft guard failures are preserved under `_softGuardWarnings` in transition evidence

## Writing custom guards

Use `GuardFunction` from `@loop-engine/guards`:

```ts
type GuardFunction = (context: GuardContext) => Promise<GuardResult>
```

See [Guards and Policy](/docs/concepts/guards-and-policy) for full custom registry setup.


---

## createLoopSystem
URL: https://bossloops.io
/docs/running-loops/create-loop-system
Summary: The createLoopSystem factory wires together a LoopEngine, event bus, and optional loop catalog client in a single call.
Section: Running Loops


## `createLoopSystem(options)`

Factory from `@loop-engine/sdk`:

```ts
createLoopSystem(options: {
  loops: LoopDefinition[]
  store?: LoopStore
  guards?: GuardRegistry
  signals?: boolean
  registry?: LoopRegistry
}): Promise<{
  engine: LoopEngine
  store: LoopStore
  eventBus: InMemoryEventBus
  signals?: SignalRegistry
}>
```

- `loops` is required and becomes the in-memory set of definitions.
- `store` defaults to `memoryStore()`.
- `guards` defaults to `defaultRegistry` from `@loop-engine/guards`.
- `signals: true` materializes a `SignalRegistry` for spec registration/validation; use the returned `eventBus` to observe `loop.*` and `loop.signal.received` events in this release.
- `registry` is the optional **loop catalog** client (`LoopRegistry`); if `registry.list()` fails, startup falls back to `loops[]`.

## Pattern 1: zero-config

```ts
// @no-typecheck
import { createLoopSystem } from '@loop-engine/sdk'

const { engine, eventBus } = await createLoopSystem({ loops: [definition] })
```

## Pattern 2: custom store (PostgreSQL adapter)

```ts
// @no-typecheck
import { createLoopSystem } from '@loop-engine/sdk'
import { postgresStore } from '@loop-engine/adapter-postgres'
import { Pool } from 'pg'

const pool = new Pool({ connectionString: process.env.DATABASE_URL })
const { engine } = await createLoopSystem({
  loops: [definition],
  store: postgresStore(pool)
})
```

## Pattern 3: signals enabled

`SignalRegistry` in `1.0.0-rc.0` is for spec registration/validation. React to live signal flow through the returned `eventBus` (for example, `loop.signal.received`).

```ts
// @no-typecheck
import { createLoopSystem } from '@loop-engine/sdk'

const { signals, eventBus } = await createLoopSystem({
  loops: [definition],
  signals: true
})

// Optional: register or inspect specs on `signals` (instance of `SignalRegistry`).
void signals?.list()

eventBus.subscribe(async (event) => {
  if (event.type === "loop.signal.received") {
    console.log(event.signal, event.aggregateId)
  }
})
```


---

## Starting Loops
URL: https://bossloops.io
/docs/running-loops/starting-loops
Summary: Start loop instances with explicit actor attribution and aggregate identity using `engine.start`.
Section: Running Loops


## `engine.start(options)`

Signature (from runtime source):

```ts
start(options: {
  loopId: string
  aggregateId: AggregateId
  actor: { type: "human" | "automation" | "ai-agent" | "system"; id: string }
  correlationId?: CorrelationId
  metadata?: Record<string, unknown>
}): Promise<LoopInstance>
```

## Behavior

- Throws if `loopId` is not registered.
- Throws if an active instance already exists for the same `aggregateId` (source check: `status === "active"`).
- Creates instance with:
  - `currentState = definition.initialState`
  - `status = "active"`
  - `startedAt` timestamp (also sets `updatedAt` to the same value)
  - generated correlation ID when omitted
- Emits `loop.started`.

## Example

```ts
import { aggregateId } from '@loop-engine/core'

const instance = await engine.start({
  loopId: 'scm.procurement',
  aggregateId: aggregateId('PO-001'),
  actor: { type: 'system', id: 'system:intake' },
  metadata: { source: 'erp_sync' }
})
```

## `LoopInstance` shape

```ts
{
  loopId,
  aggregateId,
  currentState,
  status,            // pending | active | completed | failed | cancelled | suspended
  startedAt,
  updatedAt,
  correlationId?,
  completedAt?,
  metadata?
}
```

## Choosing `aggregateId`

Use your existing entity identifier:

- PO number
- order ID
- invoice number
- ticket ID
- lead ID

Same `aggregateId` can be reused across different loop IDs.
Same `loopId + aggregateId` cannot have multiple open instances.


---

## Transitions
URL: https://bossloops.io
/docs/running-loops/transitions
Summary: Transitions apply actor-attributed state changes and return explicit execution outcomes.
Section: Running Loops


## `engine.transition(options)`

Signature:

```ts
transition(options: {
  aggregateId: AggregateId
  transitionId: TransitionId
  actor: { type: "human" | "automation" | "ai-agent" | "system"; id: string }
  evidence?: Evidence
  correlationId?: CorrelationId
}): Promise<TransitionResult>
```

## `TransitionResult`

```ts
{
  status: "executed" | "guard_failed" | "rejected" | "pending_approval"
  fromState: StateId
  toState?: StateId
  guardFailures?: { guardId: GuardId; message: string; severity: "hard" | "soft" }[]
  rejectionReason?: string
  requiresApprovalFrom?: ActorId
  event?: TransitionExecutedEvent | GuardFailedEvent
}
```

## Handle all statuses

```ts
const result = await engine.transition({
  aggregateId,
  transitionId,
  actor,
  evidence
})

switch (result.status) {
  case 'executed':
    console.log(result.toState)
    break
  case 'guard_failed':
    console.log(result.guardFailures)
    break
  case 'rejected':
    console.log(result.rejectionReason)
    break
  case 'pending_approval':
    console.log(result.requiresApprovalFrom)
    break
}
```

## Evidence best practices

Evidence is persisted in `TransitionRecord.evidence` and emitted in `loop.transition.executed`.

- Human actions: include user decision context
- Automation actions: include triggering rule or source
- AI actions: include `ai_confidence` and `ai_reasoning` (via `buildActorEvidence`)

Use evidence to answer: _why was this action taken?_ without reconstructing from logs.


---

## Event Subscriptions
URL: https://bossloops.io
/docs/running-loops/event-subscriptions
Summary: Event subscriptions stream loop lifecycle events for audit, automation, and external integrations.
Section: Running Loops


## EventBus subscription model

`InMemoryEventBus` (`@loop-engine/events`) exposes:

```ts
emit(event: LoopEvent): Promise<void>
subscribe(handler: (event: LoopEvent) => Promise<void>): () => void
```

## Event types

- `loop.started`
- `loop.completed`
- `loop.cancelled`
- `loop.failed`
- `loop.transition.requested`
- `loop.transition.executed`
- `loop.transition.blocked`
- `loop.guard.failed`
- `loop.signal.received`

## Subscribe patterns

```ts
eventBus.subscribe(async (event) => {
  console.log(event.type, event.aggregateId)
})
```

```ts
eventBus.subscribe(async (event) => {
  if (event.type === 'loop.completed') {
    console.log('Closed:', event.finalState, `${event.durationMs}ms`)
  }
})
```

```ts
const unsubscribe = eventBus.subscribe(async (event) => {
  console.log(event.type)
})

unsubscribe()
```

## Audit trail pattern

Persist `loop.transition.executed` payloads and retain:

- actor type/id
- from/to state
- evidence
- timestamp

That yields a complete decision history for compliance and incident review.

## External delivery adapters

### HTTP webhook bus

```ts
import { httpEventBus } from '@loop-engine/adapter-http'

const bus = httpEventBus({
  webhookUrl: 'https://your-app.com/loop-events'
})
```

### Kafka bus

```ts
import { kafkaEventBus } from '@loop-engine/adapter-kafka'
import { Kafka } from 'kafkajs'

const bus = kafkaEventBus({
  kafka: new Kafka({ brokers: ['localhost:9092'] }) as any,
  topic: 'loop-events'
})
```


---

## Adapters
URL: https://bossloops.io
/docs/running-loops/adapters
Summary: Adapters connect Boss Loops runtime contracts to concrete storage and delivery infrastructure.
Section: Running Loops


## `LoopStore` interface

All persistence adapters must implement:

```ts
getInstance(aggregateId: AggregateId): Promise<LoopInstance | null>
saveInstance(instance: LoopInstance): Promise<void>
getTransitionHistory(aggregateId: AggregateId): Promise<TransitionRecord[]>
saveTransitionRecord(record: TransitionRecord): Promise<void>
listOpenInstances(loopId: LoopId): Promise<LoopInstance[]>
```

## `@loop-engine/adapter-memory`

```ts
import { memoryStore } from '@loop-engine/adapter-memory'
const store = memoryStore()
```

Use for tests, local development, browser demos.  
Data resets on process restart.

## `@loop-engine/adapter-postgres`

<Callout variant="info" title="Version track">
`@loop-engine/adapter-postgres` ships at `0.2.0` while the rest of the `@loop-engine/*` family is at `1.0.0-rc.0`. The API shape is stable; the version reflects pre-1.0 commit to the migration surface rather than contract drift. Consumers can pin `@loop-engine/adapter-postgres@^0.2.0` alongside `1.0.0-rc.0` runtime packages.
</Callout>

```ts
import { postgresStore, createSchema, createPool, runMigrations } from '@loop-engine/adapter-postgres'

const pool = createPool({ connectionString: process.env.DATABASE_URL })
await runMigrations(pool)
const store = postgresStore(pool)
```

Schema creates:

- `loop_instances`
  - `aggregate_id`, `loop_id`, `current_state`, `status`, `started_at`, `updated_at`, `completed_at`, `correlation_id`, `metadata`
- `loop_transitions`
  - `id`, `loop_id`, `aggregate_id`, `transition_id`, `from_state`, `to_state`, `actor`, `evidence`, `occurred_at`, `duration_ms`
- `schema_migrations`
  - migration-tracking table managed by `runMigrations`

Additional exports: `createSchema(pool)` (legacy DDL helper; prefer `runMigrations` for incremental upgrades), plus `Migration`, `MigrationRunResult`, `PoolOptions`, `PostgresStore` types and error classification utilities.

Peer dependency: `pg@^8.0.0`.

## Event bus adapters

### `@loop-engine/adapter-kafka`

- Provides `kafkaEventBus(...)`
- Use for streaming and service-to-service fanout
- Peer dependency: `kafkajs@^2.0.0`

### `@loop-engine/adapter-http`

- Provides `httpEventBus(...)`
- Use for webhooks and low-friction integrations
- `subscribe()` is intentionally unsupported (emit-only adapter)

## Build a custom adapter

Implement `LoopStore` exactly and pass it to:

```ts
createLoopSystem({ loops, store: myStore })
```


---

## Package taxonomy
URL: https://bossloops.io
/docs/packages
Summary: Select Boss Loops npm packages by runtime role — runtime core, Providers, Channels, and Integrations.
Section: Packages


Boss Loops installs in layers. The minimum floor is always `@loop-engine/sdk`. Additional packages are opt-in by capability.

Public docs group connections as **[Providers](/docs/concepts/runtime-taxonomy#providers)**, **[Channels](/docs/concepts/runtime-taxonomy#channels)**, and **[Integrations](/docs/concepts/runtime-taxonomy#integrations)**. npm package names and developer types (`ActorAdapter`, `ToolAdapter`, `IntegrationAdapter` archetypes) sit underneath — see [IntegrationAdapter archetype](/docs/concepts/integration-adapter).

→ [Runtime connections index](/docs/integrations) · [Runtime Taxonomy](/docs/concepts/runtime-taxonomy)

## By runtime role

| Runtime role | What you add | Required | Packages (current) | Planned |
| --- | --- | --- | --- | --- |
| **Runtime core** | Types, loop execution, guards, actors, events | always | `sdk`, `runtime`, `core`, `loop-definition`, `guards`, `actors`, `events`, `signals` | — |
| **Provider** | Governed LLM actors and tool steps (intelligence) | one per model / use-case | `adapter-anthropic`, `adapter-openai`, `adapter-gemini`, `adapter-grok`, `adapter-perplexity`, `adapter-vercel-ai` | `adapter-ollama`, `adapter-cohere`, `adapter-mistral` |
| **Channel** | Route `PENDING_HUMAN_APPROVAL` to human surfaces | when humans approve outside your app | `adapter-openclaw` | `adapter-slack`, `adapter-teams`, `adapter-discord`, `adapter-webhook` |
| **Integration** | Persistence, event buses, operational backends | pick per environment | `adapter-memory`, `adapter-postgres`, `adapter-kafka`, `adapter-http`, `adapter-pagerduty`, `adapter-commerce-gateway` | `adapter-redis`, `adapter-sqlite`, `adapter-dynamodb` |
| **Platform & tooling** | Catalog, metrics, devtools | optional | `observability`, `ui-devtools`, `registry-client` | `adapter-datadog`, `adapter-grafana` |

<Callout variant="info" title="Developer map">
| Public term | Developer primitives |
| --- | --- |
| Provider | `ActorAdapter` (LLM actors), `ToolAdapter` (e.g. Perplexity Sonar retrieval) |
| Channel | EventBus routing to human surfaces (OpenClaw; Slack/Teams via Cloud connectors) |
| Integration | `IntegrationAdapter` archetypes — `LoopStore`, `LoopRegistry`, `EventBus`, operational adapters |
</Callout>

## Minimum install

```bash
npm install @loop-engine/sdk
```

Core primitives ship in `@loop-engine/sdk`. Standalone `@loop-engine/*` packages exist when you want explicit layer boundaries.

## Common install recipes

### Governed Claude tool calls (Provider + framework bridge)

```bash
npm install @loop-engine/sdk @loop-engine/adapter-anthropic @loop-engine/adapter-vercel-ai
```

### Human approval via messenger (Channel)

```bash
npm install @loop-engine/sdk @loop-engine/adapter-openclaw @loop-engine/adapter-memory
```

### Production loop with persistence + Provider + ops trigger (Integration + Provider)

```bash
npm install @loop-engine/sdk @loop-engine/adapter-postgres @loop-engine/adapter-anthropic @loop-engine/adapter-pagerduty
```

### Multi-model loop

```bash
npm install @loop-engine/sdk @loop-engine/adapter-anthropic @loop-engine/adapter-openai @loop-engine/adapter-postgres
```

### Observability stack

```bash
npm install @loop-engine/sdk @loop-engine/observability @loop-engine/ui-devtools
```

## Dependency direction

**Runtime core** has no Boss Loops upstream dependencies. **Providers**, **Channels**, and **Integrations** depend on core. Add one package per capability — not every row in the table.

<Callout variant="warning" title="Self-host vs hosted">
**Today:** install OSS packages in your processes (local-first). **Direction:** optional self-host services (registry, audit store, replay, …) documented as roadmap-only on [Runtime Platform Direction](/docs/concepts/runtime-platform-direction). **Boss Loops Cloud** adds managed connectors — not full OSS parity. Better Data apps: **[docs.betterdata.co](https://docs.betterdata.co)**.
</Callout>

<Callout variant="warning" title="Vertical loops">
Domain packs (`loops-healthcare`, `loops-fintech`, …) are under active development. [Open a discussion →](https://github.com/loopengine/loop-engine/discussions)
</Callout>


---

## @loop-engine/sdk
URL: https://bossloops.io
/docs/packages/sdk
Summary: The @loop-engine/sdk package is the recommended entry point - it re-exports everything needed to define, run, and observe loops.
Section: Packages


`@loop-engine/sdk` is the fastest way to define loops, create a runtime, and wire guards, events, and optional signals.

## Install

```bash
npm install @loop-engine/sdk
```

## Re-export surface

Source-verified exports include:

- `LoopBuilder`
- `createLoopSystem` (auto-wired aggregate; the runtime factory `createLoopEngine` is exported from `@loop-engine/runtime`)
- `redactPiiEvidence` and `defaultRegistry` / `createGuardRegistry` from the guard stack (re-exported for convenience; see each package for full lists)
- `InMemoryEventBus` and `SignalRegistry` (including when `createLoopSystem({ signals: true })` returns a `SignalRegistry` for spec metadata)
- `computeMetrics` and `buildTimeline`
- `localRegistry` and `httpRegistry`
- core types: `LoopDefinition`, `LoopInstance`, `TransitionRecord`, and the signal/actor unions you need for authoring
- `createAIActor` for provider-switched AI actor creation

## createAIActor

`createAIActor()` gives a single SDK entrypoint for `anthropic`, `openai`, `gemini`, and `grok`.
Switching providers is a config change only:

```ts
import { createAIActor } from "@loop-engine/sdk"

const actor = createAIActor({
  provider: "gemini",
  model: "gemini-1.5-pro",
  apiKey: process.env.GOOGLE_AI_API_KEY ?? ""
})
```

If the underlying provider SDK is missing, it throws a targeted install command.
Power users can still import individual adapter packages for custom client wiring.

## createLoopSystem

```ts
createLoopSystem(options: {
  loops: LoopDefinition[]
  store?: LoopStore
  guards?: GuardRegistry
  signals?: boolean
  registry?: LoopRegistry
}): Promise<{
  engine: LoopEngine
  store: LoopStore
  signals?: SignalRegistry
  eventBus: InMemoryEventBus
}>
```

Behavior from source:

- `store` defaults to `memoryStore()`
- `guards` defaults to `defaultRegistry` / `createGuardRegistry` patterns (see `@loop-engine/guards`)
- `signals: true` materializes a `SignalRegistry` for spec registration/validation; runtime notification paths use the returned `eventBus` (for example, `loop.signal.received` events) rather than a `SignalRegistry#subscribe` API
- `registry` (loop **catalog** client, type `LoopRegistry`) is additive; local `loops[]` win on ID conflicts
- catalog load failures log a warning and fall back to local loops

```ts
// @no-typecheck
import { aggregateId, transitionId } from "@loop-engine/core"
import { LoopBuilder, createLoopSystem } from "@loop-engine/sdk"

const loop = LoopBuilder
  .create("expense.approval", "finance")
  .state("SUBMITTED")
  .state("APPROVED", { isTerminal: true })
  .state("REJECTED", { isTerminal: true })
  .initialState("SUBMITTED")
  .transition({ id: "approve", from: "SUBMITTED", to: "APPROVED", actors: ["human"] })
  .transition({ id: "reject", from: "SUBMITTED", to: "REJECTED", actors: ["human"] })
  .outcome({
    id: "expense_approved",
    description: "Expense approved",
    valueUnit: "expense_approved",
    businessMetrics: [{ id: "m_expense_approved", label: "Expense approved", unit: "count" }]
  })
  .build()

const { engine, eventBus } = await createLoopSystem({ loops: [loop] })

eventBus.subscribe(async (event) => {
  if (event.type === "loop.transition.executed") {
    console.log(event.transitionId)
  }
})

await engine.start({
  loopId: "expense.approval",
  aggregateId: aggregateId("EXP-1"),
  actor: { type: "system", id: "system:intake" }
})

await engine.transition({
  aggregateId: aggregateId("EXP-1"),
  transitionId: transitionId("approve"),
  actor: { type: "human", id: "manager@acme.com" },
  evidence: { approved: true }
})
```

## Direct imports

```ts
import { createLoopEngine, type LoopEngine } from "@loop-engine/runtime"
import {
  LoopBuilder,
  createLoopSystem,
  InMemoryEventBus,
  type LoopDefinition
} from "@loop-engine/sdk"
```

## Package selection

- Use `@loop-engine/sdk` for apps, scripts, and most services.
- Use individual packages for tight bundle control or specialized integrations.


---

## @loop-engine/core
URL: https://bossloops.io
/docs/packages/core
Summary: Shared TypeScript contracts and branded IDs define the Boss Loops boundary with zero runtime dependencies.
Section: Packages


`@loop-engine/core` defines the type contract used by every other `@loop-engine/*` package and ships no runtime implementations.

## Install

```bash
npm install @loop-engine/core
```

## Overview

Core provides branded identifiers, actor and guard primitives, and canonical loop lifecycle interfaces. Runtime, DSL, adapters, and SDK layers all import these contracts.

## Branded IDs

```ts
export type LoopId = string & { readonly __brand: "LoopId" }
export type StateId = string & { readonly __brand: "StateId" }
export type TransitionId = string & { readonly __brand: "TransitionId" }
export type AggregateId = string & { readonly __brand: "AggregateId" }
export type ActorId = string & { readonly __brand: "ActorId" }
export type GuardId = string & { readonly __brand: "GuardId" }
export type SignalId = string & { readonly __brand: "SignalId" }
export type OutcomeId = string & { readonly __brand: "OutcomeId" }
export type CorrelationId = string & { readonly __brand: "CorrelationId" }
```

Helper constructors cast incoming strings to branded IDs:

```ts
import { aggregateId, transitionId } from "@loop-engine/core"

const aggregate = aggregateId("EXP-2026-001")
const transition = transitionId("approve")
```

## Loop definition types

```ts
export type ActorType = "human" | "automation" | "ai-agent" | "system"
export type LoopStatus =
  | "pending"
  | "active"
  | "completed"
  | "failed"
  | "cancelled"
  | "suspended"

export interface GuardSpec {
  id: GuardId
  description: string
  failureMessage: string
  severity: "hard" | "soft"
  evaluatedBy: "runtime" | "module" | "external"
}

export interface StateSpec {
  id: StateId
  description?: string
  isTerminal?: boolean
  isError?: boolean
}

export interface TransitionSpec {
  id: TransitionId
  from: StateId
  to: StateId
  allowedActors: ActorType[]
  guards?: GuardSpec[]
  sideEffects?: SideEffectSpec[]
  description?: string
}

export interface LoopDefinition {
  id: LoopId
  version: string
  description: string
  domain: string
  states: StateSpec[]
  initialState: StateId
  transitions: TransitionSpec[]
  outcome: OutcomeSpec
  participants?: string[]
  spawnableLoops?: LoopId[]
  metadata?: Record<string, unknown>
}
```

## Runtime state types

```ts
export interface ActorRef {
  id: ActorId
  type: ActorType
  displayName?: string
  metadata?: Record<string, unknown>
}

export interface LoopInstance {
  loopId: LoopId
  aggregateId: AggregateId
  currentState: StateId
  status: LoopStatus
  startedAt: string
  updatedAt: string
  correlationId?: string
  completedAt?: string
  metadata?: Record<string, unknown>
}

export interface TransitionRecord {
  aggregateId: AggregateId
  loopId: LoopId
  transitionId: TransitionId
  signal: SignalId
  fromState: StateId
  toState: StateId
  actor: ActorRef
  occurredAt: string
  evidence?: Record<string, unknown>
}
```

## Signal and outcome types

```ts
export interface OutcomeSpec {
  id: OutcomeId
  description: string
  valueUnit: string
  measurable: boolean
  businessMetrics?: BusinessMetric[]
}

export interface Signal {
  id: SignalId
  type: string
  subject: string
  confidence?: number
  observedAt: string
  payload: Record<string, unknown>
  triggeredLoopId?: LoopId
}
```

## Design principles

- Type-first boundaries keep packages interoperable without runtime coupling.
- Zero runtime dependencies keep `core` safe for shared libraries and edge bundles.
- Branded IDs reduce accidental string mixing across loop, actor, transition, and signal contexts.


---

## @loop-engine/runtime
URL: https://bossloops.io
/docs/packages/runtime
Summary: The LoopEngine class starts loops, executes transitions, and stores state through the LoopStore interface.
Section: Packages


`@loop-engine/runtime` is the execution layer that mutates loop state and emits lifecycle events.

## Install

```bash
npm install @loop-engine/runtime
```

## Engine construction

```ts
createLoopEngine(options: LoopEngineOptions): LoopEngine
```

`LoopEngineOptions`:

The `registry` field is your **loop catalog** client (`LoopRegistry` in types) — definitions loaded from disk, HTTP, or Better Data, not the Commerce Gateway Registry.

```ts
interface LoopEngineOptions {
  registry: LoopRegistry
  store: LoopStore
  eventBus?: EventBus
  guardEvaluator?: GuardEvaluator
  clock?: () => string
}
```

## Core methods

```ts
start(options: StartOptions): Promise<LoopInstance>
transition(options: TransitionOptions): Promise<TransitionResult>
getState(aggregateId: AggregateId): Promise<LoopInstance | null>
getHistory(aggregateId: AggregateId): Promise<TransitionRecord[]>
listOpen(loopId: string): Promise<LoopInstance[]>
registerSideEffectHandler(sideEffectId: string, handler: SideEffectHandler): void
```

Transition result statuses from source:

- `executed`
- `guard_failed`
- `rejected`
- `pending_approval`

```ts
const result = await engine.transition({
  aggregateId,
  transitionId: transitionId("approve"),
  actor: { type: "human", id: "manager@acme.com" },
  evidence: { approved: true }
})

if (result.status === "guard_failed") {
  console.log(result.guardFailures)
}
```

## Store and bus interfaces

```ts
interface LoopStore {
  getInstance(aggregateId: AggregateId): Promise<LoopInstance | null>
  saveInstance(instance: LoopInstance): Promise<void>
  getTransitionHistory(aggregateId: AggregateId): Promise<TransitionRecord[]>
  saveTransitionRecord(record: TransitionRecord): Promise<void>
  listOpenInstances(loopId: LoopId): Promise<LoopInstance[]>
}

interface EventBus {
  emit(event: LoopEvent): Promise<void>
  subscribe(handler: (event: LoopEvent) => Promise<void>): () => void
}
```

Use `@loop-engine/adapter-memory` in development and `@loop-engine/adapter-postgres` for a production persistence target.


---

## @loop-engine/loop-definition
URL: https://bossloops.io
/docs/packages/loop-definition
Summary: LoopBuilder plus YAML and JSON parsing produce validated LoopDefinition objects from fluent or file-based authoring.
Section: Packages


`@loop-engine/loop-definition` turns fluent TypeScript or YAML/JSON documents into validated `LoopDefinition` contracts.

<Callout variant="info" title="Recommended usage">
Most users should import these APIs from `@loop-engine/sdk`, which re-exports the Loop Definition surface.

Install `@loop-engine/loop-definition` directly when you need a tree-shakeable, narrow slice of the runtime.
</Callout>

## Install

```bash
npm install @loop-engine/loop-definition
```

## LoopBuilder

```ts
LoopBuilder.create(id: string, domain: string): LoopBuilder
```

Builder methods implemented in source:

- `.version(v: string): LoopBuilder`
- `.description(d: string): LoopBuilder`
- `.state(id: string, options?: { isTerminal?: boolean; isError?: boolean }): LoopBuilder`
- `.initialState(id: string): LoopBuilder`
- `.transition(spec: { id: string; from: string; to: string; actors: ActorType[]; guards?: Partial<GuardSpec>[] }): LoopBuilder`
- `.outcome(spec: { id?: string; description?: string; valueUnit?: string; measurable?: boolean; businessMetrics?: ... }): LoopBuilder`
- `.build(): LoopDefinition`

<Callout variant="warning" title="Current builder surface">
`guard()`, `signal()`, and `actor()` are slated for `1.1.0+` as experimental builder methods and are not implemented in the current release. Guards are added today inside `.transition({ guards: [...] })`.
</Callout>

## Fluent example

```ts
import { LoopBuilder } from "@loop-engine/loop-definition"

const approval = LoopBuilder
  .create("expense.approval", "finance")
  .version("1.0.0")
  .description("Expense approval loop")
  .state("SUBMITTED")
  .state("UNDER_REVIEW")
  .state("APPROVED", { isTerminal: true })
  .state("REJECTED", { isTerminal: true })
  .initialState("SUBMITTED")
  .transition({
    id: "start_review",
    from: "SUBMITTED",
    to: "UNDER_REVIEW",
    actors: ["automation"]
  })
  .transition({
    id: "approve",
    from: "UNDER_REVIEW",
    to: "APPROVED",
    actors: ["human"],
    guards: [
      {
        id: "approval_obtained" as never,
        description: "Manager approval required",
        failureMessage: "Approval missing",
        severity: "hard",
        evaluatedBy: "runtime"
      }
    ]
  })
  .outcome({
    id: "expense_approved",
    description: "Expense approved",
    valueUnit: "expense_approved",
    measurable: true,
    businessMetrics: [
      { id: "m_expense_approved", label: "Expense approved", unit: "count" }
    ]
  })
  .build()
```

## YAML parsing

```ts
import { parseLoopYaml } from "@loop-engine/loop-definition"

const definition = parseLoopYaml(yamlString)
```

Equivalent YAML for the same loop:

```yaml
id: expense.approval
version: 1.0.0
description: Expense approval loop
domain: finance
states:
  - id: SUBMITTED
  - id: UNDER_REVIEW
  - id: APPROVED
    isTerminal: true
  - id: REJECTED
    isTerminal: true
initialState: SUBMITTED
transitions:
  - id: start_review
    from: SUBMITTED
    to: UNDER_REVIEW
    allowedActors: [automation]
  - id: approve
    from: UNDER_REVIEW
    to: APPROVED
    allowedActors: [human]
    guards:
      - id: approval_obtained
        description: Manager approval required
        failureMessage: Approval missing
        severity: hard
        evaluatedBy: runtime
outcome:
  id: expense_approved
  description: Expense approved
  valueUnit: expense_approved
  measurable: true
```

See `/docs/defining-loops/yaml-format` for the full format reference.

## Validation and serialization

```ts
import {
  parseLoopJson,
  parseLoopYaml,
  serializeLoopJson,
  serializeLoopYaml,
  validateLoopDefinition
} from "@loop-engine/loop-definition"
```

Validation signature:

```ts
validateLoopDefinition(definition: LoopDefinition): ValidationResult

interface ValidationResult {
  valid: boolean
  errors: ValidationError[]
}

interface ValidationError {
  code: string
  message: string
  path?: string
}
```

Validation failure example:

```ts
{
  valid: false,
  errors: [
    {
      code: "INVALID_INITIAL_STATE",
      message: 'initialState "DRAFT" does not exist in states',
      path: "initialState"
    }
  ]
}
```


---

## @loop-engine/events
URL: https://bossloops.io
/docs/packages/events
Summary: InMemoryEventBus and typed lifecycle event contracts provide pub-sub plumbing for loop runtime behavior.
Section: Packages


`@loop-engine/events` defines the event contract and ships an in-memory event bus implementation.

## Install

```bash
npm install @loop-engine/events
```

## Event catalog

The exported `LOOP_EVENT_TYPES` constant enumerates the nine canonical lifecycle events:

- `loop.started`
- `loop.completed`
- `loop.cancelled`
- `loop.failed`
- `loop.transition.requested`
- `loop.transition.executed`
- `loop.transition.blocked`
- `loop.guard.failed`
- `loop.signal.received`

Every event extends:

```ts
interface LoopEventBase {
  eventId: string
  type: string
  loopId: LoopId
  aggregateId: AggregateId
  occurredAt: string
  correlationId?: string
  causationId?: string
}
```

## InMemoryEventBus

```ts
class InMemoryEventBus {
  emit(event: LoopEvent): Promise<void>
  subscribe(handler: (event: LoopEvent) => Promise<void>): () => void
}
```

`subscribe()` returns an unsubscribe callback, and handler failures do not block other subscribers.

```ts
import { InMemoryEventBus } from "@loop-engine/events"

const bus = new InMemoryEventBus()
const unsubscribe = bus.subscribe(async (event) => {
  if (event.type === "loop.transition.executed") {
    console.log(event.transitionId, event.actor.type)
  }
})

unsubscribe()
```

## Learning signal extraction

```ts
extractLearningSignal(
  completed: LoopCompletedEvent,
  history: LoopTransitionExecutedEvent[],
  definition: LoopDefinitionLike,
  predicted?: Record<string, number>
): LearningSignal
```

The helper derives `actual`, `predicted`, and numeric `delta` fields from the completed event, the executed-transition history, and the loop definition's declared business metrics. `predicted` keys not declared in `definition.outcome.businessMetrics` are dropped with a warning.


---

## @loop-engine/signals
URL: https://bossloops.io
/docs/packages/signals
Summary: SignalRegistry is the current signal-spec surface; SignalEngine pattern detection lands in 1.1.0 as experimental.
Section: Packages


`@loop-engine/signals` ships `SignalRegistry` for declaring and validating signal specs. The pattern-detection engine (`SignalEngine`) is on the roadmap for `1.1.0+`.

## Install

```bash
npm install @loop-engine/signals
```

## SignalRegistry

The current public surface is a registry that declares each signal's identity, optional Zod schema, and human-readable metadata. Runtime code uses it to look up and validate signal payloads.

```ts
class SignalRegistry {
  register(spec: SignalSpec): void
  get(signalId: SignalId): SignalSpec | undefined
  validatePayload(signalId: SignalId, payload: unknown): { valid: boolean; error?: string }
  list(): SignalSpec[]
}

interface SignalSpec {
  signalId: SignalId
  name: string
  description?: string
  schema?: ZodType
  tags?: string[]
}
```

```ts
import { z } from "zod"
import { SignalRegistry } from "@loop-engine/signals"
import { signalId } from "@loop-engine/core"

const registry = new SignalRegistry()
registry.register({
  signalId: signalId("expense.submitted"),
  name: "Expense submitted",
  description: "A user has submitted an expense report for review.",
  schema: z.object({
    amount: z.number().positive(),
    currency: z.string().length(3)
  })
})

const check = registry.validatePayload(signalId("expense.submitted"), {
  amount: 1200,
  currency: "USD"
})
// => { valid: true }
```

## SignalEngine (experimental, 1.1.0+)

<Callout variant="warning" title="Roadmap surface">
`SignalEngine`, `createSignalEngine()`, and the built-in rule factories listed below are slated for `1.1.0+` as experimental APIs and are **not** present in the current release. The shapes shown here are roadmap intent, not a contract — expect them to change before they ship.
</Callout>

```ts
interface SignalEngine {
  registerRule(rule: SignalRule): void
  process(events: LoopEvent[]): Signal[]
  subscribe(handler: (signal: Signal) => void): () => void
}

createSignalEngine(): SignalEngine
```

Planned built-in rule factories:

- `thresholdBreachRule(config: ThresholdRuleConfig): SignalRule`
- `stateDwellRule(config: StateDwellRuleConfig): SignalRule`
- `repeatedGuardFailureRule(config: RepeatedGuardFailureConfig): SignalRule`
- `loopNotStartedRule(config: LoopNotStartedConfig): SignalRule`

## Detection model

Signals are detections, not actors. Application code decides what to do with them — including whether to start or transition loops in response.


---

## @loop-engine/guards
URL: https://bossloops.io
/docs/packages/guards
Summary: GuardRegistry and deterministic guard functions enforce policy checks before transitions execute.
Section: Packages


`@loop-engine/guards` provides deterministic policy checks that run inside transition execution.

## Install

```bash
npm install @loop-engine/guards
```

## Guard model

Guards in this package are synchronous policy assertions wrapped as async functions. They do not call LLMs or network services.

`GuardResult`:

```ts
interface GuardResult {
  passed: boolean
  code?: string
  message?: string
  metadata?: Record<string, unknown>
}
```

## Registry API

```ts
class GuardRegistry {
  register(guardId: string, evaluator: GuardEvaluator): void
  get(guardId: string): GuardEvaluator | undefined
  registerBuiltIns(): void
}
```

`registerBuiltIns()` populates the registry with every guard exported from `@loop-engine/guards` (see "Built-in guards" below). Call it once on a fresh registry, or use the pre-populated `defaultRegistry` constant.

```ts
import { createGuardRegistry } from "@loop-engine/guards"
import { guardId } from "@loop-engine/core"

const registry = createGuardRegistry()
registry.register(guardId("budget_available"), {
  async evaluate(context) {
    return {
      passed: context.evidence?.budget_ok === true,
      message: "Budget check failed"
    }
  }
})
```

## Built-in guards

`defaultRegistry` (and `GuardRegistry.registerBuiltIns()`) pre-registers:

- `confidence-threshold` (`ConfidenceThresholdGuard`)
- `human-only` (`HumanOnlyGuard`)
- `evidence-required` (`EvidenceRequiredGuard`)
- `cooldown` (`CooldownGuard`)

## Hard and soft behavior

Hard/soft severity is defined on each `GuardSpec` in `@loop-engine/core`. Runtime blocks on hard failures and records soft failures under `_softGuardWarnings` in transition evidence.


---

## @loop-engine/actors
URL: https://bossloops.io
/docs/packages/actors
Summary: Actor types, authorization checks, and evidence helpers keep transition attribution explicit and enforceable.
Section: Packages


`@loop-engine/actors` models all five actor categories and provides transition authorization + evidence utilities.

## Install

```bash
npm install @loop-engine/actors
```

## Actor types

```ts
interface HumanActor extends ActorRef {
  type: "human"
  userId: string
  displayName: string
  roles?: string[]
}

interface AutomationActor extends ActorRef {
  type: "automation"
  serviceId: string
  version?: string
}

interface AIAgentActor extends ActorRef {
  type: "ai-agent"
  modelId: string
  provider: string
  confidence?: number
  promptHash?: string
  toolsUsed?: string[]
}
```

## Authorization

```ts
canActorExecuteTransition(
  actor: Actor,
  transition: TransitionSpec,
  constraints?: AIActorConstraints
): { authorized: boolean; requiresApproval: boolean; reason?: string }
```

`canActorExecuteTransition()` validates `transition.allowedActors` and the optional `AIActorConstraints.requiresHumanApprovalFor` list for `ai-agent` actors.

```ts
// @no-typecheck
import { canActorExecuteTransition } from "@loop-engine/actors"

const auth = canActorExecuteTransition(agentActor, transition)
if (!auth.authorized) {
  console.log(auth.reason)
}
```

## Evidence building

```ts
buildAIActorEvidence(params: {
  modelId: string
  provider: string
  reasoning: string
  confidence: number
  dataPoints?: Record<string, unknown>
  rawResponse?: unknown
  prompt?: string
}): Promise<AIAgentSubmission["evidence"] & { modelId: string; provider: string; promptHash?: string }>
```

Use `buildAIActorEvidence` when you have model metadata and need structured, attributable AI evidence to attach to a transition.

```ts
import { buildAIActorEvidence } from "@loop-engine/actors"

const evidence = await buildAIActorEvidence({
  modelId: "gpt-4o",
  provider: "openai",
  reasoning: "Demand spike at DC-East",
  confidence: 0.82,
  dataPoints: { recommended_qty: 500 }
})
```


---

## @loop-engine/adapter-anthropic
URL: https://bossloops.io
/docs/packages/adapter-anthropic
Summary: AI actor adapter for Claude (Anthropic) — wire Claude as a governed actor in any operational loop.
Section: Packages


**Runtime role:** [Provider](/docs/concepts/runtime-taxonomy#providers) · Developer: `ActorAdapter` · [Runtime connections](/docs/integrations/anthropic)

## Overview

`@loop-engine/adapter-anthropic` wraps the Anthropic Claude API as a Boss Loops AI actor. It handles prompt construction, response parsing, confidence extraction, and prompt hashing — returning an `AIAgentActor` and `AIAgentSubmission` ready for submission to the runtime. Guards run after the adapter returns. The adapter does not call `transition()` directly.

## Installation

```bash
npm install @loop-engine/adapter-anthropic @anthropic-ai/sdk
```

## Peer dependencies

```text
@anthropic-ai/sdk  ^0.39.0
```

## Basic usage

```typescript
// @no-typecheck
import Anthropic from '@anthropic-ai/sdk'
import { createAnthropicActorAdapter } from '@loop-engine/adapter-anthropic'
import { createLoopSystem } from '@loop-engine/sdk'

const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY })

const adapter = createAnthropicActorAdapter(anthropic, {
  modelId: 'claude-opus-4-6',
  confidenceThreshold: 0.75,
})

const loopSystem = await createLoopSystem({ loops: [] })
const aggregateId = 'procurement-1'

// Get the AI actor's decision for the current loop state
const { actor, decision } = await adapter.createSubmission({
  loopId: 'procurement',
  loopName: 'SCM Procurement',
  currentState: 'pending_analysis',
  availableSignals: [
    {
      signalId: 'submit_recommendation',
      name: 'Submit Recommendation',
      description: 'Submit a purchase order recommendation',
      allowedActors: ['ai-agent', 'automation'],
    },
  ],
  instruction: 'Analyze the demand data and recommend whether to issue a purchase order.',
  evidence: { demandForecast: 0.89, currentStock: 42, reorderPoint: 50 },
})

// Submit to the runtime — guards evaluate after this point
const result = await loopSystem.engine.transition({
  aggregateId,
  transitionId: decision.transitionId,
  actor,
  evidence: decision,
})
```

## Configuration reference

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `modelId` | `string` | `claude-opus-4-6` | Anthropic model to use |
| `maxTokens` | `number` | `1024` | Max tokens in response |
| `systemPrompt` | `string` | — | Optional system prompt prepended to loop context |
| `confidenceThreshold` | `number` | `0.7` | Minimum confidence required (0–1) |

## What the adapter produces

The adapter returns an `AIAgentActor` with:

- `type: "ai-agent"`
- `provider: "anthropic"`
- `modelId` — the model used
- `confidence` — extracted from the model response
- `promptHash` — SHA-256 of the prompt sent (for audit trail)

## Guard enforcement note

The confidence guard runs at the runtime level — not inside the adapter. If you configure a `confidence-threshold` guard on the transition, the runtime will block the transition if the model's confidence falls below the threshold regardless of what the adapter returns.

```typescript
// In your loop definition — this guard is structural, not prompt-based
{
  guardId: 'confidence-threshold',
  severity: 'hard',
  evaluatedBy: 'runtime',
  parameters: { threshold: 0.75 },
}
```

## Error handling

The adapter throws `ActorDecisionError` with one of these codes:

- `INVALID_SIGNAL` — model returned a signalId not in `availableSignals`
- `INVALID_CONFIDENCE` — confidence value outside 0–1 range
- `PARSE_FAILED` — model response could not be parsed as JSON
- `API_ERROR` — Anthropic API returned an error

## Links

- [View on npm](https://www.npmjs.com/package/@loop-engine/adapter-anthropic)
- [Source](https://github.com/loopengine/loop-engine/tree/main/packages/adapter-anthropic)
- Related: [AI as Actor concept](/docs/ai-and-automation/ai-as-actor), [@loop-engine/adapter-openai](/docs/packages/adapter-openai)


---

## @loop-engine/adapter-openai
URL: https://bossloops.io
/docs/packages/adapter-openai
Summary: AI actor adapter for GPT-4o and o-series models — wire OpenAI as a governed actor in any operational loop.
Section: Packages


## Overview

`@loop-engine/adapter-openai` wraps the OpenAI API as a Boss Loops AI actor using `response_format: { type: "json_object" }` for structured output. Same governance model as `adapter-anthropic` — identical guard enforcement, same audit trail, drop-in pattern for multi-model loops.

## Installation

```bash
npm install @loop-engine/adapter-openai openai
```

## Peer dependencies

```text
openai  ^4.0.0
```

## Basic usage

```typescript
// @no-typecheck
import OpenAI from 'openai'
import { createOpenAIActorAdapter } from '@loop-engine/adapter-openai'
import { createLoopSystem } from '@loop-engine/sdk'

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY })

const adapter = createOpenAIActorAdapter(openai, {
  modelId: 'gpt-4o',
  confidenceThreshold: 0.75,
})

const loopSystem = await createLoopSystem({ loops: [] })
const aggregateId = 'procurement-1'

// Get the AI actor's decision for the current loop state
const { actor, decision } = await adapter.createSubmission({
  loopId: 'procurement',
  loopName: 'SCM Procurement',
  currentState: 'pending_analysis',
  availableSignals: [
    {
      signalId: 'submit_recommendation',
      name: 'Submit Recommendation',
      description: 'Submit a purchase order recommendation',
      allowedActors: ['ai-agent', 'automation'],
    },
  ],
  instruction: 'Analyze the demand data and recommend whether to issue a purchase order.',
  evidence: { demandForecast: 0.89, currentStock: 42, reorderPoint: 50 },
})

// Submit to the runtime — guards evaluate after this point
const result = await loopSystem.engine.transition({
  aggregateId,
  transitionId: decision.transitionId,
  actor,
  evidence: decision,
})
```

## Configuration reference

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `modelId` | `string` | `gpt-4o` | OpenAI model to use |
| `maxTokens` | `number` | `1024` | Max tokens in response |
| `systemPrompt` | `string` | — | Optional system prompt prepended to loop context |
| `confidenceThreshold` | `number` | `0.7` | Minimum confidence required (0–1) |

## What the adapter produces

The adapter returns an `AIAgentActor` with:

- `type: "ai-agent"`
- `provider: "openai"`
- `modelId` — the model used
- `confidence` — extracted from the model response
- `promptHash` — SHA-256 of the prompt sent (for audit trail)

## Guard enforcement note

The confidence guard runs at the runtime level — not inside the adapter. If you configure a `confidence-threshold` guard on the transition, the runtime will block the transition if the model's confidence falls below the threshold regardless of what the adapter returns.

```typescript
// In your loop definition — this guard is structural, not prompt-based
{
  guardId: 'confidence-threshold',
  severity: 'hard',
  evaluatedBy: 'runtime',
  parameters: { threshold: 0.75 },
}
```

## Multi-model loops

Both adapters return the same `AIAgentActor` shape. You can use Claude for one transition and GPT-4o for another in the same loop — the runtime treats them identically. The `provider` and `modelId` fields on the actor record distinguish them in the audit trail.

```typescript
// @no-typecheck
// Claude handles analysis, GPT-4o handles summarization — same loop
const claudeActor = await claudeAdapter.createSubmission({ ... })
const openaiActor = await openaiAdapter.createSubmission({ ... })
```

## Error handling

The adapter throws `ActorDecisionError` with one of these codes:

- `INVALID_SIGNAL` — model returned a signalId not in `availableSignals`
- `INVALID_CONFIDENCE` — confidence value outside 0–1 range
- `PARSE_FAILED` — model response could not be parsed as JSON
- `API_ERROR` — OpenAI API returned an error

## Links

- [View on npm](https://www.npmjs.com/package/@loop-engine/adapter-openai)
- [Source](https://github.com/loopengine/loop-engine/tree/main/packages/adapter-openai)
- Related: [AI as Actor concept](/docs/ai-and-automation/ai-as-actor), [@loop-engine/adapter-anthropic](/docs/packages/adapter-anthropic)


---

## @loop-engine/adapter-gemini
URL: https://bossloops.io
/docs/packages/adapter-gemini
Summary: AI actor adapter for Google Gemini — wire Gemini 1.5 Pro/Flash as a governed actor in any operational loop.
Section: Packages


## Overview

`@loop-engine/adapter-gemini` wraps Google's Gemini API as a Boss Loops AI actor using the `@google/generative-ai` SDK. Unlike OpenAI-compatible adapters, Gemini uses Google's native SDK and response shape. The adapter applies the same governance model as other Boss Loops AI adapters: guard enforcement in runtime and consistent actor audit fields.

## Installation

```bash
npm install @loop-engine/adapter-gemini @google/generative-ai
```

## Peer dependencies

```text
@google/generative-ai  ^0.21.0
```

## Basic usage

```typescript
// @no-typecheck
import { createGeminiActorAdapter } from '@loop-engine/adapter-gemini'

const adapter = createGeminiActorAdapter(process.env.GOOGLE_AI_API_KEY!, {
  modelId: 'gemini-1.5-pro',
  confidenceThreshold: 0.75,
})

const { actor, decision } = await adapter.createSubmission({
  loopId: 'procurement',
  loopName: 'SCM Procurement',
  currentState: 'pending_analysis',
  availableSignals: [
    {
      signalId: 'submit_recommendation',
      name: 'Submit Recommendation',
      allowedActors: ['ai-agent'],
    },
  ],
  instruction: 'Analyze demand data and recommend a purchase order decision.',
  evidence: { demandForecast: 0.87, currentStock: 45 },
})
```

## Configuration reference

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `modelId` | `string` | `gemini-1.5-pro` | Gemini model (`gemini-1.5-pro`, `gemini-1.5-flash`, `gemini-2.0-flash`) |
| `maxOutputTokens` | `number` | `1024` | Max tokens in response |
| `systemPrompt` | `string` | — | Prepended to the system instruction |
| `confidenceThreshold` | `number` | `0.7` | Minimum confidence required (0-1) |

## What the adapter produces

The adapter returns an `AIAgentActor` with:

- `type: "ai-agent"`
- `provider: "gemini"`
- `modelId` — the model used
- `confidence` — extracted from the model response
- `promptHash` — SHA-256 of the prompt sent (for audit trail)

## Note on JSON parsing

Gemini 1.5 occasionally wraps JSON responses in markdown code fences despite system instructions. The adapter strips these automatically before parsing. This cleanup becomes unnecessary in a later version that switches to `responseMimeType: "application/json"`.

## Guard enforcement note

The confidence guard runs at the runtime level — not inside the adapter. If you configure a `confidence-threshold` guard on the transition, the runtime will block the transition if the model's confidence falls below the threshold regardless of what the adapter returns.

```typescript
// In your loop definition — this guard is structural, not prompt-based
{
  guardId: 'confidence-threshold',
  severity: 'hard',
  evaluatedBy: 'runtime',
  parameters: { threshold: 0.75 },
}
```

## Error handling

The adapter throws `ActorDecisionError` with one of these codes:

- `INVALID_SIGNAL` — model returned a signalId not in `availableSignals`
- `INVALID_CONFIDENCE` — confidence value outside 0–1 range
- `PARSE_FAILED` — model response could not be parsed as JSON
- `API_ERROR` — Gemini API returned an error (message prefixed with `[loop-engine/adapter-gemini]`)

## Multi-model loops

All four adapters (`adapter-anthropic`, `adapter-openai`, `adapter-grok`, and `adapter-gemini`) return the same `AIAgentActor` shape. You can use different providers for different transitions in the same loop, while `provider` and `modelId` distinguish them in the audit trail.

## Links

- [View on npm](https://www.npmjs.com/package/@loop-engine/adapter-gemini)
- [Source](https://github.com/loopengine/loop-engine/tree/main/packages/adapter-gemini)
- Related: [AI as Actor concept](/docs/ai-and-automation/ai-as-actor), [Google AI Studio](https://aistudio.google.com)


---

## @loop-engine/adapter-grok
URL: https://bossloops.io
/docs/packages/adapter-grok
Summary: AI actor adapter for Grok (xAI) — wire Grok as a governed actor using xAI's OpenAI-compatible API.
Section: Packages


## Overview

`@loop-engine/adapter-grok` wraps xAI's Grok API as a Boss Loops AI actor. Grok uses an OpenAI-compatible API, and this adapter uses the `openai` npm package pointed at `https://api.x.ai/v1`. It follows the same governance model as `adapter-anthropic` and `adapter-openai`: identical guard enforcement and the same audit trail shape.

## Installation

```bash
npm install @loop-engine/adapter-grok openai
```

## Peer dependencies

```text
openai  ^4.0.0
```

## Basic usage

```typescript
// @no-typecheck
import OpenAI from 'openai'
import { createGrokActorAdapter } from '@loop-engine/adapter-grok'

// Grok uses the OpenAI SDK with xAI's base URL
const grok = new OpenAI({
  apiKey: process.env.XAI_API_KEY,
  baseURL: 'https://api.x.ai/v1',
})

const adapter = createGrokActorAdapter(process.env.XAI_API_KEY!, {
  modelId: 'grok-3',
  confidenceThreshold: 0.75,
})

const { actor, decision } = await adapter.createSubmission({
  loopId: 'procurement',
  loopName: 'SCM Procurement',
  currentState: 'pending_analysis',
  availableSignals: [
    {
      signalId: 'submit_recommendation',
      name: 'Submit Recommendation',
      allowedActors: ['ai-agent'],
    },
  ],
  instruction: 'Analyze demand data and recommend a purchase order decision.',
  evidence: { demandForecast: 0.91, currentStock: 38 },
})
```

## Configuration reference

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `modelId` | `string` | `grok-3` | Grok model to use (`grok-2`, `grok-2-mini`, `grok-3`, `grok-3-mini`) |
| `maxTokens` | `number` | `1024` | Max tokens in response |
| `systemPrompt` | `string` | — | Optional system prompt prepended to loop context |
| `confidenceThreshold` | `number` | `0.7` | Minimum confidence required (0-1) |
| `baseURL` | `string` | `https://api.x.ai/v1` | xAI API endpoint (override for testing) |

## What the adapter produces

The adapter returns an `AIAgentActor` with:

- `type: "ai-agent"`
- `provider: "grok"`
- `modelId` — the model used
- `confidence` — extracted from the model response
- `promptHash` — SHA-256 of the prompt sent (for audit trail)

## Guard enforcement note

The confidence guard runs at the runtime level — not inside the adapter. If you configure a `confidence-threshold` guard on the transition, the runtime will block the transition if the model's confidence falls below the threshold regardless of what the adapter returns.

```typescript
// In your loop definition — this guard is structural, not prompt-based
{
  guardId: 'confidence-threshold',
  severity: 'hard',
  evaluatedBy: 'runtime',
  parameters: { threshold: 0.75 },
}
```

## Error handling

The adapter throws `ActorDecisionError` with one of these codes:

- `INVALID_SIGNAL` — model returned a signalId not in `availableSignals`
- `INVALID_CONFIDENCE` — confidence value outside 0–1 range
- `PARSE_FAILED` — model response could not be parsed as JSON
- `API_ERROR` — xAI API returned an error (message prefixed with `[loop-engine/adapter-grok]`)

## Multi-model loops

All four adapters (`adapter-anthropic`, `adapter-openai`, `adapter-grok`, and `adapter-gemini`) return the same `AIAgentActor` shape. You can use different providers for different transitions in the same loop, while `provider` and `modelId` distinguish them in the audit trail.

## Links

- [View on npm](https://www.npmjs.com/package/@loop-engine/adapter-grok)
- [Source](https://github.com/loopengine/loop-engine/tree/main/packages/adapter-grok)
- Related: [AI as Actor concept](/docs/ai-and-automation/ai-as-actor), [@loop-engine/adapter-openai](/docs/packages/adapter-openai)


---

## @loop-engine/adapter-perplexity
URL: https://bossloops.io
/docs/packages/adapter-perplexity
Summary: Perplexity Sonar adapter — grounded retrieval with citations for Loop steps that need verifiable, real-time information.
Section: Packages


<Callout variant="warning" title="Release candidate">
  This package is staged for publication. Do not treat it as available on npm until its RC moves from **Draft** to **Locked**. The integration pattern in [Governed Incident Response with Perplexity and PagerDuty](/docs/integrations/perplexity-pagerduty) is safe to document independently.
</Callout>

## Overview

`@loop-engine/adapter-perplexity` wraps the Perplexity Sonar chat API as a Boss Loops `ToolAdapter`. Sonar adds grounded web retrieval with cited sources. You use it for Loop steps that need real-time, verifiable information — regulatory lookups, compliance research, supplier or market news. It is not a general-purpose generation adapter; for broad LLM actor flows, use [Anthropic](/docs/packages/adapter-anthropic) or [OpenAI](/docs/packages/adapter-openai) actor adapters.

## Installation

```bash
npm install @loop-engine/adapter-perplexity
```

## Configuration

```typescript
import { PerplexityAdapter } from "@loop-engine/adapter-perplexity";

const adapter = new PerplexityAdapter({
  apiKey: process.env.PERPLEXITY_API_KEY,
  defaultModel: "sonar-pro", // sonar | sonar-pro | sonar-reasoning | sonar-reasoning-pro
  defaultSearchRecency: "month", // day | week | month
  timeout: 30_000,
  retries: 3,
});
```

## Basic usage

```typescript
import { PerplexityAdapter } from "@loop-engine/adapter-perplexity";
import type { AdapterInput } from "@loop-engine/core";

const adapter = new PerplexityAdapter({ apiKey: process.env.PERPLEXITY_API_KEY! });

const input: AdapterInput = {
  prompt:
    "What are the HIPAA breach notification requirements for PHI accessed outside approved hours?",
  model: "sonar-pro",
  metadata: {
    returnCitations: true,
    searchDomainFilter: ["hhs.gov", "nist.gov"],
    searchRecencyFilter: "month",
  },
};

const result = await adapter.invoke(input);

console.log(result.text); // Sonar answer text
console.log(result.citations); // { url, title, snippet }[]
```

## Citation handling

Citations are a first-class output on `SonarResult`. Each entry includes `url`, `title`, and `snippet` (for example derived from search metadata).

```typescript
const result = await adapter.invoke({
  prompt: "Summarize recent FDA guidance on AI/ML SaMD change control.",
  metadata: { returnCitations: true, searchRecencyFilter: "month" },
});

for (const citation of result.citations) {
  console.log(citation.url);
  console.log(citation.title);
}
```

<Callout variant="important" title="Compliance evidence">
  Always persist citations to your Loop audit trail. A Sonar result without citations is an unverifiable AI output — citations are the compliance evidence.
</Callout>

## Supported models

| Model | Use case | Speed |
| --- | --- | --- |
| `sonar` | Fast retrieval, change detection | Fastest |
| `sonar-pro` | Research, regulatory lookup | Fast |
| `sonar-reasoning` | Multi-step analysis | Medium |
| `sonar-reasoning-pro` | Policy classification, complex inference | Slower |

## guardEvidence

`PerplexityAdapter` implements `guardEvidence` from `@loop-engine/core`, masking `pplx-*` API keys (and common secret field names) in payloads you log or export. You do not configure this — call `adapter.guardEvidence(payload)` before persisting raw request/response objects.

## Error handling

| Error | Retryable | Description |
| --- | --- | --- |
| `PerplexityAdapterError` (400) | No | Bad prompt or parameter |
| `PerplexityAdapterError` (401) | No | Invalid or missing API key |
| `RateLimitError` (429) | Yes | Exponential backoff, up to `retries` (default 3) |
| `PerplexityAdapterError` (500, 503) | Yes | Upstream or service errors — same backoff |
| Timeout / network | Yes | Treated like a retryable failure when attempts remain |

## Environment variables

```text
PERPLEXITY_API_KEY=pplx-...
PERPLEXITY_BASE_URL=https://api.perplexity.ai   # optional
PERPLEXITY_DEFAULT_MODEL=sonar-pro               # optional
```

## Links

- [Source](https://github.com/loopengine/loop-engine/tree/main/packages/adapter-perplexity)
- Related: [Perplexity integration overview](/docs/integrations/perplexity), [PagerDuty](/docs/integrations/pagerduty), [Governed incident response guide](/docs/integrations/perplexity-pagerduty)


---

## @loop-engine/adapter-openclaw
URL: https://bossloops.io
/docs/packages/adapter-openclaw
Summary: OpenClaw gateway EventBus adapter that forwards Boss Loops lifecycle events to OpenClaw-connected messaging channels.
Section: Packages


**Runtime role:** [Channel](/docs/concepts/runtime-taxonomy#channels) · Developer: `EventBus` routing · [Runtime connections](/docs/integrations/openclaw)

## Overview

`@loop-engine/adapter-openclaw` wraps an internal event bus and forwards selected loop events to OpenClaw over its WebSocket gateway control plane.

## Install

```bash
npm install @loop-engine/adapter-openclaw ws
```

## Prerequisites

- OpenClaw gateway reachable at `ws://127.0.0.1:18789`
- Configured OpenClaw channel and target destination

## createLoopSystem usage

`createLoopSystem` always wires an in-memory `InMemoryEventBus` today. To forward events to OpenClaw, wrap the bus returned from `createLoopSystem` with `OpenClawEventBus`:

```ts
import { createLoopSystem } from '@loop-engine/sdk'
import { OpenClawEventBus } from '@loop-engine/adapter-openclaw'
import { LoopBuilder } from '@loop-engine/sdk'

const loop = LoopBuilder
  .create('demo.forward', 'demo')
  .state('A', { isTerminal: true })
  .initialState('A')
  .outcome({
    id: 'done',
    description: 'done',
    valueUnit: 'done',
    businessMetrics: [{ id: 'm_done', label: 'Done', unit: 'count' }]
  })
  .build()

const { eventBus: inner } = await createLoopSystem({ loops: [loop] })

const forward = new OpenClawEventBus(inner, {
  channel: 'whatsapp',
  target: '+15551234567',
  events: ['loop.transition.executed', 'loop.completed'],
  approvalStates: ['PENDING_BUYER_APPROVAL']
})
void forward
```

## OpenClawAdapterOptions

```ts
interface OpenClawAdapterOptions {
  gatewayUrl?: string // default: ws://127.0.0.1:18789
  channel: string
  target: string
  accountId?: string
  events?: string[] // default: ['loop.transition.executed','loop.completed','loop.guard.failed']
  loopIds?: string[] // default: []
  approvalStates?: string[] // default: []
  inner?: EventBus // default: new InMemoryEventBus()
  autoReconnect?: boolean // default: true
  reconnectDelay?: number // default: 5000
}
```

## Approval state detection

The adapter marks a transition event as approval-required when `toState` matches `PENDING|APPROVAL` unless explicit `approvalStates` are configured.

## Lifecycle cleanup

Call `disconnect()` during shutdown to stop reconnect timers and close the current socket cleanly.

## Related example

See [OpenClaw Integration](/docs/examples/openclaw) for the end-to-end approval flow.


---

## @loop-engine/adapter-memory
URL: https://bossloops.io
/docs/packages/adapter-memory
Summary: MemoryStore provides zero-config LoopStore persistence for local development, tests, and browser demos.
Section: Packages


`@loop-engine/adapter-memory` stores loop state and transition history in process memory.

## Install

```bash
npm install @loop-engine/adapter-memory
```

## Store API

```ts
class MemoryStore implements LoopStore {
  getInstance(aggregateId: AggregateId): Promise<LoopInstance | null>
  saveInstance(instance: LoopInstance): Promise<void>
  getTransitionHistory(aggregateId: AggregateId): Promise<TransitionRecord[]>
  saveTransitionRecord(record: TransitionRecord): Promise<void>
  listOpenInstances(loopId: LoopId): Promise<LoopInstance[]>
}

memoryStore(): LoopStore
```

## SDK wiring

```ts
// @no-typecheck
import { memoryStore } from "@loop-engine/adapter-memory"
import { createLoopSystem } from "@loop-engine/sdk"

const { engine } = await createLoopSystem({
  loops: [definition],
  store: memoryStore()
})
```

## Runtime limits

State resets when the process restarts. Use this adapter for development, test suites, and ephemeral demos.


---

## @loop-engine/adapter-postgres
URL: https://bossloops.io
/docs/packages/adapter-postgres
Summary: createSchema provisions PostgreSQL tables and postgresStore provides a production LoopStore backed by node-postgres.
Section: Packages


**Runtime role:** [Integration](/docs/concepts/runtime-taxonomy#integrations) · Developer: `LoopStore` · [Runtime connections](/docs/integrations/postgres)

`@loop-engine/adapter-postgres` provides schema setup and a concrete PostgreSQL `LoopStore` for runtime persistence.

## Install

```bash
npm install @loop-engine/adapter-postgres pg
```

## Schema bootstrap

```ts
createSchema(pool: PgPoolLike): Promise<void>
```

`createSchema()` creates:

- `loop_instances`
- `loop_transitions`

```ts
import { Pool } from "pg"
import { createSchema } from "@loop-engine/adapter-postgres"

const pool = new Pool({ connectionString: process.env.DATABASE_URL })
await createSchema(pool)
```

## Store factory

```ts
postgresStore(pool: PgPoolLike): LoopStore
```

`postgresStore()` implements all `LoopStore` methods:

- `getInstance`
- `saveInstance`
- `getTransitionHistory`
- `saveTransitionRecord`
- `listOpenInstances`

## Production notes

- Use `pg` connection pooling.
- Keep SSL, idle timeout, and max connection settings explicit in deployment config.
- Run `createSchema()` during provisioning before serving runtime traffic.


---

## @loop-engine/adapter-kafka
URL: https://bossloops.io
/docs/packages/adapter-kafka
Summary: kafkaEventBus bridges Boss Loops events to Kafka topics for distributed consumers and durable streaming.
Section: Packages


`@loop-engine/adapter-kafka` implements the runtime `EventBus` interface on top of a Kafka-like producer/consumer client.

## Install

```bash
npm install @loop-engine/adapter-kafka kafkajs
```

## Event bus factory

```ts
kafkaEventBus(options: {
  kafka: KafkaLike
  topic: string
  groupId?: string
}): EventBus
```

- `emit()` sends serialized `LoopEvent` payloads to `options.topic`.
- `subscribe()` starts a consumer with `groupId` (default: `loopengine`) and forwards parsed messages to the handler.

```ts
import { Kafka } from "kafkajs"
import { kafkaEventBus } from "@loop-engine/adapter-kafka"

const kafka = new Kafka({ brokers: ["localhost:9092"] })
// kafkajs `producer().send` return type is wider than the adapter's `KafkaLike` stub; emit path is compatible.
const bus = kafkaEventBus({ kafka: kafka as any, topic: "loop-events", groupId: "loopengine-docs" })
```

## Topic strategy

Use one topic per environment or domain boundary to keep replay and retention policies explicit.


---

## @loop-engine/adapter-http
URL: https://bossloops.io
/docs/packages/adapter-http
Summary: httpEventBus forwards Boss Loops events to external webhooks with lightweight retry behavior.
Section: Packages


`@loop-engine/adapter-http` sends runtime events to an outbound webhook endpoint.

## Install

```bash
npm install @loop-engine/adapter-http
```

## Event bus factory

```ts
httpEventBus(options: {
  webhookUrl: string
  headers?: Record<string, string>
  retries?: number
}): EventBus
```

- `emit()` posts JSON payloads to `webhookUrl`.
- Retries default to `3`, with exponential backoff.
- `subscribe()` throws because this adapter is push-only.

```ts
import { httpEventBus } from "@loop-engine/adapter-http"

const bus = httpEventBus({
  webhookUrl: "https://hooks.example.com/loop-events",
  headers: { Authorization: "Bearer webhook-token" },
  retries: 3
})
```

## Delivery model

Use this adapter for outbound integrations (webhooks, automation tools, monitoring sinks) where event replay is handled outside Boss Loops.


---

## @loop-engine/adapter-commerce-gateway
URL: https://bossloops.io
/docs/packages/adapter-commerce-gateway
Summary: LLM Commerce Gateway adapter that builds governed AI actors from live commerce data while keeping writes behind approval transitions.
Section: Packages


## Install

```bash
npm install @loop-engine/adapter-commerce-gateway
```

Install one LLM SDK based on provider choice:

```bash
npm install @anthropic-ai/sdk
# or
npm install openai
```

## Prerequisites

- `COMMERCE_GATEWAY_URL`
- `COMMERCE_GATEWAY_API_KEY`

## CommerceGatewayClient

```ts
const client = new CommerceGatewayClient({
  baseUrl: process.env.COMMERCE_GATEWAY_URL!,
  apiKey: process.env.COMMERCE_GATEWAY_API_KEY!
})
```

Methods:

- `getInventory(sku)`
- `getInventoryBatch(skus)`
- `getDemandForecast(sku, horizon?)`
- `getSuppliers(sku)`
- `getCurrentPrice(sku)`
- `getPriceHistory(sku, days)`
- `createPurchaseOrder(order)` (write operation; post-approval only)
- `recordLoopOutcome(outcome)` (optional endpoint support by deployment)

## buildProcurementActor

```ts
const actor = buildProcurementActor({
  gatewayClient: client,
  llmProvider: 'openai',
  apiKey: process.env.OPENAI_API_KEY!,
  confidenceThreshold: 0.8
})
```

Returns `async (context) => Evidence`, where `context.instance.data.sku` drives Gateway queries and the actor returns evidence for a guarded transition.

## Evidence shape

```ts
type ProcurementEvidence = {
  recommendedSku: string
  recommendedQty: number
  estimatedCost: number
  supplierId: string
  confidence: number
  rationale: string
  gatewayRequestIds: string[]
  modelUsed: string
  timestamp: string
  _confidence: number
}
```

## Read vs write boundary

AI actor functions in this package call read endpoints only. Order creation stays in automation flows after a human approval transition passes guard checks.

## buildPricingActor

<Callout variant="warning">Coming in v0.2: `buildPricingActor` currently throws a pending implementation error.</Callout>

## Related example

See [LLM Commerce Gateway Integration](/docs/examples/commerce-gateway) for the end-to-end procurement flow.


---

## @loop-engine/observability
URL: https://bossloops.io
/docs/packages/observability
Summary: Metrics, timeline, and replay helpers turn loop history into audit and performance insights.
Section: Packages


`@loop-engine/observability` converts instance + transition data into metrics and replayable timelines.

## Install

```bash
npm install @loop-engine/observability
```

## Metrics

```ts
interface LoopMetrics {
  loopId: LoopId
  period: { from: string; to: string }
  totalInstances: number
  openInstances: number
  closedInstances: number
  errorInstances: number
  avgDurationMs: number
  medianDurationMs: number
  p95DurationMs: number
  completionRate: number
  guardFailureRate: number
  aiActorRate: number
  humanActorRate: number
  avgTransitionCount: number
}

declare function computeMetrics(
  instances: LoopInstance[],
  history: TransitionRecord[],
  period: { from: string; to: string }
): LoopMetrics
```

The open/closed/error instance counters reflect `LoopStatus` groupings: `openInstances` counts `pending | active | suspended`, `closedInstances` counts `completed | cancelled`, and `errorInstances` counts `failed`.

```ts
// @no-typecheck
import { computeMetrics } from "@loop-engine/observability"

const metrics = computeMetrics(instances, history, {
  from: "2026-03-01T00:00:00.000Z",
  to: "2026-03-31T23:59:59.999Z"
})
```

## Timeline

```ts
declare function buildTimeline(
  instance: LoopInstance,
  history: TransitionRecord[]
): LoopTimeline

declare function getStateResidency(
  timeline: LoopTimeline
): StateResidency[]
```

`LoopTimeline` surfaces the ordered sequence of state entries and transitions for a single instance; `StateResidency` reports total duration spent in each state. Use them to power audit UIs and state-duration debugging.

## Replay

```ts
declare function replayLoop(
  definition: LoopDefinition,
  history: TransitionRecord[]
): { valid: boolean; errors: string[] }
```

Replay verifies that recorded transitions are valid against the current loop definition.


---

## @loop-engine/registry-client
URL: https://bossloops.io
/docs/packages/registry-client
Summary: Local and HTTP adapters for the loop catalog — load LoopDefinition objects, with Better Data support behind a subpath export.
Section: Packages


**Archetype:** [Registry](/docs/concepts/integration-adapter#registry-adapter) — implements `LoopRegistry`, slotted at `options.registry` on `LoopEngineOptions` / `createLoopSystem`.

**Terminology:** In product docs we call this the **loop catalog** (versioned loop definitions for Boss Loops). The npm package remains `@loop-engine/registry-client` and TypeScript types still use the name `LoopRegistry`. That is **not** the [Commerce Gateway Registry](https://commercegateway.io/registry) (gateway discovery and verification).

`@loop-engine/registry-client` provides local-first loop definition lookup with optional network adapters.

## Install

```bash
npm install @loop-engine/registry-client
```

## Local catalog

```ts
// @no-typecheck
import { localRegistry } from "@loop-engine/registry-client"

const registry = localRegistry({
  definitions: [customLoop],
  loopsDir: "./loops",
  watch: true
})
```

- `definitions` works in browser and Node.
- `loopsDir` loads `.yaml`, `.yml`, and `.json` definitions in Node.
- Browser usage with `loopsDir` logs a warning and ignores filesystem mode.

## HTTP catalog

```ts
import { httpRegistry } from "@loop-engine/registry-client"

const registry = httpRegistry({
  baseUrl: "https://registry.example.com",
  headers: { Authorization: `Bearer ${token}` },
  timeoutMs: 10_000,
  retries: 2
})
```

Expected server contract:

- `GET /loops`
- `GET /loops?domain={domain}`
- `GET /loops/{loopId}`
- `GET /loops/{loopId}/{version}`
- `POST /loops`
- `DELETE /loops/{loopId}`

## Better Data adapter

```ts
import { betterDataRegistry } from "@loop-engine/registry-client/betterdata"

const registry = betterDataRegistry({
  apiKey: process.env.BD_API_KEY!,
  orgId: "your-org-id",
  env: "production"
})
```

<Callout variant="info">
The Better Data adapter is intentionally excluded from the main package entrypoint. Import it from `@loop-engine/registry-client/betterdata`.
</Callout>

## `LoopRegistry` interface

The runtime type is still named `LoopRegistry`:

```ts
interface LoopRegistry {
  get(id: LoopId): Promise<LoopDefinition | null>
  getVersion(id: LoopId, version: string): Promise<LoopDefinition | null>
  list(options?: { domain?: string }): Promise<LoopDefinition[]>
  has(id: LoopId): Promise<boolean>
  register(definition: LoopDefinition, options?: { force?: boolean }): Promise<void>
  remove(id: LoopId): Promise<boolean>
}
```

## SDK integration

`createLoopSystem({ loops, registry })` merges **catalog** results with local loops. Local `loops[]` definitions override matching catalog IDs, and catalog load failures fall back to local-only startup.

## Error classes

The package exports three typed errors. Catch by class to distinguish missing definitions from conflicts and from network/IO failures.

```ts
import {
  RegistryNotFoundError,
  RegistryConflictError,
  RegistryNetworkError
} from "@loop-engine/registry-client"
```

### RegistryNotFoundError

Thrown by `get()` and `getVersion()` when a loop (or specific version) is not found. Exposes `loopId` and optional `version`.

### RegistryConflictError

Thrown by `register()` when a loop with the same `loopId@version` already exists. Pass `{ force: true }` (development only) to overwrite. Exposes `loopId` and `version`.

### RegistryNetworkError

Thrown by `httpRegistry` and the Better Data adapter on network or HTTP failures. Exposes `url`, optional `statusCode`, and the underlying `cause` when available.

```ts
try {
  await registry.register(definition)
} catch (error) {
  if (error instanceof RegistryConflictError) {
    console.warn(`Already registered: ${error.loopId}@${error.version}`)
    return
  }
  throw error
}
```


---

## @loop-engine/ui-devtools
URL: https://bossloops.io
/docs/packages/ui-devtools
Summary: React devtools components for visualizing loop state, timelines, events, and local diagnostics.
Section: Packages


# @loop-engine/ui-devtools

React components for local loop debugging and visualization.

## Install

```bash
npm install @loop-engine/ui-devtools
```

Peer dependencies:

- `react` (`^18 || ^19`)
- `react-dom` (`^18 || ^19`)

## API reference

Exported components:

- `LoopStateBadge`
- `ActorBadge`
- `LoopTimeline`
- `StateDiagram`
- `EventStream`
- `MetricsCard`
- `DevtoolsPanel`

Example:

```tsx
import { DevtoolsPanel } from '@loop-engine/ui-devtools'

export function Page() {
  return <DevtoolsPanel apiUrl="http://localhost:3000/api" />
}
```

`DevtoolsPanel` returns `null` unless `NODE_ENV === "development"`.

## Related packages

- Depends on core, events, observability


---

## All Packages
URL: https://bossloops.io
/docs/packages/all-packages
Summary: Boss Loops publishes modular packages for authoring, runtime execution, events, guards, adapters, and tooling.
Section: Packages


# All packages

The Boss Loops monorepo publishes the following packages:

- [`@loop-engine/sdk`](/docs/packages/sdk)
- [`@loop-engine/core`](/docs/packages/core)
- [`@loop-engine/loop-definition`](/docs/packages/loop-definition)
- [`@loop-engine/runtime`](/docs/packages/runtime)
- [`@loop-engine/events`](/docs/packages/events)
- [`@loop-engine/guards`](/docs/packages/guards)
- [`@loop-engine/actors`](/docs/packages/actors)
- [`@loop-engine/signals`](/docs/packages/signals)
- [`@loop-engine/observability`](/docs/packages/observability)
- [`@loop-engine/registry-client`](/docs/packages/registry-client)
- [`@loop-engine/ui-devtools`](/docs/packages/ui-devtools)
- [`@loop-engine/adapter-memory`](/docs/packages/adapter-memory)
- [`@loop-engine/adapter-postgres`](/docs/packages/adapter-postgres)
- [`@loop-engine/adapter-kafka`](/docs/packages/adapter-kafka)
- [`@loop-engine/adapter-http`](/docs/packages/adapter-http)

<Callout variant="info" title="Start here">
Most users should start with `@loop-engine/sdk`, then move to package-specific imports only when they need custom wiring.
</Callout>


---

## Loop catalog
URL: https://bossloops.io
/docs/catalog
Summary: Discovery and trust layer for governed Boss Loops definitions — not related to the Commerce Gateway Registry.
Section: Loop catalog


The **Boss Loops catalog** at `registry.betterdata.co` is the discovery layer for governed loop definitions.
We call it a **catalog** to distinguish it from registries in other products (for example, the [Commerce Gateway Registry](https://commercegateway.io/registry), which handles gateway discovery and domain verification under the Commerce Registry Protocol).

Think of the loop catalog as **npm for reusable governed loops** — policy-gated operational definitions you can install and compose: same versioning model, same CLI ergonomics (planned), plus semantic search instead of keyword-only search.

## Trust model

The catalog uses three trust tiers:

1. **Core** — Boss Loops maintained definitions.
2. **Verified Partner** — signed publisher identity with reviewed definitions.
3. **Community** — open publish surface, use-at-own-risk.

## Security properties

Every published loop definition declares its actor types, guard registrations, transition surface, and external service calls in a machine-readable manifest.
This is designed to prevent hidden behavior and make review/audit straightforward.

## CLI preview (coming soon)

```bash
loop catalog search "hipaa approval"
loop catalog install @betterdata/loops-healthcare
loop catalog publish
```

<Callout variant="info" title="Private beta">
  The catalog is in private beta. Join the waitlist at <a href="https://loopengine.io/catalog" target="_blank" rel="noreferrer">loopengine.io/catalog</a>.
</Callout>


---

## Examples
URL: https://bossloops.io
/docs/examples
Summary: Runtime flow patterns — Provider, Loop + Guards, Channel, Integration, Evidence — not integration catalogs or chatbot demos.
Section: Examples


Examples teach **how governed operational decisions move through the runtime**, not how to wire a single adapter. Each pattern names **who** may transition state, **what evidence** is required, and **where humans** intervene — before any side effect reaches an operational system.

→ [Runtime Taxonomy](/docs/concepts/runtime-taxonomy) · [Architecture](/docs/getting-started/architecture) · [Boss Loops vs Workflow Engines](/docs/concepts/loop-engine-vs-workflow-engines)

## Canonical runtime flow

Every priority pattern on this page follows the same spine:

```text
Provider (intelligence)
        ↓
Loop + Guards (governance)
        ↓
Channel (human surface)
        ↓
Integration (operational system)
        ↓
Evidence (audit + learning)
```

**Providers** (intelligence systems) recommend or classify — they do not commit transitions alone. **Guards** enforce deterministic policy before state changes. **Channels** (human coordination) are where operators approve, reject, or escalate — not where CRM writes occur. **Integrations** (systems of record) persist state and execute side effects after approval. **Evidence** explains *why* each transition was allowed.

| Layer | Role in examples |
| --- | --- |
| Provider | Score, draft, classify |
| Channel | Slack, Teams, doc review |
| Integration | Salesforce, Sheets apply, PagerDuty, MAP |

<Callout variant="warning" title="What these examples are not">
They are **not** simple automation recipes, chatbot demos, or “agent magic” that skips policy. Boss Loops governs **whether** a transition commits; workflow engines and apps **execute** work after approval.
</Callout>

## What examples demonstrate

| Principle | In practice |
| --- | --- |
| **Governance** | `human-only`, `confidence-threshold`, `evidence-required` guards block unauthorized transitions |
| **Evidence** | Structured fields on every material transition — not reconstructed logs |
| **Deterministic boundaries** | Guards are runtime checks, not prompt instructions |
| **Human escalation** | Low confidence or high risk → `PENDING_*` states routed to a **Channel** |
| **AI assistance** | Providers submit **recommendations** inside the loop — never self-approve |

## ABM and RevOps operational AI

<span id="abm-revops-operational-ai" className="sr-only" aria-hidden="true" />

GTM and revenue operations are where **operational AI** needs runtime governance: models draft and score, humans decide in Slack, systems of record update after policy passes.

<div className="grid gap-4 md:grid-cols-2">
  <article style={{ border: "1px solid var(--color-border)", borderRadius: 12, padding: 16 }}>
    <h3><a href="/docs/examples/sdr-qualification-loop">SDR qualification loop</a></h3>
    <p>Provider scores inbound lead → Slack escalation → SDR approves → CRM updated.</p>
    <p><strong>Layers:</strong> Provider · Channel (Slack) · Integration (CRM)</p>
  </article>
  <article style={{ border: "1px solid var(--color-border)", borderRadius: 12, padding: 16 }}>
    <h3><a href="/docs/examples/proposal-approval-loop">Proposal approval loop</a></h3>
    <p>AI drafts in Google Docs → sales/legal approve in Slack → Salesforce advances.</p>
    <p><strong>Dual-surface:</strong> Docs (work) + Slack (decisions)</p>
  </article>
  <article style={{ border: "1px solid var(--color-border)", borderRadius: 12, padding: 16 }}>
    <h3><a href="/docs/examples/campaign-approval-loop">Campaign approval loop</a></h3>
    <p>Outbound copy generation → brand/compliance guards → Slack → MAP executes.</p>
  </article>
  <article style={{ border: "1px solid var(--color-border)", borderRadius: 12, padding: 16 }}>
    <h3><a href="/docs/examples/pricing-exception-loop">Pricing exception loop</a></h3>
    <p>Sheets staging → finance approval in Slack → ERP/CRM apply with evidence.</p>
  </article>
</div>

## Dual-surface and platform patterns

<div className="grid gap-4 md:grid-cols-2">
  <article style={{ border: "1px solid var(--color-border)", borderRadius: 12, padding: 16 }}>
    <h3><a href="/docs/examples/dual-surface-docs-slack">Google Docs + Slack</a></h3>
    <p>AI-generated proposal in Docs → Slack approval → governed transition → apply path.</p>
    <p><strong>Flow:</strong> Provider → Loop + Guards → Channel (Slack) → Integration (Docs/Sheets)</p>
    <p><strong>Surface:</strong> Boss Loops Cloud · Narrative pattern</p>
  </article>

  <article style={{ border: "1px solid var(--color-border)", borderRadius: 12, padding: 16 }}>
    <h3><a href="/docs/examples/dual-surface-sheets-slack">Google Sheets + Slack</a></h3>
    <p>Spreadsheet staging → human approval in Slack → gated apply to Sheets.</p>
    <p><strong>Flow:</strong> Provider (optional) → Loop + Guards → Channel → Integration</p>
    <p><strong>Surface:</strong> Boss Loops Cloud · Narrative pattern</p>
  </article>

  <article style={{ border: "1px solid var(--color-border)", borderRadius: 12, padding: 16 }}>
    <h3><a href="/docs/examples/pagerduty-incident-loop">PagerDuty incident loop</a></h3>
    <p>AI classification + guarded escalation + PagerDuty alerting with audit trail.</p>
    <p><strong>Flow:</strong> Provider → Loop + Guards → Channel → Integration (PagerDuty)</p>
    <p><strong>Surface:</strong> OSS adapters · <a href="/docs/integrations/perplexity-pagerduty">integration guide</a></p>
  </article>

  <article style={{ border: "1px solid var(--color-border)", borderRadius: 12, padding: 16 }}>
    <h3><a href="/docs/examples/workflow-plus-loop">Workflow + Loop</a></h3>
    <p>Temporal or Salesforce durable steps with Boss Loops governing transitions.</p>
    <p><strong>Flow:</strong> Provider → Loop + Guards → Channel → Integration (workflow activity)</p>
    <p><strong>Surface:</strong> Narrative · complements workflow engines</p>
  </article>
</div>

## OSS runnable patterns

<Callout variant="info" title="Runnable source on GitHub">
Some patterns ship in <a href="https://github.com/loopengine/loop-examples" target="_blank" rel="noreferrer"><code>loopengine/loop-examples</code></a>. Pages marked <strong>Coming soon</strong> are architecture walkthroughs only — no implied clone-and-run repo.
</Callout>

```bash
git clone https://github.com/loopengine/loop-examples
cd loop-examples && pnpm install
```

<div className="grid gap-4 md:grid-cols-2">
  <article style={{ border: "1px solid var(--color-border)", borderRadius: 12, padding: 16 }}>
    <h3><a href="/docs/examples/ai-replenishment-claude">AI Replenishment (Claude)</a></h3>
    <p>Provider recommendation → confidence guard → human approval → order integration.</p>
    <p><strong>Runnable:</strong> Yes · <code>loop-examples/ai-actors/claude</code></p>
  </article>

  <article style={{ border: "1px solid var(--color-border)", borderRadius: 12, padding: 16 }}>
    <h3><a href="/docs/examples/infrastructure-change-approval">Infrastructure Change Approval</a></h3>
    <p>Provider blast-radius analysis → SRE Channel → rollout Integration.</p>
    <p><strong>Runnable:</strong> Coming soon</p>
  </article>

  <article style={{ border: "1px solid var(--color-border)", borderRadius: 12, padding: 16 }}>
    <h3><a href="/docs/examples/fraud-review">Fraud Review</a></h3>
    <p>Provider scoring → analyst Channel → case disposition with evidence.</p>
    <p><strong>Runnable:</strong> Coming soon</p>
  </article>

  <article style={{ border: "1px solid var(--color-border)", borderRadius: 12, padding: 16 }}>
    <h3><a href="/docs/examples/expense-approval">Expense Approval</a></h3>
    <p>Loop + Guards + human Channel — governance baseline without an AI Provider.</p>
    <p><strong>Runnable:</strong> Yes · <code>loop-examples/expense-approval</code></p>
  </article>

  <article style={{ border: "1px solid var(--color-border)", borderRadius: 12, padding: 16 }}>
    <h3><a href="/docs/examples/openclaw">OpenClaw Channel</a></h3>
    <p>Messenger Channel routing for <code>PENDING_HUMAN_APPROVAL</code> — OSS adapter.</p>
    <p><strong>Runnable:</strong> Pattern doc · see <a href="/docs/integrations/openclaw">OpenClaw integration</a></p>
  </article>

  <article style={{ border: "1px solid var(--color-border)", borderRadius: 12, padding: 16 }}>
    <h3><a href="/docs/examples/commerce-gateway">Commerce Gateway</a></h3>
    <p>Governed tool execution — Integration after policy passes (not a Provider).</p>
    <p><strong>Runnable:</strong> See integration + examples repo index</p>
  </article>
</div>

## Supporting patterns

| Pattern | Focus |
| --- | --- |
| [Demand Signal](/docs/examples/demand-signal) | Signals → loop start (no Provider) |
| [Postgres Persistence](/docs/examples/postgres-persistence) | Integration (`LoopStore`) swap |
| [Event Streaming](/docs/examples/event-streaming) | Evidence via event timeline |
| [AI Replenishment (OpenAI)](/docs/examples/ai-replenishment-openai) | Same flow as Claude — adapter swap |

## Don't see your use case?

- [GitHub Discussions](https://github.com/loopengine/loop-engine/discussions)
- [RFC Process](/docs/governance/rfc-process)


---

## SDR qualification loop (ABM / RevOps)
URL: https://bossloops.io
/docs/examples/sdr-qualification-loop
Summary: AI scores inbound leads, Slack escalates low confidence, human SDR decides, CRM updates — governed operational runtime pattern.
Section: Examples


<Callout variant="warning" title="Narrative pattern — RevOps / ABM">
Operational-runtime walkthrough for **governed lead qualification**. Composite of Provider + Channel + Integration patterns; **Boss Loops Cloud** connectors for Slack and CRM are documented on the [Cloud API](/docs/cloud/api-reference). Not a single `loop-examples` clone-and-run repo today.
</Callout>

## Runtime flow

| Stage | In this pattern |
| --- | --- |
| **Provider** | OpenAI or Anthropic scores fit, intent, and ICP match from form + enrichment context |
| **Loop + Guards** | `lead.qualification` — `confidence-threshold`, `evidence-required`, route to human when below bar |
| **Channel** | **Slack** — SDR receives interactive qualify/disqualify; unmapped users rejected |
| **Integration** | **Salesforce** (or HubSpot) — lead status, owner, and stage update only after approved transition |
| **Evidence + learning** | Score breakdown, model version, SDR decision; learning signal compares predicted vs closed-won |

```text
Inbound lead → Provider scores → Guards → (low confidence?) Channel: Slack → SDR → Integration: CRM → Evidence
```

## Operational scenario

1. Marketing automation opens `lead.qualification` with firmographic evidence.
2. **Provider** returns score + rationale — does not change CRM stage.
3. **Guards** block auto-accept when confidence &lt; threshold or missing required fields.
4. **Channel** posts to `#sdr-qualification` with approve / reject / needs-research actions.
5. On **human-only** approve, **Integration** writes `Qualified` stage and assigns owner.
6. **Evidence** on each transition supports pipeline reviews and model tuning.

## Governance boundaries

| Boundary | Enforcement |
| --- | --- |
| AI cannot self-qualify into pipeline | `human-only` on accept transitions |
| Slack is not the system of record | CRM write is Integration step only |
| No chatbot “magic” | Every outcome is a named loop transition |

## What this is not

- A lead-scoring Zapier recipe without audit trail.
- An LLM that updates Salesforce directly from a prompt.

## Related

- [Campaign approval loop](/docs/examples/campaign-approval-loop)
- [Dual-surface Docs + Slack](/docs/examples/dual-surface-docs-slack)
- [Runtime Taxonomy](/docs/concepts/runtime-taxonomy)


---

## Proposal approval loop (ABM / RevOps)
URL: https://bossloops.io
/docs/examples/proposal-approval-loop
Summary: AI drafts proposal in Google Docs, Slack approval for sales and legal, Salesforce opportunity advances — dual-surface governance.
Section: Examples


<Callout variant="warning" title="Narrative pattern — dual-surface RevOps">
Combines [Google Docs + Slack](/docs/examples/dual-surface-docs-slack) work/decision surfaces with CRM **Integration**. Requires **Boss Loops Cloud** for managed Google + Slack connectors; OSS SDK governs the loop definition.
</Callout>

## Runtime flow

| Stage | In this pattern |
| --- | --- |
| **Provider** | LLM drafts proposal sections from opportunity context, pricing guardrails, and legal snippets |
| **Loop + Guards** | `proposal.review` — brand/compliance guards, margin checks, `human-only` on customer-send |
| **Channel** | **Slack** — AE + legal approve; **Docs comments** for inline questions (work surface, not governance) |
| **Integration** | **Google Docs** snapshot/hash evidence; **Salesforce** stage → `Proposal Sent` after approval |
| **Evidence + learning** | Doc revision hash, approver IDs, discount exceptions for win/loss analysis |

```text
Provider drafts in Docs → Loop + Guards → Channel: Slack (+ doc comments) → Integration: SFDC + publish → Evidence
```

## Operational scenario

1. AE triggers `proposal.review` from opportunity id — Docs template cloned to work surface.
2. **Provider** proposes pricing table and legal clauses — staged, not customer-visible.
3. **Guards** fail transition if margin &lt; floor or missing legal ack.
4. **Channel** routes `#deal-desk` approval in Slack; legal may comment in Docs (context only).
5. Approved transition applies customer-visible publish + **Salesforce** stage advance.
6. **Evidence** links Slack actor, doc hash, and opportunity id for audit.

## Workflows vs loops

| | Workflow (e.g. doc generation job) | Loop (Boss Loops) |
| --- | --- | --- |
| Job | Render PDF, sync attachments | Govern whether proposal may be sent |
| Retry | Orchestrator retries API failures | Guards block illegal transitions |

## Related

- [Proposal path on dual-surface Docs](/docs/examples/dual-surface-docs-slack)
- [Pricing exception loop](/docs/examples/pricing-exception-loop)
- [Workflow + Loop](/docs/examples/workflow-plus-loop)


---

## Campaign approval loop (ABM / RevOps)
URL: https://bossloops.io
/docs/examples/campaign-approval-loop
Summary: AI-generated outbound copy passes brand and compliance guards, Slack review, then marketing platform execution.
Section: Examples


<Callout variant="warning" title="Narrative pattern — ABM outbound">
Governed **campaign launch** — not autonomous email generation. Marketing execution platform is **Integration**; humans approve in **Channel**.
</Callout>

## Runtime flow

| Stage | In this pattern |
| --- | --- |
| **Provider** | LLM generates sequence copy, subject lines, and personalization tokens from account research |
| **Loop + Guards** | `campaign.launch` — brand voice guard, compliance keyword blocklist, `evidence-required` |
| **Channel** | **Slack** — marketing ops + legal review in `#campaign-approvals` |
| **Integration** | MAP/SEP (e.g. Outreach, Marketo webhook) — schedule sends only after `APPROVED` |
| **Evidence + learning** | Copy hash, guard outcomes, approval latency; learning on reply-rate vs predicted |

## Operational scenario

1. ABM operator opens loop for target account list segment.
2. **Provider** produces draft sequences per persona — no sends yet.
3. **Guards** block transitions containing forbidden claims or missing disclaimers.
4. **Channel** collects approve / revise / reject from brand and legal roles.
5. **Integration** activates campaign in marketing platform with approved artifact id.
6. **Evidence** supports regulatory review (“who approved this copy, when, with what model”).

## Deterministic boundaries

- Prompt instructions cannot bypass compliance **guards**.
- Slack reactions are not sends — MAP activation is post-governance **Integration**.

## Related

- [SDR qualification loop](/docs/examples/sdr-qualification-loop)
- [Runtime Taxonomy — Providers](/docs/concepts/runtime-taxonomy#providers)
- [Human approval gates](/docs/ai-and-automation/human-approval-gates)


---

## Pricing exception loop (Sheets + Slack)
URL: https://bossloops.io
/docs/examples/pricing-exception-loop
Summary: Margin exception detected in Google Sheets, AI recommends band, finance approves in Slack, ERP/CRM updated — dual-surface RevOps.
Section: Examples


<Callout variant="warning" title="Narrative pattern — Sheets staging + Slack">
Extends [Google Sheets + Slack](/docs/examples/dual-surface-sheets-slack). **Sheets = work surface + staging**; **Slack = Channel**; **ERP/CRM = Integration**. Apply to rows only after approved transition.
</Callout>

## Runtime flow

| Stage | In this pattern |
| --- | --- |
| **Provider** | Optional — AI recommends discount band from deal context and policy tables |
| **Loop + Guards** | `pricing.exception` — margin floor, tier entitlements, `human-only` on apply |
| **Channel** | **Slack** — finance controller approve/reject with audit note |
| **Integration** | **Google Sheets** staged cells → approved apply; **Salesforce** / ERP price sync |
| **Evidence + learning** | Staging snapshot, exception rationale, approver; learning on exception win rate |

```text
Sheets detects exception → Provider (optional) → Guards → Channel: Slack → Integration: apply + CRM → Evidence
```

## Operational scenario

1. Rep edits discount column — change **staged**, not committed to ERP.
2. Loop opens `pricing.exception` with row keys and prior margin in evidence.
3. **Provider** may suggest allowed band — **Guards** enforce hard floors.
4. **Channel** notifies `#deal-desk-finance` in Slack.
5. On approve, **Integration** applies row + syncs opportunity line items.
6. **Evidence** proves who authorized margin erosion.

## Governance vs spreadsheet macros

| Spreadsheet macro | Governed loop |
| --- | --- |
| Auto-write on formula | No transition without human Channel action |
| Email finance manually | Attributed actor + evidence on transition |

## Related

- [Dual-surface Sheets + Slack](/docs/examples/dual-surface-sheets-slack)
- [Proposal approval loop](/docs/examples/proposal-approval-loop)
- [Confidence + Evidence](/docs/ai-and-automation/confidence-evidence)


---

## Google Docs + Slack (dual-surface)
URL: https://bossloops.io
/docs/examples/dual-surface-docs-slack
Summary: AI-generated proposal in Google Docs, human approval in Slack, governed transition before any write — Boss Loops Cloud pattern.
Section: Examples


<Callout variant="warning" title="Narrative pattern — not an OSS clone-and-run example">
This walkthrough describes the **Boss Loops Cloud** dual-surface model (Google work surface + Slack decision surface). It does **not** ship as a standalone repo in `loop-examples`. Connectors and templates are operated via **[Boss Loops Cloud](/docs/cloud/api-reference)** — see [changelog](/docs/changelog) for shipped capabilities.
</Callout>

## Runtime flow

| Stage | Role in this pattern |
| --- | --- |
| **Provider** | LLM drafts or revises proposal content (summary, rationale, risk notes) from Doc context |
| **Loop + Guards** | Versioned loop definition; `evidence-required`, tier guards, optional `confidence-threshold` |
| **Channel** | **Slack** — approver receives interactive approval; unmapped Slack users are rejected |
| **Integration** | **Google Docs** — snapshot/hash evidence; apply or publish only after approved transition |
| **Evidence** | Doc revision hash, prompt attribution, Slack actor mapping → platform `actorId`, transition audit |

```text
Google Doc (work)          Slack (decisions)        Boss Loops Cloud
      │                          │                            │
      │  context + draft         │  approve / reject          │  guards + state
      └──────────────────────────┴────────────────────────────┘
                                        │
                                        ▼
                              Evidence on each transition
```

## What this teaches

- **Governance before writes** — Docs are a *work surface*; the loop decides whether content may be applied or published.
- **Human escalation in Channel** — Slack is where tenant approvers act; not a chatbot that auto-commits.
- **Deterministic boundaries** — Automation and Providers cannot take `human-only` transitions even if prompts ask them to.
- **Evidence for disputes** — Each step records hashes and actor attribution suitable for audit, not chat logs.

## What this is not

- A Slack bot that “just approves” AI output without a loop instance and guards.
- Un governed direct Google API writes from the model.
- An OSS `adapter-slack` quickstart (planned on npm — use Cloud connectors today).

## Architecture (hosted)

Better Data’s dual-surface MVP runs on **`apps/hosted-loops`** with tenant-scoped OAuth:

1. **Work surface** — read Doc context; stage proposed changes; attach content-hash evidence to signals.
2. **Decision surface** — Slack Events + interactivity → `engine.transition(...)` with resolved platform actor.
3. **Apply gate** — destructive or customer-visible writes occur only in post-approval integration steps.

Company and connector operations docs: **[docs.betterdata.co](https://docs.betterdata.co)**. Runtime taxonomy and OSS primitives: **loopengine.io**.

## Related

- [Google Sheets + Slack](/docs/examples/dual-surface-sheets-slack) — staging/apply pattern for spreadsheets
- [Runtime Taxonomy — Channels](/docs/concepts/runtime-taxonomy#channels)
- [Boss Loops Cloud API](/docs/cloud/api-reference)
- [Human approval gates](/docs/ai-and-automation/human-approval-gates)


---

## Google Sheets + Slack (spreadsheet approval)
URL: https://bossloops.io
/docs/examples/dual-surface-sheets-slack
Summary: Stage spreadsheet changes, approve in Slack, apply rows only after governed transition — dual-surface Boss Loops Cloud pattern.
Section: Examples


<Callout variant="warning" title="Narrative pattern — not an OSS clone-and-run example">
Spreadsheet **staging + gated apply** is a **Boss Loops Cloud** dual-surface pattern. There is no `loop-examples` directory that reproduces tenant Google OAuth and Slack installs end-to-end. Use this page for architecture; use Cloud connectors when available in your environment.
</Callout>

## Runtime flow

| Stage | Role in this pattern |
| --- | --- |
| **Provider** | Optional — AI may propose row-level changes or classifications from sheet context |
| **Loop + Guards** | Explicit states (e.g. `STAGED` → `PENDING_APPROVAL` → `APPLIED`); **no blind writes** during loop execution |
| **Channel** | **Slack** — human approves or rejects staged diff; idempotent interactive handling |
| **Integration** | **Google Sheets** — **stage** proposed edits; **apply** workbook updates only after approved transition |
| **Evidence** | Staging snapshot, row keys, approver attribution, apply receipt hash |

```text
Sheet (staging)     Slack (approve/reject)     Loop + Guards
     │                      │                      │
     │  propose rows        │  human signal        │  commit transition?
     └──────────────────────┴──────────────────────┘
                               │
                               ▼ (only if approved)
                         Apply to Sheets
                               │
                               ▼
                         Evidence + events
```

## Governance rules (non-negotiable)

1. **Sheets = staging** — proposed edits land in a staging representation; production rows are not overwritten mid-loop.
2. **Apply = Integration step** — runs only after guards pass and a human Channel action records approval.
3. **Actors = platform identity** — Slack user ids map to tenant users; unmapped users cannot approve.
4. **Evidence on transition** — not a post-hoc spreadsheet of chat messages.

## What this teaches

- **Deterministic boundaries** — guards block apply transitions without approval evidence.
- **Human escalation** — high-impact row changes stay in `PENDING_*` until Slack action.
- **AI assistance without magic** — a Provider may *recommend* staging content; it cannot call `apply` directly.

## What this is not

- A formula macro or Apps Script that auto-writes on model output.
- A chatbot in Slack that edits Sheets without loop state.
- Proof that OSS npm packages alone replicate tenant Google + Slack OAuth (that is Cloud/hosted-loops scope).

## Related

- [Google Docs + Slack](/docs/examples/dual-surface-docs-slack) — Doc snapshot / publish pattern
- [Runtime Taxonomy — Integrations](/docs/concepts/runtime-taxonomy#integrations)
- [Guards and Policy](/docs/concepts/guards-and-policy)
- [Boss Loops Cloud API](/docs/cloud/api-reference)


---

## PagerDuty incident loop
URL: https://bossloops.io
/docs/examples/pagerduty-incident-loop
Summary: AI classification inside a governed loop, human escalation, PagerDuty alerting — full Provider → Channel → Integration flow with evidence.
Section: Examples


<Callout variant="info" title="Implementation detail">
Step-by-step adapter configuration, Events API payloads, and the `governed-incident-response` transition graph live on **[Governed incident response (Perplexity + PagerDuty)](/docs/integrations/perplexity-pagerduty)**. This page teaches the **runtime flow** that page implements.
</Callout>

## Runtime flow

| Stage | Role in this pattern |
| --- | --- |
| **Provider** | **Perplexity Sonar** (`ToolAdapter`) — grounded research + citations for classification input |
| **Loop + Guards** | `governed-incident-response` (or equivalent) — risk tier, `human_review`, `blocked` without alert |
| **Channel** | On-call human in PagerDuty UI / escalation policy — approves escalate vs. auto-path |
| **Integration** | **PagerDuty** Events API v2 — trigger only when loop reaches `alerting` (with `audit_ref` in `custom_details`) |
| **Evidence** | Sonar citations hash, classification rationale, human decision, alert payload reference |

```text
Provider (Sonar research)
        ↓
Loop + Guards (classify, gate, human_review)
        ↓
Channel (on-call human decision)
        ↓
Integration (PagerDuty alert)
        ↓
Evidence (tamper-evident trail)
```

## What this teaches

- **Governance** — Neither Sonar nor PagerDuty alone produces a compliance-grade decision record; the loop binds them.
- **Deterministic boundaries** — `blocked` and low-tier paths **do not** emit PagerDuty alerts; guards enforce that.
- **Human escalation** — `human_review` timeout paths escalate through policy, not model discretion.
- **AI assistance** — Provider supplies research; it does not page on-call by itself.

## What this is not

- “AI incident bot” that posts to PagerDuty without loop state.
- A replacement for PagerDuty scheduling — Boss Loops governs **when** alerting is allowed.
- A claim that every catalog loop id is pre-installed in your account — register definitions per environment.

## Runnable scope

| Piece | OSS today |
| --- | --- |
| Loop definition + `engine.transition` | Yes — `@loop-engine/sdk` |
| Sonar + PagerDuty adapters | Yes — see integration guide |
| End-to-end hosted template + tenant connectors | Boss Loops Cloud / operator setup |

## Related

- [Perplexity + PagerDuty integration](/docs/integrations/perplexity-pagerduty)
- [PagerDuty connection](/docs/integrations/pagerduty)
- [Perplexity Provider](/docs/integrations/perplexity)
- [Confidence + Evidence](/docs/ai-and-automation/confidence-evidence)


---

## Workflow engine + Boss Loops
URL: https://bossloops.io
/docs/examples/workflow-plus-loop
Summary: Temporal or Salesforce durable execution with Boss Loops governing transitions — Provider → Guards → Channel → Integration (activity).
Section: Examples


<Callout variant="warning" title="Narrative pattern">
This is an **architecture composition** example. It does not ship as a single `loop-examples` folder. Combine Boss Loops OSS with your workflow engine using explicit transition gates — see [Boss Loops vs Workflow Engines](/docs/concepts/loop-engine-vs-workflow-engines) for contracts.
</Callout>

## Runtime flow

| Stage | Role in this pattern |
| --- | --- |
| **Provider** | AI agent inside a workflow activity proposes a transition (recommendation + evidence) |
| **Loop + Guards** | Boss Loops evaluates policy **before** the workflow schedules downstream side effects |
| **Channel** | Human approval activity (Slack, ticketing UI, or in-app) resumes workflow only after governed transition |
| **Integration** | **Temporal** activity / **Salesforce** flow step executes durable work **after** `executed` status |
| **Evidence** | Loop transition evidence linked to workflow run id / Salesforce record id for audit |

```text
Workflow (Temporal / Salesforce)
        │
        ├─ activity: propose AI decision
        │       ↓
        │   Provider
        │       ↓
        │   Loop + Guards  ←── Boss Loops (governance)
        │       ↓
        │   Channel (human)
        │       ↓
        └─ activity: execute approved work  ←── Integration (durable execution)
                ↓
            Evidence (both layers)
```

## Temporal composition

**Temporal** owns: retries, timers, sagas, long-running coordination.

**Boss Loops** owns: whether a named transition may commit, with which actor, and with what evidence.

Typical sequence:

1. Workflow reaches a decision checkpoint activity.
2. Activity calls Provider adapter → submits transition candidate.
3. `engine.transition` runs guards; may return `pending` for human Channel step.
4. On `executed`, workflow continues to side-effect activities (deploy, CRM update, ticket close).

```ts
// @no-typecheck
// After Boss Loops returns executed — Temporal runs durable side effects.
const decision = await engine.transition({
  aggregateId: workflowRunId as never,
  transitionId: "approve_change" as never,
  actor: resolvedHumanActor,
  evidence: { workflowId: ctx.workflowId, runId: ctx.runId }
});

if (decision.status !== "executed") {
  throw new ApplicationFailure("Governance blocked", "GOVERNANCE_BLOCKED");
}
// continue workflow: call external Integration APIs
```

## Salesforce composition

**Salesforce Flow / Apex** often owns record updates and UI. Boss Loops governs **approval transitions** that Flow must not bypass:

- Provider step: classify opportunity risk or draft terms (AI agent actor).
- Loop + Guards: credit-policy guards, evidence-required fields.
- Channel: approver in Salesforce approval process **or** Slack via Cloud connector.
- Integration: Flow updates Opportunity only when loop instance is in approved state.

Same rule: **Flow executes; Loop governs commit.**

## What this teaches

- **Governance differentiation** — workflows coordinate; loops **authorize** state changes.
- **Deterministic boundaries** — activities must check `executed` vs. blocked/pending.
- **Human escalation** — workflow waits on Channel, not on model stream end.
- **Evidence** — audit ties workflow id to loop transition evidence.

## What this is not

- Boss Loops as a workflow engine replacement.
- Salesforce or Temporal “plugins” that hide guards behind prompts.
- An implied single npm package that embeds both runtimes — you compose explicitly.

## Related

- [Boss Loops vs Workflow Engines](/docs/concepts/loop-engine-vs-workflow-engines)
- [What is a Loop?](/docs/concepts/what-is-a-loop)
- [Architecture](/docs/getting-started/architecture)
- [Infrastructure Change Approval](/docs/examples/infrastructure-change-approval) — SRE Channel + rollout Integration


---

## AI Replenishment (Claude)
URL: https://bossloops.io
/docs/examples/ai-replenishment-claude
Summary: Anthropic Claude as a procurement AI actor - confidence-gated recommendation with human approval.
Section: Examples


<Callout variant="info" title="Full source">
<a href="https://github.com/loopengine/loop-examples/tree/main/ai-actors/claude" target="_blank" rel="noreferrer">
github.com/loopengine/loop-examples/tree/main/ai-actors/claude
</a>
</Callout>

<Callout variant="info" title="Commerce Chain production path">
  This walkthrough uses the Boss Loops SDK directly. For the Commerce Chain–oriented version (participant manifests, `configure*Runtime`, SCM/DCM modules), see **[AI Replenishment on commercechain.io](https://commercechain.io/docs/examples/ai-replenishment)** — plus [Loop participation](https://commercechain.io/docs/getting-started/loop-participation) and [Runtime configuration](https://commercechain.io/docs/getting-started/runtime-configuration).
</Callout>

## Runtime flow

| Stage | In this example |
| --- | --- |
| **Provider** | Claude (`@loop-engine/adapter-anthropic`) — `submit_recommendation` with confidence + evidence |
| **Loop + Guards** | Replenishment loop — `confidence-threshold`, state machine enforcement |
| **Channel** | Buyer approver (human actor) — `human-only` on `approve` / `reject` |
| **Integration** | Downstream order/ERP trigger after `ORDERED` (your system of record) |
| **Evidence** | SKU context, model confidence, recommendation fields on each transition |

```text
Provider (Claude) → Loop + Guards → Channel (buyer) → Integration (order) → Evidence
```

## What this example shows

An AI actor using `@loop-engine/adapter-anthropic` analyzes inventory evidence and submits a replenishment recommendation. A confidence threshold gate keeps low-confidence decisions from reaching execution. A human approval transition remains required for final ordering — **not** autonomous purchasing.

## Loop diagram

```text
IDLE ----[signal_detected]----> ANALYZING
ANALYZING --[submit_recommendation]--> PENDING_APPROVAL
ANALYZING --[insufficient_confidence]--> IDLE
PENDING_APPROVAL --[approve]--> ORDERED (terminal)
PENDING_APPROVAL --[reject]--> IDLE
```

## Actors

| Actor | Type | Transitions | Guards |
|---|---|---|---|
| signal detector | automation | `signal_detected` | none |
| claude recommender | ai-agent | `submit_recommendation` | `confidence-threshold` |
| buyer approver | human | `approve`, `reject` | `human-only` |

## Key annotated snippet

```ts
// @no-typecheck
import Anthropic from "@anthropic-ai/sdk";
import { createAnthropicActorAdapter } from "@loop-engine/adapter-anthropic";

const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
const claude = createAnthropicActorAdapter(anthropic, {
  modelId: "claude-opus-4-6",
  confidenceThreshold: 0.75
});

const { actor, decision } = await claude.createSubmission({
  loopId: "scm.replenishment",
  loopName: "SCM Replenishment",
  currentState: "ANALYZING",
  availableSignals: [{ signalId: "submit_recommendation", name: "Submit Recommendation" }],
  instruction: "Recommend reorder quantity based on stock and forecast.",
  evidence: {
    sku: "LMB-BRS-001",
    currentStock: 142,
    reorderPoint: 280,
    forecastedDemand: 527
  }
});

await engine.transition({
  aggregateId: "repl-lmb-001" as never,
  transitionId: "submit_recommendation" as never,
  actor,
  evidence: decision
});
```

## What emitted events look like

```ts
{
  type: "loop.transition.executed",
  loopId: "scm.replenishment",
  aggregateId: "repl-lmb-001",
  transitionId: "submit_recommendation",
  fromState: "ANALYZING",
  toState: "PENDING_APPROVAL",
  actor: { type: "ai-agent", id: "agent:claude-replenishment" },
  occurredAt: "2026-03-13T12:24:00.422Z"
}
```

## Try it yourself

```bash
cd loop-examples/ai-actors/claude
pnpm install
pnpm dev
```

See [AI Replenishment (OpenAI)](/docs/examples/ai-replenishment-openai) for the identical loop with a different provider adapter.


---

## AI Replenishment (OpenAI)
URL: https://bossloops.io
/docs/examples/ai-replenishment-openai
Summary: Identical replenishment loop behavior with OpenAI actor integration to show provider interchangeability.
Section: Examples


<Callout variant="info" title="Full source">
<a href="https://github.com/loopengine/loop-examples/tree/main/ai-actors/openai" target="_blank" rel="noreferrer">
github.com/loopengine/loop-examples/tree/main/ai-actors/openai
</a>
</Callout>

## What this example shows

This page uses the same replenishment loop semantics as the Claude variant, but switches to `@loop-engine/adapter-openai`. The loop definition and transition policy remain unchanged. Only the provider adapter wiring changes.

## Loop diagram

```text
IDLE ----[signal_detected]----> ANALYZING
ANALYZING --[submit_recommendation]--> PENDING_APPROVAL
ANALYZING --[insufficient_confidence]--> IDLE
PENDING_APPROVAL --[approve]--> ORDERED (terminal)
PENDING_APPROVAL --[reject]--> IDLE
```

## Actors

| Actor | Type | Transitions | Guards |
|---|---|---|---|
| signal detector | automation | `signal_detected` | none |
| gpt recommender | ai-agent | `submit_recommendation` | `confidence-threshold` |
| buyer approver | human | `approve`, `reject` | `human-only` |

## Key annotated snippet

```ts
// @no-typecheck
import OpenAI from "openai";
import { createOpenAIActorAdapter } from "@loop-engine/adapter-openai";

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const gpt = createOpenAIActorAdapter(openai, {
  modelId: "gpt-4o",
  confidenceThreshold: 0.75
});

// Same loop context and transition IDs as Claude variant.
const { actor, decision } = await gpt.createSubmission({
  loopId: "scm.replenishment",
  loopName: "SCM Replenishment",
  currentState: "ANALYZING",
  availableSignals: [{ signalId: "submit_recommendation", name: "Submit Recommendation" }],
  instruction: "Recommend reorder quantity based on stock and forecast.",
  evidence: { sku: "LMB-BRS-001", currentStock: 142, reorderPoint: 280, forecastedDemand: 527 }
});

await engine.transition({
  aggregateId: "repl-lmb-001" as never,
  transitionId: "submit_recommendation" as never,
  actor,
  evidence: decision
});
```

## What emitted events look like

```ts
{
  type: "loop.transition.executed",
  loopId: "scm.replenishment",
  aggregateId: "repl-lmb-001",
  transitionId: "submit_recommendation",
  fromState: "ANALYZING",
  toState: "PENDING_APPROVAL",
  actor: { type: "ai-agent", id: "agent:openai-replenishment" },
  occurredAt: "2026-03-13T12:29:44.501Z"
}
```

## Try it yourself

```bash
cd loop-examples/ai-actors/openai
pnpm install
pnpm dev
```

See [AI Replenishment (Claude)](/docs/examples/ai-replenishment-claude) for the Anthropic version of this same loop.


---

## Infrastructure Change Approval
URL: https://bossloops.io
/docs/examples/infrastructure-change-approval
Summary: Governed infrastructure change management - AI blast-radius analysis, SRE approval gate, and automated rollout with full audit trail.
Section: Examples


<Callout variant="warning" title="Source coming soon">
<div style={{ display: "grid", gap: 8 }}>
  <div>Source coming soon in <code>github.com/loopengine/loop-examples</code>.</div>
  <div><strong>Badge:</strong> Coming Soon</div>
</div>
</Callout>

## Runtime flow

| Stage | In this example |
| --- | --- |
| **Provider** | Claude — blast-radius analysis (`submit_analysis`) |
| **Loop + Guards** | Change-approval loop — `evidence-required`, `confidence-threshold`, state gates |
| **Channel** | SRE approver — `human-only` on `approve_change` / `reject_change` |
| **Integration** | Deploy controller automation — rollout **after** approved transition |
| **Evidence** | Blast radius score, affected services, rollback plan on transitions |

```text
Provider (analysis) → Loop + Guards → Channel (SRE) → Integration (rollout) → Evidence
```

## What this example shows

Infrastructure change management is high risk by default. This pattern introduces explicit governance checkpoints: AI blast-radius analysis, human SRE approval, and then automation-controlled rollout. Every handoff carries evidence and attributed actors — **not** an AI that deploys without approval.

## Loop diagram

```text
IDLE --[start_analysis]--> ANALYZING
ANALYZING --[submit_analysis]--> PENDING_APPROVAL
PENDING_APPROVAL --[approve_change]--> APPROVED --[execute_rollout]--> ROLLING_OUT --[complete_rollout]--> COMPLETE
PENDING_APPROVAL --[reject_change]--> REJECTED
```

## Actors

| Actor | Type | Role | Guards that apply |
|---|---|---|---|
| change analyzer | ai-agent | Produces blast-radius assessment and recommendation | `evidence-required`, `confidence-threshold` |
| sre approver | human | Approves or rejects rollout | `human-only` |
| deploy controller | automation | Executes approved rollout steps | state/transition constraints |

## Key annotated snippet

```ts
// @no-typecheck
import Anthropic from "@anthropic-ai/sdk";
import { createLoopSystem } from "@loop-engine/sdk";
import { createAnthropicActorAdapter } from "@loop-engine/adapter-anthropic";

const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
const adapter = createAnthropicActorAdapter(anthropic, { modelId: "claude-opus-4-6" });
const { engine } = await createLoopSystem({ loops: [changeApprovalLoop] });

const { actor, decision } = await adapter.createSubmission({
  loopId: "infrastructure.change_approval",
  loopName: "Infrastructure Change Approval",
  currentState: "ANALYZING",
  availableSignals: [{ signalId: "submit_analysis", name: "Submit Analysis" }],
  instruction: "Assess blast radius and rollback readiness.",
  evidence: { changeId: "CHG-10021", service: "payments-api" }
});

await engine.transition({
  aggregateId: "chg-2026-03-13-001" as never,
  transitionId: "submit_analysis" as never,
  actor,
  evidence: {
    ...decision,
    blast_radius_score: 0.22,
    affected_services: ["payments-api", "settlement-worker"],
    rollback_plan: "revert migration and recycle workers"
  }
});
```

## What emitted events look like

```ts
{
  type: "loop.transition.executed",
  loopId: "infrastructure.change_approval",
  aggregateId: "chg-2026-03-13-001",
  transitionId: "approve_change",
  fromState: "PENDING_APPROVAL",
  toState: "APPROVED",
  actor: { type: "human", id: "sre@company.com" },
  evidence: { approvalTicket: "SRE-4451", approved: true }
}
```

## Source coming soon

<Callout variant="info" title="Subscribe for release updates">
Source is coming soon in `loopengine/loop-examples`. Follow releases in the main repo to get notified when this example lands.
</Callout>

<Callout variant="important" title="Related concept">
See [Decision Governance](/docs/concepts/decision-governance) for the architecture behind this pattern.
</Callout>


---

## Fraud Review Loop
URL: https://bossloops.io
/docs/examples/fraud-review
Summary: AI-assisted fraud detection with human analyst review - structured escalation, evidence capture, and final disposition.
Section: Examples


<Callout variant="warning" title="Source coming soon">
<div style={{ display: "grid", gap: 8 }}>
  <div>Source coming soon in <code>github.com/loopengine/loop-examples</code>.</div>
  <div><strong>Badge:</strong> Coming Soon</div>
</div>
</Callout>

## Runtime flow

| Stage | In this example |
| --- | --- |
| **Provider** | OpenAI scorer — fraud likelihood + patterns (`submit_score`) |
| **Loop + Guards** | Review loop — `evidence-required`, `confidence-threshold` |
| **Channel** | Analyst reviewer — `human-only` on `analyst_review` / disposition |
| **Integration** | Case system / payment hold release after terminal states |
| **Evidence** | `fraud_score`, flagged patterns, transaction context per transition |

```text
Provider (scorer) → Loop + Guards → Channel (analyst) → Integration (case system) → Evidence
```

## What this example shows

Fraud queues move faster than human teams can triage manually. This pattern uses AI scoring for prioritization and keeps final decision authority with a human analyst. Every escalation and disposition remains attributable for audit — **not** auto-block without human path on escalated cases.

## Loop diagram

```text
IDLE --[ingest_flag]--> FLAGGED --[start_scoring]--> SCORING
SCORING --[submit_score]--> PENDING_REVIEW
PENDING_REVIEW --[dismiss_case]--> DISMISSED (terminal)
PENDING_REVIEW --[analyst_review]--> REVIEWED --[close_case]--> CLOSED (terminal)
```

## Actors

| Actor | Type | Role | Guards that apply |
|---|---|---|---|
| transaction ingestor | automation | Flags incoming transactions | none |
| risk scorer | ai-agent | Computes fraud likelihood and patterns | `evidence-required`, `confidence-threshold` |
| analyst reviewer | human | Final disposition on escalated cases | `human-only` |

## Key annotated snippet

```ts
// @no-typecheck
import OpenAI from "openai";
import { createOpenAIActorAdapter } from "@loop-engine/adapter-openai";

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const scorer = createOpenAIActorAdapter(openai, { modelId: "gpt-4o" });

const { actor, decision } = await scorer.createSubmission({
  loopId: "fraud.review",
  loopName: "Fraud Review",
  currentState: "SCORING",
  availableSignals: [{ signalId: "submit_score", name: "Submit Score" }],
  instruction: "Score fraud risk and provide suspicious patterns.",
  evidence: { merchantId: "m-42", ipRisk: "high", velocitySpike: true }
});

await engine.transition({
  aggregateId: "txn-884422" as never,
  transitionId: "submit_score" as never,
  actor,
  evidence: {
    ...decision,
    fraud_score: decision.confidence,
    flagged_patterns: ["velocity_spike", "new_device", "geo_mismatch"],
    transaction_context: { amount: 1480, currency: "USD" }
  }
});
```

## What emitted events look like

```ts
{
  type: "loop.transition.executed",
  loopId: "fraud.review",
  aggregateId: "txn-884422",
  transitionId: "analyst_review",
  fromState: "PENDING_REVIEW",
  toState: "REVIEWED",
  actor: { type: "human", id: "analyst@bank.com" },
  evidence: { disposition: "confirm_fraud", caseId: "FR-92011" }
}
```

## Source coming soon

<Callout variant="info" title="Related guidance">
Source is coming soon in `loopengine/loop-examples`. Subscribe to release updates to get notified when the runnable project lands.
</Callout>

<Callout variant="important" title="Related guidance">
See [Confidence + Evidence](/docs/ai-and-automation/confidence-evidence) for evidence modeling and [Learning Signals](/docs/concepts/learning-signals) for evaluation loops.
</Callout>


---

## Expense Approval
URL: https://bossloops.io
/docs/examples/expense-approval
Summary: The simplest governed loop - a single human-only approval gate with hard policy enforcement.
Section: Examples


<Callout variant="info" title="Full source">
<a href="https://github.com/loopengine/loop-examples/tree/main/expense-approval" target="_blank" rel="noreferrer">
github.com/loopengine/loop-examples/tree/main/expense-approval
</a>
</Callout>

## Runtime flow

| Stage | In this example |
| --- | --- |
| **Provider** | — (no AI; optional automation submits expense only) |
| **Loop + Guards** | Expense loop — `human-only` on approval transition |
| **Channel** | Approver (human actor) |
| **Integration** | Payment/ERP post after `APPROVED` |
| **Evidence** | Submission fields + approver attribution |

Teaches **governance without a Provider** — policy and human escalation still apply.

## What this example shows

The foundational Boss Loops pattern. An expense submission enters a two-step approval loop. A human-only guard on the approval transition ensures automation and AI actors can never self-approve.

## Loop diagram

```text
SUBMITTED --------[submit_expense]-------> PENDING_APPROVAL
PENDING_APPROVAL ------[approve]---------> APPROVED (terminal)
PENDING_APPROVAL -------[reject]---------> REJECTED (terminal)
```

## Actors

| Actor | Type | Transitions | Guards |
|---|---|---|---|
| submitter | human or automation | `submit_expense` | none |
| approver | human | `approve`, `reject` | `human-only` (hard) |

## Key annotated snippet

```ts
import { LoopBuilder } from "@loop-engine/sdk";

// The human-only guard is the load-bearing governance rule.
const expenseApproval = LoopBuilder
  .create("expense.approval", "finance")
  .description("Expense report approval")
  .state("SUBMITTED")
  .state("PENDING_APPROVAL")
  .state("APPROVED", { isTerminal: true })
  .state("REJECTED", { isTerminal: true })
  .initialState("SUBMITTED")
  .transition({
    id: "submit_expense",
    from: "SUBMITTED",
    to: "PENDING_APPROVAL",
    actors: ["human", "automation"]
  })
  .transition({
    id: "approve",
    from: "PENDING_APPROVAL",
    to: "APPROVED",
    actors: ["human"],
    guards: [
      {
        id: "human-only" as never,
        description: "Only a human approver can approve expenses",
        severity: "hard",
        evaluatedBy: "runtime"
      }
    ]
  })
  .transition({ id: "reject", from: "PENDING_APPROVAL", to: "REJECTED", actors: ["human"] })
  .build();
```

## What emitted events look like

```ts
{
  type: "loop.transition.executed",
  loopId: "expense.approval",
  aggregateId: "EXP-2026-001",
  transitionId: "approve",
  fromState: "PENDING_APPROVAL",
  toState: "APPROVED",
  actor: { type: "human", id: "manager@acme.com" },
  occurredAt: "2026-03-13T12:05:10.991Z"
}
```

## Try it yourself

```bash
cd loop-examples/expense-approval
pnpm install
pnpm dev
```


---

## OpenClaw Integration
URL: https://bossloops.io
/docs/examples/openclaw
Summary: Use OpenClaw as the human approval channel for Boss Loops and route approval gates through WhatsApp, Telegram, Slack, or Discord.
Section: Examples


## Runtime flow

| Stage | In this example |
| --- | --- |
| **Provider** | Optional — agent reasoning may live in OpenClaw; governed transitions still pass through Boss Loops |
| **Loop + Guards** | Approval loop — `allowedActors: ['human']`, `approval_obtained` |
| **Channel** | **OpenClaw** — WhatsApp/Telegram/Slack/Discord delivery of approval prompts |
| **Integration** | Downstream PO / ERP trigger after approved transition |
| **Evidence** | Transition events + messenger reply attribution |

```text
Provider (optional) → Loop + Guards → Channel (OpenClaw) → Integration → Evidence
```

## Overview

OpenClaw handles delivery and replies across messaging channels, while Boss Loops owns state transitions, actor constraints, and guard decisions.

Approval gates are runtime policy checks, not prompt conventions. Even if an agent asks to self-approve, a transition with `allowedActors: ['human']` rejects non-human actors.

## Architecture

```text
User (WhatsApp)
     |
     | "approve rpl-001"
     v
OpenClaw Gateway ------------------------------------.
     |                                                |
     | engine.transition('approve', humanActor)      |
     v                                                |
Boss Loops                                     |
     |                                                |
     |- guard: approval_obtained ✅                  |
     |- allowedActors: ['human'] ✅                  |
     v                                                |
PENDING_BUYER_APPROVAL -> PO_TRIGGERED               |
     |                                                |
     '--- loop.transition.executed --------------------'
                      "✅ Approved. Loop closed."
```

## Using @loop-engine/adapter-openclaw

```ts
// @no-typecheck
import { createLoopSystem, LoopBuilder } from '@loop-engine/sdk'
import { OpenClawEventBus } from '@loop-engine/adapter-openclaw'

const replenishmentLoop = LoopBuilder
  .create('demo.repl', 'scm')
  .state('A', { isTerminal: true })
  .initialState('A')
  .outcome({ id: 'o', description: 'o', valueUnit: 'o', businessMetrics: [{ id: 'm', label: 'm', unit: '1' }] })
  .build()

const { eventBus: inner } = await createLoopSystem({ loops: [replenishmentLoop] })
const eventBus = new OpenClawEventBus(inner, {
  channel: 'whatsapp',
  target: '+15551234567',
  events: ['loop.transition.executed', 'loop.completed', 'loop.guard.failed'],
  approvalStates: ['PENDING_BUYER_APPROVAL']
})
void eventBus
```

## The approval flow

1. Demand spike detection starts the loop with `loop.started`.
2. The AI analysis transition moves from `AI_ANALYSIS` to `PENDING_BUYER_APPROVAL`.
3. OpenClaw receives forwarded loop events and sends:
   `⚠️ Approval required: rpl-dc-east-001 ... Reply: approve rpl-dc-east-001 | reject rpl-dc-east-001`.
4. A buyer replies `approve rpl-dc-east-001` from a phone.
5. The OpenClaw skill calls `engine.transition` with a human actor.
6. `approval_obtained` passes and the loop advances to `PO_TRIGGERED`.
7. OpenClaw sends `✅ Approved. Loop advanced to: PO_TRIGGERED`.

## Why guards beat prompts

`allowedActors` and guard evaluation happen in the runtime transition engine, not in the language model output path. That keeps approval logic deterministic and testable.

Prompt injection can change model text, but it cannot bypass transition authorization or guard failures. This is the security boundary for agentic operations.

## Installing the OpenClaw skill

```bash
git clone https://github.com/loopengine/loop-examples
cp -r loop-examples/openclaw-skill ~/.openclaw/skills/loop-engine
```

The skill supports:

- `start loop [loop-id]`
- `transition [instance-id] [transition-id]`
- `approve [instance-id]`
- `reject [instance-id]`
- `status [instance-id]`
- `list loops`

Source: [loop-examples/openclaw-skill](https://github.com/loopengine/loop-examples/tree/main/openclaw-skill)

## Resources

- [`@loop-engine/adapter-openclaw`](/docs/packages/adapter-openclaw)
- [OpenClaw project](https://github.com/openclaw/openclaw)
- [openclaw-skill source](https://github.com/loopengine/loop-examples/tree/main/openclaw-skill)


---

## LLM Commerce Gateway Integration
URL: https://bossloops.io
/docs/examples/commerce-gateway
Summary: Connect Boss Loops to LLM Commerce Gateway so AI reads live commerce data while Boss Loops enforces approval before writes.
Section: Examples


## Overview

LLM Commerce Gateway exposes inventory, pricing, suppliers, and order operations as structured tool interfaces for LLM-driven workflows. Boss Loops governs the workflow state around those tools so recommendations and actions happen through explicit transitions.

The boundary is strict: Commerce Gateway handles commerce data access and operation execution, while Boss Loops handles state, actor attribution, guard enforcement, approval gates, and audit records.

## Architecture

```text
Demand Spike Signal
       |
       v
Boss Loops -------------- engine.start('procurement.loop')
       |                        state: GATEWAY_QUERY
       |
       v
AI Actor ----------------------- GET /inventory/:sku
       |                        GET /demand-forecast/:sku      Commerce
       |                        GET /suppliers/:sku      ----> Gateway API
       |                        (read only)
       |
       v
Boss Loops -------------- guard: confidence_threshold >= 0.80
       |                        state: PENDING_APPROVAL
       |
       v
Human Approves ----------------- engine.transition('approve_order', humanActor)
       |
       v
Automation Actor --------------- POST /purchase-orders          Commerce
       |                        (write post-approval only) ---> Gateway API
       |
       v
Boss Loops -------------- transition('place_order') -> engine.close(outcome: 'po_created')
```

## Three governed workflows

| Loop | Trigger | AI queries | Guard | Write operation |
|------|---------|------------|-------|-----------------|
| Procurement | Demand spike / low stock | Inventory, forecast, suppliers | confidence >= 0.80 + human approval | createPurchaseOrder |
| Price change | Competitor price, margin alert | Price history, demand elasticity | confidence >= 0.85 + human approval | updatePrice |
| Inventory adjustment | Expiry, damage, shrink | Current lots, expiry dates | human approval | writeDownInventory |

## Using @loop-engine/adapter-commerce-gateway

```ts
// @no-typecheck
import { createLoopSystem } from '@loop-engine/sdk'
import { CommerceGatewayClient, buildProcurementActor } from '@loop-engine/adapter-commerce-gateway'

const gatewayClient = new CommerceGatewayClient({
  baseUrl: process.env.COMMERCE_GATEWAY_URL!,
  apiKey: process.env.COMMERCE_GATEWAY_API_KEY!
})

const procurementActor = buildProcurementActor({
  gatewayClient,
  llmProvider: 'claude', // switch to 'openai' for GPT-4o
  apiKey: process.env.ANTHROPIC_API_KEY!,
  confidenceThreshold: 0.8
})

const { engine } = await createLoopSystem({ loops: [procurementLoop] })
const evidence = await procurementActor({ instance: { data: { sku: 'LMB-BRS-001' } } })
```

## The governance boundary

Commerce Gateway handles data access and commerce operations. Boss Loops governs the workflow around those operations.

| System | Owns |
|------|------|
| Commerce Gateway | Commerce data (inventory, pricing, orders, catalog), LLM tool definitions for commerce operations, and commerce API execution |
| Boss Loops | Workflow state, actor attribution, guard enforcement, human approval gates, transition audit trail, and learning signals |

Neither system needs to know the internal workings of the other. The adapter is the only coupling point.

## Full procurement walkthrough

1. `DEMAND_SPIKE` starts `procurement.loop` and moves to `GATEWAY_QUERY`.
2. AI actor reads `inventory`, `demand-forecast`, and `suppliers` from Commerce Gateway.
3. LLM emits recommendation evidence (`recommendedQty`, `supplierId`, `confidence`, `rationale`).
4. `confidence_threshold` passes and loop moves to `PENDING_APPROVAL`.
5. Human approves; automation actor calls `createPurchaseOrder`; loop executes `place_order` and closes with `po_created`.

## Resources

- [`@loop-engine/adapter-commerce-gateway`](/docs/packages/adapter-commerce-gateway)
- [commerce-gateway-example source](https://github.com/loopengine/loop-examples/tree/main/commerce-gateway-skill)
- [LLM Commerce Gateway](https://commercegateway.io)
- [Commerce Gateway docs](https://commercegateway.io/docs)


---

## AI Replenishment
URL: https://bossloops.io
/docs/examples/ai-replenishment
Summary: Anthropic and OpenAI actors run the same replenishment loop, while guards and human approval enforce safety boundaries.
Section: Examples


AI replenishment shows model-swappable actor wiring with identical loop constraints and deterministic approval policy.

## Loop behavior

- States: `SIGNAL_DETECTED -> AI_ANALYSIS -> PENDING_BUYER_APPROVAL -> PO_TRIGGERED`
- AI actor transition: `recommend_replenishment`
- Hard guards: `confidence_threshold`, `approval_obtained`
- Human-only transition: `approve_replenishment`

## Scenario

Lumebondé Bond Repair Serum (`LMB-BRS-001`) spikes `+89%` at `DC-East` with `currentStock=142`, `reorderPoint=280`, `forecastedDemand=527`, and `leadTimeDays=14`.

## Loop definition

```ts
// @no-typecheck
import { LoopBuilder } from "@loop-engine/sdk"

const replenishmentLoop = LoopBuilder
  .create("scm.replenishment", "scm")
  .version("1.0.0")
  .description("Triggered replenishment from demand signal")
  .state("SIGNAL_DETECTED")
  .state("AI_ANALYSIS")
  .state("PENDING_BUYER_APPROVAL")
  .state("PO_TRIGGERED", { isTerminal: true })
  .state("DEFERRED", { isTerminal: true })
  .initialState("SIGNAL_DETECTED")
  .transition({ id: "start_analysis", from: "SIGNAL_DETECTED", to: "AI_ANALYSIS", actors: ["automation"] })
  .transition({
    id: "recommend_replenishment",
    from: "AI_ANALYSIS",
    to: "PENDING_BUYER_APPROVAL",
    actors: ["ai-agent", "automation"],
    guards: [
      {
        id: "confidence_threshold" as never,
        description: "AI confidence >= 0.75",
        failureMessage: "Confidence below threshold",
        severity: "hard",
        evaluatedBy: "external"
      }
    ]
  })
  .transition({ id: "approve_replenishment", from: "PENDING_BUYER_APPROVAL", to: "PO_TRIGGERED", actors: ["human"] })
  .outcome({
    id: "replenishment_triggered",
    description: "PO submitted",
    valueUnit: "replenishment_triggered",
    businessMetrics: [
      { id: "m_replenishment", label: "Replenishment triggered", unit: "count" }
    ]
  })
  .build()
```

## Anthropic and OpenAI actors

Both providers create the same `AIAgentActor` shape and submit evidence with identical keys.

```ts
// @no-typecheck
import { actorId } from "@loop-engine/core"
import type { AIAgentActor } from "@loop-engine/actors"

const claudeActor: AIAgentActor = {
  type: "ai-agent",
  id: actorId("agent:demand-forecaster"),
  agentId: "claude-sonnet-4-20250514",
  gatewaySessionId: "claude-session-001"
}

const openAiActor: AIAgentActor = {
  type: "ai-agent",
  id: actorId("agent:demand-forecaster"),
  agentId: "gpt-4o",
  gatewaySessionId: "openai-session-001"
}
```

## Guard outcomes

```ts
// confidence 0.58 -> held at AI_ANALYSIS
const lowConfidence = await engine.transition({
  aggregateId,
  transitionId: transitionId("recommend_replenishment"),
  actor: claudeActor,
  evidence: { ai_confidence: 0.58, ai_reasoning: "Insufficient certainty" }
})
// lowConfidence.status === "guard_failed"

// confidence 0.82 -> advances to PENDING_BUYER_APPROVAL
const highConfidence = await engine.transition({
  aggregateId,
  transitionId: transitionId("recommend_replenishment"),
  actor: openAiActor,
  evidence: { ai_confidence: 0.82, ai_reasoning: "Demand spike sustained" }
})
// highConfidence.status === "executed"
```

## Human approval gate

```ts
// AI tries to execute human-only transition
const rejected = await engine.transition({
  aggregateId,
  transitionId: transitionId("approve_replenishment"),
  actor: claudeActor,
  evidence: { approval_obtained: true }
})
// rejected.status === "rejected"

// Human executes approval path
await engine.transition({
  aggregateId,
  transitionId: transitionId("approve_replenishment"),
  actor: { type: "human", id: "buyer@lumebonde.com" },
  evidence: { approved: true, approval_obtained: true }
})
```

## Provider parity

The loop definition, transition IDs, guards, and state progression remain identical across Anthropic and OpenAI implementations.

- https://github.com/loopengine/loop-examples/tree/main/ai-actors/claude
- https://github.com/loopengine/loop-examples/tree/main/ai-actors/openai


---

## Demand Signal
URL: https://bossloops.io
/docs/examples/demand-signal
Summary: Rule-based signal detection that triggers loop start - no AI required.
Section: Examples


<Callout variant="info" title="Full source">
<a href="https://github.com/loopengine/loop-examples/tree/main/demand-signal" target="_blank" rel="noreferrer">
github.com/loopengine/loop-examples/tree/main/demand-signal
</a>
</Callout>

## What this example shows

Not every loop needs AI. This example models rule-based detection where an automation actor watches metrics and emits a start signal when thresholds are crossed. It is the SENSE stage in the operational loop pattern.

## Loop diagram

```text
METRIC_STREAM --[threshold_breach]--> SIGNAL_DETECTED
SIGNAL_DETECTED --[start_loop]--> LOOP_STARTED
LOOP_STARTED --[run_governed_flow]--> COMPLETE
```

## Actors

| Actor | Type | Transitions | Guards |
|---|---|---|---|
| detector | automation | `threshold_breach`, `start_loop` | none |
| runtime | system | `loop_start` | none |

## Key annotated snippet

```ts
// @no-typecheck
// Roadmap-oriented narrative; published @loop-engine/signals is `SignalRegistry` only at 1.0.0-rc.0.
import { createSignalEngine, thresholdBreachRule } from "@loop-engine/signals";
import { aggregateId } from "@loop-engine/core";

const signalEngine = createSignalEngine();
signalEngine.registerRule(
  thresholdBreachRule({
    field: "demandChange",
    operator: "gt",
    threshold: 0.75
  })
);

signalEngine.subscribe(async (signal) => {
  await engine.start({
    loopId: "scm.replenishment",
    aggregateId: aggregateId(`repl-${Date.now()}`),
    actor: { type: "automation", id: "system:signal-detector" },
    metadata: {
      sourceSignalType: signal.type,
      sourceSignalId: signal.id,
      sku: signal.payload?.sku
    }
  });
});
```

## What emitted events look like

```ts
{
  type: "loop.started",
  loopId: "scm.replenishment",
  aggregateId: "repl-1710339001422",
  initialState: "SIGNAL_DETECTED",
  actor: { type: "automation", id: "system:signal-detector" },
  occurredAt: "2026-03-13T12:40:50.111Z"
}
```

## Try it yourself

```bash
cd loop-examples/demand-signal
pnpm install
pnpm dev
```


---

## Postgres Persistence
URL: https://bossloops.io
/docs/examples/postgres-persistence
Summary: Swap the in-memory adapter for Postgres - the adapter contract in practice.
Section: Examples


<Callout variant="info" title="Full source">
<a href="https://github.com/loopengine/loop-examples/tree/main/postgres-persistence" target="_blank" rel="noreferrer">
github.com/loopengine/loop-examples/tree/main/postgres-persistence
</a>
</Callout>

## What this example shows

Boss Loops storage is an adapter boundary. This example swaps `adapter-memory` for `adapter-postgres` without changing loop definitions or transition logic.

## Loop diagram

```text
START LOOP ----> WRITE INSTANCE (Postgres)
TRANSITION ----> APPEND HISTORY (Postgres)
QUERY STATE ---> READ INSTANCE + READ HISTORY
```

## Actors

| Actor | Type | Transitions | Guards |
|---|---|---|---|
| service runtime | automation | all business transitions | configured in loop definition |
| reviewer (optional) | human | approval transitions | `human-only`, policy guards |

## Key annotated snippet

```ts
import { createLoopSystem } from "@loop-engine/sdk";
import { postgresStore, createSchema } from "@loop-engine/adapter-postgres";
import { memoryStore } from "@loop-engine/adapter-memory";
import { Pool } from "pg";

// Version A: in-memory (default local dev)
const memStore = memoryStore();
const memoryRuntime = await createLoopSystem({ loops: [definition], store: memStore });

// Version B: postgres (durable)
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
await createSchema(pool);
const pgStore = postgresStore(pool);
const postgresRuntime = await createLoopSystem({ loops: [definition], store: pgStore });

// Loop definitions + transition calls are unchanged across adapters.
```

## What emitted events look like

```ts
{
  type: "loop.transition.executed",
  loopId: "expense.approval",
  aggregateId: "EXP-2026-009",
  transitionId: "approve",
  fromState: "PENDING_APPROVAL",
  toState: "APPROVED",
  actor: { type: "human", id: "manager@acme.com" },
  occurredAt: "2026-03-13T12:49:22.290Z"
}
```

## Try it yourself

```bash
cd loop-examples/postgres-persistence
pnpm install
pnpm dev
```

<Callout variant="info" title="Adapter pattern">
The same contract pattern extends to `adapter-kafka` and `adapter-http`. Any backend implementing `LoopStore` can be used.
</Callout>


---

## Event Streaming
URL: https://bossloops.io
/docs/examples/event-streaming
Summary: Event subscriptions and timeline utilities turn loop lifecycle events into auditable operational streams.
Section: Examples


<Callout variant="info" title="Full source">
<a href="https://github.com/loopengine/loop-examples/tree/main/event-streaming" target="_blank" rel="noreferrer">
github.com/loopengine/loop-examples/tree/main/event-streaming
</a>
</Callout>

## What this example shows

Every transition emits a typed event. This example shows how to subscribe, persist an audit stream, and reconstruct a timeline from transition history for replay and debugging.

## Loop diagram

```text
START ----> TRANSITION_1 ----> TRANSITION_2 ----> TERMINAL
  |              |                  |
  +---- emit events on every transition ----+
```

## Actors

| Actor | Type | Transitions | Guards |
|---|---|---|---|
| runtime emitter | automation | all runtime transitions | loop-defined guards |
| subscribers | automation | none (read-only stream consumers) | n/a |

## Key annotated snippet

```ts
// @no-typecheck
import { LOOP_EVENT_TYPES } from "@loop-engine/events";
import { buildTimeline, replayLoop } from "@loop-engine/observability";
import { aggregateId } from "@loop-engine/core";

const audit: Array<{ at: string; type: string; aggregateId: string }> = [];

eventBus.subscribe(async (event) => {
  if (
    event.type === "loop.started" ||
    event.type === "loop.transition.executed" ||
    event.type === "loop.completed"
  ) {
    audit.push({
      at: event.occurredAt,
      type: event.type,
      aggregateId: String(event.aggregateId)
    });
  }
});

const id = aggregateId("EXP-1");
const instance = await engine.getState(id);
const history = await engine.getHistory(id);
if (instance) {
  const timeline = buildTimeline(instance, history);
  const replay = replayLoop(definition, history);
  console.log(timeline.durationMs, replay.valid);
}
```

## What emitted events look like

```ts
{
  type: "loop.transition.executed",
  loopId: "expense.approval",
  aggregateId: "EXP-1",
  transitionId: "approve",
  fromState: "PENDING_APPROVAL",
  toState: "APPROVED",
  actor: { type: "human", id: "manager@acme.com" },
  occurredAt: "2026-03-13T12:57:01.440Z"
}
```

## Try it yourself

```bash
cd loop-examples/event-streaming
pnpm install
pnpm dev
```


---

## Runtime Connections
URL: https://bossloops.io
/docs/integrations
Summary: Three distinct runtime layers — Providers (intelligence), Channels (human coordination), Integrations (systems of record).
Section: Runtime Connections


Boss Loops connects **three different kinds** of external capability. They are not interchangeable buckets of “integrations.”

| Layer | Responsibility | Not this |
| --- | --- | --- |
| **[Providers](/docs/concepts/runtime-taxonomy#providers)** | Intelligence — analyze, recommend, classify, predict | Workflow engine, Slack, CRM |
| **[Channels](/docs/concepts/runtime-taxonomy#channels)** | Human coordination — approve, reject, escalate | System of record, model API |
| **[Integrations](/docs/concepts/runtime-taxonomy#integrations)** | Operational execution — persist, trigger, apply writes | Governance, chat UI |

<Callout variant="info" title="Boss Loops sits in the middle">
**Providers** submit decisions. **Channels** coordinate humans. **Integrations** execute after policy passes. **Loops + guards** govern every transition; **evidence** records why it was allowed.
</Callout>

→ [Runtime Taxonomy](/docs/concepts/runtime-taxonomy) · [Architecture](/docs/getting-started/architecture) · [ABM examples](/docs/examples#abm-and-revops-operational-ai)

**Hosted governance:** [Boss Loops Cloud (HTTP API)](/docs/cloud/api-reference) at `loops.betterdata.co` — multi-tenant connectors and API keys. **OSS runtime:** self-host with `@loop-engine/sdk` in your infrastructure.

**Developer note:** npm packages implement [IntegrationAdapter archetypes](/docs/concepts/integration-adapter) (`Store`, `Registry`, `AI`, `EventBus`). Public grouping below follows the product taxonomy, not package folder names.

## ⟩ Providers — intelligence systems

**Generate intelligence** into the loop: recommendations, classifications, draft copy, research steps. Providers **do not** approve in Slack, **do not** write to CRM, and **do not** bypass guards.

Examples: OpenAI, Anthropic, Gemini, Grok, Perplexity Sonar, Vercel AI SDK.

Use any major LLM as a governed actor. Provider actor adapters produce the same `AIAgentActor` shape — switching providers requires changing one import. Perplexity Sonar covers **grounded retrieval with citations** as a `ToolAdapter` for research steps.

<div className="grid gap-4 md:grid-cols-2">
  <IntegrationCard
    name="Anthropic / Claude"
    subtext="claude-opus-4-6, claude-sonnet-4-6"
    tier="official"
    status="stable"
    attributes={["built-in"]}
    logoPath="/logos/anthropic.svg"
    href="/docs/integrations/anthropic"
  />
  <IntegrationCard
    name="OpenAI"
    subtext="gpt-4o, o-series models"
    tier="official"
    status="stable"
    attributes={["built-in"]}
    logoPath="/logos/openai.svg"
    href="/docs/integrations/openai"
  />
  <IntegrationCard
    name="Grok (xAI)"
    subtext="grok-3, grok-3-mini via xAI API"
    tier="official"
    status="stable"
    attributes={["built-in"]}
    logoPath="/logos/xai.svg"
    href="/docs/integrations/grok"
  />
  <IntegrationCard
    name="Google Gemini"
    subtext="gemini-1.5-pro, gemini-2.0-flash"
    tier="official"
    status="stable"
    attributes={["built-in"]}
    logoPath="/logos/gemini.svg"
    href="/docs/integrations/gemini"
  />
  <IntegrationCard
    name="Perplexity Sonar"
    subtext="sonar, sonar-pro, sonar-reasoning — citations + domain filters"
    tier="official"
    status="rc"
    attributes={["built-in"]}
    logoPath="/logos/perplexity.svg"
    href="/docs/integrations/perplexity"
  />
  <IntegrationCard
    name="Vercel AI SDK"
    subtext="Governed tool calls and streams inside loop transitions"
    tier="official"
    status="stable"
    attributes={["built-in"]}
    logoPath="/logos/vercel.svg"
    href="/docs/integrations/vercel-ai-sdk"
  />
</div>

## ⟩ Channels — human coordination surfaces

**Coordinate humans** — request approvals, surface decisions, escalate operators. Channels **are not** Salesforce, Jira, or Postgres. They **are not** governance (that is loops + guards).

Examples: Slack, Microsoft Teams, email, Google Docs comments, OpenClaw messenger routing.

<div className="grid gap-4 md:grid-cols-2">
  <IntegrationCard
    name="OpenClaw"
    subtext="Route PENDING_HUMAN_APPROVAL to WhatsApp, Telegram, Slack, or Discord"
    tier="official"
    status="stable"
    attributes={["featured"]}
    logoPath="/logos/openclaw.svg"
    href="/docs/integrations/openclaw"
  />
</div>

<Callout variant="info" title="Slack, Teams, and hosted connectors">
Slack and Microsoft Teams connectors are available on **Boss Loops Cloud** for dual-surface approval patterns. OSS `adapter-slack` / `adapter-teams` are planned — see [changelog](/docs/changelog).
</Callout>

## ⟩ Integrations — systems of record

**Execute operational actions** and persist business state **after** governance passes: CRM updates, incident triggers, staged sheet apply, HTTP side effects. Integrations **are not** LLM APIs and **are not** human chat UIs.

Examples: Salesforce (via your connectors), PagerDuty, Jira, Google Workspace apply paths, Postgres, Kafka, Commerce Gateway.

### Persistence and events

<div className="grid gap-4 md:grid-cols-2">
  <IntegrationCard
    name="In-Memory"
    subtext="Zero-config store for development and testing"
    tier="official"
    status="stable"
    attributes={["built-in"]}
    href="/docs/packages/adapter-memory"
  />
  <IntegrationCard
    name="Postgres"
    subtext="Persist loop state and events to PostgreSQL"
    tier="official"
    status="stable"
    attributes={["built-in"]}
    href="/docs/integrations/postgres"
  />
  <IntegrationCard
    name="Kafka"
    subtext="Publish loop events to Kafka topics"
    tier="official"
    status="stable"
    attributes={["built-in"]}
    href="/docs/integrations/kafka"
  />
  <IntegrationCard
    name="HTTP"
    subtext="Generic HTTP adapter — connect any REST backend"
    tier="community"
    href="/docs/integrations/http"
  />
</div>

### Operations and commerce

<div className="grid gap-4 md:grid-cols-2">
  <IntegrationCard
    name="PagerDuty"
    subtext="Incident-triggered governed loops with on-call human steps"
    tier="official"
    status="stable"
    attributes={["built-in"]}
    logoPath="/logos/pagerduty.svg"
    href="/docs/integrations/pagerduty"
  />
  <IntegrationCard
    name="Governed incident (Perplexity + PagerDuty)"
    subtext="Sonar research → governed loop → PagerDuty with audit_ref"
    tier="official"
    status="stable"
    attributes={["built-in"]}
    logoPath="/logos/perplexity.svg"
    href="/docs/integrations/perplexity-pagerduty"
  />
  <IntegrationCard
    name="Commerce Gateway"
    subtext="Controlled connectivity for AI tool execution in operational loops"
    tier="official"
    status="stable"
    attributes={["built-in"]}
    href="/docs/integrations/commerce-gateway"
  />
  <IntegrationCard
    name="Boss Loops Cloud API"
    subtext="Hosted multi-tenant runtime, connectors, and governance API"
    tier="official"
    status="stable"
    attributes={["built-in"]}
    href="/docs/cloud/api-reference"
  />
</div>

## Coverage map (one category per page)

| Connection | Taxonomy | Developer primitive |
| --- | --- | --- |
| Anthropic, OpenAI, Gemini, Grok, Perplexity, Vercel AI SDK | Provider | `ActorAdapter` / `ToolAdapter` |
| OpenClaw | Channel | Human-surface `EventBus` routing |
| Memory, Postgres, Kafka, HTTP, PagerDuty, Commerce Gateway, Boss Loops Cloud API | Integration | `LoopStore` / `EventBus` / operational adapters |
| Perplexity + PagerDuty (composite) | Integration | Provider step + ops trigger in one pattern |
| Vercel AI (`/docs/integrations/vercel-ai`) | Provider | Alias → [vercel-ai-sdk](/docs/integrations/vercel-ai-sdk) |

## Building an adapter?

Implement [IntegrationAdapter](/docs/concepts/integration-adapter) archetypes. Set `taxonomy:` in frontmatter (`provider` \| `channel` \| `integration`) so nav and indexes stay aligned.

- [Runtime Taxonomy](/docs/concepts/runtime-taxonomy)
- [Adapter interface docs →](/docs/running-loops/adapters)
- [Apply for certification →](mailto:oss@betterdata.co)
- [Open an RFC →](https://github.com/loopengine/loop-engine/discussions)


---

## Anthropic / Claude
URL: https://bossloops.io
/docs/integrations/anthropic
Summary: Use Claude as a governed Boss Loops actor — confidence-gated, evidence-backed, fully attributed.
Section: Runtime Connections


<div className="docs-quick-links">
  <span className="docs-status-badge tier-official status-stable">Official · Stable</span>
  <span className="docs-status-badge attr-built-in">Built-in</span>
  <span className="docs-status-badge attr-built-in">npm: @loop-engine/adapter-anthropic</span>
  <span className="docs-status-badge attr-built-in">Provider: Anthropic</span>
</div>

<div className="docs-quick-links md:grid-cols-3">
  <a className="docs-quick-link" href="/docs/packages/adapter-anthropic">Package reference →</a>
  <a className="docs-quick-link" href="https://www.npmjs.com/package/@loop-engine/adapter-anthropic">npm →</a>
  <a className="docs-quick-link" href="/docs/ai-and-automation/ai-as-actor">AI as Actor →</a>
</div>

**Archetype:** [AI](/docs/concepts/integration-adapter#ai-llm-adapter) (Actor) — returns `AIAgentActor` + `AIActorDecision` for governed `engine.transition(...)` submission.

## What it does

`@loop-engine/adapter-anthropic` wraps the Anthropic Messages API as a Boss Loops AI actor. The adapter calls Claude with loop context, parses the structured response, and returns an `AIAgentActor` plus `AIActorDecision` ready for runtime submission. Guards run after the adapter returns — Claude cannot bypass them.

## Quick setup

1. **Install**

   ```bash
   npm install @loop-engine/adapter-anthropic
   npm install @anthropic-ai/sdk
   ```

2. **Create the actor**

   ```typescript
   import { createAnthropicActorAdapter } from "@loop-engine/adapter-anthropic";

   const adapter = createAnthropicActorAdapter({
     apiKey: process.env.ANTHROPIC_API_KEY!,
     model: "claude-opus-4-6"
   });
   ```

3. **Submit to a loop transition**

   ```typescript
   // @no-typecheck
   const { actor, decision } = await adapter.createSubmission({
     loopId: "procurement",
     loopName: "SCM Procurement",
     currentState: "pending_analysis",
     availableSignals: [
       {
         signalId: "submit_recommendation",
         name: "Submit Recommendation",
         allowedActors: ["ai-agent"]
       }
     ],
     instruction: "Analyze demand data and recommend a purchase order.",
     evidence: { demandForecast: 0.91, currentStock: 38 }
   });

   await loopSystem.engine.transition({
     aggregateId: "procurement-1",
     transitionId: decision.transitionId,
     actor,
     evidence: decision
   });
   ```

## How it works

1. Builds a structured prompt from `LoopActorPromptContext`
2. Calls `client.messages.create(...)` with loop context
3. Parses JSON and validates `signalId` + `confidence`
4. Computes SHA-256 `promptHash`
5. Returns `AIAgentActor` (`provider: "anthropic"`) + `AIActorDecision`
6. Caller submits to runtime and guards evaluate after submission

## Configuration reference

| Option | Type | Default | Description |
|---|---|---|---|
| `modelId` | `string` | `claude-opus-4-6` | Anthropic model ID |
| `maxTokens` | `number` | `1024` | Max tokens in response |
| `systemPrompt` | `string` | — | Optional system prompt prepended to loop context |
| `confidenceThreshold` | `number` | `0.7` | Minimum confidence required (0–1) |

## Troubleshooting

- `ActorDecisionError: INVALID_SIGNAL` — Model returned a signal not present in `availableSignals`; tighten instruction language around allowed signals.
- `ActorDecisionError: INVALID_CONFIDENCE` — Confidence was outside 0–1; include "confidence must be between 0 and 1" in `systemPrompt`.
- `ActorDecisionError: API_ERROR` — Check `ANTHROPIC_API_KEY` and model ID validity.

## Related

- [AI as Actor](/docs/ai-and-automation/ai-as-actor)
- [Confidence + Evidence](/docs/ai-and-automation/confidence-evidence)
- [Human Approval Gates](/docs/ai-and-automation/human-approval-gates)
- [OpenAI adapter](/docs/integrations/openai), [Grok adapter](/docs/integrations/grok), [Gemini adapter](/docs/integrations/gemini)


---

## OpenAI
URL: https://bossloops.io
/docs/integrations/openai
Summary: Use OpenAI as a governed Boss Loops actor — confidence-gated, evidence-backed, fully attributed.
Section: Runtime Connections


<div className="docs-quick-links">
  <span className="docs-status-badge tier-official status-stable">Official · Stable</span>
  <span className="docs-status-badge attr-built-in">Built-in</span>
  <span className="docs-status-badge attr-built-in">npm: @loop-engine/adapter-openai</span>
  <span className="docs-status-badge attr-built-in">Provider: OpenAI</span>
</div>

<div className="docs-quick-links md:grid-cols-3">
  <a className="docs-quick-link" href="/docs/packages/adapter-openai">Package reference →</a>
  <a className="docs-quick-link" href="https://www.npmjs.com/package/@loop-engine/adapter-openai">npm →</a>
  <a className="docs-quick-link" href="/docs/ai-and-automation/ai-as-actor">AI as Actor →</a>
</div>

**Archetype:** [AI](/docs/concepts/integration-adapter#ai-llm-adapter) (Actor) — returns `AIAgentActor` + `AIActorDecision` for governed `engine.transition(...)` submission.

## What it does

`@loop-engine/adapter-openai` uses OpenAI chat completions with `response_format: { type: "json_object" }` to produce structured actor decisions. It returns an `AIAgentActor` and `AIActorDecision` for runtime submission where policy guards are enforced.

## Quick setup

1. **Install**

   ```bash
   npm install @loop-engine/adapter-openai openai
   ```

2. **Create the actor**

   ```typescript
   import { createOpenAIActorAdapter } from "@loop-engine/adapter-openai";

   const adapter = createOpenAIActorAdapter({
     apiKey: process.env.OPENAI_API_KEY!,
     model: "gpt-4o"
   });
   ```

3. **Submit to a loop transition**

   ```typescript
   // @no-typecheck
   const { actor, decision } = await adapter.createSubmission({
     loopId: "procurement",
     loopName: "SCM Procurement",
     currentState: "pending_analysis",
     availableSignals: [
       {
         signalId: "submit_recommendation",
         name: "Submit Recommendation",
         allowedActors: ["ai-agent"]
       }
     ],
     instruction: "Analyze demand data and recommend a purchase order.",
     evidence: { demandForecast: 0.89, currentStock: 42, reorderPoint: 50 }
   });

   await loopSystem.engine.transition({
     aggregateId: "procurement-1",
     transitionId: decision.transitionId,
     actor,
     evidence: decision
   });
   ```

## How it works

1. Builds a structured prompt from loop context
2. Calls OpenAI with JSON object response format
3. Parses response and validates `signalId` + `confidence`
4. Computes `promptHash` for auditability
5. Returns actor + decision for runtime enforcement

## Configuration reference

| Option | Type | Default | Description |
|---|---|---|---|
| `modelId` | `string` | `gpt-4o` | OpenAI model ID (`gpt-4o-mini`, `o1`, `o3-mini` also supported) |
| `maxTokens` | `number` | `1024` | Max tokens in response |
| `systemPrompt` | `string` | — | Optional system prompt prepended to loop context |
| `confidenceThreshold` | `number` | `0.7` | Minimum confidence required (0–1) |

## Troubleshooting

- `ActorDecisionError: INVALID_SIGNAL` — Returned `signalId` is not in `availableSignals`.
- `ActorDecisionError: INVALID_CONFIDENCE` — Confidence outside 0–1; constrain via `systemPrompt`.
- `ActorDecisionError: API_ERROR` — Check `OPENAI_API_KEY` and model availability.

## Related

- [AI as Actor](/docs/ai-and-automation/ai-as-actor)
- [Confidence + Evidence](/docs/ai-and-automation/confidence-evidence)
- [Human Approval Gates](/docs/ai-and-automation/human-approval-gates)
- [Anthropic adapter](/docs/integrations/anthropic), [Grok adapter](/docs/integrations/grok), [Gemini adapter](/docs/integrations/gemini)


---

## Grok (xAI)
URL: https://bossloops.io
/docs/integrations/grok
Summary: Use Grok as a governed Boss Loops actor through xAI's OpenAI-compatible API.
Section: Runtime Connections


<div className="docs-quick-links">
  <span className="docs-status-badge tier-official status-stable">Official · Stable</span>
  <span className="docs-status-badge attr-built-in">Built-in</span>
  <span className="docs-status-badge attr-built-in">npm: @loop-engine/adapter-grok</span>
  <span className="docs-status-badge attr-built-in">Provider: xAI</span>
</div>

<div className="docs-quick-links md:grid-cols-3">
  <a className="docs-quick-link" href="/docs/packages/adapter-grok">Package reference →</a>
  <a className="docs-quick-link" href="https://www.npmjs.com/package/@loop-engine/adapter-grok">npm →</a>
  <a className="docs-quick-link" href="/docs/ai-and-automation/ai-as-actor">AI as Actor →</a>
</div>

**Archetype:** [AI](/docs/concepts/integration-adapter#ai-llm-adapter) (Actor) — returns `AIAgentActor` + `AIActorDecision` for governed `engine.transition(...)` submission.

## What it does

`@loop-engine/adapter-grok` uses the OpenAI SDK pointed at `https://api.x.ai/v1`. Grok's API is OpenAI-compatible, so the adapter follows the same structural pattern while attributing `provider: "grok"` in actor records.

## Quick setup

1. **Install**

   ```bash
   npm install @loop-engine/adapter-grok openai
   ```

2. **Create the actor**

   ```typescript
   import { createGrokActorAdapter } from "@loop-engine/adapter-grok";

   const adapter = createGrokActorAdapter(process.env.XAI_API_KEY!, {
     modelId: "grok-3",
     baseURL: "https://api.x.ai/v1"
   });
   ```

3. **Submit to a loop transition**

   ```typescript
   const { actor, decision } = await adapter.createSubmission({
     loopId: "procurement",
     loopName: "SCM Procurement",
     currentState: "pending_analysis",
     availableSignals: [{ signalId: "submit_recommendation", name: "Submit Recommendation", allowedActors: ["ai-agent"] }],
     instruction: "Analyze demand data and recommend a purchase order.",
     evidence: { demandForecast: 0.87, currentStock: 41 }
   });

   await loopSystem.engine.transition({
     aggregateId: "procurement-1",
     transitionId: decision.transitionId,
     actor,
     evidence: decision
   });
   ```

## How it works

1. Builds loop prompt context
2. Calls xAI endpoint through OpenAI-compatible SDK
3. Parses and validates structured response
4. Returns attributed actor + decision for runtime guard enforcement

## Configuration reference

| Option | Type | Default | Description |
|---|---|---|---|
| `modelId` | `string` | `grok-3` | xAI model ID (`grok-3-mini`, `grok-2`, `grok-2-mini`) |
| `baseURL` | `string` | `https://api.x.ai/v1` | Override endpoint (useful for testing) |
| `maxTokens` | `number` | `1024` | Max tokens in response |
| `confidenceThreshold` | `number` | `0.7` | Minimum confidence required (0–1) |

## Troubleshooting

- `ActorDecisionError: API_ERROR` — Verify `XAI_API_KEY` in xAI console and endpoint availability.
- `ActorDecisionError: INVALID_SIGNAL` — Clarify `availableSignals` in instruction.
- OpenAI SDK-flavored errors are expected because Grok adapter uses the OpenAI client shape.

## Related

- [AI as Actor](/docs/ai-and-automation/ai-as-actor)
- [OpenAI adapter](/docs/integrations/openai)
- [Anthropic adapter](/docs/integrations/anthropic)
- [Gemini adapter](/docs/integrations/gemini)


---

## Google Gemini
URL: https://bossloops.io
/docs/integrations/gemini
Summary: Use Gemini as a governed Boss Loops actor with confidence thresholds and auditable submissions.
Section: Runtime Connections


<div className="docs-quick-links">
  <span className="docs-status-badge tier-official status-stable">Official · Stable</span>
  <span className="docs-status-badge attr-built-in">Built-in</span>
  <span className="docs-status-badge attr-built-in">npm: @loop-engine/adapter-gemini</span>
  <span className="docs-status-badge attr-built-in">Provider: Google</span>
</div>

<div className="docs-quick-links md:grid-cols-3">
  <a className="docs-quick-link" href="/docs/packages/adapter-gemini">Package reference →</a>
  <a className="docs-quick-link" href="https://www.npmjs.com/package/@loop-engine/adapter-gemini">npm →</a>
  <a className="docs-quick-link" href="/docs/ai-and-automation/ai-as-actor">AI as Actor →</a>
</div>

**Archetype:** [AI](/docs/concepts/integration-adapter#ai-llm-adapter) (Actor) — returns `AIAgentActor` + `AIActorDecision` for governed `engine.transition(...)` submission.

## What it does

`@loop-engine/adapter-gemini` wraps Gemini API calls as Boss Loops actor submissions. It returns structured decisions for runtime guard enforcement, preserving attribution and evidence on every transition.

## Quick setup

1. **Install**

   ```bash
   npm install @loop-engine/adapter-gemini @google/generative-ai
   ```

2. **Create the actor**

   ```typescript
   import { createGeminiActorAdapter } from "@loop-engine/adapter-gemini";

   const adapter = createGeminiActorAdapter(process.env.GOOGLE_AI_API_KEY!, {
     modelId: "gemini-1.5-pro"
   });
   ```

3. **Submit to a loop transition**

   ```typescript
   const { actor, decision } = await adapter.createSubmission({
     loopId: "procurement",
     loopName: "SCM Procurement",
     currentState: "pending_analysis",
     availableSignals: [{ signalId: "submit_recommendation", name: "Submit Recommendation", allowedActors: ["ai-agent"] }],
     instruction: "Analyze demand data and recommend a purchase order.",
     evidence: { demandForecast: 0.93, currentStock: 36 }
   });

   await loopSystem.engine.transition({
     aggregateId: "procurement-1",
     transitionId: decision.transitionId,
     actor,
     evidence: decision
   });
   ```

## How it works

1. Formats context using Boss Loops actor prompt shape
2. Calls Gemini generate endpoint
3. Parses decision JSON and validates fields
4. Returns actor + decision for runtime guard evaluation

## Configuration reference

| Option | Type | Default | Description |
|---|---|---|---|
| `modelId` | `string` | `gemini-1.5-pro` | Gemini model (`gemini-1.5-flash`, `gemini-2.0-flash`) |
| `maxOutputTokens` | `number` | `1024` | Max output tokens |
| `systemPrompt` | `string` | — | Optional system prompt prepended to loop context |
| `confidenceThreshold` | `number` | `0.7` | Minimum confidence required (0–1) |

## Troubleshooting

- `ActorDecisionError: PARSE_FAILED` — Gemini may wrap JSON in markdown fences; add "raw JSON only" to `systemPrompt`.
- `ActorDecisionError: API_ERROR` — Verify `GOOGLE_AI_API_KEY` in AI Studio.
- `ActorDecisionError: INVALID_CONFIDENCE` — Ensure response confidence is numeric between 0 and 1.

## Related

- [AI as Actor](/docs/ai-and-automation/ai-as-actor)
- [OpenAI adapter](/docs/integrations/openai)
- [Anthropic adapter](/docs/integrations/anthropic)
- [Grok adapter](/docs/integrations/grok)


---

## Perplexity Sonar
URL: https://bossloops.io
/docs/integrations/perplexity
Summary: Grounded web retrieval with citations — use Sonar inside Loop steps that need verifiable, real-time information.
Section: Runtime Connections


<div className="docs-quick-links">
  <span className="docs-status-badge tier-official status-rc">Official · RC</span>
  <span className="docs-status-badge attr-built-in">Built-in</span>
  <span className="docs-status-badge attr-built-in">npm: @loop-engine/adapter-perplexity</span>
  <span className="docs-status-badge attr-built-in">Provider: Perplexity</span>
</div>

<div className="docs-quick-links md:grid-cols-3">
  <a className="docs-quick-link" href="/docs/packages/adapter-perplexity">Package reference →</a>
  <a className="docs-quick-link" href="/docs/integrations/perplexity-pagerduty">Governed incident pattern →</a>
  <a className="docs-quick-link" href="/docs/ai-and-automation/confidence-evidence">Confidence + evidence →</a>
</div>

**Archetype:** [AI](/docs/concepts/integration-adapter#ai-llm-adapter) (Tool) — implements `ToolAdapter.invoke(...)` for grounded retrieval with citations.

## What it does

`@loop-engine/adapter-perplexity` implements `ToolAdapter.invoke()` against the Sonar chat API. You get answer text plus structured citations for audit and evidence attachment. Use it where provenance matters more than open-ended generation.

## When to use it

- Regulatory or policy research with domain allowlists
- Supplier, market, or news checks inside a governed Loop
- Any step where you must show **which sources** justified the output

## Quick setup

1. **Install**

   ```bash
   npm install @loop-engine/adapter-perplexity
   ```

2. **Create the adapter**

   ```typescript
   import { PerplexityAdapter } from "@loop-engine/adapter-perplexity";

   const perplexity = new PerplexityAdapter({
     apiKey: process.env.PERPLEXITY_API_KEY!,
     defaultModel: "sonar-pro",
     defaultSearchRecency: "month",
   });
   ```

3. **Invoke from your Loop step**

   See the full API, metadata keys, and error table on the [package reference](/docs/packages/adapter-perplexity).

## Related

- [Governed Incident Response with Perplexity and PagerDuty](/docs/integrations/perplexity-pagerduty)
- [PagerDuty integration](/docs/integrations/pagerduty)


---

## Vercel AI SDK
URL: https://bossloops.io
/docs/integrations/vercel-ai-sdk
Summary: Stream AI responses inside governed Boss Loops transitions — use the Vercel AI SDK for model calls, Boss Loops for governance.
Section: Runtime Connections


<div className="docs-quick-links">
  <span className="docs-status-badge tier-official status-stable">Official · Stable</span>
  <span className="docs-status-badge attr-built-in">Built-in</span>
  <span className="docs-status-badge attr-built-in">npm: @loop-engine/adapter-vercel-ai</span>
</div>

<div className="docs-quick-links md:grid-cols-3">
  <a className="docs-quick-link" href="/docs/packages/adapter-openai">OpenAI package reference →</a>
  <a className="docs-quick-link" href="https://www.npmjs.com/package/@loop-engine/adapter-vercel-ai">npm →</a>
  <a className="docs-quick-link" href="/docs/ai-and-automation/ai-as-actor">AI as Actor →</a>
</div>

## What it does

Vercel AI SDK handles streaming and model access. Boss Loops governs when and whether model-requested tool actions are authorized. Use Vercel AI SDK for model execution; use Boss Loops for guard enforcement, actor attribution, and audit trails.

## Quick setup

1. **Install**

   ```bash
   npm install @loop-engine/adapter-vercel-ai ai
   ```

2. **Wrap a tool with governance**

   ```typescript
   import { z } from "zod";
   import { streamText, tool } from "ai";
   import { actorId, type ActorRef } from "@loop-engine/core";
   import { wrapTool, type CoreTool } from "@loop-engine/adapter-vercel-ai";

   // `wrapTool` expects the adapter's `CoreTool` shape; bridge the Vercel AI `tool()` helper
   // by wrapping a thin CoreTool that delegates to the same work unit.
   const baseTool = tool({
     description: "Submit purchase order",
     inputSchema: z.object({ vendor: z.string(), amount: z.number() }),
     execute: async ({ vendor, amount }) => ({ orderId: "PO-0042", vendor, amount })
   });
   const submitPurchaseOrder = wrapTool(baseTool as unknown as CoreTool<{ vendor: string; amount: number }, { orderId: string; vendor: string; amount: number }>, {
     loopDefinition: purchaseOrderLoop,
     engine,
     actor: {
       type: "ai-agent",
       id: actorId("ai:vercel-tool"),
       modelId: "gpt-4o",
       provider: "openai"
     } as ActorRef,
     requiresApproval: (input) => input.amount > 5000
   });
   ```

3. **Run with streaming**

   ```typescript
   await streamText({
     model: openai("gpt-4o"),
     tools: { submitPurchaseOrder },
     prompt: "Submit a PO to Acme Medical for $9,200"
   });
   ```

## How it works

1. Model requests tool invocation
2. Adapter starts and advances loop transitions
3. Approval gates hold high-impact actions
4. Human decision unblocks execution
5. Execution and evidence are appended to history

## Configuration reference

| Option | Type | Default | Description |
|---|---|---|---|
| `loopDefinition` | `LoopDefinition` | required | Governance state machine for the tool |
| `engine` | `LoopEngine` | required | Runtime instance |
| `requiresApproval` | `(input) => boolean` | — | Predicate for human checkpointing |
| `onApprovalRequired` | `(loopId, input) => Promise<void>` | — | Notification hook |
| `actor` | `Actor` | `ai-agent` | Actor attribution for transition records |

## Troubleshooting

- **Streaming parse errors** — Enforce strict JSON response contracts in tool output.
- **Model resolution errors** — Verify the selected model provider is available in your AI SDK config.
- **Missing approvals** — Ensure `requiresApproval` returns true for high-risk tool inputs.

## Related

- [AI as Actor](/docs/ai-and-automation/ai-as-actor)
- [Anthropic integration](/docs/integrations/anthropic)
- [OpenAI integration](/docs/integrations/openai)


---

## Vercel AI SDK
URL: https://bossloops.io
/docs/integrations/vercel-ai
Summary: Stream AI responses inside governed Boss Loops transitions — use the Vercel AI SDK for model calls, Boss Loops for governance.
Section: Runtime Connections


<Callout variant="info" title="Canonical path">
Use [/docs/integrations/vercel-ai-sdk](/docs/integrations/vercel-ai-sdk) as the primary route. This page remains for backward-compatible links.
</Callout>

## What it does

Vercel AI SDK handles streaming and model access. Boss Loops governs when and whether model-requested tool actions are authorized. Use Vercel AI SDK for model execution; use Boss Loops for guard enforcement, actor attribution, and audit trails.

## Quick setup

1. **Install**

   ```bash
   npm install @loop-engine/adapter-vercel-ai ai
   ```

2. **Wrap a tool with governance**

   ```typescript
   import { z } from "zod";
   import { streamText, tool } from "ai";
   import { actorId, type ActorRef } from "@loop-engine/core";
   import { wrapTool, type CoreTool } from "@loop-engine/adapter-vercel-ai";

   const baseTool = tool({
     description: "Submit purchase order",
     inputSchema: z.object({ vendor: z.string(), amount: z.number() }),
     execute: async ({ vendor, amount }) => ({ orderId: "PO-0042", vendor, amount })
   });
   const submitPurchaseOrder = wrapTool(baseTool as unknown as CoreTool<{ vendor: string; amount: number }, { orderId: string; vendor: string; amount: number }>, {
     loopDefinition: purchaseOrderLoop,
     engine,
     actor: {
       type: "ai-agent",
       id: actorId("ai:vercel-tool"),
       modelId: "gpt-4o",
       provider: "openai"
     } as ActorRef,
     requiresApproval: (input) => input.amount > 5000
   });
   ```

3. **Run with streaming**

   ```typescript
   await streamText({
     model: openai("gpt-4o"),
     tools: { submitPurchaseOrder },
     prompt: "Submit a PO to Acme Medical for $9,200"
   });
   ```


---

## OpenClaw
URL: https://bossloops.io
/docs/integrations/openclaw
Summary: Boss Loops as the decision governance layer for OpenClaw agentic workflows — policy enforcement at the runtime level.
Section: Runtime Connections


<div className="docs-quick-links">
  <span className="docs-status-badge attr-featured">★ Featured</span>
  <span className="docs-status-badge tier-official status-stable">Official · Stable</span>
  <span className="docs-status-badge attr-built-in">Built-in</span>
  <span className="docs-status-badge attr-built-in">npm: @loop-engine/adapter-openclaw</span>
  <span className="docs-status-badge attr-built-in">Channel</span>
</div>

<div className="docs-quick-links md:grid-cols-3">
  <a className="docs-quick-link" href="/docs/concepts/runtime-taxonomy#channels">Runtime taxonomy →</a>
  <a className="docs-quick-link" href="https://docs.openclaw.ai">OpenClaw docs →</a>
  <a className="docs-quick-link" href="/docs/packages/adapter-openclaw">Package reference →</a>
  <a className="docs-quick-link" href="/partners#openclaw">Partner page →</a>
</div>

**Archetype:** [EventBus](/docs/concepts/integration-adapter#eventbus-adapter) — `@loop-engine/adapter-openclaw` forwards selected loop events to OpenClaw's gateway; governed transitions go through `loopSystem.engine.transition(...)`.

## What it does

Boss Loops provides the decision governance layer for OpenClaw workflows. OpenClaw handles agentic reasoning and tool orchestration; Boss Loops governs which actions are authorized, by whom, under what policy, and records full attribution for each transition.

This is the Sense → Decide → Govern pattern in practice:

- OpenClaw retrieves context and reasons over it (`Decide`)
- Boss Loops evaluates policy and transition guards (`Govern`)
- Action executes only after the loop permits it (`Execute`)

## Quick setup

1. **Install**

   ```bash
   npm install @loop-engine/adapter-openclaw @loop-engine/sdk
   ```

2. **Wire Boss Loops into an OpenClaw workflow**

   ```typescript
   // @no-typecheck
   import { createLoopSystem } from "@loop-engine/sdk";
   import { OpenClawAdapter } from "@loop-engine/adapter-openclaw";

   const loopSystem = await createLoopSystem({
     loops: [procurementLoop]
   });
   // loopSystem is { engine: LoopEngine, signals?: SignalEngine, eventBus: InMemoryEventBus }

   const openclaw = new OpenClawAdapter({ engine: loopSystem.engine });
   ```

3. **Define the governed decision point**

   ```typescript
   // @no-typecheck
   const proposal = await openclaw.proposeAction({
     workflowId: "procurement-workflow",
     action: "submit_purchase_order",
     input: { vendor: "Acme Medical Devices", amount: 9200 }
   });

   await loopSystem.engine.transition({
     aggregateId: proposal.aggregateId,
     transitionId: proposal.transitionId,
     actor: proposal.actor,
     evidence: proposal.evidence
   });
   ```

## How it works

1. OpenClaw agent proposes an action
2. Adapter maps proposal to a Boss Loops transition
3. Runtime evaluates guards and policies
4. Human approval gate pauses when required
5. Approved transition executes and is fully audited

## Configuration reference

| Option | Type | Default | Description |
|---|---|---|---|
| `engine` | `LoopEngine` | required | Runtime instance used for governed transitions (pass `loopSystem.engine` from `createLoopSystem`) |
| `transitionMap` | `Record<string, TransitionId>` | `{}` | Optional action-to-transition mapping override |
| `defaultActor` | `Actor` | `ai-agent/openclaw` | Fallback actor attribution metadata |
| `onProposal` | `(proposal) => Promise<void>` | — | Optional hook before transition submission |

## Troubleshooting

- **Transition mapping mismatch** — Ensure OpenClaw action IDs map to valid loop transition IDs.
- **Transition blocked by guard** — Inspect runtime decision and evidence payload in transition history.
- **Approval not routing** — Confirm your approval notifier is subscribed to pending-state transitions.

## Related

- [Decision Governance](/docs/concepts/decision-governance)
- [Agents and RAG](/docs/concepts/agents-and-rag)
- [Human Approval Gates](/docs/ai-and-automation/human-approval-gates)
- [OpenClaw docs](https://docs.openclaw.ai)


---

## Postgres
URL: https://bossloops.io
/docs/integrations/postgres
Summary: Persist decision loop state and events to PostgreSQL — production-ready storage with full event history.
Section: Runtime Connections


<div className="docs-quick-links">
  <span className="docs-status-badge tier-official status-stable">Official · Stable</span>
  <span className="docs-status-badge attr-built-in">Built-in</span>
  <span className="docs-status-badge attr-built-in">npm: @loop-engine/adapter-postgres</span>
  <span className="docs-status-badge attr-built-in">Integration</span>
</div>

<div className="docs-quick-links md:grid-cols-2">
  <a className="docs-quick-link" href="/docs/concepts/runtime-taxonomy#integrations">Runtime taxonomy →</a>
  <a className="docs-quick-link" href="/docs/packages/adapter-postgres">Package reference →</a>
</div>

**Archetype:** [Store](/docs/concepts/integration-adapter#store-adapter) — implements `LoopStore`, slotted at `options.store`.

## What it does

Swaps the in-memory adapter for PostgreSQL persistence. Loop state, transitions, and events are stored in Postgres through the same `LoopStore` interface, so loop definitions and business logic remain unchanged.

## Quick setup

1. **Install**

   ```bash
   npm install @loop-engine/adapter-postgres
   ```

2. **Create a `LoopStore` with `postgresStore`**

   ```typescript
   // @no-typecheck
   import { createPool, postgresStore } from "@loop-engine/adapter-postgres";
   import { createLoopSystem } from "@loop-engine/sdk";

   const pool = createPool({ connectionString: process.env.DATABASE_URL! });
   const store = postgresStore(pool);
   const { engine } = await createLoopSystem({
     loops: [procurementLoop],
     store
   });
   ```

3. **Local vs production pattern**

   ```typescript
   // Dev: in-memory (default) — omit `store`
   const dev = await createLoopSystem({ loops: [procurementLoop] });

   // Prod: pass `store: postgresStore(pool)` as above
   ```

## Schema note

On first startup, the adapter creates required persistence tables:

- `loop_instances`
- `loop_events`
- `loop_transitions`

## Configuration reference

| Option | Type | Default | Description |
|---|---|---|---|
| `connectionString` | `string` | required | Postgres connection URL |
| `maxConnections` | `number` | `10` | Connection pool size |
| `ssl` | `boolean` | `false` | Enable SSL for connection |

## Troubleshooting

- **Connection refused** — Verify database host/port and credentials.
- **Migration failed** — Adapter user requires `CREATE TABLE` privileges.
- **Slow queries** — Add targeted indexes for your query paths, for example:

  ```sql
  CREATE INDEX IF NOT EXISTS idx_loop_instances_loop_id
  ON loop_instances(loop_id);
  ```

## Related

- [Postgres Persistence example](/docs/examples/postgres-persistence)
- [Kafka integration](/docs/integrations/kafka)
- [Adapter interface](/docs/running-loops/adapters)


---

## Kafka
URL: https://bossloops.io
/docs/integrations/kafka
Summary: Publish Boss Loops events to Kafka topics — event streaming for audit, analytics, and downstream integration.
Section: Runtime Connections


<div className="docs-quick-links">
  <span className="docs-status-badge tier-official status-stable">Official · Stable</span>
  <span className="docs-status-badge attr-built-in">Built-in</span>
  <span className="docs-status-badge attr-built-in">npm: @loop-engine/adapter-kafka</span>
</div>

**Archetype:** [EventBus](/docs/concepts/integration-adapter#eventbus-adapter) — routes lifecycle events to Kafka topics, slotted at `options.eventBus`.

## What it does

Publishes Boss Loops events (`LoopTransitionedEvent`, `LoopStartedEvent`, `LoopCompletedEvent`, `LearningSignalEmittedEvent`) to Kafka topics. Use this for audit pipelines, analytics, and cross-system event triggers.

## Quick setup

1. **Install**

   ```bash
   npm install @loop-engine/adapter-kafka kafkajs
   ```

2. **Create a Kafka-backed `EventBus` with `kafkaEventBus`**

   `kafkaEventBus` publishes loop events to Kafka. The `emit` path is supported at `1.0.0-rc.0`; the `kafkajs` client’s `producer().send` return type is slightly wider than the internal `KafkaLike` stub, so the example below uses a narrow `as any` on the `kafka` instance.

   ```typescript
   // @no-typecheck
   import { Kafka } from "kafkajs";
   import { kafkaEventBus } from "@loop-engine/adapter-kafka";
   import { createLoopSystem } from "@loop-engine/sdk";

   const brokers = ["kafka-1:9092", "kafka-2:9092"];
   const connection = new Kafka({ clientId: "loop-engine", brokers });
   const events = kafkaEventBus({
     kafka: connection as any,
     topic: "loop-engine.events"
   });

   const { engine, eventBus: loopBus } = await createLoopSystem({ loops: [procurementLoop] });
   // Application wiring: bridge `loopBus` → `events` (or use `events` as the sole bus) per your deployment.
   void engine;
   void events;
   void loopBus;
   ```

## Configuration reference

| Option | Type | Default | Description |
|---|---|---|---|
| `brokers` | `string[]` | required | Kafka broker list |
| `topicPrefix` | `string` | `loop-engine` | Prefix for emitted event topics |
| `clientId` | `string` | `loop-engine` | Kafka client ID |
| `ssl` | `boolean` | `false` | Enable TLS |
| `sasl` | `object` | — | SASL credentials and mechanism |

## Troubleshooting

- **Connection timeout** — Check broker addresses and network policy/firewall.
- **Authentication error** — Validate `sasl` mechanism/user/secret.
- **Topic missing** — Enable topic auto-create or pre-create topics manually.

## Related

- [Event Streaming example](/docs/examples/event-streaming)
- [Events package](/docs/packages/events)
- [Postgres integration](/docs/integrations/postgres)


---

## HTTP Adapter
URL: https://bossloops.io
/docs/integrations/http
Summary: Generic HTTP storage adapter — connect Boss Loops to any REST backend that implements the adapter protocol.
Section: Runtime Connections


<div className="docs-quick-links">
  <span className="docs-status-badge tier-community">Community</span>
  <span className="docs-status-badge attr-built-in">npm: @loop-engine/adapter-http</span>
</div>

## What it does

The `@1.0.0-rc.0` package exports `httpEventBus` — a webhook-oriented `EventBus` that can emit loop lifecycle events to an HTTP endpoint. (A generic `LoopStore` over HTTP is not in this release surface.)

## Adapter protocol

Expected backend endpoints:

- `POST /loops/:id/start`
- `GET /loops/:id`
- `POST /loops/:id/transition`
- `GET /loops/:id/events`

## Quick setup

1. **Install**

   ```bash
   npm install @loop-engine/adapter-http
   ```

2. **Create an `httpEventBus` for outbound webhook emission**

   ```typescript
   import { httpEventBus } from "@loop-engine/adapter-http";

   const events = httpEventBus({
     webhookUrl: "https://observability.internal/loop-engine/events"
   });
   // Wire `events` with your `LoopEngine` / `InMemoryEventBus` composition in application code.
   void events;
   ```

## Note

If your backend is in the same process, implementing `LoopStore` directly is usually simpler than standing up the HTTP protocol.

## Configuration reference

| Option | Type | Default | Description |
|---|---|---|---|
| `baseUrl` | `string` | required | Base URL for storage API |
| `timeoutMs` | `number` | `5000` | Request timeout |
| `headers` | `Record<string, string>` | — | Additional auth or routing headers |

## Related

- [Adapter interface](/docs/running-loops/adapters)
- [Postgres integration](/docs/integrations/postgres)


---

## In-Memory Adapter
URL: https://bossloops.io
/docs/integrations/memory
Summary: Built-in development storage adapter for local loops and tests.
Section: Runtime Connections


<div className="docs-quick-links">
  <span className="docs-status-badge tier-official status-stable">Official · Stable</span>
  <span className="docs-status-badge attr-built-in">Built-in</span>
</div>

**Archetype:** [Store](/docs/concepts/integration-adapter#store-adapter) — implements `LoopStore`, slotted at `options.store`.

The in-memory adapter is the default storage for local development and tests. It requires zero configuration and is ideal for quick prototyping.

For API details and full reference, use:

- [@loop-engine/adapter-memory package reference](/docs/packages/adapter-memory)
- [Adapter interface docs](/docs/running-loops/adapters)


---

## PagerDuty
URL: https://bossloops.io
/docs/integrations/pagerduty
Summary: Incident-triggered loops — PagerDuty alerts start governed Boss Loops response workflows with full attribution.
Section: Runtime Connections


<div className="docs-quick-links">
  <span className="docs-status-badge tier-official status-stable">Official · Stable</span>
  <span className="docs-status-badge attr-built-in">Built-in</span>
  <span className="docs-status-badge attr-built-in">npm: @loop-engine/adapter-pagerduty</span>
</div>

## What it does

PagerDuty incidents can trigger Boss Loops workflows, turning urgent alerts into governed and attributable response loops. The adapter maps incident events to loop signals, starts a loop per incident, and keeps human decisions in-policy.

## Use case

PagerDuty fires a `SEV-2` database incident:

1. Boss Loops starts `incident-response` loop
2. On-call engineer acknowledges (human-only guard)
3. Runbook automation executes
4. Loop closes and emits learning signal

## Quick setup

1. **Install**

   ```bash
   npm install @loop-engine/adapter-pagerduty
   ```

2. **Configure webhook endpoint**

   ```text
   POST https://your-app.example.com/hooks/pagerduty
   ```

3. **Wire a `PagerDutyNotifier` (Events v2 key)**

   ```typescript
   import { PagerDutyNotifier } from "@loop-engine/adapter-pagerduty";

   const notifier = new PagerDutyNotifier({
     integrationKey: process.env.PAGERDUTY_INTEGRATION_KEY!
   });
   void notifier;
   ```

4. **Define incident loop**

   ```yaml
   loopId: incident-response
   initialState: triage
   states:
     - stateId: triage
       transitions:
         - signalId: acknowledge_incident
           toState: executing
   ```

## Configuration reference

| Option | Type | Default | Description |
|---|---|---|---|
| `webhookSecret` | `string` | required | PagerDuty webhook signing secret |
| `incidentLoopId` | `string` | required | Loop definition ID to start on incident |
| `severityMap` | `object` | — | Map PagerDuty severity to loop signals |

## Troubleshooting

- **Webhook signature invalid** — Ensure `webhookSecret` matches PagerDuty integration settings.
- **Loop not starting** — Verify `incidentLoopId` is registered in runtime.

## Related

- [Governed Incident Response with Perplexity and PagerDuty](/docs/integrations/perplexity-pagerduty)
- [Perplexity Sonar](/docs/integrations/perplexity)
- [Infrastructure Change Approval example](/docs/examples/infrastructure-change-approval)
- [Human Approval Gates](/docs/ai-and-automation/human-approval-gates)
- [PagerDuty webhook docs](https://developer.pagerduty.com/docs/webhooks)


---

## Governed Incident Response with Perplexity and PagerDuty
URL: https://bossloops.io
/docs/integrations/perplexity-pagerduty
Summary: Research with citations, governance in Boss Loops, execution and escalation in PagerDuty — with a tamper-evident audit trail throughout.
Section: Runtime Connections


## Introduction

Perplexity Sonar can research and propose answers. PagerDuty can alert and escalate. Neither product, by itself, produces a compliance-grade record of what the AI did, what sources it used, and who approved the next action. Boss Loops closes that gap: you model the flow as explicit states and transitions, attach evidence at each step, and only then hand off to PagerDuty when policy allows.

The architecture is linear: **Perplexity Sonar** supplies grounded text and citations; **Boss Loops** runs a finite-state loop (for example a `governed-incident-response` definition) with guards and human gates; **PagerDuty** receives Events API v2 triggers when the loop reaches an alerting state. The audit trail is written from the loop side — one entry per material step, with hashes and references you can tie back to incidents.

## Architecture

```text
                    ┌── audit trail (tamper-evident entries per step)
                    │
Perplexity Sonar ──►│  Boss Loops — governed-incident-response FSM
                    │
                    └──► PagerDuty (Events API v2 — trigger / dedupe / custom_details)
```

## The `governed-incident-response` loop

The catalog id `gov.governed-incident-response` (version `0.1.0`) uses the following state set and transitions. Your runtime should register the definition and drive transitions through the same actor boundaries.

**States**

```json
[
  "idle",
  "researching",
  "classifying",
  "auto_approving",
  "human_review",
  "escalating",
  "alerting",
  "complete",
  "rejected",
  "blocked",
  "failed"
]
```

**Key states (annotated)**

| State | Role |
| --- | --- |
| `researching` | Sonar call with domain filter and citation requirement (unless you pre-seed citations and skip research). |
| `classifying` | Derive risk tier from Sonar output — typically **LOW**, **HIGH**, or **BLOCKED**. |
| `human_review` | Configurable gate; timeout paths can escalate through PagerDuty or move to `escalating`. |
| `blocked` | No PagerDuty alert; the audit trail records the block decision and rationale. |
| `alerting` | Build an Events API payload (see below) including `audit_ref` in `custom_details`. |

Full transition graph:

```json
{
  "transitions": [
    { "from": "idle", "to": "researching", "actor": "automation" },
    { "from": "researching", "to": "classifying", "actor": "automation" },
    { "from": "researching", "to": "failed", "actor": "automation" },
    { "from": "classifying", "to": "auto_approving", "actor": "automation" },
    { "from": "classifying", "to": "human_review", "actor": "automation" },
    { "from": "classifying", "to": "blocked", "actor": "human" },
    { "from": "auto_approving", "to": "alerting", "actor": "automation" },
    { "from": "human_review", "to": "alerting", "actor": "human" },
    { "from": "human_review", "to": "rejected", "actor": "human" },
    { "from": "human_review", "to": "escalating", "actor": "automation" },
    { "from": "escalating", "to": "human_review", "actor": "automation" },
    { "from": "escalating", "to": "failed", "actor": "automation" },
    { "from": "alerting", "to": "complete", "actor": "automation" },
    { "from": "alerting", "to": "failed", "actor": "automation" }
  ]
}
```

## Code walkthrough

### 1. Initialize adapters

You wire `PerplexityAdapter` to Sonar and implement a small PagerDuty port that posts to the Events API with your routing key.

```typescript
import type { AdapterInput } from "@loop-engine/core";
import type { PagerDutyEventPayload } from "@loop-engine/adapter-pagerduty";
import { PerplexityAdapter } from "@loop-engine/adapter-perplexity";

const perplexity = new PerplexityAdapter({
  apiKey: process.env.PERPLEXITY_API_KEY!,
  defaultModel: "sonar-pro",
  defaultSearchRecency: "month",
  timeout: 30_000,
  retries: 3,
});

async function sendPagerDutyTrigger(payload: PagerDutyEventPayload): Promise<{ dedupKey: string }> {
  const res = await fetch("https://events.pagerduty.com/v2/enqueue", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(payload),
  });
  if (!res.ok) {
    throw new Error(`PagerDuty enqueue failed: ${res.status}`);
  }
  const body = (await res.json()) as { dedup_key?: string };
  return { dedupKey: body.dedup_key ?? "" };
}

// Your governed-incident module composes { perplexity, pagerduty, auditTrail } into the FSM above.
```

### 2. Run one incident (pre-seeded citations)

When you already have authoritative citations, you skip the live Sonar call and still run classify → gate → alert. The exact function name lives in **your** governed-AI layer; the inputs and outputs below match the pattern we use in production demos.

```typescript
type Citation = { url: string; title: string; snippet?: string };

const result = await yourGovernedIncidentExecutor.run(
  {
    loopId: crypto.randomUUID(),
    perplexitySessionId: "session-abc",
    taskSummary: "PHI access outside approved hours",
    preSeedCitations: [
      { url: "https://www.hhs.gov/hipaa/for-professionals/breach-notification/index.html", title: "HIPAA Breach Notification" },
    ],
    tenantId: "your-tenant-id",
    riskSignal: "unusual_off_hours_phi_access",
  },
  {
    sonarModel: "sonar-pro",
    skipResearchIfCitationsProvided: true,
    euAiActLogging: true,
    hipaaIncidentLogging: true,
  },
  {
    perplexity,
    pagerduty: { sendTrigger: sendPagerDutyTrigger },
    auditTrail: yourAuditTrailWriter,
  },
);

// result.state: 'complete' | 'awaiting_review' | 'blocked' | 'failed' | 'rejected'
// result.auditRef: tamper-evident audit trail reference for the last persisted step
```

### 3. PagerDuty `custom_details`

Include the audit reference so responders and downstream SIEM exports can correlate the incident with Loop evidence.

```typescript
const examplePayload: PagerDutyEventPayload = {
  routing_key: process.env.PAGERDUTY_INTEGRATION_KEY!,
  event_action: "trigger",
  dedup_key: "loop-your-loop-id",
  payload: {
    summary: "Governed incident: PHI access outside approved hours",
    severity: "critical",
    source: "loop-engine/governed-incident-response",
    custom_details: {
      loop_id: "8b7c…",
      audit_ref: "a1f2c3d4e5f67890",
      risk_classification: "HIGH",
      citation_count: 2,
      reviewer_id: "auto-approved",
      sonar_model: "sonar-pro",
      prompt_tokens: 1200,
      completion_tokens: 180,
      eu_ai_act_logging: true,
    },
  },
  links: [{ href: "https://www.hhs.gov/…", text: "HIPAA Breach Notification" }],
};
```

## Audit trail fields

Each row is what you persist per step (names align with common governed-AI implementations). Map them to your control framework columns in the same way you map any other security log schema.

| Field | Compliance mapping (typical) |
| --- | --- |
| `loopId` | Correlation id across systems; ties PagerDuty dedupe to Loop execution |
| `tenantId` | Tenant isolation evidence for multi-entity operators |
| `stepName` | Which FSM phase produced the row (`researching`, `classifying`, `human_review`, …) |
| `timestamp` | Ordering and retention policy scope |
| `inputHash` / `outputHash` | Integrity — detects tampering of serialized step input/output |
| `auditRef` | External reference surfaced in PagerDuty and executive reporting |
| `perplexitySessionId` | Session-level trace for Sonar usage |
| `sonarModel` | Model transparency (EU AI Act Art. 13 style disclosures) |
| `sonarPromptTokens` / `sonarCompletionTokens` | Usage metering and cost attribution |
| `citationCount` / `citationUrls` | Source provenance for verifiable AI outputs |
| `riskClassification` | Policy outcome (LOW / HIGH / BLOCKED) |
| `classificationBasis` | Textual rationale or structured reason code |
| `humanInLoop` | Whether a human gate applied |
| `reviewerId` / `reviewDecision` / `reviewDurationMs` | SOC 2 change / access review style evidence |
| `pagerdutyIncidentId` | Back-link from Loop to on-call ticket |
| `euAiActLogging` / `hipaaIncidentLogging` | Flags for jurisdiction-specific retention and DLP |
| `error` | Failure capture for `failed` transitions |

<Callout variant="important" title="Control mapping (examples)">
  **EU AI Act Article 13** — `sonarModel`, `citationUrls`  
  **SOC 2 CC7.2** — `auditRef`, `reviewerId`, `reviewDecision`  
  **HIPAA §164.308(a)(6)** — `riskClassification`, `reviewDecision`, incident workflow linkage via `pagerdutyIncidentId`
</Callout>

## Environment variables

```text
PERPLEXITY_API_KEY=
PERPLEXITY_DEFAULT_MODEL=sonar-pro
PAGERDUTY_INTEGRATION_KEY=
LOOP_ENGINE_REGISTRY_URL=   # loop catalog HTTP base URL (env name uses REGISTRY_ for compatibility)
LOOP_ENGINE_REGISTRY_ORG=
LOOP_ENGINE_JWT_SECRET=
LOOP_ENGINE_AUTH_ISSUER=
```

## Related

- [Perplexity Sonar package](/docs/packages/adapter-perplexity)
- [PagerDuty integration](/docs/integrations/pagerduty)
- [IT / Governed AI use case](/use-cases)


---

## Commerce Gateway
URL: https://bossloops.io
/docs/integrations/commerce-gateway
Summary: LLM-accessible commerce data for AI actors inside Boss Loops procurement and demand loops.
Section: Runtime Connections


<div className="docs-quick-links">
  <span className="docs-status-badge tier-official status-stable">Official · Stable</span>
  <span className="docs-status-badge attr-built-in">Built-in</span>
  <span className="docs-status-badge attr-built-in">npm: @loop-engine/adapter-commerce-gateway</span>
</div>

<div className="docs-quick-links md:grid-cols-3">
  <a className="docs-quick-link" href="https://commercegateway.io">commercegateway.io →</a>
  <a className="docs-quick-link" href="https://commercegateway.io/docs">Commerce Gateway docs →</a>
  <a className="docs-quick-link" href="/docs/examples/ai-replenishment">AI Replenishment example →</a>
</div>

## What it does

Commerce Gateway provides LLM-accessible commerce data, including product catalog, pricing, inventory, and supplier context through a unified API. AI actors in Boss Loops procurement and demand loops use this data as evidence before submitting governed recommendations.

- Without Commerce Gateway: AI actors lack structured commerce context.
- With Commerce Gateway: actors query commerce data, attach evidence, and submit decisions into runtime guards.

In **Commerce Chain** deployments, SCM and DCM procurement loops often combine Boss Loops governance with Commerce Gateway so AI actors can retrieve product, supplier, and inventory context before submitting governed transitions. See the [Commerce Gateway integration guide](https://commercechain.io/docs/integrations/commerce-gateway) on commercechain.io for the CCO-oriented setup and boundaries.

## Use case

SCM Procurement loop at `ANALYZING`:

1. AI actor queries Commerce Gateway for suppliers on `SKU-4892`
2. Gateway returns structured supplier + inventory data
3. Actor submits recommendation with attached evidence
4. Confidence guard and human approval gates evaluate transition

## Quick setup

1. **Install**

   ```bash
   npm install @loop-engine/adapter-commerce-gateway
   ```

2. **Create a `CommerceGatewayClient`**

   ```typescript
   import { CommerceGatewayClient } from "@loop-engine/adapter-commerce-gateway";

   const gateway = new CommerceGatewayClient({
     baseUrl: process.env.COMMERCE_GATEWAY_URL!,
     apiKey: process.env.COMMERCE_GATEWAY_API_KEY!
   });
   ```

3. **Query commerce context (typed client surface)**

   ```typescript
   // @no-typecheck
   // Illustrative: fetch inventory + price before you attach evidence to a governed transition
   const inv = await gateway.getInventory("SKU-4892");
   const price = await gateway.getCurrentPrice("SKU-4892");
   void { inv, price };
   ```

## Configuration reference

| Option | Type | Default | Description |
|---|---|---|---|
| `baseUrl` | `string` | required | Commerce Gateway base URL |
| `apiKey` | `string` | required | Commerce Gateway API key |

## Troubleshooting

- **401 Unauthorized** — Verify API key and gateway environment.
- **Product not found** — Confirm SKU/GTIN format matches gateway schema.
- **Timeout** — Increase timeout or inspect gateway availability.

## Related

- [AI Replenishment example](/docs/examples/ai-replenishment)
- [Confidence + Evidence](/docs/ai-and-automation/confidence-evidence)
- [Commerce Gateway docs](https://commercegateway.io/docs)


---

## License
URL: https://bossloops.io
/docs/governance/license
Summary: Boss Loops is licensed under Apache 2.0, enabling commercial use, modification, and distribution with required notices.
Section: Governance


# License

Boss Loops is licensed under the Apache License 2.0.

## What this means

You can:

- use Boss Loops in commercial products
- modify the source code
- distribute modifications
- use it privately
- use patent rights granted under Apache 2.0 for contributed code

You must:

- include the copyright notice
- include a copy of the Apache License 2.0
- include NOTICE attributions when redistributing derivative works

You cannot:

- hold contributors liable for damages under the license terms

## Full license text

See the repository `LICENSE` file for the canonical Apache License 2.0 text.

<Callout variant="info" title="Why Apache-2.0">
Apache-2.0 keeps adoption friction low while adding an explicit patent grant.
Commercial Better Data platform components are licensed separately.
</Callout>

## Trademark

"Boss Loops" is a trademark of Better Data, Inc.  
The Apache License 2.0 grants source code rights and does not grant trademark rights.


---

## Contributing
URL: https://bossloops.io
/docs/governance/contributing
Summary: How to contribute to Boss Loops - DCO sign-off, what belongs in this repo, design principles, and PR conventions.
Section: Governance


<Callout variant="tip" title="New contributors">
Look for issues tagged `good first issue`. Documentation improvements and loop definitions in `loops/` are the easiest starting points.
</Callout>

# Contributing to Boss Loops

## Before you build anything

Open an issue before significant work. This avoids duplicated implementation and ensures roadmap alignment.

## DCO sign-off

All commits must be signed off.

```bash
git commit -s -m "feat: add ..."
```

This appends the required `Signed-off-by: Your Name <email>` trailer.

## What belongs in this repo

Allowed:

- domain-neutral primitives (`packages/core`)
- reusable loop definitions (`loops/`)
- adapters and examples with cross-domain utility

Not accepted:

- SCM-specific business logic
- proprietary optimization algorithms
- Better Data tenant/billing internals

## Governance model

Repository currently documents a BDFL model:

- Better Data, Inc. controls final roadmap and release decisions
- community contributions are welcomed

## Branch and PR conventions

- open issue first for significant work
- pass CI checks before review
- breaking changes to core types require RFC issue (`[RFC]`)

## Documentation: TypeScript fences

Some MDX pages use fenced ` ```typescript` blocks for full runnable examples; others use the same fence for **partial** snippets (object shapes, type-only fragments, or multi-step fragments that are not meant to compile as a single file). Repository automation that type-checks doc examples only processes blocks that look like **module-style examples** (they contain `import` …) and **do not** start with an opt-out line. If a block is intentionally incomplete or non-compiling, put **`// @no-typecheck`** on the **first line inside the fence** so those checks skip it. That split matters: use the marker when the point is structure or pedagogy, not a copy-pastable import path. **When the intent is a real, copy-pastable example, fix the snippet to match the published API rather than adding the marker.**

## Versioning with changesets

```bash
pnpm changeset
```

Event schema breaking changes require a 6-month deprecation notice.

## Local development

```bash
pnpm install
pnpm build
pnpm test
```

Run package-specific tests:

```bash
pnpm --filter @loop-engine/core test
pnpm --filter @loop-engine/runtime test
```


---

## RFC Process
URL: https://bossloops.io
/docs/governance/rfc-process
Summary: Significant cross-cutting changes should follow the RFC process before implementation.
Section: Governance


# RFC Process

Significant changes should go through an RFC issue before implementation.

## When an RFC is required

Required (from current contributor policy):

- breaking changes to core types (`@loop-engine/core`)

Strongly recommended:

- breaking event schema changes (`@loop-engine/events`)
- DSL format changes
- governance model changes
- new top-level packages with cross-cutting impact

Not usually required:

- bug fixes
- new built-in guards or signal rules
- loop definition additions in `loops/`
- documentation changes

## Why event schema changes require extra care

<Callout variant="important" title="Downstream risk">
Event payloads are often consumed by analytics and training pipelines.  
Unexpected schema changes can corrupt downstream data silently.
</Callout>

Repository guidance currently states: breaking event schema changes require a 6-month deprecation notice.

## RFC submission flow

1. Open GitHub issue with `[RFC]` in title
2. Describe:
   - problem
   - proposal
   - alternatives considered
3. Collect maintainer/community feedback
4. Land implementation PR linked to the RFC issue

## Deprecation policy

Current documented rule in `CONTRIBUTING.md`:

- breaking event schema changes require 6-month deprecation notice

See the repository governance docs for the current maintainer model and decision process:

- [`GOVERNANCE.md`](https://github.com/loopengine/loop-engine/blob/main/GOVERNANCE.md)
- [`MAINTAINERS.md`](https://github.com/loopengine/loop-engine/blob/main/MAINTAINERS.md)


---

## Changelog
URL: https://bossloops.io
/docs/governance/changelog
Summary: Notable documentation and integration updates for Boss Loops.
Section: Governance


## Unreleased

### New

- `@loop-engine/adapter-perplexity` — Perplexity Sonar adapter (grounded retrieval, citations)
- Integration guide: [Governed Incident Response with Perplexity and PagerDuty](/docs/integrations/perplexity-pagerduty)
- IT / Governed AI use case: [Use cases](/use-cases) — Boss Loops as the compliance envelope for agentic AI

### Changed

- [Integrations index](/docs/integrations/index) — Perplexity Sonar entry; governed incident card under observability
- [Partners](/partners) — adapter grid order and copy (LLM + Sonar + PagerDuty)

For package version history, follow [GitHub Releases](https://github.com/loopengine/loop-engine/releases).


---

## Changelog
URL: https://bossloops.io
/docs/changelog
Summary: All notable changes to Boss Loops
Section: Project


{/* Synced from loop-engine/CHANGELOG.md — update both when releasing */}

All notable changes to Boss Loops will be documented here.

Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)  
Versioning: [Semantic Versioning](https://semver.org/)

## Unreleased

### Documentation
- [Runtime Platform Direction](/docs/concepts/runtime-platform-direction) — self-host operational runtime narrative, OSS vs Boss Loops Cloud, roadmap-only extensions (registry, audit store, observability collector, replay, Studio, compose) with constrained claims language

### Added
- `@loop-engine/adapter-perplexity` — Perplexity Sonar `ToolAdapter` with citations, retries, and `guardEvidence` integration
- `@loop-engine/core` — `ToolAdapter`, `AdapterInput` / `AdapterOutput`, and deep `guardEvidence()` for adapter audit redaction
- Docs: `docs/integrations-perplexity.md` (Sonar vs [Perplexity Computer skills](https://www.perplexity.ai/computer/skills))
- Release contract stub: `.rc/adapter-perplexity.json` (RC **DRAFT** until promoted **LOCKED**)

{/* Note: v0.1.4 was an internal tag not published to npm. Compare link is intentionally v0.1.4...v0.1.5. */}

## [0.1.5] — 2026-03-14

### Fixed
- Replaced `workspace:*` references with explicit version pins for npm compatibility
- Fixed stale dependency pins in published tarballs
- Clean build verified — `npm install @loop-engine/sdk` works correctly

## [0.1.3] — 2026-03-14

### Added
- `repository` field added to all published `@loop-engine/*` package manifests, including correct `directory` mapping for `packages/*` and `packages/adapters/*`

### Changed
- Version bumped from `0.1.2` to `0.1.3` across all `@loop-engine/*` packages

## [0.1.2] — 2026-03-13

### Added
- Keywords added to all 22 package.json files for npm discoverability
- README.md added to all packages
- LICENSE file added to all packages (Apache-2.0)

### Fixed
- Correct Apache-2.0 license field across all packages

## [0.1.1] — 2026-03-13

### Added
- LICENSE file included in published npm tarballs
- README.md included in published npm tarballs
- `@loop-engine/adapter-grok` — Grok (xAI) AI actor adapter
- `@loop-engine/adapter-gemini` — Google Gemini AI actor adapter
- `ActorDecisionError` with typed error codes (INVALID_SIGNAL, INVALID_CONFIDENCE, PARSE_FAILED, API_ERROR) in `@loop-engine/actors`

## [0.1.0] — 2026-03-12

### Added
- Initial public release of all 20 `@loop-engine/*` packages
- `@loop-engine/core` — branded ID types and Zod schemas
- `@loop-engine/dsl` — YAML loop definition parser and validator
- `@loop-engine/events` — typed event definitions and factories
- `@loop-engine/signals` — learning signal schema and extraction
- `@loop-engine/actors` — actor types and authorization logic
- `@loop-engine/guards` — guard evaluation pipeline and built-in guards
- `@loop-engine/runtime` — loop lifecycle and transition execution
- `@loop-engine/observability` — timeline reconstruction and replay
- `@loop-engine/registry-client` — loop registry client
- `@loop-engine/sdk` — main developer SDK (recommended entry point)
- `@loop-engine/ui-devtools` — React developer tools
- `@loop-engine/adapter-memory` — in-memory storage adapter
- `@loop-engine/adapter-postgres` — PostgreSQL storage adapter
- `@loop-engine/adapter-kafka` — Kafka event streaming adapter
- `@loop-engine/adapter-http` — generic HTTP storage adapter
- `@loop-engine/adapter-anthropic` — Anthropic Claude AI actor adapter
- `@loop-engine/adapter-openai` — OpenAI AI actor adapter
- `@loop-engine/adapter-openclaw` — OpenClaw integration adapter
- `@loop-engine/adapter-commerce-gateway` — Commerce Gateway adapter
- `@loop-engine/adapter-pagerduty` — PagerDuty incident adapter
- `@loop-engine/adapter-vercel-ai` — Vercel AI SDK adapter
- Apache-2.0 license
- Full test suite across all packages

[0.1.5]: https://github.com/loopengine/loop-engine/compare/v0.1.4...v0.1.5
[0.1.3]: https://github.com/loopengine/loop-engine/compare/v0.1.2...v0.1.3
[0.1.2]: https://github.com/loopengine/loop-engine/compare/v0.1.1...v0.1.2
[0.1.1]: https://github.com/loopengine/loop-engine/compare/v0.1.0...v0.1.1
[0.1.0]: https://github.com/loopengine/loop-engine/releases/tag/v0.1.0


---