inject

type AbortHandler func(ctx context.Context, req AbortRequest) error

type AbortRequest struct {
	// SessionID identifies the session to mark aborted.
	SessionID string `json:"session_id"`

	// Reason is the operator-supplied reason, recorded in the abort
	// marker and surfaced by `mast sessions list/show`.
	Reason string `json:"reason,omitempty"`
}

type AckEffectsHandler func(ctx context.Context, req AckEffectsRequest) error

type AckEffectsRequest struct {
	// SessionID identifies the session being acknowledged.
	SessionID string `json:"session_id"`

	// Reason is the operator-supplied note, recorded in the marker.
	Reason string `json:"reason,omitempty"`
}

type Config struct {
	// Listen is the bind address, e.g. ":7777".
	Listen string

	// BearerToken is the shared secret required in the Authorization
	// header. Empty disables auth (intended only for local development;
	// production deploys must set it).
	BearerToken string

	// Handler is called for each valid inject. Required.
	Handler Handler

	// ResumeHandler is called for each valid resume POST. Optional.
	ResumeHandler ResumeHandler

	// Authenticator, when set, resolves the caller identity behind a
	// /resume request and puts it on the handler's context
	// (auth.CallerFromContext). It runs IN ADDITION to BearerToken, not
	// instead of it: the shared token still admits the request, and
	// this says who presented it.
	//
	// Only /resume consults it, deliberately. An approval is the one
	// place in v0.3 where identity is load-bearing — "who authorized
	// this change" is the audit question the release exists to answer,
	// and it is the half that cannot be backfilled (docs/v0.3-plan.md
	// W2.1). Extending authentication to the other routes is a
	// behaviour change for every existing emitter and belongs with the
	// multi-session substrate, not here.
	//
	// Nil means unauthenticated: verdicts record the shared-credential
	// identity, which is honest about what a single bearer token can
	// prove.
	Authenticator auth.Authenticator

	// AssertedCallerHeader is the header a proxy Caller uses to assert
	// the effective identity. Empty means auth.HeaderAssertedCaller.
	// Ignored unless Authenticator implements auth.AuthenticatorWithProxy.
	AssertedCallerHeader string

	// AbortHandler is called for each valid abort POST. Optional.
	AbortHandler AbortHandler

	// AckEffectsHandler is called for each valid ack-effects POST.
	// Optional.
	AckEffectsHandler AckEffectsHandler

	// PauseHandler is called for each valid pause POST. Optional.
	PauseHandler PauseHandler

	// ExtendTokenHandler is called for each valid extend-token POST.
	// Optional.
	ExtendTokenHandler ExtendTokenHandler

	// StopHandler is called for each valid stop POST. Optional.
	StopHandler StopHandler

	// Logger is the structured logger. Defaults to slog.Default().
	Logger *slog.Logger

	// Metrics, when non-nil, is served at GET /metrics (Prometheus
	// scrape). Unauthenticated by design — scrape configs don't carry
	// the inject bearer token, and the payload is aggregate counters
	// only. Nil leaves the route unregistered.
	Metrics http.Handler

	// BaseContext, when non-nil, is the context every request context
	// derives from. The daemon passes its turn-lifetime context so
	// that when the shutdown drain window elapses, in-flight handler
	// turns are cancelled and unwind instead of dying at process exit.
	BaseContext context.Context
}

type ExtendTokenHandler func(ctx context.Context, req ExtendTokenRequest) (ExtendTokenResult, error)

type ExtendTokenRequest struct {
	// Token is the mast resume token (mrt_...).
	Token string `json:"token"`

	// TTL (Go duration) sets the new lifetime from now.
	TTL string `json:"ttl"`
}

type ExtendTokenResult struct {
	Token     string `json:"token"`
	ExpiresAt string `json:"expires_at"`
}

type Handler func(ctx context.Context, payload envelope.InjectPayload) error

type PauseHandler func(ctx context.Context, req PauseRequest) (PauseResult, error)

type PauseRequest struct {
	// SessionID identifies the session to pause.
	SessionID string `json:"session_id"`

	// Reason is the pause-reason enum value (transcript.ValidReasons).
	Reason string `json:"reason"`

	// Message is the human-readable context, surfaced by list/show.
	Message string `json:"message,omitempty"`

	// Metadata is free-form context recorded on the pause record.
	Metadata map[string]any `json:"metadata,omitempty"`

	// ResumeAt (RFC3339), when set, arms the timed-pause scheduler.
	ResumeAt string `json:"resume_at,omitempty"`

	// Interrupt additionally cancels the session's in-flight turn (hard
	// pause). The cancellation leaves no engine record — the pause
	// record is the durable truth — and may strand dangling mutating
	// intents for the effects outbox to guard.
	Interrupt bool `json:"interrupt,omitempty"`

	// TTL (Go duration, e.g. "48h") shortens the resume token's default
	// 7-day lifetime. Lengthening at mint is not offered — extend-token
	// is the audited operator path.
	TTL string `json:"ttl,omitempty"`
}

type PauseResult struct {
	Token     string `json:"token"`
	SessionID string `json:"session_id"`
	ExpiresAt string `json:"expires_at"`
}

type ResumeHandler func(ctx context.Context, req ResumeRequest) error

type ResumeRequest struct {
	// SessionID identifies the paused session (e.g. "incident-<uid>").
	// Not required when Token is set.
	SessionID string `json:"session_id,omitempty"`

	// InterruptID matches the pending RequestInput's InterruptID. Not
	// required when Token is set.
	InterruptID string `json:"interrupt_id,omitempty"`

	// Token is a mast resume token (mrt_...) minted at pause time —
	// the v0.2 programmatic-pause keying. Mutually exclusive with
	// SessionID/InterruptID.
	Token string `json:"token,omitempty"`

	// Response is the reply payload; validated against the interrupt's
	// ResponseSchema by the workflow engine on resume.
	Response any `json:"response"`

	// AckEffects acknowledges ambiguous prior effects before the resume
	// turn runs: dangling mutating tool calls from an interrupted turn
	// stop tripping the recorded-effect outbox's fail-closed refusal
	// (docs/durable-execution-design.md, "Recorded-effect outbox"). The
	// operator asserts they have checked whether those calls took
	// effect externally.
	AckEffects bool `json:"ack_effects,omitempty"`
}

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

type StopHandler func(ctx context.Context, req StopRequest) (StopResult, error)

type StopRequest struct {
	// Reason is appended to the interruption markers' "operator stop"
	// classification.
	Reason string `json:"reason,omitempty"`

	// PauseSessions gate-pauses every session that receives an
	// interruption marker during the drain, so boot-time auto-resume
	// hands them back to the operator instead of continuing them.
	PauseSessions bool `json:"pause_sessions,omitempty"`
}

type StopResult struct {
	DrainBound string `json:"drain_bound"`
}