@kmmao/happy-agent 0.3.11 → 0.4.1

package/dist/index.d.cts

@@ -345,6 +345,90 @@ declare class TunnelManager {
     stopRefresh(): void;
 }
 
+/**
+ * AutomationScheduler — lightweight in-memory job queue for agent triggers.
+ *
+ * Features:
+ * - Priority queue (urgent > user > background)
+ * - dedupeKey deduplication (queued/dispatching/running)
+ * - Concurrency limit (maxConcurrentJobs)
+ * - Retry with incremental backoff (attempt * retryDelayMs)
+ * - Ring buffer for recent completions (observability)
+ */
+type JobPriority = "urgent" | "user" | "background";
+type JobStatus = "queued" | "dispatching" | "running" | "completed" | "failed";
+interface SchedulerJob {
+    readonly id: string;
+    readonly kind: "webhook" | "supervisor" | "task";
+    readonly dedupeKey: string;
+    readonly priority: JobPriority;
+    status: JobStatus;
+    attempt: number;
+    readonly maxAttempts: number;
+    readonly createdAt: number;
+    updatedAt: number;
+    nextRunAt: number;
+    errorMessage?: string;
+    pid?: number;
+    /** The thunk that performs the actual work (spawn session etc.) */
+    readonly run: (jobId: string) => Promise<{
+        pid: number;
+    }>;
+}
+interface EnqueueOptions {
+    kind: SchedulerJob["kind"];
+    dedupeKey: string;
+    priority: JobPriority;
+    run: (jobId: string) => Promise<{
+        pid: number;
+    }>;
+}
+interface EnqueueResult {
+    job: SchedulerJob;
+    deduped: boolean;
+}
+interface SchedulerStatus {
+    queueLength: number;
+    runningCount: number;
+    recentCompletions: Array<{
+        id: string;
+        kind: string;
+        dedupeKey: string;
+        status: "completed" | "failed";
+        completedAt: number;
+        errorMessage?: string;
+    }>;
+}
+interface SchedulerOptions {
+    maxConcurrentJobs?: number;
+    retryDelayMs?: number;
+    maxAttempts?: number;
+    maxRecentCompletions?: number;
+}
+declare class AutomationScheduler {
+    private readonly maxConcurrentJobs;
+    private readonly retryDelayMs;
+    private readonly defaultMaxAttempts;
+    private readonly maxRecentCompletions;
+    /** Active jobs indexed by id. */
+    private readonly jobs;
+    /** dedupeKey → jobId for fast dedup lookups. */
+    private readonly dedupeIndex;
+    /** Ring buffer for completed/failed jobs. */
+    private readonly recentCompletions;
+    private pumpTimer;
+    private pumping;
+    constructor(options?: SchedulerOptions);
+    enqueue(opts: EnqueueOptions): EnqueueResult;
+    markCompleted(jobId: string): void;
+    markFailed(jobId: string, error: string): void;
+    getStatus(): SchedulerStatus;
+    shutdown(): void;
+    private pump;
+    private dispatch;
+    private finalize;
+}
+
 /**
  * Machine WebSocket client — trimmed from CLI's ApiMachineClient.
  *
@@ -361,17 +445,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 +509,79 @@ 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;
+    private scheduler;
     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, scheduler: AutomationScheduler): 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 +593,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

@@ -345,6 +345,90 @@ declare class TunnelManager {
     stopRefresh(): void;
 }
 
+/**
+ * AutomationScheduler — lightweight in-memory job queue for agent triggers.
+ *
+ * Features:
+ * - Priority queue (urgent > user > background)
+ * - dedupeKey deduplication (queued/dispatching/running)
+ * - Concurrency limit (maxConcurrentJobs)
+ * - Retry with incremental backoff (attempt * retryDelayMs)
+ * - Ring buffer for recent completions (observability)
+ */
+type JobPriority = "urgent" | "user" | "background";
+type JobStatus = "queued" | "dispatching" | "running" | "completed" | "failed";
+interface SchedulerJob {
+    readonly id: string;
+    readonly kind: "webhook" | "supervisor" | "task";
+    readonly dedupeKey: string;
+    readonly priority: JobPriority;
+    status: JobStatus;
+    attempt: number;
+    readonly maxAttempts: number;
+    readonly createdAt: number;
+    updatedAt: number;
+    nextRunAt: number;
+    errorMessage?: string;
+    pid?: number;
+    /** The thunk that performs the actual work (spawn session etc.) */
+    readonly run: (jobId: string) => Promise<{
+        pid: number;
+    }>;
+}
+interface EnqueueOptions {
+    kind: SchedulerJob["kind"];
+    dedupeKey: string;
+    priority: JobPriority;
+    run: (jobId: string) => Promise<{
+        pid: number;
+    }>;
+}
+interface EnqueueResult {
+    job: SchedulerJob;
+    deduped: boolean;
+}
+interface SchedulerStatus {
+    queueLength: number;
+    runningCount: number;
+    recentCompletions: Array<{
+        id: string;
+        kind: string;
+        dedupeKey: string;
+        status: "completed" | "failed";
+        completedAt: number;
+        errorMessage?: string;
+    }>;
+}
+interface SchedulerOptions {
+    maxConcurrentJobs?: number;
+    retryDelayMs?: number;
+    maxAttempts?: number;
+    maxRecentCompletions?: number;
+}
+declare class AutomationScheduler {
+    private readonly maxConcurrentJobs;
+    private readonly retryDelayMs;
+    private readonly defaultMaxAttempts;
+    private readonly maxRecentCompletions;
+    /** Active jobs indexed by id. */
+    private readonly jobs;
+    /** dedupeKey → jobId for fast dedup lookups. */
+    private readonly dedupeIndex;
+    /** Ring buffer for completed/failed jobs. */
+    private readonly recentCompletions;
+    private pumpTimer;
+    private pumping;
+    constructor(options?: SchedulerOptions);
+    enqueue(opts: EnqueueOptions): EnqueueResult;
+    markCompleted(jobId: string): void;
+    markFailed(jobId: string, error: string): void;
+    getStatus(): SchedulerStatus;
+    shutdown(): void;
+    private pump;
+    private dispatch;
+    private finalize;
+}
+
 /**
  * Machine WebSocket client — trimmed from CLI's ApiMachineClient.
  *
@@ -361,17 +445,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 +509,79 @@ 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;
+    private scheduler;
     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, scheduler: AutomationScheduler): 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 +593,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 };