@kmmao/happy-agent 0.2.2 → 0.3.0

package/dist/index.d.cts

@@ -1 +1,328 @@
 #!/usr/bin/env node
+import { z } from 'zod';
+import { EventEmitter } from 'node:events';
+import { Socket } from 'socket.io-client';
+
+type Config = {
+    serverUrl: string;
+    webappUrl: string;
+    homeDir: string;
+    credentialPath: string;
+};
+declare function loadConfig(): Config;
+
+type Credentials = {
+    token: string;
+    secret: Uint8Array;
+    contentKeyPair: {
+        publicKey: Uint8Array;
+        secretKey: Uint8Array;
+    };
+};
+declare function readCredentials(config: Config): Credentials | null;
+declare function requireCredentials(config: Config): Credentials;
+
+declare function authLogin(config: Config, opts?: {
+    web?: boolean;
+}): Promise<void>;
+declare function authLogout(config: Config): Promise<void>;
+declare function authStatus(config: Config): Promise<void>;
+
+type EncryptionVariant = "legacy" | "dataKey";
+type SessionEncryption = {
+    readonly key: Uint8Array;
+    readonly variant: EncryptionVariant;
+};
+type RawSession = {
+    readonly id: string;
+    readonly seq: number;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+    readonly active: boolean;
+    readonly activeAt: number;
+    readonly metadata: string;
+    readonly metadataVersion: number;
+    readonly agentState: string | null;
+    readonly agentStateVersion: number;
+    readonly dataEncryptionKey: string | null;
+};
+type DecryptedSession = {
+    id: string;
+    seq: number;
+    createdAt: number;
+    updatedAt: number;
+    active: boolean;
+    activeAt: number;
+    metadata: unknown;
+    agentState: unknown | null;
+    dataEncryptionKey: string | null;
+    encryption: SessionEncryption;
+};
+declare const MachineMetadataSchema: z.ZodObject<{
+    host: z.ZodString;
+    platform: z.ZodString;
+    happyCliVersion: z.ZodString;
+    homeDir: z.ZodString;
+    happyHomeDir: z.ZodString;
+    happyLibDir: z.ZodString;
+}, z.core.$strip>;
+type MachineMetadata = z.infer<typeof MachineMetadataSchema>;
+declare const DaemonStateSchema: z.ZodObject<{
+    status: z.ZodUnion<readonly [z.ZodEnum<{
+        running: "running";
+        "shutting-down": "shutting-down";
+    }>, z.ZodString]>;
+    pid: z.ZodOptional<z.ZodNumber>;
+    httpPort: z.ZodOptional<z.ZodNumber>;
+    startedAt: z.ZodOptional<z.ZodNumber>;
+    shutdownRequestedAt: z.ZodOptional<z.ZodNumber>;
+    shutdownSource: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        unknown: "unknown";
+        "mobile-app": "mobile-app";
+        cli: "cli";
+        "os-signal": "os-signal";
+    }>, z.ZodString]>>;
+}, z.core.$strip>;
+type DaemonState = z.infer<typeof DaemonStateSchema>;
+type Machine = {
+    readonly id: string;
+    readonly encryptionKey: Uint8Array;
+    readonly encryptionVariant: EncryptionVariant;
+    readonly metadata: MachineMetadata;
+    readonly metadataVersion: number;
+    readonly daemonState: DaemonState | null;
+    readonly daemonStateVersion: number;
+};
+
+/**
+ * HTTP API client for happy-agent.
+ *
+ * Provides all HTTP-based operations: session CRUD, message fetching,
+ * and v3 batch message API. Migrated from src/api.ts with v3 additions.
+ */
+
+type DecryptedMessage = {
+    id: string;
+    seq: number;
+    content: unknown;
+    localId: string | null;
+    createdAt: number;
+    updatedAt: number;
+};
+type V3PostMessagesResponse = {
+    messages: Array<{
+        id: string;
+        seq: number;
+        localId: string | null;
+        createdAt: number;
+        updatedAt: number;
+    }>;
+};
+declare function resolveSessionEncryption(session: RawSession, creds: Credentials): SessionEncryption;
+declare function listSessions(config: Config, creds: Credentials): Promise<DecryptedSession[]>;
+declare function listActiveSessions(config: Config, creds: Credentials): Promise<DecryptedSession[]>;
+declare function createSession(config: Config, creds: Credentials, opts: {
+    tag: string;
+    metadata: unknown;
+}): Promise<DecryptedSession & {
+    sessionKey: Uint8Array;
+}>;
+declare function deleteSession(config: Config, creds: Credentials, sessionId: string): Promise<void>;
+declare function getSessionMessages(config: Config, creds: Credentials, sessionId: string, encryption: SessionEncryption): Promise<DecryptedMessage[]>;
+/**
+ * Fetch messages after a given seq using v3 API.
+ * Returns decrypted messages and whether more pages are available.
+ */
+declare function fetchMessagesAfterSeq(config: Config, creds: Credentials, sessionId: string, encryption: SessionEncryption, afterSeq: number, limit?: number): Promise<{
+    messages: DecryptedMessage[];
+    hasMore: boolean;
+}>;
+/**
+ * Send a batch of encrypted messages using v3 API.
+ */
+declare function sendMessagesBatch(config: Config, creds: Credentials, sessionId: string, encryption: SessionEncryption, contents: unknown[]): Promise<V3PostMessagesResponse>;
+type RawMachine = {
+    id: string;
+    metadata: string;
+    metadataVersion: number;
+    daemonState: string | null;
+    daemonStateVersion: number;
+    dataEncryptionKey: string | null;
+};
+/**
+ * Get or create a machine identity on the server.
+ * Returns the machine with decrypted metadata.
+ */
+declare function getOrCreateMachine(config: Config, creds: Credentials, metadata: MachineMetadata): Promise<Machine>;
+/**
+ * List all machines for the current account.
+ */
+declare function listMachines(config: Config, creds: Credentials): Promise<RawMachine[]>;
+
+/**
+ * Common RPC types and interfaces for both session and machine clients.
+ * Mirrors happy-cli/src/api/rpc/types.ts
+ */
+/**
+ * Generic RPC handler function type
+ */
+type RpcHandler<TRequest = any, TResponse = any> = (data: TRequest) => TResponse | Promise<TResponse>;
+/**
+ * RPC request data from server
+ */
+interface RpcRequest {
+    method: string;
+    params: string;
+}
+/**
+ * Configuration for RPC handler manager
+ */
+interface RpcHandlerConfig {
+    scopePrefix: string;
+    encryptionKey: Uint8Array;
+    encryptionVariant: "legacy" | "dataKey";
+    logger?: (message: string, data?: unknown) => void;
+}
+
+/**
+ * Generic RPC handler manager for session and machine clients.
+ * Manages RPC method registration, encryption/decryption, and handler execution.
+ *
+ * Adapted from happy-cli/src/api/rpc/RpcHandlerManager.ts with
+ * Agent-local imports (no @/ path alias).
+ */
+
+declare class RpcHandlerManager {
+    private handlers;
+    private readonly scopePrefix;
+    private readonly encryptionKey;
+    private readonly encryptionVariant;
+    private readonly logger;
+    private socket;
+    private reregisterInterval;
+    constructor(config: RpcHandlerConfig);
+    /**
+     * Register an RPC handler for a specific method
+     */
+    registerHandler<TRequest = any, TResponse = any>(method: string, handler: RpcHandler<TRequest, TResponse>): void;
+    /**
+     * Handle an incoming RPC request
+     */
+    handleRequest(request: RpcRequest): Promise<string>;
+    onSocketConnect(socket: Socket): void;
+    onSocketDisconnect(): void;
+    getHandlerCount(): number;
+    hasHandler(method: string): boolean;
+    clearHandlers(): void;
+    /**
+     * Register a single method with ack + retry.
+     * Falls back to fire-and-forget emit after all retries exhausted.
+     */
+    private emitRegisterWithRetry;
+    private registerAllHandlers;
+    /**
+     * Periodic re-registration every 60s as a safety net.
+     */
+    private startReregisterInterval;
+    private stopReregisterInterval;
+    private getPrefixedMethod;
+}
+declare function createRpcHandlerManager(config: RpcHandlerConfig): RpcHandlerManager;
+
+/**
+ * Enhanced session WebSocket client with RPC support.
+ *
+ * Improvements over the original session.ts:
+ * - RPC handler integration (bash, readFile, writeFile via RpcHandlerManager)
+ * - keepAlive with thinking state
+ * - updateMetadata / updateAgentState with OCC backoff
+ * - Typed socket events
+ *
+ * All existing public API is preserved for backward compatibility.
+ */
+
+type SessionClientOptions = {
+    readonly sessionId: string;
+    readonly encryptionKey: Uint8Array;
+    readonly encryptionVariant: EncryptionVariant;
+    readonly token: string;
+    readonly serverUrl: string;
+    readonly initialAgentState?: unknown | null;
+    /** Working directory for RPC handlers (bash cwd, file operations). Defaults to process.cwd(). */
+    readonly workingDirectory?: string;
+    /** Set to false to disable automatic RPC handler registration. Default: true */
+    readonly enableRpc?: boolean;
+};
+declare class SessionClient extends EventEmitter {
+    readonly sessionId: string;
+    readonly rpcHandlerManager: RpcHandlerManager;
+    private readonly encryptionKey;
+    private readonly encryptionVariant;
+    private socket;
+    private metadata;
+    private metadataVersion;
+    private agentState;
+    private agentStateVersion;
+    private aliveInterval;
+    private thinking;
+    constructor(opts: SessionClientOptions);
+    sendMessage(text: string, meta?: Record<string, unknown>): void;
+    getMetadata(): unknown | null;
+    getAgentState(): unknown | null;
+    setThinking(thinking: boolean): void;
+    waitForConnect(timeoutMs?: number): Promise<void>;
+    waitForIdle(timeoutMs?: number): Promise<void>;
+    sendStop(): void;
+    close(): void;
+    updateMetadata(newMetadata: unknown): Promise<void>;
+    updateAgentState(newState: unknown | null): Promise<void>;
+    private setupSocketListeners;
+}
+
+/**
+ * Machine WebSocket client — trimmed from CLI's ApiMachineClient.
+ *
+ * Core capabilities retained:
+ * - Machine-scoped Socket.IO connection
+ * - RPC handler registration (via RpcHandlerManager)
+ * - keepAlive heartbeat
+ * - updateMetadata / updateDaemonState with OCC backoff
+ * - Ephemeral event handling (webhook/supervisor triggers)
+ *
+ * Removed (CLI-only):
+ * - Webhook/supervisor status emit + pending queues
+ * - Fix kill handler
+ * - CLI-specific logging (debugLargeJson)
+ */
+
+type MachineClientOptions = {
+    readonly token: string;
+    readonly machine: Machine;
+    readonly serverUrl: string;
+    /** Working directory for RPC handlers. Defaults to process.cwd(). */
+    readonly workingDirectory?: string;
+    /** Handler for ephemeral events from server. */
+    readonly onEphemeral?: (data: {
+        type: string;
+        [key: string]: unknown;
+    }) => void;
+};
+declare class MachineClient {
+    readonly machine: Machine;
+    readonly rpcHandlerManager: RpcHandlerManager;
+    private socket;
+    private keepAliveInterval;
+    private readonly token;
+    private readonly serverUrl;
+    private readonly onEphemeral?;
+    constructor(opts: MachineClientOptions);
+    connect(): void;
+    updateMachineMetadata(handler: (metadata: MachineMetadata | null) => MachineMetadata): Promise<void>;
+    updateDaemonState(handler: (state: DaemonState | null) => DaemonState): Promise<void>;
+    shutdown(): void;
+    private startKeepAlive;
+    private stopKeepAlive;
+}
+
+export { MachineClient, RpcHandlerManager, SessionClient, authLogin, authLogout, authStatus, createRpcHandlerManager, createSession, deleteSession, fetchMessagesAfterSeq, getOrCreateMachine, getSessionMessages, listActiveSessions, listMachines, listSessions, loadConfig, readCredentials, requireCredentials, resolveSessionEncryption, sendMessagesBatch };
+export type { Config, Credentials, DecryptedMessage, DecryptedSession, EncryptionVariant, MachineClientOptions, RpcHandler, RpcHandlerConfig, SessionClientOptions, SessionEncryption };

