@thoughtflow/core 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 zgaduj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,247 @@
+# thoughtflow
+
+**TypeScript framework for building autonomous AI agents** — streaming, tool-calling, plugins, skills, workspace automation, and advanced orchestration.
+
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![npm](https://img.shields.io/npm/v/@thoughtflow/core)](https://www.npmjs.com/package/@thoughtflow/core)
+
+```ts
+import { Conversation, OpenAiAdapter } from "@thoughtflow/core";
+
+const agent = new Conversation({
+  llmAdapter: new OpenAiAdapter({ apiKey: process.env.OPENAI_API_KEY }),
+  model: "gpt-4o",
+  systemPrompt: "You are a helpful coding agent.",
+});
+
+const { output } = await agent.sendPrompt("List files in the project root");
+console.log(output);
+```
+
+---
+
+## Installation
+
+```bash
+npm install @thoughtflow/core
+# or
+bun add @thoughtflow/core
+```
+
+Requires **Node.js ≥ 18** or **Bun ≥ 1.2**.
+
+---
+
+## Design approach
+
+- **One package, everything included.** Install thoughtflow, get all adapters, tools, storage, skills, and orchestrators in one go. No hunting for plugin packages.
+- **TypeScript-native.** The API, types, and tool system are designed for the TS ecosystem from the ground up — not ported from another language.
+- **Composable.** Conversation, adapters, tools, skills — each piece works independently or together. Use just the event bus, or the full agent stack.
+- **LLM-agnostic.** Switch between OpenAI, Anthropic, Ollama, or vLLM by changing one line. The adapter pattern treats every provider the same.
+- **Pragmatic tooling.** 120+ built-in tools for real workflows — code analysis, refactoring, planning, testing, devops — not abstractions over abstractions.
+
+---
+
+## Quick Reference
+
+### 1. Basic agent with tools
+
+```ts
+import { Conversation, OpenAiAdapter, ReadFileTool, GrepTool } from "@thoughtflow/core";
+
+const agent = new Conversation({
+  llmAdapter: new OpenAiAdapter({ apiKey: process.env.OPENAI_API_KEY }),
+  model: "gpt-4o",
+  systemPrompt: "You are a coding assistant. Use tools to explore and modify code.",
+  tools: [
+    new ReadFileTool("/path/to/project"),
+    new GrepTool("/path/to/project"),
+  ],
+});
+
+const { output } = await agent.sendPrompt("Find all TODO comments in src/");
+```
+
+### 2. Multi-turn conversation
+
+```ts
+await agent.sendPrompt("What files are in src/tools/?");
+await agent.sendPrompt("How is the ReadFileTool implemented?");
+const history = agent.getHistory(); // full message history
+```
+
+### 3. Streaming events
+
+Thoughtflow emits RxJS events for real-time UI and logging:
+
+```ts
+agent.events.pipe(
+  filter((e) => e.type === "stream_chunk"),
+).subscribe((chunk) => {
+  process.stdout.write(chunk.contentDelta ?? "");
+});
+```
+
+Available event types: `stream_chunk`, `status_changed`, `message_pushed`, `tool_event`, `interrupt`, `interrupt_resolved`, `error`.
+
+### 4. Using different providers
+
+```ts
+import { LlmAdapterFactory } from "@thoughtflow/core";
+
+// Ollama (local)
+const ollama = LlmAdapterFactory.create({
+  provider: "ollama",
+  baseUrl: "http://localhost:11434",
+});
+
+// Anthropic
+const anthropic = LlmAdapterFactory.create({
+  provider: "anthropic",
+  apiKey: process.env.ANTHROPIC_API_KEY,
+});
+
+// OpenAI-compatible (vLLM, OpenRouter, etc.)
+const vllm = LlmAdapterFactory.create({
+  provider: "openai",
+  baseUrl: "https://api.openai.com/v1",
+  apiKey: process.env.OPENAI_API_KEY,
+});
+```
+
+| Provider | Adapter | Default baseUrl |
+|----------|---------|-----------------|
+| OpenAI-compatible | `OpenAiAdapter` | `https://api.openai.com/v1` |
+| Anthropic | `AnthropicAdapter` | — |
+| Ollama | `OllamaAdapter` | `http://localhost:11434` |
+| Mock | `MockAdapter` | — (testing) |
+
+### 5. Subagent delegation
+
+Spawn child agents with isolated context, tools, and state:
+
+```ts
+import { SubagentConversationTool } from "@thoughtflow/core";
+
+const agent = new Conversation({
+  llmAdapter: adapter,
+  model: "gpt-4o",
+  tools: [new SubagentConversationTool()],
+});
+
+await agent.sendPrompt(
+  "Research best testing frameworks, then summarize."
+);
+```
+
+### 6. Skills — reusable instructions
+
+Skills are `.md` files that inject context and constraints into the agent:
+
+```ts
+import { SkillLoader } from "@thoughtflow/core";
+
+const loader = new SkillLoader();
+await loader.load("path/to/my-skill.md");
+agent.skills = loader.skills;
+```
+
+Skills can define behavior, coding conventions, security rules, or domain knowledge.
+
+### 7. Context window management
+
+```ts
+const agent = new Conversation({
+  llmAdapter: adapter,
+  model: "gpt-4o",
+  contextWindow: {
+    maxTokens: 8000,
+    strategy: "sliding-window", // or "truncation"
+  },
+});
+```
+
+### 8. Storage / Persistence
+
+Plug in different storage backends for memory, vector search, and embeddings:
+
+```ts
+import { InMemoryAdapter, JsonFileAdapter } from "@thoughtflow/core";
+import { LanceDbVectorStore } from "@thoughtflow/core";
+
+const store = new JsonFileAdapter("./data/sessions.json");
+
+// Recalling past context
+const entries = await store.query({ limit: 5 });
+```
+
+### 9. Interrupts / Human-in-the-Loop
+
+```ts
+const result = await agent.sendPrompt("Deploy to production", {
+  interruptConfig: {
+    riskLevel: "high",     // auto-interrupt on risky actions
+    keywords: ["deploy", "delete", "rm -rf"],
+  },
+});
+
+if (result.interrupted) {
+  const decision = await agent.resolveInterrupt(result.interruptId, "approved");
+  const resumed = await agent.resume(decision);
+}
+```
+
+---
+
+## Architecture
+
+```
+src/
+├── adapters/llm/         # LLM provider adapters (OpenAI, Anthropic, Ollama, mock)
+├── contracts/            # TypeScript interfaces and types
+├── contexts/             # Context document management & routing
+├── libs/                 # Core libraries (runner, history, subagents, task flow, ...)
+├── plugins/              # Workspace, Docker, Browser, Codebase Intelligence
+├── skills/               # Skill loader + built-in .md skill definitions
+├── storage/              # Persistence adapters (memory, JSON, vector stores)
+├── tools/                # 120+ tools across 12 categories
+│   ├── workspace/        #   file, git, browser, docker, terminal, ...
+│   ├── codebase/         #   search, graph, impact, knowledge, ...
+│   ├── planning/         #   breakdown, deps, estimate, risks, ...
+│   ├── quality/          #   complexity, coupling, coverage, duplication, ...
+│   ├── refactor/         #   rename, extract, split, move, eslint-fix
+│   ├── testing/          #   gen-unit, gen-integration, fuzz, snapshot, fix
+│   ├── docs/             #   gen-readme, gen-api, gen-adr, check-links
+│   ├── neural/           #   review, debug, explain, optimize, security, ...
+│   ├── memory/           #   save, recall, context, patterns, lessons
+│   ├── database/         #   migration, diagram, index-suggest
+│   └── devops/           #   ci-diagnose, deploy-check, docker-optimize, ...
+└── quick/                # Preset configs for common setups
+```
+
+---
+
+## Examples
+
+Full working examples can be found in the [`demos/`](./demos/) directory:
+
+| Example | Description |
+|---------|-------------|
+| `agent-live-demo.ts` | Basic agent with real LLM |
+| `tool-calling-test.ts` | Tool-calling loop walkthrough |
+| `workspace-demo.ts` | File/git/terminal workspace automation |
+| `subagent-demo.ts` | Subagent delegation and orchestration |
+| `code-review-autonomous-demo.ts` | Automated code review pipeline |
+| `solve-complex-demo.ts` | Multi-step complex problem solving |
+| `autonomous-dev-demo.ts` | End-to-end autonomous development |
+| `multi-server-demo.ts` | Distributed agent architecture |
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+*Built with TypeScript. Requires Node.js ≥18 or Bun ≥1.2.*

package/dist/adapters/llm/adapter-factory.d.ts

@@ -0,0 +1,43 @@
+import { LlmAdapter } from "../../contracts";
+import { OpenAiAdapterConfig } from "./openai.adapter";
+import { AnthropicAdapterConfig } from "./anthropic.adapter";
+import { MockAdapter, MockAdapterConfig } from "./mock.adapter";
+export type LlmAdapterType = "ollama" | "openai" | "anthropic" | "mock";
+export interface OllamaAdapterFactoryConfig {
+    /** Base URL of Ollama instance, e.g. http://localhost:11434 */
+    baseUrl: string;
+}
+export type AdapterConfig = ({
+    type: "ollama";
+} & OllamaAdapterFactoryConfig) | ({
+    type: "openai";
+} & OpenAiAdapterConfig) | ({
+    type: "anthropic";
+} & AnthropicAdapterConfig) | ({
+    type: "mock";
+} & MockAdapterConfig);
+/**
+ * Factory for creating LLM adapters.
+ *
+ * All configuration is explicit — NO env variables are read.
+ *
+ * @example
+ * ```ts
+ * const ollama = LlmAdapterFactory.create({ type: 'ollama', baseUrl: 'http://localhost:11434' });
+ * const openai = LlmAdapterFactory.create({ type: 'openai', apiKey: 'sk-...', model: 'gpt-4o' });
+ * const claude = LlmAdapterFactory.create({ type: 'anthropic', apiKey: 'sk-ant-...' });
+ * const mock   = LlmAdapterFactory.create({ type: 'mock', defaultContent: 'Hello test!' });
+ * ```
+ */
+export declare class LlmAdapterFactory {
+    static create(config: AdapterConfig): LlmAdapter;
+    /** Convenience: create an Ollama adapter. */
+    static ollama(baseUrl: string): LlmAdapter;
+    /** Convenience: create an OpenAI adapter. */
+    static openai(config: OpenAiAdapterConfig): LlmAdapter;
+    /** Convenience: create an Anthropic adapter. */
+    static anthropic(config: AnthropicAdapterConfig): LlmAdapter;
+    /** Convenience: create a deterministic mock adapter for tests. */
+    static mock(config?: MockAdapterConfig): MockAdapter;
+}
+//# sourceMappingURL=adapter-factory.d.ts.map

package/dist/adapters/llm/adapter-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-factory.d.ts","sourceRoot":"","sources":["../../../src/adapters/llm/adapter-factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,EAAiB,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAoB,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEhE,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,MAAM,CAAC;AAExE,MAAM,WAAW,0BAA0B;IACzC,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,aAAa,GACrB,CAAC;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAAG,0BAA0B,CAAC,GACjD,CAAC;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAAG,mBAAmB,CAAC,GAC1C,CAAC;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GAAG,sBAAsB,CAAC,GAChD,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,iBAAiB,CAAC,CAAC;AAE3C;;;;;;;;;;;;GAYG;AACH,qBAAa,iBAAiB;IAC5B,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,UAAU;IAahD,6CAA6C;IAC7C,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU;IAI1C,6CAA6C;IAC7C,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,mBAAmB,GAAG,UAAU;IAItD,gDAAgD;IAChD,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,sBAAsB,GAAG,UAAU;IAI5D,kEAAkE;IAClE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,WAAW;CAGrD"}

package/dist/adapters/llm/adapter-factory.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LlmAdapterFactory = void 0;
+const ollama_adapter_1 = require("./ollama.adapter");
+const openai_adapter_1 = require("./openai.adapter");
+const anthropic_adapter_1 = require("./anthropic.adapter");
+const mock_adapter_1 = require("./mock.adapter");
+/**
+ * Factory for creating LLM adapters.
+ *
+ * All configuration is explicit — NO env variables are read.
+ *
+ * @example
+ * ```ts
+ * const ollama = LlmAdapterFactory.create({ type: 'ollama', baseUrl: 'http://localhost:11434' });
+ * const openai = LlmAdapterFactory.create({ type: 'openai', apiKey: 'sk-...', model: 'gpt-4o' });
+ * const claude = LlmAdapterFactory.create({ type: 'anthropic', apiKey: 'sk-ant-...' });
+ * const mock   = LlmAdapterFactory.create({ type: 'mock', defaultContent: 'Hello test!' });
+ * ```
+ */
+class LlmAdapterFactory {
+    static create(config) {
+        switch (config.type) {
+            case "ollama":
+                return new ollama_adapter_1.OllamaAdapter({ baseUrl: config.baseUrl });
+            case "openai":
+                return new openai_adapter_1.OpenAiAdapter(config);
+            case "anthropic":
+                return new anthropic_adapter_1.AnthropicAdapter(config);
+            case "mock":
+                return new mock_adapter_1.MockAdapter(config);
+        }
+    }
+    /** Convenience: create an Ollama adapter. */
+    static ollama(baseUrl) {
+        return new ollama_adapter_1.OllamaAdapter({ baseUrl });
+    }
+    /** Convenience: create an OpenAI adapter. */
+    static openai(config) {
+        return new openai_adapter_1.OpenAiAdapter(config);
+    }
+    /** Convenience: create an Anthropic adapter. */
+    static anthropic(config) {
+        return new anthropic_adapter_1.AnthropicAdapter(config);
+    }
+    /** Convenience: create a deterministic mock adapter for tests. */
+    static mock(config) {
+        return new mock_adapter_1.MockAdapter(config);
+    }
+}
+exports.LlmAdapterFactory = LlmAdapterFactory;
+//# sourceMappingURL=adapter-factory.js.map

package/dist/adapters/llm/adapter-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-factory.js","sourceRoot":"","sources":["../../../src/adapters/llm/adapter-factory.ts"],"names":[],"mappings":";;;AACA,qDAAiD;AACjD,qDAAsE;AACtE,2DAA+E;AAC/E,iDAAgE;AAehE;;;;;;;;;;;;GAYG;AACH,MAAa,iBAAiB;IAC5B,MAAM,CAAC,MAAM,CAAC,MAAqB;QACjC,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;YACpB,KAAK,QAAQ;gBACX,OAAO,IAAI,8BAAa,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;YACxD,KAAK,QAAQ;gBACX,OAAO,IAAI,8BAAa,CAAC,MAAM,CAAC,CAAC;YACnC,KAAK,WAAW;gBACd,OAAO,IAAI,oCAAgB,CAAC,MAAM,CAAC,CAAC;YACtC,KAAK,MAAM;gBACT,OAAO,IAAI,0BAAW,CAAC,MAAM,CAAC,CAAC;QACnC,CAAC;IACH,CAAC;IAED,6CAA6C;IAC7C,MAAM,CAAC,MAAM,CAAC,OAAe;QAC3B,OAAO,IAAI,8BAAa,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;IACxC,CAAC;IAED,6CAA6C;IAC7C,MAAM,CAAC,MAAM,CAAC,MAA2B;QACvC,OAAO,IAAI,8BAAa,CAAC,MAAM,CAAC,CAAC;IACnC,CAAC;IAED,gDAAgD;IAChD,MAAM,CAAC,SAAS,CAAC,MAA8B;QAC7C,OAAO,IAAI,oCAAgB,CAAC,MAAM,CAAC,CAAC;IACtC,CAAC;IAED,kEAAkE;IAClE,MAAM,CAAC,IAAI,CAAC,MAA0B;QACpC,OAAO,IAAI,0BAAW,CAAC,MAAM,CAAC,CAAC;IACjC,CAAC;CACF;AAjCD,8CAiCC"}

package/dist/adapters/llm/anthropic.adapter.d.ts

@@ -0,0 +1,28 @@
+import { LlmAdapter, LlmChatRequest, LlmChatResponse, LlmModelInfo, LlmPreflightRequest, LlmPreflightResult, LlmStreamChunk } from "../../contracts";
+import { LlmRetryConfig } from "../../libs/llm-retry";
+export interface AnthropicAdapterConfig {
+    /** Anthropic API key — required. */
+    apiKey: string;
+    /**
+     * Model to use. Examples:
+     *   - claude-3-5-sonnet-20241022 (fast + capable)
+     *   - claude-3-5-haiku-20241022 (fast + cheap)
+     *   - claude-3-7-sonnet-20250219 (extended thinking support)
+     */
+    defaultModel?: string;
+    /** Retry config for transient 429/503 errors. Defaults: maxRetries=3. */
+    retry?: LlmRetryConfig;
+}
+export declare class AnthropicAdapter implements LlmAdapter {
+    private readonly config;
+    private readonly headers;
+    private readonly defaultModel;
+    constructor(config: AnthropicAdapterConfig);
+    listModels(): Promise<LlmModelInfo[]>;
+    preflight(request: LlmPreflightRequest): Promise<LlmPreflightResult>;
+    chat(request: LlmChatRequest): Promise<LlmChatResponse>;
+    streamChat(request: LlmChatRequest, onChunk: (chunk: LlmStreamChunk) => void): Promise<LlmChatResponse>;
+    private toAnthropicMessage;
+    private buildBody;
+}
+//# sourceMappingURL=anthropic.adapter.d.ts.map

package/dist/adapters/llm/anthropic.adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic.adapter.d.ts","sourceRoot":"","sources":["../../../src/adapters/llm/anthropic.adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAEH,UAAU,EACV,cAAc,EACd,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EAEjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAqB,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEzE,MAAM,WAAW,sBAAsB;IACrC,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB;AAQD,qBAAa,gBAAiB,YAAW,UAAU;IAIrC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAHnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IACjD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAET,MAAM,EAAE,sBAAsB;IASrD,UAAU,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAiBrC,SAAS,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA0CpE,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAmDvD,UAAU,CACd,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GACvC,OAAO,CAAC,eAAe,CAAC;IAoG3B,OAAO,CAAC,kBAAkB;IAqD1B,OAAO,CAAC,SAAS;CA2ClB"}