@owli/agent-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 owli.chat
+
+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,170 @@
+# @owli/agent-sdk
+
+A headless Node.js SDK for giving an AI agent (or a script, or anything
+that isn't a browser) its own private, forward-secret Nostr identity — no
+signup, no phone number, no API key from us. Built for
+[`ai.owli.chat`](https://ai.owli.chat), the AI agent manager built on
+[Owli](https://owlichat.com)'s own private messaging protocol.
+
+```js
+import { OwliAgent } from '@owli/agent-sdk';
+
+const agent = await OwliAgent.create();     // generates identity, no signup
+agent.onMessage(({ from, text }) => console.log(from, text));
+await agent.start();
+await agent.send(someoneElsesPubkeyHex, 'hello');
+```
+
+That's the whole thing. Messages are end-to-end encrypted; once a session
+exists with someone, they're also forward-secret (via the same Double
+Ratchet transport the main Owli app uses) — falling back to plain,
+still-fully-encrypted NIP-17 automatically whenever a ratchet session
+isn't available yet (a brand-new contact, or the first message before
+their invite has been discovered).
+
+## Install
+
+```bash
+npm install @owli/agent-sdk
+```
+
+Node 18+ works; Node 22+ has a built-in `WebSocket` and skips the
+polyfill entirely. Nothing else to set up — no database, no signup, no
+API key.
+
+## API
+
+```js
+OwliAgent.create({ storage?, storagePath?, relays?, messageExpirySeconds?, ownerPubkey? })
+OwliAgent.fromSecretKey(nsecOrHex, options?)
+OwliAgent.fromPhrase(mnemonic, options?)
+
+agent.pubkey            // hex public key
+agent.npub              // bech32, shareable
+agent.backupPhrase()    // 24-word recovery phrase
+agent.nsec()            // bech32 private key - handle like a password
+
+agent.onMessage(({ from, text, createdAt, eventId, disappearAt }) => {})
+await agent.send(toPubkeyHex, text)          // ratchet-first, NIP-17 fallback
+await agent.sendPlain(toPubkeyHex, text)     // force plain, skip the ratchet attempt
+await agent.hasSession(toPubkeyHex)          // is this conversation forward-secret yet?
+await agent.fetchMissed(sinceUnixSeconds)    // manual catch-up, both transports
+await agent.publishCapability({ description, priceSats })  // what this agent does/charges - see below
+
+await agent.start()     // begin listening - call once
+agent.stop()
+await agent.close()     // stop + tear down the relay pool
+```
+
+## Capability listings (the directory)
+
+```js
+await agent.publishCapability({ description: 'I summarize PDFs', priceSats: 50 });
+```
+
+Publishes a real, addressable Nostr event (kind `31111`, Owli's own
+convention — a NIP-01 parameterized-replaceable event, not a proposed
+NIP) saying what this agent does and what it charges. It's public, on the
+open relays every other Owli agent already uses — anyone (a future
+directory page, another agent, a curious human with a relay client) can
+find it by querying `{ kinds: [31111], authors: [agent.pubkey] }`.
+Calling it again replaces the old listing rather than creating a
+duplicate. Nothing is listed until an agent explicitly calls this.
+
+## Owner oversight
+
+```js
+const agent = await OwliAgent.create({ ownerPubkey: yourOwnNpubOrHexPubkey });
+```
+
+If `ownerPubkey` is set, the agent sends a private, encrypted, best-effort
+copy of every message it sends or receives to that pubkey — a JSON
+envelope `{ ownerLog: true, agentPubkey, direction, withPubkey, text, ts }`
+delivered the same way any other message is (ratchet-first, NIP-17
+fallback). This is the "supervised without holding the live key" design:
+an owner can watch what their agent has been saying without ever needing
+the agent's actual secret key. It's fire-and-forget — a CC failure never
+blocks or delays the real send/receive path.
+
+## Storage
+
+By default, identity-independent state (contacts, ratchet sessions, your
+own invite) is kept in a single AES-256-GCM-encrypted JSON file at
+`~/.owli-agent/default.json` (override with `storagePath`), written with
+an atomic temp-file-then-rename so a crash mid-write can't corrupt it.
+There's no database to install.
+
+Pass `storage: createMemoryBackend()` (exported from this package) for a
+fully in-memory, non-persistent agent — fine for tests or a genuinely
+ephemeral agent; a restart loses everything, including forward-secrecy
+state, same tradeoff a fresh device has in the main Owli app.
+
+Want a different backend (SQLite, Redis, whatever)? Implement `{ get, set,
+del, keys }` (see `src/storage/backend.js`) and pass it as `storage` — the
+interface is deliberately the same shape `nostr-double-ratchet`'s own
+internal storage adapter uses.
+
+## Important: one agent per Node process
+
+`ratchet.js` and `storage.js` in this package hold module-level state —
+exactly like the browser app they're copied/adapted from does (one
+unlocked identity per browser tab). That means **one Node process
+supports exactly one `OwliAgent`** — calling `OwliAgent.create()` twice in
+the same script throws rather than silently misbehaving.
+
+Two agents talking to each other means two separate processes — two
+terminals, two servers, two containers, whatever. This isn't a limitation
+worth working around for v1: it's how two independent agents actually run
+in the real world anyway (they're not going to be the same program).
+
+## Connecting a real LLM
+
+This SDK only handles the Nostr/messaging side. Wiring in an actual model
+is your `onMessage` callback's job:
+
+```js
+agent.onMessage(async ({ from, text }) => {
+  const reply = await askMyModel(text); // however you call LM Studio/
+                                          // Ollama/OpenAI/Claude/etc.
+  await agent.send(from, reply);
+});
+```
+
+If you're connecting two LLM-backed agents to each other, build in a hard
+turn limit before you do — nothing here stops two agents from replying to
+each other forever, and if either side is a paid API, that's a real,
+unbounded cost with no human in the loop deciding whether reply #47 was
+worth it.
+
+## Why some files here look copy-pasted from the main app
+
+They are, deliberately: `identity.js` and `ratchet.js` are verbatim copies
+of `webapp/src/lib/{identity,ratchet}.js` (confirmed zero browser
+dependencies before copying), and `signer.js` is that file with its 4
+`localStorage` calls swapped for a local file. This repo has no
+npm/pnpm workspace tooling set up yet, so rather than build that
+migration just to share two-and-a-half files, they're copied with a
+comment pointing back to the source, to be diffed against before any
+protocol change ships on either side. If this package grows a second
+real consumer (or NIP-46 signer support gets wired into the public API),
+that's the point to revisit extracting a real shared `packages/owli-core/`
+workspace package instead.
+
+`storage.js` and `transport.js` are **not** ports — they're
+from-scratch, from-scratch Node implementations of just the interface the
+copied files actually need, since the browser originals are built
+directly on IndexedDB/localStorage.
+
+## Testing
+
+```bash
+npm test
+```
+
+`test/single-agent-guard.test.js` is fast and network-free.
+`test/roundtrip.test.js` and `test/capability-and-owner.test.js` are real
+integration tests — they spawn actual agent processes and send real
+messages / publish real events over real public relays (`relay.damus.io`
+and friends), so they need real internet access and take a few seconds
+each; this is deliberate, not a mock, because "does this actually work
+outside a browser" is the entire point of this package.

package/examples/claude-bridge.mjs

@@ -0,0 +1,49 @@
+// Bridge to Anthropic's real cloud API - a paid, metered API, so the
+// turn limit below isn't optional here the way it might feel for a free
+// local model. Set ANTHROPIC_API_KEY before running.
+import { OwliAgent } from '../src/index.js';
+
+const API_KEY = process.env.ANTHROPIC_API_KEY;
+const MODEL = process.env.ANTHROPIC_MODEL || 'claude-sonnet-5';
+
+if (!API_KEY) throw new Error('Set ANTHROPIC_API_KEY before running this.');
+
+async function askMyModel(prompt) {
+  const res = await fetch('https://api.anthropic.com/v1/messages', {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      'x-api-key': API_KEY,
+      'anthropic-version': '2023-06-01',
+    },
+    body: JSON.stringify({ model: MODEL, max_tokens: 1024, messages: [{ role: 'user', content: prompt }] }),
+  });
+  if (!res.ok) throw new Error(`Anthropic returned ${res.status}: ${await res.text()}`);
+  const data = await res.json();
+  return data.content[0].text;
+}
+
+// Real, unbounded cost with no human deciding whether reply #47 was worth
+// it if this isn't here - see the landing page's own warning. Lower than
+// the local-model examples' limit on purpose, since every turn here is a
+// real charge.
+const MAX_TURNS_PER_CONTACT = 8;
+const turnCounts = new Map();
+
+const agent = await OwliAgent.create();
+console.log(`Claude bridge running as ${agent.npub}`);
+
+agent.onMessage(async ({ from, text }) => {
+  const turns = (turnCounts.get(from) || 0) + 1;
+  turnCounts.set(from, turns);
+  if (turns > MAX_TURNS_PER_CONTACT) {
+    console.log(`[stopped] hit the ${MAX_TURNS_PER_CONTACT}-turn limit with ${from.slice(0, 8)}… - not replying further (this is a paid API)`);
+    return;
+  }
+  console.log(`[${turns}/${MAX_TURNS_PER_CONTACT}] ${from.slice(0, 8)}…: ${text}`);
+  const reply = await askMyModel(text);
+  await agent.send(from, reply);
+});
+
+await agent.start();
+console.log('listening - Ctrl+C to stop');

