feat(guard,runs): a guard is shown the agent's diagnosis and the evidence it read before proposing an action (#2006)

This commit is contained in:
sam committed 2026-11-16 09:55:14 +11:00
1 parent a4a4e97f07
commit 88afd1ebc9
7 files changed
+231 -43

No files matched your search

+116 -35
View File
@@ -576,7 +576,12 @@ type JudgeRequest struct {
// deadline is how long the host waits for the verdict.
Deadline *durationpb.Duration `protobuf:"bytes,8,opt,name=deadline,proto3" json:"deadline,omitempty"`
// at is the host's clock when the action was put to the guard.
At *timestamppb.Timestamp `protobuf:"bytes,9,opt,name=at,proto3" json:"at,omitempty"`
At *timestamppb.Timestamp `protobuf:"bytes,9,opt,name=at,proto3" json:"at,omitempty"`
// diagnosis is what the agent concluded so far, in its own words. Empty
// when no agent proposed the action.
Diagnosis string `protobuf:"bytes,10,opt,name=diagnosis,proto3" json:"diagnosis,omitempty"`
// evidence is what the agent read during the run, oldest first.
Evidence []*Evidence `protobuf:"bytes,11,rep,name=evidence,proto3" json:"evidence,omitempty"`
unknownFields protoimpl.UnknownFields
sizeCache protoimpl.SizeCache
}
@@ -674,6 +679,74 @@ func (x *JudgeRequest) GetAt() *timestamppb.Timestamp {
return nil
}
func (x *JudgeRequest) GetDiagnosis() string {
if x != nil {
return x.Diagnosis
}
return ""
}
func (x *JudgeRequest) GetEvidence() []*Evidence {
if x != nil {
return x.Evidence
}
return nil
}
// Evidence is one result the agent read, as the tool returned it.
type Evidence struct {
state protoimpl.MessageState `protogen:"open.v1"`
// source names the tool that returned it.
Source string `protobuf:"bytes,1,opt,name=source,proto3" json:"source,omitempty"`
Text string `protobuf:"bytes,2,opt,name=text,proto3" json:"text,omitempty"`
unknownFields protoimpl.UnknownFields
sizeCache protoimpl.SizeCache
}
func (x *Evidence) Reset() {
*x = Evidence{}
mi := &file_guard_v1_guard_proto_msgTypes[8]
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
ms.StoreMessageInfo(mi)
}
func (x *Evidence) String() string {
return protoimpl.X.MessageStringOf(x)
}
func (*Evidence) ProtoMessage() {}
func (x *Evidence) ProtoReflect() protoreflect.Message {
mi := &file_guard_v1_guard_proto_msgTypes[8]
if x != nil {
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
if ms.LoadMessageInfo() == nil {
ms.StoreMessageInfo(mi)
}
return ms
}
return mi.MessageOf(x)
}
// Deprecated: Use Evidence.ProtoReflect.Descriptor instead.
func (*Evidence) Descriptor() ([]byte, []int) {
return file_guard_v1_guard_proto_rawDescGZIP(), []int{8}
}
func (x *Evidence) GetSource() string {
if x != nil {
return x.Source
}
return ""
}
func (x *Evidence) GetText() string {
if x != nil {
return x.Text
}
return ""
}
type Finding struct {
state protoimpl.MessageState `protogen:"open.v1"`
Text string `protobuf:"bytes,1,opt,name=text,proto3" json:"text,omitempty"`
@@ -686,7 +759,7 @@ type Finding struct {
func (x *Finding) Reset() {
*x = Finding{}
mi := &file_guard_v1_guard_proto_msgTypes[8]
mi := &file_guard_v1_guard_proto_msgTypes[9]
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
ms.StoreMessageInfo(mi)
}
@@ -698,7 +771,7 @@ func (x *Finding) String() string {
func (*Finding) ProtoMessage() {}
func (x *Finding) ProtoReflect() protoreflect.Message {
mi := &file_guard_v1_guard_proto_msgTypes[8]
mi := &file_guard_v1_guard_proto_msgTypes[9]
if x != nil {
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
if ms.LoadMessageInfo() == nil {
@@ -711,7 +784,7 @@ func (x *Finding) ProtoReflect() protoreflect.Message {
// Deprecated: Use Finding.ProtoReflect.Descriptor instead.
func (*Finding) Descriptor() ([]byte, []int) {
return file_guard_v1_guard_proto_rawDescGZIP(), []int{8}
return file_guard_v1_guard_proto_rawDescGZIP(), []int{9}
}
func (x *Finding) GetText() string {
@@ -748,7 +821,7 @@ type JudgeResponse struct {
func (x *JudgeResponse) Reset() {
*x = JudgeResponse{}
mi := &file_guard_v1_guard_proto_msgTypes[9]
mi := &file_guard_v1_guard_proto_msgTypes[10]
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
ms.StoreMessageInfo(mi)
}
@@ -760,7 +833,7 @@ func (x *JudgeResponse) String() string {
func (*JudgeResponse) ProtoMessage() {}
func (x *JudgeResponse) ProtoReflect() protoreflect.Message {
mi := &file_guard_v1_guard_proto_msgTypes[9]
mi := &file_guard_v1_guard_proto_msgTypes[10]
if x != nil {
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
if ms.LoadMessageInfo() == nil {
@@ -773,7 +846,7 @@ func (x *JudgeResponse) ProtoReflect() protoreflect.Message {
// Deprecated: Use JudgeResponse.ProtoReflect.Descriptor instead.
func (*JudgeResponse) Descriptor() ([]byte, []int) {
return file_guard_v1_guard_proto_rawDescGZIP(), []int{9}
return file_guard_v1_guard_proto_rawDescGZIP(), []int{10}
}
func (x *JudgeResponse) GetCeiling() Ceiling {
@@ -832,7 +905,7 @@ const file_guard_v1_guard_proto_rawDesc = "" +
"\n" +
"RunContext\x12\x15\n" +
"\x06run_id\x18\x01 \x01(\tR\x05runId\x12!\n" +
"\fdecision_key\x18\x02 \x01(\tR\vdecisionKey\"\xcd\x02\n" +
"\fdecision_key\x18\x02 \x01(\tR\vdecisionKey\"\x9b\x03\n" +
"\fJudgeRequest\x12\x1c\n" +
"\tconnector\x18\x01 \x01(\tR\tconnector\x12\x12\n" +
"\x04name\x18\x02 \x01(\tR\x04name\x12\x14\n" +
@@ -842,7 +915,13 @@ const file_guard_v1_guard_proto_rawDesc = "" +
"\x06effect\x18\x06 \x01(\v2\x10.guard.v1.EffectR\x06effect\x12&\n" +
"\x03run\x18\a \x01(\v2\x14.guard.v1.RunContextR\x03run\x125\n" +
"\bdeadline\x18\b \x01(\v2\x19.google.protobuf.DurationR\bdeadline\x12*\n" +
"\x02at\x18\t \x01(\v2\x1a.google.protobuf.TimestampR\x02at\"i\n" +
"\x02at\x18\t \x01(\v2\x1a.google.protobuf.TimestampR\x02at\x12\x1c\n" +
"\tdiagnosis\x18\n" +
" \x01(\tR\tdiagnosis\x12.\n" +
"\bevidence\x18\v \x03(\v2\x12.guard.v1.EvidenceR\bevidence\"6\n" +
"\bEvidence\x12\x16\n" +
"\x06source\x18\x01 \x01(\tR\x06source\x12\x12\n" +
"\x04text\x18\x02 \x01(\tR\x04text\"i\n" +
"\aFinding\x12\x12\n" +
"\x04text\x18\x01 \x01(\tR\x04text\x12\x1a\n" +
"\bevidence\x18\x02 \x01(\tR\bevidence\x12.\n" +
@@ -889,7 +968,7 @@ func file_guard_v1_guard_proto_rawDescGZIP() []byte {
}
var file_guard_v1_guard_proto_enumTypes = make([]protoimpl.EnumInfo, 3)
var file_guard_v1_guard_proto_msgTypes = make([]protoimpl.MessageInfo, 12)
var file_guard_v1_guard_proto_msgTypes = make([]protoimpl.MessageInfo, 13)
var file_guard_v1_guard_proto_goTypes = []any{
(Reversibility)(0), // 0: guard.v1.Reversibility
(Ceiling)(0), // 1: guard.v1.Ceiling
@@ -902,36 +981,38 @@ var file_guard_v1_guard_proto_goTypes = []any{
(*Target)(nil), // 8: guard.v1.Target
(*RunContext)(nil), // 9: guard.v1.RunContext
(*JudgeRequest)(nil), // 10: guard.v1.JudgeRequest
(*Finding)(nil), // 11: guard.v1.Finding
(*JudgeResponse)(nil), // 12: guard.v1.JudgeResponse
nil, // 13: guard.v1.ConfigureRequest.SettingsEntry
nil, // 14: guard.v1.ConfigureRequest.SecretsEntry
(*durationpb.Duration)(nil), // 15: google.protobuf.Duration
(*timestamppb.Timestamp)(nil), // 16: google.protobuf.Timestamp
(*Evidence)(nil), // 11: guard.v1.Evidence
(*Finding)(nil), // 12: guard.v1.Finding
(*JudgeResponse)(nil), // 13: guard.v1.JudgeResponse
nil, // 14: guard.v1.ConfigureRequest.SettingsEntry
nil, // 15: guard.v1.ConfigureRequest.SecretsEntry
(*durationpb.Duration)(nil), // 16: google.protobuf.Duration
(*timestamppb.Timestamp)(nil), // 17: google.protobuf.Timestamp
}
var file_guard_v1_guard_proto_depIdxs = []int32{
13, // 0: guard.v1.ConfigureRequest.settings:type_name -> guard.v1.ConfigureRequest.SettingsEntry
14, // 1: guard.v1.ConfigureRequest.secrets:type_name -> guard.v1.ConfigureRequest.SecretsEntry
14, // 0: guard.v1.ConfigureRequest.settings:type_name -> guard.v1.ConfigureRequest.SettingsEntry
15, // 1: guard.v1.ConfigureRequest.secrets:type_name -> guard.v1.ConfigureRequest.SecretsEntry
0, // 2: guard.v1.Effect.reversibility:type_name -> guard.v1.Reversibility
8, // 3: guard.v1.JudgeRequest.target:type_name -> guard.v1.Target
7, // 4: guard.v1.JudgeRequest.effect:type_name -> guard.v1.Effect
9, // 5: guard.v1.JudgeRequest.run:type_name -> guard.v1.RunContext
15, // 6: guard.v1.JudgeRequest.deadline:type_name -> google.protobuf.Duration
16, // 7: guard.v1.JudgeRequest.at:type_name -> google.protobuf.Timestamp
2, // 8: guard.v1.Finding.strength:type_name -> guard.v1.Strength
1, // 9: guard.v1.JudgeResponse.ceiling:type_name -> guard.v1.Ceiling
11, // 10: guard.v1.JudgeResponse.findings:type_name -> guard.v1.Finding
3, // 11: guard.v1.GuardService.Configure:input_type -> guard.v1.ConfigureRequest
5, // 12: guard.v1.GuardService.Describe:input_type -> guard.v1.DescribeRequest
10, // 13: guard.v1.GuardService.Judge:input_type -> guard.v1.JudgeRequest
4, // 14: guard.v1.GuardService.Configure:output_type -> guard.v1.ConfigureResponse
6, // 15: guard.v1.GuardService.Describe:output_type -> guard.v1.DescribeResponse
12, // 16: guard.v1.GuardService.Judge:output_type -> guard.v1.JudgeResponse
14, // [14:17] is the sub-list for method output_type
11, // [11:14] is the sub-list for method input_type
11, // [11:11] is the sub-list for extension type_name
11, // [11:11] is the sub-list for extension extendee
0, // [0:11] is the sub-list for field type_name
16, // 6: guard.v1.JudgeRequest.deadline:type_name -> google.protobuf.Duration
17, // 7: guard.v1.JudgeRequest.at:type_name -> google.protobuf.Timestamp
11, // 8: guard.v1.JudgeRequest.evidence:type_name -> guard.v1.Evidence
2, // 9: guard.v1.Finding.strength:type_name -> guard.v1.Strength
1, // 10: guard.v1.JudgeResponse.ceiling:type_name -> guard.v1.Ceiling
12, // 11: guard.v1.JudgeResponse.findings:type_name -> guard.v1.Finding
3, // 12: guard.v1.GuardService.Configure:input_type -> guard.v1.ConfigureRequest
5, // 13: guard.v1.GuardService.Describe:input_type -> guard.v1.DescribeRequest
10, // 14: guard.v1.GuardService.Judge:input_type -> guard.v1.JudgeRequest
4, // 15: guard.v1.GuardService.Configure:output_type -> guard.v1.ConfigureResponse
6, // 16: guard.v1.GuardService.Describe:output_type -> guard.v1.DescribeResponse
13, // 17: guard.v1.GuardService.Judge:output_type -> guard.v1.JudgeResponse
15, // [15:18] is the sub-list for method output_type
12, // [12:15] is the sub-list for method input_type
12, // [12:12] is the sub-list for extension type_name
12, // [12:12] is the sub-list for extension extendee
0, // [0:12] is the sub-list for field type_name
}
func init() { file_guard_v1_guard_proto_init() }
@@ -945,7 +1026,7 @@ func file_guard_v1_guard_proto_init() {
GoPackagePath: reflect.TypeOf(x{}).PkgPath(),
RawDescriptor: unsafe.Slice(unsafe.StringData(file_guard_v1_guard_proto_rawDesc), len(file_guard_v1_guard_proto_rawDesc)),
NumEnums: 3,
NumMessages: 12,
NumMessages: 13,
NumExtensions: 0,
NumServices: 1,
},
+19 -5
View File
@@ -31,6 +31,15 @@ type GuardRequest struct {
// Deadline is how long the host waits; the caller's context enforces it.
Deadline time.Duration
At time.Time
// Diagnosis and Evidence are what the proposing agent concluded and read.
Diagnosis string
Evidence []GuardEvidence
}
// GuardEvidence is one tool result the agent read.
type GuardEvidence struct {
Source string
Text string
}
// GuardFinding is one thing a guard noticed. Strength is "weak", "moderate"
@@ -78,13 +87,18 @@ func (g *Guard) Advisory() bool { return g.advisory }
// Judge asks the guard about one action. ctx bounds the wait.
func (g *Guard) Judge(ctx context.Context, r GuardRequest) (GuardAnswer, error) {
evidence := make([]*gpb.Evidence, 0, len(r.Evidence))
for _, e := range r.Evidence {
evidence = append(evidence, &gpb.Evidence{Source: e.Source, Text: e.Text})
}
resp, err := g.client.Judge(ctx, &gpb.JudgeRequest{
Connector: r.Connector, Name: r.Name, Input: r.Input, Digest: r.Digest,
Target: &gpb.Target{Kind: r.Target.Kind, Id: r.Target.ID, Environment: r.Target.Environment, Disposable: r.Target.Disposable},
Effect: &gpb.Effect{ReadOnly: r.Effect.ReadOnly, Reversibility: gpb.Reversibility(r.Effect.Reversibility), Summary: r.Effect.Summary},
Run: &gpb.RunContext{RunId: r.RunID, DecisionKey: r.DecisionKey},
Deadline: durationpb.New(r.Deadline),
At: timestamppb.New(r.At),
Target: &gpb.Target{Kind: r.Target.Kind, Id: r.Target.ID, Environment: r.Target.Environment, Disposable: r.Target.Disposable},
Effect: &gpb.Effect{ReadOnly: r.Effect.ReadOnly, Reversibility: gpb.Reversibility(r.Effect.Reversibility), Summary: r.Effect.Summary},
Run: &gpb.RunContext{RunId: r.RunID, DecisionKey: r.DecisionKey},
Deadline: durationpb.New(r.Deadline),
At: timestamppb.New(r.At),
Diagnosis: r.Diagnosis, Evidence: evidence,
})
if err != nil {
return GuardAnswer{}, fmt.Errorf("guard %q: %w", g.name, err)
+14
View File
@@ -25,6 +25,16 @@ type RunContext struct {
RunID uuid.UUID
Key string
Workflow string
// Diagnosis and Evidence are what the proposing agent concluded and read
// before proposing the action.
Diagnosis string
Evidence []Evidence
}
// Evidence is one tool result the agent read, as the tool returned it.
type Evidence struct {
Source string `json:"source"`
Text string `json:"text"`
}
type runKey struct{}
@@ -59,6 +69,10 @@ func (e extensionGuard) Judge(ctx context.Context, a Action) (Verdict, error) {
RunID: run.RunID.String(), DecisionKey: run.Key,
At: time.Now(),
}
req.Diagnosis = run.Diagnosis
for _, e := range run.Evidence {
req.Evidence = append(req.Evidence, connectors.GuardEvidence{Source: e.Source, Text: e.Text})
}
if d, ok := ctx.Deadline(); ok {
req.Deadline = time.Until(d)
}
+5 -1
View File
@@ -146,6 +146,10 @@ type Request struct {
Input jsontext.Value
// Workflow is the workflow the run executes, the principal hard rules see.
Workflow string
// Diagnosis and Evidence are what the proposing agent concluded and read,
// for guards that weigh the reasoning behind an action. Both may be empty.
Diagnosis string
Evidence []Evidence
}
// Tools finds the tool that resolves and runs an action.
@@ -211,7 +215,7 @@ func (m *Module) Assess(ctx context.Context, req Request) (Decision, error) {
Connector: req.Connector, Name: req.Action, Input: req.Input,
Digest: connectors.Digest(req.Action, req.Input), Target: res.Target, Effect: res.Effect,
}
d := m.decide(withRun(ctx, RunContext{RunID: req.RunID, Key: req.Key, Workflow: req.Workflow}), a)
d := m.decide(withRun(ctx, RunContext{RunID: req.RunID, Key: req.Key, Workflow: req.Workflow, Diagnosis: req.Diagnosis, Evidence: req.Evidence}), a)
d.ID, d.RunID, d.Key, d.At = uuid.New(), req.RunID, req.Key, m.now().UTC()
return m.record(ctx, d)
}
+7 -2
View File
@@ -317,9 +317,10 @@ func settleOne(rc *Context, judge Judge, ask Approver, settings Settings, d judg
}
out.By = answer.By
fresh, err := rc.Step("judge-again:"+d.Key, func(ctx context.Context, key string) (judgement.Decision, error) {
diagnosis, evidence := rc.Rationale()
return judge.Assess(ctx, judgement.Request{
RunID: rc.RunID(), Key: key, Connector: d.Action.Connector, Action: d.Action.Name, Input: d.Action.Input,
Workflow: rc.Workflow(),
Workflow: rc.Workflow(), Diagnosis: diagnosis, Evidence: evidence,
})
})
if err != nil {
@@ -632,7 +633,11 @@ func call(ctx context.Context, box Toolbox, judge Judge, rc *Context, d connecto
// is proposed to a person when the investigation ends, so it comes back to
// the agent as something waiting rather than a failure.
key := core.IdempotencyKey(ctx)
decision, err := judge.Assess(ctx, judgement.Request{RunID: rc.RunID(), Key: key, Connector: d.Connector, Action: d.Name, Input: input, Workflow: rc.Workflow()})
diagnosis, evidence := rc.Rationale()
decision, err := judge.Assess(ctx, judgement.Request{
RunID: rc.RunID(), Key: key, Connector: d.Connector, Action: d.Name, Input: input, Workflow: rc.Workflow(),
Diagnosis: diagnosis, Evidence: evidence,
})
if err != nil {
return "", err
}
+58
View File
@@ -0,0 +1,58 @@
package runs
import (
json "encoding/json/v2"
"slices"
"strings"
"github.com/samcharles93/ai-sdk/agentloop"
"github.com/samcharles93/archie-core/modules/judgement"
)
// What a guard that weighs reasoning is shown: the latest evidence, each
// result cut to a length a judge model can read.
const (
maxEvidenceItems = 12
maxEvidenceChars = 2000
)
// Rationale is what the run's agent concluded and read before now: its latest
// words, and the tool results it saw, oldest first. It reads the agent loop's
// journal, so a resumed run shows what an earlier attempt saw.
func (rc *Context) Rationale() (string, []judgement.Evidence) {
seqs := make([]int, 0, len(rc.saved))
for seq, s := range rc.saved {
if strings.HasPrefix(s.Name, "journal:agent:") {
seqs = append(seqs, seq)
}
}
slices.Sort(seqs)
var diagnosis string
var evidence []judgement.Evidence
for _, seq := range seqs {
var e agentloop.Entry
if json.Unmarshal(rc.saved[seq].Output, &e) != nil {
continue
}
switch {
case e.Kind == agentloop.EntryModel && e.Message != nil:
if text := strings.TrimSpace(e.Message.Text()); text != "" {
diagnosis = text
}
case e.Kind == agentloop.EntryTool && e.Error == "" && !e.Unknown && e.Output != "":
evidence = append(evidence, judgement.Evidence{Source: e.ToolName, Text: clip(e.Output)})
}
}
if len(evidence) > maxEvidenceItems {
evidence = evidence[len(evidence)-maxEvidenceItems:]
}
return diagnosis, evidence
}
func clip(s string) string {
if len(s) <= maxEvidenceChars {
return s
}
return strings.ToValidUTF8(s[:maxEvidenceChars], "") + "..."
}
+12
View File
@@ -95,6 +95,18 @@ message JudgeRequest {
google.protobuf.Duration deadline = 8;
// at is the host's clock when the action was put to the guard.
google.protobuf.Timestamp at = 9;
// diagnosis is what the agent concluded so far, in its own words. Empty
// when no agent proposed the action.
string diagnosis = 10;
// evidence is what the agent read during the run, oldest first.
repeated Evidence evidence = 11;
}
// Evidence is one result the agent read, as the tool returned it.
message Evidence {
// source names the tool that returned it.
string source = 1;
string text = 2;
}
message Finding {