@netgreener/runtime 0.1.14 → 0.1.15

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/TUTORIAL.md CHANGED
@@ -227,7 +227,7 @@ Pass = scripts exit 0; payloads validate; no live upload required.
227
227
 
228
228
  1. Deploy / start the API with live env (§4.3).
229
229
  2. Call 2–3 real routes (health + one business route).
230
- 3. Stop the process (or wait for `NETGREENER_RUNTIME_FLUSH_MINUTES`, default 5).
230
+ 3. Stop the process (or wait for `NETGREENER_RUNTIME_FLUSH_MINUTES`, default 1).
231
231
  4. Dashboard → **Project `<PROJECT_ID>`** → newest **Run** → **Runtime Ops** / API Runtime.
232
232
  5. Pass = bounded route templates listed (e.g. `GET /health`), not raw customer paths.
233
233
  6. Keep a sanitized evidence record (revision, env, run id) — see
@@ -16,9 +16,11 @@ export declare class ServiceRuntimeAggregator {
16
16
  cpuTimeMs?: number;
17
17
  /** Measured RSS KiB at sample end. */
18
18
  peakRssKb?: number;
19
+ completed?: boolean;
20
+ completionDurationMs?: number;
19
21
  }): void;
20
22
  private recordIntoMap;
21
- /** Peak RSS (KiB) across units with calls — for crude window RAM estimate. */
23
+ /** Peak RSS (KiB) across units with calls/activity — for the window RAM estimate. */
22
24
  maxPeakRssKb(): number;
23
25
  private buildUnitsList;
24
26
  hasData(): boolean;
@@ -57,6 +57,7 @@ export class ServiceRuntimeAggregator {
57
57
  calls: 0,
58
58
  errors: 0,
59
59
  durationMsTotal: 0,
60
+ completedDurationMsTotal: 0,
60
61
  durationMsMax: 0,
61
62
  cpuMsTotal: 0,
62
63
  cpuMsMeasured: false,
@@ -65,13 +66,18 @@ export class ServiceRuntimeAggregator {
65
66
  target.set(key, unit);
66
67
  }
67
68
  }
68
- unit.calls += 1;
69
- if (sample.error)
69
+ if (sample.completed !== false)
70
+ unit.calls += 1;
71
+ if (sample.completed !== false && sample.error)
70
72
  unit.errors += 1;
71
73
  // Math.max(0, NaN) === NaN — must reject non-finite before accumulate.
72
74
  const ms = nonNegativeFinite(sample.durationMs);
73
75
  unit.durationMsTotal += ms;
74
- unit.durationMsMax = Math.max(unit.durationMsMax, ms);
76
+ if (sample.completed !== false) {
77
+ const completedMs = nonNegativeFinite(sample.completionDurationMs ?? sample.durationMs);
78
+ unit.completedDurationMsTotal += completedMs;
79
+ unit.durationMsMax = Math.max(unit.durationMsMax, completedMs);
80
+ }
75
81
  if (sample.cpuTimeMs !== undefined) {
76
82
  unit.cpuMsTotal += nonNegativeFinite(sample.cpuTimeMs);
77
83
  unit.cpuMsMeasured = true;
@@ -82,17 +88,17 @@ export class ServiceRuntimeAggregator {
82
88
  unit.peakRssKbMax = Math.max(unit.peakRssKbMax, rss);
83
89
  }
84
90
  }
85
- /** Peak RSS (KiB) across units with calls — for crude window RAM estimate. */
91
+ /** Peak RSS (KiB) across units with calls/activity — for the window RAM estimate. */
86
92
  maxPeakRssKb() {
87
93
  let max = 0;
88
94
  for (const u of this.units.values()) {
89
- if (u.calls > 0 && u.peakRssKbMax > max)
95
+ if ((u.calls > 0 || u.durationMsTotal > 0) && u.peakRssKbMax > max)
90
96
  max = u.peakRssKbMax;
91
97
  }
92
98
  return max;
93
99
  }
