Generation Telemetry

videoclaw records generation telemetry as project events. The goal is simple: every provider submission and poll should leave enough machine-readable evidence to answer what route ran, how many tasks were sent, what it cost when the provider reports cost, how long it took, and how many outputs were ingested.

Where it is recorded

Telemetry is appended to the existing event ledger:

projects/<slug>/events/events.jsonl

Each record uses event type:

generation.telemetry.recorded

The payload schema is versioned with schemaVersion: 1.

What is captured

Each telemetry payload can include:

1. projectSlug, routeId, operationKind, status, and dryRun
2. taskCount and sceneIndices
3. execution config such as aspect ratio, resolution, audio flag, output count, average duration, prompt word count, and reference counts
4. externalJobId when live submission or polling exposes one
5. outputsIngested after polling
6. provider-reported cost fields: usd and/or creditsCharged
7. generationTimeSec when provider output exposes it
8. issues for blocked, failed, or warning-bearing runs

Dry-runs are recorded as telemetry, but they are not used as historical cost samples.

Cost-estimate integration

vclaw video cost-estimate still uses the static Seedance defaults when there is no historical provider-reported USD data.

When completed seedance-direct telemetry exists with both cost.usd and taskCount, project estimates can switch to:

{
  "estimateSource": "historical-telemetry",
  "telemetry": {
    "sampleCount": 1,
    "matchedRouteId": "seedance-direct",
    "averageSeedancePerSceneUsd": 0.5,
    "lastRecordedAt": "2026-05-03T12:00:00.000Z"
  }
}

Credits are recorded but not converted to USD. Do not add a conversion unless the route has an explicit, verified conversion contract.

Operator guidance

Use telemetry to tune estimates and investigate provider behavior, not to replace the execution report. The execution report remains the canonical artifact for the latest execution state; telemetry is the longitudinal ledger for submissions, polls, costs, durations, and failures.

Public helpers

The package exports helpers for integration code:

1. appendGenerationTelemetry
2. readProjectGenerationTelemetry
3. readPortfolioGenerationTelemetry
4. buildGenerationTelemetryFromReport
5. buildGenerationTelemetryFromPoll
6. findHistoricalSeedanceCostTelemetry
7. extractProviderMetrics