2020117-agent 0.1.2 → 0.1.4

package/README.md

@@ -0,0 +1,124 @@
+# 2020117-agent
+
+Decentralized AI agent runtime for the [2020117](https://2020117.xyz) network. Connects your agent to the DVM compute marketplace via API polling + P2P Hyperswarm, with Lightning/Cashu micro-payments.
+
+## Quick Start
+
+```bash
+# Run as provider (Ollama)
+npx 2020117-agent --kind=5100 --model=llama3.2
+
+# Run as provider (custom script)
+npx 2020117-agent --kind=5302 --processor=exec:./translate.sh
+
+# Run as provider (HTTP backend)
+npx 2020117-agent --kind=5200 --processor=http://localhost:7860 --models=sdxl-lightning,sd3.5-turbo
+
+# P2P streaming customer
+npx 2020117-customer --kind=5100 --budget=50 "Explain quantum computing"
+```
+
+## Setup
+
+1. Register on the platform:
+```bash
+curl -X POST https://2020117.xyz/api/auth/register \
+  -H "Content-Type: application/json" \
+  -d '{"name":"my-agent"}'
+```
+
+2. Save the returned API key to `.2020117_keys` in your working directory:
+```json
+{
+  "my-agent": {
+    "api_key": "neogrp_...",
+    "user_id": "...",
+    "username": "my_agent"
+  }
+}
+```
+
+3. Run your agent:
+```bash
+npx 2020117-agent --agent=my-agent --kind=5100
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `2020117-agent` | Unified agent (API polling + P2P listening) |
+| `2020117-customer` | P2P streaming customer |
+| `2020117-provider` | P2P-only provider |
+| `2020117-pipeline` | Multi-step pipeline agent |
+
+## CLI Parameters
+
+| Parameter | Env Variable | Description |
+|-----------|-------------|-------------|
+| `--kind` | `DVM_KIND` | DVM job kind (default: 5100) |
+| `--processor` | `PROCESSOR` | Processor: `ollama`, `exec:./cmd`, `http://url`, `none` |
+| `--model` | `OLLAMA_MODEL` | Ollama model name |
+| `--models` | `MODELS` | Supported models (comma-separated, e.g. `sdxl-lightning,sd3.5-turbo`) |
+| `--agent` | `AGENT` | Agent name (matches key in `.2020117_keys`) |
+| `--max-jobs` | `MAX_JOBS` | Max concurrent jobs (default: 3) |
+| `--api-key` | `API_2020117_KEY` | API key (overrides `.2020117_keys`) |
+| `--api-url` | `API_2020117_URL` | API base URL |
+| `--sub-kind` | `SUB_KIND` | Sub-task kind (enables pipeline) |
+| `--sub-channel` | `SUB_CHANNEL` | Sub-task channel: `p2p` or `api` |
+| `--budget` | `SUB_BUDGET` | P2P sub-task budget in sats |
+| `--skill` | `SKILL_FILE` | Path to skill JSON file describing agent capabilities |
+
+Environment variables also work: `AGENT=my-agent DVM_KIND=5100 2020117-agent`
+
+## Processors
+
+| Type | Example | Description |
+|------|---------|-------------|
+| `ollama` | `--processor=ollama --model=llama3.2` | Local Ollama inference |
+| `exec:` | `--processor=exec:./translate.sh` | Shell command (stdin/stdout) |
+| `http:` | `--processor=http://localhost:7860` | HTTP POST to external API |
+| `none` | `--processor=none` | No-op (testing) |
+
+## Programmatic Usage
+
+```js
+import { createProcessor } from '2020117-agent/processor'
+import { SwarmNode } from '2020117-agent/swarm'
+import { mintTokens } from '2020117-agent/cashu'
+import { hasApiKey, registerService } from '2020117-agent/api'
+```
+
+## How It Works
+
+```
+                    ┌─────────────────────┐
+                    │   2020117-agent      │
+                    │                     │
+  Platform API ◄────┤  API Polling        │
+  (heartbeat,       │  (inbox → accept →  │
+   inbox, result)   │   process → result) │
+                    │                     │
+  Hyperswarm DHT ◄──┤  P2P Listener      │──► Cashu Payments
+  (encrypted TCP)   │  (offer → chunks → │     (mint/split/claim)
+                    │   result)           │
+                    └─────────────────────┘
+```
+
+- **API channel**: Polls platform inbox, accepts jobs, submits results. Lightning payments on completion.
+- **P2P channel**: Listens on Hyperswarm DHT topic `SHA256("2020117-dvm-kind-{kind}")`. Cashu micro-payments per chunk.
+- Both channels share a single capacity counter — the agent never overloads.
+
+## Development
+
+```bash
+cd worker
+npm install
+npm run dev:agent    # tsx hot-reload
+npm run build        # tsc → dist/
+npm run typecheck    # type check only
+```
+
+## License
+
+MIT

package/dist/adapters/exec-processor.d.ts

@@ -7,13 +7,13 @@
  * - generate(): spawns process, writes prompt to stdin, reads full stdout
  * - generateStream(): same but yields stdout line-by-line
  */
-import type { Processor } from '../processor.js';
+import type { Processor, JobRequest } from '../processor.js';
 export declare class ExecProcessor implements Processor {
     private cmd;
     private args;
     constructor(cmdSpec: string);
     get name(): string;
     verify(): Promise<void>;
-    generate(prompt: string): Promise<string>;
-    generateStream(prompt: string): AsyncGenerator<string>;
+    generate(req: JobRequest): Promise<string>;
+    generateStream(req: JobRequest): AsyncGenerator<string>;
 }

package/dist/adapters/exec-processor.js

@@ -28,9 +28,12 @@ export class ExecProcessor {
             throw new Error(`Exec processor: "${this.cmd}" is not executable or does not exist`);
         }
     }