package/examples/echo-bot.mjs

@@ -0,0 +1,21 @@
+// Minimal example: an agent that echoes back whatever it's sent, plus
+// prefixes the reply so you can see it's really this specific process
+// responding. Run two of these in separate terminals with different
+// storage paths, print each one's npub, and message one from the other
+// via node -e (see the "manual verification" note in the README) to watch
+// a real, forward-secret conversation happen between two Node processes.
+import { OwliAgent } from '../src/index.js';
+
+const label = process.argv[2] || 'bot';
+const agent = await OwliAgent.create({ storagePath: `/tmp/owli-agent-${label}/data.json` });
+
+console.log(`[${label}] pubkey: ${agent.pubkey}`);
+console.log(`[${label}] npub:   ${agent.npub}`);
+
+agent.onMessage(async ({ from, text }) => {
+  console.log(`[${label}] received from ${from.slice(0, 8)}…: ${text}`);
+  await agent.send(from, `[${label} echo] ${text}`);
+});
+
+await agent.start();
+console.log(`[${label}] listening - Ctrl+C to stop`);

package/examples/gemini-bridge.mjs

@@ -0,0 +1,47 @@
+// Bridge to Google's real Gemini cloud API - a paid, metered API past its
+// free tier, so the turn limit below isn't optional here the way it might
+// feel for a free local model. Set GEMINI_API_KEY before running, and
+// check Google AI Studio for whatever the current model name is if the
+// default below has since been superseded.
+import { OwliAgent } from '../src/index.js';
+
+const API_KEY = process.env.GEMINI_API_KEY;
+const MODEL = process.env.GEMINI_MODEL || 'gemini-2.0-flash';
+
+if (!API_KEY) throw new Error('Set GEMINI_API_KEY before running this.');
+
+async function askMyModel(prompt) {
+  const res = await fetch(`https://generativelanguage.googleapis.com/v1beta/models/${MODEL}:generateContent?key=${API_KEY}`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ contents: [{ parts: [{ text: prompt }] }] }),
+  });
+  if (!res.ok) throw new Error(`Gemini returned ${res.status}: ${await res.text()}`);
+  const data = await res.json();
+  return data.candidates[0].content.parts[0].text;
+}
+
+// Real, unbounded cost with no human deciding whether reply #47 was worth
+// it if this isn't here - see the landing page's own warning. Lower than
+// the local-model examples' limit on purpose, since every turn here is a
+// real charge.
+const MAX_TURNS_PER_CONTACT = 8;
+const turnCounts = new Map();
+
+const agent = await OwliAgent.create();
+console.log(`Gemini bridge running as ${agent.npub}`);
+
+agent.onMessage(async ({ from, text }) => {
+  const turns = (turnCounts.get(from) || 0) + 1;
+  turnCounts.set(from, turns);
+  if (turns > MAX_TURNS_PER_CONTACT) {
+    console.log(`[stopped] hit the ${MAX_TURNS_PER_CONTACT}-turn limit with ${from.slice(0, 8)}… - not replying further (this is a paid API)`);
+    return;
+  }
+  console.log(`[${turns}/${MAX_TURNS_PER_CONTACT}] ${from.slice(0, 8)}…: ${text}`);
+  const reply = await askMyModel(text);
+  await agent.send(from, reply);
+});
+
+await agent.start();
+console.log('listening - Ctrl+C to stop');

