indusagi 0.12.31 → 0.12.33

package/README.md

@@ -1,415 +1,74 @@
-# indusagi
+# Indusagi
 
-`indusagi` is a Node.js + TypeScript SDK that bundles the main building blocks needed to build AI-powered coding agents and terminal tooling in one package.
+> A terminal-first AI coding-agent framework — a unified multi-provider LLM gateway, an
+> agent runtime with tool-calling, a built-in tool set, an MCP bridge, multi-agent crews, a
+> SaaS-connector bridge, an agent-builder, and homegrown tracing. **Clean-room implementation.**
 
-It exposes:
-- an AI/model layer
-- an agent runtime with tools and session support
-- a terminal UI toolkit
-- MCP (Model Context Protocol) client/server utilities
-- observability/observe surfaces
+Indusagi is designed and written from scratch — its code reuses no third-party application source.
+See [`CREDITS.md`](./CREDITS.md) and [`NOTICE`](./NOTICE).
 
-This package is published as `indusagi` and is organized in this repo under `indusvx-screth_copy`.
-
-## Highlights
-
-- **Single package, multiple surfaces** via subpath exports
-- **Model + provider registry** for working with many LLM providers
-- **Streaming-first AI APIs** with structured assistant events
-- **Agent runtime** with tool calling, session history, and coding-focused tools
-- **Terminal UI toolkit** for building rich CLI/TUI workflows
-- **MCP support** for connecting external MCP servers and exposing tools over MCP
-- **Observability hooks** for traces, events, exporters, and runtime capture
-- **ESM + TypeScript** package targeting Node.js 20+
-
-## Installation
+## Install / build
 
 ```bash
-npm install indusagi
-```
-
-Requirements:
-- Node.js `>= 20`
-- ESM-compatible runtime
-
-## Quick start
-
-### 1) Simple AI completion
-
-```ts
-import { completeSimple, getModel } from "indusagi/ai";
-
-const model = getModel("mock", "mock-default");
-
-const message = await completeSimple(model, {
-  messages: [
-    {
-      role: "user",
-      content: "Say hello in one short sentence.",
-      timestamp: Date.now(),
-    },
-  ],
-});
-
-console.log(message.content);
-```
-
-### 2) Streaming AI output
-
-```ts
-import { getModel, streamSimple } from "indusagi/ai";
-
-const model = getModel("mock", "mock-default");
-const stream = streamSimple(model, {
-  messages: [
-    {
-      role: "user",
-      content: "Stream a short answer.",
-      timestamp: Date.now(),
-    },
-  ],
-});
-
-for await (const event of stream) {
-  console.log(event.type);
-}
-```
-
-### 3) Create an agent with a tool
-
-```ts
-import { Agent, type AgentTool } from "indusagi/agent";
-import { createAssistantMessage, createAssistantMessageEventStream, getModel } from "indusagi/ai";
-
-const model = getModel("mock", "mock-default");
-let turn = 0;
-
-const echoTool: AgentTool = {
-  name: "echo",
-  label: "echo",
-  description: "Echoes text back",
-  parameters: {
-    type: "object",
-    properties: {
-      text: { type: "string" },
-    },
-    required: ["text"],
-    additionalProperties: false,
-  },
-  execute: async (_toolCallId, args) => ({
-    content: [{ type: "text", text: String(args.text ?? "") }],
-    details: {},
-  }),
-};
-
-const agent = new Agent({
-  initialState: { model },
-  streamFn: () => {
-    const stream = createAssistantMessageEventStream();
-
-    queueMicrotask(() => {
-      if (turn === 0) {
-        const first = createAssistantMessage({
-          api: model.api,
-          provider: model.provider,
-          model: model.id,
-          stopReason: "toolUse",
-          content: [
-            { type: "toolCall", id: "echo-1", name: "echo", arguments: { text: "hello" } },
-          ],
-        });
-        stream.push({ type: "done", reason: "toolUse", message: first });
-      } else {
-        const second = createAssistantMessage({
-          api: model.api,
-          provider: model.provider,
-          model: model.id,
-          stopReason: "stop",
-          content: [{ type: "text", text: "done" }],
-        });
-        stream.push({ type: "done", reason: "stop", message: second });
-      }
-      turn += 1;
-    });
-
-    return stream;
-  },
-});
-
-agent.setTools([echoTool]);
-await agent.prompt("Run the tool and finish.");
-
-console.log(agent.state.messages);
-```
-
-### 4) Build a basic TUI view
-
-```ts
-import { Container, Text } from "indusagi/tui";
-
-const root = new Container();
-root.addChild(new Text("Hello from indusagi", 0, 0));
-
-console.log(root.render(40));
-```
-
-### 5) Initialize MCP tools
-
-```ts
-import { ToolRegistry } from "indusagi/agent";
-import { initializeMCP } from "indusagi/mcp";
-
-const registry = new ToolRegistry();
-const { pool, toolCount } = await initializeMCP(registry, process.cwd());
-
-console.log(`Connected servers: ${pool.getAllClients().length}`);
-console.log(`Registered tools: ${toolCount}`);
+npm install
+npm run typecheck     # tsc --noEmit  (the type gate)
+npm run test          # vitest        (100 tests)
+npm run build         # esbuild bundles + tsc declarations -> dist/
+npm run lineage-scan  # source-hygiene gate
 ```
 
