@cassiomc1/forgeloop 1.6.5 → 1.8.0

package/src/core/schema-validation.js

@@ -50,6 +50,10 @@ export const SHIPPED_SCHEMA_NAMES = Object.freeze([
   "code-attestation",
   "attestation-verification-result",
   "in-toto-statement",
+  "usage",
+  "execution-profile-benchmark-scenario",
+  "execution-profile-benchmark-run",
+  "execution-profile-benchmark-aggregate",
 ]);
 
 export class SchemaValidationError extends Error {

package/src/core/task-paths.js

@@ -18,6 +18,7 @@ export const TASK_ARTIFACT_FILES = Object.freeze({
   actions: "actions",
   approvals: "approvals",
   evaluations: "evaluations",
+  usage: "usage.json",
   policySnapshot: "policy-snapshot.json",
   recovery: "recovery.json",
   workspaceBinding: "workspace-binding.json",
@@ -193,6 +194,7 @@ export function buildTaskArtifactPaths(taskId) {
     actions: `${dir}/${TASK_ARTIFACT_FILES.actions}`,
     approvals: `${dir}/${TASK_ARTIFACT_FILES.approvals}`,
     evaluations: `${dir}/${TASK_ARTIFACT_FILES.evaluations}`,
+    usage: `${dir}/${TASK_ARTIFACT_FILES.usage}`,
     lock: taskLockPath(taskId),
     policySnapshot: `${dir}/${TASK_ARTIFACT_FILES.policySnapshot}`,
     recovery: `${dir}/${TASK_ARTIFACT_FILES.recovery}`,

package/src/core/templates.js

@@ -83,6 +83,10 @@ export const TEMPLATE_PATHS = [
   "schemas/code-attestation.schema.json",
   "schemas/attestation-verification-result.schema.json",
   "schemas/in-toto-statement.schema.json",
+  "schemas/usage.schema.json",
+  "schemas/execution-profile-benchmark-scenario.schema.json",
+  "schemas/execution-profile-benchmark-run.schema.json",
+  "schemas/execution-profile-benchmark-aggregate.schema.json",
 ];
 
 export function getPackageRoot() {

package/src/core/trace.js

@@ -68,6 +68,7 @@ const EVENT_CATEGORY_MAP = Object.freeze({
   APPROVAL_REQUESTED: "execution",
   APPROVAL_RESOLVED: "execution",
   TRAJECTORY_EVALUATED: "audit",
+  USAGE_RECORDED: "audit",
 });
 
 const LIFECYCLE_TRANSITIONS = Object.freeze([

package/src/core/trajectory-evaluation.js

@@ -12,7 +12,7 @@ import { withTaskTransaction } from "./transaction.js";
 
 function evaluationError(code, message) { const error = new Error(message); error.code = code; return error; }
 
-export async function evaluateTrajectory({ target, packageRoot, taskId, scenarioPath, evaluationId = `eval-${randomUUID()}` }) {
+export async function evaluateTrajectory({ target, packageRoot, taskId, scenarioPath, evaluationId = `eval-${randomUUID()}`, runtimeContext = null }) {
   if (typeof scenarioPath !== "string" || !scenarioPath || path.isAbsolute(scenarioPath) || scenarioPath.includes("..")) {
     throw evaluationError("E_TRAJECTORY_SCENARIO_INVALID", "scenario path must be a relative project-local file");
   }
@@ -26,7 +26,7 @@ export async function evaluateTrajectory({ target, packageRoot, taskId, scenario
   assertSchema(scenario, await readSchema("trajectory-scenario", packageRoot), "trajectory scenario");
   if (!/^eval-[A-Za-z0-9_-]+$/.test(evaluationId)) throw evaluationError("E_TRAJECTORY_SCENARIO_INVALID", "evaluationId is invalid");
   const trace = await buildTaskTrace({ target, packageRoot, taskId });
-  const metrics = await buildTrajectoryMetrics({ target, packageRoot, taskId });
+  const metrics = await buildTrajectoryMetrics({ target, packageRoot, taskId, runtimeContext });
   const milestoneSet = new Set(trace.events.map((event) => event.type));
   const missingMilestones = (scenario.requiredMilestones ?? []).filter((milestone) => !milestoneSet.has(milestone));
   const completionEvent = trace.events.find((event) => event.type === "COMPLETION_VALIDATED");

package/src/core/trajectory-metrics.js

@@ -1,12 +1,15 @@
 import { buildTaskTrace } from "./trace.js";
 import { buildTaskReflection } from "./reflection.js";
+import { readPersistedRoute } from "./route-artifact.js";
+import { providerUsage, readTaskUsage, unknownUsage } from "./usage.js";
+import { projectExecutionProfile } from "./execution-profile.js";
 
 export const COMPARABLE_WORK_EVENTS = new Set([
   "EXECUTION_STARTED", "VERIFICATION_RECORDED", "DIAGNOSTIC_CASE_RECORDED",
   "INTERVENTION_RECORDED", "ACTION_STARTED", "ACTION_RECONCILED", "REVIEW_STARTED",
 ]);
 
-export async function buildTrajectoryMetrics({ target, packageRoot, taskId }) {
+export async function buildTrajectoryMetrics({ target, packageRoot, taskId, runtimeContext = null }) {
   const trace = await buildTaskTrace({ target, packageRoot, taskId });
   const reflection = await buildTaskReflection({ target, packageRoot, taskId });
   const events = trace.events;
@@ -18,6 +21,18 @@ export async function buildTrajectoryMetrics({ target, packageRoot, taskId }) {
   const firstMs = firstEventAt ? Date.parse(firstEventAt) : NaN;
   const lastMs = lastEventAt ? Date.parse(lastEventAt) : NaN;
   const interventions = reflection.interventions ?? { count: 0, informative: 0, nonInformative: 0 };
+  let executionProfile = null;
+  try {
+    const route = await readPersistedRoute(target, packageRoot, { taskId });
+    executionProfile = projectExecutionProfile(route.value);
+  } catch {
+    // Legacy tasks and incomplete task namespaces may not have a route.
+  }
+  let usage = await readTaskUsage(target, packageRoot, taskId);
+  const usageProvider = runtimeContext?.usageProvider;
+  if (usageProvider && typeof usageProvider.getTaskUsage === "function") {
+    usage = providerUsage(await usageProvider.getTaskUsage({ projectPath: target, taskId }));
+  }
   return {
     schemaVersion: 1,
     taskId,
@@ -74,7 +89,8 @@ export async function buildTrajectoryMetrics({ target, packageRoot, taskId }) {
       lastEventAt,
       wallClockMs: Number.isFinite(firstMs) && Number.isFinite(lastMs) ? Math.max(0, lastMs - firstMs) : null,
     },
-    usage: { tokens: null, costUsd: null, source: "UNKNOWN" },
+    executionProfile,
+    usage: usage ?? unknownUsage(),
     comparableSteps: events.filter((event) => COMPARABLE_WORK_EVENTS.has(event.type)).length,
   };
 }

package/src/core/usage.js

@@ -0,0 +1,137 @@
+import { readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
+import { taskArtifactPath } from "./task-paths.js";
+
+export const USAGE_SOURCES = Object.freeze([
+  "PROVIDER_REPORTED",
+  "HOST_REPORTED",
+  "ACTOR_REPORTED",
+  "UNKNOWN",
+]);
+
+export const USAGE_FIELDS = Object.freeze([
+  "inputTokens",
+  "outputTokens",
+  "cacheReadTokens",
+  "cacheWriteTokens",
+  "totalTokens",
+  "costUsd",
+  "model",
+  "provider",
+  "source",
+]);
+
+function usageError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function nullableNonNegativeInteger(value, label) {
+  if (value === null || value === undefined || value === "") return null;
+  if (!Number.isInteger(value) || value < 0) {
+    throw usageError("E_USAGE_INVALID", `${label} must be a non-negative integer or null`);
+  }
+  return value;
+}
+
+function nullableCost(value) {
+  if (value === null || value === undefined || value === "") return null;
+  const numeric = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(numeric) || numeric < 0) {
+    throw usageError("E_USAGE_INVALID", "costUsd must be a non-negative finite number or null");
+  }
+  return numeric;
+}
+
+function nullableString(value, label) {
+  if (value === null || value === undefined || value === "") return null;
+  if (typeof value !== "string" || !value.trim()) {
+    throw usageError("E_USAGE_INVALID", `${label} must be a non-empty string or null`);
+  }
+  return value.trim();
+}
+
+export function unknownUsage() {
+  return {
+    inputTokens: null,
+    outputTokens: null,
+    cacheReadTokens: null,
+    cacheWriteTokens: null,
+    totalTokens: null,
+    costUsd: null,
+    model: null,
+    provider: null,
+    source: "UNKNOWN",
+  };
+}
+
+export function normalizeUsage(value = {}, { defaultSource = "UNKNOWN", allowedSources = USAGE_SOURCES } = {}) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw usageError("E_USAGE_INVALID", "usage must be an object");
+  }
+  const source = value.source ?? defaultSource;
+  if (!allowedSources.includes(source)) {
+    throw usageError("E_USAGE_SOURCE_INVALID", `usage.source must be one of ${allowedSources.join(", ")}`);
+  }
+  return {
+    inputTokens: nullableNonNegativeInteger(value.inputTokens, "inputTokens"),
+    outputTokens: nullableNonNegativeInteger(value.outputTokens, "outputTokens"),
+    cacheReadTokens: nullableNonNegativeInteger(value.cacheReadTokens, "cacheReadTokens"),
+    cacheWriteTokens: nullableNonNegativeInteger(value.cacheWriteTokens, "cacheWriteTokens"),
+    totalTokens: nullableNonNegativeInteger(value.totalTokens, "totalTokens"),
+    costUsd: nullableCost(value.costUsd),
+    model: nullableString(value.model, "model"),
+    provider: nullableString(value.provider, "provider"),
+    source,
+  };
+}
+
+export function createUsageArtifact({ taskId, usage = {}, recordedAt = new Date().toISOString() } = {}) {
+  if (typeof taskId !== "string" || !taskId) throw usageError("E_USAGE_INVALID", "taskId is required for usage telemetry");
+  if (typeof recordedAt !== "string" || !recordedAt.trim() || Number.isNaN(Date.parse(recordedAt))) {
+    throw usageError("E_USAGE_INVALID", "recordedAt must be a valid timestamp");
+  }
+  return {
+    schemaVersion: 1,
+    protocolVersion: 1,
+    taskId,
+    recordedAt,
+    usage: normalizeUsage(usage),
+  };
+}
+
+export function providerUsage(value) {
+  if (value === null || value === undefined) return unknownUsage();
+  const candidate = value?.usage && typeof value.usage === "object" && !Array.isArray(value.usage)
+    ? value.usage
+    : value;
+  const source = candidate?.source ?? "HOST_REPORTED";
+  if (!["PROVIDER_REPORTED", "HOST_REPORTED"].includes(source)) {
+    throw usageError("E_USAGE_SOURCE_INVALID", "host usage providers may report only PROVIDER_REPORTED or HOST_REPORTED");
+  }
+  return normalizeUsage(candidate, { defaultSource: source, allowedSources: ["PROVIDER_REPORTED", "HOST_REPORTED"] });
+}
+
+export async function readTaskUsage(target, packageRoot, taskId) {
+  try {
+    const artifact = await readJsonArtifact(target, taskArtifactPath(taskId, "usage"), "usage", packageRoot);
+    return artifact.value.usage;
+  } catch (error) {
+    if (error.code === "ARTIFACT_MISSING") return unknownUsage();
+    if (error.code === "E_USAGE_SOURCE_INVALID" || error.code === "E_USAGE_INVALID") throw error;
+    error.code = "E_USAGE_INVALID";
+    throw error;
+  }
+}
+
+export async function writeTaskUsage(target, packageRoot, artifact, options = {}) {
+  const value = createUsageArtifact(artifact);
+  return writeJsonArtifact(
+    target,
+    taskArtifactPath(value.taskId, "usage"),
+    value,
+    "usage",
+    packageRoot,
+    { ...options, taskId: value.taskId, operation: options.operation ?? "usage-record" },
+  );
+}

package/src/integration.d.ts

@@ -59,8 +59,92 @@ export interface ForgeLoopContext {
   authorityContext: Record<string, unknown>;
   verificationExecutionAdapter?: Record<string, unknown>;
   verificationExecutionPolicy?: { requiredIsolation: string };
+  usageProvider?: ForgeLoopUsageProvider;
 }
 
+export interface ForgeLoopUsageProvider {
+  getTaskUsage(input: { projectPath: string; taskId: string }): Promise<ForgeLoopUsage | Record<string, unknown>> | ForgeLoopUsage | Record<string, unknown>;
+}
+
+export interface ForgeLoopUsage {
+  inputTokens: number | null;
+  outputTokens: number | null;
+  cacheReadTokens: number | null;
+  cacheWriteTokens: number | null;
+  totalTokens: number | null;
+  costUsd: number | null;
+  model: string | null;
+  provider: string | null;
+  source: "PROVIDER_REPORTED" | "HOST_REPORTED";
+}
+
+export interface ForgeLoopContextUsage {
+  source: "HOST_REPORTED" | "UNKNOWN";
+  profile: "light" | "balanced" | "full" | null;
+  items: {
+    taskContext: number | null;
+    guides: number | null;
+    history: number | null;
+    protocolInstructions: number | null;
+    repositoryContext: number | null;
+    other: number | null;
+  };
+}
+
+export declare const EXECUTION_PROFILES: readonly ["light", "balanced", "full"];
+export declare const EXECUTION_PROFILE_REQUESTS: readonly ["auto", "light", "balanced", "full"];
+export declare const LEGACY_EXECUTION_PROFILE: "balanced";
+export declare function projectExecutionProfile(route?: Record<string, unknown> | null): "light" | "balanced" | "full" | null;
+export declare function resolveExecutionProfile(input?: {
+  routeInput?: Record<string, unknown>;
+  contract?: Record<string, unknown> | null;
+  taskDescriptor?: Record<string, unknown> | null;
+  configuredProfile?: "auto" | "light" | "balanced" | "full";
+  requestedProfile?: "auto" | "light" | "balanced" | "full" | null;
+}): {
+  requested: "auto" | "light" | "balanced" | "full";
+  floor: "light" | "balanced" | "full";
+  resolved: "light" | "balanced" | "full";
+  reasons: readonly string[];
+  escalated: boolean;
+};
+
+export interface ForgeLoopExecutionProfileContext {
+  schemaVersion: 1;
+  protocolVersion: 1;
+  taskId: string;
+  executionProfile: {
+    requested: "auto" | "light" | "balanced" | "full";
+    floor: "light" | "balanced" | "full";
+    resolved: "light" | "balanced" | "full";
+    reasons: readonly string[];
+    escalated: boolean;
+  };
+  phase: string;
+  nextAction: string | null;
+  objective: string | null;
+  deliverables: readonly string[];
+  constraints: readonly string[];
+  selectedGuideIds: readonly string[];
+  verificationRequirements: readonly Record<string, unknown>[];
+  contextPolicy: Record<string, unknown>;
+  contextUsage?: ForgeLoopContextUsage;
+  optionalContext: { available: readonly string[]; loaded: readonly string[] };
+  invariants: Record<string, boolean>;
+}
+
+export declare const PROFILE_CONTEXT_POLICIES: Readonly<Record<string, Record<string, unknown>>>;
+export declare function getExecutionProfileContextPolicy(profile: "light" | "balanced" | "full"): Record<string, unknown>;
+export declare function legacyExecutionProfile(): ForgeLoopExecutionProfileContext["executionProfile"];
+export declare function projectExecutionProfileContext(input: Record<string, unknown>): ForgeLoopExecutionProfileContext;
+export declare function buildExecutionProfileContext(input: {
+  target: string;
+  packageRoot?: string;
+  taskId: string;
+  authorityContext?: Record<string, unknown>;
+  runtimeContext?: Record<string, unknown>;
+}): Promise<ForgeLoopExecutionProfileContext>;
+
 export declare const FORGELOOP_INTEGRATION_API_VERSION: number;
 export declare const FORGELOOP_INTEGRATION_RUNTIME_VERSION: number;
 export declare const CLI_COMMAND_DEFINITIONS: Readonly<Record<string, ForgeLoopCommandDefinition>>;

package/src/integration.js

@@ -45,6 +45,20 @@ export {
 };
 
 export { createForgeLoopContext } from "./core/runtime-context.js";
+export {
+  PROFILE_CONTEXT_POLICIES,
+  buildExecutionProfileContext,
+  getExecutionProfileContextPolicy,
+  legacyExecutionProfile,
+  projectExecutionProfileContext,
+} from "./core/execution-profile-context.js";
+export {
+  EXECUTION_PROFILES,
+  EXECUTION_PROFILE_REQUESTS,
+  LEGACY_EXECUTION_PROFILE,
+  projectExecutionProfile,
+  resolveExecutionProfile,
+} from "./core/execution-profile.js";
 export {
   E_VERIFICATION_EXECUTION_INVALID,
   E_VERIFICATION_ISOLATION_UNAVAILABLE,