@hassangameryt/freeflow 0.5.0 → 0.6.0

package/pi-extension/tests/cognitive-routing/history.test.js

@@ -0,0 +1,274 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { projectCognitiveRoutingHistory } from "../../dist/cognitive-routing/history.js";
+
+const standard = { provider: "faux", modelId: "standard", thinkingLevel: "high" };
+const reasoning = { provider: "faux", modelId: "reasoning", thinkingLevel: "max" };
+
+function intent(overrides = {}) {
+  return {
+    version: 2,
+    phase: "prepared",
+    kind: "profile",
+    control: "automatic",
+    source: "agent",
+    mechanism: "agent-tool",
+    decisionCorrelationId: "correlation-1",
+    fromPair: standard,
+    fromProfile: "standard",
+    epoch: "epoch-1",
+    correlationId: "correlation-1",
+    profile: "reasoning",
+    target: reasoning,
+    returnTarget: { provider: "faux", modelId: "return", thinkingLevel: "medium" },
+    reason: "Need deeper analysis.",
+    ...overrides,
+  };
+}
+
+function hostEntry(overrides = {}) {
+  return {
+    type: "model_state_change",
+    id: "state-1",
+    parentId: "intent-1",
+    timestamp: "2026-08-23T11:00:00.000Z",
+    provider: reasoning.provider,
+    modelId: reasoning.modelId,
+    thinkingLevel: reasoning.thinkingLevel,
+    correlationId: "correlation-1",
+    origin: { source: "piflow", operation: "model-state-control" },
+    ...overrides,
+  };
+}
+
+function current(profile = "reasoning", control = "automatic") {
+  return { profile, control };
+}
+
+test("projects a completed switch from the host representative and captured baseline", () => {
+  const entries = [
+    { id: "root", type: "message", parentId: null, timestamp: "2026-08-23T10:59:00.000Z" },
+    {
+      id: "intent-1",
+      type: "custom",
+      parentId: "root",
+      timestamp: "2026-08-23T10:59:01.000Z",
+      customType: "freeflow-cognitive-routing-intent",
+      data: intent(),
+    },
+    hostEntry(),
+  ];
+
+  const result = projectCognitiveRoutingHistory(entries, {
+    branchEntries: entries,
+    current: current(),
+  });
+
+  assert.deepEqual(result.current, current());
+  assert.deepEqual(result.summary, {
+    latestSemanticEventId: "intent:intent-1",
+    latestCompletedEventId: "intent:intent-1",
+    unresolvedCount: 0,
+    anomalyCount: 0,
+  });
+  assert.deepEqual(result.events, [
+    {
+      id: "intent:intent-1",
+      timestamp: "2026-08-23T11:00:00.000Z",
+      jsonlPosition: 2,
+      entryId: "state-1",
+      parentId: "intent-1",
+      branchAnchor: "state-1",
+      classification: "semantic-switch",
+      decisionSource: "agent",
+      mechanism: "agent-tool",
+      outcome: "completed",
+      changed: true,
+      integrity: "valid",
+      from: "standard",
+      to: "reasoning",
+      control: "automatic",
+      reason: "Need deeper analysis.",
+      epoch: "epoch-1",
+      correlationId: "correlation-1",
+      decisionCorrelationId: "correlation-1",
+      hostOrigin: { source: "piflow", operation: "model-state-control" },
+    },
+  ]);
+});
+
+test("orders completed events by JSONL position and preserves tri-state change semantics", () => {
+  const entries = [
+    {
+      id: "intent-a",
+      type: "custom",
+      customType: "freeflow-cognitive-routing-intent",
+      data: intent({ correlationId: "correlation-a", decisionCorrelationId: "correlation-a" }),
+    },
+    hostEntry({ id: "state-a", correlationId: "correlation-a", timestamp: "2026-08-23T11:01:00.000Z" }),
+    {
+      id: "intent-b",
+      type: "custom",
+      customType: "freeflow-cognitive-routing-intent",
+      data: intent({
+        correlationId: "correlation-b",
+        decisionCorrelationId: "correlation-b",
+        fromPair: standard,
+        fromProfile: "standard",
+        profile: "standard",
+        target: standard,
+      }),
+    },
+    hostEntry({
+      id: "state-b",
+      correlationId: "correlation-b",
+      timestamp: "not-a-timestamp",
+      provider: standard.provider,
+      modelId: standard.modelId,
+      thinkingLevel: standard.thinkingLevel,
+    }),
+    {
+      id: "intent-c",
+      type: "custom",
+      customType: "freeflow-cognitive-routing-intent",
+      data: intent({
+        version: 1,
+        correlationId: "correlation-c",
+        decisionCorrelationId: undefined,
+        fromPair: undefined,
+        fromProfile: undefined,
+      }),
+    },
+    hostEntry({ id: "state-c", correlationId: "correlation-c", timestamp: undefined }),
+  ];
+
+  const result = projectCognitiveRoutingHistory(entries, { current: current() });
+
+  assert.deepEqual(
+    result.events.map(({ id, jsonlPosition, changed, timestamp }) => ({ id, jsonlPosition, changed, timestamp })),
+    [
+      { id: "intent:intent-c", jsonlPosition: 5, changed: "unknown", timestamp: undefined },
+      { id: "intent:intent-b", jsonlPosition: 3, changed: false, timestamp: undefined },
+      { id: "intent:intent-a", jsonlPosition: 1, changed: true, timestamp: "2026-08-23T11:01:00.000Z" },
+    ],
+  );
+  assert.equal(result.summary.latestCompletedEventId, "intent:intent-c");
+});
+
+test("keeps unresolved and anomalous evidence distinct from the anomalies view", () => {
+  const entries = [
+    {
+      id: "intent-unresolved",
+      type: "custom",
+      customType: "freeflow-cognitive-routing-intent",
+      data: intent({ correlationId: "correlation-unresolved", decisionCorrelationId: "correlation-unresolved" }),
+    },
+    {
+      id: "intent-mismatch",
+      type: "custom",
+      customType: "freeflow-cognitive-routing-intent",
+      data: intent({ correlationId: "correlation-mismatch", decisionCorrelationId: "correlation-mismatch" }),
+    },
+    hostEntry({
+      id: "state-mismatch",
+      correlationId: "correlation-mismatch",
+      provider: standard.provider,
+      modelId: standard.modelId,
+      thinkingLevel: standard.thinkingLevel,
+    }),
+  ];
+
+  const result = projectCognitiveRoutingHistory(entries, { current: current() });
+  assert.equal(result.summary.unresolvedCount, 2);
+  assert.equal(result.summary.anomalyCount, 1);
+  assert.deepEqual(
+    result.events.map(({ id, outcome, integrity, anomalyReason }) => ({ id, outcome, integrity, anomalyReason })),
+    [
+      {
+        id: "intent:intent-mismatch",
+        outcome: "unresolved",
+        integrity: "anomaly",
+        anomalyReason: "host_target_mismatch",
+      },
+      { id: "intent:intent-unresolved", outcome: "unresolved", integrity: "unknown", anomalyReason: undefined },
+    ],
+  );
+
+  const anomalies = projectCognitiveRoutingHistory(entries, { current: current(), anomaliesOnly: true });
+  assert.equal(anomalies.summary.unresolvedCount, 2);
+  assert.equal(anomalies.summary.anomalyCount, 1);
+  assert.deepEqual(
+    anomalies.events.map(({ id }) => id),
+    ["intent:intent-mismatch"],
+  );
+});
+
+test("projects control-only entries without fabricating a profile transition", () => {
+  const entries = [
+    {
+      id: "control-1",
+      type: "custom",
+      customType: "freeflow-cognitive-routing-control",
+      data: {
+        version: 2,
+        control: "automatic",
+        source: "user",
+        mechanism: "profile-command",
+        epoch: "epoch-1",
+        reason: "manual hold release",
+      },
+    },
+  ];
+
+  const result = projectCognitiveRoutingHistory(entries, { current: current() });
+
+  assert.deepEqual(result.summary, {
+    unresolvedCount: 0,
+    anomalyCount: 0,
+  });
+  assert.deepEqual(result.events, [
+    {
+      id: "control:control-1",
+      jsonlPosition: 0,
+      entryId: "control-1",
+      branchAnchor: "control-1",
+      classification: "control-only",
+      decisionSource: "user",
+      mechanism: "profile-command",
+      outcome: "completed",
+      changed: false,
+      integrity: "valid",
+      control: "automatic",
+      reason: "manual hold release",
+      epoch: "epoch-1",
+    },
+  ]);
+});
+
+test("latest completed transition ignores later control-only entries", () => {
+  const entries = [
+    {
+      id: "intent-completed",
+      type: "custom",
+      customType: "freeflow-cognitive-routing-intent",
+      data: intent(),
+    },
+    hostEntry({ id: "state-completed" }),
+    {
+      id: "control-later",
+      type: "custom",
+      customType: "freeflow-cognitive-routing-control",
+      data: {
+        version: 2,
+        control: "automatic",
+        source: "user",
+        mechanism: "profile-command",
+        epoch: "epoch-1",
+      },
+    },
+  ];
+
+  const result = projectCognitiveRoutingHistory(entries, { current: current() });
+
+  assert.equal(result.summary.latestCompletedEventId, "intent:intent-completed");
+});

