@radaros/core 0.1.0

package/src/storage/mongodb.ts

@@ -0,0 +1,70 @@
+import { createRequire } from "node:module";
+import type { StorageDriver } from "./driver.js";
+
+const _require = createRequire(import.meta.url);
+
+export class MongoDBStorage implements StorageDriver {
+  private client: any;
+  private db: any;
+  private collection: any;
+
+  constructor(
+    private uri: string,
+    private dbName: string = "radaros",
+    private collectionName: string = "kv_store"
+  ) {
+    try {
+      const { MongoClient } = _require("mongodb");
+      this.client = new MongoClient(uri);
+    } catch {
+      throw new Error(
+        "mongodb is required for MongoDBStorage. Install it: npm install mongodb"
+      );
+    }
+  }
+
+  async initialize(): Promise<void> {
+    await this.client.connect();
+    this.db = this.client.db(this.dbName);
+    this.collection = this.db.collection(this.collectionName);
+    await this.collection.createIndex(
+      { namespace: 1, key: 1 },
+      { unique: true }
+    );
+  }
+
+  async get<T>(namespace: string, key: string): Promise<T | null> {
+    const doc = await this.collection.findOne({ namespace, key });
+    if (!doc) return null;
+    return doc.value as T;
+  }
+
+  async set<T>(namespace: string, key: string, value: T): Promise<void> {
+    await this.collection.updateOne(
+      { namespace, key },
+      { $set: { value, updatedAt: new Date() } },
+      { upsert: true }
+    );
+  }
+
+  async delete(namespace: string, key: string): Promise<void> {
+    await this.collection.deleteOne({ namespace, key });
+  }
+
+  async list<T>(
+    namespace: string,
+    prefix?: string
+  ): Promise<Array<{ key: string; value: T }>> {
+    const filter: Record<string, unknown> = { namespace };
+    if (prefix) {
+      filter.key = { $regex: `^${prefix}` };
+    }
+
+    const docs = await this.collection.find(filter).toArray();
+    return docs.map((doc: any) => ({ key: doc.key as string, value: doc.value as T }));
+  }
+
+  async close(): Promise<void> {
+    await this.client.close();
+  }
+}

package/src/storage/postgres.ts

