@hassangameryt/freeflow 0.4.0 → 0.6.0

package/pi-extension/dist/cognitive-routing/tool.js

@@ -0,0 +1,211 @@
+import { textComponent } from "../ui/text-component.js";
+export const COGNITIVE_ROUTING_SWITCH_TOOL_NAME = "freeflow_switch_profile";
+export const COGNITIVE_ROUTING_HISTORY_TOOL_NAME = "freeflow_cognitive_routing_history";
+export const COGNITIVE_ROUTING_HISTORY_PARAMETERS = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    scope: {
+      type: "string",
+      enum: ["session", "active-branch"],
+      description: "History scope to read.",
+    },
+    anomaliesOnly: {
+      type: "boolean",
+      description: "Return only events whose integrity is anomaly.",
+    },
+    limit: {
+      type: "integer",
+      minimum: 1,
+      maximum: 100,
+      description: "Maximum number of newest events to return.",
+    },
+  },
+  required: [],
+};
+export const COGNITIVE_ROUTING_SWITCH_PARAMETERS = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    target: {
+      type: "string",
+      enum: ["standard", "reasoning"],
+      description: "The configured Cognitive Routing profile to activate.",
+    },
+    reason: {
+      type: "string",
+      minLength: 1,
+      maxLength: 160,
+      description: "A concise one-line reason for the profile transition.",
+    },
+  },
+  required: ["target", "reason"],
+};
+function resultText(result) {
+  if (result.status === "active") {
+    const fields = [COGNITIVE_ROUTING_SWITCH_TOOL_NAME + "|active", `profile|${result.profile}`];
+    if (result.changed !== undefined) fields.push(`changed|${result.changed}`);
+    if (result.from) fields.push(`from|${result.from}`);
+    if (result.to) fields.push(`to|${result.to}`);
+    return fields.join("\n");
+  }
+  return `${COGNITIVE_ROUTING_SWITCH_TOOL_NAME}|${result.status}\nreason|${result.reason}`;
+}
+function blocked(reason) {
+  return { status: "blocked", reason };
+}
+function renderNothing() {
+  return {
+    render() {
+      return [];
+    },
+    invalidate() {},
+  };
+}
+function renderTransition(text, theme) {
+  return textComponent(theme?.fg ? theme.fg("accent", text) : text);
+}
+function isProfileName(value) {
+  return value === "standard" || value === "reasoning";
+}
+function resultFromPayload(payload) {
+  const details = payload?.details?.result ?? payload?.result ?? payload?.details;
+  if (details && (details.status === "active" || details.status === "blocked" || details.status === "inactive")) {
+    if (details.status !== "active") return details;
+    if (!isProfileName(details.profile)) return undefined;
+    return {
+      status: "active",
+      profile: details.profile,
+      ...(typeof details.changed === "boolean" ? { changed: details.changed } : {}),
+      ...(isProfileName(details.from) ? { from: details.from } : {}),
+      ...(isProfileName(details.to) ? { to: details.to } : {}),
+    };
+  }
+  const text = Array.isArray(payload?.content)
+    ? payload.content.find((part) => part?.type === "text")?.text
+    : undefined;
+  if (typeof text !== "string") return undefined;
+  const fields = new Map();
+  for (const line of text.split("\\n")) {
+    const separator = line.indexOf("|");
+    if (separator <= 0) continue;
+    fields.set(line.slice(0, separator), line.slice(separator + 1));
+  }
+  const status = fields.get(COGNITIVE_ROUTING_SWITCH_TOOL_NAME);
+  if (status === "active") {
+    const profile = fields.get("profile");
+    if (!isProfileName(profile)) return undefined;
+    const changed = fields.get("changed");
+    const from = fields.get("from");
+    const to = fields.get("to");
+    return {
+      status,
+      profile,
+      ...(changed === "true" || changed === "false" ? { changed: changed === "true" } : {}),
+      ...(isProfileName(from) ? { from } : {}),
+      ...(isProfileName(to) ? { to } : {}),
+    };
+  }
+  if (status === "blocked" || status === "inactive") {
+    const reason = fields.get("reason");
+    return reason ? { status, reason } : undefined;
+  }
+  return undefined;
+}
+function historyOptions(params) {
+  return {
+    ...(params.scope === "active-branch" ? { scope: "active-branch" } : {}),
+    ...(params.anomaliesOnly === true ? { anomaliesOnly: true } : {}),
+    ...(Number.isInteger(params.limit) ? { limit: Math.max(1, Math.min(100, params.limit)) } : {}),
+  };
+}
+function validateParams(params) {
+  if (params.target !== "standard" && params.target !== "reasoning") {
+    return { status: "invalid", reason: "target_must_be_standard_or_reasoning" };
+  }
+  if (typeof params.reason !== "string") {
+    return { status: "invalid", reason: "reason_required" };
+  }
+  const reason = params.reason.trim();
+  if (!reason) return { status: "invalid", reason: "reason_required" };
+  if (reason.includes("\n") || reason.includes("\r"))
+    return { status: "invalid", reason: "reason_must_be_single_line" };
+  if (reason.length > 160) return { status: "invalid", reason: "reason_too_long" };
+  return { status: "valid", target: params.target, reason };
+}
+export function registerCognitiveRoutingTool(pi, getController) {
+  pi.registerTool({
+    name: COGNITIVE_ROUTING_SWITCH_TOOL_NAME,
+    label: "Switch Cognitive Profile",
+    description: "Request one bounded Cognitive Routing profile transition while automatic control is active.",
+    promptSnippet: "Switch between the configured standard and reasoning profiles when the current task needs it.",
+    promptGuidelines: [
+      "Use only when the current task needs a different reasoning profile.",
+      "Give one concise sentence as the reason and make this the only tool call in the response.",
+      "Do not call this tool while a deterministic manual profile hold is active.",
+    ],
+    parameters: COGNITIVE_ROUTING_SWITCH_PARAMETERS,
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      const controller = getController();
+      const input = validateParams(params ?? {});
+      let result;
+      if (input.status === "invalid") {
+        result = blocked(input.reason);
+      } else if (!controller) {
+        result = blocked("not_available");
+      } else if (!controller.state().effective) {
+        result = blocked("not_active");
+      } else if (controller.state().controlMode === "automatic") {
+        result = await controller.switchAutomaticProfile(input.target, input.reason);
+      } else {
+        result = blocked("manual_hold");
+      }
+      return {
+        content: [{ type: "text", text: resultText(result) }],
+        details: { result },
+      };
+    },
+    renderCall(_args, _theme) {
+      return renderNothing();
+    },
+    renderResult(result, _options, theme) {
+      const outcome = resultFromPayload(result);
+      if (outcome?.status === "active") {
+        if (outcome.changed === true && outcome.from && outcome.to) {
+          return renderTransition(`Cognitive Routing: ${outcome.from} → ${outcome.to}`, theme);
+        }
+        if (outcome.changed === false && outcome.to) {
+          return renderTransition(`Cognitive Routing: ${outcome.to} (already active)`, theme);
+        }
+        return renderTransition(`Cognitive Routing: active · ${outcome.profile}`, theme);
+      }
+      if (outcome) {
+        return renderTransition(`Cognitive Routing: ${outcome.status} · ${outcome.reason}`, theme);
+      }
+      return renderTransition(`Cognitive Routing: ${result?.isError ? "error" : "result unavailable"}`, theme);
+    },
+  });
+}
+export function registerCognitiveRoutingHistoryTool(pi, readHistory) {
+  pi.registerTool({
+    name: COGNITIVE_ROUTING_HISTORY_TOOL_NAME,
+    label: "Read Cognitive Routing History",
+    description:
+      "Read the deterministic Cognitive Routing transition history without changing routing or session state.",
+    promptSnippet: "Inspect Cognitive Routing transition history when debugging or monitoring profile behavior.",
+    promptGuidelines: [
+      "Use only when debugging or monitoring Cognitive Routing is requested.",
+      "This tool is read-only and does not change profile, control, branch, or session state.",
+      "Use scope=active-branch to inspect only the current branch ancestry.",
+      "Use anomaliesOnly=true to inspect only integrity anomalies.",
+    ],
+    parameters: COGNITIVE_ROUTING_HISTORY_PARAMETERS,
+    async execute(_toolCallId, params, _signal, _onUpdate, context) {
+      const result = await readHistory(historyOptions(params ?? {}), context);
+      return {
+        content: [{ type: "text", text: `Cognitive Routing history\n${JSON.stringify(result)}` }],
+        details: { result },
+      };
+    },
+  });
+}

package/pi-extension/dist/cognitive-routing/types.js

@@ -0,0 +1,6 @@
+export const COGNITIVE_ROUTING_PROFILE_NAMES = ["standard", "reasoning"];
+export const COGNITIVE_ROUTING_SESSION_START_CONTROLS = ["automatic", "manual"];
+export const DEFAULT_COGNITIVE_ROUTING_SESSION_START = {
+  control: "automatic",
+  profile: "standard",
+};

package/pi-extension/dist/context-virtualization/commands.js

@@ -0,0 +1,89 @@
+function formatStatus(status, features) {
+  if (!status.available) {
+    return `Freeflow Context: unavailable${status.unavailableReason ? ` (${status.unavailableReason})` : ""}`;
+  }
+  return [
+    "Freeflow Context: available",
+    `Context Virtualization: ${features.contextVirtualization ? "enabled" : "disabled"}`,
+    `Conversation History: ${features.conversationHistory ? "enabled" : "disabled"}`,
+    `Session: ${status.sessionId}`,
+    `Branch: ${status.branchLeafId ?? "root"}`,
+    `Projections: full=${status.counts.full}, archived=${status.counts.archived}, retained=${status.counts.retained}`,
+    `Characters: original=${status.originalCharacters.toLocaleString("en-US")}, projected=${status.projectedCharacters.toLocaleString("en-US")}`,
+    `Availability: history-only=${status.historyOnly}, unresolved=${status.unresolved}`,
+  ].join("\n");
+}
+function formatList(status) {
+  if (!status.available) return formatStatus(status, { contextVirtualization: true, conversationHistory: false });
+  const items = status.items.filter((item) => item.mode === "archived");
+  if (items.length === 0) return "Context Virtualization: no archived projections in the active session branch.";
+  const lines = ["Context Virtualization: archived projections"];
+  for (const item of items) {
+    lines.push(
+      "",
+      `Ref: ${item.ref}`,
+      `Tool: ${item.toolName ?? "tool"}`,
+      `State: ${item.retained === undefined ? "archived" : "retained"}`,
+      `Original: ${item.originalCharacters.toLocaleString("en-US")} characters`,
+      `Projected: ${item.projectedCharacters.toLocaleString("en-US")} characters`,
+      `Availability: ${item.availability}`,
+    );
+    if (item.retained !== undefined) lines.push(`Retained: ${item.retained}`);
+  }
+  return lines.join("\n");
+}
+function refsFromArgs(args) {
+  return args
+    .split(/[\s,]+/)
+    .map((value) => value.trim())
+    .filter(Boolean);
+}
+export async function handleContextCommand(args, ctx, runtime, enabled, conversationHistoryEnabled = false) {
+  const input = (args ?? "status").trim();
+  const [action = "status", ...rest] = input.split(/\s+/);
+  const normalized = action.toLowerCase();
+  if (!runtime) {
+    ctx.ui.notify("Context Virtualization is unavailable for this session.", "warning");
+    return { changed: false, error: "unavailable" };
+  }
+  if (normalized === "status") {
+    const status = await runtime.status();
+    ctx.ui.notify(
+      formatStatus(status, { contextVirtualization: enabled, conversationHistory: conversationHistoryEnabled }),
+      enabled || conversationHistoryEnabled ? "info" : "warning",
+    );
+    return { changed: false, status };
+  }
+  if (normalized === "list") {
+    const status = await runtime.status();
+    ctx.ui.notify(formatList(status), enabled ? "info" : "warning");
+    return { changed: false, status };
+  }
+  if (normalized === "restore") {
+    const refs = refsFromArgs(rest.join(" "));
+    if (!enabled) {
+      ctx.ui.notify("Context Virtualization is disabled by configuration; no projection state was changed.", "warning");
+      return { changed: false, error: "disabled" };
+    }
+    const result = await runtime.restore(refs, "user");
+    ctx.ui.notify(
+      result.message ?? `${result.status}: ${result.operation}`,
+      result.status === "ok" ? "info" : "warning",
+    );
+    return { changed: result.status === "ok", result };
+  }
+  if (normalized === "reset" && rest.join(" ").toLowerCase() === "all") {
+    if (!enabled) {
+      ctx.ui.notify("Context Virtualization is disabled by configuration; no projection state was changed.", "warning");
+      return { changed: false, error: "disabled" };
+    }
+    const result = await runtime.reset();
+    ctx.ui.notify(
+      result.message ?? `${result.status}: ${result.operation}`,
+      result.status === "ok" ? "info" : "warning",
+    );
+    return { changed: result.status === "ok", result };
+  }
+  ctx.ui.notify("Usage: /freeflow context [status|list|restore <ctx:entryId>...|reset all]", "warning");
+  return { changed: false, error: "invalid_action" };
+}

