npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@molecule/api-paracrine

v1.1.0

Published

Paracrine core interface — messages between the AI agents sharing one machine: send, receive, ack, reads, purge over a bonded store.

Readme

@molecule/api-paracrine

Paracrine core interface — messages between the AI agents on one machine.

In biology, PARACRINE signaling is how nearby cells communicate — a cell secretes a signal its neighbors read, with no central wire and no distance to cross. This package is that, for AI agents: Claude Code, Codex, ZCode, the IDE's executor and any other harness sharing one machine (or one checkout) exchange messages through one bonded store, each in its own process, with no harness-specific channel.

The contract is a mailbox, deliberately NOT a queue and NOT an RPC:

  • send places a message for one agent (to: 'agent-id') or for every agent (to: PARACRINE_BROADCAST).
  • receive reports a mailbox non-destructively — addressed messages plus broadcasts, narrowed by time, subject prefix or read state. An agent that never checks still loses nothing that a re-check cannot find.
  • ack records that the recipient has READ a message, and reads lets the sender learn that ("did the benchmark session see my question?"). A receipt is the only side effect reading has.
  • purge is retention with the policy left to the caller.

Every open coordination channel a workspace improvises today — deploy-ledger notes, who-owns lookups, "ask the other session to fix its file" — is one of those four operations on a message neither improvisation natively supports: a QUESTION with a RECEIPT.

Interface only. One store bonds as the singleton of the paracrine category: a machine has one mailbox tree.

Bonds:

  • @molecule/api-paracrine-file — the zero-config local store: one directory of message files (default ~/.agents/paracrine), readable by any process, with a paracrine CLI so a harness with no bond support at all can still send and receive.

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

import { setProvider } from '@molecule/api-paracrine'
import { createProvider } from '@molecule/api-paracrine-file'

setProvider(createProvider()) // ~/.agents/paracrine, created on first use
// A question with a receipt the sender can check:
//   await requireProvider().send({ from: 'codex-42', to: 'bench-1', body: '…' })
//   await requireProvider().receive({ for: 'bench-1', unreadOnly: true })

Type

core

Installation

npm install @molecule/api-paracrine @molecule/api-bond

API

Interfaces

ParacrineMessage

One message between agents.

interface ParacrineMessage {
  /** The store's identity for this message, unique within the store. */
  id: string
  /** Who sent it. */
  from: ParacrineAgentId
  /** Who it is for — one agent id, or {@link PARACRINE_BROADCAST}. */
  to: ParacrineAgentId | typeof PARACRINE_BROADCAST
  /** A short line for listings; the body is the message. */
  subject?: string
  /** The message body. */
  body: string
  /**
   * When the store accepted it, ISO 8601 UTC (`date -u` at send time — never
   * an estimate of elapsed time).
   */
  sentAt: string
  /** Replies carry the id of the message they answer, so a question and its answer thread. */
  threadId?: string
}

ParacrineSendInput

What a caller hands the store to send. The store mints id and sentAt.

interface ParacrineSendInput {
  from: ParacrineAgentId
  to: ParacrineAgentId | typeof PARACRINE_BROADCAST
  subject?: string
  body: string
  threadId?: string
}

ParacrineQuery

How one agent narrows what it receives.

interface ParacrineQuery {
  /** The mailbox to read. */
  for: ParacrineAgentId
  /** Only messages sent at or after this instant, ISO 8601. */
  since?: string
  /** Only messages no read-receipt from `for` exists for. Default `false`. */
  unreadOnly?: boolean
  /** Only messages whose subject starts with this prefix (case-sensitive). */
  subjectPrefix?: string
}

ParacrineRead

One agent's read receipt for one message.

interface ParacrineRead {
  messageId: string
  by: ParacrineAgentId
  /** When the receipt was recorded, ISO 8601 UTC. */
  at: string
}

ParacrinePurgeOptions

What a store may purge, and what it must never touch.