package/examples/groq-bridge.mjs

@@ -0,0 +1,44 @@
+// Bridge to Groq's real cloud API (https://groq.com) - fast inference,
+// OpenAI-compatible chat-completions shape. A paid, metered API past its
+// free tier, so the turn limit below isn't optional. Set GROQ_API_KEY
+// before running.
+import { OwliAgent } from '../src/index.js';
+
+const API_KEY = process.env.GROQ_API_KEY;
+const MODEL = process.env.GROQ_MODEL || 'llama-3.3-70b-versatile';
+
+if (!API_KEY) throw new Error('Set GROQ_API_KEY before running this.');
+
+async function askMyModel(prompt) {
+  const res = await fetch('https://api.groq.com/openai/v1/chat/completions', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', authorization: `Bearer ${API_KEY}` },
+    body: JSON.stringify({ model: MODEL, messages: [{ role: 'user', content: prompt }] }),
+  });
+  if (!res.ok) throw new Error(`Groq returned ${res.status}: ${await res.text()}`);
+  const data = await res.json();
+  return data.choices[0].message.content;
+}
+
+// Real, unbounded cost with no human deciding whether reply #47 was worth
+// it if this isn't here - see the landing page's own warning.
+const MAX_TURNS_PER_CONTACT = 8;
+const turnCounts = new Map();
+
+const agent = await OwliAgent.create();
+console.log(`Groq bridge running as ${agent.npub}`);
+
+agent.onMessage(async ({ from, text }) => {
+  const turns = (turnCounts.get(from) || 0) + 1;
+  turnCounts.set(from, turns);
+  if (turns > MAX_TURNS_PER_CONTACT) {
+    console.log(`[stopped] hit the ${MAX_TURNS_PER_CONTACT}-turn limit with ${from.slice(0, 8)}… - not replying further (this is a paid API)`);
+    return;
+  }
+  console.log(`[${turns}/${MAX_TURNS_PER_CONTACT}] ${from.slice(0, 8)}…: ${text}`);
+  const reply = await askMyModel(text);
+  await agent.send(from, reply);
+});
+
+await agent.start();
+console.log('listening - Ctrl+C to stop');

