notices

type AutomationNotice struct {
	Name        string `json:"name"`
	DisplayName string `json:"display_name,omitempty"`
	// Reference dereferences the automation, for `fetch`.
	Reference string `json:"reference"`
	// Version is the version the failed run executed.
	Version int `json:"version"`
	// RunID is the failed run, for manage_script get_run.
	RunID string `json:"run_id"`
	// Cause is why it failed (script, upstream, transient, memory, ...), and
	// Retryable whether running it again is expected to succeed.
	Cause     string `json:"cause"`
	Retryable bool   `json:"retryable"`
	// Error is the failure's last line, which names what went wrong.
	Error string `json:"error,omitempty"`
	// ConsecutiveFailures is how many finished runs in a row have failed.
	ConsecutiveFailures int `json:"consecutive_failures"`
	// FailedAt is when the failed run finished, RFC3339.
	FailedAt string `json:"failed_at,omitempty"`
	// LastSucceededAt is when a run of it last succeeded, RFC3339; absent
	// when none has.
	LastSucceededAt string `json:"last_succeeded_at,omitempty"`
	// Scheduled is whether a schedule is set to fire it again.
	Scheduled bool `json:"scheduled"`
	// New is whether it failed since the caller was last briefed.
	New bool `json:"new"`
}

type AutomationSource interface {
	List(ctx context.Context, filter script.ListFilter) ([]script.Script, error)
	ListSchedules(ctx context.Context, filter script.ScheduleFilter) ([]script.Schedule, error)
	runstate.FailureStreakReader
}

type Digest struct {
	// Since is the watermark this digest covers, RFC3339. Everything reported
	// arrived after it.
	Since string `json:"since"`
	// Feedback lists unresolved threads on assets the caller owns, newest
	// activity first, capped at maxFeedbackNotices.
	Feedback []FeedbackNotice `json:"feedback,omitempty"`
	// FeedbackTotal is how many such threads exist. It exceeds len(Feedback)
	// when the cap truncated the list, so the agent can say how many were not
	// named rather than implying the list is complete.
	FeedbackTotal int `json:"feedback_total,omitempty"`
	// NewShares lists artifacts shared with the caller since the watermark,
	// newest first, capped at maxShareNotices.
	NewShares []ShareNotice `json:"new_shares,omitempty"`
	// NewSharesTruncated records that more shares arrived than the list holds.
	// The share query is bounded rather than counted, so the digest reports
	// "at least this many" rather than presenting a truncated list as the whole
	// set -- an unknown remainder is its own state, not zero.
	NewSharesTruncated bool `json:"new_shares_truncated,omitempty"`
	// FailingAutomations lists the automations the caller owns whose latest
	// finished run failed, newest failure first, capped at
	// maxAutomationNotices (#1934). Unlike the other lists it is not bounded
	// by the watermark: an automation that is still failing is still listed.
	//
	// It is not part of the notices block's JSON (#1971): releases up to
	// v1.137.1 advertised that block as a closed object, and a client still
	// holding one of those tool lists rejects a key it does not declare.
	// platform_info carries the list at its top level, which every release
	// since v1.102.0 has advertised open; see Failing.
	FailingAutomations []AutomationNotice `json:"-"`
	// FailingAutomationsTotal is how many there are, which exceeds the list
	// when the cap cut it.
	FailingAutomationsTotal int `json:"-"`
}

type FeedbackNotice struct {
	ThreadID string `json:"thread_id"`
	// Kind is the thread's classification (comment, question, correction, ...).
	Kind   string `json:"kind"`
	Status string `json:"status"`
	Title  string `json:"title,omitempty"`
	// AuthorEmail is who opened the thread; never the caller.
	AuthorEmail string `json:"author_email,omitempty"`
	AssetID     string `json:"asset_id"`
	AssetName   string `json:"asset_name,omitempty"`
	// AssetReference dereferences the asset the thread is on, for `fetch`.
	AssetReference string `json:"asset_reference"`
	// LastActivityAt is when the thread last moved, RFC3339.
	LastActivityAt string `json:"last_activity_at"`
}

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

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

type ShareNotice struct {
	// Kind is asset, collection, or prompt.
	Kind string `json:"kind"`
	ID   string `json:"id"`
	Name string `json:"name,omitempty"`
	// Reference dereferences the artifact, for `fetch`.
	Reference string `json:"reference"`
	// SharedBy is the person who made the grant, falling back to the artifact's
	// owner for a legacy row that recorded no creator.
	SharedBy string `json:"shared_by,omitempty"`
	// SharedAt is when the grant was made, RFC3339.
	SharedAt string `json:"shared_at"`
	// Permission is viewer or editor.
	Permission string `json:"permission,omitempty"`
}

type WatermarkStore interface {
	// Now returns the clock the watermark is kept on.
	//
	// A digest compares its boundary against timestamps the database stamped
	// (portal_shares.created_at defaults to NOW()), so the boundary has to be
	// read from that same clock. Stamping it from the process clock instead
	// compares two clocks: a few milliseconds of skew between the application
	// host and the database server is enough to place an already-delivered
	// share after the watermark and read it out to the caller a second time.
	Now(ctx context.Context) (time.Time, error)
	Get(ctx context.Context, userKey string) (*time.Time, error)
	Set(ctx context.Context, userKey string, at time.Time) error
}