@hunterzhu/pulse-runtime 0.1.0

package/dist/scheduler/telemetry.d.ts

@@ -0,0 +1,111 @@
+import type { JsonValue, RuntimeState } from '../core/types.js';
+export interface RuntimeTelemetryAttempt {
+    effectId: string;
+    agentId: string | null;
+    laneId: string | null;
+    attemptId: string;
+    attemptNo: number;
+    modelId: string;
+    providerId: string;
+    slotWaitMs?: number;
+    usage?: JsonValue;
+}
+export interface RuntimeTelemetrySnapshot {
+    eventCounts: Record<string, number>;
+    agents: {
+        total: number;
+        byState: Record<string, number>;
+    };
+    lanes: {
+        total: number;
+        byStatus: Record<string, number>;
+    };
+    effects: {
+        total: number;
+        byState: Record<string, number>;
+        byKind: Record<string, number>;
+    };
+    llm: {
+        effects: number;
+        metadataEvents: number;
+        attempts: RuntimeTelemetryAttempt[];
+        routeRejections: Record<string, number>;
+        usage: {
+            inputTokens: number;
+            outputTokens: number;
+            cachedInputTokens: number;
+            uncachedInputTokens: number;
+            latencyMs: number;
+            costByCurrency: Record<string, number>;
+        };
+    };
+}
+export interface RuntimeTelemetryEnvelope {
+    schemaVersion: 1;
+    timestamp: number;
+    snapshot: RuntimeTelemetrySnapshot;
+}
+export interface RuntimeTelemetryExporter {
+    publish(envelope: RuntimeTelemetryEnvelope): Promise<void> | void;
+}
+export interface RuntimeTelemetryAlertRule {
+    id: string;
+    metric: string;
+    threshold: number;
+    direction: 'above' | 'below';
+    cooldownMs?: number;
+}
+export interface RuntimeTelemetryAlert {
+    ruleId: string;
+    metric: string;
+    value: number;
+    threshold: number;
+    direction: RuntimeTelemetryAlertRule['direction'];
+    timestamp: number;
+}
+export interface RuntimeTelemetryAggregateSnapshot {
+    schemaVersion: 1;
+    sampleCount: number;
+    firstTimestamp?: number;
+    lastTimestamp?: number;
+    latest?: RuntimeTelemetryEnvelope;
+    peaks: Record<string, number>;
+    alerts: RuntimeTelemetryAlert[];
+}
+/** Aggregates exported samples without retaining the full telemetry stream in Runtime state. */
+export declare class RuntimeTelemetryAggregator {
+    readonly rules: readonly RuntimeTelemetryAlertRule[];
+    private sampleCount;
+    private firstTimestamp;
+    private lastTimestamp;
+    private latest;
+    private readonly peaks;
+    private readonly alerts;
+    private readonly lastAlertAt;
+    constructor(rules?: readonly RuntimeTelemetryAlertRule[]);
+    ingest(envelope: RuntimeTelemetryEnvelope): RuntimeTelemetryAlert[];
+    snapshot(): RuntimeTelemetryAggregateSnapshot;
+}
+/** A durable, append-only exporter suitable for a local host or sidecar collector. */
+export declare class FileRuntimeTelemetryExporter implements RuntimeTelemetryExporter {
+    readonly filePath: string;
+    private pending;
+    constructor(filePath: string);
+    publish(envelope: RuntimeTelemetryEnvelope): Promise<void>;
+}
+export interface HttpRuntimeTelemetryExporterOptions {
+    endpoint: string;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+    fetch?: typeof globalThis.fetch;
+}
+/** Sends complete envelopes to an external collector without changing Runtime state. */
+export declare class HttpRuntimeTelemetryExporter implements RuntimeTelemetryExporter {
+    private readonly endpoint;
+    private readonly headers;
+    private readonly timeoutMs;
+    private readonly fetcher;
+    constructor(options: HttpRuntimeTelemetryExporterOptions);
+    publish(envelope: RuntimeTelemetryEnvelope): Promise<void>;
+}
+export declare function collectRuntimeTelemetry(state: RuntimeState): RuntimeTelemetrySnapshot;

package/dist/scheduler/telemetry.js

@@ -0,0 +1,177 @@
+import { mkdir, open } from 'node:fs/promises';
+import { dirname } from 'node:path';
+function metricValue(snapshot, path) {
+    let current = snapshot;
+    for (const segment of path.split('.')) {
+        if (!current || typeof current !== 'object' || Array.isArray(current))
+            return undefined;
+        current = current[segment];
+    }
+    return typeof current === 'number' && Number.isFinite(current) ? current : undefined;
+}
+/** Aggregates exported samples without retaining the full telemetry stream in Runtime state. */
+export class RuntimeTelemetryAggregator {
+    rules;
+    sampleCount = 0;
+    firstTimestamp;
+    lastTimestamp;
+    latest;
+    peaks = new Map();
+    alerts = [];
+    lastAlertAt = new Map();
+    constructor(rules = []) {
+        this.rules = rules;
+    }
+    ingest(envelope) {
+        if (envelope.schemaVersion !== 1 || !Number.isFinite(envelope.timestamp))
+            throw new Error('INVALID_TELEMETRY_ENVELOPE');
+        const emitted = [];
+        this.sampleCount++;
+        this.firstTimestamp ??= envelope.timestamp;
+        this.lastTimestamp = envelope.timestamp;
+        this.latest = structuredClone(envelope);
+        for (const rule of this.rules) {
+            const value = metricValue(envelope.snapshot, rule.metric);
+            if (value === undefined)
+                continue;
+            this.peaks.set(rule.metric, Math.max(this.peaks.get(rule.metric) ?? Number.NEGATIVE_INFINITY, value));
+            const matched = rule.direction === 'above' ? value >= rule.threshold : value <= rule.threshold;
+            const last = this.lastAlertAt.get(rule.id);
+            if (!matched || (last !== undefined && envelope.timestamp - last < (rule.cooldownMs ?? 0)))
+                continue;
+            const alert = { ruleId: rule.id, metric: rule.metric, value, threshold: rule.threshold, direction: rule.direction, timestamp: envelope.timestamp };
+            this.lastAlertAt.set(rule.id, envelope.timestamp);
+            this.alerts.push(alert);
+            emitted.push(alert);
+        }
+        return emitted;
+    }
+    snapshot() {
+        return { schemaVersion: 1, sampleCount: this.sampleCount, ...(this.firstTimestamp === undefined ? {} : { firstTimestamp: this.firstTimestamp }), ...(this.lastTimestamp === undefined ? {} : { lastTimestamp: this.lastTimestamp }), ...(this.latest === undefined ? {} : { latest: structuredClone(this.latest) }), peaks: Object.fromEntries(this.peaks.entries()), alerts: structuredClone(this.alerts) };
+    }
+}
+/** A durable, append-only exporter suitable for a local host or sidecar collector. */
+export class FileRuntimeTelemetryExporter {
+    filePath;
+    pending = Promise.resolve();
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    async publish(envelope) {
+        const operation = this.pending.then(async () => {
+            await mkdir(dirname(this.filePath), { recursive: true });
+            const handle = await open(this.filePath, 'a', 0o600);
+            try {
+                await handle.writeFile(`${JSON.stringify(envelope)}\n`, 'utf8');
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+        });
+        this.pending = operation.catch(() => undefined);
+        await operation;
+    }
+}
+/** Sends complete envelopes to an external collector without changing Runtime state. */
+export class HttpRuntimeTelemetryExporter {
+    endpoint;
+    headers;
+    timeoutMs;
+    fetcher;
+    constructor(options) {
+        if (!options.endpoint)
+            throw new Error('TELEMETRY_ENDPOINT_REQUIRED');
+        this.endpoint = options.endpoint;
+        this.headers = { 'content-type': 'application/json', ...(options.headers ?? {}) };
+        this.timeoutMs = options.timeoutMs ?? 10_000;
+        if (!Number.isFinite(this.timeoutMs) || this.timeoutMs <= 0)
+            throw new Error('INVALID_TELEMETRY_TIMEOUT');
+        this.fetcher = options.fetch ?? globalThis.fetch;
+    }
+    async publish(envelope) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const response = await this.fetcher(this.endpoint, { method: 'POST', headers: this.headers, body: JSON.stringify(envelope), signal: controller.signal });
+            if (!response.ok)
+                throw new Error(`TELEMETRY_HTTP_${response.status}`);
+        }
+        catch (cause) {
+            if (controller.signal.aborted)
+                throw new Error('TELEMETRY_HTTP_TIMEOUT');
+            throw cause;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+function count(target, key) { target[key] = (target[key] ?? 0) + 1; }
+function numberField(value, key) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const field = value[key];
+    return typeof field === 'number' && Number.isFinite(field) ? field : undefined;
+}
+export function collectRuntimeTelemetry(state) {
+    const eventCounts = {};
+    for (const event of state.events)
+        count(eventCounts, event.type);
+    const agentStates = {};
+    for (const agent of state.agents.values())
+        count(agentStates, agent.state ?? 'unknown');
+    const laneStatuses = {};
+    for (const lane of state.lanes.values())
+        count(laneStatuses, lane.status);
+    const effectStates = {};
+    const effectKinds = {};
+    for (const effect of state.effects.values()) {
+        count(effectStates, effect.state);
+        count(effectKinds, effect.kind);
+    }
+    const attempts = [];
+    const routeRejections = {};
+    const usage = { inputTokens: 0, outputTokens: 0, cachedInputTokens: 0, uncachedInputTokens: 0, latencyMs: 0, costByCurrency: {} };
+    let metadataEvents = 0;
+    for (const event of state.events) {
+        if (event.type !== 'effect.execution_metadata' || !event.effectId)
+            continue;
+        metadataEvents++;
+        const metadata = event.data && typeof event.data === 'object' && !Array.isArray(event.data) ? event.data : {};
+        const routeList = Array.isArray(metadata.routes) ? metadata.routes : [];
+        for (const route of routeList) {
+            if (!route || typeof route !== 'object' || Array.isArray(route))
+                continue;
+            const item = route;
+            if (item.accepted === false && Array.isArray(item.reasons))
+                for (const reason of item.reasons)
+                    if (typeof reason === 'string')
+                        count(routeRejections, reason);
+        }
+        const recorded = Array.isArray(metadata.attempts) ? metadata.attempts : [];
+        const effect = state.effects.get(event.effectId);
+        for (const item of recorded) {
+            if (!item || typeof item !== 'object' || Array.isArray(item))
+                continue;
+            const value = item;
+            if (typeof value.attemptId !== 'string' || typeof value.attemptNo !== 'number' || typeof value.modelId !== 'string' || typeof value.providerId !== 'string')
+                continue;
+            const attempt = { effectId: event.effectId, agentId: effect?.agentId ?? null, laneId: effect?.ownerLaneId ?? null, attemptId: value.attemptId, attemptNo: value.attemptNo, modelId: value.modelId, providerId: value.providerId, ...(typeof value.slotWaitMs === 'number' ? { slotWaitMs: value.slotWaitMs } : {}), ...(value.usage === undefined ? {} : { usage: value.usage }) };
+            attempts.push(attempt);
+            const attemptUsage = value.usage;
+            for (const field of ['inputTokens', 'outputTokens', 'cachedInputTokens', 'uncachedInputTokens', 'latencyMs'])
+                usage[field] += numberField(attemptUsage, field) ?? 0;
+            if (attemptUsage && typeof attemptUsage === 'object' && !Array.isArray(attemptUsage)) {
+                const cost = attemptUsage.cost;
+                if (cost && typeof cost === 'object' && !Array.isArray(cost)) {
+                    const amount = numberField(cost, 'amount');
+                    const currency = cost.currency;
+                    if (amount !== undefined && typeof currency === 'string')
+                        usage.costByCurrency[currency] = (usage.costByCurrency[currency] ?? 0) + amount;
+                }
+            }
+        }
+    }
+    return { eventCounts, agents: { total: state.agents.size, byState: agentStates }, lanes: { total: state.lanes.size, byStatus: laneStatuses }, effects: { total: state.effects.size, byState: effectStates, byKind: effectKinds }, llm: { effects: [...state.effects.values()].filter((effect) => effect.kind === 'llm').length, metadataEvents, attempts, routeRejections, usage } };
+}

package/dist/scheduler/worker.d.ts

@@ -0,0 +1,158 @@
+import type { EffectExecution } from './runtime.js';
+import type { EffectRecord, JsonValue, RuntimeError } from '../core/types.js';
+export interface WorkerTaskRecord {
+    id: string;
+    payload: JsonValue;
+    state: 'queued' | 'leased' | 'succeeded' | 'failed' | 'cancelled';
+    attempt: number;
+    leaseId?: string;
+    workerId?: string;
+    leaseExpiresAt?: number;
+    leaseMs?: number;
+    idempotencyKey?: string;
+    result?: JsonValue;
+    error?: RuntimeError;
+}
+export interface WorkerLease {
+    task: WorkerTaskRecord;
+    workerId: string;
+    leaseId: string;
+}
+export interface WorkerCoordinatorSnapshot {
+    schemaVersion: 1;
+    sequence: number;
+    tasks: WorkerTaskRecord[];
+    idempotency: Record<string, string>;
+    integrity?: {
+        algorithm: 'sha256';
+        digest: string;
+    };
+}
+export interface WorkerPersistenceBackend {
+    load(): Promise<WorkerCoordinatorSnapshot | undefined>;
+    save(snapshot: WorkerCoordinatorSnapshot, expectedDigest?: string): Promise<void>;
+}
+export declare class FileWorkerPersistenceBackend implements WorkerPersistenceBackend {
+    readonly filePath: string;
+    private pending;
+    constructor(filePath: string);
+    load(): Promise<WorkerCoordinatorSnapshot | undefined>;
+    save(snapshot: WorkerCoordinatorSnapshot, expectedDigest?: string): Promise<void>;
+}
+/** Durable SQLite snapshot backend for sharing WorkerCoordinator state between processes. */
+export declare class SqliteWorkerPersistenceBackend implements WorkerPersistenceBackend {
+    readonly filePath: string;
+    private database;
+    private tail;
+    constructor(filePath: string);
+    load(): Promise<WorkerCoordinatorSnapshot | undefined>;
+    save(snapshot: WorkerCoordinatorSnapshot, expectedDigest?: string): Promise<void>;
+    close(): Promise<void>;
+    private open;
+    private enqueue;
+}
+export type WorkerHandler = (payload: JsonValue, signal: AbortSignal) => Promise<JsonValue>;
+export interface WorkerSubmitOptions {
+    taskId?: string;
+    idempotencyKey?: string;
+    leaseMs?: number;
+    signal?: AbortSignal;
+}
+export interface WorkerCoordinatorOptions {
+    persistenceBackend?: WorkerPersistenceBackend;
+}
+export interface WorkerCoordinatorContract {
+    submit(payload: JsonValue, options?: WorkerSubmitOptions): Promise<JsonValue>;
+    register(workerId: string, handler: WorkerHandler): () => void;
+    registerRemote(workerId: string): () => void;
+    unregister(workerId: string): void;
+    claim(workerId: string, now?: number): WorkerLease | undefined;
+    renewLease(workerId: string, leaseId: string, now?: number, leaseMs?: number): number | undefined;
+    completeRemote(workerId: string, leaseId: string, value: JsonValue, now?: number): boolean;
+    failRemote(workerId: string, leaseId: string, error: RuntimeError, now?: number): boolean;
+    get(taskId: string): WorkerTaskRecord | undefined;
+    cancel(taskId: string, reason?: string): boolean;
+    recoverExpired(now?: number): string[];
+}
+/** A lease-based worker coordinator. A network transport can implement the same claim/complete contract. */
+export declare class WorkerCoordinator implements WorkerCoordinatorContract {
+    private readonly tasks;
+    private readonly deferreds;
+    private readonly idempotency;
+    private readonly handlers;
+    private readonly remoteWorkers;
+    private readonly activeLeases;
+    private readonly persistenceBackend;
+    private persistenceDigest;
+    private persistencePending;
+    private sequence;
+    constructor(options?: WorkerCoordinatorOptions);
+    static restore(snapshot: WorkerCoordinatorSnapshot, options?: WorkerCoordinatorOptions): WorkerCoordinator;
+    static fromPersistence(backend: WorkerPersistenceBackend): Promise<WorkerCoordinator>;
+    flushPersistence(): Promise<void>;
+    register(workerId: string, handler: WorkerHandler): () => void;
+    registerRemote(workerId: string): () => void;
+    unregister(workerId: string): void;
+    submit(payload: JsonValue, options?: WorkerSubmitOptions): Promise<JsonValue>;
+    recoverExpired(now?: number): string[];
+    claim(workerId: string, now?: number): WorkerLease | undefined;
+    renewLease(workerId: string, leaseId: string, now?: number, leaseMs?: number): number | undefined;
+    completeRemote(workerId: string, leaseId: string, value: JsonValue, _now?: number): boolean;
+    failRemote(workerId: string, leaseId: string, error: RuntimeError, _now?: number): boolean;
+    get(taskId: string): WorkerTaskRecord | undefined;
+    snapshot(): WorkerCoordinatorSnapshot;
+    cancel(taskId: string, reason?: string): boolean;
+    inspect(): WorkerTaskRecord[];
+    private schedulePersistence;
+    private requeue;
+    private ensureDeferred;
+    private promiseFor;
+    private pump;
+    private assign;
+    private taskForLease;
+    private settleRemote;
+    private completeTask;
+    private failTask;
+}
+/**
+ * A WorkerCoordinator whose lease transitions are owned by SQLite transactions.
+ * Separate processes may open the same database and race safely on the same queue.
+ */
+export declare class SqliteDistributedWorkerCoordinator implements WorkerCoordinatorContract {
+    readonly filePath: string;
+    private database;
+    private readonly deferreds;
+    private readonly watchers;
+    private readonly handlers;
+    private readonly remoteWorkers;
+    private readonly activeLeases;
+    constructor(filePath: string);
+    register(workerId: string, handler: WorkerHandler): () => void;
+    registerRemote(workerId: string): () => void;
+    unregister(workerId: string): void;
+    submit(payload: JsonValue, options?: WorkerSubmitOptions): Promise<JsonValue>;
+    claim(workerId: string, now?: number): WorkerLease | undefined;
+    renewLease(workerId: string, leaseId: string, now?: number, leaseMs?: number): number | undefined;
+    completeRemote(workerId: string, leaseId: string, value: JsonValue, now?: number): boolean;
+    failRemote(workerId: string, leaseId: string, error: RuntimeError, now?: number): boolean;
+    get(taskId: string): WorkerTaskRecord | undefined;
+    inspect(): WorkerTaskRecord[];
+    cancel(taskId: string, reason?: string): boolean;
+    recoverExpired(now?: number): string[];
+    close(): void;
+    private pump;
+    private ensureDeferred;
+    private watch;
+    private taskIdForLease;
+    private getByLease;
+    private requeueWorker;
+    private nextId;
+    private leaseMs;
+    private rowToTask;
+    private changedRows;
+    private open;
+    private withTransaction;
+}
+export declare function createWorkerEffectExecutor(coordinator: Pick<WorkerCoordinatorContract, 'submit'>, options?: {
+    leaseMs?: number;
+}): (effect: Readonly<EffectRecord>, signal: AbortSignal) => Promise<EffectExecution>;