package/examples/lmstudio-bridge.mjs

@@ -0,0 +1,44 @@
+// Bridge to a local LM Studio model (https://lmstudio.ai) - load a model
+// and start its local server (Developer tab > Start Server) first, then
+// run this. LM Studio speaks the same OpenAI-compatible chat-completions
+// shape openai-compatible-bridge.mjs uses; this is its own file since
+// it's the local-model option most people reach for first, but see that
+// file if you're pointing at something else with the same API shape.
+import { OwliAgent } from '../src/index.js';
+
+const BASE_URL = process.env.LMSTUDIO_URL || 'http://localhost:1234/v1';
+const MODEL = process.env.LMSTUDIO_MODEL || 'local-model'; // LM Studio ignores this if only one model is loaded
+
+async function askMyModel(prompt) {
+  const res = await fetch(`${BASE_URL}/chat/completions`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ model: MODEL, messages: [{ role: 'user', content: prompt }] }),
+  });
+  if (!res.ok) throw new Error(`LM Studio returned ${res.status}: ${await res.text()}`);
+  const data = await res.json();
+  return data.choices[0].message.content;
+}
+
+// See ollama-bridge.mjs's comment on why this exists - same reasoning,
+// kept here too since this is a copy-paste starting point people adapt.
+const MAX_TURNS_PER_CONTACT = 12;
+const turnCounts = new Map();
+
+const agent = await OwliAgent.create();
+console.log(`LM Studio bridge running as ${agent.npub}`);
+
+agent.onMessage(async ({ from, text }) => {
+  const turns = (turnCounts.get(from) || 0) + 1;
+  turnCounts.set(from, turns);
+  if (turns > MAX_TURNS_PER_CONTACT) {
+    console.log(`[stopped] hit the ${MAX_TURNS_PER_CONTACT}-turn limit with ${from.slice(0, 8)}… - not replying further`);
+    return;
+  }
+  console.log(`[${turns}/${MAX_TURNS_PER_CONTACT}] ${from.slice(0, 8)}…: ${text}`);
+  const reply = await askMyModel(text);
+  await agent.send(from, reply);
+});
+
+await agent.start();
+console.log('listening - Ctrl+C to stop');

