statuscomment

package
v0.44.0-rc.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 1, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package statuscomment posts agent start/completion status comments on issues and pull requests via the tracker abstraction.

Unlike internal/sticky, which manages persistent bot comments that accumulate history across multiple runs (e.g. review output), statuscomment manages transient lifecycle markers: a start comment created when the agent begins, then updated or replaced on completion (including cancellation). GitHub and GitLab use invisible HTML markers; Jira stores the same bookkeeping in comment entity properties.

The notification destination is dynamically determined by event provenance: a Jira-triggered run posts status to Jira, a GitHub-triggered run posts to GitHub, independently of the forge used for code output (branches, PRs/MRs). This event-source routing is implemented via tracker.Client and recorded in ADR 0093.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BuildRunInfoFooter added in v0.38.0

func BuildRunInfoFooter(info *RunInfo) string

BuildRunInfoFooter renders the optional runtime/model/effort/cost line for the terminal status comment. Unknown fields are omitted.

func ReconcileOrphaned added in v0.18.0

func ReconcileOrphaned(ctx context.Context, client tracker.Client, project string, number int, runID, runURL, sha string, reason TerminationReason, completionMode, jobStatus string, wasSkipped bool, agentDescription string) error

ReconcileOrphaned finds and finalizes a status comment that was left in "Started" state because the process was hard-killed (SIGKILL, OOM, etc.) before the deferred PostCompletion call could run.

It searches for a comment matching the run's status metadata that has not reached a terminal state. Jira uses comment properties; GitHub and GitLab use the fullsend:agent-status and fullsend:status:terminal HTML markers. If found in a non-terminal state, it updates the comment to "Interrupted" and records it as terminal.

completionMode is the configured comment.completion value ("enabled", "on_failure", or "disabled"). It changes what an absent marker means:

  • "on_failure": no start comment marker is ever created, so an absent marker doesn't by itself indicate a problem. It may mean the process was hard-killed before PostCompletion could run. See PR #5736.
  • "" or "enabled" (the default): a status comment should exist for every run that reached the harness, win or lose. An absent marker here means the process crashed before it could post anything at all (e.g. during environment validation) — a blind spot where maintainers can't tell "no review was triggered" from "review was attempted and failed silently." See #3635.
  • "disabled": an explicit opt-out of all status comments. An absent marker is never synthesized in this mode, regardless of outcome.

jobStatus is the GitHub Actions job status (e.g., "success", "failure", "cancelled"). Synthesis is skipped when jobStatus is "success" or empty — "success" means the run completed normally, and empty means the job outcome is unknown (e.g., --job-status was omitted). wasSkipped overrides this for "on_failure" mode only: it's true when the pre-script itself decided to skip the run, which means jobStatus can be "success" even though no completion comment ended up recorded for it (its error is only logged, not propagated to the job's exit code). See PR #5736.

agentDescription is used as the heading for a synthesized "Interrupted" comment (e.g. "Code" for the code agent), so operators can tell which agent failed when multiple agents run against the same issue/PR.

This function is designed to be called from an out-of-process cleanup mechanism (e.g., a GitHub Actions post-job step) that runs even when the fullsend process is killed. It does not require a Notifier instance since the process that created it is gone.

Known limitation: this does not reconcile an orphaned start reaction (see Notifier.startReactionID). Comments carry recoverable status metadata; reactions have no equivalent identity that survives the process, so a hard-killed run can leave a stray 👀 reaction behind indefinitely.

Returns an error if runID contains characters outside [a-zA-Z0-9_-].

Types

type ClientFactory added in v0.18.0

type ClientFactory func(ctx context.Context) (tracker.Client, error)

ClientFactory returns a fresh tracker.Client. It is called before each API operation so the underlying token is never stale.

type Notifier

type Notifier struct {
	// contains filtered or unexported fields
}

Notifier manages status comment lifecycle for a single agent run. The notification destination is dynamically determined by the event source — callers wire in the appropriate tracker.Client adapter based on which system originated the triggering event.

func New

func New(client tracker.Client, cfg config.StatusNotificationConfig,
	project string, number int, runURL, sha, runID string) *Notifier

New creates a Notifier. The runID becomes either an invisible HTML marker or tracker-native status metadata so concurrent runs don't collide. It panics if runID contains characters outside [a-zA-Z0-9_-].

project identifies the issue's container: "owner/repo" for GitHub/GitLab, a Jira project key for Jira.

