@sema-agent/core/dist/agents/cross-session-ref.d.ts

Stateless, task-oriented AI agent core

/** CC `aa` / `bmn`: a ref is 6..12 hex characters — the shortest prefix of `sha256(kind:id)` that is
 *  unique against its sorted neighbours in the LISTING that minted it. */
export declare const PEER_REF_MIN = 6;
export declare const PEER_REF_MAX = 12;
/** CC `Mz`. */
export declare const PEER_REF_RE: RegExp;
export interface PeerRefEntry {
    /** The identity kind (`session`, `agent`, …): part of the hash input so two kinds with the same id
     *  never share a ref. */
    kind: string;
    /** The durable id (a `session.<id>` box handle, an a* agent handle, …). */
    id: string;
}
/**
 * CC `K8` transcribed on sha256: mint the ref of EVERY entry of one listing. Refs are minted by the
 * listing side and are valid only against that listing (a ref the model did not just read from a
 * listing or a disambiguation error will not resolve). The optional `self` entry joins the
 * disambiguation set (so no ref collides with the caller's own identity) but is not returned.
 * The hash choice is local to this engine: a ref never crosses a process boundary, so the value
 * domain (`[0-9a-f]{6,12}`) is what interoperates, not the digest.
 */
export declare function mintPeerRef<T extends PeerRefEntry>(entries: readonly T[], self?: PeerRefEntry): Array<T & {
    ref: string;
}>;
/** CC `qN` — the display token. */
export declare function formatPeerNameRef(name: string, ref: string): string;
/** CC `V8`/`DO` — split a `name [ref]` token; `undefined` when no ref suffix is present. */
export declare function parsePeerNameRef(text: string): {
    name: string;
    ref: string;
} | undefined;
/**
 * CC `dr` — the MATCHING key of a peer/session name: NFKC → strip control/format code points → trim →
 * lower-case → collapse whitespace runs to `-`. Every terminal resolves and compares names on this
 * key (a display name is never the key).
 */
export declare function normalizePeerName(name: string): string;
/** The box-address prefixes of design/385 (`session.<id>` per-session box, `principal.<…>` the
 *  cross-principal inbox family). Reserved: a NAME may never spell an address. */
export declare const PEER_ADDRESS_PREFIXES: readonly string[];
/**
 * design/385 §2.2 namespace protection (CC `qd` in spirit): a candidate spawn/session name is refused
 * when its normalized key would shadow an explicit address — a reserved box prefix, a transport
 * scheme (`uds:` / `bridge:` / `did:`), a socket path, an `@`-bearing team form, or the `*`
 * broadcast token. Returns the reason, or `undefined` when the name is admissible. Registration-side
 * check (loud refusal at write time); the resolution ladder ranks explicit addresses first regardless.
 *
 * The socket-path arm is judged on the RAW name AND on its normalized key (CC `QHe` runs its
 * classifier over both): a name that is a socket path in either spelling is refused, since the
 * resolution ladder would read the raw spelling as an address.
 */
export declare function reservedPeerNameReason(name: string): "empty" | "address_prefix" | "transport_scheme" | "socket_path" | "at_sign" | "wildcard" | undefined;