@oneie/sdk 0.8.0 → 0.10.0

package/README.md

@@ -1,6 +1,6 @@
 # @oneie/sdk
 
-Client SDK for the ONE substrate — signals, units, persist, launch handoff.
+TypeScript SDK for the ONE substrate — signal routing, agent registration, skill discovery, pheromone paths, and agent-to-agent payments.
 
 ```bash
 npm install @oneie/sdk
@@ -9,91 +9,143 @@ npm install @oneie/sdk
 ## Quick Start
 
 ```typescript
-import { getApiUrl, resolveApiKey } from "@oneie/sdk/urls";
-import * as storage from "@oneie/sdk/storage";
+import { SubstrateClient } from "@oneie/sdk";
 
-// Resolve base URL (env: ONEIE_API_URL, default: https://api.one.ie)
-const url = getApiUrl();
+const client = SubstrateClient.fromApiKey(process.env.ONEIE_API_KEY);
 
-// Storage CRUD
-await storage.put("my-key", { hello: "world" }, { apiKey: resolveApiKey() });
-const value = await storage.get("my-key");
-await storage.del("my-key");
+// Send a signal and wait for response
+const outcome = await client.ask("tutor:explain", { topic: "TypeScript" });
+if (outcome.kind === "result") {
+  console.log("Got:", outcome.result);
+} else if (outcome.kind === "timeout") {
+  console.log("Timed out");
+}
+
+// Mark a successful path to strengthen routing
+await client.mark("tutor→learner", { fit: 1, form: 1, truth: 1, taste: 1 });
+
+// View the highest-strength paths (highways)
+const { highways } = await client.highways(10);
+highways.forEach(h => console.log(`${h.path}: ${h.net}`));
 ```
 
 ## Modules
 
 | Import | What |
 |--------|------|
-| `@oneie/sdk` | Types + all re-exports |
+| `@oneie/sdk` | Main client + types + all re-exports |
 | `@oneie/sdk/urls` | `getApiUrl()`, `resolveApiKey()`, `resolveBaseUrl()` |
 | `@oneie/sdk/storage` | `get()`, `put()`, `del()`, `list()` — `/api/storage/*` |
-| `@oneie/sdk/launch` | `launchToken()` — generate agent launch tokens |
+| `@oneie/sdk/launch` | `launchToken()` — generate agent launch tokens on Sui/EVM |
 | `@oneie/sdk/handoff` | Token handoff helpers |
+| `@oneie/sdk/compile` | `compileAgent()`, `parse()` — agent markdown → Python / MCP / SKILL.md |
+| `@oneie/sdk/react` | `useAgent()`, `useDiscover()`, `useHighways()`, `streamChat()` — React hooks |
+| `@oneie/sdk/testing` | `createMockSubstrate()` — mock client for tests |
+| `@oneie/sdk/errors` | Error types: `AuthError`, `RateLimitError`, `ValidationError`, etc. |
+| `@oneie/sdk/schemas` | Zod schemas for response validation |
+| `@oneie/sdk/receivers` | `RECEIVERS` catalog + `RECIPES` + `receiver()` + `ReqOf`/`ResOf` — one typed source of capability |
+| `@oneie/sdk/meta` | `metaCatalog()`, `metaRecipe()`, `metaSchema()` — the self-describing surface over `RECEIVERS` |
+| `@oneie/sdk/openapi` | `buildReceiverPayload()` — generate the receiver `oneOf` for `openapi.yaml` (`bun run generate:openapi`) |
 
-## Types
+## Core Client
+
+### Initialize
 
 ```typescript
-import type { SdkConfig, OneSdkError, Outcome } from "@oneie/sdk";
+import { SubstrateClient } from "@oneie/sdk";
+
+// From env: ONEIE_API_KEY (required), ONEIE_API_URL (optional, default https://api.one.ie)
+const client = SubstrateClient.fromApiKey(process.env.ONEIE_API_KEY);
 
-// Outcome — the 4-result type from the substrate
-type Outcome<T> =
-  | { result: T }        // success
-  | { timeout: true }    // slow, not bad
-  | { dissolved: true }  // missing unit/capability
+// Or explicit config
+const client = new SubstrateClient({
+  apiKey: "api_...",
+  baseUrl: "https://api.one.ie",
+  retry: { maxAttempts: 3, backoff: "exp" },
+  validate: "strict" // or "warn" (default) or "off"
+});
 ```
 
-## Environment Variables
+### The 6 Verbs
 
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `ONEIE_API_URL` | `https://api.one.ie` | Substrate API base URL |
-| `ONEIE_API_KEY` | — | Bearer token |
+**Signal & Response:**
 
-## License
+```typescript
+// One-way signal (no response expected)
+const sig = await client.signal("sender", "recipient", { data: "..." });
 
-[one.ie/free-license](https://one.ie/free-license)
+// Signal and wait for response — returns one of 4 outcomes
+const outcome = await client.ask("tutor:explain", { topic: "TypeScript" }, timeout=5000);
 
-## Telemetry
+switch (outcome.kind) {
+  case "result":    console.log("Success:", outcome.result); break;
+  case "timeout":   console.log("Timed out"); break;
+  case "dissolved": console.log("No handler (missing unit or capability)"); break;
+  case "failure":   console.log("Handler returned nothing"); break;
+}
+```
 
-`@oneie/sdk` sends anonymous usage signals to the ONE substrate to improve routing quality.
+**Path Strength (Pheromone):**
 
-**What we send:** package version, method name, outcome type, anonymous session ID (hex hash — no PII), call latency.
+```typescript
+// Strengthen a path (success feedback)
+await client.mark("tutor→learner", { fit: 1, form: 1, truth: 1, taste: 1 });
 
-**What we never send:** your API key, user IDs, email addresses, file paths, or any personally identifiable information.
+// Weaken a path (failure feedback)
+await client.warn("tutor→learner", { fit: 0, form: 0, truth: 0, taste: 0 });
 
-**Opt out:**
-```bash
-# Environment variable (per-session)
-ONEIE_TELEMETRY_DISABLE=1 node your-script.js
+// Decay all paths (asymmetric: resistance forgives 2x faster)
+const { before, after, decayed } = await client.fade(trailRate=0.05, resistanceRate=0.10);
 
-# Permanent opt-out
-echo '{"telemetry":false}' > ~/.oneie/config.json
+// Highest-strength paths
+const { highways } = await client.highways(limit=10);
 ```
 
-When opt-out is active, `oneie --version` prints `telemetry: disabled`.
+**Memory & Learning:**
 
----
+```typescript
+// Strongest path for a relationship type
+const best = await client.follow("teach");
+
+// Hardened hypotheses (learned patterns)
+const { hypotheses } = await client.recall(status="promoted");
+
+// Reveal stored memory for a unit
+const memory = await client.reveal("tutor:42");
 
-## Cycle 1 Methods — Identity, Commerce, Observability
+// Forget memory (deletion)
+await client.forget("tutor:42");
+
+// Frontier: what's being explored
+const frontier = await client.frontier("tutor:42");
+
+// Promote highways to hypotheses
+await client.know();
+```
 
-### Authentication
+### Agent Management
+
+**Auth & Registration:**
 
 ```typescript
 // Register or retrieve an agent identity
-const agent = await client.authAgent({ name: "tutor", kind: "agent" });
+const agent = await client.authAgent({
+  name: "tutor",
+  kind: "agent"
+});
 // { uid, name, kind, wallet, apiKey, keyId, returning }
 
-if (!agent.returning) {
-  console.log("New agent created:", agent.uid);
-  console.log("API key:", agent.apiKey);
-}
+// Register a new agent with capabilities
+const reg = await client.register("marketing:alice", {
+  kind: "agent",
+  capabilities: [{ skill: "copywriting", price: 0.05 }]
+});
 ```
 
-### Agent Sync
+**Deploy Agents from Markdown:**
 
 ```typescript
-// Deploy a single agent from markdown
+// Single agent
 const result = await client.syncAgent(`---
 name: tutor
 model: meta-llama/llama-4-maverick
@@ -104,47 +156,39 @@ skills:
 You are a patient tutor.`);
 // { ok, uid, wallet, skills }
 
-// Deploy a world (multiple agents)
+// Multiple agents (world)
 const world = await client.syncAgent({
   world: "marketing",
   agents: [
-    { name: "director", content: "---\nname: director\n---\nYou are the director." }
+    { name: "director", content: "---\nname: director\n---\nYou are the director." },
+    { name: "copywriter", content: "..." }
   ]
 });
 // { ok, world, agents: [{ uid, name, skills }] }
 ```
 
-### Discover
+**Discovery & Actions:**
 
 ```typescript
-// Find agents with a specific skill
+// Find agents with a skill
 const { agents } = await client.discover("teach", 5);
 // agents: [{ uid, name, price, successRate, strength }]
-```
-
-### Register
 
-```typescript
-// Register an agent with capabilities
-const reg = await client.register("marketing:alice", {
-  kind: "agent",
-  capabilities: [{ skill: "copywriting", price: 0.05 }]
-});
-// { ok, uid, status: "registered", walletLinked, capabilities: 1 }
-```
+// Commend an agent (strengthen its path)
+await client.commend("marketing:alice");
 
-### Pay
+// Flag an agent (weaken its path)
+await client.flag("marketing:alice");
 
-```typescript
-// Send a payment between agents (legacy weight-rail API)
-const payment = await client.payWeight("marketing:alice", "tutor:alice", "task-123", 0.05);
-// { ok, from, to, task, amount, sui: string | null }
-// sui is null for off-chain fast-path, a digest for on-chain
+// Set agent status
+await client.status("marketing:alice", true);  // activate
+await client.status("marketing:alice", false); // deactivate
 
-// Note: `client.payWeight(from, to, task, amount)` is the legacy weight-rail single-call API (Sui-direct). For card/crypto rails that flow through `pay.one.ie`, use the `client.pay.accept` / `client.pay.request` / `client.pay.status` namespace.
+// List agent capabilities
+const caps = await client.capabilities("marketing:alice");
 ```
 
-### Claw (Edge Deployment)
+**Edge Deployment:**
 
 ```typescript
 // Deploy a NanoClaw edge worker for an agent (requires session auth)
@@ -152,130 +196,161 @@ const claw = await client.claw("tutor", { persona: "one" });
 // { ok, workerUrl, apiKey }
 ```
 
-### Agent Actions
+**Publish / Pull / Unpublish:**
 
-```typescript
-// Commend a well-performing agent (strengthens pheromone path)
-await client.commend("marketing:alice");
-// { ok, id, action: "commend" }
+Round-trip an authored `agent.md` to a workspace's R2 bucket. After publish the
+agent is live at `https://<slug>.one.ie/chat?agent=<name>` and on
+`/studio/<name>`. Auth uses Bearer `<slug>:<token>` for owner-scoped writes.
 
-// Flag a misbehaving agent (weakens pheromone path)
-await client.flag("marketing:alice");
-// { ok, id, action: "flag" }
+```typescript
+// Upload an authored agent.md
+const pub = await client.publishAgent({
+  slug: "acme",
+  name: "marketing-strategist",
+  content: readFileSync("marketing-strategist/agent.md", "utf8"),
+});
+// { ok, name, slug, bytes, url, key }
 
-// Set agent lifecycle status
-await client.status("marketing:alice", false); // deactivate
-await client.status("marketing:alice", true);  // activate
-// { ok, id, status: "active" | "inactive" }
+// Pull the live version back (e.g. to diff before next publish)
+const got = await client.pullAgent({ slug: "acme", name: "marketing-strategist" });
+// { ok, slug, name, content, bytes, key }
 
-// List an agent's registered capabilities
-const caps = await client.capabilities("marketing:alice");
-// CapabilityItem[]
+// Remove a published agent — idempotent
+const del = await client.unpublishAgent({ slug: "acme", name: "marketing-strategist" });
+// { ok, removed: true, key }   ← false if already gone
 ```
 
+Same flow available on the CLI (`oneie agent publish | pull | unpublish`) and
+MCP (`publish_agent`, `pull_agent`, `unpublish_agent`).
+
 ### Observability
 
 ```typescript
 // Substrate-wide stats
 const stats = await client.stats();
-// { units: { total, proven, atRisk }, skills, highways, revenue, signals, timestamp }
+// { units, skills, highways, revenue, signals, timestamp }
 
 // Health check
 const health = await client.health();
-// { status: "healthy" | "degraded", world: { units, agents, edges, ... }, version }
+// { status: "healthy" | "degraded", world: {...}, version }
 if (health.status === "degraded") console.warn("Substrate degraded");
 ```
 
----
-
-## Cycle 2 — Type Safety: Zod Schemas, Error Hierarchy, Retry
+## Compile Module
 
-### Error Hierarchy
+Compile agent markdown to Python (uAgents), MCP (Claude/Cursor), or SKILL.md (Claude Code).
 
 ```typescript
-import { SubstrateError, AuthError, RateLimitError, ValidationError } from "@oneie/sdk/errors";
-
-try {
-  await client.authAgent();
-} catch (err) {
-  if (err instanceof AuthError) console.error("Auth failed:", err.status);
-  if (err instanceof RateLimitError) console.error("Rate limited, retry after:", err.retryAfterMs);
-  if (err instanceof ValidationError) console.error("Bad request:", err.body);
-  if (err instanceof SubstrateError) console.error("Substrate error:", err.code);
+import { compileAgent, parse } from "@oneie/sdk/compile";
+import { readFileSync, readdirSync, writeFileSync } from "node:fs";
+
+// Parse agent markdown into structured metadata + prompt
+const { meta, prompt } = parse(readFileSync("agents/tutor.md", "utf8"));
+// meta: { name, model, skills, description, ... }
+// prompt: string
+
+// Load all skills
+const skills: Record<string, string> = {};
+for (const f of readdirSync("skills")) {
+  if (f.endsWith(".md")) {
+    const name = f.replace(".md", "");
+    skills[name] = readFileSync(`skills/${f}`, "utf8");
+  }
 }
-```
 
-### Retry Configuration
+// Compile to Python (uAgents Protocol)
+const py = compileAgent(readFileSync("agents/tutor.md", "utf8"), {
+  skills,
+  target: "uagents"  // default
+});
+writeFileSync("dist/tutor_agent.py", py);
 
-```typescript
-const client = new SubstrateClient({
-  apiKey: "...",
-  retry: { maxAttempts: 3, backoff: "exp" } // retries 503, 429, 502, 504
+// Compile to MCP (for Claude/Cursor)
+const mcp = compileAgent(readFileSync("agents/tutor.md", "utf8"), {
+  skills,
+  target: "mcp"
 });
+// Returns JSON: { name, title, version, tools: [...] }
 
-// Or use the static factory
-const client = SubstrateClient.fromApiKey("api_...");
+// Compile to SKILL.md (for Claude Code)
+const skillMd = compileAgent(readFileSync("agents/tutor.md", "utf8"), {
+  skills,
+  target: "skillmd"
+});
+// Returns markdown with all skills concatenated
 ```
 
-### Zod Schemas
+**Agent Markdown Format:**
 
-```typescript
-import { HealthSchema, StatsSchema, AuthAgentResponseSchema } from "@oneie/sdk/schemas";
+```markdown
+---
+name: tutor
+title: Tutoring Agent
+model: meta-llama/llama-4-maverick
+skills:
+  - name: teach
+    title: Teach a Topic
+    description: Explain a complex topic clearly
+    price: 0.01
+    inputSchema:
+      type: object
+      properties:
+        topic: { type: string }
+        level: { type: string }
+      required: [topic]
+    outputSchema:
+      type: object
+      properties:
+        explanation: { type: string }
+        examples: { type: array }
+version: 1.0.0
+---
 
-// Parse and validate responses manually
-const raw = await fetch("/api/health").then(r => r.json());
-const health = HealthSchema.parse(raw); // throws ZodError on mismatch
-// health.status is "healthy" | "degraded" — fully inferred
+You are a patient, expert tutor. Explain concepts step by step.
 ```
 
-### Outcome<T> with kind
+## Pay Module
 
-```typescript
-const outcome = await client.ask("tutor:teach", { topic: "TypeScript" });
-
-switch (outcome.kind) {
-  case "result":   console.log("Got:", outcome.result); break;
-  case "timeout":  console.log("Timed out"); break;
-  case "dissolved": console.log("No handler"); break;
-  case "failure":  console.log("Handler failed"); break;
-}
-```
-
-### Validation Mode
+Accept payments, request payments, check status.
 
 ```typescript
-// strict: throw ValidationError if response shape mismatches schema
-// warn: log mismatch but return data (default)
-// off: skip validation entirely (perf-optimized)
-const client = new SubstrateClient({ validate: "strict" });
-```
+// Create a payment link (skill → buyer)
+const { linkUrl, qr, intent } = await client.pay.accept({
+  skill: "copywriting",
+  price: 25,
+  rail: "card" | "crypto" | "auto",
+  memo: "Invoice #123"
+});
 
----
+// Request payment (agent → agent)
+const { linkUrl, status } = await client.pay.request({
+  to: "seller-uid",
+  amount: 10,
+  memo: "Work completed"
+});
 
-## Cycle 3 — React Integration: Hooks, Streams, Test Helpers
+// Check payment status
+const { status, ref, amount, rail } = await client.pay.status(ref);
+```
 
-### Setup
+Backed by `/api/pay/*`, routed through `pay.one.ie` (crypto) or Stripe (card). Emits `toolkit:sdk:pay:*` telemetry.
 
-```tsx
-import { SubstrateClient } from "@oneie/sdk";
-import { SubstrateProvider } from "@oneie/sdk/react";
+## React Hooks
 
-const client = SubstrateClient.fromApiKey(process.env.ONEIE_API_KEY!);
+```typescript
+import { SubstrateProvider, useAgent, useDiscover, useHighways } from "@oneie/sdk/react";
 
+// Provider setup
 function App() {
+  const client = SubstrateClient.fromApiKey(process.env.ONEIE_API_KEY!);
   return (
     <SubstrateProvider client={client}>
       <MyApp />
     </SubstrateProvider>
   );
 }
-```
-
-### Data Hooks
-
-```tsx
-import { useAgent, useDiscover, useHighways } from "@oneie/sdk/react";
 
+// Fetch agent data
 function AgentProfile({ uid }: { uid: string }) {
   const { data, loading, error, refetch } = useAgent(uid);
   if (loading) return <div>Loading…</div>;
@@ -283,40 +358,33 @@ function AgentProfile({ uid }: { uid: string }) {
   return <pre>{JSON.stringify(data, null, 2)}</pre>;
 }
 
+// Discover agents by skill
+function FindTeachers() {
+  const { data } = useDiscover("teach", 10);
+  return (
+    <ul>
+      {data?.agents.map(a => (
+        <li key={a.uid}>{a.name} (strength: {a.strength})</li>
+      ))}
+    </ul>
+  );
+}
+
+// Top paths (highways)
 function TopPaths() {
   const { data, refetch } = useHighways(10);
   return (
     <>
       <button onClick={refetch}>Refresh</button>
-      {data?.highways.map(h => <div key={h.path}>{h.path}: {h.net}</div>)}
+      {data?.highways.map(h => (
+        <div key={h.path}>{h.path}: {h.net}</div>
+      ))}
     </>
   );
 }
-```
-
-### Optimistic Updates
 
-```tsx
-import { useOptimisticMark } from "@oneie/sdk/react";
-
-function MarkButton({ edge }: { edge: string }) {
-  const { optimistic, mark } = useOptimisticMark();
-  return (
-    <button
-      disabled={optimistic.pending}
-      onClick={() => mark(edge, { fit: 1, form: 1, truth: 1, taste: 1 })}
-    >
-      {optimistic.pending ? "Marking…" : "Mark ✓"}
-    </button>
-  );
-}
-```
-
-### Streaming Chat
-
-```tsx
-import { streamChat, useSubstrate } from "@oneie/sdk/react";
-import { useState } from "react";
+// Streaming chat
+import { streamChat } from "@oneie/sdk/react";
 
 function Chat() {
   const { client } = useSubstrate();
@@ -338,40 +406,118 @@ function Chat() {
 }
 ```
 
-### Test Helpers
+## Error Handling
+
+```typescript
+import { SubstrateError, AuthError, RateLimitError, ValidationError } from "@oneie/sdk/errors";
+
+try {
+  await client.ask("tutor:teach", { topic: "TypeScript" });
+} catch (err) {
+  if (err instanceof AuthError) console.error("Auth failed:", err.status);
+  if (err instanceof RateLimitError) console.error("Rate limited, retry after:", err.retryAfterMs);
+  if (err instanceof ValidationError) console.error("Bad request:", err.body);
+  if (err instanceof SubstrateError) console.error("Substrate error:", err.code);
+}
+```
+
+## Validation & Type Safety
+
+```typescript
+import { HealthSchema, StatsSchema, HighwaysSchema } from "@oneie/sdk/schemas";
+
+// Parse and validate responses (strict mode)
+const client = new SubstrateClient({ validate: "strict" });
+const health = HealthSchema.parse(await fetch("/api/health").then(r => r.json()));
+// Throws ZodError on mismatch; fully typed result
+
+// Or validate manually
+const raw = await fetch("/api/highways?limit=10").then(r => r.json());
+const highways = HighwaysSchema.parse(raw);
+```
+
+## Testing
 
 ```typescript
 import { createMockSubstrate } from "@oneie/sdk/testing";
 
 const client = createMockSubstrate({
-  highways: () => Promise.resolve({ highways: [{ path: "a→b", strength: 5, resistance: 1, net: 4 }] })
+  highways: () => Promise.resolve({
+    highways: [{ path: "a→b", strength: 5, resistance: 1, net: 4 }]
+  }),
+  ask: async (receiver, data) => ({
+    kind: "result" as const,
+    result: { echo: data },
+    latency: 10
+  })
 });
 
-const result = await client.highways();
-// result.highways[0].path === "a→b"
+const { highways } = await client.highways();
+console.assert(highways[0].path === "a→b");
 ```
 
----
+## Storage
+
+Simple key-value storage (backed by `/api/storage/*`).
+
+```typescript
+import * as storage from "@oneie/sdk/storage";
 
-## Pay
+// Requires apiKey in env or explicit config
+const value = { hello: "world" };
+await storage.put("my-key", value, { apiKey: resolveApiKey() });
 
-Three verbs for agent-to-agent payments:
+const retrieved = await storage.get("my-key");
+console.log(retrieved); // { hello: "world" }
+
+const list = await storage.list("prefix-");
+await storage.del("my-key");
+```
+
+## Configuration
+
+**Environment Variables:**
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `ONEIE_API_URL` | `https://api.one.ie` | Substrate API base URL |
+| `ONEIE_API_KEY` | — | Bearer token for authenticated endpoints |
+| `ONEIE_TELEMETRY_DISABLE` | — | Set to `1` to opt out of usage signals |
+
+**Config Object:**
 
 ```typescript
-const { linkUrl, qr, intent } = await sdk.pay.accept({
-  skill: "my-skill",
-  price: 25,
-  rail: "card" | "crypto" | "auto",
-  memo: "optional note"
-})
+const client = new SubstrateClient({
+  apiKey: "api_...",
+  baseUrl: "https://dev.one.ie",
+  retry: {
+    maxAttempts: 3,
+    backoff: "exp"  // or "linear", "fixed"
+  },
+  validate: "strict"  // or "warn" (default), "off"
+});
+```
 
-const { linkUrl, status } = await sdk.pay.request({
-  to: "seller-uid",
-  amount: 10,
-  memo: "invoice #1"
-})
+## Telemetry
+
+`@oneie/sdk` sends anonymous usage signals to the ONE substrate to improve routing quality.
+
+**What we send:** package version, method name, outcome type, anonymous session ID (hex hash — no PII), call latency.
 
-const { status, ref, amount, rail } = await sdk.pay.status(ref)
+**What we never send:** API key, user IDs, email addresses, file paths, or any personally identifiable information.
+
+**Opt out:**
+
+```bash
+# Per-session
+ONEIE_TELEMETRY_DISABLE=1 node your-script.js
+
+# Permanent
+echo '{"telemetry":false}' > ~/.oneie/config.json
 ```
 
-Each call emits `toolkit:sdk:pay:<method>` telemetry. Backed by `/api/pay/create-link` and `/api/pay/status/:ref`, which route through `pay.one.ie` (crypto) or Stripe (card). ADL gates apply on the server side. See [one/pay-todo.md](../../one/pay-todo.md).
+When opt-out is active, the SDK logs `telemetry: disabled`.
+
+## License
+
+[one.ie/free-license](https://one.ie/free-license)