package/dist/index.d.mts

@@ -1 +1,328 @@
 #!/usr/bin/env node
+import { z } from 'zod';
+import { EventEmitter } from 'node:events';
+import { Socket } from 'socket.io-client';
+
+type Config = {
+    serverUrl: string;
+    webappUrl: string;
+    homeDir: string;
+    credentialPath: string;
+};
+declare function loadConfig(): Config;
+
+type Credentials = {
+    token: string;
+    secret: Uint8Array;
+    contentKeyPair: {
+        publicKey: Uint8Array;
+        secretKey: Uint8Array;
+    };
+};
+declare function readCredentials(config: Config): Credentials | null;
+declare function requireCredentials(config: Config): Credentials;
+
+declare function authLogin(config: Config, opts?: {
+    web?: boolean;
+}): Promise<void>;
+declare function authLogout(config: Config): Promise<void>;
+declare function authStatus(config: Config): Promise<void>;
+
+type EncryptionVariant = "legacy" | "dataKey";
+type SessionEncryption = {
+    readonly key: Uint8Array;
+    readonly variant: EncryptionVariant;
+};
+type RawSession = {
+    readonly id: string;
+    readonly seq: number;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+    readonly active: boolean;
+    readonly activeAt: number;
+    readonly metadata: string;
+    readonly metadataVersion: number;
+    readonly agentState: string | null;
+    readonly agentStateVersion: number;
+    readonly dataEncryptionKey: string | null;
+};
+type DecryptedSession = {
+    id: string;
+    seq: number;
+    createdAt: number;
+    updatedAt: number;
+    active: boolean;
+    activeAt: number;
+    metadata: unknown;
+    agentState: unknown | null;
+    dataEncryptionKey: string | null;
+    encryption: SessionEncryption;
+};
+declare const MachineMetadataSchema: z.ZodObject<{
+    host: z.ZodString;
+    platform: z.ZodString;
+    happyCliVersion: z.ZodString;
+    homeDir: z.ZodString;
+    happyHomeDir: z.ZodString;
+    happyLibDir: z.ZodString;
+}, z.core.$strip>;
+type MachineMetadata = z.infer<typeof MachineMetadataSchema>;
+declare const DaemonStateSchema: z.ZodObject<{
+    status: z.ZodUnion<readonly [z.ZodEnum<{
+        running: "running";
+        "shutting-down": "shutting-down";
+    }>, z.ZodString]>;
+    pid: z.ZodOptional<z.ZodNumber>;
+    httpPort: z.ZodOptional<z.ZodNumber>;
+    startedAt: z.ZodOptional<z.ZodNumber>;
+    shutdownRequestedAt: z.ZodOptional<z.ZodNumber>;
+    shutdownSource: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        unknown: "unknown";
+        "mobile-app": "mobile-app";
+        cli: "cli";
+        "os-signal": "os-signal";
+    }>, z.ZodString]>>;
+}, z.core.$strip>;
+type DaemonState = z.infer<typeof DaemonStateSchema>;
+type Machine = {
+    readonly id: string;
+    readonly encryptionKey: Uint8Array;
+    readonly encryptionVariant: EncryptionVariant;
+    readonly metadata: MachineMetadata;
+    readonly metadataVersion: number;
+    readonly daemonState: DaemonState | null;
+    readonly daemonStateVersion: number;
+};
+
+/**
+ * HTTP API client for happy-agent.
+ *
+ * Provides all HTTP-based operations: session CRUD, message fetching,
+ * and v3 batch message API. Migrated from src/api.ts with v3 additions.
+ */
+
+type DecryptedMessage = {
+    id: string;
+    seq: number;
+    content: unknown;
+    localId: string | null;
+    createdAt: number;
+    updatedAt: number;
+};
+type V3PostMessagesResponse = {
+    messages: Array<{
+        id: string;
+        seq: number;
+        localId: string | null;
+        createdAt: number;
+        updatedAt: number;
+    }>;
+};
+declare function resolveSessionEncryption(session: RawSession, creds: Credentials): SessionEncryption;
+declare function listSessions(config: Config, creds: Credentials): Promise<DecryptedSession[]>;
+declare function listActiveSessions(config: Config, creds: Credentials): Promise<DecryptedSession[]>;
+declare function createSession(config: Config, creds: Credentials, opts: {
+    tag: string;
+    metadata: unknown;
+}): Promise<DecryptedSession & {
+    sessionKey: Uint8Array;
+}>;
+declare function deleteSession(config: Config, creds: Credentials, sessionId: string): Promise<void>;
+declare function getSessionMessages(config: Config, creds: Credentials, sessionId: string, encryption: SessionEncryption): Promise<DecryptedMessage[]>;
+/**
+ * Fetch messages after a given seq using v3 API.
+ * Returns decrypted messages and whether more pages are available.
+ */
+declare function fetchMessagesAfterSeq(config: Config, creds: Credentials, sessionId: string, encryption: SessionEncryption, afterSeq: number, limit?: number): Promise<{
+    messages: DecryptedMessage[];
+    hasMore: boolean;
+}>;
+/**
+ * Send a batch of encrypted messages using v3 API.
+ */
+declare function sendMessagesBatch(config: Config, creds: Credentials, sessionId: string, encryption: SessionEncryption, contents: unknown[]): Promise<V3PostMessagesResponse>;
+type RawMachine = {
+    id: string;
+    metadata: string;
+    metadataVersion: number;
+    daemonState: string | null;
+    daemonStateVersion: number;
+    dataEncryptionKey: string | null;
+};
+/**
+ * Get or create a machine identity on the server.
+ * Returns the machine with decrypted metadata.
+ */
+declare function getOrCreateMachine(config: Config, creds: Credentials, metadata: MachineMetadata): Promise<Machine>;
+/**
+ * List all machines for the current account.
+ */
+declare function listMachines(config: Config, creds: Credentials): Promise<RawMachine[]>;
+
+/**
+ * Common RPC types and interfaces for both session and machine clients.
+ * Mirrors happy-cli/src/api/rpc/types.ts
+ */
+/**
+ * Generic RPC handler function type
+ */
+type RpcHandler<TRequest = any, TResponse = any> = (data: TRequest) => TResponse | Promise<TResponse>;
+/**
+ * RPC request data from server
+ */
+interface RpcRequest {
+    method: string;
+    params: string;
+}
+/**
+ * Configuration for RPC handler manager
+ */
+interface RpcHandlerConfig {
+    scopePrefix: string;
+    encryptionKey: Uint8Array;
+    encryptionVariant: "legacy" | "dataKey";
+    logger?: (message: string, data?: unknown) => void;
+}
+
+/**
+ * Generic RPC handler manager for session and machine clients.
+ * Manages RPC method registration, encryption/decryption, and handler execution.
+ *
+ * Adapted from happy-cli/src/api/rpc/RpcHandlerManager.ts with
+ * Agent-local imports (no @/ path alias).
+ */
+
+declare class RpcHandlerManager {
+    private handlers;
+    private readonly scopePrefix;
+    private readonly encryptionKey;
+    private readonly encryptionVariant;
+    private readonly logger;
+    private socket;
+    private reregisterInterval;
+    constructor(config: RpcHandlerConfig);
+    /**
+     * Register an RPC handler for a specific method
+     */
+    registerHandler<TRequest = any, TResponse = any>(method: string, handler: RpcHandler<TRequest, TResponse>): void;
+    /**
+     * Handle an incoming RPC request
+     */
+    handleRequest(request: RpcRequest): Promise<string>;
+    onSocketConnect(socket: Socket): void;
+    onSocketDisconnect(): void;
+    getHandlerCount(): number;
+    hasHandler(method: string): boolean;
+    clearHandlers(): void;
+    /**
+     * Register a single method with ack + retry.
+     * Falls back to fire-and-forget emit after all retries exhausted.
+     */
+    private emitRegisterWithRetry;
+    private registerAllHandlers;
+    /**
+     * Periodic re-registration every 60s as a safety net.
+     */
+    private startReregisterInterval;
+    private stopReregisterInterval;
+    private getPrefixedMethod;
+}
+declare function createRpcHandlerManager(config: RpcHandlerConfig): RpcHandlerManager;
+
+/**
+ * Enhanced session WebSocket client with RPC support.
+ *
+ * Improvements over the original session.ts:
+ * - RPC handler integration (bash, readFile, writeFile via RpcHandlerManager)
+ * - keepAlive with thinking state
+ * - updateMetadata / updateAgentState with OCC backoff
+ * - Typed socket events
+ *
+ * All existing public API is preserved for backward compatibility.
+ */
+
+type SessionClientOptions = {
+    readonly sessionId: string;
+    readonly encryptionKey: Uint8Array;
+    readonly encryptionVariant: EncryptionVariant;
+    readonly token: string;
+    readonly serverUrl: string;
+    readonly initialAgentState?: unknown | null;
+    /** Working directory for RPC handlers (bash cwd, file operations). Defaults to process.cwd(). */
+    readonly workingDirectory?: string;
+    /** Set to false to disable automatic RPC handler registration. Default: true */
+    readonly enableRpc?: boolean;
+};
+declare class SessionClient extends EventEmitter {
+    readonly sessionId: string;
+    readonly rpcHandlerManager: RpcHandlerManager;
+    private readonly encryptionKey;
+    private readonly encryptionVariant;
+    private socket;
+    private metadata;
+    private metadataVersion;
+    private agentState;
+    private agentStateVersion;
+    private aliveInterval;
+    private thinking;
+    constructor(opts: SessionClientOptions);
+    sendMessage(text: string, meta?: Record<string, unknown>): void;
+    getMetadata(): unknown | null;
+    getAgentState(): unknown | null;
+    setThinking(thinking: boolean): void;
+    waitForConnect(timeoutMs?: number): Promise<void>;
+    waitForIdle(timeoutMs?: number): Promise<void>;
+    sendStop(): void;
+    close(): void;
+    updateMetadata(newMetadata: unknown): Promise<void>;
+    updateAgentState(newState: unknown | null): Promise<void>;
+    private setupSocketListeners;
+}
+
+/**
+ * Machine WebSocket client — trimmed from CLI's ApiMachineClient.
+ *
+ * Core capabilities retained:
+ * - Machine-scoped Socket.IO connection
+ * - RPC handler registration (via RpcHandlerManager)
+ * - keepAlive heartbeat
+ * - updateMetadata / updateDaemonState with OCC backoff
+ * - Ephemeral event handling (webhook/supervisor triggers)
+ *
+ * Removed (CLI-only):
+ * - Webhook/supervisor status emit + pending queues
+ * - Fix kill handler
+ * - CLI-specific logging (debugLargeJson)
+ */
+
+type MachineClientOptions = {
+    readonly token: string;
+    readonly machine: Machine;
+    readonly serverUrl: string;
+    /** Working directory for RPC handlers. Defaults to process.cwd(). */
+    readonly workingDirectory?: string;
+    /** Handler for ephemeral events from server. */
+    readonly onEphemeral?: (data: {
+        type: string;
+        [key: string]: unknown;
+    }) => void;
+};
+declare class MachineClient {
+    readonly machine: Machine;
+    readonly rpcHandlerManager: RpcHandlerManager;
+    private socket;
+    private keepAliveInterval;
+    private readonly token;
+    private readonly serverUrl;
+    private readonly onEphemeral?;
+    constructor(opts: MachineClientOptions);
+    connect(): void;
+    updateMachineMetadata(handler: (metadata: MachineMetadata | null) => MachineMetadata): Promise<void>;
+    updateDaemonState(handler: (state: DaemonState | null) => DaemonState): Promise<void>;
+    shutdown(): void;
+    private startKeepAlive;
+    private stopKeepAlive;
+}
+
+export { MachineClient, RpcHandlerManager, SessionClient, authLogin, authLogout, authStatus, createRpcHandlerManager, createSession, deleteSession, fetchMessagesAfterSeq, getOrCreateMachine, getSessionMessages, listActiveSessions, listMachines, listSessions, loadConfig, readCredentials, requireCredentials, resolveSessionEncryption, sendMessagesBatch };
+export type { Config, Credentials, DecryptedMessage, DecryptedSession, EncryptionVariant, MachineClientOptions, RpcHandler, RpcHandlerConfig, SessionClientOptions, SessionEncryption };