trellis/dist/cli/presence.d.ts

Agentic State Engine — event-sourced causal graph with branching, decision traces, and realtime sync for AI-native applications

/**
 * Ambient presence ledger (TRL — Layer 1 of agent stigmergy).
 *
 * Each agent session writes a heartbeat to `.trellis/presence/<sessionId>.json`.
 * `trellis who` reads all non-stale heartbeats to give ambient awareness of
 * who else is working in the repo right now — no server, no relay. This is
 * pure stigmergy: presence is discovered through the shared repo environment.
 *
 * Presence lives OUTSIDE the causal op log on purpose: liveness is ephemeral
 * and must not pollute milestones, the garden, or sync. It rides beside the
 * repo, not in it.
 */
/** A single agent's live presence record. */
export interface PresenceInfo {
    /** Stable per-session key: TRELLIS_SESSION_ID || TRELLIS_LANE_ID || generated. */
    sessionId: string;
    /** Agent identity entity id (identity:<did>). */
    agentId: string;
    /** Human-readable name from local identity. */
    displayName: string;
    /** Client/provider: opencode | claude | gemini | codex | unknown. */
    client: string;
    /** Lane this session is working in, if any. */
    laneId?: string;
    /** Current branch name, if known. */
    branch?: string;
    /** Issue this session has claimed, if any. */
    claimedIssueId?: string;
    /** Title of the claimed issue, for quick scan. */
    claimedIssueTitle?: string;
    /** Self-reported liveness. */
    status: 'active' | 'idle' | 'away';
    /** ISO timestamp this session first announced. */
    startedAt: string;
    /** ISO timestamp of the last heartbeat (drives staleness pruning). */
    lastHeartbeat: string;
}
/** Heartbeats older than this are considered offline. */
export declare const DEFAULT_STALE_MS: number;
export declare function presenceDir(rootPath: string): string;
export declare function writeHeartbeat(rootPath: string, info: PresenceInfo): void;
export declare function clearHeartbeat(rootPath: string, sessionId: string): void;
export interface ReadPresenceOpts {
    /** Override the staleness window (ms). */
    staleMs?: number;
    /** Include the calling session's own record (default: false). */
    includeSelf?: boolean;
    /** The calling session's id, used to exclude self unless includeSelf. */
    selfSessionId?: string;
}
/** Read all non-stale presence records, newest heartbeat first. */
export declare function readPresence(rootPath: string, opts?: ReadPresenceOpts): PresenceInfo[];
/** Stable session key for this process: session id, else lane id, else ephemeral uuid. */
export declare function resolveSessionId(): string;
//# sourceMappingURL=presence.d.ts.map