@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,27 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
/**
|
|
3
|
+
* Records exactly what `agentwatch setup` wrote into one agent's native
|
|
4
|
+
* configuration, so uninstall removes only AgentWatch-owned entries.
|
|
5
|
+
*
|
|
6
|
+
* Passthrough: a state file written by a newer version must survive a
|
|
7
|
+
* downgrade with its unknown fields intact.
|
|
8
|
+
*/
|
|
9
|
+
export const agentInstallSchema = z
|
|
10
|
+
.object({
|
|
11
|
+
hooksInstalledAt: z.string().optional(),
|
|
12
|
+
hookConfigPath: z.string().optional(),
|
|
13
|
+
hookEvents: z.array(z.string()).default([]),
|
|
14
|
+
hookCommand: z.string().optional(),
|
|
15
|
+
otelConfiguredAt: z.string().optional(),
|
|
16
|
+
otelConfigPath: z.string().optional(),
|
|
17
|
+
otelOwnedKeys: z.array(z.string()).default([]),
|
|
18
|
+
notes: z.array(z.string()).default([])
|
|
19
|
+
})
|
|
20
|
+
.passthrough();
|
|
21
|
+
/** The whole install-state file: one entry per agent. */
|
|
22
|
+
export const installStateSchema = z
|
|
23
|
+
.object({
|
|
24
|
+
schemaVersion: z.literal(1).default(1),
|
|
25
|
+
agents: z.record(agentInstallSchema).default({})
|
|
26
|
+
})
|
|
27
|
+
.passthrough();
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import type { z } from 'zod';
|
|
2
|
+
import type { agentInstallSchema, installStateSchema } from '../schemas/storage.schema.js';
|
|
3
|
+
/** Every filesystem location AgentWatch owns, derived once per command. */
|
|
4
|
+
export interface AgentWatchPaths {
|
|
5
|
+
/** Configuration (endpoint, token, capture flags). */
|
|
6
|
+
readonly configDir: string;
|
|
7
|
+
readonly configFile: string;
|
|
8
|
+
/** Record of exactly what setup wrote into agent configs. */
|
|
9
|
+
readonly installStateFile: string;
|
|
10
|
+
/** Mutable state: queue, locks, backups. */
|
|
11
|
+
readonly dataDir: string;
|
|
12
|
+
readonly queueDir: string;
|
|
13
|
+
readonly locksDir: string;
|
|
14
|
+
readonly backupsDir: string;
|
|
15
|
+
/** Per-session accumulator state for turn summaries. */
|
|
16
|
+
readonly turnsDir: string;
|
|
17
|
+
/** Per-repository record of the last snapshot sent, so the next one is a diff. */
|
|
18
|
+
readonly snapshotsDir: string;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* Outcome of a tolerant JSON read. `missing` and `invalid` are distinct on
|
|
22
|
+
* purpose: a file we cannot parse must never be overwritten.
|
|
23
|
+
*/
|
|
24
|
+
export type JsonReadResult = {
|
|
25
|
+
readonly state: 'missing';
|
|
26
|
+
} | {
|
|
27
|
+
readonly state: 'invalid';
|
|
28
|
+
readonly error: string;
|
|
29
|
+
} | {
|
|
30
|
+
readonly state: 'ok';
|
|
31
|
+
readonly value: unknown;
|
|
32
|
+
};
|
|
33
|
+
/** Releases a held advisory lock. */
|
|
34
|
+
export type ReleaseLock = () => Promise<void>;
|
|
35
|
+
export type AgentInstallState = z.infer<typeof agentInstallSchema>;
|
|
36
|
+
export type InstallState = z.infer<typeof installStateSchema>;
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Destination for events queued before any endpoint is configured: they are
|
|
3
|
+
* explicitly waiting for whatever backend `setup` configures first. Legacy
|
|
4
|
+
* entries without a destination have the same pre-setup behavior.
|
|
5
|
+
*/
|
|
6
|
+
export declare const ANY_DESTINATION = "*";
|
|
7
|
+
/** How long hooks skip direct sends after the backend failed one. */
|
|
8
|
+
export declare const BACKEND_COOLDOWN_MS = 60000;
|
|
9
|
+
/**
|
|
10
|
+
* Bound on individual poison-isolation sends per drain pass.
|
|
11
|
+
*
|
|
12
|
+
* Drain runs on the coding agent's hook critical path and each send may cost the
|
|
13
|
+
* full transport timeout, so isolation must never stack up enough sends to trip
|
|
14
|
+
* the agent's own hook timeout.
|
|
15
|
+
*/
|
|
16
|
+
export declare const MAX_ISOLATION_SENDS = 3;
|
|
17
|
+
/** Exponential backoff for a failed queue entry, and its ceiling. */
|
|
18
|
+
export declare const BACKOFF_BASE_MS = 5000;
|
|
19
|
+
export declare const BACKOFF_MAX_MS: number;
|
|
20
|
+
/** Jitter band applied to the backoff, so retries of a batch spread out. */
|
|
21
|
+
export declare const BACKOFF_JITTER_MIN = 0.75;
|
|
22
|
+
export declare const BACKOFF_JITTER_RANGE = 0.5;
|
|
23
|
+
/** Lock names serializing the two multi-process operations. */
|
|
24
|
+
export declare const QUEUE_DRAIN_LOCK = "queue-drain";
|
|
25
|
+
export declare const DELIVERY_STATS_LOCK = "delivery-stats";
|
|
26
|
+
/** Bounded wait for the drain lock when setup re-routes the backlog. */
|
|
27
|
+
export declare const RETARGET_LOCK_WAIT_MS = 10000;
|
|
28
|
+
export declare const RETARGET_LOCK_POLL_MS = 50;
|
|
29
|
+
/** Bounded: recordRejected runs on the hook path and must never stall it. */
|
|
30
|
+
export declare const STATS_LOCK_MAX_WAIT_MS = 300;
|
|
31
|
+
export declare const STATS_LOCK_POLL_MS = 25;
|
|
32
|
+
/** HTTP statuses worth retrying that are not 5xx. */
|
|
33
|
+
export declare const RETRYABLE_STATUSES: ReadonlySet<number>;
|
|
34
|
+
/** Request headers every batch carries. */
|
|
35
|
+
export declare const CONTENT_TYPE_HEADER = "content-type";
|
|
36
|
+
export declare const USER_AGENT_HEADER = "user-agent";
|
|
37
|
+
export declare const AUTHORIZATION_HEADER = "authorization";
|
|
38
|
+
export declare const INSTALLATION_HEADER = "x-agentwatch-installation";
|
|
39
|
+
export declare const JSON_CONTENT_TYPE = "application/json";
|
|
40
|
+
export declare const USER_AGENT = "agentwatch-edge";
|
|
41
|
+
/** Filenames under the data directory. */
|
|
42
|
+
export declare const COOLDOWN_FILE_NAME = "backend-cooldown.json";
|
|
43
|
+
export declare const DELIVERY_STATS_FILE_NAME = "delivery-stats.json";
|
|
44
|
+
export declare const MS_PER_DAY: number;
|
|
45
|
+
/** Characters unsafe in a queue filename. */
|
|
46
|
+
export declare const RE_UNSAFE_QUEUE_NAME: RegExp;
|
|
47
|
+
export declare const QUEUE_FILE_SUFFIX = ".json";
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Destination for events queued before any endpoint is configured: they are
|
|
3
|
+
* explicitly waiting for whatever backend `setup` configures first. Legacy
|
|
4
|
+
* entries without a destination have the same pre-setup behavior.
|
|
5
|
+
*/
|
|
6
|
+
export const ANY_DESTINATION = '*';
|
|
7
|
+
/** How long hooks skip direct sends after the backend failed one. */
|
|
8
|
+
export const BACKEND_COOLDOWN_MS = 60_000;
|
|
9
|
+
/**
|
|
10
|
+
* Bound on individual poison-isolation sends per drain pass.
|
|
11
|
+
*
|
|
12
|
+
* Drain runs on the coding agent's hook critical path and each send may cost the
|
|
13
|
+
* full transport timeout, so isolation must never stack up enough sends to trip
|
|
14
|
+
* the agent's own hook timeout.
|
|
15
|
+
*/
|
|
16
|
+
export const MAX_ISOLATION_SENDS = 3;
|
|
17
|
+
/** Exponential backoff for a failed queue entry, and its ceiling. */
|
|
18
|
+
export const BACKOFF_BASE_MS = 5_000;
|
|
19
|
+
export const BACKOFF_MAX_MS = 6 * 60 * 60 * 1000;
|
|
20
|
+
/** Jitter band applied to the backoff, so retries of a batch spread out. */
|
|
21
|
+
export const BACKOFF_JITTER_MIN = 0.75;
|
|
22
|
+
export const BACKOFF_JITTER_RANGE = 0.5;
|
|
23
|
+
/** Lock names serializing the two multi-process operations. */
|
|
24
|
+
export const QUEUE_DRAIN_LOCK = 'queue-drain';
|
|
25
|
+
export const DELIVERY_STATS_LOCK = 'delivery-stats';
|
|
26
|
+
/** Bounded wait for the drain lock when setup re-routes the backlog. */
|
|
27
|
+
export const RETARGET_LOCK_WAIT_MS = 10_000;
|
|
28
|
+
export const RETARGET_LOCK_POLL_MS = 50;
|
|
29
|
+
/** Bounded: recordRejected runs on the hook path and must never stall it. */
|
|
30
|
+
export const STATS_LOCK_MAX_WAIT_MS = 300;
|
|
31
|
+
export const STATS_LOCK_POLL_MS = 25;
|
|
32
|
+
/** HTTP statuses worth retrying that are not 5xx. */
|
|
33
|
+
export const RETRYABLE_STATUSES = new Set([401, 403, 408, 429]);
|
|
34
|
+
/** Request headers every batch carries. */
|
|
35
|
+
export const CONTENT_TYPE_HEADER = 'content-type';
|
|
36
|
+
export const USER_AGENT_HEADER = 'user-agent';
|
|
37
|
+
export const AUTHORIZATION_HEADER = 'authorization';
|
|
38
|
+
export const INSTALLATION_HEADER = 'x-agentwatch-installation';
|
|
39
|
+
export const JSON_CONTENT_TYPE = 'application/json';
|
|
40
|
+
export const USER_AGENT = 'agentwatch-edge';
|
|
41
|
+
/** Filenames under the data directory. */
|
|
42
|
+
export const COOLDOWN_FILE_NAME = 'backend-cooldown.json';
|
|
43
|
+
export const DELIVERY_STATS_FILE_NAME = 'delivery-stats.json';
|
|
44
|
+
export const MS_PER_DAY = 24 * 60 * 60 * 1000;
|
|
45
|
+
/** Characters unsafe in a queue filename. */
|
|
46
|
+
export const RE_UNSAFE_QUEUE_NAME = /[^A-Za-z0-9_-]/g;
|
|
47
|
+
export const QUEUE_FILE_SUFFIX = '.json';
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Persisted circuit breaker for the in-hook direct send.
|
|
3
|
+
*
|
|
4
|
+
* Hooks are separate short-lived processes, so "the backend is down" has to live
|
|
5
|
+
* on disk: after a failed send, later hooks skip the direct attempt — and its
|
|
6
|
+
* timeout — entirely until the cooldown expires, queueing events instead. In
|
|
7
|
+
* memory this signal would be forgotten before the next hook even started.
|
|
8
|
+
*/
|
|
9
|
+
export declare class BackendCooldown {
|
|
10
|
+
private readonly file;
|
|
11
|
+
private readonly now;
|
|
12
|
+
/**
|
|
13
|
+
* Bind the breaker to its state file.
|
|
14
|
+
*
|
|
15
|
+
* @param file - Where the cooldown deadline is persisted.
|
|
16
|
+
* @param now - Clock, injectable for tests.
|
|
17
|
+
*/
|
|
18
|
+
constructor(file: string, now?: () => Date);
|
|
19
|
+
/**
|
|
20
|
+
* Whether direct sends should currently be skipped.
|
|
21
|
+
*
|
|
22
|
+
* @returns True while the cooldown is in force.
|
|
23
|
+
*/
|
|
24
|
+
active(): Promise<boolean>;
|
|
25
|
+
/**
|
|
26
|
+
* Start a cooldown.
|
|
27
|
+
*
|
|
28
|
+
* @param durationMs - How long to skip direct sends for.
|
|
29
|
+
*/
|
|
30
|
+
trip(durationMs: number): Promise<void>;
|
|
31
|
+
/**
|
|
32
|
+
* End the cooldown after a successful send.
|
|
33
|
+
*/
|
|
34
|
+
clear(): Promise<void>;
|
|
35
|
+
}
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
import fs from 'node:fs/promises';
|
|
2
|
+
import { asRecord } from '../core/object.js';
|
|
3
|
+
import { writeFileAtomic } from '../storage/atomic-file.js';
|
|
4
|
+
import { SECRET_FILE_MODE } from '../storage/constants/storage.constants.js';
|
|
5
|
+
/**
|
|
6
|
+
* Persisted circuit breaker for the in-hook direct send.
|
|
7
|
+
*
|
|
8
|
+
* Hooks are separate short-lived processes, so "the backend is down" has to live
|
|
9
|
+
* on disk: after a failed send, later hooks skip the direct attempt — and its
|
|
10
|
+
* timeout — entirely until the cooldown expires, queueing events instead. In
|
|
11
|
+
* memory this signal would be forgotten before the next hook even started.
|
|
12
|
+
*/
|
|
13
|
+
export class BackendCooldown {
|
|
14
|
+
file;
|
|
15
|
+
now;
|
|
16
|
+
/**
|
|
17
|
+
* Bind the breaker to its state file.
|
|
18
|
+
*
|
|
19
|
+
* @param file - Where the cooldown deadline is persisted.
|
|
20
|
+
* @param now - Clock, injectable for tests.
|
|
21
|
+
*/
|
|
22
|
+
constructor(file, now = () => new Date()) {
|
|
23
|
+
this.file = file;
|
|
24
|
+
this.now = now;
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* Whether direct sends should currently be skipped.
|
|
28
|
+
*
|
|
29
|
+
* @returns True while the cooldown is in force.
|
|
30
|
+
*/
|
|
31
|
+
async active() {
|
|
32
|
+
try {
|
|
33
|
+
const until = asRecord(JSON.parse(await fs.readFile(this.file, 'utf8')))?.['until'];
|
|
34
|
+
return typeof until === 'number' && until > this.now().getTime();
|
|
35
|
+
}
|
|
36
|
+
catch {
|
|
37
|
+
// No file, or one we cannot read: assume the backend is healthy. Failing
|
|
38
|
+
// open here costs one timeout; failing closed would silence telemetry.
|
|
39
|
+
return false;
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* Start a cooldown.
|
|
44
|
+
*
|
|
45
|
+
* @param durationMs - How long to skip direct sends for.
|
|
46
|
+
*/
|
|
47
|
+
async trip(durationMs) {
|
|
48
|
+
try {
|
|
49
|
+
await writeFileAtomic(this.file, JSON.stringify({ until: this.now().getTime() + durationMs }), SECRET_FILE_MODE);
|
|
50
|
+
}
|
|
51
|
+
catch {
|
|
52
|
+
// The cooldown is an optimization; failing to persist it must not break
|
|
53
|
+
// the hook.
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* End the cooldown after a successful send.
|
|
58
|
+
*/
|
|
59
|
+
async clear() {
|
|
60
|
+
await fs.rm(this.file, { force: true });
|
|
61
|
+
}
|
|
62
|
+
}
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
import type { DeliveryStatsSnapshot } from './types/transport.types.js';
|
|
2
|
+
export type { DeliveryStatsSnapshot } from './types/transport.types.js';
|
|
3
|
+
/**
|
|
4
|
+
* Persisted tally of everything the local queue lost, and why.
|
|
5
|
+
*
|
|
6
|
+
* See {@link DeliveryStatsSnapshot} for what the three outcomes mean and why
|
|
7
|
+
* they are counted separately. `agentwatch status` surfaces all of them.
|
|
8
|
+
*/
|
|
9
|
+
export declare class DeliveryStats {
|
|
10
|
+
private readonly file;
|
|
11
|
+
private readonly now;
|
|
12
|
+
private readonly locksDir?;
|
|
13
|
+
/**
|
|
14
|
+
* Bind the tally to its file and lock directory.
|
|
15
|
+
*
|
|
16
|
+
* @param file - Where the tally is persisted.
|
|
17
|
+
* @param now - Clock, injectable for tests.
|
|
18
|
+
* @param locksDir - Serializes the read-modify-write across hook processes.
|
|
19
|
+
*/
|
|
20
|
+
constructor(file: string, now?: () => Date, locksDir?: string | undefined);
|
|
21
|
+
/**
|
|
22
|
+
* Read the tally.
|
|
23
|
+
*
|
|
24
|
+
* @returns The snapshot, or undefined when there is nothing recorded.
|
|
25
|
+
*/
|
|
26
|
+
read(): Promise<DeliveryStatsSnapshot | undefined>;
|
|
27
|
+
/**
|
|
28
|
+
* Note events the backend refused inside an accepted batch. Never throws.
|
|
29
|
+
*
|
|
30
|
+
* @param count - How many were refused.
|
|
31
|
+
*/
|
|
32
|
+
recordRejected(count: number): Promise<void>;
|
|
33
|
+
/**
|
|
34
|
+
* Note events the queue gave up on. Never throws, for the same reason.
|
|
35
|
+
*
|
|
36
|
+
* @param count - How many were lost.
|
|
37
|
+
*/
|
|
38
|
+
recordDropped(count: number): Promise<void>;
|
|
39
|
+
/**
|
|
40
|
+
* Note a status the transport will not retry. Never throws.
|
|
41
|
+
*
|
|
42
|
+
* @param status - The refusing HTTP status, when there was one.
|
|
43
|
+
*/
|
|
44
|
+
recordRefusal(status: number | undefined): Promise<void>;
|
|
45
|
+
/**
|
|
46
|
+
* Apply one patch to the persisted tally.
|
|
47
|
+
*
|
|
48
|
+
* Two hooks can finish sends concurrently, and without the lock one increment
|
|
49
|
+
* of this read-modify-write is silently lost. The lock is polled for a bounded
|
|
50
|
+
* interval — the hook path must never stall — and when it still cannot be
|
|
51
|
+
* acquired the write proceeds unlocked: a rare lost increment beats losing the
|
|
52
|
+
* record entirely. The guarantee is bounded-wait serialization, not mutual
|
|
53
|
+
* exclusion under arbitrary contention.
|
|
54
|
+
*
|
|
55
|
+
* @param count - How many events this call is about; zero is a no-op.
|
|
56
|
+
* @param patch - Builds the fields to change.
|
|
57
|
+
*/
|
|
58
|
+
private record;
|
|
59
|
+
/**
|
|
60
|
+
* Acquire the stats lock, waiting a bounded time.
|
|
61
|
+
*
|
|
62
|
+
* @returns The release function, or undefined to write unlocked.
|
|
63
|
+
*/
|
|
64
|
+
private waitForLock;
|
|
65
|
+
}
|
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
import fs from 'node:fs/promises';
|
|
2
|
+
import { pollUntil } from '../core/async.js';
|
|
3
|
+
import { writeFileAtomic } from '../storage/atomic-file.js';
|
|
4
|
+
import { acquireLock } from '../storage/lock.js';
|
|
5
|
+
import { SECRET_FILE_MODE } from '../storage/constants/storage.constants.js';
|
|
6
|
+
import { DELIVERY_STATS_LOCK, STATS_LOCK_MAX_WAIT_MS, STATS_LOCK_POLL_MS } from './constants/transport.constants.js';
|
|
7
|
+
/**
|
|
8
|
+
* Persisted tally of everything the local queue lost, and why.
|
|
9
|
+
*
|
|
10
|
+
* See {@link DeliveryStatsSnapshot} for what the three outcomes mean and why
|
|
11
|
+
* they are counted separately. `agentwatch status` surfaces all of them.
|
|
12
|
+
*/
|
|
13
|
+
export class DeliveryStats {
|
|
14
|
+
file;
|
|
15
|
+
now;
|
|
16
|
+
locksDir;
|
|
17
|
+
/**
|
|
18
|
+
* Bind the tally to its file and lock directory.
|
|
19
|
+
*
|
|
20
|
+
* @param file - Where the tally is persisted.
|
|
21
|
+
* @param now - Clock, injectable for tests.
|
|
22
|
+
* @param locksDir - Serializes the read-modify-write across hook processes.
|
|
23
|
+
*/
|
|
24
|
+
constructor(file, now = () => new Date(), locksDir) {
|
|
25
|
+
this.file = file;
|
|
26
|
+
this.now = now;
|
|
27
|
+
this.locksDir = locksDir;
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* Read the tally.
|
|
31
|
+
*
|
|
32
|
+
* @returns The snapshot, or undefined when there is nothing recorded.
|
|
33
|
+
*/
|
|
34
|
+
async read() {
|
|
35
|
+
try {
|
|
36
|
+
const raw = JSON.parse(await fs.readFile(this.file, 'utf8'));
|
|
37
|
+
// A file written before the dropped/refusal counters existed still reads.
|
|
38
|
+
if (typeof raw.totalRejected !== 'number' && typeof raw.totalDropped !== 'number' && typeof raw.lastRefusalStatus !== 'number') {
|
|
39
|
+
return undefined;
|
|
40
|
+
}
|
|
41
|
+
return {
|
|
42
|
+
totalRejected: numberOr(raw.totalRejected, 0),
|
|
43
|
+
lastRejectedCount: numberOr(raw.lastRejectedCount, 0),
|
|
44
|
+
lastRejectedAt: stringOr(raw.lastRejectedAt),
|
|
45
|
+
totalDropped: numberOr(raw.totalDropped, 0),
|
|
46
|
+
lastDroppedCount: numberOr(raw.lastDroppedCount, 0),
|
|
47
|
+
lastDroppedAt: stringOr(raw.lastDroppedAt),
|
|
48
|
+
lastRefusalStatus: numberOr(raw.lastRefusalStatus, 0),
|
|
49
|
+
lastRefusalAt: stringOr(raw.lastRefusalAt)
|
|
50
|
+
};
|
|
51
|
+
}
|
|
52
|
+
catch {
|
|
53
|
+
return undefined;
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* Note events the backend refused inside an accepted batch. Never throws.
|
|
58
|
+
*
|
|
59
|
+
* @param count - How many were refused.
|
|
60
|
+
*/
|
|
61
|
+
async recordRejected(count) {
|
|
62
|
+
await this.record(count, (current, at) => ({
|
|
63
|
+
totalRejected: (current?.totalRejected ?? 0) + count,
|
|
64
|
+
lastRejectedCount: count,
|
|
65
|
+
lastRejectedAt: at
|
|
66
|
+
}));
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* Note events the queue gave up on. Never throws, for the same reason.
|
|
70
|
+
*
|
|
71
|
+
* @param count - How many were lost.
|
|
72
|
+
*/
|
|
73
|
+
async recordDropped(count) {
|
|
74
|
+
await this.record(count, (current, at) => ({
|
|
75
|
+
totalDropped: (current?.totalDropped ?? 0) + count,
|
|
76
|
+
lastDroppedCount: count,
|
|
77
|
+
lastDroppedAt: at
|
|
78
|
+
}));
|
|
79
|
+
}
|
|
80
|
+
/**
|
|
81
|
+
* Note a status the transport will not retry. Never throws.
|
|
82
|
+
*
|
|
83
|
+
* @param status - The refusing HTTP status, when there was one.
|
|
84
|
+
*/
|
|
85
|
+
async recordRefusal(status) {
|
|
86
|
+
if (status === undefined)
|
|
87
|
+
return;
|
|
88
|
+
await this.record(1, (_current, at) => ({ lastRefusalStatus: status, lastRefusalAt: at }));
|
|
89
|
+
}
|
|
90
|
+
/**
|
|
91
|
+
* Apply one patch to the persisted tally.
|
|
92
|
+
*
|
|
93
|
+
* Two hooks can finish sends concurrently, and without the lock one increment
|
|
94
|
+
* of this read-modify-write is silently lost. The lock is polled for a bounded
|
|
95
|
+
* interval — the hook path must never stall — and when it still cannot be
|
|
96
|
+
* acquired the write proceeds unlocked: a rare lost increment beats losing the
|
|
97
|
+
* record entirely. The guarantee is bounded-wait serialization, not mutual
|
|
98
|
+
* exclusion under arbitrary contention.
|
|
99
|
+
*
|
|
100
|
+
* @param count - How many events this call is about; zero is a no-op.
|
|
101
|
+
* @param patch - Builds the fields to change.
|
|
102
|
+
*/
|
|
103
|
+
async record(count, patch) {
|
|
104
|
+
if (count <= 0)
|
|
105
|
+
return;
|
|
106
|
+
const release = await this.waitForLock();
|
|
107
|
+
try {
|
|
108
|
+
const current = await this.read();
|
|
109
|
+
const next = { ...emptySnapshot(), ...current, ...patch(current, this.now().toISOString()) };
|
|
110
|
+
await writeFileAtomic(this.file, JSON.stringify(next), SECRET_FILE_MODE);
|
|
111
|
+
}
|
|
112
|
+
catch {
|
|
113
|
+
// Stats are diagnostics; failing to persist them must not break the hook.
|
|
114
|
+
}
|
|
115
|
+
finally {
|
|
116
|
+
await releaseQuietly(release);
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
/**
|
|
120
|
+
* Acquire the stats lock, waiting a bounded time.
|
|
121
|
+
*
|
|
122
|
+
* @returns The release function, or undefined to write unlocked.
|
|
123
|
+
*/
|
|
124
|
+
async waitForLock() {
|
|
125
|
+
if (!this.locksDir)
|
|
126
|
+
return undefined;
|
|
127
|
+
try {
|
|
128
|
+
return await pollUntil(() => acquireLock(this.locksDir, DELIVERY_STATS_LOCK, this.now), STATS_LOCK_MAX_WAIT_MS, STATS_LOCK_POLL_MS);
|
|
129
|
+
}
|
|
130
|
+
catch {
|
|
131
|
+
// The locking machinery itself failed; fall back to unlocked.
|
|
132
|
+
return undefined;
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
/**
|
|
137
|
+
* Release a lock without letting the failure escape.
|
|
138
|
+
*
|
|
139
|
+
* @param release - The release function, when one was acquired.
|
|
140
|
+
*/
|
|
141
|
+
async function releaseQuietly(release) {
|
|
142
|
+
if (!release)
|
|
143
|
+
return;
|
|
144
|
+
try {
|
|
145
|
+
await release();
|
|
146
|
+
}
|
|
147
|
+
catch {
|
|
148
|
+
// The stale-lock breaker reclaims an unreleased lock after 30s.
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
/**
|
|
152
|
+
* A tally with nothing recorded yet.
|
|
153
|
+
*
|
|
154
|
+
* @returns The zero snapshot.
|
|
155
|
+
*/
|
|
156
|
+
function emptySnapshot() {
|
|
157
|
+
return {
|
|
158
|
+
totalRejected: 0,
|
|
159
|
+
lastRejectedCount: 0,
|
|
160
|
+
lastRejectedAt: '',
|
|
161
|
+
totalDropped: 0,
|
|
162
|
+
lastDroppedCount: 0,
|
|
163
|
+
lastDroppedAt: '',
|
|
164
|
+
lastRefusalStatus: 0,
|
|
165
|
+
lastRefusalAt: ''
|
|
166
|
+
};
|
|
167
|
+
}
|
|
168
|
+
/**
|
|
169
|
+
* A number, or a fallback.
|
|
170
|
+
*
|
|
171
|
+
* @param value - Candidate of unknown shape.
|
|
172
|
+
* @param fallback - Value to use instead.
|
|
173
|
+
* @returns The number.
|
|
174
|
+
*/
|
|
175
|
+
function numberOr(value, fallback) {
|
|
176
|
+
return typeof value === 'number' ? value : fallback;
|
|
177
|
+
}
|
|
178
|
+
/**
|
|
179
|
+
* A string, or the empty string.
|
|
180
|
+
*
|
|
181
|
+
* @param value - Candidate of unknown shape.
|
|
182
|
+
* @returns The string.
|
|
183
|
+
*/
|
|
184
|
+
function stringOr(value) {
|
|
185
|
+
return typeof value === 'string' ? value : '';
|
|
186
|
+
}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import type { ProductEvent } from '../events/product-event.js';
|
|
2
|
+
import type { BackendCooldown } from './cooldown.js';
|
|
3
|
+
import type { DeliveryStats } from './delivery-stats.js';
|
|
4
|
+
import type { EventQueue } from './queue.js';
|
|
5
|
+
import type { DeliveryOutcome, EventTransport } from './types/transport.types.js';
|
|
6
|
+
export { BACKEND_COOLDOWN_MS } from './constants/transport.constants.js';
|
|
7
|
+
export type { DeliveryOutcome } from './types/transport.types.js';
|
|
8
|
+
/**
|
|
9
|
+
* Hook-path delivery: one quick direct send, then whatever the backlog allows.
|
|
10
|
+
*
|
|
11
|
+
* Three properties this has to keep, in order of importance. It never loses a
|
|
12
|
+
* product record — a failed send always ends in the queue, never in a discard.
|
|
13
|
+
* It never blocks the agent for long — a backend that just failed is skipped
|
|
14
|
+
* entirely for the cooldown window rather than costing every hook a full
|
|
15
|
+
* timeout. And it keeps the backlog moving even on hooks that emit nothing,
|
|
16
|
+
* because those are the majority.
|
|
17
|
+
*
|
|
18
|
+
* @param events - Product events this hook produced; often empty.
|
|
19
|
+
* @param transport - Where to send, or undefined before setup configures one.
|
|
20
|
+
* @param queue - The offline queue.
|
|
21
|
+
* @param drainBatchSize - Ceiling on events one drain pass may send.
|
|
22
|
+
* @param cooldown - Persisted circuit breaker, when enabled.
|
|
23
|
+
* @param stats - Sink for permanent losses, when enabled.
|
|
24
|
+
* @returns What was delivered, queued, drained and rejected.
|
|
25
|
+
*/
|
|
26
|
+
export declare function deliverEvents(events: readonly ProductEvent[], transport: EventTransport | undefined, queue: EventQueue, drainBatchSize: number, cooldown?: BackendCooldown, stats?: DeliveryStats): Promise<DeliveryOutcome>;
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
import { debugLog } from '../core/logger.js';
|
|
2
|
+
import { ANY_DESTINATION, BACKEND_COOLDOWN_MS } from './constants/transport.constants.js';
|
|
3
|
+
export { BACKEND_COOLDOWN_MS } from './constants/transport.constants.js';
|
|
4
|
+
/**
|
|
5
|
+
* Hook-path delivery: one quick direct send, then whatever the backlog allows.
|
|
6
|
+
*
|
|
7
|
+
* Three properties this has to keep, in order of importance. It never loses a
|
|
8
|
+
* product record — a failed send always ends in the queue, never in a discard.
|
|
9
|
+
* It never blocks the agent for long — a backend that just failed is skipped
|
|
10
|
+
* entirely for the cooldown window rather than costing every hook a full
|
|
11
|
+
* timeout. And it keeps the backlog moving even on hooks that emit nothing,
|
|
12
|
+
* because those are the majority.
|
|
13
|
+
*
|
|
14
|
+
* @param events - Product events this hook produced; often empty.
|
|
15
|
+
* @param transport - Where to send, or undefined before setup configures one.
|
|
16
|
+
* @param queue - The offline queue.
|
|
17
|
+
* @param drainBatchSize - Ceiling on events one drain pass may send.
|
|
18
|
+
* @param cooldown - Persisted circuit breaker, when enabled.
|
|
19
|
+
* @param stats - Sink for permanent losses, when enabled.
|
|
20
|
+
* @returns What was delivered, queued, drained and rejected.
|
|
21
|
+
*/
|
|
22
|
+
export async function deliverEvents(events, transport, queue, drainBatchSize, cooldown, stats) {
|
|
23
|
+
if (!transport) {
|
|
24
|
+
// No endpoint configured yet: keep the events for whatever backend setup
|
|
25
|
+
// configures first.
|
|
26
|
+
if (events.length > 0)
|
|
27
|
+
await queue.enqueue(events, ANY_DESTINATION);
|
|
28
|
+
return { delivered: 0, queued: events.length, drained: 0, rejected: 0 };
|
|
29
|
+
}
|
|
30
|
+
if (await isCoolingDown(cooldown)) {
|
|
31
|
+
// Circuit breaker: a recently-dead backend must not cost every hook the
|
|
32
|
+
// full send timeout. Skip straight to the queue.
|
|
33
|
+
if (events.length > 0)
|
|
34
|
+
await queue.enqueue(events, transport.destination);
|
|
35
|
+
return { delivered: 0, queued: events.length, drained: 0, rejected: 0 };
|
|
36
|
+
}
|
|
37
|
+
if (events.length === 0) {
|
|
38
|
+
// Hooks that emit no summary still keep the offline queue moving; there is
|
|
39
|
+
// just no direct request to make.
|
|
40
|
+
const drained = await queue.drain(transport, drainBatchSize, stats);
|
|
41
|
+
return { delivered: 0, queued: 0, drained: drained.sent, rejected: drained.rejected };
|
|
42
|
+
}
|
|
43
|
+
const result = await transport.send(events);
|
|
44
|
+
if (!result.ok) {
|
|
45
|
+
debugLog('direct send failed', result.error ?? `status ${result.status}`);
|
|
46
|
+
if (result.retryable && cooldown)
|
|
47
|
+
await cooldown.trip(BACKEND_COOLDOWN_MS);
|
|
48
|
+
// A refusal the transport will not retry is the whole diagnosis: without it
|
|
49
|
+
// a developer sees only a backlog that grows and then empties itself when
|
|
50
|
+
// the entries age out.
|
|
51
|
+
if (!result.retryable && stats)
|
|
52
|
+
await stats.recordRefusal(result.status);
|
|
53
|
+
// Product records are never discarded on the direct path. A permanent
|
|
54
|
+
// response can be caused by a temporarily incompatible route or schema, and
|
|
55
|
+
// the queued copy may succeed once the backend is corrected.
|
|
56
|
+
await queue.enqueue(events, transport.destination);
|
|
57
|
+
return { delivered: 0, queued: events.length, drained: 0, rejected: 0 };
|
|
58
|
+
}
|
|
59
|
+
const rejected = result.counters?.rejected ?? 0;
|
|
60
|
+
if (rejected > 0) {
|
|
61
|
+
debugLog(`backend permanently rejected ${rejected} event(s) from the direct send`);
|
|
62
|
+
if (stats)
|
|
63
|
+
await stats.recordRejected(rejected);
|
|
64
|
+
}
|
|
65
|
+
if (cooldown)
|
|
66
|
+
await cooldown.clear();
|
|
67
|
+
const drained = await queue.drain(transport, drainBatchSize, stats);
|
|
68
|
+
return { delivered: events.length, queued: 0, drained: drained.sent, rejected: rejected + drained.rejected };
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* Whether the backend is inside its cooldown window.
|
|
72
|
+
*
|
|
73
|
+
* @param cooldown - The breaker, when one is configured.
|
|
74
|
+
* @returns True when direct sends should be skipped.
|
|
75
|
+
*/
|
|
76
|
+
async function isCoolingDown(cooldown) {
|
|
77
|
+
if (!cooldown)
|
|
78
|
+
return false;
|
|
79
|
+
return cooldown.active();
|
|
80
|
+
}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The headers that identify this Edge to the backend, on any route.
|
|
3
|
+
*
|
|
4
|
+
* One place, so the next header the platform requires is added once rather than
|
|
5
|
+
* on every request path — and so a route can never accidentally identify itself
|
|
6
|
+
* differently from the others.
|
|
7
|
+
*
|
|
8
|
+
* @param token - Edge token, when one is configured.
|
|
9
|
+
* @param installationId - This installation's id, when one exists.
|
|
10
|
+
* @returns The header map.
|
|
11
|
+
*/
|
|
12
|
+
export declare function edgeHeaders(token?: string, installationId?: string): Record<string, string>;
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import { AUTHORIZATION_HEADER, INSTALLATION_HEADER, USER_AGENT, USER_AGENT_HEADER } from './constants/transport.constants.js';
|
|
2
|
+
/**
|
|
3
|
+
* The headers that identify this Edge to the backend, on any route.
|
|
4
|
+
*
|
|
5
|
+
* One place, so the next header the platform requires is added once rather than
|
|
6
|
+
* on every request path — and so a route can never accidentally identify itself
|
|
7
|
+
* differently from the others.
|
|
8
|
+
*
|
|
9
|
+
* @param token - Edge token, when one is configured.
|
|
10
|
+
* @param installationId - This installation's id, when one exists.
|
|
11
|
+
* @returns The header map.
|
|
12
|
+
*/
|
|
13
|
+
export function edgeHeaders(token, installationId) {
|
|
14
|
+
return {
|
|
15
|
+
[USER_AGENT_HEADER]: USER_AGENT,
|
|
16
|
+
...(token ? { [AUTHORIZATION_HEADER]: `Bearer ${token}` } : {}),
|
|
17
|
+
...(installationId ? { [INSTALLATION_HEADER]: installationId } : {})
|
|
18
|
+
};
|
|
19
|
+
}
|