diff --git a/agent/fact_assets.go b/agent/fact_assets.go new file mode 100644 index 0000000..3d0ead2 --- /dev/null +++ b/agent/fact_assets.go @@ -0,0 +1,41 @@ +package agent + +import ( + "encoding/json" + "fmt" + "slices" +) + +// factAssetAnchors accepts the historical asset_ids spelling and its explicit +// tested_asset_ids alias. Never union conflicting lists: that could attribute +// a conclusion to assets the caller did not actually check. +func (it factItem) factAssetAnchors() ([]int64, error) { + assets, err := parseFactAssetIDs("asset_ids", it.AssetIDs) + if err != nil { + return nil, err + } + tested, err := parseFactAssetIDs("tested_asset_ids", it.TestedAssetIDs) + if err != nil { + return nil, err + } + if it.AssetIDs != nil && it.TestedAssetIDs != nil && !slices.Equal(assets, tested) { + return nil, fmt.Errorf("asset_ids and tested_asset_ids must contain the same asset IDs when both are provided; use one field or correct the conflicting lists") + } + if it.TestedAssetIDs != nil { + return tested, nil + } + return assets, nil +} + +func parseFactAssetIDs(field string, raw []json.RawMessage) ([]int64, error) { + ids := make([]int64, 0, len(raw)) + for i, value := range raw { + id := pid(value) + if id <= 0 { + return nil, fmt.Errorf("%s[%d] must be a positive integer asset ID", field, i) + } + ids = append(ids, id) + } + slices.Sort(ids) + return slices.Compact(ids), nil +} diff --git a/agent/fact_assets_test.go b/agent/fact_assets_test.go new file mode 100644 index 0000000..d2b1a78 --- /dev/null +++ b/agent/fact_assets_test.go @@ -0,0 +1,182 @@ +package agent + +import ( + "encoding/json" + "fmt" + "slices" + "strconv" + "strings" + "testing" + + "github.com/Autumn-27/artex/db" +) + +func TestRecordFactAssetAliases(t *testing.T) { + d := testDB(t) + defer d.Close() + task, err := d.CreateTask("fact asset alias", "test", nil, 0, 0) + if err != nil { + t.Fatal(err) + } + defer d.DeleteTask(task.ID) + assets := d.Assets() + first, err := assets.UpsertRootDomain(db.UpsertRootDomainReq{Domain: "fact-alias-one.example", TaskID: task.ID}) + if err != nil { + t.Fatal(err) + } + second, err := assets.UpsertRootDomain(db.UpsertRootDomainReq{Domain: "fact-alias-two.example", TaskID: task.ID}) + if err != nil { + t.Fatal(err) + } + defer assets.DeleteByIDs([]int64{first, second}) + store := d.Exploration(task.ExplorationID) + tools := NewToolSet(store, "worker") + check := func(t *testing.T, id int64, want []int64) { + t.Helper() + rows, err := d.Query("SELECT asset_id FROM exploration_anchors WHERE node_id=$1 ORDER BY asset_id", id) + if err != nil { + t.Fatal(err) + } + defer rows.Close() + var got []int64 + for rows.Next() { + var asset int64 + if err := rows.Scan(&asset); err != nil { + t.Fatal(err) + } + got = append(got, asset) + } + if err := rows.Err(); err != nil { + t.Fatal(err) + } + slices.Sort(want) + if !slices.Equal(got, want) { + t.Fatalf("anchors = %v, want %v", got, want) + } + } + for _, tc := range []struct{ name, fields string }{ + {"canonical", fmt.Sprintf(`"asset_ids":[%d,%d,%d]`, first, second, first)}, + {"alias", fmt.Sprintf(`"tested_asset_ids":[%d,%d]`, first, second)}, + {"equal sets", fmt.Sprintf(`"asset_ids":[%d,%d],"tested_asset_ids":[%d,%d,%d]`, first, second, second, first, first)}, + {"numeric strings", fmt.Sprintf(`"tested_asset_ids":["%d","%d"]`, first, second)}, + } { + t.Run(tc.name, func(t *testing.T) { + out := callGuardTool(t, tools.recordFact(), fmt.Sprintf(`{"summary":%q,%s}`, tc.name, tc.fields)) + if out.IsError { + t.Fatal(out.Flatten()) + } + id, err := strconv.ParseInt(strings.TrimPrefix(out.Flatten(), "fact recorded: "), 10, 64) + if err != nil { + t.Fatal(out.Flatten(), err) + } + check(t, id, []int64{first, second}) + }) + } + before := tools.Writes().Facts + for _, fields := range []string{ + fmt.Sprintf(`"asset_ids":[%d],"tested_asset_ids":[%d]`, first, second), + fmt.Sprintf(`"asset_ids":[],"tested_asset_ids":[%d]`, first), + fmt.Sprintf(`"tested_asset_ids":[%d,0]`, first), + fmt.Sprintf(`"asset_ids":[%d,-1]`, first), + `"tested_asset_ids":[null]`, + `"tested_asset_ids":[1.5]`, + `"tested_asset_ids":["invalid"]`, + } { + out := callGuardTool(t, tools.recordFact(), `{"summary":"invalid assets",`+fields+`}`) + if !out.IsError || !strings.Contains(out.Flatten(), "asset_ids") { + t.Fatalf("accepted %s: %q", fields, out.Flatten()) + } + } + if tools.Writes().Facts != before { + t.Fatal("invalid asset lists wrote facts") + } + + out := callGuardTool(t, tools.recordFact(), fmt.Sprintf(`{"facts":[{"summary":"batch alias","tested_asset_ids":[%d]},{"summary":"batch conflict","asset_ids":[%d],"tested_asset_ids":[%d]},{"summary":"no inherited assets"}]}`, first, first, second)) + var batch struct { + IDs []int64 `json:"ids"` + Errors map[string]string `json:"errors"` + } + if err := json.Unmarshal([]byte(out.Flatten()), &batch); err != nil { + t.Fatal(out.Flatten(), err) + } + if len(batch.IDs) != 3 || batch.IDs[0] <= 0 || batch.IDs[1] != 0 || batch.IDs[2] <= 0 || !strings.Contains(batch.Errors["1"], "same asset IDs") { + t.Fatalf("batch: %s", out.Flatten()) + } + check(t, batch.IDs[0], []int64{first}) + check(t, batch.IDs[2], nil) + + before = tools.Writes().Facts + malformed := callGuardTool(t, tools.recordFact(), fmt.Sprintf(`{"facts":[{"summary":"must not be saved"},{"summary":"bad list","tested_asset_ids":%d}]}`, first)) + if !malformed.IsError || tools.Writes().Facts != before { + t.Fatal("malformed list caused a partial write", malformed.Flatten()) + } +} + +func TestRecordFactAssetAliasSchema(t *testing.T) { + schema := NewToolSet(nil, "").recordFact().InputSchema() + props := schema["properties"].(map[string]any) + for _, name := range []string{"asset_ids", "tested_asset_ids"} { + if props[name] == nil { + t.Fatalf("single schema missing %s", name) + } + } + item := props["facts"].(map[string]any)["items"].(map[string]any) + itemProps, _ := item["properties"].(map[string]any) + for _, name := range []string{"summary", "asset_ids", "tested_asset_ids"} { + if itemProps[name] == nil { + t.Fatalf("batch schema missing %s", name) + } + } +} + +func TestRecordFactRejectsMissingAssets(t *testing.T) { + d := testDB(t) + defer d.Close() + task, err := d.CreateTask("missing fact anchors", "test", nil, 0, 0) + if err != nil { + t.Fatal(err) + } + defer d.DeleteTask(task.ID) + assets := d.Assets() + var ids []int64 + for _, name := range []string{"missing-fact-one.example", "missing-fact-two.example", "existing-fact.example"} { + id, err := assets.UpsertRootDomain(db.UpsertRootDomainReq{Domain: name, TaskID: task.ID}) + if err != nil { + t.Fatal(err) + } + ids = append(ids, id) + } + defer assets.DeleteByIDs(ids) + if _, err := assets.DeleteByIDs(ids[:2]); err != nil { + t.Fatal(err) + } + tools := NewToolSet(d.Exploration(task.ExplorationID), "worker") + var beforeFacts int + if err := d.QueryRow("SELECT count(*) FROM exploration_nodes WHERE exploration_id=$1 AND kind='fact'", task.ExplorationID).Scan(&beforeFacts); err != nil { + t.Fatal(err) + } + for _, field := range []string{"asset_ids", "tested_asset_ids"} { + out := callGuardTool(t, tools.recordFact(), fmt.Sprintf(`{"summary":"missing anchors","%s":[%d,%d,%d]}`, field, ids[0], ids[1], ids[2])) + if !out.IsError || !strings.Contains(out.Flatten(), "do not exist") || + !strings.Contains(out.Flatten(), strconv.FormatInt(ids[0], 10)) || + !strings.Contains(out.Flatten(), strconv.FormatInt(ids[1], 10)) || + strings.Contains(out.Flatten(), "23503") || strings.Contains(out.Flatten(), "foreign key") { + t.Fatalf("missing assets did not produce an actionable error: %s", out.Flatten()) + } + } + var count int + if err := d.QueryRow("SELECT count(*) FROM exploration_nodes WHERE exploration_id=$1 AND kind='fact'", task.ExplorationID).Scan(&count); err != nil || count != beforeFacts || tools.Writes().Facts != 0 { + t.Fatalf("failed anchors left facts: count=%d err=%v", count, err) + } + out := callGuardTool(t, tools.recordFact(), fmt.Sprintf(`{"facts":[{"summary":"valid","asset_ids":[%d]},{"summary":"missing","tested_asset_ids":[%d]}]}`, ids[2], ids[0])) + var batch struct { + IDs []int64 `json:"ids"` + Errors map[string]string `json:"errors"` + } + if err := json.Unmarshal([]byte(out.Flatten()), &batch); err != nil { + t.Fatal(out.Flatten(), err) + } + if !out.IsError || len(batch.IDs) != 2 || batch.IDs[0] <= 0 || batch.IDs[1] != 0 || !strings.Contains(batch.Errors["1"], "do not exist") || tools.Writes().Facts != 1 { + t.Fatal("missing asset batch handling:", out.Flatten()) + } +} diff --git a/agent/fact_input.go b/agent/fact_input.go new file mode 100644 index 0000000..60c0890 --- /dev/null +++ b/agent/fact_input.go @@ -0,0 +1,160 @@ +package agent + +import ( + "bytes" + "encoding/json" + "fmt" +) + +// Match strings.TrimSpace, including Unicode whitespace, in the published schema. +const factWhitespace = "\t\n\v\f\r \u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000" + +func factAssetIDSchema() map[string]any { + return map[string]any{ + "type": []string{"integer", "string"}, "minimum": 1, + "pattern": "^[" + factWhitespace + "]*\\+?0*[1-9][0-9]*[" + factWhitespace + "]*$", + } +} + +func factItemSchema() map[string]any { + schema := obj(map[string]any{ + "summary": str("Required on every fact: a non-empty one-sentence summary of this conclusion. Batch items do not inherit summary from the top level."), + "intent_id": idp("The intent that produced this fact; only this field inherits from the top level in a batch."), + "detail": str("Details of this fact, including all related observations."), + "evidence": str("One line of key evidence: the command and the most proving output lines. Put longer output in detail."), + "confidence": str("observed (seen directly in output) | inferred (inferred from phenomena). Label negative conclusions honestly."), + "source": map[string]any{"type": "string", "enum": factSources, "description": "where the content came from: target_response | tool_output | third_party_intel | operator_input | inference (default when omitted)"}, + "asset_ids": map[string]any{"type": "array", "items": factAssetIDSchema(), "description": "Asset IDs explicitly involved in this fact. Use asset_ids as the canonical field; tested_asset_ids is accepted as an alias. If both are provided, they must name the same set. Do not infer IDs from the intent."}, + "tested_asset_ids": map[string]any{"type": "array", "items": factAssetIDSchema(), "description": "Compatibility alias for asset_ids, not an additional list. When both are provided their sets must match. Only include assets actually involved in this conclusion."}, + }, "summary") + summary := schema["properties"].(map[string]any)["summary"].(map[string]any) + summary["minLength"] = 1 + summary["pattern"] = "[^" + factWhitespace + "]" + schema["additionalProperties"] = false + return schema +} + +func recordFactSchema() map[string]any { + props := factItemSchema()["properties"].(map[string]any) + props["facts"] = map[string]any{ + "type": "array", "minItems": 1, "items": factItemSchema(), + "description": "A non-empty batch of complete facts. Every item needs its own summary. Only intent_id inherits from the top level. Returned ids match item order; retry only failed indices.", + } + schema := obj(props) + // Providers reject root-level anyOf. The handler enforces single/batch mode. + schema["additionalProperties"] = false + return schema +} + +// RepairRecordFactSchema restores the single/batch input contract in stored or +// cached schemas, preserving annotations only on fields the handler accepts. +func RepairRecordFactSchema(stored map[string]any) map[string]any { + raw, _ := json.Marshal(stored) + var out map[string]any + _ = json.Unmarshal(raw, &out) + if out == nil { + out = map[string]any{} + } + mergeFactContract(out, recordFactSchema()) + // A batch requires summaries on its items, never a redundant top-level one. + delete(out, "required") + delete(out, "anyOf") + canonical := recordFactSchema()["properties"].(map[string]any) + props := out["properties"].(map[string]any) + for name := range props { + if _, known := canonical[name]; !known { + delete(props, name) + } + } + items := props["facts"].(map[string]any)["items"].(map[string]any) + itemProps := items["properties"].(map[string]any) + for name := range itemProps { + if _, known := canonical[name]; !known || name == "facts" { + delete(itemProps, name) + } + } + return out +} + +func mergeFactContract(dst, src map[string]any) { + for key, value := range src { + if key == "description" || key == "default" { + if _, ok := dst[key]; ok { + continue + } + } + if child, ok := value.(map[string]any); ok { + target, _ := dst[key].(map[string]any) + if target == nil { + target = map[string]any{} + dst[key] = target + } + mergeFactContract(target, child) + } else { + dst[key] = value + } + } +} + +type recordFactInput struct { + Facts []factItem `json:"facts"` + factItem +} + +// Validate exact field names before decoding: encoding/json otherwise treats +// Summary, SUMMARY, etc. as aliases even with DisallowUnknownFields enabled. +func decodeRecordFactInput(in json.RawMessage) (recordFactInput, bool, error) { + var out recordFactInput + fields, err := exactFactFields(in, true) + if err != nil { + return out, false, err + } + _, batch := fields["facts"] + if batch { + for name := range fields { + if name != "intent_id" && name != "facts" { + return out, true, fmt.Errorf("field %q is not allowed at the top level in batch mode; only intent_id and facts are accepted", name) + } + } + var items []json.RawMessage + if err := json.Unmarshal(fields["facts"], &items); err != nil { + return out, true, fmt.Errorf("facts must be an array: %w", err) + } + if len(items) == 0 { + return out, true, fmt.Errorf("facts must be a non-empty array of complete facts, each with its own summary") + } + for i, item := range items { + if _, err := exactFactFields(item, false); err != nil { + return out, true, fmt.Errorf("facts[%d]: %w", i, err) + } + } + } + decoder := json.NewDecoder(bytes.NewReader(in)) + decoder.DisallowUnknownFields() // Also applies recursively to every factItem. + if err := decoder.Decode(&out); err != nil { + return out, batch, err + } + return out, batch, nil +} + +func exactFactFields(in json.RawMessage, topLevel bool) (map[string]json.RawMessage, error) { + var fields map[string]json.RawMessage + if err := json.Unmarshal(in, &fields); err != nil { + return nil, err + } + if fields == nil { + return nil, fmt.Errorf("record_fact input and each fact must be objects") + } + for name := range fields { + switch name { + case "summary", "detail", "evidence", "confidence", "source", "intent_id", "asset_ids", "tested_asset_ids": + case "facts": + if !topLevel { + return nil, fmt.Errorf("unknown field %q", name) + } + default: + return nil, fmt.Errorf("unknown field %q (field names are case-sensitive)", name) + } + } + return fields, nil +} diff --git a/agent/fact_input_test.go b/agent/fact_input_test.go new file mode 100644 index 0000000..6c02c12 --- /dev/null +++ b/agent/fact_input_test.go @@ -0,0 +1,165 @@ +package agent + +import ( + "encoding/json" + "regexp" + "strings" + "testing" + + actool "github.com/Autumn-27/norma/tool" +) + +func TestRecordFactSummaryContract(t *testing.T) { + tools := NewToolSet(guardTaskStore(t), "worker") + tool := tools.recordFact() + for _, input := range []string{ + `{}`, `null`, `[]`, + `{"summary":""}`, `{"summary":" "}`, + `{"summary":"must not substitute","facts":[]}`, + `{"summary":"must not substitute","facts":null}`, + `{"summary":"must not inherit","facts":[{"detail":"missing summary"}]}`, + `{"facts":[{"summary":"must not save"},{"summary":42}]}`, + } { + out := callGuardTool(t, tool, input) + if !out.IsError { + t.Errorf("accepted %s: %s", input, out.Flatten()) + } + } + if tools.Writes().Facts != 0 { + t.Fatal("invalid inputs wrote facts") + } + single := callGuardTool(t, tool, `{"summary":"valid single"}`) + if single.IsError { + t.Fatal(single.Flatten()) + } + batch := callGuardTool(t, tool, `{"facts":[{"summary":"valid batch"},{"detail":"missing summary"}]}`) + var result struct { + IDs []int64 `json:"ids"` + Errors map[string]string `json:"errors"` + Retry string `json:"retry_instruction"` + } + if err := json.Unmarshal([]byte(batch.Flatten()), &result); err != nil { + t.Fatal(batch.Flatten(), err) + } + if !batch.IsError || len(result.IDs) != 2 || result.IDs[0] <= 0 || result.IDs[1] != 0 || + !strings.Contains(result.Errors["1"], "summary") || result.Retry == "" || tools.Writes().Facts != 2 { + t.Fatalf("partial failure is not actionable: %s", batch.Flatten()) + } +} + +func TestRecordFactStoredContractRepair(t *testing.T) { + old := map[string]any{ + "type": "object", "required": []any{"summary"}, + "anyOf": []any{map[string]any{"required": []string{"summary"}}}, + "properties": map[string]any{ + "summary": map[string]any{"type": "string", "description": "operator summary"}, + "confidence": map[string]any{"type": "string", "default": "inferred"}, + "custom_field": map[string]any{"type": "string"}, + "facts": map[string]any{"type": "array", "items": map[string]any{"type": "object"}}, + }, + } + base := NewToolSet(nil, "").recordFact() + repaired := DecorateTool(base, "operator tool", old) + schema := repaired.InputSchema() + if _, required := schema["required"]; required { + t.Fatal("batch still requires a top-level summary") + } + if _, exists := schema["anyOf"]; exists { + t.Fatal("root anyOf reaches the provider") + } + props := schema["properties"].(map[string]any) + item := props["facts"].(map[string]any)["items"].(map[string]any) + required := item["required"].([]string) + if len(required) != 1 || required[0] != "summary" || props["facts"].(map[string]any)["minItems"] != 1 { + t.Fatal("batch must require a nonempty list with a summary per item") + } + if props["summary"].(map[string]any)["minLength"] != 1 || + item["properties"].(map[string]any)["summary"].(map[string]any)["minLength"] != 1 { + t.Fatal("empty summaries permitted by schema") + } + if repaired.Description() != "operator tool" || + props["summary"].(map[string]any)["description"] != "operator summary" || + props["confidence"].(map[string]any)["default"] != "inferred" || props["custom_field"] != nil { + t.Fatal("operator annotations lost") + } + if _, ok := old["properties"].(map[string]any)["tested_asset_ids"]; ok { + t.Fatal("shared old schema mutated") + } + first, _ := json.Marshal(schema) + second, _ := json.Marshal(DecorateTool(base, "", schema).InputSchema()) + if string(first) != string(second) { + t.Fatal("repair is not idempotent") + } + var roundTrip map[string]any + if err := json.Unmarshal(first, &roundTrip); err != nil { + t.Fatal(err) + } + for _, input := range []string{`{"summary":"single"}`, `{"facts":[{"summary":"batch"}]}`} { + if err := actool.ValidateInput(roundTrip, json.RawMessage(input)); err != nil { + t.Fatalf("SDK rejects valid %s after catalog round trip: %v", input, err) + } + } +} + +func TestRecordFactStrictFields(t *testing.T) { + tools := NewToolSet(guardTaskStore(t), "worker") + for _, tc := range []struct{ input, field string }{ + {`{"summary":"valid","typo":1}`, "typo"}, + {`{"Summary":"case alias"}`, "Summary"}, + {`{"summary":"valid","Facts":[]}`, "Facts"}, + {`{"facts":[{"summary":"first"},{"summary":"second","typo":1}]}`, "typo"}, + {`{"facts":[{"summary":"first"},{"Summary":"case alias"}]}`, "Summary"}, + {`{"facts":[{"summary":"first"},{"summary":"second","ASSET_IDS":[]}]}`, "ASSET_IDS"}, + {`{"facts":[{"summary":"nested","facts":[]}]}`, "facts"}, + {`{"summary":"ignored","facts":[{"summary":"batch"}]}`, "summary"}, + {`{"detail":"ignored","facts":[{"summary":"batch"}]}`, "detail"}, + {`{"evidence":"ignored","facts":[{"summary":"batch"}]}`, "evidence"}, + {`{"source":"inference","facts":[{"summary":"batch"}]}`, "source"}, + {`{"confidence":"inferred","facts":[{"summary":"batch"}]}`, "confidence"}, + {`{"asset_ids":[],"facts":[{"summary":"batch"}]}`, "asset_ids"}, + {`{"tested_asset_ids":[],"facts":[{"summary":"batch"}]}`, "tested_asset_ids"}, + } { + out := callGuardTool(t, tools.recordFact(), tc.input) + if !out.IsError || !strings.Contains(out.Flatten(), tc.field) { + t.Errorf("input %s: want named rejection for %s, got %s", tc.input, tc.field, out.Flatten()) + } + } + if tools.Writes().Facts != 0 { + t.Fatal("malformed fields caused partial writes") + } + for _, input := range []string{ + `{"facts":[null]}`, `{"facts":[[]]}`, `{"summary":"valid"} {"summary":"extra object"}`, + } { + if _, _, err := decodeRecordFactInput(json.RawMessage(input)); err == nil { + t.Errorf("accepted %s", input) + } + } + if _, batch, err := decodeRecordFactInput(json.RawMessage(`{"intent_id":1,"facts":[{"summary":"valid","intent_id":2}]}`)); err != nil || !batch { + t.Fatalf("valid batch: %v %v", batch, err) + } +} + +func TestRecordFactSchemaMatchesStrings(t *testing.T) { + props := recordFactSchema()["properties"].(map[string]any) + summary := regexp.MustCompile(props["summary"].(map[string]any)["pattern"].(string)) + for _, value := range []string{"", " ", "\t\r\n", "\u00a0\u0085", "\u2003\u3000", "conclusion", " observed "} { + if got, want := summary.MatchString(value), strings.TrimSpace(value) != ""; got != want { + t.Errorf("summary %q: schema=%v runtime=%v", value, got, want) + } + } + id := regexp.MustCompile(factAssetIDSchema()["pattern"].(string)) + for _, value := range []string{"1", "001", "+1", " +001 ", "\u200312\u3000", "", "0", "-1", "1.5", "a"} { + raw, _ := json.Marshal(value) + if got, want := id.MatchString(value), pid(raw) > 0; got != want { + t.Errorf("asset ID %q: schema=%v runtime=%v", value, got, want) + } + } + for _, input := range []string{ + `{"summary":"single","asset_ids":["1",2]}`, + `{"facts":[{"summary":"batch","tested_asset_ids":["1",2]}]}`, + } { + if err := actool.ValidateInput(recordFactSchema(), json.RawMessage(input)); err != nil { + t.Errorf("numeric-string compatibility rejected: %v", err) + } + } +} diff --git a/agent/toolcatalog.go b/agent/toolcatalog.go index 36fa00a..5811203 100644 --- a/agent/toolcatalog.go +++ b/agent/toolcatalog.go @@ -162,6 +162,9 @@ func DecorateTool(t actool.CoreTool, desc string, schema map[string]any) actool. if len(schema) == 0 { schema = t.InputSchema() } + if t.Name() == "record_fact" { + schema = RepairRecordFactSchema(schema) + } return &overriddenTool{CoreTool: t, desc: desc, schema: schema} } diff --git a/agent/tools.go b/agent/tools.go index eca4ad1..f143f28 100644 --- a/agent/tools.go +++ b/agent/tools.go @@ -1495,13 +1495,14 @@ func (t *ToolSet) addFinding() actool.CoreTool { // must NOT be stuffed into the asset graph via upsert_asset. // factItem is one fact of a record_fact batch/single call. type factItem struct { - Summary string `json:"summary"` - Detail string `json:"detail"` - Evidence string `json:"evidence"` // one line of key evidence (command + key output lines) supporting the conclusion, for later verification - Confidence string `json:"confidence"` // observed (seen directly) | inferred (inferred from phenomena) - Source string `json:"source"` // where the content came from, one of factSources; empty = inference - IntentID json.RawMessage `json:"intent_id"` - AssetIDs []json.RawMessage `json:"asset_ids"` + Summary string `json:"summary"` + Detail string `json:"detail"` + Evidence string `json:"evidence"` // one line of key evidence (command + key output lines) supporting the conclusion, for later verification + Confidence string `json:"confidence"` // observed (seen directly) | inferred (inferred from phenomena) + Source string `json:"source"` // where the content came from, one of factSources; empty = inference + IntentID json.RawMessage `json:"intent_id"` + AssetIDs []json.RawMessage `json:"asset_ids"` + TestedAssetIDs []json.RawMessage `json:"tested_asset_ids"` } // Fact sources (#124, F4): where a fact's content came from, as declared by the @@ -1537,12 +1538,16 @@ func normalizeFactSource(s string) (string, error) { // intent_id). func (t *ToolSet) recordOneFact(it factItem, defaultIntent int64) (int64, error) { if strings.TrimSpace(it.Summary) == "" { - return 0, fmt.Errorf("summary must not be empty") + return 0, fmt.Errorf("summary must not be empty: every fact, including each batch item, requires its own one-sentence summary") } source, err := normalizeFactSource(it.Source) if err != nil { return 0, err } + anchors, err := it.factAssetAnchors() + if err != nil { + return 0, err + } payload := map[string]any{"summary": it.Summary, "source": source} if it.Detail != "" { payload["detail"] = it.Detail @@ -1564,7 +1569,7 @@ func (t *ToolSet) recordOneFact(it factItem, defaultIntent int64) (int64, error) } } // a fact is its OWN node kind (distinct from a vuln finding). - id, err := t.ts.AddNode(db.KindFact, payload, 5, "confirmed", t.worker, pidList(it.AssetIDs)) + id, err := t.ts.AddNode(db.KindFact, payload, 5, "confirmed", t.worker, anchors) if err != nil { return 0, err } @@ -1584,23 +1589,12 @@ func (t *ToolSet) recordFact() actool.CoreTool { " · confidence = observed (seen directly in output) | inferred (inferred from phenomena).\n"+ " · source = where the content came from: target_response (content the target itself returned: page bodies, headers, error messages, banners, even when a tool fetched it) | tool_output (a tool's own result about the target: port states, scanner verdicts, status codes, timings) | third_party_intel (OSINT, CVE databases, public reports) | operator_input (given by the human operator) | inference (your own reasoning; the default when omitted). Any other value is refused.\n"+ " · **Negative conclusions** (not injectable / port closed / no entry found, etc.) state only \"observation + tentative reading\" — state what you actually saw; whether to abandon the direction is for the planner to decide globally; always provide evidence, mark inferred when the means weren't exhausted or the evidence is weak (including probed only once, looks-like), and mark observed only when truly exhausted and directly seen.", - obj(map[string]any{ - "facts": map[string]any{"type": "array", "description": "[use when there are several distinct conclusions] array of facts; element fields same as the top-level fields below (summary/detail/evidence/confidence/source/intent_id/asset_ids); omitting intent_id falls back to the top-level intent_id. The returned ids match this array in length and order.", "items": map[string]any{"type": "object"}}, - "summary": str("a [one-sentence summary] of this exploration's conclusion (a condensation of detail)"), - "intent_id": idp("the id of the intent that produced this fact (the intent you claimed; the default for each item in batch mode)"), - "detail": str("details related to this fact: write all of this exploration's observations here"), - "evidence": str("[one line] of key evidence: the command + the one or two most proving output lines. Keep it brief; don't paste large output blocks (details go in detail)."), - "confidence": str("observed (seen directly in output) | inferred (inferred from phenomena). Always label negative conclusions honestly."), - "source": map[string]any{"type": "string", "enum": factSources, "description": "where the content came from: target_response | tool_output | third_party_intel | operator_input | inference (default when omitted)"}, - "asset_ids": map[string]any{"type": "array", "items": map[string]any{"type": "integer"}, "description": "related asset ids (optional, 0/1/many): which assets this fact involves"}, - }), + recordFactSchema(), func(_ context.Context, in json.RawMessage) (actool.Result, error) { - var a struct { - Facts []factItem `json:"facts"` - factItem // single mode + batch default intent_id + a, batch, err := decodeRecordFactInput(in) + if err != nil { + return actool.Errorf("invalid record_fact input: " + err.Error() + "; no facts were written"), nil } - _ = json.Unmarshal(in, &a) - batch := len(a.Facts) > 0 items := a.Facts if !batch { items = []factItem{a.factItem} @@ -1627,8 +1621,11 @@ func (t *ToolSet) recordFact() actool.CoreTool { out := map[string]any{"ids": ids} if len(errs) > 0 { out["errors"] = errs + out["retry_instruction"] = "Retry only failed indices with complete facts, including summary. Successful indices were already saved; do not retry them." } - return jsonResult(out) + result, err := jsonResult(out) + result.IsError = len(errs) > 0 + return result, err }) } diff --git a/db/exploration.go b/db/exploration.go index ee2c919..055ee54 100644 --- a/db/exploration.go +++ b/db/exploration.go @@ -230,6 +230,13 @@ func (s *ExplorationStore) AddNode(kind string, payload map[string]any, priority return 0, err } defer tx.Rollback() + // Validate fact anchors before creating a node. Key-share locks retain the + // checked assets through commit, closing the check/insert deletion race. + if kind == KindFact && len(anchors) > 0 { + if err := checkFactAnchorAssets(tx, anchors); err != nil { + return 0, err + } + } var id int64 if err := tx.QueryRow(` INSERT INTO exploration_nodes(exploration_id, kind, payload, priority, state, origin) @@ -245,6 +252,40 @@ VALUES ($1, $2, $3, $4, $5, $6) RETURNING id`, return id, tx.Commit() } +func checkFactAnchorAssets(tx *sql.Tx, ids []int64) error { + rows, err := tx.Query("SELECT id FROM assets WHERE id = ANY($1::bigint[]) ORDER BY id FOR KEY SHARE", ids) + if err != nil { + return err + } + found := make(map[int64]bool, len(ids)) + for rows.Next() { + var id int64 + if err := rows.Scan(&id); err != nil { + rows.Close() + return err + } + found[id] = true + } + err = rows.Err() + closeErr := rows.Close() + if err != nil { + return err + } + if closeErr != nil { + return closeErr + } + var missing []int64 + for _, id := range ids { + if !found[id] { + missing = append(missing, id) + } + } + if len(missing) != 0 { + return fmt.Errorf("asset IDs do not exist: %v; use existing IDs or register the assets first", missing) + } + return nil +} + // AddIntent is a convenience: an open intent. func (s *ExplorationStore) AddIntent(payload map[string]any, priority int, anchors []int64, origin string) (int64, error) { if origin == "" { diff --git a/server/fact_input_schema.go b/server/fact_input_schema.go new file mode 100644 index 0000000..22ffed6 --- /dev/null +++ b/server/fact_input_schema.go @@ -0,0 +1,38 @@ +package server + +import ( + "encoding/json" + "log" + + "github.com/Autumn-27/artex/agent" +) + +// SeedTool only inserts new rows. Repair existing built-ins too, while keeping +// descriptions, bindings, enabled/deferred flags and parameter annotations. +func (s *Server) seedFactInputSchema() { + row, err := s.m.pg.GetTool("record_fact") + if err != nil { + log.Printf("[facts] read record_fact schema: %v", err) + return + } + if row == nil || !row.System || row.Kind != "builtin" { + return + } + var schema map[string]any + if err := json.Unmarshal(row.Schema, &schema); err != nil { + log.Printf("[facts] decode record_fact schema: %v", err) + return + } + raw, err := json.Marshal(agent.RepairRecordFactSchema(schema)) + if err != nil { + log.Printf("[facts] encode record_fact schema: %v", err) + return + } + // Compare-and-swap preserves concurrent operator edits; JSONB equality + // avoids changing updated_at again on every startup. + if _, err := s.m.pg.Exec(`UPDATE tools SET schema=$2::jsonb, updated_at=now() +WHERE key='record_fact' AND system AND kind='builtin' + AND schema=$1::jsonb AND schema IS DISTINCT FROM $2::jsonb`, string(row.Schema), string(raw)); err != nil { + log.Printf("[facts] repair record_fact schema: %v", err) + } +} diff --git a/server/fact_input_schema_test.go b/server/fact_input_schema_test.go new file mode 100644 index 0000000..4114633 --- /dev/null +++ b/server/fact_input_schema_test.go @@ -0,0 +1,106 @@ +package server + +import ( + "context" + "encoding/json" + "testing" + "time" + + "github.com/Autumn-27/artex/agent" + actool "github.com/Autumn-27/norma/tool" +) + +func TestRecordFactInputSchemaUpgrade(t *testing.T) { + skipWithoutDSN(t) + m, err := NewManager(t.TempDir(), "") + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { m.Close() }) + ctx, cancel := context.WithCancel(context.Background()) + cancel() + s := New(ctx, m, t.TempDir(), t.TempDir(), t.TempDir()) + t.Cleanup(func() { agent.SetToolResolve(nil) }) + pg := m.pg + old, err := pg.GetTool("record_fact") + if err != nil || old == nil { + t.Fatal("missing record_fact", err) + } + bindings, _ := json.Marshal(old.Agents) + t.Cleanup(func() { pg.UpdateTool(old.Key, old.Description, old.Schema, bindings, old.Enabled) }) + legacy := map[string]any{ + "type": "object", "required": []string{"summary"}, + "anyOf": []any{map[string]any{"required": []string{"summary"}}}, + "properties": map[string]any{ + "summary": map[string]any{"type": "string", "description": "operator summary"}, + "confidence": map[string]any{"type": "string", "default": "inferred"}, + "custom": map[string]any{"type": "string"}, + "facts": map[string]any{"type": "array", "items": map[string]any{"type": "object"}}, + }, + } + raw, _ := json.Marshal(legacy) + if err := pg.UpdateTool("record_fact", "operator tool", raw, bindings, old.Enabled); err != nil { + t.Fatal(err) + } + check := func(schema map[string]any) { + t.Helper() + if _, ok := schema["required"]; ok { + t.Fatal("top-level summary still required for batches") + } + if _, ok := schema["anyOf"]; ok { + t.Fatal("root anyOf still present") + } + if schema["additionalProperties"] != false { + t.Fatal("unknown fields allowed") + } + props := schema["properties"].(map[string]any) + items := props["facts"].(map[string]any)["items"].(map[string]any) + itemProps := items["properties"].(map[string]any) + if props["tested_asset_ids"] == nil || itemProps["tested_asset_ids"] == nil || itemProps["summary"] == nil { + t.Fatal("repaired schema missing alias or batch summary") + } + if props["summary"].(map[string]any)["description"] != "operator summary" || + props["confidence"].(map[string]any)["default"] != "inferred" || props["custom"] != nil { + t.Fatal("operator annotations lost") + } + if err := actool.ValidateInput(schema, json.RawMessage(`{"facts":[{"summary":"complete batch item"}]}`)); err != nil { + t.Fatal("valid batch rejected", err) + } + } + // Runtime repair protects cached or edited rows even before startup migration. + tools := agent.ToolResolve()(context.Background(), "worker", agent.NewToolSet(nil, "").WorkerTools()) + found := false + for _, tool := range tools { + if tool.Name() == "record_fact" { + check(tool.InputSchema()) + found = true + } + } + if !found { + t.Fatal("record_fact not resolved") + } + s.seedFactInputSchema() + repaired, err := pg.GetTool("record_fact") + if err != nil || repaired == nil { + t.Fatal(err) + } + var schema map[string]any + if err := json.Unmarshal(repaired.Schema, &schema); err != nil { + t.Fatal(err) + } + check(schema) + if repaired.Description != "operator tool" || repaired.Enabled != old.Enabled { + t.Fatal("operator tool settings changed") + } + var before, after time.Time + if err := pg.QueryRow("SELECT updated_at FROM tools WHERE key='record_fact'").Scan(&before); err != nil { + t.Fatal(err) + } + s.seedFactInputSchema() + if err := pg.QueryRow("SELECT updated_at FROM tools WHERE key='record_fact'").Scan(&after); err != nil { + t.Fatal(err) + } + if !before.Equal(after) { + t.Fatal("second migration changed the row") + } +} diff --git a/server/fact_source_schema_test.go b/server/fact_source_schema_test.go index a677658..a087b4f 100644 --- a/server/fact_source_schema_test.go +++ b/server/fact_source_schema_test.go @@ -47,8 +47,8 @@ func TestRecordFactSourceSchemaUpgrade(t *testing.T) { if err := pg.UpdateTool("record_fact", "operator description", custom, bindings, true); err != nil { t.Fatal(err) } - if src := resolvedRecordFactProps(t)["source"]; src != nil { - t.Fatalf("precondition: stored schema should not expose source yet: %v", src) + if src := resolvedRecordFactProps(t)["source"]; src == nil { + t.Fatal("runtime contract repair must expose source even before startup migration") } snapshot := func() (string, string, time.Time) { diff --git a/server/orchestration.go b/server/orchestration.go index d03dc4a..bf88343 100644 --- a/server/orchestration.go +++ b/server/orchestration.go @@ -571,6 +571,7 @@ func (s *Server) seedOrchestrationTools() { s.seedFindingWorkflowTools() s.seedFindingVerificationSchema() // S1: poe_level / evidence_quotes on update_finding_report, added once per DB s.seedFindingEvidenceSchema() // optional counterevidence / confidence_rationale on report_finding, added once per DB + s.seedFactInputSchema() // restore record_fact single/batch contracts s.seedFactSourceSchema() // source enum on record_fact, added once per DB s.seedTaskScopeDescription() // add_task_scope: "coverage scope, not enforced" replaces the authorization-boundary text // Note: pentest's default tool bindings need no migration — BuiltinToolSeeds already seeds