@borgee/agents-host 0.2.97 → 0.2.110

package/dist/execution-telemetry.js

@@ -0,0 +1,583 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+export class ExecutionDeliveryJournal {
+    path;
+    maxCompletedEntries;
+    now;
+    entries = new Map();
+    loaded = false;
+    writeQueue = Promise.resolve();
+    constructor(path, maxCompletedEntries = 2_048, now = Date.now) {
+        this.path = path;
+        this.maxCompletedEntries = maxCompletedEntries;
+        this.now = now;
+    }
+    async load() {
+        if (this.loaded)
+            return;
+        if (!this.path) {
+            this.loaded = true;
+            return;
+        }
+        let content;
+        try {
+            content = await readFile(this.path, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                this.loaded = true;
+                return;
+            }
+            throw error;
+        }
+        const parsed = JSON.parse(content);
+        if (!Array.isArray(parsed) ||
+            parsed.some((entry) => !this.isStoredExecutionDelivery(entry)) ||
+            new Set(parsed.map((entry) => entry.executionId)).size !== parsed.length) {
+            throw new Error('Invalid execution delivery journal');
+        }
+        this.entries = new Map(parsed.map((entry) => [entry.executionId, entry]));
+        this.loaded = true;
+    }
+    async claim(executionId) {
+        await this.load();
+        const existing = this.entries.get(executionId);
+        if (existing?.state === 'completed')
+            return 'completed';
+        if (existing?.state === 'running')
+            return 'recovering';
+        await this.mutate((next) => {
+            next.set(executionId, {
+                executionId,
+                state: 'running',
+                updatedAt: this.now(),
+            });
+        });
+        return 'new';
+    }
+    async complete(executionId) {
+        await this.load();
+        await this.mutate((next) => {
+            next.set(executionId, {
+                executionId,
+                state: 'completed',
+                updatedAt: this.now(),
+            });
+            const completed = [...next.values()]
+                .filter((entry) => entry.state === 'completed')
+                .sort((left, right) => left.updatedAt - right.updatedAt);
+            for (const entry of completed.slice(0, Math.max(0, completed.length - this.maxCompletedEntries))) {
+                next.delete(entry.executionId);
+            }
+        });
+    }
+    async recordUsage(executionId, usage) {
+        await this.load();
+        await this.mutate((next) => {
+            const entry = next.get(executionId);
+            if (!entry || entry.state !== 'running') {
+                throw new Error('Cannot record usage for an execution that is not running');
+            }
+            next.set(executionId, {
+                ...entry,
+                updatedAt: this.now(),
+                usage: { ...usage },
+            });
+        });
+    }
+    async readUsage(executionId) {
+        await this.load();
+        const usage = this.entries.get(executionId)?.usage;
+        return usage ? { ...usage } : undefined;
+    }
+    async mutate(update) {
+        const operation = this.writeQueue.then(async () => {
+            const next = new Map(this.entries);
+            update(next);
+            if (this.path) {
+                await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+                const temporaryPath = `${this.path}.${process.pid}.${randomUUID()}.tmp`;
+                try {
+                    await writeFile(temporaryPath, JSON.stringify([...next.values()]), { encoding: 'utf8', mode: 0o600 });
+                    await rename(temporaryPath, this.path);
+                }
+                catch (error) {
+                    await unlink(temporaryPath).catch(() => { });
+                    throw error;
+                }
+            }
+            this.entries = next;
+        });
+        this.writeQueue = operation.catch(() => { });
+        await operation;
+    }
+    isStoredExecutionDelivery(value) {
+        if (!value || typeof value !== 'object')
+            return false;
+        const entry = value;
+        return (typeof entry.executionId === 'string' &&
+            entry.executionId.length > 0 &&
+            (entry.state === 'running' || entry.state === 'completed') &&
+            typeof entry.updatedAt === 'number' &&
+            Number.isSafeInteger(entry.updatedAt) &&
+            (entry.usage === undefined || this.isStoredExecutionUsage(entry.usage)));
+    }
+    isStoredExecutionUsage(value) {
+        if (!value || typeof value !== 'object')
+            return false;
+        const usage = value;
+        return ((usage.provider === 'claude' ||
+            usage.provider === 'codex' ||
+            usage.provider === 'copilot') &&
+            [usage.inputTokens, usage.outputTokens, usage.cacheReadTokens, usage.cacheWriteTokens]
+                .every((token) => (typeof token === 'number' &&
+                Number.isSafeInteger(token) &&
+                token >= 0)));
+    }
+}
+function stableEventId(executionId, kind) {
+    return createHash('sha256')
+        .update(`agents-host-execution-telemetry\0${executionId}\0${kind}`)
+        .digest('hex');
+}
+export class ExecutionTelemetryReporter {
+    grant;
+    sink;
+    now;
+    persistUsage;
+    started = false;
+    finished = false;
+    attemptCount = 0;
+    attemptsSucceeded = true;
+    provider;
+    pendingUsage;
+    usageFrameDurable = false;
+    usagePersistence = Promise.resolve();
+    continuations = [];
+    finishing;
+    get startFrameDurable() {
+        return this.started;
+    }
+    get terminalFrameDurable() {
+        return this.finished;
+    }
+    get allRequiredFramesDurable() {
+        return (this.started &&
+            this.finished &&
+            (this.pendingUsage === undefined || this.usageFrameDurable));
+    }
+    constructor(grant, sink, now = Date.now, persistUsage) {
+        this.grant = grant;
+        this.sink = sink;
+        this.now = now;
+        this.persistUsage = persistUsage;
+    }
+    async start() {
+        if (this.started || this.finished)
+            return;
+        await this.sink.reportExecutionTelemetry({
+            type: 'execution_started',
+            eventId: stableEventId(this.grant.executionId, 'started'),
+            executionId: this.grant.executionId,
+            telemetryContext: this.grant.telemetryContext,
+            startedAt: this.now(),
+        });
+        this.started = true;
+    }
+    async usage(provider, usage) {
+        if (!this.started || this.finished)
+            return;
+        if (usage.inputTokens === 0 &&
+            usage.outputTokens === 0 &&
+            usage.cacheReadTokens === 0 &&
+            usage.cacheWriteTokens === 0) {
+            return;
+        }
+        this.provider ??= provider;
+        this.pendingUsage = {
+            inputTokens: (this.pendingUsage?.inputTokens ?? 0) + usage.inputTokens,
+            outputTokens: (this.pendingUsage?.outputTokens ?? 0) + usage.outputTokens,
+            cacheReadTokens: (this.pendingUsage?.cacheReadTokens ?? 0) + usage.cacheReadTokens,
+            cacheWriteTokens: (this.pendingUsage?.cacheWriteTokens ?? 0) + usage.cacheWriteTokens,
+        };
+        this.usageFrameDurable = false;
+        if (this.persistUsage) {
+            const snapshot = { ...this.pendingUsage };
+            this.usagePersistence = this.usagePersistence
+                .then(() => this.persistUsage(this.provider, snapshot))
+                .catch(() => undefined);
+            await this.usagePersistence;
+        }
+    }
+    noteAttempt(succeeded) {
+        if (!this.started || this.finished)
+            return;
+        this.attemptCount += 1;
+        this.attemptsSucceeded &&= succeeded;
+    }
+    noteFailure() {
+        if (!this.started || this.finished)
+            return;
+        this.attemptsSucceeded = false;
+    }
+    hold(completion) {
+        if (this.finished || this.finishing)
+            return;
+        this.continuations.push(completion);
+    }
+    finish(succeeded) {
+        if (this.finishing)
+            return this.finishing;
+        const attempt = this.finalize(succeeded);
+        this.finishing = attempt;
+        void attempt.catch(() => {
+            if (this.finishing === attempt) {
+                this.finishing = undefined;
+            }
+        });
+        return this.finishing;
+    }
+    async finalize(succeeded) {
+        if (!this.started || this.finished)
+            return;
+        const continuationResults = await Promise.allSettled(this.continuations);
+        if (continuationResults.some((result) => result.status === 'rejected' || result.value === false)) {
+            this.attemptsSucceeded = false;
+        }
+        const finalSucceeded = succeeded ?? (this.attemptCount > 0 && this.attemptsSucceeded);
+        if (this.pendingUsage && !this.usageFrameDurable) {
+            const errors = [];
+            try {
+                await this.usagePersistence;
+                await this.persistUsage?.(this.provider, this.pendingUsage);
+                await this.sink.reportExecutionTelemetry({
+                    type: 'execution_usage',
+                    eventId: stableEventId(this.grant.executionId, 'usage'),
+                    executionId: this.grant.executionId,
+                    telemetryContext: this.grant.telemetryContext,
+                    usageGranularity: 'execution_aggregate',
+                    provider: this.provider,
+                    model: 'unknown',
+                    inputTokens: this.pendingUsage.inputTokens,
+                    outputTokens: this.pendingUsage.outputTokens,
+                    cacheReadTokens: this.pendingUsage.cacheReadTokens,
+                    cacheWriteTokens: this.pendingUsage.cacheWriteTokens,
+                    observedAt: this.now(),
+                });
+                this.usageFrameDurable = true;
+            }
+            catch (error) {
+                errors.push(error);
+            }
+            if (errors.length > 0) {
+                throw new AggregateError(errors, 'Execution usage telemetry could not be persisted');
+            }
+        }
+        try {
+            await this.sink.reportExecutionTelemetry({
+                type: 'execution_finished',
+                eventId: stableEventId(this.grant.executionId, 'finished'),
+                executionId: this.grant.executionId,
+                telemetryContext: this.grant.telemetryContext,
+                succeeded: finalSucceeded,
+                endedAt: this.now(),
+            });
+            this.finished = true;
+        }
+        catch (error) {
+            throw new AggregateError([error], 'Execution telemetry could not be finalized');
+        }
+    }
+}
+function isStoredFrame(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const frame = value;
+    const hasIdentity = typeof frame.eventId === 'string' &&
+        frame.eventId.length > 0 &&
+        typeof frame.executionId === 'string' &&
+        frame.executionId.length > 0 &&
+        typeof frame.telemetryContext === 'string' &&
+        frame.telemetryContext.length > 0;
+    if (!hasIdentity)
+        return false;
+    if (frame.type === 'execution_started') {
+        return typeof frame.startedAt === 'number' && Number.isSafeInteger(frame.startedAt);
+    }
+    if (frame.type === 'execution_finished') {
+        return (typeof frame.succeeded === 'boolean' &&
+            typeof frame.endedAt === 'number' &&
+            Number.isSafeInteger(frame.endedAt));
+    }
+    if (frame.type !== 'execution_usage')
+        return false;
+    return ((frame.usageGranularity === 'llm_call' ||
+        frame.usageGranularity === 'execution_aggregate') &&
+        typeof frame.provider === 'string' &&
+        frame.provider.length > 0 &&
+        typeof frame.model === 'string' &&
+        frame.model.length > 0 &&
+        [frame.inputTokens, frame.outputTokens, frame.cacheReadTokens, frame.cacheWriteTokens]
+            .every((token) => typeof token === 'number' && Number.isSafeInteger(token) && token >= 0) &&
+        typeof frame.observedAt === 'number' &&
+        Number.isSafeInteger(frame.observedAt));
+}
+// The wire has ACK but no terminal NACK. Requiring both age and attempts keeps
+// a long offline interval from looking like rejection, while maxEntries applies
+// backpressure instead of deleting recent unacknowledged facts.
+const DEFAULT_OUTBOX_POLICY = {
+    maxEntries: 2_048,
+    maxAttempts: 64,
+    retentionMs: 7 * 24 * 60 * 60 * 1_000,
+    retryIntervalMs: 30_000,
+};
+export class ExecutionTelemetryOutboxCapacityError extends Error {
+    constructor() {
+        super('Execution telemetry outbox capacity reached');
+        this.name = 'ExecutionTelemetryOutboxCapacityError';
+    }
+}
+export class ExecutionTelemetryOutbox {
+    path;
+    frames = new Map();
+    loaded = false;
+    writeQueue = Promise.resolve();
+    flushInFlight;
+    now;
+    onRetired;
+    policy;
+    capacityWaiters = new Set();
+    constructor(path, options = {}) {
+        this.path = path;
+        this.now = options.now ?? Date.now;
+        this.onRetired = options.onRetired;
+        this.policy = { ...DEFAULT_OUTBOX_POLICY, ...options.policy };
+    }
+    async load() {
+        if (this.loaded)
+            return;
+        if (!this.path) {
+            this.loaded = true;
+            return;
+        }
+        let content;
+        try {
+            content = await readFile(this.path, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                this.loaded = true;
+                return;
+            }
+            throw error;
+        }
+        const parsed = JSON.parse(content);
+        if (!Array.isArray(parsed)) {
+            throw new Error('Invalid execution telemetry outbox');
+        }
+        const restored = [];
+        for (const value of parsed) {
+            if (isStoredFrame(value)) {
+                restored.push({
+                    frame: value,
+                    enqueuedAt: this.frameTimestamp(value),
+                    attempts: 0,
+                });
+                continue;
+            }
+            if (!this.isStoredEntry(value)) {
+                throw new Error('Invalid execution telemetry outbox');
+            }
+            restored.push(value);
+        }
+        if (new Set(restored.map(({ frame }) => frame.eventId)).size !== restored.length) {
+            throw new Error('Invalid execution telemetry outbox');
+        }
+        this.frames = new Map(restored.map((entry) => [entry.frame.eventId, entry]));
+        this.loaded = true;
+    }
+    async enqueue(frame) {
+        await this.load();
+        await this.retireExpired();
+        await this.mutate((next) => {
+            if (next.has(frame.eventId))
+                return false;
+            if (next.size >= this.policy.maxEntries) {
+                throw new ExecutionTelemetryOutboxCapacityError();
+            }
+            next.set(frame.eventId, {
+                frame,
+                enqueuedAt: this.now(),
+                attempts: 0,
+            });
+            return true;
+        });
+    }
+    async acknowledge(eventId) {
+        await this.load();
+        if (!this.frames.has(eventId))
+            return;
+        await this.mutate((next) => {
+            next.delete(eventId);
+            return true;
+        });
+        this.notifyCapacityAvailable();
+    }
+    async flush(send, force = false) {
+        if (this.flushInFlight)
+            return this.flushInFlight;
+        const operation = this.flushOnce(send, force);
+        const tracked = operation.finally(() => {
+            if (this.flushInFlight === tracked) {
+                this.flushInFlight = undefined;
+            }
+        });
+        this.flushInFlight = tracked;
+        return tracked;
+    }
+    async flushOnce(send, force) {
+        await this.load();
+        await this.retireExpired();
+        const now = this.now();
+        let pending = [];
+        await this.mutate((next) => {
+            pending = [...next.values()].filter((entry) => entry.attempts < this.policy.maxAttempts &&
+                (entry.attempts === 0 ||
+                    force ||
+                    entry.lastAttemptAt === undefined ||
+                    now - entry.lastAttemptAt >= this.policy.retryIntervalMs));
+            if (pending.length === 0)
+                return false;
+            const pendingIds = new Set(pending.map(({ frame }) => frame.eventId));
+            for (const [eventId, entry] of next) {
+                if (!pendingIds.has(eventId))
+                    continue;
+                next.set(eventId, {
+                    ...entry,
+                    attempts: entry.attempts + 1,
+                    lastAttemptAt: now,
+                });
+            }
+            return true;
+        });
+        const errors = [];
+        for (const { frame } of pending) {
+            try {
+                send(frame);
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        if (errors.length > 0) {
+            throw new AggregateError(errors, 'Execution telemetry delivery failed');
+        }
+    }
+    async settle() {
+        await this.writeQueue;
+    }
+    pendingCount() {
+        return this.frames.size;
+    }
+    nextRetryDelayMs() {
+        if (this.frames.size === 0)
+            return undefined;
+        const now = this.now();
+        return Math.max(0, Math.min(...[...this.frames.values()].map((entry) => entry.attempts >= this.policy.maxAttempts
+            ? entry.enqueuedAt + this.policy.retentionMs - now
+            : entry.attempts === 0 || entry.lastAttemptAt === undefined
+                ? 0
+                : entry.lastAttemptAt + this.policy.retryIntervalMs - now)));
+    }
+    hasCapacity() {
+        return this.frames.size < this.policy.maxEntries;
+    }
+    waitForCapacity(timeoutMs) {
+        if (this.hasCapacity())
+            return Promise.resolve(true);
+        return new Promise((resolve) => {
+            const settle = (available) => {
+                clearTimeout(timeout);
+                this.capacityWaiters.delete(settle);
+                resolve(available);
+            };
+            const timeout = setTimeout(() => settle(false), timeoutMs);
+            this.capacityWaiters.add(settle);
+        });
+    }
+    async retireExpired() {
+        const now = this.now();
+        let retired = 0;
+        await this.mutate((next) => {
+            for (const [eventId, entry] of next) {
+                if (entry.attempts >= this.policy.maxAttempts &&
+                    now - entry.enqueuedAt >= this.policy.retentionMs) {
+                    next.delete(eventId);
+                    retired += 1;
+                }
+            }
+            return retired > 0;
+        });
+        if (retired > 0) {
+            this.onRetired?.(retired);
+            this.notifyCapacityAvailable();
+        }
+    }
+    async mutate(change) {
+        const operation = this.writeQueue.then(async () => {
+            const next = new Map(this.frames);
+            if (!change(next))
+                return;
+            await this.persist(next);
+            this.frames = next;
+        });
+        this.writeQueue = operation.catch(() => { });
+        await operation;
+    }
+    async persist(frames) {
+        if (!this.path)
+            return;
+        await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+        const temporary = `${this.path}.${process.pid}.${randomUUID()}.tmp`;
+        try {
+            await writeFile(temporary, JSON.stringify([...frames.values()]), {
+                encoding: 'utf8',
+                mode: 0o600,
+                flag: 'wx',
+            });
+            await rename(temporary, this.path);
+        }
+        catch (error) {
+            await unlink(temporary).catch(() => { });
+            throw error;
+        }
+    }
+    frameTimestamp(frame) {
+        if (frame.type === 'execution_started')
+            return frame.startedAt;
+        if (frame.type === 'execution_usage')
+            return frame.observedAt;
+        return frame.endedAt;
+    }
+    isStoredEntry(value) {
+        if (!value || typeof value !== 'object')
+            return false;
+        const entry = value;
+        return (isStoredFrame(entry.frame) &&
+            typeof entry.enqueuedAt === 'number' &&
+            Number.isSafeInteger(entry.enqueuedAt) &&
+            typeof entry.attempts === 'number' &&
+            Number.isSafeInteger(entry.attempts) &&
+            entry.attempts >= 0 &&
+            (entry.lastAttemptAt === undefined ||
+                (typeof entry.lastAttemptAt === 'number' &&
+                    Number.isSafeInteger(entry.lastAttemptAt))));
+    }
+    notifyCapacityAvailable() {
+        if (!this.hasCapacity())
+            return;
+        for (const waiter of [...this.capacityWaiters])
+            waiter(true);
+    }
+}

package/dist/gateway/channel-file-workspace.d.ts

@@ -0,0 +1,15 @@
+export declare const CHANNEL_FILE_WORKING_COPY_DIRECTORY = ".borgee/channel-files";
+export declare const CHANNEL_FILE_TRANSFER_MAX_BYTES: number;
+export declare class ChannelFileWorkspaceError extends Error {
+    readonly code: 'execution_local_directory_required' | 'invalid_file_path' | 'symlink_not_allowed' | 'file_too_large' | 'file_exists' | 'file_not_found';
+    constructor(code: 'execution_local_directory_required' | 'invalid_file_path' | 'symlink_not_allowed' | 'file_too_large' | 'file_exists' | 'file_not_found', message: string);
+}
+export declare function validatePortableRelativePath(path: string): string;
+export declare function requireExecutionRoot(payload: {
+    resolvedWorkspace?: {
+        authority: string;
+        rootPath: string;
+    };
+}): string;
+export declare function readWorkspaceFile(rootPath: string, sourcePath: string): Promise<Buffer>;
+export declare function writeWorkingCopy(rootPath: string, channelPath: string, content: Buffer, overwrite: boolean): Promise<string>;