Git designed for AI agents.
// Package resolver is the server side of the graft-resolve protocol v1 (see
// doc/graft/RESOLVE.md). It holds the request and response types, the
// acceptance rules the server applies to every answer (Validate), a Client
// that calls an operator-chosen resolver over a command or an HTTP endpoint,
// and the path and actor policy that decides which conflicts may be sent to
// it.
//
// The server never talks to an LLM or a vendor API: the resolver is any
// program or endpoint the operator configures.
package resolver
import (
"encoding/base64"
"encoding/json"
)
// ProtocolVersion is the only protocol version this package speaks.
const ProtocolVersion = 1
// MaxResolverNameBytes bounds Response.Resolver, the name of the resolver that
// the server writes into the Graft-Resolved-By commit trailer. A longer name is
// rejected. tools/graft-agents mirrors this value.
const MaxResolverNameBytes = 128
// File kinds of Request.Files.
const (
KindContent = "content"
KindModifyDelete = "modify-delete"
KindAddAdd = "add-add"
KindMode = "mode"
)
// Actions of ResponseFile.
const (
ActionWrite = "write"
ActionDelete = "delete"
)
// Git file modes accepted in responses.
const (
ModeRegular = "100644"
ModeExecutable = "100755"
ModeSymlink = "120000"
)
// Request is the resolve request the server sends to the resolver.
// Ours is the current branch tip side, Theirs the change being landed. Any
// side may be nil (absent).
type Request struct {
Version int `json:"version"`
// Operation is OperationResolve (also when absent) or OperationCheck.
Operation string `json:"operation,omitempty"`
Repository Repository `json:"repository"`
Branch string `json:"branch"`
Tip string `json:"tip"`
Commit string `json:"commit"`
MergeBase string `json:"merge_base"`
Messages Messages `json:"messages"`
Actor string `json:"actor"`
Files []File `json:"files"`
// Resolution is, for OperationCheck only, the agent's resolution of Files to check.
Resolution []ResponseFile `json:"resolution,omitempty"`
Limits Limits `json:"limits"`
// Capabilities are what the server that sends the request does with a resolver's answers (the
// Capability constants). A server that sets none is an older one, which lands every answer that
// graft-resolve gives without verification: graft-resolve then gives no model's resolution
// (resolve.Resolver.resolveFile).
Capabilities []string `json:"capabilities,omitempty"`
// RulesOnly asks the resolver to run only its rules (the strategies whose answers are a rule's:
// trivial, union, rerere, a command with origin "rule") and never to call a model: the lane of
// the server asks it so when it resolves a member inline, within a bound of time. What the rules
// cannot resolve is left unresolved. A resolver that honours it says so in Response.RulesOnly.
RulesOnly bool `json:"rules_only,omitempty"`
}
// The capabilities of a server (Request.Capabilities).
const (
// CapabilityOrigin: the server reads the origin of a resolved file and lands only the files of a rule
// without verification.
CapabilityOrigin = "origin"
// CapabilityProposal: a file the server does not know to be a rule's is a model's, a proposal that
// lands only on a tree that verify.command passed on.
CapabilityProposal = "proposal"
// CapabilityHold: the server never lands a file with a hold (ResponseFile.Hold).
CapabilityHold = "hold"
// CapabilityVerify: the server verifies the exact tree that lands (verify.command) and lands a model's
// resolution on no other.
CapabilityVerify = "verify"
)
// ServerCapabilities returns the capabilities of this server, sent with every resolve request. Every
// call returns a new slice, which nothing can change for the next request.
func ServerCapabilities() []string {
return []string{CapabilityOrigin, CapabilityProposal, CapabilityHold, CapabilityVerify}
}
// Operations of a request.
const (
// OperationResolve asks the resolver to resolve Files; an absent operation means it.
OperationResolve = "resolve"
// OperationCheck asks the resolver to check an agent's Resolution of Files with the checks of
// its own answers, and to answer a CheckResponse.
OperationCheck = "check"
)
// CheckResponse is the answer to an OperationCheck request: one verdict per file of the
// resolution, in its order.
type CheckResponse struct {
Version int `json:"version"`
Operation string `json:"operation"`
// Resolver names the checker, for the Graft-Checked-By trailer.
Resolver string `json:"resolver"`
Files []CheckFile `json:"files"`
}
// Syntax verdicts of a CheckFile.
const (
// SyntaxChecked: both sides parse, and so does the resolution.
SyntaxChecked = "checked"
// SyntaxUnchecked: a side does not parse with the grammar, so the resolution got no syntax
// verdict.
SyntaxUnchecked = "unchecked"
// SyntaxNone: the path has no grammar, or the file is deleted.
SyntaxNone = "none"
)
// CheckFile is the verdict on one file of a resolution.
type CheckFile struct {
Path string `json:"path"`
OK bool `json:"ok"`
Reason string `json:"reason,omitempty"`
Syntax string `json:"syntax"`
}
// ErrorResponse is the body of a refusal: the HTTP 422 answer, or the stdout of
// a command that exits non-zero. Files is optional.
type ErrorResponse struct {
Error string `json:"error"`
Files []FileOutcome `json:"files,omitempty"`
}
// Outcomes of a file in a refusal.
const (
// OutcomeResolved: the resolver resolved the file, but not every file of
// the request.
OutcomeResolved = "resolved"
// OutcomeRejected: the resolver's result for the file failed a check.
OutcomeRejected = "rejected"
// OutcomeFailed: the resolver failed on the file (a model error, a spent
// budget, no strategy applying).
OutcomeFailed = "failed"
)
// FileOutcome is what the resolver did with one file of a refused request.
type FileOutcome struct {
Path string `json:"path"`
Outcome string `json:"outcome"`
Reason string `json:"reason,omitempty"`
}
// Repository identifies the repository the conflict belongs to.
type Repository struct {
Storage string `json:"storage"`
RelativePath string `json:"relative_path"`
}
// Messages carries the commit messages of both sides.
type Messages struct {
Tip string `json:"tip"`
Commit string `json:"commit"`
}
// File is one conflicting path. Path must be valid UTF-8: JSON strings cannot
// carry arbitrary bytes, so a path that is not would reach the resolver under
// another name.
type File struct {
Path string `json:"path"`
Kind string `json:"kind"`
Base *Side `json:"base"`
Ours *Side `json:"ours"`
Theirs *Side `json:"theirs"`
}
// Side is one version of a file. Content is base64 on the wire; a present
// side always carries a content string, possibly empty.
type Side struct {
OID string `json:"oid"`
Mode string `json:"mode"`
Content []byte `json:"-"`
}
// sideJSON is the wire form of Side.
type sideJSON struct {
OID string `json:"oid"`
Mode string `json:"mode"`
Content string `json:"content"`
}
// MarshalJSON encodes Content as base64, emitting "" rather than null for an
// empty present side.
func (s Side) MarshalJSON() ([]byte, error) {
return json.Marshal(sideJSON{
OID: s.OID,
Mode: s.Mode,
Content: base64.StdEncoding.EncodeToString(s.Content),
})
}
// UnmarshalJSON decodes the base64 wire form of Side.
func (s *Side) UnmarshalJSON(data []byte) error {
var raw sideJSON
if err := json.Unmarshal(data, &raw); err != nil {
return err
}
content, err := base64.StdEncoding.DecodeString(raw.Content)
if err != nil {
return err
}
*s = Side{OID: raw.OID, Mode: raw.Mode, Content: content}
return nil
}
// Limits are the bounds the resolver must respect.
type Limits struct {
MaxFileBytes int64 `json:"max_file_bytes"`
}
// Response is the resolver's answer.
type Response struct {
Version int `json:"version"`
Resolver string `json:"resolver"`
Files []ResponseFile `json:"files"`
Explanation string `json:"explanation"`
// RulesOnly echoes a request's RulesOnly: the resolver ran only its rules. A server that asked for
// it and does not get it back is talking to an older resolver, and does not ask again.
RulesOnly bool `json:"rules_only,omitempty"`
}
// The origins of a resolved file: what made the resolution.
const (
// OriginRule: an operator's rule (trivial, union, rerere, command) made it. Only a file marked
// as a rule lands without the operator's verification of the tree.
OriginRule = "rule"
// OriginModel: a model made it. It lands only if verify.command passed on the tree that lands
// (PLAN10 14, 15.9), and is otherwise proposed to the agent.
OriginModel = "model"
)
// ResponseFile is the resolution of one conflicting path. Content is base64
// on the wire and is only meaningful for ActionWrite.
//
// Origin says what made the resolution: OriginRule or OriginModel. It is fail-safe: a file is a
// rule's only when it says so, and a file without an origin, or with one that is none of the two,
// is a model's, which lands only through the operator's verification. Proposal is the older mark of
// a model's resolution, still read: it means OriginModel, whatever Origin says. The name of the
// resolver decides nothing.
type ResponseFile struct {
Path string `json:"path"`
Action string `json:"action"`
Mode string `json:"mode,omitempty"`
Content []byte `json:"content,omitempty"`
Origin string `json:"origin,omitempty"`
Proposal bool `json:"proposal,omitempty"`
// Hold is the reason the resolver holds a model's resolution back (the second model of the llm
// strategy's agree_with did not agree): the file is a proposal for the agent and never lands by
// itself, whatever verify.command says (decideLand). A held file is a model's, whatever its
// origin says.
Hold string `json:"hold,omitempty"`
// Report is the composition report of a model's resolution (PLAN10 15.3): in exact words what it
// keeps, drops and repeats of the two sides' changes. A report, never a gate: nothing in it
// decides whether the resolution lands. It goes to the agent with the proposal.
Report []string `json:"report,omitempty"`
}
// FromModel reports whether the file is a model's resolution: anything that is not marked as a
// rule's, anything marked as a proposal, and anything held back.
func (f ResponseFile) FromModel() bool {
return f.Proposal || f.Hold != "" || f.Origin != OriginRule
}