chainlesschain 0.163.6 → 0.163.7

package/src/lib/runtime-usage-ledger.js

@@ -0,0 +1,182 @@
+const MAX_LABEL_LENGTH = 160;
+const MAX_CALL_ID_LENGTH = 128;
+const MAX_ATTRIBUTION_ID_LENGTH = 256;
+let fallbackToolSequence = 0;
+const USAGE_FIELDS = Object.freeze([
+  ["input_tokens", "prompt_tokens"],
+  ["output_tokens", "completion_tokens"],
+  ["cache_read_input_tokens", "cache_read_tokens"],
+  ["cache_creation_input_tokens", "cache_creation_tokens"],
+]);
+const SOURCES = new Set(["model", "semantic-compaction", "subagent"]);
+const UNKNOWN_CODES = new Set([
+  "provider_call_failed",
+  "provider_usage_missing",
+  "provider_transport_outcome_unknown",
+]);
+
+function cleanLabel(value, max = MAX_LABEL_LENGTH) {
+  if (typeof value !== "string") return null;
+  const clean = value.replace(/\p{Cc}/gu, "").trim();
+  return clean ? clean.slice(0, max) : null;
+}
+
+function tokenCount(usage, canonical, alias, { required = false } = {}) {
+  const hasCanonical = Object.hasOwn(usage, canonical);
+  const hasAlias = Object.hasOwn(usage, alias);
+  if (!hasCanonical && !hasAlias) {
+    if (required) {
+      throw new TypeError(
+        `runtime token usage requires ${canonical} or ${alias}`,
+      );
+    }
+    return 0;
+  }
+  if (hasCanonical && hasAlias && usage[canonical] !== usage[alias]) {
+    throw new TypeError("runtime token usage aliases conflict");
+  }
+  const selected = hasCanonical ? usage[canonical] : usage[alias];
+  if (
+    typeof selected !== "number" ||
+    !Number.isSafeInteger(selected) ||
+    selected < 0
+  ) {
+    throw new TypeError(
+      "runtime token usage must contain non-negative safe integers",
+    );
+  }
+  return selected;
+}
+
+function source(value, fallback = "model") {
+  return SOURCES.has(value) ? value : fallback;
+}
+
+function callId(value, { required = false } = {}) {
+  if (
+    typeof value !== "string" ||
+    !value.trim() ||
+    value.length > MAX_CALL_ID_LENGTH ||
+    /\p{Cc}/u.test(value)
+  ) {
+    if (!required && value === undefined) return null;
+    throw new TypeError("runtime usage boundary requires a bounded call id");
+  }
+  return value.trim();
+}
+
+function projectAttribution(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const projected = {};
+  for (const field of [
+    "origin",
+    "skill",
+    "subagentId",
+    "role",
+    "parentSessionId",
+  ]) {
+    const clean = cleanLabel(value[field], MAX_ATTRIBUTION_ID_LENGTH);
+    if (clean) projected[field] = clean;
+  }
+  if (
+    typeof value.depth === "number" &&
+    Number.isSafeInteger(value.depth) &&
+    value.depth >= 0 &&
+    value.depth <= 64
+  ) {
+    projected.depth = value.depth;
+  }
+  return Object.keys(projected).length > 0 ? projected : null;
+}
+
+/** Project a runtime token event onto the secret-free persisted ledger schema. */
+export function projectRuntimeTokenUsage(event = {}) {
+  if (
+    !event.usage ||
+    typeof event.usage !== "object" ||
+    Array.isArray(event.usage)
+  ) {
+    throw new TypeError("runtime token usage requires an object");
+  }
+  const usage = {};
+  for (const [index, [canonical, alias]] of USAGE_FIELDS.entries()) {
+    usage[canonical] = tokenCount(event.usage, canonical, alias, {
+      // A known settlement must prove both billable input and output counts.
+      // Cache counters are optional because many providers do not expose them.
+      required: index < 2,
+    });
+  }
+  if (Object.hasOwn(event.usage, "total_tokens")) {
+    const total = event.usage.total_tokens;
+    if (
+      typeof total !== "number" ||
+      !Number.isSafeInteger(total) ||
+      total < 0 ||
+      total !== usage.input_tokens + usage.output_tokens
+    ) {
+      throw new TypeError(
+        "runtime token usage total conflicts with components",
+      );
+    }
+  }
+  const projectedCallId = callId(event.callId);
+  const attribution = projectAttribution(event.attribution);
+  return {
+    provider: cleanLabel(event.provider),
+    model: cleanLabel(event.model),
+    usage,
+    ...(projectedCallId ? { callId: projectedCallId } : {}),
+    ...(event.source ? { source: source(event.source) } : {}),
+    ...(attribution ? { attribution } : {}),
+  };
+}
+
+/** Project started/unknown boundaries without retaining provider error text. */
+export function projectRuntimeUsageBoundary(event = {}, outcome) {
+  if (outcome !== "started" && outcome !== "unknown") {
+    throw new TypeError(
+      "runtime usage boundary outcome must be started or unknown",
+    );
+  }
+  const projected = {
+    callId: callId(event.callId, { required: true }),
+    provider: cleanLabel(event.provider),
+    model: cleanLabel(event.model),
+    source: source(event.source),
+  };
+  const attribution = projectAttribution(event.attribution);
+  if (attribution) projected.attribution = attribution;
+  if (outcome === "unknown") {
+    projected.code = UNKNOWN_CODES.has(event.code)
+      ? event.code
+      : "provider_transport_outcome_unknown";
+  }
+  return projected;
+}
+
+export function runtimeUsageEventType(outcome) {
+  return outcome === "started" ? "model_usage_started" : "model_usage_unknown";
+}
+
+export function runtimeToolCallId(value) {
+  const projected = callId(value);
+  if (projected) return projected;
+  fallbackToolSequence = (fallbackToolSequence + 1) % Number.MAX_SAFE_INTEGER;
+  return `tool-${Date.now().toString(36)}-${fallbackToolSequence.toString(36)}`;
+}
+
+export function markRuntimeLedgerPersistenceError(error) {
+  if (error && (typeof error === "object" || typeof error === "function")) {
+    try {
+      error.runtimeLedgerPersistence = true;
+      if (error.runtimeLedgerPersistence === true) return error;
+    } catch {
+      // Frozen/non-extensible errors are wrapped below.
+    }
+  }
+  const wrapped = new Error("runtime usage ledger persistence failed", {
+    cause: error,
+  });
+  wrapped.runtimeLedgerPersistence = true;
+  return wrapped;
+}

