@haywoodmarx/agent-pager 0.1.0

package/dist/src/index.d.ts

@@ -0,0 +1,27 @@
+export { Broker, type AgentImplementation, type AttachmentChannel, type BrokerCommit, type BrokerCommitListener, type BrokerFetchRequest, type BrokerOperationalEvent, type BrokerOptions, type ClaimedMessage, type ClaimSource, type NotificationOutcome, type ResumeSessionRequest, } from "./broker/broker.js";
+export { type AgentLifecycleState, type LifecycleTone } from "./broker/schema.js";
+export { ProtocolError, assertAgentId, assertProtocolVersion, decodeMessageBody, encodeMessageBody, hasControlCharacter, isAgentId, isDirectAgentAddress, isImplementationId, isOpaqueId, isSessionKey, issueOpaqueToken, lifecycleEventState, mintAgentId, normalizeMessageSubject, normalizeMessageType, validateImplementationId, validateSessionKey, AGENT_ID_SCHEME, FETCH_LIMIT_DEFAULT, FETCH_LIMIT_MAX, IMPLEMENTATION_ID_MAX_LENGTH, IMPLEMENTATION_ID_PATTERN, MESSAGE_BODY_LIMIT_BYTES, MESSAGE_SUBJECT_LIMIT_CHARACTERS, MESSAGE_TYPE_LIMIT_CHARACTERS, PROTOCOL_VERSION, REGISTRATION_SESSION_NAME_MAX_LENGTH, SESSION_IDENTIFIER_PATTERN, SESSION_KEY_MAX_LENGTH, type AgentId, type LifecycleEventType, type MessageState, } from "./broker/protocol.js";
+export { publicEpoch, startSnapshotServer, type BrokerSnapshot, type SnapshotAgent, type SnapshotDelivery, type SnapshotDiagnostics, type SnapshotHealth, type SnapshotLifecycleEntry, type SnapshotServerHandle, type SnapshotWorkspace, } from "./broker/snapshot.js";
+export { parseAgentAddress, workspaceTeamId } from "./broker/address.js";
+export type { HostPushNotificationCapability, HostRegistrationCommand, HostRegistrationImplementationCapability, HostWake, ImplementationCapabilityName, ImplementationDescriptor, ImplementationId, ImplementationLaunchPlan, ImplementationLaunchRequest, ImplementationProvider, KnownValue, LaunchImplementationCapability, NotificationImplementationCapability, SessionIdentityImplementationCapability, SessionIdentityInput, UnsupportedImplementationCapability, } from "./implementations/model.js";
+export { ImplementationRegistry, assertImplementationProvider, discoverImplementationRegistry, implementationId, type ImplementationDiscoveryPort, } from "./implementations/registry.js";
+export { harnessSessionKey } from "./implementations/session-key.js";
+export { createImplementationRegistry } from "./launch/runtime-composition.js";
+export { PAGER_DEFAULTS, ConfigurationError, initializePagerStore, loadPagerConfiguration, resolvePagerStoreDirectory, resolveConfigurationSetting, type PagerConfig, type ConfigurationLoadOptions, type ConfigurationSettingPrecedence, type LoadedConfiguration, } from "./configuration.js";
+export { DirectTerminalProvider, ForegroundTerminalProvider, LaunchService, renderLaunchResult, type AttachState, type ForegroundProcessSpawner, type LaunchDiagnostic, type LaunchRequest, type LaunchResult, type ProcessSpawner, type ProcessState, type TerminalLaunch, type TerminalProvider, type TerminalProviderName, type TerminalSession, type TerminalTaskCompletion, } from "./launch/launch.js";
+export { BunRuntimeError, assertSupportedBunRuntime, probeBunVersion, resolveBunExecutable, satisfiesBunVersionFloor, BUN_PATH_ENVIRONMENT, MINIMUM_BUN_VERSION, RETIRED_NODE_PATH_ENVIRONMENT, type RuntimeProbe, } from "./launch/runtime.js";
+export { BrokerService, EndpointPortUnavailableError, systemWorkspaceBranch, type BrokerServiceOptions, type BrokerServiceStatus, } from "./launch/service.js";
+export { systemBrokerServiceFilesystem, systemBrokerServiceScheduler } from "./launch/service-system.js";
+export { BrokerLockGuard, brokerLockPath } from "./launch/broker-lock.js";
+export { readRuntimeEnvironment, PAGER_AGENT_ID_ENVIRONMENT, PAGER_ATTACH_RESERVATION_ENVIRONMENT, PAGER_BROKER_URL_ENVIRONMENT, PAGER_MCP_URL_ENVIRONMENT, type RuntimeEnvironment, } from "./launch/environment.js";
+export { claimsWakeContent, CLAIMS_WAKE_PREFIX, type ClaimsDelivered, type DeliveryAddress, type DeliveryReach, type MessageClaim, } from "./messaging/delivery.js";
+export { BrokerDeliveryClient, adoptRotation, asRecord, compatibilityPayload, exactRecord, registerAgent, rpcEnvelope, type AttachDeliveryClientOptions, type AttachedSession, type BrokerIdentity, type BrokerRequest, } from "./messaging/delivery-client.js";
+export { startMcpServer, DELIVERY_ADDRESS_HEADER, type McpNotificationPort, type McpServerHandle, type StartMcpServerOptions, } from "./messaging/mcp.js";
+export { NotificationHub, NotificationScheduler, NotificationValidationError, NOTIFICATION_OPERATIONAL_EVENT_LIMIT, OPERATOR_CONTROL_CORRELATION_LIMIT, type AdapterCapabilities, type BusyWakeRelease, type InboxChanged, type InboxMessageChanged, type InboxMessageReason, type NotificationBroker, type NotificationEvent, type NotificationSubscriberFailure, type OperatorPingAdmission, type OperatorPingChanged, } from "./messaging/notifications.js";
+export { PushDeliveryService, type DeliveryAddressRegistration, type PushDeliveryBroker, type PushDeliveryDependencies, type PushDeliveryScheduler, } from "./messaging/push-delivery.js";
+export { MCP_TOOLS, type McpToolDefinition } from "./messaging/tools.js";
+export { PAGER_WAKE_TYPE, wakeLine, wakeMetadata } from "./messaging/wake.js";
+export { classifyOperatorEvent, validateOperatorAgent, validateOperatorCommand, validateOperatorCommandResult, validateOperatorCommandResultForCommand, validateOperatorControlId, validateOperatorCursor, validateOperatorDiagnostic, validateOperatorEventEnvelope, validateOperatorMessageBody, validateOperatorRepository, validateOperatorSnapshot, validateOperatorSnapshotByteLength, validateOperatorTraffic, validateOperatorTransportRequest, OperatorValidationError, OPERATOR_ARRAY_LENGTH_LIMIT, } from "./operator/validation.js";
+export { OPERATOR_DIAGNOSTIC_TEXT_LIMIT, OPERATOR_PROTOCOL_VERSION, OPERATOR_REJECTION_REASONS, OPERATOR_SNAPSHOT_CHUNK_BYTES, OPERATOR_SNAPSHOT_TOTAL_LIMIT_BYTES, OPERATOR_TRANSPORT_FRAME_LIMIT_BYTES, type OperatorAcceptedDelivery, type OperatorAdapterState, type OperatorAgent, type OperatorCommand, type OperatorCommandEnvelope, type OperatorCommandEnvelopeFor, type OperatorCommandResult, type OperatorCorrelatedCommandResult, type OperatorCursor, type OperatorCursorResult, type OperatorDeliveryLifecycleEntry, type OperatorDiagnostic, type OperatorDiagnosticSeverity, type OperatorEventEnvelope, type OperatorImplementation, type OperatorImplementationVersion, type OperatorJsonObject, type OperatorJsonValue, type OperatorMessageBody, type OperatorPingAudit, type OperatorRejectionReason, type OperatorRepository, type OperatorResyncReason, type OperatorSnapshot, type OperatorStateEvent, type OperatorTraffic, type OperatorTransportFrame, type OperatorTransportRequest, type OperatorWorktree, } from "./operator/protocol.js";
+export { PAGER_VERSION } from "./version.js";
+export { shellQuote } from "./shared/shell.js";

package/dist/src/index.js

@@ -0,0 +1,26 @@
+export { Broker, } from "./broker/broker.js";
+export {} from "./broker/schema.js";
+export { ProtocolError, assertAgentId, assertProtocolVersion, decodeMessageBody, encodeMessageBody, hasControlCharacter, isAgentId, isDirectAgentAddress, isImplementationId, isOpaqueId, isSessionKey, issueOpaqueToken, lifecycleEventState, mintAgentId, normalizeMessageSubject, normalizeMessageType, validateImplementationId, validateSessionKey, AGENT_ID_SCHEME, FETCH_LIMIT_DEFAULT, FETCH_LIMIT_MAX, IMPLEMENTATION_ID_MAX_LENGTH, IMPLEMENTATION_ID_PATTERN, MESSAGE_BODY_LIMIT_BYTES, MESSAGE_SUBJECT_LIMIT_CHARACTERS, MESSAGE_TYPE_LIMIT_CHARACTERS, PROTOCOL_VERSION, REGISTRATION_SESSION_NAME_MAX_LENGTH, SESSION_IDENTIFIER_PATTERN, SESSION_KEY_MAX_LENGTH, } from "./broker/protocol.js";
+export { publicEpoch, startSnapshotServer, } from "./broker/snapshot.js";
+export { parseAgentAddress, workspaceTeamId } from "./broker/address.js";
+export { ImplementationRegistry, assertImplementationProvider, discoverImplementationRegistry, implementationId, } from "./implementations/registry.js";
+export { harnessSessionKey } from "./implementations/session-key.js";
+export { createImplementationRegistry } from "./launch/runtime-composition.js";
+export { PAGER_DEFAULTS, ConfigurationError, initializePagerStore, loadPagerConfiguration, resolvePagerStoreDirectory, resolveConfigurationSetting, } from "./configuration.js";
+export { DirectTerminalProvider, ForegroundTerminalProvider, LaunchService, renderLaunchResult, } from "./launch/launch.js";
+export { BunRuntimeError, assertSupportedBunRuntime, probeBunVersion, resolveBunExecutable, satisfiesBunVersionFloor, BUN_PATH_ENVIRONMENT, MINIMUM_BUN_VERSION, RETIRED_NODE_PATH_ENVIRONMENT, } from "./launch/runtime.js";
+export { BrokerService, EndpointPortUnavailableError, systemWorkspaceBranch, } from "./launch/service.js";
+export { systemBrokerServiceFilesystem, systemBrokerServiceScheduler } from "./launch/service-system.js";
+export { BrokerLockGuard, brokerLockPath } from "./launch/broker-lock.js";
+export { readRuntimeEnvironment, PAGER_AGENT_ID_ENVIRONMENT, PAGER_ATTACH_RESERVATION_ENVIRONMENT, PAGER_BROKER_URL_ENVIRONMENT, PAGER_MCP_URL_ENVIRONMENT, } from "./launch/environment.js";
+export { claimsWakeContent, CLAIMS_WAKE_PREFIX, } from "./messaging/delivery.js";
+export { BrokerDeliveryClient, adoptRotation, asRecord, compatibilityPayload, exactRecord, registerAgent, rpcEnvelope, } from "./messaging/delivery-client.js";
+export { startMcpServer, DELIVERY_ADDRESS_HEADER, } from "./messaging/mcp.js";
+export { NotificationHub, NotificationScheduler, NotificationValidationError, NOTIFICATION_OPERATIONAL_EVENT_LIMIT, OPERATOR_CONTROL_CORRELATION_LIMIT, } from "./messaging/notifications.js";
+export { PushDeliveryService, } from "./messaging/push-delivery.js";
+export { MCP_TOOLS } from "./messaging/tools.js";
+export { PAGER_WAKE_TYPE, wakeLine, wakeMetadata } from "./messaging/wake.js";
+export { classifyOperatorEvent, validateOperatorAgent, validateOperatorCommand, validateOperatorCommandResult, validateOperatorCommandResultForCommand, validateOperatorControlId, validateOperatorCursor, validateOperatorDiagnostic, validateOperatorEventEnvelope, validateOperatorMessageBody, validateOperatorRepository, validateOperatorSnapshot, validateOperatorSnapshotByteLength, validateOperatorTraffic, validateOperatorTransportRequest, OperatorValidationError, OPERATOR_ARRAY_LENGTH_LIMIT, } from "./operator/validation.js";
+export { OPERATOR_DIAGNOSTIC_TEXT_LIMIT, OPERATOR_PROTOCOL_VERSION, OPERATOR_REJECTION_REASONS, OPERATOR_SNAPSHOT_CHUNK_BYTES, OPERATOR_SNAPSHOT_TOTAL_LIMIT_BYTES, OPERATOR_TRANSPORT_FRAME_LIMIT_BYTES, } from "./operator/protocol.js";
+export { PAGER_VERSION } from "./version.js";
+export { shellQuote } from "./shared/shell.js";

