@agents-eco/framework 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agents.eco
+
+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,387 @@
+<p align="center">
+  <img src="icon.png" alt="agents.eco framework" width="128" />
+</p>
+
+# @agents-eco/framework
+
+**Open agentic framework** — skills-as-markdown, pluggable LLM providers, file-based memory.
+
+Built for [agents.eco](https://agents.eco). MIT licensed. Works with any OpenAI-compatible API.
+
+```
+npm install @agents-eco/framework
+```
+
+## Why
+
+Most agent frameworks are either too complex (LangChain) or too locked-in (proprietary APIs). This framework takes inspiration from [OpenClaw](https://github.com/openclaw/openclaw)'s architecture:
+
+- **Skills as Markdown** — extend your agent with `.md` files, not code. Hot-reloadable, human-readable, agent-authorable.
+- **Pluggable providers** — OpenAI, Venice, Groq, Ollama, agents.eco, or any OpenAI-compatible API.
+- **File-based memory** — JSONL + Markdown files you can inspect, edit, and version control.
+- **Tool calling** — register handlers, define tools in skill files, let the agent use them.
+- **Zero lock-in** — MIT license, no vendor dependencies, works offline with Ollama.
+
+## Quick Start
+
+### Programmatic
+
+```typescript
+import { Agent } from "@agents-eco/framework";
+
+const agent = new Agent({
+  name: "my-agent",
+  systemPrompt: "You are a helpful assistant.",
+  provider: {
+    name: "venice",
+    apiKey: process.env.VENICE_API_KEY!,
+    baseUrl: "https://api.venice.ai/api/v1",
+    defaultModel: "qwen3-4b",
+  },
+});
+
+const result = await agent.chat("What is agents.eco?");
+console.log(result.response);
+```
+
+### CLI
+
+```bash
+# Initialize a new agent project
+npx @agents-eco/framework init
+
+# Start interactive chat
+npx @agents-eco/framework chat
+
+# One-shot prompt
+npx @agents-eco/framework run "Explain quantum computing in 3 sentences"
+```
+
+## Providers
+
+Works with any OpenAI-compatible API out of the box:
+
+```typescript
+import {
+  veniceProvider,
+  openaiProvider,
+  groqProvider,
+  ollamaProvider,
+  agentsEcoProvider,
+  OpenAIProvider,
+} from "@agents-eco/framework";
+
+// Pre-configured providers
+const venice = veniceProvider("your-api-key");
+const openai = openaiProvider("sk-...");
+const groq = groqProvider("gsk_...");
+const ollama = ollamaProvider("llama3.2"); // local, no API key needed
+const eco = agentsEcoProvider("ak_...");
+
+// Custom provider
+const custom = new OpenAIProvider({
+  name: "my-provider",
+  apiKey: "...",
+  baseUrl: "https://my-api.com/v1",
+  defaultModel: "my-model",
+});
+```
+
+Use with an agent:
+
+```typescript
+const agent = new Agent({
+  name: "my-agent",
+  systemPrompt: "You are helpful.",
+  provider: { name: "ollama", baseUrl: "http://localhost:11434/v1", defaultModel: "llama3.2" },
+});
+
+// Or swap providers at runtime
+agent.useProvider(veniceProvider("your-key"));
+```
+
+## Skills (Markdown-Driven)
+
+Skills are `.md` files with YAML frontmatter. Drop them in a `skills/` directory and the agent loads them automatically.
+
+### Example Skill
+
+Create `skills/weather.md`:
+
+```markdown
+---
+name: weather
+description: Get current weather for a location
+tools:
+  - name: get_weather
+    description: Fetch current weather data
+    parameters:
+      type: object
+      properties:
+        location:
+          type: string
+          description: City name or coordinates
+      required:
+        - location
+---
+
+# Weather Skill
+
+When the user asks about weather, use the `get_weather` tool.
+Present the results in a friendly, conversational format.
+Include temperature, conditions, and any relevant alerts.
+```
+
+### Register the tool handler:
+
+```typescript
+const agent = new Agent({
+  name: "weather-bot",
+  systemPrompt: "You help people check the weather.",
+  provider: { ... },
+  skillsDir: "./skills",
+  toolHandlers: {
+    get_weather: async ({ location }) => {
+      const res = await fetch(`https://wttr.in/${location}?format=j1`);
+      const data = await res.json();
+      return JSON.stringify(data.current_condition[0]);
+    },
+  },
+});
+```
+
+### Skill Discovery
+
+Skills are loaded from:
+1. **`skillsDir`** — auto-discovers all `.md` files with YAML frontmatter
+2. **`skills` array** — explicit file paths or `Skill` objects
+3. **Subdirectories** — looks for `SKILL.md` inside each subdirectory
+
+```
+skills/
+├── greeting.md          # Simple skill (single file)
+├── weather.md           # Another simple skill
+├── web-search/
+│   └── SKILL.md         # Skill in a directory (can include extra files)
+└── code-exec/
+    └── SKILL.md
+```
+
+## Memory
+
+File-based memory that's human-readable and inspectable:
+
+```typescript
+const agent = new Agent({
+  name: "my-agent",
+  systemPrompt: "You remember previous conversations.",
+  provider: { ... },
+  memoryDir: "./.agent/memory",  // default
+});
+
+// Memory is automatic — conversations are stored after each chat
+await agent.chat("My name is Alice");
+await agent.chat("What's my name?"); // "Your name is Alice"
+```
+
+Memory files:
+- **`memory.jsonl`** — append-only log (one JSON per line)
+- **`context.md`** — auto-generated markdown summary
+
+### Custom Memory Store
+
+```typescript
+import { MemoryStore, MemoryEntry } from "@agents-eco/framework";
+
+class MyVectorMemory implements MemoryStore {
+  async add(entry) { /* store in your vector DB */ }
+  async search(query, limit) { /* semantic search */ }
+  async list(limit) { /* return recent entries */ }
+  async clear() { /* wipe */ }
+}
+
+const agent = new Agent({
+  ...config,
+  memory: new MyVectorMemory(),
+});
+```
+
+### Disable Memory
+
+```typescript
+const agent = new Agent({ ...config, memory: false });
+```
+
+## Tool Calling
+
+Register tool handlers that the agent can invoke:
+
+```typescript
+const agent = new Agent({
+  name: "tool-agent",
+  systemPrompt: "You can use tools to help users.",
+  provider: { ... },
+  toolHandlers: {
+    calculate: async ({ expression }) => {
+      return String(eval(expression));
+    },
+    fetch_url: async ({ url }) => {
+      const res = await fetch(url);
+      return await res.text();
+    },
+  },
+});
+
+// Or add tools after creation
+agent.tool("greet", async ({ name }) => `Hello, ${name}!`);
+```
+
+## Hooks
+
+Intercept and modify behavior at every stage:
+
+```typescript
+const agent = new Agent({
+  ...config,
+  hooks: {
+    beforeRequest: async (messages, tools) => {
+      console.log(`Sending ${messages.length} messages`);
+      return messages; // can modify
+    },
+    afterResponse: async (response) => {
+      console.log(`Got response: ${response.content.slice(0, 50)}...`);
+      return response; // can modify
+    },
+    beforeToolCall: async (name, args) => {
+      console.log(`Calling tool: ${name}`, args);
+      return args; // can modify
+    },
+    afterToolCall: async (name, result) => {
+      console.log(`Tool result: ${result.content.slice(0, 50)}...`);
+      return result; // can modify
+    },
+    onError: (error) => {
+      console.error("Agent error:", error);
+    },
+  },
+});
+```
+
+## Configuration (agent.yaml)
+
+The CLI uses `agent.yaml` for configuration:
+
+```yaml
+name: my-agent
+systemPrompt: |
+  You are a helpful AI assistant.
+
+provider:
+  name: venice
+  apiKey: ${VENICE_API_KEY}
+  baseUrl: https://api.venice.ai/api/v1
+  defaultModel: qwen3-4b
+
+skillsDir: ./skills
+memoryDir: ./.agent/memory
+temperature: 0.7
+maxTokens: 4096
+```
+
+Environment variables are resolved with `${VAR_NAME}` syntax.
+
+## Integration with agents.eco SDK
+
+Use alongside the [agents-eco-sdk](https://www.npmjs.com/package/agents-eco-sdk) for billing, wallet management, and the full agents.eco platform:
+
+```typescript
+import { Agent, agentsEcoProvider } from "@agents-eco/framework";
+import { AgentsEco } from "agents-eco-sdk";
+
+// Use agents.eco as the LLM provider (pay-per-token with USDC)
+const agent = new Agent({
+  name: "eco-agent",
+  systemPrompt: "You are powered by agents.eco.",
+  provider: {
+    name: "agents.eco",
+    apiKey: process.env.AGENTS_ECO_API_KEY!,
+    baseUrl: "https://agents-eco-dfc6baa9f955.herokuapp.com/v1",
+    defaultModel: "qwen3-4b",
+  },
+  skillsDir: "./skills",
+});
+
+const result = await agent.chat("Hello!");
+console.log(result.response);
+console.log(`Tokens used: ${result.usage.totalTokens}`);
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│                   Agent                      │
+│                                              │
+│  ┌──────────┐  ┌──────────┐  ┌───────────┐ │
+│  │  Skills   │  │  Memory  │  │   Hooks   │ │
+│  │ (SKILL.md)│  │ (JSONL)  │  │           │ │
+│  └─────┬─────┘  └─────┬────┘  └─────┬─────┘ │
+│        │              │              │       │
+│  ┌─────▼──────────────▼──────────────▼─────┐ │
+│  │           Message Builder               │ │
+│  │  system prompt + skills + memory + user  │ │
+│  └─────────────────┬───────────────────────┘ │
+│                    │                         │
+│  ┌─────────────────▼───────────────────────┐ │
+│  │         Provider (OpenAI-compat)        │ │
+│  │  Venice │ OpenAI │ Groq │ Ollama │ ...  │ │
+│  └─────────────────┬───────────────────────┘ │
+│                    │                         │
+│  ┌─────────────────▼───────────────────────┐ │
+│  │           Tool Call Loop                │ │
+│  │  LLM → tool calls → execute → repeat   │ │
+│  └─────────────────────────────────────────┘ │
+└─────────────────────────────────────────────┘
+```
+
+## Built-in Skills
+
+The package includes starter skills in the `skills/` directory:
+
+| Skill | Description |
+|-------|-------------|
+| `web-search` | Search the web for current information |
+| `code-exec` | Execute JavaScript code snippets |
+| `file-ops` | Read, write, and list files |
+
+Copy them to your project's `skills/` directory and register the corresponding tool handlers.
+
+## API Reference
+
+### `Agent`
+
+| Method | Description |
+|--------|-------------|
+| `chat(message)` | Send a message, get a response (with history + memory) |
+| `run(prompt, systemPrompt?)` | One-shot completion (no history/memory) |
+| `useProvider(provider)` | Swap the LLM provider |
+| `tool(name, handler)` | Register a tool handler |
+| `addSkill(skill)` | Add a skill at runtime |
+| `loadSkillFile(path)` | Load a skill from a file |
+| `getHistory()` | Get conversation history |
+| `clearHistory()` | Clear conversation history |
+| `getMemory()` | Get the memory store |
+
+### `RunResult`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `response` | `string` | The agent's response |
+| `messages` | `ChatMessage[]` | Full message chain |
+| `toolCalls` | `Array<{name, args, result}>` | Tool calls made |
+| `usage` | `{promptTokens, completionTokens, totalTokens, llmCalls}` | Token usage |
+| `duration` | `number` | Time in milliseconds |
+
+## License
+
+MIT — [agents.eco](https://agents.eco)

package/dist/agent.d.ts

@@ -0,0 +1,58 @@
+import type { AgentConfig, ChatMessage, Provider, RunResult, Skill, ToolHandler, MemoryStore } from "./types.js";
+/**
+ * The core agent runtime.
+ *
+ * Usage:
+ * ```ts
+ * import { Agent } from "@agents-eco/framework";
+ *
+ * const agent = new Agent({
+ *   name: "my-agent",
+ *   systemPrompt: "You are a helpful assistant.",
+ *   provider: { name: "venice", apiKey: "...", baseUrl: "https://api.venice.ai/api/v1", defaultModel: "qwen3-4b" },
+ *   skillsDir: "./skills",
+ * });
+ *
+ * const result = await agent.chat("Hello!");
+ * console.log(result.response);
+ * ```
+ */
+export declare class Agent {
+    readonly name: string;
+    private provider;
+    private model;
+    private systemPrompt;
+    private skills;
+    private toolHandlers;
+    private memory;
+    private history;
+    private config;
+    private maxReasoningSteps;
+    constructor(config: AgentConfig);
+    /** Use a custom provider instance */
+    useProvider(provider: Provider): this;
+    /** Register a tool handler */
+    tool(name: string, handler: ToolHandler): this;
+    /** Add a skill at runtime */
+    addSkill(skill: Skill): this;
+    /** Load a skill from a file path */
+    loadSkillFile(path: string): this;
+    /** Get conversation history */
+    getHistory(): ChatMessage[];
+    /** Clear conversation history */
+    clearHistory(): void;
+    /** Get the memory store */
+    getMemory(): MemoryStore | null;
+    /**
+     * Send a message to the agent and get a response.
+     * Handles tool calling loops, memory retrieval, and skill injection.
+     */
+    chat(message: string): Promise<RunResult>;
+    /**
+     * Run a one-shot completion (no history, no memory).
+     */
+    run(prompt: string, systemPrompt?: string): Promise<string>;
+    private loadSkills;
+    private getAllTools;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EAGX,QAAQ,EACR,SAAS,EACT,KAAK,EAEL,WAAW,EAEX,WAAW,EACZ,MAAM,YAAY,CAAC;AAOpB;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,KAAK;IAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,YAAY,CAAuC;IAC3D,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,iBAAiB,CAAS;gBAEtB,MAAM,EAAE,WAAW;IA8B/B,qCAAqC;IACrC,WAAW,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAKrC,8BAA8B;IAC9B,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI;IAK9C,6BAA6B;IAC7B,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAK5B,oCAAoC;IACpC,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKjC,+BAA+B;IAC/B,UAAU,IAAI,WAAW,EAAE;IAI3B,iCAAiC;IACjC,YAAY,IAAI,IAAI;IAIpB,2BAA2B;IAC3B,SAAS,IAAI,WAAW,GAAG,IAAI;IAI/B;;;OAGG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAqK/C;;OAEG;IACG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAkBjE,OAAO,CAAC,UAAU;IAuBlB,OAAO,CAAC,WAAW;CAwBpB"}