mirror of
https://github.com/deepseek-ai/deepseek-harness.git
synced 2026-09-09 04:02:35 +00:00
Yichen Jiang
13daefe073
Telemetry was the only call site this PR could not cover without changing the SDK transport underneath it, and both ways of doing that cost more than the channel is worth. Routing an `http.Agent` needs Node's `proxyEnv`, added in 22.21 and 24.5 — inside the engines range, so three supported runtimes stayed direct anyway, and the proxy package had to keep a `createNodeHttpAgent` export for a path that only sometimes worked. Replacing the transport with the SDK's `fetch` delegate covered every runtime but has no compression, while the shipped `base` bundle enables gzip and a realistic OTLP batch is 6.4x smaller with it; keeping both meant gzipping at the serializer, which put transport code inside a telemetry plugin. Telemetry is the one outbound channel whose loss costs the user nothing: no tool, model request, or session depends on it, and an export that cannot connect is already dropped silently. A user behind a mandatory proxy is left where they were rather than regressed. `src/index.ts`, `otel.spec.ts`, and `tsconfig.json` return to their state on master; the package keeps only a dev dependency on the proxy library. `egress.spec.ts` inverts: it installs a policy and asserts the fake proxy saw nothing, so an SDK upgrade that moved the exporter onto `fetch` would surface as a failing test rather than silently routing telemetry.
description, kind
| description | kind |
|---|---|
| Package map for the durable session data plane: the persistence seam and its backends, checkpoint policy, projections, log-backed titles, and outbound session telemetry. | package-group |
session/ — durable session data plane
English | 中文
Summary
The session group makes an agent's conversation durable and reusable outside the live loop: the persistence seam stores the event log and restores it on resume, the checkpoint policy keeps requests, tool side effects, and completed steps durable before the next action, projections serve whole log-derived values to client carriers, titles name each session from its content, and telemetry reports session activity outbound. Mount the shipped JSONL persistence provider first, then add the checkpoint policy and any projection, title, or telemetry packages the deployment needs. This page maps the group; every package README owns its contract, and session-query/ is a sibling group whose read/tool surface consumes persistence independently.
Table of Contents
Packages
The group splits into four families: durable storage (persistence seam, backends, checkpoint policy), projections, titles, and telemetry. Each package README owns its contract and configuration.
Persistence
| Package | Role | ctx key |
|---|---|---|
session-persistence/ |
Defines the durable session-storage service and the shared write coordination every backend composes | ctx.sessionPersistence |
session-persistence-jsonl/ |
Shipped backend: one append-only JSONL log per session, optionally Zstandard-compressed | registers on ctx.sessionPersistence |
session-checkpoint-policy/ |
Makes model requests, top-level tool side effects, and completed steps durable before the next action | wraps ctx.llm and ctx.tools |
session-log-deepseek/ |
Uploads the incremental canonical log as optional official DeepSeek request metadata | contributes dsh_session_log |
Projection
| Package | Role | ctx key |
|---|---|---|
session-projection/ |
Defines and drives projection units that fold committed events into whole current values | ctx.sessionProjections |
session-projection-cache/ |
Persists projection checkpoints so cold reads skip full log loads | ctx.sessionProjectionCache |
session-stats/ |
Serves whole-log conversation counts and wall times through the sessionStats unit |
registers on ctx.sessionProjections |
session-turn-outline/ |
Serves the whole-log turn outline (turn, turn/start seq, prompt preview) through the turnOutline unit |
registers on ctx.sessionProjections |
Titles
| Package | Role | ctx key |
|---|---|---|
session-title/ |
Log-backed session titles with a deterministic fallback and one optional provider | ctx.sessionTitle |
session-title-llm/ |
Shared model-backed title-generation policy for the provider packages | library — no ctx key |
session-title-first-prompt-llm/ |
Titles a session from its first eligible human message | registers on ctx.sessionTitle |
session-title-all-prompts-llm/ |
Titles a session from all eligible human messages | registers on ctx.sessionTitle |
Telemetry
| Package | Role | ctx key |
|---|---|---|
session-telemetry/ |
Captures session activity and hands records to a configured reporting backend | ctx.sessionTelemetry |
session-telemetry-otel/ |
Delivers telemetry through OpenTelemetry logs in FULL, FEEDBACK_ONLY, or DISABLED mode |
registers on ctx.sessionTelemetry |
Only one title provider may register at a time; without one, the title service keeps its deterministic fallback. The subsystem pages below are the backend-neutral references for each family.
Related documentation
- Session persistence subsystem — backend-neutral service semantics, the flush checkpoint, and crash recovery.
- Session projections subsystem — the projection unit contract and drive semantics.
- Session titles subsystem — title eligibility, fallback, and provider flow.
- Session telemetry subsystem — capture, redaction, and delivery modes.
- Session subsystem — the live event log every package in this group persists or derives from.
Dev Note
None.