stoops 0.1.0 → 0.2.0

package/dist/types-CzHDzfHA.d.ts

@@ -0,0 +1,201 @@
+import { P as Participant, M as Message, a as PaginatedResult, E as EventCategory, R as RoomEvent, b as Room, C as Channel } from './index-DlxJ95ki.js';
+
+/**
+ * RoomDataSource — abstraction over room data access.
+ *
+ * Allows tool handlers and EventProcessor to work against either a local
+ * Room object or a remote HTTP API. This is the critical enabler for
+ * client-side agent runtimes that connect to remote stoop servers.
+ */
+
+/**
+ * Uniform interface for reading/writing room data.
+ *
+ * Implemented by:
+ * - `LocalRoomDataSource` — wraps a Room + Channel for in-process access
+ * - `RemoteRoomDataSource` — wraps HTTP calls to a stoop server (Phase 5)
+ */
+interface RoomDataSource {
+    readonly roomId: string;
+    listParticipants(): Participant[];
+    getMessage(id: string): Promise<Message | null>;
+    searchMessages(query: string, limit?: number, cursor?: string | null): Promise<PaginatedResult<Message>>;
+    getMessages(limit?: number, cursor?: string | null): Promise<PaginatedResult<Message>>;
+    getEvents(category?: EventCategory | null, limit?: number, cursor?: string | null): Promise<PaginatedResult<RoomEvent>>;
+    sendMessage(content: string, replyToId?: string, image?: {
+        url: string;
+        mimeType: string;
+        sizeBytes: number;
+    } | null): Promise<Message>;
+    emitEvent?(event: RoomEvent): Promise<void>;
+}
+/**
+ * LocalRoomDataSource — wraps a Room + Channel for in-process access.
+ *
+ * Used by app-path consumers (ClaudeSession, LangGraphSession) and the
+ * CLI server's EventProcessor. Transparent — all calls delegate directly
+ * to the Room and Channel.
+ */
+declare class LocalRoomDataSource implements RoomDataSource {
+    private _room;
+    private _channel;
+    constructor(_room: Room, _channel: Channel);
+    get roomId(): string;
+    /** Direct access to the underlying Room (for backward compat / internal use). */
+    get room(): Room;
+    /** Direct access to the underlying Channel (for backward compat / internal use). */
+    get channel(): Channel;
+    listParticipants(): Participant[];
+    getMessage(id: string): Promise<Message | null>;
+    searchMessages(query: string, limit?: number, cursor?: string | null): Promise<PaginatedResult<Message>>;
+    getMessages(limit?: number, cursor?: string | null): Promise<PaginatedResult<Message>>;
+    getEvents(category?: EventCategory | null, limit?: number, cursor?: string | null): Promise<PaginatedResult<RoomEvent>>;
+    sendMessage(content: string, replyToId?: string, image?: {
+        url: string;
+        mimeType: string;
+        sizeBytes: number;
+    } | null): Promise<Message>;
+    emitEvent(event: RoomEvent): Promise<void>;
+}
+
+/**
+ * Shared interfaces for stoops agent infrastructure.
+ *
+ * Two layers:
+ *
+ *   EventProcessor  ──deliver()──►  Consumer (ClaudeSession, LangGraphSession, tmux, etc.)
+ *
+ * EventProcessor owns the event loop, engagement, formatting.
+ * Consumers own LLM delivery, MCP servers, compaction, stats.
+ */
+
+/**
+ * A structured content item delivered to the consumer.
+ *
+ * Text parts carry formatted event text; image parts carry the URL of an
+ * attached image so vision-capable consumers can see it natively.
+ */
+type ContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    url: string;
+};
+/**
+ * A resolved room connection: the data source, the room's display name,
+ * and optional direct room/channel references for backward compatibility.
+ *
+ * Tool handlers and EventProcessor use `dataSource` for all data access.
+ * Direct `room`/`channel` access is kept for app-path consumers that need it.
+ */
+interface RoomConnection {
+    dataSource: RoomDataSource;
+    /** Present for local (app-path) rooms; absent for remote rooms. */
+    room?: Room;
+    /** Present for local (app-path) rooms; absent for remote rooms. */
+    channel?: Channel;
+    name: string;
+}
+/**
+ * Maps room names (and identifiers) to their live connections.
+ *
+ * Implemented by `EventProcessor`. Tool handlers and sessions receive a
+ * `RoomResolver` so they can look up rooms by the names the LLM uses.
+ */
+interface RoomResolver {
+    /** Resolve a room by display name, identifier slug, or room ID. Returns null if unknown. */
+    resolve(roomName: string): RoomConnection | null;
+    /** List all currently connected rooms with metadata. */
+    listAll(): Array<{
+        name: string;
+        roomId: string;
+        identifier?: string;
+        mode: string;
+        participantCount: number;
+        lastMessage?: string;
+    }>;
+}
+/**
+ * A single tool call or result recorded during an LLM evaluation.
+ * Used for trace logging and observability.
+ */
+interface QueryTurn {
+    type: "tool_use" | "tool_result";
+    tool: string;
+    content: unknown;
+}
+/**
+ * Stats from one complete LLM evaluation (one `session.process()` call).
+ * Reported via `LLMSessionOptions.onQueryComplete` after every evaluation.
+ */
+interface LLMQueryStats {
+    totalCostUsd: number;
+    durationMs: number;
+    durationApiMs: number;
+    numTurns: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadInputTokens: number;
+    cacheCreationInputTokens: number;
+    isError: boolean;
+    contextPct: number;
+    input: string;
+    turns: QueryTurn[];
+}
+/**
+ * LLM session interface — the consumer side of the EventProcessor split.
+ *
+ * Each instance represents one agent's persistent conversation.
+ * `process()` is the delivery method — EventProcessor calls it via the
+ * `deliver` callback passed to `run()`.
+ */
+interface ILLMSession {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    process(parts: ContentPart[]): Promise<void>;
+    setApiKey(key: string): void;
+}
+/** Agent identity fields. */
+interface AgentIdentity {
+    selfId?: string;
+    selfIdentifier?: string;
+    identity?: string;
+    apiKey?: string;
+}
+/** Callbacks that bridge the session to the EventProcessor. */
+interface ProcessorBridge {
+    isEventSeen?: (eventId: string) => boolean;
+    markEventsSeen?: (eventIds: string[]) => void;
+    assignRef?: (messageId: string) => string;
+    resolveRef?: (ref: string) => string | undefined;
+    onContextCompacted?: () => void;
+    onToolUse?: (toolName: string, status: "started" | "completed") => void;
+}
+/** Session-level callbacks and settings. */
+interface SessionCallbacks {
+    onQueryComplete?: (stats: LLMQueryStats) => void;
+    resolveParticipantIdentifier?: (id: string) => string | null;
+    autoCompactPct?: number;
+}
+/**
+ * Options for LLM session consumers.
+ *
+ * These are callbacks the session calls to integrate with the EventProcessor:
+ * event tracking, ref resolution, stats reporting, and context management.
+ * The caller assembles these by wiring EventProcessor methods.
+ */
+interface LLMSessionOptions extends AgentIdentity, ProcessorBridge, SessionCallbacks {
+}
+/** Subset of ProcessorBridge used by tool handlers and MCP server. */
+type ToolHandlerOptions = Pick<ProcessorBridge, "isEventSeen" | "markEventsSeen" | "assignRef" | "resolveRef">;
+/** Claude-specific session options. */
+interface ClaudeSessionOptions extends LLMSessionOptions {
+    pathToClaudeCodeExecutable?: string;
+}
+/** LangGraph-specific session options. */
+interface LangGraphSessionOptions extends LLMSessionOptions {
+    drainEventQueue?: () => ContentPart[][] | null;
+}
+
+export { type AgentIdentity as A, type ClaudeSessionOptions as C, type ILLMSession as I, type LangGraphSessionOptions as L, type ProcessorBridge as P, type QueryTurn as Q, type RoomResolver as R, type SessionCallbacks as S, type ToolHandlerOptions as T, type ContentPart as a, type RoomConnection as b, type RoomDataSource as c, type LLMQueryStats as d, type LLMSessionOptions as e, LocalRoomDataSource as f };

