Agent-System-Backend/pkg/extension/project_context.go

package extension

import (
	"context"

	core "agent-system-core"
)

// ProjectContextRegistry is optional. An in-process plugin may register one
// provider; existing Registry implementations are unchanged.
type ProjectContextRegistry interface {
	RegisterProjectContextProvider(ProjectContextProvider) error
}

// ProjectContextRequest is built by the host from an authenticated dispatch or
// persisted run. Plugins and model arguments cannot choose Actor or ProjectID.
type ProjectContextRequest struct {
	Actor          string
	PluginID       string
	ProjectID      core.ID
	ConversationID core.ID
	TaskID         core.ID
	RunID          core.ID
	StepID         core.ID
	Goal           string
	TargetID       string
	BudgetChars    int
	LastWatermark  string
}

type ProjectContextStatus string

const (
	ProjectContextReady      ProjectContextStatus = "ready"
	ProjectContextNotFound   ProjectContextStatus = "not-found"
	ProjectContextDenied     ProjectContextStatus = "denied"
	ProjectContextIncomplete ProjectContextStatus = "incomplete"
)

// ProjectContextItem is a currently authorized summary or requirement. Text is
// untrusted source material and must enter the model as user-level context.
type ProjectContextItem struct {
	SourceID string
	Revision string
	Hash     string
	Text     string
	Required bool
}

type ProjectEvidenceRef struct {
	ID       string
	SourceID string
	Revision string
	Hash     string
}

type ProjectContextBundle struct {
	Status             ProjectContextStatus
	ProjectID          core.ID
	Version            string
	Watermark          string
	AuthorizationEpoch string
	PublicationEpoch   string
	Items              []ProjectContextItem
	Evidence           []ProjectEvidenceRef
	Missing            []string
}

// ProjectEvidenceRequest permits only a reference returned by Resolve for the
// same trusted scope. The provider must recheck current access at read time.
type ProjectEvidenceRequest struct {
	Scope     ProjectContextRequest
	Reference ProjectEvidenceRef
}

type ProjectEvidence struct {
	Reference ProjectEvidenceRef
	Text      string
}

type ProjectContextProvider interface {
	Resolve(context.Context, ProjectContextRequest) (ProjectContextBundle, error)
	ReadEvidence(context.Context, ProjectEvidenceRequest) (ProjectEvidence, error)
}

// ProjectContextSourceRecheckRequest names only sources already present in a
// trusted model-input receipt. Scope identity is rebuilt by Backend from the
// persisted run; no prompt, output body, or caller-chosen owner is accepted.
type ProjectContextSourceRecheckRequest struct {
	Scope             ProjectContextRequest
	Included          []ProjectContextManifestEntry
	OfferedReferences []ProjectEvidenceRef
	ReadEvidence      []ProjectContextManifestEntry
}

// ProjectContextSourceRecheckResult contains current authorized source text
// only for transient Backend hash verification. It is never stored as a new
// model receipt. Every requested source/ref must be present in Bundle.
type ProjectContextSourceRecheckResult struct{ Bundle ProjectContextBundle }

// ProjectContextSourceRechecker is an optional method of the same registered
// ProjectContextProvider. Project workflow reuse fails closed without it.
//
// Fail-closed comparison contract: Backend compares the returned Bundle with
// the recorded receipt as a set of stable identities, never as provider-ordered
// output and never by the provider's own echo. Every recorded Included entry
// must be answered by exactly one item with the same SourceID, Revision and
// Hash whose text still hashes to the recorded InputSHA256; every recorded
// OfferedReference and ReadEvidence must be answered by the same
// (ID, SourceID, Revision, Hash); Missing must be equal as a set, so a benign
// reordering is accepted while an added, dropped or replaced entry is refused.
// Anything unproven, extra or absent rejects; reordering never widens
// authorization.
type ProjectContextSourceRechecker interface {
	Recheck(context.Context, ProjectContextSourceRecheckRequest) (ProjectContextSourceRecheckResult, error)
}

// WorkCompletionRequest gives the generation goal and optional target. It has
// no owner/project field; both are resolved from the dispatch host's stored
// conversation immediately before the model call.
type WorkCompletionRequest struct {
	Goal         string
	TargetID     string
	TaskID       string   // recovery locator only; host verifies its persisted owner/plugin/project binding
	EvidenceRefs []string // optional stable refs from the current provider bundle; no paths or owners
}

// WorkTaskHost creates a persisted task bound to this dispatch's authenticated
// owner, plugin, conversation and project. Legacy Host.TaskCreate is unbound and
// cannot be used to recover a WorkCompletionHost scope.
type WorkTaskHost interface {
	TaskCreateForWork(kind, title string) (taskID string, err error)
}

type ProjectContextManifestEntry struct {
	ReferenceID string
	SourceID    string
	Revision    string
	SourceHash  string
	InputSHA256 string
	Reason      string
}

// ProjectContextManifest describes the text actually passed to the completion
// client. Candidate references in a bundle are never listed as included input.
type ProjectContextManifest struct {
	ProjectID             core.ID
	TaskID                string
	Version               string
	Watermark             string
	AuthorizationEpoch    string
	PublicationEpoch      string
	AttemptID             string
	WorkflowStepAttemptID string
	Delivery              string // attempted | responded | unknown; never implies user-visible delivery
	Model                 string
	BudgetChars           int
	InputSHA256           string
	Included              []ProjectContextManifestEntry
	Dropped               []ProjectContextManifestEntry
	OfferedReferences     []ProjectEvidenceRef
	ReadEvidence          []ProjectContextManifestEntry
	Missing               []string
}

type WorkCompletionResult struct {
	Text     string
	Manifest ProjectContextManifest
}

// WorkCompletionHost is optional and available only on a dispatch-scoped Host.
// A Host obtained via NewScopedHost has no trusted conversation scope.
type WorkCompletionHost interface {
	CompleteForWork(context.Context, WorkCompletionRequest) (WorkCompletionResult, error)
}