@kmmao/happy-agent 0.4.1 → 0.5.0

package/dist/index.d.cts

@@ -399,17 +399,26 @@ interface SchedulerStatus {
         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. */
@@ -429,6 +438,179 @@ declare class AutomationScheduler {
     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.
  *
@@ -516,8 +698,12 @@ declare class MachineClient {
     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>;
@@ -579,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, scheduler: AutomationScheduler): 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

@@ -399,17 +399,26 @@ interface SchedulerStatus {
         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. */
@@ -429,6 +438,179 @@ declare class AutomationScheduler {
     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.
  *
@@ -516,8 +698,12 @@ declare class MachineClient {
     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>;
@@ -579,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, scheduler: AutomationScheduler): 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. */