@netgreener/runtime 0.1.13 → 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/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
  }
@@ -23,6 +23,30 @@ type ProjectRow = Record<string, unknown> & {
23
23
  directory?: string;
24
24
  git_url?: string | null;
25
25
  };
26
+ export type ExternalApiGateBudgets = {
27
+ max_total_tokens?: number;
28
+ max_input_tokens?: number;
29
+ max_output_tokens?: number;
30
+ max_external_api_calls?: number;
31
+ max_external_cost_usd?: number;
32
+ external_provider?: string;
33
+ };
34
+ export type ExternalApiGateEvaluation = {
35
+ gate_version: number;
36
+ passed: boolean;
37
+ exit_code: number;
38
+ run_id: number;
39
+ project_id: number;
40
+ current: Record<string, unknown>;
41
+ checks: Array<{
42
+ name: string;
43
+ limit: number | null;
44
+ actual: number | null;
45
+ passed: boolean;
46
+ detail: string;
47
+ }>;
48
+ warnings: string[];
49
+ };
26
50
  export declare class NetGreenerClient {
27
51
  baseUrl: string;
28
52
  private token;
@@ -48,6 +72,7 @@ export declare class NetGreenerClient {
48
72
  login(email: string, password: string): Promise<Record<string, unknown>>;
49
73
  getMe(): Promise<Record<string, unknown>>;
50
74
  postRunSession(payload: Record<string, unknown>): Promise<Record<string, unknown>>;
75
+ evaluateExternalApiGate(runId: number, budgets: ExternalApiGateBudgets): Promise<ExternalApiGateEvaluation>;
51
76
  getRunSession(runId: number): Promise<Record<string, unknown>>;
52
77
  getRunOutcome(runId: number): Promise<Record<string, unknown>>;
53
78
  attachRunOutcome(runId: number, payload: Record<string, unknown>): Promise<Record<string, unknown>>;
@@ -97,6 +122,8 @@ export declare class NetGreenerClient {
97
122
  format?: string;
98
123
  }): Promise<Record<string, unknown>>;
99
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>>;
100
127
  estimateRun(payload: Record<string, unknown>): Promise<Record<string, unknown>>;
101
128
  estimateProject(projectId: number, payload: Record<string, unknown>): Promise<Record<string, unknown>>;
102
129
  getRunEstimate(runId: number): Promise<Record<string, unknown>>;
@@ -123,6 +123,9 @@ export class NetGreenerClient {
123
123
  async postRunSession(payload) {
124
124
  return this.request('POST', '/runsessions/', payload);
125
125
  }
126
+ async evaluateExternalApiGate(runId, budgets) {
127
+ return this.request('POST', `/runsessions/${runId}/external-gate`, budgets);
128
+ }
126
129
  async getRunSession(runId) {
127
130
  return this.request('GET', `/runsessions/${runId}`);
128
131
  }
@@ -282,6 +285,10 @@ export class NetGreenerClient {
282
285
  async quoteCredits(orgId, payload) {
283
286
  return this.request('POST', `/billing/organizations/${orgId}/credit-quote`, payload);
284
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
+ }
285
292
  async estimateRun(payload) {
286
293
  return this.request('POST', '/runs/estimate', payload);
287
294
  }
@@ -3,3 +3,4 @@
3
3
  */
4
4
  export { ApiError, NetGreenerClient, type NetGreenerSdkOptions } from './client.js';
5
5
  export { normalizeGitUrl } from './gitUrl.js';
6
+ export type { ExternalApiGateBudgets, ExternalApiGateEvaluation } from './client.js';
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/dist/types.d.ts CHANGED
@@ -104,6 +104,10 @@ export type ExternalApiTenantBucket = {
104
104
  calls: number;
105
105
  errors: number;
106
106
  providers: ExternalApiProvider[];
107
+ by_service_unit?: Record<string, {
108
+ service_unit: string;
109
+ providers: ExternalApiProvider[];
110
+ }>;
107
111
  };
108
112
  export type ExternalApiV0 = {
109
113
  collector: string;