@kmmao/happy-agent 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -345,6 +345,272 @@ 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;
+    }>;
+}
+type AuditCallback = (event: {
+    kind: "job_enqueued" | "job_dispatched" | "job_completed" | "job_failed" | "job_retried";
+    jobId: string;
+    dedupeKey: string;
+    message?: string;
+    errorMessage?: string;
+}) => void;
+interface SchedulerOptions {
+    maxConcurrentJobs?: number;
+    retryDelayMs?: number;
+    maxAttempts?: number;
+    maxRecentCompletions?: number;
+    onAudit?: AuditCallback;
+}
+declare class AutomationScheduler {
+    private readonly maxConcurrentJobs;
+    private readonly retryDelayMs;
+    private readonly defaultMaxAttempts;
+    private readonly maxRecentCompletions;
+    private readonly onAudit;
+    /** 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;
+}
+
+/**
+ * GuardianSessionRegistry — session reuse for recurring automation.
+ *
+ * When a loop or supervisor trigger spawns a session, the registry
+ * remembers which Happy session ID was used. On subsequent runs,
+ * it resolves the existing session so the spawner can --resume it
+ * instead of creating a fresh session every iteration.
+ *
+ * Key hierarchy: loop:{loopId} > project:{projectId}
+ *
+ * In-memory only — no file persistence (daemon restart = fresh).
+ */
+interface GuardianEntry {
+    readonly key: string;
+    sessionId: string;
+    loopId?: string;
+    projectId?: string;
+    updatedAt: number;
+}
+interface ResolveInput {
+    loopId?: string;
+    projectId?: string;
+}
+declare class GuardianSessionRegistry {
+    private readonly entries;
+    /**
+     * Find an existing session to reuse.
+     * Tries loop key first, then project key.
+     */
+    resolve(input: ResolveInput): string | null;
+    /**
+     * Remember a session for future reuse.
+     * Stores under both loop and project keys if available.
+     */
+    remember(sessionId: string, input: ResolveInput): void;
+    /**
+     * Forget a specific session (e.g., after it exits).
+     */
+    forgetSession(sessionId: string): number;
+    /**
+     * Forget all entries for a loop.
+     */
+    forgetLoop(loopId: string): boolean;
+    /**
+     * Get all entries (for observability).
+     */
+    getSnapshot(): GuardianEntry[];
+    /**
+     * Number of tracked guardian entries.
+     */
+    get size(): number;
+}
+
+/**
+ * AgentLoopCoordinator — lightweight loop scheduler for agent daemon.
+ *
+ * A "loop" is a recurring autonomous task: run a prompt in a directory
+ * at a fixed interval. The coordinator polls every second, enqueues
+ * due loops into the AutomationScheduler, and tracks iteration state.
+ *
+ * Simplified from CLI's full coordinator — no cron, quiet hours,
+ * downstream chains, notifications, or memory snapshots.
+ */
+
+type LoopState = "idle" | "active" | "paused" | "blocked";
+interface AgentLoop {
+    readonly id: string;
+    readonly name: string;
+    readonly prompt: string;
+    readonly directory: string;
+    readonly intervalMs: number;
+    readonly createdAt: number;
+    state: LoopState;
+    iteration: number;
+    nextRunAt: number;
+    lastStartedAt?: number;
+    lastCompletedAt?: number;
+    activeJobId?: string;
+    consecutiveFailures: number;
+    maxConsecutiveFailures: number;
+    maxIterations: number;
+    errorMessage?: string;
+}
+interface CreateLoopInput {
+    name: string;
+    prompt: string;
+    directory: string;
+    intervalMs: number;
+    maxConsecutiveFailures?: number;
+    maxIterations?: number;
+}
+interface LoopSummary {
+    id: string;
+    name: string;
+    state: LoopState;
+    iteration: number;
+    intervalMs: number;
+    nextRunAt: number;
+    lastCompletedAt?: number;
+}
+declare class AgentLoopCoordinator {
+    private readonly loops;
+    private readonly scheduler;
+    private readonly serverUrl;
+    private readonly authToken;
+    private readonly guardian;
+    private tickTimer;
+    constructor(scheduler: AutomationScheduler, serverUrl: string, authToken: string, guardian?: GuardianSessionRegistry);
+    start(): void;
+    shutdown(): void;
+    createLoop(input: CreateLoopInput): AgentLoop;
+    getLoop(id: string): AgentLoop | undefined;
+    listLoops(): LoopSummary[];
+    pauseLoop(id: string): boolean;
+    resumeLoop(id: string): boolean;
+    deleteLoop(id: string): boolean;
+    onJobTerminal(loopId: string, status: "completed" | "failed", errorMessage?: string): void;
+    private tick;
+    private enqueueLoop;
+}
+
+/**
+ * AutomationAuditStore — in-memory ring buffer for automation events.
+ *
+ * Records job lifecycle events (enqueued, started, completed, failed)
+ * for observability. Capped at maxEntries to prevent unbounded growth.
+ * Queryable via RPC for dashboard / debugging.
+ */
+type AuditEventKind = "job_enqueued" | "job_dispatched" | "job_completed" | "job_failed" | "job_retried" | "loop_started" | "loop_blocked" | "loop_paused";
+interface AuditEvent {
+    readonly id: number;
+    readonly kind: AuditEventKind;
+    readonly timestamp: number;
+    readonly jobId?: string;
+    readonly dedupeKey?: string;
+    readonly loopId?: string;
+    readonly loopName?: string;
+    readonly status?: string;
+    readonly message?: string;
+    readonly errorMessage?: string;
+}
+interface AuditQuery {
+    kind?: AuditEventKind;
+    loopId?: string;
+    limit?: number;
+    since?: number;
+}
+interface AuditStorOptions {
+    maxEntries?: number;
+}
+declare class AutomationAuditStore {
+    private readonly maxEntries;
+    private readonly events;
+    private nextId;
+    constructor(options?: AuditStorOptions);
+    /**
+     * Record an audit event.
+     */
+    record(event: Omit<AuditEvent, "id" | "timestamp">): AuditEvent;
+    /**
+     * Query events with optional filters.
+     */
+    query(filter?: AuditQuery): AuditEvent[];
+    /**
+     * Summary counts by kind.
+     */
+    summarize(): Record<AuditEventKind, number>;
+    /**
+     * Total number of stored events.
+     */
+    get size(): number;
+}
+
 /**
  * Machine WebSocket client — trimmed from CLI's ApiMachineClient.
  *
@@ -431,8 +697,13 @@ declare class MachineClient {
     private automationEnabled;
     private automationServerUrl;
     private automationAuthToken;
+    private scheduler;
+    private loopCoordinator;
+    private auditStore;
     constructor(opts: MachineClientOptions);
     private registerMachineHandlers;
+    private registerLoopHandlers;
+    private registerAuditHandlers;
     connect(): void;
     updateMachineMetadata(handler: (metadata: MachineMetadata | null) => MachineMetadata): Promise<void>;
     updateDaemonState(handler: (state: DaemonState | null) => DaemonState): Promise<void>;
@@ -494,7 +765,7 @@ declare class MachineClient {
      * 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;
+    enableAutomation(serverUrl: string, authToken: string, scheduler: AutomationScheduler, loopCoordinator?: AgentLoopCoordinator, auditStore?: AutomationAuditStore): void;
     /** Internal dispatch for ephemeral events that need automation handling. */
     private handleAutomationEvent;
     /** Seed initial Tailscale info detected before connect. */

package/dist/index.d.mts

@@ -345,6 +345,272 @@ 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;
+    }>;
+}
+type AuditCallback = (event: {
+    kind: "job_enqueued" | "job_dispatched" | "job_completed" | "job_failed" | "job_retried";
+    jobId: string;
+    dedupeKey: string;
+    message?: string;
+    errorMessage?: string;
+}) => void;
+interface SchedulerOptions {
+    maxConcurrentJobs?: number;
+    retryDelayMs?: number;
+    maxAttempts?: number;
+    maxRecentCompletions?: number;
+    onAudit?: AuditCallback;
+}
+declare class AutomationScheduler {
+    private readonly maxConcurrentJobs;
+    private readonly retryDelayMs;
+    private readonly defaultMaxAttempts;
+    private readonly maxRecentCompletions;
+    private readonly onAudit;
+    /** 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;
+}
+
+/**
+ * GuardianSessionRegistry — session reuse for recurring automation.
+ *
+ * When a loop or supervisor trigger spawns a session, the registry
+ * remembers which Happy session ID was used. On subsequent runs,
+ * it resolves the existing session so the spawner can --resume it
+ * instead of creating a fresh session every iteration.
+ *
+ * Key hierarchy: loop:{loopId} > project:{projectId}
+ *
+ * In-memory only — no file persistence (daemon restart = fresh).
+ */
+interface GuardianEntry {
+    readonly key: string;
+    sessionId: string;
+    loopId?: string;
+    projectId?: string;
+    updatedAt: number;
+}
+interface ResolveInput {
+    loopId?: string;
+    projectId?: string;
+}
+declare class GuardianSessionRegistry {
+    private readonly entries;
+    /**
+     * Find an existing session to reuse.
+     * Tries loop key first, then project key.
+     */
+    resolve(input: ResolveInput): string | null;
+    /**
+     * Remember a session for future reuse.
+     * Stores under both loop and project keys if available.
+     */
+    remember(sessionId: string, input: ResolveInput): void;
+    /**
+     * Forget a specific session (e.g., after it exits).
+     */
+    forgetSession(sessionId: string): number;
+    /**
+     * Forget all entries for a loop.
+     */
+    forgetLoop(loopId: string): boolean;
+    /**
+     * Get all entries (for observability).
+     */
+    getSnapshot(): GuardianEntry[];
+    /**
+     * Number of tracked guardian entries.
+     */
+    get size(): number;
+}
+
+/**
+ * AgentLoopCoordinator — lightweight loop scheduler for agent daemon.
+ *
+ * A "loop" is a recurring autonomous task: run a prompt in a directory
+ * at a fixed interval. The coordinator polls every second, enqueues
+ * due loops into the AutomationScheduler, and tracks iteration state.
+ *
+ * Simplified from CLI's full coordinator — no cron, quiet hours,
+ * downstream chains, notifications, or memory snapshots.
+ */
+
+type LoopState = "idle" | "active" | "paused" | "blocked";
+interface AgentLoop {
+    readonly id: string;
+    readonly name: string;
+    readonly prompt: string;
+    readonly directory: string;
+    readonly intervalMs: number;
+    readonly createdAt: number;
+    state: LoopState;
+    iteration: number;
+    nextRunAt: number;
+    lastStartedAt?: number;
+    lastCompletedAt?: number;
+    activeJobId?: string;
+    consecutiveFailures: number;
+    maxConsecutiveFailures: number;
+    maxIterations: number;
+    errorMessage?: string;
+}
+interface CreateLoopInput {
+    name: string;
+    prompt: string;
+    directory: string;
+    intervalMs: number;
+    maxConsecutiveFailures?: number;
+    maxIterations?: number;
+}
+interface LoopSummary {
+    id: string;
+    name: string;
+    state: LoopState;
+    iteration: number;
+    intervalMs: number;
+    nextRunAt: number;
+    lastCompletedAt?: number;
+}
+declare class AgentLoopCoordinator {
+    private readonly loops;
+    private readonly scheduler;
+    private readonly serverUrl;
+    private readonly authToken;
+    private readonly guardian;
+    private tickTimer;
+    constructor(scheduler: AutomationScheduler, serverUrl: string, authToken: string, guardian?: GuardianSessionRegistry);
+    start(): void;
+    shutdown(): void;
+    createLoop(input: CreateLoopInput): AgentLoop;
+    getLoop(id: string): AgentLoop | undefined;
+    listLoops(): LoopSummary[];
+    pauseLoop(id: string): boolean;
+    resumeLoop(id: string): boolean;
+    deleteLoop(id: string): boolean;
+    onJobTerminal(loopId: string, status: "completed" | "failed", errorMessage?: string): void;
+    private tick;
+    private enqueueLoop;
+}
+
+/**
+ * AutomationAuditStore — in-memory ring buffer for automation events.
+ *
+ * Records job lifecycle events (enqueued, started, completed, failed)
+ * for observability. Capped at maxEntries to prevent unbounded growth.
+ * Queryable via RPC for dashboard / debugging.
+ */
+type AuditEventKind = "job_enqueued" | "job_dispatched" | "job_completed" | "job_failed" | "job_retried" | "loop_started" | "loop_blocked" | "loop_paused";
+interface AuditEvent {
+    readonly id: number;
+    readonly kind: AuditEventKind;
+    readonly timestamp: number;
+    readonly jobId?: string;
+    readonly dedupeKey?: string;
+    readonly loopId?: string;
+    readonly loopName?: string;
+    readonly status?: string;
+    readonly message?: string;
+    readonly errorMessage?: string;
+}
+interface AuditQuery {
+    kind?: AuditEventKind;
+    loopId?: string;
+    limit?: number;
+    since?: number;
+}
+interface AuditStorOptions {
+    maxEntries?: number;
+}
+declare class AutomationAuditStore {
+    private readonly maxEntries;
+    private readonly events;
+    private nextId;
+    constructor(options?: AuditStorOptions);
+    /**
+     * Record an audit event.
+     */
+    record(event: Omit<AuditEvent, "id" | "timestamp">): AuditEvent;
+    /**
+     * Query events with optional filters.
+     */
+    query(filter?: AuditQuery): AuditEvent[];
+    /**
+     * Summary counts by kind.
+     */
+    summarize(): Record<AuditEventKind, number>;
+    /**
+     * Total number of stored events.
+     */
+    get size(): number;
+}
+
 /**
  * Machine WebSocket client — trimmed from CLI's ApiMachineClient.
  *
@@ -431,8 +697,13 @@ declare class MachineClient {
     private automationEnabled;
     private automationServerUrl;
     private automationAuthToken;
+    private scheduler;
+    private loopCoordinator;
+    private auditStore;
     constructor(opts: MachineClientOptions);
     private registerMachineHandlers;
+    private registerLoopHandlers;
+    private registerAuditHandlers;
     connect(): void;
     updateMachineMetadata(handler: (metadata: MachineMetadata | null) => MachineMetadata): Promise<void>;
     updateDaemonState(handler: (state: DaemonState | null) => DaemonState): Promise<void>;
@@ -494,7 +765,7 @@ declare class MachineClient {
      * 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;
+    enableAutomation(serverUrl: string, authToken: string, scheduler: AutomationScheduler, loopCoordinator?: AgentLoopCoordinator, auditStore?: AutomationAuditStore): void;
     /** Internal dispatch for ephemeral events that need automation handling. */
     private handleAutomationEvent;
     /** Seed initial Tailscale info detected before connect. */