@hassangameryt/freeflow 0.7.1 → 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 (122) hide show
  1. package/.claude-plugin/marketplace.json +1 -1
  2. package/.claude-plugin/plugin.json +1 -1
  3. package/.codex-plugin/plugin.json +1 -1
  4. package/.cursor-plugin/plugin.json +1 -1
  5. package/README.md +28 -23
  6. package/capabilities/cognitive-routing/SKILL.md +94 -311
  7. package/command-surface.json +7 -1
  8. package/gemini-extension.json +1 -1
  9. package/package.json +4 -4
  10. package/pi-extension/dist/cognitive-routing-v2/budget.js +42 -0
  11. package/pi-extension/dist/cognitive-routing-v2/config.js +120 -0
  12. package/pi-extension/dist/cognitive-routing-v2/projection.js +321 -0
  13. package/pi-extension/dist/cognitive-routing-v2/render.js +231 -0
  14. package/pi-extension/dist/cognitive-routing-v2/runtime.js +1585 -0
  15. package/pi-extension/dist/cognitive-routing-v2/schemas.js +107 -0
  16. package/pi-extension/dist/cognitive-routing-v2/state.js +612 -0
  17. package/pi-extension/dist/cognitive-routing-v2/tools.js +91 -0
  18. package/pi-extension/dist/cognitive-routing-v2/types.js +44 -0
  19. package/pi-extension/dist/freeflow-context/tool.js +5 -0
  20. package/pi-extension/dist/index.js +279 -624
  21. package/pi-extension/dist/runtime/runtime-context.js +63 -13
  22. package/pi-extension/dist/session-sources/events.js +195 -0
  23. package/pi-extension/dist/session-sources/read-only-session.js +148 -0
  24. package/pi-extension/dist/session-sources/sources.js +233 -0
  25. package/pi-extension/dist/settings/settings-ui.js +44 -117
  26. package/pi-extension/src/cognitive-routing-v2/budget.ts +42 -0
  27. package/pi-extension/src/cognitive-routing-v2/config.ts +143 -0
  28. package/pi-extension/src/cognitive-routing-v2/projection.ts +365 -0
  29. package/pi-extension/src/cognitive-routing-v2/render.ts +256 -0
  30. package/pi-extension/src/cognitive-routing-v2/runtime.ts +1634 -0
  31. package/pi-extension/src/cognitive-routing-v2/schemas.ts +109 -0
  32. package/pi-extension/src/cognitive-routing-v2/state.ts +622 -0
  33. package/pi-extension/src/cognitive-routing-v2/tools.ts +93 -0
  34. package/pi-extension/src/cognitive-routing-v2/types.ts +222 -0
  35. package/pi-extension/src/freeflow-context/tool.ts +5 -0
  36. package/pi-extension/src/index.ts +285 -674
  37. package/pi-extension/src/runtime/runtime-context.ts +75 -14
  38. package/pi-extension/src/session-sources/events.ts +208 -0
  39. package/pi-extension/src/session-sources/read-only-session.ts +170 -0
  40. package/pi-extension/src/session-sources/sources.ts +263 -0
  41. package/pi-extension/src/settings/settings-ui.ts +54 -131
  42. package/pi-extension/tests/cognitive-routing-v2/communication.test.js +484 -0
  43. package/pi-extension/tests/cognitive-routing-v2/compaction-input.test.js +183 -0
  44. package/pi-extension/tests/cognitive-routing-v2/native.test.js +441 -0
  45. package/pi-extension/tests/cognitive-routing-v2/performance.test.js +87 -0
  46. package/pi-extension/tests/cognitive-routing-v2/persistence.test.js +245 -0
  47. package/pi-extension/tests/cognitive-routing-v2/projection.test.js +241 -0
  48. package/pi-extension/tests/cognitive-routing-v2/recovery.test.js +236 -0
  49. package/pi-extension/tests/cognitive-routing-v2/render.test.js +230 -0
  50. package/pi-extension/tests/cognitive-routing-v2/runtime.test.js +153 -0
  51. package/pi-extension/tests/cognitive-routing-v2/stabilization.test.js +521 -0
  52. package/pi-extension/tests/cognitive-routing-v2/state.test.js +275 -0
  53. package/pi-extension/tests/context-virtualization/extension.test.js +16 -0
  54. package/pi-extension/tests/fixtures/routing-native.js +188 -0
  55. package/pi-extension/tests/integration/mode-free-core.test.js +3 -2
  56. package/pi-extension/tests/integration/pi-extension.test.js +154 -37
  57. package/pi-extension/tests/integration/prompt-architecture.test.js +87 -6
  58. package/pi-extension/tests/integration/unaffected-regressions.test.js +77 -10
  59. package/plugin.json +1 -1
  60. package/runtime/prompts/cognitive-routing.md +4 -5
  61. package/runtime/prompts/core.md +51 -45
  62. package/runtime/prompts/interaction-contract.md +5 -5
  63. package/skills/action-selection/SKILL.md +57 -97
  64. package/skills/design-for-depth/SKILL.md +58 -193
  65. package/skills/design-for-depth/references/implementation-decisions.md +76 -0
  66. package/skills/diagnose-failure/SKILL.md +64 -196
  67. package/skills/discuss/SKILL.md +64 -123
  68. package/skills/discuss/references/discussion-continuity.md +7 -3
  69. package/skills/execute-work/SKILL.md +69 -88
  70. package/skills/execute-work/references/execute-work-edges.md +9 -3
  71. package/skills/handoff/SKILL.md +44 -54
  72. package/skills/handoff/references/handoff-templates.md +15 -6
  73. package/skills/review-artifact/SKILL.md +80 -127
  74. package/skills/review-artifact/references/independent-artifact-reviewer-contract.md +1 -1
  75. package/skills/review-work/SKILL.md +65 -115
  76. package/skills/review-work/references/independent-work-reviewer-contract.md +1 -1
  77. package/skills/simplify-code/SKILL.md +47 -100
  78. package/skills/track-work/SKILL.md +128 -119
  79. package/skills/track-work/references/working-record-format.md +14 -2
  80. package/skills/verify-work/SKILL.md +58 -62
  81. package/skills/verify-work/references/integration-evidence.md +4 -2
  82. package/skills/verify-work/references/test-design.md +89 -0
  83. package/skills/workflow/SKILL.md +73 -119
  84. package/skills/write-plan/SKILL.md +46 -77
  85. package/skills/write-plan/references/plan-shapes.md +5 -5
  86. package/skills/write-spec/SKILL.md +51 -63
  87. package/skills/write-spec/references/artifact-standards.md +2 -2
  88. package/skills/write-spec/references/decision-records.md +3 -2
  89. package/skills/write-spec/references/spec-shapes.md +15 -0
  90. package/pi-extension/dist/cognitive-routing/commands.js +0 -96
  91. package/pi-extension/dist/cognitive-routing/config.js +0 -232
  92. package/pi-extension/dist/cognitive-routing/controller.js +0 -1292
  93. package/pi-extension/dist/cognitive-routing/history.js +0 -451
  94. package/pi-extension/dist/cognitive-routing/host.js +0 -188
  95. package/pi-extension/dist/cognitive-routing/pi-routing-session.js +0 -414
  96. package/pi-extension/dist/cognitive-routing/pi-session-control.js +0 -320
  97. package/pi-extension/dist/cognitive-routing/runtime.js +0 -43
  98. package/pi-extension/dist/cognitive-routing/tool.js +0 -212
  99. package/pi-extension/dist/cognitive-routing/types.js +0 -6
  100. package/pi-extension/src/cognitive-routing/commands.ts +0 -129
  101. package/pi-extension/src/cognitive-routing/config.ts +0 -303
  102. package/pi-extension/src/cognitive-routing/controller.ts +0 -1628
  103. package/pi-extension/src/cognitive-routing/history.ts +0 -650
  104. package/pi-extension/src/cognitive-routing/host.ts +0 -266
  105. package/pi-extension/src/cognitive-routing/pi-routing-session.ts +0 -538
  106. package/pi-extension/src/cognitive-routing/pi-session-control.ts +0 -444
  107. package/pi-extension/src/cognitive-routing/runtime.ts +0 -57
  108. package/pi-extension/src/cognitive-routing/tool.ts +0 -273
  109. package/pi-extension/src/cognitive-routing/types.ts +0 -89
  110. package/pi-extension/tests/cognitive-routing/commands.test.js +0 -134
  111. package/pi-extension/tests/cognitive-routing/controller.test.js +0 -1128
  112. package/pi-extension/tests/cognitive-routing/extension-lifecycle.test.js +0 -1142
  113. package/pi-extension/tests/cognitive-routing/history.test.js +0 -274
  114. package/pi-extension/tests/cognitive-routing/host-identity.test.js +0 -63
  115. package/pi-extension/tests/cognitive-routing/pi-normal-lifecycle.test.js +0 -434
  116. package/pi-extension/tests/cognitive-routing/pi-session-control.test.js +0 -174
  117. package/pi-extension/tests/cognitive-routing/pi-session-history.test.js +0 -91
  118. package/pi-extension/tests/cognitive-routing/profile-resolution.test.js +0 -279
  119. package/pi-extension/tests/cognitive-routing/tool.test.js +0 -230
  120. package/skills/tdd/SKILL.md +0 -143
  121. package/skills/tdd/references/test-design.md +0 -96
  122. /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
- }