From 88afd1ebc979b7cd64bb3bc6787a2bc8a9a5b5e8 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Mon, 16 Nov 2026 09:55:14 +1100 Subject: [PATCH] feat(guard,runs): a guard is shown the agent's diagnosis and the evidence it read before proposing an action (#2006) --- internal/contracts/guard/v1/guard.pb.go | 151 ++++++++++++++++++------ modules/connectors/guards.go | 24 +++- modules/judgement/extensions.go | 14 +++ modules/judgement/judgement.go | 6 +- modules/runs/investigate.go | 9 +- modules/runs/rationale.go | 58 +++++++++ proto/guard/v1/guard.proto | 12 ++ 7 files changed, 231 insertions(+), 43 deletions(-) create mode 100644 modules/runs/rationale.go diff --git a/internal/contracts/guard/v1/guard.pb.go b/internal/contracts/guard/v1/guard.pb.go index 7458f8707..bb6221134 100644 --- a/internal/contracts/guard/v1/guard.pb.go +++ b/internal/contracts/guard/v1/guard.pb.go @@ -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, }, diff --git a/modules/connectors/guards.go b/modules/connectors/guards.go index bfd4fa0d2..2e122b98f 100644 --- a/modules/connectors/guards.go +++ b/modules/connectors/guards.go @@ -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) diff --git a/modules/judgement/extensions.go b/modules/judgement/extensions.go index 87ec74702..de2392e79 100644 --- a/modules/judgement/extensions.go +++ b/modules/judgement/extensions.go @@ -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) } diff --git a/modules/judgement/judgement.go b/modules/judgement/judgement.go index d908d954c..de481805a 100644 --- a/modules/judgement/judgement.go +++ b/modules/judgement/judgement.go @@ -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) } diff --git a/modules/runs/investigate.go b/modules/runs/investigate.go index 42d46130a..261c2957b 100644 --- a/modules/runs/investigate.go +++ b/modules/runs/investigate.go @@ -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 } diff --git a/modules/runs/rationale.go b/modules/runs/rationale.go new file mode 100644 index 000000000..d9f661775 --- /dev/null +++ b/modules/runs/rationale.go @@ -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], "") + "..." +} diff --git a/proto/guard/v1/guard.proto b/proto/guard/v1/guard.proto index 84aeaf8c6..23450544e 100644 --- a/proto/guard/v1/guard.proto +++ b/proto/guard/v1/guard.proto @@ -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 {