@harness-engineering/orchestrator 0.4.6 → 0.5.0

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-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 } from '@harness-engineering/types';
-import { IssueTrackerClient, Issue as Issue$1, TrackerConfig, CacheMetricsRecorder } from '@harness-engineering/core';
-import { EnrichedSpec, ComplexityScore, SimulationResult, IntelligencePipeline, WeightedRecommendation } from '@harness-engineering/intelligence';
+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 { EnrichedSpec, ComplexityScore, SimulationResult, IntelligencePipeline, WeightedRecommendation, AnalysisProvider } from '@harness-engineering/intelligence';
 import { GraphStore } from '@harness-engineering/graph';
 import { execFile } from 'node:child_process';
 import { EventEmitter } from 'node:events';
@@ -1117,6 +1117,15 @@ interface RunResult {
     prUpdated: boolean;
     /** Error message if status is 'failure' */
     error?: string;
+    /**
+     * Cumulative agent spend in USD for this run (Hermes Phase 5).
+     *
+     * Always present (defaults to 0). Populated by the
+     * `CostCeilingMonitor` from per-turn `TokenUsage` × `ModelPricing`.
+     * When the run aborted on cost-ceiling exceed, `status === 'failure'`
+     * and `error === 'cost_ceiling_exceeded'`.
+     */
+    costUsd?: number;
 }
 /**
  * Schedule entry for a single task, used in MaintenanceStatus.
@@ -1226,6 +1235,8 @@ declare class Orchestrator extends EventEmitter {
     private cacheMetrics?;
     private otlpExporter?;
     private telemetryFanoutOff?;
+    private notificationsRegistry?;
+    private notificationFanoutOff?;
     private orchestratorIdPromise;
     private recorder;
     private intelligenceRunner;
@@ -1341,6 +1352,15 @@ declare class Orchestrator extends EventEmitter {
      * Informs the state machine that an agent worker has exited.
      */
     private emitWorkerExit;