func (*Notifier) HasClientFactory added in v0.18.0

func (n *Notifier) HasClientFactory() bool

HasClientFactory reports whether a client factory has been configured.

func (*Notifier) InvokeClientFactory added in v0.19.0

func (n *Notifier) InvokeClientFactory(ctx context.Context) (tracker.Client, error)

InvokeClientFactory calls the configured factory and returns the result. Useful for verifying factory wiring in tests without triggering API calls.

func (*Notifier) PostCompletion

func (n *Notifier) PostCompletion(ctx context.Context, description, status string) error

PostCompletion posts or edits a completion comment with no extra detail. See PostCompletionWithDetail.

func (*Notifier) PostCompletionWithDetail added in v0.33.0

func (n *Notifier) PostCompletionWithDetail(ctx context.Context, description, status, detail string) error

PostCompletionWithDetail posts or edits a completion comment. status should be "success", "failure", "cancelled", or "skipped".

detail is an optional short explanation rendered after the status label (e.g. the pre-script's skip reason). It may come from script output, so it is sanitized before rendering — see sanitizeDetail.

Placement follows three rules:

  1. If the agent posted output after the start comment (a bot-authored comment that is not a status marker), the start comment is updated in place — the agent's output is the visible forward signal and a separate end comment would be redundant.
  2. If no agent output was posted and the start comment is still the last entry on the timeline, the start comment is updated in place.
  3. Otherwise (other activity pushed past the start, but no agent output), a new completion comment is posted so the user sees the result while reading forward.

func (*Notifier) PostStart

func (n *Notifier) PostStart(ctx context.Context, description string) error

PostStart posts a start comment on the issue/PR.

When completion is set to "on_failure", the start comment is automatically suppressed regardless of the start setting. Posting a start comment that gets deleted on success would still trigger a GitHub notification pointing to a deleted comment — defeating the purpose of reducing noise.

func (*Notifier) SetClientFactory added in v0.18.0

func (n *Notifier) SetClientFactory(f ClientFactory)

SetClientFactory sets a factory that mints a fresh tracker.Client before each API operation. When set, the static client passed to New is only used if the factory is nil.

func (*Notifier) SetRunInfo added in v0.38.0

func (n *Notifier) SetRunInfo(info RunInfo)

SetRunInfo sets optional runtime/model metadata rendered in the terminal status comment footer.

func (*Notifier) SetTriggerCommentID added in v0.38.0

func (n *Notifier) SetTriggerCommentID(id string)

SetTriggerCommentID records the ID of the comment that triggered this run via a slash command. When set, start/completion reactions target that comment instead of the issue/PR itself — matching the behavior a human collaborator would expect from a reply, not a reaction to the whole thread. Has no effect on comments, which always post to the issue/PR regardless of what triggered the run.

func (*Notifier) SetWarnFunc

func (n *Notifier) SetWarnFunc(f func(string, ...any))

SetWarnFunc sets a function called for non-fatal warnings (e.g. API errors during fail-open operations). Defaults to a no-op.

type RunInfo added in v0.38.0

type RunInfo struct {
	Runtime        string  // e.g. "claude", "pi"
	RequestedModel string  // model the harness/agent asked for
	ReportedModel  string  // model the provider actually used
	Effort         string  // e.g. "medium", "high"
	CostUSD        float64 // total cost; zero means unknown
}

RunInfo holds optional runtime/model metadata surfaced in the terminal status comment footer. All fields are optional — omitted fields are excluded from the rendered line.

type TerminationReason added in v0.18.0

type TerminationReason string

TerminationReason describes why the agent process was terminated.

const (
	ReasonTerminated TerminationReason = "terminated"
	ReasonCancelled  TerminationReason = "cancelled"

	// ReasonSkipCommentFailed is used when the pre-script decided to skip
	// the run but no completion comment ended up recorded for it, while the
	// job otherwise completed normally (jobStatus is "success" or
	// unknown). The missing comment could mean the notifier failed to set
	// up (no post was ever attempted) or that PostCompletionWithDetail's
	// own skip-reason comment failed to post — this function can't tell
	// those apart, so the label stays outcome-neutral rather than
	// asserting a specific cause. It's semantically distinct from a hard
	// kill or job cancellation — the agent ran to completion — so it gets
	// a dedicated label rather than falling through to ReasonTerminated.
	// See PR #5736.
	ReasonSkipCommentFailed TerminationReason = "skip_comment_failed"
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL