@hassangameryt/freeflow 0.7.0 → 0.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (136) hide show
  1. package/.claude-plugin/marketplace.json +1 -1
  2. package/.claude-plugin/plugin.json +2 -1
  3. package/.codex-plugin/plugin.json +2 -2
  4. package/.cursor-plugin/plugin.json +25 -0
  5. package/README.md +57 -26
  6. package/capabilities/cognitive-routing/SKILL.md +94 -311
  7. package/com.github.copilot/hooks/hooks.json +11 -0
  8. package/command-surface.json +7 -1
  9. package/gemini-extension.json +5 -0
  10. package/hooks/adapters/claude-session-start.mjs +16 -0
  11. package/hooks/adapters/codex-session-start.mjs +16 -0
  12. package/hooks/adapters/copilot-session-start.mjs +13 -0
  13. package/hooks/adapters/cursor-session-start.mjs +13 -0
  14. package/hooks/adapters/gemini-session-start.mjs +15 -0
  15. package/hooks/claude/hooks.json +18 -0
  16. package/hooks/codex/hooks.json +18 -0
  17. package/hooks/cursor/hooks.json +9 -0
  18. package/hooks/freeflow-runtime-context.mjs +3 -215
  19. package/hooks/hooks.json +4 -5
  20. package/hooks/shared/runtime-context.mjs +210 -0
  21. package/hooks/tests/check-host-adapters.test.mjs +82 -0
  22. package/hooks/tests/check-runtime-context-hook.sh +34 -3
  23. package/package.json +20 -6
  24. package/pi-extension/dist/cognitive-routing-v2/budget.js +42 -0
  25. package/pi-extension/dist/cognitive-routing-v2/config.js +120 -0
  26. package/pi-extension/dist/cognitive-routing-v2/projection.js +321 -0
  27. package/pi-extension/dist/cognitive-routing-v2/render.js +231 -0
  28. package/pi-extension/dist/cognitive-routing-v2/runtime.js +1585 -0
  29. package/pi-extension/dist/cognitive-routing-v2/schemas.js +107 -0
  30. package/pi-extension/dist/cognitive-routing-v2/state.js +612 -0
  31. package/pi-extension/dist/cognitive-routing-v2/tools.js +91 -0
  32. package/pi-extension/dist/cognitive-routing-v2/types.js +44 -0
  33. package/pi-extension/dist/freeflow-context/tool.js +5 -0
  34. package/pi-extension/dist/index.js +279 -624
  35. package/pi-extension/dist/runtime/runtime-context.js +63 -13
  36. package/pi-extension/dist/session-sources/events.js +195 -0
  37. package/pi-extension/dist/session-sources/read-only-session.js +148 -0
  38. package/pi-extension/dist/session-sources/sources.js +233 -0
  39. package/pi-extension/dist/settings/settings-ui.js +44 -117
  40. package/pi-extension/src/cognitive-routing-v2/budget.ts +42 -0
  41. package/pi-extension/src/cognitive-routing-v2/config.ts +143 -0
  42. package/pi-extension/src/cognitive-routing-v2/projection.ts +365 -0
  43. package/pi-extension/src/cognitive-routing-v2/render.ts +256 -0
  44. package/pi-extension/src/cognitive-routing-v2/runtime.ts +1634 -0
  45. package/pi-extension/src/cognitive-routing-v2/schemas.ts +109 -0
  46. package/pi-extension/src/cognitive-routing-v2/state.ts +622 -0
  47. package/pi-extension/src/cognitive-routing-v2/tools.ts +93 -0
  48. package/pi-extension/src/cognitive-routing-v2/types.ts +222 -0
  49. package/pi-extension/src/freeflow-context/tool.ts +5 -0
  50. package/pi-extension/src/index.ts +285 -674
  51. package/pi-extension/src/runtime/runtime-context.ts +75 -14
  52. package/pi-extension/src/session-sources/events.ts +208 -0
  53. package/pi-extension/src/session-sources/read-only-session.ts +170 -0
  54. package/pi-extension/src/session-sources/sources.ts +263 -0
  55. package/pi-extension/src/settings/settings-ui.ts +54 -131
  56. package/pi-extension/tests/cognitive-routing-v2/communication.test.js +484 -0
  57. package/pi-extension/tests/cognitive-routing-v2/compaction-input.test.js +183 -0
  58. package/pi-extension/tests/cognitive-routing-v2/native.test.js +441 -0
  59. package/pi-extension/tests/cognitive-routing-v2/performance.test.js +87 -0
  60. package/pi-extension/tests/cognitive-routing-v2/persistence.test.js +245 -0
  61. package/pi-extension/tests/cognitive-routing-v2/projection.test.js +241 -0
  62. package/pi-extension/tests/cognitive-routing-v2/recovery.test.js +236 -0
  63. package/pi-extension/tests/cognitive-routing-v2/render.test.js +230 -0
  64. package/pi-extension/tests/cognitive-routing-v2/runtime.test.js +153 -0
  65. package/pi-extension/tests/cognitive-routing-v2/stabilization.test.js +521 -0
  66. package/pi-extension/tests/cognitive-routing-v2/state.test.js +275 -0
  67. package/pi-extension/tests/context-virtualization/extension.test.js +16 -0
  68. package/pi-extension/tests/fixtures/routing-native.js +188 -0
  69. package/pi-extension/tests/integration/mode-free-core.test.js +3 -2
  70. package/pi-extension/tests/integration/pi-extension.test.js +154 -37
  71. package/pi-extension/tests/integration/prompt-architecture.test.js +87 -6
  72. package/pi-extension/tests/integration/unaffected-regressions.test.js +77 -10
  73. package/plugin.json +33 -0
  74. package/runtime/prompts/cognitive-routing.md +4 -5
  75. package/runtime/prompts/core.md +51 -45
  76. package/runtime/prompts/interaction-contract.md +5 -5
  77. package/skills/action-selection/SKILL.md +57 -97
  78. package/skills/design-for-depth/SKILL.md +58 -193
  79. package/skills/design-for-depth/references/implementation-decisions.md +76 -0
  80. package/skills/diagnose-failure/SKILL.md +64 -196
  81. package/skills/discuss/SKILL.md +64 -123
  82. package/skills/discuss/references/discussion-continuity.md +7 -3
  83. package/skills/execute-work/SKILL.md +69 -88
  84. package/skills/execute-work/references/execute-work-edges.md +9 -3
  85. package/skills/handoff/SKILL.md +44 -54
  86. package/skills/handoff/references/handoff-templates.md +15 -6
  87. package/skills/review-artifact/SKILL.md +80 -127
  88. package/skills/review-artifact/references/independent-artifact-reviewer-contract.md +1 -1
  89. package/skills/review-work/SKILL.md +65 -115
  90. package/skills/review-work/references/independent-work-reviewer-contract.md +1 -1
  91. package/skills/simplify-code/SKILL.md +47 -100
  92. package/skills/track-work/SKILL.md +128 -119
  93. package/skills/track-work/references/working-record-format.md +14 -2
  94. package/skills/verify-work/SKILL.md +58 -62
  95. package/skills/verify-work/references/integration-evidence.md +4 -2
  96. package/skills/verify-work/references/test-design.md +89 -0
  97. package/skills/workflow/SKILL.md +73 -119
  98. package/skills/write-plan/SKILL.md +46 -77
  99. package/skills/write-plan/references/plan-shapes.md +5 -5
  100. package/skills/write-spec/SKILL.md +51 -63
  101. package/skills/write-spec/references/artifact-standards.md +2 -2
  102. package/skills/write-spec/references/decision-records.md +3 -2
  103. package/skills/write-spec/references/spec-shapes.md +15 -0
  104. package/pi-extension/dist/cognitive-routing/commands.js +0 -96
  105. package/pi-extension/dist/cognitive-routing/config.js +0 -232
  106. package/pi-extension/dist/cognitive-routing/controller.js +0 -1292
  107. package/pi-extension/dist/cognitive-routing/history.js +0 -451
  108. package/pi-extension/dist/cognitive-routing/host.js +0 -188
  109. package/pi-extension/dist/cognitive-routing/pi-routing-session.js +0 -414
  110. package/pi-extension/dist/cognitive-routing/pi-session-control.js +0 -320
  111. package/pi-extension/dist/cognitive-routing/runtime.js +0 -43
  112. package/pi-extension/dist/cognitive-routing/tool.js +0 -212
  113. package/pi-extension/dist/cognitive-routing/types.js +0 -6
  114. package/pi-extension/src/cognitive-routing/commands.ts +0 -129
  115. package/pi-extension/src/cognitive-routing/config.ts +0 -303
  116. package/pi-extension/src/cognitive-routing/controller.ts +0 -1628
  117. package/pi-extension/src/cognitive-routing/history.ts +0 -650
  118. package/pi-extension/src/cognitive-routing/host.ts +0 -266
  119. package/pi-extension/src/cognitive-routing/pi-routing-session.ts +0 -538
  120. package/pi-extension/src/cognitive-routing/pi-session-control.ts +0 -444
  121. package/pi-extension/src/cognitive-routing/runtime.ts +0 -57
  122. package/pi-extension/src/cognitive-routing/tool.ts +0 -273
  123. package/pi-extension/src/cognitive-routing/types.ts +0 -89
  124. package/pi-extension/tests/cognitive-routing/commands.test.js +0 -134
  125. package/pi-extension/tests/cognitive-routing/controller.test.js +0 -1128
  126. package/pi-extension/tests/cognitive-routing/extension-lifecycle.test.js +0 -1142
  127. package/pi-extension/tests/cognitive-routing/history.test.js +0 -274
  128. package/pi-extension/tests/cognitive-routing/host-identity.test.js +0 -63
  129. package/pi-extension/tests/cognitive-routing/pi-normal-lifecycle.test.js +0 -434
  130. package/pi-extension/tests/cognitive-routing/pi-session-control.test.js +0 -174
  131. package/pi-extension/tests/cognitive-routing/pi-session-history.test.js +0 -91
  132. package/pi-extension/tests/cognitive-routing/profile-resolution.test.js +0 -279
  133. package/pi-extension/tests/cognitive-routing/tool.test.js +0 -230
  134. package/skills/tdd/SKILL.md +0 -143
  135. package/skills/tdd/references/test-design.md +0 -96
  136. /package/pi-extension/tests/{cognitive-routing/host-fixture.js → fixtures/pi-host.js} +0 -0
