Class StateManager

Singleton manager for persistent agent state stored in ~/.oss-autopilot/state.json.

Delegates file I/O to state-persistence.ts and scoring logic to repo-score-manager.ts. Retains lightweight CRUD operations for config, events, issues, shelving, dismissal, and status overrides.

Constructors

constructor

new StateManager(inMemoryOnly?: boolean): StateManager
Create a new StateManager instance.
Parameters
- inMemoryOnly: boolean = false
  When true, state is held only in memory and never read from or written to disk. Useful for unit tests that need isolated state without side effects. Defaults to false (normal persistent mode).
Returns StateManager
- Defined in core/state.ts:55

Methods

addClosedPRs

addClosedPRs(prs: { closedAt: string; title: string; url: string }[]): void
Add closed PRs to storage, deduplicating by URL.
Parameters
- prs: { closedAt: string; title: string; url: string }[]
  Closed PRs to add (duplicates by URL are ignored)
Returns void
- Defined in core/state.ts:275

addIssue

addIssue(
    issue: {
        createdAt: string;
        id: number;
        labels: string[];
        number: number;
        repo: string;
        status: "candidate" | "claimed" | "in_progress" | "pr_submitted";
        title: string;
        updatedAt: string;
        url: string;
        vetted: boolean;
        vettingResult?: {
            checks: {
                clearRequirements: boolean;
                contributionGuidelinesFound: boolean;
                noExistingPR: boolean;
                notClaimed: boolean;
                projectActive: boolean;
            };
            contributionGuidelines?: {
                branchNamingConvention?: string;
                claRequired?: boolean;
                commitMessageFormat?: string;
                formatter?: string;
                issueClaimProcess?: string;
                linter?: string;
                prTitleFormat?: string;
                rawContent?: string;
                requiredChecks?: string[];
                reviewProcess?: string;
                styleGuideUrl?: string;
                testCoverageRequired?: boolean;
                testFileNaming?: string;
                testFramework?: string;
            };
            notes: string[];
            passedAllChecks: boolean;
        };
    },
): void
Track a new issue. No-op if the issue URL is already tracked.
Parameters
- issue: {
      createdAt: string;
      id: number;
      labels: string[];
      number: number;
      repo: string;
      status: "candidate" | "claimed" | "in_progress" | "pr_submitted";
      title: string;
      updatedAt: string;
      url: string;
      vetted: boolean;
      vettingResult?: {
          checks: {
              clearRequirements: boolean;
              contributionGuidelinesFound: boolean;
              noExistingPR: boolean;
              notClaimed: boolean;
              projectActive: boolean;
          };
          contributionGuidelines?: {
              branchNamingConvention?: string;
              claRequired?: boolean;
              commitMessageFormat?: string;
              formatter?: string;
              issueClaimProcess?: string;
              linter?: string;
              prTitleFormat?: string;
              rawContent?: string;
              requiredChecks?: string[];
              reviewProcess?: string;
              styleGuideUrl?: string;
              testCoverageRequired?: boolean;
              testFileNaming?: string;
              testFramework?: string;
          };
          notes: string[];
          passedAllChecks: boolean;
      };
  }
  The issue to track
Returns void
- Defined in core/state.ts:355

addMergedPRs

addMergedPRs(prs: { mergedAt: string; title: string; url: string }[]): void
Add merged PRs to storage, deduplicating by URL.
Parameters
- prs: { mergedAt: string; title: string; url: string }[]
  Merged PRs to add (duplicates by URL are ignored)
Returns void
- Defined in core/state.ts:247

addTrustedProject

addTrustedProject(repo: string): void
Add a repository to the trusted projects list. No-op if already trusted.
Parameters
- repo: string
  Repository in "owner/repo" format
Returns void
- Defined in core/state.ts:373

appendEvent

appendEvent(
    type:
        | "pr_tracked"
        | "pr_merged"
        | "pr_closed"
        | "pr_dormant"
        | "daily_check"
        | "comment_posted",
    data: Record<string, unknown>,
): void
Append a new event to the event log and auto-persist. Events are capped at 1000 to prevent unbounded growth.
Parameters
- type:
      | "pr_tracked"
      | "pr_merged"
      | "pr_closed"
      | "pr_dormant"
      | "daily_check"
      | "comment_posted"
  The event type identifier
- data: Record<string, unknown>
  Arbitrary event payload
Returns void
- Defined in core/state.ts:311

