@harness-engineering/orchestrator 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { Issue, AgentEvent, WorkflowConfig, TokenUsage, ConcernSignal, ScopeTier, EscalationConfig, RoutingDecision, Result, WorkflowDefinition, WorkspaceConfig, HooksConfig, AgentBackend, SessionStartParams, AgentSession, AgentError, TurnParams, TurnResult, BackendDef, RoutingConfig, RoutingUseCase, ContainerConfig, SecretConfig, AgentConfig, TokenScope, AuthToken, AuthTokenPublic, IndexedFileKind, SessionSearchResult, ReindexStats, SessionSummarizationConfig, SessionSummary, SessionSummaryMeta, SessionsConfig, GatewayEvent, NotificationEnvelope, NotificationDeliveryResult, NotificationSinkConfig, NotificationsConfig } from '@harness-engineering/types';
-import { IssueTrackerClient, Issue as Issue$1, TrackerConfig, CacheMetricsRecorder, ArchiveHooks } from '@harness-engineering/core';
+import { Issue, AgentEvent, WorkflowConfig, TokenUsage, ConcernSignal, ScopeTier, EscalationConfig, RoutingDecision, Result, WorkflowDefinition, WorkspaceConfig, HooksConfig, AgentBackend, SessionStartParams, AgentSession, AgentError, TurnParams, TurnResult, CheckScriptDefinition, OutputRetentionConfig, BackendDef, RoutingConfig, RoutingUseCase, ContainerConfig, SecretConfig, AgentConfig, CustomTaskDefinition, TokenScope, AuthToken, AuthTokenPublic, IndexedFileKind, SessionSearchResult, ReindexStats, SessionSummarizationConfig, SessionSummary, SessionSummaryMeta, SessionsConfig, GatewayEvent, NotificationEnvelope, NotificationDeliveryResult, NotificationSinkConfig, NotificationsConfig } from '@harness-engineering/types';
+import { IssueTrackerClient, Issue as Issue$1, TrackerConfig, CacheMetricsRecorder, ArchiveHooks, SkillProposal, ProposalGateFinding } from '@harness-engineering/core';
 import { EnrichedSpec, ComplexityScore, SimulationResult, IntelligencePipeline, WeightedRecommendation, AnalysisProvider } from '@harness-engineering/intelligence';
 import { GraphStore } from '@harness-engineering/graph';
 import { execFile } from 'node:child_process';
