Skip to content

Fully autonomous AI Agents system capable of performing complex penetration testing tasks

feat: add evidence receipt hash chain prototype (#279)

mason5052d5a86ff27b63
diff --git a/.env.example b/.env.example
index 4b95dc8f..d0d159e4 100644
--- a/.env.example
+++ b/.env.example
@@ -100,6 +100,9 @@ EXECUTION_MONITOR_ENABLED=
EXECUTION_MONITOR_SAME_TOOL_LIMIT=
EXECUTION_MONITOR_TOTAL_TOOL_LIMIT=
+## Evidence receipt hash chain
+EVIDENCE_RECEIPTS_ENABLED=false
+
## Agent execution tool calls limit
MAX_GENERAL_AGENT_TOOL_CALLS=
MAX_LIMITED_AGENT_TOOL_CALLS=
diff --git a/backend/docs/config.md b/backend/docs/config.md
index 08c8d1b6..f6be6625 100644
--- a/backend/docs/config.md
+++ b/backend/docs/config.md
@@ -127,17 +127,18 @@ The environment variables documented below remain the source of truth for config
These settings control basic application behavior and are foundational for the system's operation.
-| Option | Environment Variable | Default Value | Description |
-| ---------------- | --------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
-| DatabaseURL | `DATABASE_URL` | `postgres://pentagiuser:pentagipass@pgvector:5432/pentagidb?sslmode=disable` | Connection string for the PostgreSQL database with pgvector extension |
-| DBMaxOpenConns | `DATABASE_MAX_OPEN_CONNS` | `25` | Maximum open connections in the shared `sql.DB` pool (sqlc + GORM combined). See [database.md §Connection Pooling](database.md#connection-pooling). |
-| DBMaxIdleConns | `DATABASE_MAX_IDLE_CONNS` | `5` | Maximum idle connections kept open between requests |
-| DBVectorMaxConns | `DATABASE_VECTOR_MAX_CONNS` | `10` | Maximum connections in the shared `pgxpool` for all pgvector stores |
-| Debug | `DEBUG` | `false` | Enables debug mode with additional logging |
-| DataDir | `DATA_DIR` | `./data` | Directory for storing persistent data |
-| AskUser | `ASK_USER` | `false` | When enabled, requires explicit user confirmation for certain operations |
-| InstallationID | `INSTALLATION_ID` | *(none)* | Unique installation identifier for PentAGI Cloud API communication |
-| LicenseKey | `LICENSE_KEY` | *(none)* | License key for PentAGI Cloud API authentication and feature activation |
+| Option | Environment Variable | Default Value | Description |
+| ----------------------- | --------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| DatabaseURL | `DATABASE_URL` | `postgres://pentagiuser:pentagipass@pgvector:5432/pentagidb?sslmode=disable` | Connection string for the PostgreSQL database with pgvector extension |
+| DBMaxOpenConns | `DATABASE_MAX_OPEN_CONNS` | `25` | Maximum open connections in the shared `sql.DB` pool (sqlc + GORM combined). See [database.md §Connection Pooling](database.md#connection-pooling). |
+| DBMaxIdleConns | `DATABASE_MAX_IDLE_CONNS` | `5` | Maximum idle connections kept open between requests |
+| DBVectorMaxConns | `DATABASE_VECTOR_MAX_CONNS` | `10` | Maximum connections in the shared `pgxpool` for all pgvector stores |
+| Debug | `DEBUG` | `false` | Enables debug mode with additional logging |
+| DataDir | `DATA_DIR` | `./data` | Directory for storing persistent data |
+| AskUser | `ASK_USER` | `false` | When enabled, requires explicit user confirmation for certain operations |
+| EvidenceReceiptsEnabled | `EVIDENCE_RECEIPTS_ENABLED` | `false` | Enables export-only toolcall evidence receipts |
+| InstallationID | `INSTALLATION_ID` | *(none)* | Unique installation identifier for PentAGI Cloud API communication |
+| LicenseKey | `LICENSE_KEY` | *(none)* | License key for PentAGI Cloud API authentication and feature activation |
### Usage Details
@@ -1845,6 +1846,10 @@ The supervision settings work together as a comprehensive system:
```
Disabled supervision for debugging to observe natural agent behavior.
+## Evidence Receipt Settings
+
+When `EVIDENCE_RECEIPTS_ENABLED=true`, PentAGI writes hash-chain-only JSONL receipts for finished and failed tool calls to `<DATA_DIR>/flow-<flow_id>/evidence/receipts.jsonl`. Receipts include toolcall provenance metadata plus hashes of arguments and results, not raw argument or result content. Ed25519 signing and report bundle export are deferred to a later evidence-chain milestone.
+
## Observability Settings
These settings control the observability and monitoring capabilities, including telemetry and trace collection for system performance and debugging.
diff --git a/backend/pkg/config/config.go b/backend/pkg/config/config.go
index 9ad47c97..37d7ba4e 100644
--- a/backend/pkg/config/config.go
+++ b/backend/pkg/config/config.go
@@ -23,6 +23,9 @@ type Config struct {
DataDir string `env:"DATA_DIR" envDefault:"./data"`
AskUser bool `env:"ASK_USER" envDefault:"false"`
+ // === Evidence Receipt Prototype ===
+ EvidenceReceiptsEnabled bool `env:"EVIDENCE_RECEIPTS_ENABLED" envDefault:"false"`
+
// === PentAGI Cloud Service Integration ===
InstallationID string `env:"INSTALLATION_ID"`
LicenseKey string `env:"LICENSE_KEY"`
diff --git a/backend/pkg/config/config_test.go b/backend/pkg/config/config_test.go
index 85aa69f6..ac5dff67 100644
--- a/backend/pkg/config/config_test.go
+++ b/backend/pkg/config/config_test.go
@@ -269,7 +269,7 @@ func clearConfigEnv(t *testing.T) {
t.Helper()
envVars := []string{
- "DATABASE_URL", "DEBUG", "DATA_DIR", "ASK_USER", "INSTALLATION_ID", "LICENSE_KEY",
+ "DATABASE_URL", "DEBUG", "DATA_DIR", "ASK_USER", "EVIDENCE_RECEIPTS_ENABLED", "INSTALLATION_ID", "LICENSE_KEY",
"DOCKER_INSIDE", "DOCKER_NET_ADMIN", "DOCKER_SOCKET", "DOCKER_NETWORK",
"DOCKER_PUBLIC_IP", "DOCKER_WORK_DIR", "DOCKER_DEFAULT_IMAGE", "DOCKER_DEFAULT_IMAGE_FOR_PENTEST", "TERMINAL_TOOL_TIMEOUT",
"SERVER_PORT", "SERVER_HOST", "SERVER_USE_SSL", "SERVER_SSL_KEY", "SERVER_SSL_CRT",
@@ -331,6 +331,7 @@ func TestNewConfig_Defaults(t *testing.T) {
assert.Equal(t, "0.0.0.0", config.ServerHost)
assert.Equal(t, false, config.Debug)
assert.Equal(t, "./data", config.DataDir)
+ assert.Equal(t, false, config.EvidenceReceiptsEnabled)
assert.Equal(t, false, config.ServerUseSSL)
assert.Equal(t, "openai", config.EmbeddingProvider)
assert.Equal(t, 512, config.EmbeddingBatchSize)
@@ -511,6 +512,20 @@ func TestNewConfig_CorsOrigins(t *testing.T) {
assert.Equal(t, []string{"*"}, config.CorsOrigins)
}
+func TestNewConfig_EvidenceReceipts(t *testing.T) {
+ clearConfigEnv(t)
+ t.Chdir(t.TempDir())
+
+ config, err := NewConfig()
+ require.NoError(t, err)
+ assert.Equal(t, false, config.EvidenceReceiptsEnabled)
+
+ t.Setenv("EVIDENCE_RECEIPTS_ENABLED", "true")
+ config, err = NewConfig()
+ require.NoError(t, err)
+ assert.Equal(t, true, config.EvidenceReceiptsEnabled)
+}
+
func TestNewConfig_OllamaDefaults(t *testing.T) {
clearConfigEnv(t)
t.Chdir(t.TempDir())
diff --git a/backend/pkg/tools/evidence_receipts.go b/backend/pkg/tools/evidence_receipts.go
new file mode 100644
index 00000000..145ba4a9
--- /dev/null
+++ b/backend/pkg/tools/evidence_receipts.go
@@ -0,0 +1,316 @@
+package tools
+
+import (
+ "bufio"
+ "bytes"
+ "context"
+ "crypto/sha256"
+ "encoding/hex"
+ "encoding/json"
+ "fmt"
+ "io"
+ "os"
+ "path/filepath"
+ "strings"
+ "sync"
+ "time"
+
+ "github.com/google/uuid"
+)
+
+const (
+ evidenceReceiptSchema = "pentagi.evidence_receipt"
+ evidenceReceiptVersion = 1
+ evidenceReceiptFile = "receipts.jsonl"
+
+ evidenceReceiptStatusFinished = "finished"
+ evidenceReceiptStatusFailed = "failed"
+)
+
+type evidenceReceiptRecorder interface {
+ RecordFinished(context.Context, evidenceReceiptEvent) error
+ RecordFailed(context.Context, evidenceReceiptEvent) error
+}
+
+type evidenceReceiptEvent struct {
+ FlowID int64
+ TaskID *int64
+ SubtaskID *int64
+ ToolcallID int64
+ CallID string
+ ToolName string
+ Args json.RawMessage
+ Result string
+}
+
+type evidenceReceipt struct {
+ Schema string `json:"schema"`
+ Version int `json:"version"`
+ ReceiptID string `json:"receipt_id"`
+ ReceiptHash string `json:"receipt_hash"`
+ PreviousReceiptHash string `json:"previous_receipt_hash"`
+ FlowID int64 `json:"flow_id"`
+ TaskID *int64 `json:"task_id,omitempty"`
+ SubtaskID *int64 `json:"subtask_id,omitempty"`
+ ToolcallID int64 `json:"toolcall_id"`
+ CallID string `json:"call_id"`
+ ToolName string `json:"tool_name"`
+ Status string `json:"status"`
+ ArgsHash string `json:"args_hash"`
+ ResultHash string `json:"result_hash"`
+ CreatedAt time.Time `json:"created_at"`
+}
+
+type evidenceReceiptPayload struct {
+ Schema string `json:"schema"`
+ Version int `json:"version"`
+ ReceiptID string `json:"receipt_id"`
+ PreviousReceiptHash string `json:"previous_receipt_hash"`
+ FlowID int64 `json:"flow_id"`
+ TaskID *int64 `json:"task_id,omitempty"`
+ SubtaskID *int64 `json:"subtask_id,omitempty"`
+ ToolcallID int64 `json:"toolcall_id"`
+ CallID string `json:"call_id"`
+ ToolName string `json:"tool_name"`
+ Status string `json:"status"`
+ ArgsHash string `json:"args_hash"`
+ ResultHash string `json:"result_hash"`
+ CreatedAt time.Time `json:"created_at"`
+}
+
+type noopEvidenceReceiptRecorder struct{}
+
+func (noopEvidenceReceiptRecorder) RecordFinished(context.Context, evidenceReceiptEvent) error {
+ return nil
+}
+
+func (noopEvidenceReceiptRecorder) RecordFailed(context.Context, evidenceReceiptEvent) error {
+ return nil
+}
+
+type fileEvidenceReceiptRecorder struct {
+ dataDir string
+ flowID int64
+ now func() time.Time
+ newID func() string
+}
+
+var evidenceReceiptLocks sync.Map
+
+func newEvidenceReceiptRecorder(dataDir string, flowID int64, enabled bool) evidenceReceiptRecorder {
+ if !enabled {
+ return noopEvidenceReceiptRecorder{}
+ }
+
+ return &fileEvidenceReceiptRecorder{
+ dataDir: dataDir,
+ flowID: flowID,
+ now: time.Now,
+ newID: newEvidenceReceiptID,
+ }
+}
+
+func newEvidenceReceiptID() string {
+ return "receipt_" + uuid.NewString()
+}
+
+func (r *fileEvidenceReceiptRecorder) RecordFinished(ctx context.Context, event evidenceReceiptEvent) error {
+ return r.record(ctx, event, evidenceReceiptStatusFinished)
+}
+
+func (r *fileEvidenceReceiptRecorder) RecordFailed(ctx context.Context, event evidenceReceiptEvent) error {
+ return r.record(ctx, event, evidenceReceiptStatusFailed)
+}
+
+func (r *fileEvidenceReceiptRecorder) record(ctx context.Context, event evidenceReceiptEvent, status string) error {
+ if err := ctx.Err(); err != nil {
+ return err
+ }
+
+ event.FlowID = r.flowID
+ path, err := evidenceReceiptsPath(r.dataDir, event.FlowID)
+ if err != nil {
+ return err
+ }
+
+ lock := evidenceReceiptPathLock(path)
+ lock.Lock()
+ defer lock.Unlock()
+
+ previousHash, err := readLastEvidenceReceiptHash(path)
+ if err != nil {
+ return err
+ }
+
+ argsHash, err := hashCanonicalJSON(event.Args)
+ if err != nil {
+ return fmt.Errorf("failed to hash evidence receipt arguments: %w", err)
+ }
+
+ receipt := evidenceReceipt{
+ Schema: evidenceReceiptSchema,
+ Version: evidenceReceiptVersion,
+ ReceiptID: r.newID(),
+ PreviousReceiptHash: previousHash,
+ FlowID: event.FlowID,
+ TaskID: event.TaskID,
+ SubtaskID: event.SubtaskID,
+ ToolcallID: event.ToolcallID,
+ CallID: event.CallID,
+ ToolName: event.ToolName,
+ Status: status,
+ ArgsHash: argsHash,
+ ResultHash: hashBytes([]byte(event.Result)),
+ CreatedAt: r.now().UTC(),
+ }
+
+ receiptHash, err := computeEvidenceReceiptHash(receipt)
+ if err != nil {
+ return err
+ }
+ receipt.ReceiptHash = receiptHash
+
+ line, err := json.Marshal(receipt)
+ if err != nil {
+ return fmt.Errorf("failed to marshal evidence receipt: %w", err)
+ }
+
+ if err := os.MkdirAll(filepath.Dir(path), 0755); err != nil {
+ return fmt.Errorf("failed to prepare evidence receipt directory: %w", err)
+ }
+
+ file, err := os.OpenFile(path, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0644)
+ if err != nil {
+ return fmt.Errorf("failed to open evidence receipt file: %w", err)
+ }
+ defer file.Close()
+
+ if _, err := file.Write(append(line, '\n')); err != nil {
+ return fmt.Errorf("failed to write evidence receipt: %w", err)
+ }
+
+ return nil
+}
+
+func evidenceReceiptsPath(dataDir string, flowID int64) (string, error) {
+ baseDir, err := filepath.Abs(dataDir)
+ if err != nil {
+ return "", fmt.Errorf("failed to resolve evidence receipt data directory: %w", err)
+ }
+
+ path := filepath.Join(baseDir, fmt.Sprintf("flow-%d", flowID), "evidence", evidenceReceiptFile)
+ cleanPath := filepath.Clean(path)
+ rel, err := filepath.Rel(baseDir, cleanPath)
+ if err != nil {
+ return "", fmt.Errorf("failed to validate evidence receipt path: %w", err)
+ }
+ if rel == "." || strings.HasPrefix(rel, ".."+string(os.PathSeparator)) || rel == ".." || filepath.IsAbs(rel) {
+ return "", fmt.Errorf("evidence receipt path escapes data directory")
+ }
+
+ return cleanPath, nil
+}
+
+func evidenceReceiptPathLock(path string) *sync.Mutex {
+ lock, _ := evidenceReceiptLocks.LoadOrStore(path, &sync.Mutex{})
+ return lock.(*sync.Mutex)
+}
+
+func readLastEvidenceReceiptHash(path string) (string, error) {
+ file, err := os.Open(path)
+ if os.IsNotExist(err) {
+ return "", nil
+ }
+ if err != nil {
+ return "", fmt.Errorf("failed to read evidence receipt file: %w", err)
+ }
+ defer file.Close()
+
+ scanner := bufio.NewScanner(file)
+ scanner.Buffer(make([]byte, 0, 64*1024), 1024*1024)
+
+ previousHash := ""
+ lineNumber := 0
+ for scanner.Scan() {
+ line := bytes.TrimSpace(scanner.Bytes())
+ if len(line) == 0 {
+ continue
+ }
+ lineNumber++
+
+ var receipt evidenceReceipt
+ if err := json.Unmarshal(line, &receipt); err != nil {
+ return "", fmt.Errorf("failed to parse evidence receipt line %d: %w", lineNumber, err)
+ }
+ if receipt.Schema != evidenceReceiptSchema || receipt.Version != evidenceReceiptVersion {
+ return "", fmt.Errorf("unsupported evidence receipt schema or version on line %d", lineNumber)
+ }
+ if receipt.PreviousReceiptHash != previousHash {
+ return "", fmt.Errorf("evidence receipt chain mismatch on line %d", lineNumber)
+ }
+
+ hash, err := computeEvidenceReceiptHash(receipt)
+ if err != nil {
+ return "", fmt.Errorf("failed to hash evidence receipt line %d: %w", lineNumber, err)
+ }
+ if receipt.ReceiptHash != hash {
+ return "", fmt.Errorf("evidence receipt hash mismatch on line %d", lineNumber)
+ }
+
+ previousHash = receipt.ReceiptHash
+ }
+ if err := scanner.Err(); err != nil {
+ return "", fmt.Errorf("failed to scan evidence receipt file: %w", err)
+ }
+
+ return previousHash, nil
+}
+
+func computeEvidenceReceiptHash(receipt evidenceReceipt) (string, error) {
+ payload, err := json.Marshal(evidenceReceiptPayload{
+ Schema: receipt.Schema,
+ Version: receipt.Version,
+ ReceiptID: receipt.ReceiptID,
+ PreviousReceiptHash: receipt.PreviousReceiptHash,
+ FlowID: receipt.FlowID,
+ TaskID: receipt.TaskID,
+ SubtaskID: receipt.SubtaskID,
+ ToolcallID: receipt.ToolcallID,
+ CallID: receipt.CallID,
+ ToolName: receipt.ToolName,
+ Status: receipt.Status,
+ ArgsHash: receipt.ArgsHash,
+ ResultHash: receipt.ResultHash,
+ CreatedAt: receipt.CreatedAt,
+ })
+ if err != nil {
+ return "", fmt.Errorf("failed to marshal evidence receipt payload: %w", err)
+ }
+
+ return hashBytes(payload), nil
+}
+
+func hashCanonicalJSON(raw json.RawMessage) (string, error) {
+ decoder := json.NewDecoder(bytes.NewReader(raw))
+ decoder.UseNumber()
+
+ var value any
+ if err := decoder.Decode(&value); err != nil {
+ return "", err
+ }
+ if err := decoder.Decode(&struct{}{}); err != io.EOF {
+ return "", fmt.Errorf("unexpected extra JSON data")
+ }
+
+ canonical, err := json.Marshal(value)
+ if err != nil {
+ return "", err
+ }
+
+ return hashBytes(canonical), nil
+}
+
+func hashBytes(data []byte) string {
+ sum := sha256.Sum256(data)
+ return "sha256:" + hex.EncodeToString(sum[:])
+}
diff --git a/backend/pkg/tools/evidence_receipts_test.go b/backend/pkg/tools/evidence_receipts_test.go
new file mode 100644
index 00000000..ee47eba0
--- /dev/null
+++ b/backend/pkg/tools/evidence_receipts_test.go
@@ -0,0 +1,249 @@
+package tools
+
+import (
+ "encoding/json"
+ "fmt"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+ "time"
+)
+
+func TestEvidenceReceiptHashDeterministic(t *testing.T) {
+ t.Parallel()
+
+ argsHashA, err := hashCanonicalJSON(json.RawMessage(`{"b":2,"a":{"d":4,"c":3}}`))
+ if err != nil {
+ t.Fatalf("hashCanonicalJSON() unexpected error: %v", err)
+ }
+ argsHashB, err := hashCanonicalJSON(json.RawMessage(`{"a":{"c":3,"d":4},"b":2}`))
+ if err != nil {
+ t.Fatalf("hashCanonicalJSON() unexpected error: %v", err)
+ }
+ if argsHashA != argsHashB {
+ t.Fatalf("canonical argument hashes differ: %s != %s", argsHashA, argsHashB)
+ }
+
+ receipt := testEvidenceReceipt(argsHashA, hashBytes([]byte("result")))
+ hashA, err := computeEvidenceReceiptHash(receipt)
+ if err != nil {
+ t.Fatalf("computeEvidenceReceiptHash() unexpected error: %v", err)
+ }
+ hashB, err := computeEvidenceReceiptHash(receipt)
+ if err != nil {
+ t.Fatalf("computeEvidenceReceiptHash() unexpected error: %v", err)
+ }
+ if hashA != hashB {
+ t.Fatalf("receipt hash should be deterministic: %s != %s", hashA, hashB)
+ }
+}
+
+func TestEvidenceReceiptHashChangesWithContentHashes(t *testing.T) {
+ t.Parallel()
+
+ receipt := testEvidenceReceipt(hashBytes([]byte("args")), hashBytes([]byte("result")))
+ baseHash, err := computeEvidenceReceiptHash(receipt)
+ if err != nil {
+ t.Fatalf("computeEvidenceReceiptHash() unexpected error: %v", err)
+ }
+
+ receipt.ArgsHash = hashBytes([]byte("different args"))
+ argsHash, err := computeEvidenceReceiptHash(receipt)
+ if err != nil {
+ t.Fatalf("computeEvidenceReceiptHash() unexpected error: %v", err)
+ }
+ if argsHash == baseHash {
+ t.Fatal("receipt hash should change when args_hash changes")
+ }
+
+ receipt = testEvidenceReceipt(hashBytes([]byte("args")), hashBytes([]byte("different result")))
+ resultHash, err := computeEvidenceReceiptHash(receipt)
+ if err != nil {
+ t.Fatalf("computeEvidenceReceiptHash() unexpected error: %v", err)
+ }
+ if resultHash == baseHash {
+ t.Fatal("receipt hash should change when result_hash changes")
+ }
+}
+
+func TestNoopEvidenceReceiptRecorder(t *testing.T) {
+ t.Parallel()
+
+ dir := t.TempDir()
+ recorder := newEvidenceReceiptRecorder(dir, 10, false)
+ err := recorder.RecordFinished(t.Context(), testEvidenceReceiptEvent())
+ if err != nil {
+ t.Fatalf("RecordFinished() unexpected error: %v", err)
+ }
+
+ path, err := evidenceReceiptsPath(dir, 10)
+ if err != nil {
+ t.Fatalf("evidenceReceiptsPath() unexpected error: %v", err)
+ }
+ if _, err := os.Stat(path); !os.IsNotExist(err) {
+ t.Fatalf("disabled recorder should not create %s, stat err: %v", path, err)
+ }
+}
+
+func TestFileEvidenceReceiptRecorderWritesJSONLAndLinksReceipts(t *testing.T) {
+ t.Parallel()
+
+ dir := t.TempDir()
+ recorder := newTestEvidenceReceiptRecorder(dir, 42)
+
+ if err := recorder.RecordFinished(t.Context(), testEvidenceReceiptEvent()); err != nil {
+ t.Fatalf("RecordFinished() unexpected error: %v", err)
+ }
+ if err := recorder.RecordFinished(t.Context(), evidenceReceiptEvent{
+ FlowID: 42,
+ ToolcallID: 101,
+ CallID: "call-101",
+ ToolName: "terminal",
+ Args: json.RawMessage(`{"cmd":"whoami"}`),
+ Result: "root",
+ }); err != nil {
+ t.Fatalf("RecordFinished() second receipt unexpected error: %v", err)
+ }
+
+ path, err := evidenceReceiptsPath(dir, 42)
+ if err != nil {
+ t.Fatalf("evidenceReceiptsPath() unexpected error: %v", err)
+ }
+ data, err := os.ReadFile(path)
+ if err != nil {
+ t.Fatalf("failed to read evidence receipts: %v", err)
+ }
+ if strings.Contains(string(data), "sensitive output") {
+ t.Fatal("receipt file should not store raw result content")
+ }
+ receipts := readEvidenceReceiptLines(t, path)
+ if len(receipts) != 2 {
+ t.Fatalf("got %d receipts, want 2", len(receipts))
+ }
+
+ if receipts[0].Status != evidenceReceiptStatusFinished {
+ t.Fatalf("first receipt status = %q, want %q", receipts[0].Status, evidenceReceiptStatusFinished)
+ }
+ if receipts[0].PreviousReceiptHash != "" {
+ t.Fatalf("first receipt previous hash = %q, want empty", receipts[0].PreviousReceiptHash)
+ }
+ if receipts[1].PreviousReceiptHash != receipts[0].ReceiptHash {
+ t.Fatalf("second receipt previous hash = %q, want %q", receipts[1].PreviousReceiptHash, receipts[0].ReceiptHash)
+ }
+}
+
+func TestFileEvidenceReceiptRecorderRecordsFailedStatus(t *testing.T) {
+ t.Parallel()
+
+ dir := t.TempDir()
+ recorder := newTestEvidenceReceiptRecorder(dir, 77)
+
+ if err := recorder.RecordFailed(t.Context(), testEvidenceReceiptEvent()); err != nil {
+ t.Fatalf("RecordFailed() unexpected error: %v", err)
+ }
+
+ path, err := evidenceReceiptsPath(dir, 77)
+ if err != nil {
+ t.Fatalf("evidenceReceiptsPath() unexpected error: %v", err)
+ }
+ receipts := readEvidenceReceiptLines(t, path)
+ if len(receipts) != 1 {
+ t.Fatalf("got %d receipts, want 1", len(receipts))
+ }
+ if receipts[0].Status != evidenceReceiptStatusFailed {
+ t.Fatalf("receipt status = %q, want %q", receipts[0].Status, evidenceReceiptStatusFailed)
+ }
+}
+
+func TestFileEvidenceReceiptRecorderFailsClosedOnUnreadablePreviousReceipt(t *testing.T) {
+ t.Parallel()
+
+ dir := t.TempDir()
+ path, err := evidenceReceiptsPath(dir, 88)
+ if err != nil {
+ t.Fatalf("evidenceReceiptsPath() unexpected error: %v", err)
+ }
+ if err := os.MkdirAll(filepath.Dir(path), 0755); err != nil {
+ t.Fatalf("failed to create evidence dir: %v", err)
+ }
+ if err := os.WriteFile(path, []byte(`{"schema":"wrong"}`+"\n"), 0644); err != nil {
+ t.Fatalf("failed to seed corrupt receipt: %v", err)
+ }
+
+ recorder := newTestEvidenceReceiptRecorder(dir, 88)
+ err = recorder.RecordFinished(t.Context(), testEvidenceReceiptEvent())
+ if err == nil {
+ t.Fatal("RecordFinished() should fail when previous receipt cannot be verified")
+ }
+}
+
+func testEvidenceReceipt(argsHash, resultHash string) evidenceReceipt {
+ return evidenceReceipt{
+ Schema: evidenceReceiptSchema,
+ Version: evidenceReceiptVersion,
+ ReceiptID: "receipt_test",
+ PreviousReceiptHash: "sha256:previous",
+ FlowID: 42,
+ ToolcallID: 100,
+ CallID: "call-100",
+ ToolName: "terminal",
+ Status: evidenceReceiptStatusFinished,
+ ArgsHash: argsHash,
+ ResultHash: resultHash,
+ CreatedAt: time.Date(2026, 4, 22, 12, 0, 0, 0, time.UTC),
+ }
+}
+
+func testEvidenceReceiptEvent() evidenceReceiptEvent {
+ taskID := int64(20)
+ subtaskID := int64(30)
+
+ return evidenceReceiptEvent{
+ FlowID: 10,
+ TaskID: &taskID,
+ SubtaskID: &subtaskID,
+ ToolcallID: 100,
+ CallID: "call-100",
+ ToolName: "terminal",
+ Args: json.RawMessage(`{"cmd":"id"}`),
+ Result: "sensitive output",
+ }
+}
+
+func newTestEvidenceReceiptRecorder(dir string, flowID int64) *fileEvidenceReceiptRecorder {
+ var count int
+
+ return &fileEvidenceReceiptRecorder{
+ dataDir: dir,
+ flowID: flowID,
+ now: func() time.Time {
+ count++
+ return time.Date(2026, 4, 22, 12, 0, count, 0, time.UTC)
+ },
+ newID: func() string {
+ return fmt.Sprintf("receipt_%03d", count+1)
+ },
+ }
+}
+
+func readEvidenceReceiptLines(t *testing.T, path string) []evidenceReceipt {
+ t.Helper()
+
+ data, err := os.ReadFile(path)
+ if err != nil {
+ t.Fatalf("failed to read evidence receipts: %v", err)
+ }
+
+ lines := strings.Split(strings.TrimSpace(string(data)), "\n")
+ receipts := make([]evidenceReceipt, 0, len(lines))
+ for _, line := range lines {
+ var receipt evidenceReceipt
+ if err := json.Unmarshal([]byte(line), &receipt); err != nil {
+ t.Fatalf("failed to parse receipt line %q: %v", line, err)
+ }
+ receipts = append(receipts, receipt)
+ }
+
+ return receipts
+}
diff --git a/backend/pkg/tools/executor.go b/backend/pkg/tools/executor.go
index 8320940c..a0fa02d0 100644
--- a/backend/pkg/tools/executor.go
+++ b/backend/pkg/tools/executor.go
@@ -15,6 +15,7 @@ import (
"pentagi/pkg/observability/langfuse"
"pentagi/pkg/schema"
+ "github.com/sirupsen/logrus"
"github.com/vxcontrol/langchaingo/documentloaders"
"github.com/vxcontrol/langchaingo/llms"
"github.com/vxcontrol/langchaingo/textsplitter"
@@ -135,11 +136,12 @@ type customExecutor struct {
taskID *int64
subtaskID *int64
- db database.Querier
- mlp MsgLogProvider
- tclp ToolCallLogProvider
- store *pgvector.Store
- vslp VectorStoreLogProvider
+ db database.Querier
+ mlp MsgLogProvider
+ tclp ToolCallLogProvider
+ store *pgvector.Store
+ vslp VectorStoreLogProvider
+ evidence evidenceReceiptRecorder
definitions []llms.FunctionDefinition
handlers map[string]ExecutorHandler
@@ -301,7 +303,9 @@ func (ce *customExecutor) Execute(
result, err := handler(ctx, name, args)
if err != nil {
durationDelta := time.Since(startTime).Seconds()
- _ = ce.tclp.UpdateLogFailed(ctx, tcID, fmt.Sprintf("failed to execute handler: %s", err.Error()), durationDelta)
+ failureResult := fmt.Sprintf("failed to execute handler: %s", err.Error())
+ _ = ce.tclp.UpdateLogFailed(ctx, tcID, failureResult, durationDelta)
+ ce.recordEvidenceReceipt(ctx, tcID, id, name, args, evidenceReceiptStatusFailed, failureResult)
return "", resultFormat, fmt.Errorf("failed to execute handler: %w", err)
}
@@ -315,7 +319,9 @@ func (ce *customExecutor) Execute(
result, err = ce.summarizer(ctx, summarizePrompt)
if err != nil {
durationDelta := time.Since(startTime).Seconds()
- _ = ce.tclp.UpdateLogFailed(ctx, tcID, fmt.Sprintf("failed to summarize result: %s", err.Error()), durationDelta)
+ failureResult := fmt.Sprintf("failed to summarize result: %s", err.Error())
+ _ = ce.tclp.UpdateLogFailed(ctx, tcID, failureResult, durationDelta)
+ ce.recordEvidenceReceipt(ctx, tcID, id, name, args, evidenceReceiptStatusFailed, failureResult)
return "", resultFormat, fmt.Errorf("failed to summarize result: %w", err)
}
resultFormat = database.MsglogResultFormatMarkdown
@@ -334,6 +340,7 @@ func (ce *customExecutor) Execute(
if err != nil {
return "", resultFormat, fmt.Errorf("failed to update toolcall result: %w", err)
}
+ ce.recordEvidenceReceipt(ctx, tcID, id, name, args, evidenceReceiptStatusFinished, result)
return result, resultFormat, nil
}
@@ -367,6 +374,50 @@ func (ce *customExecutor) Execute(
return result, nil
}
+// A recording failure is logged and swallowed: evidence receipts are an
+// optional audit feature and must never fail an otherwise-successful toolcall.
+func (ce *customExecutor) recordEvidenceReceipt(
+ ctx context.Context,
+ tcID int64,
+ callID, toolName string,
+ args json.RawMessage,
+ status, result string,
+) {
+ if ce.evidence == nil {
+ return
+ }
+
+ event := evidenceReceiptEvent{
+ FlowID: ce.flowID,
+ TaskID: ce.taskID,
+ SubtaskID: ce.subtaskID,
+ ToolcallID: tcID,
+ CallID: callID,
+ ToolName: toolName,
+ Args: args,
+ Result: result,
+ }
+
+ var err error
+ switch status {
+ case evidenceReceiptStatusFinished:
+ err = ce.evidence.RecordFinished(ctx, event)
+ case evidenceReceiptStatusFailed:
+ err = ce.evidence.RecordFailed(ctx, event)
+ default:
+ err = fmt.Errorf("unknown evidence receipt status %q", status)
+ }
+ if err != nil {
+ logrus.WithContext(ctx).
+ WithError(err).
+ WithFields(enrichLogrusFields(ce.flowID, ce.taskID, ce.subtaskID, logrus.Fields{
+ "tool_name": toolName,
+ "toolcall_id": tcID,
+ })).
+ Error("failed to record evidence receipt")
+ }
+}
+
func (ce *customExecutor) IsBarrierFunction(name string) bool {
_, ok := ce.barriers[name]
return ok
diff --git a/backend/pkg/tools/tools.go b/backend/pkg/tools/tools.go
index 2c72884b..17a77834 100644
--- a/backend/pkg/tools/tools.go
+++ b/backend/pkg/tools/tools.go
@@ -173,6 +173,7 @@ type flowToolsExecutor struct {
db database.Querier
cfg *config.Config
embedder embeddings.Embedder
+ evidence evidenceReceiptRecorder
store *pgvector.Store
graphitiClient *graphiti.Client
image string
@@ -373,6 +374,7 @@ func NewFlowToolsExecutor(
functions: functions,
replacer: replacer,
cfg: cfg,
+ evidence: newEvidenceReceiptRecorder(cfg.DataDir, flowID, cfg.EvidenceReceiptsEnabled),
flowID: flowID,
userID: userID,
definitions: make(map[string]llms.FunctionDefinition),
@@ -386,6 +388,7 @@ func (fte *flowToolsExecutor) SetUserID(userID int64) {
func (fte *flowToolsExecutor) SetFlowID(flowID int64) {
fte.flowID = flowID
+ fte.evidence = newEvidenceReceiptRecorder(fte.cfg.DataDir, flowID, fte.cfg.EvidenceReceiptsEnabled)
}
func (fte *flowToolsExecutor) SetImage(image string) {
@@ -770,6 +773,7 @@ func (fte *flowToolsExecutor) GetCustomExecutor(cfg CustomExecutorConfig) (Conte
vslp: fte.vslp,
db: fte.db,
store: fte.store,
+ evidence: fte.evidence,
definitions: cfg.Definitions,
handlers: cfg.Handlers,
barriers: barriers,
@@ -1018,6 +1022,7 @@ func (fte *flowToolsExecutor) GetAssistantExecutor(cfg AssistantExecutorConfig)
vslp: fte.vslp,
db: fte.db,
store: fte.store,
+ evidence: fte.evidence,
definitions: definitions,
handlers: handlers,
barriers: map[string]struct{}{},
@@ -1066,6 +1071,7 @@ func (fte *flowToolsExecutor) GetPrimaryExecutor(cfg PrimaryExecutorConfig) (Con
vslp: fte.vslp,
db: fte.db,
store: fte.store,
+ evidence: fte.evidence,
definitions: []llms.FunctionDefinition{
registryDefinitions[FinalyToolName],
registryDefinitions[AdviceToolName],
@@ -1142,6 +1148,7 @@ func (fte *flowToolsExecutor) GetInstallerExecutor(cfg InstallerExecutorConfig)
vslp: fte.vslp,
db: fte.db,
store: fte.store,
+ evidence: fte.evidence,
definitions: []llms.FunctionDefinition{
registryDefinitions[MaintenanceResultToolName],
registryDefinitions[AdviceToolName],
@@ -1248,6 +1255,7 @@ func (fte *flowToolsExecutor) GetCoderExecutor(cfg CoderExecutorConfig) (Context
vslp: fte.vslp,
db: fte.db,
store: fte.store,
+ evidence: fte.evidence,
definitions: []llms.FunctionDefinition{
registryDefinitions[CodeResultToolName],
registryDefinitions[AdviceToolName],
@@ -1371,6 +1379,7 @@ func (fte *flowToolsExecutor) GetPentesterExecutor(cfg PentesterExecutorConfig)
vslp: fte.vslp,
db: fte.db,
store: fte.store,
+ evidence: fte.evidence,
definitions: []llms.FunctionDefinition{
registryDefinitions[HackResultToolName],
registryDefinitions[AdviceToolName],
@@ -1476,6 +1485,7 @@ func (fte *flowToolsExecutor) GetSearcherExecutor(cfg SearcherExecutorConfig) (C
vslp: fte.vslp,
db: fte.db,
store: fte.store,
+ evidence: fte.evidence,
definitions: []llms.FunctionDefinition{
registryDefinitions[SearchResultToolName],
registryDefinitions[MemoristToolName],
@@ -1640,14 +1650,15 @@ func (fte *flowToolsExecutor) GetGeneratorExecutor(cfg GeneratorExecutorConfig)
)
ce := &customExecutor{
- userID: fte.userID,
- flowID: fte.flowID,
- taskID: &cfg.TaskID,
- mlp: fte.mlp,
- tclp: fte.tclp,
- vslp: fte.vslp,
- db: fte.db,
- store: fte.store,
+ userID: fte.userID,
+ flowID: fte.flowID,
+ taskID: &cfg.TaskID,
+ mlp: fte.mlp,
+ tclp: fte.tclp,
+ vslp: fte.vslp,
+ db: fte.db,
+ store: fte.store,
+ evidence: fte.evidence,
definitions: []llms.FunctionDefinition{
registryDefinitions[MemoristToolName],
registryDefinitions[SearchToolName],
@@ -1708,14 +1719,15 @@ func (fte *flowToolsExecutor) GetRefinerExecutor(cfg RefinerExecutorConfig) (Con
)
ce := &customExecutor{
- userID: fte.userID,
- flowID: fte.flowID,
- taskID: &cfg.TaskID,
- mlp: fte.mlp,
- tclp: fte.tclp,
- vslp: fte.vslp,
- db: fte.db,
- store: fte.store,
+ userID: fte.userID,
+ flowID: fte.flowID,
+ taskID: &cfg.TaskID,
+ mlp: fte.mlp,
+ tclp: fte.tclp,
+ vslp: fte.vslp,
+ db: fte.db,
+ store: fte.store,
+ evidence: fte.evidence,
definitions: []llms.FunctionDefinition{
registryDefinitions[MemoristToolName],
registryDefinitions[SearchToolName],
@@ -1781,6 +1793,7 @@ func (fte *flowToolsExecutor) GetMemoristExecutor(cfg MemoristExecutorConfig) (C
vslp: fte.vslp,
db: fte.db,
store: fte.store,
+ evidence: fte.evidence,
definitions: []llms.FunctionDefinition{
registryDefinitions[MemoristResultToolName],
registryDefinitions[TerminalToolName],
@@ -1852,6 +1865,7 @@ func (fte *flowToolsExecutor) GetEnricherExecutor(cfg EnricherExecutorConfig) (C
vslp: fte.vslp,
db: fte.db,
store: fte.store,
+ evidence: fte.evidence,
definitions: []llms.FunctionDefinition{
registryDefinitions[EnricherResultToolName],
registryDefinitions[TerminalToolName],
@@ -1921,6 +1935,7 @@ func (fte *flowToolsExecutor) GetReporterExecutor(cfg ReporterExecutorConfig) (C
vslp: fte.vslp,
db: fte.db,
store: fte.store,
+ evidence: fte.evidence,
definitions: []llms.FunctionDefinition{registryDefinitions[ReportResultToolName]},
handlers: map[string]ExecutorHandler{ReportResultToolName: cfg.ReportResult},
barriers: map[string]struct{}{ReportResultToolName: {}},
diff --git a/docker-compose.yml b/docker-compose.yml
index 20cc37d4..25599af5 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -106,6 +106,7 @@ services:
- EXECUTION_MONITOR_ENABLED=${EXECUTION_MONITOR_ENABLED:-}
- EXECUTION_MONITOR_SAME_TOOL_LIMIT=${EXECUTION_MONITOR_SAME_TOOL_LIMIT:-}
- EXECUTION_MONITOR_TOTAL_TOOL_LIMIT=${EXECUTION_MONITOR_TOTAL_TOOL_LIMIT:-}
+ - EVIDENCE_RECEIPTS_ENABLED=${EVIDENCE_RECEIPTS_ENABLED:-}
- MAX_GENERAL_AGENT_TOOL_CALLS=${MAX_GENERAL_AGENT_TOOL_CALLS:-}
- MAX_LIMITED_AGENT_TOOL_CALLS=${MAX_LIMITED_AGENT_TOOL_CALLS:-}
- AGENT_PLANNING_STEP_ENABLED=${AGENT_PLANNING_STEP_ENABLED:-}