@harness-engineering/types 0.2.0 → 0.3.0

package/dist/index.d.mts

@@ -1,8 +1,283 @@
+/**
+ * Token usage statistics for an agent turn or session.
+ */
+interface TokenUsage {
+    /** Number of tokens used in the input (prompt) */
+    inputTokens: number;
+    /** Number of tokens generated in the output (response) */
+    outputTokens: number;
+    /** Combined total tokens used */
+    totalTokens: number;
+}
+/**
+ * Reference to a blocking issue.
+ */
+interface BlockerRef {
+    /** Unique ID of the blocker */
+    id: string | null;
+    /** Human-readable identifier (e.g., "CORE-123") */
+    identifier: string | null;
+    /** Current state of the blocker */
+    state: string | null;
+}
+/**
+ * Representation of a work item (issue/feature) in a tracker.
+ */
+interface Issue {
+    /** Unique ID in the tracking system */
+    id: string;
+    /** Human-readable identifier (e.g., "CORE-123") */
+    identifier: string;
+    /** Title or headline of the issue */
+    title: string;
+    /** Detailed description, if available */
+    description: string | null;
+    /** Numerical priority (lower is typically higher priority) */
+    priority: number | null;
+    /** Current lifecycle state */
+    state: string;
+    /** Name of the git branch associated with this issue */
+    branchName: string | null;
+    /** Direct URL to the issue in the tracker */
+    url: string | null;
+    /** List of labels or tags */
+    labels: string[];
+    /** References to issues that block this one */
+    blockedBy: BlockerRef[];
+    /** ISO timestamp of creation */
+    createdAt: string | null;
+    /** ISO timestamp of last update */
+    updatedAt: string | null;
+}
+/**
+ * Categories of errors that can occur during agent execution.
+ */
+type AgentErrorCategory = 'agent_not_found' | 'invalid_workspace_cwd' | 'response_timeout' | 'turn_timeout' | 'process_exit' | 'response_error' | 'turn_failed' | 'turn_cancelled' | 'turn_input_required';
+/**
+ * Error returned by an agent backend.
+ */
+interface AgentError {
+    /** Machine-readable category */
+    category: AgentErrorCategory;
+    /** Human-readable message */
+    message: string;
+    /** Optional additional context */
+    details?: unknown;
+}
+/**
+ * Parameters for starting a new agent session.
+ */
+interface SessionStartParams {
+    /** Absolute path to the workspace directory */
+    workspacePath: string;
+    /** Permission level for the agent (e.g., "readonly", "full") */
+    permissionMode: string;
+    /** List of tool names the agent is allowed to use */
+    allowedTools?: string[];
+    /** Custom system instructions for the agent */
+    systemPrompt?: string;
+}
+/**
+ * Represents an active session with an agent backend.
+ */
+interface AgentSession {
+    /** Unique ID for the session */
+    sessionId: string;
+    /** Workspace associated with this session */
+    workspacePath: string;
+    /** Name of the backend provider */
+    backendName: string;
+    /** ISO timestamp when the session started */
+    startedAt: string;
+}
+/**
+ * Parameters for a single interaction (turn) with an agent.
+ */
+interface TurnParams {
+    /** ID of the active session */
+    sessionId: string;
+    /** User or system prompt for this turn */
+    prompt: string;
+    /** Whether this is a continuation of a previous turn */
+    isContinuation: boolean;
+}
+/**
+ * Event emitted by an agent during a turn.
+ */
+interface AgentEvent {
+    /** Event type (e.g., "thought", "tool_call", "output") */
+    type: string;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Optional subtype for finer-grained classification */
+    subtype?: string;
+    /** Token usage snapshot if available */
+    usage?: TokenUsage;
+    /** Event payload */
+    content?: unknown;
+    /** Session ID if not implicit */
+    sessionId?: string;
+}
+/**
+ * Result of a completed agent turn.
+ */
+interface TurnResult {
+    /** Whether the turn completed successfully */
+    success: boolean;
+    /** ID of the session */
+    sessionId: string;
+    /** Cumulative usage for this turn */
+    usage: TokenUsage;
+    /** Error message if success is false */
+    error?: string;
+}
+/**
+ * Interface for agent backend implementations (Claude, Mock, etc.)
+ */
+interface AgentBackend {
+    /** Unique name of the backend */
+    readonly name: string;
+    /** Starts a new session */
+    startSession(params: SessionStartParams): Promise<Result<AgentSession, AgentError>>;
+    /** Runs a turn and streams events */
+    runTurn(session: AgentSession, params: TurnParams): AsyncGenerator<AgentEvent, TurnResult, void>;
+    /** Stops and cleans up a session */
+    stopSession(session: AgentSession): Promise<Result<void, AgentError>>;
+    /** Verifies connectivity and health */
+    healthCheck(): Promise<Result<void, AgentError>>;
+}
+/**
+ * Interface for issue tracking systems (Roadmap, Linear, GitHub, etc.)
+ */
+interface IssueTrackerClient {
+    /** Fetches issues eligible for agent assignment */
+    fetchCandidateIssues(): Promise<Result<Issue[], Error>>;
+    /** Fetches issues in specific lifecycle states */
+    fetchIssuesByStates(stateNames: string[]): Promise<Result<Issue[], Error>>;
+    /** Fetches current state for a set of issue IDs */
+    fetchIssueStatesByIds(issueIds: string[]): Promise<Result<Map<string, Issue>, Error>>;
+}
+/**
+ * Configuration for an issue tracker adapter.
+ */
+interface TrackerConfig {
+    /** Adapter kind (e.g., "roadmap", "linear") */
+    kind: string;
+    /** API endpoint if applicable */
+    endpoint?: string;
+    /** API key or token */
+    apiKey?: string;
+    /** Project slug or identifier */
+    projectSlug?: string;
+    /** Local file path for file-based trackers */
+    filePath?: string;
+    /** States considered "ready for work" */
+    activeStates: string[];
+    /** States considered "finished" */
+    terminalStates: string[];
+}
+/**
+ * Polling interval configuration.
+ */
+interface PollingConfig {
+    /** Interval in milliseconds */
+    intervalMs: number;
+}
+/**
+ * Workspace management configuration.
+ */
+interface WorkspaceConfig {
+    /** Root directory where agent workspaces are created */
+    root: string;
+}
+/**
+ * Lifecycle hooks configuration.
+ */
+interface HooksConfig {
+    /** Script to run after creating a workspace */
+    afterCreate: string | null;
+    /** Script to run before starting an agent */
+    beforeRun: string | null;
+    /** Script to run after an agent completes */
+    afterRun: string | null;
+    /** Script to run before removing a workspace */
+    beforeRemove: string | null;
+    /** Maximum time allowed for hook execution */
+    timeoutMs: number;
+}
+/**
+ * Configuration for the agent runner.
+ */
+interface AgentConfig {
+    /** Backend type to use */
+    backend: string;
+    /** Command to launch the agent if applicable */
+    command?: string;
+    /** Model name/identifier */
+    model?: string;
+    /** API key for the agent provider */
+    apiKey?: string;
+    /** Global limit on concurrent agents */
+    maxConcurrentAgents: number;
+    /** Maximum turns allowed per session */
+    maxTurns: number;
+    /** Maximum backoff for retries */
+    maxRetryBackoffMs: number;
+    /** Concurrency limits partitioned by issue state */
+    maxConcurrentAgentsByState: Record<string, number>;
+    /** Policy for approving tool calls */
+    approvalPolicy?: string;
+    /** Policy for execution environment isolation */
+    sandboxPolicy?: string;
+    /** Timeout for a single turn */
+    turnTimeoutMs: number;
+    /** Timeout for reading from the agent */
+    readTimeoutMs: number;
+    /** Timeout for agent inactivity */
+    stallTimeoutMs: number;
+}
+/**
+ * Internal server configuration.
+ */
+interface ServerConfig {
+    /** Port to listen on (null to disable) */
+    port: number | null;
+}
+/**
+ * Root workflow configuration object.
+ */
+interface WorkflowConfig {
+    /** Issue tracker settings */
+    tracker: TrackerConfig;
+    /** Polling loop settings */
+    polling: PollingConfig;
+    /** Workspace settings */
+    workspace: WorkspaceConfig;
+    /** Lifecycle hook settings */
+    hooks: HooksConfig;
+    /** Agent execution settings */
+    agent: AgentConfig;
+    /** Server settings */
+    server: ServerConfig;
+}
+/**
+ * Complete workflow definition including config and prompts.
+ */
+interface WorkflowDefinition {
+    /** Orchestrator configuration */
+    config: WorkflowConfig;
+    /** Template used to generate agent prompts */
+    promptTemplate: string;
+}
+
 /**
  * @harness-engineering/types
  *
  * Core types and interfaces for Harness Engineering toolkit
  */
