feat: add maxInvocationHistory cap and O(1) totalDuration/averageCycleTime

[kdn-posipaka]

Summary

Implements the feature requested in #785: bounded invocation history to prevent unbounded memory growth in long-lived agents.

Changes

Meter class (src/telemetry/meter.ts)

• Added MeterConfig with optional maxInvocationHistory (default: Infinity) and onInvocationHistoryFlush callback
• startNewInvocation() now evicts oldest entries when the cap is exceeded
• Flush callback is fire-and-forget; errors are caught and never propagate
• Added _totalCycleDurationMs and _totalCycleCount scalars accumulated in endCycle() — these survive eviction

AgentMetrics class

• totalDuration now O(1) via lifetime scalar (was O(N) scan of all invocations)
• averageCycleTime now O(1) via lifetime scalar (was O(N) scan)
• Both fall back to array scan when constructed without scalars (backward compat)
• toJSON() includes totalCycleDurationMs and totalCycleCount for roundtrip

AgentConfig (src/agent/agent.ts)

• Added maxInvocationHistory?: number — passed through to Meter
• Added onInvocationHistoryFlush? — passed through to Meter

Tests

• All 48 existing tests pass (2 updated for new toJSON fields)
• 5 new tests for bounded history: eviction, flush callback, lifetime metrics after eviction, default unbounded, error swallowing
• Total: 53 tests passing

Usage

const agent = new Agent({
  model,
  maxInvocationHistory: 500,
  onInvocationHistoryFlush: async (evicted) => {
    await metricsDb.bulkInsert(evicted);
  },
});

Fully backward-compatible — both options default to preserving current behavior.

Closes #785

[strands-agent]

This repository has been merged into the strands-agents/harness-sdk monorepo and will be archived shortly. All new development happens there.

If this PR is still relevant, please recreate it against the monorepo. The code now lives under strands-ts/. Full commit history was preserved, so your base should be findable.

Apologies for the disruption, and thank you for contributing!