@robota-sdk/agent-session-analytics 3.0.0-beta.76

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Robota Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,23 @@
+# @robota-sdk/agent-session-analytics
+
+Session-log timing analysis and reporting for the Robota SDK.
+
+Given persisted session records, it computes per-turn timing intervals (LLM wait vs. tool
+execution), aggregates across sessions, and renders text reports. Pure functions — no file I/O, no
+`process.*`, no CLI concerns; callers load records and write output.
+
+## API
+
+| Export                      | Description                                          |
+| --------------------------- | ---------------------------------------------------- |
+| `analyzeSession(record)`    | Compute the timing report for one session record     |
+| `aggregateReports(reports)` | Aggregate multiple single-session reports            |
+| `computeTimingIntervals(h)` | Classify a history array into timing intervals       |
+| `gapMs(from, to)`           | Millisecond gap between two timestamps (string/Date) |
+| `formatSingleSession(r)`    | Render a single-session report as text               |
+| `formatAggregateReport(a)`  | Render an aggregate report as text                   |
+
+Operates on the canonical `IInteractiveSessionRecord` projection and `IHistoryEntry` — owns no
+duplicate record/history types.
+
+See [docs/SPEC.md](./docs/SPEC.md) for the full contract.

package/dist/node/index.cjs

@@ -0,0 +1,3 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});function e(e,t){return new Date(t).getTime()-new Date(e).getTime()}function t(e){return new Date(e).toISOString()}function n(n,r,i,a,o,s){return{kind:n,fromType:r,toType:i,fromTimestamp:t(a),toTimestamp:t(o),durationMs:e(a,o),turnIndex:s}}function r(e){let t=[],r=0,i=0;for(;i<e.length;){let a=e[i];if(!a){i++;continue}if(a.category===`chat`&&a.type===`user`){r++;let o=a.timestamp,s=!1,c=null,l=i+1;for(;l<e.length;){let i=e[l];if(!i){l++;continue}if(i.category===`chat`&&i.type===`user`)break;if(i.category===`event`&&i.type===`tool-start`){s?c!==null&&t.push(n(`llm_between_tools`,`tool-end`,`tool-start`,c,i.timestamp,r)):(t.push(n(`user_to_first_tool`,`user`,`tool-start`,o,i.timestamp,r)),s=!0),c=null,l++;continue}if(i.category===`event`&&i.type===`tool-end`){let a=e[l-1];a&&a.category===`event`&&a.type===`tool-start`&&t.push(n(`tool_exec`,`tool-start`,`tool-end`,a.timestamp,i.timestamp,r)),c=i.timestamp,l++;continue}if(i.category===`event`&&i.type===`tool-summary`){c!==null&&t.push(n(`llm_final_response`,`tool-end`,`tool-summary`,c,i.timestamp,r)),l++;continue}if(i.category===`chat`&&i.type===`assistant`){s?c!==null&&t.push(n(`llm_final_response`,`tool-end`,`assistant`,c,i.timestamp,r)):t.push(n(`user_to_assistant`,`user`,`assistant`,o,i.timestamp,r)),l++;break}l++}i=l}else i++}return t}function i(e){let t=e.filter(e=>e.kind===`user_to_first_tool`||e.kind===`user_to_assistant`||e.kind===`llm_between_tools`||e.kind===`llm_final_response`),n=e.filter(e=>e.kind===`tool_exec`),r=e.filter(e=>e.kind===`user_to_assistant`),i=e=>e.length?Math.round(e.reduce((e,t)=>e+t.durationMs,0)/e.length):0,a=e=>e.length?Math.max(...e.map(e=>e.durationMs)):0;return{llmWaitMs:{avg:i(t),max:a(t),total:t.reduce((e,t)=>e+t.durationMs,0),count:t.length},toolExecMs:{avg:i(n),max:a(n),median:(e=>{if(!e.length)return 0;let t=[...e].sort((e,t)=>e.durationMs-t.durationMs),n=Math.floor(t.length/2);return t.length%2==0?Math.round(((t[n-1]?.durationMs??0)+(t[n]?.durationMs??0))/2):t[n]?.durationMs??0})(n),count:n.length},userToAssistantMs:{avg:i(r),max:a(r),count:r.length}}}function a(e){let t=r(e.history??[]),n=t.filter(e=>e.durationMs>=1e4);return{sessionId:e.id,cwd:e.cwd,createdAt:e.createdAt,totalIntervals:t.length,intervals:t,slowIntervals:n,stats:i(t)}}function o(e){let t=e.flatMap(e=>e.intervals.filter(e=>e.kind===`user_to_first_tool`||e.kind===`user_to_assistant`||e.kind===`llm_between_tools`||e.kind===`llm_final_response`)),n=e.flatMap(e=>e.intervals.filter(e=>e.kind===`tool_exec`)),r=t.length?Math.round(t.reduce((e,t)=>e+t.durationMs,0)/t.length):0,i=n.length?Math.round(n.reduce((e,t)=>e+t.durationMs,0)/n.length):0,a=0,o=``,s=0,c=``;for(let t of e)for(let e of t.intervals)e.durationMs>a&&(a=e.durationMs,o=t.sessionId,s=e.turnIndex,c=e.kind);let l=e.map(e=>e.createdAt).sort();return{sessionCount:e.length,fromDate:l[0]??``,toDate:l[l.length-1]??``,avgLlmResponseMs:r,avgToolExecMs:i,maxSingleDelayMs:a,maxSingleDelaySession:o,maxSingleDelayTurn:s,maxSingleDelayKind:c}}function s(e){return e>=1e3?`${(e/1e3).toFixed(1)}s`:`${e}ms`}function c(e){return new Date(e).toLocaleString(`sv-SE`,{timeZoneName:`short`}).slice(0,16)}function l(e){return{user_to_first_tool:`user → tool-start`,user_to_assistant:`user → assistant`,tool_exec:`tool-start → tool-end`,llm_between_tools:`tool-end → tool-start`,llm_final_response:`tool-end → assistant/summary`}[e.kind]??e.kind}function u(e){let{stats:t}=e,n=t.llmWaitMs.total+t.toolExecMs.avg*t.toolExecMs.count;if(n===0)return`Verdict: No timing data available.`;let r=Math.round(t.llmWaitMs.total/n*100);return`Verdict: LLM API wait ${r}% | Code processing ${100-r}%`}function d(e){let t=[],{stats:n}=e;if(t.push(`Session: ${e.sessionId}`),t.push(`Created: ${c(e.createdAt)} | cwd: ${e.cwd}`),t.push(``),t.push(`Timing Summary:`),n.llmWaitMs.count>0&&t.push(`  LLM API wait        ${s(n.llmWaitMs.avg).padStart(8)} avg  |  ${s(n.llmWaitMs.max).padStart(8)} max`),n.toolExecMs.count>0&&t.push(`  Tool execution      ${s(n.toolExecMs.avg).padStart(8)} avg  |  ${s(n.toolExecMs.median).padStart(8)} median`),n.userToAssistantMs.count>0&&t.push(`  user → assistant    ${s(n.userToAssistantMs.avg).padStart(8)} avg`),n.llmWaitMs.count===0&&n.toolExecMs.count===0&&t.push(`  (no intervals computed — session may have no history)`),e.slowIntervals.length>0){t.push(``),t.push(`Slow intervals (>10s):`);for(let n of e.slowIntervals)t.push(`  turn ${n.turnIndex}  ${l(n).padEnd(32)} ${s(n.durationMs).padStart(8)}`)}return t.push(``),t.push(u(e)),t.join(`
+`)}function f(e){let t=[];return t.push(`Analyzed ${e.sessionCount} sessions (${c(e.fromDate)} ~ ${c(e.toDate)})`),t.push(`  Avg LLM response:   ${s(e.avgLlmResponseMs)}`),t.push(`  Avg tool exec:      ${s(e.avgToolExecMs)}`),e.maxSingleDelayMs>0&&t.push(`  Max single delay:   ${s(e.maxSingleDelayMs)} (${e.maxSingleDelaySession}, turn ${e.maxSingleDelayTurn}, ${e.maxSingleDelayKind})`),t.join(`
+`)}exports.aggregateReports=o,exports.analyzeSession=a,exports.computeTimingIntervals=r,exports.formatAggregateReport=f,exports.formatSingleSession=d,exports.gapMs=e;

