Compare commits

..
Author SHA1 Message Date
BaaRai 51e2c603b9 Merge pull request #282 from renaesop/codex/fix-record-fact-input-contract
fix: repair record_fact summary contracts and asset aliases
2026-11-18 03:30:48 +01:00
BaaRai 9355d83eea Merge pull request #314 from yeting1107/docs/post-0-6-0-changelog
docs: record the post-0.6.0 changes
2026-11-18 03:03:44 +01:00
BaaRai 9b850a090c docs: add the post-#305 changelog entries
The rebase onto current main keeps the original entries and adds the three
user-facing changes merged after its base: the finding report_state field,
the ordered LLM health persistence, and the framed intent summaries.
2026-11-18 02:52:25 +01:00
yeting1107 398a08814a docs: record the post-0.6.0 changes 2026-11-18 02:52:06 +01:00
Chubboy Ren c833130c28 fix: enforce exact record_fact fields and validate asset anchors 2026-11-18 01:51:41 +00:00
Chubboy Ren c0c568b31f Merge remote-tracking branch 'upstream/main' into codex/fix-record-fact-input-contract 2026-11-18 01:34:26 +00:00
BaaRai ac5e714eb6 Merge pull request #313 from BaaRai/fix/task-llm-health-badge
fix(llm): record breaker health on every task path
2026-11-18 01:42:49 +01:00
Chubboy Ren 70d6833f35 fix: repair record_fact input contracts and asset aliases 2026-11-17 06:14:31 +00:00
13 changed files with 791 additions and 28 deletions
+22
View File
@@ -25,6 +25,13 @@ All notable changes to this project are documented in this file. The format is b
- **Release provenance**: release archives carry GitHub build provenance attestations and a CycloneDX SBOM (`gh attestation verify <zip> --repo BaaRai/ARTEX`); release notes are the matching `CHANGELOG.md` section (#219, #201).
- **Capture-proxy rewrite rules, storage and API**: `GET`, `POST`, `PUT` and `DELETE /api/traffic/rewrite-rules` and `POST /api/traffic/rewrite-rules/{id}/toggle` manage rules that match a request or a response (method, host, URL, headers, body, status) and describe a rewrite (method, path and query, headers, body, status). Rules are validated on save, limited to 100 of which 50 enabled, created disabled, and stored in the new table `traffic_rewrite_rules` (migration `0005_traffic_rewrite_rules.sql`) with `matchers` and `actions` encrypted at rest. The value of an action marked `sensitive` is never returned, and an update sent without it keeps the stored one. The server compiles the enabled rules at startup and after every change and hands the snapshot to the proxy. The proxy applies them from the next entry. See `docs/traffic-rewrite-rules.md`.
- **Capture-proxy rewrite rules applied**: the capture proxy applies enabled rules to each HTTP request before it is sent to the target and to each response before it reaches the client. Each action that ran is recorded in the new table `exchange_rewrites` in the same transaction as the exchange, `traffic_get` shows a `REWRITTEN` line, and `traffic_search` never finds a value a rule wrote. SSE status and headers are rewritten at the start of the stream. **WebSocket handshakes are not rewritten**: the capture library runs its hook after the upgrade, so the status and headers cannot be changed, and frames pass unchanged. **Responses of 5 MiB or more** are forwarded unchanged and not recorded in full, because the library does not call the response hook for them. Snapshots of original requests are capped at 1024 entries and 64 MiB. Replays go through the proxy, so the rules apply to them. Archives, a per-replay rule toggle, the web UI and the proof flag come later.
- **Bulk finding status** (#298): select findings in the findings table and apply one disposition to all of them, up to 500 per call, in one transaction; each row still goes through the single-decision notification semantics and the change is mirrored onto its exploration node (#289).
- **Traffic replay** (#266): replay a recorded request from the traffic detail with its method, URL, headers and stored body; replay is disabled when only the body preview is loaded.
- **Finding proof strength in reports** (#268): the Markdown report and the export show each finding's proof strength next to its verification status.
- **Opt-in Keenable web search backend** (#295): the search tool gains Keenable alongside Brave and Tavily; the key is stored encrypted and can be cleared independently.
- **Durable activity outbox** (#300): activity rows that cannot be stored are written to the new `activity_outbox` table (migration `0006_activity_outbox.sql`) and replayed once on the next start. The server stops admitting new work before the drain, and a shutdown cancel leaves an in-flight intent claim running so the next start can reset it to open instead of recording it as done or blocked.
- **LLM model search** (#284): the System → LLM model picker can search the model list, and the API-key field opts out of password-manager autofill.
- **Finding report state** (#308): findings carry a `report_state` (`none`, `submitted`, `accepted`, `rejected`, `duplicate`) for what was sent to a bug bounty program, separate from the triage status; the bulk update accepts both fields, and restoring an older archive fills `none` (migration `0007_finding_report_state.sql`).
### Changed
@@ -33,16 +40,31 @@ All notable changes to this project are documented in this file. The format is b
- **Untrusted-output boundary is now on by default**: Norma frames tool results for the worker, planner, chat and main agent unless `ARTEX_UNTRUSTED_BOUNDARY` is set to `0`, `false`, `off` or `no`. It was opt-in via `ARTEX_UNTRUSTED_BOUNDARY=1` in 0.6.0 (#166); the default flips here (#203).
- **Versioned migrations**: the `db` package applies numbered `db/migrations/NNNN_slug.sql` files once, in order, under the schema advisory lock, and records a SHA-256 checksum in `schema_migrations`; missing, renamed, changed or out-of-order migrations fail closed (#226).
- **Coverage graph performance**: the coverage graph batches its connector lookups (three queries instead of one per root and per company) and adds the partial index `idx_ts_icp`; on a task of about 3,000 assets the p50 dropped from 126 ms to 27 ms and the queries per call from 221 to 3 (#230).
- **Request body bounds** (#305): JSON request bodies decode at most 32 MiB, every non-multipart body is capped, and an oversized body answers 413 instead of a generic bad request. `ReadTimeout` bounds how long headers and the body may take to arrive without cutting a handler that is already running.
- **Chat attachments up to 512 MiB** (#252): the client, server, compose file and reverse-proxy sample agree on a 512 MiB combined multipart limit.
- **MITM passthrough TTL** (#306): a host that cannot be intercepted is tunnelled for one minute, then interception is tried again; an expired mark counts as intercepted.
- **Norma v0.4.11** (#294).
- **CI**: the suite also runs on the latest Go release as an advisory job, the rewrite-rule engine runs under the race detector, and the gzip/compression fixtures no longer depend on the local Go version (#279, #278).
- **Repository hygiene** (#275): `docs/` is no longer ignored, and contributing documents the 7-open-pull-request cap (#307).
### Fixed
- **LLM health badge on every task path**: `/system/llm/` read a breaker state that only the failover Pool wrote, so a profile used by an explicit task chain, by a bound agent with failover off, or as the global provider stayed "Healthy" through a real outage. Every task LLM attempt now records its outcome through the same policy the Pool uses, keyed by the profile that served it. The LLM recording page also explains an empty list when the `llm_record` toggle is off instead of looking broken.
- **LLM health persistence** (#304): persisted breaker rows are applied in sequence at startup and written before the database closes, and a slow write no longer holds the registry lock while it runs.
- **Skill visibility survives restarts**: turning a skill off now writes an explicit disabled row instead of deleting it, so the startup seed, which only inserts missing rows, can no longer bring the skill back. Skills that were turned off before this version have no row to keep, so they come back once after the upgrade and must be turned off again.
- **Browser extension traffic capture**: CDP delivers `Network.responseReceived` response headers as an object, not an array of `{name, value}` records, so the extension threw on every response and never queued an exchange. It now accepts both shapes and lower-cases names before the body-capture gate, so captures work again and `content-type` correctly controls body capture.
- **bbot on arm64**: the image now builds on arm64 hosts such as Apple Silicon. bbot's `gowitness` downloaded an x86-64 Chrome and `retirejs` an x86-64 Node, which can't run there, so the build failed. On arm64 the image uses Debian's `chromium` for gowitness and an arm64 Node for retirejs, and the build check now covers `retirejs` too. amd64 builds are unchanged.
- **Auto-scope hygiene**: auto `task_scope` rows count for coverage and untested assets only under a declared root, and direct coverage counts anchored assets through fact anchors only; the scope is described as "coverage scope, not enforced" (#196).
- **Enrich HTTP probe**: it now dials through `intercept.PinnedDialer`, so the target gate applies and a probe without a target scope is refused (#198).
- **Agent hook data races**: the eight package-level hooks are synchronised, so a second wire-up no longer races tasks that already read them (#227).
- **Coverage flag read failure** (#303): asset-coverage tools stay available when the coverage flag cannot be read, and a failed read no longer disables coverage for the task.
- **RSI lesson correctness** (#287, #290): lessons are scoped from `task_scope`, UTF-8 is no longer split mid-character, caution lessons are looked up by cue, lesson evidence and every retest are retracted when a finding's disposition reverses, and extraction is skipped on a task with more than one company.
- **Finding disposition mirror** (#289): finding triage is mirrored onto its exploration node, so the graph and the findings table agree.
- **RSI lessons in the data envelope** (#288): lesson text reaches the planner and worker inside the same nonce-framed envelope as other target-derived content.
- **Intent summaries framed** (#311): the intent summary on the worker-finished and finding lines, and the summaries in `graph_overview`, now reach the planner inside the nonce frame; the structured intent fields stay in the plain JSON, and the operator-typed deletion reason stays outside.
- **LLM pool context window** (#286): the pool and side-question paths use the model's real context window instead of a default when computing compression thresholds.
- **Sensitive rewrite values** (#273 follow-ups): a kept sensitive value is matched on action type, header name and regex, and a host change is refused while a stored sensitive value is kept.
- **Triage bot context** (#274): the PR triage bot receives a directory map instead of a truncated file list.
### Security
+8 -1
View File
@@ -233,7 +233,11 @@ worker remains confined to the intent it claimed.
</details>
- **Verified findings**: findings carry a POE level, a verification status and a note; a finding is
`verified` only when a bound proof/response and verbatim evidence quotes support it. Gzip/deflate
bodies are decoded before the quote check.
bodies are decoded before the quote check. The findings table supports bulk status updates, and
the report and export show each finding's proof strength next to its status.
- **Traffic replay**: open a captured exchange and replay the recorded request (method, URL,
headers and stored body) from the traffic detail; replay stays disabled while only the body
preview is loaded.
- **Vulnerability retest loop**: a dedicated `retester` agent re-runs a finding with optional fixed
version/conditions, records `Still reproducible / Fixed / Cannot confirm`, and can move the
finding to `Fixed` automatically. Original evidence and reports are preserved.
@@ -295,6 +299,9 @@ worker remains confined to the intent it claimed.
for every call.
- **MCP servers, skills, memory and a workspace**: extend the agent with remote tools and reusable
prompt/playbook material.
- **Web search**: the agent's search tool uses Brave, Tavily or the opt-in Keenable backend,
configured in **System → Settings** with the key encrypted at rest; search can also egress
through its own proxy.
- **Single binary**: the Next.js UI is embedded with `go:embed`; PostgreSQL is the only external
dependency.
+41
View File
@@ -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
}
+182
View File
@@ -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())
}
}
+160
View File
@@ -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
}
+165
View File
@@ -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)
}
}
}
+3
View File
@@ -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}
}
+22 -25
View File
@@ -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
})
}
+41
View File
@@ -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 == "" {
+38
View File
@@ -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)
}
}
+106
View File
@@ -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")
}
}
+2 -2
View File
@@ -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) {
+1
View File
@@ -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