Threads 1: Define useThread package contracts

packages/thread/biome.jsonc

@@ -0,0 +1,11 @@
+{
+	"formatter": {
+		"enabled": true
+	},
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": true
+		}
+	}
+}

packages/thread/package.json

@@ -0,0 +1,58 @@
+{
+	"name": "@chatjs/thread",
+	"version": "0.0.0",
+	"description": "Headless threaded chat engine for AI SDK UI messages",
+	"license": "Apache-2.0",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/franciscomoretti/chat-js.git",
+		"directory": "packages/thread"
+	},
+	"homepage": "https://github.com/franciscomoretti/chat-js/tree/main/packages/thread",
+	"bugs": {
+		"url": "https://github.com/franciscomoretti/chat-js/issues"
+	},
+	"keywords": [
+		"chatjs",
+		"ai",
+		"ai-sdk",
+		"thread",
+		"chat"
+	],
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"bun": "./src/index.ts",
+			"development": "./src/index.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"types": "./dist/index.d.ts",
+	"files": [
+		"dist",
+		"src",
+		"README.md",
+		"ARCHITECTURE.md"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "bun -e \"import { rmSync } from 'node:fs'; rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json && bun build ./src/index.ts --outfile ./dist/index.js --target=browser --format=esm --packages external",
+		"format": "bunx @biomejs/biome@2.4.10 check --write src *.md package.json tsconfig.json tsconfig.build.json biome.jsonc",
+		"lint": "bunx @biomejs/biome@2.4.10 check src ARCHITECTURE.md package.json tsconfig.json tsconfig.build.json biome.jsonc",
+		"prepublishOnly": "bun run build",
+		"test": "bun test --pass-with-no-tests",
+		"test:unit": "bun test --pass-with-no-tests",
+		"test:types": "bun run build"
+	},
+	"peerDependencies": {
+		"ai": "^6.0.0"
+	},
+	"devDependencies": {
+		"@types/bun": "^1.3.12",
+		"ai": "^6.0.150",
+		"typescript": "6.0.2"
+	}
+}

packages/thread/src/index.ts

@@ -0,0 +1,13 @@
+export type {
+	MessageTreeNode,
+	MessageTreeSnapshot,
+	SendMessageInput,
+	ThreadChatOptions,
+	ThreadConcurrency,
+	ThreadEvent,
+	ThreadRun,
+	ThreadRunHandle,
+	ThreadStartRunOptions,
+	ThreadStateSnapshot,
+	TreeSendOptions,
+} from "./types.js";

packages/thread/src/types.ts

@@ -0,0 +1,104 @@
+import type {
+	AbstractChat,
+	ChatInit,
+	ChatRequestOptions,
+	ChatStatus,
+	UIMessage,
+} from "ai";
+
+export type ThreadRun = {
+	assistantMessageId: string;
+	error: Error | undefined;
+	follow: boolean;
+	id: string;
+	originCursorId: string | null;
+	parentMessageId: string | null;
+	status: ChatStatus;
+	userMessageId: string;
+};
+
+export type ThreadRunHandle = {
+	readonly assistantMessageId: string;
+	readonly finished: Promise<void>;
+	readonly id: string;
+	getSnapshot: () => ThreadRun | undefined;
+	stop: () => Promise<void>;
+};
+
+export type TreeSendOptions = ChatRequestOptions & {
+	tree?: {
+		follow?: boolean;
+		from?: string | null;
+	};
+};
+
+export type SendMessageInput<TMessage extends UIMessage> = Parameters<
+	AbstractChat<TMessage>["sendMessage"]
+>[0];
+
+export type ThreadStartRunOptions<TMessage extends UIMessage = UIMessage> = {
+	follow?: boolean;
+	from?: string | null;
+	message?: SendMessageInput<TMessage>;
+	request?: TreeSendOptions;
+};
+
+export type ThreadConcurrency = {
+	maxActiveRuns?: number;
+	maxActiveRunsPerMessage?: number;
+};
+
+export type ThreadEvent =
+	| { cursorId: string | null; type: "cursor-changed" }
+	| { run: ThreadRun; type: "run-started" | "run-updated" }
+	| {
+			run: ThreadRun;
+			type: "run-aborted" | "run-completed" | "run-failed";
+	  };
+
+export type MessageTreeNode<TMessage extends UIMessage = UIMessage> = {
+	message: TMessage;
+	parentId: string | null;
+};
+
+export type MessageTreeSnapshot<TMessage extends UIMessage = UIMessage> = {
+	cursorId: string | null;
+	nodes: MessageTreeNode<TMessage>[];
+	version: 1;
+};
+
+export type ThreadStateSnapshot<TMessage extends UIMessage = UIMessage> =
+	MessageTreeSnapshot<TMessage> & {
+		activeRuns: ThreadRun[];
+		childrenByParentId: Record<string, string[]>;
+		error: Error | undefined;
+		/** Free-form diagnostic description of the latest state transition. */
+		lastEvent: string;
+		messages: TMessage[];
+		messagesById: Record<string, TMessage>;
+		parentById: Record<string, string | null>;
+		rootIds: string[];
+		runs: ThreadRun[];
+		status: ChatStatus;
+		storeVersion: number;
+		treeStatus: ChatStatus;
+	};
+
+export type ThreadChatOptions<TMessage extends UIMessage = UIMessage> = Omit<
+	ChatInit<TMessage>,
+	"messages"
+> & {
+	concurrency?: ThreadConcurrency;
+	initialTree?: MessageTreeSnapshot<TMessage>;
+	messages?: TMessage[];
+	onThreadEvent?: (event: ThreadEvent) => void;
+};
+
+export type ThreadRunSpec = {
+	assistantMessageId: string;
+	follow: boolean;
+	originCursorId: string | null;
+	parentMessageId: string | null;
+	runId: string;
+	userMessageId: string;
+};

packages/thread/tsconfig.build.json

@@ -0,0 +1,11 @@
+{
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"declaration": true,
+		"emitDeclarationOnly": true,
+		"noEmit": false,
+		"outDir": "dist",
+		"rootDir": "src"
+	},
+	"include": ["src/**/*.ts"]
+}

packages/thread/tsconfig.json

@@ -0,0 +1,15 @@
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"lib": ["dom", "dom.iterable", "esnext"],
+		"module": "ESNext",
+		"moduleResolution": "Bundler",
+		"strict": true,
+		"skipLibCheck": true,
+		"noEmit": true,
+		"esModuleInterop": true,
+		"isolatedModules": true,
+		"types": ["bun"]
+	},
+	"include": ["src/**/*.ts", "test/**/*.ts"]
+}