dual-brain 0.2.30 → 0.3.0

package/dist/src/head.d.ts

@@ -0,0 +1,222 @@
+export interface TaskShape {
+    type: string;
+    scope: 'small' | 'medium' | 'large';
+    risk: 'low' | 'medium' | 'high' | 'critical';
+    reversibility: 'easy' | 'moderate' | 'hard';
+    ambiguity: 'low' | 'medium' | 'high';
+    riskSignals: string[];
+    ambiguitySignals: string[];
+}
+export interface Material {
+    touchedFiles: string[];
+    fragileAreas: Array<{
+        file: string;
+        reason: string;
+    }>;
+    existingPatterns: string[];
+    value: 'low' | 'medium' | 'high';
+    userOwnedChanges: string[];
+}
+export interface Relationship {
+    shouldAsk: boolean;
+    likelyMismatch: boolean;
+    wrongAssumption: boolean;
+}
+export interface ModeResult {
+    primary: string;
+    confidence: number;
+    scores: Record<string, number>;
+    signals: string[];
+}
+export interface SituationModel {
+    raw: string;
+    explicitAsk: string;
+    inferredGoal: string | null;
+    urgency: 'low' | 'medium' | 'high';
+    isQuestion: boolean;
+    isShort: boolean;
+    taskShape: TaskShape;
+    material: Material;
+    relationship: Relationship;
+    mode: ModeResult;
+    ambiguity: 'low' | 'medium' | 'high';
+    risk: 'low' | 'medium' | 'high' | 'critical';
+    reversibility: 'easy' | 'moderate' | 'hard';
+    scope: 'small' | 'medium' | 'large';
+    novelty: string;
+    materialValue: 'low' | 'medium' | 'high';
+    userStress: string;
+    contextVolatility: string;
+    priorFailures: number;
+}
+export interface UncertaintyEntry {
+    claim: string;
+    confidence: number;
+    basis: string;
+    wouldChangeIf: string;
+}
+export interface ConfidenceSummary {
+    level: 'sufficient' | 'partial' | 'insufficient';
+    score: number;
+    gaps: string[];
+    blockers?: Array<{
+        claim: string;
+        wouldResolve: string;
+    }>;
+    entryCount?: number;
+}
+export interface Obligation {
+    priority: 'critical' | 'high' | 'medium';
+    description: string;
+    type: string;
+    trigger: string;
+}
+export interface Noticing {
+    type: string;
+    severity: 'low' | 'medium' | 'high';
+    observation: string;
+    shouldSurface: boolean;
+}
+export interface Action {
+    type: string;
+    mode: string;
+    fitness?: number;
+}
+export interface DeliberationResult {
+    depth: string;
+    action: Action;
+    rationale: string;
+    confidence: ConfidenceSummary;
+    obligations: Obligation[];
+    surfaceNoticings: Noticing[];
+    shouldAskUser: boolean;
+    uncertainties: string[];
+}
+export interface TurnHistory {
+    count: number;
+    lastActions: string[];
+    failureStreak: number;
+    sameActionCount: number;
+    avgConfidence?: number;
+}
+export interface HeadState {
+    sessionId: string;
+    declaredGoal: string | null;
+    originalScope: number | null;
+    turns: Array<{
+        timestamp: number;
+        depth: string;
+        action: string;
+        confidence: number;
+        obligationCount: number;
+        noticingCount: number;
+    }>;
+    dispatches: Array<{
+        ts: number;
+        type: string;
+        objective: string;
+        outcome: string;
+        durationMs: number;
+    }>;
+    contextEstimate: {
+        messages: number;
+        estimatedTokens: number;
+    };
+    lastActivity: number;
+    created: number;
+}
+export interface ProcessTurnOutput {
+    situation: SituationModel;
+    depth: string;
+    uncertainties: UncertaintyEntry[];
+    obligations: Obligation[];
+    noticings: Noticing[];
+    result: DeliberationResult;
+    shouldAskUser: boolean;
+    shouldDispatch: boolean;
+    shouldClarify: boolean;
+    shouldThink: boolean;
+    action: Action;
+    rationale: string;
+}
+interface DepthSignals {
+    ambiguity?: string;
+    risk?: string;
+    reversibility?: string;
+    scope?: string;
+    priorFailures?: number;
+    novelty?: string;
+    materialValue?: string;
+    userStress?: string;
+    contextVolatility?: string;
+    taskShape?: {
+        type?: string;
+    };
+    type?: string;
+}
+interface Context {
+    files?: string[];
+    recentFiles?: string[];
+    priorFailures?: number;
+    patterns?: string[];
+    uncommittedFiles?: string[];
+    novelty?: string;
+    volatility?: string;
+    staleContext?: boolean;
+    contextAge?: string;
+    recentFailures?: unknown[];
+    hasTests?: Record<string, boolean>;
+    opportunities?: string[];
+    _priorWasProposal?: boolean;
+    _isFirstTurn?: boolean;
+    [key: string]: unknown;
+}
+export declare const HEAD_VALUES: Record<string, string>;
+/**
+ * Assess how much deliberation this situation deserves.
+ * Returns 'reflexive' | 'light' | 'full' | 'deep'
+ */
+export declare function assessDepth(signals: DepthSignals): 'reflexive' | 'light' | 'full' | 'deep';
+/**
+ * Build a situation model from user input and context.
+ */
+export declare function perceive(message: string, context?: Context): SituationModel;
+/**
+ * Detect user's conversational mode from message signals.
+ */
+export declare function detectMode(message: string, context?: Context): ModeResult;
+/**
+ * Build an uncertainty ledger from the situation model.
+ */
+export declare function assessUncertainty(situation: SituationModel, context?: Context): UncertaintyEntry[];
+/**
+ * Overall confidence from the uncertainty ledger.
+ */
+export declare function summarizeConfidence(ledger: UncertaintyEntry[]): ConfidenceSummary;
+/**
+ * Derive which care obligations are active given the current situation.
+ */
+export declare function deriveObligations(situation: SituationModel): Obligation[];
+export declare function queryRecentTurns(state: HeadState, n?: number): TurnHistory;
+/**
+ * Passive observation layer.
+ */
+export declare function notice(situation: SituationModel, state: HeadState, context?: Context): Noticing[];
+/**
+ * Full deliberation pipeline.
+ */
+export declare function deliberate(situation: SituationModel, uncertaintyLedger: UncertaintyEntry[], obligations: Obligation[], noticings: Noticing[], state: HeadState): DeliberationResult;
+/**
+ * Process a complete turn through the cognitive pipeline.
+ */
+export declare function processTurn(state: HeadState, userMessage: string, context?: Context): ProcessTurnOutput;
+export declare function loadState(): HeadState;
+export declare function freshState(): HeadState;
+export declare function saveState(state: HeadState): void;
+export declare function recordDispatchOutcome(state: HeadState, outcome: {
+    type?: string;
+    objective?: string;
+    status?: string;
+    durationMs?: number;
+}): void;
+export {};