+    /**
+     * Hermes Phase 3: wire in-process notification sinks against the
+     * orchestrator's event bus (`this`). A misconfigured sink (unknown kind,
+     * missing env var) logs + skips rather than breaking startup — the
+     * hardened doctor (`harness doctor`) surfaces the gap. Sinks subscribe
+     * to the same topics as `wireWebhookFanout`; a slow Slack call cannot
+     * block webhook delivery because the two paths fan out independently.
+     */
+    private setupNotifications;
     /**
      * Stops execution for a specific issue.
      *
@@ -1697,4 +1717,267 @@ declare class WebhookQueue {
     close(): void;
 }
 
-export { type AgentUpdateEvent, AnalysisArchive, type AnalysisRecord, type ApplyEventResult, type ArtifactPresence, type AttemptStats, BackendRouter, type BackendRouterOptions, type BaseRefFallbackEvent, ClaimManager, type ClaimManagerConfig, type CleanWorkspaceEffect, type CreateTokenInput, type CreateTokenResult, type DispatchEffect, type EmitLogEffect, type EscalateEffect, type ExecFileFn$1 as ExecFileFn, type Highlight, type HighlightsInfo, InteractionQueue, type LinearGraphQLExtension, LinearGraphQLStub, type LiveSession, MAX_ATTEMPTS, type MigrationResult, MockBackend, 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 ReleaseClaimEffect, type RetryEntry, type RetryFiredEvent, RoadmapTrackerAdapter, type RunAttemptPhase, type RunningEntry, type ScheduleRetryEffect, type SideEffect, type StallDetectedEvent, type StopEffect, type StreamManifest, StreamRecorder, 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, calculateRetryDelay, canDispatch, computeRateLimitDelay, createBackend, createEmptyState, detectScopeTier, extractHighlights, extractTitlePrefix, getAvailableSlots, getDefaultConfig, getPerStateCount, isEligible, launchTUI, loadPublishedIndex, migrateAgentConfig, reconcile, renderAnalysisComment, renderPRComment, resolveEscalationConfig, resolveOrchestratorId, routeIssue, savePublishedIndex, selectCandidates, sortCandidates, syncMain, triageIssue, validateWorkflowConfig };
+interface IndexedDoc {
+    sessionId: string;
+    archived: boolean;
+    fileKind: IndexedFileKind;
+    /** Path relative to project root, posix-style. */
+    path: string;
+    mtimeMs: number;
+    body: string;
+}
+interface SearchOptions {
+    limit?: number;
+    archivedOnly?: boolean;
+    fileKinds?: IndexedFileKind[];
+    /** Maximum bytes to retain per doc body (defaults 256 KiB; longer bodies are truncated with a marker). */
+    maxBytesPerBody?: number;
+}
+/**
+ * Convert a user-typed query string into a safe FTS5 expression.
+ *
+ * If the caller's query already contains explicit FTS5 syntax markers (double
+ * quotes, parens, asterisk, caret, plus, the literal words AND/OR/NOT or a
+ * `column:` selector) it is passed through unchanged so power users keep the
+ * full FTS5 grammar.
+ *
+ * Otherwise each whitespace-separated token is wrapped as an FTS5 phrase so
+ * characters like `-`, `:` and `*` inside the token are treated as content
+ * (not operators), and the tokens are implicitly AND-joined by FTS5.
+ *
+ * Without this, `idx.search('token-aleph')` is parsed by FTS5 as
+ * `token NOT aleph` and fails with `no such column: aleph`.
+ */
+declare function normalizeFts5Query(query: string): string;
+/**
+ * Filesystem path of the search-index sqlite file for a given project root.
+ * Stable so consumers (cleanup tools, doctor, gitignore guards) can locate it.
+ */
+declare function searchIndexPath(projectPath: string): string;
+declare class SqliteSearchIndex {
+    private readonly db;
+    private readonly upsertStmt;
+    private readonly removeSessionStmt;
+    private readonly totalStmt;
+    constructor(dbPath: string);
+    upsertSessionDoc(doc: IndexedDoc): void;
+    removeSession(sessionId: string): number;
+    /**
+     * Drop all `archived=1` rows. Used by `reindexFromArchive` before a full
+     * re-walk. Live (archived=0) rows are preserved.
+     */
+    resetArchived(): void;
+    /** Total rows currently indexed (across both live and archived). */
+    totalIndexed(): number;
+    /**
+     * Ranked FTS5 query. Returns BM25-sorted matches. The `query` is passed to
+     * FTS5 as-is; FTS5 syntax (phrases with quotes, AND/OR/NOT, `column:term`)
+     * is therefore the user-facing language. Errors from malformed queries
+     * surface as thrown `SqliteError` so the CLI can catch + render them.
+     */
+    search(query: string, opts?: SearchOptions): SessionSearchResult;
+    close(): void;
+}
+/** Open (or create) the project's search index. Idempotent. */
+declare function openSearchIndex(projectPath: string): SqliteSearchIndex;
+/**
+ * Walk a session/archive directory and upsert one row per existing file_kind.
+ * Used by both the archive hook (`indexArchivedSession`) and `reindexFromArchive`.
+ *
+ * Bodies larger than `maxBytesPerBody` are truncated with a marker so the index
+ * does not bloat on pathological session files.
+ */
+declare function indexSessionDirectory(idx: SqliteSearchIndex, args: {
+    sessionId: string;
+    sessionDir: string;
+    archived: boolean;
+    projectPath: string;
+    /** Subset of file_kinds to consider (defaults to all). */
+    fileKinds?: IndexedFileKind[];
+    maxBytesPerBody?: number;
+}): {
+    docsWritten: number;
+};
+/**
+ * Drop and rebuild the `archived=1` portion of the index from
+ * `.harness/archive/sessions/<slug-date>/`. Idempotent.
+ *
+ * Each subdirectory is treated as one session whose id is the basename.
+ */
+declare function reindexFromArchive(projectPath: string, opts?: {
+    fileKinds?: IndexedFileKind[];
+    maxBytesPerBody?: number;
+}): ReindexStats;
+
+interface SummarizeContext {
+    /** Path to the archived session directory, e.g. .harness/archive/sessions/foo-2026-05-16. */
+    archiveDir: string;
+    /** Resolved AnalysisProvider — caller skips this step when no provider is available. */
+    provider: AnalysisProvider;
+    /** Optional session summary config, defaults applied when fields are missing. */
+    config?: SessionSummarizationConfig | undefined;
+    /** Optional logger; falls back to console.warn for diagnostics. */
+    logger?: {
+        warn?: (msg: string, meta?: Record<string, unknown>) => void;
+    };
+    /** When true, on provider error a stub `llm-summary.md` is still written. Default true. */
+    writeStubOnError?: boolean;
+}
+interface SummarizeResult {
+    summary: SessionSummary;
+    meta: SessionSummaryMeta;
+    filePath: string;
+}
+/** Approximate token cap via char count; conservative because tokens average ~4 chars. */
+declare function truncateForBudget(text: string, inputBudgetTokens: number): string;
+/** Render the structured summary as the `llm-summary.md` markdown payload. */
+declare function renderLlmSummaryMarkdown(summary: SessionSummary, meta: SessionSummaryMeta): string;
+/**
+ * Summarise a single archived session via the provided AnalysisProvider.
+ *
+ * On success: writes `llm-summary.md` into the archive directory and returns
+ * the structured summary + metadata.
+ *
+ * On provider error: optionally writes a stub `llm-summary.md` so callers can
+ * still detect that summarization was attempted, then returns `Err`.
+ *
+ * Empty / missing input corpus is returned as `Err` and never produces a file.
+ */
+declare function summarizeArchivedSession(ctx: SummarizeContext): Promise<Result<SummarizeResult, Error>>;
+/** Resolve whether summarization should run for the given config. */
+declare function isSummaryEnabled(config?: SessionSummarizationConfig): boolean;
+
+/**
+ * Session archive hook bundle.
+ *
+ * `buildArchiveHooks()` returns an `ArchiveHooks` implementation that wires
+ * `summarizeArchivedSession()` + `indexSessionDirectory()` together so the
+ * core `archiveSession()` lifecycle invokes both after a successful move.
+ *
+ * Both steps are individually wrapped in try/catch — failure of either does
+ * not propagate up the call stack. Spec: §"Risks" treats summary + index
+ * failure as non-fatal.
+ */
+
+interface BuildArchiveHooksOptions {
+    /** Absolute path to the project root (contains `.harness/`). */
+    projectPath: string;
+    /** Optional AnalysisProvider — summarization is skipped when omitted. */
+    provider?: AnalysisProvider | undefined;
+    /** Optional sessions config slice. */
+    config?: SessionsConfig | undefined;
+    /** Optional logger; falls back to console.warn. */
+    logger?: HookLogger | undefined;
+}
+interface HookLogger {
+    warn?: (msg: string, meta?: Record<string, unknown>) => void;
+}
+/**
+ * Construct the `ArchiveHooks` impl. Always returns a working hook bundle —
+ * missing provider or disabled config simply skips that step.
+ */
+declare function buildArchiveHooks(opts: BuildArchiveHooksOptions): ArchiveHooks;
+
+/**
+ * Wrap a `GatewayEvent` into a platform-agnostic `NotificationEnvelope`.
+ * Used when a sink has `wrap_response: true` in its config. Unknown event
+ * types fall back to a generic title/summary so newly-emitted events do
+ * not require a code change to be deliverable.
+ */
+declare function wrapAsEnvelope(event: GatewayEvent): NotificationEnvelope;
+
+/**
+ * Payload passed to `NotificationSink.deliver`. `wrapped` discriminates
+ * which member of the union `payload` is. Sinks branch on `wrapped`
+ * rather than runtime-detecting the shape.
+ */
+interface NotificationSinkDeliverInput {
+    payload: GatewayEvent | NotificationEnvelope;
+    wrapped: boolean;
+}
+/**
+ * Hermes Phase 3 sink contract.
+ *
+ * Sinks subscribe to the orchestrator event bus via `wireNotificationSinks`
+ * and deliver each filtered event to a destination (chat channel, webhook
+ * URL, etc.). Delivery is best-effort: no retry, no persistence.
+ *
+ * Sinks MUST be idempotent w.r.t. their own delivery semantics — the bus
+ * may emit the same logical state transition more than once during testing
+ * or recovery. Sinks should not assume one-shot semantics.
+ */
+interface NotificationSink {
+    /** Stable id used in config + CLI; lowercase, kebab-case. */
+    readonly id: string;
+    /** Sink kind literal (matches `NotificationSinkKind`). */
+    readonly kind: string;
+    /** One-shot delivery. Returns Ok on 2xx, Err on any other outcome. */
+    deliver(input: NotificationSinkDeliverInput): Promise<NotificationDeliveryResult>;
+    /** Optional teardown hook called on orchestrator stop. */
+    dispose?(): Promise<void>;
+}
+
+interface SlackSinkOptions {
+    id: string;
+    webhookUrl: string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}
+/**
+ * Slack sink shipped with Hermes Phase 3. Uses incoming-webhook URLs only;
+ * OAuth + bot tokens are intentionally out of scope (spec D3). Sends one
+ * HTTP POST per delivery and never retries — retries are the operator's
+ * call via the Phase 0 webhook fanout if they need durable delivery.
+ */
+declare class SlackSink implements NotificationSink {
+    readonly kind = "slack";
+    readonly id: string;
+    private readonly webhookUrl;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(opts: SlackSinkOptions);
+    deliver(input: NotificationSinkDeliverInput): Promise<NotificationDeliveryResult>;
+    private renderEnvelope;
+    private renderRawEvent;
+}
+
+interface RegistryEntry {
+    config: NotificationSinkConfig;
+    adapter: NotificationSink;
+}
+interface FromConfigOptions {
+    env: NodeJS.ProcessEnv;
+    /** Optional per-sink fetch override (testing). */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Surfaced when a sink config refers to an unknown kind, or its env-var
+ * secret cannot be resolved. Carrying the sinkId helps the doctor + CLI
+ * print operator-actionable messages.
+ */
+declare class SinkConfigError extends Error {
+    readonly sinkId: string;
+    constructor(sinkId: string, message: string);
+}
+/**
+ * In-memory registry of configured notification sinks. Built once at
+ * orchestrator startup from `harness.config.json` `notifications.sinks[]`.
+ * Disposed on orchestrator stop.
+ */
+declare class SinkRegistry {
+    private readonly entries;
+    private constructor();
+    static fromConfig(config: NotificationsConfig, options: FromConfigOptions): SinkRegistry;
+    list(): readonly RegistryEntry[];
+    get(id: string): RegistryEntry | null;
+    ids(): string[];
+    dispose(): Promise<void>;
+}
+
+interface WireParams {
+    bus: EventEmitter;
+    registry: SinkRegistry;
+}
+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 };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-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 } from '@harness-engineering/types';
-import { IssueTrackerClient, Issue as Issue$1, TrackerConfig, CacheMetricsRecorder } from '@harness-engineering/core';
-import { EnrichedSpec, ComplexityScore, SimulationResult, IntelligencePipeline, WeightedRecommendation } from '@harness-engineering/intelligence';
+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 { EnrichedSpec, ComplexityScore, SimulationResult, IntelligencePipeline, WeightedRecommendation, AnalysisProvider } from '@harness-engineering/intelligence';
 import { GraphStore } from '@harness-engineering/graph';
 import { execFile } from 'node:child_process';
 import { EventEmitter } from 'node:events';
