borderless-agent 0.0.1-alpha.1

package/README.md

@@ -0,0 +1,274 @@
+# borderless-agent
+
+[![npm version](https://img.shields.io/npm/v/borderless-agent.svg)](https://www.npmjs.com/package/borderless-agent)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+A portable, framework-agnostic **agentic AI toolkit** for TypeScript/Node.js. Build production-ready AI agents with custom tools, skills, system prompts, and persistent sessions — in just a few lines of code.
+
+```
+npm install borderless-agent
+```
+
+## ✨ Highlights
+
+- 🔧 **Custom Tools** — Give your agent any capability with typed tool definitions
+- 🧠 **Skills** — Hot-load domain knowledge on demand
+- 💬 **Sessions** — Persistent, resumable conversation history
+- 🌊 **Streaming** — Token-by-token SSE-compatible streaming
+- 🧩 **Framework-agnostic** — Works with Express, Next.js, Hono, standalone scripts
+- 🔒 **Approval Flow** — Gate dangerous tool calls behind user confirmation
+- 📦 **Zero config** — Works out of the box with OpenAI-compatible APIs
+
+---
+
+## Quick Start
+
+```typescript
+import { AgentBuilder } from 'borderless-agent';
+
+const agent = new AgentBuilder()
+  .setLLM({ apiKey: process.env.OPENAI_API_KEY! })
+  .setSystemPrompt('You are a concise, helpful assistant.')
+  .addTool({
+    name: 'get_weather',
+    description: 'Get the current weather for a city',
+    parameters: { city: { type: 'string', description: 'City name' } },
+    required: ['city'],
+    execute: async (args) => {
+      // Your logic here
+      return JSON.stringify({ city: args.city, temp: '22°C', sky: 'sunny' });
+    },
+  })
+  .build();
+
+const result = await agent.chat('What is the weather in Tokyo?');
+console.log(result.reply);
+// → "The weather in Tokyo is 22°C and sunny."
+```
+
+---
+
+## Core Concepts
+
+### Tools
+
+Tools let your agent take actions. Define a name, description, parameters, and an `execute` function — the agent decides when to call them.
+
+```typescript
+agent.addTool({
+  name: 'search_docs',
+  description: 'Search internal documentation',
+  parameters: {
+    query: { type: 'string', description: 'Search query' },
+    limit: { type: 'integer', description: 'Max results' },
+  },
+  required: ['query'],
+  execute: async (args) => {
+    const results = await mySearchEngine.search(args.query, args.limit ?? 5);
+    return JSON.stringify(results);
+  },
+});
+```
+
+### Skills
+
+Skills inject specialized knowledge into the agent's context when loaded via the `Skill` tool. Use them for domain-specific instructions, API docs, or workflow guides.
+
+```typescript
+builder.addSkill({
+  name: 'sql-expert',
+  description: 'Expert knowledge for writing SQL queries',
+  body: `
+    ## SQL Best Practices
+    - Always use parameterized queries
+    - Prefer JOINs over subqueries for readability
+    - Add indexes on frequently filtered columns
+    ...
+  `,
+});
+```
+
+### Sessions
+
+Sessions maintain conversation history across multiple turns and persist to disk (or cloud storage).
+
+```typescript
+// Create a new session
+const session = agent.createSession();
+await session.chat('My name is Alice and I work on Project X.');
+const r = await session.chat('What project do I work on?');
+console.log(r.reply); // → "You work on Project X."
+
+// Persist
+await session.save();
+
+// Restore later (even after restart)
+const restored = agent.restoreSession(session.id);
+```
+
+### Streaming
+
+Stream responses token-by-token — perfect for chat UIs and SSE endpoints.
+
+```typescript
+for await (const chunk of agent.stream('Explain quantum computing')) {
+  if (chunk.delta) process.stdout.write(chunk.delta);
+  if (chunk.done) console.log('\n[done]');
+}
+```
+
+---
+
+## Builder API
+
+| Method | Description |
+|--------|-------------|
+| `.setLLM({ apiKey, model?, baseUrl?, timeout? })` | Configure OpenAI-compatible LLM |
+| `.setLLMProvider(provider)` | Supply a custom `LLMProvider` implementation |
+| `.setSystemPrompt(prompt)` | Set the base system prompt |
+| `.addTool(tool)` / `.addTools(tools)` | Register custom tools |
+| `.addSkill(skill)` / `.addSkills(skills)` | Register skills |
+| `.setIncludeBuiltinTools(bool)` | Include bash, file read/write/edit, grep (`true` by default) |
+| `.setStorage({ backend, dir? })` | Configure persistence (`'file'` or `'cloud'`) |
+| `.enableMemory()` | Enable long-term episodic + semantic memory |
+| `.enableStreaming()` | Enable streaming by default |
+| `.enableContext()` | Enable token budgeting & history trimming |
+| `.setMaxToolRounds(n)` | Safety limit for tool-use loops (default: 20) |
+| `.setApprovalCallback(fn)` | Gate mutating tool calls behind user approval |
+| `.build()` | → `AgentInstance` |
+
+## Agent API
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `agent.chat(message, history?)` | `Promise<ChatResult>` | Single stateless turn |
+| `agent.stream(message, history?)` | `AsyncGenerator<StreamChunk>` | Streaming turn |
+| `agent.createSession()` | `AgentSession` | New persistent session |
+| `agent.restoreSession(id)` | `AgentSession \| null` | Restore by ID |
+| `agent.listSessions()` | `string[]` | All saved session IDs |
+| `agent.listSessionSummaries(limit?)` | `object[]` | Session metadata |
+
+---
+
+## Integration Examples
+
+### Next.js (App Router)
+
+```typescript
+// app/api/chat/route.ts
+import { AgentBuilder } from 'borderless-agent';
+
+const agent = new AgentBuilder()
+  .setLLM({ apiKey: process.env.OPENAI_API_KEY! })
+  .setSystemPrompt('You are a helpful assistant.')
+  .setIncludeBuiltinTools(false) // no bash/fs in serverless
+  .addTool({ name: 'lookup', description: '...', execute: async (args) => '...' })
+  .build();
+
+export async function POST(req: Request) {
+  const { message, sessionId } = await req.json();
+  const session = agent.restoreSession(sessionId) ?? agent.createSession();
+  const result = await session.chat(message);
+  return Response.json({ reply: result.reply, sessionId: session.id });
+}
+```
+
+### Next.js (Streaming SSE)
+
+```typescript
+export async function POST(req: Request) {
+  const { message } = await req.json();
+
+  const stream = new ReadableStream({
+    async start(controller) {
+      const encoder = new TextEncoder();
+      for await (const chunk of agent.stream(message)) {
+        if (chunk.delta) {
+          controller.enqueue(encoder.encode(`data: ${JSON.stringify({ delta: chunk.delta })}\n\n`));
+        }
+      }
+      controller.close();
+    },
+  });
+
+  return new Response(stream, {
+    headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' },
+  });
+}
+```
+
+### Express
+
+```typescript
+import express from 'express';
+import { AgentBuilder } from 'borderless-agent';
+
+const app = express();
+app.use(express.json());
+
+const agent = new AgentBuilder()
+  .setLLM({ apiKey: process.env.OPENAI_API_KEY! })
+  .build();
+
+app.post('/chat', async (req, res) => {
+  const result = await agent.chat(req.body.message);
+  res.json({ reply: result.reply });
+});
+
+app.listen(3000);
+```
+
+---
+
+## Approval Callback
+
+Gate dangerous tool calls behind user confirmation:
+
+```typescript
+const agent = new AgentBuilder()
+  .setLLM({ apiKey: '...' })
+  .setApprovalCallback(async (toolName, args) => {
+    console.log(`🔐 Tool "${toolName}" wants to run with:`, args);
+    // Return true to approve, false to deny
+    return toolName !== 'bash'; // e.g., allow everything except bash
+  })
+  .build();
+```
+
+---
+
+## Types
+
+All types are fully exported for TypeScript consumers:
+
+```typescript
+import type {
+  ToolDefinition,
+  SkillDefinition,
+  AgentConfig,
+  ChatResult,
+  StreamChunk,
+  AgentSession,
+  LLMConfig,
+  LLMProvider,
+} from 'borderless-agent';
+```
+
+---
+
+## Configuration
+
+| Environment Variable | Default | Description |
+|---------------------|---------|-------------|
+| `OPENAI_API_KEY` | — | OpenAI API key |
+| `MODEL_ID` | `gpt-4o` | Model identifier |
+| `AGENT_STREAM` | `0` | Enable streaming (`1` to enable) |
+| `AGENT_MEMORY` | `0` | Enable long-term memory |
+| `AGENT_CONTEXT` | `1` | Enable context management |
+| `AGENT_STORAGE_BACKEND` | `file` | `file` or `cloud` |
+
+---
+
+## License
+
+[MIT](./LICENSE)

package/dist/agentBuilder.d.ts

@@ -0,0 +1,51 @@
+/**
+ * agentBuilder.ts — Fluent builder for creating portable agent instances.
+ *
+ * Usage:
+ * ```ts
+ * const agent = new AgentBuilder()
+ *   .setLLM({ apiKey: 'sk-...', model: 'gpt-4o' })
+ *   .setSystemPrompt('You are a helpful assistant.')
+ *   .addTool({ name: 'greet', description: 'Say hi', execute: () => 'Hi!' })
+ *   .addSkill({ name: 'ts', description: 'TypeScript', body: '...' })
+ *   .enableMemory()
+ *   .build();
+ * ```
+ */
+import { LLMProvider } from './llmProtocol';
+import { ToolDefinition, SkillDefinition, LLMConfig, StorageConfig } from './types';
+import { AgentInstance } from './agentInstance';
+export declare class AgentBuilder {
+    private _config;
+    /** Provide an LLM config (creates an OpenAIProvider automatically). */
+    setLLM(config: LLMConfig): this;
+    /** Provide a custom LLMProvider instance directly. */
+    setLLMProvider(provider: LLMProvider): this;
+    /** Set the base system prompt the agent uses. */
+    setSystemPrompt(prompt: string): this;
+    /** Add a single user-defined tool. */
+    addTool(tool: ToolDefinition): this;
+    /** Add multiple user-defined tools at once. */
+    addTools(tools: ToolDefinition[]): this;
+    /** Whether to include built-in tools (bash, read_file, etc.). Default: true. */
+    setIncludeBuiltinTools(include: boolean): this;
+    /** Add a single skill. */
+    addSkill(skill: SkillDefinition): this;
+    /** Add multiple skills at once. */
+    addSkills(skills: SkillDefinition[]): this;
+    /** Configure storage backend. */
+    setStorage(config: StorageConfig): this;
+    /** Enable long-term memory (episodic + semantic). */
+    enableMemory(enable?: boolean): this;
+    /** Enable streaming responses by default. */
+    enableStreaming(enable?: boolean): this;
+    /** Enable context management (token budgeting, history trimming). */
+    enableContext(enable?: boolean): this;
+    /** Max tool rounds per turn (safety limit). */
+    setMaxToolRounds(max: number): this;
+    /** Set approval callback for mutating tools. */
+    setApprovalCallback(cb: (toolName: string, args: Record<string, any>) => Promise<boolean> | boolean): this;
+    /** Validate config and build the agent instance. */
+    build(): AgentInstance;
+}
+//# sourceMappingURL=agentBuilder.d.ts.map

package/dist/agentBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentBuilder.d.ts","sourceRoot":"","sources":["../src/agentBuilder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAkB,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,EACH,cAAc,EACd,eAAe,EAEf,SAAS,EACT,aAAa,EAChB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,qBAAa,YAAY;IACrB,OAAO,CAAC,OAAO,CAQb;IAIF,uEAAuE;IACvE,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI;IAK/B,sDAAsD;IACtD,cAAc,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI;IAO3C,iDAAiD;IACjD,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAOrC,sCAAsC;IACtC,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI;IAMnC,+CAA+C;IAC/C,QAAQ,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,IAAI;IAMvC,gFAAgF;IAChF,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAO9C,0BAA0B;IAC1B,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAMtC,mCAAmC;IACnC,SAAS,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,IAAI;IAQ1C,iCAAiC;IACjC,UAAU,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IAOvC,qDAAqD;IACrD,YAAY,CAAC,MAAM,GAAE,OAAc,GAAG,IAAI;IAK1C,6CAA6C;IAC7C,eAAe,CAAC,MAAM,GAAE,OAAc,GAAG,IAAI;IAK7C,qEAAqE;IACrE,aAAa,CAAC,MAAM,GAAE,OAAc,GAAG,IAAI;IAK3C,+CAA+C;IAC/C,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAKnC,gDAAgD;IAChD,mBAAmB,CACf,EAAE,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,GAChF,IAAI;IAOP,oDAAoD;IACpD,KAAK,IAAI,aAAa;CAmBzB"}

package/dist/agentBuilder.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * agentBuilder.ts — Fluent builder for creating portable agent instances.
+ *
+ * Usage:
+ * ```ts
+ * const agent = new AgentBuilder()
+ *   .setLLM({ apiKey: 'sk-...', model: 'gpt-4o' })
+ *   .setSystemPrompt('You are a helpful assistant.')
+ *   .addTool({ name: 'greet', description: 'Say hi', execute: () => 'Hi!' })
+ *   .addSkill({ name: 'ts', description: 'TypeScript', body: '...' })
+ *   .enableMemory()
+ *   .build();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentBuilder = void 0;
+const llmProtocol_1 = require("./llmProtocol");
+const agentInstance_1 = require("./agentInstance");
+class AgentBuilder {
+    _config = {
+        includeBuiltinTools: true,
+        enableMemory: false,
+        enableStreaming: false,
+        enableContext: true,
+        maxToolRounds: 20,
+        tools: [],
+        skills: [],
+    };
+    // ---- LLM ----
+    /** Provide an LLM config (creates an OpenAIProvider automatically). */
+    setLLM(config) {
+        this._config.llmConfig = config;
+        return this;
+    }
+    /** Provide a custom LLMProvider instance directly. */
+    setLLMProvider(provider) {
+        this._config.llm = provider;
+        return this;
+    }
+    // ---- System prompt ----
+    /** Set the base system prompt the agent uses. */
+    setSystemPrompt(prompt) {
+        this._config.systemPrompt = prompt;
+        return this;
+    }
+    // ---- Tools ----
+    /** Add a single user-defined tool. */
+    addTool(tool) {
+        this._config.tools = this._config.tools ?? [];
+        this._config.tools.push(tool);
+        return this;
+    }
+    /** Add multiple user-defined tools at once. */
+    addTools(tools) {
+        this._config.tools = this._config.tools ?? [];
+        this._config.tools.push(...tools);
+        return this;
+    }
+    /** Whether to include built-in tools (bash, read_file, etc.). Default: true. */
+    setIncludeBuiltinTools(include) {
+        this._config.includeBuiltinTools = include;
+        return this;
+    }
+    // ---- Skills ----
+    /** Add a single skill. */
+    addSkill(skill) {
+        this._config.skills = this._config.skills ?? [];
+        this._config.skills.push(skill);
+        return this;
+    }
+    /** Add multiple skills at once. */
+    addSkills(skills) {
+        this._config.skills = this._config.skills ?? [];
+        this._config.skills.push(...skills);
+        return this;
+    }
+    // ---- Storage ----
+    /** Configure storage backend. */
+    setStorage(config) {
+        this._config.storage = config;
+        return this;
+    }
+    // ---- Feature toggles ----
+    /** Enable long-term memory (episodic + semantic). */
+    enableMemory(enable = true) {
+        this._config.enableMemory = enable;
+        return this;
+    }
+    /** Enable streaming responses by default. */
+    enableStreaming(enable = true) {
+        this._config.enableStreaming = enable;
+        return this;
+    }
+    /** Enable context management (token budgeting, history trimming). */
+    enableContext(enable = true) {
+        this._config.enableContext = enable;
+        return this;
+    }
+    /** Max tool rounds per turn (safety limit). */
+    setMaxToolRounds(max) {
+        this._config.maxToolRounds = Math.max(1, Math.min(max, 100));
+        return this;
+    }
+    /** Set approval callback for mutating tools. */
+    setApprovalCallback(cb) {
+        this._config.approvalCallback = cb;
+        return this;
+    }
+    // ---- Build ----
+    /** Validate config and build the agent instance. */
+    build() {
+        // Resolve LLM provider
+        if (!this._config.llm) {
+            const cfg = this._config.llmConfig;
+            if (!cfg?.apiKey) {
+                throw new Error('AgentBuilder: must call .setLLM({ apiKey }) or .setLLMProvider() before .build()');
+            }
+            this._config.llm = new llmProtocol_1.OpenAIProvider({
+                apiKey: cfg.apiKey,
+                model: cfg.model ?? 'gpt-4o',
+                baseUrl: cfg.baseUrl,
+                timeout: cfg.timeout ?? 120,
+            });
+        }
+        return new agentInstance_1.AgentInstance({ ...this._config });
+    }
+}
+exports.AgentBuilder = AgentBuilder;
+//# sourceMappingURL=agentBuilder.js.map

package/dist/agentBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentBuilder.js","sourceRoot":"","sources":["../src/agentBuilder.ts"],"names":[],"mappings":"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"}

package/dist/agentInstance.d.ts

@@ -0,0 +1,45 @@
+/**
+ * agentInstance.ts — Runtime agent returned by AgentBuilder.build().
+ *
+ * Provides: chat(), stream(), createSession(), restoreSession().
+ * All internal modules are wired through dependency injection — no globals.
+ */
+import { AgentConfig, ToolDefinition, ChatResult, StreamChunk, AgentSession } from './types';
+import { LLMProvider } from './llmProtocol';
+export declare class AgentInstance {
+    private _llm;
+    private _systemPrompt;
+    private _tools;
+    private _skills;
+    private _openaiTools;
+    private _toolMap;
+    private _sessionMgr;
+    private _maxToolRounds;
+    private _memoryEnabled;
+    private _streamingEnabled;
+    private _contextEnabled;
+    private _approvalCallback?;
+    constructor(config: AgentConfig);
+    /** Send a single message (no session, stateless). */
+    chat(message: string, history?: Record<string, any>[]): Promise<ChatResult>;
+    /** Stream a single message (no session, stateless). */
+    stream(message: string, history?: Record<string, any>[]): AsyncGenerator<StreamChunk>;
+    /** Create a new session (persisted, maintains conversation history). */
+    createSession(): AgentSession;
+    /** Restore a previously saved session by ID. */
+    restoreSession(sessionId: string): AgentSession | null;
+    /** List saved session IDs. */
+    listSessions(): string[];
+    /** List saved session summaries. */
+    listSessionSummaries(limit?: number): Record<string, any>[];
+    /** Get the underlying LLM provider. */
+    get llm(): LLMProvider;
+    /** Get the list of registered tools. */
+    get tools(): ToolDefinition[];
+    private _wrapSession;
+    private _executeTool;
+    private _buildSystemForTurn;
+    private _runLoop;
+    private _runLoopStream;
+}
+//# sourceMappingURL=agentInstance.d.ts.map

package/dist/agentInstance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentInstance.d.ts","sourceRoot":"","sources":["../src/agentInstance.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EACH,WAAW,EACX,cAAc,EAEd,UAAU,EACV,WAAW,EACX,YAAY,EACf,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,WAAW,EAAyB,MAAM,eAAe,CAAC;AAyKnE,qBAAa,aAAa;IACtB,OAAO,CAAC,IAAI,CAAc;IAC1B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,OAAO,CAAoB;IACnC,OAAO,CAAC,YAAY,CAAwB;IAC5C,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,WAAW,CAAiB;IACpC,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,cAAc,CAAU;IAChC,OAAO,CAAC,iBAAiB,CAAU;IACnC,OAAO,CAAC,eAAe,CAAU;IACjC,OAAO,CAAC,iBAAiB,CAAC,CAGM;gBAEpB,MAAM,EAAE,WAAW;IAiD/B,qDAAqD;IAC/C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC;IAMjF,uDAAuD;IAChD,MAAM,CACT,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAChC,cAAc,CAAC,WAAW,CAAC;IAK9B,wEAAwE;IACxE,aAAa,IAAI,YAAY;IAK7B,gDAAgD;IAChD,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAMtD,8BAA8B;IAC9B,YAAY,IAAI,MAAM,EAAE;IAIxB,oCAAoC;IACpC,oBAAoB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE;IAI3D,uCAAuC;IACvC,IAAI,GAAG,IAAI,WAAW,CAErB;IAED,wCAAwC;IACxC,IAAI,KAAK,IAAI,cAAc,EAAE,CAE5B;IAID,OAAO,CAAC,YAAY;YAgCN,YAAY;IAqB1B,OAAO,CAAC,mBAAmB;YAeb,QAAQ;YAwGP,cAAc;CAiHhC"}