batch

batch(fn: () => void): void
Execute multiple mutations as a single batch, deferring disk I/O until the batch completes. Nested batch() calls are flattened — only the outermost saves.
Parameters
- fn: () => void
  The function containing mutations to batch
Returns void
- Defined in core/state.ts:85

cleanupExcludedData

cleanupExcludedData(repos: string[], orgs: string[]): void
Remove excluded repos/orgs from trusted projects.
Parameters
- repos: string[]
  Repository names to exclude
- orgs: string[]
  Organization names to exclude
Returns void
- Defined in core/state.ts:393

clearStatusOverride

clearStatusOverride(url: string): boolean
Remove a manual status override for a PR.
Parameters
- url: string
  The PR URL
Returns boolean
true if an override was removed, false if none existed
- Defined in core/state.ts:550

dismissIssue

dismissIssue(url: string, timestamp: string): boolean
Dismiss an issue's notifications. Auto-resurfaces on new activity.
Parameters
- url: string
  The issue URL to dismiss
- timestamp: string
  ISO timestamp of dismissal
Returns boolean
true if newly dismissed, false if already dismissed
- Defined in core/state.ts:491

getClosedPRs

getClosedPRs(): { closedAt: string; title: string; url: string }[]
Returns all stored closed-without-merge PRs (sorted by close date descending via addClosedPRs).

Returns { closedAt: string; title: string; url: string }[]
- Defined in core/state.ts:267

getClosedPRWatermark

getClosedPRWatermark(): string | undefined
Returns the most recent close date, used as a watermark for incremental fetching.

Returns string | undefined
- Defined in core/state.ts:288

getEventsByType

getEventsByType(
    type:
        | "pr_tracked"
        | "pr_merged"
        | "pr_closed"
        | "pr_dormant"
        | "daily_check"
        | "comment_posted",
): {
    at: string;
    data: Record<string, unknown>;
    id: string;
    type:
        | "pr_tracked"
        | "pr_merged"
        | "pr_closed"
        | "pr_dormant"
        | "daily_check"
        | "comment_posted";
}[]
Filter events by type.
Parameters
- type:
      | "pr_tracked"
      | "pr_merged"
      | "pr_closed"
      | "pr_dormant"
      | "daily_check"
      | "comment_posted"
  The event type to filter by
Returns {
    at: string;
    data: Record<string, unknown>;
    id: string;
    type:
        | "pr_tracked"
        | "pr_merged"
        | "pr_closed"
        | "pr_dormant"
        | "daily_check"
        | "comment_posted";
}[]
Events matching the given type
- Defined in core/state.ts:332

getEventsInRange

getEventsInRange(
    since: Date,
    until?: Date,
): {
    at: string;
    data: Record<string, unknown>;
    id: string;
    type:
        | "pr_tracked"
        | "pr_merged"
        | "pr_closed"
        | "pr_dormant"
        | "daily_check"
        | "comment_posted";
}[]
Filter events within a date range.
Parameters
- since: Date
  Start of range (inclusive)
- until: Date = ...
  End of range (inclusive), defaults to now
Returns {
    at: string;
    data: Record<string, unknown>;
    id: string;
    type:
        | "pr_tracked"
        | "pr_merged"
        | "pr_closed"
        | "pr_dormant"
        | "daily_check"
        | "comment_posted";
}[]
Events within the date range
- Defined in core/state.ts:342

getHighScoringRepos

getHighScoringRepos(minScore?: number): string[]
Returns repos above the score threshold.
Parameters
- OptionalminScore: number
  Minimum score (default: config.minRepoScoreThreshold)
Returns string[]
- Defined in core/state.ts:639

getIssueDismissedAt

getIssueDismissedAt(url: string): string | undefined
Get the timestamp when an issue was dismissed, or undefined if not dismissed.
Parameters
- url: string
  The issue URL to check
Returns string | undefined
- Defined in core/state.ts:521

getLowScoringRepos

getLowScoringRepos(maxScore?: number): string[]
Returns repos below the score threshold.
Parameters
- OptionalmaxScore: number
  Maximum score (default: config.minRepoScoreThreshold)
Returns string[]
- Defined in core/state.ts:647

getMergedPRs

getMergedPRs(): { mergedAt: string; title: string; url: string }[]
Returns all stored merged PRs (sorted by merge date descending via addMergedPRs).

Returns { mergedAt: string; title: string; url: string }[]
- Defined in core/state.ts:239

