@harness-engineering/types 0.5.0 → 0.6.0

package/README.md

@@ -63,6 +63,26 @@ Type guard to check if Result is Ok.
 
 Type guard to check if Result is Err.
 
+### `UsageRecord`
+
+Extended token usage entry for cost tracking. Composes `TokenUsage` with session metadata, cache token counts, model identifier, and cost in integer microdollars.
+
+```typescript
+import type { UsageRecord } from '@harness-engineering/types';
+```
+
+### `ModelPricing`
+
+Per-model pricing rates in USD per 1 million tokens. Includes input, output, and optional cache read/write rates.
+
+```typescript
+import type { ModelPricing } from '@harness-engineering/types';
+```
+
+### `DailyUsage` / `SessionUsage`
+
+Aggregated usage views for daily trends and per-session breakdowns. Used by `harness usage` CLI commands.
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -1,53 +1,3 @@
-/**
- * Session-scoped accumulative state types.
- *
- * Session memory allows skills to append to shared sections (terminology,
- * decisions, constraints, risks, openQuestions, evidence) rather than
- * overwriting. Each entry is timestamped and tagged with the authoring skill.
- *
- * @see docs/changes/ai-foundations-integration/proposal.md
- */
-/**
- * Names of accumulative session sections.
- * Runtime array used for iteration and validation.
- */
-declare const SESSION_SECTION_NAMES: readonly ["terminology", "decisions", "constraints", "risks", "openQuestions", "evidence"];
-/**
- * Union type of valid session section names.
- */
-type SessionSectionName = (typeof SESSION_SECTION_NAMES)[number];
-/**
- * Lifecycle status of a session entry.
- * - `active` — current and relevant
- * - `resolved` — addressed or answered (e.g., an open question that was resolved)
- * - `superseded` — replaced by a newer entry
- */
-type SessionEntryStatus = 'active' | 'resolved' | 'superseded';
-/**
- * A single entry in a session section.
- * Entries are append-only; skills mark them as `resolved` or `superseded`
- * rather than deleting.
- */
-interface SessionEntry {
-    /** Auto-generated unique identifier */
-    id: string;
-    /** ISO 8601 timestamp of when the entry was created */
-    timestamp: string;
-    /** Name of the skill that authored this entry */
-    authorSkill: string;
-    /** The entry content (free-form text) */
-    content: string;
-    /** Lifecycle status of the entry */
-    status: SessionEntryStatus;
-}
-/**
- * Container mapping each section name to its array of entries.
- * Used as the shape of session-scoped state in `state.json`.
- */
-type SessionSections = {
-    [K in SessionSectionName]: SessionEntry[];
-};
-
 /**
  * Token usage statistics for an agent turn or session.
  */
@@ -320,6 +270,132 @@ interface WorkflowDefinition {
     promptTemplate: string;
 }
 
