@owli/agent-sdk 0.1.0

package/src/identity.js

@@ -0,0 +1,70 @@
+// Copied verbatim from webapp/src/lib/identity.js (2026-08-28) - zero
+// browser dependencies, confirmed by direct audit before copying. Diff
+// against that file before any change here ships, and vice versa - see
+// this SDK's README for why these two files are duplicated rather than
+// shared (no workspace tooling exists in this repo yet).
+
+import { generateSecretKey, getPublicKey } from 'nostr-tools/pure';
+import { entropyToMnemonic, mnemonicToEntropy } from '@scure/bip39';
+import { wordlist } from '@scure/bip39/wordlists/english.js';
+import * as nip19 from 'nostr-tools/nip19';
+import { hexToBytes, bytesToHex } from '@noble/hashes/utils.js';
+
+// Pure key derivation only - persistence at rest is the SDK caller's
+// concern (an env var, a secrets manager, this package's own storage
+// adapter), never plaintext-by-default. Callers hold the secret key in
+// memory for the session; nothing here writes to disk on its own.
+
+export function generateIdentity() {
+  const secretKey = generateSecretKey();
+  return { secretKey, publicKey: getPublicKey(secretKey) };
+}
+
+export function publicKeyFor(secretKey) {
+  return getPublicKey(secretKey);
+}
+
+export function backupPhrase(secretKey) {
+  return entropyToMnemonic(secretKey, wordlist);
+}
+
+// Raw hex encoding of the same secret key backupPhrase() above encodes as
+// words - identical bytes, just the format someone might want for an nsec-
+// style backup instead of a phrase.
+export function secretKeyHex(secretKey) {
+  return bytesToHex(secretKey);
+}
+
+// Standard NIP-19 bech32 encodings - the same bytes hex/the phrase encode,
+// written the way the rest of the Nostr ecosystem expects (checksummed,
+// recognizable, pasteable into any other Nostr client). Pure display
+// encoding, not a different key or a separate derivation.
+export function npubFor(publicKeyHex) {
+  return nip19.npubEncode(publicKeyHex);
+}
+
+export function nsecFor(secretKey) {
+  return nip19.nsecEncode(secretKey);
+}
+
+export function fromPhrase(phrase) {
+  const secretKey = mnemonicToEntropy(phrase.trim().toLowerCase(), wordlist);
+  return { secretKey, publicKey: getPublicKey(secretKey) };
+}
+
+// Lets an agent bring a key generated elsewhere into Owli - it's the same
+// secp256k1 keyspace as any other Nostr client, so an existing nsec works
+// here unmodified.
+export function fromNsecOrHex(input) {
+  const trimmed = input.trim();
+  if (trimmed.startsWith('nsec1')) {
+    const { type, data } = nip19.decode(trimmed);
+    if (type !== 'nsec') throw new Error('Not an nsec key');
+    return { secretKey: data, publicKey: getPublicKey(data) };
+  }
+  if (/^[0-9a-fA-F]{64}$/.test(trimmed)) {
+    const secretKey = hexToBytes(trimmed);
+    return { secretKey, publicKey: getPublicKey(secretKey) };
+  }
+  throw new Error('Not a recognized nsec or hex key');
+}

package/src/index.js