package/dist/node/index.d.ts

@@ -0,0 +1,77 @@
+import { IInteractiveSessionRecord } from "@robota-sdk/agent-interface-transport";
+import { IHistoryEntry } from "@robota-sdk/agent-core";
+
+//#region src/types.d.ts
+/** Minimal session-record projection the analyzer reads — SSOT-derived, not a duplicate. */
+type ISessionAnalysisInput = Pick<IInteractiveSessionRecord, 'id' | 'cwd' | 'createdAt' | 'history'>;
+type TIntervalKind = 'user_to_first_tool' | 'user_to_assistant' | 'tool_exec' | 'llm_between_tools' | 'llm_final_response';
+interface ITimingInterval {
+  kind: TIntervalKind;
+  fromType: string;
+  toType: string;
+  fromTimestamp: string;
+  toTimestamp: string;
+  durationMs: number;
+  turnIndex: number;
+}
+interface ITimingStats {
+  llmWaitMs: {
+    avg: number;
+    max: number;
+    total: number;
+    count: number;
+  };
+  toolExecMs: {
+    avg: number;
+    max: number;
+    median: number;
+    count: number;
+  };
+  userToAssistantMs: {
+    avg: number;
+    max: number;
+    count: number;
+  };
+}
+interface ISessionTimingReport {
+  sessionId: string;
+  cwd: string;
+  createdAt: string;
+  totalIntervals: number;
+  intervals: ITimingInterval[];
+  slowIntervals: ITimingInterval[];
+  stats: ITimingStats;
+}
+interface IAggregateReport {
+  sessionCount: number;
+  fromDate: string;
+  toDate: string;
+  avgLlmResponseMs: number;
+  avgToolExecMs: number;
+  maxSingleDelayMs: number;
+  maxSingleDelaySession: string;
+  maxSingleDelayTurn: number;
+  maxSingleDelayKind: string;
+}
+//#endregion
+//#region src/analyze.d.ts
+/** Gap in milliseconds between two timestamps (ISO string or Date). */
+declare function gapMs(from: string | Date, to: string | Date): number;
+/**
+ * Compute timing intervals from a history entry array.
+ *
+ * Strategy: scan the timeline turn by turn. A "turn" starts with a user message. After user, we
+ * expect zero or more tool-start → tool-end cycles, optionally a tool-summary, then an assistant
+ * message.
+ */
+declare function computeTimingIntervals(history: readonly IHistoryEntry[]): ITimingInterval[];
+/** Compute the timing report for a single session record. */
+declare function analyzeSession(record: ISessionAnalysisInput): ISessionTimingReport;
+/** Aggregate multiple single-session reports into a fleet-level summary. */
+declare function aggregateReports(reports: readonly ISessionTimingReport[]): IAggregateReport;
+//#endregion
+//#region src/report.d.ts
+declare function formatSingleSession(report: ISessionTimingReport): string;
+declare function formatAggregateReport(aggregate: IAggregateReport): string;
+//#endregion
+export { type IAggregateReport, type ISessionAnalysisInput, type ISessionTimingReport, type ITimingInterval, type ITimingStats, type TIntervalKind, aggregateReports, analyzeSession, computeTimingIntervals, formatAggregateReport, formatSingleSession, gapMs };

package/dist/node/index.js

@@ -0,0 +1,3 @@
+function e(e,t){return new Date(t).getTime()-new Date(e).getTime()}function t(e){return new Date(e).toISOString()}function n(n,r,i,a,o,s){return{kind:n,fromType:r,toType:i,fromTimestamp:t(a),toTimestamp:t(o),durationMs:e(a,o),turnIndex:s}}function r(e){let t=[],r=0,i=0;for(;i<e.length;){let a=e[i];if(!a){i++;continue}if(a.category===`chat`&&a.type===`user`){r++;let o=a.timestamp,s=!1,c=null,l=i+1;for(;l<e.length;){let i=e[l];if(!i){l++;continue}if(i.category===`chat`&&i.type===`user`)break;if(i.category===`event`&&i.type===`tool-start`){s?c!==null&&t.push(n(`llm_between_tools`,`tool-end`,`tool-start`,c,i.timestamp,r)):(t.push(n(`user_to_first_tool`,`user`,`tool-start`,o,i.timestamp,r)),s=!0),c=null,l++;continue}if(i.category===`event`&&i.type===`tool-end`){let a=e[l-1];a&&a.category===`event`&&a.type===`tool-start`&&t.push(n(`tool_exec`,`tool-start`,`tool-end`,a.timestamp,i.timestamp,r)),c=i.timestamp,l++;continue}if(i.category===`event`&&i.type===`tool-summary`){c!==null&&t.push(n(`llm_final_response`,`tool-end`,`tool-summary`,c,i.timestamp,r)),l++;continue}if(i.category===`chat`&&i.type===`assistant`){s?c!==null&&t.push(n(`llm_final_response`,`tool-end`,`assistant`,c,i.timestamp,r)):t.push(n(`user_to_assistant`,`user`,`assistant`,o,i.timestamp,r)),l++;break}l++}i=l}else i++}return t}function i(e){let t=e.filter(e=>e.kind===`user_to_first_tool`||e.kind===`user_to_assistant`||e.kind===`llm_between_tools`||e.kind===`llm_final_response`),n=e.filter(e=>e.kind===`tool_exec`),r=e.filter(e=>e.kind===`user_to_assistant`),i=e=>e.length?Math.round(e.reduce((e,t)=>e+t.durationMs,0)/e.length):0,a=e=>e.length?Math.max(...e.map(e=>e.durationMs)):0;return{llmWaitMs:{avg:i(t),max:a(t),total:t.reduce((e,t)=>e+t.durationMs,0),count:t.length},toolExecMs:{avg:i(n),max:a(n),median:(e=>{if(!e.length)return 0;let t=[...e].sort((e,t)=>e.durationMs-t.durationMs),n=Math.floor(t.length/2);return t.length%2==0?Math.round(((t[n-1]?.durationMs??0)+(t[n]?.durationMs??0))/2):t[n]?.durationMs??0})(n),count:n.length},userToAssistantMs:{avg:i(r),max:a(r),count:r.length}}}function a(e){let t=r(e.history??[]),n=t.filter(e=>e.durationMs>=1e4);return{sessionId:e.id,cwd:e.cwd,createdAt:e.createdAt,totalIntervals:t.length,intervals:t,slowIntervals:n,stats:i(t)}}function o(e){let t=e.flatMap(e=>e.intervals.filter(e=>e.kind===`user_to_first_tool`||e.kind===`user_to_assistant`||e.kind===`llm_between_tools`||e.kind===`llm_final_response`)),n=e.flatMap(e=>e.intervals.filter(e=>e.kind===`tool_exec`)),r=t.length?Math.round(t.reduce((e,t)=>e+t.durationMs,0)/t.length):0,i=n.length?Math.round(n.reduce((e,t)=>e+t.durationMs,0)/n.length):0,a=0,o=``,s=0,c=``;for(let t of e)for(let e of t.intervals)e.durationMs>a&&(a=e.durationMs,o=t.sessionId,s=e.turnIndex,c=e.kind);let l=e.map(e=>e.createdAt).sort();return{sessionCount:e.length,fromDate:l[0]??``,toDate:l[l.length-1]??``,avgLlmResponseMs:r,avgToolExecMs:i,maxSingleDelayMs:a,maxSingleDelaySession:o,maxSingleDelayTurn:s,maxSingleDelayKind:c}}function s(e){return e>=1e3?`${(e/1e3).toFixed(1)}s`:`${e}ms`}function c(e){return new Date(e).toLocaleString(`sv-SE`,{timeZoneName:`short`}).slice(0,16)}function l(e){return{user_to_first_tool:`user → tool-start`,user_to_assistant:`user → assistant`,tool_exec:`tool-start → tool-end`,llm_between_tools:`tool-end → tool-start`,llm_final_response:`tool-end → assistant/summary`}[e.kind]??e.kind}function u(e){let{stats:t}=e,n=t.llmWaitMs.total+t.toolExecMs.avg*t.toolExecMs.count;if(n===0)return`Verdict: No timing data available.`;let r=Math.round(t.llmWaitMs.total/n*100);return`Verdict: LLM API wait ${r}% | Code processing ${100-r}%`}function d(e){let t=[],{stats:n}=e;if(t.push(`Session: ${e.sessionId}`),t.push(`Created: ${c(e.createdAt)} | cwd: ${e.cwd}`),t.push(``),t.push(`Timing Summary:`),n.llmWaitMs.count>0&&t.push(`  LLM API wait        ${s(n.llmWaitMs.avg).padStart(8)} avg  |  ${s(n.llmWaitMs.max).padStart(8)} max`),n.toolExecMs.count>0&&t.push(`  Tool execution      ${s(n.toolExecMs.avg).padStart(8)} avg  |  ${s(n.toolExecMs.median).padStart(8)} median`),n.userToAssistantMs.count>0&&t.push(`  user → assistant    ${s(n.userToAssistantMs.avg).padStart(8)} avg`),n.llmWaitMs.count===0&&n.toolExecMs.count===0&&t.push(`  (no intervals computed — session may have no history)`),e.slowIntervals.length>0){t.push(``),t.push(`Slow intervals (>10s):`);for(let n of e.slowIntervals)t.push(`  turn ${n.turnIndex}  ${l(n).padEnd(32)} ${s(n.durationMs).padStart(8)}`)}return t.push(``),t.push(u(e)),t.join(`
+`)}function f(e){let t=[];return t.push(`Analyzed ${e.sessionCount} sessions (${c(e.fromDate)} ~ ${c(e.toDate)})`),t.push(`  Avg LLM response:   ${s(e.avgLlmResponseMs)}`),t.push(`  Avg tool exec:      ${s(e.avgToolExecMs)}`),e.maxSingleDelayMs>0&&t.push(`  Max single delay:   ${s(e.maxSingleDelayMs)} (${e.maxSingleDelaySession}, turn ${e.maxSingleDelayTurn}, ${e.maxSingleDelayKind})`),t.join(`
+`)}export{o as aggregateReports,a as analyzeSession,r as computeTimingIntervals,f as formatAggregateReport,d as formatSingleSession,e as gapMs};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@robota-sdk/agent-session-analytics",
+  "version": "3.0.0-beta.76",
+  "description": "Session-log timing analysis and reporting for the Robota SDK (analyzeSession, aggregateReports, report formatters)",
+  "type": "module",
+  "main": "dist/node/index.js",
+  "types": "dist/node/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/node/index.d.ts",
+      "source": "./src/index.ts",
+      "node": {
+        "import": "./dist/node/index.js",
+        "require": "./dist/node/index.cjs"
+      },
+      "default": {
+        "import": "./dist/node/index.js",
+        "require": "./dist/node/index.cjs"
+      }
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/woojubb/robota.git"
+  },
+  "homepage": "https://robota.io/",
+  "bugs": {
+    "url": "https://github.com/woojubb/robota/issues"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@robota-sdk/agent-core": "3.0.0-beta.76",
+    "@robota-sdk/agent-interface-transport": "3.0.0-beta.76"
+  },
+  "devDependencies": {
+    "rimraf": "^5.0.10",
+    "tsdown": "^0.22.2",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.6"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "build:js": "tsdown --no-dts",
+    "build:types": "tsdown --dts",
+    "test": "vitest run --passWithNoTests",
+    "test:coverage": "vitest run --coverage --passWithNoTests",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/ --ext .ts",
+    "clean": "rimraf dist"
+  }
+}