+/**
+ * Extended entry for cost tracking storage and display.
+ * Composes TokenUsage — does not extend it.
+ */
+interface UsageRecord {
+    /** Harness session identifier */
+    sessionId: string;
+    /** ISO 8601 timestamp of the usage event */
+    timestamp: string;
+    /** Token counts for this event */
+    tokens: TokenUsage;
+    /** Tokens used to create prompt cache entries */
+    cacheCreationTokens?: number;
+    /** Tokens read from prompt cache */
+    cacheReadTokens?: number;
+    /** Model identifier (e.g., "claude-sonnet-4-20250514") */
+    model?: string;
+    /** Cost in integer microdollars (USD * 1,000,000), calculated at read time */
+    costMicroUSD?: number;
+}
+/**
+ * Per-model pricing rates, all in USD per 1 million tokens.
+ */
+interface ModelPricing {
+    /** Input token cost per 1M tokens */
+    inputPer1M: number;
+    /** Output token cost per 1M tokens */
+    outputPer1M: number;
+    /** Cache read cost per 1M tokens (not all models support caching) */
+    cacheReadPer1M?: number;
+    /** Cache write/creation cost per 1M tokens */
+    cacheWritePer1M?: number;
+}
+/**
+ * Aggregated usage for a single calendar day.
+ */
+interface DailyUsage {
+    /** ISO 8601 date string (YYYY-MM-DD) */
+    date: string;
+    /** Number of distinct sessions that had activity on this day */
+    sessionCount: number;
+    /** Summed token counts across all sessions */
+    tokens: TokenUsage;
+    /** Summed cache creation tokens (omitted if no cache data) */
+    cacheCreationTokens?: number;
+    /** Summed cache read tokens (omitted if no cache data) */
+    cacheReadTokens?: number;
+    /** Total cost in integer microdollars, null if any session has unknown pricing */
+    costMicroUSD: number | null;
+    /** Distinct model identifiers seen on this day */
+    models: string[];
+}
+/**
+ * Aggregated usage for a single session across all its turns.
+ */
+interface SessionUsage {
+    /** Harness session identifier */
+    sessionId: string;
+    /** ISO 8601 timestamp of the first event in this session */
+    firstTimestamp: string;
+    /** ISO 8601 timestamp of the last event in this session */
+    lastTimestamp: string;
+    /** Summed token counts across all turns */
+    tokens: TokenUsage;
+    /** Summed cache creation tokens (omitted if no cache data) */
+    cacheCreationTokens?: number;
+    /** Summed cache read tokens (omitted if no cache data) */
+    cacheReadTokens?: number;
+    /** Model identifier (may be populated from CC data) */
+    model?: string;
+    /** Total cost in integer microdollars, null if pricing unavailable */
+    costMicroUSD: number | null;
+    /** Data source: 'harness', 'claude-code', or 'merged' */
+    source: 'harness' | 'claude-code' | 'merged';
+}
+
+/**
+ * Session-scoped accumulative state types.
+ *
+ * Session memory allows skills to append to shared sections (terminology,
+ * decisions, constraints, risks, openQuestions, evidence) rather than
+ * overwriting. Each entry is timestamped and tagged with the authoring skill.
+ *
+ * @see docs/changes/ai-foundations-integration/proposal.md
+ */
+/**
+ * Names of accumulative session sections.
+ * Runtime array used for iteration and validation.
+ */
+declare const SESSION_SECTION_NAMES: readonly ["terminology", "decisions", "constraints", "risks", "openQuestions", "evidence"];
+/**
+ * Union type of valid session section names.
+ */
+type SessionSectionName = (typeof SESSION_SECTION_NAMES)[number];
+/**
+ * Lifecycle status of a session entry.
+ * - `active` — current and relevant
+ * - `resolved` — addressed or answered (e.g., an open question that was resolved)
+ * - `superseded` — replaced by a newer entry
+ */
+type SessionEntryStatus = 'active' | 'resolved' | 'superseded';
+/**
+ * A single entry in a session section.
+ * Entries are append-only; skills mark them as `resolved` or `superseded`
+ * rather than deleting.
+ */
+interface SessionEntry {
+    /** Auto-generated unique identifier */
+    id: string;
+    /** ISO 8601 timestamp of when the entry was created */
+    timestamp: string;
+    /** Name of the skill that authored this entry */
+    authorSkill: string;
+    /** The entry content (free-form text) */
+    content: string;
+    /** Lifecycle status of the entry */
+    status: SessionEntryStatus;
+}
+/**
+ * Container mapping each section name to its array of entries.
+ * Used as the shape of session-scoped state in `state.json`.
+ */
+type SessionSections = {
+    [K in SessionSectionName]: SessionEntry[];
+};
+
 /**
  * @harness-engineering/types
  *
@@ -643,4 +719,4 @@ interface Roadmap {
     milestones: RoadmapMilestone[];
 }
 
-export { type AgentBackend, type AgentConfig, type AgentError, type AgentErrorCategory, type AgentEvent, type AgentSession, type BlockerRef, type CICheckIssue, type CICheckName, type CICheckOptions, type CICheckReport, type CICheckResult, type CICheckStatus, type CICheckSummary, type CIFailOnSeverity, type CIInitOptions, type CIPlatform, type CognitiveMode, Err, type FeatureStatus, type HooksConfig, type Issue, type IssueTrackerClient, Ok, type PollingConfig, type Result, type Roadmap, type RoadmapFeature, type RoadmapFrontmatter, type RoadmapMilestone, SESSION_SECTION_NAMES, STANDARD_COGNITIVE_MODES, type ServerConfig, type SessionEntry, type SessionEntryStatus, type SessionSectionName, type SessionSections, type SessionStartParams, type SkillContext, type SkillError, type SkillLifecycleHooks, type SkillMetadata, type SkillResult, type StepOutcome, type TokenUsage, type TrackerConfig, type TurnContext, type TurnParams, type TurnResult, type Workflow, type WorkflowConfig, type WorkflowDefinition, type WorkflowResult, type WorkflowStep, type WorkflowStepResult, type WorkspaceConfig, isErr, isOk };
+export { type AgentBackend, type AgentConfig, type AgentError, type AgentErrorCategory, type AgentEvent, type AgentSession, type BlockerRef, type CICheckIssue, type CICheckName, type CICheckOptions, type CICheckReport, type CICheckResult, type CICheckStatus, type CICheckSummary, type CIFailOnSeverity, type CIInitOptions, type CIPlatform, type CognitiveMode, type DailyUsage, Err, type FeatureStatus, type HooksConfig, type Issue, type IssueTrackerClient, type ModelPricing, Ok, type PollingConfig, type Result, type Roadmap, type RoadmapFeature, type RoadmapFrontmatter, type RoadmapMilestone, SESSION_SECTION_NAMES, STANDARD_COGNITIVE_MODES, type ServerConfig, type SessionEntry, type SessionEntryStatus, type SessionSectionName, type SessionSections, type SessionStartParams, type SessionUsage, type SkillContext, type SkillError, type SkillLifecycleHooks, type SkillMetadata, type SkillResult, type StepOutcome, type TokenUsage, type TrackerConfig, type TurnContext, type TurnParams, type TurnResult, type UsageRecord, type Workflow, type WorkflowConfig, type WorkflowDefinition, type WorkflowResult, type WorkflowStep, type WorkflowStepResult, type WorkspaceConfig, isErr, isOk };

package/dist/index.d.ts

@@ -1,53 +1,3 @@
-/**
- * Session-scoped accumulative state types.
- *
- * Session memory allows skills to append to shared sections (terminology,
- * decisions, constraints, risks, openQuestions, evidence) rather than
- * overwriting. Each entry is timestamped and tagged with the authoring skill.
- *
- * @see docs/changes/ai-foundations-integration/proposal.md
- */
-/**
- * Names of accumulative session sections.
- * Runtime array used for iteration and validation.
- */
-declare const SESSION_SECTION_NAMES: readonly ["terminology", "decisions", "constraints", "risks", "openQuestions", "evidence"];
-/**
- * Union type of valid session section names.
- */
-type SessionSectionName = (typeof SESSION_SECTION_NAMES)[number];
-/**
- * Lifecycle status of a session entry.
- * - `active` — current and relevant
- * - `resolved` — addressed or answered (e.g., an open question that was resolved)
- * - `superseded` — replaced by a newer entry
- */
-type SessionEntryStatus = 'active' | 'resolved' | 'superseded';
-/**
- * A single entry in a session section.
- * Entries are append-only; skills mark them as `resolved` or `superseded`
- * rather than deleting.
- */
-interface SessionEntry {
-    /** Auto-generated unique identifier */
-    id: string;
-    /** ISO 8601 timestamp of when the entry was created */
-    timestamp: string;
-    /** Name of the skill that authored this entry */
-    authorSkill: string;
-    /** The entry content (free-form text) */
-    content: string;
-    /** Lifecycle status of the entry */
-    status: SessionEntryStatus;
-}
-/**
- * Container mapping each section name to its array of entries.
- * Used as the shape of session-scoped state in `state.json`.
- */
-type SessionSections = {
-    [K in SessionSectionName]: SessionEntry[];
-};
-
 /**
  * Token usage statistics for an agent turn or session.
  */
