society-protocol 1.0.0

package/dist/cot-stream.d.ts

@@ -0,0 +1,220 @@
+/**
+ * Society Protocol — Collaborative Chain-of-Thought (CoT) Streaming v1.0
+ *
+ * Killer feature: Real-time distributed reasoning between agents.
+ * Each agent publishes reasoning tokens, insights, questions and answers
+ * via GossipSub, enabling "pair programming between LLMs" — agents can
+ * absorb each other's reasoning in real-time and build on it.
+ *
+ * Key concepts:
+ * - CoT Stream: A reasoning session tied to a room/chain/step
+ * - Tokens: Typed reasoning chunks (reasoning, observation, hypothesis, etc.)
+ * - Insights: Distilled discoveries that can auto-create Knowledge Cards
+ * - Questions/Answers: Inter-agent Socratic dialogue
+ * - Branches: Divergent reasoning paths explored in parallel
+ * - Merges: Synthesis of multiple reasoning branches
+ *
+ * Architecture:
+ *   Agent A ──┐                    ┌── Agent C (absorbs A+B reasoning)
+ *             ├── GossipSub topic ─┤
+ *   Agent B ──┘                    └── Agent D (branches from A's insight)
+ */
+import { EventEmitter } from 'events';
+import { type Identity } from './identity.js';
+import { type RoomManager } from './rooms.js';
+import { type KnowledgePool } from './knowledge.js';
+import type { CotStreamTokenBody, CotStreamInsightBody, CotStreamQuestionBody, CotStreamEndBody } from './swp.js';
+export interface CotStream {
+    stream_id: string;
+    room_id: string;
+    chain_id?: string;
+    step_id?: string;
+    goal: string;
+    model?: string;
+    owner_did: string;
+    parent_stream_id?: string;
+    status: 'active' | 'paused' | 'completed' | 'abandoned' | 'merged';
+    started_at: number;
+    ended_at?: number;
+    token_count: number;
+    insight_count: number;
+    question_count: number;
+    branches: string[];
+    merged_into?: string;
+}
+export interface CotInsight {
+    insight_id: string;
+    stream_id: string;
+    title: string;
+    content: string;
+    insight_type: CotStreamInsightBody['insight_type'];
+    confidence: number;
+    supporting_evidence: string[];
+    author_did: string;
+    created_at: number;
+    knowledge_card_id?: string;
+}
+export interface CotQuestion {
+    question_id: string;
+    stream_id: string;
+    question: string;
+    question_type: CotStreamQuestionBody['question_type'];
+    context: string;
+    asked_by: string;
+    target_did?: string;
+    urgency: 'low' | 'normal' | 'high';
+    asked_at: number;
+    answered: boolean;
+    answers: CotAnswer[];
+}
+export interface CotAnswer {
+    answer_id: string;
+    question_id: string;
+    stream_id: string;
+    answer: string;
+    confidence: number;
+    references: string[];
+    answered_by: string;
+    answered_at: number;
+}
+export interface CotStreamConfig {
+    /** Max tokens to buffer per stream before flushing */
+    maxBufferSize?: number;
+    /** Auto-create knowledge cards from insights */
+    autoCreateCards?: boolean;
+    /** Minimum confidence to auto-create a card */
+    autoCardMinConfidence?: number;
+    /** Max concurrent streams per room */
+    maxStreamsPerRoom?: number;
+    /** Token broadcast interval (ms) — batch tokens for efficiency */
+    batchIntervalMs?: number;
+}
+export interface ReasoningContext {
+    stream_id: string;
+    tokens: CotStreamTokenBody[];
+    insights: CotInsight[];
+    questions: CotQuestion[];
+    goal: string;
+    branches: string[];
+}
+export declare class CotStreamEngine extends EventEmitter {
+    private identity;
+    private rooms;
+    private knowledge?;
+    private streams;
+    private insights;
+    private questions;
+    private tokenBuffers;
+    private roomStreams;
+    private batchTimers;
+    private config;
+    constructor(identity: Identity, rooms: RoomManager, knowledge?: KnowledgePool, config?: CotStreamConfig);
+    /**
+     * Start a new reasoning stream — begins broadcasting thinking tokens.
+     */
+    startStream(roomId: string, goal: string, options?: {
+        chain_id?: string;
+        step_id?: string;
+        model?: string;
+        parent_stream_id?: string;
+    }): Promise<string>;
+    /**
+     * Emit a reasoning token — the core of collaborative thinking.
+     * Tokens are batched for network efficiency.
+     */
+    emitToken(streamId: string, token: string, tokenType: CotStreamTokenBody['token_type'], options?: {
+        confidence?: number;
+        domain?: string;
+        references?: string[];
+    }): Promise<void>;
+    /**
+     * Publish an insight — a distilled discovery from reasoning.
+     * Can auto-create a Knowledge Card if configured.
+     */
+    publishInsight(streamId: string, title: string, content: string, insightType: CotStreamInsightBody['insight_type'], options?: {
+        confidence?: number;
+        supporting_evidence?: string[];
+        related_streams?: string[];
+        auto_create_card?: boolean;
+    }): Promise<string>;
+    /**
+     * Ask a question to other agents in the room — Socratic dialogue.
+     */
+    askQuestion(streamId: string, question: string, questionType: CotStreamQuestionBody['question_type'], options?: {
+        context?: string;
+        target_did?: string;
+        urgency?: 'low' | 'normal' | 'high';
+    }): Promise<string>;
+    /**
+     * Answer a question from another agent.
+     */
+    answerQuestion(streamId: string, questionId: string, answer: string, options?: {
+        confidence?: number;
+        references?: string[];
+    }): Promise<void>;
+    /**
+     * Branch the reasoning — explore a divergent hypothesis in parallel.
+     */
+    branchStream(parentStreamId: string, hypothesis: string, branchReason: string): Promise<string>;
+    /**
+     * Merge multiple reasoning branches into a synthesis.
+     */
+    mergeStreams(targetStreamId: string, sourceStreamIds: string[], synthesis: string, consensusLevel: number): Promise<void>;
+    /**
+     * End a reasoning stream.
+     */
+    endStream(streamId: string, status: CotStreamEndBody['status'], summary: string): Promise<void>;
+    /**
+     * Get the full reasoning context for a stream — enables agents
+     * to "absorb" another agent's thinking and build on it.
+     */
+    getReasoningContext(streamId: string): ReasoningContext | null;
+    /**
+     * Get all active streams in a room — see what everyone is thinking.
+     */
+    getRoomStreams(roomId: string): CotStream[];
+    /**
+     * Get active streams for a specific CoC chain.
+     */
+    getChainStreams(chainId: string): CotStream[];
+    /**
+     * Get all unanswered questions targeting this agent.
+     */
+    getPendingQuestions(): CotQuestion[];
+    /**
+     * Get the reasoning tree starting from a root stream,
+     * including all branches and merges.
+     */
+    getReasoningTree(rootStreamId: string): {
+        root: CotStream;
+        branches: CotStream[];
+        insights: CotInsight[];
+        depth: number;
+    } | null;
+    private bindEvents;
+    private handleRemoteStreamStart;
+    private handleRemoteToken;
+    private handleRemoteInsight;
+    private handleRemoteQuestion;
+    private handleRemoteAnswer;
+    private handleRemoteBranch;
+    private handleRemoteMerge;
+    private handleRemoteStreamEnd;
+    private flushTokenBuffer;
+    private isRemoteToken;
+    private getDefaultSpaceId;
+    private insightTypeToKnowledgeType;
+    getStream(streamId: string): CotStream | undefined;
+    getInsight(insightId: string): CotInsight | undefined;
+    getQuestion(questionId: string): CotQuestion | undefined;
+    getActiveStreams(): CotStream[];
+    getStats(): {
+        totalStreams: number;
+        activeStreams: number;
+        totalInsights: number;
+        totalQuestions: number;
+        answeredQuestions: number;
+    };
+    destroy(): void;
+}
+//# sourceMappingURL=cot-stream.d.ts.map

package/dist/cot-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cot-stream.d.ts","sourceRoot":"","sources":["../src/cot-stream.ts"],"names":[],"mappings":"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"}