@nodetool-ai/agents 0.7.0-rc.23 → 0.8.1

package/README.md

@@ -0,0 +1,35 @@
+# @nodetool-ai/agents
+
+The planning agent system: `TaskPlanner` → `ParallelTaskExecutor` →
+`TaskExecutor` → `CodeActExecutor`, plus skills and agent capabilities.
+
+## Responsibilities
+
+- Decompose an objective into a DAG of tasks/steps and execute them (parallel
+  where dependencies allow).
+- Tool integration and progressive-disclosure memory tools (`list_shared`,
+  `read_shared`, `share_result`).
+
+## Usage
+
+```ts
+import { createChatCodeActSession } from "@nodetool-ai/agents";
+
+const session = createChatCodeActSession({
+  tools: belt,                        // ToolSignatureSource[]
+  executeTool: (call) => router(call), // the gated tool router
+  signal: abortController.signal
+});
+// `session.systemPrompt` goes in the system message; `session.tools` are what
+// the provider is offered. Run them through the host's own generateLoop.
+```
+
+## Develop
+
+```bash
+npm run build --workspace=packages/agents
+npm run test  --workspace=packages/agents
+npm run lint  --workspace=packages/agents
+```
+
+Architecture, parallel execution, skills, and tuning: [packages/agents/AGENTS.md](./AGENTS.md).

package/dist/.nodetool-build-stamp

@@ -0,0 +1 @@
+2026-09-28T09:19:14.863Z

package/dist/analysis/audio-dsp.d.ts

