@molecule/api-paracrine

Core interface · paracrine · API (Node) · v1.1.0 · Apache-2.0

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

npm install @molecule/api-paracrine

npm · Source on GitHub

How it works

@molecule/api-paracrine is the paracrine core interface on the API (Node) side: the API your app calls, with no vendor inside.

Choose the implementation by bonding one of its 1 provider: @molecule/api-paracrine-file.

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

Providers (1): @molecule/api-paracrine-file

Works with: @molecule/api-bond

Reference

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 `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 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 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 (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

ProviderPackage
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 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".