@kmmao/happy-agent 0.3.11 → 0.4.0

package/dist/index.d.cts

@@ -361,17 +361,59 @@ declare class TunnelManager {
  * - CLI-specific logging (debugLargeJson)
  */
 
+/** Strongly-typed ephemeral event from server. */
+type EphemeralEvent = {
+    type: "activity";
+    id: string;
+    active: boolean;
+    activeAt: number;
+    thinking: boolean;
+} | {
+    type: "webhook-trigger";
+    webhookEventId: string;
+    issueNumber: number;
+    issueTitle: string;
+    issueBody: string;
+    issueAuthor: string;
+    issueLabels: string[];
+    issueUrl: string;
+    repoUrl: string;
+    repoPath: string;
+    provider: string;
+} | {
+    type: "supervisor-trigger";
+    projectId: string;
+    runId: string;
+    trigger: string;
+    machineId: string;
+    repoPath: string;
+    mode?: string;
+    dimensions?: string[];
+    changedFiles?: string[];
+    customRules?: string;
+} | {
+    type: "task-trigger";
+    taskId: string;
+    prompt: string;
+    directory: string;
+    priority: string;
+    projectId?: string;
+    resultToken?: string;
+    skillContents?: Array<{
+        name: string;
+        content: string;
+    }>;
+};
 type MachineClientOptions = {
     readonly token: string;
     readonly machine: Machine;
     readonly serverUrl: string;
+    /** Agent package version for DaemonState reporting. */
+    readonly agentVersion?: 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;
+    readonly onEphemeral?: (data: EphemeralEvent) => void;
 };
 declare class MachineClient {
     readonly machine: Machine;
@@ -383,11 +425,78 @@ declare class MachineClient {
     private tunnelManager;
     private readonly token;
     private readonly serverUrl;
+    private readonly agentVersion;
+    private readonly startTime;
     private readonly onEphemeral?;
+    private automationEnabled;
+    private automationServerUrl;
+    private automationAuthToken;
     constructor(opts: MachineClientOptions);
+    private registerMachineHandlers;
     connect(): void;
     updateMachineMetadata(handler: (metadata: MachineMetadata | null) => MachineMetadata): Promise<void>;
     updateDaemonState(handler: (state: DaemonState | null) => DaemonState): Promise<void>;
+    /** Emit a session lifecycle event. */
+    emitSessionEvent(sessionId: string, eventType: string, summary: string, detail?: Record<string, unknown>): void;
+    /** Report webhook processing status. */
+    emitWebhookStatus(data: {
+        webhookEventId: string;
+        status: "dispatched" | "completed" | "failed";
+        sessionId?: string;
+        errorMessage?: string;
+    }): void;
+    /** Report supervisor run status. */
+    emitSupervisorRunStatus(data: {
+        runId: string;
+        projectId: string;
+        status: "running" | "completed" | "failed";
+        sessionId?: string;
+        actionsCount?: number;
+        issuesCreated?: number;
+        errorMessage?: string;
+    }): void;
+    /** Submit a knowledge entry from a session. */
+    emitSubmitKnowledge(sid: string, entry: {
+        entryType: string;
+        contributorType: string;
+        action: string;
+        title: string;
+        content: string;
+        request?: string;
+        outcome?: string;
+        tags: string[];
+        confidence: string;
+        model?: string;
+        affectedFiles: string[];
+    }): void;
+    /** Fetch knowledge for a session. */
+    emitFetchKnowledge(sid: string, mode: "auto" | "full" | "minimal", contextHints: string[] | undefined, callback: (response: {
+        profile: {
+            techStack: string[];
+            architectureType?: string;
+            knownPitfalls: string[];
+            coreConventions: string[];
+            lastUpdatedAt: number;
+        } | null;
+        entries: {
+            id: string;
+            entryType: string;
+            title: string;
+            content: string;
+            tags: string[];
+            confidence: string;
+            createdAt: string;
+        }[];
+    }) => void): void;
+    /** Stream task log chunk. */
+    emitTaskLog(sid: string, taskId: string, outputFile: string, chunk: string, offset: number): void;
+    /**
+     * Enable automation handling — agent will process webhook, supervisor,
+     * and task triggers from the server by spawning Happy CLI sessions.
+     */
+    enableAutomation(serverUrl: string, authToken: string): void;
+    /** Internal dispatch for ephemeral events that need automation handling. */
+    private handleAutomationEvent;
     /** Seed initial Tailscale info detected before connect. */
     setTailscaleInfo(info: TailscaleInfo): void;
     /** Attach a TunnelManager for periodic tunnel state refresh. */
@@ -399,5 +508,26 @@ declare class MachineClient {
     private stopTailscaleRefresh;
 }
 
-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 };
+/**
+ * Daemon mode — persistent background process that connects to the server,
+ * registers RPC handlers, and processes automation triggers.
+ *
+ * Usage: happy-agent daemon start [--directory <dir>]
+ *
+ * The daemon:
+ * 1. Loads credentials and config
+ * 2. Registers/gets machine identity
+ * 3. Detects Tailscale and tunnel state
+ * 4. Creates MachineClient with all RPC handlers
+ * 5. Enables automation (webhook/supervisor/task triggers)
+ * 6. Runs until SIGTERM/SIGINT
+ */
+declare function startDaemon(options: {
+    directory?: string;
+    foreground?: boolean;
+}): Promise<void>;
+declare function stopDaemon(): void;
+declare function daemonStatus(): void;
+
+export { MachineClient, RpcHandlerManager, SessionClient, authLogin, authLogout, authStatus, createRpcHandlerManager, createSession, daemonStatus, deleteSession, fetchMessagesAfterSeq, getOrCreateMachine, getSessionMessages, listActiveSessions, listMachines, listSessions, loadConfig, readCredentials, requireCredentials, resolveSessionEncryption, sendMessagesBatch, startDaemon, stopDaemon };
+export type { Config, Credentials, DecryptedMessage, DecryptedSession, EncryptionVariant, EphemeralEvent, MachineClientOptions, RpcHandler, RpcHandlerConfig, SessionClientOptions, SessionEncryption };

package/dist/index.d.mts

@@ -361,17 +361,59 @@ declare class TunnelManager {
  * - CLI-specific logging (debugLargeJson)
  */
 
+/** Strongly-typed ephemeral event from server. */
+type EphemeralEvent = {
+    type: "activity";
+    id: string;
+    active: boolean;
+    activeAt: number;
+    thinking: boolean;
+} | {
+    type: "webhook-trigger";
+    webhookEventId: string;
+    issueNumber: number;
+    issueTitle: string;
+    issueBody: string;
+    issueAuthor: string;
+    issueLabels: string[];
+    issueUrl: string;
+    repoUrl: string;
+    repoPath: string;
+    provider: string;
+} | {
+    type: "supervisor-trigger";
+    projectId: string;
+    runId: string;
+    trigger: string;
+    machineId: string;
+    repoPath: string;
+    mode?: string;
+    dimensions?: string[];
+    changedFiles?: string[];
+    customRules?: string;
+} | {
+    type: "task-trigger";
+    taskId: string;
+    prompt: string;
+    directory: string;
+    priority: string;
+    projectId?: string;
+    resultToken?: string;
+    skillContents?: Array<{
+        name: string;
+        content: string;
+    }>;
+};
 type MachineClientOptions = {
     readonly token: string;
     readonly machine: Machine;
     readonly serverUrl: string;
+    /** Agent package version for DaemonState reporting. */
+    readonly agentVersion?: 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;
+    readonly onEphemeral?: (data: EphemeralEvent) => void;
 };
 declare class MachineClient {
     readonly machine: Machine;
@@ -383,11 +425,78 @@ declare class MachineClient {
     private tunnelManager;
     private readonly token;
     private readonly serverUrl;
+    private readonly agentVersion;
+    private readonly startTime;
     private readonly onEphemeral?;
+    private automationEnabled;
+    private automationServerUrl;
+    private automationAuthToken;
     constructor(opts: MachineClientOptions);
+    private registerMachineHandlers;
     connect(): void;
     updateMachineMetadata(handler: (metadata: MachineMetadata | null) => MachineMetadata): Promise<void>;
     updateDaemonState(handler: (state: DaemonState | null) => DaemonState): Promise<void>;
+    /** Emit a session lifecycle event. */
+    emitSessionEvent(sessionId: string, eventType: string, summary: string, detail?: Record<string, unknown>): void;
+    /** Report webhook processing status. */
+    emitWebhookStatus(data: {
+        webhookEventId: string;
+        status: "dispatched" | "completed" | "failed";
+        sessionId?: string;
+        errorMessage?: string;
+    }): void;
+    /** Report supervisor run status. */
+    emitSupervisorRunStatus(data: {
+        runId: string;
+        projectId: string;
+        status: "running" | "completed" | "failed";
+        sessionId?: string;
+        actionsCount?: number;
+        issuesCreated?: number;
+        errorMessage?: string;
+    }): void;
+    /** Submit a knowledge entry from a session. */
+    emitSubmitKnowledge(sid: string, entry: {
+        entryType: string;
+        contributorType: string;
+        action: string;
+        title: string;
+        content: string;
+        request?: string;
+        outcome?: string;
+        tags: string[];
+        confidence: string;
+        model?: string;
+        affectedFiles: string[];
+    }): void;
+    /** Fetch knowledge for a session. */
+    emitFetchKnowledge(sid: string, mode: "auto" | "full" | "minimal", contextHints: string[] | undefined, callback: (response: {
+        profile: {
+            techStack: string[];
+            architectureType?: string;
+            knownPitfalls: string[];
+            coreConventions: string[];
+            lastUpdatedAt: number;
+        } | null;
+        entries: {
+            id: string;
+            entryType: string;
+            title: string;
+            content: string;
+            tags: string[];
+            confidence: string;
+            createdAt: string;
+        }[];
+    }) => void): void;
+    /** Stream task log chunk. */
+    emitTaskLog(sid: string, taskId: string, outputFile: string, chunk: string, offset: number): void;
+    /**
+     * Enable automation handling — agent will process webhook, supervisor,
+     * and task triggers from the server by spawning Happy CLI sessions.
+     */
+    enableAutomation(serverUrl: string, authToken: string): void;
+    /** Internal dispatch for ephemeral events that need automation handling. */
+    private handleAutomationEvent;
     /** Seed initial Tailscale info detected before connect. */
     setTailscaleInfo(info: TailscaleInfo): void;
     /** Attach a TunnelManager for periodic tunnel state refresh. */
@@ -399,5 +508,26 @@ declare class MachineClient {
     private stopTailscaleRefresh;
 }
 
-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 };
+/**
+ * Daemon mode — persistent background process that connects to the server,
+ * registers RPC handlers, and processes automation triggers.
+ *
+ * Usage: happy-agent daemon start [--directory <dir>]
+ *
+ * The daemon:
+ * 1. Loads credentials and config
+ * 2. Registers/gets machine identity
+ * 3. Detects Tailscale and tunnel state
+ * 4. Creates MachineClient with all RPC handlers
+ * 5. Enables automation (webhook/supervisor/task triggers)
+ * 6. Runs until SIGTERM/SIGINT
+ */
+declare function startDaemon(options: {
+    directory?: string;
+    foreground?: boolean;
+}): Promise<void>;
+declare function stopDaemon(): void;
+declare function daemonStatus(): void;
+
+export { MachineClient, RpcHandlerManager, SessionClient, authLogin, authLogout, authStatus, createRpcHandlerManager, createSession, daemonStatus, deleteSession, fetchMessagesAfterSeq, getOrCreateMachine, getSessionMessages, listActiveSessions, listMachines, listSessions, loadConfig, readCredentials, requireCredentials, resolveSessionEncryption, sendMessagesBatch, startDaemon, stopDaemon };
+export type { Config, Credentials, DecryptedMessage, DecryptedSession, EncryptionVariant, EphemeralEvent, MachineClientOptions, RpcHandler, RpcHandlerConfig, SessionClientOptions, SessionEncryption };