builder

Documentation

Overview

Package builder provides shared helpers for converting provider hook payloads into broker.RawEvent values.

Hash helpers return an empty string when storage or serialization fails. Callers still emit the event without the missing blob reference.

Index

• func BaseRawEvent(in BaseInput) broker.RawEvent
• func ComputeEventID(sourceKey string, event *hooks.Event) string
• func PutAndHash(ctx context.Context, bs api.BlobPutter, payload []byte) string
• func Redact(s string) string
• func StorePromptPayload(ctx context.Context, bs api.BlobPutter, prompt string) string
• func StoreWrappedHookProvenance(ctx context.Context, bs api.BlobPutter, ...) string
• func SynthesizeAssistantBlob(ctx context.Context, bs api.BlobPutter, toolName string, ...) string
• func TruncateClean(s string, max int) string
• func TruncateWithEllipsis(s string, max int) string
• type BaseInput

Functions

func BaseRawEvent

func BaseRawEvent(in BaseInput) broker.RawEvent

BaseRawEvent constructs the fields shared by provider events. The caller fills in fields specific to the event type.

func ComputeEventID

func ComputeEventID(sourceKey string, event *hooks.Event) string

ComputeEventID returns a deterministic SHA-256 hex digest derived from the source key and stable hook context. Using ToolUseID (or TurnID when ToolUseID is empty) as the stable key means replayed hook deliveries for the same step produce the same event ID, and downstream INSERT OR IGNORE semantics suppress duplicates without the broker needing a separate deduplication pass.

The format of the hashed input is:

sourceKey + ":hook:" + HookPhase + ":" + ToolName + ":" + StableKey

where StableKey is ToolUseID if non-empty, otherwise TurnID.

func PutAndHash

func PutAndHash(ctx context.Context, bs api.BlobPutter, payload []byte) string

PutAndHash writes the payload to the blob store and returns its content hash. Returns an empty string when the blob store is nil or the Put call fails; the caller continues to assemble the event with the hash field left empty, matching the direct-emit silent-degradation contract.

func Redact

func Redact(s string) string

Redact wraps redact.String with the error policy every direct-emit helper already uses: on redaction failure, return the input string unchanged rather than surfacing the error. Returns the input untouched when it is empty so call sites do not have to guard individually.

func StorePromptPayload

func StorePromptPayload(ctx context.Context, bs api.BlobPutter, prompt string) string

StorePromptPayload persists the raw bytes of a user or subagent prompt and returns the content hash. Thin wrapper over PutAndHash named for intent so call sites read naturally.

func StoreWrappedHookProvenance

func StoreWrappedHookProvenance(ctx context.Context, bs api.BlobPutter, toolInput, toolResponse json.RawMessage) string

StoreWrappedHookProvenance stores a tool input payload under the shared envelope used by file-changing providers:

{ "tool_input": <toolInput>, "tool_response": <toolResponse> }

The tool_response field is omitted when toolResponse is empty, so hooks that do not carry a response (for example pre-tool-use) produce a smaller, wrapper-only blob.

File-edit provenance uses this envelope so hosted diff readers can parse one stable shape across providers. Provider-specific blobs may still use local helpers when their schema is not file-edit data.

Returns an empty string on marshal or blob-store failure.

func SynthesizeAssistantBlob

func SynthesizeAssistantBlob(ctx context.Context, bs api.BlobPutter, toolName string, inputJSON json.RawMessage) string

SynthesizeAssistantBlob marshals the canonical assistant payload shape consumed by the attribution scorer and stores it in the blob store. The shape is:

{
  "type": "assistant",
  "message": {
    "content": [
      { "type": "tool_use", "name": <toolName>, "input": <inputJSON> }
    ]
  }
}

inputJSON must already be normalized to the shape the scorer expects for the given tool. Providers whose hook payloads use different field names convert them to the canonical shape before calling this helper.

Returns an empty string on marshal or blob-store failure.

func TruncateClean

func TruncateClean(s string, max int) string

TruncateClean normalizes whitespace and truncates without an ellipsis. Used by the Copilot prompt and subagent-prompt paths. The steps are:

1. Trim leading and trailing whitespace.
2. Replace embedded newlines with single spaces.
3. Strip carriage returns entirely (no substitution, which means "a\rb" becomes "ab" rather than "a b").
4. Truncate to at most max bytes, with no ellipsis appended.

The asymmetry between newline handling (substituted) and carriage return handling (dropped) is preserved from the original agentcopilot.Truncate implementation and is asserted by the Copilot direct-emit tests.

func TruncateWithEllipsis

func TruncateWithEllipsis(s string, max int) string

TruncateWithEllipsis returns s unchanged when its length is at most max; otherwise it returns the first max bytes followed by "...". Used by the Claude, Cursor, Gemini, and Kiro CLI prompt paths. No whitespace normalization is applied; the input appears in the summary exactly as it was received.

Types

type BaseInput

type BaseInput struct {
	// Event is the source hook event. Required.
	Event *hooks.Event

	// SourceKey identifies the source used for deterministic event IDs.
	SourceKey string

	// Provider is the canonical agent provider name.
	Provider string

	// ProviderSessionID is the provider's opaque session identifier.
	ProviderSessionID string

	// ParentSessionID links a child session to its parent when available.
	ParentSessionID string

	// SessionMetaJSON is a pre-serialized provider metadata object.
	SessionMetaJSON string

	// SourceProjectPath is the repository root associated with the event.
	SourceProjectPath string
}

BaseInput contains provider-specific fields for a broker.RawEvent.