@agent-watch-ai/edge 0.2.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +251 -0
- package/LICENSE +21 -0
- package/README.md +168 -0
- package/dist/billing/billing-mode.d.ts +16 -0
- package/dist/billing/billing-mode.js +139 -0
- package/dist/billing/constants/billing.constants.d.ts +37 -0
- package/dist/billing/constants/billing.constants.js +38 -0
- package/dist/billing/index.d.ts +6 -0
- package/dist/billing/index.js +6 -0
- package/dist/cli/args.d.ts +29 -0
- package/dist/cli/args.js +61 -0
- package/dist/cli/constants/cli.constants.d.ts +60 -0
- package/dist/cli/constants/cli.constants.js +60 -0
- package/dist/cli/context.d.ts +51 -0
- package/dist/cli/context.js +108 -0
- package/dist/cli/doctor.d.ts +15 -0
- package/dist/cli/doctor.js +416 -0
- package/dist/cli/hook.d.ts +20 -0
- package/dist/cli/hook.js +166 -0
- package/dist/cli/index.d.ts +13 -0
- package/dist/cli/index.js +8 -0
- package/dist/cli/misc.d.ts +31 -0
- package/dist/cli/misc.js +63 -0
- package/dist/cli/setup.d.ts +32 -0
- package/dist/cli/setup.js +298 -0
- package/dist/cli/status.d.ts +11 -0
- package/dist/cli/status.js +174 -0
- package/dist/cli/types/cli.types.d.ts +69 -0
- package/dist/cli/types/cli.types.js +1 -0
- package/dist/cli/ui.d.ts +41 -0
- package/dist/cli/ui.js +78 -0
- package/dist/cli/uninstall.d.ts +13 -0
- package/dist/cli/uninstall.js +83 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +124 -0
- package/dist/config/config-store.d.ts +29 -0
- package/dist/config/config-store.js +75 -0
- package/dist/config/config.d.ts +73 -0
- package/dist/config/config.js +115 -0
- package/dist/config/constants/config.constants.d.ts +62 -0
- package/dist/config/constants/config.constants.js +70 -0
- package/dist/config/index.d.ts +10 -0
- package/dist/config/index.js +5 -0
- package/dist/config/repo-config.d.ts +37 -0
- package/dist/config/repo-config.js +178 -0
- package/dist/config/schemas/config.schema.d.ts +409 -0
- package/dist/config/schemas/config.schema.js +97 -0
- package/dist/config/types/config.types.d.ts +33 -0
- package/dist/config/types/config.types.js +1 -0
- package/dist/core/async.d.ts +20 -0
- package/dist/core/async.js +32 -0
- package/dist/core/constants/core.constants.d.ts +18 -0
- package/dist/core/constants/core.constants.js +18 -0
- package/dist/core/env.d.ts +12 -0
- package/dist/core/env.js +20 -0
- package/dist/core/index.d.ts +13 -0
- package/dist/core/index.js +8 -0
- package/dist/core/logger.d.ts +27 -0
- package/dist/core/logger.js +82 -0
- package/dist/core/number.d.ts +33 -0
- package/dist/core/number.js +47 -0
- package/dist/core/object.d.ts +78 -0
- package/dist/core/object.js +127 -0
- package/dist/core/pipe.d.ts +55 -0
- package/dist/core/pipe.js +81 -0
- package/dist/core/types/core.types.d.ts +54 -0
- package/dist/core/types/core.types.js +4 -0
- package/dist/core/version.d.ts +19 -0
- package/dist/core/version.js +35 -0
- package/dist/core/which.d.ts +13 -0
- package/dist/core/which.js +57 -0
- package/dist/enforcement/constants/enforcement.constants.d.ts +23 -0
- package/dist/enforcement/constants/enforcement.constants.js +22 -0
- package/dist/enforcement/decision-cache.d.ts +57 -0
- package/dist/enforcement/decision-cache.js +138 -0
- package/dist/enforcement/decision-client.d.ts +14 -0
- package/dist/enforcement/decision-client.js +84 -0
- package/dist/enforcement/enforcement.d.ts +17 -0
- package/dist/enforcement/enforcement.js +90 -0
- package/dist/enforcement/index.d.ts +11 -0
- package/dist/enforcement/index.js +10 -0
- package/dist/enforcement/schemas/enforcement.schema.d.ts +30 -0
- package/dist/enforcement/schemas/enforcement.schema.js +36 -0
- package/dist/enforcement/types/enforcement.types.d.ts +59 -0
- package/dist/enforcement/types/enforcement.types.js +1 -0
- package/dist/enrollment/constants/enrollment.constants.d.ts +6 -0
- package/dist/enrollment/constants/enrollment.constants.js +6 -0
- package/dist/enrollment/enrollment-provider.d.ts +5 -0
- package/dist/enrollment/enrollment-provider.js +1 -0
- package/dist/enrollment/index.d.ts +7 -0
- package/dist/enrollment/index.js +1 -0
- package/dist/enrollment/manual-enrollment.d.ts +32 -0
- package/dist/enrollment/manual-enrollment.js +72 -0
- package/dist/enrollment/types/enrollment.types.d.ts +25 -0
- package/dist/enrollment/types/enrollment.types.js +1 -0
- package/dist/events/canonical-event.d.ts +10 -0
- package/dist/events/canonical-event.js +9 -0
- package/dist/events/constants/enrich.constants.d.ts +14 -0
- package/dist/events/constants/enrich.constants.js +15 -0
- package/dist/events/constants/events.constants.d.ts +35 -0
- package/dist/events/constants/events.constants.js +57 -0
- package/dist/events/enrich.d.ts +16 -0
- package/dist/events/enrich.js +226 -0
- package/dist/events/event-id.d.ts +32 -0
- package/dist/events/event-id.js +49 -0
- package/dist/events/index.d.ts +14 -0
- package/dist/events/index.js +5 -0
- package/dist/events/llm-call.d.ts +14 -0
- package/dist/events/llm-call.js +84 -0
- package/dist/events/product-event.d.ts +39 -0
- package/dist/events/product-event.js +19 -0
- package/dist/events/types/enrich.types.d.ts +25 -0
- package/dist/events/types/enrich.types.js +1 -0
- package/dist/events/types/events.types.d.ts +112 -0
- package/dist/events/types/events.types.js +1 -0
- package/dist/events/types/llm-call.types.d.ts +79 -0
- package/dist/events/types/llm-call.types.js +1 -0
- package/dist/events/types/repo-snapshot.types.d.ts +32 -0
- package/dist/events/types/repo-snapshot.types.js +1 -0
- package/dist/feature/constants/feature.constants.d.ts +10 -0
- package/dist/feature/constants/feature.constants.js +10 -0
- package/dist/feature/index.d.ts +6 -0
- package/dist/feature/index.js +6 -0
- package/dist/feature/ticket-candidates.d.ts +13 -0
- package/dist/feature/ticket-candidates.js +26 -0
- package/dist/git/constants/git.constants.d.ts +84 -0
- package/dist/git/constants/git.constants.js +113 -0
- package/dist/git/git-context.d.ts +52 -0
- package/dist/git/git-context.js +226 -0
- package/dist/git/index.d.ts +9 -0
- package/dist/git/index.js +3 -0
- package/dist/git/remote-sanitize.d.ts +26 -0
- package/dist/git/remote-sanitize.js +92 -0
- package/dist/git/repo-snapshot.d.ts +40 -0
- package/dist/git/repo-snapshot.js +95 -0
- package/dist/git/types/git.types.d.ts +36 -0
- package/dist/git/types/git.types.js +1 -0
- package/dist/git/types/snapshot.types.d.ts +25 -0
- package/dist/git/types/snapshot.types.js +1 -0
- package/dist/otlp/constants/otlp.constants.d.ts +84 -0
- package/dist/otlp/constants/otlp.constants.js +99 -0
- package/dist/otlp/http.d.ts +24 -0
- package/dist/otlp/http.js +37 -0
- package/dist/otlp/index.d.ts +9 -0
- package/dist/otlp/index.js +3 -0
- package/dist/otlp/normalize.d.ts +14 -0
- package/dist/otlp/normalize.js +404 -0
- package/dist/otlp/types/otlp.types.d.ts +69 -0
- package/dist/otlp/types/otlp.types.js +1 -0
- package/dist/pipeline/constants/pipeline.constants.d.ts +23 -0
- package/dist/pipeline/constants/pipeline.constants.js +22 -0
- package/dist/pipeline/hook-pipeline.d.ts +14 -0
- package/dist/pipeline/hook-pipeline.js +297 -0
- package/dist/pipeline/index.d.ts +6 -0
- package/dist/pipeline/index.js +1 -0
- package/dist/pipeline/types/pipeline.types.d.ts +48 -0
- package/dist/pipeline/types/pipeline.types.js +1 -0
- package/dist/privacy/constants/privacy.constants.d.ts +23 -0
- package/dist/privacy/constants/privacy.constants.js +38 -0
- package/dist/privacy/index.d.ts +7 -0
- package/dist/privacy/index.js +2 -0
- package/dist/privacy/sanitizer.d.ts +20 -0
- package/dist/privacy/sanitizer.js +52 -0
- package/dist/privacy/types/privacy.types.d.ts +13 -0
- package/dist/privacy/types/privacy.types.js +1 -0
- package/dist/providers/antigravity/antigravity.adapter.d.ts +54 -0
- package/dist/providers/antigravity/antigravity.adapter.js +311 -0
- package/dist/providers/antigravity/antigravity.detect.d.ts +25 -0
- package/dist/providers/antigravity/antigravity.detect.js +64 -0
- package/dist/providers/antigravity/antigravity.hooks.d.ts +24 -0
- package/dist/providers/antigravity/antigravity.hooks.js +126 -0
- package/dist/providers/antigravity/antigravity.provider.d.ts +2 -0
- package/dist/providers/antigravity/antigravity.provider.js +22 -0
- package/dist/providers/antigravity/constants/antigravity.constants.d.ts +72 -0
- package/dist/providers/antigravity/constants/antigravity.constants.js +75 -0
- package/dist/providers/antigravity/schemas/antigravity.schema.d.ts +521 -0
- package/dist/providers/antigravity/schemas/antigravity.schema.js +64 -0
- package/dist/providers/antigravity/types/antigravity.types.d.ts +13 -0
- package/dist/providers/antigravity/types/antigravity.types.js +1 -0
- package/dist/providers/claude/claude.adapter.d.ts +15 -0
- package/dist/providers/claude/claude.adapter.js +141 -0
- package/dist/providers/claude/claude.detect.d.ts +20 -0
- package/dist/providers/claude/claude.detect.js +57 -0
- package/dist/providers/claude/claude.hooks.d.ts +23 -0
- package/dist/providers/claude/claude.hooks.js +94 -0
- package/dist/providers/claude/claude.otel.d.ts +95 -0
- package/dist/providers/claude/claude.otel.js +331 -0
- package/dist/providers/claude/claude.provider.d.ts +2 -0
- package/dist/providers/claude/claude.provider.js +26 -0
- package/dist/providers/claude/constants/claude.constants.d.ts +34 -0
- package/dist/providers/claude/constants/claude.constants.js +54 -0
- package/dist/providers/claude/constants/claude.otel.constants.d.ts +17 -0
- package/dist/providers/claude/constants/claude.otel.constants.js +17 -0
- package/dist/providers/claude/schemas/claude.schema.d.ts +72 -0
- package/dist/providers/claude/schemas/claude.schema.js +32 -0
- package/dist/providers/claude/types/claude.types.d.ts +3 -0
- package/dist/providers/claude/types/claude.types.js +1 -0
- package/dist/providers/codex/codex.adapter.d.ts +11 -0
- package/dist/providers/codex/codex.adapter.js +106 -0
- package/dist/providers/codex/codex.detect.d.ts +30 -0
- package/dist/providers/codex/codex.detect.js +58 -0
- package/dist/providers/codex/codex.hooks.d.ts +27 -0
- package/dist/providers/codex/codex.hooks.js +129 -0
- package/dist/providers/codex/codex.otel.d.ts +51 -0
- package/dist/providers/codex/codex.otel.js +325 -0
- package/dist/providers/codex/codex.provider.d.ts +2 -0
- package/dist/providers/codex/codex.provider.js +25 -0
- package/dist/providers/codex/constants/codex.constants.d.ts +41 -0
- package/dist/providers/codex/constants/codex.constants.js +62 -0
- package/dist/providers/codex/constants/codex.otel.constants.d.ts +22 -0
- package/dist/providers/codex/constants/codex.otel.constants.js +22 -0
- package/dist/providers/codex/schemas/codex.schema.d.ts +70 -0
- package/dist/providers/codex/schemas/codex.schema.js +32 -0
- package/dist/providers/codex/types/codex.types.d.ts +3 -0
- package/dist/providers/codex/types/codex.types.js +1 -0
- package/dist/providers/constants/provider.constants.d.ts +33 -0
- package/dist/providers/constants/provider.constants.js +33 -0
- package/dist/providers/cursor/constants/cursor.constants.d.ts +58 -0
- package/dist/providers/cursor/constants/cursor.constants.js +95 -0
- package/dist/providers/cursor/cursor.adapter.d.ts +11 -0
- package/dist/providers/cursor/cursor.adapter.js +331 -0
- package/dist/providers/cursor/cursor.detect.d.ts +23 -0
- package/dist/providers/cursor/cursor.detect.js +66 -0
- package/dist/providers/cursor/cursor.hooks.d.ts +25 -0
- package/dist/providers/cursor/cursor.hooks.js +95 -0
- package/dist/providers/cursor/cursor.provider.d.ts +2 -0
- package/dist/providers/cursor/cursor.provider.js +27 -0
- package/dist/providers/cursor/schemas/cursor.schema.d.ts +130 -0
- package/dist/providers/cursor/schemas/cursor.schema.js +62 -0
- package/dist/providers/cursor/types/cursor.types.d.ts +3 -0
- package/dist/providers/cursor/types/cursor.types.js +1 -0
- package/dist/providers/gemini/constants/gemini.constants.d.ts +36 -0
- package/dist/providers/gemini/constants/gemini.constants.js +58 -0
- package/dist/providers/gemini/constants/gemini.otel.constants.d.ts +34 -0
- package/dist/providers/gemini/constants/gemini.otel.constants.js +48 -0
- package/dist/providers/gemini/gemini.adapter.d.ts +15 -0
- package/dist/providers/gemini/gemini.adapter.js +146 -0
- package/dist/providers/gemini/gemini.detect.d.ts +23 -0
- package/dist/providers/gemini/gemini.detect.js +78 -0
- package/dist/providers/gemini/gemini.hooks.d.ts +22 -0
- package/dist/providers/gemini/gemini.hooks.js +93 -0
- package/dist/providers/gemini/gemini.otel.d.ts +62 -0
- package/dist/providers/gemini/gemini.otel.js +274 -0
- package/dist/providers/gemini/gemini.provider.d.ts +2 -0
- package/dist/providers/gemini/gemini.provider.js +22 -0
- package/dist/providers/gemini/schemas/gemini.schema.d.ts +81 -0
- package/dist/providers/gemini/schemas/gemini.schema.js +35 -0
- package/dist/providers/gemini/types/gemini.types.d.ts +3 -0
- package/dist/providers/gemini/types/gemini.types.js +1 -0
- package/dist/providers/index.d.ts +14 -0
- package/dist/providers/index.js +8 -0
- package/dist/providers/provider.d.ts +16 -0
- package/dist/providers/provider.js +149 -0
- package/dist/providers/registry.d.ts +12 -0
- package/dist/providers/registry.js +23 -0
- package/dist/providers/shared/constants/hook-refusal.constants.d.ts +6 -0
- package/dist/providers/shared/constants/hook-refusal.constants.js +6 -0
- package/dist/providers/shared/constants/tooling.constants.d.ts +25 -0
- package/dist/providers/shared/constants/tooling.constants.js +25 -0
- package/dist/providers/shared/event-builder.d.ts +85 -0
- package/dist/providers/shared/event-builder.js +166 -0
- package/dist/providers/shared/hook-config.d.ts +80 -0
- package/dist/providers/shared/hook-config.js +164 -0
- package/dist/providers/shared/hook-refusal.d.ts +16 -0
- package/dist/providers/shared/hook-refusal.js +33 -0
- package/dist/providers/shared/install-record.d.ts +75 -0
- package/dist/providers/shared/install-record.js +113 -0
- package/dist/providers/shared/tooling.d.ts +58 -0
- package/dist/providers/shared/tooling.js +103 -0
- package/dist/providers/shared/types/adapter.types.d.ts +54 -0
- package/dist/providers/shared/types/adapter.types.js +1 -0
- package/dist/providers/shared/types/hook-config.types.d.ts +32 -0
- package/dist/providers/shared/types/hook-config.types.js +1 -0
- package/dist/providers/types/provider.types.d.ts +98 -0
- package/dist/providers/types/provider.types.js +1 -0
- package/dist/snapshot/branch-selection.d.ts +37 -0
- package/dist/snapshot/branch-selection.js +69 -0
- package/dist/snapshot/budget.d.ts +41 -0
- package/dist/snapshot/budget.js +67 -0
- package/dist/snapshot/constants/snapshot-stages.constants.d.ts +11 -0
- package/dist/snapshot/constants/snapshot-stages.constants.js +11 -0
- package/dist/snapshot/constants/snapshot.constants.d.ts +56 -0
- package/dist/snapshot/constants/snapshot.constants.js +56 -0
- package/dist/snapshot/index.d.ts +16 -0
- package/dist/snapshot/index.js +6 -0
- package/dist/snapshot/snapshot-event.d.ts +17 -0
- package/dist/snapshot/snapshot-event.js +66 -0
- package/dist/snapshot/snapshot-pipeline.d.ts +14 -0
- package/dist/snapshot/snapshot-pipeline.js +163 -0
- package/dist/snapshot/snapshot-state.d.ts +55 -0
- package/dist/snapshot/snapshot-state.js +100 -0
- package/dist/snapshot/types/snapshot.types.d.ts +86 -0
- package/dist/snapshot/types/snapshot.types.js +1 -0
- package/dist/storage/atomic-file.d.ts +25 -0
- package/dist/storage/atomic-file.js +76 -0
- package/dist/storage/constants/storage.constants.d.ts +34 -0
- package/dist/storage/constants/storage.constants.js +35 -0
- package/dist/storage/index.d.ts +10 -0
- package/dist/storage/index.js +5 -0
- package/dist/storage/install-state.d.ts +20 -0
- package/dist/storage/install-state.js +40 -0
- package/dist/storage/json-file.d.ts +13 -0
- package/dist/storage/json-file.js +31 -0
- package/dist/storage/lock.d.ts +15 -0
- package/dist/storage/lock.js +70 -0
- package/dist/storage/paths.d.ts +14 -0
- package/dist/storage/paths.js +42 -0
- package/dist/storage/schemas/storage.schema.d.ts +128 -0
- package/dist/storage/schemas/storage.schema.js +27 -0
- package/dist/storage/types/storage.types.d.ts +36 -0
- package/dist/storage/types/storage.types.js +1 -0
- package/dist/transport/constants/transport.constants.d.ts +47 -0
- package/dist/transport/constants/transport.constants.js +47 -0
- package/dist/transport/cooldown.d.ts +35 -0
- package/dist/transport/cooldown.js +62 -0
- package/dist/transport/delivery-stats.d.ts +65 -0
- package/dist/transport/delivery-stats.js +186 -0
- package/dist/transport/delivery.d.ts +26 -0
- package/dist/transport/delivery.js +80 -0
- package/dist/transport/headers.d.ts +12 -0
- package/dist/transport/headers.js +19 -0
- package/dist/transport/http-transport.d.ts +39 -0
- package/dist/transport/http-transport.js +106 -0
- package/dist/transport/index.d.ts +13 -0
- package/dist/transport/index.js +7 -0
- package/dist/transport/queue.d.ts +177 -0
- package/dist/transport/queue.js +474 -0
- package/dist/transport/schemas/queue.schema.d.ts +30 -0
- package/dist/transport/schemas/queue.schema.js +18 -0
- package/dist/transport/transport.d.ts +6 -0
- package/dist/transport/transport.js +1 -0
- package/dist/transport/types/transport.types.d.ts +102 -0
- package/dist/transport/types/transport.types.js +1 -0
- package/dist/turns/aggregate-usage.d.ts +20 -0
- package/dist/turns/aggregate-usage.js +269 -0
- package/dist/turns/claude-transcript.d.ts +18 -0
- package/dist/turns/claude-transcript.js +80 -0
- package/dist/turns/constants/turns.constants.d.ts +69 -0
- package/dist/turns/constants/turns.constants.js +86 -0
- package/dist/turns/cursor-transcript.d.ts +21 -0
- package/dist/turns/cursor-transcript.js +66 -0
- package/dist/turns/index.d.ts +17 -0
- package/dist/turns/index.js +7 -0
- package/dist/turns/transcript.d.ts +74 -0
- package/dist/turns/transcript.js +188 -0
- package/dist/turns/turn-state.d.ts +94 -0
- package/dist/turns/turn-state.js +234 -0
- package/dist/turns/turn-summary.d.ts +27 -0
- package/dist/turns/turn-summary.js +164 -0
- package/dist/turns/turn-tracker.d.ts +14 -0
- package/dist/turns/turn-tracker.js +521 -0
- package/dist/turns/types/aggregate-usage.types.d.ts +26 -0
- package/dist/turns/types/aggregate-usage.types.js +1 -0
- package/dist/turns/types/transcript.types.d.ts +41 -0
- package/dist/turns/types/transcript.types.js +1 -0
- package/dist/turns/types/turn-state.types.d.ts +37 -0
- package/dist/turns/types/turn-state.types.js +1 -0
- package/dist/turns/types/turn-summary.types.d.ts +106 -0
- package/dist/turns/types/turn-summary.types.js +1 -0
- package/dist/turns/types/turn-tracker.types.d.ts +27 -0
- package/dist/turns/types/turn-tracker.types.js +1 -0
- package/example/README.md +43 -0
- package/example/server.mjs +240 -0
- package/package.json +89 -0
|
@@ -0,0 +1,474 @@
|
|
|
1
|
+
import fs from 'node:fs/promises';
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
import { pollUntil } from '../core/async.js';
|
|
4
|
+
import { debugLog } from '../core/logger.js';
|
|
5
|
+
import { PRODUCT_EVENT_TYPE_SET } from '../events/constants/events.constants.js';
|
|
6
|
+
import { writeFileAtomic } from '../storage/atomic-file.js';
|
|
7
|
+
import { acquireLock } from '../storage/lock.js';
|
|
8
|
+
import { SECRET_FILE_MODE } from '../storage/constants/storage.constants.js';
|
|
9
|
+
import { ANY_DESTINATION, BACKOFF_BASE_MS, BACKOFF_JITTER_MIN, BACKOFF_JITTER_RANGE, BACKOFF_MAX_MS, MAX_ISOLATION_SENDS, MS_PER_DAY, QUEUE_DRAIN_LOCK, QUEUE_FILE_SUFFIX, RETARGET_LOCK_POLL_MS, RETARGET_LOCK_WAIT_MS, RE_UNSAFE_QUEUE_NAME } from './constants/transport.constants.js';
|
|
10
|
+
import { queueEntrySchema } from './schemas/queue.schema.js';
|
|
11
|
+
export { ANY_DESTINATION } from './constants/transport.constants.js';
|
|
12
|
+
/**
|
|
13
|
+
* File-per-event offline queue.
|
|
14
|
+
*
|
|
15
|
+
* The filename *is* the deterministic event id, which is what makes enqueueing
|
|
16
|
+
* idempotent: the same event can never be queued twice, however many hooks race
|
|
17
|
+
* to write it.
|
|
18
|
+
*/
|
|
19
|
+
export class EventQueue {
|
|
20
|
+
options;
|
|
21
|
+
now;
|
|
22
|
+
/**
|
|
23
|
+
* Bind the queue to its directories and bounds.
|
|
24
|
+
*
|
|
25
|
+
* @param options - Directories, bounds and the clock.
|
|
26
|
+
*/
|
|
27
|
+
constructor(options) {
|
|
28
|
+
this.options = options;
|
|
29
|
+
this.now = options.now ?? (() => new Date());
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* Persist events for a later attempt.
|
|
33
|
+
*
|
|
34
|
+
* @param events - Events to keep.
|
|
35
|
+
* @param destination - Events URL they are pinned to, when one is configured.
|
|
36
|
+
*/
|
|
37
|
+
async enqueue(events, destination) {
|
|
38
|
+
if (events.length === 0)
|
|
39
|
+
return;
|
|
40
|
+
await fs.mkdir(this.options.queueDir, { recursive: true });
|
|
41
|
+
for (const event of events) {
|
|
42
|
+
const file = this.fileFor(event.id);
|
|
43
|
+
if (await exists(file))
|
|
44
|
+
continue; // dedup by deterministic id
|
|
45
|
+
const at = this.now().toISOString();
|
|
46
|
+
// 0600: a queued turn summary holds prompt and response text.
|
|
47
|
+
await writeFileAtomic(file, JSON.stringify({ event, attempts: 0, firstQueuedAt: at, nextAttemptAt: at, destination }), SECRET_FILE_MODE);
|
|
48
|
+
}
|
|
49
|
+
await this.enforceBound();
|
|
50
|
+
}
|
|
51
|
+
/**
|
|
52
|
+
* How many events are waiting.
|
|
53
|
+
*
|
|
54
|
+
* @returns The entry count.
|
|
55
|
+
*/
|
|
56
|
+
async pendingCount() {
|
|
57
|
+
return (await this.listFiles()).length;
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* Age of the oldest waiting event.
|
|
61
|
+
*
|
|
62
|
+
* @returns Milliseconds, or undefined when the queue is empty.
|
|
63
|
+
*/
|
|
64
|
+
async oldestPendingAgeMs() {
|
|
65
|
+
let oldest;
|
|
66
|
+
for (const name of await this.listFiles()) {
|
|
67
|
+
const entry = await this.readEntry(path.join(this.options.queueDir, name));
|
|
68
|
+
const queuedAt = entry ? Date.parse(entry.firstQueuedAt) : NaN;
|
|
69
|
+
if (!Number.isFinite(queuedAt))
|
|
70
|
+
continue;
|
|
71
|
+
if (oldest === undefined || queuedAt < oldest)
|
|
72
|
+
oldest = queuedAt;
|
|
73
|
+
}
|
|
74
|
+
if (oldest === undefined)
|
|
75
|
+
return undefined;
|
|
76
|
+
return this.now().getTime() - oldest;
|
|
77
|
+
}
|
|
78
|
+
/**
|
|
79
|
+
* Send due queued events through the transport.
|
|
80
|
+
*
|
|
81
|
+
* Serialized by a lock so concurrent hook invocations cannot double-send, and
|
|
82
|
+
* bounded by maxBatch because this runs inside the agent's hook process.
|
|
83
|
+
*
|
|
84
|
+
* The recorder's methods must not throw: failures have to be swallowed by the
|
|
85
|
+
* implementation, because drain is on the critical path and is not wrapped
|
|
86
|
+
* against recorder errors.
|
|
87
|
+
*
|
|
88
|
+
* @param transport - Where to send.
|
|
89
|
+
* @param maxBatch - Ceiling on events sent in one pass.
|
|
90
|
+
* @param statsRecorder - Optional sink for what this pass lost.
|
|
91
|
+
* @returns What the pass sent, failed, dropped and had rejected.
|
|
92
|
+
*/
|
|
93
|
+
async drain(transport, maxBatch, statsRecorder) {
|
|
94
|
+
const release = await acquireLock(this.options.locksDir, QUEUE_DRAIN_LOCK, this.now);
|
|
95
|
+
if (!release)
|
|
96
|
+
return { sent: 0, failed: 0, dropped: 0, rejected: 0, skipped: true };
|
|
97
|
+
try {
|
|
98
|
+
const nowMs = this.now().getTime();
|
|
99
|
+
const collected = await this.collectDue(transport, nowMs);
|
|
100
|
+
// Oldest first: hash-ordered filenames would otherwise let a large
|
|
101
|
+
// backlog defer the same late-sorting entries on every drain.
|
|
102
|
+
const batch = collected.due
|
|
103
|
+
.slice()
|
|
104
|
+
.sort((a, b) => Date.parse(a.entry.firstQueuedAt) - Date.parse(b.entry.firstQueuedAt))
|
|
105
|
+
.slice(0, maxBatch);
|
|
106
|
+
const sent = batch.length === 0 ? EMPTY_DELTA : await this.sendBatch(transport, batch, nowMs);
|
|
107
|
+
const stats = { ...mergeDeltas(collected.delta, sent), skipped: false };
|
|
108
|
+
await report(statsRecorder, stats);
|
|
109
|
+
return stats;
|
|
110
|
+
}
|
|
111
|
+
finally {
|
|
112
|
+
await release();
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
/**
|
|
116
|
+
* Re-pin entries queued for one destination to another.
|
|
117
|
+
*
|
|
118
|
+
* Setup calls this — with the user's explicit consent — after the backend URL
|
|
119
|
+
* changes, so the backlog follows instead of expiring pinned to a URL nothing
|
|
120
|
+
* will ever drain. Entries pinned to any *other* backend stay untouched: this
|
|
121
|
+
* re-routes one reconfigured destination, it is not a license to replay one
|
|
122
|
+
* backend's data to another.
|
|
123
|
+
*
|
|
124
|
+
* Runs under the drain lock so a concurrent drain cannot resurrect the old
|
|
125
|
+
* destination from a stale in-memory copy.
|
|
126
|
+
*
|
|
127
|
+
* @param destination - The new events URL.
|
|
128
|
+
* @param previousDestination - The URL being replaced.
|
|
129
|
+
* @returns False when the lock never freed and nothing was re-pinned.
|
|
130
|
+
*/
|
|
131
|
+
async retarget(destination, previousDestination) {
|
|
132
|
+
const release = await this.waitForDrainLock();
|
|
133
|
+
if (!release)
|
|
134
|
+
return false;
|
|
135
|
+
try {
|
|
136
|
+
for (const name of await this.listFiles()) {
|
|
137
|
+
const file = path.join(this.options.queueDir, name);
|
|
138
|
+
const entry = await this.readEntry(file);
|
|
139
|
+
if (!entry || entry.destination !== previousDestination)
|
|
140
|
+
continue;
|
|
141
|
+
await writeFileAtomic(file, JSON.stringify({ ...entry, destination }), SECRET_FILE_MODE);
|
|
142
|
+
}
|
|
143
|
+
return true;
|
|
144
|
+
}
|
|
145
|
+
finally {
|
|
146
|
+
await release();
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
/**
|
|
150
|
+
* Entries pinned to exactly this destination; legacy and ANY entries are not
|
|
151
|
+
* counted, because they are not stranded.
|
|
152
|
+
*
|
|
153
|
+
* @param destination - Events URL to count for.
|
|
154
|
+
* @returns The entry count.
|
|
155
|
+
*/
|
|
156
|
+
async pendingFor(destination) {
|
|
157
|
+
let count = 0;
|
|
158
|
+
for (const name of await this.listFiles()) {
|
|
159
|
+
const entry = await this.readEntry(path.join(this.options.queueDir, name));
|
|
160
|
+
if (entry?.destination === destination)
|
|
161
|
+
count++;
|
|
162
|
+
}
|
|
163
|
+
return count;
|
|
164
|
+
}
|
|
165
|
+
/**
|
|
166
|
+
* Entries due for this transport, dropping the ones that can never be sent.
|
|
167
|
+
*
|
|
168
|
+
* @param transport - Where the pass will send.
|
|
169
|
+
* @param nowMs - This pass's clock reading.
|
|
170
|
+
* @returns The due entries and what collecting them dropped.
|
|
171
|
+
*/
|
|
172
|
+
async collectDue(transport, nowMs) {
|
|
173
|
+
const due = [];
|
|
174
|
+
let dropped = 0;
|
|
175
|
+
for (const name of await this.listFiles()) {
|
|
176
|
+
const file = path.join(this.options.queueDir, name);
|
|
177
|
+
const entry = await this.readEntry(file);
|
|
178
|
+
if (!entry || this.isExpired(entry, nowMs) || !isProductEntry(entry)) {
|
|
179
|
+
// Unreadable, aged out, or — for a backlog written by a pre-product
|
|
180
|
+
// release — an internal lifecycle event the backend does not accept.
|
|
181
|
+
// Draining one of those would poison every batch it rides in.
|
|
182
|
+
await fs.rm(file, { force: true });
|
|
183
|
+
dropped += 1;
|
|
184
|
+
continue;
|
|
185
|
+
}
|
|
186
|
+
if (!matchesDestination(entry.destination, transport.destination))
|
|
187
|
+
continue;
|
|
188
|
+
if (Date.parse(entry.nextAttemptAt) <= nowMs)
|
|
189
|
+
due.push({ file, entry });
|
|
190
|
+
}
|
|
191
|
+
return { due, delta: { ...EMPTY_DELTA, dropped } };
|
|
192
|
+
}
|
|
193
|
+
/**
|
|
194
|
+
* Send one batch, isolating a poison entry when the backend refuses it.
|
|
195
|
+
*
|
|
196
|
+
* @param transport - Where to send.
|
|
197
|
+
* @param batch - Entries to send.
|
|
198
|
+
* @param nowMs - This pass's clock reading.
|
|
199
|
+
* @returns What the send accomplished and cost.
|
|
200
|
+
*/
|
|
201
|
+
async sendBatch(transport, batch, nowMs) {
|
|
202
|
+
const result = await transport.send(batch.map(({ entry }) => entry.event));
|
|
203
|
+
if (result.ok) {
|
|
204
|
+
await Promise.all(batch.map(({ file }) => fs.rm(file, { force: true })));
|
|
205
|
+
return { ...EMPTY_DELTA, sent: batch.length, rejected: reportRejected(result.counters?.rejected, 'the drained batch') };
|
|
206
|
+
}
|
|
207
|
+
debugLog('queue drain failed', result.error ?? `status ${result.status}`);
|
|
208
|
+
if (!result.retryable && batch.length > 1)
|
|
209
|
+
return this.isolateBatch(transport, batch, nowMs);
|
|
210
|
+
let delta = EMPTY_DELTA;
|
|
211
|
+
for (const { file, entry } of batch) {
|
|
212
|
+
delta = mergeDeltas(delta, await this.recordFailure(file, entry, nowMs));
|
|
213
|
+
}
|
|
214
|
+
return delta;
|
|
215
|
+
}
|
|
216
|
+
/**
|
|
217
|
+
* Retry a refused batch one entry at a time.
|
|
218
|
+
*
|
|
219
|
+
* The backend rejected the batch outright, but that verdict belongs to at most
|
|
220
|
+
* a few events. Sending entries alone stops one poison record taking its
|
|
221
|
+
* healthy co-batched neighbours down with it. The probes are capped: drain runs
|
|
222
|
+
* inside the agent's hook process and each send can cost the full transport
|
|
223
|
+
* timeout, so the remainder keeps its backoff and is probed on a later drain.
|
|
224
|
+
*
|
|
225
|
+
* @param transport - Where to send.
|
|
226
|
+
* @param batch - Entries the batch send refused.
|
|
227
|
+
* @param nowMs - This pass's clock reading.
|
|
228
|
+
* @returns What the probes accomplished and cost.
|
|
229
|
+
*/
|
|
230
|
+
async isolateBatch(transport, batch, nowMs) {
|
|
231
|
+
let delta = EMPTY_DELTA;
|
|
232
|
+
let probes = 0;
|
|
233
|
+
for (const { file, entry } of batch) {
|
|
234
|
+
if (probes >= MAX_ISOLATION_SENDS) {
|
|
235
|
+
delta = mergeDeltas(delta, await this.recordFailure(file, entry, nowMs));
|
|
236
|
+
continue;
|
|
237
|
+
}
|
|
238
|
+
probes += 1;
|
|
239
|
+
const single = await transport.send([entry.event]);
|
|
240
|
+
if (!single.ok) {
|
|
241
|
+
delta = mergeDeltas(delta, await this.recordFailure(file, entry, nowMs));
|
|
242
|
+
continue;
|
|
243
|
+
}
|
|
244
|
+
await fs.rm(file, { force: true });
|
|
245
|
+
delta = mergeDeltas(delta, { ...EMPTY_DELTA, sent: 1, rejected: reportRejected(single.counters?.rejected, 'an isolation probe') });
|
|
246
|
+
}
|
|
247
|
+
return delta;
|
|
248
|
+
}
|
|
249
|
+
/**
|
|
250
|
+
* Acquire the drain lock, waiting a bounded time.
|
|
251
|
+
*
|
|
252
|
+
* @returns The release function, or undefined on timeout.
|
|
253
|
+
*/
|
|
254
|
+
waitForDrainLock() {
|
|
255
|
+
return pollUntil(() => acquireLock(this.options.locksDir, QUEUE_DRAIN_LOCK, this.now), RETARGET_LOCK_WAIT_MS, RETARGET_LOCK_POLL_MS);
|
|
256
|
+
}
|
|
257
|
+
/**
|
|
258
|
+
* Back a failed entry off, or drop it once its budget is spent.
|
|
259
|
+
*
|
|
260
|
+
* Even a "permanent" HTTP status can be a transient route or schema mismatch
|
|
261
|
+
* on the backend, so an entry is dropped only once maxAttempts (or the age
|
|
262
|
+
* bound) is exhausted — never on the first refusal.
|
|
263
|
+
*
|
|
264
|
+
* @param file - The entry's file.
|
|
265
|
+
* @param entry - The entry.
|
|
266
|
+
* @param nowMs - This pass's clock reading.
|
|
267
|
+
* @returns Whether the entry was backed off or lost.
|
|
268
|
+
*/
|
|
269
|
+
async recordFailure(file, entry, nowMs) {
|
|
270
|
+
const attempts = entry.attempts + 1;
|
|
271
|
+
if (attempts >= this.options.maxAttempts) {
|
|
272
|
+
// Out of attempts: the event is gone for good, which is exactly what the
|
|
273
|
+
// dropped counter has to survive to say.
|
|
274
|
+
debugLog(`dropping a queued event after ${attempts} failed attempt(s)`);
|
|
275
|
+
await fs.rm(file, { force: true });
|
|
276
|
+
return { ...EMPTY_DELTA, dropped: 1 };
|
|
277
|
+
}
|
|
278
|
+
const nextAttemptAt = new Date(nowMs + backoffMs(attempts)).toISOString();
|
|
279
|
+
await writeFileAtomic(file, JSON.stringify({ ...entry, attempts, nextAttemptAt }), SECRET_FILE_MODE);
|
|
280
|
+
return { ...EMPTY_DELTA, failed: 1 };
|
|
281
|
+
}
|
|
282
|
+
/**
|
|
283
|
+
* File one event is queued in.
|
|
284
|
+
*
|
|
285
|
+
* @param eventId - The deterministic event id.
|
|
286
|
+
* @returns Absolute file path.
|
|
287
|
+
*/
|
|
288
|
+
fileFor(eventId) {
|
|
289
|
+
return path.join(this.options.queueDir, `${eventId.replace(RE_UNSAFE_QUEUE_NAME, '_')}${QUEUE_FILE_SUFFIX}`);
|
|
290
|
+
}
|
|
291
|
+
/**
|
|
292
|
+
* Queue filenames, sorted.
|
|
293
|
+
*
|
|
294
|
+
* @returns The names, or an empty list when the directory is absent.
|
|
295
|
+
*/
|
|
296
|
+
async listFiles() {
|
|
297
|
+
try {
|
|
298
|
+
const names = await fs.readdir(this.options.queueDir);
|
|
299
|
+
return names.filter((name) => name.endsWith(QUEUE_FILE_SUFFIX)).sort();
|
|
300
|
+
}
|
|
301
|
+
catch {
|
|
302
|
+
return [];
|
|
303
|
+
}
|
|
304
|
+
}
|
|
305
|
+
/**
|
|
306
|
+
* Read and validate one entry.
|
|
307
|
+
*
|
|
308
|
+
* @param file - Entry file.
|
|
309
|
+
* @returns The entry, or undefined when it cannot be used.
|
|
310
|
+
*/
|
|
311
|
+
async readEntry(file) {
|
|
312
|
+
try {
|
|
313
|
+
const parsed = queueEntrySchema.safeParse(JSON.parse(await fs.readFile(file, 'utf8')));
|
|
314
|
+
return parsed.success ? parsed.data : undefined;
|
|
315
|
+
}
|
|
316
|
+
catch {
|
|
317
|
+
return undefined;
|
|
318
|
+
}
|
|
319
|
+
}
|
|
320
|
+
/**
|
|
321
|
+
* Whether an entry has outlived the age bound.
|
|
322
|
+
*
|
|
323
|
+
* @param entry - The entry.
|
|
324
|
+
* @param nowMs - This pass's clock reading.
|
|
325
|
+
* @returns True when it should be dropped.
|
|
326
|
+
*/
|
|
327
|
+
isExpired(entry, nowMs) {
|
|
328
|
+
return nowMs - Date.parse(entry.firstQueuedAt) > this.options.maxEventAgeDays * MS_PER_DAY;
|
|
329
|
+
}
|
|
330
|
+
/**
|
|
331
|
+
* Keep the queue bounded, sacrificing the entries that have waited longest.
|
|
332
|
+
*
|
|
333
|
+
* The oldest are the least likely to still be deliverable, and an unbounded
|
|
334
|
+
* queue on a developer machine is a disk-space bug.
|
|
335
|
+
*/
|
|
336
|
+
async enforceBound() {
|
|
337
|
+
const files = await this.listFiles();
|
|
338
|
+
const excess = files.length - this.options.maxEvents;
|
|
339
|
+
if (excess <= 0)
|
|
340
|
+
return;
|
|
341
|
+
const dated = [];
|
|
342
|
+
for (const name of files) {
|
|
343
|
+
const full = path.join(this.options.queueDir, name);
|
|
344
|
+
const queuedAt = await this.queuedAt(full);
|
|
345
|
+
if (queuedAt !== undefined)
|
|
346
|
+
dated.push({ full, queuedAt });
|
|
347
|
+
}
|
|
348
|
+
const doomed = dated.sort((a, b) => a.queuedAt - b.queuedAt).slice(0, excess);
|
|
349
|
+
for (const { full } of doomed) {
|
|
350
|
+
await fs.rm(full, { force: true });
|
|
351
|
+
}
|
|
352
|
+
}
|
|
353
|
+
/**
|
|
354
|
+
* When an entry was first queued, falling back to the file clock.
|
|
355
|
+
*
|
|
356
|
+
* An unreadable entry still has to age out, or it would pin the queue at its
|
|
357
|
+
* bound forever.
|
|
358
|
+
*
|
|
359
|
+
* @param full - Entry file.
|
|
360
|
+
* @returns Epoch milliseconds, or undefined when the file vanished.
|
|
361
|
+
*/
|
|
362
|
+
async queuedAt(full) {
|
|
363
|
+
const entry = await this.readEntry(full);
|
|
364
|
+
if (entry)
|
|
365
|
+
return Date.parse(entry.firstQueuedAt);
|
|
366
|
+
try {
|
|
367
|
+
return (await fs.stat(full)).mtimeMs;
|
|
368
|
+
}
|
|
369
|
+
catch {
|
|
370
|
+
return undefined;
|
|
371
|
+
}
|
|
372
|
+
}
|
|
373
|
+
}
|
|
374
|
+
const EMPTY_DELTA = { sent: 0, failed: 0, dropped: 0, rejected: 0 };
|
|
375
|
+
/**
|
|
376
|
+
* Combine what two steps of a pass accomplished.
|
|
377
|
+
*
|
|
378
|
+
* @param left - One step's delta.
|
|
379
|
+
* @param right - The next step's delta.
|
|
380
|
+
* @returns Their sum.
|
|
381
|
+
*/
|
|
382
|
+
function mergeDeltas(left, right) {
|
|
383
|
+
return {
|
|
384
|
+
sent: left.sent + right.sent,
|
|
385
|
+
failed: left.failed + right.failed,
|
|
386
|
+
dropped: left.dropped + right.dropped,
|
|
387
|
+
rejected: left.rejected + right.rejected
|
|
388
|
+
};
|
|
389
|
+
}
|
|
390
|
+
/**
|
|
391
|
+
* Log events the backend permanently refused inside an accepted batch.
|
|
392
|
+
*
|
|
393
|
+
* @param rejected - Count the backend reported.
|
|
394
|
+
* @param source - What to name in the diagnostic.
|
|
395
|
+
* @returns The count, normalized to a number.
|
|
396
|
+
*/
|
|
397
|
+
function reportRejected(rejected, source) {
|
|
398
|
+
if (!rejected || rejected <= 0)
|
|
399
|
+
return 0;
|
|
400
|
+
debugLog(`backend permanently rejected ${rejected} event(s) from ${source}`);
|
|
401
|
+
return rejected;
|
|
402
|
+
}
|
|
403
|
+
/**
|
|
404
|
+
* Persist what this pass lost.
|
|
405
|
+
*
|
|
406
|
+
* Called once per drain rather than at each drop site: the stats file is
|
|
407
|
+
* lock-serialized, and one write per pass keeps drain off the critical path.
|
|
408
|
+
*
|
|
409
|
+
* @param recorder - Sink, when the caller supplied one.
|
|
410
|
+
* @param stats - What the pass lost.
|
|
411
|
+
*/
|
|
412
|
+
async function report(recorder, stats) {
|
|
413
|
+
if (!recorder)
|
|
414
|
+
return;
|
|
415
|
+
if (stats.rejected > 0)
|
|
416
|
+
await recorder.recordRejected(stats.rejected);
|
|
417
|
+
if (stats.dropped > 0)
|
|
418
|
+
await recorder.recordDropped(stats.dropped);
|
|
419
|
+
}
|
|
420
|
+
/**
|
|
421
|
+
* Whether an entry may be sent to this transport.
|
|
422
|
+
*
|
|
423
|
+
* Entries pinned to another backend are never re-routed at drain time; they wait
|
|
424
|
+
* for their own backend, or for `retarget` when setup reconfigures the URL.
|
|
425
|
+
* Legacy entries without destination metadata predate pinning, so they flow to
|
|
426
|
+
* the first configured backend just like ANY_DESTINATION entries.
|
|
427
|
+
*
|
|
428
|
+
* @param entry - The entry's pinned destination.
|
|
429
|
+
* @param transport - The transport's destination.
|
|
430
|
+
* @returns True when the entry belongs to this transport.
|
|
431
|
+
*/
|
|
432
|
+
function matchesDestination(entry, transport) {
|
|
433
|
+
if (entry === undefined || entry === ANY_DESTINATION)
|
|
434
|
+
return true;
|
|
435
|
+
return entry === transport;
|
|
436
|
+
}
|
|
437
|
+
/**
|
|
438
|
+
* Whether a queued record is one the backend still accepts.
|
|
439
|
+
*
|
|
440
|
+
* @param entry - The entry.
|
|
441
|
+
* @returns True for an llm.call or turn.summary.
|
|
442
|
+
*/
|
|
443
|
+
function isProductEntry(entry) {
|
|
444
|
+
const type = entry.event.event?.type;
|
|
445
|
+
return typeof type === 'string' && PRODUCT_EVENT_TYPE_SET.has(type);
|
|
446
|
+
}
|
|
447
|
+
/**
|
|
448
|
+
* Backoff for the nth attempt, with jitter.
|
|
449
|
+
*
|
|
450
|
+
* The jitter matters: without it every entry of a refused batch retries in the
|
|
451
|
+
* same millisecond, so the backend gets the same thundering herd it just failed.
|
|
452
|
+
*
|
|
453
|
+
* @param attempts - Attempts made so far, including this failure.
|
|
454
|
+
* @returns Delay in milliseconds.
|
|
455
|
+
*/
|
|
456
|
+
function backoffMs(attempts) {
|
|
457
|
+
const base = Math.min(BACKOFF_BASE_MS * 2 ** (attempts - 1), BACKOFF_MAX_MS);
|
|
458
|
+
return Math.floor(base * (BACKOFF_JITTER_MIN + Math.random() * BACKOFF_JITTER_RANGE));
|
|
459
|
+
}
|
|
460
|
+
/**
|
|
461
|
+
* Whether a file exists.
|
|
462
|
+
*
|
|
463
|
+
* @param file - Path to test.
|
|
464
|
+
* @returns True when it does.
|
|
465
|
+
*/
|
|
466
|
+
async function exists(file) {
|
|
467
|
+
try {
|
|
468
|
+
await fs.access(file);
|
|
469
|
+
return true;
|
|
470
|
+
}
|
|
471
|
+
catch {
|
|
472
|
+
return false;
|
|
473
|
+
}
|
|
474
|
+
}
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
/**
|
|
3
|
+
* One persisted offline-queue entry.
|
|
4
|
+
*
|
|
5
|
+
* Passthrough so an entry written by a newer version survives a downgrade with
|
|
6
|
+
* its unknown fields intact rather than being dropped as invalid — which, for
|
|
7
|
+
* this file, would mean losing the event.
|
|
8
|
+
*/
|
|
9
|
+
export declare const queueEntrySchema: z.ZodObject<{
|
|
10
|
+
event: z.ZodRecord<z.ZodString, z.ZodUnknown>;
|
|
11
|
+
attempts: z.ZodDefault<z.ZodNumber>;
|
|
12
|
+
firstQueuedAt: z.ZodString;
|
|
13
|
+
nextAttemptAt: z.ZodString;
|
|
14
|
+
/** Events URL this entry was queued for; absent on pre-destination entries. */
|
|
15
|
+
destination: z.ZodOptional<z.ZodString>;
|
|
16
|
+
}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
|
|
17
|
+
event: z.ZodRecord<z.ZodString, z.ZodUnknown>;
|
|
18
|
+
attempts: z.ZodDefault<z.ZodNumber>;
|
|
19
|
+
firstQueuedAt: z.ZodString;
|
|
20
|
+
nextAttemptAt: z.ZodString;
|
|
21
|
+
/** Events URL this entry was queued for; absent on pre-destination entries. */
|
|
22
|
+
destination: z.ZodOptional<z.ZodString>;
|
|
23
|
+
}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
|
|
24
|
+
event: z.ZodRecord<z.ZodString, z.ZodUnknown>;
|
|
25
|
+
attempts: z.ZodDefault<z.ZodNumber>;
|
|
26
|
+
firstQueuedAt: z.ZodString;
|
|
27
|
+
nextAttemptAt: z.ZodString;
|
|
28
|
+
/** Events URL this entry was queued for; absent on pre-destination entries. */
|
|
29
|
+
destination: z.ZodOptional<z.ZodString>;
|
|
30
|
+
}, z.ZodTypeAny, "passthrough">>;
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
/**
|
|
3
|
+
* One persisted offline-queue entry.
|
|
4
|
+
*
|
|
5
|
+
* Passthrough so an entry written by a newer version survives a downgrade with
|
|
6
|
+
* its unknown fields intact rather than being dropped as invalid — which, for
|
|
7
|
+
* this file, would mean losing the event.
|
|
8
|
+
*/
|
|
9
|
+
export const queueEntrySchema = z
|
|
10
|
+
.object({
|
|
11
|
+
event: z.record(z.unknown()),
|
|
12
|
+
attempts: z.number().int().nonnegative().default(0),
|
|
13
|
+
firstQueuedAt: z.string(),
|
|
14
|
+
nextAttemptAt: z.string(),
|
|
15
|
+
/** Events URL this entry was queued for; absent on pre-destination entries. */
|
|
16
|
+
destination: z.string().optional()
|
|
17
|
+
})
|
|
18
|
+
.passthrough();
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The contract between delivery and whatever actually moves bytes. Kept
|
|
3
|
+
* separate from the HTTP implementation so the queue, the cooldown and the
|
|
4
|
+
* whole test suite can substitute their own.
|
|
5
|
+
*/
|
|
6
|
+
export type { DeliveryCounters, DeliveryResult, EventTransport, HttpTransportOptions } from './types/transport.types.js';
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
import type { z } from 'zod';
|
|
2
|
+
import type { ProductEvent } from '../../events/product-event.js';
|
|
3
|
+
import type { queueEntrySchema } from '../schemas/queue.schema.js';
|
|
4
|
+
/** Per-event outcome counters the backend reports for an accepted batch. */
|
|
5
|
+
export interface DeliveryCounters {
|
|
6
|
+
readonly accepted: number;
|
|
7
|
+
readonly duplicate: number;
|
|
8
|
+
readonly rejected: number;
|
|
9
|
+
readonly failed: number;
|
|
10
|
+
}
|
|
11
|
+
export interface DeliveryResult {
|
|
12
|
+
readonly ok: boolean;
|
|
13
|
+
readonly status?: number;
|
|
14
|
+
/** Whether a failure is worth retrying later (network error, 5xx, 429...). */
|
|
15
|
+
readonly retryable: boolean;
|
|
16
|
+
readonly error?: string;
|
|
17
|
+
/** Per-event outcomes from an accepted batch, when the backend sent them. */
|
|
18
|
+
readonly counters?: DeliveryCounters;
|
|
19
|
+
}
|
|
20
|
+
export interface EventTransport {
|
|
21
|
+
send(events: readonly ProductEvent[]): Promise<DeliveryResult>;
|
|
22
|
+
/**
|
|
23
|
+
* Where events go (the events URL).
|
|
24
|
+
*
|
|
25
|
+
* Queued entries are pinned to it so a later endpoint change never replays old
|
|
26
|
+
* events to a new backend; re-routing the backlog takes the user's explicit
|
|
27
|
+
* consent in setup.
|
|
28
|
+
*/
|
|
29
|
+
readonly destination?: string;
|
|
30
|
+
}
|
|
31
|
+
export interface HttpTransportOptions {
|
|
32
|
+
readonly eventsUrl: string;
|
|
33
|
+
readonly token?: string;
|
|
34
|
+
readonly installationId?: string;
|
|
35
|
+
readonly timeoutMs: number;
|
|
36
|
+
readonly fetchFn?: typeof fetch;
|
|
37
|
+
}
|
|
38
|
+
/** What one hook-path delivery attempt did. */
|
|
39
|
+
export interface DeliveryOutcome {
|
|
40
|
+
readonly delivered: number;
|
|
41
|
+
readonly queued: number;
|
|
42
|
+
readonly drained: number;
|
|
43
|
+
/** Events the backend permanently rejected; they are never resent. */
|
|
44
|
+
readonly rejected: number;
|
|
45
|
+
}
|
|
46
|
+
export interface QueueOptions {
|
|
47
|
+
readonly queueDir: string;
|
|
48
|
+
readonly locksDir: string;
|
|
49
|
+
readonly maxEvents: number;
|
|
50
|
+
readonly maxAttempts: number;
|
|
51
|
+
readonly maxEventAgeDays: number;
|
|
52
|
+
readonly now?: () => Date;
|
|
53
|
+
}
|
|
54
|
+
export interface DrainStats {
|
|
55
|
+
readonly sent: number;
|
|
56
|
+
readonly failed: number;
|
|
57
|
+
readonly dropped: number;
|
|
58
|
+
/** Events the backend accepted the batch for but rejected individually. */
|
|
59
|
+
readonly rejected: number;
|
|
60
|
+
/** True when the drain lock was held elsewhere and this pass did nothing. */
|
|
61
|
+
readonly skipped: boolean;
|
|
62
|
+
}
|
|
63
|
+
export interface DrainStatsRecorder {
|
|
64
|
+
recordRejected(count: number): Promise<void>;
|
|
65
|
+
recordDropped(count: number): Promise<void>;
|
|
66
|
+
}
|
|
67
|
+
/** One persisted queue entry. */
|
|
68
|
+
export type QueueEntry = z.infer<typeof queueEntrySchema>;
|
|
69
|
+
/** A due entry together with the file it lives in. */
|
|
70
|
+
export interface DueEntry {
|
|
71
|
+
readonly file: string;
|
|
72
|
+
readonly entry: QueueEntry;
|
|
73
|
+
}
|
|
74
|
+
/**
|
|
75
|
+
* Persisted tally of everything the local queue lost, and why.
|
|
76
|
+
*
|
|
77
|
+
* Three separate outcomes, because they need three different fixes:
|
|
78
|
+
*
|
|
79
|
+
* - `rejected` — the backend accepted the batch and refused the event inside it.
|
|
80
|
+
* Never resent: the schema said no.
|
|
81
|
+
* - `dropped` — the entry ran out of attempts or aged out. This is the one that
|
|
82
|
+
* used to be invisible: drain counted it and the caller threw the count away,
|
|
83
|
+
* so a backend answering 400 to everything looked exactly like a healthy queue
|
|
84
|
+
* right up to the moment the events were gone.
|
|
85
|
+
* - `refusal` — the last non-retryable status seen. Without it a developer
|
|
86
|
+
* watching a growing backlog cannot tell a dead endpoint from a rejected token
|
|
87
|
+
* from a schema mismatch.
|
|
88
|
+
*
|
|
89
|
+
* `agentwatch status` surfaces all three.
|
|
90
|
+
*/
|
|
91
|
+
export interface DeliveryStatsSnapshot {
|
|
92
|
+
readonly totalRejected: number;
|
|
93
|
+
readonly lastRejectedCount: number;
|
|
94
|
+
readonly lastRejectedAt: string;
|
|
95
|
+
/** Events abandoned after maxAttempts or the age bound: real data loss. */
|
|
96
|
+
readonly totalDropped: number;
|
|
97
|
+
readonly lastDroppedCount: number;
|
|
98
|
+
readonly lastDroppedAt: string;
|
|
99
|
+
/** Last non-retryable HTTP status the backend answered with, if any. */
|
|
100
|
+
readonly lastRefusalStatus: number;
|
|
101
|
+
readonly lastRefusalAt: string;
|
|
102
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import type { LlmCallEvent } from '../events/types/llm-call.types.js';
|
|
2
|
+
import type { AggregateTurnUsageOptions } from './types/aggregate-usage.types.js';
|
|
3
|
+
import type { TurnSummaryEvent } from './types/turn-summary.types.js';
|
|
4
|
+
export type { AggregateTurnUsageOptions, UsageTotals } from './types/aggregate-usage.types.js';
|
|
5
|
+
/**
|
|
6
|
+
* Finalize a turn exclusively from its atomic llm.call ledger.
|
|
7
|
+
*
|
|
8
|
+
* Three rules make the result trustworthy. Calls are deduplicated by
|
|
9
|
+
* (provider, call_id) before summing, so OTLP retries cannot inflate usage. A
|
|
10
|
+
* call is attributed to exactly one turn — by turn id, or by the arbitrated
|
|
11
|
+
* window join — so overlapping turns cannot double-count. And a ledger that
|
|
12
|
+
* matched calls but carries no usage never overwrites provisional transcript
|
|
13
|
+
* totals or claims a completeness it cannot back.
|
|
14
|
+
*
|
|
15
|
+
* @param summary - The turn summary to finalize.
|
|
16
|
+
* @param calls - Ledger rows to consider; may span the whole session.
|
|
17
|
+
* @param options - Terminal signal and the session's other summaries.
|
|
18
|
+
* @returns The finalized summary, or the original when no rows matched.
|
|
19
|
+
*/
|
|
20
|
+
export declare function aggregateTurnUsage(summary: TurnSummaryEvent, calls: readonly LlmCallEvent[], options?: AggregateTurnUsageOptions): TurnSummaryEvent;
|