package/examples/mistral-bridge.mjs

@@ -0,0 +1,44 @@
+// Bridge to Mistral AI's real cloud API (https://mistral.ai) - their own
+// hosted models, OpenAI-compatible chat-completions shape. A paid,
+// metered API past its free tier, so the turn limit below isn't
+// optional. Set MISTRAL_API_KEY before running.
+import { OwliAgent } from '../src/index.js';
+
+const API_KEY = process.env.MISTRAL_API_KEY;
+const MODEL = process.env.MISTRAL_MODEL || 'mistral-large-latest';
+
+if (!API_KEY) throw new Error('Set MISTRAL_API_KEY before running this.');
+
+async function askMyModel(prompt) {
+  const res = await fetch('https://api.mistral.ai/v1/chat/completions', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', authorization: `Bearer ${API_KEY}` },
+    body: JSON.stringify({ model: MODEL, messages: [{ role: 'user', content: prompt }] }),
+  });
+  if (!res.ok) throw new Error(`Mistral returned ${res.status}: ${await res.text()}`);
+  const data = await res.json();
+  return data.choices[0].message.content;
+}
+
+// Real, unbounded cost with no human deciding whether reply #47 was worth
+// it if this isn't here - see the landing page's own warning.
+const MAX_TURNS_PER_CONTACT = 8;
+const turnCounts = new Map();
+
+const agent = await OwliAgent.create();
+console.log(`Mistral bridge running as ${agent.npub}`);
+
+agent.onMessage(async ({ from, text }) => {
+  const turns = (turnCounts.get(from) || 0) + 1;
+  turnCounts.set(from, turns);
+  if (turns > MAX_TURNS_PER_CONTACT) {
+    console.log(`[stopped] hit the ${MAX_TURNS_PER_CONTACT}-turn limit with ${from.slice(0, 8)}… - not replying further (this is a paid API)`);
+    return;
+  }
+  console.log(`[${turns}/${MAX_TURNS_PER_CONTACT}] ${from.slice(0, 8)}…: ${text}`);
+  const reply = await askMyModel(text);
+  await agent.send(from, reply);
+});
+
+await agent.start();
+console.log('listening - Ctrl+C to stop');

package/examples/ollama-bridge.mjs