@@ -1117,6 +1117,15 @@ interface RunResult {
     prUpdated: boolean;
     /** Error message if status is 'failure' */
     error?: string;
+    /**
+     * Cumulative agent spend in USD for this run (Hermes Phase 5).
+     *
+     * Always present (defaults to 0). Populated by the
+     * `CostCeilingMonitor` from per-turn `TokenUsage` × `ModelPricing`.
+     * When the run aborted on cost-ceiling exceed, `status === 'failure'`
+     * and `error === 'cost_ceiling_exceeded'`.
+     */
+    costUsd?: number;
 }
 /**
  * Schedule entry for a single task, used in MaintenanceStatus.
@@ -1226,6 +1235,8 @@ declare class Orchestrator extends EventEmitter {
     private cacheMetrics?;
     private otlpExporter?;
     private telemetryFanoutOff?;
+    private notificationsRegistry?;
+    private notificationFanoutOff?;
     private orchestratorIdPromise;
     private recorder;
     private intelligenceRunner;
@@ -1341,6 +1352,15 @@ declare class Orchestrator extends EventEmitter {
      * Informs the state machine that an agent worker has exited.
      */
     private emitWorkerExit;
+    /**
+     * Hermes Phase 3: wire in-process notification sinks against the
+     * orchestrator's event bus (`this`). A misconfigured sink (unknown kind,
+     * missing env var) logs + skips rather than breaking startup — the
+     * hardened doctor (`harness doctor`) surfaces the gap. Sinks subscribe
+     * to the same topics as `wireWebhookFanout`; a slow Slack call cannot
+     * block webhook delivery because the two paths fan out independently.
+     */
+    private setupNotifications;
     /**
      * Stops execution for a specific issue.
      *
@@ -1697,4 +1717,267 @@ declare class WebhookQueue {
     close(): void;
 }
 
-export { type AgentUpdateEvent, AnalysisArchive, type AnalysisRecord, type ApplyEventResult, type ArtifactPresence, type AttemptStats, BackendRouter, type BackendRouterOptions, type BaseRefFallbackEvent, ClaimManager, type ClaimManagerConfig, type CleanWorkspaceEffect, type CreateTokenInput, type CreateTokenResult, type DispatchEffect, type EmitLogEffect, type EscalateEffect, type ExecFileFn$1 as ExecFileFn, type Highlight, type HighlightsInfo, InteractionQueue, type LinearGraphQLExtension, LinearGraphQLStub, type LiveSession, MAX_ATTEMPTS, type MigrationResult, MockBackend, 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 ReleaseClaimEffect, type RetryEntry, type RetryFiredEvent, RoadmapTrackerAdapter, type RunAttemptPhase, type RunningEntry, type ScheduleRetryEffect, type SideEffect, type StallDetectedEvent, type StopEffect, type StreamManifest, StreamRecorder, 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, calculateRetryDelay, canDispatch, computeRateLimitDelay, createBackend, createEmptyState, detectScopeTier, extractHighlights, extractTitlePrefix, getAvailableSlots, getDefaultConfig, getPerStateCount, isEligible, launchTUI, loadPublishedIndex, migrateAgentConfig, reconcile, renderAnalysisComment, renderPRComment, resolveEscalationConfig, resolveOrchestratorId, routeIssue, savePublishedIndex, selectCandidates, sortCandidates, syncMain, triageIssue, validateWorkflowConfig };
+interface IndexedDoc {
+    sessionId: string;
+    archived: boolean;
+    fileKind: IndexedFileKind;
+    /** Path relative to project root, posix-style. */
+    path: string;
+    mtimeMs: number;
+    body: string;
+}
+interface SearchOptions {
+    limit?: number;
+    archivedOnly?: boolean;
+    fileKinds?: IndexedFileKind[];
+    /** Maximum bytes to retain per doc body (defaults 256 KiB; longer bodies are truncated with a marker). */
+    maxBytesPerBody?: number;
+}
+/**
+ * Convert a user-typed query string into a safe FTS5 expression.
+ *
+ * If the caller's query already contains explicit FTS5 syntax markers (double
+ * quotes, parens, asterisk, caret, plus, the literal words AND/OR/NOT or a
+ * `column:` selector) it is passed through unchanged so power users keep the
+ * full FTS5 grammar.
+ *
+ * Otherwise each whitespace-separated token is wrapped as an FTS5 phrase so
+ * characters like `-`, `:` and `*` inside the token are treated as content
+ * (not operators), and the tokens are implicitly AND-joined by FTS5.
+ *
+ * Without this, `idx.search('token-aleph')` is parsed by FTS5 as
+ * `token NOT aleph` and fails with `no such column: aleph`.
+ */
+declare function normalizeFts5Query(query: string): string;
+/**
+ * Filesystem path of the search-index sqlite file for a given project root.
+ * Stable so consumers (cleanup tools, doctor, gitignore guards) can locate it.
+ */
+declare function searchIndexPath(projectPath: string): string;
+declare class SqliteSearchIndex {
+    private readonly db;
+    private readonly upsertStmt;
+    private readonly removeSessionStmt;
+    private readonly totalStmt;
+    constructor(dbPath: string);
+    upsertSessionDoc(doc: IndexedDoc): void;
+    removeSession(sessionId: string): number;
+    /**
+     * Drop all `archived=1` rows. Used by `reindexFromArchive` before a full
+     * re-walk. Live (archived=0) rows are preserved.
+     */
+    resetArchived(): void;
+    /** Total rows currently indexed (across both live and archived). */
+    totalIndexed(): number;
+    /**
+     * Ranked FTS5 query. Returns BM25-sorted matches. The `query` is passed to
+     * FTS5 as-is; FTS5 syntax (phrases with quotes, AND/OR/NOT, `column:term`)
+     * is therefore the user-facing language. Errors from malformed queries
+     * surface as thrown `SqliteError` so the CLI can catch + render them.
+     */
+    search(query: string, opts?: SearchOptions): SessionSearchResult;
+    close(): void;
+}
+/** Open (or create) the project's search index. Idempotent. */
+declare function openSearchIndex(projectPath: string): SqliteSearchIndex;
+/**
+ * Walk a session/archive directory and upsert one row per existing file_kind.
+ * Used by both the archive hook (`indexArchivedSession`) and `reindexFromArchive`.
+ *
+ * Bodies larger than `maxBytesPerBody` are truncated with a marker so the index
+ * does not bloat on pathological session files.
+ */
+declare function indexSessionDirectory(idx: SqliteSearchIndex, args: {
+    sessionId: string;
+    sessionDir: string;
+    archived: boolean;
+    projectPath: string;
+    /** Subset of file_kinds to consider (defaults to all). */
+    fileKinds?: IndexedFileKind[];
+    maxBytesPerBody?: number;
+}): {
+    docsWritten: number;
+};
+/**
+ * Drop and rebuild the `archived=1` portion of the index from
+ * `.harness/archive/sessions/<slug-date>/`. Idempotent.
+ *
+ * Each subdirectory is treated as one session whose id is the basename.
+ */
+declare function reindexFromArchive(projectPath: string, opts?: {
+    fileKinds?: IndexedFileKind[];
+    maxBytesPerBody?: number;
+}): ReindexStats;
+
+interface SummarizeContext {
+    /** Path to the archived session directory, e.g. .harness/archive/sessions/foo-2026-05-16. */
+    archiveDir: string;
+    /** Resolved AnalysisProvider — caller skips this step when no provider is available. */
+    provider: AnalysisProvider;
+    /** Optional session summary config, defaults applied when fields are missing. */
+    config?: SessionSummarizationConfig | undefined;
+    /** Optional logger; falls back to console.warn for diagnostics. */
+    logger?: {
+        warn?: (msg: string, meta?: Record<string, unknown>) => void;
+    };
+    /** When true, on provider error a stub `llm-summary.md` is still written. Default true. */
+    writeStubOnError?: boolean;
+}
+interface SummarizeResult {
+    summary: SessionSummary;
+    meta: SessionSummaryMeta;
+    filePath: string;
+}
+/** Approximate token cap via char count; conservative because tokens average ~4 chars. */
+declare function truncateForBudget(text: string, inputBudgetTokens: number): string;
+/** Render the structured summary as the `llm-summary.md` markdown payload. */
+declare function renderLlmSummaryMarkdown(summary: SessionSummary, meta: SessionSummaryMeta): string;
+/**
+ * Summarise a single archived session via the provided AnalysisProvider.
+ *
+ * On success: writes `llm-summary.md` into the archive directory and returns
+ * the structured summary + metadata.
+ *
+ * On provider error: optionally writes a stub `llm-summary.md` so callers can
+ * still detect that summarization was attempted, then returns `Err`.
+ *
+ * Empty / missing input corpus is returned as `Err` and never produces a file.
+ */
+declare function summarizeArchivedSession(ctx: SummarizeContext): Promise<Result<SummarizeResult, Error>>;
+/** Resolve whether summarization should run for the given config. */
+declare function isSummaryEnabled(config?: SessionSummarizationConfig): boolean;
+
+/**
+ * Session archive hook bundle.
+ *
+ * `buildArchiveHooks()` returns an `ArchiveHooks` implementation that wires
+ * `summarizeArchivedSession()` + `indexSessionDirectory()` together so the
+ * core `archiveSession()` lifecycle invokes both after a successful move.
+ *
+ * Both steps are individually wrapped in try/catch — failure of either does
+ * not propagate up the call stack. Spec: §"Risks" treats summary + index
+ * failure as non-fatal.
+ */
+
+interface BuildArchiveHooksOptions {
+    /** Absolute path to the project root (contains `.harness/`). */
+    projectPath: string;
+    /** Optional AnalysisProvider — summarization is skipped when omitted. */
+    provider?: AnalysisProvider | undefined;
+    /** Optional sessions config slice. */
+    config?: SessionsConfig | undefined;
+    /** Optional logger; falls back to console.warn. */
+    logger?: HookLogger | undefined;
+}
+interface HookLogger {
+    warn?: (msg: string, meta?: Record<string, unknown>) => void;
+}
+/**
+ * Construct the `ArchiveHooks` impl. Always returns a working hook bundle —
+ * missing provider or disabled config simply skips that step.
+ */
+declare function buildArchiveHooks(opts: BuildArchiveHooksOptions): ArchiveHooks;
+
+/**
+ * Wrap a `GatewayEvent` into a platform-agnostic `NotificationEnvelope`.
+ * Used when a sink has `wrap_response: true` in its config. Unknown event
+ * types fall back to a generic title/summary so newly-emitted events do
+ * not require a code change to be deliverable.
+ */
+declare function wrapAsEnvelope(event: GatewayEvent): NotificationEnvelope;
+
+/**
+ * Payload passed to `NotificationSink.deliver`. `wrapped` discriminates
+ * which member of the union `payload` is. Sinks branch on `wrapped`
+ * rather than runtime-detecting the shape.
+ */
+interface NotificationSinkDeliverInput {
+    payload: GatewayEvent | NotificationEnvelope;
+    wrapped: boolean;
+}
+/**
+ * Hermes Phase 3 sink contract.
+ *
+ * Sinks subscribe to the orchestrator event bus via `wireNotificationSinks`
+ * and deliver each filtered event to a destination (chat channel, webhook
+ * URL, etc.). Delivery is best-effort: no retry, no persistence.
+ *
+ * Sinks MUST be idempotent w.r.t. their own delivery semantics — the bus
+ * may emit the same logical state transition more than once during testing
+ * or recovery. Sinks should not assume one-shot semantics.
+ */
+interface NotificationSink {
+    /** Stable id used in config + CLI; lowercase, kebab-case. */
+    readonly id: string;
+    /** Sink kind literal (matches `NotificationSinkKind`). */
+    readonly kind: string;
+    /** One-shot delivery. Returns Ok on 2xx, Err on any other outcome. */
+    deliver(input: NotificationSinkDeliverInput): Promise<NotificationDeliveryResult>;
+    /** Optional teardown hook called on orchestrator stop. */
+    dispose?(): Promise<void>;
+}
+
+interface SlackSinkOptions {
+    id: string;
+    webhookUrl: string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}
+/**
+ * Slack sink shipped with Hermes Phase 3. Uses incoming-webhook URLs only;
+ * OAuth + bot tokens are intentionally out of scope (spec D3). Sends one
+ * HTTP POST per delivery and never retries — retries are the operator's
+ * call via the Phase 0 webhook fanout if they need durable delivery.
+ */
+declare class SlackSink implements NotificationSink {
+    readonly kind = "slack";
+    readonly id: string;
+    private readonly webhookUrl;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(opts: SlackSinkOptions);
+    deliver(input: NotificationSinkDeliverInput): Promise<NotificationDeliveryResult>;
+    private renderEnvelope;
+    private renderRawEvent;
+}
+
+interface RegistryEntry {
+    config: NotificationSinkConfig;
+    adapter: NotificationSink;
+}
+interface FromConfigOptions {
+    env: NodeJS.ProcessEnv;
+    /** Optional per-sink fetch override (testing). */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Surfaced when a sink config refers to an unknown kind, or its env-var
+ * secret cannot be resolved. Carrying the sinkId helps the doctor + CLI
+ * print operator-actionable messages.
+ */
+declare class SinkConfigError extends Error {
+    readonly sinkId: string;
+    constructor(sinkId: string, message: string);
+}
+/**
+ * In-memory registry of configured notification sinks. Built once at
+ * orchestrator startup from `harness.config.json` `notifications.sinks[]`.
+ * Disposed on orchestrator stop.
+ */
+declare class SinkRegistry {
+    private readonly entries;
+    private constructor();
+    static fromConfig(config: NotificationsConfig, options: FromConfigOptions): SinkRegistry;
+    list(): readonly RegistryEntry[];
+    get(id: string): RegistryEntry | null;
+    ids(): string[];
+    dispose(): Promise<void>;
+}
+
+interface WireParams {
+    bus: EventEmitter;
+    registry: SinkRegistry;
+}
+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 };