@mono-agent/agent-app 0.19.1 → 0.20.1

package/dist/background-log-maintenance.d.ts

@@ -1,6 +1,89 @@
+import type { LaunchctlRunner, LaunchdPaths } from "./launchd.js";
+import type { LaunchdLogInspection } from "./launchd-logs.js";
 import type { PollOptions } from "./background-lifecycle-utils.js";
 import type { BackgroundDeps, BackgroundLifecycleTarget } from "./background.js";
+export interface ManagedLaunchdLogInspectionDependencies {
+    readonly inspectLaunchdLogs: (paths: Pick<LaunchdPaths, "logDir" | "stdoutPath" | "stderrPath">) => Promise<LaunchdLogInspection>;
+    readonly runner: LaunchctlRunner;
+    readonly getuid: () => number;
+    /** Monotonic clock: cooldown authority never depends on wall-clock movement. */
+    readonly monotonicNow?: () => number;
+    readonly wallClockNow?: () => number;
+    readonly isStopped?: () => boolean;
+}
+export interface ManagedLaunchdLogMonitorDependencies extends ManagedLaunchdLogInspectionDependencies {
+    readonly stderr: (text: string) => void | Promise<void>;
+    readonly recordStatus?: (status: ManagedLaunchdLogMonitorStatus) => void | Promise<void>;
+}
+export interface ManagedLaunchdLogMonitor {
+    stop(): void;
+}
+export interface AdditionalLaunchdLogInspection {
+    readonly needsMaintenance: boolean;
+    readonly canMaintain: boolean;
+    readonly issues: readonly string[];
+}
+export interface AdditionalLaunchdLogMaintenanceResult {
+    readonly refusals: readonly string[];
+}
+/** Narrow mutation port shared by agent maintenance and the isolated web helper. */
+export interface LaunchdLogMaintenanceDeps {
+    readonly runner: LaunchctlRunner;
+    readonly getuid: () => number;
+    readonly now: () => number;
+    readonly sleep: (ms: number) => Promise<void>;
+    readonly stderr: (text: string) => void;
+    readonly inspectLaunchdLogs: BackgroundDeps["inspectLaunchdLogs"];
+    readonly rotateStoppedLaunchdLogs: BackgroundDeps["rotateStoppedLaunchdLogs"];
+    readonly readLaunchdLogMaintenanceIntent: BackgroundDeps["readLaunchdLogMaintenanceIntent"];
+    readonly beginLaunchdLogMaintenanceIntent: BackgroundDeps["beginLaunchdLogMaintenanceIntent"];
+    readonly markLaunchdLogMaintenanceStopped: BackgroundDeps["markLaunchdLogMaintenanceStopped"];
+    readonly markLaunchdLogMaintenanceRestoring: BackgroundDeps["markLaunchdLogMaintenanceRestoring"];
+    readonly clearLaunchdLogMaintenanceIntent: BackgroundDeps["clearLaunchdLogMaintenanceIntent"];
+    readonly verifyLaunchdPlist: BackgroundDeps["verifyLaunchdPlist"];
+    readonly isAlive: (pid: number) => boolean;
+    /** Optional bounded compatibility seam; it cannot read or mutate intent/journal state. */
+    readonly inspectAdditionalLaunchdLogArtifacts?: (paths: Pick<LaunchdPaths, "logDir" | "stdoutPath" | "stderrPath">) => Promise<AdditionalLaunchdLogInspection>;
+    /** Runs only after durable stopped-writer proof and before core rotation. */
+    readonly maintainAdditionalLaunchdLogArtifacts?: (paths: Pick<LaunchdPaths, "logDir" | "stdoutPath" | "stderrPath">) => Promise<AdditionalLaunchdLogMaintenanceResult>;
+    readonly recordAdditionalLaunchdLogRefusals?: (refusals: readonly string[]) => Promise<void>;
+    readonly recordMaintenancePhase?: (phase: "inspecting" | "stopping" | "stopped" | "rotating" | "restoring" | "complete") => Promise<void>;
+}
+export type ManagedLaunchdLogMonitorOutcome = "idle" | "shared-only" | "pending-artifact" | "cooldown" | "stopped" | "helper-unloaded" | "helper-running" | "requested" | "request-failed" | "inspection-failed";
+export interface ManagedLaunchdLogMonitorStatus {
+    readonly version: 1;
+    readonly lastInspectionAt: string;
+    readonly wakeCount: number;
+    readonly lastOutcome: ManagedLaunchdLogMonitorOutcome;
+    readonly cooldownDeadline: string;
+}
+export interface ManagedLaunchdLogWakeState {
+    cooldownIndex: number;
+    cooldownDeadlineMonotonicMs: number;
+    wakeCount: number;
+    lastOutcome: ManagedLaunchdLogMonitorOutcome;
+    lastReportedOutcome: ManagedLaunchdLogMonitorOutcome | undefined;
+}
+export declare function createManagedLaunchdLogWakeState(monotonicNow?: typeof defaultMonotonicNow): ManagedLaunchdLogWakeState;
+/**
+ * Run the managed worker's bounded metadata fast path. The dependency surface
+ * intentionally excludes config validation, snapshots, and runtime recovery:
+ * only a concrete safe maintenance inventory may wake the authenticated helper.
+ */
+export declare function requestLaunchdLogMaintenanceIfNeeded(target: BackgroundLifecycleTarget, deps: ManagedLaunchdLogInspectionDependencies, state?: ManagedLaunchdLogWakeState): Promise<ManagedLaunchdLogMonitorOutcome>;
+/**
+ * Inspect active logs in the already-running worker every five minutes. One
+ * inspection may be in flight at a time, so a slow filesystem cannot build an
+ * overlapping timer queue. Consecutive failures are reported only once.
+ */
+export declare function startManagedLaunchdLogMonitor(target: BackgroundLifecycleTarget, deps: ManagedLaunchdLogMonitorDependencies): ManagedLaunchdLogMonitor;
+declare function defaultMonotonicNow(): number;
 /** Run one authenticated, crash-recoverable stopped-writer log rotation pass. */