getMergedPRWatermark

getMergedPRWatermark(): string | undefined
Returns the most recent merge date, used as a watermark for incremental fetching.

Returns string | undefined
- Defined in core/state.ts:260

getRepoScore

getRepoScore(
    repo: string,
):
    | Readonly<
        {
            avgResponseDays: number
            | null;
            closedWithoutMergeCount: number;
            language?: string | null;
            lastEvaluatedAt: string;
            lastMergedAt?: string;
            mergedPRCount: number;
            repo: string;
            score: number;
            signals: {
                hasActiveMaintainers: boolean;
                hasHostileComments: boolean;
                isResponsive: boolean;
            };
            stargazersCount?: number;
        },
    >
    | undefined
Get the score record for a repository.
Parameters
- repo: string
  Repository in "owner/repo" format
Returns
    | Readonly<
        {
            avgResponseDays: number
            | null;
            closedWithoutMergeCount: number;
            language?: string | null;
            lastEvaluatedAt: string;
            lastMergedAt?: string;
            mergedPRCount: number;
            repo: string;
            score: number;
            signals: {
                hasActiveMaintainers: boolean;
                hasHostileComments: boolean;
                isResponsive: boolean;
            };
            stargazersCount?: number;
        },
    >
    | undefined
Read-only score record, or undefined if not tracked
- Defined in core/state.ts:584

getReposWithMergedPRs

getReposWithMergedPRs(): string[]
Returns repository names that have at least one merged PR.

Returns string[]
- Defined in core/state.ts:626

getReposWithOpenPRs

getReposWithOpenPRs(): string[]
Returns repository names with open PRs but no merged PRs yet.

Returns string[]
- Defined in core/state.ts:631

getStarredRepos

getStarredRepos(): string[]
Returns cached starred repository names.

Returns string[]
- Defined in core/state.ts:409

getState

getState(): Readonly<AgentState>
Get the current state as a read-only snapshot.

Returns Readonly<AgentState>
- Defined in core/state.ts:161

getStats

getStats(): Stats
Returns aggregate contribution statistics (merge rate, PR counts, repo breakdown).

Returns Stats
- Defined in core/state.ts:652

getStatusOverride

getStatusOverride(
    url: string,
    currentUpdatedAt?: string,
):
    | {
        lastActivityAt: string;
        setAt: string;
        status: "needs_addressing"
        | "waiting_on_maintainer";
    }
    | undefined
Get the status override for a PR, auto-clearing if new activity has occurred.
Parameters
- url: string
  The PR URL
- OptionalcurrentUpdatedAt: string
  PR's current updatedAt timestamp for staleness check
Returns
    | {
        lastActivityAt: string;
        setAt: string;
        status: "needs_addressing"
        | "waiting_on_maintainer";
    }
    | undefined
The override if still valid, undefined otherwise
- Defined in core/state.ts:565

incrementClosedCount

incrementClosedCount(repo: string): void
Increment the closed-without-merge PR count.
Parameters
- repo: string
  Repository in "owner/repo" format
Returns void
- Defined in core/state.ts:611

incrementMergedCount

incrementMergedCount(repo: string): void
Increment the merged PR count for a repository.
Parameters
- repo: string
  Repository in "owner/repo" format
Returns void
- Defined in core/state.ts:602

initializeWithDefaults

initializeWithDefaults(username: string): void
Initialize state with sensible defaults for zero-config onboarding. No-op if setup is already complete.
Parameters
- username: string
Returns void
- Defined in core/state.ts:132

isPRShelved

isPRShelved(url: string): boolean
Check if a PR is currently shelved.
Parameters
- url: string
  The PR URL to check
Returns boolean
true if the PR is shelved
- Defined in core/state.ts:479

isSetupComplete

isSetupComplete(): boolean
Check if initial setup has been completed.

Returns boolean
- Defined in core/state.ts:115

isStarredReposStale

isStarredReposStale(): boolean
Returns true if starred repos cache is older than 24 hours.

Returns boolean
- Defined in core/state.ts:425

markRepoHostile

markRepoHostile(repo: string): void
Mark a repository as hostile (score zeroed).
Parameters
- repo: string
  Repository in "owner/repo" format
Returns void
- Defined in core/state.ts:620

markSetupComplete

markSetupComplete(): void
Mark setup as complete and record the completion timestamp.

Returns void
- Defined in core/state.ts:122

