@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,74 @@
|
|
|
1
|
+
import type { ReadTurnUsageRetry, TranscriptUsageEntry, TurnUsage } from './types/transcript.types.js';
|
|
2
|
+
/** One read pass over a transcript. */
|
|
3
|
+
export type TranscriptPass = () => Promise<TurnUsage | undefined>;
|
|
4
|
+
/** How the settle loop should treat a transcript that reports no usage at all. */
|
|
5
|
+
export interface SettleOptions {
|
|
6
|
+
/**
|
|
7
|
+
* Stop immediately when the very first pass finds nothing.
|
|
8
|
+
*
|
|
9
|
+
* For a provider whose transcript format carries no usage today, retrying
|
|
10
|
+
* cannot change the answer, and the settle loop would add attempts×delay of
|
|
11
|
+
* pure latency to every Stop.
|
|
12
|
+
*/
|
|
13
|
+
readonly bailOnFirstEmpty?: boolean;
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* Re-read until two consecutive passes agree, or the attempts run out.
|
|
17
|
+
*
|
|
18
|
+
* Agents flush their transcript asynchronously, so the final assistant entry
|
|
19
|
+
* may not be on disk when Stop fires — and in a turn with tool calls the
|
|
20
|
+
* *earlier* entries already are, so stopping at the first hit would
|
|
21
|
+
* systematically undercount. Agreement between two passes, no earlier than the
|
|
22
|
+
* settle window, is the signal that the flush is done.
|
|
23
|
+
*
|
|
24
|
+
* @param pass - Reads the transcript once.
|
|
25
|
+
* @param retry - Attempt count, delay and settle window.
|
|
26
|
+
* @param options - Provider-specific early-exit behaviour.
|
|
27
|
+
* @returns The settled usage, or the last thing read.
|
|
28
|
+
*/
|
|
29
|
+
export declare function readUntilSettled(pass: TranscriptPass, retry?: ReadTurnUsageRetry, options?: SettleOptions): Promise<TurnUsage | undefined>;
|
|
30
|
+
/**
|
|
31
|
+
* Read the tail of a transcript file.
|
|
32
|
+
*
|
|
33
|
+
* Only the tail: the turn's entries are at the end of the JSONL and the settle
|
|
34
|
+
* loop re-reads the file several times per Stop, so parsing a whole
|
|
35
|
+
* multi-megabyte session each pass would be waste (STYLEGUIDE 3.3).
|
|
36
|
+
*
|
|
37
|
+
* @param transcriptPath - Path the provider reported.
|
|
38
|
+
* @returns The tail text, or undefined when the file cannot be read.
|
|
39
|
+
*/
|
|
40
|
+
export declare function readTranscriptTail(transcriptPath: string): Promise<string | undefined>;
|
|
41
|
+
/**
|
|
42
|
+
* Stable identity for a transcript entry.
|
|
43
|
+
*
|
|
44
|
+
* Some transcript variants omit the message id. A content hash is stable
|
|
45
|
+
* across retries and processes, so anonymous entries can still take part in
|
|
46
|
+
* the persisted exactly-once claim ledger. Identical anonymous lines are
|
|
47
|
+
* indistinguishable and intentionally deduplicate.
|
|
48
|
+
*
|
|
49
|
+
* @param rawId - The provider's own id, when it has one.
|
|
50
|
+
* @param line - The verbatim line, used for the fallback hash.
|
|
51
|
+
* @returns The id to key this entry by.
|
|
52
|
+
*/
|
|
53
|
+
export declare function messageIdFor(rawId: string | undefined, line: string): string;
|
|
54
|
+
/**
|
|
55
|
+
* Sum the usage of deduplicated transcript entries.
|
|
56
|
+
*
|
|
57
|
+
* A turn's window can mix models (subagents, title generation), so the model
|
|
58
|
+
* reported is the one that produced the most tokens — last-write-wins would
|
|
59
|
+
* let a tiny side-call mislabel the whole turn and misprice it downstream.
|
|
60
|
+
*
|
|
61
|
+
* @param entries - Usage entries keyed by message id.
|
|
62
|
+
* @returns The turn's usage, or undefined when there is nothing to report.
|
|
63
|
+
*/
|
|
64
|
+
export declare function accumulateUsage(entries: ReadonlyMap<string, TranscriptUsageEntry>): TurnUsage | undefined;
|
|
65
|
+
/**
|
|
66
|
+
* Decode one JSONL line.
|
|
67
|
+
*
|
|
68
|
+
* Unparseable lines are skipped rather than failing the read: a transcript
|
|
69
|
+
* being appended to concurrently routinely ends mid-line.
|
|
70
|
+
*
|
|
71
|
+
* @param line - The line text.
|
|
72
|
+
* @returns The object, or undefined when the line is not one.
|
|
73
|
+
*/
|
|
74
|
+
export declare function parseJsonLine(line: string): Record<string, unknown> | undefined;
|
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
import fs from 'node:fs/promises';
|
|
2
|
+
import { add, finiteOrZero } from '../core/number.js';
|
|
3
|
+
import { asRecord } from '../core/object.js';
|
|
4
|
+
import { sleep } from '../core/async.js';
|
|
5
|
+
import { sha256Hex } from '../events/event-id.js';
|
|
6
|
+
import { ANONYMOUS_MESSAGE_ID_PREFIX, TRANSCRIPT_CACHE_CREATION_TOKENS, TRANSCRIPT_CACHE_READ_TOKENS, TRANSCRIPT_INPUT_TOKENS, TRANSCRIPT_OUTPUT_TOKENS, TRANSCRIPT_TAIL_BYTES, TRANSCRIPT_TOKEN_FIELDS } from './constants/turns.constants.js';
|
|
7
|
+
/**
|
|
8
|
+
* Re-read until two consecutive passes agree, or the attempts run out.
|
|
9
|
+
*
|
|
10
|
+
* Agents flush their transcript asynchronously, so the final assistant entry
|
|
11
|
+
* may not be on disk when Stop fires — and in a turn with tool calls the
|
|
12
|
+
* *earlier* entries already are, so stopping at the first hit would
|
|
13
|
+
* systematically undercount. Agreement between two passes, no earlier than the
|
|
14
|
+
* settle window, is the signal that the flush is done.
|
|
15
|
+
*
|
|
16
|
+
* @param pass - Reads the transcript once.
|
|
17
|
+
* @param retry - Attempt count, delay and settle window.
|
|
18
|
+
* @param options - Provider-specific early-exit behaviour.
|
|
19
|
+
* @returns The settled usage, or the last thing read.
|
|
20
|
+
*/
|
|
21
|
+
export async function readUntilSettled(pass, retry, options = {}) {
|
|
22
|
+
const attempts = Math.max(1, retry?.attempts ?? 1);
|
|
23
|
+
const delayMs = retry?.delayMs ?? 0;
|
|
24
|
+
const minSettleMs = retry?.minSettleMs ?? 0;
|
|
25
|
+
let previous;
|
|
26
|
+
for (let attempt = 0; attempt < attempts; attempt++) {
|
|
27
|
+
const usage = await pass();
|
|
28
|
+
if (options.bailOnFirstEmpty && usage === undefined && previous === undefined)
|
|
29
|
+
return undefined;
|
|
30
|
+
const settled = attempt * delayMs >= minSettleMs;
|
|
31
|
+
if (settled && usage && previous && sameUsage(usage, previous))
|
|
32
|
+
return usage;
|
|
33
|
+
previous = usage;
|
|
34
|
+
if (attempt < attempts - 1)
|
|
35
|
+
await sleep(delayMs);
|
|
36
|
+
}
|
|
37
|
+
return previous;
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* Read the tail of a transcript file.
|
|
41
|
+
*
|
|
42
|
+
* Only the tail: the turn's entries are at the end of the JSONL and the settle
|
|
43
|
+
* loop re-reads the file several times per Stop, so parsing a whole
|
|
44
|
+
* multi-megabyte session each pass would be waste (STYLEGUIDE 3.3).
|
|
45
|
+
*
|
|
46
|
+
* @param transcriptPath - Path the provider reported.
|
|
47
|
+
* @returns The tail text, or undefined when the file cannot be read.
|
|
48
|
+
*/
|
|
49
|
+
export async function readTranscriptTail(transcriptPath) {
|
|
50
|
+
try {
|
|
51
|
+
const stat = await fs.stat(transcriptPath);
|
|
52
|
+
if (stat.size <= TRANSCRIPT_TAIL_BYTES)
|
|
53
|
+
return await fs.readFile(transcriptPath, 'utf8');
|
|
54
|
+
return await readTailBytes(transcriptPath, stat.size);
|
|
55
|
+
}
|
|
56
|
+
catch {
|
|
57
|
+
return undefined;
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* Stable identity for a transcript entry.
|
|
62
|
+
*
|
|
63
|
+
* Some transcript variants omit the message id. A content hash is stable
|
|
64
|
+
* across retries and processes, so anonymous entries can still take part in
|
|
65
|
+
* the persisted exactly-once claim ledger. Identical anonymous lines are
|
|
66
|
+
* indistinguishable and intentionally deduplicate.
|
|
67
|
+
*
|
|
68
|
+
* @param rawId - The provider's own id, when it has one.
|
|
69
|
+
* @param line - The verbatim line, used for the fallback hash.
|
|
70
|
+
* @returns The id to key this entry by.
|
|
71
|
+
*/
|
|
72
|
+
export function messageIdFor(rawId, line) {
|
|
73
|
+
if (rawId)
|
|
74
|
+
return rawId;
|
|
75
|
+
return `${ANONYMOUS_MESSAGE_ID_PREFIX}${sha256Hex(line)}`;
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* Sum the usage of deduplicated transcript entries.
|
|
79
|
+
*
|
|
80
|
+
* A turn's window can mix models (subagents, title generation), so the model
|
|
81
|
+
* reported is the one that produced the most tokens — last-write-wins would
|
|
82
|
+
* let a tiny side-call mislabel the whole turn and misprice it downstream.
|
|
83
|
+
*
|
|
84
|
+
* @param entries - Usage entries keyed by message id.
|
|
85
|
+
* @returns The turn's usage, or undefined when there is nothing to report.
|
|
86
|
+
*/
|
|
87
|
+
export function accumulateUsage(entries) {
|
|
88
|
+
if (entries.size === 0)
|
|
89
|
+
return undefined;
|
|
90
|
+
let inputTokens;
|
|
91
|
+
let outputTokens;
|
|
92
|
+
let cachedInputTokens;
|
|
93
|
+
let cacheCreationInputTokens;
|
|
94
|
+
const modelTokens = new Map();
|
|
95
|
+
for (const { model, usage } of entries.values()) {
|
|
96
|
+
inputTokens = add(inputTokens, usage[TRANSCRIPT_INPUT_TOKENS]);
|
|
97
|
+
outputTokens = add(outputTokens, usage[TRANSCRIPT_OUTPUT_TOKENS]);
|
|
98
|
+
cachedInputTokens = add(cachedInputTokens, usage[TRANSCRIPT_CACHE_READ_TOKENS]);
|
|
99
|
+
cacheCreationInputTokens = add(cacheCreationInputTokens, usage[TRANSCRIPT_CACHE_CREATION_TOKENS]);
|
|
100
|
+
if (model)
|
|
101
|
+
modelTokens.set(model, (modelTokens.get(model) ?? 0) + entryWeight(usage));
|
|
102
|
+
}
|
|
103
|
+
return {
|
|
104
|
+
model: dominantModel(modelTokens),
|
|
105
|
+
inputTokens,
|
|
106
|
+
outputTokens,
|
|
107
|
+
cachedInputTokens,
|
|
108
|
+
cacheCreationInputTokens,
|
|
109
|
+
messageIds: [...entries.keys()]
|
|
110
|
+
};
|
|
111
|
+
}
|
|
112
|
+
/**
|
|
113
|
+
* Read the last TRANSCRIPT_TAIL_BYTES of a file, dropping the partial first
|
|
114
|
+
* line.
|
|
115
|
+
*
|
|
116
|
+
* @param transcriptPath - File to read.
|
|
117
|
+
* @param size - Its current size.
|
|
118
|
+
* @returns The tail text.
|
|
119
|
+
*/
|
|
120
|
+
async function readTailBytes(transcriptPath, size) {
|
|
121
|
+
const handle = await fs.open(transcriptPath, 'r');
|
|
122
|
+
try {
|
|
123
|
+
const buffer = Buffer.alloc(TRANSCRIPT_TAIL_BYTES);
|
|
124
|
+
const { bytesRead } = await handle.read(buffer, 0, TRANSCRIPT_TAIL_BYTES, size - TRANSCRIPT_TAIL_BYTES);
|
|
125
|
+
const raw = buffer.subarray(0, bytesRead).toString('utf8');
|
|
126
|
+
// Drop the first, almost certainly partial, line.
|
|
127
|
+
return raw.slice(raw.indexOf('\n') + 1);
|
|
128
|
+
}
|
|
129
|
+
finally {
|
|
130
|
+
await handle.close();
|
|
131
|
+
}
|
|
132
|
+
}
|
|
133
|
+
/**
|
|
134
|
+
* Decode one JSONL line.
|
|
135
|
+
*
|
|
136
|
+
* Unparseable lines are skipped rather than failing the read: a transcript
|
|
137
|
+
* being appended to concurrently routinely ends mid-line.
|
|
138
|
+
*
|
|
139
|
+
* @param line - The line text.
|
|
140
|
+
* @returns The object, or undefined when the line is not one.
|
|
141
|
+
*/
|
|
142
|
+
export function parseJsonLine(line) {
|
|
143
|
+
try {
|
|
144
|
+
return asRecord(JSON.parse(line));
|
|
145
|
+
}
|
|
146
|
+
catch {
|
|
147
|
+
return undefined;
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
/**
|
|
151
|
+
* Total tokens one entry accounts for, used to weight its model.
|
|
152
|
+
*
|
|
153
|
+
* @param usage - The entry's usage block.
|
|
154
|
+
* @returns The token weight.
|
|
155
|
+
*/
|
|
156
|
+
function entryWeight(usage) {
|
|
157
|
+
let weight = 0;
|
|
158
|
+
for (const field of TRANSCRIPT_TOKEN_FIELDS)
|
|
159
|
+
weight += finiteOrZero(usage[field]);
|
|
160
|
+
return weight;
|
|
161
|
+
}
|
|
162
|
+
/**
|
|
163
|
+
* The model that produced the most tokens.
|
|
164
|
+
*
|
|
165
|
+
* @param modelTokens - Token weight per model.
|
|
166
|
+
* @returns The dominant model, or undefined when none was named.
|
|
167
|
+
*/
|
|
168
|
+
function dominantModel(modelTokens) {
|
|
169
|
+
let dominant;
|
|
170
|
+
let best = -1;
|
|
171
|
+
for (const [model, tokens] of modelTokens) {
|
|
172
|
+
if (tokens <= best)
|
|
173
|
+
continue;
|
|
174
|
+
dominant = model;
|
|
175
|
+
best = tokens;
|
|
176
|
+
}
|
|
177
|
+
return dominant;
|
|
178
|
+
}
|
|
179
|
+
/**
|
|
180
|
+
* Whether two passes read the same usage.
|
|
181
|
+
*
|
|
182
|
+
* @param left - One pass.
|
|
183
|
+
* @param right - The other.
|
|
184
|
+
* @returns True when they are equal.
|
|
185
|
+
*/
|
|
186
|
+
function sameUsage(left, right) {
|
|
187
|
+
return JSON.stringify(left) === JSON.stringify(right);
|
|
188
|
+
}
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
import type { TurnRecord, TurnStateEntry } from './types/turn-state.types.js';
|
|
2
|
+
export type { PromptRecord, ResponseRecord, ToolRecord, TurnRecord, TurnStateEntry } from './types/turn-state.types.js';
|
|
3
|
+
/**
|
|
4
|
+
* Per-session accumulator for turn summaries.
|
|
5
|
+
*
|
|
6
|
+
* Hooks are separate short-lived processes and subagents can fire them
|
|
7
|
+
* concurrently, so state is one file per record: an append is an atomic create
|
|
8
|
+
* that can never race a read-modify-write, and two hooks writing at once
|
|
9
|
+
* simply produce two files.
|
|
10
|
+
*/
|
|
11
|
+
export declare class TurnStateStore {
|
|
12
|
+
readonly turnsDir: string;
|
|
13
|
+
/**
|
|
14
|
+
* Bind the store to its state root.
|
|
15
|
+
*
|
|
16
|
+
* @param turnsDir - Root directory the per-session state lives under.
|
|
17
|
+
*/
|
|
18
|
+
constructor(turnsDir: string);
|
|
19
|
+
/**
|
|
20
|
+
* Record one event of an open turn.
|
|
21
|
+
*
|
|
22
|
+
* @param sessionId - Provider session id.
|
|
23
|
+
* @param recordId - Stable id for this record; the filename.
|
|
24
|
+
* @param record - What happened.
|
|
25
|
+
*/
|
|
26
|
+
append(sessionId: string, recordId: string, record: TurnRecord): Promise<void>;
|
|
27
|
+
/**
|
|
28
|
+
* Every record of a session, oldest first.
|
|
29
|
+
*
|
|
30
|
+
* @param sessionId - Provider session id.
|
|
31
|
+
* @returns The records, without the files they came from.
|
|
32
|
+
*/
|
|
33
|
+
collect(sessionId: string): Promise<TurnRecord[]>;
|
|
34
|
+
/**
|
|
35
|
+
* Every record of a session with its file, so the caller can consume exactly
|
|
36
|
+
* what it summarized.
|
|
37
|
+
*
|
|
38
|
+
* @param sessionId - Provider session id.
|
|
39
|
+
* @returns The entries, sorted by record timestamp.
|
|
40
|
+
* @throws When the store exists but cannot be read — a broken store must not
|
|
41
|
+
* masquerade as "no records", or the turn would silently lose its context.
|
|
42
|
+
*/
|
|
43
|
+
collectEntries(sessionId: string): Promise<TurnStateEntry[]>;
|
|
44
|
+
/**
|
|
45
|
+
* Delete exactly these record files; concurrent appends are untouched.
|
|
46
|
+
*
|
|
47
|
+
* @param files - Paths returned by {@link collectEntries}.
|
|
48
|
+
*/
|
|
49
|
+
remove(files: readonly string[]): Promise<void>;
|
|
50
|
+
/**
|
|
51
|
+
* Record which transcript messages a closed turn has counted.
|
|
52
|
+
*
|
|
53
|
+
* One atomic file per turn; allocation across turns is serialized by the
|
|
54
|
+
* session usage lock in the tracker. Claims outlive turn-record removal on
|
|
55
|
+
* purpose, so a later-closing overlapping turn can never re-count them.
|
|
56
|
+
*
|
|
57
|
+
* @param sessionId - Provider session id.
|
|
58
|
+
* @param turnId - Turn the claim belongs to.
|
|
59
|
+
* @param messageIds - Transcript message ids counted into that turn.
|
|
60
|
+
*/
|
|
61
|
+
claimUsage(sessionId: string, turnId: string, messageIds: readonly string[]): Promise<void>;
|
|
62
|
+
/**
|
|
63
|
+
* Every transcript message id already claimed in this session.
|
|
64
|
+
*
|
|
65
|
+
* @param sessionId - Provider session id.
|
|
66
|
+
* @returns The claimed ids; empty when nothing has closed yet.
|
|
67
|
+
*/
|
|
68
|
+
claimedMessageIds(sessionId: string): Promise<Set<string>>;
|
|
69
|
+
/**
|
|
70
|
+
* Drop all state for a session, at SessionEnd.
|
|
71
|
+
*
|
|
72
|
+
* @param sessionId - Provider session id.
|
|
73
|
+
*/
|
|
74
|
+
clear(sessionId: string): Promise<void>;
|
|
75
|
+
/**
|
|
76
|
+
* Remove sessions whose newest record is older than `maxAgeMs`.
|
|
77
|
+
*
|
|
78
|
+
* Crashed or abandoned sessions never see a Stop or SessionEnd, and their
|
|
79
|
+
* raw prompt text must not sit on disk indefinitely.
|
|
80
|
+
*
|
|
81
|
+
* @param maxAgeMs - Age past which a session is considered abandoned.
|
|
82
|
+
*/
|
|
83
|
+
sweep(maxAgeMs: number): Promise<void>;
|
|
84
|
+
/**
|
|
85
|
+
* Directory holding one session's state.
|
|
86
|
+
*
|
|
87
|
+
* Hashed: session ids come from untrusted payloads and must never be able to
|
|
88
|
+
* traverse out of the state root.
|
|
89
|
+
*
|
|
90
|
+
* @param sessionId - Provider session id.
|
|
91
|
+
* @returns Absolute directory path.
|
|
92
|
+
*/
|
|
93
|
+
private sessionDir;
|
|
94
|
+
}
|
|
@@ -0,0 +1,234 @@
|
|
|
1
|
+
import fs from 'node:fs/promises';
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
import { asRecord } from '../core/object.js';
|
|
4
|
+
import { sha256Hex } from '../events/event-id.js';
|
|
5
|
+
import { writeFileAtomic } from '../storage/atomic-file.js';
|
|
6
|
+
import { readJsonFile } from '../storage/json-file.js';
|
|
7
|
+
import { SECRET_FILE_MODE } from '../storage/constants/storage.constants.js';
|
|
8
|
+
import { RE_UNSAFE_NAME_CHARS, SESSION_DIR_HASH_LENGTH, USAGE_CLAIM_PREFIX } from './constants/turns.constants.js';
|
|
9
|
+
/**
|
|
10
|
+
* Per-session accumulator for turn summaries.
|
|
11
|
+
*
|
|
12
|
+
* Hooks are separate short-lived processes and subagents can fire them
|
|
13
|
+
* concurrently, so state is one file per record: an append is an atomic create
|
|
14
|
+
* that can never race a read-modify-write, and two hooks writing at once
|
|
15
|
+
* simply produce two files.
|
|
16
|
+
*/
|
|
17
|
+
export class TurnStateStore {
|
|
18
|
+
turnsDir;
|
|
19
|
+
/**
|
|
20
|
+
* Bind the store to its state root.
|
|
21
|
+
*
|
|
22
|
+
* @param turnsDir - Root directory the per-session state lives under.
|
|
23
|
+
*/
|
|
24
|
+
constructor(turnsDir) {
|
|
25
|
+
this.turnsDir = turnsDir;
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* Record one event of an open turn.
|
|
29
|
+
*
|
|
30
|
+
* @param sessionId - Provider session id.
|
|
31
|
+
* @param recordId - Stable id for this record; the filename.
|
|
32
|
+
* @param record - What happened.
|
|
33
|
+
*/
|
|
34
|
+
async append(sessionId, recordId, record) {
|
|
35
|
+
const file = path.join(this.sessionDir(sessionId), `${safeName(recordId)}.json`);
|
|
36
|
+
// 0600: records hold raw prompt and response text.
|
|
37
|
+
await writeFileAtomic(file, JSON.stringify(record), SECRET_FILE_MODE);
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* Every record of a session, oldest first.
|
|
41
|
+
*
|
|
42
|
+
* @param sessionId - Provider session id.
|
|
43
|
+
* @returns The records, without the files they came from.
|
|
44
|
+
*/
|
|
45
|
+
async collect(sessionId) {
|
|
46
|
+
const entries = await this.collectEntries(sessionId);
|
|
47
|
+
return entries.map((entry) => entry.record);
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* Every record of a session with its file, so the caller can consume exactly
|
|
51
|
+
* what it summarized.
|
|
52
|
+
*
|
|
53
|
+
* @param sessionId - Provider session id.
|
|
54
|
+
* @returns The entries, sorted by record timestamp.
|
|
55
|
+
* @throws When the store exists but cannot be read — a broken store must not
|
|
56
|
+
* masquerade as "no records", or the turn would silently lose its context.
|
|
57
|
+
*/
|
|
58
|
+
async collectEntries(sessionId) {
|
|
59
|
+
const dir = this.sessionDir(sessionId);
|
|
60
|
+
const names = await readSessionDir(dir);
|
|
61
|
+
if (!names)
|
|
62
|
+
return [];
|
|
63
|
+
const entries = [];
|
|
64
|
+
for (const name of names) {
|
|
65
|
+
if (!name.endsWith('.json') || name.startsWith(USAGE_CLAIM_PREFIX))
|
|
66
|
+
continue;
|
|
67
|
+
const file = path.join(dir, name);
|
|
68
|
+
const read = await readJsonFile(file);
|
|
69
|
+
if (read.state !== 'ok' || !isTurnRecord(read.value))
|
|
70
|
+
continue;
|
|
71
|
+
entries.push({ file, record: read.value });
|
|
72
|
+
}
|
|
73
|
+
return entries.sort((a, b) => a.record.at.localeCompare(b.record.at));
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* Delete exactly these record files; concurrent appends are untouched.
|
|
77
|
+
*
|
|
78
|
+
* @param files - Paths returned by {@link collectEntries}.
|
|
79
|
+
*/
|
|
80
|
+
async remove(files) {
|
|
81
|
+
await Promise.all(files.map((file) => fs.rm(file, { force: true })));
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* Record which transcript messages a closed turn has counted.
|
|
85
|
+
*
|
|
86
|
+
* One atomic file per turn; allocation across turns is serialized by the
|
|
87
|
+
* session usage lock in the tracker. Claims outlive turn-record removal on
|
|
88
|
+
* purpose, so a later-closing overlapping turn can never re-count them.
|
|
89
|
+
*
|
|
90
|
+
* @param sessionId - Provider session id.
|
|
91
|
+
* @param turnId - Turn the claim belongs to.
|
|
92
|
+
* @param messageIds - Transcript message ids counted into that turn.
|
|
93
|
+
*/
|
|
94
|
+
async claimUsage(sessionId, turnId, messageIds) {
|
|
95
|
+
if (messageIds.length === 0)
|
|
96
|
+
return;
|
|
97
|
+
const file = path.join(this.sessionDir(sessionId), `${USAGE_CLAIM_PREFIX}${safeName(turnId)}.json`);
|
|
98
|
+
await writeFileAtomic(file, JSON.stringify({ messageIds }), SECRET_FILE_MODE);
|
|
99
|
+
}
|
|
100
|
+
/**
|
|
101
|
+
* Every transcript message id already claimed in this session.
|
|
102
|
+
*
|
|
103
|
+
* @param sessionId - Provider session id.
|
|
104
|
+
* @returns The claimed ids; empty when nothing has closed yet.
|
|
105
|
+
*/
|
|
106
|
+
async claimedMessageIds(sessionId) {
|
|
107
|
+
const dir = this.sessionDir(sessionId);
|
|
108
|
+
const claimed = new Set();
|
|
109
|
+
const names = await readSessionDirSafely(dir);
|
|
110
|
+
for (const name of names) {
|
|
111
|
+
if (!name.startsWith(USAGE_CLAIM_PREFIX) || !name.endsWith('.json'))
|
|
112
|
+
continue;
|
|
113
|
+
const read = await readJsonFile(path.join(dir, name));
|
|
114
|
+
const ids = asRecord(read.state === 'ok' ? read.value : undefined)?.['messageIds'];
|
|
115
|
+
if (!Array.isArray(ids))
|
|
116
|
+
continue;
|
|
117
|
+
for (const id of ids) {
|
|
118
|
+
if (typeof id === 'string')
|
|
119
|
+
claimed.add(id);
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
return claimed;
|
|
123
|
+
}
|
|
124
|
+
/**
|
|
125
|
+
* Drop all state for a session, at SessionEnd.
|
|
126
|
+
*
|
|
127
|
+
* @param sessionId - Provider session id.
|
|
128
|
+
*/
|
|
129
|
+
async clear(sessionId) {
|
|
130
|
+
await fs.rm(this.sessionDir(sessionId), { recursive: true, force: true });
|
|
131
|
+
}
|
|
132
|
+
/**
|
|
133
|
+
* Remove sessions whose newest record is older than `maxAgeMs`.
|
|
134
|
+
*
|
|
135
|
+
* Crashed or abandoned sessions never see a Stop or SessionEnd, and their
|
|
136
|
+
* raw prompt text must not sit on disk indefinitely.
|
|
137
|
+
*
|
|
138
|
+
* @param maxAgeMs - Age past which a session is considered abandoned.
|
|
139
|
+
*/
|
|
140
|
+
async sweep(maxAgeMs) {
|
|
141
|
+
const sessionDirs = await readSessionDirSafely(this.turnsDir);
|
|
142
|
+
const cutoff = Date.now() - maxAgeMs;
|
|
143
|
+
for (const name of sessionDirs) {
|
|
144
|
+
const dir = path.join(this.turnsDir, name);
|
|
145
|
+
await removeIfStale(dir, cutoff);
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
/**
|
|
149
|
+
* Directory holding one session's state.
|
|
150
|
+
*
|
|
151
|
+
* Hashed: session ids come from untrusted payloads and must never be able to
|
|
152
|
+
* traverse out of the state root.
|
|
153
|
+
*
|
|
154
|
+
* @param sessionId - Provider session id.
|
|
155
|
+
* @returns Absolute directory path.
|
|
156
|
+
*/
|
|
157
|
+
sessionDir(sessionId) {
|
|
158
|
+
return path.join(this.turnsDir, sha256Hex(sessionId).slice(0, SESSION_DIR_HASH_LENGTH));
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
/**
|
|
162
|
+
* List a session directory, distinguishing "never written" from "broken".
|
|
163
|
+
*
|
|
164
|
+
* @param dir - Session directory.
|
|
165
|
+
* @returns The file names, or undefined when the directory does not exist.
|
|
166
|
+
* @throws When the directory exists but cannot be listed.
|
|
167
|
+
*/
|
|
168
|
+
async function readSessionDir(dir) {
|
|
169
|
+
try {
|
|
170
|
+
return await fs.readdir(dir);
|
|
171
|
+
}
|
|
172
|
+
catch (error) {
|
|
173
|
+
// A session that never wrote state has no directory. Anything else
|
|
174
|
+
// (ENOTDIR, EACCES) is a broken store and has to surface.
|
|
175
|
+
if (error.code === 'ENOENT')
|
|
176
|
+
return undefined;
|
|
177
|
+
throw error;
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
/**
|
|
181
|
+
* List a directory, treating any failure as empty.
|
|
182
|
+
*
|
|
183
|
+
* @param dir - Directory to list.
|
|
184
|
+
* @returns The names, or an empty list.
|
|
185
|
+
*/
|
|
186
|
+
async function readSessionDirSafely(dir) {
|
|
187
|
+
try {
|
|
188
|
+
return await fs.readdir(dir);
|
|
189
|
+
}
|
|
190
|
+
catch {
|
|
191
|
+
return [];
|
|
192
|
+
}
|
|
193
|
+
}
|
|
194
|
+
/**
|
|
195
|
+
* Delete a session directory when nothing in it is newer than the cutoff.
|
|
196
|
+
*
|
|
197
|
+
* @param dir - Session directory.
|
|
198
|
+
* @param cutoff - Epoch milliseconds; older than this is abandoned.
|
|
199
|
+
*/
|
|
200
|
+
async function removeIfStale(dir, cutoff) {
|
|
201
|
+
try {
|
|
202
|
+
let newest = 0;
|
|
203
|
+
for (const file of await fs.readdir(dir)) {
|
|
204
|
+
const stat = await fs.stat(path.join(dir, file));
|
|
205
|
+
newest = Math.max(newest, stat.mtimeMs);
|
|
206
|
+
}
|
|
207
|
+
if (newest < cutoff)
|
|
208
|
+
await fs.rm(dir, { recursive: true, force: true });
|
|
209
|
+
}
|
|
210
|
+
catch {
|
|
211
|
+
// Concurrent hook activity in this session; leave it for the next sweep.
|
|
212
|
+
}
|
|
213
|
+
}
|
|
214
|
+
/**
|
|
215
|
+
* Filesystem-safe form of an untrusted record id.
|
|
216
|
+
*
|
|
217
|
+
* @param recordId - Id from a provider payload.
|
|
218
|
+
* @returns The sanitized name.
|
|
219
|
+
*/
|
|
220
|
+
function safeName(recordId) {
|
|
221
|
+
return recordId.replace(RE_UNSAFE_NAME_CHARS, '_');
|
|
222
|
+
}
|
|
223
|
+
/**
|
|
224
|
+
* Whether a decoded value is a turn record we still understand.
|
|
225
|
+
*
|
|
226
|
+
* @param value - Decoded file contents.
|
|
227
|
+
* @returns True when it is a usable record.
|
|
228
|
+
*/
|
|
229
|
+
function isTurnRecord(value) {
|
|
230
|
+
const record = asRecord(value);
|
|
231
|
+
if (!record || typeof record['at'] !== 'string')
|
|
232
|
+
return false;
|
|
233
|
+
return record['kind'] === 'prompt' || record['kind'] === 'tool' || record['kind'] === 'response';
|
|
234
|
+
}
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
import type { BuildTurnSummaryInput, TurnSummaryEvent } from './types/turn-summary.types.js';
|
|
2
|
+
export type { AgentUsageSummary, BuildTurnSummaryInput, TouchedFiles, TurnResponse, TurnSummaryEvent, TurnUsageStatus } from './types/turn-summary.types.js';
|
|
3
|
+
/**
|
|
4
|
+
* Flatten one turn's accumulated state into the single product record the hook
|
|
5
|
+
* path emits.
|
|
6
|
+
*
|
|
7
|
+
* Everything here is derived from the input: the same prompts, tools and usage
|
|
8
|
+
* always produce the same summary, including its id. That is what makes a
|
|
9
|
+
* duplicate Stop harmless.
|
|
10
|
+
*
|
|
11
|
+
* @param input - The turn's accumulated state.
|
|
12
|
+
* @returns The summary, with absent fields omitted rather than null.
|
|
13
|
+
*/
|
|
14
|
+
export declare function buildTurnSummary(input: BuildTurnSummaryInput): TurnSummaryEvent;
|
|
15
|
+
/**
|
|
16
|
+
* Recompute content evidence from the text that is actually transmitted.
|
|
17
|
+
*
|
|
18
|
+
* Evidence is captured before sanitization, but the sanitizer truncates and
|
|
19
|
+
* redacts; a backend verifying length or hash against the received text would
|
|
20
|
+
* then reject honest events. When the text is absent (capture disabled), the
|
|
21
|
+
* capture-time evidence still describes the content the developer saw, and is
|
|
22
|
+
* kept as the only description there is.
|
|
23
|
+
*
|
|
24
|
+
* @param summary - Summary about to be sent.
|
|
25
|
+
* @returns A copy whose evidence matches its own text.
|
|
26
|
+
*/
|
|
27
|
+
export declare function alignContentEvidence(summary: TurnSummaryEvent): TurnSummaryEvent;
|