@openwaggle/waggle-core
Runtime-neutral Waggle policy, prompts, state, presets, consensus, and turn orchestration primitives.
@openwaggle/waggle-core contains the reusable Waggle policy layer.
Use it when you need Waggle configuration, built-in presets, prompt construction, state parsing, consensus checks, metadata helpers, or turn decisions without depending on Pi or the OpenWaggle desktop app.
Main imports
import {
BUILT_IN_WAGGLE_PRESETS,
WAGGLE_INHERIT_MODEL,
buildWaggleTurnPrompt,
decideNextWaggleTurn,
getWaggleTurn,
parseWaggleConfig,
} from '@openwaggle/waggle-core'
import type { WaggleConfig } from '@openwaggle/waggle-core'
Supported public subpaths include:
| Subpath | Use it for |
|---|---|
@openwaggle/waggle-core | Primary config, prompt, preset, state, consensus, event, and turn-policy exports. |
@openwaggle/waggle-core/config | Waggle config types, constants, and parsing helpers. |
@openwaggle/waggle-core/presets | Built-in presets and preset merge helpers. |
@openwaggle/waggle-core/prompts | Prompt construction helpers. |
@openwaggle/waggle-core/state | Run state that records the current and completed turns. |
@openwaggle/waggle-core/turn-policy | Turn ownership and next-turn decisions. |
@openwaggle/waggle-core/consensus | Consensus result helpers. |
@openwaggle/waggle-core/events | Runtime-neutral event metadata helpers. |
Configure two agents
Waggle mode currently models exactly two collaborating agents.
import { WAGGLE_INHERIT_MODEL } from '@openwaggle/waggle-core'
import type { WaggleConfig } from '@openwaggle/waggle-core'
const config = {
mode: 'sequential',
agents: [
{
label: 'Architect',
model: WAGGLE_INHERIT_MODEL,
roleDescription: 'Review architecture and identify structural tradeoffs.',
color: 'blue',
},
{
label: 'Reviewer',
model: WAGGLE_INHERIT_MODEL,
roleDescription: 'Check correctness, tests, security, and edge cases.',
color: 'amber',
},
],
stop: {
primary: 'consensus',
maxTurnsSafety: 8,
},
} satisfies WaggleConfig
Use provider-qualified model ids such as openai/gpt-5.5 when the host runtime should switch models per agent. Use WAGGLE_INHERIT_MODEL when the host runtime should keep the current model.
Validate external config
import { parseWaggleConfig } from '@openwaggle/waggle-core'
const parsed = parseWaggleConfig(JSON.parse(configJson))
if (!parsed.success) {
throw new Error(parsed.issues.join('\n'))
}
const config = parsed.value
Decide turns
import { buildWaggleTurnPrompt, decideNextWaggleTurn, getWaggleTurn } from '@openwaggle/waggle-core'
import type { WaggleConfig } from '@openwaggle/waggle-core'
export function nextPrompt(config: WaggleConfig, userPrompt: string, turnNumber: number) {
const turn = getWaggleTurn(config, turnNumber)
const prompt = buildWaggleTurnPrompt({ config, userPrompt, turnNumber })
const next = decideNextWaggleTurn(config, {
turnNumber,
consensusReached: false,
})
return {
turn,
prompt,
nextTurn: next.continue ? next.nextTurn : undefined,
}
}
decideNextWaggleTurn stops when consensus is reached, a terminal error is reported, or stop.maxTurnsSafety would be exceeded. parseWaggleConfig accepts a stop.maxTurnsSafety that is a whole number from 1 to 100.
To keep a record of the run, startWaggleRun from @openwaggle/waggle-core/state creates the run state, and completeWaggleTurn records each finished turn and applies the same stop rules.
Runtime boundary
@openwaggle/waggle-core is runtime-neutral. It should not import Pi, Electron, OpenWaggle renderer stores, app services, or Node-specific APIs. Use @openwaggle/pi-waggle when you want Pi commands, Pi renderers, Pi mode state, or Pi session integration.
Compatibility
| Requirement | Supported line |
|---|---|
| Node.js | 22.19 and newer |
| Runtime | Browser-safe or server-side JavaScript |
| Module format | ESM and CommonJS |
| Waggle documentation | 0.2 |
Reference and support
Troubleshooting
External configuration does not parse. Use parseWaggleConfig and surface every returned issue instead of coercing unknown input into WaggleConfig.
A host needs Pi commands or renderers. Keep core runtime-neutral and integrate through @openwaggle/pi-waggle or a host-specific adapter.
Turn execution does not stop. Always honor both the primary stop policy and maxTurnsSafety. The safety limit is the final guard against an endless loop.
Migrating from 0.1
Version 0.2 has the same API as 0.1, so code written for 0.1 works without changes. The new line comes from a build change. The package is now compiled with TypeScript 7.
@openwaggle/pi-waggle 0.2 depends on @openwaggle/waggle-core 0.2. If you install both, upgrade them together.