Documentation
¶
Overview ¶
Package discover enumerates agent session files from each agent's known roots. It only locates files; reading their headers and resolving them to a project is the resolve package's job.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ErrorCount ¶ added in v0.5.5
ErrorCount returns the number of independent discovery failures represented by err. Non-discovery errors count as one so callers can use it at boundaries.
func Matches ¶
Matches reports whether a filename is a session file for the given agent. Codex files are named rollout-*.jsonl; Claude and pi use any *.jsonl. This is only a suffix gate: every agent's files are further validated by a positive session-header signature at resolve time (see resolve.sessionSignature), which is what keeps unrelated *.jsonl under a custom extra_root from being ingested.
func ResolveRoot ¶ added in v0.5.5
ResolveRoot applies the closed root-link policy to one candidate root and reports what discovery should do with it. discover.Discover and watch.Watcher's addRecursive both call this so the two traversal paths cannot drift: a root that discovery would reject or skip is rejected or skipped identically when watch (re)adds its filesystem watches.
A root that is a plain directory (the common case) resolves normally: dir is root.Dir. A root that is a symlink or, on Windows, a directory junction (see isWindowsReparsePoint) is a link standing in for the root, and is rejected by default: the closed policy that stops a link inside a walked root from being followed applies to the root itself for the same reason, escaping the configured location undetected. There is one exception, for the built-in per-agent default directories only (root.Optional): a linked Optional root is skipped with a non-fatal notice instead of an error, because those roots are opportunistic already (a missing one is silently skipped) and a user who junctioned their agent directory must opt in explicitly, but their sync must not start failing over it. Setting root.FollowRootLink resolves the link (any depth) to its target directory and walks that instead; the no-follow policy still applies to every path found inside the walk.
The returned err is nil whenever dir or notice is set; it is non-nil only when the root cannot be used at all (missing, not a directory, or a rejected link).
Types ¶
type Error ¶ added in v0.5.5
type Error struct {
// contains filtered or unexported fields
}
Error reports every root or entry that could not be traversed safely. Discover still returns files from the complete portions of the scan so callers can make progress, but they must surface this error and finish unsuccessfully.
type Excluder ¶
type Excluder struct {
// contains filtered or unexported fields
}
Excluder skips discovered paths that match any of a set of glob patterns, backing the config's `excludes` knob (config.Client.Excludes) so a user can keep a sensitive or noisy session directory from being discovered, watched, and uploaded. Patterns match against the full path with forward slashes, and `*` (or `**`) spans separators, so `**/tmp/**` excludes any path with a `tmp` segment and `*.private.jsonl` excludes by suffix anywhere. A zero Excluder (no patterns) excludes nothing, so callers that do not filter pass the zero value.
func NewExcluder ¶
NewExcluder compiles a set of exclude globs. Blank patterns are dropped and every pattern is normalized to forward slashes so a config written on one OS matches paths discovered on another.
func (Excluder) Excluded ¶
Excluded reports whether path matches any exclude pattern. The path is normalized to forward slashes before matching so the patterns are OS-agnostic.
func (Excluder) ExcludedDir ¶
ExcludedDir reports whether a directory should be pruned. A directory is matched both bare and with a trailing slash so either pattern style prunes it: the bare form catches an exact pattern like `**/private`, and the trailing-slash form catches a subtree pattern like `**/tmp/**` (whose trailing `**` needs the slash to match the directory node itself, not just files under it).
type File ¶
File is one discovered session file. Root is the discovery directory the file was found under: it is what lets resolution compute a stable, unique id from the file's location relative to the root, which is how Claude's subagent and workflow files (which all carry their parent's sessionId inside) avoid colliding on a single source id.
func Discover ¶
Discover walks every root and returns the session files it finds, de-duplicated by path and sorted for stable output. A missing optional built-in root is quiet; missing configured roots and every other incomplete traversal are returned as errors alongside files found in complete portions of the scan. Symlink roots and matching session-file symlinks are errors and are never followed (see ResolveRoot for the one exception: a linked Optional built-in root is skipped with a notice rather than an error). notices carries those non-fatal skips so a caller can report them without counting them as failures. ex drops paths the user configured to exclude (pass the zero Excluder to keep everything).
type Root ¶
type Root struct {
Agent string
Dir string
Optional bool // a missing built-in default is expected when its agent is unused
// FollowRootLink opts a root into resolving a symlink or (on Windows) a
// directory junction at the root itself before walking, when the directory an
// agent's sessions actually live under is only reachable through such a link
// (for example a Windows user who relocated their session directory with
// `mklink /J`). The default (false) rejects a linked root: see ResolveRoot.
// The no-follow policy still applies to everything found inside the walk
// regardless of this setting; it only ever affects the root path itself.
FollowRootLink bool
}
Root is a directory to scan for one agent's sessions.
Source Files