usage

package

v1.0.65 Latest Latest Go to latest Published: Oct 20, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation ¶

Overview ¶

Package usage records the SHAPE of MCP tool calls (which product/tool, which argument keys, and a redacted sample of ID/enum-like values) so that the shortcut layer can later mine high-frequency patterns and suggest distilling them into custom shortcuts (see docs/shortcut-p2-design.md).

Privacy first: free-text / content / credential values are NEVER recorded — only argument KEYS plus short, whitespace-free ID/enum-like values. Tracking is OFF by default (opt-in): enable it with DWS_USAGE_TRACKING=1 (or true/on/yes). When enabled it announces itself once on first use.

Index ¶

func Append(product, tool string, args map[string]any, ok, dryRun bool)
func Enabled() bool
func LogPath() string
func NewShortcutCommand() *cobra.Command
func Purge() error
type Group
- func Aggregate(recs []Record) []Group
type Record
- func Read() ([]Record, error)

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

func Append ¶

func Append(product, tool string, args map[string]any, ok, dryRun bool)

Append records one tool call. It never blocks or fails the caller: any error (disabled, unwritable dir, marshal issue) is swallowed. dryRun calls are skipped — they are not real usage.

func Enabled ¶

func Enabled() bool

Enabled reports whether usage tracking is active. Default OFF (opt-in): local telemetry — even shape-only — should not be on without the user's explicit consent. Enable by setting DWS_USAGE_TRACKING to 1/true/on/yes (case-insensitive).

func LogPath ¶

func LogPath() string

LogPath returns the absolute path of the usage log.

func NewShortcutCommand ¶

func NewShortcutCommand() *cobra.Command

NewShortcutCommand builds the `dws shortcut` management command tree:

dws shortcut list [--service x]   # list built-in shortcuts
dws shortcut stats [--top N]      # high-frequency usage aggregation
dws shortcut stats --purge        # clear the usage log

func Purge ¶

func Purge() error

Purge deletes the usage log. Returns nil when there is nothing to delete.

Types ¶

type Group ¶

type Group struct {
	Product  string   `json:"product"`
	Tool     string   `json:"tool"`
	ArgKeys  []string `json:"arg_keys"`
	Count    int      `json:"count"`
	OKCount  int      `json:"ok_count"`
	LastSeen string   `json:"last_seen"`
	// FixedArgs are argument keys whose sampled value was identical across every
	// occurrence — strong candidates to bake into a custom shortcut as constants.
	FixedArgs map[string]string `json:"fixed_args,omitempty"`
}

Group aggregates records that share the same (product, tool, arg_keys) shape — the unit a custom shortcut would capture.

func Aggregate ¶

func Aggregate(recs []Record) []Group

Aggregate groups records and computes per-group counts and fixed-value args, sorted by descending count.

type Record ¶

type Record struct {
	TS         string            `json:"ts"`
	Product    string            `json:"product"`
	Tool       string            `json:"tool"`
	ArgKeys    []string          `json:"arg_keys,omitempty"`
	SampleArgs map[string]string `json:"sample_args,omitempty"`
	OK         bool              `json:"ok"`
}

Record is one line in usage.jsonl. It captures the call shape, not its data.

func Read ¶

func Read() ([]Record, error)

Read loads all usage records from the log. Returns an empty slice when the log does not exist yet. Malformed lines are skipped.

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL