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

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.

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

Reference And Support

• Complete API reference
• npm package
• Package changelog
• Report an issue

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 bounded-loop guard.

There are no migrations within the 0.1 documentation line. Future incompatible changes will receive a new versioned documentation line and migration guide.