94
100
  buildUnitsList(source, windowEnergyKwh, equalShare, totalDuration, occByUnit, alloc) {
95
- const list = [...source.values()].filter((u) => u.calls > 0);
101
+ const list = [...source.values()].filter((u) => (u.calls > 0 || u.durationMsTotal > 0));
96
102
  if (!list.length)
97
103
  return [];
98
104
  const energyBudget = nonNegativeFinite(windowEnergyKwh);
@@ -104,9 +110,9 @@ export class ServiceRuntimeAggregator {
104
110
  const sorted = list.sort((a, b) => b.durationMsTotal - a.durationMsTotal);
105
111
  const totalCalls = list.reduce((sum, unit) => sum + unit.calls, 0);
106
112
  const units = sorted.map((u) => {
107
- const share = equalShare ? u.calls / totalCalls : u.durationMsTotal / totalDuration;
113
+ const share = equalShare ? (totalCalls > 0 ? u.calls / totalCalls : 1 / list.length) : u.durationMsTotal / totalDuration;
108
114
  const energy = energyBudget * share;
109
- const avg = u.calls ? u.durationMsTotal / u.calls : 0;
115
+ const avg = u.calls ? u.completedDurationMsTotal / u.calls : 0;
110
116
  const cpuSeconds = alloc?.windowCpuSeconds != null
111
117
  ? nonNegativeFinite(alloc.windowCpuSeconds) * share
112
118
  : u.cpuMsMeasured
@@ -153,7 +159,7 @@ export class ServiceRuntimeAggregator {
153
159
  }
154
160
  hasData() {
155
161
  for (const u of this.units.values()) {
156
- if (u.calls > 0)
162
+ if ((u.calls > 0 || u.durationMsTotal > 0))
157
163
  return true;
158
164
  }
159
165
  return false;
@@ -161,7 +167,7 @@ export class ServiceRuntimeAggregator {
161
167
  totalDurationMs() {
162
168
  let total = 0;
163
169
  for (const u of this.units.values()) {
164
- if (u.calls > 0)
170
+ if ((u.calls > 0 || u.durationMsTotal > 0))
165
171
  total += u.durationMsTotal;
166
172
  }
167
173
  return total;
@@ -170,7 +176,7 @@ export class ServiceRuntimeAggregator {
170
176
  totalMeasuredCpuMs() {
171
177
  let total = 0;
172
178
  for (const u of this.units.values()) {
173
- if (u.calls > 0 && u.cpuMsMeasured)
179
+ if ((u.calls > 0 || u.durationMsTotal > 0) && u.cpuMsMeasured)
174
180
  total += u.cpuMsTotal;
175
181
  }
176
182
  return total;
@@ -178,7 +184,7 @@ export class ServiceRuntimeAggregator {
178
184
  /** True when any unit recorded measured process CPU (not duration proxy). */
179
185
  hasMeasuredCpu() {
180
186
  for (const u of this.units.values()) {
181
- if (u.calls > 0 && u.cpuMsMeasured)
187
+ if ((u.calls > 0 || u.durationMsTotal > 0) && u.cpuMsMeasured)
182
188
  return true;
183
189
  }
184
190
  return false;
@@ -186,7 +192,7 @@ export class ServiceRuntimeAggregator {
186
192
  /** True when any unit recorded peak RSS. */
187
193
  hasMeasuredRss() {
188
194
  for (const u of this.units.values()) {
189
- if (u.calls > 0 && u.peakRssKbMax > 0)
195
+ if ((u.calls > 0 || u.durationMsTotal > 0) && u.peakRssKbMax > 0)
190
196
  return true;
191
197
  }
192
198
  return false;
@@ -197,7 +203,7 @@ export class ServiceRuntimeAggregator {
197
203
  * Occupancy is window-scaled (Python twin) so coverage reconciles to ``window_seconds``.
198
204
  */
199
205
  buildV0(opts) {
200
- const list = [...this.units.values()].filter((u) => u.calls > 0);
206
+ const list = [...this.units.values()].filter((u) => (u.calls > 0 || u.durationMsTotal > 0));
201
207
  if (!list.length)
202
208
  return null;
203
209
  const windowEnergyKwh = nonNegativeFinite(opts.windowEnergyKwh);
@@ -263,12 +269,12 @@ export class ServiceRuntimeAggregator {
263
269
  const totalBusy = list.reduce((s, u) => s + u.durationMsTotal, 0);
264
270
  const totalCalls = list.reduce((s, u) => s + u.calls, 0);
265
271
  for (const [tenantId, tenantMap] of this.byTenant.entries()) {
266
- const tenantList = [...tenantMap.values()].filter((u) => u.calls > 0);
272
+ const tenantList = [...tenantMap.values()].filter((u) => (u.calls > 0 || u.durationMsTotal > 0));
267
273
  if (!tenantList.length)
268
274
  continue;
269
275
  const tenantBusy = tenantList.reduce((s, u) => s + u.durationMsTotal, 0);
270
276
  const tenantShare = totalBusy > 0 ? tenantBusy / totalBusy
271
- : tenantList.reduce((sum, unit) => sum + unit.calls, 0) / totalCalls;
277
+ : totalCalls > 0 ? tenantList.reduce((sum, unit) => sum + unit.calls, 0) / totalCalls : 0;
272
278
  const tenantEnergy = totalBusy > 0
273
279
  ? windowEnergyKwh * (tenantBusy / totalBusy)
274
280
  : windowEnergyKwh * tenantShare;
@@ -411,6 +417,7 @@ export class ServiceRuntimeAggregator {
411
417
  dst.calls += src.calls;
412
418
  dst.errors += src.errors;
413
419
  dst.durationMsTotal += src.durationMsTotal;
420
+ dst.completedDurationMsTotal += src.completedDurationMsTotal;
414
421
  dst.durationMsMax = Math.max(dst.durationMsMax, src.durationMsMax);
415
422
  dst.cpuMsTotal += src.cpuMsTotal;
416
423
  dst.cpuMsMeasured = dst.cpuMsMeasured || src.cpuMsMeasured;
package/dist/config.d.ts CHANGED
@@ -20,7 +20,7 @@ export type RuntimeConfig = {
20
20
  tenantLabelClaim: string | null;
21
21
  };
22
22
  /** Established v0 flush / TDP bounds (committed Node runtime foundation). */
23
- export declare const DEFAULT_RUNTIME_FLUSH_MINUTES = 5;
23
+ export declare const DEFAULT_RUNTIME_FLUSH_MINUTES = 1;
24
24
  export declare const MIN_RUNTIME_FLUSH_MINUTES = 1;
25
25
  export declare const MAX_RUNTIME_FLUSH_MINUTES: number;
26
26
  export declare const DEFAULT_ESTIMATE_TDP_WATTS = 65;
package/dist/config.js CHANGED
@@ -1,5 +1,5 @@
1
1
  /** Established v0 flush / TDP bounds (committed Node runtime foundation). */
2
- export const DEFAULT_RUNTIME_FLUSH_MINUTES = 5;
2
+ export const DEFAULT_RUNTIME_FLUSH_MINUTES = 1;
3
3
  export const MIN_RUNTIME_FLUSH_MINUTES = 1;
4
4
  export const MAX_RUNTIME_FLUSH_MINUTES = 24 * 60;
5
5
  export const DEFAULT_ESTIMATE_TDP_WATTS = 65;
@@ -14,7 +14,7 @@ export declare function validateExternalApiV0(value: unknown, path?: string): Co
14
14
  export declare function validateMeasurementProvenance(value: unknown, path?: string): ContractResult;
15
15
  /**
16
16
  * Validate a session_metadata fragment Node will upload.
17
- * Requires at least service_runtime_v0 or external_api_v0.
17
+ * Requires runtime resources, external APIs, or MCP observations.
18
18
  */
19
19
  export declare function validateRuntimeSessionMetadata(value: unknown): ContractResult;
20
20
  export type { ExternalApiV0, MeasurementProvenance, RuntimeSessionMetadata, ServiceRuntimeV0, };
@@ -202,7 +202,7 @@ export function validateMeasurementProvenance(value, path = 'measurement_provena
202
202
  }
203
203
  /**
204
204
  * Validate a session_metadata fragment Node will upload.
205
- * Requires at least service_runtime_v0 or external_api_v0.
205
+ * Requires runtime resources, external APIs, or MCP observations.
206
206
  */
207
207
  export function validateRuntimeSessionMetadata(value) {
208
208
  const issues = [];
@@ -211,8 +211,9 @@ export function validateRuntimeSessionMetadata(value) {
211
211
  }
212
212
  const hasRuntime = value.service_runtime_v0 !== undefined;
213
213
  const hasExternal = value.external_api_v0 !== undefined;
214
- if (!hasRuntime && !hasExternal) {
215
- issues.push(issue('session_metadata', 'expected service_runtime_v0 and/or external_api_v0'));
214
+ const hasMcp = value.mcp_tool_v0 !== undefined;
215
+ if (!hasRuntime && !hasExternal && !hasMcp) {
216
+ issues.push(issue('session_metadata', 'expected service_runtime_v0, external_api_v0, or mcp_tool_v0'));
216
217
  }
217
218
  if (hasRuntime) {
218
219
  issues.push(...validateServiceRuntimeV0(value.service_runtime_v0).issues);
@@ -220,6 +221,26 @@ export function validateRuntimeSessionMetadata(value) {
220
221
  if (hasExternal) {
221
222
  issues.push(...validateExternalApiV0(value.external_api_v0).issues);
222
223
  }
224
+ if (hasMcp) {
225
+ const mcp = value.mcp_tool_v0;
226
+ if (!isObject(mcp) || mcp.schema !== 'mcp_tool_v0' || !Array.isArray(mcp.calls) || !mcp.calls.length) {
227
+ issues.push(issue('mcp_tool_v0', 'expected MCP ledger with schema and non-empty calls'));
228
+ }
229
+ else {
230
+ mcp.calls.forEach((call, index) => {
231
+ const path = `mcp_tool_v0.calls[${index}]`;
232
+ if (!isObject(call)) {
233
+ issues.push(issue(path, 'expected object'));
234
+ return;
235
+ }
236
+ requireString(call, 'server', path, issues);
237
+ requireString(call, 'tool', path, issues);
238
+ requireNumber(call, 'duration_ms', path, issues, { nonNegative: true });
239
+ if (typeof call.success !== 'boolean')
240
+ issues.push(issue(`${path}.success`, 'expected boolean'));
241
+ });
242
+ }
243
+ }
223
244
  if (value.measurement_provenance !== undefined) {
224
245
  issues.push(...validateMeasurementProvenance(value.measurement_provenance).issues);
225
246
  }
@@ -5,8 +5,8 @@
5
5
  * Behavior depends primarily on lifecycle. Detection is best-effort;
6
6
  * ``NETGREENER_RUNTIME`` / ``init({ runtime })`` always wins.
7
7
  *
8
- * Does not rewrite the persistent collector pipeline. Ephemeral only
9
- * changes flush timing and prefers thin export when EXPORT_MODE is unset.
8
+ * Does not rewrite the persistent collector pipeline. Ephemeral bounds
9
+ * interval timers to active invocations and prefers thin export when unset.
10
10
  */
11
11
  import { type ServerlessPlatformSignal } from './serverlessHints.js';
12
12
  export type RuntimeModePreference = 'auto' | 'persistent' | 'ephemeral';
@@ -19,6 +19,8 @@ export type RuntimeCapabilities = {
19
19
  /** process.cpuUsage / RSS deltas on instrumented hooks. */
20
20
  process_cpu_time: boolean;
21
21
  periodic_flush: boolean;
22
+ /** Interval reporting while the host keeps an invocation active. */
23
+ active_invocation_flush?: boolean;
22
24
  local_durable_spool: boolean;
23
25
  };
24
26
  export type ResolvedRuntimeLifecycle = {
package/dist/lifecycle.js CHANGED
@@ -5,8 +5,8 @@
5
5
  * Behavior depends primarily on lifecycle. Detection is best-effort;
6
6
  * ``NETGREENER_RUNTIME`` / ``init({ runtime })`` always wins.
7
7
  *
8
- * Does not rewrite the persistent collector pipeline. Ephemeral only
9
- * changes flush timing and prefers thin export when EXPORT_MODE is unset.
8
+ * Does not rewrite the persistent collector pipeline. Ephemeral bounds
9
+ * interval timers to active invocations and prefers thin export when unset.
10
10
  */
11
11
  import { detectServerlessPlatformSignals, } from './serverlessHints.js';
12
12
  function readModePreference(env, override) {
@@ -46,6 +46,7 @@ function capabilitiesFor(lifecycle) {
46
46
  gpu_sampling: false,
47
47
  process_cpu_time: true,
48
48
  periodic_flush: false,
49
+ active_invocation_flush: true,
49
50
  local_durable_spool: false,
50
51
  };
51
52
  }
@@ -80,7 +81,7 @@ export function resolveLifecycle(opts = {}) {
80
81
  }
81
82
  else if (hint.detected) {
82
83
  lifecycle = 'ephemeral';
83
- notes.push('auto: serverless host signal → ephemeral lifecycle (invoke-end flush; no periodic timer)');
84
+ notes.push('auto: serverless host signal → ephemeral lifecycle (intervals while active; final partial window at invoke end)');
84
85
  }
85
86
  else {
86
87
  lifecycle = 'persistent';
@@ -95,7 +96,7 @@ export function resolveLifecycle(opts = {}) {
95
96
  notes.push(`container/platform signal: ${containerPlatform} (lifecycle remains ${lifecycle})`);
96
97
  }
97
98
  if (lifecycle === 'ephemeral') {
98
- notes.push('ephemeral: prefer NETGREENER_EXPORT_MODE=thin when unset; flush at invoke/request idle boundary');
99
+ notes.push('ephemeral: interval reporting only during active invocations; flush final partial window at invoke/request idle boundary');
99
100
  }
100
101
  return {
101
102
  mode,
package/dist/runtime.d.ts CHANGED
@@ -19,7 +19,7 @@ export type NetGreenerRuntimeOptions = {
19
19
  };
20
20
  /**
21
21
  * Process-wide runtime controller: record samples, periodic flush, shutdown flush.
22
- * Ephemeral lifecycle skips the periodic timer and flushes at invoke/request idle.
22
+ * Ephemeral timers run only during active invocations; idle flush sends the tail.
23
23
  */
24
24
  export declare class NetGreenerRuntime {
25
25
  readonly config: RuntimeConfig;
@@ -31,6 +31,8 @@ export declare class NetGreenerRuntime {
31
31
  private readonly exporter;
32
32
  private readonly onFlush?;
33
33
  private timer;
34
+ private stopControls?;
35
+ private readonly windowCheckpoints;
34
36
  private flushing;
35
37
  private started;
36
38
  private outboundInstalled;
@@ -46,9 +48,10 @@ export declare class NetGreenerRuntime {
46
48
  private ensureOutboundMeter;
47
49
  /** Prefer unwrapped fetch so telemetry uploads are never metered. */
48
50
  private uploadFetch;
51
+ private scheduleWindow;
49
52
  start(): void;
50
53
  /** Mark start of an inbound request/task (ephemeral idle-flush accounting). */
51
- beginRequest(): void;
54
+ beginRequest(checkpoint?: () => void): () => void;
52
55
  /**
53
56
  * Mark end of an inbound request/task. In ephemeral mode, schedules a flush
54
57
  * when no requests remain in flight (safe under concurrency).
@@ -84,6 +87,8 @@ export declare class NetGreenerRuntime {
84
87
  tenantId?: string | null;
85
88
  cpuTimeMs?: number;
86
89
  peakRssKb?: number;
90
+ completed?: boolean;
91
+ completionDurationMs?: number;
87
92
  }): void;
88
93
  private exportPendingWindow;
89
94
  flush(kind?: FlushKind): Promise<UploadResult | null>;
package/dist/runtime.js CHANGED
@@ -1,4 +1,4 @@
1
- import { meteringAllowed, startRuntimeControls } from './runtimeControls.js';
1
+ import { meteringAllowed, runtimeWindowIntervalMs, startRuntimeControls } from './runtimeControls.js';
2
2
  import { hostname } from 'node:os';
3
3
  import { ServiceRuntimeAggregator } from './aggregator.js';
4
4
  import { carbonFactorDict } from './carbonLedger.js';
@@ -35,7 +35,7 @@ function vercelDeploymentHosts() {
35
35
  }
36
36
  /**
37
37
  * Process-wide runtime controller: record samples, periodic flush, shutdown flush.
38
- * Ephemeral lifecycle skips the periodic timer and flushes at invoke/request idle.
38
+ * Ephemeral timers run only during active invocations; idle flush sends the tail.
39
39
  */
40
40
  export class NetGreenerRuntime {
41
41
  config;
@@ -47,6 +47,8 @@ export class NetGreenerRuntime {
47
47
  exporter;
48
48
  onFlush;
49
49
  timer = null;
50
+ stopControls;
51
+ windowCheckpoints = new Set();
50
52
  flushing = false;
51
53
  started = false;
52
54
  outboundInstalled = false;
@@ -103,6 +105,17 @@ export class NetGreenerRuntime {
103
105
  uploadFetch() {
104
106
  return getOriginalFetch() ?? this.fetchImpl;
105
107
  }
108
+ scheduleWindow(milliseconds) {
109
+ if (this.timer)
110
+ clearInterval(this.timer);
111
+ this.timer = null;
112
+ // Serverless timers exist only while an invocation is active. Never wait
113
+ // for this timer to deliver a short invocation's final partial window.
114
+ if (this.lifecycle === 'ephemeral' && this.inFlight === 0)
115
+ return;
116
+ this.timer = setInterval(() => { void this.flush('periodic'); }, milliseconds);
117
+ this.timer.unref?.();
118
+ }
106
119
  start() {
107
120
  if (this.started)
108
121
  return;
@@ -115,7 +128,7 @@ export class NetGreenerRuntime {
115
128
  pauseAt = Date.now();
116
129
  pauseCpu = process.cpuUsage();
117
130
  }
118
- startRuntimeControls(this.config, this.uploadFetch(), (enabled) => {
131
+ this.stopControls = startRuntimeControls(this.config, this.uploadFetch(), (enabled) => {
119
132
  if (!enabled) {
120
133
  pauseAt = Date.now();
121
134
  pauseCpu = process.cpuUsage();
@@ -127,7 +140,7 @@ export class NetGreenerRuntime {
127
140
  this.aggregator.excludePausedTime(Date.now() - pauseAt);
128
141
  pauseCpu = null;
129
142
  }
130
- });
143
+ }, milliseconds => this.scheduleWindow(milliseconds));
131
144
  markHooksActive({
132
145
  processKind: this.framework,
133
146
  exportMode: this.exporter.mode,
@@ -135,17 +148,25 @@ export class NetGreenerRuntime {
135
148
  noteExportMode(this.exporter.mode);
136
149
  this.ensureOutboundMeter();
137
150
  // Persistent path unchanged: periodic flush. Ephemeral must not depend on it.
138
- if (this.lifecycle === 'persistent' && this.lifecycleInfo.capabilities.periodic_flush) {
139
- this.timer = setInterval(() => {
140
- void this.flush('periodic');
141
- }, this.config.flushIntervalMs);
142
- // Do not keep the process alive solely for the timer.
143
- this.timer.unref?.();
144
- }
151
+ this.scheduleWindow(runtimeWindowIntervalMs(this.config));
145
152
  }
146
153
  /** Mark start of an inbound request/task (ephemeral idle-flush accounting). */
147
- beginRequest() {
154
+ beginRequest(checkpoint) {
155
+ if (checkpoint)
156
+ this.windowCheckpoints.add(checkpoint);
157
+ if (this.lifecycle === 'ephemeral' && this.inFlight === 0 && !this.pendingPayload &&
158
+ !this.aggregator.hasData() && !getExternalAggregator().hasData() && !getMcpToolLedger().hasCalls()) {
159
+ // A reused serverless instance may have been suspended for hours. Start
160
+ // the new invocation's resource window here rather than including idle time.
161
+ this.aggregator.resetWindow();
162
+ this.cpuWindowMark = beginProcessResourceSample();
163
+ getOccupancyTracker().takeWindowSnapshot();
164
+ }
148
165
  this.inFlight += 1;
166
+ if (this.lifecycle === 'ephemeral' && this.inFlight === 1)
167
+ this.scheduleWindow(runtimeWindowIntervalMs(this.config));
168
+ return () => { if (checkpoint)
169
+ this.windowCheckpoints.delete(checkpoint); };
149
170
  }
150
171
  /**
151
172
  * Mark end of an inbound request/task. In ephemeral mode, schedules a flush
@@ -160,6 +181,10 @@ export class NetGreenerRuntime {
160
181
  this.inFlight -= 1;
161
182
  if (this.lifecycle !== 'ephemeral')
162
183
  return;
184
+ if (this.inFlight === 0 && this.timer) {
185
+ clearInterval(this.timer);
186
+ this.timer = null;
187
+ }
163
188
  if (opts?.deferInvokeFlush)
164
189
  return;
165
190
  if (this.invokeFlushScheduled)
@@ -181,6 +206,8 @@ export class NetGreenerRuntime {
181
206
  return this.inFlight;
182
207
  }
183
208
  stop() {
209
+ this.stopControls?.();
210
+ this.stopControls = undefined;
184
211
  if (this.timer) {
185
212
  clearInterval(this.timer);
186
213
  this.timer = null;
@@ -218,6 +245,8 @@ export class NetGreenerRuntime {
218
245
  this.aggregator.record({
219
246
  serviceUnit: sample.serviceUnit,
220
247
  unitType: 'task',
248
+ completed: sample.completed,
249
+ completionDurationMs: sample.completionDurationMs,
221
250
  durationMs: sample.durationMs,
222
251
  error: Boolean(sample.error),
223
252
  tenantId: sample.tenantId ?? getTenantContext()?.tenantId ?? null,
@@ -264,20 +293,32 @@ export class NetGreenerRuntime {
264
293
  }
265
294
  }
266
295
  const externalAgg = getExternalAggregator();
296
+ const mcpLedger = getMcpToolLedger();
297
+ for (const checkpoint of this.windowCheckpoints) {
298
+ try {
299
+ checkpoint();
300
+ }
301
+ catch { /* Telemetry must not interrupt customer work. */ }
302
+ }
303
+ if (((this.started && this.lifecycle === 'persistent' && kind !== 'manual') || this.inFlight > 0) && !this.aggregator.hasData()) {
304
+ this.aggregator.record({ serviceUnit: 'Process resources', unitType: 'process', completed: false,
305
+ durationMs: Math.max(0.001, Date.now() - this.aggregator.windowStartedMs()),
306
+ peakRssKb: endProcessResourceSample(this.cpuWindowMark).rssKb });
307
+ }
267
308
  const hasRuntime = this.aggregator.hasData();
268
309
  const hasExternal = externalAgg.hasData();
269
- if (!hasRuntime && !hasExternal)
310
+ if (!hasRuntime && !hasExternal && !mcpLedger.hasCalls())
270
311
  return null;
271
312
  this.flushing = true;
272
313
  let mcpSnapshot = null;
273
314
  noteExportMode(this.exporter.mode);
315
+ const windowStartedMs = this.aggregator.windowStartedMs();
274
316
  const snapshot = hasRuntime ? this.aggregator.takeSnapshot() : null;
317
+ if (!hasRuntime)
318
+ this.aggregator.resetWindow();
275
319
  const externalSnapshot = hasExternal ? externalAgg.takeSnapshot() : null;
276
320
  const previousCpuMark = this.cpuWindowMark;
277
321
  try {
278
- const windowStartedMs = snapshot
279
- ? snapshot.windowStartedMs()
280
- : Date.now() - 1000;
281
322
  const windowSeconds = Math.max(0.001, (Date.now() - windowStartedMs) / 1000);
282
323
  const windowCpuSeconds = endProcessResourceSample(this.cpuWindowMark).cpuTimeMs / 1000;
283
324
  this.cpuWindowMark = beginProcessResourceSample();
@@ -309,7 +350,6 @@ export class NetGreenerRuntime {
309
350
  return null;
310
351
  }
311
352
  const externalV0 = externalSnapshot ? externalSnapshot.buildV0() : null;
312
- const mcpLedger = getMcpToolLedger();
313
353
  mcpSnapshot = mcpLedger.hasCalls() ? mcpLedger.takeSnapshot() : null;
314
354
  const mcpV0 = mcpSnapshot ? mcpSnapshot.buildV0() : null;
315
355
  if (mcpSnapshot && !mcpV0) {
@@ -325,6 +365,8 @@ export class NetGreenerRuntime {
325
365
  const runContext = {
326
366
  client: 'netgreener_node_runtime',
327
367
  runtime_flush_kind: kind,
368
+ reporting_interval_seconds: runtimeWindowIntervalMs(this.config) / 1000,
369
+ reporting_window_kind: kind === 'periodic' ? 'interval' : 'partial',
328
370
  measured_scope: 'process',
329
371
  resource_scope: 'process',
330
372
  runtime_lifecycle: this.lifecycleInfo.lifecycle,
@@ -1,5 +1,6 @@
1
1
  import type { RuntimeConfig } from './config.js';
2
2
  export declare function meteringAllowed(config?: RuntimeConfig): boolean;
3
+ export declare function runtimeWindowIntervalMs(config: RuntimeConfig): number;
3
4
  export declare function applyRuntimeControls(config: RuntimeConfig, enabled: boolean, orgId?: number): void;
4
5
  export declare function refreshRuntimeControls(config: RuntimeConfig, fetchImpl: typeof fetch): Promise<void>;
5
- export declare function startRuntimeControls(config: RuntimeConfig, fetchImpl: typeof fetch, onChange?: (enabled: boolean) => void): void;
6
+ export declare function startRuntimeControls(config: RuntimeConfig, fetchImpl: typeof fetch, onChange?: (enabled: boolean) => void, onIntervalChange?: (milliseconds: number) => void): () => void;
@@ -12,7 +12,7 @@ function stateFor(config) {
12
12
  if (!state) {
13
13
  const claim = jwtPayloadUnverified(`Bearer ${config.token}`)?.org_id;
14
14
  const id = config.organizationId ?? Number(claim);
15
- state = { enabled: true, orgId: Number.isSafeInteger(id) && Number(id) > 0 ? Number(id) : null, refreshing: false, listeners: new Set() };
15
+ state = { enabled: true, orgId: Number.isSafeInteger(id) && Number(id) > 0 ? Number(id) : null, refreshing: false, listeners: new Set(), windowSeconds: null, intervalListeners: new Set() };
16
16
  states.set(key, state);
17
17
  }
18
18
  return state;
@@ -20,6 +20,10 @@ function stateFor(config) {
20
20
  export function meteringAllowed(config) {
21
21
  return (config ? stateFor(config) : activeKey ? states.get(activeKey) : undefined)?.enabled ?? true;
22
22
  }
23
+ export function runtimeWindowIntervalMs(config) {
24
+ const seconds = stateFor(config).windowSeconds;
25
+ return seconds == null ? config.flushIntervalMs : seconds * 1000;
26
+ }
23
27
  export function applyRuntimeControls(config, enabled, orgId) {
24
28
  const state = stateFor(config);
25
29
  if (orgId != null && Number.isSafeInteger(orgId) && orgId > 0)
@@ -46,6 +50,14 @@ export async function refreshRuntimeControls(config, fetchImpl) {
46
50
  const data = await response.json();
47
51
  if (data.org_id === state.orgId && typeof data.metering_enabled === 'boolean') {
48
52
  applyRuntimeControls(config, data.metering_enabled);
53
+ const seconds = data.effective_runtime_window_seconds ?? data.runtime_window_seconds;
54
+ if (seconds === null || (typeof seconds === 'number' && Number.isInteger(seconds) && seconds >= 30 && seconds <= 86400)) {
55
+ if (state.windowSeconds !== seconds) {
56
+ state.windowSeconds = seconds;
57
+ for (const listener of state.intervalListeners)
58
+ listener();
59
+ }
60
+ }
49
61
  }
50
62
  }
51
63
  catch {
@@ -55,15 +67,24 @@ export async function refreshRuntimeControls(config, fetchImpl) {
55
67
  state.refreshing = false;
56
68
  }
57
69
  }
58
- export function startRuntimeControls(config, fetchImpl, onChange) {
70
+ export function startRuntimeControls(config, fetchImpl, onChange, onIntervalChange) {
59
71
  if (config.dryRun || !config.enabled)
60
- return;
72
+ return () => { };
61
73
  activeKey = accountKey(config);
62
74
  const state = stateFor(config);
63
75
  if (onChange)
64
76
  state.listeners.add(onChange);
65
- if (state.timer)
66
- return;
67
- state.timer = setInterval(() => { void refreshRuntimeControls(config, fetchImpl); }, 30_000);
68
- state.timer.unref?.();
77
+ const intervalListener = onIntervalChange ? () => onIntervalChange(runtimeWindowIntervalMs(config)) : undefined;
78
+ if (intervalListener)
79
+ state.intervalListeners.add(intervalListener);
80
+ if (!state.timer) {
81
+ state.timer = setInterval(() => { void refreshRuntimeControls(config, fetchImpl); }, 30_000);
82
+ state.timer.unref?.();
83
+ }
84
+ return () => {
85
+ if (onChange)
86
+ state.listeners.delete(onChange);
87
+ if (intervalListener)
88
+ state.intervalListeners.delete(intervalListener);
89
+ };
69
90
  }
@@ -122,6 +122,8 @@ export declare class NetGreenerClient {
122
122
  format?: string;
123
123
  }): Promise<Record<string, unknown>>;
124
124
  quoteCredits(orgId: number, payload: Record<string, unknown>): Promise<Record<string, unknown>>;
125
+ /** Debit a server-priced quantity; reuse operation_id for retries of the same work. */
126
+ debitOrgCredits(orgId: number, payload: Record<string, unknown>): Promise<Record<string, unknown>>;
125
127
  estimateRun(payload: Record<string, unknown>): Promise<Record<string, unknown>>;
126
128
  estimateProject(projectId: number, payload: Record<string, unknown>): Promise<Record<string, unknown>>;
127
129
  getRunEstimate(runId: number): Promise<Record<string, unknown>>;
@@ -285,6 +285,10 @@ export class NetGreenerClient {
285
285
  async quoteCredits(orgId, payload) {
286
286
  return this.request('POST', `/billing/organizations/${orgId}/credit-quote`, payload);
287
287
  }
288
+ /** Debit a server-priced quantity; reuse operation_id for retries of the same work. */
289
+ async debitOrgCredits(orgId, payload) {
290
+ return this.request('POST', `/billing/organizations/${orgId}/credit-debit`, payload);
291
+ }
288
292
  async estimateRun(payload) {
289
293
  return this.request('POST', '/runs/estimate', payload);
290
294
  }
package/dist/taskMeter.js CHANGED
@@ -11,23 +11,35 @@ export function recordMeteredTask(runtime, sample) {
11
11
  if (!runtime.enabled) {
12
12
  return sample.fn();
13
13
  }
14
- const started = performance.now();
15
- const resourceMark = beginProcessResourceSample();
14
+ const lifetimeStarted = performance.now();
15
+ let started = lifetimeStarted;
16
+ let resourceMark = beginProcessResourceSample();
16
17
  const taskId = String(sample.taskId || '').trim() || randomUUID();
17
18
  getOccupancyTracker().begin(taskId);
18
19
  let error = false;
19
- runtime.beginRequest();
20
- const finalize = () => {
20
+ const checkpoint = (completed = false) => {
21
21
  const resources = endProcessResourceSample(resourceMark);
22
22
  getOccupancyTracker().end(taskId, sample.serviceUnit);
23
+ const now = performance.now();
23
24
  runtime.recordTask({
24
25
  serviceUnit: sample.serviceUnit,
25
- durationMs: performance.now() - started,
26
+ durationMs: now - started,
27
+ completed,
28
+ ...(completed ? { completionDurationMs: now - lifetimeStarted } : {}),
26
29
  error,
27
30
  tenantId: sample.tenantId,
28
31
  cpuTimeMs: resources.cpuTimeMs,
29
32
  peakRssKb: resources.rssKb,
30
33
  });
34
+ started = now;
35
+ resourceMark = beginProcessResourceSample();
36
+ if (!completed)
37
+ getOccupancyTracker().begin(taskId);
38
+ };
39
+ const unregister = runtime.beginRequest(() => checkpoint());
40
+ const finalize = () => {
41
+ unregister();
42
+ checkpoint(true);
31
43
  runtime.endRequest();
32
44
  };
33
45
  try {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@netgreener/runtime",
3
- "version": "0.1.14",
3
+ "version": "0.1.15",
4
4
  "description": "NetGreener Node.js Runtime — Express/Fastify/Nest/Next/process adapter uploading RunSessions to api_server.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",