2020117-agent 0.1.1 → 0.1.3

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 });
     }
 }

package/dist/agent.js

@@ -60,6 +60,12 @@ for (const arg of process.argv.slice(2)) {
         case '--api-url':
             process.env.API_2020117_URL = val;
             break;
+        case '--models':
+            process.env.MODELS = val;
+            break;
+        case '--skill':
+            process.env.SKILL_FILE = val;
+            break;
     }
 }
 import { SwarmNode, topicFromKind } from './swarm.js';
@@ -67,6 +73,7 @@ import { receiveToken, peekToken, mintTokens, splitTokens } from './cashu.js';
 import { createProcessor } from './processor.js';
 import { hasApiKey, loadAgentName, registerService, startHeartbeatLoop, getInbox, acceptJob, sendFeedback, submitResult, createJob, getJob, } from './api.js';
 import { randomBytes } from 'crypto';
+import { readFileSync } from 'fs';
 // --- Config from env ---
 const KIND = Number(process.env.DVM_KIND) || 5100;
 const MAX_CONCURRENT = Number(process.env.MAX_JOBS) || 3;
@@ -83,6 +90,25 @@ const SUB_BID = Number(process.env.SUB_BID) || 100;
 const MAX_SATS_PER_CHUNK = Number(process.env.MAX_SATS_PER_CHUNK) || 5;
 const MIN_BID_SATS = Number(process.env.MIN_BID_SATS) || SATS_PER_CHUNK * CHUNKS_PER_PAYMENT; // default = pricing per job
 const SUB_BATCH_SIZE = Number(process.env.SUB_BATCH_SIZE) || 500; // chars to accumulate before local processing
