@cogstream/types

Shared TypeScript types and Zod schemas for the CogStream platform.

This package is the single source of truth for all domain contracts — primitives, patterns, intents, episodes, user state, and agent events — used by every other package in the @cogstream/* family.

Installation

npm install @cogstream/types

No runtime dependencies beyond zod.

Contents

Primitives

Low-level building blocks derived from raw UI signals.

import { PRIMITIVE_TYPES, type PrimitiveInstance } from '@cogstream/types';

Families: movement, temporal, directional, interaction, error-correction, attention, progression, control, exit, voice.

Patterns

Sequences of primitives with behavioral meaning.

import { PATTERN_TYPES, type PatternInstance } from '@cogstream/types';

Families: friction, navigation, reading, motion, decision, progress, engagement, stability, voice.

Intents

High-confidence interpretations of what the user is trying to accomplish.

import { INTENT_TYPES, type CandidateIntent } from '@cogstream/types';

Families: orientation, decision, execution, recovery, disengagement, voice-strengthened.

Episodes

The core boundary object between sensing (client) and interpretation (server).

import type { EpisodeV2, UIContext, EpisodeMetrics } from '@cogstream/types';

EpisodeV2 is the only payload the sensing SDK ever transmits to the server — raw signals stay in the browser.

User State Model

The interpretation layer's output: a structured summary of the user's current intent, friction, and trajectory.

import type {
  UserStateModel,
  IntentHypothesis,
  FrictionState,
  ProgressState,
  TrajectoryState,
} from '@cogstream/types';

Agent & AG-UI Events

Decision inputs, intervention objects, and the AG-UI event stream that carries agent responses to the frontend.

import type {
  DecisionInput,
  DecisionOutput,
  Intervention,
  InterventionOutcome,
  AGUIEvent,
  ApplicationContextInterface,
} from '@cogstream/types';

Schemas (Zod)

Runtime-validated schemas for API boundaries.

import { validateEpisodeV2 } from '@cogstream/types/schemas';

const result = validateEpisodeV2(incoming);
if (!result.success) {
  console.error(result.error.issues);
}

Graph Seed

Manifest format for seeding the interpretation graph via POST /seed/openapi.

import type { AppGraphSeed } from '@cogstream/types';
import { AppGraphSeedSchema } from '@cogstream/types';

Architecture position

@cogstream/types (no runtime deps)
    ↑
    ├── @cogstream/sensing   — browser signal capture
    ├── @cogstream/agent     — decision + intervention logic
    └── @cogstream/copilotkit — React + CopilotKit integration

Links

• cogstream.ai
• Full specification