dsh-observe 0.1.0

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.
Files changed (92) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/LICENSE +201 -0
  3. package/README.es.md +198 -0
  4. package/README.hi.md +198 -0
  5. package/README.md +198 -0
  6. package/README.pt.md +198 -0
  7. package/README.zh.md +198 -0
  8. package/THIRD_PARTY_NOTICES.md +21 -0
  9. package/cordis.patch.yml +86 -0
  10. package/lib/index.js +1947 -0
  11. package/lib/typert.host.js +109 -0
  12. package/lib/types/backoff.d.ts +17 -0
  13. package/lib/types/backoff.d.ts.map +1 -0
  14. package/lib/types/backoff.js +17 -0
  15. package/lib/types/backoff.js.map +1 -0
  16. package/lib/types/collector.d.ts +83 -0
  17. package/lib/types/collector.d.ts.map +1 -0
  18. package/lib/types/collector.js +506 -0
  19. package/lib/types/collector.js.map +1 -0
  20. package/lib/types/config.d.ts +286 -0
  21. package/lib/types/config.d.ts.map +1 -0
  22. package/lib/types/config.js +312 -0
  23. package/lib/types/config.js.map +1 -0
  24. package/lib/types/ids.d.ts +43 -0
  25. package/lib/types/ids.d.ts.map +1 -0
  26. package/lib/types/ids.js +63 -0
  27. package/lib/types/ids.js.map +1 -0
  28. package/lib/types/index.d.ts +35 -0
  29. package/lib/types/index.d.ts.map +1 -0
  30. package/lib/types/index.js +162 -0
  31. package/lib/types/index.js.map +1 -0
  32. package/lib/types/model.d.ts +89 -0
  33. package/lib/types/model.d.ts.map +1 -0
  34. package/lib/types/model.js +25 -0
  35. package/lib/types/model.js.map +1 -0
  36. package/lib/types/pipeline.d.ts +71 -0
  37. package/lib/types/pipeline.d.ts.map +1 -0
  38. package/lib/types/pipeline.js +193 -0
  39. package/lib/types/pipeline.js.map +1 -0
  40. package/lib/types/pricing.d.ts +34 -0
  41. package/lib/types/pricing.d.ts.map +1 -0
  42. package/lib/types/pricing.js +45 -0
  43. package/lib/types/pricing.js.map +1 -0
  44. package/lib/types/project.d.ts +26 -0
  45. package/lib/types/project.d.ts.map +1 -0
  46. package/lib/types/project.js +52 -0
  47. package/lib/types/project.js.map +1 -0
  48. package/lib/types/remote.d.ts +28 -0
  49. package/lib/types/remote.d.ts.map +1 -0
  50. package/lib/types/remote.js +45 -0
  51. package/lib/types/remote.js.map +1 -0
  52. package/lib/types/sanitize.d.ts +78 -0
  53. package/lib/types/sanitize.d.ts.map +1 -0
  54. package/lib/types/sanitize.js +132 -0
  55. package/lib/types/sanitize.js.map +1 -0
  56. package/lib/types/sinks.d.ts +84 -0
  57. package/lib/types/sinks.d.ts.map +1 -0
  58. package/lib/types/sinks.js +434 -0
  59. package/lib/types/sinks.js.map +1 -0
  60. package/lib/types/spool.d.ts +113 -0
  61. package/lib/types/spool.d.ts.map +1 -0
  62. package/lib/types/spool.js +167 -0
  63. package/lib/types/spool.js.map +1 -0
  64. package/lib/types/typert.host.d.ts +93 -0
  65. package/lib/types/typert.host.d.ts.map +1 -0
  66. package/lib/types/typert.host.js +23 -0
  67. package/lib/types/typert.host.js.map +1 -0
  68. package/lib/types/version.d.ts +10 -0
  69. package/lib/types/version.d.ts.map +1 -0
  70. package/lib/types/version.js +10 -0
  71. package/lib/types/version.js.map +1 -0
  72. package/lib/types/wire.d.ts +206 -0
  73. package/lib/types/wire.d.ts.map +1 -0
  74. package/lib/types/wire.js +71 -0
  75. package/lib/types/wire.js.map +1 -0
  76. package/package.json +147 -0
  77. package/src/backoff.ts +20 -0
  78. package/src/collector.ts +561 -0
  79. package/src/config.ts +604 -0
  80. package/src/ids.ts +68 -0
  81. package/src/index.ts +186 -0
  82. package/src/model.ts +100 -0
  83. package/src/pipeline.ts +205 -0
  84. package/src/pricing.ts +55 -0
  85. package/src/project.ts +55 -0
  86. package/src/remote.ts +56 -0
  87. package/src/sanitize.ts +132 -0
  88. package/src/sinks.ts +471 -0
  89. package/src/spool.ts +196 -0
  90. package/src/typert.host.ts +24 -0
  91. package/src/version.ts +10 -0
  92. package/src/wire.ts +97 -0
@@ -0,0 +1,109 @@
1
+ import { z } from "zod";
2
+ //#region src/wire.ts
3
+ /**
4
+ * The `observe` Remote wire vocabulary: the status snapshot and the kill
5
+ * switch result, their zod v4 strict schemas, and the invocation descriptors
6
+ * shared by the host `./typert` manifest. One canonical source keeps the two
7
+ * Typert faces from drifting apart.
8
+ * @module dsh-observe/wire
9
+ */
10
+ /** Strict wire schema for {@link ObserveStatus} (zod v4). */
11
+ const OBSERVE_STATUS_SCHEMA = z.object({
12
+ enabled: z.boolean(),
13
+ backends: z.object({
14
+ otlp: z.boolean(),
15
+ langfuse: z.boolean()
16
+ }),
17
+ queueDepth: z.object({
18
+ otlp: z.number().int(),
19
+ langfuse: z.number().int()
20
+ }),
21
+ spool: z.object({
22
+ otlp: z.object({
23
+ batches: z.number().int(),
24
+ records: z.number().int()
25
+ }),
26
+ langfuse: z.object({
27
+ batches: z.number().int(),
28
+ records: z.number().int()
29
+ })
30
+ })
31
+ });
32
+ /** Strict wire schema for {@link ObserveSetEnabledResult} (zod v4). */
33
+ const OBSERVE_SET_ENABLED_RESULT_SCHEMA = z.object({ enabled: z.boolean() });
34
+ /** JSON codec for the setEnabled argument. */
35
+ const SET_ENABLED_ARGS_CODEC = z.object({ enabled: z.boolean() });
36
+ /** The `observe/status` invocation descriptor: the read-only status snapshot. */
37
+ const OBSERVE_STATUS_DESCRIPTOR = Object.freeze({
38
+ id: "dsh-observe#observe/status",
39
+ service: "dsh-observe",
40
+ namespace: "observe",
41
+ method: "status",
42
+ invocation: Object.freeze({ kind: "direct" }),
43
+ parameters: Object.freeze([]),
44
+ result: Object.freeze({
45
+ mode: "strict",
46
+ typeSymbol: "dsh-observe/types#ObserveStatus",
47
+ schema: OBSERVE_STATUS_SCHEMA
48
+ }),
49
+ sourceLocation: Object.freeze({
50
+ file: "src/wire.ts",
51
+ line: 1,
52
+ column: 1
53
+ })
54
+ });
55
+ /** The `observe/setEnabled` invocation descriptor: the runtime kill switch. */
56
+ const OBSERVE_SET_ENABLED_DESCRIPTOR = Object.freeze({
57
+ id: "dsh-observe#observe/setEnabled",
58
+ service: "dsh-observe",
59
+ namespace: "observe",
60
+ method: "setEnabled",
61
+ invocation: Object.freeze({ kind: "direct" }),
62
+ parameters: Object.freeze([Object.freeze({
63
+ name: "request",
64
+ wire: "request",
65
+ source: "json",
66
+ codec: Object.freeze({
67
+ mode: "strict",
68
+ typeSymbol: "dsh-observe/types#ObserveSetEnabledArgs",
69
+ schema: SET_ENABLED_ARGS_CODEC
70
+ })
71
+ })]),
72
+ result: Object.freeze({
73
+ mode: "strict",
74
+ typeSymbol: "dsh-observe/types#ObserveSetEnabledResult",
75
+ schema: OBSERVE_SET_ENABLED_RESULT_SCHEMA
76
+ }),
77
+ sourceLocation: Object.freeze({
78
+ file: "src/wire.ts",
79
+ line: 1,
80
+ column: 1
81
+ })
82
+ });
83
+ /** The canonical invocation list both Typert faces register. */
84
+ const OBSERVE_INVOCATIONS = Object.freeze([OBSERVE_STATUS_DESCRIPTOR, OBSERVE_SET_ENABLED_DESCRIPTOR]);
85
+ //#endregion
86
+ //#region src/typert.host.ts
87
+ /**
88
+ * The hand-written Typert HOST manifest for `dsh-observe`, exported as
89
+ * `./typert` so the harness's typert-loader registers the `observe` status /
90
+ * kill-switch invocations automatically when this plugin mounts. Same shape
91
+ * as a generator output (validated by the loader): package face, empty model
92
+ * and schemas, and the canonical invocation list from `src/wire.ts`.
93
+ *
94
+ * @module dsh-observe/typert
95
+ */
96
+ /** Host Typert manifest (validated by `@deepseek-ai/dsh-typert-loader`). */
97
+ const TYPERT = Object.freeze({
98
+ package: "dsh-observe",
99
+ face: "host",
100
+ schemas: Object.freeze([]),
101
+ invocations: OBSERVE_INVOCATIONS,
102
+ model: Object.freeze({
103
+ services: Object.freeze([]),
104
+ events: Object.freeze([]),
105
+ objects: Object.freeze([])
106
+ })
107
+ });
108
+ //#endregion
109
+ export { TYPERT };
@@ -0,0 +1,17 @@
1
+ /**
2
+ * Backoff delay computation for export retries: deterministic exponential
3
+ * backoff (no jitter — tests and replays stay reproducible).
4
+ * @module dsh-observe/backoff
5
+ */
6
+ /**
7
+ * Compute the delay before the next retry attempt.
8
+ * @param consecutiveFailures - failures so far (1 = first retry).
9
+ * @param policy - the resolved retry policy.
10
+ * @returns the delay in milliseconds, capped at `maxDelayMs`.
11
+ */
12
+ export declare function backoffDelayMs(consecutiveFailures: number, policy: {
13
+ readonly baseDelayMs: number;
14
+ readonly factor: number;
15
+ readonly maxDelayMs: number;
16
+ }): number;
17
+ //# sourceMappingURL=backoff.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"backoff.d.ts","sourceRoot":"","sources":["../../src/backoff.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,mBAAmB,EAAE,MAAM,EAC3B,MAAM,EAAE;IAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAC7F,MAAM,CAIR"}
@@ -0,0 +1,17 @@
1
+ /**
2
+ * Backoff delay computation for export retries: deterministic exponential
3
+ * backoff (no jitter — tests and replays stay reproducible).
4
+ * @module dsh-observe/backoff
5
+ */
6
+ /**
7
+ * Compute the delay before the next retry attempt.
8
+ * @param consecutiveFailures - failures so far (1 = first retry).
9
+ * @param policy - the resolved retry policy.
10
+ * @returns the delay in milliseconds, capped at `maxDelayMs`.
11
+ */
12
+ export function backoffDelayMs(consecutiveFailures, policy) {
13
+ const exponent = Math.min(consecutiveFailures, 30);
14
+ const delay = policy.baseDelayMs * (policy.factor ** exponent);
15
+ return Math.min(delay, policy.maxDelayMs);
16
+ }
17
+ //# sourceMappingURL=backoff.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"backoff.js","sourceRoot":"","sources":["../../src/backoff.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAC5B,mBAA2B,EAC3B,MAA8F;IAE9F,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAA;IAClD,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,GAAG,CAAC,MAAM,CAAC,MAAM,IAAI,QAAQ,CAAC,CAAA;IAC9D,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,CAAA;AAC3C,CAAC"}
@@ -0,0 +1,83 @@
1
+ /**
2
+ * The session/event collector: turns the durable session log stream into
3
+ * closed span records and metric samples. Spans open at their boundary
4
+ * events and close at their counterpart events (turn/start → turn/end,
5
+ * step/start → step/end, tool/call → tool/result, request/header →
6
+ * assistant/message); a missing closer (crash, disposal) closes the span
7
+ * with an error status at the latest observed event time. Everything
8
+ * exported is reconstructable from the session log alone — the collector
9
+ * invents no model-visible content, and prompt/completion bodies come from
10
+ * the logged header and the session surface.
11
+ * @module dsh-observe/collector
12
+ */
13
+ import type { Session, SessionEvent } from '@deepseek-ai/dsh-session';
14
+ import type { ResolvedConfig } from './config.ts';
15
+ import type { MetricRecord, SpanRecord } from './model.ts';
16
+ import type { ObserveLogger } from './sinks.ts';
17
+ /**
18
+ * The structural surface of the optional `ctx.tokenMeter` service. Only the
19
+ * fields dsh-observe reads are declared; the service is optional, so a host
20
+ * without it simply skips the context-token gauge.
21
+ */
22
+ export interface TokenMeterService {
23
+ measure(session: Session): {
24
+ totalTokens: number;
25
+ baseline?: {
26
+ kind?: string;
27
+ };
28
+ };
29
+ }
30
+ /**
31
+ * The event → span/metric collector. State lives in a WeakMap keyed by the
32
+ * live Session, so sessions the plugin stops seeing are garbage-collected.
33
+ */
34
+ export declare class Collector {
35
+ private readonly config;
36
+ private readonly tokenMeter;
37
+ private readonly onSpan;
38
+ private readonly onMetric;
39
+ private readonly logger;
40
+ private readonly states;
41
+ /**
42
+ * @param config - the resolved plugin config.
43
+ * @param tokenMeter - lazy lookup of the optional token meter service.
44
+ * @param onSpan - span sink (both pipelines).
45
+ * @param onMetric - metric sink (OTLP aggregation).
46
+ * @param logger - the plugin logger.
47
+ */
48
+ constructor(config: ResolvedConfig, tokenMeter: () => TokenMeterService | undefined, onSpan: (span: SpanRecord) => void, onMetric: (metric: MetricRecord) => void, logger: ObserveLogger);
49
+ /**
50
+ * Fold one appended session event.
51
+ * @param session - the session the event belongs to.
52
+ * @param event - the appended event.
53
+ */
54
+ handleEvent(session: Session, event: SessionEvent): void;
55
+ /**
56
+ * Close every open span for a session leaving the store.
57
+ * @param session - the disposed session.
58
+ */
59
+ handleSessionDisposed(session: Session): void;
60
+ private stateOf;
61
+ private turnStart;
62
+ private stepStart;
63
+ private assistantMessage;
64
+ private toolCall;
65
+ private toolResult;
66
+ private stepEnd;
67
+ private turnEnd;
68
+ /** Close one step: dangling LLM span, dangling tool spans, the step span, and the context gauge. */
69
+ private closeStep;
70
+ /** The context-pressure gauge from the optional token meter (contained). */
71
+ private emitContextGauge;
72
+ /** Token and cost counters for one LLM call. */
73
+ private emitUsageMetrics;
74
+ /** The sanitized prompt snapshot: logged system prompt plus the current session surface. */
75
+ private capturePrompt;
76
+ /** The current provider/model attribution: request context first, then the logged header. */
77
+ private modelOf;
78
+ /** Common span attributes (sanitized and budgeted). */
79
+ private baseAttributes;
80
+ /** Sanitize and bound one attribute string. */
81
+ private attr;
82
+ }
83
+ //# sourceMappingURL=collector.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"collector.d.ts","sourceRoot":"","sources":["../../src/collector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAA+B,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAElG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACjD,OAAO,KAAK,EAAc,YAAY,EAAE,UAAU,EAAe,MAAM,YAAY,CAAA;AAInF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAK/C;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG;QACzB,WAAW,EAAE,MAAM,CAAA;QACnB,QAAQ,CAAC,EAAE;YAAE,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAC7B,CAAA;CACF;AAmDD;;;GAGG;AACH,qBAAa,SAAS;IAWlB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAdzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuC;IAE9D;;;;;;OAMG;gBAEgB,MAAM,EAAE,cAAc,EACtB,UAAU,EAAE,MAAM,iBAAiB,GAAG,SAAS,EAC/C,MAAM,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,EAClC,QAAQ,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,EACxC,MAAM,EAAE,aAAa;IAGxC;;;;OAIG;IACH,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI;IAqDxD;;;OAGG;IACH,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAqB7C,OAAO,CAAC,OAAO;IAef,OAAO,CAAC,SAAS;IAmBjB,OAAO,CAAC,SAAS;IAejB,OAAO,CAAC,gBAAgB;IAiDxB,OAAO,CAAC,QAAQ;IAiBhB,OAAO,CAAC,UAAU;IA6ClB,OAAO,CAAC,OAAO;IAMf,OAAO,CAAC,OAAO;IA6Bf,oGAAoG;IACpG,OAAO,CAAC,SAAS;IAsEjB,4EAA4E;IAC5E,OAAO,CAAC,gBAAgB;IAuBxB,gDAAgD;IAChD,OAAO,CAAC,gBAAgB;IAqCxB,4FAA4F;IAC5F,OAAO,CAAC,aAAa;IAYrB,6FAA6F;IAC7F,OAAO,CAAC,OAAO;IAOf,uDAAuD;IACvD,OAAO,CAAC,cAAc;IAatB,+CAA+C;IAC/C,OAAO,CAAC,IAAI;CAGb"}