+// --- Skill file loading ---
+function loadSkill() {
+    const skillPath = process.env.SKILL_FILE;
+    if (!skillPath)
+        return null;
+    try {
+        const raw = readFileSync(skillPath, 'utf-8');
+        const skill = JSON.parse(raw);
+        if (!skill.name || !skill.version || !Array.isArray(skill.features)) {
+            console.error(`[agent] Skill file missing required fields: name, version, features`);
+            process.exit(1);
+        }
+        return skill;
+    }
+    catch (e) {
+        console.error(`[agent] Failed to load skill file "${skillPath}": ${e.message}`);
+        process.exit(1);
+    }
+}
 const state = {
     agentName: loadAgentName(),
     activeJobs: 0,
@@ -91,6 +117,7 @@ const state = {
     pollTimer: null,
     swarmNode: null,
     processor: null,
+    skill: loadSkill(),
 };
 // --- Capacity management ---
 function acquireSlot() {
@@ -123,6 +150,9 @@ async function main() {
     }
     await state.processor.verify();
     console.log(`[${label}] Processor "${state.processor.name}" verified`);
+    if (state.skill) {
+        console.log(`[${label}] Skill: ${state.skill.name} v${state.skill.version} (${state.skill.features.join(', ')})`);
+    }
     // 2. Platform registration + heartbeat
     await setupPlatform(label);
     // 3. Async inbox poller
@@ -140,11 +170,14 @@ async function setupPlatform(label) {
         return;
     }
     console.log(`[${label}] Registering on platform...`);
+    const models = process.env.MODELS ? process.env.MODELS.split(',').map(s => s.trim()) : undefined;
     await registerService({
         kind: KIND,
         satsPerChunk: SATS_PER_CHUNK,
         chunksPerPayment: CHUNKS_PER_PAYMENT,
         model: state.processor?.name || 'unknown',
+        models,
+        skill: state.skill,
     });
     state.stopHeartbeat = startHeartbeatLoop(() => getAvailableCapacity());
 }
@@ -176,7 +209,7 @@ function startInboxPoller(label) {
                     continue;
                 }
                 // Process in background — don't await
-                processAsyncJob(label, job.id, job.input).catch((err) => {
+                processAsyncJob(label, job.id, job.input, job.params).catch((err) => {
                     console.error(`[${label}] Async job ${job.id} error: ${err.message}`);
                 });
             }
@@ -194,7 +227,7 @@ function startInboxPoller(label) {
     // First poll after a short delay to let swarm set up
     state.pollTimer = setTimeout(poll, 2000);
 }
-async function processAsyncJob(label, inboxJobId, input) {
+async function processAsyncJob(label, inboxJobId, input, params) {
     try {
         console.log(`[${label}] Accepting job ${inboxJobId}...`);
         const accepted = await acceptJob(inboxJobId);
@@ -214,7 +247,7 @@ async function processAsyncJob(label, inboxJobId, input) {
                     // API delegation is non-streaming — collect full result, then process
                     const subResult = await delegateAPI(SUB_KIND, input, SUB_BID, SUB_PROVIDER);
                     console.log(`[${label}] Job ${providerJobId}: sub-task returned ${subResult.length} chars`);
-                    result = await state.processor.generate(subResult);
+                    result = await state.processor.generate({ input: subResult, params });
                 }
                 else {
                     // P2P delegation — stream-collect from sub-provider, batch-translate
@@ -226,12 +259,12 @@ async function processAsyncJob(label, inboxJobId, input) {
             }
             catch (e) {
                 console.error(`[${label}] Job ${providerJobId}: sub-task failed: ${e.message}, using original input`);
-                result = await state.processor.generate(input);
+                result = await state.processor.generate({ input, params });
             }
         }
         else {
             // No pipeline — direct local processing
-            result = await state.processor.generate(input);
+            result = await state.processor.generate({ input, params });
         }
         console.log(`[${label}] Job ${providerJobId}: generated ${result.length} chars`);
         const ok = await submitResult(providerJobId, result);
@@ -402,7 +435,7 @@ async function* delegateP2PStream(kind, input, budgetSats) {
 async function* pipelineStream(kind, input, budgetSats) {
     let batch = '';
     async function* translateBatch(text) {
-        for await (const token of state.processor.generateStream(text)) {
+        for await (const token of state.processor.generateStream({ input: text })) {
             yield token;
         }
     }
@@ -462,6 +495,10 @@ async function startSwarmListener(label) {
     console.log(`[${label}] P2P listening for customers...`);
     node.on('message', async (msg, socket, peerId) => {
         const tag = peerId.slice(0, 8);
+        if (msg.type === 'skill_request') {
+            node.send(socket, { type: 'skill_response', id: msg.id, skill: state.skill });
+            return;
+        }
         if (msg.type === 'request') {
             console.log(`[${label}] P2P job ${msg.id} from ${tag}: "${(msg.input || '').slice(0, 60)}..."`);
             if (!acquireSlot()) {
@@ -571,7 +608,7 @@ async function runP2PGeneration(node, job, msg, label) {
     // Pick the source: pipeline (delegate + local) or direct local generation
     const source = SUB_KIND
         ? pipelineStream(SUB_KIND, msg.input || '', SUB_BUDGET)
-        : state.processor.generateStream(msg.input || '');
+        : state.processor.generateStream({ input: msg.input || '', params: msg.params });
     try {
         for await (const chunk of source) {
             if (job.stopped) {

package/dist/api.d.ts

@@ -22,6 +22,8 @@ export declare function registerService(opts: {
     satsPerChunk: number;
     chunksPerPayment: number;
     model?: string;
+    models?: string[];
+    skill?: Record<string, unknown> | null;
 }): Promise<unknown | null>;
 export declare function sendHeartbeat(capacity?: number): Promise<boolean>;
 export declare function getOnlineProviders(kind: number): Promise<OnlineAgent[]>;

package/dist/api.js

@@ -136,6 +136,10 @@ export async function registerService(opts) {
             description: desc,
             pricing: { min_sats: satsPerPayment, max_sats: satsPerPayment },
         };
+        if (opts.models && opts.models.length > 0)
+            body.models = opts.models;
+        if (opts.skill)
+            body.skill = opts.skill;
         const resp = await fetch(`${BASE_URL}/api/dvm/services`, {
             method: 'POST',
             headers: {

package/dist/customer.js

@@ -78,6 +78,30 @@ async function main() {
         process.exit(1);
     }
     console.log(`[customer] Connected to provider: ${peer.peerId.slice(0, 12)}...`);
+    // Query provider skill
+    console.log(`[customer] Querying provider skill...`);
+    const skillJobId = randomBytes(4).toString('hex');
+    node.send(peer.socket, { type: 'skill_request', id: skillJobId, kind: KIND });
+    const providerSkill = await new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            console.log(`[customer] No skill response (provider may not support skill)`);
+            resolve(null);
+        }, 5000);
+        const handler = (msg) => {
+            if (msg.type === 'skill_response' && msg.id === skillJobId) {
+                clearTimeout(timer);
+                node.removeListener('message', handler);
+                resolve(msg.skill || null);
+            }
+        };
+        node.on('message', handler);
+    });
+    if (providerSkill) {
+        console.log(`[customer] Provider skill: ${providerSkill.name} v${providerSkill.version}`);
+        if (providerSkill.features) {
+            console.log(`[customer] Features: ${providerSkill.features.join(', ')}`);
+        }
+    }
     // --- Step 3: Send request and handle streaming payment ---
     return new Promise((resolve) => {
         let microTokens = [];

package/dist/processor.d.ts

@@ -9,15 +9,22 @@
  *   PROCESSOR=exec:./cmd    — stdin/stdout child process
  *   PROCESSOR=http://url    — remote HTTP endpoint
  */
+/** Structured request passed to every Processor method. */
+export interface JobRequest {
+    /** The text input (prompt / source text / query) */
+    input: string;
+    /** Optional extra parameters (model overrides, LoRA, ControlNet, etc.) */
+    params?: Record<string, unknown>;
+}
 export interface Processor {
     /** Human-readable name for logs (e.g. "ollama:llama3.2", "none") */
     readonly name: string;
     /** Startup check — may throw to abort launch */
     verify(): Promise<void>;
     /** Non-streaming generation */
-    generate(prompt: string): Promise<string>;
+    generate(req: JobRequest): Promise<string>;
     /** Streaming generation — yields chunks as they arrive */
-    generateStream(prompt: string): AsyncGenerator<string>;
+    generateStream(req: JobRequest): AsyncGenerator<string>;
 }
 /**
  * Factory — reads PROCESSOR env var and returns the appropriate backend.

package/dist/swarm.d.ts

@@ -5,7 +5,9 @@
  * Customer: joins the same topic to find the provider
  *
  * Wire protocol (newline-delimited JSON) — streaming payment:
- *   → { type: "request", id, kind, input, budget }         customer sends job with budget
+ *   → { type: "skill_request", id, kind }                  customer queries provider skill
+ *   ← { type: "skill_response", id, skill }                provider replies with skill manifest
+ *   → { type: "request", id, kind, input, budget, params } customer sends job with budget
  *   ← { type: "offer", id, sats_per_chunk, chunks_per_payment }  provider quotes price
  *   → { type: "payment", id, token }                       customer sends micro-token
  *   ← { type: "payment_ack", id, amount }                  provider confirms + accepts
@@ -22,7 +24,7 @@
 import Hyperswarm from 'hyperswarm';
 import { EventEmitter } from 'events';
 export interface SwarmMessage {
-    type: 'request' | 'accepted' | 'chunk' | 'result' | 'error' | 'payment' | 'payment_ack' | 'offer' | 'pay_required' | 'stop';
+    type: 'request' | 'accepted' | 'chunk' | 'result' | 'error' | 'payment' | 'payment_ack' | 'offer' | 'pay_required' | 'stop' | 'skill_request' | 'skill_response';
     id: string;
     kind?: number;
     input?: string;
@@ -31,6 +33,8 @@ export interface SwarmMessage {
     token?: string;
     amount?: number;
     message?: string;
+    params?: Record<string, unknown>;
+    skill?: Record<string, unknown> | null;
     sats_per_chunk?: number;
     chunks_per_payment?: number;
     budget?: number;

package/dist/swarm.js

@@ -5,7 +5,9 @@
  * Customer: joins the same topic to find the provider
  *
  * Wire protocol (newline-delimited JSON) — streaming payment:
- *   → { type: "request", id, kind, input, budget }         customer sends job with budget
+ *   → { type: "skill_request", id, kind }                  customer queries provider skill
+ *   ← { type: "skill_response", id, skill }                provider replies with skill manifest
+ *   → { type: "request", id, kind, input, budget, params } customer sends job with budget
  *   ← { type: "offer", id, sats_per_chunk, chunks_per_payment }  provider quotes price
  *   → { type: "payment", id, token }                       customer sends micro-token
  *   ← { type: "payment_ack", id, amount }                  provider confirms + accepts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "2020117-agent",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "2020117 agent runtime — API polling + Hyperswarm P2P + Cashu streaming payments",
   "type": "module",
   "bin": {