package tools import ( "encoding/json" "fmt" "strconv" "strings" "pentagi/pkg/database/knowledge/limits" "pentagi/pkg/graph/model" ) // FileOp is a type alias (not a distinct type) for String: it shares the // exact same lenient UnmarshalJSON, so every FileOp value - including the // ReadFile/WriteFile/EditFile constants below - automatically benefits from // the quote-unwrapping behaviour documented on String, with zero changes // needed at any existing call site (switches, comparisons, assignments) // elsewhere in the codebase. type FileOp = String const ( ReadFile FileOp = "read_file" WriteFile FileOp = "write_file" EditFile FileOp = "edit_file" ) // FileAction's field descriptions are layered on purpose, each one adding // only what the level above doesn't already say: the tool description (see // registry.go) gives the read/write/edit decision; Action's enum values name // which payload field each one consumes; Content/Diff each spec out the // format of their own payload. Path/Message never vary by action, so they're // described once, action-agnostically. type FileAction struct { Action FileOp `json:"action" jsonschema:"required,type=string,enum=read_file,enum=write_file,enum=edit_file" jsonschema_description:"'read_file' reads the file (no other field needed). 'write_file' overwrites it with 'content' (the whole file). 'edit_file' applies the patch in 'diff' (existing content elsewhere is untouched)."` Content string `json:"content,omitempty" jsonschema_description:"write_file only: the complete new file content (not a diff, not a partial update)."` Diff String `json:"diff,omitempty" jsonschema:"type=string" jsonschema_description:"edit_file only: unified-diff hunk(s) - '@@ -old +new @@' header, then ' '/'-'/'+' lines. Always keep at least one unchanged context line so the location is unambiguous; context/removed lines must match the file's current content verbatim (read_file first). Header line numbers are only a hint - the line text is what must match."` Path String `json:"path" jsonschema:"required,type=string" jsonschema_description:"Absolute path to the file, taken literally. This field is not run through a shell, so command substitutions, variables and globs would become part of the filename - resolve them with the terminal tool first and pass the result."` Message string `json:"message" jsonschema:"required,title=File action message" jsonschema_description:"Engagement-log entry — a 1-2 short sentence running commentary describing what you are reading, writing, or editing and why. Written in the engagement language declared by your system prompt."` } // BrowserAction is a type alias for String - see the FileOp comment above. type BrowserAction = String const ( Markdown BrowserAction = "markdown" HTML BrowserAction = "html" Links BrowserAction = "links" ) type Browser struct { Url string `json:"url" jsonschema:"required" jsonschema_description:"URL to open in the browser"` Action BrowserAction `json:"action" jsonschema:"required,type=string,enum=markdown,enum=html,enum=links" jsonschema_description:"Action to perform in the browser. 'markdown' - Returns the content of the page in markdown format. 'html' - Returns the content of the page in html format. 'links' - Get the list of all URLs on the page to be used in later calls (e.g., open search results after the initial search lookup)."` Message string `json:"message" jsonschema:"required,title=Browser action message" jsonschema_description:"Engagement-log entry — a 1-2 short sentence running commentary describing what content you are fetching, in which format, and why. Written in the engagement language declared by your system prompt."` } type SubtaskInfo struct { Title string `json:"title" jsonschema:"required,title=Subtask title" jsonschema_description:"Engagement-log plan entry — short title of this subtask capturing its main goal as it appears in the engagement plan. Written in the engagement language declared by your system prompt."` Description string `json:"description" jsonschema:"required,title=Subtask to complete" jsonschema_description:"Engagement-log plan entry — full description of this subtask (instructions, rules, requirements, success criteria) as it appears in the engagement plan. Written in the engagement language declared by your system prompt."` } type SubtaskList struct { Subtasks SubtaskInfos `json:"subtasks" jsonschema:"required,title=Subtasks to complete" jsonschema_description:"Ordered list of subtasks produced by decomposing the task. Each subtask's title and description are engagement-log plan entries (see SubtaskInfo) — written in the engagement language declared by your system prompt."` Message string `json:"message" jsonschema:"required,title=Subtask generation result" jsonschema_description:"Engagement-log entry — a 1-2 short sentence running commentary on the generation result and the main goal of the plan. Written in the engagement language declared by your system prompt."` } // SubtaskOperationType defines the type of operation to perform on a subtask. // It is a type alias for String - see the FileOp comment above. type SubtaskOperationType = String const ( SubtaskOpAdd SubtaskOperationType = "add" SubtaskOpRemove SubtaskOperationType = "remove" SubtaskOpModify SubtaskOperationType = "modify" SubtaskOpReorder SubtaskOperationType = "reorder" ) // SubtaskOperation defines a single operation on the subtask list for delta-based refinement type SubtaskOperation struct { Op SubtaskOperationType `json:"op" jsonschema:"required,type=string,enum=add,enum=remove,enum=modify,enum=reorder" jsonschema_description:"Operation type: 'add' creates a new subtask, 'remove' deletes a subtask by ID, 'modify' updates title/description of existing subtask, 'reorder' moves a subtask to a different position"` ID *int64 `json:"id,omitempty" jsonschema:"title=Subtask ID" jsonschema_description:"ID of existing subtask (required for remove/modify/reorder operations)"` AfterID *int64 `json:"after_id,omitempty" jsonschema:"title=Insert after ID" jsonschema_description:"For add/reorder: insert after this subtask ID (null/0 = insert at beginning)"` Title string `json:"title,omitempty" jsonschema:"title=New title" jsonschema_description:"Engagement-log plan entry — new subtask title (required for add, optional for modify). Written in the engagement language declared by your system prompt."` Description string `json:"description,omitempty" jsonschema:"title=New description" jsonschema_description:"Engagement-log plan entry — new subtask description (required for add, optional for modify). Written in the engagement language declared by your system prompt."` } type SubtaskInfoPatch struct { ID int64 `json:"id,omitempty" jsonschema:"title=Subtask ID" jsonschema_description:"ID of the subtask (populated by the system for existing subtasks)"` SubtaskInfo } // SubtaskPatch is the delta-based refinement output for modifying subtask lists type SubtaskPatch struct { Operations SubtaskOperations `json:"operations" jsonschema:"required" jsonschema_description:"List of operations to apply to the current subtask list. Empty array means no changes needed. Each operation's title/description, when present, is an engagement-log plan entry (see operations)."` Message string `json:"message" jsonschema:"required,title=Refinement summary" jsonschema_description:"Engagement-log entry — a 1-2 short sentence running commentary on the changes made and the justification for the modifications. Written in the engagement language declared by your system prompt."` } type TaskResult struct { // Success is a pointer so an omitted field is distinguishable from false. // It decides whether the task is recorded as finished or failed, and a model // that leaves it out must be asked again rather than have a failure assumed. Success *Bool `json:"success" jsonschema:"title=Execution result,type=boolean" jsonschema_description:"True if the task was executed successfully and its objective was reached"` Result string `json:"result" jsonschema:"required,title=Task result description" jsonschema_description:"Engagement-log closing entry — fully detailed write-up of the task/subtask outcome (what was achieved or why it failed). Written in the engagement language declared by your system prompt."` Message string `json:"message" jsonschema:"required,title=Task result message" jsonschema_description:"Engagement-log closing summary — a concise 1-2 sentence recap of the outcome and the path taken to reach the goal. Written in the engagement language declared by your system prompt."` } const ( toolCallFieldEnd = `` toolCallMessageStart = `` toolCallFieldStart = `= len(s) { b.WriteString(`\\`) continue } switch next := s[i+1]; next { case '"', '\\', '/', 'b', 'f', 'n', 'r', 't': b.WriteByte(c) b.WriteByte(next) i++ case 'u': if i+6 <= len(s) && isHex4(s[i+2:i+6]) { b.WriteString(s[i : i+6]) i += 5 continue } b.WriteString(`\\`) default: b.WriteString(`\\`) } } return b.String() } func isHex4(s string) bool { if len(s) != 4 { return false } for i := 0; i < 4; i++ { c := s[i] if (c < '0' || c > '9') && (c < 'a' || c > 'f') && (c < 'A' || c > 'F') { return false } } return true } // LeakedMarkupListError is a list argument whose value is the model's own // tool-call markup rather than data -- Anthropic's `` // emitted inside the JSON string. Nothing in it is a recoverable list, so the // message has to tell the fixer what shape to send instead of what failed to // parse. type LeakedMarkupListError struct { // Field is the argument that arrived as markup, so the refusal can name it. Field string } func (e *LeakedMarkupListError) Error() string { return fmt.Sprintf( "%s contains tool-call markup instead of data: send %s as a JSON array of objects, "+ "not as text containing tags", e.Field, e.Field, ) } type Bool bool func (b *Bool) UnmarshalJSON(data []byte) error { sdata := strings.Trim(strings.ToLower(string(data)), "' \"\n\r\t") switch sdata { case "true": *b = true case "false": *b = false default: return fmt.Errorf("invalid bool value: %s", sdata) } return nil } func (b *Bool) MarshalJSON() ([]byte, error) { if b == nil || !*b { return []byte("false"), nil } return []byte("true"), nil } func (b *Bool) Bool() bool { if b == nil { return false } return bool(*b) } func (b *Bool) String() string { if b == nil { return "" } return strconv.FormatBool(bool(*b)) } type Int64 int64 func (i *Int64) UnmarshalJSON(data []byte) error { sdata := strings.Trim(strings.ToLower(string(data)), "' \"\n\r\t") if sdata == "" { *i = 0 return nil } num, err := strconv.ParseInt(sdata, 10, 64) if err != nil { return fmt.Errorf("invalid int value: %s", sdata) } *i = Int64(num) return nil } func (i *Int64) MarshalJSON() ([]byte, error) { if i == nil { return []byte("0"), nil } return []byte(strconv.FormatInt(int64(*i), 10)), nil } func (i *Int64) Int() int { if i == nil { return 0 } return int(*i) } func (i *Int64) Int64() int64 { if i == nil { return 0 } return int64(*i) } func (i *Int64) PtrInt64() *int64 { if i == nil { return nil } v := int64(*i) return &v } func (i *Int64) String() string { if i == nil { return "" } return strconv.FormatInt(int64(*i), 10) } // String is a lenient string for LLM-generated tool-call arguments, in // particular enum-like fields (action/type/search_type/... - anywhere a // value is compared or switched on rather than read as free text). Models // occasionally wrap the value in an extra, literal pair of quote characters // - e.g. the JSON string "\"write_file\"" decodes via a plain string // UnmarshalJSON into the 12-character Go string `"write_file"` (quotes // included), which then matches no known enum value, fails validation, and // forces an unnecessary tool-call-fixer round-trip. UnmarshalJSON unwraps // that redundant quoting instead of failing outright. // // FileOp, BrowserAction, SubtaskOperationType, and FlowStatusDetail are type // aliases for String (not distinct types), so every field declared with one // of those names gets this leniency automatically, with zero changes needed // at any existing call site: switches, `==` comparisons, and assignments // against their constants all keep working exactly as before, because the // alias makes them the exact same type as String, not merely a similar one. type String string func (s *String) UnmarshalJSON(data []byte) error { // A bare JSON "null" unmarshals into an empty string with no error by // default, which would silently mask a required field being omitted - // treat it as invalid instead, consistent with Bool/Int64/Strings above. if trimmed := strings.TrimSpace(string(data)); trimmed == "null" { return fmt.Errorf("invalid string value: got null") } var raw string if err := json.Unmarshal(data, &raw); err != nil { return err } *s = String(unwrapRedundantQuotes(raw)) return nil } func (s String) MarshalJSON() ([]byte, error) { return json.Marshal(string(s)) } // String implements fmt.Stringer, so %s/%v formatting and logrus fields show // the unwrapped value, and callers that need a plain string (map keys, // strings.* helpers, external struct fields, typed casts) can call it explicitly. func (s String) String() string { return string(s) } // unwrapRedundantQuotes strips at most a few layers of a matching leading+ // trailing '"' pair from a decoded JSON string value. Bounded to guard // against pathological input; the observed corruption is a single extra // layer, but a small bound costs nothing and covers repeated wrapping too. func unwrapRedundantQuotes(s string) string { for range 3 { trimmed := strings.TrimSpace(s) if len(trimmed) < 2 || trimmed[0] != '"' || trimmed[len(trimmed)-1] != '"' { return s } s = trimmed[1 : len(trimmed)-1] } return s } // Strings is a lenient []string for LLM-generated tool-call arguments (e.g. // the "questions" field of vector-store search tools). Models occasionally // double-encode the array as a JSON string containing the array literal // (e.g. "[\"a\", \"b\"]" instead of a real ["a","b"]), which fails a plain // []string unmarshal with "cannot unmarshal string into ... []string" and // forces an unnecessary tool-call-fixer round-trip. UnmarshalJSON recovers // from that case instead of failing outright. type Strings []string func (s *Strings) UnmarshalJSON(data []byte) error { // A bare JSON "null" unmarshals into a nil slice with no error by default, // which would silently mask a required field being omitted - treat it as // invalid instead, consistent with Bool/Int64 above. if trimmed := strings.TrimSpace(string(data)); trimmed == "null" { return fmt.Errorf("invalid strings value: expected a JSON array of strings, got: null") } // Primary path: a real JSON array of strings - the common, schema-conforming case. var arr []string if err := json.Unmarshal(data, &arr); err == nil { *s = arr return nil } // Recovery path: the array was sent as a JSON string. Try to decode its // content as a JSON array of strings first (the double-encoding case seen // in production), then fall back to treating the whole string as a single // element so one plain question doesn't fail either. var encoded string if err := json.Unmarshal(data, &encoded); err == nil { var nested []string if err := json.Unmarshal([]byte(encoded), &nested); err == nil { *s = nested return nil } if trimmed := strings.TrimSpace(encoded); trimmed != "" { *s = []string{trimmed} return nil } } return fmt.Errorf( "invalid strings value: expected a JSON array of strings, e.g. [\"question 1\",\"question 2\"], got: %s", strings.TrimSpace(string(data)), ) } func (s *Strings) MarshalJSON() ([]byte, error) { if s == nil || *s == nil { return []byte("[]"), nil } return json.Marshal([]string(*s)) } // GuideType is a KnowledgeGuideType decoded from LLM-generated tool-call arguments. type GuideType model.KnowledgeGuideType func (t *GuideType) UnmarshalJSON(data []byte) error { var raw String if err := raw.UnmarshalJSON(data); err != nil { return err } gt := model.KnowledgeGuideType(strings.ToLower(strings.TrimSpace(raw.String()))) if !gt.IsValid() { gt = model.KnowledgeGuideTypeOther } *t = GuideType(gt) return nil } type CodeLang string func (l *CodeLang) UnmarshalJSON(data []byte) error { var raw String if err := raw.UnmarshalJSON(data); err != nil { return err } *l = CodeLang(limits.CanonicalCodeLang(raw.String())) return nil } func (l CodeLang) MarshalJSON() ([]byte, error) { return json.Marshal(string(l)) } func (l CodeLang) String() string { return string(l) } func (t GuideType) MarshalJSON() ([]byte, error) { return json.Marshal(string(t)) } func (t GuideType) String() string { return string(t) } // AnswerType is the KnowledgeAnswerType counterpart of GuideType. type AnswerType model.KnowledgeAnswerType func (t *AnswerType) UnmarshalJSON(data []byte) error { var raw String if err := raw.UnmarshalJSON(data); err != nil { return err } at := model.KnowledgeAnswerType(strings.ToLower(strings.TrimSpace(raw.String()))) if !at.IsValid() { at = model.KnowledgeAnswerTypeOther } *t = AnswerType(at) return nil } func (t AnswerType) MarshalJSON() ([]byte, error) { return json.Marshal(string(t)) } func (t AnswerType) String() string { return string(t) }