@@ -1084,8 +1084,10 @@ declare class PromptRenderer {
 
 /**
  * Internal types for the maintenance module.
- * Public config types (MaintenanceConfig, TaskOverride) live in @harness-engineering/types.
+ * Public config types (MaintenanceConfig, TaskOverride, CustomTaskDefinition,
+ * CheckScriptDefinition, OutputRetentionConfig) live in @harness-engineering/types.
  */
+
 /**
  * Classification of maintenance task execution strategy.
  *
@@ -1095,6 +1097,85 @@ declare class PromptRenderer {
  * - housekeeping: Run a mechanical command directly; no AI, no PR.
  */
 type TaskType = 'mechanical-ai' | 'pure-ai' | 'report-only' | 'housekeeping';
+/**
+ * Hermes Phase 2 — Provenance tag identifying the trigger source of a run.
+ *
+ * Set by the entry point, never user-configurable:
+ *   - 'cron'                      — scheduled by MaintenanceScheduler
+ *   - 'cli'                       — `harness maintenance run <id>`
+ *   - { kind: 'api', tokenName }  — Gateway API trigger (Phase 0)
+ *   - { kind: 'chain', upstreamTaskId } — fired by a downstream `contextFrom`
+ *                                          dependency (reserved; not yet wired)
+ */
+type RunOrigin = 'cron' | 'cli' | {
+    kind: 'api';
+    tokenName: string;
+} | {
+    kind: 'chain';
+    upstreamTaskId: string;
+};
+/**
+ * Per-task cost ceiling (Hermes Phase 5).
+ *
+ * When set, the orchestrator's `CostCeilingMonitor` tracks cumulative
+ * agent spend for the task and aborts dispatch on exceed (D6 — abort
+ * is advisory at the turn boundary).
+ */
+interface TaskCostCeiling {
+    /** Hard cap in USD. Cumulative spend > maxUsd fires the abort path. */
+    maxUsd: number;
+    /** Warn threshold expressed as a percentage of `maxUsd` (1–99). */
+    warnAtPct?: number;
+}
+/**
+ * Definition of a maintenance task (built-in or Phase 2 custom).
+ *
+ * Custom-task-only fields (`checkScript`, `inlineSkills`, `inlineSkillsBudgetTokens`,
+ * `contextFrom`, `contextFromMaxAgeMinutes`, `outputRetention`, `isCustom`) are
+ * populated by the scheduler when merging `MaintenanceConfig.customTasks` into the
+ * resolved task list. Built-ins leave them unset and the runner falls through to
+ * the legacy execution paths unchanged.
+ */
+interface TaskDefinition {
+    /** Unique identifier for this task (e.g., 'arch-violations') */
+    id: string;
+    /** Execution strategy */
+    type: TaskType;
+    /** Human-readable description */
+    description: string;
+    /** Default cron expression (e.g., '0 2 * * *' for daily at 2am) */
+    schedule: string;
+    /** Branch name for PRs, or null for report-only/housekeeping tasks */
+    branch: string | null;
+    /** CLI command args for the mechanical check step (mechanical-ai and report-only) */
+    checkCommand?: string[];
+    /** Skill name to dispatch for AI fix (mechanical-ai and pure-ai) */
+    fixSkill?: string;
+    /**
+     * Per-task cost ceiling (Hermes Phase 5). When set, cumulative agent
+     * spend across all turns dispatched for this task is tracked; the
+     * orchestrator aborts dispatch on `maxUsd` exceedance with
+     * `RunResult.error === 'cost_ceiling_exceeded'`. Default: unset = no cap.
+     */
+    costCeiling?: TaskCostCeiling;
+    /**
+     * Hermes Phase 2 — Arbitrary-executable check (replaces `checkCommand`).
+     * Mutually-exclusive with `checkCommand`; validator rejects both.
+     */
+    checkScript?: CheckScriptDefinition;
+    /** Hermes Phase 2 — Skill names whose markdown is inlined into the agent prompt. */
+    inlineSkills?: string[];
+    /** Hermes Phase 2 — Token-budget cap for inlined skills. Default: 8000. */
+    inlineSkillsBudgetTokens?: number;
+    /** Hermes Phase 2 — Upstream task IDs whose latest output feeds prompt context. */
+    contextFrom?: string[];
+    /** Hermes Phase 2 — Max upstream-output age (minutes). Default: 1440. */
+    contextFromMaxAgeMinutes?: number;
+    /** Hermes Phase 2 — Output retention overrides. */
+    outputRetention?: OutputRetentionConfig;
+    /** Hermes Phase 2 — Marks tasks originating from `customTasks` config. */
+    isCustom?: boolean;
+}
 /**
  * Result of a single maintenance task run.
  */
@@ -1126,6 +1207,12 @@ interface RunResult {
      * and `error === 'cost_ceiling_exceeded'`.
      */
     costUsd?: number;
+    /**
+     * Hermes Phase 2 — Provenance tag set by the entry point.
+     * Older orchestrators may emit this field absent; renderers should fall
+     * back to `'—'` rather than crash.
+     */
+    origin?: RunOrigin;
 }
 /**
  * Schedule entry for a single task, used in MaintenanceStatus.
@@ -1614,6 +1701,147 @@ interface SyncMainOptions {
  */
 declare function syncMain(repoRoot: string, opts?: SyncMainOptions): Promise<SyncMainResult>;
 
+/**
+ * All 21 built-in maintenance task definitions with default schedules.
+ *
+ * Tasks are grouped by type:
+ * - mechanical-ai (7): Run check first, dispatch AI only if fixable issues found
+ * - pure-ai (4): Always dispatch AI agent on schedule
+ * - report-only (7): Run command, record metrics, no PR
+ * - housekeeping (3): Mechanical command, no AI, no PR
+ */
+declare const BUILT_IN_TASKS: readonly TaskDefinition[];
+
+/**
+ * Unified logger interface for all maintenance classes.
+ * Matches StructuredLogger's shape.
+ */
+interface MaintenanceLogger {
+    info(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    error(message: string, context?: Record<string, unknown>): void;
+    debug?(message: string, context?: Record<string, unknown>): void;
+}
+
+/**
+ * Hermes Phase 2 — A single persisted run entry.
+ *
+ * Mirrors `RunResult` plus the captured stdout/stderr, the parsed structured
+ * status envelope (if any), the resolved upstream context that was injected
+ * into the prompt (if any), and the trigger origin.
+ */
+interface PersistedOutputEntry {
+    taskId: string;
+    startedAt: string;
+    completedAt: string;
+    status: RunResult['status'];
+    findings: number;
+    fixed: number;
+    prUrl: string | null;
+    prUpdated: boolean;
+    error?: string;
+    costUsd?: number;
+    origin?: RunOrigin;
+    /** Raw captured stdout from the check step (or housekeeping command). */
+    stdout?: string;
+    /** Raw captured stderr from the check step. */
+    stderr?: string;
+    /** Structured envelope when a JSON status line was parsed; null otherwise. */
+    structured?: Record<string, unknown> | null;
+    /** Resolved upstream-context block, if any. */
+    context?: string;
+}
+interface TaskOutputStoreOptions {
+    /** Root directory under which `<taskId>/outputs/` lives. Default: `.harness/maintenance`. */
+    rootDir: string;
+    /** Default retention bounds applied when a task doesn't specify its own. */
+    retentionDefaults?: Required<OutputRetentionConfig>;
+    logger?: MaintenanceLogger;
+}
+/**
+ * Persists per-task run outputs to disk and applies retention. The store is
+ * intentionally simple: one file per run keyed by completion timestamp, JSON
+ * payload, no SQLite. The chain-context read path (`latest`) and the
+ * dashboard list path (`list`) both consume the same on-disk format.
+ *
+ * Concurrency: `processQueue` already serializes runs of the same task ID,
+ * so the store assumes exclusive write access per task.
+ */
+declare class TaskOutputStore {
+    private rootDir;
+    private retentionDefaults;
+    private logger;
+    constructor(options: TaskOutputStoreOptions);
+    /**
+     * Reject task IDs that don't match the validator's kebab-case pattern —
+     * defends `dirFor()` against caller-supplied path-traversal segments
+     * (`'../foo'`) when the store is invoked from CLI surfaces that don't
+     * round-trip through `validateCustomTasks`.
+     */
+    private ensureSafeTaskId;
+    /**
+     * Persist a single run entry. Retention is applied after the write so
+     * the latest record is durable even if pruning fails.
+     */
+    write(taskId: string, entry: PersistedOutputEntry, retention?: OutputRetentionConfig): Promise<void>;
+    /**
+     * Return the most recent persisted entry for the task, or null if none.
+     */
+    latest(taskId: string): Promise<PersistedOutputEntry | null>;
+    /**
+     * List entries newest-first with offset+limit pagination.
+     */
+    list(taskId: string, limit: number, offset: number): Promise<PersistedOutputEntry[]>;
+    /**
+     * Lookup a specific run by its file name (without the `.json` suffix) or
+     * by its raw completion timestamp.
+     */
+    get(taskId: string, runId: string): Promise<PersistedOutputEntry | null>;
+    /**
+     * The on-disk root for a given task. Exposed for tooling that needs to walk
+     * outputs from outside the store API.
+     */
+    dirFor(taskId: string): string;
+    private readEntry;
+    private applyRetention;
+}
+
+/**
+ * Hermes Phase 2 — Validation errors surfaced by `validateCustomTasks`.
+ *
+ * `path` always begins with `customTasks.<taskId>` so the caller can render
+ * it directly without re-prefixing. Multiple errors may be returned in a
+ * single call; the validator does not short-circuit on the first failure.
+ */
+interface CustomTaskValidationError {
+    path: string;
+    message: string;
+}
+interface CustomTaskValidatorDeps {
+    /** Returns true if a skill with this name exists in the project's registry. */
+    skillExists?: (name: string) => boolean;
+    /** Returns true if the executable referenced by a checkScript.path exists. */
+    scriptExists?: (path: string) => boolean;
+}
+/**
+ * Validates a `MaintenanceConfig.customTasks` map.
+ *
+ * Checks:
+ *  - kebab-case task IDs (matching the BUILT_IN_TASKS convention)
+ *  - no collision with built-in IDs
+ *  - per-type required fields (e.g., mechanical-ai must have `branch` + `fixSkill`)
+ *  - exactly one of `checkCommand` / `checkScript` for types that need a check step
+ *  - `contextFrom` cycle detection across the merged graph (built-ins + customs)
+ *  - `contextFrom` entries reference existing task IDs
+ *  - `inlineSkills` entries exist in the skill registry (when `skillExists` is provided)
+ *  - `checkScript.path` exists on disk (when `scriptExists` is provided)
+ *
+ * Returns `Ok(void)` when all custom tasks pass; otherwise an `Err` carrying
+ * every distinct violation. The validator is pure: no I/O outside the
+ * injected predicates.
+ */
+declare function validateCustomTasks(customTasks: Record<string, CustomTaskDefinition> | undefined, builtIns: readonly TaskDefinition[], deps?: CustomTaskValidatorDeps): Result<void, CustomTaskValidationError[]>;
+
 interface CreateTokenInput {
     name: string;
     scopes: TokenScope[];
@@ -1980,4 +2208,87 @@ interface WireParams {
 }
 declare function wireNotificationSinks({ bus, registry }: WireParams): () => void;
 
-export { type AgentUpdateEvent, AnalysisArchive, type AnalysisRecord, type ApplyEventResult, type ArtifactPresence, type AttemptStats, BackendRouter, type BackendRouterOptions, type BaseRefFallbackEvent, type BuildArchiveHooksOptions, ClaimManager, type ClaimManagerConfig, type CleanWorkspaceEffect, type CreateTokenInput, type CreateTokenResult, type DispatchEffect, type EmitLogEffect, type EscalateEffect, type ExecFileFn$1 as ExecFileFn, type FromConfigOptions, type Highlight, type HighlightsInfo, type IndexedDoc, InteractionQueue, type LinearGraphQLExtension, LinearGraphQLStub, type LiveSession, MAX_ATTEMPTS, type MigrationResult, MockBackend, type NotificationSink, type NotificationSinkDeliverInput, ORCHESTRATOR_IDENTITY_FILE, Orchestrator, OrchestratorBackendFactory, type OrchestratorBackendFactoryOptions, type OrchestratorContext, type OrchestratorEvent, type OrchestratorState, PRDetector, type PRDetectorLogger, type PendingInteraction, PromptRenderer, type PublishedIndex, type QueueInsertInput, type QueueRow, type QueueStats, RETRY_DELAYS_MS, type RateLimitSnapshot as RateLimitComputeSnapshot, type RateLimitConfig, type RateLimitSnapshot$1 as RateLimitSnapshot, type RegistryEntry, type ReleaseClaimEffect, type RetryEntry, type RetryFiredEvent, RoadmapTrackerAdapter, type RunAttemptPhase, type RunningEntry, type ScheduleRetryEffect, type SearchOptions, type SideEffect, SinkConfigError, SinkRegistry, SlackSink, type SlackSinkOptions, SqliteSearchIndex, type StallDetectedEvent, type StopEffect, type StreamManifest, StreamRecorder, type SummarizeContext, type SummarizeResult, type SyncMainOptions, type SyncMainResult, type SyncSkipReason, type TickEvent, TokenStore, type TokenTotals, type TriageConfig, type TriageDecision, type TriageSignals, type TriageSkill, type UpdateTokensEffect, WebhookQueue, type WorkerExitEvent, WorkflowLoader, WorkspaceHooks, WorkspaceManager, type WorkspaceManagerOptions, applyEvent, artifactPresenceFromIssue, buildArchiveHooks, calculateRetryDelay, canDispatch, computeRateLimitDelay, createBackend, createEmptyState, detectScopeTier, extractHighlights, extractTitlePrefix, getAvailableSlots, getDefaultConfig, getPerStateCount, indexSessionDirectory, isEligible, isSummaryEnabled, launchTUI, loadPublishedIndex, migrateAgentConfig, normalizeFts5Query, openSearchIndex, reconcile, reindexFromArchive, renderAnalysisComment, renderLlmSummaryMarkdown, renderPRComment, resolveEscalationConfig, resolveOrchestratorId, routeIssue, savePublishedIndex, searchIndexPath, selectCandidates, sortCandidates, summarizeArchivedSession, syncMain, triageIssue, truncateForBudget, validateWorkflowConfig, wireNotificationSinks, wrapAsEnvelope };
+/**
+ * Phase 4 gate (degraded mode, see spec D5).
+ *
+ * The full design calls for `harness skill run harness-soundness-review
+ * --mode skill` against materialized proposal content. The skill-mode check
+ * vocabulary is not yet designed; its design is the explicit follow-up spec
+ * referenced in Phase 4's Non-goals.
+ *
+ * In v1 we run a small set of mechanical checks inline against the proposal
+ * payload. They cover the obvious structural failures (unparseable YAML,
+ * empty markdown, name/regex drift) without needing an LLM. The result
+ * shape mirrors the eventual soundness-review output so the downstream
+ * promote step (and dashboard panel) does not need to change when
+ * skill-mode lands.
+ */
+declare class GateRunError extends Error {
+    constructor(message: string);
+}
+interface GateResult {
+    proposalId: string;
+    status: SkillProposal['status'];
+    findings: ProposalGateFinding[];
+    runAt: string;
+}
+/**
+ * Synchronously run the gate against the given proposal. The proposal is
+ * read from disk, checks are computed, and the proposal JSON is patched
+ * with the gate result. Returns the post-update gate snapshot for the
+ * caller to render.
+ */
+declare function runGate(projectPath: string, proposalId: string): Promise<GateResult>;
+
+declare class GateNotReadyError extends Error {
+    constructor(message: string);
+}
+declare class PromotionError extends Error {
+    constructor(message: string);
+}
+interface PromotionResult {
+    proposalId: string;
+    skillPath: string;
+    /** Provenance field stamped onto the promoted skill. */
+    provenance: 'agent-proposed';
+}
+/**
+ * Promote a proposal to the skill catalog. Caller is responsible for
+ * emitting `proposal.approved` after a successful return.
+ */
+declare function promote(projectPath: string, proposalId: string, decidedBy: string): Promise<PromotionResult>;
+
+/**
+ * Phase 4 — thin wrappers around the orchestrator event bus that emit the
+ * three `proposal.*` lifecycle events with a stable, validated payload
+ * shape. Both the webhook fan-out (gateway/webhooks/events.ts) and the
+ * in-process notification dispatcher (notifications/events.ts) subscribe
+ * to these topics; their envelope derivers know the field names below.
+ */
+interface ProposalCreatedData {
+    id: string;
+    kind: SkillProposal['kind'];
+    name: string;
+    targetSkill?: string;
+    proposedBy: string;
+    justification: string;
+}
+interface ProposalApprovedData {
+    id: string;
+    kind: SkillProposal['kind'];
+    name: string;
+    targetSkill?: string;
+    decidedBy: string;
+}
+interface ProposalRejectedData {
+    id: string;
+    kind: SkillProposal['kind'];
+    name: string;
+    decidedBy: string;
+    reason: string;
+}
+declare function emitProposalCreated(bus: EventEmitter, proposal: SkillProposal): void;
+declare function emitProposalApproved(bus: EventEmitter, proposal: SkillProposal): void;
+declare function emitProposalRejected(bus: EventEmitter, proposal: SkillProposal): void;
+
+export { type AgentUpdateEvent, AnalysisArchive, type AnalysisRecord, type ApplyEventResult, type ArtifactPresence, type AttemptStats, BUILT_IN_TASKS, BackendRouter, type BackendRouterOptions, type BaseRefFallbackEvent, type BuildArchiveHooksOptions, ClaimManager, type ClaimManagerConfig, type CleanWorkspaceEffect, type CreateTokenInput, type CreateTokenResult, type CustomTaskValidationError, type DispatchEffect, type EmitLogEffect, type EscalateEffect, type ExecFileFn$1 as ExecFileFn, type FromConfigOptions, GateNotReadyError, type GateResult, GateRunError, type Highlight, type HighlightsInfo, type IndexedDoc, InteractionQueue, type LinearGraphQLExtension, LinearGraphQLStub, type LiveSession, MAX_ATTEMPTS, type MigrationResult, MockBackend, type NotificationSink, type NotificationSinkDeliverInput, ORCHESTRATOR_IDENTITY_FILE, Orchestrator, OrchestratorBackendFactory, type OrchestratorBackendFactoryOptions, type OrchestratorContext, type OrchestratorEvent, type OrchestratorState, PRDetector, type PRDetectorLogger, type PendingInteraction, type PersistedOutputEntry, PromotionError, type PromotionResult, PromptRenderer, type ProposalApprovedData, type ProposalCreatedData, type ProposalRejectedData, type PublishedIndex, type QueueInsertInput, type QueueRow, type QueueStats, RETRY_DELAYS_MS, type RateLimitSnapshot as RateLimitComputeSnapshot, type RateLimitConfig, type RateLimitSnapshot$1 as RateLimitSnapshot, type RegistryEntry, type ReleaseClaimEffect, type RetryEntry, type RetryFiredEvent, RoadmapTrackerAdapter, type RunAttemptPhase, type RunOrigin, type RunningEntry, type ScheduleRetryEffect, type SearchOptions, type SideEffect, SinkConfigError, SinkRegistry, SlackSink, type SlackSinkOptions, SqliteSearchIndex, type StallDetectedEvent, type StopEffect, type StreamManifest, StreamRecorder, type SummarizeContext, type SummarizeResult, type SyncMainOptions, type SyncMainResult, type SyncSkipReason, type TaskDefinition, TaskOutputStore, type TaskType, type TickEvent, TokenStore, type TokenTotals, type TriageConfig, type TriageDecision, type TriageSignals, type TriageSkill, type UpdateTokensEffect, WebhookQueue, type WorkerExitEvent, WorkflowLoader, WorkspaceHooks, WorkspaceManager, type WorkspaceManagerOptions, applyEvent, artifactPresenceFromIssue, buildArchiveHooks, calculateRetryDelay, canDispatch, computeRateLimitDelay, createBackend, createEmptyState, detectScopeTier, emitProposalApproved, emitProposalCreated, emitProposalRejected, extractHighlights, extractTitlePrefix, getAvailableSlots, getDefaultConfig, getPerStateCount, indexSessionDirectory, isEligible, isSummaryEnabled, launchTUI, loadPublishedIndex, migrateAgentConfig, normalizeFts5Query, openSearchIndex, promote, reconcile, reindexFromArchive, renderAnalysisComment, renderLlmSummaryMarkdown, renderPRComment, resolveEscalationConfig, resolveOrchestratorId, routeIssue, runGate, savePublishedIndex, searchIndexPath, selectCandidates, sortCandidates, summarizeArchivedSession, syncMain, triageIssue, truncateForBudget, validateCustomTasks, validateWorkflowConfig, wireNotificationSinks, wrapAsEnvelope };