package/dist/src/launch/broker-lock.d.ts

@@ -0,0 +1,257 @@
+import { ProtocolError, type BrokerServiceIdentity } from "../broker/protocol.js";
+/** Identifies the ownership schema understood by this release. */
+export declare const SERVICE_PROTOCOL_VERSION = 1;
+/** Identifies the package build that owns production service state. */
+export declare const SERVICE_BUILD_ID: string;
+/** Identifies the production runtime required to own SQLite. */
+export declare const SERVICE_RUNTIME = "bun";
+/** Describes the process ownership record published beside a broker database. */
+export type BrokerLock = {
+    /** Identifies the process that owns the lock. */
+    pid: number;
+    /** Identifies the broker generation held by the process. */
+    epoch: string;
+    /** Locates the shared MCP endpoint after service startup. */
+    mcpUrl?: string;
+    /** Locates the shared snapshot origin after service startup. */
+    snapshotUrl?: string;
+    /** Locates the loopback operator TCP stream when its projection boundary is available. */
+    operatorUrl?: string;
+    /**
+     * Identifies the acquisition that created the record. Only the acquisition holding this token may
+     * replace or remove the lock, so a reclaimer cannot delete a lock that was rewritten underneath it.
+     */
+    holder?: string;
+    /**
+     * Records the owning process's start time as the platform reports it. Absent where the platform
+     * cannot report one; present, it distinguishes the owner from a later process given its pid.
+     */
+    ownerStartedAt?: string;
+} & BrokerServiceIdentity;
+/**
+ * Returns the identity published by the current Bun service build.
+ * @returns - Runtime, build, and wire-protocol ownership fields.
+ */
+export declare function currentBrokerServiceIdentity(): BrokerServiceIdentity;
+/**
+ * Report whether a lock belongs to the current production service contract.
+ * @param lock - Candidate lock identity from an untrusted adjacent file.
+ * @returns - True only for the current Bun build and wire protocol.
+ */
+export declare function brokerLockHasCurrentIdentity(lock: BrokerLock | undefined): boolean;
+/**
+ * Validate an untrusted health payload against the current service contract.
+ * @param value - Parsed health response or lock-shaped object.
+ * @returns - True when it names a supported Bun and the current build/protocol.
+ */
+export declare function isCurrentBrokerServiceIdentity(value: unknown): value is BrokerServiceIdentity;
+/**
+ * Report whether a lock names a live, current-build service that has left its starting epoch.
+ * @param lock - Candidate lock identity from an untrusted adjacent file.
+ * @param isAlive - Operating-system liveness boundary.
+ * @returns - True only for a live service whose published endpoints a reader may use.
+ */
+export declare function brokerLockIsLive(lock: BrokerLock | undefined, isAlive: (pid: number) => boolean): lock is BrokerLock;
+/**
+ * Read only the process id from any structurally valid current or legacy lock.
+ * @param lockPath - File containing a candidate ownership record.
+ * @returns - Positive process id when the file carries one.
+ */
+export declare function readBrokerOwnerPid(lockPath: string): number | undefined;
+/**
+ * Read the owning process from any structurally valid current or legacy lock.
+ *
+ * Reads only the fields every build has written, so a lock left by a build whose full record this
+ * one no longer accepts still names its owner.
+ * @param lockPath - File containing a candidate ownership record.
+ * @returns - The owner's positive process id, with the start time the lock recorded for it when it
+ *   recorded one.
+ */
+export declare function readBrokerOwner(lockPath: string): {
+    pid: number;
+    startedAt?: string;
+} | undefined;
+/**
+ * Resolve the service lock beside its durable database.
+ * @param databasePath - Durable SQLite file whose owning service publishes the lock.
+ * @returns - Path of the lock file beside the database.
+ */
+export declare function brokerLockPath(databasePath: string): string;
+/**
+ * Read a valid broker lock record without importing the SQLite-backed service.
+ * @param lockPath - File containing the candidate lock record.
+ * @returns - Valid parsed lock data when the file is well-formed.
+ */
+export declare function readBrokerLock(lockPath: string): BrokerLock | undefined;
+/** Bounds how many times acquisition re-attempts after losing a lock-file race. */
+export declare const BROKER_LOCK_ACQUISITION_ATTEMPTS = 5;
+/** Reports the start time of a process, or that this platform cannot supply one. */
+export type ProcessStartTime = {
+    known: true;
+    value: string;
+} | {
+    known: false;
+};
+/** Supplies the operating-system and timing boundaries the lock protocol reads. */
+export type BrokerLockPorts = {
+    /** Reports whether a process id currently names a running process. */
+    processIsAlive(pid: number): boolean;
+    /** Reports when a running process started, in a form comparable only against itself. */
+    processStartedAt(pid: number): ProcessStartTime;
+    /** Issues an unguessable token identifying one acquisition of the lock. */
+    newHolderToken(): string;
+    /** Blocks the calling thread, because lock acquisition runs before the service has an event loop. */
+    sleep(milliseconds: number): void;
+};
+/** Reports that the lock is held by a live service of the current build. */
+export declare class BrokerServiceAlreadyRunningError extends ProtocolError {
+    /** Identifies the live process that owns the lock. */
+    readonly pid: number;
+    /**
+     * Construct the failure naming the live owner a second service must defer to.
+     * @param pid - Process id recorded by the lock this process could not take.
+     */
+    constructor(
+    /** Identifies the live process that owns the lock. */
+    pid: number);
+}
+/** Reports that the lock is held by a live service this build must not displace. */
+export declare class BrokerServiceLockOwnedError extends ProtocolError {
+    /** Identifies the live process that owns the lock. */
+    readonly pid: number;
+    /**
+     * Construct the failure naming the incompatible owner an operator must resolve.
+     * @param pid - Process id recorded by the lock this process could not take.
+     */
+    constructor(
+    /** Identifies the live process that owns the lock. */
+    pid: number);
+}
+/** Reports that acquisition kept losing the lock file to another writer. */
+export declare class BrokerLockContendedError extends ProtocolError {
+    /** Names the contended lock file. */
+    readonly lockPath: string;
+    /** Records how many attempts were made before giving up. */
+    readonly attempts: number;
+    /** Names the file that blocked the final attempt. */
+    readonly blockedBy: string;
+    /**
+     * Construct the failure that ends a bounded acquisition rather than retrying forever.
+     * @param lockPath - Lock file this process was trying to take.
+     * @param attempts - Number of acquisition attempts that were made and lost.
+     * @param blockedBy - File that was still held or recreated on the final attempt, which is the one
+     * an operator has to deal with and is not always the lock itself.
+     */
+    constructor(
+    /** Names the contended lock file. */
+    lockPath: string, 
+    /** Records how many attempts were made before giving up. */
+    attempts: number, 
+    /** Names the file that blocked the final attempt. */
+    blockedBy: string);
+}
+/** Reports that the lock this process acquired is no longer the one on disk. */
+export declare class BrokerLockLostError extends ProtocolError {
+    /** Names the lock file this process no longer holds. */
+    readonly lockPath: string;
+    /**
+     * Construct the failure that stops a service publishing endpoints it no longer owns.
+     * @param lockPath - Lock file whose holder token stopped matching this acquisition.
+     */
+    constructor(
+    /** Names the lock file this process no longer holds. */
+    lockPath: string);
+}
+/**
+ * Report whether a process id names a running process.
+ * @param pid - Process id to probe.
+ * @returns - True unless the operating system reports no such process.
+ */
+export declare function processIsAlive(pid: number): boolean;
+/**
+ * Read a process's start time from the platform, where the platform can report one.
+ *
+ * The value is tagged with the reading that produced it. A record carrying a tag this build does not
+ * produce describes a moment measured some other way, and comparing the two would be meaningless.
+ * @param pid - Process id to describe.
+ * @returns - The start time, or an explicit absence on a platform that cannot supply one.
+ */
+export declare function processStartedAt(pid: number): ProcessStartTime;
+/**
+ * Report whether a recorded start time still describes whichever process now holds a process id.
+ * @param recorded - Start time captured when the record was written.
+ * @param actual - Start time read from the platform now.
+ * @returns - False only when both readings are the same kind and disagree.
+ */
+export declare function startTimeStillMatches(recorded: string, actual: ProcessStartTime): boolean;
+/**
+ * Build the operating-system boundaries used by a production lock acquisition.
+ * @returns - Ports backed by the operating system's process table, a random token source, and a sleep that blocks the thread.
+ */
+export declare function systemBrokerLockPorts(): BrokerLockPorts;
+/**
+ * The exclusive claim a broker service holds on its database for the life of the process.
+ *
+ * Structural rather than the class itself: `BrokerLockGuard` has `#private` fields, so a consumer
+ * typed against the class could only ever be handed a real one.
+ */
+export type BrokerLockOwner = {
+    /** Names the lock file this owner claims. */
+    readonly path: string;
+    /** Takes exclusive ownership of the database, reclaiming a lock whose owner is gone. */
+    acquire(): void;
+    /** Replaces the acquired lock with the record readers adopt. */
+    publish(lock: BrokerLock): void;
+    /** Gives up ownership, leaving any lock this owner does not hold untouched. */
+    release(): void;
+};
+/**
+ * Owns one process's exclusive claim on a broker database.
+ *
+ * Creation links a staged record into place and fails on a name another process holds, so
+ * uncontended acquisition already selects one winner. Reclaiming a stale lock cannot be, because it
+ * spans a read and an unlink: two processes that each read the same dead owner would each remove
+ * whatever lock was present by the time they got to the unlink, including the other's fresh one. A
+ * separate reclaim file, claimed the same way, serialises that span, and the owner is re-read inside
+ * it, so a reclaimer that lost the race sees the winner rather than deleting it.
+ */
+export declare class BrokerLockGuard implements BrokerLockOwner {
+    #private;
+    /**
+     * Construct a guard over one lock file.
+     * @param lockPath - Lock file adjacent to the database this process wants to own.
+     * @param ports - Operating-system boundaries, replaced only by this module's own tests.
+     */
+    constructor(lockPath: string, ports?: BrokerLockPorts);
+    /**
+     * Names the lock file this guard claims.
+     * @returns - Path the guard was constructed over.
+     */
+    get path(): string;
+    /**
+     * Take exclusive ownership of the database, reclaiming a lock whose owner is gone.
+     *
+     * Terminates in every case: each attempt either wins the lock, throws because a live owner holds
+     * it, or consumes one of a fixed number of attempts.
+     * @throws {BrokerServiceAlreadyRunningError} - A live service of this build holds the lock.
+     * @throws {BrokerServiceLockOwnedError} - A live service this build must not displace holds the lock.
+     * @throws {BrokerLockContendedError} - Another writer kept recreating the lock.
+     */
+    acquire(): void;
+    /**
+     * Replace the acquired lock with the record readers adopt.
+     *
+     * Written to a scratch file and renamed, so no reader can observe a partial document and treat
+     * the database as unowned.
+     * @param lock - Ownership record naming this process's published endpoints.
+     * @throws {BrokerLockLostError} - The lock on disk is no longer the one this guard acquired.
+     */
+    publish(lock: BrokerLock): void;
+    /**
+     * Give up ownership, leaving any lock this guard does not hold untouched.
+     *
+     * A service that failed to acquire, or whose lock was reclaimed while it shut down, must not
+     * delete the record naming whichever process owns the database now.
+     */
+    release(): void;
+}