|
| 1 | +package sigil |
| 2 | + |
| 3 | +import ( |
| 4 | + "context" |
| 5 | + "fmt" |
| 6 | + "strings" |
| 7 | +) |
| 8 | + |
| 9 | +// ContentCaptureMode controls what content is included in exported generation |
| 10 | +// payloads and OTel span attributes. |
| 11 | +type ContentCaptureMode int |
| 12 | + |
| 13 | +const ( |
| 14 | + // ContentCaptureModeDefault uses the parent or client-level default. |
| 15 | + // On Config this resolves to Full for backward compatibility. |
| 16 | + // On GenerationStart this inherits from Config. |
| 17 | + // On ToolExecutionStart this inherits from the parent generation context, |
| 18 | + // falling back to Config. |
| 19 | + ContentCaptureModeDefault ContentCaptureMode = iota |
| 20 | + // ContentCaptureModeFull exports all content. |
| 21 | + ContentCaptureModeFull |
| 22 | + // ContentCaptureModeMetadataOnly preserves message structure, tool names, |
| 23 | + // usage, and timing but strips text, tool arguments, tool results, |
| 24 | + // thinking, system prompts, and raw artifacts. |
| 25 | + // |
| 26 | + // Note: user-provided Metadata and Tags are NOT stripped — callers are |
| 27 | + // responsible for ensuring these maps do not contain sensitive content |
| 28 | + // when using MetadataOnly mode. |
| 29 | + ContentCaptureModeMetadataOnly |
| 30 | +) |
| 31 | + |
| 32 | +const ( |
| 33 | + metadataKeyContentCaptureMode = "sigil.sdk.content_capture_mode" |
| 34 | + contentCaptureModeValueFull = "full" |
| 35 | + contentCaptureModeValueMetaOnly = "metadata_only" |
| 36 | +) |
| 37 | + |
| 38 | +// resolveContentCaptureMode returns the effective mode from an override and a |
| 39 | +// fallback. Default is transparent — it falls through to the fallback. |
| 40 | +func resolveContentCaptureMode(override, fallback ContentCaptureMode) ContentCaptureMode { |
| 41 | + if override != ContentCaptureModeDefault { |
| 42 | + return override |
| 43 | + } |
| 44 | + return fallback |
| 45 | +} |
| 46 | + |
| 47 | +// callContentCaptureResolver invokes the resolver callback safely, recovering |
| 48 | +// from panics. Returns ContentCaptureModeDefault when the resolver is nil. |
| 49 | +// Panics are treated as ContentCaptureModeMetadataOnly (fail-closed). |
| 50 | +func callContentCaptureResolver(resolver func(ctx context.Context, metadata map[string]any) ContentCaptureMode, ctx context.Context, metadata map[string]any) (mode ContentCaptureMode) { |
| 51 | + if resolver == nil { |
| 52 | + return ContentCaptureModeDefault |
| 53 | + } |
| 54 | + defer func() { |
| 55 | + if r := recover(); r != nil { |
| 56 | + mode = ContentCaptureModeMetadataOnly |
| 57 | + } |
| 58 | + }() |
| 59 | + return resolver(ctx, metadata) |
| 60 | +} |
| 61 | + |
| 62 | +// resolveClientContentCaptureMode resolves the effective mode for the client. |
| 63 | +// Default at the client level means Full (backward compatibility). |
| 64 | +func resolveClientContentCaptureMode(mode ContentCaptureMode) ContentCaptureMode { |
| 65 | + if mode == ContentCaptureModeDefault { |
| 66 | + return ContentCaptureModeFull |
| 67 | + } |
| 68 | + return mode |
| 69 | +} |
| 70 | + |
| 71 | +// stampContentCaptureMetadata sets the content capture mode marker on the generation. |
| 72 | +func stampContentCaptureMetadata(g *Generation, mode ContentCaptureMode) { |
| 73 | + if g.Metadata == nil { |
| 74 | + g.Metadata = map[string]any{} |
| 75 | + } |
| 76 | + g.Metadata[metadataKeyContentCaptureMode] = mode.String() |
| 77 | +} |
| 78 | + |
| 79 | +// isContentStripped reports whether the generation has been through MetadataOnly |
| 80 | +// stripping, based on the stamped metadata marker. |
| 81 | +func isContentStripped(g Generation) bool { |
| 82 | + if g.Metadata == nil { |
| 83 | + return false |
| 84 | + } |
| 85 | + v, _ := g.Metadata[metadataKeyContentCaptureMode].(string) |
| 86 | + return v == contentCaptureModeValueMetaOnly |
| 87 | +} |
| 88 | + |
| 89 | +// stripContent removes sensitive content from a generation while preserving |
| 90 | +// message structure (roles, part kinds), tool names/IDs, usage, timing, and |
| 91 | +// all other metadata fields. errorCategory is the classified error category |
| 92 | +// (e.g. "rate_limit", "timeout") used to replace the raw CallError text. |
| 93 | +func stripContent(g *Generation, errorCategory string) { |
| 94 | + g.SystemPrompt = "" |
| 95 | + g.Artifacts = nil |
| 96 | + |
| 97 | + if g.CallError != "" { |
| 98 | + if errorCategory != "" { |
| 99 | + g.CallError = errorCategory |
| 100 | + } else { |
| 101 | + g.CallError = "sdk_error" |
| 102 | + } |
| 103 | + } |
| 104 | + delete(g.Metadata, "call_error") |
| 105 | + |
| 106 | + for i := range g.Input { |
| 107 | + stripMessageContent(&g.Input[i]) |
| 108 | + } |
| 109 | + for i := range g.Output { |
| 110 | + stripMessageContent(&g.Output[i]) |
| 111 | + } |
| 112 | + for i := range g.Tools { |
| 113 | + g.Tools[i].Description = "" |
| 114 | + g.Tools[i].InputSchema = nil |
| 115 | + } |
| 116 | +} |
| 117 | + |
| 118 | +func stripMessageContent(m *Message) { |
| 119 | + for i := range m.Parts { |
| 120 | + m.Parts[i].Text = "" |
| 121 | + m.Parts[i].Thinking = "" |
| 122 | + if m.Parts[i].ToolCall != nil { |
| 123 | + m.Parts[i].ToolCall.InputJSON = nil |
| 124 | + } |
| 125 | + if m.Parts[i].ToolResult != nil { |
| 126 | + m.Parts[i].ToolResult.Content = "" |
| 127 | + m.Parts[i].ToolResult.ContentJSON = nil |
| 128 | + } |
| 129 | + } |
| 130 | +} |
| 131 | + |
| 132 | +// shouldIncludeToolContent determines whether tool execution content (arguments, |
| 133 | +// results) should be included in span attributes. It resolves the effective mode |
| 134 | +// from the explicit override, context, client default, and legacy IncludeContent. |
| 135 | +func shouldIncludeToolContent(toolMode, ctxMode ContentCaptureMode, ctxSet bool, clientDefault ContentCaptureMode, legacyInclude bool) bool { |
| 136 | + resolved := resolveClientContentCaptureMode(clientDefault) |
| 137 | + if ctxSet { |
| 138 | + resolved = ctxMode |
| 139 | + } |
| 140 | + if toolMode != ContentCaptureModeDefault { |
| 141 | + resolved = toolMode |
| 142 | + } |
| 143 | + if resolved == ContentCaptureModeMetadataOnly { |
| 144 | + return false |
| 145 | + } |
| 146 | + // In Full mode, fall back to legacy IncludeContent behavior. |
| 147 | + return legacyInclude |
| 148 | +} |
| 149 | + |
| 150 | +// String returns the string representation of a ContentCaptureMode. |
| 151 | +func (m ContentCaptureMode) String() string { |
| 152 | + switch m { |
| 153 | + case ContentCaptureModeMetadataOnly: |
| 154 | + return contentCaptureModeValueMetaOnly |
| 155 | + case ContentCaptureModeFull: |
| 156 | + return contentCaptureModeValueFull |
| 157 | + default: |
| 158 | + return "default" |
| 159 | + } |
| 160 | +} |
| 161 | + |
| 162 | +// MarshalText implements encoding.TextMarshaler for ContentCaptureMode. |
| 163 | +func (m ContentCaptureMode) MarshalText() ([]byte, error) { |
| 164 | + return []byte(m.String()), nil |
| 165 | +} |
| 166 | + |
| 167 | +// UnmarshalText implements encoding.TextUnmarshaler for ContentCaptureMode. |
| 168 | +func (m *ContentCaptureMode) UnmarshalText(text []byte) error { |
| 169 | + switch strings.ToLower(string(text)) { |
| 170 | + case contentCaptureModeValueFull: |
| 171 | + *m = ContentCaptureModeFull |
| 172 | + case contentCaptureModeValueMetaOnly: |
| 173 | + *m = ContentCaptureModeMetadataOnly |
| 174 | + case "default", "": |
| 175 | + *m = ContentCaptureModeDefault |
| 176 | + default: |
| 177 | + return fmt.Errorf("unknown content capture mode: %q", string(text)) |
| 178 | + } |
| 179 | + return nil |
| 180 | +} |
0 commit comments