@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[];
/** THE principal inbox: the one box of a scope that the organization's delivery gate
 *  appends cross-principal letters into (`append(recipientScope, PRINCIPAL_INBOX_HANDLE, record)`), the
 *  `principal.` member of the reserved family above — so no spawn or session name can ever spell it. The
 *  only spelling: every writer and reader imports this constant. */
export declare const PRINCIPAL_INBOX_HANDLE = "principal.inbox";
/** The names that already address a fixed party — CC 2.1.296 `fD` (cli296.js:238093) reads `main`
 *  (`Og`: the conversation that spawned the run), `team-lead` (`ca`), `user` (`mxe`) and `system`
 *  (`adt`) off the NORMALIZED key, so every spelling that normalizes to one of them is the name.
 *  The frames a run speaks (`from`, `teammate_id`, a stop attribution) already carry these four
 *  words as parties; a spawn named one of them would speak as that party. */
export declare const RESERVED_AGENT_NAMES: 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, the `*` broadcast
 * token, one of the {@link RESERVED_AGENT_NAMES} (`reserved_name`) or the shape of an agent id
 * (`agent_id_shape`). 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 spawn face (the Agent tool's `name`) refuses on every reason this returns.
 *
 * 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" | "reserved_name" | "agent_id_shape" | undefined;