package/src/lib/scheduler-kernel/agenda-adapter.js

@@ -1,6 +1,8 @@
 import { createHash } from "node:crypto";
 import { effectiveFireAt } from "../schedule-planner.js";
 import {
+  agendaMigrationSourceDigest,
+  agendaMigrationSourceSnapshot,
   nextCronTime,
   normalizeTimeZone,
   parseCron,
@@ -13,10 +15,12 @@ import {
   normalizeJson,
 } from "./contract.js";
 import { SchedulerRuntime } from "./runtime.js";
+import { schedulerMigrationSourceDigest } from "./store.js";
 import {
   bindSchedulerAuthorityPolicy,
   createSchedulerAuthorityResolver,
 } from "./authority-resolver.js";
+import { canonicalSchedulerSourcePath } from "./source-locator-path.js";
 
 export const AGENDA_SCHEDULER_KIND = "agenda";
 export const AGENDA_SCHEDULER_CAPABILITY = "agent.execute";
@@ -188,6 +192,7 @@ function validateEntrySnapshot(entry) {
   const plain = { ...entry };
   delete plain.executionLease;
   delete plain.schedulerExecution;
+  delete plain.schedulerMigration;
   const snapshot = normalizeJson(plain, "agendaEntrySnapshot");
   snapshot.id = normalizeIdentifier(snapshot.id, "agenda.entry.id");
   if (!AGENDA_SCHEDULER_ENTRY_KINDS.includes(snapshot.kind)) {
@@ -361,6 +366,223 @@ export function syncAgendaSchedulerJob(schedulerStore, entry) {
   }
 }
 
+export function migrateAgendaSchedulerEntry({
+  agendaStore,
+  schedulerStore,
+  entry,
+}) {
+  const snapshot = agendaEntrySnapshot(entry);
+  const directory = canonicalSchedulerSourcePath(agendaStore.dir);
+  const sourceScope = { store: "agent-schedule", directory };
+  const sourceLocator = {
+    schemaVersion: 1,
+    type: "agenda-store",
+    directory,
+  };
+  let prepared = schedulerStore.getActiveDomainMigrationBySource({
+    domain: "agenda",
+    sourceScope,
+    sourceId: snapshot.id,
+  });
+  if (!prepared && agendaStore.dir !== directory) {
+    const ambiguousLegacy = schedulerStore.getActiveDomainMigrationBySource({
+      domain: "agenda",
+      sourceScope: {
+        store: "agent-schedule",
+        directory: agendaStore.dir,
+      },
+      sourceId: snapshot.id,
+    });
+    if (ambiguousLegacy) {
+      throw agendaError(
+        "AGENDA_SCHEDULER_MIGRATION_SOURCE_UNBOUND",
+        `Legacy Agenda migration uses a non-canonical path scope and cannot be bound safely: ${snapshot.id}`,
+      );
+    }
+  }
+  const desired = buildAgendaSchedulerJob(snapshot);
+  desired.authority = bindSchedulerAuthorityPolicy(
+    schedulerStore,
+    desired.authority,
+  );
+  const sourceDigest = agendaMigrationSourceDigest(entry);
+  const sourceSnapshot = agendaMigrationSourceSnapshot(entry);
+  if (prepared) {
+    const migrationEntries = prepared.entries.filter(
+      (candidate) =>
+        candidate.domain === "agenda" && candidate.sourceId === snapshot.id,
+    );
+    if (prepared.entries.length !== 1 || migrationEntries.length !== 1) {
+      throw agendaError(
+        "AGENDA_SCHEDULER_MIGRATION_DOMAIN_MISMATCH",
+        "Agenda entry belongs to an invalid mixed-domain migration",
+      );
+    }
+    const [migrationEntry] = migrationEntries;
+    schedulerStore.bindDomainMigrationSourceLocator({
+      migrationId: prepared.id,
+      entryId: migrationEntry.entryId,
+      sourceLocator,
+      expectedSourceDigest: migrationEntry.sourceDigest,
+      expectedTargetJobId: migrationEntry.targetJobId,
+    });
+    prepared = schedulerStore.getDomainMigration(prepared.id);
+  } else {
+    prepared = schedulerStore.prepareDomainMigration({
+      entries: [
+        {
+          domain: "agenda",
+          sourceId: snapshot.id,
+          sourceScope,
+          sourceLocator,
+          source: sourceSnapshot,
+          targetJob: desired,
+          rollbackStrategy: "disable",
+        },
+      ],
+    });
+  }
+  if (
+    prepared.entries.length !== 1 ||
+    prepared.entries[0].domain !== "agenda"
+  ) {
+    throw agendaError(
+      "AGENDA_SCHEDULER_MIGRATION_DOMAIN_MISMATCH",
+      "Agenda entry belongs to an invalid mixed-domain migration",
+    );
+  }
+  const expectedJournalDigest = schedulerMigrationSourceDigest(sourceSnapshot);
+  if (
+    prepared.entries[0].sourceDigest !== expectedJournalDigest ||
+    prepared.entries[0].targetJobId !== desired.id
+  ) {
+    throw agendaError(
+      "AGENDA_SCHEDULER_MIGRATION_SOURCE_CHANGED",
+      `Agenda entry changed after its scheduler migration started: ${snapshot.id}`,
+    );
+  }
+  let migration = prepared;
+  if (migration.state === "rolled_back" || migration.state === "rolling_back") {
+    throw agendaError(
+      "AGENDA_SCHEDULER_MIGRATION_STATE_CONFLICT",
+      `Agenda migration cannot resume from state ${migration.state}`,
+    );
+  }
+  if (migration.state === "retired") {
+    const migrationEntry = migration.entries[0];
+    agendaStore.retireForSchedulerMigration(snapshot.id, {
+      migrationId: migration.id,
+      sourceDigest,
+      targetJobId: desired.id,
+      retirementToken: migrationEntry.retirementToken,
+    });
+    return migration;
+  }
+  if (migration.state === "prepared") {
+    agendaStore.prepareSchedulerMigration(snapshot.id, {
+      migrationId: migration.id,
+      sourceDigest,
+      targetJobId: desired.id,
+    });
+    migration = schedulerStore.applyDomainMigration(migration.id);
+  }
+  if (migration.state === "applied") {
+    migration = schedulerStore.verifyDomainMigration(migration.id, {
+      sources: [
+        {
+          entryId: migration.entries[0].entryId,
+          source: agendaMigrationSourceSnapshot(entry),
+        },
+      ],
+    });
+  }
+  const retiring =
+    migration.state === "retiring"
+      ? migration
+      : schedulerStore.beginDomainMigrationRetirement(migration.id);
+  const retiringEntry = retiring.entries[0];
+  const retired = agendaStore.retireForSchedulerMigration(snapshot.id, {
+    migrationId: prepared.id,
+    sourceDigest,
+    targetJobId: desired.id,
+    retirementToken: retiringEntry.retirementToken,
+  });
+  schedulerStore.confirmDomainMigrationEntryRetired({
+    migrationId: prepared.id,
+    entryId: retiringEntry.entryId,
+    retirementToken: retiringEntry.retirementToken,
+    source: retired,
+  });
+  return schedulerStore.getDomainMigration(prepared.id);
+}
+
+export function rollbackAgendaSchedulerMigration({
+  agendaStore,
+  schedulerStore,
+  migrationId,
+}) {
+  const directory = canonicalSchedulerSourcePath(agendaStore.dir);
+  const assertRollbackBinding = (migration) => {
+    if (
+      migration?.id !== migrationId ||
+      !Array.isArray(migration.entries) ||
+      migration.entries.length === 0 ||
+      migration.entries.some((entry) => entry.domain !== "agenda")
+    ) {
+      throw agendaError(
+        "AGENDA_SCHEDULER_MIGRATION_DOMAIN_MISMATCH",
+        "Agenda rollback cannot operate on a mixed-domain migration",
+      );
+    }
+    for (const entry of migration.entries) {
+      const locator = entry.sourceLocator;
+      if (
+        locator?.schemaVersion !== 1 ||
+        locator.type !== "agenda-store" ||
+        locator.directory !== directory
+      ) {
+        throw agendaError(
+          "AGENDA_SCHEDULER_MIGRATION_SOURCE_UNBOUND",
+          `Agenda rollback source locator does not match its store: ${entry.sourceId}`,
+        );
+      }
+    }
+    return migration;
+  };
+  const current = assertRollbackBinding(
+    schedulerStore.getDomainMigration(migrationId),
+  );
+  if (current.state === "rolled_back") {
+    return { ...current, deduplicated: true };
+  }
+  const migration = assertRollbackBinding(
+    schedulerStore.beginDomainMigrationRollback(migrationId),
+  );
+  if (migration.state === "rolled_back") return migration;
+  const entries = migration.entries;
+  for (const entry of entries) {
+    if (entry.state === "rolled_back") continue;
+    schedulerStore.restoreDomainMigrationEntrySource({
+      migrationId,
+      entryId: entry.entryId,
+      retirementToken: entry.retirementToken,
+      restoreSource: () => {
+        const current = agendaStore.get(entry.sourceId);
+        const restored = current.schedulerMigration
+          ? agendaStore.restoreFromSchedulerMigration(entry.sourceId, {
+              migrationId,
+              sourceDigest: agendaMigrationSourceDigest(current),
+              targetJobId: entry.targetJobId,
+              retirementToken: entry.retirementToken,
+            })
+          : current;
+        return agendaMigrationSourceSnapshot(restored);
+      },
+    });
+  }
+  return schedulerStore.getDomainMigration(migrationId);
+}
+
 export function enqueueAgendaEntry(schedulerStore, entry) {
   const snapshot = agendaEntrySnapshot(entry);
   const job = syncAgendaSchedulerJob(schedulerStore, snapshot);
@@ -455,6 +677,40 @@ export function createAgendaSchedulerAdapter({
   }
   return {
     kind: AGENDA_SCHEDULER_KIND,
+    async adjudicate({ occurrence, adjudication }) {
+      const payload = occurrence.payload;
+      const expected = agendaEntrySnapshot(payload?.entry);
+      const expectedDigest = agendaEntrySnapshotDigest(expected);
+      if (
+        payload.snapshotDigest !== expectedDigest ||
+        typeof agendaStore.adjudicateSchedulerExecution !== "function"
+      ) {
+        throw agendaError(
+          "AGENDA_SCHEDULER_ADJUDICATION_UNSUPPORTED",
+          `Agenda adjudication cannot be applied: ${occurrence.id}`,
+        );
+      }
+      agendaStore.adjudicateSchedulerExecution(expected.id, {
+        occurrenceId: occurrence.id,
+        snapshotDigest: expectedDigest,
+        attempt: adjudication.expectedAttempt,
+        decision: adjudication.decision,
+        requestId: adjudication.requestId,
+        atMs: now(),
+      });
+      if (adjudication.decision === "confirmed_applied") {
+        return {
+          settled: true,
+          result: {
+            id: expected.id,
+            kind: expected.kind,
+            action: "adjudicated-applied",
+            adjudicationRequestId: adjudication.requestId,
+          },
+        };
+      }
+      return { continue: true };
+    },
     async execute({ occurrence }) {
       const payload = occurrence.payload;
       const expected = agendaEntrySnapshot(payload?.entry);
@@ -709,6 +965,7 @@ export class AgendaSchedulerBridge {
     leaseMs,
     renewIntervalMs,
     authorityResolver,
+    migrateLegacy = true,
   } = {}) {
     if (typeof now !== "function") {
       throw agendaError(
@@ -719,6 +976,7 @@ export class AgendaSchedulerBridge {
     this.agendaStore = agendaStore;
     this.schedulerStore = schedulerStore;
     this.now = now;
+    this.migrateLegacy = migrateLegacy !== false;
     this.runtime = new SchedulerRuntime({
       store: schedulerStore,
       adapters: [
@@ -750,6 +1008,31 @@ export class AgendaSchedulerBridge {
   async runDue({ signal } = {}) {
     const results = [];
     const observedOccurrences = new Set();
+    if (!signal?.aborted && this.migrateLegacy) {
+      const sourceScope = {
+        store: "agent-schedule",
+        directory: canonicalSchedulerSourcePath(this.agendaStore.dir),
+      };
+      const candidates = this.agendaStore.list().filter((entry) => {
+        const activeMigration =
+          this.schedulerStore.getActiveDomainMigrationBySource({
+            domain: "agenda",
+            sourceScope,
+            sourceId: entry.id,
+          });
+        if (entry.schedulerMigration) {
+          return activeMigration?.state !== "retired";
+        }
+        return activeMigration?.state !== undefined;
+      });
+      for (const entry of candidates) {
+        migrateAgendaSchedulerEntry({
+          agendaStore: this.agendaStore,
+          schedulerStore: this.schedulerStore,
+          entry,
+        });
+      }
+    }
     const recovered = await this.runtime.runUntilIdle({
       limit: 10_000,
       signal,
@@ -772,9 +1055,9 @@ export class AgendaSchedulerBridge {
 
     const now = normalizeEpochMs(Number(this.now()), "now");
     const due = [
-      ...this.agendaStore.due("wakeup", now),
-      ...this.agendaStore.due("cron", now),
-      ...this.agendaStore.due("monitor", now),
+      ...this.agendaStore.due("wakeup", now, { schedulerMigration: true }),
+      ...this.agendaStore.due("cron", now, { schedulerMigration: true }),
+      ...this.agendaStore.due("monitor", now, { schedulerMigration: true }),
     ];
     for (const entry of due) {
       const occurrence = enqueueAgendaEntry(this.schedulerStore, entry);
@@ -790,6 +1073,28 @@ export class AgendaSchedulerBridge {
         result,
       });
     }
+    if (this.migrateLegacy) {
+      const candidates = this.agendaStore
+        .list()
+        .filter(
+          (entry) =>
+            !entry.schedulerMigration &&
+            [undefined, "succeeded"].includes(
+              entry.schedulerExecution?.status,
+            ) &&
+            !entry.executionLease &&
+            ((entry.kind === "wakeup" && entry.status === "pending") ||
+              (["cron", "monitor"].includes(entry.kind) &&
+                entry.status === "active")),
+        );
+      for (const entry of candidates) {
+        migrateAgendaSchedulerEntry({
+          agendaStore: this.agendaStore,
+          schedulerStore: this.schedulerStore,
+          entry,
+        });
+      }
+    }
     return results;
   }
 }