reloadIfChanged

reloadIfChanged(): boolean
Re-read state from disk if the file has been modified since the last load/save. Returns true if state was reloaded, false if unchanged or in-memory mode.

Returns boolean
- Defined in core/state.ts:169

save

save(): void
Persist the current state to disk, creating a timestamped backup of the previous state file first. In in-memory mode, only updates lastRunAt without any file I/O.

Returns void
- Defined in core/state.ts:148

setDailyActivityCounts

setDailyActivityCounts(counts: Record<string, number>): void
Update daily activity counts for dashboard display.
Parameters
- counts: Record<string, number>
  Daily activity counts keyed by YYYY-MM-DD
Returns void
- Defined in core/state.ts:222

setLastDigest

setLastDigest(
    digest: {
        autoUnshelvedPRs: {
            daysSinceActivity: number;
            number: number;
            repo: string;
            status: "needs_addressing" | "waiting_on_maintainer";
            title: string;
            url: string;
        }[];
        generatedAt: string;
        needsAddressingPRs: any[];
        openPRs: any[];
        recentlyClosedPRs: {
            closedAt: string;
            closedBy?: string;
            number: number;
            repo: string;
            title: string;
            url: string;
        }[];
        recentlyMergedPRs: {
            mergedAt: string;
            number: number;
            repo: string;
            title: string;
            url: string;
        }[];
        shelvedPRs: {
            daysSinceActivity: number;
            number: number;
            repo: string;
            status: "needs_addressing"
            | "waiting_on_maintainer";
            title: string;
            url: string;
        }[];
        summary: {
            mergeRate: number;
            totalActivePRs: number;
            totalMergedAllTime: number;
            totalNeedingAttention: number;
        };
        waitingOnMaintainerPRs: any[];
    },
): void
Store the latest daily digest and update the digest timestamp.
Parameters
- digest: {
      autoUnshelvedPRs: {
          daysSinceActivity: number;
          number: number;
          repo: string;
          status: "needs_addressing" | "waiting_on_maintainer";
          title: string;
          url: string;
      }[];
      generatedAt: string;
      needsAddressingPRs: any[];
      openPRs: any[];
      recentlyClosedPRs: {
          closedAt: string;
          closedBy?: string;
          number: number;
          repo: string;
          title: string;
          url: string;
      }[];
      recentlyMergedPRs: {
          mergedAt: string;
          number: number;
          repo: string;
          title: string;
          url: string;
      }[];
      shelvedPRs: {
          daysSinceActivity: number;
          number: number;
          repo: string;
          status: "needs_addressing"
          | "waiting_on_maintainer";
          title: string;
          url: string;
      }[];
      summary: {
          mergeRate: number;
          totalActivePRs: number;
          totalMergedAllTime: number;
          totalNeedingAttention: number;
      };
      waitingOnMaintainerPRs: any[];
  }
  The daily digest to store
Returns void
- Defined in core/state.ts:185

setLocalRepoCache

setLocalRepoCache(
    cache: {
        cachedAt: string;
        repos: Record<
            string,
            { currentBranch: string
            | null; exists: boolean; path: string },
        >;
        scanPaths: string[];
    },
): void
Update the local repository cache.
Parameters
- cache: {
      cachedAt: string;
      repos: Record<
          string,
          { currentBranch: string
          | null; exists: boolean; path: string },
      >;
      scanPaths: string[];
  }
  Local repository cache mapping repo names to paths
Returns void
- Defined in core/state.ts:231

setMonthlyClosedCounts

setMonthlyClosedCounts(counts: Record<string, number>): void
Update monthly closed PR counts for dashboard display.
Parameters
- counts: Record<string, number>
  Monthly closed PR counts keyed by YYYY-MM
Returns void
- Defined in core/state.ts:204

setMonthlyMergedCounts

setMonthlyMergedCounts(counts: Record<string, number>): void
Update monthly merged PR counts for dashboard display.
Parameters
- counts: Record<string, number>
  Monthly merged PR counts keyed by YYYY-MM
Returns void
- Defined in core/state.ts:195

setMonthlyOpenedCounts

setMonthlyOpenedCounts(counts: Record<string, number>): void
Update monthly opened PR counts for dashboard display.
Parameters
- counts: Record<string, number>
  Monthly opened PR counts keyed by YYYY-MM
Returns void
- Defined in core/state.ts:213

setStarredRepos

