@cogstream/agent

Framework-neutral agent logic for CogStream — evaluates whether to intervene, builds interventions with LLM-generated messages, and translates them into AG-UI events.

This package is pure transformation: no runtime state, no React, no singletons. It can be used in any Node.js or edge environment.

Installation

npm install @cogstream/agent

Quick start

import {
  buildDecisionInput,
  evaluateTriggers,
  buildIntervention,
  interventionToAGUIEvents,
  configureInterventionModel,
} from '@cogstream/agent';
import { createAnthropic } from '@ai-sdk/anthropic';

// Configure LLM once at startup (optional — falls back to static templates)
configureInterventionModel(createAnthropic()('claude-haiku-4-5-20251001'));

// Per-episode pipeline
const decisionInput = buildDecisionInput(userStateModel);
const decisionOutput = evaluateTriggers(decisionInput);

if (decisionOutput.should_intervene) {
  const intervention = await buildIntervention(decisionOutput, userStateModel);
  if (intervention) {
    const events = interventionToAGUIEvents(intervention);
    // stream events to the frontend via AG-UI / CopilotKit
  }
}

API

Decision pipeline

buildDecisionInput(userState, context?)

Constructs a DecisionInput from a UserStateModel. Optionally accepts an ApplicationContext override.

evaluateTriggers(input, hint?, appCtx?)

Evaluates whether to intervene based on the user's current state. Returns a DecisionOutput:

{
  should_intervene: boolean;
  intervention_type: 'assist' | 'confirm' | 'escalate' | 'nudge' | null;
  priority: number;
  rationale: string;
}

Trigger thresholds (from the interpretation graph's HeuristicConfig):

• Session EWMA friction ≥ 0.65
• Per-field struggle ratio ≥ 0.65
• Intent uncertainty ≥ 0.70
• Stalled trajectory for N+ episodes

buildIntervention(decisionOutput, userState)

Generates an Intervention with a contextual message. Uses the configured LLM with a 2-second timeout; falls back to a static template if the LLM is unavailable or slow.

Returns null when should_intervene is false.

interventionToAGUIEvents(intervention)

Maps an Intervention to an array of AGUIEvent objects for the AG-UI / SSE transport layer.

Confirmation flow

For interventions that require explicit user approval (requires_confirmation: true):

import {
  buildConfirmationRequest,
  applyConfirmationResponse,
} from '@cogstream/agent';

const request = buildConfirmationRequest(intervention);
// present request.prompt to the user...

const outcome = applyConfirmationResponse(intervention, {
  approved: true,
  via: 'ui',
});

if (outcome.proceed) {
  const events = interventionToAGUIEvents(outcome.intervention);
}

LLM configuration

import { configureInterventionModel } from '@cogstream/agent';
import { createAnthropic } from '@ai-sdk/anthropic';

configureInterventionModel(createAnthropic()('claude-haiku-4-5-20251001'));

Accepts any Vercel AI SDK LanguageModel. If not configured, all interventions use static templates.

Design principles

• Restraint-first: should_intervene defaults to false. Interventions fire only when a trigger condition is clearly met.
• Speech always interruptible: all generated SpeechPayload objects have interruptible: true.
• Framework-neutral: no React, no CopilotKit, no HTTP. Plug into any server or edge function.

Links

• cogstream.ai
• Full specification