@harness-engineering/types 0.9.1 → 0.9.2

package/dist/index.d.mts

@@ -86,6 +86,24 @@ interface WorkflowResult {
     totalDurationMs: number;
 }
 
+/**
+ * Stability classification for prompt caching.
+ *
+ * - `static`    -- changes only on deploy/update (skills index, tool definitions, SKILL.md)
+ * - `session`   -- stable within a session, varies between sessions (graph context, project state)
+ * - `ephemeral` -- changes per call (tool responses, diff content, file reads)
+ */
+type StabilityTier = 'static' | 'session' | 'ephemeral';
+/**
+ * Metadata describing a content block's caching stability.
+ */
+interface StabilityMetadata {
+    /** The stability classification of this content */
+    stability: StabilityTier;
+    /** Advisory TTL hint (e.g., '1h', '5m') -- provider adapters decide actual TTL */
+    ttlHint?: string;
+}
+
 /**
  * Predefined cognitive modes for skills.
  */
@@ -106,6 +124,8 @@ interface SkillMetadata {
     description: string;
     /** The cognitive mode this skill operates in */
     cognitive_mode?: CognitiveMode;
+    /** Caching stability tier -- defaults to inferred from content type if omitted */
+    stability?: StabilityTier;
 }
 /**
  * Contextual information for a skill execution.
@@ -422,6 +442,10 @@ interface TokenUsage {
     outputTokens: number;
     /** Combined total tokens used */
     totalTokens: number;