package/pi-extension/dist/context-virtualization/projector.js

@@ -0,0 +1,42 @@
+import { CONTEXT_REF_PREFIX, contextRefForEntry } from "./types.js";
+export function contentCharacters(content) {
+  if (typeof content === "string") return content.length;
+  if (!Array.isArray(content)) return 0;
+  return content.reduce((total, part) => {
+    if (part?.type === "text" && typeof part.text === "string") return total + part.text.length;
+    if (part?.type === "image") return total + 16;
+    return total;
+  }, 0);
+}
+export function contextMarker(source) {
+  return {
+    type: "text",
+    text: `[context-ref: ${contextRefForEntry(source.entryId)}]`,
+  };
+}
+export function archiveContent(source, retained) {
+  const marker = `[context archived: ${contextRefForEntry(source.entryId)}]`;
+  if (!retained) return marker;
+  return `${marker}\n\n<retained-context>\n${retained}\n</retained-context>`;
+}
+export function fullContent(source, content = []) {
+  return [...content, contextMarker(source)];
+}
+export function projectedContent(source, content, projection) {
+  if (projection.mode === "archived") {
+    return [{ type: "text", text: archiveContent(source, projection.retained) }];
+  }
+  return fullContent(source, Array.isArray(content) ? content : [{ type: "text", text: String(content ?? "") }]);
+}
+export function projectToolResultMessage(message, source, projection) {
+  return {
+    ...message,
+    content: projectedContent(source, message.content, projection),
+  };
+}
+export function projectedCharacters(source, message, projection) {
+  return contentCharacters(projectedContent(source, message?.content, projection));
+}
+export function sourceReference(source) {
+  return `${CONTEXT_REF_PREFIX}${source.entryId}`;
+}