-export declare function maintainLaunchdLogsOperation(target: BackgroundLifecycleTarget, deps: BackgroundDeps, poll: PollOptions): Promise<number>;
-export declare function reportMaintenanceFailure(target: BackgroundLifecycleTarget, deps: BackgroundDeps, action: string, error: unknown): void;
+export declare function maintainLaunchdLogsOperation(target: BackgroundLifecycleTarget, deps: BackgroundDeps, poll: PollOptions, acquireSharedLogLock: () => Promise<(() => Promise<void>) | undefined>): Promise<number>;
+/** Acquire the shared lease after the caller already owns this agent's lifecycle. */
+export declare function maintainLaunchdLogsWithLifecycleLockOperation(target: BackgroundLifecycleTarget, deps: BackgroundDeps, poll: PollOptions, acquireSharedLogLock: () => Promise<(() => Promise<void>) | undefined>): Promise<number>;
+/** Execute log maintenance only while the caller owns per-agent then shared leases. */
+export declare function maintainLaunchdLogsWithSharedLockOperation(target: BackgroundLifecycleTarget, deps: LaunchdLogMaintenanceDeps, poll: PollOptions): Promise<number>;
+export declare function reportMaintenanceFailure(target: BackgroundLifecycleTarget, deps: Pick<LaunchdLogMaintenanceDeps, "stderr">, action: string, error: unknown): void;
+export {};
 //# sourceMappingURL=background-log-maintenance.d.ts.map

package/dist/background-log-maintenance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"background-log-maintenance.d.ts","sourceRoot":"","sources":["../src/background-log-maintenance.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,KAAK,EAAE,cAAc,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAGjF,iFAAiF;AACjF,wBAAsB,4BAA4B,CAChD,MAAM,EAAE,yBAAyB,EACjC,IAAI,EAAE,cAAc,EACpB,IAAI,EAAE,WAAW,GAChB,OAAO,CAAC,MAAM,CAAC,CAgOjB;AAED,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,yBAAyB,EACjC,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,GACb,IAAI,CAIN"}
+{"version":3,"file":"background-log-maintenance.d.ts","sourceRoot":"","sources":["../src/background-log-maintenance.ts"],"names":[],"mappings":"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"}