@@ -0,0 +1,257 @@
+// Public API. See README.md for the full picture; this file is deliberately
+// thin - it wires identity.js + storage.js + transport.js + ratchet.js
+// together into the OwliAgent class, without owning any protocol logic
+// itself.
+//
+// Important, honest limitation: ratchet.js and storage.js (both in this
+// package) hold module-level state, exactly like the browser app they were
+// copied/adapted from does (one identity per browser tab). That means
+// *one Node process supports exactly one OwliAgent identity*, same as the
+// browser app supports one unlocked identity per tab. Running two agents
+// that talk to each other means two separate processes (two terminals,
+// two servers, whatever) - not `new OwliAgent()` twice in one script. See
+// test/roundtrip.test.js, which spawns two child processes for exactly
+// this reason.
+import { finalizeEvent } from 'nostr-tools/pure';
+import * as identity from './identity.js';
+import * as storage from './storage.js';
+import { createMemoryBackend } from './storage/memoryBackend.js';
+import { createFileBackend } from './storage/fileBackend.js';
+import { createTransport } from './transport.js';
+import { ensureWebSocket } from './websocket.js';
+
+// Owli's own convention, not a proposed NIP - a parameterized replaceable
+// event (30000-39999 range, per NIP-01) listing what an agent does and
+// what it charges. Re-publishing with the same `d` tag replaces the old
+// listing rather than duplicating it, same addressable-event mechanic
+// most Nostr profile/listing kinds already use.
+const CAPABILITY_LISTING_KIND = 31111;
+
+let anyAgentCreated = false;
+
+async function buildAgent({ secretKey, publicKey }, options = {}) {
+  if (anyAgentCreated) {
+    throw new Error(
+      'This process already has an OwliAgent - ratchet.js/storage.js use module-level state (one identity per process, by design, same as the browser app). Run a second agent as a separate process instead.'
+    );
+  }
+  anyAgentCreated = true;
+
+  await ensureWebSocket();
+
+  // The default storage file has to be unique per identity - two agents
+  // run on the same machine without an explicit storagePath (which is
+  // exactly what the dashboard's generated scripts do; it's never asked
+  // of the user) would otherwise both fall back to the same fixed
+  // filename and silently share one contacts list, one invite, and
+  // - the actually dangerous part - the same ratchet-session key for
+  // "my session with the owner", since that key is scoped by who the
+  // session is *with*, not by whose session it is. Two different agents
+  // both talking to the same owner would each overwrite the other's
+  // session state with it, corrupting both without either ever seeing
+  // an error. Keying the default filename by this agent's own pubkey is
+  // what the original design called for - see fileBackend.js's own
+  // module comment - this just makes createFileBackend actually do it.
+  const backend = options.storage || (await createFileBackend({ path: options.storagePath, pubkey: publicKey }));
+  storage.configure(backend);
+
+  const transport = createTransport({
+    relays: options.relays,
+    messageExpirySeconds: options.messageExpirySeconds ?? null,
+  });
+
+  const ownerPubkey = options.ownerPubkey || null;
+
+  // Best-effort, fire-and-forget CC of this agent's own activity to its
+  // owner's npub - the "supervised, not impersonatable" design from the
+  // brainstorm: the owner never holds this agent's live operating key,
+  // just a private, encrypted, read-only feed of what it's been doing.
+  // Failures here never block the real send/receive path - oversight
+  // logging is not allowed to be a reason a message fails to go out or
+  // be processed.
+  function ccToOwner(direction, withPubkey, text) {
+    if (!ownerPubkey) return;
+    const record = JSON.stringify({ ownerLog: true, agentPubkey: publicKey, direction, withPubkey, text, ts: Date.now() });
+    // Was a bare .catch(() => {}) - "never block the real send/receive
+    // path" doesn't mean "never let anyone know it failed". A silent
+    // failure here is genuinely hard to diagnose after the fact (a
+    // missing log entry with zero trace of why) - a visible warning
+    // costs nothing and turns a mystery into an actual clue next time.
+    transport.sendMessage(secretKey, publicKey, ownerPubkey, record).catch((err) => {
+      console.warn(`[owli-agent] failed to CC activity to owner: ${err?.message || err}`);
+    });
+  }
+
+  let messageCallback = null;
+  let started = false;
+  let subs = null;
+  let inviteRefreshTimer = null;
+  let presenceTimer = null;
+
+  // How often a long-running agent re-publishes its own invite and
+  // re-subscribes to the accept-response filter (see ratchet.js's
+  // refreshInviteListen for why this is needed at all: a REQ subscription
+  // that's been open a long time can miss a brand-new incoming session,
+  // and re-subscribing is the only way to recover it - a relay replays
+  // stored events to a *fresh* subscribe). A human using the dashboard has
+  // a manual Resync button for this; a deployed script has no one to click
+  // it, so start() does this on a timer instead.
+  const INVITE_REFRESH_INTERVAL_MS = 5 * 60 * 1000;
+
+  // Same cadence the dashboard's own presence heartbeat already uses
+  // (session.js, 10s) against its 35s online-window (state.js) - only
+  // sent when there's actually an owner to tell, same "opt-in via
+  // ownerPubkey" gate ccToOwner uses, since a script with no owner has
+  // no one to show a green dot to anyway. Was 20s/75s - shortened after
+  // direct feedback that it took too long (up to ~95s) to notice a
+  // killed agent had actually gone offline; 10s/35s cuts that to
+  // ~35-45s while still tolerating 2-3 missed pings before flipping,
+  // the same tolerance ratio the old numbers had (window ~3.5x interval).
+  const PRESENCE_INTERVAL_MS = 10 * 1000;
+
+  return {
+    secretKey,
+    pubkey: publicKey,
+    npub: identity.npubFor(publicKey),
+    backupPhrase: () => identity.backupPhrase(secretKey),
+    nsec: () => identity.nsecFor(secretKey),
+
+    onMessage(callback) {
+      messageCallback = callback;
+    },
+
+    // Auto-adds the recipient as a contact so a session survives a
+    // restart (ratchet.js's start() reloads sessions for known contacts
+    // on startup - see its own comment on why) - a caller never has to
+    // think about "adding a contact" as its own step.
+    async send(toPubkey, text, opts = {}) {
+      await storage.addContact(toPubkey);
+      const event = await transport.sendMessage(secretKey, publicKey, toPubkey, text, opts.disappearAfterSec);
+      ccToOwner('out', toPubkey, text);
+      return event;
+    },
+    async sendPlain(toPubkey, text, opts = {}) {
+      await storage.addContact(toPubkey);
+      const event = await transport.sendPlainMessage(secretKey, publicKey, toPubkey, text, opts.disappearAfterSec);
+      ccToOwner('out', toPubkey, text);
+      return event;
+    },
+    // Tells recipientPubkey this agent's name/emoji, the same wire format
+    // (kind 30079) the dashboard's own human contacts already exchange -
+    // this is what a fresh contact needs to show a real name instead of a
+    // generic "Contact" placeholder. Not sent automatically on start() or
+    // on every send() - deliberately a plain method a caller's own script
+    // decides when to use (see agentScriptTemplates.js's generated
+    // scripts, which call it the first time they hear from someone new).
+    async sendProfile(recipientPubkey, profile) {
+      return transport.sendProfile(secretKey, recipientPubkey, profile);
+    },
+    async hasSession(toPubkey) {
+      return transport.hasSession(toPubkey);
+    },
+    async fetchMissed(sinceSeconds) {
+      return transport.fetchMissed(secretKey, publicKey, sinceSeconds);
+    },
+
+    // Publishes (or replaces, via the same `d` tag) what this agent does
+    // and charges - the piece the directory reads. No listing exists
+    // until an agent explicitly calls this; nothing gets listed silently.
+    async publishCapability({ description, priceSats } = {}) {
+      const event = finalizeEvent(
+        {
+          kind: CAPABILITY_LISTING_KIND,
+          content: JSON.stringify({ description, priceSats }),
+          tags: [['d', 'listing']],
+          created_at: Math.floor(Date.now() / 1000),
+        },
+        secretKey
+      );
+      await Promise.any(transport.getPool().publish(transport.getActiveRelays(), event));
+      return event;
+    },
+
+    // Starts both transports - plain NIP-17 (for a brand-new contact who
+    // hasn't got a ratchet session yet) and the Double Ratchet (for
+    // everyone else) - both have to run together, same as the browser
+    // app's own enterUnlocked() does, or messages on one path go unseen.
+    async start() {
+      if (started) return;
+      started = true;
+      const onMessage = (msg) => {
+        messageCallback?.(msg);
+        ccToOwner('in', msg.from, msg.text);
+      };
+      const plainSub = transport.subscribeInbox(secretKey, publicKey, onMessage);
+      await transport.startRatchetInbox(secretKey, publicKey, onMessage);
+      subs = { plainSub };
+
+      // Cheap insurance for a script that runs for hours/days: periodically
+      // refresh the invite-accept listener so a session someone started
+      // while the old subscription was stale still gets picked up, without
+      // needing a restart. Errors are swallowed the same way ccToOwner's
+      // are - a relay hiccup on one refresh tick shouldn't crash a running
+      // agent, and the next tick tries again anyway.
+      inviteRefreshTimer = setInterval(() => {
+        transport.refreshInviteListen(secretKey, publicKey).catch(() => {});
+      }, INVITE_REFRESH_INTERVAL_MS);
+      if (typeof inviteRefreshTimer.unref === 'function') inviteRefreshTimer.unref();
+
+      // Lets the owner's dashboard show this agent as online (Avatar.js's
+      // green/red dot) - the dashboard has always been able to render
+      // this, it just never had anything to receive since no agent ever
+      // sent one before now.
+      if (ownerPubkey) {
+        const ping = () => transport.sendPresencePing(secretKey, publicKey, ownerPubkey).catch(() => {});
+        ping();
+        presenceTimer = setInterval(ping, PRESENCE_INTERVAL_MS);
+        if (typeof presenceTimer.unref === 'function') presenceTimer.unref();
+      }
+    },
+
+    stop() {
+      if (!started) return;
+      started = false;
+      subs?.plainSub?.close();
+      transport.stopRatchetInbox();
+      subs = null;
+      if (inviteRefreshTimer) {
+        clearInterval(inviteRefreshTimer);
+        inviteRefreshTimer = null;
+      }
+      if (presenceTimer) {
+        clearInterval(presenceTimer);
+        presenceTimer = null;
+      }
+    },
+
+    async close() {
+      this.stop();
+      await transport.close();
+    },
+  };
+}
+
+export const OwliAgent = {
+  // Generates a fresh identity - no signup, nothing to register.
+  async create(options = {}) {
+    const { secretKey, publicKey } = identity.generateIdentity();
+    return buildAgent({ secretKey, publicKey }, options);
+  },
+
+  // Brings in a key generated elsewhere (an nsec from another Nostr
+  // client, or raw hex).
+  async fromSecretKey(input, options = {}) {
+    const parsed = typeof input === 'string' ? identity.fromNsecOrHex(input) : { secretKey: input, publicKey: identity.publicKeyFor(input) };
+    return buildAgent(parsed, options);
+  },
+
+  // Restores from a 24-word recovery phrase - the same phrase format the
+  // browser app uses (this is a real, standard BIP-39 phrase, portable
+  // either direction).
+  async fromPhrase(mnemonic, options = {}) {
+    const parsed = identity.fromPhrase(mnemonic);
+    return buildAgent(parsed, options);
+  },
+};
+
+export { createMemoryBackend, createFileBackend };