@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.
Maintainers
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:
sendplaces a message for one agent (to: 'agent-id') or for every agent (to: PARACRINE_BROADCAST).receivereports 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.ackrecords that the recipient has READ a message, andreadslets the sender learn that ("did the benchmark session see my question?"). A receipt is the only side effect reading has.purgeis 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 aparacrineCLI 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.tsJSDoc, 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-bondAPI
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 = stringFunctions
setProvider(provider)
Register the machine's paracrine store.
function setProvider(provider: ParacrineProvider): voidprovider— The store.
getProvider()
The bonded paracrine store, or null.
function getProvider(): ParacrineProvider | nullReturns: The store, or null when none is bonded.
hasProvider()
Whether a paracrine store is bonded.
function hasProvider(): booleanReturns: true when one is.
requireProvider()
The bonded paracrine store.
function requireProvider(): ParacrineProviderReturns: The store.
isParacrineAgentId(value)
Whether a value is a safe agent id ({@link PARACRINE_AGENT_ID}).
function isParacrineAgentId(value: unknown): value is ParacrineAgentIdConstants
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: RegExpAvailable 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".
