@harness-engineering/types 0.5.0 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +20 -0
- package/dist/index.d.mts +211 -45
- package/dist/index.d.ts +211 -45
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -63,6 +63,26 @@ Type guard to check if Result is Ok.
|
|
|
63
63
|
|
|
64
64
|
Type guard to check if Result is Err.
|
|
65
65
|
|
|
66
|
+
### `UsageRecord`
|
|
67
|
+
|
|
68
|
+
Extended token usage entry for cost tracking. Composes `TokenUsage` with session metadata, cache token counts, model identifier, and cost in integer microdollars.
|
|
69
|
+
|
|
70
|
+
```typescript
|
|
71
|
+
import type { UsageRecord } from '@harness-engineering/types';
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
### `ModelPricing`
|
|
75
|
+
|
|
76
|
+
Per-model pricing rates in USD per 1 million tokens. Includes input, output, and optional cache read/write rates.
|
|
77
|
+
|
|
78
|
+
```typescript
|
|
79
|
+
import type { ModelPricing } from '@harness-engineering/types';
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
### `DailyUsage` / `SessionUsage`
|
|
83
|
+
|
|
84
|
+
Aggregated usage views for daily trends and per-session breakdowns. Used by `harness usage` CLI commands.
|
|
85
|
+
|
|
66
86
|
## License
|
|
67
87
|
|
|
68
88
|
MIT
|
package/dist/index.d.mts
CHANGED
|
@@ -1,52 +1,65 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
*
|
|
4
|
-
* Session memory allows skills to append to shared sections (terminology,
|
|
5
|
-
* decisions, constraints, risks, openQuestions, evidence) rather than
|
|
6
|
-
* overwriting. Each entry is timestamped and tagged with the authoring skill.
|
|
7
|
-
*
|
|
8
|
-
* @see docs/changes/ai-foundations-integration/proposal.md
|
|
9
|
-
*/
|
|
10
|
-
/**
|
|
11
|
-
* Names of accumulative session sections.
|
|
12
|
-
* Runtime array used for iteration and validation.
|
|
13
|
-
*/
|
|
14
|
-
declare const SESSION_SECTION_NAMES: readonly ["terminology", "decisions", "constraints", "risks", "openQuestions", "evidence"];
|
|
15
|
-
/**
|
|
16
|
-
* Union type of valid session section names.
|
|
17
|
-
*/
|
|
18
|
-
type SessionSectionName = (typeof SESSION_SECTION_NAMES)[number];
|
|
19
|
-
/**
|
|
20
|
-
* Lifecycle status of a session entry.
|
|
21
|
-
* - `active` — current and relevant
|
|
22
|
-
* - `resolved` — addressed or answered (e.g., an open question that was resolved)
|
|
23
|
-
* - `superseded` — replaced by a newer entry
|
|
24
|
-
*/
|
|
25
|
-
type SessionEntryStatus = 'active' | 'resolved' | 'superseded';
|
|
26
|
-
/**
|
|
27
|
-
* A single entry in a session section.
|
|
28
|
-
* Entries are append-only; skills mark them as `resolved` or `superseded`
|
|
29
|
-
* rather than deleting.
|
|
2
|
+
* Represents a ticket created in an external tracking service.
|
|
30
3
|
*/
|
|
31
|
-
interface
|
|
32
|
-
/**
|
|
33
|
-
|
|
34
|
-
/**
|
|
35
|
-
|
|
36
|
-
/** Name of the skill that authored this entry */
|
|
37
|
-
authorSkill: string;
|
|
38
|
-
/** The entry content (free-form text) */
|
|
39
|
-
content: string;
|
|
40
|
-
/** Lifecycle status of the entry */
|
|
41
|
-
status: SessionEntryStatus;
|
|
4
|
+
interface ExternalTicket {
|
|
5
|
+
/** External identifier, e.g., "github:owner/repo#42" */
|
|
6
|
+
externalId: string;
|
|
7
|
+
/** URL to the ticket in the external service */
|
|
8
|
+
url: string;
|
|
42
9
|
}
|
|
43
10
|
/**
|
|
44
|
-
*
|
|
45
|
-
*
|
|
11
|
+
* Current state of a ticket in the external service.
|
|
12
|
+
* Pulled during syncFromExternal.
|
|
46
13
|
*/
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
14
|
+
interface ExternalTicketState {
|
|
15
|
+
/** External identifier */
|
|
16
|
+
externalId: string;
|
|
17
|
+
/** External status (e.g., "open", "closed") */
|
|
18
|
+
status: string;
|
|
19
|
+
/** External labels (used for status disambiguation on GitHub) */
|
|
20
|
+
labels: string[];
|
|
21
|
+
/** Current assignee in the external service, or null */
|
|
22
|
+
assignee: string | null;
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* Result of a sync operation. Collects successes and errors per-feature.
|
|
26
|
+
*/
|
|
27
|
+
interface SyncResult {
|
|
28
|
+
/** Tickets created during this sync */
|
|
29
|
+
created: ExternalTicket[];
|
|
30
|
+
/** External IDs of tickets that were updated */
|
|
31
|
+
updated: string[];
|
|
32
|
+
/** Assignment changes detected during pull */
|
|
33
|
+
assignmentChanges: Array<{
|
|
34
|
+
feature: string;
|
|
35
|
+
from: string | null;
|
|
36
|
+
to: string | null;
|
|
37
|
+
}>;
|
|
38
|
+
/** Per-feature errors (sync never throws) */
|
|
39
|
+
errors: Array<{
|
|
40
|
+
featureOrId: string;
|
|
41
|
+
error: Error;
|
|
42
|
+
}>;
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* Configuration for external tracker sync.
|
|
46
|
+
*/
|
|
47
|
+
interface TrackerSyncConfig {
|
|
48
|
+
/** Adapter kind -- narrowed to GitHub-only for now */
|
|
49
|
+
kind: 'github';
|
|
50
|
+
/** Repository in "owner/repo" format (for GitHub) */
|
|
51
|
+
repo?: string;
|
|
52
|
+
/** Labels auto-applied to created tickets for filtering + identification */
|
|
53
|
+
labels?: string[];
|
|
54
|
+
/** Maps roadmap status -> external status string */
|
|
55
|
+
statusMap: Record<FeatureStatus, string>;
|
|
56
|
+
/**
|
|
57
|
+
* Maps external status (+ optional label) -> roadmap status.
|
|
58
|
+
* Compound keys like "open:in-progress" express state + label.
|
|
59
|
+
* Optional — when absent, syncFromExternal preserves current roadmap status.
|
|
60
|
+
*/
|
|
61
|
+
reverseStatusMap?: Record<string, FeatureStatus>;
|
|
62
|
+
}
|
|
50
63
|
|
|
51
64
|
/**
|
|
52
65
|
* Token usage statistics for an agent turn or session.
|
|
@@ -320,6 +333,132 @@ interface WorkflowDefinition {
|
|
|
320
333
|
promptTemplate: string;
|
|
321
334
|
}
|
|
322
335
|
|
|
336
|
+
/**
|
|
337
|
+
* Extended entry for cost tracking storage and display.
|
|
338
|
+
* Composes TokenUsage — does not extend it.
|
|
339
|
+
*/
|
|
340
|
+
interface UsageRecord {
|
|
341
|
+
/** Harness session identifier */
|
|
342
|
+
sessionId: string;
|
|
343
|
+
/** ISO 8601 timestamp of the usage event */
|
|
344
|
+
timestamp: string;
|
|
345
|
+
/** Token counts for this event */
|
|
346
|
+
tokens: TokenUsage;
|
|
347
|
+
/** Tokens used to create prompt cache entries */
|
|
348
|
+
cacheCreationTokens?: number;
|
|
349
|
+
/** Tokens read from prompt cache */
|
|
350
|
+
cacheReadTokens?: number;
|
|
351
|
+
/** Model identifier (e.g., "claude-sonnet-4-20250514") */
|
|
352
|
+
model?: string;
|
|
353
|
+
/** Cost in integer microdollars (USD * 1,000,000), calculated at read time */
|
|
354
|
+
costMicroUSD?: number;
|
|
355
|
+
}
|
|
356
|
+
/**
|
|
357
|
+
* Per-model pricing rates, all in USD per 1 million tokens.
|
|
358
|
+
*/
|
|
359
|
+
interface ModelPricing {
|
|
360
|
+
/** Input token cost per 1M tokens */
|
|
361
|
+
inputPer1M: number;
|
|
362
|
+
/** Output token cost per 1M tokens */
|
|
363
|
+
outputPer1M: number;
|
|
364
|
+
/** Cache read cost per 1M tokens (not all models support caching) */
|
|
365
|
+
cacheReadPer1M?: number;
|
|
366
|
+
/** Cache write/creation cost per 1M tokens */
|
|
367
|
+
cacheWritePer1M?: number;
|
|
368
|
+
}
|
|
369
|
+
/**
|
|
370
|
+
* Aggregated usage for a single calendar day.
|
|
371
|
+
*/
|
|
372
|
+
interface DailyUsage {
|
|
373
|
+
/** ISO 8601 date string (YYYY-MM-DD) */
|
|
374
|
+
date: string;
|
|
375
|
+
/** Number of distinct sessions that had activity on this day */
|
|
376
|
+
sessionCount: number;
|
|
377
|
+
/** Summed token counts across all sessions */
|
|
378
|
+
tokens: TokenUsage;
|
|
379
|
+
/** Summed cache creation tokens (omitted if no cache data) */
|
|
380
|
+
cacheCreationTokens?: number;
|
|
381
|
+
/** Summed cache read tokens (omitted if no cache data) */
|
|
382
|
+
cacheReadTokens?: number;
|
|
383
|
+
/** Total cost in integer microdollars, null if any session has unknown pricing */
|
|
384
|
+
costMicroUSD: number | null;
|
|
385
|
+
/** Distinct model identifiers seen on this day */
|
|
386
|
+
models: string[];
|
|
387
|
+
}
|
|
388
|
+
/**
|
|
389
|
+
* Aggregated usage for a single session across all its turns.
|
|
390
|
+
*/
|
|
391
|
+
interface SessionUsage {
|
|
392
|
+
/** Harness session identifier */
|
|
393
|
+
sessionId: string;
|
|
394
|
+
/** ISO 8601 timestamp of the first event in this session */
|
|
395
|
+
firstTimestamp: string;
|
|
396
|
+
/** ISO 8601 timestamp of the last event in this session */
|
|
397
|
+
lastTimestamp: string;
|
|
398
|
+
/** Summed token counts across all turns */
|
|
399
|
+
tokens: TokenUsage;
|
|
400
|
+
/** Summed cache creation tokens (omitted if no cache data) */
|
|
401
|
+
cacheCreationTokens?: number;
|
|
402
|
+
/** Summed cache read tokens (omitted if no cache data) */
|
|
403
|
+
cacheReadTokens?: number;
|
|
404
|
+
/** Model identifier (may be populated from CC data) */
|
|
405
|
+
model?: string;
|
|
406
|
+
/** Total cost in integer microdollars, null if pricing unavailable */
|
|
407
|
+
costMicroUSD: number | null;
|
|
408
|
+
/** Data source: 'harness', 'claude-code', or 'merged' */
|
|
409
|
+
source: 'harness' | 'claude-code' | 'merged';
|
|
410
|
+
}
|
|
411
|
+
|
|
412
|
+
/**
|
|
413
|
+
* Session-scoped accumulative state types.
|
|
414
|
+
*
|
|
415
|
+
* Session memory allows skills to append to shared sections (terminology,
|
|
416
|
+
* decisions, constraints, risks, openQuestions, evidence) rather than
|
|
417
|
+
* overwriting. Each entry is timestamped and tagged with the authoring skill.
|
|
418
|
+
*
|
|
419
|
+
* @see docs/changes/ai-foundations-integration/proposal.md
|
|
420
|
+
*/
|
|
421
|
+
/**
|
|
422
|
+
* Names of accumulative session sections.
|
|
423
|
+
* Runtime array used for iteration and validation.
|
|
424
|
+
*/
|
|
425
|
+
declare const SESSION_SECTION_NAMES: readonly ["terminology", "decisions", "constraints", "risks", "openQuestions", "evidence"];
|
|
426
|
+
/**
|
|
427
|
+
* Union type of valid session section names.
|
|
428
|
+
*/
|
|
429
|
+
type SessionSectionName = (typeof SESSION_SECTION_NAMES)[number];
|
|
430
|
+
/**
|
|
431
|
+
* Lifecycle status of a session entry.
|
|
432
|
+
* - `active` — current and relevant
|
|
433
|
+
* - `resolved` — addressed or answered (e.g., an open question that was resolved)
|
|
434
|
+
* - `superseded` — replaced by a newer entry
|
|
435
|
+
*/
|
|
436
|
+
type SessionEntryStatus = 'active' | 'resolved' | 'superseded';
|
|
437
|
+
/**
|
|
438
|
+
* A single entry in a session section.
|
|
439
|
+
* Entries are append-only; skills mark them as `resolved` or `superseded`
|
|
440
|
+
* rather than deleting.
|
|
441
|
+
*/
|
|
442
|
+
interface SessionEntry {
|
|
443
|
+
/** Auto-generated unique identifier */
|
|
444
|
+
id: string;
|
|
445
|
+
/** ISO 8601 timestamp of when the entry was created */
|
|
446
|
+
timestamp: string;
|
|
447
|
+
/** Name of the skill that authored this entry */
|
|
448
|
+
authorSkill: string;
|
|
449
|
+
/** The entry content (free-form text) */
|
|
450
|
+
content: string;
|
|
451
|
+
/** Lifecycle status of the entry */
|
|
452
|
+
status: SessionEntryStatus;
|
|
453
|
+
}
|
|
454
|
+
/**
|
|
455
|
+
* Container mapping each section name to its array of entries.
|
|
456
|
+
* Used as the shape of session-scoped state in `state.json`.
|
|
457
|
+
*/
|
|
458
|
+
type SessionSections = {
|
|
459
|
+
[K in SessionSectionName]: SessionEntry[];
|
|
460
|
+
};
|
|
461
|
+
|
|
323
462
|
/**
|
|
324
463
|
* @harness-engineering/types
|
|
325
464
|
*
|
|
@@ -587,6 +726,11 @@ interface SkillLifecycleHooks {
|
|
|
587
726
|
* Valid statuses for a roadmap feature.
|
|
588
727
|
*/
|
|
589
728
|
type FeatureStatus = 'backlog' | 'planned' | 'in-progress' | 'done' | 'blocked';
|
|
729
|
+
/**
|
|
730
|
+
* Priority override levels for roadmap features.
|
|
731
|
+
* When present, priority replaces positional ordering as the primary sort key.
|
|
732
|
+
*/
|
|
733
|
+
type Priority = 'P0' | 'P1' | 'P2' | 'P3';
|
|
590
734
|
/**
|
|
591
735
|
* A feature entry in the project roadmap.
|
|
592
736
|
*/
|
|
@@ -603,6 +747,12 @@ interface RoadmapFeature {
|
|
|
603
747
|
blockedBy: string[];
|
|
604
748
|
/** One-line summary */
|
|
605
749
|
summary: string;
|
|
750
|
+
/** GitHub username, email, or display name — null if unassigned */
|
|
751
|
+
assignee: string | null;
|
|
752
|
+
/** Optional priority override — null uses positional ordering */
|
|
753
|
+
priority: Priority | null;
|
|
754
|
+
/** External tracker ID (e.g., "github:owner/repo#42") — null if not synced */
|
|
755
|
+
externalId: string | null;
|
|
606
756
|
}
|
|
607
757
|
/**
|
|
608
758
|
* A milestone grouping in the roadmap. The special "Backlog" milestone
|
|
@@ -616,6 +766,20 @@ interface RoadmapMilestone {
|
|
|
616
766
|
/** Features in this milestone, in document order */
|
|
617
767
|
features: RoadmapFeature[];
|
|
618
768
|
}
|
|
769
|
+
/**
|
|
770
|
+
* A single record in the assignment history log.
|
|
771
|
+
* Reassignment produces two records: 'unassigned' for previous, 'assigned' for new.
|
|
772
|
+
*/
|
|
773
|
+
interface AssignmentRecord {
|
|
774
|
+
/** Feature name */
|
|
775
|
+
feature: string;
|
|
776
|
+
/** Assignee identifier (username, email, or display name) */
|
|
777
|
+
assignee: string;
|
|
778
|
+
/** What happened */
|
|
779
|
+
action: 'assigned' | 'completed' | 'unassigned';
|
|
780
|
+
/** ISO date string (YYYY-MM-DD) */
|
|
781
|
+
date: string;
|
|
782
|
+
}
|
|
619
783
|
/**
|
|
620
784
|
* YAML frontmatter of the roadmap file.
|
|
621
785
|
*/
|
|
@@ -641,6 +805,8 @@ interface Roadmap {
|
|
|
641
805
|
frontmatter: RoadmapFrontmatter;
|
|
642
806
|
/** Milestones in document order (including Backlog) */
|
|
643
807
|
milestones: RoadmapMilestone[];
|
|
808
|
+
/** Assignment history records, in document order */
|
|
809
|
+
assignmentHistory: AssignmentRecord[];
|
|
644
810
|
}
|
|
645
811
|
|
|
646
|
-
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 };
|
|
812
|
+
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 };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,52 +1,65 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
3
|
-
*
|
|
4
|
-
* Session memory allows skills to append to shared sections (terminology,
|
|
5
|
-
* decisions, constraints, risks, openQuestions, evidence) rather than
|
|
6
|
-
* overwriting. Each entry is timestamped and tagged with the authoring skill.
|
|
7
|
-
*
|
|
8
|
-
* @see docs/changes/ai-foundations-integration/proposal.md
|
|
9
|
-
*/
|
|
10
|
-
/**
|
|
11
|
-
* Names of accumulative session sections.
|
|
12
|
-
* Runtime array used for iteration and validation.
|
|
13
|
-
*/
|
|
14
|
-
declare const SESSION_SECTION_NAMES: readonly ["terminology", "decisions", "constraints", "risks", "openQuestions", "evidence"];
|
|
15
|
-
/**
|
|
16
|
-
* Union type of valid session section names.
|
|
17
|
-
*/
|
|
18
|
-
type SessionSectionName = (typeof SESSION_SECTION_NAMES)[number];
|
|
19
|
-
/**
|
|
20
|
-
* Lifecycle status of a session entry.
|
|
21
|
-
* - `active` — current and relevant
|
|
22
|
-
* - `resolved` — addressed or answered (e.g., an open question that was resolved)
|
|
23
|
-
* - `superseded` — replaced by a newer entry
|
|
24
|
-
*/
|
|
25
|
-
type SessionEntryStatus = 'active' | 'resolved' | 'superseded';
|
|
26
|
-
/**
|
|
27
|
-
* A single entry in a session section.
|
|
28
|
-
* Entries are append-only; skills mark them as `resolved` or `superseded`
|
|
29
|
-
* rather than deleting.
|
|
2
|
+
* Represents a ticket created in an external tracking service.
|
|
30
3
|
*/
|
|
31
|
-
interface
|
|
32
|
-
/**
|
|
33
|
-
|
|
34
|
-
/**
|
|
35
|
-
|
|
36
|
-
/** Name of the skill that authored this entry */
|
|
37
|
-
authorSkill: string;
|
|
38
|
-
/** The entry content (free-form text) */
|
|
39
|
-
content: string;
|
|
40
|
-
/** Lifecycle status of the entry */
|
|
41
|
-
status: SessionEntryStatus;
|
|
4
|
+
interface ExternalTicket {
|
|
5
|
+
/** External identifier, e.g., "github:owner/repo#42" */
|
|
6
|
+
externalId: string;
|
|
7
|
+
/** URL to the ticket in the external service */
|
|
8
|
+
url: string;
|
|
42
9
|
}
|
|
43
10
|
/**
|
|
44
|
-
*
|
|
45
|
-
*
|
|
11
|
+
* Current state of a ticket in the external service.
|
|
12
|
+
* Pulled during syncFromExternal.
|
|
46
13
|
*/
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
14
|
+
interface ExternalTicketState {
|
|
15
|
+
/** External identifier */
|
|
16
|
+
externalId: string;
|
|
17
|
+
/** External status (e.g., "open", "closed") */
|
|
18
|
+
status: string;
|
|
19
|
+
/** External labels (used for status disambiguation on GitHub) */
|
|
20
|
+
labels: string[];
|
|
21
|
+
/** Current assignee in the external service, or null */
|
|
22
|
+
assignee: string | null;
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* Result of a sync operation. Collects successes and errors per-feature.
|
|
26
|
+
*/
|
|
27
|
+
interface SyncResult {
|
|
28
|
+
/** Tickets created during this sync */
|
|
29
|
+
created: ExternalTicket[];
|
|
30
|
+
/** External IDs of tickets that were updated */
|
|
31
|
+
updated: string[];
|
|
32
|
+
/** Assignment changes detected during pull */
|
|
33
|
+
assignmentChanges: Array<{
|
|
34
|
+
feature: string;
|
|
35
|
+
from: string | null;
|
|
36
|
+
to: string | null;
|
|
37
|
+
}>;
|
|
38
|
+
/** Per-feature errors (sync never throws) */
|
|
39
|
+
errors: Array<{
|
|
40
|
+
featureOrId: string;
|
|
41
|
+
error: Error;
|
|
42
|
+
}>;
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* Configuration for external tracker sync.
|
|
46
|
+
*/
|
|
47
|
+
interface TrackerSyncConfig {
|
|
48
|
+
/** Adapter kind -- narrowed to GitHub-only for now */
|
|
49
|
+
kind: 'github';
|
|
50
|
+
/** Repository in "owner/repo" format (for GitHub) */
|
|
51
|
+
repo?: string;
|
|
52
|
+
/** Labels auto-applied to created tickets for filtering + identification */
|
|
53
|
+
labels?: string[];
|
|
54
|
+
/** Maps roadmap status -> external status string */
|
|
55
|
+
statusMap: Record<FeatureStatus, string>;
|
|
56
|
+
/**
|
|
57
|
+
* Maps external status (+ optional label) -> roadmap status.
|
|
58
|
+
* Compound keys like "open:in-progress" express state + label.
|
|
59
|
+
* Optional — when absent, syncFromExternal preserves current roadmap status.
|
|
60
|
+
*/
|
|
61
|
+
reverseStatusMap?: Record<string, FeatureStatus>;
|
|
62
|
+
}
|
|
50
63
|
|
|
51
64
|
/**
|
|
52
65
|
* Token usage statistics for an agent turn or session.
|
|
@@ -320,6 +333,132 @@ interface WorkflowDefinition {
|
|
|
320
333
|
promptTemplate: string;
|
|
321
334
|
}
|
|
322
335
|
|
|
336
|
+
/**
|
|
337
|
+
* Extended entry for cost tracking storage and display.
|
|
338
|
+
* Composes TokenUsage — does not extend it.
|
|
339
|
+
*/
|
|
340
|
+
interface UsageRecord {
|
|
341
|
+
/** Harness session identifier */
|
|
342
|
+
sessionId: string;
|
|
343
|
+
/** ISO 8601 timestamp of the usage event */
|
|
344
|
+
timestamp: string;
|
|
345
|
+
/** Token counts for this event */
|
|
346
|
+
tokens: TokenUsage;
|
|
347
|
+
/** Tokens used to create prompt cache entries */
|
|
348
|
+
cacheCreationTokens?: number;
|
|
349
|
+
/** Tokens read from prompt cache */
|
|
350
|
+
cacheReadTokens?: number;
|
|
351
|
+
/** Model identifier (e.g., "claude-sonnet-4-20250514") */
|
|
352
|
+
model?: string;
|
|
353
|
+
/** Cost in integer microdollars (USD * 1,000,000), calculated at read time */
|
|
354
|
+
costMicroUSD?: number;
|
|
355
|
+
}
|
|
356
|
+
/**
|
|
357
|
+
* Per-model pricing rates, all in USD per 1 million tokens.
|
|
358
|
+
*/
|
|
359
|
+
interface ModelPricing {
|
|
360
|
+
/** Input token cost per 1M tokens */
|
|
361
|
+
inputPer1M: number;
|
|
362
|
+
/** Output token cost per 1M tokens */
|
|
363
|
+
outputPer1M: number;
|
|
364
|
+
/** Cache read cost per 1M tokens (not all models support caching) */
|
|
365
|
+
cacheReadPer1M?: number;
|
|
366
|
+
/** Cache write/creation cost per 1M tokens */
|
|
367
|
+
cacheWritePer1M?: number;
|
|
368
|
+
}
|
|
369
|
+
/**
|
|
370
|
+
* Aggregated usage for a single calendar day.
|
|
371
|
+
*/
|
|
372
|
+
interface DailyUsage {
|
|
373
|
+
/** ISO 8601 date string (YYYY-MM-DD) */
|
|
374
|
+
date: string;
|
|
375
|
+
/** Number of distinct sessions that had activity on this day */
|
|
376
|
+
sessionCount: number;
|
|
377
|
+
/** Summed token counts across all sessions */
|
|
378
|
+
tokens: TokenUsage;
|
|
379
|
+
/** Summed cache creation tokens (omitted if no cache data) */
|
|
380
|
+
cacheCreationTokens?: number;
|
|
381
|
+
/** Summed cache read tokens (omitted if no cache data) */
|
|
382
|
+
cacheReadTokens?: number;
|
|
383
|
+
/** Total cost in integer microdollars, null if any session has unknown pricing */
|
|
384
|
+
costMicroUSD: number | null;
|
|
385
|
+
/** Distinct model identifiers seen on this day */
|
|
386
|
+
models: string[];
|
|
387
|
+
}
|
|
388
|
+
/**
|
|
389
|
+
* Aggregated usage for a single session across all its turns.
|
|
390
|
+
*/
|
|
391
|
+
interface SessionUsage {
|
|
392
|
+
/** Harness session identifier */
|
|
393
|
+
sessionId: string;
|
|
394
|
+
/** ISO 8601 timestamp of the first event in this session */
|
|
395
|
+
firstTimestamp: string;
|
|
396
|
+
/** ISO 8601 timestamp of the last event in this session */
|
|
397
|
+
lastTimestamp: string;
|
|
398
|
+
/** Summed token counts across all turns */
|
|
399
|
+
tokens: TokenUsage;
|
|
400
|
+
/** Summed cache creation tokens (omitted if no cache data) */
|
|
401
|
+
cacheCreationTokens?: number;
|
|
402
|
+
/** Summed cache read tokens (omitted if no cache data) */
|
|
403
|
+
cacheReadTokens?: number;
|
|
404
|
+
/** Model identifier (may be populated from CC data) */
|
|
405
|
+
model?: string;
|
|
406
|
+
/** Total cost in integer microdollars, null if pricing unavailable */
|
|
407
|
+
costMicroUSD: number | null;
|
|
408
|
+
/** Data source: 'harness', 'claude-code', or 'merged' */
|
|
409
|
+
source: 'harness' | 'claude-code' | 'merged';
|
|
410
|
+
}
|
|
411
|
+
|
|
412
|
+
/**
|
|
413
|
+
* Session-scoped accumulative state types.
|
|
414
|
+
*
|
|
415
|
+
* Session memory allows skills to append to shared sections (terminology,
|
|
416
|
+
* decisions, constraints, risks, openQuestions, evidence) rather than
|
|
417
|
+
* overwriting. Each entry is timestamped and tagged with the authoring skill.
|
|
418
|
+
*
|
|
419
|
+
* @see docs/changes/ai-foundations-integration/proposal.md
|
|
420
|
+
*/
|
|
421
|
+
/**
|
|
422
|
+
* Names of accumulative session sections.
|
|
423
|
+
* Runtime array used for iteration and validation.
|
|
424
|
+
*/
|
|
425
|
+
declare const SESSION_SECTION_NAMES: readonly ["terminology", "decisions", "constraints", "risks", "openQuestions", "evidence"];
|
|
426
|
+
/**
|
|
427
|
+
* Union type of valid session section names.
|
|
428
|
+
*/
|
|
429
|
+
type SessionSectionName = (typeof SESSION_SECTION_NAMES)[number];
|
|
430
|
+
/**
|
|
431
|
+
* Lifecycle status of a session entry.
|
|
432
|
+
* - `active` — current and relevant
|
|
433
|
+
* - `resolved` — addressed or answered (e.g., an open question that was resolved)
|
|
434
|
+
* - `superseded` — replaced by a newer entry
|
|
435
|
+
*/
|
|
436
|
+
type SessionEntryStatus = 'active' | 'resolved' | 'superseded';
|
|
437
|
+
/**
|
|
438
|
+
* A single entry in a session section.
|
|
439
|
+
* Entries are append-only; skills mark them as `resolved` or `superseded`
|
|
440
|
+
* rather than deleting.
|
|
441
|
+
*/
|
|
442
|
+
interface SessionEntry {
|
|
443
|
+
/** Auto-generated unique identifier */
|
|
444
|
+
id: string;
|
|
445
|
+
/** ISO 8601 timestamp of when the entry was created */
|
|
446
|
+
timestamp: string;
|
|
447
|
+
/** Name of the skill that authored this entry */
|
|
448
|
+
authorSkill: string;
|
|
449
|
+
/** The entry content (free-form text) */
|
|
450
|
+
content: string;
|
|
451
|
+
/** Lifecycle status of the entry */
|
|
452
|
+
status: SessionEntryStatus;
|
|
453
|
+
}
|
|
454
|
+
/**
|
|
455
|
+
* Container mapping each section name to its array of entries.
|
|
456
|
+
* Used as the shape of session-scoped state in `state.json`.
|
|
457
|
+
*/
|
|
458
|
+
type SessionSections = {
|
|
459
|
+
[K in SessionSectionName]: SessionEntry[];
|
|
460
|
+
};
|
|
461
|
+
|
|
323
462
|
/**
|
|
324
463
|
* @harness-engineering/types
|
|
325
464
|
*
|
|
@@ -587,6 +726,11 @@ interface SkillLifecycleHooks {
|
|
|
587
726
|
* Valid statuses for a roadmap feature.
|
|
588
727
|
*/
|
|
589
728
|
type FeatureStatus = 'backlog' | 'planned' | 'in-progress' | 'done' | 'blocked';
|
|
729
|
+
/**
|
|
730
|
+
* Priority override levels for roadmap features.
|
|
731
|
+
* When present, priority replaces positional ordering as the primary sort key.
|
|
732
|
+
*/
|
|
733
|
+
type Priority = 'P0' | 'P1' | 'P2' | 'P3';
|
|
590
734
|
/**
|
|
591
735
|
* A feature entry in the project roadmap.
|
|
592
736
|
*/
|
|
@@ -603,6 +747,12 @@ interface RoadmapFeature {
|
|
|
603
747
|
blockedBy: string[];
|
|
604
748
|
/** One-line summary */
|
|
605
749
|
summary: string;
|
|
750
|
+
/** GitHub username, email, or display name — null if unassigned */
|
|
751
|
+
assignee: string | null;
|
|
752
|
+
/** Optional priority override — null uses positional ordering */
|
|
753
|
+
priority: Priority | null;
|
|
754
|
+
/** External tracker ID (e.g., "github:owner/repo#42") — null if not synced */
|
|
755
|
+
externalId: string | null;
|
|
606
756
|
}
|
|
607
757
|
/**
|
|
608
758
|
* A milestone grouping in the roadmap. The special "Backlog" milestone
|
|
@@ -616,6 +766,20 @@ interface RoadmapMilestone {
|
|
|
616
766
|
/** Features in this milestone, in document order */
|
|
617
767
|
features: RoadmapFeature[];
|
|
618
768
|
}
|
|
769
|
+
/**
|
|
770
|
+
* A single record in the assignment history log.
|
|
771
|
+
* Reassignment produces two records: 'unassigned' for previous, 'assigned' for new.
|
|
772
|
+
*/
|
|
773
|
+
interface AssignmentRecord {
|
|
774
|
+
/** Feature name */
|
|
775
|
+
feature: string;
|
|
776
|
+
/** Assignee identifier (username, email, or display name) */
|
|
777
|
+
assignee: string;
|
|
778
|
+
/** What happened */
|
|
779
|
+
action: 'assigned' | 'completed' | 'unassigned';
|
|
780
|
+
/** ISO date string (YYYY-MM-DD) */
|
|
781
|
+
date: string;
|
|
782
|
+
}
|
|
619
783
|
/**
|
|
620
784
|
* YAML frontmatter of the roadmap file.
|
|
621
785
|
*/
|
|
@@ -641,6 +805,8 @@ interface Roadmap {
|
|
|
641
805
|
frontmatter: RoadmapFrontmatter;
|
|
642
806
|
/** Milestones in document order (including Backlog) */
|
|
643
807
|
milestones: RoadmapMilestone[];
|
|
808
|
+
/** Assignment history records, in document order */
|
|
809
|
+
assignmentHistory: AssignmentRecord[];
|
|
644
810
|
}
|
|
645
811
|
|
|
646
|
-
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 };
|
|
812
|
+
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 };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@harness-engineering/types",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.7.0",
|
|
4
4
|
"description": "TypeScript types and interfaces for Harness Engineering",
|
|
5
5
|
"main": "./dist/index.js",
|
|
6
6
|
"module": "./dist/index.mjs",
|
|
@@ -37,9 +37,9 @@
|
|
|
37
37
|
},
|
|
38
38
|
"homepage": "https://github.com/Intense-Visions/harness-engineering/tree/main/packages/types#readme",
|
|
39
39
|
"devDependencies": {
|
|
40
|
-
"@vitest/coverage-v8": "^4.
|
|
41
|
-
"tsup": "^8.
|
|
42
|
-
"vitest": "^4.
|
|
40
|
+
"@vitest/coverage-v8": "^4.1.2",
|
|
41
|
+
"tsup": "^8.5.1",
|
|
42
|
+
"vitest": "^4.1.2"
|
|
43
43
|
},
|
|
44
44
|
"scripts": {
|
|
45
45
|
"build": "tsup src/index.ts --format cjs,esm --dts --tsconfig tsconfig.build.json",
|