interface ParacrinePurgeOptions {
  /** Purge only messages sent strictly before this instant, ISO 8601. */
  before: string
  /**
   * Purge receipts too. Default `false`: a receipt is a fact about work done,
   * and losing it re-surfaces an answered message as unread.
   */
  includeReceipts?: boolean
}

ParacrineProvider

The paracrine store — the one contract every provider implements.

Delivery is NEVER destructive: receive reports, ack records that the recipient has seen a message, and what happens after an ack (delete, archive, nothing) is the recipient's policy, not the store's. A message that reached nobody is still a fact the sender can check through {@link ParacrineProvider.reads}.

interface ParacrineProvider {
  readonly name: string

  /** Place one message in its recipient's mailbox (or the broadcast stream). */
  send(input: ParacrineSendInput): Promise<ParacrineMessage>
  /**
   * Report the messages `for` may read: addressed to it, plus broadcasts.
   * Ordered by `sentAt`, then id. Never consumes anything.
   *
   * @throws {Error} When the mailbox cannot be read — an empty list is
   *   "looked, found none", never "could not look".
   */
  receive(query: ParacrineQuery): Promise<ParacrineMessage[]>
  /** Record that `by` has read one message. Idempotent. */
  ack(messageId: string, by: ParacrineAgentId): Promise<void>
  /** Every read receipt for one message — how a sender learns it was seen. */
  reads(messageId: string): Promise<ParacrineRead[]>
  /**
   * Remove messages older than a bound. Retention policy belongs to the
   * caller; only the mechanism is here.
   */
  purge(options: ParacrinePurgeOptions): Promise<number>
}

Types

ParacrineAgentId

An agent's identity on the machine — opaque to the store.

Whatever the caller considers stable enough to route by: a presence registry session id, harness:pid, a project slug. A store MUST treat it as an untrusted string (see {@link PARACRINE_AGENT_ID}) and never as a filesystem path.

type ParacrineAgentId = string

Functions

setProvider(provider)

Register the machine's paracrine store.

function setProvider(provider: ParacrineProvider): void
  • provider — The store.

getProvider()

The bonded paracrine store, or null.

function getProvider(): ParacrineProvider | null

Returns: The store, or null when none is bonded.

hasProvider()

Whether a paracrine store is bonded.

function hasProvider(): boolean

Returns: true when one is.

requireProvider()

The bonded paracrine store.

function requireProvider(): ParacrineProvider

Returns: The store.

isParacrineAgentId(value)

Whether a value is a safe agent id ({@link PARACRINE_AGENT_ID}).

function isParacrineAgentId(value: unknown): value is ParacrineAgentId

Constants

PARACRINE_BOND_TYPE

The bond category paracrine stores are registered under.

const PARACRINE_BOND_TYPE: 'paracrine'

PARACRINE_BROADCAST

The recipient address meaning "every agent that checks".

const PARACRINE_BROADCAST: '*'

PARACRINE_AGENT_ID

The shape an agent id must have before a file-backed store may use it.

One flat character class, no separators, no percent-encoding, no whitespace: anything with path structure (/, .., ?) or escape sequences could retarget a filesystem path when interpolated, so such ids are refused outright rather than sanitized — a normalized id is an identity the caller did not name.

const PARACRINE_AGENT_ID: RegExp

Available Providers

| Provider | Package | | -------------- | ------------------------------ | | Paracrine File | @molecule/api-paracrine-file |

Injection Notes

Requirements

Peer dependencies:

  • @molecule/api-bond ^1.0.1

Runtime Dependencies

  • @molecule/api-bond

Agent ids are data, never paths. A store treats every id as an untrusted string and must refuse (not sanitize) anything outside {@link PARACRINE_AGENT_ID} — a normalized id is an identity the caller did not name.

Delivery never destroys. There is no pop, no ack-and-delete, no at-most-once: two harnesses may read the same broadcast, and a receipt says "seen", not "gone".