@@ -320,6 +270,132 @@ interface WorkflowDefinition {
     promptTemplate: string;
 }
 
+/**
+ * Extended entry for cost tracking storage and display.
+ * Composes TokenUsage — does not extend it.
+ */
+interface UsageRecord {
+    /** Harness session identifier */
+    sessionId: string;
+    /** ISO 8601 timestamp of the usage event */
+    timestamp: string;
+    /** Token counts for this event */
+    tokens: TokenUsage;
+    /** Tokens used to create prompt cache entries */
+    cacheCreationTokens?: number;
+    /** Tokens read from prompt cache */
+    cacheReadTokens?: number;
+    /** Model identifier (e.g., "claude-sonnet-4-20250514") */
+    model?: string;
+    /** Cost in integer microdollars (USD * 1,000,000), calculated at read time */
+    costMicroUSD?: number;
+}
+/**
+ * Per-model pricing rates, all in USD per 1 million tokens.
+ */
+interface ModelPricing {
+    /** Input token cost per 1M tokens */
+    inputPer1M: number;
+    /** Output token cost per 1M tokens */
+    outputPer1M: number;
+    /** Cache read cost per 1M tokens (not all models support caching) */
+    cacheReadPer1M?: number;
+    /** Cache write/creation cost per 1M tokens */
+    cacheWritePer1M?: number;
+}
+/**
+ * Aggregated usage for a single calendar day.
+ */
+interface DailyUsage {
+    /** ISO 8601 date string (YYYY-MM-DD) */
+    date: string;
+    /** Number of distinct sessions that had activity on this day */
+    sessionCount: number;
+    /** Summed token counts across all sessions */
+    tokens: TokenUsage;
+    /** Summed cache creation tokens (omitted if no cache data) */
+    cacheCreationTokens?: number;
+    /** Summed cache read tokens (omitted if no cache data) */
+    cacheReadTokens?: number;
+    /** Total cost in integer microdollars, null if any session has unknown pricing */
+    costMicroUSD: number | null;
+    /** Distinct model identifiers seen on this day */
+    models: string[];
+}
+/**
+ * Aggregated usage for a single session across all its turns.
+ */
+interface SessionUsage {
+    /** Harness session identifier */
+    sessionId: string;
+    /** ISO 8601 timestamp of the first event in this session */
+    firstTimestamp: string;
+    /** ISO 8601 timestamp of the last event in this session */
+    lastTimestamp: string;
+    /** Summed token counts across all turns */
+    tokens: TokenUsage;
+    /** Summed cache creation tokens (omitted if no cache data) */
+    cacheCreationTokens?: number;
+    /** Summed cache read tokens (omitted if no cache data) */
+    cacheReadTokens?: number;
+    /** Model identifier (may be populated from CC data) */
+    model?: string;
+    /** Total cost in integer microdollars, null if pricing unavailable */
+    costMicroUSD: number | null;
+    /** Data source: 'harness', 'claude-code', or 'merged' */
+    source: 'harness' | 'claude-code' | 'merged';
+}
+
+/**
+ * Session-scoped accumulative state types.
+ *
+ * Session memory allows skills to append to shared sections (terminology,
+ * decisions, constraints, risks, openQuestions, evidence) rather than
+ * overwriting. Each entry is timestamped and tagged with the authoring skill.
+ *
+ * @see docs/changes/ai-foundations-integration/proposal.md
+ */
+/**
+ * Names of accumulative session sections.
+ * Runtime array used for iteration and validation.
+ */
+declare const SESSION_SECTION_NAMES: readonly ["terminology", "decisions", "constraints", "risks", "openQuestions", "evidence"];
+/**
+ * Union type of valid session section names.
+ */
+type SessionSectionName = (typeof SESSION_SECTION_NAMES)[number];
+/**
+ * Lifecycle status of a session entry.
+ * - `active` — current and relevant
+ * - `resolved` — addressed or answered (e.g., an open question that was resolved)
+ * - `superseded` — replaced by a newer entry
+ */
+type SessionEntryStatus = 'active' | 'resolved' | 'superseded';
+/**
+ * A single entry in a session section.
+ * Entries are append-only; skills mark them as `resolved` or `superseded`
+ * rather than deleting.
+ */
+interface SessionEntry {
+    /** Auto-generated unique identifier */
+    id: string;
+    /** ISO 8601 timestamp of when the entry was created */
+    timestamp: string;
+    /** Name of the skill that authored this entry */
+    authorSkill: string;
+    /** The entry content (free-form text) */
+    content: string;
+    /** Lifecycle status of the entry */
+    status: SessionEntryStatus;
+}
+/**
+ * Container mapping each section name to its array of entries.
+ * Used as the shape of session-scoped state in `state.json`.
+ */
+type SessionSections = {
+    [K in SessionSectionName]: SessionEntry[];
+};
+
 /**
  * @harness-engineering/types
  *
@@ -643,4 +719,4 @@ interface Roadmap {
     milestones: RoadmapMilestone[];
 }
 
-export { type AgentBackend, type AgentConfig, type AgentError, type AgentErrorCategory, type AgentEvent, type AgentSession, type BlockerRef, type CICheckIssue, type CICheckName, type CICheckOptions, type CICheckReport, type CICheckResult, type CICheckStatus, type CICheckSummary, type CIFailOnSeverity, type CIInitOptions, type CIPlatform, type CognitiveMode, Err, type FeatureStatus, type HooksConfig, type Issue, type IssueTrackerClient, Ok, type PollingConfig, type Result, type Roadmap, type RoadmapFeature, type RoadmapFrontmatter, type RoadmapMilestone, SESSION_SECTION_NAMES, STANDARD_COGNITIVE_MODES, type ServerConfig, type SessionEntry, type SessionEntryStatus, type SessionSectionName, type SessionSections, type SessionStartParams, type SkillContext, type SkillError, type SkillLifecycleHooks, type SkillMetadata, type SkillResult, type StepOutcome, type TokenUsage, type TrackerConfig, type TurnContext, type TurnParams, type TurnResult, type Workflow, type WorkflowConfig, type WorkflowDefinition, type WorkflowResult, type WorkflowStep, type WorkflowStepResult, type WorkspaceConfig, isErr, isOk };
+export { type AgentBackend, type AgentConfig, type AgentError, type AgentErrorCategory, type AgentEvent, type AgentSession, type BlockerRef, type CICheckIssue, type CICheckName, type CICheckOptions, type CICheckReport, type CICheckResult, type CICheckStatus, type CICheckSummary, type CIFailOnSeverity, type CIInitOptions, type CIPlatform, type CognitiveMode, type DailyUsage, Err, type FeatureStatus, type HooksConfig, type Issue, type IssueTrackerClient, type ModelPricing, Ok, type PollingConfig, type Result, type Roadmap, type RoadmapFeature, type RoadmapFrontmatter, type RoadmapMilestone, SESSION_SECTION_NAMES, STANDARD_COGNITIVE_MODES, type ServerConfig, type SessionEntry, type SessionEntryStatus, type SessionSectionName, type SessionSections, type SessionStartParams, type SessionUsage, type SkillContext, type SkillError, type SkillLifecycleHooks, type SkillMetadata, type SkillResult, type StepOutcome, type TokenUsage, type TrackerConfig, type TurnContext, type TurnParams, type TurnResult, type UsageRecord, type Workflow, type WorkflowConfig, type WorkflowDefinition, type WorkflowResult, type WorkflowStep, type WorkflowStepResult, type WorkspaceConfig, isErr, isOk };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harness-engineering/types",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "TypeScript types and interfaces for Harness Engineering",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",