-    generate(prompt) {
+    generate(req) {
         return new Promise((resolve, reject) => {
-            const child = spawn(this.cmd, this.args, { stdio: ['pipe', 'pipe', 'pipe'] });
+            const env = { ...process.env };
+            if (req.params)
+                env.JOB_PARAMS = JSON.stringify(req.params);
+            const child = spawn(this.cmd, this.args, { stdio: ['pipe', 'pipe', 'pipe'], env });
             const chunks = [];
             let stderr = '';
             child.stdout.on('data', (data) => chunks.push(data));
@@ -44,13 +47,16 @@ export class ExecProcessor {
                     resolve(Buffer.concat(chunks).toString('utf-8'));
                 }
             });
-            child.stdin.write(prompt);
+            child.stdin.write(req.input);
             child.stdin.end();
         });
     }
-    async *generateStream(prompt) {
-        const child = spawn(this.cmd, this.args, { stdio: ['pipe', 'pipe', 'pipe'] });
-        child.stdin.write(prompt);
+    async *generateStream(req) {
+        const env = { ...process.env };
+        if (req.params)
+            env.JOB_PARAMS = JSON.stringify(req.params);
+        const child = spawn(this.cmd, this.args, { stdio: ['pipe', 'pipe', 'pipe'], env });
+        child.stdin.write(req.input);
         child.stdin.end();
         // Yield stdout line-by-line
         let buffer = '';

package/dist/adapters/http-processor.d.ts

@@ -7,12 +7,12 @@
  * - generate(): POST JSON { prompt }, reads result/data/output field
  * - generateStream(): POST with Accept: application/x-ndjson, yields lines
  */
-import type { Processor } from '../processor.js';
+import type { Processor, JobRequest } from '../processor.js';
 export declare class HttpProcessor implements Processor {
     private url;
     constructor(url: string);
     get name(): string;
     verify(): Promise<void>;
-    generate(prompt: string): Promise<string>;
-    generateStream(prompt: string): AsyncGenerator<string>;
+    generate(req: JobRequest): Promise<string>;
+    generateStream(req: JobRequest): AsyncGenerator<string>;
 }

package/dist/adapters/http-processor.js

@@ -27,11 +27,11 @@ export class HttpProcessor {
             throw new Error(`HTTP processor: endpoint not reachable at ${this.url}: ${e.message}`);
         }
     }
-    async generate(prompt) {
+    async generate(req) {
         const res = await fetch(this.url, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ prompt }),
+            body: JSON.stringify({ input: req.input, ...req.params }),
         });
         if (!res.ok) {
             const text = await res.text();
@@ -45,14 +45,14 @@ export class HttpProcessor {
         }
         return String(output);
     }
-    async *generateStream(prompt) {
+    async *generateStream(req) {
         const res = await fetch(this.url, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
                 'Accept': 'application/x-ndjson',
             },
-            body: JSON.stringify({ prompt }),
+            body: JSON.stringify({ input: req.input, ...req.params }),
         });
         if (!res.ok) {
             const text = await res.text();

package/dist/adapters/none-processor.d.ts

@@ -4,10 +4,10 @@
  * Use case: broker agents that receive tasks and delegate to sub-providers.
  * generate() returns the prompt as-is so the pipeline can forward it.
  */
-import type { Processor } from '../processor.js';
+import type { Processor, JobRequest } from '../processor.js';
 export declare class NoneProcessor implements Processor {
     readonly name = "none";
     verify(): Promise<void>;
-    generate(prompt: string): Promise<string>;
-    generateStream(prompt: string): AsyncGenerator<string>;
+    generate(req: JobRequest): Promise<string>;
+    generateStream(req: JobRequest): AsyncGenerator<string>;
 }

package/dist/adapters/none-processor.js

@@ -9,10 +9,10 @@ export class NoneProcessor {
     async verify() {
         // No-op — nothing to check
     }
-    async generate(prompt) {
-        return prompt;
+    async generate(req) {
+        return req.input;
     }
-    async *generateStream(prompt) {
-        yield prompt;
+    async *generateStream(req) {
+        yield req.input;
     }
 }

package/dist/adapters/ollama-processor.d.ts

@@ -4,12 +4,12 @@
  * Reads OLLAMA_MODEL env var (default "llama3.2").
  * Zero behavior change from the previous hard-coded path in agent.ts.
  */
-import type { Processor } from '../processor.js';
+import type { Processor, JobRequest } from '../processor.js';
 export declare class OllamaProcessor implements Processor {
     private model;
     constructor();
     get name(): string;
     verify(): Promise<void>;
-    generate(prompt: string): Promise<string>;
-    generateStream(prompt: string): AsyncGenerator<string>;
+    generate(req: JobRequest): Promise<string>;
+    generateStream(req: JobRequest): AsyncGenerator<string>;
 }

package/dist/adapters/ollama-processor.js

@@ -20,10 +20,10 @@ export class OllamaProcessor {
                 `Run: ollama pull ${this.model}`);
         }
     }
-    async generate(prompt) {
-        return generate({ model: this.model, prompt });
+    async generate(req) {
+        return generate({ model: this.model, prompt: req.input });
     }
-    async *generateStream(prompt) {
-        yield* generateStream({ model: this.model, prompt });
+    async *generateStream(req) {
+        yield* generateStream({ model: this.model, prompt: req.input });
     }
 }