@stelis/agent-q-core 0.0.0

package/dist/core.d.ts

@@ -0,0 +1,320 @@
+import { ConfigStore, type DeviceListing } from "./config.js";
+export { SerialPortUsbDriver } from "./usb.js";
+import { type Account, type ApprovalHistoryRecord, type CapabilityChain, type DeviceStatusSnapshot, type IdentifyDeviceResponse, type PolicyDocument, type PolicyProposeResultResponse, type SignResultResponse, type SigningCapabilities, type StatusResponse } from "./protocol.js";
+import { type UnavailableReason, type UsbSerialDriver } from "./usb.js";
+export interface LiveDeviceStatus {
+    source: "live";
+    connected: true;
+    portPath: string;
+    protocolResponse: StatusResponse;
+}
+export interface CachedDeviceStatus {
+    source: "cached";
+    connected: false;
+    statusObservedAt: string;
+    unavailableReason: UnavailableReason;
+    firmwareErrorCode?: string;
+    cachedStatus: DeviceStatusSnapshot;
+}
+export type DeviceStatusResult = LiveDeviceStatus | CachedDeviceStatus;
+export type DeviceStatusToolResult = DeviceStatusResult;
+export interface ScanDevicesResult {
+    source: "live";
+    devices: LiveDeviceStatus[];
+    failures: ScanDeviceFailure[];
+    activeDeviceId: string | null;
+}
+export interface ScanDeviceFailure {
+    source: "error";
+    connected: false;
+    portPath: string;
+    unavailableReason: UnavailableReason;
+    firmwareErrorCode?: string;
+}
+export interface IdentifiedDevice {
+    source: "live";
+    connected: true;
+    portPath: string;
+    status: "displayed";
+    code: string;
+    protocolResponse: IdentifyDeviceResponse;
+}
+export interface IdentifyDeviceFailure {
+    source: "error";
+    connected: false;
+    portPath: string;
+    deviceId: string;
+    status: "error";
+    error: {
+        code: string;
+        message: string;
+        retryable: boolean;
+    };
+}
+export interface IdentifyDevicesResult {
+    source: "live";
+    devices: Array<IdentifiedDevice | IdentifyDeviceFailure>;
+    activeDeviceId: string | null;
+}
+export interface SelectDeviceResult {
+    source: "selected";
+    activeDeviceId: string;
+    purpose: string | null;
+    device: StatusResponse["device"];
+}
+export interface RuntimeSessionView {
+    sessionTtlMs: number;
+    connectedAt: string;
+}
+export interface DeviceListEntry extends DeviceListing {
+    runtimeSession: RuntimeSessionView | null;
+}
+export interface DeviceListResult {
+    source: "list";
+    devices: DeviceListEntry[];
+    activeDeviceId: string | null;
+    activeDeviceIdsByPurpose: Record<string, string>;
+}
+export interface SetDeviceMetadataResult {
+    source: "metadata";
+    deviceId: string;
+    label: string | null;
+}
+export interface ConnectDeviceResult {
+    source: "connected";
+    deviceId: string;
+    sessionTtlMs: number;
+    connectedAt: string;
+    device: StatusResponse["device"];
+}
+export declare const DISCONNECT_REASONS: readonly ["firmware_confirmed", "invalid_session", "transport_unavailable", "timeout", "not_connected"];
+export type DisconnectReason = (typeof DISCONNECT_REASONS)[number];
+export declare const DISCONNECT_ENDED_REASONS: readonly ["firmware_confirmed", "invalid_session", "transport_unavailable", "timeout"];
+export type DisconnectEndedReason = (typeof DISCONNECT_ENDED_REASONS)[number];
+export declare const GET_ACCOUNTS_SESSION_ENDED_REASONS: readonly ["invalid_session", "transport_unavailable", "timeout"];
+export type GetAccountsSessionEndedReason = (typeof GET_ACCOUNTS_SESSION_ENDED_REASONS)[number];
+export declare const GET_CAPABILITIES_SESSION_ENDED_REASONS: readonly ["invalid_session", "transport_unavailable", "timeout"];
+export type GetCapabilitiesSessionEndedReason = GetAccountsSessionEndedReason;
+export declare const POLICY_GET_SESSION_ENDED_REASONS: readonly ["invalid_session", "transport_unavailable", "timeout"];
+export type PolicyGetSessionEndedReason = GetAccountsSessionEndedReason;
+export declare const GET_APPROVAL_HISTORY_SESSION_ENDED_REASONS: readonly ["invalid_session", "transport_unavailable", "timeout"];
+export type GetApprovalHistorySessionEndedReason = GetAccountsSessionEndedReason;
+export declare const POLICY_PROPOSE_SESSION_ENDED_REASONS: readonly ["invalid_session", "transport_unavailable", "timeout"];
+export type PolicyProposeSessionEndedReason = GetAccountsSessionEndedReason;
+export declare const SIGN_TRANSACTION_SESSION_ENDED_REASONS: readonly ["invalid_session", "transport_unavailable", "timeout"];
+export type SignTransactionSessionEndedReason = GetAccountsSessionEndedReason;
+export declare const SIGN_PERSONAL_MESSAGE_SESSION_ENDED_REASONS: readonly ["invalid_session", "transport_unavailable", "timeout"];
+export type SignPersonalMessageSessionEndedReason = GetAccountsSessionEndedReason;
+export type DisconnectDeviceResult = {
+    source: "disconnected";
+    deviceId: string;
+    reason: DisconnectEndedReason;
+} | {
+    source: "not_connected";
+    deviceId: string;
+    reason: "not_connected";
+};
+export type GetCapabilitiesResult = {
+    source: "live";
+    deviceId: string;
+    capabilities: CapabilityChain[];
+    signing?: SigningCapabilities;
+} | {
+    source: "not_connected";
+    deviceId: string;
+    reason: "not_connected";
+} | {
+    source: "session_ended";
+    deviceId: string;
+    reason: GetCapabilitiesSessionEndedReason;
+};
+export type GetAccountsResult = {
+    source: "live";
+    deviceId: string;
+    accounts: Account[];
+} | {
+    source: "not_connected";
+    deviceId: string;
+    reason: "not_connected";
+} | {
+    source: "session_ended";
+    deviceId: string;
+    reason: GetAccountsSessionEndedReason;
+};
+export type PolicyGetResult = {
+    source: "live";
+    deviceId: string;
+    policy: PolicyDocument;
+} | {
+    source: "not_connected";
+    deviceId: string;
+    reason: "not_connected";
+} | {
+    source: "session_ended";
+    deviceId: string;
+    reason: PolicyGetSessionEndedReason;
+};
+export type GetApprovalHistoryResult = {
+    source: "live";
+    deviceId: string;
+    records: ApprovalHistoryRecord[];
+    hasMore: boolean;
+} | {
+    source: "not_connected";
+    deviceId: string;
+    reason: "not_connected";
+} | {
+    source: "session_ended";
+    deviceId: string;
+    reason: GetApprovalHistorySessionEndedReason;
+};
+export type PolicyProposeResult = {
+    source: "live";
+    deviceId: string;
+    status: PolicyProposeResultResponse["status"];
+    reasonCode: PolicyProposeResultResponse["reasonCode"];
+    policy?: PolicyProposeResultResponse["policy"];
+} | {
+    source: "not_connected";
+    deviceId: string;
+    reason: "not_connected";
+} | {
+    source: "session_ended";
+    deviceId: string;
+    reason: PolicyProposeSessionEndedReason;
+};
+type SignTerminalResponse = Extract<SignResultResponse, {
+    status: "user_rejected" | "user_timed_out" | "policy_rejected" | "signing_failed";
+}>;
+type LiveSignedResult = {
+    source: "live";
+    deviceId: string;
+    status: "signed";
+    authorization: Extract<SignResultResponse, {
+        status: "signed";
+    }>["authorization"];
+    chain: Extract<SignResultResponse, {
+        status: "signed";
+    }>["chain"];
+    method: Extract<SignResultResponse, {
+        status: "signed";
+    }>["method"];
+    signature: string;
+    messageBytes?: string;
+};
+type LiveTerminalSignResult = {
+    source: "live";
+    deviceId: string;
+    status: Exclude<SignTerminalResponse["status"], "policy_rejected">;
+    authorization: SignTerminalResponse["authorization"];
+    error: Extract<SignTerminalResponse, {
+        status: Exclude<SignTerminalResponse["status"], "policy_rejected">;
+    }>["error"];
+} | {
+    source: "live";
+    deviceId: string;
+    status: "policy_rejected";
+    authorization: "policy";
+    policyHash: string;
+    ruleRef: string;
+    error: Extract<SignTerminalResponse, {
+        status: "policy_rejected";
+    }>["error"];
+};
+export type SignTransactionResult = LiveSignedResult | LiveTerminalSignResult | {
+    source: "not_connected";
+    deviceId: string;
+    reason: "not_connected";
+} | {
+    source: "session_ended";
+    deviceId: string;
+    reason: SignTransactionSessionEndedReason;
+};
+export type SignPersonalMessageResult = LiveSignedResult | LiveTerminalSignResult | {
+    source: "not_connected";
+    deviceId: string;
+    reason: "not_connected";
+} | {
+    source: "session_ended";
+    deviceId: string;
+    reason: SignPersonalMessageSessionEndedReason;
+};
+export declare const DEFAULT_CLIENT_NAME = "Agent-Q";
+export declare class AgentQCore {
+    private readonly configStore;
+    private readonly clock;
+    private readonly runtimeSessions;
+    private readonly usbDriver;
+    constructor(configStore: ConfigStore, usbDriver: UsbSerialDriver, clock?: () => Date);
+    scanDevices(input?: Record<string, never>): Promise<ScanDevicesResult>;
+    identifyDevices(input?: Record<string, never>): Promise<IdentifyDevicesResult>;
+    selectDevice(input: {
+        deviceId: string;
+        purpose?: string;
+    }): Promise<SelectDeviceResult>;
+    listDevices(): Promise<DeviceListResult>;
+    setDeviceMetadata(input: {
+        deviceId: string;
+        label?: string | null;
+    }): Promise<SetDeviceMetadataResult>;
+    connectDevice(input?: {
+        deviceId?: string;
+        purpose?: string;
+        clientName?: string;
+    }): Promise<ConnectDeviceResult>;
+    disconnectDevice(input?: {
+        deviceId?: string;
+        purpose?: string;
+    }): Promise<DisconnectDeviceResult>;
+    getCapabilities(input?: {
+        deviceId?: string;
+        purpose?: string;
+    }): Promise<GetCapabilitiesResult>;
+    getAccounts(input?: {
+        deviceId?: string;
+        purpose?: string;
+    }): Promise<GetAccountsResult>;
+    policyGet(input?: {
+        deviceId?: string;
+        purpose?: string;
+    }): Promise<PolicyGetResult>;
+    getApprovalHistory(input?: {
+        deviceId?: string;
+        purpose?: string;
+        limit?: number;
+        beforeSeq?: string;
+    }): Promise<GetApprovalHistoryResult>;
+    policyPropose(input: {
+        deviceId?: string;
+        purpose?: string;
+        policy: Record<string, unknown>;
+    }): Promise<PolicyProposeResult>;
+    signTransaction(input: {
+        deviceId?: string;
+        purpose?: string;
+        chain: string;
+        method: string;
+        network: unknown;
+        txBytes: string;
+    }): Promise<SignTransactionResult>;
+    signPersonalMessage(input: {
+        deviceId?: string;
+        purpose?: string;
+        chain: string;
+        method: string;
+        network: unknown;
+        message: string;
+    }): Promise<SignPersonalMessageResult>;
+    private peekRuntimeSession;
+    private recordSession;
+    private clearRuntimeSessionsAbsentFromLiveUsbScan;
+    private clearRuntimeSessionMirror;
+    private clearRuntimeSessionMirrorIfEnded;
+    private resolveTargetDevice;
+    private findLivePortForDevice;
+    getDeviceStatus(input?: {
+        deviceId?: string;
+        purpose?: string;
+    }): Promise<DeviceStatusResult>;
+}
+export declare function createDefaultAgentQCore(): AgentQCore;