Skip to content
OpenWaggle
Applies to @openwaggle/[email protected]

@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:

SubpathUse it for
@openwaggle/waggle-corePrimary config, prompt, preset, state, consensus, event, and turn-policy exports.
@openwaggle/waggle-core/configWaggle config types, constants, and parsing helpers.
@openwaggle/waggle-core/presetsBuilt-in presets and preset merge helpers.
@openwaggle/waggle-core/promptsPrompt construction helpers.
@openwaggle/waggle-core/stateRun state that records the current and completed turns.
@openwaggle/waggle-core/turn-policyTurn ownership and next-turn decisions.
@openwaggle/waggle-core/consensusConsensus result helpers.
@openwaggle/waggle-core/eventsRuntime-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

RequirementSupported line
Node.js22.19 and newer
RuntimeBrowser-safe or server-side JavaScript
Module formatESM and CommonJS
Waggle documentation0.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.