-## Subpath exports
-
-The package is split into focused public entrypoints:
-
-- `indusagi`
-- `indusagi/ai`
-- `indusagi/agent`
-- `indusagi/tui`
-- `indusagi/mcp`
-- `indusagi/observe`
-- `indusagi/observability`
-
-## AI surface
-
-The AI layer lives under `indusagi/ai` and includes:
-
-- model registry helpers: `getModel`, `getModels`, `getProviders`, `findModels`
-- stream/complete helpers: `stream`, `streamSimple`, `complete`, `completeSimple`
-- provider registration and built-in adapter registration
-- message/content/tool-call types
-- auth helpers for supported providers
-- event stream primitives for assistant streaming
-
-### Built-in provider families
-
-The current provider/model layer includes support for providers such as:
-
-- `mock`
-- `openai`
-- `azure-openai-responses`
-- `openai-codex`
-- `anthropic`
-- `google`
-- `google-vertex`
-- `amazon-bedrock`
-- `github-copilot`
-- `xai`
-- `groq`
-- `cerebras`
-- `openrouter`
-- `vercel-ai-gateway`
-- `zai`
-- `mistral`
-- `minimax`
-- `minimax-cn`
-- `opencode`
-- `kimi`
-- `kimi-coding`
-- `sarvam`
-
-## Agent surface
-
-The agent layer lives under `indusagi/agent` and includes:
-
-- `Agent` runtime
-- agent loop and proxy helpers
-- message/state/tool types
-- session manager support
-- coding-focused built-in tools
-- tool registry utilities
+## Use the CLI
 
-### Built-in coding tools
-
-The agent actions export includes tool factories and defaults such as:
-
-- `read`
-- `bash`
-- `edit`
-- `write`
-- `grep`
-- `find`
-- `ls`
-- `process`
-- `todoread`
-- `todowrite`
-- `websearch`
-- `webfetch`
-- `composio_toolkits`
-- `composio_tools`
-- `composio_execute`
-- `composio_enable`
-- `composio_connect`
-- `composio_accounts`
-
-Useful exports include:
-- `ToolRegistry`
-- `createToolRegistry(...)`
-- `codingTools`
-- `readOnlyTools`
-- `createComposioAgentTools(...)`
-
-### Composio integration
-
-The framework now ships with a built-in Composio tool family. The recommended default path is to hydrate toolkit tools as native `AgentTool`s through `composio_enable`, which creates a Composio session and returns `session.tools()` in the framework's native tool shape while keeping Composio session-based execution for auth and routing.
-
-Control tools:
-
-- `composio_enable` is the preferred path and prepares selected toolkit tools as native `AgentTool`s
-- `composio_toolkits` checks toolkit availability and connection state before hydration
-- `composio_connect` recovers pending/expired connections or starts a fresh session authorization flow and returns the auth URL
-- `composio_accounts` inspects connected accounts for debugging or recovery
-- `composio_tools` is fallback discovery when the toolkit or exact slug is unknown
-- `composio_execute` is fallback direct execution for one-off/debug scenarios
-
-Configure the registry with Composio options:
-
-```ts
-import { createToolRegistry } from "indusagi/agent";
-
-const registry = createToolRegistry(process.cwd(), {
-  composio: {
-    apiKey: process.env.COMPOSIO_API_KEY,
-    userId: "user_123",
-  },
-});
+```bash
+node dist/cli.js --help
+node dist/cli.js -m <model> -p "explain this repo"     # one-shot (print) mode
+node dist/cli.js -m <model> --json                     # JSON line protocol (wire/RPC) mode
+node dist/cli.js -m <model>                             # interactive REPL (minimal text view)
 ```
 
-Recommended flow for a known toolkit:
-
-```ts
-const registry = createToolRegistry(process.cwd(), {
-  composio: {
-    apiKey: process.env.COMPOSIO_API_KEY,
-    userId: "user_123",
-  },
-});
+Set the provider key for your model (e.g. `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`,
+`GEMINI_API_KEY`, …). Attach MCP servers with `--mcp`.
 