setStarredRepos(repos: string[]): void
Update the cached starred repositories and timestamp.
Parameters
- repos: string[]
  Repository names in "owner/repo" format
Returns void
- Defined in core/state.ts:417

setStatusOverride

setStatusOverride(
    url: string,
    status: "needs_addressing" | "waiting_on_maintainer",
    lastActivityAt: string,
): void
Set a manual status override for a PR. Auto-clears when the PR has new activity.
Parameters
- url: string
  The PR URL
- status: "needs_addressing" | "waiting_on_maintainer"
  The overridden status
- lastActivityAt: string
  ISO timestamp of PR's last activity when override was set
Returns void
- Defined in core/state.ts:533

shelvePR

shelvePR(url: string): boolean
Shelve a PR URL, hiding it from daily digest and capacity.
Parameters
- url: string
  The PR URL to shelve
Returns boolean
true if newly shelved, false if already shelved
- Defined in core/state.ts:444

undismissIssue

undismissIssue(url: string): boolean
Restore a dismissed issue to notifications.
Parameters
- url: string
  The issue URL to undismiss
Returns boolean
true if undismissed, false if not currently dismissed
- Defined in core/state.ts:508

unshelvePR

unshelvePR(url: string): boolean
Unshelve a PR URL, restoring it to daily digest.
Parameters
- url: string
  The PR URL to unshelve
Returns boolean
true if removed from shelf, false if not shelved
- Defined in core/state.ts:461

updateConfig

updateConfig(config: Partial<AgentState["config"]>): void
Merge partial config updates into the current configuration.
Parameters
- config: Partial<AgentState["config"]>
  Partial config object to merge
Returns void
- Defined in core/state.ts:298

updateRepoScore

updateRepoScore(repo: string, updates: RepoScoreUpdate): void
Update scoring data for a repository.
Parameters
- repo: string
  Repository in "owner/repo" format
- updates: RepoScoreUpdate
  Partial score fields to merge
Returns void
- Defined in core/state.ts:593

Class StateManager

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns StateManager

Methods

addClosedPRs

Parameters

Returns void

addIssue

Parameters

Returns void

addMergedPRs

Parameters

Returns void

addTrustedProject

Parameters

Returns void

appendEvent

Parameters

Returns void

batch

Parameters

Returns void

cleanupExcludedData

Parameters

Returns void

clearStatusOverride

Parameters

Returns boolean

dismissIssue

Parameters

Returns boolean

getClosedPRs

Returns { closedAt: string; title: string; url: string }[]

getClosedPRWatermark

Returns string | undefined

getEventsByType

Parameters

Returns { at: string; data: Record<string, unknown>; id: string; type: | "pr_tracked" | "pr_merged" | "pr_closed" | "pr_dormant" | "daily_check" | "comment_posted";}[]

getEventsInRange

Parameters

Returns { at: string; data: Record<string, unknown>; id: string; type: | "pr_tracked" | "pr_merged" | "pr_closed" | "pr_dormant" | "daily_check" | "comment_posted";}[]

getHighScoringRepos

Parameters

Returns string[]

getIssueDismissedAt

Parameters

Returns string | undefined

getLowScoringRepos

Parameters

Returns string[]

getMergedPRs

Returns { mergedAt: string; title: string; url: string }[]

getMergedPRWatermark

Returns string | undefined

getRepoScore

Parameters

getReposWithMergedPRs

Returns string[]

getReposWithOpenPRs

Returns string[]

getStarredRepos

Returns string[]

getState

Returns Readonly<AgentState>

getStats

Returns Stats

getStatusOverride

Parameters

Returns | { lastActivityAt: string; setAt: string; status: "needs_addressing" | "waiting_on_maintainer"; } | undefined

incrementClosedCount

Parameters

Returns void

incrementMergedCount

Parameters

Returns void

Returns {
at: string;
data: Record<string, unknown>;
id: string;
type:
| "pr_tracked"
| "pr_merged"
| "pr_closed"
| "pr_dormant"
| "daily_check"
| "comment_posted";
}[]

Returns {
at: string;
data: Record<string, unknown>;
id: string;
type:
| "pr_tracked"
| "pr_merged"
| "pr_closed"
| "pr_dormant"
| "daily_check"
| "comment_posted";
}[]

Returns
| {
lastActivityAt: string;
setAt: string;
status: "needs_addressing"
| "waiting_on_maintainer";
}
| undefined