@@ -0,0 +1,223 @@
+/**
+ * Audio analysis math — pure functions over PCM, no I/O and no media library.
+ *
+ * Everything here takes samples and returns numbers, so a test can synthesize
+ * a signal whose answer is known analytically (a 1 kHz sine's centroid is
+ * 1 kHz, a -20 dBFS tone integrates to a loudness the ITU spec pins) and check
+ * the implementation against it. Decoding lives in `media-decode.ts`; the
+ * capability that calls both lives in `capabilities/analysis.ts`.
+ *
+ * Loudness follows ITU-R BS.1770-4 (K-weighting, 400 ms gated blocks) and EBU
+ * Tech 3342 for the loudness range, which is what every broadcast and
+ * streaming target is specified in. dBFS peak/RMS is kept alongside it because
+ * clipping and headroom are peak questions, not loudness questions.
+ */
+/** Amplitude floor reported instead of -Infinity for digital silence. */
+export declare const SILENT_DB = -120;
+/** Interleaved PCM plus the format needed to interpret it. */
+export interface PcmAudio {
+    readonly samples: Float32Array;
+    readonly sampleRate: number;
+    readonly channels: number;
+}
+/** dBFS for a linear amplitude, floored so silence is a number. */
+export declare function amplitudeToDb(amplitude: number): number;
+/** Round to `digits` decimals, keeping JSON payloads readable. */
+export declare function round(value: number, digits?: number): number;
+/** Downmix interleaved PCM to one channel by averaging. */
+export declare function toMono(samples: Float32Array, channels: number): Float32Array;
+/** Split interleaved PCM into one array per channel. */
+export declare function toPlanar(samples: Float32Array, channels: number): Float32Array[];
+/** One window of the energy envelope: where the level is at a point in time. */
+export interface EnergyFrame {
+    /** Window start, in seconds from the beginning of the audio. */
+    readonly time: number;
+    readonly rms: number;
+    readonly peak: number;
+}
+/**
+ * The level envelope: RMS and peak per analysis window.
+ *
+ * This is the "where is the energy" answer — a caller reads it as a series, or
+ * derives silence, onsets and dynamics from it. Windows are laid out from the
+ * start at `hop` intervals; the last partial window is kept so a short clip
+ * still reports something.
+ */
+export declare function energyFrames(mono: Float32Array, sampleRate: number, frameSamples: number, hopSamples: number): EnergyFrame[];
+/** Whole-signal level, clipping and DC offset — the headroom questions. */
+export interface PeakSummary {
+    readonly peak: number;
+    readonly rms: number;
+    readonly dcOffset: number;
+    readonly clippedSamples: number;
+    readonly crestFactorDb: number;
+}
+/**
+ * Peak, RMS, DC offset and clipping over the whole signal.
+ *
+ * "Clipped" is a sample at or past `clipThreshold` (0.999 by default, not 1.0):
+ * a decoder's rounding puts a genuinely clipped sample a hair under full scale,
+ * so an exact-1.0 test reports zero on audio that is visibly squared off.
+ */
+export declare function peakSummary(mono: Float32Array, clipThreshold?: number): PeakSummary;
+/** Largest power of two at or below `value`, at least 2. */
+export declare function floorPowerOfTwo(value: number): number;
+/** A periodic Hann window of length `size`. */
+export declare function hannWindow(size: number): Float32Array;
+/**
+ * In-place radix-2 Cooley-Tukey FFT. `re`/`im` must have the same
+ * power-of-two length; the transform overwrites both.
+ */
+export declare function fftInPlace(re: Float32Array, im: Float32Array): void;
+/**
+ * The magnitude spectrum of one windowed frame — bins 0..size/2 inclusive.
+ *
+ * `signal` is read from `offset`; a frame that runs past the end is
+ * zero-padded, which is what makes the last window of a clip analysable.
+ */
+export declare function magnitudeSpectrum(signal: Float32Array, offset: number, window: Float32Array): Float32Array;
+/** What one spectrum says about the sound's colour. */
+export interface SpectralFeatures {
+    /** Energy-weighted mean frequency — "brightness". */
+    readonly centroidHz: number;
+    /** Frequency below which `rolloffFraction` of the energy sits. */
+    readonly rolloffHz: number;
+    /** Geometric over arithmetic mean: 0 is tonal, 1 is noise-like. */
+    readonly flatness: number;
+    /** Energy-weighted spread around the centroid. */
+    readonly bandwidthHz: number;
+    /** The loudest bin's frequency. */
+    readonly peakHz: number;
+    /** Total magnitude in the frame, for weighting averages. */
+    readonly energy: number;
+}
+/** Centroid, rolloff, flatness, bandwidth and peak bin of one spectrum. */
+export declare function spectralFeatures(magnitude: Float32Array, sampleRate: number, fftSize: number, rolloffFraction?: number): SpectralFeatures;
+/** One band of the octave split, and the energy in it. */
+export interface FrequencyBand {
+    readonly name: string;
+    readonly lowHz: number;
+    readonly highHz: number;
+}
+/**
+ * Ten octave bands from sub-bass to air, named the way a mix engineer names
+ * them. The upper edge of `air` is open — `bandEnergies` clamps it to Nyquist.
+ */
+export declare const OCTAVE_BANDS: readonly FrequencyBand[];
+/** Summed magnitude per octave band, and that band's share of the total. */
+export declare function bandEnergies(magnitude: Float32Array, sampleRate: number, fftSize: number): {
+    band: FrequencyBand;
+    energy: number;
+}[];
+interface BiquadCoefficients {
+    readonly b0: number;
+    readonly b1: number;
+    readonly b2: number;
+    readonly a1: number;
+    readonly a2: number;
+}
+/** Apply a normalized biquad (a0 == 1) to a signal, returning a new array. */
+export declare function applyBiquad(signal: Float32Array, { b0, b1, b2, a1, a2 }: BiquadCoefficients): Float32Array;
+/**
+ * The two K-weighting stages of BS.1770 at an arbitrary sample rate.
+ *
+ * The spec tabulates coefficients for 48 kHz only. These are the analog
+ * prototype's parameters (a +4 dB high shelf at 1681.97 Hz and an RLB high-pass
+ * at 38.14 Hz) run through the bilinear transform at `sampleRate`, so a 44.1 kHz
+ * or 96 kHz file is weighted correctly instead of being measured through a
+ * filter designed for a different rate.
+ */
+export declare function kWeightingFilters(sampleRate: number): [BiquadCoefficients, BiquadCoefficients];
+/** Everything the loudness pass reports. */
+export interface LoudnessResult {
+    /** Gated programme loudness over the whole signal, in LUFS. */
+    readonly integratedLufs: number;
+    /** EBU Tech 3342 loudness range, in LU. */
+    readonly loudnessRangeLu: number;
+    /** Loudest 400 ms block, in LUFS. */
+    readonly momentaryMaxLufs: number;
+    /** Loudest 3 s block, in LUFS. */
+    readonly shortTermMaxLufs: number;
+    /** Per-block momentary loudness, `{time, lufs}` at 100 ms hops. */
+    readonly momentary: {
+        time: number;
+        lufs: number;
+    }[];
+}
+/**
+ * Gated loudness per ITU-R BS.1770-4, with the EBU Tech 3342 loudness range.
+ *
+ * Momentary blocks are 400 ms at a 100 ms hop and short-term blocks are 3 s at
+ * the same hop. Integration applies the absolute gate at -70 LUFS and then the
+ * relative gate 10 LU below the absolutely-gated mean; the loudness range gates
+ * at -70 LUFS and 20 LU and reports the 10th-to-95th percentile spread.
+ *
+ * A signal shorter than one 400 ms block has no gated loudness to report and
+ * comes back as -Infinity, which the caller renders as null rather than as a
+ * number nobody measured.
+ */
+export declare function measureLoudness(planar: readonly Float32Array[], sampleRate: number): LoudnessResult;
+/**
+ * Half-wave rectified spectral flux between two frames, normalized by the
+ * current frame's total magnitude.
+ *
+ * The normalization is what makes the number mean something. Raw flux scales
+ * with how loud the passage is, so one threshold cannot serve a quiet verse
+ * and a loud chorus. Worse, a *stationary* tone does not produce zero raw
+ * flux: at a hop that is not a whole number of cycles the sinusoid's leakage
+ * pattern shifts between frames, so its bin magnitudes wobble by a few percent
+ * forever. Measured against the frame's own magnitude that wobble is ~0.02 and
+ * a real onset is a large fraction of 1, which is a difference a threshold can
+ * act on. Against raw flux the two are indistinguishable, and a held note
+ * reads as a stream of onsets at a confident tempo.
+ */
+export declare function spectralFlux(magnitude: Float32Array, previous: Float32Array): number;
+/** A stretch of the timeline classified as silent or as sound. */
+export interface AudioSegment {
+    readonly start: number;
+    readonly end: number;
+    readonly duration: number;
+}
+/**
+ * Runs where the envelope stays under `thresholdDb`, at least
+ * `minDurationSeconds` long.
+ *
+ * `frameDuration` is how much time one envelope frame covers, so a run that
+ * ends at the last frame is reported through to the end of that frame rather
+ * than to its start.
+ */
+export declare function silenceSegments(frames: readonly EnergyFrame[], thresholdDb: number, minDurationSeconds: number, frameDuration: number): AudioSegment[];
+/** The gaps between silences: everything that is not silent. */
+export declare function invertSegments(segments: readonly AudioSegment[], duration: number): AudioSegment[];
+/**
+ * Onset times from a normalized spectral-flux novelty curve.
+ *
+ * A peak is an onset when it is a local maximum, clears an adaptive threshold
+ * (the local mean plus `sensitivity` local standard deviations), and clears
+ * `minStrength` outright. Both halves are needed. The adaptive half handles
+ * dynamics — a fixed threshold finds every hit in a loud passage and none in a
+ * quiet one. The absolute half handles the opposite failure: where the curve
+ * is essentially flat the local standard deviation collapses, every ripple
+ * clears mean + 1.5σ, and a held note reports dozens of onsets. `minStrength`
+ * is in the units {@link spectralFlux} returns — a fraction of the frame's own
+ * magnitude — so 0.04 means "at least 4% of this frame's energy is new".
+ */
+export declare function detectOnsets(flux: readonly number[], times: readonly number[], sensitivity?: number, windowFrames?: number, minGapSeconds?: number, minStrength?: number): number[];
+/** A tempo estimate, and how strongly the novelty curve supports it. */
+export interface TempoEstimate {
+    readonly bpm: number;
+    /** Normalized autocorrelation at the winning lag, 0..1. */
+    readonly confidence: number;
+}
+/**
+ * Tempo from the autocorrelation of the novelty curve.
+ *
+ * Only lags inside `minBpm`..`maxBpm` are considered, so the classic
+ * half/double-time ambiguity is bounded rather than unbounded. Confidence is
+ * the autocorrelation at the winning lag over the curve's own energy; a
+ * non-rhythmic signal scores near zero, and the caller is expected to say so
+ * instead of printing a BPM for speech.
+ */
+export declare function estimateTempo(novelty: readonly number[], hopSeconds: number, minBpm?: number, maxBpm?: number): TempoEstimate;
+export {};
+//# sourceMappingURL=audio-dsp.d.ts.map

package/dist/analysis/audio-dsp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-dsp.d.ts","sourceRoot":"","sources":["../../src/analysis/audio-dsp.ts"],"names":[],"mappings":"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"}