package/pi-extension/tests/cognitive-routing/host-fixture.js

@@ -0,0 +1,4 @@
+export const PIFLOW_HOST = Object.freeze({
+  distribution: Object.freeze({ id: "piflow", version: "test" }),
+  capabilities: Object.freeze({ sessionModelStateControl: 1 }),
+});

package/pi-extension/tests/cognitive-routing/host-identity.test.js

@@ -0,0 +1,63 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import freeflowExtension from "../../dist/index.js";
+
+const PIFLOW_HOST = Object.freeze({
+  distribution: Object.freeze({ id: "piflow", version: "test" }),
+  capabilities: Object.freeze({ sessionModelStateControl: 1 }),
+});
+
+function loadExtension(host) {
+  const tools = [];
+  const commands = [];
+  const handlers = new Map();
+  const pi = {
+    host,
+    registerTool(tool) {
+      tools.push(tool);
+    },
+    registerCommand(name, definition) {
+      commands.push({ name, definition });
+    },
+    on(event, handler) {
+      handlers.set(event, handler);
+    },
+  };
+  freeflowExtension(pi);
+  return { tools, commands, handlers };
+}
+
+test("does not activate PiFlow behavior from FREEFLOW_RUNTIME without host metadata", () => {
+  const previousRuntime = process.env.FREEFLOW_RUNTIME;
+  process.env.FREEFLOW_RUNTIME = "piflow";
+  try {
+    const { tools, commands } = loadExtension(undefined);
+    assert.equal(
+      tools.some((tool) => tool.name === "freeflow_switch_profile"),
+      false,
+    );
+    const freeflowCommand = commands.find((command) => command.name === "freeflow");
+    assert.ok(freeflowCommand);
+    assert.equal(
+      freeflowCommand.definition.getArgumentCompletions("").some((item) => item.value === "profile"),
+      false,
+    );
+  } finally {
+    if (previousRuntime === undefined) delete process.env.FREEFLOW_RUNTIME;
+    else process.env.FREEFLOW_RUNTIME = previousRuntime;
+  }
+});
+
+test("activates PiFlow behavior only with the complete host descriptor", () => {
+  const { tools, commands } = loadExtension(PIFLOW_HOST);
+  assert.equal(
+    tools.some((tool) => tool.name === "freeflow_switch_profile"),
+    true,
+  );
+  const freeflowCommand = commands.find((command) => command.name === "freeflow");
+  assert.ok(freeflowCommand);
+  assert.equal(
+    freeflowCommand.definition.getArgumentCompletions("").some((item) => item.value === "profile"),
+    true,
+  );
+});

package/pi-extension/tests/cognitive-routing/profile-resolution.test.js

@@ -0,0 +1,236 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { resolveCognitiveRoutingConfig } from "../../dist/cognitive-routing/config.js";
+import { resolveCognitiveRoutingState } from "../../dist/cognitive-routing/runtime.js";
+import { readCapabilityState } from "../../dist/runtime/runtime-context.js";
+import { PIFLOW_HOST } from "./host-fixture.js";
+
+const standard = {
+  provider: "openai-codex",
+  model: "gpt-5.6-luna",
+  thinkingLevel: "high",
+};
+const reasoning = {
+  provider: "openai-codex",
+  model: "gpt-5.6-sol",
+  thinkingLevel: "max",
+};
+
+function configuredRepository(overrides = {}) {
+  return {
+    cognitiveRouting: {
+      enabled: true,
+      profiles: { standard, reasoning },
+      ...overrides,
+    },
+  };
+}
+
+function createHost({ models = [], unauthenticated = [], clamps = {} } = {}) {
+  const modelMap = new Map(models.map((model) => [`${model.provider}/${model.id}`, model]));
+  const unauthenticatedSet = new Set(unauthenticated);
+  return {
+    modelRegistry: {
+      find(provider, modelId) {
+        return modelMap.get(`${provider}/${modelId}`);
+      },
+      async getApiKeyAndHeaders(model) {
+        return unauthenticatedSet.has(model.provider) ? { ok: false, error: "missing credentials" } : { ok: true };
+      },
+      clampThinkingLevel(model, level) {
+        return clamps[`${model.provider}/${model.id}`]?.[level] ?? level;
+      },
+    },
+  };
+}
+
+const standardModel = { provider: standard.provider, id: standard.model };
+const reasoningModel = { provider: reasoning.provider, id: reasoning.model };
+
+test("resolves two complete repository profiles", () => {
+  const result = resolveCognitiveRoutingConfig(configuredRepository(), {});
+
+  assert.equal(result.valid, true);
+  assert.equal(result.enabled, true);
+  assert.equal(result.enabledSource, "repository");
+  assert.deepEqual(result.profiles, { standard, reasoning });
+  assert.deepEqual(result.profileSources, { standard: "repository", reasoning: "repository" });
+});
+
+test("defaults new-session Cognitive Routing to automatic standard control", () => {
+  const result = resolveCognitiveRoutingConfig(configuredRepository(), {});
+
+  assert.deepEqual(result.sessionStart, { control: "automatic", profile: "standard" });
+  assert.deepEqual(result.sessionStartSources, { control: "default", profile: "default" });
+});
+
+test("layers session-start control and profile independently", () => {
+  const result = resolveCognitiveRoutingConfig(
+    configuredRepository({ sessionStart: { control: "automatic", profile: "standard" } }),
+    { cognitiveRouting: { sessionStart: { control: "manual", profile: "reasoning" } } },
+  );
+
+  assert.deepEqual(result.sessionStart, { control: "manual", profile: "reasoning" });
+  assert.deepEqual(result.sessionStartSources, { control: "personal", profile: "personal" });
+
+  const inheritedProfile = resolveCognitiveRoutingConfig(
+    configuredRepository({ sessionStart: { control: "manual" } }),
+    { cognitiveRouting: { sessionStart: { profile: "reasoning" } } },
+  );
+  assert.deepEqual(inheritedProfile.sessionStart, { control: "manual", profile: "reasoning" });
+  assert.deepEqual(inheritedProfile.sessionStartSources, { control: "repository", profile: "personal" });
+});
+
+test("replaces a profile atomically from the personal layer", () => {
+  const personalStandard = {
+    provider: "openai-codex",
+    model: "gpt-5.6-luna-personal",
+    thinkingLevel: "medium",
+  };
+  const result = resolveCognitiveRoutingConfig(configuredRepository(), {
+    cognitiveRouting: { profiles: { standard: personalStandard } },
+  });
+
+  assert.equal(result.valid, true);
+  assert.deepEqual(result.profiles.standard, personalStandard);
+  assert.deepEqual(result.profiles.reasoning, reasoning);
+  assert.deepEqual(result.profileSources, { standard: "personal", reasoning: "repository" });
+});
+
+test("rejects a partial personal profile instead of merging fields", () => {
+  const result = resolveCognitiveRoutingConfig(configuredRepository(), {
+    cognitiveRouting: { profiles: { standard: { model: "personal-only" } } },
+  });
+
+  assert.equal(result.valid, false);
+  assert.equal(result.error.code, "invalid_profile");
+  assert.equal(result.error.profile, "standard");
+});
+
+test("keeps Cognitive Routing disabled by default without a config block", async () => {
+  const result = await resolveCognitiveRoutingState({}, {}, createHost({ models: [standardModel, reasoningModel] }));
+
+  assert.equal(result.configured, false);
+  assert.equal(result.enabled, false);
+  assert.equal(result.effective, false);
+  assert.equal(result.blockingReason.code, "disabled");
+});
+
+test("fails only Cognitive Routing closed when its config is invalid", async () => {
+  const result = await resolveCognitiveRoutingState(
+    { cognitiveRouting: { enabled: true, profiles: { standard: { provider: "only-provider" } } } },
+    {},
+    createHost({ models: [standardModel, reasoningModel] }),
+  );
+
+  assert.equal(result.configured, true);
+  assert.equal(result.configValid, false);
+  assert.equal(result.effective, false);
+  assert.equal(result.blockingReason.code, "config_invalid");
+});
+
+test("reports an unsupported host without weakening core capability state", async () => {
+  const result = await resolveCognitiveRoutingState(configuredRepository(), {}, undefined);
+
+  assert.equal(result.enabled, true);
+  assert.equal(result.effective, false);
+  assert.equal(result.blockingReason.code, "host_unsupported");
+});
+
+test("preflights exact identities, authentication, and effective thinking levels", async () => {
+  const host = createHost({
+    models: [standardModel, reasoningModel],
+    clamps: { "openai-codex/gpt-5.6-luna": { high: "high" }, "openai-codex/gpt-5.6-sol": { max: "max" } },
+  });
+  const result = await resolveCognitiveRoutingState(configuredRepository(), {}, host);
+
+  assert.equal(result.effective, true);
+  assert.deepEqual(result.resolvedProfiles.standard, {
+    ...standard,
+    effectiveThinkingLevel: "high",
+  });
+  assert.deepEqual(result.resolvedProfiles.reasoning, {
+    ...reasoning,
+    effectiveThinkingLevel: "max",
+  });
+});
+
+test("runtime context isolates invalid Cognitive Routing from core Freeflow state", async () => {
+  const cwd = await mkdtemp(join(tmpdir(), "freeflow-cognitive-routing-"));
+  await mkdir(join(cwd, ".freeflow"));
+  const host = createHost({ models: [standardModel, reasoningModel] });
+  try {
+    await writeFile(
+      join(cwd, ".freeflow", "config.json"),
+      JSON.stringify({ defaultMode: "workflow", cognitiveRouting: configuredRepository().cognitiveRouting }),
+    );
+    let state = await readCapabilityState(cwd, host, PIFLOW_HOST);
+    assert.equal(state.configured, true);
+    assert.equal(state.enabled, true);
+    assert.equal(state.cognitiveRouting.effective, true);
+
+    await writeFile(
+      join(cwd, ".freeflow", "config.json"),
+      JSON.stringify({ enabled: false, cognitiveRouting: configuredRepository().cognitiveRouting }),
+    );
+    state = await readCapabilityState(cwd, host, PIFLOW_HOST);
+    assert.equal(state.enabled, false);
+    assert.equal(state.cognitiveRouting.enabled, false);
+    assert.equal(state.cognitiveRouting.effective, false);
+    assert.equal(state.cognitiveRouting.blockingReason.code, "disabled");
+
+    await writeFile(
+      join(cwd, ".freeflow", "config.json"),
+      JSON.stringify({
+        defaultMode: "workflow",
+        cognitiveRouting: { enabled: true, profiles: { standard: { provider: "only-provider" } } },
+      }),
+    );
+    state = await readCapabilityState(cwd, host, PIFLOW_HOST);
+    assert.equal(state.configured, true);
+    assert.equal(state.enabled, true);
+    assert.equal(state.cognitiveRouting.configValid, false);
+    assert.equal(state.cognitiveRouting.effective, false);
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test("rejects unavailable, unauthenticated, weakened, and identical profile pairs", async () => {
+  const unavailable = await resolveCognitiveRoutingState(
+    configuredRepository(),
+    {},
+    createHost({ models: [standardModel] }),
+  );
+  assert.equal(unavailable.blockingReason.code, "profile_unavailable");
+  assert.equal(unavailable.blockingReason.profile, "reasoning");
+
+  const unauthenticated = await resolveCognitiveRoutingState(
+    configuredRepository(),
+    {},
+    createHost({ models: [standardModel, reasoningModel], unauthenticated: ["openai-codex"] }),
+  );
+  assert.equal(unauthenticated.blockingReason.code, "profile_unauthenticated");
+  assert.equal(unauthenticated.blockingReason.profile, "standard");
+
+  const weakened = await resolveCognitiveRoutingState(
+    configuredRepository(),
+    {},
+    createHost({
+      models: [standardModel, reasoningModel],
+      clamps: { "openai-codex/gpt-5.6-luna": { high: "medium" } },
+    }),
+  );
+  assert.equal(weakened.blockingReason.code, "profile_clamped");
+  assert.equal(weakened.blockingReason.profile, "standard");
+
+  const identical = await resolveCognitiveRoutingState(
+    configuredRepository({ profiles: { standard, reasoning: { ...standard } } }),
+    {},
+    createHost({ models: [standardModel] }),
+  );
+  assert.equal(identical.blockingReason.code, "profiles_identical");
+});