timing

Documentation

Overview

Package timing mide la duración REAL de una conversación: el "tiempo activo" (trabajo efectivo) frente al span de calendario. La clave es que un agente no estima en unidades de equipo humano sin calibrar; con esto puede anclar sus estimaciones en cuánto tardó de verdad un trabajo análogo.

Modelo role-aware: se recorren los mensajes en orden cronológico y cada hueco entre dos se clasifica por quién habló último —si el agente terminó y esperaba al humano (assistant→user) el hueco se topea corto (te fuiste); cualquier otro hueco es trabajo del agente y se topea generoso. Así un rato largo en que el agente está ocupado cuenta como activo (sus tool calls/results lo pueblan), y solo las ausencias reales del usuario se descuentan.

Index

• Constants
• func Ago(ts, now int64) string
• func Format(d time.Duration) string
• type Event
• type Span
  • func Compute(evs []Event) Span
  • func SpanForChats(store db.Store, chatIDs []string) (Span, error)
  • func (s Span) Line(now int64) string
  • func (s Span) Merge(o Span) Span

Constants

const (
	// WorkCap: máximo que aporta un hueco de trabajo (agente ocupado), por si fue
	// una sola generación larga sin pasos intermedios timestampeados.
	WorkCap = 30 * time.Minute
	// WaitCap: máximo que aporta un hueco de espera (agente terminó, espera al
	// humano); más que esto = el usuario se fue.
	WaitCap = 5 * time.Minute
	// SessionGap: hueco a partir del cual contamos una "sentada" nueva (volviste
	// más tarde). Independiente de los caps de tiempo activo.
	SessionGap = 45 * time.Minute
)

Topes por hueco (cap del modelo role-aware). Ajustables.

Functions

func Ago

func Ago(ts, now int64) string

Ago da una distancia temporal humana respecto a `now` (unix): "hace 3d".

func Format

func Format(d time.Duration) string

Format imprime una duración de forma compacta: "45m", "2h10m", "3d 4h".

Types

type Event

type Event struct {
	Role string
	Ts   int64 // unix seconds
}

Event es un mensaje reducido a (rol, timestamp) para medir duración.

type Span

type Span struct {
	Active   time.Duration // tiempo activo (trabajo real), role-aware
	Wall     time.Duration // span de calendario (último - primer mensaje)
	Sessions int           // nº de sentadas (huecos que superan su cap, +1)
	Msgs     int           // nº de mensajes con timestamp válido
	First    int64         // unix del primer mensaje
	Last     int64         // unix del último mensaje
}

Span resume la duración de una conversación (o agregado de varias).

func Compute

func Compute(evs []Event) Span

Compute calcula el Span de una secuencia de eventos en orden cronológico (orden de Seq). Filtra timestamps inválidos (<=0) preservando el orden.

func SpanForChats

func SpanForChats(store db.Store, chatIDs []string) (Span, error)

SpanForChats computa el Span agregado de uno o varios chats leyendo sus timestamps del store. Reusado por `nem timeline`, `nem stats`, el tool MCP nem_duration y el `index` (para poblar la duración en los nodos).

func (Span) Line

func (s Span) Line(now int64) string

Line es un resumen de una línea de la Span (para timeline/stats/nem_duration).

func (Span) Merge

func (s Span) Merge(o Span) Span

Merge agrega dos spans (p.ej. los chats de un proyecto): el tiempo activo y las sesiones suman; el span de calendario abarca de la primera a la última.