@@ -0,0 +1,81 @@
+import { createRequire } from "node:module";
+import type { StorageDriver } from "./driver.js";
+
+const _require = createRequire(import.meta.url);
+
+export class PostgresStorage implements StorageDriver {
+  private pool: any;
+
+  constructor(connectionString: string) {
+    try {
+      const { Pool } = _require("pg");
+      this.pool = new Pool({ connectionString });
+    } catch {
+      throw new Error(
+        "pg is required for PostgresStorage. Install it: npm install pg"
+      );
+    }
+  }
+
+  async initialize(): Promise<void> {
+    await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS kv_store (
+        namespace TEXT NOT NULL,
+        key TEXT NOT NULL,
+        value JSONB NOT NULL,
+        updated_at TIMESTAMPTZ DEFAULT NOW(),
+        PRIMARY KEY (namespace, key)
+      )
+    `);
+  }
+
+  async get<T>(namespace: string, key: string): Promise<T | null> {
+    const result = await this.pool.query(
+      "SELECT value FROM kv_store WHERE namespace = $1 AND key = $2",
+      [namespace, key]
+    );
+    if (result.rows.length === 0) return null;
+    return result.rows[0].value as T;
+  }
+
+  async set<T>(namespace: string, key: string, value: T): Promise<void> {
+    await this.pool.query(
+      `INSERT INTO kv_store (namespace, key, value, updated_at)
+       VALUES ($1, $2, $3, NOW())
+       ON CONFLICT (namespace, key)
+       DO UPDATE SET value = EXCLUDED.value, updated_at = NOW()`,
+      [namespace, key, JSON.stringify(value)]
+    );
+  }
+
+  async delete(namespace: string, key: string): Promise<void> {
+    await this.pool.query(
+      "DELETE FROM kv_store WHERE namespace = $1 AND key = $2",
+      [namespace, key]
+    );
+  }
+
+  async list<T>(
+    namespace: string,
+    prefix?: string
+  ): Promise<Array<{ key: string; value: T }>> {
+    const result = prefix
+      ? await this.pool.query(
+          "SELECT key, value FROM kv_store WHERE namespace = $1 AND key LIKE $2",
+          [namespace, `${prefix}%`]
+        )
+      : await this.pool.query(
+          "SELECT key, value FROM kv_store WHERE namespace = $1",
+          [namespace]
+        );
+
+    return result.rows.map((row: { key: string; value: T }) => ({
+      key: row.key,
+      value: row.value,
+    }));
+  }
+
+  async close(): Promise<void> {
+    await this.pool.end();
+  }
+}

package/src/storage/sqlite.ts

@@ -0,0 +1,81 @@
+import { createRequire } from "node:module";
+import type { StorageDriver } from "./driver.js";
+
+const _require = createRequire(import.meta.url);
+
+export class SqliteStorage implements StorageDriver {
+  private db: any;
+
+  constructor(dbPath: string) {
+    try {
+      const Database = _require("better-sqlite3");
+      this.db = new Database(dbPath);
+      this.db.pragma("journal_mode = WAL");
+      this.db.exec(`
+        CREATE TABLE IF NOT EXISTS kv_store (
+          namespace TEXT NOT NULL,
+          key TEXT NOT NULL,
+          value TEXT NOT NULL,
+          updated_at TEXT DEFAULT (datetime('now')),
+          PRIMARY KEY (namespace, key)
+        )
+      `);
+    } catch {
+      throw new Error(
+        "better-sqlite3 is required for SqliteStorage. Install it: npm install better-sqlite3"
+      );
+    }
+  }
+
+  async get<T>(namespace: string, key: string): Promise<T | null> {
+    const row = this.db
+      .prepare("SELECT value FROM kv_store WHERE namespace = ? AND key = ?")
+      .get(namespace, key) as { value: string } | undefined;
+    if (!row) return null;
+    return JSON.parse(row.value) as T;
+  }
+
+  async set<T>(namespace: string, key: string, value: T): Promise<void> {
+    this.db
+      .prepare(
+        `INSERT INTO kv_store (namespace, key, value, updated_at)
+         VALUES (?, ?, ?, datetime('now'))
+         ON CONFLICT(namespace, key)
+         DO UPDATE SET value = excluded.value, updated_at = datetime('now')`
+      )
+      .run(namespace, key, JSON.stringify(value));
+  }
+
+  async delete(namespace: string, key: string): Promise<void> {
+    this.db
+      .prepare("DELETE FROM kv_store WHERE namespace = ? AND key = ?")
+      .run(namespace, key);
+  }
+
+  async list<T>(
+    namespace: string,
+    prefix?: string
+  ): Promise<Array<{ key: string; value: T }>> {
+    const rows = prefix
+      ? (this.db
+          .prepare(
+            "SELECT key, value FROM kv_store WHERE namespace = ? AND key LIKE ?"
+          )
+          .all(namespace, `${prefix}%`) as Array<{
+          key: string;
+          value: string;
+        }>)
+      : (this.db
+          .prepare("SELECT key, value FROM kv_store WHERE namespace = ?")
+          .all(namespace) as Array<{ key: string; value: string }>);
+
+    return rows.map((row) => ({
+      key: row.key,
+      value: JSON.parse(row.value) as T,
+    }));
+  }
+
+  async close(): Promise<void> {
+    this.db.close();
+  }
+}

package/src/team/modes.ts

@@ -0,0 +1 @@
+export { TeamMode } from "./types.js";

package/src/team/team.ts

@@ -0,0 +1,323 @@
+import { v4 as uuidv4 } from "uuid";
+import { EventBus } from "../events/event-bus.js";
+import { RunContext } from "../agent/run-context.js";
+import { getTextContent, type StreamChunk } from "../models/types.js";
+import type { RunOpts, RunOutput } from "../agent/types.js";
+import type { Agent } from "../agent/agent.js";
+import { TeamMode, type TeamConfig } from "./types.js";
+
+interface DelegationPlan {
+  memberId: string;
+  task: string;
+}
+
+export class Team {
+  readonly name: string;
+  readonly eventBus: EventBus;
+
+  private config: TeamConfig;
+
+  constructor(config: TeamConfig) {
+    this.config = config;
+    this.name = config.name;
+    this.eventBus = config.eventBus ?? new EventBus();
+  }
+
+  async run(input: string, opts?: RunOpts): Promise<RunOutput> {
+    const ctx = new RunContext({
+      sessionId: opts?.sessionId ?? uuidv4(),
+      userId: opts?.userId,
+      metadata: opts?.metadata ?? {},
+      eventBus: this.eventBus,
+      sessionState: { ...(this.config.sessionState ?? {}) },
+    });
+
+    this.eventBus.emit("run.start", {
+      runId: ctx.runId,
+      agentName: this.name,
+      input,
+    });
+
+    try {
+      let output: RunOutput;
+
+      switch (this.config.mode) {
+        case TeamMode.Route:
+          output = await this.runRouteMode(input, ctx);
+          break;
+        case TeamMode.Broadcast:
+          output = await this.runBroadcastMode(input, ctx);
+          break;
+        case TeamMode.Collaborate:
+          output = await this.runCollaborateMode(input, ctx);
+          break;
+        case TeamMode.Coordinate:
+        default:
+          output = await this.runCoordinateMode(input, ctx);
+          break;
+      }
+
+      this.eventBus.emit("run.complete", { runId: ctx.runId, output });
+      return output;
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      this.eventBus.emit("run.error", { runId: ctx.runId, error: err });
+      throw err;
+    }
+  }
+
+  async *stream(
+    input: string,
+    opts?: RunOpts
+  ): AsyncGenerator<StreamChunk> {
+    const result = await this.run(input, opts);
+    yield { type: "text", text: result.text };
+    yield { type: "finish", finishReason: "stop", usage: result.usage };
+  }
+
+  private async runCoordinateMode(
+    input: string,
+    ctx: RunContext
+  ): Promise<RunOutput> {
+    const memberDescriptions = this.buildMemberDescriptions();
+    const planPrompt = this.buildCoordinatorPrompt(
+      input,
+      memberDescriptions,
+      "coordinate"
+    );
+
+    const planResponse = await this.config.model.generate([
+      { role: "system", content: planPrompt },
+      { role: "user", content: input },
+    ]);
+
+    const delegations = this.parseDelegationPlan(
+      getTextContent(planResponse.message.content)
+    );
+
+    const memberOutputs: Array<{ memberId: string; output: RunOutput }> = [];
+
+    for (const delegation of delegations) {
+      const member = this.findMember(delegation.memberId);
+      if (!member) continue;
+
+      this.eventBus.emit("team.delegate", {
+        runId: ctx.runId,
+        memberId: delegation.memberId,
+        task: delegation.task,
+      });
+
+      const output = await member.run(delegation.task, {
+        sessionId: ctx.sessionId,
+      });
+      memberOutputs.push({ memberId: delegation.memberId, output });
+    }
+
+    const synthesisPrompt = this.buildSynthesisPrompt(
+      input,
+      memberOutputs
+    );
+    const synthesisResponse = await this.config.model.generate([
+      { role: "user", content: synthesisPrompt },
+    ]);
+
+    return {
+      text: getTextContent(synthesisResponse.message.content),
+      toolCalls: memberOutputs.flatMap((o) => o.output.toolCalls),
+      usage: synthesisResponse.usage,
+    };
+  }
+
+  private async runRouteMode(
+    input: string,
+    ctx: RunContext
+  ): Promise<RunOutput> {
+    const memberDescriptions = this.buildMemberDescriptions();
+    const routePrompt = this.buildCoordinatorPrompt(
+      input,
+      memberDescriptions,
+      "route"
+    );
+
+    const routeResponse = await this.config.model.generate([
+      { role: "system", content: routePrompt },
+      { role: "user", content: input },
+    ]);
+
+    const selectedName = getTextContent(routeResponse.message.content).trim();
+    const member = this.findMember(selectedName);
+
+    if (!member) {
+      return {
+        text: `Could not route to member "${selectedName}". Available: ${this.config.members.map((m) => m.name).join(", ")}`,
+        toolCalls: [],
+        usage: routeResponse.usage,
+      };
+    }
+
+    this.eventBus.emit("team.delegate", {
+      runId: ctx.runId,
+      memberId: member.name,
+      task: input,
+    });
+
+    return member.run(input, { sessionId: ctx.sessionId });
+  }
+
+  private async runBroadcastMode(
+    input: string,
+    ctx: RunContext
+  ): Promise<RunOutput> {
+    for (const member of this.config.members) {
+      this.eventBus.emit("team.delegate", {
+        runId: ctx.runId,
+        memberId: member.name,
+        task: input,
+      });
+    }
+
+    const outputs = await Promise.all(
+      this.config.members.map((member) =>
+        member.run(input, { sessionId: ctx.sessionId })
+      )
+    );
+
+    const memberOutputs = this.config.members.map((member, i) => ({
+      memberId: member.name,
+      output: outputs[i],
+    }));
+
+    const synthesisPrompt = this.buildSynthesisPrompt(input, memberOutputs);
+    const synthesisResponse = await this.config.model.generate([
+      { role: "user", content: synthesisPrompt },
+    ]);
+
+    return {
+      text: getTextContent(synthesisResponse.message.content),
+      toolCalls: outputs.flatMap((o) => o.toolCalls),
+      usage: synthesisResponse.usage,
+    };
+  }
+
+  private async runCollaborateMode(
+    input: string,
+    ctx: RunContext
+  ): Promise<RunOutput> {
+    const maxRounds = this.config.maxRounds ?? 3;
+    let currentInput = input;
+    let finalOutput: RunOutput | null = null;
+
+    for (let round = 0; round < maxRounds; round++) {
+      for (const member of this.config.members) {
+        this.eventBus.emit("team.delegate", {
+          runId: ctx.runId,
+          memberId: member.name,
+          task: currentInput,
+        });
+      }
+
+      const outputs = await Promise.all(
+        this.config.members.map((member) =>
+          member.run(currentInput, { sessionId: ctx.sessionId })
+        )
+      );
+
+      const memberOutputs = this.config.members.map((member, i) => ({
+        memberId: member.name,
+        output: outputs[i],
+      }));
+
+      const consensusPrompt = `Given the following responses to "${input}", determine if there is consensus. If yes, synthesize a final answer. If not, provide a follow-up question.\n\n${memberOutputs.map((o) => `${o.memberId}: ${o.output.text}`).join("\n\n")}\n\nRespond with either "CONSENSUS: <final answer>" or "FOLLOW_UP: <question>"`;
+
+      const consensusResponse = await this.config.model.generate([
+        { role: "user", content: consensusPrompt },
+      ]);
+
+      const responseText = getTextContent(consensusResponse.message.content);
+
+      if (responseText.startsWith("CONSENSUS:")) {
+        finalOutput = {
+          text: responseText.slice("CONSENSUS:".length).trim(),
+          toolCalls: outputs.flatMap((o) => o.toolCalls),
+          usage: consensusResponse.usage,
+        };
+        break;
+      }
+
+      currentInput = responseText.startsWith("FOLLOW_UP:")
+        ? responseText.slice("FOLLOW_UP:".length).trim()
+        : responseText;
+    }
+
+    if (!finalOutput) {
+      const lastSynthesis = this.buildSynthesisPrompt(input, []);
+      const response = await this.config.model.generate([
+        { role: "user", content: lastSynthesis },
+      ]);
+      finalOutput = {
+        text: getTextContent(response.message.content),
+        toolCalls: [],
+        usage: response.usage,
+      };
+    }
+
+    return finalOutput!;
+  }
+
+  private buildMemberDescriptions(): string {
+    return this.config.members
+      .map((member) => {
+        const desc =
+          typeof member.instructions === "function"
+            ? "(dynamic instructions)"
+            : (member.instructions ?? "General-purpose agent");
+        return `- ${member.name}: ${desc}`;
+      })
+      .join("\n");
+  }
+
+  private buildCoordinatorPrompt(
+    input: string,
+    memberDescriptions: string,
+    mode: "coordinate" | "route"
+  ): string {
+    if (mode === "route") {
+      return `You are a team coordinator. Based on the user's request, select the single most appropriate team member to handle it. Available members:\n${memberDescriptions}\n\nRespond with ONLY the member name, nothing else.`;
+    }
+
+    return `You are a team coordinator. Break down the user's request into subtasks and delegate to appropriate team members. Available members:\n${memberDescriptions}\n\nRespond with a JSON array of delegations: [{"memberId": "name", "task": "specific task"}]\n${this.config.instructions ? `\nAdditional instructions: ${this.config.instructions}` : ""}`;
+  }
+
+  private buildSynthesisPrompt(
+    originalInput: string,
+    memberOutputs: Array<{ memberId: string; output: RunOutput }>
+  ): string {
+    const outputsText = memberOutputs
+      .map((o) => `### ${o.memberId}\n${o.output.text}`)
+      .join("\n\n");
+
+    return `Original request: ${originalInput}\n\nTeam member responses:\n${outputsText}\n\nSynthesize these responses into a single coherent answer.`;
+  }
+
+  private parseDelegationPlan(content: string): DelegationPlan[] {
+    try {
+      const jsonMatch = content.match(/\[[\s\S]*\]/);
+      if (jsonMatch) {
+        return JSON.parse(jsonMatch[0]);
+      }
+    } catch {
+      // fall through
+    }
+
+    return this.config.members.map((m) => ({
+      memberId: m.name,
+      task: content,
+    }));
+  }
+
+  private findMember(name: string): Agent | undefined {
+    return this.config.members.find(
+      (m) => m.name.toLowerCase() === name.toLowerCase()
+    );
+  }
+}

package/src/team/types.ts

@@ -0,0 +1,26 @@
+import type { ModelProvider } from "../models/provider.js";
+import type { StorageDriver } from "../storage/driver.js";
+import type { EventBus } from "../events/event-bus.js";
+import type { Agent } from "../agent/agent.js";
+import type { RunOpts, RunOutput, StreamChunk } from "../agent/types.js";
+
+export enum TeamMode {
+  Coordinate = "coordinate",
+  Route = "route",
+  Broadcast = "broadcast",
+  Collaborate = "collaborate",
+}
+
+export interface TeamConfig {
+  name: string;
+  mode: TeamMode;
+  model: ModelProvider;
+  members: Agent[];
+  instructions?: string;
+  sessionState?: Record<string, unknown>;
+  storage?: StorageDriver;
+  maxRounds?: number;
+  eventBus?: EventBus;
+}
+
+export type { RunOpts, RunOutput, StreamChunk };

package/src/tools/define-tool.ts

@@ -0,0 +1,20 @@
+import type { z } from "zod";
+import type { RunContext } from "../agent/run-context.js";
+import type { ToolDef, ToolResult } from "./types.js";
+
+export function defineTool<T extends z.ZodObject<any>>(config: {
+  name: string;
+  description: string;
+  parameters: T;
+  execute: (
+    args: z.infer<T>,
+    ctx: RunContext
+  ) => Promise<string | ToolResult>;
+}): ToolDef {
+  return {
+    name: config.name,
+    description: config.description,
+    parameters: config.parameters,
+    execute: config.execute as ToolDef["execute"],
+  };
+}