-const enableTool = registry.create("composio_enable");
-await enableTool.execute("call_1", {
-  toolkits: ["github"],
-});
-```
+## Architecture (capability layers)
 
-Hydrate toolkit tools directly when you want native framework tools instead of control-tool mediation:
+| Layer | Module | Subpath | Responsibility |
+|-------|--------|---------|----------------|
+| L1 Foundation | `llmgateway` | `indusagi/llmgateway` | Multi-provider LLM gateway (adapters, SSE streaming, model catalog, credentials/PKCE) |
+| L2 Agent | `runtime` | `indusagi/runtime` | FSM agent loop, session DAG, compaction, event ledger |
+| L3 Tools | `capabilities` | `indusagi/capabilities` | Built-in tools (bash/files/search/web/todo/process) + registry → `ToolBox` |
+| L3 External | `interop` | `indusagi/interop` | MCP client/server bridge (official SDK) |
+| L3 External | `connectors-saas` | `indusagi/connectors-saas` | Composio SaaS-connector bridge |
+| L3 External | `swarm` | `indusagi/swarm` | Multi-agent crews (worktrees, mailbox, task board) |
+| L5 Product | `smithy` | `indusagi/smithy` | IndusForge agent-builder |
+| L5 Product | `shell-app` | `indusagi/shell-app` | CLI: boot pipeline, flag parsing, runners (print/wire/repl) |
+| Cross-cutting | `tracing` | `indusagi/tracing` | Homegrown span tracer (no OpenTelemetry SDK) |
 
 ```ts
-import { createComposioAgentTools } from "indusagi/agent";
+import { runtime, capabilities, gateway } from "indusagi";
 
-const composioTools = await createComposioAgentTools({
-  apiKey: process.env.COMPOSIO_API_KEY,
-  userId: "user_123",
-  toolkits: ["github"],
+const agent = runtime.createAgent({
+  model: "claude-...",
+  tools: capabilities.toolBox("coding"),
 });
+const result = await agent.submit("list the TODOs in this repo");
 ```
 
-Under the hood, `createComposioAgentTools(...)` creates a session with `composio.create(userId, ...)` and hydrates the tools from `session.tools()`. `composio_connect` uses the session authorization flow for first-time connections, so callers do not need to manually create auth configs or connected accounts before starting.
-
-The framework always passes `userId` into `composio.create(userId)` and reuses Composio sessions per user/tool selection. Direct per-call `userId` forwarding is intentionally avoided.
-
-## TUI surface
-
-The TUI layer lives under `indusagi/tui` and includes:
-
-- layout/container primitives
-- text, markdown, loader, editor, image, input, list components
-- keyboard parsing and keybinding helpers
-- fuzzy matching helpers
-- terminal abstraction and image rendering helpers
-- the `TUI` container/runtime
-
-This is useful for building interactive terminal apps, coding assistants, and custom CLI dashboards.
-
-## MCP surface
-
-The MCP layer lives under `indusagi/mcp` and includes:
-
-- `MCPClient`
-- `MCPClientPool`
-- `MCPServer`
-- MCP config loading/saving helpers
-- schema conversion helpers
-- tool registration helpers for wiring MCP tools into an agent registry
-
-Typical use cases:
-- connect to local or remote MCP servers
-- register external MCP tools as agent tools
-- expose your own tools over MCP
-
-## Observe / observability
+## Status
 
-The package exposes:
-
-- `indusagi/observe` for the observe runtime/export surface
-- `indusagi/observability` for observability module exports
-
-These surfaces are intended for tracing, exporters, events, and runtime instrumentation around agent and AI execution.
-
-## Repository layout
-
-```text
-app/                  source code
-  bot/                agent runtime and tools
-  ml/                 AI/models/providers/streaming
-  ui/                 terminal UI primitives
-  mcp/                MCP client/server/config tooling
-  observability/      observability core modules
-spec/                 tests
-ops/                  operational scripts
-dist/                 build output
-```
-
-## Development
-
-Install dependencies:
-
-```bash
-npm install
-```
-
-Build:
-
-```bash
-npm run build
-```
-
-Watch mode:
-
-```bash
-npm run dev
-```
-
-Run tests:
-
-```bash
-npm test
-```
-
-Prepare for publish:
-
-```bash
-npm run prepublishOnly
-```
+v0.12.33 — core complete (gateway · runtime · tools · MCP · shell · Composio · crew · IndusForge ·
+tracing), **type-clean and 100 tests green**. The interactive terminal UI is a minimal text view
+behind an `InteractiveView` seam; a richer UI plugs in there. See [`reports/`](./reports/) for the
+per-phase build reports and [`PROVENANCE.md`](./PROVENANCE.md) for the independent-creation log.
 
-## Notes
+## Changelog
 
-- This package is ESM-first.
-- Public APIs are intended to be consumed through subpath exports rather than internal file paths.
-- The `mock` provider is useful for tests, local experimentation, and examples.
-- For provider-specific auth and environment setup, check the auth helpers under `indusagi/ai`.
+See [`CHANGELOG.md`](./CHANGELOG.md) for the full version history.
 
 ## License
 
-See `LICENSE` and `LICENSE-THIRD-PARTY.txt`.
+MIT — see [`NOTICE`](./NOTICE) and [`CREDITS.md`](./CREDITS.md).
 
 ## Credits
 
-IndusAGI is built and maintained by **Varun Israni / IndusAGI **, with modifications and Indian-context extensions on top of [pi-mono](https://github.com/badlogic/pi-mono) by Mario Zechner (MIT License).
+Indusagi is an independent implementation, designed and written from scratch. See
+[`CREDITS.md`](./CREDITS.md) for the open standards it implements and its dependency acknowledgements.