@mclawnet/swarm 0.1.13 → 0.1.14

package/dist/always-on/always-on-manager.d.ts

@@ -0,0 +1,170 @@
+import type { AlwaysOnSnapshot, AlwaysOnTickRecord } from "@mclawnet/shared";
+import { WorkCycleRunner, type TaskRef } from "./workcycle-runner.js";
+import type { TaskSource } from "./task-sources/types.js";
+import type { TaskStore } from "@mclawnet/task";
+import { type AlwaysOnConfig, type AlwaysOnPersistedConfig } from "./config.js";
+import type { SwarmCoordinator } from "../swarm-coordinator.js";
+export interface AlwaysOnManagerOptions {
+    home: string;
+    swarmCoordinator: SwarmCoordinator;
+    /**
+     * Picks the next task for a given project; null = nothing actionable.
+     * Backwards-compat (M7) single-source DI. When `taskSources` is also
+     * provided the cascade picker takes precedence — `pickNextTask` is then
+     * ignored, but kept in the type for callers that still pass it.
+     */
+    pickNextTask?: (projectRoot: string) => Promise<TaskRef | null>;
+    /**
+     * M8.0 cascade source list. When provided the manager builds a
+     * CascadePicker over these sources and wires it into the runner with the
+     * source lifecycle hooks active. When omitted, falls back to the M7
+     * single-source `pickNextTask` DI above (or a TaskStore-backed source
+     * when `taskStore` is provided).
+     */
+    taskSources?: TaskSource[];
+    /**
+     * Convenience: when neither `pickNextTask` nor `taskSources` is provided
+     * but a TaskStore factory is, the manager auto-wraps it into a default
+     * single-source cascade. Lets the agent pass just the store factory and
+     * get the same picking behaviour as M7.
+     */
+    taskStore?: (projectRoot: string) => TaskStore | undefined;
+    /** Optional clock injection for tests. */
+    now?: () => Date;
+    /** Override the user-active window (tests). */
+    userActiveWindowMs?: number;
+    /** Override the log rotation byte cap (tests). */
+    logRotateBytes?: number;
+    /**
+     * Construct a WorkCycleRunner. Defaults to a real runner bound to the
+     * shared SwarmCoordinator + provided pickNextTask. Test-only override.
+     */
+    runnerFactory?: (workDir: string) => WorkCycleRunner;
+}
+export declare class AlwaysOnManager {
+    private readonly home;
+    private readonly swarmCoordinator;
+    private readonly pickNextTask;
+    private readonly cascadePicker;
+    /**
+     * R3 I-B — kept around so `drainPending(workDir)` can iterate sources
+     * BEFORE the cascade runs each tick. The cascade picker itself only
+     * exposes filtered-pick semantics; the drain must bypass the filter so
+     * a source whose toggle was flipped off mid-flight still gets to reap
+     * its in-flight work.
+     */
+    private readonly taskSources;
+    private readonly now;
+    private readonly userActiveWindowMs;
+    private readonly logRotateBytes;
+    private readonly runnerFactory?;
+    private readonly entries;
+    constructor(opts: AlwaysOnManagerOptions);
+    /**
+     * Boot (or rebuild) the scheduler for one project. Loads config from disk;
+     * restores ticksToday/lastFireAt when the persisted date matches today; if
+     * mode === "off", the scheduler is created but left stopped (cheap, lets
+     * `applyConfig` flip the switch later without re-instantiating).
+     *
+     * Idempotent: calling start() twice for the same project rebuilds; the old
+     * scheduler is stopped first to avoid duplicate timers.
+     */
+    start(workDir: string): Promise<void>;
+    /** Stop the scheduler for a project and drop the entry. Idempotent. */
+    stop(workDir: string): Promise<void>;
+    /**
+     * Returns the live snapshot serialised to the wire format (Date → ISO),
+     * or null when no scheduler is booted for the project.
+     */
+    snapshot(workDir: string): AlwaysOnSnapshot | null;
+    /**
+     * Re-sync the live scheduler with whatever's on disk right now (M7.3).
+     * The M7.2 projects-handler already does load→merge→save, then calls our
+     * hook with the new config. Rather than re-doing the persistence here we
+     * just pull the canonical state off disk and push it into the scheduler.
+     * Auto-boots if the project never started; idempotent otherwise.
+     */
+    refreshFromDisk(workDir: string): Promise<void>;
+    /**
+     * Apply a config patch: merges over the persisted baseline, writes it back,
+     * updates the live scheduler in place. Auto-boots the scheduler when the
+     * project has never been started (UI may flip a mode on a fresh project).
+     *
+     * Returns the merged config and the post-update snapshot so callers can
+     * hand both back to the UI in one round trip.
+     */
+    applyConfig(workDir: string, patch: Omit<Partial<AlwaysOnConfig>, "pausedUntil"> & {
+        pausedUntil?: string | null;
+        lastIntrospectionAt?: string | null;
+        lastIntrospectionRejected?: boolean | null;
+        pendingIntrospectionSwarmId?: string | null;
+        pendingIntrospectionWorkspaceCwd?: string | null;
+    }): Promise<{
+        config: AlwaysOnPersistedConfig;
+        snapshot: AlwaysOnSnapshot;
+    }>;
+    /**
+     * Record agent activity for the userActive gate. S1 hotfix: scoped per
+     * project. Pass `workDir` to update one project only; omit (or pass null)
+     * to broadcast to every entry — preserves the old global behaviour for
+     * callers that can't resolve a workDir from an inbound hub frame.
+     */
+    recordActivity(workDir?: string | null): void;
+    /**
+     * B6 — force a tick immediately, clearing the per-project userActive
+     * timestamp first so the gate cascade doesn't skip on "user active <30min
+     * ago". Dev-only entrypoint: the hub gates the corresponding HTTP route on
+     * `NODE_ENV !== "production"` so this never reaches the agent in prod.
+     *
+     * Returns the TickRecord (decision + gateBreakdown + durationMs) and the
+     * post-tick snapshot in one call so the caller can show in dev tooling
+     * whether the force-tick fired or still skipped (e.g. on a real
+     * pausedUntil that genuinely should block).
+     *
+     * Note: only `lastActivityAt` is cleared. Other gates (pausedUntil,
+     * dailyBudget) intentionally still apply — force-tick is for bypassing
+     * the "I'm typing, don't fire" UX gate, not the user's explicit pause or
+     * the daily budget. Throws when no scheduler is booted for the project.
+     */
+    forceTick(workDir: string): Promise<{
+        record: AlwaysOnTickRecord;
+        snapshot: AlwaysOnSnapshot;
+    }>;
+    /** Stop every per-project scheduler. Called on agent shutdown. */
+    disposeAll(): Promise<void>;
+    /**
+     * R3 I-B — public test/ops hook. Invokes `drainPending(workDir)` on every
+     * TaskSource that defines it, regardless of whether its toggle is on. This
+     * is the same drain that runs automatically inside `onFire` before each
+     * tick; exposed publicly so:
+     *   - tests can simulate "user toggled off mid-flight → next tick reaps
+     *     cleanly" without driving the scheduler timer, and
+     *   - future ops surfaces (admin reseed, manual reconcile) can request a
+     *     drain pass without firing a work cycle.
+     * Failures inside a single source are logged and swallowed — one source's
+     * drain must not break the manager's tick loop.
+     */
+    drainAllSources(workDir: string): Promise<void>;
+    /**
+     * Hotfix C1 — map a TaskSource onto its taskSources toggle flag and
+     * resolve against the project's persisted config. Unknown source names
+     * default to enabled so non-standard sources (e.g. tests, future M9
+     * sources not yet listed in `AlwaysOnTaskSourcesConfig`) aren't silently
+     * dropped. Called fresh per pick by the cascade picker filter, so toggling
+     * a source on/off in the UI takes effect on the very next tick — no
+     * scheduler/picker rebuild required (the JSON read is cheap compared to a
+     * swarm spawn).
+     */
+    private isSourceEnabledForProject;
+    /** User-facing gates: pausedUntil + userActive. */
+    private buildGates;
+    /**
+     * Persist ticksToday/lastFireAt AND append a jsonl line to always-on.log.
+     * Hooked into DiscoveryScheduler.onTick so every fired / skipped / halted
+     * decision is captured. Best-effort — write failures are logged but never
+     * thrown back into the scheduler tick loop.
+     */
+    private onTick;
+    private appendLog;
+}
+//# sourceMappingURL=always-on-manager.d.ts.map

package/dist/always-on/always-on-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"always-on-manager.d.ts","sourceRoot":"","sources":["../../src/always-on/always-on-manager.ts"],"names":[],"mappings":"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"}