@@ -1,650 +0,0 @@
1
- import { PI_SESSION_MODEL_STATE_ENTRY, parsePiSessionModelStateCommit } from "./pi-session-control.js";
2
- import type { CognitiveRoutingProfileName } from "./types.js";
3
-
4
- const COGNITIVE_ROUTING_INTENT_ENTRY = "freeflow-cognitive-routing-intent";
5
- const COGNITIVE_ROUTING_CONTROL_ENTRY = "freeflow-cognitive-routing-control";
6
- const UNKNOWN = "unknown";
7
-
8
- export type CognitiveRoutingHistoryScope = "session" | "active-branch";
9
- export type CognitiveRoutingHistoryClassification =
10
- | "semantic-switch"
11
- | "lifecycle-replay"
12
- | "initialization"
13
- | "return-target-restore"
14
- | "control-only"
15
- | "external-host-change";
16
- export type CognitiveRoutingHistoryDecisionSource = "user" | "agent" | "none" | "unknown";
17
- export type CognitiveRoutingHistoryOutcome = "completed" | "unresolved" | "abandoned" | "external";
18
- export type CognitiveRoutingHistoryIntegrity = "valid" | "unknown" | "anomaly";
19
-
20
- export type CognitiveRoutingHistoryPair = {
21
- provider: string;
22
- modelId: string;
23
- thinkingLevel: string;
24
- };
25
-
26
- export type CognitiveRoutingHistoryCurrent = {
27
- control: "automatic" | "manual" | "unavailable";
28
- profile: CognitiveRoutingProfileName | "unavailable";
29
- };
30
-
31
- export type CognitiveRoutingHistoryEvent = {
32
- id: string;
33
- timestamp?: string;
34
- jsonlPosition: number;
35
- entryId: string;
36
- parentId?: string;
37
- branchAnchor?: string;
38
- classification: CognitiveRoutingHistoryClassification;
39
- decisionSource: CognitiveRoutingHistoryDecisionSource;
40
- mechanism?: string;
41
- outcome: CognitiveRoutingHistoryOutcome;
42
- changed: boolean | "unknown";
43
- integrity: CognitiveRoutingHistoryIntegrity;
44
- from?: CognitiveRoutingProfileName;
45
- to?: CognitiveRoutingProfileName;
46
- control?: "automatic" | "manual";
47
- reason?: string;
48
- epoch?: string;
49
- correlationId?: string;
50
- decisionCorrelationId?: string;
51
- hostOrigin?: unknown;
52
- anomalyReason?: string;
53
- };
54
-
55
- export type CognitiveRoutingHistoryResult = {
56
- current: CognitiveRoutingHistoryCurrent;
57
- summary: {
58
- latestSemanticEventId?: string;
59
- latestCompletedEventId?: string;
60
- unresolvedCount: number;
61
- anomalyCount: number;
62
- };
63
- events: CognitiveRoutingHistoryEvent[];
64
- };
65
-
66
- export type CognitiveRoutingHistoryOptions = {
67
- branchEntries?: readonly unknown[];
68
- scope?: CognitiveRoutingHistoryScope;
69
- anomaliesOnly?: boolean;
70
- limit?: number;
71
- current?: CognitiveRoutingHistoryCurrent;
72
- profilePairs?: Partial<Record<CognitiveRoutingProfileName, CognitiveRoutingHistoryPair>>;
73
- profileForPair?: (pair: CognitiveRoutingHistoryPair) => CognitiveRoutingProfileName | undefined;
74
- };
75
-
76
- export type CognitiveRoutingHistoryContext = {
77
- sessionManager?: {
78
- getEntries?: () => readonly unknown[];
79
- getBranch?: () => readonly unknown[];
80
- };
81
- };
82
-
83
- type EntryRecord = Record<string, unknown>;
84
- type HistoryVersion = 1 | 2;
85
- type IntentSource = "system" | "user" | "agent" | "unknown";
86
-
87
- type ParsedIntent = {
88
- version: HistoryVersion;
89
- kind: "activation" | "profile" | "closing";
90
- phase: "prepared" | "abandoned";
91
- control: "automatic" | "manual";
92
- source: IntentSource;
93
- reason?: string;
94
- branchId?: string | null;
95
- epoch: string;
96
- correlationId: string;
97
- profile?: CognitiveRoutingProfileName;
98
- resumeProfile?: CognitiveRoutingProfileName;
99
- resumeControl?: "automatic" | "manual";
100
- resumeReason?: string;
101
- target: CognitiveRoutingHistoryPair;
102
- returnTarget: CognitiveRoutingHistoryPair;
103
- mechanism?: string;
104
- decisionCorrelationId?: string;
105
- fromPair?: CognitiveRoutingHistoryPair;
106
- fromProfile?: CognitiveRoutingProfileName;
107
- };
108
-
109
- type ParsedControl = {
110
- version: HistoryVersion;
111
- control: "automatic";
112
- source: "user" | "unknown";
113
- reason?: string;
114
- branchId?: string | null;
115
- epoch?: string;
116
- mechanism?: string;
117
- };
118
-
119
- type EntryMetadata = {
120
- raw: EntryRecord;
121
- position: number;
122
- id: string;
123
- parentId?: string;
124
- timestamp?: string;
125
- branchAnchor?: string;
126
- };
127
-
128
- type HostRecord = {
129
- metadata: EntryMetadata;
130
- pair?: CognitiveRoutingHistoryPair;
131
- correlationId?: string;
132
- hostOrigin?: unknown;
133
- };
134
-
135
- type IntentRecord = {
136
- prepared: { metadata: EntryMetadata; intent: ParsedIntent };
137
- abandonment?: { metadata: EntryMetadata; intent: ParsedIntent };
138
- conflict: boolean;
139
- };
140
-
141
- type InternalEvent = CognitiveRoutingHistoryEvent & {
142
- representativePosition: number;
143
- };
144
-
145
- function isRecord(value: unknown): value is EntryRecord {
146
- return Boolean(value && typeof value === "object");
147
- }
148
-
149
- function stringValue(value: unknown): string | undefined {
150
- return typeof value === "string" && value.length > 0 ? value : undefined;
151
- }
152
-
153
- function nullableString(value: unknown): string | null | undefined {
154
- if (value === null) return null;
155
- return typeof value === "string" ? value : undefined;
156
- }
157
-
158
- function profileName(value: unknown): CognitiveRoutingProfileName | undefined {
159
- return value === "standard" || value === "reasoning" ? value : undefined;
160
- }
161
-
162
- function pairFrom(value: unknown): CognitiveRoutingHistoryPair | undefined {
163
- if (!isRecord(value)) return undefined;
164
- const provider = stringValue(value.provider);
165
- const modelId = stringValue(value.modelId ?? value.id);
166
- const thinkingLevel = stringValue(value.thinkingLevel);
167
- if (!provider || !modelId || !thinkingLevel) return undefined;
168
- return { provider, modelId, thinkingLevel };
169
- }
170
-
171
- function pairFromEntry(entry: EntryRecord): CognitiveRoutingHistoryPair | undefined {
172
- return pairFrom({
173
- provider: entry.provider,
174
- modelId: entry.modelId,
175
- thinkingLevel: entry.thinkingLevel,
176
- });
177
- }
178
-
179
- function pairsEqual(
180
- left: CognitiveRoutingHistoryPair | undefined,
181
- right: CognitiveRoutingHistoryPair | undefined,
182
- ): boolean {
183
- return (
184
- left?.provider === right?.provider &&
185
- left?.modelId === right?.modelId &&
186
- left?.thinkingLevel === right?.thinkingLevel
187
- );
188
- }
189
-
190
- function validTimestamp(value: unknown): string | undefined {
191
- if (typeof value === "string" && !Number.isNaN(Date.parse(value))) return value;
192
- if (typeof value === "number" && Number.isFinite(value)) {
193
- const date = new Date(value);
194
- return Number.isNaN(date.getTime()) ? undefined : date.toISOString();
195
- }
196
- return undefined;
197
- }
198
-
199
- function metadataFor(entry: unknown, position: number): EntryMetadata {
200
- const raw = isRecord(entry) ? entry : {};
201
- const knownId = stringValue(raw.id);
202
- const parentId = stringValue(raw.parentId);
203
- const timestamp = validTimestamp(raw.timestamp);
204
- const id = knownId ?? `${UNKNOWN}:${position}`;
205
- return {
206
- raw,
207
- position,
208
- id,
209
- ...(parentId ? { parentId } : {}),
210
- ...(timestamp ? { timestamp } : {}),
211
- ...(knownId ? { branchAnchor: knownId } : {}),
212
- };
213
- }
214
-
215
- function sourceFrom(value: unknown): IntentSource {
216
- return value === "user" || value === "agent" || value === "system" ? value : "unknown";
217
- }
218
-
219
- function versionFrom(value: unknown): HistoryVersion | undefined {
220
- return value === 1 || value === 2 ? value : undefined;
221
- }
222
-
223
- function parseIntent(value: unknown): ParsedIntent | undefined {
224
- if (!isRecord(value)) return undefined;
225
- const version = versionFrom(value.version);
226
- const kind =
227
- value.kind === "activation" || value.kind === "profile" || value.kind === "closing" ? value.kind : undefined;
228
- const phase = value.phase === "prepared" || value.phase === "abandoned" ? value.phase : undefined;
229
- const epoch = stringValue(value.epoch);
230
- const correlationId = stringValue(value.correlationId);
231
- const target = pairFrom(value.target);
232
- const returnTarget = pairFrom(value.returnTarget);
233
- if (!version || !kind || !phase || !target || !returnTarget || !epoch || !correlationId) return undefined;
234
- const reason = stringValue(value.reason);
235
- const resumeReason = stringValue(value.resumeReason);
236
- const branchId = nullableString(value.branchId);
237
- const mechanism = stringValue(value.mechanism);
238
- const decisionCorrelationId = stringValue(value.decisionCorrelationId);
239
- const fromPair = pairFrom(value.fromPair);
240
- const profile = profileName(value.profile);
241
- const resumeProfile = profileName(value.resumeProfile);
242
- const fromProfile = profileName(value.fromProfile);
243
- return {
244
- version,
245
- kind,
246
- phase,
247
- control: value.control === "manual" ? "manual" : "automatic",
248
- source: sourceFrom(value.source),
249
- ...(reason ? { reason } : {}),
250
- ...(branchId === undefined ? {} : { branchId }),
251
- epoch,
252
- correlationId,
253
- ...(profile ? { profile } : {}),
254
- ...(resumeProfile ? { resumeProfile } : {}),
255
- ...(value.resumeControl === "automatic" || value.resumeControl === "manual"
256
- ? { resumeControl: value.resumeControl }
257
- : {}),
258
- ...(resumeReason ? { resumeReason } : {}),
259
- target,
260
- returnTarget,
261
- ...(mechanism ? { mechanism } : {}),
262
- ...(decisionCorrelationId ? { decisionCorrelationId } : {}),
263
- ...(fromPair ? { fromPair } : {}),
264
- ...(fromProfile ? { fromProfile } : {}),
265
- };
266
- }
267
-
268
- function parseControl(value: unknown): ParsedControl | undefined {
269
- if (!isRecord(value)) return undefined;
270
- const version = versionFrom(value.version);
271
- if (!version || value.control !== "automatic") return undefined;
272
- const reason = stringValue(value.reason);
273
- const branchId = nullableString(value.branchId);
274
- const epoch = stringValue(value.epoch);
275
- const mechanism = stringValue(value.mechanism);
276
- return {
277
- version,
278
- control: "automatic",
279
- source: value.source === "user" ? "user" : "unknown",
280
- ...(reason ? { reason } : {}),
281
- ...(branchId === undefined ? {} : { branchId }),
282
- ...(epoch ? { epoch } : {}),
283
- ...(mechanism ? { mechanism } : {}),
284
- };
285
- }
286
-
287
- function eventBase(
288
- id: string,
289
- metadata: EntryMetadata,
290
- ): Omit<CognitiveRoutingHistoryEvent, "classification" | "decisionSource" | "outcome" | "changed" | "integrity"> {
291
- return {
292
- id,
293
- ...(metadata.timestamp ? { timestamp: metadata.timestamp } : {}),
294
- jsonlPosition: metadata.position,
295
- entryId: metadata.id,
296
- ...(metadata.parentId ? { parentId: metadata.parentId } : {}),
297
- ...(metadata.branchAnchor ? { branchAnchor: metadata.branchAnchor } : {}),
298
- };
299
- }
300
-
301
- function profileForPair(pair: CognitiveRoutingHistoryPair | undefined, options: CognitiveRoutingHistoryOptions) {
302
- if (!pair) return undefined;
303
- if (options.profileForPair) return options.profileForPair(pair);
304
- for (const profile of ["standard", "reasoning"] as const) {
305
- if (pairsEqual(pair, options.profilePairs?.[profile])) return profile;
306
- }
307
- return undefined;
308
- }
309
-
310
- function intentClassification(intent: ParsedIntent): CognitiveRoutingHistoryClassification {
311
- if (intent.kind === "profile")
312
- return intent.source === "user" || intent.source === "agent" ? "semantic-switch" : "lifecycle-replay";
313
- if (intent.kind === "closing") return "return-target-restore";
314
- return ["reload-restore", "recovery", "session-tree", "session-compact"].includes(intent.mechanism ?? "")
315
- ? "lifecycle-replay"
316
- : "initialization";
317
- }
318
-
319
- function lifecycleDecisionSource(
320
- intent: ParsedIntent,
321
- semanticSources: ReadonlyMap<string, "user" | "agent">,
322
- ): CognitiveRoutingHistoryDecisionSource {
323
- if (intent.kind === "profile" && (intent.source === "user" || intent.source === "agent")) return intent.source;
324
- if (intent.decisionCorrelationId && semanticSources.get(intent.decisionCorrelationId)) {
325
- return semanticSources.get(intent.decisionCorrelationId) as "user" | "agent";
326
- }
327
- if (intent.kind === "profile" || intent.source === "unknown") return "unknown";
328
- return "none";
329
- }
330
-
331
- function metadataIntegrity(
332
- intent: ParsedIntent,
333
- semanticSources: ReadonlyMap<string, "user" | "agent">,
334
- ): { integrity: CognitiveRoutingHistoryIntegrity; anomalyReason?: string } {
335
- if (intent.version === 1) return { integrity: "unknown" };
336
- if (!intent.mechanism) return { integrity: "anomaly", anomalyReason: "mechanism_missing" };
337
- if (!intent.fromPair) return { integrity: "anomaly", anomalyReason: "from_pair_missing" };
338
- if (intent.kind === "profile") {
339
- if (!intent.decisionCorrelationId) return { integrity: "anomaly", anomalyReason: "decision_correlation_missing" };
340
- if (intent.source === "user" || intent.source === "agent") {
341
- if (intent.decisionCorrelationId !== intent.correlationId) {
342
- return { integrity: "anomaly", anomalyReason: "semantic_decision_correlation_mismatch" };
343
- }
344
- } else if (!semanticSources.has(intent.decisionCorrelationId)) {
345
- return { integrity: "anomaly", anomalyReason: "lifecycle_decision_unresolved" };
346
- }
347
- }
348
- return { integrity: "valid" };
349
- }
350
-
351
- function intentEvent(
352
- record: IntentRecord,
353
- representative: EntryMetadata,
354
- host: HostRecord | undefined,
355
- options: CognitiveRoutingHistoryOptions,
356
- semanticSources: ReadonlyMap<string, "user" | "agent">,
357
- outcome: CognitiveRoutingHistoryOutcome,
358
- integrity: CognitiveRoutingHistoryIntegrity,
359
- changed: boolean | "unknown",
360
- anomalyReason?: string,
361
- ): InternalEvent {
362
- const intent = record.prepared.intent;
363
- const metadata = metadataIntegrity(intent, semanticSources);
364
- const effectiveIntegrity = metadata.integrity === "anomaly" ? "anomaly" : integrity;
365
- const classification = intentClassification(intent);
366
- const from = intent.fromProfile ?? profileForPair(intent.fromPair, options);
367
- const to = intent.profile ?? profileForPair(intent.target, options);
368
- return {
369
- ...eventBase(`intent:${record.prepared.metadata.id}`, representative),
370
- classification,
371
- decisionSource: lifecycleDecisionSource(intent, semanticSources),
372
- ...(intent.mechanism ? { mechanism: intent.mechanism } : {}),
373
- outcome,
374
- changed,
375
- integrity: effectiveIntegrity,
376
- ...(from ? { from } : {}),
377
- ...(to ? { to } : {}),
378
- ...(intent.control ? { control: intent.control } : {}),
379
- ...(intent.reason ? { reason: intent.reason } : {}),
380
- epoch: intent.epoch,
381
- correlationId: intent.correlationId,
382
- ...(intent.decisionCorrelationId ? { decisionCorrelationId: intent.decisionCorrelationId } : {}),
383
- ...(host?.hostOrigin === undefined ? {} : { hostOrigin: host.hostOrigin }),
384
- ...(anomalyReason || metadata.anomalyReason ? { anomalyReason: anomalyReason ?? metadata.anomalyReason } : {}),
385
- representativePosition: representative.position,
386
- };
387
- }
388
-
389
- function controlEvent(metadata: EntryMetadata, control: ParsedControl): InternalEvent {
390
- const integrity = control.version === 1 ? "unknown" : control.mechanism ? "valid" : "anomaly";
391
- const anomalyReason = control.version === 2 && !control.mechanism ? "mechanism_missing" : undefined;
392
- return {
393
- ...eventBase(`control:${metadata.id}`, metadata),
394
- classification: "control-only",
395
- decisionSource: control.source,
396
- ...(control.mechanism ? { mechanism: control.mechanism } : {}),
397
- outcome: "completed",
398
- changed: false,
399
- integrity,
400
- control: "automatic",
401
- ...(control.reason ? { reason: control.reason } : {}),
402
- ...(control.epoch ? { epoch: control.epoch } : {}),
403
- ...(anomalyReason ? { anomalyReason } : {}),
404
- representativePosition: metadata.position,
405
- };
406
- }
407
-
408
- function hostEvent(
409
- host: HostRecord,
410
- integrity: CognitiveRoutingHistoryIntegrity,
411
- anomalyReason: string | undefined,
412
- ): InternalEvent {
413
- return {
414
- ...eventBase(`host:${host.metadata.id}`, host.metadata),
415
- classification: "external-host-change",
416
- decisionSource: "none",
417
- outcome: "external",
418
- changed: "unknown",
419
- integrity,
420
- ...(host.correlationId ? { correlationId: host.correlationId } : {}),
421
- ...(host.hostOrigin === undefined ? {} : { hostOrigin: host.hostOrigin }),
422
- ...(anomalyReason ? { anomalyReason } : {}),
423
- representativePosition: host.metadata.position,
424
- };
425
- }
426
-
427
- function activeEntryIds(entries: readonly unknown[] | undefined): Set<string> {
428
- return new Set(
429
- (Array.isArray(entries) ? entries : [])
430
- .map((entry, index) => metadataFor(entry, index).id)
431
- .filter((id) => !id.startsWith(`${UNKNOWN}:`)),
432
- );
433
- }
434
-
435
- function normalizeLimit(limit: number | undefined): number {
436
- if (!Number.isInteger(limit)) return 20;
437
- return Math.max(1, Math.min(100, limit as number));
438
- }
439
-
440
- function currentState(current: CognitiveRoutingHistoryCurrent | undefined): CognitiveRoutingHistoryCurrent {
441
- return {
442
- control: current?.control === "automatic" || current?.control === "manual" ? current.control : "unavailable",
443
- profile: current?.profile === "standard" || current?.profile === "reasoning" ? current.profile : "unavailable",
444
- };
445
- }
446
-
447
- export function projectCognitiveRoutingHistory(
448
- entries: readonly unknown[],
449
- options: CognitiveRoutingHistoryOptions = {},
450
- ): CognitiveRoutingHistoryResult {
451
- const intentRecords = new Map<string, IntentRecord>();
452
- const controls: Array<{ metadata: EntryMetadata; control: ParsedControl }> = [];
453
- const hosts: HostRecord[] = [];
454
- const semanticSources = new Map<string, "user" | "agent">();
455
-
456
- entries.forEach((entry, position) => {
457
- const metadata = metadataFor(entry, position);
458
- if (!isRecord(entry)) return;
459
- if (entry.type === "custom" && entry.customType === COGNITIVE_ROUTING_INTENT_ENTRY) {
460
- const parsed = parseIntent(entry.data);
461
- if (!parsed) return;
462
- if (parsed.phase === "abandoned") {
463
- const existing = intentRecords.get(parsed.correlationId);
464
- if (existing) existing.abandonment = { metadata, intent: parsed };
465
- return;
466
- }
467
- const existing = intentRecords.get(parsed.correlationId);
468
- if (existing) {
469
- existing.conflict = true;
470
- } else {
471
- intentRecords.set(parsed.correlationId, { prepared: { metadata, intent: parsed }, conflict: false });
472
- if (parsed.kind === "profile" && (parsed.source === "user" || parsed.source === "agent")) {
473
- semanticSources.set(parsed.correlationId, parsed.source);
474
- }
475
- }
476
- return;
477
- }
478
- if (entry.type === "custom" && entry.customType === COGNITIVE_ROUTING_CONTROL_ENTRY) {
479
- const parsed = parseControl(entry.data);
480
- if (parsed) controls.push({ metadata, control: parsed });
481
- return;
482
- }
483
- if (entry.type === "custom" && entry.customType === PI_SESSION_MODEL_STATE_ENTRY) {
484
- const parsed = parsePiSessionModelStateCommit(entry.data);
485
- if (!parsed || parsed.phase !== "committed" || parsed.status !== "applied") return;
486
- hosts.push({
487
- metadata,
488
- pair: parsed.target,
489
- correlationId: parsed.correlationId,
490
- hostOrigin: parsed.origin,
491
- });
492
- return;
493
- }
494
- if (entry.type === "model_state_change") {
495
- const correlationId = stringValue(entry.correlationId);
496
- hosts.push({
497
- metadata,
498
- pair: pairFromEntry(entry),
499
- ...(correlationId ? { correlationId } : {}),
500
- ...(entry.origin === undefined
501
- ? entry.hostOrigin === undefined
502
- ? {}
503
- : { hostOrigin: entry.hostOrigin }
504
- : { hostOrigin: entry.origin }),
505
- });
506
- }
507
- });
508
-
509
- const usedHostPositions = new Set<number>();
510
- const events: InternalEvent[] = [];
511
- const activeEpochs = new Set<string>();
512
- let completedClosing = false;
513
-
514
- for (const record of intentRecords.values()) {
515
- const intent = record.prepared.intent;
516
- const correlatedHosts = hosts.filter((host) => host.correlationId === intent.correlationId);
517
- const matchingHosts = correlatedHosts.filter((host) => pairsEqual(host.pair, intent.target));
518
- correlatedHosts.forEach((host) => usedHostPositions.add(host.metadata.position));
519
- const metadata = metadataIntegrity(intent, semanticSources);
520
-
521
- if (intent.kind === "closing" && matchingHosts.length > 0) completedClosing = true;
522
-
523
- if (record.abandonment) {
524
- events.push(
525
- intentEvent(
526
- record,
527
- record.abandonment.metadata,
528
- undefined,
529
- options,
530
- semanticSources,
531
- "abandoned",
532
- record.conflict ? "anomaly" : metadata.integrity,
533
- "unknown",
534
- record.conflict ? "duplicate_intent" : metadata.anomalyReason,
535
- ),
536
- );
537
- continue;
538
- }
539
-
540
- if (intent.kind !== "closing") activeEpochs.add(intent.epoch);
541
-
542
- if (matchingHosts.length > 0) {
543
- const representative = matchingHosts.at(-1) as HostRecord;
544
- const changed = intent.fromPair ? !pairsEqual(intent.fromPair, representative.pair) : "unknown";
545
- const duplicateReason = record.conflict
546
- ? "duplicate_intent"
547
- : correlatedHosts.length > 1
548
- ? "conflicting_host_results"
549
- : undefined;
550
- events.push(
551
- intentEvent(
552
- record,
553
- representative.metadata,
554
- representative,
555
- options,
556
- semanticSources,
557
- "completed",
558
- duplicateReason ? "anomaly" : changed === "unknown" ? "unknown" : metadata.integrity,
559
- changed,
560
- duplicateReason,
561
- ),
562
- );
563
- continue;
564
- }
565
-
566
- events.push(
567
- intentEvent(
568
- record,
569
- record.prepared.metadata,
570
- undefined,
571
- options,
572
- semanticSources,
573
- "unresolved",
574
- record.conflict || correlatedHosts.length > 0 || metadata.integrity === "anomaly" ? "anomaly" : "unknown",
575
- "unknown",
576
- record.conflict
577
- ? "duplicate_intent"
578
- : correlatedHosts.length > 0
579
- ? "host_target_mismatch"
580
- : metadata.anomalyReason,
581
- ),
582
- );
583
- }
584
-
585
- for (const item of controls) events.push(controlEvent(item.metadata, item.control));
586
-
587
- const routingOwnsHost = activeEpochs.size > 0 && !completedClosing;
588
- for (const host of hosts) {
589
- if (usedHostPositions.has(host.metadata.position)) continue;
590
- events.push(
591
- hostEvent(
592
- host,
593
- host.correlationId || routingOwnsHost ? "anomaly" : "valid",
594
- host.correlationId ? "correlation_unresolved" : routingOwnsHost ? "host_change_during_routing" : undefined,
595
- ),
596
- );
597
- }
598
-
599
- const scope = options.scope ?? "session";
600
- const activeIds = activeEntryIds(options.branchEntries);
601
- const scoped = events.filter((event) => scope !== "active-branch" || activeIds.has(event.entryId));
602
- const summary = {
603
- ...(scoped
604
- .filter((event) => event.classification === "semantic-switch")
605
- .sort((left, right) => left.representativePosition - right.representativePosition)
606
- .at(-1)?.id
607
- ? {
608
- latestSemanticEventId: scoped
609
- .filter((event) => event.classification === "semantic-switch")
610
- .sort((left, right) => left.representativePosition - right.representativePosition)
611
- .at(-1)?.id,
612
- }
613
- : {}),
614
- ...(scoped
615
- .filter((event) => event.outcome === "completed" && event.classification !== "control-only")
616
- .sort((left, right) => left.representativePosition - right.representativePosition)
617
- .at(-1)?.id
618
- ? {
619
- latestCompletedEventId: scoped
620
- .filter((event) => event.outcome === "completed" && event.classification !== "control-only")
621
- .sort((left, right) => left.representativePosition - right.representativePosition)
622
- .at(-1)?.id,
623
- }
624
- : {}),
625
- unresolvedCount: scoped.filter((event) => event.outcome === "unresolved").length,
626
- anomalyCount: scoped.filter((event) => event.integrity === "anomaly").length,
627
- };
628
- const visible = (options.anomaliesOnly ? scoped.filter((event) => event.integrity === "anomaly") : scoped)
629
- .sort((left, right) => right.representativePosition - left.representativePosition)
630
- .slice(0, normalizeLimit(options.limit))
631
- .map(({ representativePosition: _representativePosition, ...event }) => event);
632
-
633
- return { current: currentState(options.current), summary, events: visible };
634
- }
635
-
636
- export function readCognitiveRoutingHistory(
637
- context: CognitiveRoutingHistoryContext | undefined,
638
- options: CognitiveRoutingHistoryOptions = {},
639
- ): CognitiveRoutingHistoryResult {
640
- let entries: readonly unknown[] = [];
641
- let branchEntries: readonly unknown[] = [];
642
- try {
643
- entries = context?.sessionManager?.getEntries?.() ?? [];
644
- branchEntries = context?.sessionManager?.getBranch?.() ?? entries;
645
- } catch {
646
- entries = [];
647
- branchEntries = [];
648
- }
649
- return projectCognitiveRoutingHistory(entries, { ...options, branchEntries });
650
- }