package/package.json

@@ -1,27 +1,85 @@
 {
   "name": "stoops",
-  "version": "0.1.0",
-  "description": "Real-time multi-agent chat framework. Coming soon.",
+  "version": "0.2.0",
+  "description": "A group chat for humans and Claude Code agents",
+  "keywords": [
+    "ai",
+    "agents",
+    "mcp",
+    "claude",
+    "claude-code",
+    "rooms",
+    "chat",
+    "multi-agent",
+    "llm",
+    "collaborative"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/izzat5233/stoops.git"
+  },
+  "homepage": "https://github.com/izzat5233/stoops",
+  "bugs": {
+    "url": "https://github.com/izzat5233/stoops/issues"
+  },
   "type": "module",
   "main": "./dist/index.js",
-  "files": ["dist"],
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "stoops": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist"
+  ],
   "exports": {
     ".": {
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./agent": {
+      "import": "./dist/agent/index.js",
+      "types": "./dist/agent/index.d.ts"
+    },
+    "./claude": {
+      "import": "./dist/claude/index.js",
+      "types": "./dist/claude/index.d.ts"
+    },
+    "./langgraph": {
+      "import": "./dist/langgraph/index.js",
+      "types": "./dist/langgraph/index.d.ts"
     }
   },
   "scripts": {
-    "build": "tsup"
-  },
-  "keywords": ["agents", "multi-agent", "chat", "real-time", "ai"],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/izzat5233/stoops"
+    "build": "tsup",
+    "watch": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
   },
   "author": "Izzat Alsharif <work@izzatalsharif.com>",
   "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "ink": "^6.8.0",
+    "react": "^19.2.4",
+    "uuid": "^11.0.0",
+    "zod": "^4.0.0"
+  },
+  "optionalDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.12",
+    "@langchain/anthropic": "^1.0.0",
+    "@langchain/core": "^1.0.0",
+    "@langchain/langgraph": "^1.0.0",
+    "@langchain/mcp-adapters": "^1.1.3",
+    "langchain": "^1.0.0"
+  },
   "devDependencies": {
+    "@types/node": "^25.2.3",
+    "@types/react": "^19.2.14",
+    "@types/uuid": "^10.0.0",
     "tsup": "^8.0.0",
-    "typescript": "^5.7.0"
+    "tsx": "^4.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
   }
 }