+/**
+ * Result type for consistent error handling across the toolkit.
+ */
 type Result<T, E = Error> = {
     ok: true;
     value: T;
@@ -11,124 +286,251 @@ type Result<T, E = Error> = {
     error: E;
 };
 /**
- * Creates a successful Result
+ * Creates a successful Result.
  */
 declare function Ok<T>(value: T): Result<T, never>;
 /**
- * Creates a failed Result
+ * Creates a failed Result.
  */
 declare function Err<E>(error: E): Result<never, E>;
 /**
- * Type guard to check if a Result is successful
+ * Type guard to check if a Result is successful.
  */
 declare function isOk<T, E>(result: Result<T, E>): result is {
     ok: true;
     value: T;
 };
 /**
- * Type guard to check if a Result is failed
+ * Type guard to check if a Result is failed.
  */
 declare function isErr<T, E>(result: Result<T, E>): result is {
     ok: false;
     error: E;
 };
+/**
+ * A single step in a multi-skill workflow.
+ */
 interface WorkflowStep {
+    /** The skill to execute (e.g., "detect-doc-drift") */
     skill: string;
+    /** Name of the artifact this step produces */
     produces: string;
+    /** Name of the artifact this step expects as input */
     expects?: string;
+    /** Whether failure of this step stops the workflow */
     gate?: 'pass-required' | 'advisory';
 }
+/**
+ * Definition of a sequence of steps to achieve a goal.
+ */
 interface Workflow {
+    /** Descriptive name of the workflow */
     name: string;
+    /** Ordered list of steps */
     steps: WorkflowStep[];
 }
+/**
+ * Possible outcomes for a single workflow step.
+ */
 type StepOutcome = 'pass' | 'fail' | 'skipped';
+/**
+ * Detailed result of a workflow step execution.
+ */
 interface WorkflowStepResult {
+    /** The step that was executed */
     step: WorkflowStep;
+    /** The outcome of the execution */
     outcome: StepOutcome;
+    /** Path to the produced artifact, if any */
     artifact?: string;
+    /** Error message if outcome is 'fail' */
     error?: string;
+    /** Execution time in milliseconds */
     durationMs: number;
 }
+/**
+ * Final result of a complete workflow execution.
+ */
 interface WorkflowResult {
+    /** The workflow that was executed */
     workflow: Workflow;
+    /** Results for each step in the workflow */
     stepResults: WorkflowStepResult[];
+    /** Whether the overall workflow passed (all required gates passed) */
     pass: boolean;
+    /** Total execution time in milliseconds */
     totalDurationMs: number;
 }
+/**
+ * Predefined cognitive modes for skills.
+ */
 declare const STANDARD_COGNITIVE_MODES: readonly ["adversarial-reviewer", "constructive-architect", "meticulous-implementer", "diagnostic-investigator", "advisory-guide", "meticulous-verifier"];
+/**
+ * Cognitive mode of a skill, determining its behavior and persona.
+ */
 type CognitiveMode = (typeof STANDARD_COGNITIVE_MODES)[number] | (string & {});
+/**
+ * Static metadata for a skill.
+ */
 interface SkillMetadata {
+    /** Unique name of the skill */
     name: string;
+    /** Semantic version string */
     version: string;
+    /** Brief description of what the skill does */
     description: string;
+    /** The cognitive mode this skill operates in */
     cognitive_mode?: CognitiveMode;
 }
+/**
+ * Contextual information for a skill execution.
+ */
 interface SkillContext {
+    /** Name of the executing skill */
     skillName: string;
+    /** Current pipeline phase */
     phase: string;
+    /** Files relevant to the current execution */
     files: string[];
     /** Optional token budget — uses a plain record to avoid cross-package deps. */
     tokenBudget?: Record<string, number>;
+    /** Additional metadata */
     metadata: Record<string, unknown>;
 }
+/**
+ * Context for a single turn in a multi-turn skill interaction.
+ */
 interface TurnContext extends SkillContext {
+    /** Current turn number (1-indexed) */
     turnNumber: number;
+    /** Results from previous turns in the same session */
     previousResults: unknown[];
 }
+/**
+ * Error reported by a skill.
+ */
 type SkillError = {
+    /** Machine-readable error code */
     code: string;
+    /** Human-readable error message */
     message: string;
+    /** Phase in which the error occurred */
     phase: string;
 };
-type CICheckName = 'validate' | 'deps' | 'docs' | 'entropy' | 'security' | 'perf' | 'phase-gate';
+/**
+ * Names of standard CI checks.
+ */
+type CICheckName = 'validate' | 'deps' | 'docs' | 'entropy' | 'security' | 'perf' | 'phase-gate' | 'arch';
+/**
+ * Status of a CI check.
+ */
 type CICheckStatus = 'pass' | 'fail' | 'warn' | 'skip';
+/**
+ * A specific issue found during a CI check.
+ */
 interface CICheckIssue {
+    /** Severity level */
     severity: 'error' | 'warning';
+    /** Descriptive message */
     message: string;
+    /** Path to the affected file */
     file?: string;
+    /** Line number in the affected file */
     line?: number;
 }
+/**
+ * Result of a single CI check execution.
+ */
 interface CICheckResult {
+    /** Name of the check */
     name: CICheckName;
+    /** Final status of the check */
     status: CICheckStatus;
+    /** List of issues discovered */
     issues: CICheckIssue[];
+    /** Execution time in milliseconds */
     durationMs: number;
 }
+/**
+ * Summary counts for a set of CI checks.
+ */
 interface CICheckSummary {
+    /** Total number of checks run */
     total: number;
+    /** Number of passing checks */
     passed: number;
+    /** Number of failing checks */
     failed: number;
+    /** Number of checks with warnings */
     warnings: number;
+    /** Number of skipped checks */
     skipped: number;
 }
+/**
+ * Final report for a CI run.
+ */
 interface CICheckReport {
+    /** Schema version */
     version: 1;
+    /** Name of the project */
     project: string;
+    /** ISO timestamp of the run */
     timestamp: string;
+    /** Detailed results for each check */
     checks: CICheckResult[];
+    /** Aggregated summary */
     summary: CICheckSummary;
+    /** Process exit code suggested for the CI runner */
     exitCode: 0 | 1 | 2;
 }
+/**
+ * Severity level that should trigger a CI failure.
+ */
 type CIFailOnSeverity = 'error' | 'warning';
+/**
+ * Configuration options for the CI command.
+ */
 interface CICheckOptions {
+    /** Checks to skip */
     skip?: CICheckName[];
+    /** Severity level that causes failure */
     failOn?: CIFailOnSeverity;
+    /** Custom config file path */
     configPath?: string;
 }
+/**
+ * Supported CI platforms.
+ */
 type CIPlatform = 'github' | 'gitlab' | 'generic';
+/**
+ * Options for initializing CI configuration.
+ */
 interface CIInitOptions {
+    /** Target CI platform */
     platform?: CIPlatform;
+    /** Checks to enable */
     checks?: CICheckName[];
 }
+/**
+ * Result of a skill execution.
+ */
 type SkillResult = {
+    /** Whether the skill achieved its goal */
     success: boolean;
+    /** List of artifact paths produced */
     artifacts: string[];
+    /** One-line summary of the outcome */
     summary: string;
 };
+/**
+ * Lifecycle hooks for skills.
+ */
 interface SkillLifecycleHooks {
+    /** Called before the skill starts execution */
     preExecution?: (context: SkillContext) => SkillContext | null;
+    /** Called before each turn in a multi-turn interaction */
     perTurn?: (context: TurnContext) => TurnContext | null;
+    /** Called after the skill completes execution */
     postExecution?: (context: SkillContext, result: SkillResult) => void;
 }
 /**
@@ -187,4 +589,4 @@ interface Roadmap {
     milestones: RoadmapMilestone[];
 }
 
-export { 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, Ok, type Result, type Roadmap, type RoadmapFeature, type RoadmapFrontmatter, type RoadmapMilestone, STANDARD_COGNITIVE_MODES, type SkillContext, type SkillError, type SkillLifecycleHooks, type SkillMetadata, type SkillResult, type StepOutcome, type TurnContext, type Workflow, type WorkflowResult, type WorkflowStep, type WorkflowStepResult, 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, Err, type FeatureStatus, type HooksConfig, type Issue, type IssueTrackerClient, Ok, type PollingConfig, type Result, type Roadmap, type RoadmapFeature, type RoadmapFrontmatter, type RoadmapMilestone, STANDARD_COGNITIVE_MODES, type ServerConfig, 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 };

package/dist/index.d.ts

@@ -1,8 +1,283 @@
+/**
+ * Token usage statistics for an agent turn or session.
+ */
+interface TokenUsage {
+    /** Number of tokens used in the input (prompt) */
+    inputTokens: number;
+    /** Number of tokens generated in the output (response) */
+    outputTokens: number;
+    /** Combined total tokens used */
+    totalTokens: number;
+}
+/**
+ * Reference to a blocking issue.
+ */
+interface BlockerRef {
+    /** Unique ID of the blocker */
+    id: string | null;
+    /** Human-readable identifier (e.g., "CORE-123") */
+    identifier: string | null;
+    /** Current state of the blocker */
+    state: string | null;
+}
+/**
+ * Representation of a work item (issue/feature) in a tracker.
+ */
+interface Issue {
+    /** Unique ID in the tracking system */
+    id: string;
+    /** Human-readable identifier (e.g., "CORE-123") */
+    identifier: string;
+    /** Title or headline of the issue */
+    title: string;
+    /** Detailed description, if available */
+    description: string | null;
+    /** Numerical priority (lower is typically higher priority) */
+    priority: number | null;
+    /** Current lifecycle state */
+    state: string;
+    /** Name of the git branch associated with this issue */
+    branchName: string | null;
+    /** Direct URL to the issue in the tracker */
+    url: string | null;
+    /** List of labels or tags */
+    labels: string[];
+    /** References to issues that block this one */
+    blockedBy: BlockerRef[];
+    /** ISO timestamp of creation */
+    createdAt: string | null;
+    /** ISO timestamp of last update */
+    updatedAt: string | null;
+}
+/**
+ * Categories of errors that can occur during agent execution.
+ */
+type AgentErrorCategory = 'agent_not_found' | 'invalid_workspace_cwd' | 'response_timeout' | 'turn_timeout' | 'process_exit' | 'response_error' | 'turn_failed' | 'turn_cancelled' | 'turn_input_required';
+/**
+ * Error returned by an agent backend.
+ */
+interface AgentError {
+    /** Machine-readable category */
+    category: AgentErrorCategory;
+    /** Human-readable message */
+    message: string;
+    /** Optional additional context */
+    details?: unknown;
+}
+/**
+ * Parameters for starting a new agent session.
+ */
+interface SessionStartParams {
+    /** Absolute path to the workspace directory */
+    workspacePath: string;
+    /** Permission level for the agent (e.g., "readonly", "full") */
+    permissionMode: string;
+    /** List of tool names the agent is allowed to use */
+    allowedTools?: string[];
+    /** Custom system instructions for the agent */
+    systemPrompt?: string;
+}
+/**
+ * Represents an active session with an agent backend.
+ */
+interface AgentSession {
+    /** Unique ID for the session */
+    sessionId: string;
+    /** Workspace associated with this session */
+    workspacePath: string;
+    /** Name of the backend provider */
+    backendName: string;
+    /** ISO timestamp when the session started */
+    startedAt: string;
+}
+/**
+ * Parameters for a single interaction (turn) with an agent.
+ */
+interface TurnParams {
+    /** ID of the active session */
+    sessionId: string;
+    /** User or system prompt for this turn */
+    prompt: string;
+    /** Whether this is a continuation of a previous turn */
+    isContinuation: boolean;
+}
+/**
+ * Event emitted by an agent during a turn.
+ */
+interface AgentEvent {
+    /** Event type (e.g., "thought", "tool_call", "output") */
+    type: string;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Optional subtype for finer-grained classification */
+    subtype?: string;
+    /** Token usage snapshot if available */
+    usage?: TokenUsage;
+    /** Event payload */
+    content?: unknown;
+    /** Session ID if not implicit */
+    sessionId?: string;
+}
+/**
+ * Result of a completed agent turn.
+ */
+interface TurnResult {
+    /** Whether the turn completed successfully */
+    success: boolean;
+    /** ID of the session */
+    sessionId: string;
+    /** Cumulative usage for this turn */
+    usage: TokenUsage;
+    /** Error message if success is false */
+    error?: string;
+}
+/**
+ * Interface for agent backend implementations (Claude, Mock, etc.)
+ */
+interface AgentBackend {
+    /** Unique name of the backend */
+    readonly name: string;
+    /** Starts a new session */
+    startSession(params: SessionStartParams): Promise<Result<AgentSession, AgentError>>;
+    /** Runs a turn and streams events */
+    runTurn(session: AgentSession, params: TurnParams): AsyncGenerator<AgentEvent, TurnResult, void>;
+    /** Stops and cleans up a session */
+    stopSession(session: AgentSession): Promise<Result<void, AgentError>>;
+    /** Verifies connectivity and health */
+    healthCheck(): Promise<Result<void, AgentError>>;
+}
+/**
+ * Interface for issue tracking systems (Roadmap, Linear, GitHub, etc.)
+ */
+interface IssueTrackerClient {
+    /** Fetches issues eligible for agent assignment */
+    fetchCandidateIssues(): Promise<Result<Issue[], Error>>;
+    /** Fetches issues in specific lifecycle states */
+    fetchIssuesByStates(stateNames: string[]): Promise<Result<Issue[], Error>>;
+    /** Fetches current state for a set of issue IDs */
+    fetchIssueStatesByIds(issueIds: string[]): Promise<Result<Map<string, Issue>, Error>>;
+}
+/**
+ * Configuration for an issue tracker adapter.
+ */
+interface TrackerConfig {
+    /** Adapter kind (e.g., "roadmap", "linear") */
+    kind: string;
+    /** API endpoint if applicable */
+    endpoint?: string;
+    /** API key or token */
+    apiKey?: string;
+    /** Project slug or identifier */
+    projectSlug?: string;
+    /** Local file path for file-based trackers */
+    filePath?: string;
+    /** States considered "ready for work" */
+    activeStates: string[];
+    /** States considered "finished" */
+    terminalStates: string[];
+}
+/**
+ * Polling interval configuration.
+ */
+interface PollingConfig {
+    /** Interval in milliseconds */
+    intervalMs: number;
+}
+/**
+ * Workspace management configuration.
+ */
+interface WorkspaceConfig {
+    /** Root directory where agent workspaces are created */
+    root: string;
+}
+/**
+ * Lifecycle hooks configuration.
+ */
+interface HooksConfig {
+    /** Script to run after creating a workspace */
+    afterCreate: string | null;
+    /** Script to run before starting an agent */
+    beforeRun: string | null;
+    /** Script to run after an agent completes */
+    afterRun: string | null;
+    /** Script to run before removing a workspace */
+    beforeRemove: string | null;
+    /** Maximum time allowed for hook execution */
+    timeoutMs: number;
+}
+/**
+ * Configuration for the agent runner.
+ */
+interface AgentConfig {
+    /** Backend type to use */
+    backend: string;
+    /** Command to launch the agent if applicable */
+    command?: string;
+    /** Model name/identifier */
+    model?: string;
+    /** API key for the agent provider */
+    apiKey?: string;
+    /** Global limit on concurrent agents */
+    maxConcurrentAgents: number;
+    /** Maximum turns allowed per session */
+    maxTurns: number;
+    /** Maximum backoff for retries */
+    maxRetryBackoffMs: number;
+    /** Concurrency limits partitioned by issue state */
+    maxConcurrentAgentsByState: Record<string, number>;
+    /** Policy for approving tool calls */
+    approvalPolicy?: string;
+    /** Policy for execution environment isolation */
+    sandboxPolicy?: string;
+    /** Timeout for a single turn */
+    turnTimeoutMs: number;
+    /** Timeout for reading from the agent */
+    readTimeoutMs: number;
+    /** Timeout for agent inactivity */
+    stallTimeoutMs: number;
+}
+/**
+ * Internal server configuration.
+ */
+interface ServerConfig {
+    /** Port to listen on (null to disable) */
+    port: number | null;
+}
+/**
+ * Root workflow configuration object.
+ */
+interface WorkflowConfig {
+    /** Issue tracker settings */
+    tracker: TrackerConfig;
+    /** Polling loop settings */
+    polling: PollingConfig;
+    /** Workspace settings */
+    workspace: WorkspaceConfig;
+    /** Lifecycle hook settings */
+    hooks: HooksConfig;
+    /** Agent execution settings */
+    agent: AgentConfig;
+    /** Server settings */
+    server: ServerConfig;
+}
+/**
+ * Complete workflow definition including config and prompts.
+ */
+interface WorkflowDefinition {
+    /** Orchestrator configuration */
+    config: WorkflowConfig;
+    /** Template used to generate agent prompts */
+    promptTemplate: string;
+}
+
 /**
  * @harness-engineering/types
  *
  * Core types and interfaces for Harness Engineering toolkit
  */
+/**
+ * Result type for consistent error handling across the toolkit.
+ */
 type Result<T, E = Error> = {
     ok: true;
     value: T;
@@ -11,124 +286,251 @@ type Result<T, E = Error> = {
     error: E;
 };
 /**
- * Creates a successful Result
+ * Creates a successful Result.
  */
 declare function Ok<T>(value: T): Result<T, never>;
 /**
- * Creates a failed Result
+ * Creates a failed Result.
  */
 declare function Err<E>(error: E): Result<never, E>;
 /**
- * Type guard to check if a Result is successful
+ * Type guard to check if a Result is successful.
  */
 declare function isOk<T, E>(result: Result<T, E>): result is {
     ok: true;
     value: T;
 };
 /**
- * Type guard to check if a Result is failed
+ * Type guard to check if a Result is failed.
  */
 declare function isErr<T, E>(result: Result<T, E>): result is {
     ok: false;
     error: E;
 };
+/**
+ * A single step in a multi-skill workflow.
+ */
 interface WorkflowStep {
+    /** The skill to execute (e.g., "detect-doc-drift") */
     skill: string;
+    /** Name of the artifact this step produces */
     produces: string;
+    /** Name of the artifact this step expects as input */
     expects?: string;
+    /** Whether failure of this step stops the workflow */
     gate?: 'pass-required' | 'advisory';
 }
+/**
+ * Definition of a sequence of steps to achieve a goal.
+ */
 interface Workflow {
+    /** Descriptive name of the workflow */
     name: string;
+    /** Ordered list of steps */
     steps: WorkflowStep[];
 }
+/**
+ * Possible outcomes for a single workflow step.
+ */
 type StepOutcome = 'pass' | 'fail' | 'skipped';
+/**
+ * Detailed result of a workflow step execution.
+ */
 interface WorkflowStepResult {
+    /** The step that was executed */
     step: WorkflowStep;
+    /** The outcome of the execution */
     outcome: StepOutcome;
+    /** Path to the produced artifact, if any */
     artifact?: string;
+    /** Error message if outcome is 'fail' */
     error?: string;
+    /** Execution time in milliseconds */
     durationMs: number;
 }
+/**
+ * Final result of a complete workflow execution.
+ */
 interface WorkflowResult {
+    /** The workflow that was executed */
     workflow: Workflow;
+    /** Results for each step in the workflow */
     stepResults: WorkflowStepResult[];
+    /** Whether the overall workflow passed (all required gates passed) */
     pass: boolean;
+    /** Total execution time in milliseconds */
     totalDurationMs: number;
 }
+/**
+ * Predefined cognitive modes for skills.
+ */
 declare const STANDARD_COGNITIVE_MODES: readonly ["adversarial-reviewer", "constructive-architect", "meticulous-implementer", "diagnostic-investigator", "advisory-guide", "meticulous-verifier"];
+/**
+ * Cognitive mode of a skill, determining its behavior and persona.
+ */
 type CognitiveMode = (typeof STANDARD_COGNITIVE_MODES)[number] | (string & {});
+/**
+ * Static metadata for a skill.
+ */
 interface SkillMetadata {
+    /** Unique name of the skill */
     name: string;
+    /** Semantic version string */
     version: string;
+    /** Brief description of what the skill does */
     description: string;
+    /** The cognitive mode this skill operates in */
     cognitive_mode?: CognitiveMode;
 }
+/**
+ * Contextual information for a skill execution.
+ */
 interface SkillContext {
+    /** Name of the executing skill */
     skillName: string;
+    /** Current pipeline phase */
     phase: string;
+    /** Files relevant to the current execution */
     files: string[];
     /** Optional token budget — uses a plain record to avoid cross-package deps. */
     tokenBudget?: Record<string, number>;
+    /** Additional metadata */
     metadata: Record<string, unknown>;
 }
+/**
+ * Context for a single turn in a multi-turn skill interaction.
+ */
 interface TurnContext extends SkillContext {
+    /** Current turn number (1-indexed) */
     turnNumber: number;
+    /** Results from previous turns in the same session */
     previousResults: unknown[];
 }
+/**
+ * Error reported by a skill.
+ */
 type SkillError = {
+    /** Machine-readable error code */
     code: string;
+    /** Human-readable error message */
     message: string;
+    /** Phase in which the error occurred */
     phase: string;
 };
-type CICheckName = 'validate' | 'deps' | 'docs' | 'entropy' | 'security' | 'perf' | 'phase-gate';
+/**
+ * Names of standard CI checks.
+ */
+type CICheckName = 'validate' | 'deps' | 'docs' | 'entropy' | 'security' | 'perf' | 'phase-gate' | 'arch';
+/**
+ * Status of a CI check.
+ */
 type CICheckStatus = 'pass' | 'fail' | 'warn' | 'skip';
+/**
+ * A specific issue found during a CI check.
+ */
 interface CICheckIssue {
+    /** Severity level */
     severity: 'error' | 'warning';
+    /** Descriptive message */
     message: string;
+    /** Path to the affected file */
     file?: string;
+    /** Line number in the affected file */
     line?: number;
 }
+/**
+ * Result of a single CI check execution.
+ */
 interface CICheckResult {
+    /** Name of the check */
     name: CICheckName;
+    /** Final status of the check */
     status: CICheckStatus;
+    /** List of issues discovered */
     issues: CICheckIssue[];
+    /** Execution time in milliseconds */
     durationMs: number;
 }
+/**
+ * Summary counts for a set of CI checks.
+ */
 interface CICheckSummary {
+    /** Total number of checks run */
     total: number;
+    /** Number of passing checks */
     passed: number;
+    /** Number of failing checks */
     failed: number;
+    /** Number of checks with warnings */
     warnings: number;
+    /** Number of skipped checks */
     skipped: number;
 }
+/**
+ * Final report for a CI run.
+ */
 interface CICheckReport {
+    /** Schema version */
     version: 1;
+    /** Name of the project */
     project: string;
+    /** ISO timestamp of the run */
     timestamp: string;
+    /** Detailed results for each check */
     checks: CICheckResult[];
+    /** Aggregated summary */
     summary: CICheckSummary;
+    /** Process exit code suggested for the CI runner */
     exitCode: 0 | 1 | 2;
 }
+/**
+ * Severity level that should trigger a CI failure.
+ */
 type CIFailOnSeverity = 'error' | 'warning';
+/**
+ * Configuration options for the CI command.
+ */
 interface CICheckOptions {
+    /** Checks to skip */
     skip?: CICheckName[];
+    /** Severity level that causes failure */
     failOn?: CIFailOnSeverity;
+    /** Custom config file path */
     configPath?: string;
 }
+/**
+ * Supported CI platforms.
+ */
 type CIPlatform = 'github' | 'gitlab' | 'generic';
+/**
+ * Options for initializing CI configuration.
+ */
 interface CIInitOptions {
+    /** Target CI platform */
     platform?: CIPlatform;
+    /** Checks to enable */
     checks?: CICheckName[];
 }
+/**
+ * Result of a skill execution.
+ */
 type SkillResult = {
+    /** Whether the skill achieved its goal */
     success: boolean;
+    /** List of artifact paths produced */
     artifacts: string[];
+    /** One-line summary of the outcome */
     summary: string;
 };
+/**
+ * Lifecycle hooks for skills.
+ */
 interface SkillLifecycleHooks {
+    /** Called before the skill starts execution */
     preExecution?: (context: SkillContext) => SkillContext | null;
+    /** Called before each turn in a multi-turn interaction */
     perTurn?: (context: TurnContext) => TurnContext | null;
+    /** Called after the skill completes execution */
     postExecution?: (context: SkillContext, result: SkillResult) => void;
 }
 /**
@@ -187,4 +589,4 @@ interface Roadmap {
     milestones: RoadmapMilestone[];
 }
 
-export { 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, Ok, type Result, type Roadmap, type RoadmapFeature, type RoadmapFrontmatter, type RoadmapMilestone, STANDARD_COGNITIVE_MODES, type SkillContext, type SkillError, type SkillLifecycleHooks, type SkillMetadata, type SkillResult, type StepOutcome, type TurnContext, type Workflow, type WorkflowResult, type WorkflowStep, type WorkflowStepResult, 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, Err, type FeatureStatus, type HooksConfig, type Issue, type IssueTrackerClient, Ok, type PollingConfig, type Result, type Roadmap, type RoadmapFeature, type RoadmapFrontmatter, type RoadmapMilestone, STANDARD_COGNITIVE_MODES, type ServerConfig, 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harness-engineering/types",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "TypeScript types and interfaces for Harness Engineering",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -41,12 +41,12 @@
     "vitest": "^4.0.18"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "build": "tsup src/index.ts --format cjs,esm --dts --tsconfig tsconfig.build.json",
     "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
     "lint": "eslint src",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
-    "clean": "rm -rf dist"
+    "clean": "node ../../scripts/clean.mjs dist"
   }
 }