@zaip-ai/cli 2.0.0 → 2.6.0

package/templates/.agents/dashboard/packages/local-runtime/src/sqlite-materialize-runs.ts

@@ -0,0 +1,600 @@
+import { createHash } from "node:crypto";
+import type { DatabaseSync } from "node:sqlite";
+import { pricingCatalogSchema, resolveHistoricalDeveloperAttribution } from "@zaip-ai/costs";
+import {
+  foldRunV2Records,
+  parseRunV2JsonLines,
+  type RunV2Fold,
+} from "../../../../../packages/decisions/src/index.js";
+import {
+  affectedTemporalIntervals,
+  type SqliteParsedSourceCache,
+} from "./sqlite-incremental-cache.js";
+import {
+  activityKind,
+  aggregateCost,
+  allocateAttributedTokenActiveMs,
+  type CanonicalEntity,
+  canonicalProvider,
+  consolidatedValue,
+  knownSum,
+  latestFxRate,
+  readAgentProfiles,
+  recordValue,
+  resolveDurations,
+  saoPauloDay,
+  type TemporalInterval,
+  usagePricingAudit,
+} from "./sqlite-read-model-canonical.js";
+export interface RunMaterializationInput {
+  database: DatabaseSync;
+  previousActivities: Array<Record<string, any>>;
+  parsedSources: SqliteParsedSourceCache;
+  refresh: { canonical_runs_refolded: number };
+  hasPersistentSchema: boolean;
+  dirtyRunIds: Set<string>;
+  changedSources: Set<string>;
+  oldIntervals: TemporalInterval[];
+  canonicalEntities: Map<string, CanonicalEntity>;
+  entityChanged: boolean;
+}
+export function materializeCanonicalRuns(input: RunMaterializationInput) {
+  const {
+    database,
+    previousActivities,
+    parsedSources,
+    refresh,
+    hasPersistentSchema,
+    dirtyRunIds,
+    changedSources,
+    oldIntervals,
+    canonicalEntities,
+    entityChanged,
+  } = input;
+  const catalogContent = (
+    database
+      .prepare("SELECT content FROM files WHERE path = ?")
+      .get(".agents/config/agents/catalog.yaml") as { content?: string } | undefined
+  )?.content;
+  const clientProfilesContent = (
+    database
+      .prepare("SELECT content FROM files WHERE path = ?")
+      .get(".agents/config/clients.yaml") as { content?: string } | undefined
+  )?.content;
+  const agentProfiles = readAgentProfiles(catalogContent, clientProfilesContent);
+  const catalogHash =
+    catalogContent === undefined ? null : createHash("sha256").update(catalogContent).digest("hex");
+  const pricingContent = (
+    database
+      .prepare("SELECT content FROM files WHERE path = ?")
+      .get(".agents/config/pricing/models.json") as { content?: string } | undefined
+  )?.content;
+  const pricingCatalog = pricingCatalogSchema.parse(
+    JSON.parse(
+      pricingContent ??
+        '{"schema_version":1,"updated_at":"1970-01-01T00:00:00.000Z","source":"missing","disclaimer":"missing","models":[]}',
+    ),
+  );
+  const fxRate = latestFxRate(
+    database
+      .prepare("SELECT path, content FROM files WHERE path LIKE '.agents/config/pricing/fx/%.json'")
+      .all() as Array<{ path: string; content: string }>,
+  );
+  const runRows = database
+    .prepare(
+      "SELECT path, content, content_sha256 FROM files WHERE (path LIKE '.agents/data/runs/%.jsonl' OR path LIKE '.agents/records/runs/%.jsonl') ORDER BY CASE WHEN path LIKE '.agents/data/%' THEN 1 ELSE 0 END, path",
+    )
+    .all() as Array<{ path: string; content: string; content_sha256: string }>;
+
+  // Historical attribution is an append-only, self-verifying overlay. It
+  // never changes a Run stream and therefore participates only after the
+  // native identity carried by the Run itself.
+  const historicalDeveloperManifests = (
+    database
+      .prepare(
+        "SELECT content FROM files WHERE path LIKE '.agents/data/lifecycle/historical-developer-attribution/%.json' OR path LIKE '.agents/records/lifecycle/historical-developer-attribution/%.json'",
+      )
+      .all() as Array<{ content: string }>
+  ).flatMap((row) => {
+    try {
+      return [JSON.parse(row.content)];
+    } catch {
+      return [];
+    }
+  });
+  const resolveDeveloper = (row: { path: string; content: string }, identity: unknown) => {
+    const native = recordValue(identity);
+    if (
+      native !== null &&
+      typeof native.account_id === "string" &&
+      typeof native.login_snapshot === "string"
+    )
+      return {
+        accountId: native.account_id,
+        login: native.login_snapshot,
+        source:
+          typeof native.attribution_source === "string" ? native.attribution_source : "native",
+      };
+    for (const candidate of historicalDeveloperManifests) {
+      try {
+        const resolved = resolveHistoricalDeveloperAttribution({
+          manifest: candidate,
+          run_id: String(JSON.parse(row.content.split(/\r?\n/u)[0] ?? "{}").run_id ?? ""),
+          path: row.path,
+          content: row.content,
+        });
+        if (resolved !== null)
+          return {
+            accountId: resolved.account_id,
+            login: resolved.login_snapshot,
+            source: resolved.attribution_source,
+          };
+      } catch {
+        // A corrupt or non-matching historical manifest is not an
+        // attribution source. The consumer remains fail-closed.
+      }
+    }
+    return null;
+  };
+  const runRowsById = new Map(
+    runRows.map((row) => [
+      row.path
+        .split("/")
+        .at(-1)
+        ?.replace(/\.jsonl$/, ""),
+      row,
+    ]),
+  );
+  for (const previous of previousActivities) {
+    const row = runRows.find((row) => row.path === previous.source_path);
+    const selected = runRowsById.get(previous.run_id);
+    if (row && (selected === undefined || !selected.path.startsWith(".agents/data/")))
+      runRowsById.set(previous.run_id, row);
+  }
+  const folds = new Map<string, { row: (typeof runRows)[number]; fold: RunV2Fold }>();
+  const readFold = (row: (typeof runRows)[number]) =>
+    parsedSources.read("fold", row.path, row.content_sha256, () => {
+      refresh.canonical_runs_refolded += 1;
+      return foldRunV2Records(parseRunV2JsonLines(row.content));
+    });
+  const getFold = (runId: string) => {
+    const available = folds.get(runId);
+    if (available) return available;
+    const row = runRowsById.get(runId);
+    if (!row) return undefined;
+    return { row, fold: readFold(row) };
+  };
+  for (const row of runRows) {
+    const previous = previousActivities.find((activity) => activity.source_path === row.path);
+    if (
+      hasPersistentSchema &&
+      previous &&
+      !dirtyRunIds.has(previous.run_id) &&
+      !changedSources.has(row.path)
+    )
+      continue;
+    const fold = readFold(row);
+    dirtyRunIds.add(fold.run.run_id);
+    folds.set(fold.run.run_id, { row, fold });
+  }
+  const rootRunId = (fold: RunV2Fold): string => {
+    let current = fold;
+    const seen = new Set<string>();
+    while (current.run.parent_run_id !== null && !seen.has(current.run.run_id)) {
+      seen.add(current.run.run_id);
+      const parent = getFold(current.run.parent_run_id)?.fold;
+      if (parent === undefined) break;
+      current = parent;
+    }
+    return current.run.run_id;
+  };
+  const columns = [
+    "activity_row_id",
+    "activity_source_kind",
+    "activity_key",
+    "source_path",
+    "source_hash",
+    "source_occurred_at",
+    "recorded_at",
+    "version_activity_id",
+    "source_last_event_id",
+    "source_last_sequence",
+    "work_item_kind",
+    "title",
+    "work_item_status",
+    "work_stage",
+    "risk",
+    "run_role",
+    "root_run_id",
+    "parent_run_id",
+    "agent_run_id",
+    "root_agent_run_id",
+    "parent_agent_run_id",
+    "agent_run_role",
+    "delegation_depth",
+    "agent_invocation_id",
+    "root_agent_invocation_id",
+    "parent_agent_invocation_id",
+    "invocation_kind",
+    "execution_id",
+    "task_id",
+    "spec_id",
+    "prd_id",
+    "change_id",
+    "conversation_id",
+    "run_id",
+    "occurred_at",
+    "occurred_day_sp",
+    "execution_kind",
+    "entrypoint",
+    "work_type",
+    "phase",
+    "purpose",
+    "status",
+    "activity_kind",
+    "zaip_agent",
+    "zaip_agent_persona",
+    "zaip_agent_job",
+    "zaip_agent_role",
+    "agent_catalog_id",
+    "agent_catalog_hash",
+    "client",
+    "provider",
+    "model",
+    "service_tier",
+    "reasoning_effort",
+    "developer_account_id",
+    "developer_login",
+    "developer_attribution_source",
+    "source_duration_ms",
+    "source_started_at",
+    "source_finished_at",
+    "duration_ms",
+    "duration_provenance",
+    "input_tokens",
+    "cached_input_tokens",
+    "output_tokens",
+    "reasoning_tokens",
+    "total_tokens",
+    "token_source",
+    "usage_event_count",
+    "llm_call_count",
+    "cost_usd",
+    "cost_brl",
+    "cost_method",
+    "pricing_model",
+    "pricing_source",
+    "fx_rate",
+    "source_event_count",
+    "root_run_duration",
+    "sub_run_duration",
+    "payload_type",
+    "payload_json",
+  ] as const;
+  const canonicalInsertActivity = database.prepare(
+    `INSERT INTO zaip_aios_activities(${columns.join(",")}) VALUES (${columns.map(() => "?").join(",")})`,
+  );
+  const insertTemporalFact = database.prepare(
+    "INSERT INTO attributed_token_active_facts(activity_row_id, occurred_day_sp, attributed_token_active_ms) VALUES (?, ?, ?)",
+  );
+  const insertUsageSegment = database.prepare(
+    "INSERT INTO invocation_usage_segments VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+  );
+  const insertCanonicalRun = database.prepare(
+    "INSERT INTO canonical_run_index(run_id, occurred_at, occurred_day_sp, task_id, phase, run_role, duration_ms, source_event_count, zaip_agent, provider, model, status) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+  );
+  let unassistedActivityCount = previousActivities.filter(
+    (row) => !dirtyRunIds.has(row.run_id) && row.agent_invocation_id === null,
+  ).length;
+  const excludedUnknownTokenRunCount = 0;
+  const temporalIntervals: TemporalInterval[] = oldIntervals.filter(
+    (interval) =>
+      !previousActivities.some(
+        (row) => row.activity_row_id === interval.activityRowId && dirtyRunIds.has(row.run_id),
+      ),
+  );
+  const zeroDurationFacts: Array<{ activityRowId: string; day: string }> = [];
+  for (const { row, fold } of folds.values()) {
+    const started = fold.run;
+    const developer = resolveDeveloper(row, started.developer_identity ?? null);
+    const usage = fold.effective_usage_records;
+    const agentRunId = started.agent_invocation_id ?? null;
+    const isAgentRun = agentRunId !== null;
+    const runRole = started.parent_run_id === null ? "root" : "subrun";
+    const agentRunRole = !isAgentRun
+      ? null
+      : started.parent_agent_invocation_id === null
+        ? "root"
+        : "subagent";
+    const totalTokens = knownSum(usage, "total");
+    const durations = resolveDurations(usage, fold);
+    const cost = aggregateCost(usage, fold, pricingCatalog, fxRate);
+    // Provider/model dimensions are factual only when the same usage
+    // segment carries a recorded financial fact. A null-only secondary
+    // segment must not turn an otherwise attributable activity into
+    // "mixed".
+    const financialUsage = usage.filter(
+      (record) =>
+        typeof record.tokens.total === "number" ||
+        typeof record.cost.usd === "number" ||
+        typeof record.cost.brl === "number",
+    );
+    const model =
+      consolidatedValue(financialUsage.map((record) => record.model ?? started.model)) ??
+      (started.model === "unavailable" ? null : started.model);
+    const provider =
+      consolidatedValue(
+        financialUsage.map((record) =>
+          canonicalProvider(record.provider, record.model ?? started.model, started.client),
+        ),
+      ) ?? canonicalProvider(started.provider, model, started.client);
+    const zaipAgent = started.agent_name ?? started.agent;
+    insertCanonicalRun.run(
+      started.run_id,
+      started.occurred_at,
+      saoPauloDay(started.occurred_at),
+      started.task_id,
+      started.phase,
+      runRole,
+      durations.effective,
+      fold.records.length,
+      zaipAgent,
+      provider,
+      model,
+      fold.status,
+    );
+    // Preserve an attributed Run with absent telemetry as an analytical
+    // fact with NULL measures. This makes coverage visibly unknown rather
+    // than silently converting it to a known zero or erasing its owner.
+    const profile = agentProfiles.get(zaipAgent) ?? agentProfiles.get(started.agent);
+    const workItem =
+      started.task_id === null
+        ? started.spec_id === null
+          ? started.prd_id === null
+            ? null
+            : canonicalEntities.get(`prd:${started.prd_id}`)
+          : canonicalEntities.get(`spec:${started.spec_id}`)
+        : canonicalEntities.get(`task:${started.task_id}`);
+    const callIds = new Set([
+      ...fold.model_call_records.map((record) => record.call_id),
+      ...usage
+        .map((record) => record.model_call_id)
+        .filter((value): value is string => typeof value === "string"),
+    ]);
+    const lastRecord = fold.records.at(-1)!;
+    const activityRowId = `ACTV-${createHash("sha256").update(`run:${started.run_id}`).digest("hex").slice(0, 24)}`;
+    const activity = {
+      activity_row_id: activityRowId,
+      activity_source_kind: isAgentRun ? "agent_run" : "unassisted_turn",
+      activity_key: `run:${started.run_id}`,
+      source_path: row.path,
+      source_hash: row.content_sha256,
+      source_occurred_at:
+        usage
+          .map((record) => record.source_occurred_at)
+          .filter((value): value is string => typeof value === "string")
+          .sort()[0] ?? started.occurred_at,
+      recorded_at: lastRecord.occurred_at,
+      version_activity_id: null,
+      source_last_event_id: lastRecord.event_id,
+      source_last_sequence: lastRecord.sequence,
+      work_item_kind: workItem?.kind ?? null,
+      title: workItem?.title ?? null,
+      work_item_status: workItem?.status ?? null,
+      work_stage: workItem?.stage ?? null,
+      risk: workItem?.risk ?? null,
+      run_role: runRole,
+      root_run_id: rootRunId(fold),
+      parent_run_id: started.parent_run_id,
+      agent_run_id: agentRunId,
+      root_agent_run_id: started.root_agent_invocation_id ?? agentRunId,
+      parent_agent_run_id: started.parent_agent_invocation_id ?? null,
+      agent_run_role: agentRunRole,
+      delegation_depth: started.delegation_depth ?? null,
+      agent_invocation_id: agentRunId,
+      root_agent_invocation_id: started.root_agent_invocation_id ?? agentRunId,
+      parent_agent_invocation_id: started.parent_agent_invocation_id ?? null,
+      invocation_kind: started.invocation_kind ?? null,
+      execution_id: started.execution_id,
+      task_id: started.task_id,
+      spec_id: started.spec_id,
+      prd_id: started.prd_id,
+      change_id: started.change_id,
+      conversation_id: started.conversation_id,
+      run_id: started.run_id,
+      occurred_at: started.occurred_at,
+      occurred_day_sp: saoPauloDay(started.occurred_at),
+      execution_kind: started.execution_kind ?? null,
+      entrypoint: started.entrypoint,
+      work_type: started.work_type,
+      phase: started.phase,
+      purpose: started.run_purpose ?? null,
+      status: fold.status,
+      activity_kind: activityKind({
+        execution_id: started.execution_id,
+        task_id: started.task_id,
+        spec_id: started.spec_id,
+        prd_id: started.prd_id,
+        phase: started.phase,
+        purpose: started.run_purpose ?? null,
+      }),
+      zaip_agent: zaipAgent,
+      zaip_agent_persona: profile?.persona ?? null,
+      zaip_agent_job: profile?.job ?? null,
+      zaip_agent_role: profile?.role ?? null,
+      agent_catalog_id: profile?.catalogId ?? null,
+      agent_catalog_hash: catalogHash,
+      client: started.client,
+      provider,
+      model,
+      service_tier: consolidatedValue(usage.map((record) => record.runtime?.service_tier ?? null)),
+      reasoning_effort:
+        consolidatedValue(usage.map((record) => record.runtime?.reasoning_effort ?? null)) ??
+        started.reasoning_effort ??
+        null,
+      developer_account_id: developer?.accountId ?? null,
+      developer_login: developer?.login ?? null,
+      developer_attribution_source: developer?.source ?? null,
+      source_duration_ms: durations.source,
+      source_started_at: durations.sourceStartedAt,
+      source_finished_at: durations.sourceFinishedAt,
+      duration_ms: durations.effective,
+      duration_provenance: durations.provenance,
+      input_tokens: knownSum(usage, "input"),
+      cached_input_tokens: knownSum(usage, "cached_input"),
+      output_tokens: knownSum(usage, "output"),
+      reasoning_tokens: knownSum(usage, "reasoning"),
+      total_tokens: totalTokens,
+      token_source: consolidatedValue(usage.map((record) => record.tokens.source)),
+      usage_event_count: usage.length,
+      llm_call_count: callIds.size > 0 ? callIds.size : null,
+      cost_usd: cost.usd,
+      cost_brl: cost.brl,
+      cost_method: cost.method,
+      pricing_model: cost.pricingModel,
+      pricing_source: cost.pricingSource,
+      fx_rate: cost.fxRate,
+      source_event_count: fold.records.length,
+      root_run_duration: runRole === "root" ? durations.effective : null,
+      sub_run_duration: runRole === "subrun" ? durations.effective : null,
+      payload_type: null,
+      payload_json: null,
+    } satisfies Record<(typeof columns)[number], string | number | null>;
+    canonicalInsertActivity.run(...columns.map((column) => activity[column] ?? null));
+    if (
+      totalTokens !== null &&
+      totalTokens > 0 &&
+      durations.effective !== null &&
+      durations.effective >= 0
+    ) {
+      const startMs = Date.parse(durations.sourceStartedAt ?? started.occurred_at);
+      const endMs = Date.parse(durations.sourceFinishedAt ?? "") || startMs + durations.effective;
+      if (Number.isFinite(startMs) && Number.isFinite(endMs) && endMs > startMs)
+        temporalIntervals.push({ activityRowId, startMs, endMs });
+      else if (durations.effective === 0)
+        zeroDurationFacts.push({ activityRowId, day: saoPauloDay(started.occurred_at) });
+    }
+    if (agentRunId !== null) {
+      for (const record of usage) {
+        const tokens = record.tokens;
+        const audit = usagePricingAudit(record, fold, pricingCatalog, fxRate);
+        insertUsageSegment.run(
+          agentRunId,
+          record.provider ?? null,
+          record.model ?? null,
+          audit.serviceTier,
+          record.runtime?.reasoning_effort ?? null,
+          tokens.input,
+          tokens.cached_input,
+          audit.uncachedInputTokens,
+          tokens.output,
+          tokens.reasoning,
+          audit.visibleOutputTokens,
+          tokens.total,
+          audit.inputRate,
+          audit.cachedRate,
+          audit.outputRate,
+          audit.reasoningRate,
+          audit.contextInputMultiplier,
+          audit.contextOutputMultiplier,
+          audit.speedCostMultiplier,
+          audit.pricingScenario,
+          audit.standardUsd,
+          audit.speedUpliftUsd,
+          audit.inputUsd,
+          audit.cachedInputUsd,
+          audit.outputUsd,
+          audit.reasoningUsd,
+          audit.calculatedUsd,
+          audit.recordedUsd,
+          audit.varianceUsd,
+          audit.effectiveUsd,
+          audit.effectiveBrl,
+          audit.recordedUsd !== null ? "canonical_recorded" : "token_pricing_estimate",
+          audit.pricingModel,
+          audit.pricingSource,
+          audit.fxRate,
+        );
+      }
+    }
+    if (!isAgentRun) unassistedActivityCount += 1;
+  }
+  const dirtyActivityIds = new Set(
+    previousActivities
+      .filter((row) => dirtyRunIds.has(row.run_id))
+      .map((row) => String(row.activity_row_id)),
+  );
+  for (const row of database
+    .prepare("SELECT activity_row_id,run_id FROM zaip_aios_activities WHERE payload_type IS NULL")
+    .all() as Array<{ activity_row_id: string; run_id: string }>)
+    if (dirtyRunIds.has(row.run_id)) dirtyActivityIds.add(row.activity_row_id);
+  const temporalDelta = affectedTemporalIntervals(
+    oldIntervals,
+    temporalIntervals,
+    dirtyActivityIds,
+  );
+  for (const id of temporalDelta.ids)
+    database.prepare("DELETE FROM attributed_token_active_facts WHERE activity_row_id=?").run(id);
+  for (const fact of allocateAttributedTokenActiveMs(temporalDelta.intervals))
+    insertTemporalFact.run(fact.activityRowId, fact.day, fact.value);
+  for (const fact of zeroDurationFacts) insertTemporalFact.run(fact.activityRowId, fact.day, 0);
+  const updateDuration =
+    database.prepare(`UPDATE zaip_aios_activities SET duration_ms=?,duration_provenance=?
+        WHERE activity_row_id=? AND (duration_ms IS NOT ? OR duration_provenance IS NOT ?)`);
+  const temporalRuns = new Set(dirtyRunIds);
+  for (const id of temporalDelta.ids) {
+    const fact = database
+      .prepare(
+        "SELECT SUM(attributed_token_active_ms) value,COUNT(*) count FROM attributed_token_active_facts WHERE activity_row_id=?",
+      )
+      .get(id) as { value: number | null; count: number };
+    const provenance = fact.count ? "attributed_token_active" : null;
+    updateDuration.run(fact.value, provenance, id, fact.value, provenance);
+    const run = database
+      .prepare("SELECT run_id FROM zaip_aios_activities WHERE activity_row_id=?")
+      .get(id) as { run_id: string } | undefined;
+    if (run) temporalRuns.add(run.run_id);
+  }
+  // Entity links and titles are projections of canonical metadata, not new Run usage.
+  if (entityChanged)
+    for (const row of database
+      .prepare(
+        "SELECT activity_row_id,task_id,spec_id,prd_id,change_id,execution_id,conversation_id FROM zaip_aios_activities WHERE payload_type IS NULL",
+      )
+      .all() as Array<Record<string, any>>) {
+      const entity =
+        row.task_id !== null
+          ? canonicalEntities.get(`task:${row.task_id}`)
+          : row.spec_id !== null
+            ? canonicalEntities.get(`spec:${row.spec_id}`)
+            : row.prd_id !== null
+              ? canonicalEntities.get(`prd:${row.prd_id}`)
+              : null;
+      const values = [
+        entity?.kind ?? null,
+        entity?.title ?? null,
+        entity?.status ?? null,
+        entity?.stage ?? null,
+        entity?.risk ?? null,
+      ];
+      database
+        .prepare(
+          `UPDATE zaip_aios_activities SET work_item_kind=?,title=?,work_item_status=?,work_stage=?,risk=? WHERE activity_row_id=? AND (work_item_kind IS NOT ? OR title IS NOT ? OR work_item_status IS NOT ? OR work_stage IS NOT ? OR risk IS NOT ?)`,
+        )
+        .run(...values, row.activity_row_id, ...values);
+    }
+
+  return {
+    temporalRuns,
+    getFold,
+    pricingCatalog,
+    fxRate,
+    rootRunId,
+    catalogHash,
+    columns,
+    canonicalInsertActivity,
+    excludedUnknownTokenRunCount,
+    unassistedActivityCount,
+    agentProfiles,
+  };
+}

package/templates/.agents/dashboard/packages/local-runtime/src/sqlite-metric-contract.test.ts

@@ -27,7 +27,7 @@ describe("SQLite metric contract", () => {
   });
 
   it("covers every allowlisted SQLite view and the paginated read-model endpoints", () => {
-    const server = readFileSync(new URL("server.ts", import.meta.url), "utf8");
+    const server = readFileSync(new URL("server-operations-routes.ts", import.meta.url), "utf8");
     const actualViews = Object.keys(sqliteViewMetadata);
     expect(SQLITE_VIEW_CONTRACTS.map(([view]) => view).sort()).toEqual(actualViews.sort());
     expect(server).toContain("${API_PREFIX}/sqlite-read-models");