@kontourai/flow-agents 0.1.1

package/scripts/telemetry/lib/session.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# session.sh — Session lifecycle management
+
+session_start() {
+  local agent_name="$1"
+  local session_id start_time pid tty
+  
+  session_id=$(uuidgen 2>/dev/null || echo "s-$(date +%s)-$$")
+  start_time=$(date +%s)
+  pid="${PPID:-$$}"
+  tty=$(ps -o tty= -p "$pid" 2>/dev/null | tr -d ' ' || echo "unknown")
+  
+  local session_file="${TELEMETRY_SESSION_DIR}/${session_id}.session"
+  jq -nc \
+    --arg sid "$session_id" \
+    --arg an "$agent_name" \
+    --argjson st "$start_time" \
+    --argjson pid "$pid" \
+    --arg tty "$tty" \
+    '{
+      session_id: $sid,
+      agent_name: $an,
+      start_time: $st,
+      pid: $pid,
+      tty: $tty
+    }' > "$session_file"
+  
+  echo "$session_id"
+}
+
+session_get() {
+  local latest_session
+  latest_session=$(ls -t "${TELEMETRY_SESSION_DIR}"/*.session 2>/dev/null | head -n1)
+  [[ -f "$latest_session" ]] && jq -r '.session_id' "$latest_session" 2>/dev/null
+}
+
+session_get_tty() {
+  local latest_session
+  latest_session=$(ls -t "${TELEMETRY_SESSION_DIR}"/*.session 2>/dev/null | head -n1)
+  [[ -f "$latest_session" ]] && jq -r '.tty // "unknown"' "$latest_session" 2>/dev/null
+}
+
+session_end() {
+  local session_id
+  session_id=$(session_get)
+  [[ -z "$session_id" ]] && return
+  
+  local session_file="${TELEMETRY_SESSION_DIR}/${session_id}.session"
+  [[ ! -f "$session_file" ]] && return
+  
+  local start_time end_time duration_s
+  start_time=$(jq -r '.start_time' "$session_file" 2>/dev/null)
+  end_time=$(date +%s)
+  duration_s=$((end_time - start_time))
+  
+  jq --argjson et "$end_time" --argjson ds "$duration_s" \
+    '. + {end_time: $et, duration_s: $ds}' \
+    "$session_file" > "${session_file}.tmp" && mv "${session_file}.tmp" "$session_file"
+}
+
+session_cleanup() {
+  find "${TELEMETRY_SESSION_DIR}" -name "*.session" -mtime +1 -delete 2>/dev/null || true
+}

package/scripts/telemetry/lib/transport.sh

@@ -0,0 +1,183 @@
+#!/usr/bin/env bash
+# transport.sh — Dual-channel telemetry transport
+
+source "${TELEMETRY_DIR}/lib/redact.sh"
+
+console_telemetry_endpoint_url() {
+  if [[ -n "${CONSOLE_TELEMETRY_ENDPOINT_URL:-}" ]]; then
+    echo "$CONSOLE_TELEMETRY_ENDPOINT_URL"
+    return
+  fi
+  [[ -z "${CONSOLE_TELEMETRY_URL:-}" ]] && return
+  local base="${CONSOLE_TELEMETRY_URL%/}"
+  case "$base" in
+    */api/telemetry/records) echo "$base" ;;
+    */api/telemetry) echo "${base}/records" ;;
+    *) echo "${base}/api/telemetry/records" ;;
+  esac
+}
+
+console_telemetry_endpoint_allowed() {
+  local endpoint_url="$1"
+  [[ -z "$endpoint_url" || "$endpoint_url" == *$'\n'* || "$endpoint_url" == *$'\r'* || "$endpoint_url" == *'"'* ]] && return 1
+  case "$endpoint_url" in
+    https://*) return 0 ;;
+    http://127.0.0.1|http://127.0.0.1/*|http://127.0.0.1:*|http://localhost|http://localhost/*|http://localhost:*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+console_telemetry_safe_token() {
+  local value="$1"
+  [[ ${#value} -ge 1 && ${#value} -le 4096 && "$value" =~ ^[A-Za-z0-9._~+/=-]+$ ]]
+}
+
+console_telemetry_safe_tenant() {
+  local value="$1"
+  [[ ${#value} -ge 1 && ${#value} -le 128 && "$value" =~ ^[A-Za-z0-9._:-]+$ ]]
+}
+
+console_telemetry_timeout_seconds() {
+  local value="$1" fallback="$2" max="$3"
+  if [[ "$value" =~ ^[0-9]+$ ]] && [[ "$value" -ge 1 && "$value" -le "$max" ]]; then
+    echo "$value"
+  else
+    echo "$fallback"
+  fi
+}
+
+console_telemetry_emit() {
+  local event="$1"
+  local endpoint_url
+  endpoint_url=$(console_telemetry_endpoint_url)
+  [[ -z "$endpoint_url" ]] && return
+  console_telemetry_endpoint_allowed "$endpoint_url" || return
+
+  local processed_event
+  processed_event=$(redact_event "$event" "${CONSOLE_TELEMETRY_REDACT:-${TELEMETRY_CHANNEL_ANALYTICS_REDACT:-}}")
+
+  local curl_config curl_body connect_timeout max_time
+  connect_timeout=$(console_telemetry_timeout_seconds "${CONSOLE_TELEMETRY_CONNECT_TIMEOUT_SECONDS:-2}" 2 30)
+  max_time=$(console_telemetry_timeout_seconds "${CONSOLE_TELEMETRY_MAX_TIME_SECONDS:-5}" 5 60)
+  curl_config=$(mktemp "${TELEMETRY_SESSION_DIR}/console-curl.XXXXXX") || return
+  curl_body=$(mktemp "${TELEMETRY_SESSION_DIR}/console-body.XXXXXX") || {
+    rm -f "$curl_config"
+    return
+  }
+  chmod 600 "$curl_config" "$curl_body" 2>/dev/null
+  printf '%s' "$processed_event" > "$curl_body" || {
+    rm -f "$curl_config" "$curl_body"
+    return
+  }
+
+  {
+    printf 'url = "%s"\n' "$endpoint_url"
+    printf 'request = "POST"\n'
+    printf 'connect-timeout = "%s"\n' "$connect_timeout"
+    printf 'max-time = "%s"\n' "$max_time"
+    printf 'header = "Content-Type: application/json"\n'
+    if [[ -n "${CONSOLE_TELEMETRY_TOKEN:-}" ]] && console_telemetry_safe_token "$CONSOLE_TELEMETRY_TOKEN"; then
+      printf 'header = "Authorization: Bearer %s"\n' "$CONSOLE_TELEMETRY_TOKEN"
+    fi
+    if [[ -n "${CONSOLE_TENANT_ID:-}" ]] && console_telemetry_safe_tenant "$CONSOLE_TENANT_ID"; then
+      printf 'header = "x-console-tenant-id: %s"\n' "$CONSOLE_TENANT_ID"
+    fi
+    printf 'data-binary = "@%s"\n' "$curl_body"
+  } > "$curl_config" || {
+    rm -f "$curl_config" "$curl_body"
+    return
+  }
+
+  (
+    curl -s --proto =https,http --proto-redir =https,http --config "$curl_config" >/dev/null 2>&1
+    rm -f "$curl_config" "$curl_body"
+  ) &
+}
+
+transport_emit() {
+  local event="$1"
+  [[ -z "$event" ]] && return
+  
+  # Process each channel
+  IFS=',' read -ra channels <<< "$TELEMETRY_CHANNELS"
+  for channel in "${channels[@]}"; do
+    channel=$(echo "$channel" | tr -d ' ')
+    [[ -z "$channel" ]] && continue
+    
+    # Get channel config
+    channel_upper=$(echo "$channel" | tr '[:lower:]' '[:upper:]')
+    log_file_var="TELEMETRY_CHANNEL_${channel_upper}_LOG_FILE"
+    redact_var="TELEMETRY_CHANNEL_${channel_upper}_REDACT"
+    endpoint_var="TELEMETRY_CHANNEL_${channel_upper}_ENDPOINT_URL"
+    
+    local log_file="${!log_file_var}"
+    local redact_fields="${!redact_var}"
+    local endpoint_url="${!endpoint_var}"
+    
+    [[ -z "$log_file" ]] && continue
+    
+    # Apply redaction
+    local processed_event
+    processed_event=$(redact_event "$event" "$redact_fields")
+    
+    # Write to log file
+    echo "$processed_event" >> "$log_file" 2>/dev/null
+    
+    # POST to endpoint if configured
+    if [[ -n "$endpoint_url" ]]; then
+      curl -s --connect-timeout 2 --max-time 5 -X POST \
+        -H "Content-Type: application/json" \
+        -d "$processed_event" \
+        "$endpoint_url" >/dev/null 2>&1 &
+    fi
+  done
+
+  console_telemetry_emit "$event"
+}
+
+transport_maybe_rotate() {
+  # Only rotate if no active sessions
+  local active_sessions
+  active_sessions=$(ls "${TELEMETRY_SESSION_DIR}"/*.session 2>/dev/null | wc -l | tr -d ' ')
+  [[ "$active_sessions" -gt 0 ]] && return
+  
+  IFS=',' read -ra channels <<< "$TELEMETRY_CHANNELS"
+  for channel in "${channels[@]}"; do
+    channel=$(echo "$channel" | tr -d ' ')
+    [[ -z "$channel" ]] && continue
+    
+    channel_upper=$(echo "$channel" | tr '[:lower:]' '[:upper:]')
+    log_file_var="TELEMETRY_CHANNEL_${channel_upper}_LOG_FILE"
+    local log_file="${!log_file_var}"
+    [[ ! -f "$log_file" ]] && continue
+    
+    # Check file size - try GNU stat first, then BSD
+    local file_size_bytes=0
+    if stat -c %s "$log_file" >/dev/null 2>&1; then
+      file_size_bytes=$(stat -c %s "$log_file")
+    else
+      file_size_bytes=$(stat -f %z "$log_file" 2>/dev/null || echo "0")
+    fi
+    
+    local file_size_mb=$((file_size_bytes / 1024 / 1024))
+    [[ "$file_size_mb" -lt "$TELEMETRY_MAX_LOG_SIZE_MB" ]] && continue
+    
+    # Rotate logs
+    local base_name="${log_file%.*}"
+    local extension="${log_file##*.}"
+    
+    # Remove oldest log if at limit
+    local oldest_log="${base_name}.$((TELEMETRY_MAX_LOG_FILES - 1)).${extension}"
+    [[ -f "$oldest_log" ]] && rm -f "$oldest_log"
+    
+    # Shift existing logs
+    for ((i = TELEMETRY_MAX_LOG_FILES - 2; i >= 1; i--)); do
+      local current_log="${base_name}.${i}.${extension}"
+      local next_log="${base_name}.$((i + 1)).${extension}"
+      [[ -f "$current_log" ]] && mv "$current_log" "$next_log"
+    done
+    
+    # Move current log to .1
+    mv "$log_file" "${base_name}.1.${extension}"
+  done
+}

package/scripts/telemetry/lib/usage.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# usage.sh — Session usage metric functions
+
+# Resolve model from agent-spec.json
+usage_get_model() {
+  local agent_name="$1"
+  local agents_dir="${HOME}/.kiro/agents"
+  # Try exact match first, then glob for package-prefixed names
+  local spec_file="${agents_dir}/${agent_name}.json"
+  if [[ ! -f "$spec_file" ]]; then
+    spec_file=$(ls "${agents_dir}"/*-"${agent_name}.json" 2>/dev/null | head -n1)
+  fi
+  [[ -n "$spec_file" && -f "$spec_file" ]] && jq -r '.model // "unknown"' "$spec_file" 2>/dev/null && return
+  echo "unknown"
+}
+
+# Count tool invocations for a session
+usage_count_tool_calls() {
+  local session_id="$1" jsonl_path="$2"
+  [[ ! -f "$jsonl_path" ]] && echo 0 && return
+  grep -c "\"session_id\":\"${session_id}\".*\"event_type\":\"tool.invoke\"" "$jsonl_path" 2>/dev/null || echo 0
+}
+
+# Count subagent delegations for a session
+usage_count_delegations() {
+  local session_id="$1" jsonl_path="$2"
+  [[ ! -f "$jsonl_path" ]] && echo 0 && return
+  grep -c "\"session_id\":\"${session_id}\".*\"event_type\":\"agent.delegate\"" "$jsonl_path" 2>/dev/null || echo 0
+}

package/scripts/telemetry/sync-agents.sh

@@ -0,0 +1,173 @@
+#!/usr/bin/env bash
+# sync-agents.sh — Inject telemetry hooks into matching agent configs
+# Usage: bash sync-agents.sh [--dry-run] [--restore]
+set -euo pipefail
+
+TELEMETRY_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${TELEMETRY_DIR}/lib/config.sh"
+
+MODE="apply"
+[[ "${1:-}" == "--dry-run" ]] && MODE="dry-run"
+[[ "${1:-}" == "--restore" ]] && MODE="restore"
+
+AGENTS_DIR="${HOME}/.kiro/agents"
+MARKER="telemetry.sh"
+NOTIFY_MARKER="desktop-notify.sh"
+GOVERNANCE_MARKER="governance-audit.sh"
+HOOKS_DIR="$(cd "${TELEMETRY_DIR}/../hooks" && pwd)"
+
+# Check if agent name matches any pattern in a comma-separated list
+_matches_any() {
+  local name="$1" patterns="$2"
+  local old_ifs="$IFS" pat
+  IFS=','
+  set -f
+  for pat in $patterns; do
+    pat="${pat## }"; pat="${pat%% }"
+    case "$name" in $pat) IFS="$old_ifs"; set +f; return 0 ;; esac
+  done
+  IFS="$old_ifs"
+  set +f
+  return 1
+}
+
+# Build the telemetry hook entry for a given hook type and agent
+_hook_entry() {
+  local hook_type="$1" agent_name="$2"
+  local cmd="bash ${TELEMETRY_DIR}/telemetry.sh ${hook_type} ${agent_name}"
+  case "$hook_type" in
+    preToolUse|postToolUse)
+      jq -nc --arg c "$cmd" '{matcher:"*",command:$c,timeout_ms:10000}'
+      ;;
+    *)
+      jq -nc --arg c "$cmd" '{command:$c,timeout_ms:10000}'
+      ;;
+  esac
+}
+
+# Build desktop notification hook entry (stop only)
+_notify_hook_entry() {
+  local agent_name="$1"
+  local cmd="bash ${HOOKS_DIR}/desktop-notify.sh stop ${agent_name}"
+  jq -nc --arg c "$cmd" '{command:$c,timeout_ms:5000}'
+}
+
+# Build governance hook entry (preToolUse/postToolUse only)
+_governance_hook_entry() {
+  local hook_type="$1" agent_name="$2"
+  local cmd="bash ${HOOKS_DIR}/governance-audit.sh ${hook_type} ${agent_name}"
+  jq -nc --arg c "$cmd" '{matcher:"*",command:$c,timeout_ms:5000}'
+}
+
+# Merge all hooks into an agent's existing hooks
+_merge_hooks() {
+  local agent_file="$1" agent_name="$2"
+  local hook_types=("agentSpawn" "userPromptSubmit" "preToolUse" "postToolUse" "stop")
+
+  # Build the telemetry hooks object
+  local all_hooks='{}'
+  for ht in "${hook_types[@]}"; do
+    local entry
+    entry=$(_hook_entry "$ht" "$agent_name")
+    all_hooks=$(echo "$all_hooks" | jq --arg ht "$ht" --argjson e "$entry" '.[$ht] = (.[$ht] // []) + [$e]')
+  done
+
+  # Add desktop notification hook to stop
+  if [[ "$TELEMETRY_NOTIFICATIONS" == "true" ]]; then
+    local notify_entry
+    notify_entry=$(_notify_hook_entry "$agent_name")
+    all_hooks=$(echo "$all_hooks" | jq --argjson e "$notify_entry" '.stop = (.stop // []) + [$e]')
+  fi
+
+  # Add governance hooks to preToolUse and postToolUse
+  if [[ "$TELEMETRY_GOVERNANCE" == "true" ]]; then
+    for ht in preToolUse postToolUse; do
+      local gov_entry
+      gov_entry=$(_governance_hook_entry "$ht" "$agent_name")
+      all_hooks=$(echo "$all_hooks" | jq --arg ht "$ht" --argjson e "$gov_entry" '.[$ht] = (.[$ht] // []) + [$e]')
+    done
+  fi
+
+  # Read existing agent JSON, merge hooks (preserve non-managed entries)
+  local m1="$MARKER" m2="$NOTIFY_MARKER" m3="$GOVERNANCE_MARKER"
+  jq --argjson th "$all_hooks" --arg m1 "$m1" --arg m2 "$m2" --arg m3 "$m3" '
+    .hooks //= {} |
+    .hooks = reduce ($th | keys[]) as $ht (
+      .hooks;
+      .[$ht] = (
+        ([.[$ht] // [] | .[] | select(
+          (.command | contains($m1) | not) and
+          (.command | contains($m2) | not) and
+          (.command | contains($m3) | not)
+        )])
+        + $th[$ht]
+      )
+    )
+  ' "$agent_file"
+}
+
+# Remove all managed hooks from an agent
+_strip_hooks() {
+  local agent_file="$1"
+  local m1="$MARKER" m2="$NOTIFY_MARKER" m3="$GOVERNANCE_MARKER"
+  jq --arg m1 "$m1" --arg m2 "$m2" --arg m3 "$m3" '
+    if .hooks then
+      .hooks |= with_entries(
+        .value |= map(select(
+          (.command | contains($m1) | not) and
+          (.command | contains($m2) | not) and
+          (.command | contains($m3) | not)
+        ))
+      )
+    else . end
+  ' "$agent_file"
+}
+
+# Main
+echo "Telemetry Hook Sync — mode: ${MODE}"
+echo "Include: ${TELEMETRY_SYNC_INCLUDE}"
+echo "Exclude: ${TELEMETRY_SYNC_EXCLUDE}"
+echo "---"
+
+synced=0
+skipped=0
+
+for agent_file in "${AGENTS_DIR}"/*.json; do
+  [[ -f "$agent_file" ]] || continue
+  fname=$(basename "$agent_file" .json)
+
+  # Apply include/exclude
+  if ! _matches_any "$fname" "$TELEMETRY_SYNC_INCLUDE"; then
+    skipped=$((skipped + 1))
+    continue
+  fi
+  if _matches_any "$fname" "$TELEMETRY_SYNC_EXCLUDE"; then
+    skipped=$((skipped + 1))
+    continue
+  fi
+
+  # Get agent name from JSON or filename
+  agent_name=$(jq -r '.name // ""' "$agent_file" 2>/dev/null)
+  [[ -z "$agent_name" ]] && agent_name="$fname"
+
+  case "$MODE" in
+    dry-run)
+      echo "[DRY-RUN] Would update: ${fname} (agent: ${agent_name})"
+      ;;
+    restore)
+      result=$(_strip_hooks "$agent_file")
+      echo "$result" > "${agent_file}.tmp" && mv "${agent_file}.tmp" "$agent_file"
+      echo "[RESTORED] ${fname} — telemetry hooks removed"
+      synced=$((synced + 1))
+      ;;
+    apply)
+      result=$(_merge_hooks "$agent_file" "$agent_name")
+      echo "$result" > "${agent_file}.tmp" && mv "${agent_file}.tmp" "$agent_file"
+      echo "[SYNCED] ${fname} (agent: ${agent_name})"
+      synced=$((synced + 1))
+      ;;
+  esac
+done
+
+echo "---"
+echo "Done. ${synced} synced, ${skipped} skipped."

package/scripts/telemetry/telemetry.conf

@@ -0,0 +1,23 @@
+enabled=true
+channels=full,analytics
+channel.full.redact=hook.raw_input,turn.prompt_text,tool.input,tool.output
+channel.full.endpoint_url=http://localhost:3141/v1/agent-events
+channel.analytics.redact=tool.input,tool.output,turn.prompt_text,delegation.targets.query,context.cwd,hook.raw_input,hook.last_assistant_message,hook.transcript_path
+# Console mirror is opt-in. Prefer installer telemetry sinks such as
+# local-kontour-console, kontour-hosted-console, or user-hosted-console.
+# The transport derives /api/telemetry/records from console_telemetry_url.
+# console_telemetry_token=
+# console_tenant_id=
+enrich_system=true
+enrich_workspace=true
+enrich_auth=true
+max_log_size_mb=50
+max_log_files=3
+sync_include=*
+sync_exclude=neo-*,Neo,local-gamma-*
+usage_tracking=true
+notifications=true
+notification_profile=standard
+governance=true
+governance_audit_max_size_mb=25
+governance_audit_max_files=5