@@ -0,0 +1,47 @@
+// Bridge to a local Ollama model (https://ollama.com) - run `ollama pull
+// llama3.2` (or whatever model you like) and `ollama serve` first, then
+// run this. Same Owli-facing shape as every other bridge here; only the
+// askMyModel() function differs per backend.
+import { OwliAgent } from '../src/index.js';
+
+const OLLAMA_URL = process.env.OLLAMA_URL || 'http://localhost:11434';
+const MODEL = process.env.OLLAMA_MODEL || 'llama3.2';
+
+async function askMyModel(prompt) {
+  const res = await fetch(`${OLLAMA_URL}/api/generate`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ model: MODEL, prompt, stream: false }),
+  });
+  if (!res.ok) throw new Error(`Ollama returned ${res.status}: ${await res.text()}`);
+  const data = await res.json();
+  return data.response;
+}
+
+// Hard turn limit, per contact - see the README/landing page's own
+// warning: nothing stops two model-backed agents replying to each other
+// forever, and if either side is a paid API that's real unbounded cost
+// with no human deciding whether reply #47 was worth it. This one's a
+// local model (free to run, no per-call cost), but the same cap is kept
+// here so this file is a safe template to copy into the paid backends
+// too, not just this one.
+const MAX_TURNS_PER_CONTACT = 12;
+const turnCounts = new Map();
+
+const agent = await OwliAgent.create();
+console.log(`Ollama bridge running as ${agent.npub}`);
+
+agent.onMessage(async ({ from, text }) => {
+  const turns = (turnCounts.get(from) || 0) + 1;
+  turnCounts.set(from, turns);
+  if (turns > MAX_TURNS_PER_CONTACT) {
+    console.log(`[stopped] hit the ${MAX_TURNS_PER_CONTACT}-turn limit with ${from.slice(0, 8)}… - not replying further`);
+    return;
+  }
+  console.log(`[${turns}/${MAX_TURNS_PER_CONTACT}] ${from.slice(0, 8)}…: ${text}`);
+  const reply = await askMyModel(text);
+  await agent.send(from, reply);
+});
+
+await agent.start();
+console.log('listening - Ctrl+C to stop');

package/examples/openai-bridge.mjs

@@ -0,0 +1,45 @@
+// Bridge to OpenAI's real cloud API - a paid, metered API, so the turn
+// limit below isn't optional here the way it might feel for a free local
+// model. Set OPENAI_API_KEY before running.
+import { OwliAgent } from '../src/index.js';
+
+const API_KEY = process.env.OPENAI_API_KEY;
+const MODEL = process.env.OPENAI_MODEL || 'gpt-4o-mini';
+
+if (!API_KEY) throw new Error('Set OPENAI_API_KEY before running this.');
+
+async function askMyModel(prompt) {
+  const res = await fetch('https://api.openai.com/v1/chat/completions', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', authorization: `Bearer ${API_KEY}` },
+    body: JSON.stringify({ model: MODEL, messages: [{ role: 'user', content: prompt }] }),
+  });
+  if (!res.ok) throw new Error(`OpenAI returned ${res.status}: ${await res.text()}`);
+  const data = await res.json();
+  return data.choices[0].message.content;
+}
+
+// Real, unbounded cost with no human deciding whether reply #47 was worth
+// it if this isn't here - see the landing page's own warning. Lower than
+// the local-model examples' limit on purpose, since every turn here is a
+// real charge.
+const MAX_TURNS_PER_CONTACT = 8;
+const turnCounts = new Map();
+
+const agent = await OwliAgent.create();
+console.log(`OpenAI bridge running as ${agent.npub}`);
+
+agent.onMessage(async ({ from, text }) => {
+  const turns = (turnCounts.get(from) || 0) + 1;
+  turnCounts.set(from, turns);
+  if (turns > MAX_TURNS_PER_CONTACT) {
+    console.log(`[stopped] hit the ${MAX_TURNS_PER_CONTACT}-turn limit with ${from.slice(0, 8)}… - not replying further (this is a paid API)`);
+    return;
+  }
+  console.log(`[${turns}/${MAX_TURNS_PER_CONTACT}] ${from.slice(0, 8)}…: ${text}`);
+  const reply = await askMyModel(text);
+  await agent.send(from, reply);
+});
+
+await agent.start();
+console.log('listening - Ctrl+C to stop');

package/examples/openai-compatible-bridge.mjs

@@ -0,0 +1,56 @@
+// Generic bridge for anything that speaks the OpenAI chat-completions API
+// shape - which is most of the ecosystem at this point, not just OpenAI
+// itself. Real services this same script covers, just by changing
+// BASE_URL/API_KEY/MODEL: Groq, Together AI, OpenRouter, Mistral AI's own
+// API, Perplexity, Fireworks, DeepInfra, Azure OpenAI (with its own URL
+// shape), and self-hosted servers like vLLM, llama.cpp's server, and
+// text-generation-webui. If your provider isn't LM Studio, Ollama,
+// OpenAI, Claude, or Gemini specifically (each has its own file here),
+// it's almost certainly this one.
+import { OwliAgent } from '../src/index.js';
+
+const BASE_URL = process.env.OPENAI_COMPATIBLE_BASE_URL; // e.g. https://api.groq.com/openai/v1
+const API_KEY = process.env.OPENAI_COMPATIBLE_API_KEY;
+const MODEL = process.env.OPENAI_COMPATIBLE_MODEL;
+
+if (!BASE_URL || !MODEL) {
+  throw new Error('Set OPENAI_COMPATIBLE_BASE_URL and OPENAI_COMPATIBLE_MODEL (and OPENAI_COMPATIBLE_API_KEY if your provider needs one).');
+}
+
+async function askMyModel(prompt) {
+  const res = await fetch(`${BASE_URL.replace(/\/+$/, '')}/chat/completions`, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      ...(API_KEY ? { authorization: `Bearer ${API_KEY}` } : {}),
+    },
+    body: JSON.stringify({ model: MODEL, messages: [{ role: 'user', content: prompt }] }),
+  });
+  if (!res.ok) throw new Error(`${BASE_URL} returned ${res.status}: ${await res.text()}`);
+  const data = await res.json();
+  return data.choices[0].message.content;
+}
+
+// See ollama-bridge.mjs's comment on why this exists - doubly worth
+// keeping here, since a misconfigured BASE_URL/MODEL pointed at a real
+// paid API is exactly the case this guards against.
+const MAX_TURNS_PER_CONTACT = 12;
+const turnCounts = new Map();
+
+const agent = await OwliAgent.create();
+console.log(`OpenAI-compatible bridge (${BASE_URL}) running as ${agent.npub}`);
+
+agent.onMessage(async ({ from, text }) => {
+  const turns = (turnCounts.get(from) || 0) + 1;
+  turnCounts.set(from, turns);
+  if (turns > MAX_TURNS_PER_CONTACT) {
+    console.log(`[stopped] hit the ${MAX_TURNS_PER_CONTACT}-turn limit with ${from.slice(0, 8)}… - not replying further`);
+    return;
+  }
+  console.log(`[${turns}/${MAX_TURNS_PER_CONTACT}] ${from.slice(0, 8)}…: ${text}`);
+  const reply = await askMyModel(text);
+  await agent.send(from, reply);
+});
+
+await agent.start();
+console.log('listening - Ctrl+C to stop');

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@owli/agent-sdk",
+  "version": "0.1.0",
+  "description": "Headless Node.js SDK for giving an AI agent its own private, forward-secret Nostr identity - no signup, no browser. Phase 1 of the ai.owli.chat initiative.",
+  "keywords": [
+    "nostr",
+    "ai-agent",
+    "forward-secrecy",
+    "double-ratchet",
+    "e2ee",
+    "decentralized-identity"
+  ],
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "author": "owli.chat",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test 'test/*.test.js'"
+  },
+  "dependencies": {
+    "nostr-tools": "^2.24.1",
+    "nostr-double-ratchet": "^0.0.138",
+    "@scure/bip39": "^2.3.0",
+    "@noble/hashes": "^1.3.1",
+    "ws": "^8.18.0"
+  },
+  "license": "MIT"
+}