+    /** Tokens used to create a new cache entry (provider-specific) */
+    cacheCreationTokens?: number;
+    /** Tokens read from an existing cache entry (provider-specific) */
+    cacheReadTokens?: number;
 }
 /**
  * Reference to a blocking issue.
@@ -760,6 +784,62 @@ interface SessionUsage {
     source: 'harness' | 'claude-code' | 'merged';
 }
 
+/**
+ * A single skill invocation record stored in adoption.jsonl.
+ * One line per invocation, appended by the adoption-tracker hook.
+ */
+interface SkillInvocationRecord {
+    /** Skill name (e.g., "harness-brainstorming") */
+    skill: string;
+    /** Session identifier */
+    session: string;
+    /** ISO 8601 timestamp when the skill started */
+    startedAt: string;
+    /** Duration in milliseconds */
+    duration: number;
+    /** Invocation outcome */
+    outcome: 'completed' | 'failed' | 'abandoned';
+    /** Phase names reached during the invocation */
+    phasesReached: string[];
+    /** Skill tier (1, 2, or 3). Absent when not derivable from events. */
+    tier?: number;
+    /** How the skill was triggered. Absent when not derivable from events. */
+    trigger?: string;
+}
+/**
+ * Aggregated summary for a single skill across multiple invocations.
+ */
+interface SkillAdoptionSummary {
+    /** Skill name */
+    skill: string;
+    /** Total invocation count */
+    invocations: number;
+    /** Fraction of invocations with outcome 'completed' (0-1) */
+    successRate: number;
+    /** Mean duration in milliseconds */
+    avgDuration: number;
+    /** ISO 8601 timestamp of the most recent invocation */
+    lastUsed: string;
+    /** Skill tier (absent when unknown) */
+    tier?: number;
+}
+/**
+ * Point-in-time snapshot of adoption metrics.
+ * Used by CLI commands and dashboard API.
+ */
+interface AdoptionSnapshot {
+    /** Time period: "daily", "weekly", or "all-time" */
+    period: string;
+    /** Total invocations in the period */
+    totalInvocations: number;
+    /** Count of distinct skills invoked */
+    uniqueSkills: number;
+    /** Top skills by invocation count */
+    topSkills: SkillAdoptionSummary[];
+    /** ISO 8601 timestamp when this snapshot was generated */
+    generatedAt: string;
+}
+
 /**
  * Session-scoped accumulative state types.
  *
@@ -810,4 +890,56 @@ type SessionSections = {
     [K in SessionSectionName]: SessionEntry[];
 };
 
-export { type AgentBackend, type AgentConfig, type AgentError, type AgentErrorCategory, type AgentEvent, type AgentSession, type AssignmentRecord, 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 ExternalTicket, type ExternalTicketState, type FeatureStatus, type HooksConfig, type Issue, type IssueTrackerClient, type ModelPricing, Ok, type PollingConfig, type Priority, 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 SyncResult, type TokenUsage, type TrackerConfig, type TrackerSyncConfig, type TurnContext, type TurnParams, type TurnResult, type UsageRecord, type Workflow, type WorkflowConfig, type WorkflowDefinition, type WorkflowResult, type WorkflowStep, type WorkflowStepResult, type WorkspaceConfig, isErr, isOk };
+/**
+ * Project-level telemetry configuration stored in harness.config.json.
+ * Only the on/off toggle lives here -- identity is in .harness/telemetry.json.
+ */
+interface TelemetryConfig {
+    /** Whether telemetry collection is enabled. Default: true. */
+    enabled: boolean;
+}
+/**
+ * Optional identity fields stored in .harness/telemetry.json (gitignored).
+ * Each field is independently opt-in.
+ */
+interface TelemetryIdentity {
+    project?: string;
+    team?: string;
+    alias?: string;
+}
+/**
+ * Resolved consent state after merging env vars, config, and identity file.
+ * Discriminated union: when allowed is false, no identity or installId fields exist.
+ */
+type ConsentState = {
+    allowed: true;
+    identity: TelemetryIdentity;
+    installId: string;
+} | {
+    allowed: false;
+};
+/**
+ * A single telemetry event payload for PostHog HTTP batch API.
+ */
+interface TelemetryEvent {
+    /** Event name, e.g. "skill_invocation", "session_end" */
+    event: string;
+    /** installId (anonymous) or alias (identified) */
+    distinctId: string;
+    properties: {
+        installId: string;
+        os: string;
+        nodeVersion: string;
+        harnessVersion: string;
+        skillName?: string;
+        duration?: number;
+        outcome?: 'success' | 'failure';
+        phasesReached?: string[];
+        project?: string;
+        team?: string;
+    };
+    /** ISO 8601 timestamp */
+    timestamp: string;
+}
+
+export { type AdoptionSnapshot, type AgentBackend, type AgentConfig, type AgentError, type AgentErrorCategory, type AgentEvent, type AgentSession, type AssignmentRecord, 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 ConsentState, type DailyUsage, Err, type ExternalTicket, type ExternalTicketState, type FeatureStatus, type HooksConfig, type Issue, type IssueTrackerClient, type ModelPricing, Ok, type PollingConfig, type Priority, 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 SkillAdoptionSummary, type SkillContext, type SkillError, type SkillInvocationRecord, type SkillLifecycleHooks, type SkillMetadata, type SkillResult, type StabilityMetadata, type StabilityTier, type StepOutcome, type SyncResult, type TelemetryConfig, type TelemetryEvent, type TelemetryIdentity, type TokenUsage, type TrackerConfig, type TrackerSyncConfig, 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

@@ -86,6 +86,24 @@ interface WorkflowResult {
     totalDurationMs: number;
 }
 
+/**
+ * Stability classification for prompt caching.
+ *
+ * - `static`    -- changes only on deploy/update (skills index, tool definitions, SKILL.md)
+ * - `session`   -- stable within a session, varies between sessions (graph context, project state)
+ * - `ephemeral` -- changes per call (tool responses, diff content, file reads)
+ */
+type StabilityTier = 'static' | 'session' | 'ephemeral';
+/**
+ * Metadata describing a content block's caching stability.
+ */
+interface StabilityMetadata {
+    /** The stability classification of this content */
+    stability: StabilityTier;
+    /** Advisory TTL hint (e.g., '1h', '5m') -- provider adapters decide actual TTL */
+    ttlHint?: string;
+}
+
 /**
  * Predefined cognitive modes for skills.
  */
@@ -106,6 +124,8 @@ interface SkillMetadata {
     description: string;
     /** The cognitive mode this skill operates in */
     cognitive_mode?: CognitiveMode;
+    /** Caching stability tier -- defaults to inferred from content type if omitted */
+    stability?: StabilityTier;
 }
 /**
  * Contextual information for a skill execution.
@@ -422,6 +442,10 @@ interface TokenUsage {
     outputTokens: number;
     /** Combined total tokens used */
     totalTokens: number;
+    /** Tokens used to create a new cache entry (provider-specific) */
+    cacheCreationTokens?: number;
+    /** Tokens read from an existing cache entry (provider-specific) */
+    cacheReadTokens?: number;
 }
 /**
  * Reference to a blocking issue.
@@ -760,6 +784,62 @@ interface SessionUsage {
     source: 'harness' | 'claude-code' | 'merged';
 }
 
+/**
+ * A single skill invocation record stored in adoption.jsonl.
+ * One line per invocation, appended by the adoption-tracker hook.
+ */
+interface SkillInvocationRecord {
+    /** Skill name (e.g., "harness-brainstorming") */
+    skill: string;
+    /** Session identifier */
+    session: string;
+    /** ISO 8601 timestamp when the skill started */
+    startedAt: string;
+    /** Duration in milliseconds */
+    duration: number;
+    /** Invocation outcome */
+    outcome: 'completed' | 'failed' | 'abandoned';
+    /** Phase names reached during the invocation */
+    phasesReached: string[];
+    /** Skill tier (1, 2, or 3). Absent when not derivable from events. */
+    tier?: number;
+    /** How the skill was triggered. Absent when not derivable from events. */
+    trigger?: string;
+}
+/**
+ * Aggregated summary for a single skill across multiple invocations.
+ */
+interface SkillAdoptionSummary {
+    /** Skill name */
+    skill: string;
+    /** Total invocation count */
+    invocations: number;
+    /** Fraction of invocations with outcome 'completed' (0-1) */
+    successRate: number;
+    /** Mean duration in milliseconds */
+    avgDuration: number;
+    /** ISO 8601 timestamp of the most recent invocation */
+    lastUsed: string;
+    /** Skill tier (absent when unknown) */
+    tier?: number;
+}
+/**
+ * Point-in-time snapshot of adoption metrics.
+ * Used by CLI commands and dashboard API.
+ */
+interface AdoptionSnapshot {
+    /** Time period: "daily", "weekly", or "all-time" */
+    period: string;
+    /** Total invocations in the period */
+    totalInvocations: number;
+    /** Count of distinct skills invoked */
+    uniqueSkills: number;
+    /** Top skills by invocation count */
+    topSkills: SkillAdoptionSummary[];
+    /** ISO 8601 timestamp when this snapshot was generated */
+    generatedAt: string;
+}
+
 /**
  * Session-scoped accumulative state types.
  *
@@ -810,4 +890,56 @@ type SessionSections = {
     [K in SessionSectionName]: SessionEntry[];
 };
 
-export { type AgentBackend, type AgentConfig, type AgentError, type AgentErrorCategory, type AgentEvent, type AgentSession, type AssignmentRecord, 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 ExternalTicket, type ExternalTicketState, type FeatureStatus, type HooksConfig, type Issue, type IssueTrackerClient, type ModelPricing, Ok, type PollingConfig, type Priority, 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 SyncResult, type TokenUsage, type TrackerConfig, type TrackerSyncConfig, type TurnContext, type TurnParams, type TurnResult, type UsageRecord, type Workflow, type WorkflowConfig, type WorkflowDefinition, type WorkflowResult, type WorkflowStep, type WorkflowStepResult, type WorkspaceConfig, isErr, isOk };
+/**
+ * Project-level telemetry configuration stored in harness.config.json.
+ * Only the on/off toggle lives here -- identity is in .harness/telemetry.json.
+ */
+interface TelemetryConfig {
+    /** Whether telemetry collection is enabled. Default: true. */
+    enabled: boolean;
+}
+/**
+ * Optional identity fields stored in .harness/telemetry.json (gitignored).
+ * Each field is independently opt-in.
+ */
+interface TelemetryIdentity {
+    project?: string;
+    team?: string;
+    alias?: string;
+}
+/**
+ * Resolved consent state after merging env vars, config, and identity file.
+ * Discriminated union: when allowed is false, no identity or installId fields exist.
+ */
+type ConsentState = {
+    allowed: true;
+    identity: TelemetryIdentity;
+    installId: string;
+} | {
+    allowed: false;
+};
+/**
+ * A single telemetry event payload for PostHog HTTP batch API.
+ */
+interface TelemetryEvent {
+    /** Event name, e.g. "skill_invocation", "session_end" */
+    event: string;
+    /** installId (anonymous) or alias (identified) */
+    distinctId: string;
+    properties: {
+        installId: string;
+        os: string;
+        nodeVersion: string;
+        harnessVersion: string;
+        skillName?: string;
+        duration?: number;
+        outcome?: 'success' | 'failure';
+        phasesReached?: string[];
+        project?: string;
+        team?: string;
+    };
+    /** ISO 8601 timestamp */
+    timestamp: string;
+}
+
+export { type AdoptionSnapshot, type AgentBackend, type AgentConfig, type AgentError, type AgentErrorCategory, type AgentEvent, type AgentSession, type AssignmentRecord, 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 ConsentState, type DailyUsage, Err, type ExternalTicket, type ExternalTicketState, type FeatureStatus, type HooksConfig, type Issue, type IssueTrackerClient, type ModelPricing, Ok, type PollingConfig, type Priority, 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 SkillAdoptionSummary, type SkillContext, type SkillError, type SkillInvocationRecord, type SkillLifecycleHooks, type SkillMetadata, type SkillResult, type StabilityMetadata, type StabilityTier, type StepOutcome, type SyncResult, type TelemetryConfig, type TelemetryEvent, type TelemetryIdentity, type TokenUsage, type TrackerConfig, type TrackerSyncConfig, 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.9.1",
+  "version": "0.9.2",
   "description": "TypeScript types and interfaces for Harness Engineering",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",