subconscious-cli 6.0.1 → 6.2.0

package/bin/runbook/cursor/agent.json

@@ -0,0 +1,138 @@
+{
+  "id": "cursor",
+  "command": "cursor",
+  "aliases": [],
+  "name": "Cursor",
+  "description": "Install Cursor conversation and compaction hooks in the Cursor desktop app and IDE, then finish model setup in Cursor Settings. The Cursor CLI is not supported.",
+  "protocol": "openai",
+  "homepage": "https://cursor.com",
+  "install": {
+    "commands": null,
+    "url": "https://cursor.com/download",
+    "method": "user",
+    "package": null,
+    "version": null,
+    "minimum_version": null,
+    "verified": true,
+    "note": "IDE installed by the user. The model endpoint is set by hand in Cursor Settings (OpenAI API Key Override)."
+  },
+  "runbook": {
+    "mode": "setup",
+    "setup_script": "install.sh",
+    "setup_actions": ["install", "status", "uninstall"]
+  },
+  "help": {
+    "usage": "subc [-p NAME] cursor [help|install|status|uninstall]",
+    "behavior": "Manages Cursor correlation hooks in the Cursor desktop app and IDE; model endpoint setup is completed in Cursor Settings. The Cursor CLI is not supported.",
+    "options": [
+      ["help", "Show this help"],
+      ["install", "Install or update the Cursor hooks (default action)"],
+      ["status", "Inspect the installed hook configuration"],
+      ["uninstall", "Remove only the Subconscious Cursor hooks"]
+    ]
+  },
+  "prerequisites": [
+    { "command": "jq", "needed_for": "install", "required": true },
+    { "command": "curl", "needed_for": "install", "required": true }
+  ],
+  "launch": null,
+  "inputs": [
+    {
+      "name": "CURSOR_API_KEY",
+      "label": "Cursor hook API key",
+      "description": "Cursor hook credential override; blank uses API_KEY.",
+      "type": "secret"
+    }
+  ],
+  "env": [],
+  "config": [
+    {
+      "kind": "file",
+      "path": "~/.cursor/hooks.json",
+      "lifetime": "persistent",
+      "description": "beforeSubmitPrompt and preCompact entries are merged in; other entries are kept."
+    },
+    {
+      "kind": "file",
+      "path": "~/.cursor/hooks/subconscious-hook.sh",
+      "lifetime": "persistent",
+      "description": "Hook script."
+    },
+    {
+      "kind": "file",
+      "path": "~/.cursor/subconscious-hooks.env",
+      "lifetime": "persistent",
+      "description": "SUBCONSCIOUS_GATEWAY_URL and SUBCONSCIOUS_API_KEY for the hook (mode 600)."
+    }
+  ],
+  "capabilities": {
+    "compaction": {
+      "default": "unknown",
+      "on": {
+        "set_by_subc": false,
+        "kind": null,
+        "name": null,
+        "value": null,
+        "verified": false,
+        "note": "subc does not configure Cursor compaction."
+      },
+      "off": {
+        "set_by_subc": false,
+        "kind": null,
+        "name": null,
+        "value": null,
+        "verified": false,
+        "note": "subc does not configure Cursor compaction."
+      },
+      "threshold": {
+        "set_by_subc": false,
+        "kind": null,
+        "name": null,
+        "value": null,
+        "verified": false,
+        "note": "subc does not configure Cursor compaction."
+      }
+    },
+    "mcp": {
+      "configured_by_subc": false,
+      "transports": null,
+      "verified": false,
+      "note": "subc configures no MCP servers."
+    },
+    "headers": [
+      {
+        "name": "x-subconscious-client",
+        "value": "cursor",
+        "on": "hook POSTs to {baseUrl}/v1/agent-hooks",
+        "set_by_subc": true,
+        "verified": true,
+        "note": "Cursor cannot add headers to model requests."
+      },
+      {
+        "name": "Authorization",
+        "value": "Bearer {apiKey}",
+        "on": "hook POSTs to {baseUrl}/v1/agent-hooks",
+        "set_by_subc": true,
+        "verified": true
+      }
+    ],
+    "hooks": [
+      {
+        "event": "beforeSubmitPrompt",
+        "posts": "conversation_ensure",
+        "endpoint": "{baseUrl}/v1/agent-hooks",
+        "config": "~/.cursor/hooks.json",
+        "installed_by": ["install"],
+        "verified": true
+      },
+      {
+        "event": "preCompact",
+        "posts": "conversation_compaction phase=point",
+        "endpoint": "{baseUrl}/v1/agent-hooks",
+        "config": "~/.cursor/hooks.json",
+        "installed_by": ["install"],
+        "verified": true
+      }
+    ]
+  }
+}

package/bin/runbook/cursor/install.sh

@@ -44,37 +44,12 @@ set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 HOOK_SRC="${SCRIPT_DIR}/hook.sh"
-HOOKS_TEMPLATE="${SCRIPT_DIR}/hooks.json"
-
-# Load shared env from SUBC_ENV_FILE, or a sibling .env / env.example.
-SHARED_ENV="${SUBC_ENV_FILE:-${SCRIPT_DIR}/../.env}"
-[[ -f "$SHARED_ENV" ]] || SHARED_ENV="${SCRIPT_DIR}/../env.example"
-if [[ -f "$SHARED_ENV" ]]; then set -a; source "$SHARED_ENV"; set +a; fi
 
 GATEWAY_URL="${GATEWAY_URL:-}"
 API_KEY="${CURSOR_API_KEY:-${API_KEY:-}}"
-MODEL="${MODEL:-subconscious/glm-5.3-marathon}"
+MODEL="${MODEL:-}"
 COMMAND="install"
 
-DEFAULT_SUBCONSCIOUS_MODELS="subconscious/glm-5.3-marathon
-subconscious/glm-5.2
-subconscious/tim-qwen3.6-27b
-subconscious/deepseek-v4-flash-marathon
-subconscious/deepseek-v4.1-flash-marathon"
-
-SUPPORTED_MODELS=()
-add_supported_model() {
-  local model_id="$1"
-  for existing in "${SUPPORTED_MODELS[@]:-}"; do
-    [[ "$existing" == "$model_id" ]] && return
-  done
-  SUPPORTED_MODELS+=("$model_id")
-}
-add_supported_model "$MODEL"
-while IFS= read -r model_id; do
-  [[ -n "$model_id" ]] && add_supported_model "$model_id"
-done <<< "${SUBCONSCIOUS_MODELS:-$DEFAULT_SUBCONSCIOUS_MODELS}"
-
 usage() {
   cat <<'EOF'
 Usage:
@@ -209,13 +184,11 @@ remove_hook_entries() {
 }
 
 merge_hooks_json() {
-  if [[ ! -f "$HOOKS_JSON" ]]; then
-    sed "s|HOOK_SH_PATH|${HOOK_DST}|g" "$HOOKS_TEMPLATE" >"$HOOKS_JSON"
-    return
-  fi
-  # Replace our marker entries, then register the two lifecycle events we use.
-  remove_hook_entries "$HOOKS_JSON" "$MARKER"
-  merge_hook_entries "$HOOKS_JSON" "$MARKER" "$HOOK_DST" beforeSubmitPrompt preCompact
+  local command
+  command="$(jq -rn --arg path "$HOOK_DST" '$path | @sh')"
+  # The merge handles both first install and refresh; jq escapes JSON while
+  # @sh keeps spaces and shell characters inside the executable path.
+  merge_hook_entries "$HOOKS_JSON" "$MARKER" "$command" beforeSubmitPrompt preCompact
 }
 
 uninstall_hooks() {
@@ -270,9 +243,9 @@ case "$COMMAND" in
     echo "  Enable OpenAI API Key Override, then use:"
     echo "    Base URL: ${GATEWAY_URL%/}/v1"
     echo "  Add the available custom models:"
-    for model_id in "${SUPPORTED_MODELS[@]}"; do
+    while IFS= read -r model_id; do
       echo "    ${model_id}"
-    done
+    done <<< "$SUBC_MODEL_IDS"
     echo "  Select ${MODEL} for this profile."
     echo "  Paste your Subconscious API key there, then fully restart Cursor."
     ;;

package/bin/runbook/deepseek-harness/agent.json

@@ -0,0 +1,164 @@
+{
+  "id": "deepseek-harness",
+  "command": "dsh",
+  "aliases": ["deepseek-harness", "deepseek"],
+  "name": "DeepSeek Harness",
+  "description": "Launch DeepSeek Harness with an ephemeral Subconscious provider populated from the live model catalog.",
+  "protocol": "openai",
+  "homepage": "https://www.deepseek.com/harness/en/",
+  "install": {
+    "commands": {
+      "darwin": "npm i -g {package}",
+      "linux": "npm i -g {package}",
+      "win32": "npm i -g {package}"
+    },
+    "url": "https://www.deepseek.com/harness/en/",
+    "method": "npm",
+    "package": "@deepseek-ai/dsh",
+    "version": null,
+    "channel": "latest (unpinned)",
+    "minimum_version": null,
+    "verified": true
+  },
+  "runbook": {
+    "mode": "launch",
+    "script": "run.sh"
+  },
+  "help": {
+    "usage": "subc [-p NAME] dsh [web|headless] [--model MODEL] [Harness arguments...]",
+    "behavior": "Launches DeepSeek Harness with a temporary Subconscious provider containing every live gateway model. Web mode is the default.",
+    "options": [
+      ["help", "Show this help"],
+      ["web", "Launch the DeepSeek Harness Web UI (default)"],
+      ["headless PROMPT", "Run one headless task and exit"],
+      ["--model MODEL", "Set the initial model for new Harness sessions"]
+    ],
+    "args": ["ARGS...", "Pass remaining arguments to the selected Harness mode"]
+  },
+  "prerequisites": [],
+  "launch": {
+    "argv": ["dsh", "web", "--patch", "{tempFile}", "{args}"],
+    "headless_argv": [
+      "dsh",
+      "--profile",
+      "headless",
+      "--patch",
+      "{tempFile}",
+      "{args}"
+    ],
+    "headless_stdin": "{prompt}",
+    "headless_platforms": ["darwin", "linux", "win32"],
+    "mode_word": "web",
+    "persistent_setup": false
+  },
+  "inputs": [
+    {
+      "name": "DEEPSEEK_HARNESS_API_KEY",
+      "label": "DeepSeek Harness API key",
+      "description": "DeepSeek Harness credential override; blank uses API_KEY.",
+      "type": "secret"
+    },
+    {
+      "name": "DEEPSEEK_HARNESS_CONTEXT_WINDOW",
+      "default": 5000000,
+      "label": "Context window",
+      "description": "Context capacity advertised to DeepSeek Harness.",
+      "type": "integer",
+      "min": 1
+    },
+    {
+      "name": "DEEPSEEK_HARNESS_MAX_TOKENS",
+      "default": 65536,
+      "label": "Maximum output tokens",
+      "description": "Output capacity advertised to DeepSeek Harness.",
+      "type": "integer",
+      "min": 1
+    }
+  ],
+  "env": [
+    {
+      "name": "SUBCONSCIOUS_API_KEY",
+      "value": "{apiKey}",
+      "description": "Credential, read through apiKeyEnv in the overlay."
+    },
+    {
+      "name": "SUBCONSCIOUS_DSH_BASE_URL",
+      "value": "{baseUrlV1}",
+      "description": "OpenAI-compatible base URL, read by the overlay."
+    }
+  ],
+  "config": [
+    {
+      "kind": "file",
+      "path": "{tmp}/subc-dsh.XXXXXX/subconscious.cordis.yml",
+      "lifetime": "launch",
+      "value": {
+        "llm-pi-ai.providers.subconscious.api": "openai-completions",
+        "llm-pi-ai.providers.subconscious.apiKeyEnv": "SUBCONSCIOUS_API_KEY",
+        "llm-pi-ai.providers.subconscious.headers": {
+          "x-subconscious-client": "deepseek-harness"
+        },
+        "llm-pi-ai.providers.subconscious.compat": {
+          "supportsDeveloperRole": false,
+          "maxTokensField": "max_tokens"
+        },
+        "llm-pi-ai.providers.subconscious.defaultContextWindow": "${DEEPSEEK_HARNESS_CONTEXT_WINDOW}",
+        "llm-pi-ai.providers.subconscious.defaultMaxTokens": "${DEEPSEEK_HARNESS_MAX_TOKENS}",
+        "agent-default-model": {
+          "provider": "subconscious",
+          "model": "{model}"
+        },
+        "llm-pi-ai.providers.subconscious.models[].contextWindow": "${DEEPSEEK_HARNESS_CONTEXT_WINDOW}",
+        "llm-pi-ai.providers.subconscious.models[].maxTokens": "${DEEPSEEK_HARNESS_MAX_TOKENS}"
+      },
+      "description": "Cordis patch the runbook writes and passes with --patch; holds no API key; removed once dsh exits."
+    }
+  ],
+  "capabilities": {
+    "compaction": {
+      "default": "unknown",
+      "on": {
+        "set_by_subc": false,
+        "kind": null,
+        "name": null,
+        "value": null,
+        "verified": false,
+        "note": "subc sets contextWindow only; DeepSeek Harness compaction behaviour is not described in this repo."
+      },
+      "off": {
+        "set_by_subc": false,
+        "kind": null,
+        "name": null,
+        "value": null,
+        "verified": false,
+        "note": "No off knob is set or documented by subc."
+      },
+      "threshold": {
+        "set_by_subc": true,
+        "kind": "config-field",
+        "name": "llm-pi-ai.providers.subconscious.models[].contextWindow",
+        "value": "${DEEPSEEK_HARNESS_CONTEXT_WINDOW}",
+        "verified": false,
+        "note": "subc sets it; whether it drives compaction is not confirmed here.",
+        "semantics": "window",
+        "config": "{tmp}/subc-dsh.XXXXXX/subconscious.cordis.yml"
+      }
+    },
+    "mcp": {
+      "configured_by_subc": false,
+      "transports": null,
+      "verified": false,
+      "note": "subc configures no MCP servers."
+    },
+    "headers": [
+      {
+        "name": "x-subconscious-client",
+        "value": "deepseek-harness",
+        "on": "model requests",
+        "set_by_subc": true,
+        "verified": true
+      }
+    ],
+    "hooks": []
+  }
+}

package/bin/runbook/deepseek-harness/run.sh

@@ -1,28 +1,15 @@
 #!/usr/bin/env bash
-# Launch DeepSeek Harness with a temporary Cordis overlay that adds the live
-# Subconscious catalog. The user's DSH settings and profiles are not rewritten.
+# Write a temporary Cordis overlay that adds the live Subconscious catalog,
+# then start the dsh argv subc built. The user's DSH settings and profiles are
+# not rewritten.
 
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "${SCRIPT_DIR}/../model-capabilities.generated.sh"
+source "${SCRIPT_DIR}/../lib.sh"
 
-GATEWAY_URL="${GATEWAY_URL:-}"
-API_KEY="${DEEPSEEK_HARNESS_API_KEY:-${API_KEY:-}}"
-MODEL="${MODEL:-subconscious/glm-5.3-marathon}"
-CONTEXT_WINDOW="${DEEPSEEK_HARNESS_CONTEXT_WINDOW:-5000000}"
-MAX_TOKENS="${DEEPSEEK_HARNESS_MAX_TOKENS:-65536}"
-
-DEFAULT_SUBCONSCIOUS_MODELS="subconscious/glm-5.3-marathon
-subconscious/glm-5.2
-subconscious/tim-qwen3.6-27b
-subconscious/deepseek-v4-flash-marathon
-subconscious/deepseek-v4.1-flash-marathon"
-
-if [[ -z "$GATEWAY_URL" || -z "$API_KEY" ]]; then
-  echo "error: GATEWAY_URL and API_KEY are required to launch DeepSeek Harness" >&2
-  exit 1
-fi
+CONTEXT_WINDOW="$DEEPSEEK_HARNESS_CONTEXT_WINDOW"
+MAX_TOKENS="$DEEPSEEK_HARNESS_MAX_TOKENS"
 if [[ ! "$CONTEXT_WINDOW" =~ ^[1-9][0-9]*$ ]]; then
   echo "error: DEEPSEEK_HARNESS_CONTEXT_WINDOW must be a positive integer" >&2
   exit 1
@@ -32,27 +19,6 @@ if [[ ! "$MAX_TOKENS" =~ ^[1-9][0-9]*$ ]]; then
   exit 1
 fi
 
-SUPPORTED_MODELS=()
-add_supported_model() {
-  local model_id="$1" existing
-  [[ -n "$model_id" ]] || return 0
-  if [[ ! "$model_id" =~ ^[-A-Za-z0-9._:/+]+$ ]]; then
-    echo "error: invalid model id: $model_id" >&2
-    exit 1
-  fi
-  if [[ "${#SUPPORTED_MODELS[@]}" -gt 0 ]]; then
-    for existing in "${SUPPORTED_MODELS[@]}"; do
-      [[ "$existing" == "$model_id" ]] && return 0
-    done
-  fi
-  SUPPORTED_MODELS+=("$model_id")
-}
-
-add_supported_model "$MODEL"
-while IFS= read -r model_id; do
-  add_supported_model "$model_id"
-done <<< "${SUBCONSCIOUS_MODELS:-$DEFAULT_SUBCONSCIOUS_MODELS}"
-
 OVERLAY_DIR="$(mktemp -d "${TMPDIR:-/tmp}/subc-dsh.XXXXXX")"
 OVERLAY_FILE="${OVERLAY_DIR}/subconscious.cordis.yml"
 cleanup() {
@@ -80,7 +46,7 @@ trap cleanup EXIT HUP INT TERM
     "        defaultContextWindow: ${CONTEXT_WINDOW}" \
     "        defaultMaxTokens: ${MAX_TOKENS}" \
     '        models:'
-  for model_id in "${SUPPORTED_MODELS[@]}"; do
+  while IFS= read -r model_id; do
     printf "          - id: '%s'\n" "$model_id"
     printf "            name: '%s'\n" "$model_id"
     if subc_model_supports_vision "$model_id"; then
@@ -88,7 +54,7 @@ trap cleanup EXIT HUP INT TERM
     fi
     printf "            contextWindow: %s\n" "$CONTEXT_WINDOW"
     printf "            maxTokens: %s\n" "$MAX_TOKENS"
-  done
+  done <<< "$SUBC_MODEL_IDS"
   printf '%s\n' \
     '- id: agent-default-model' \
     '  config:' \
@@ -97,21 +63,16 @@ trap cleanup EXIT HUP INT TERM
 } >"$OVERLAY_FILE"
 chmod 600 "$OVERLAY_FILE"
 
-export SUBCONSCIOUS_API_KEY="$API_KEY"
-export SUBCONSCIOUS_DSH_BASE_URL="${GATEWAY_URL%/}/v1"
+# dsh replaces this shell, keeping its PID, so signals and the exit status
+# are dsh's own. A detached watcher removes the overlay once that PID exits.
+runbook_pid=$$
+(
+  # A stop sent to the whole process group must not kill the watcher first.
+  trap '' HUP INT TERM
+  set +e
+  while kill -0 "$runbook_pid" 2>/dev/null; do sleep 1; done
+  cleanup
+) </dev/null >/dev/null 2>&1 &
+trap - EXIT HUP INT TERM
 
-mode="web"
-if [[ "${1:-}" == "web" || "${1:-}" == "headless" ]]; then
-  mode="$1"
-  shift
-fi
-
-set +e
-if [[ "$mode" == "headless" ]]; then
-  dsh --profile headless --patch "$OVERLAY_FILE" "$@"
-else
-  dsh web --patch "$OVERLAY_FILE" "$@"
-fi
-status=$?
-set -e
-exit "$status"
+subc_exec "{tempFile}" "$OVERLAY_FILE" -- "$@"

package/bin/runbook/image-window/index.ts

@@ -0,0 +1,14 @@
+// Pi extension (Pi loads a folder's index.ts): keep requests to Subconscious at the newest 30 images, so a
+// long screenshot session's upload stops growing. The rule lives in
+// window.js (plain JS so the CLI's tests can import it).
+
+import { windowImages } from './window.js';
+
+export default function (pi: {
+  on: (
+    event: 'before_provider_request',
+    handler: (event: { payload: unknown }) => unknown,
+  ) => void;
+}) {
+  pi.on('before_provider_request', (event) => windowImages(event.payload));
+}

package/bin/runbook/image-window/window.d.ts

@@ -0,0 +1,19 @@
+export declare const MAX_IMAGES: number;
+export declare const IMAGE_LABEL: string;
+export declare const DEFAULT_SOFT_IMAGE_MIB: number;
+export declare const DEFAULT_HARD_IMAGE_MIB: number;
+export declare const SOFT_IMAGE_BYTES: number;
+export declare const HARD_IMAGE_BYTES: number;
+export declare function imagesToDrop(
+  sizes: number[],
+  maxImages?: number,
+  softBytes?: number,
+  hardBytes?: number,
+): number;
+export declare function windowImages(
+  payload: unknown,
+  maxImages?: number,
+  softBytes?: number,
+  hardBytes?: number,
+): unknown;
+export declare function windowFetch(fetchFn: typeof fetch): typeof fetch;

package/bin/runbook/image-window/window.js

@@ -0,0 +1,140 @@
+// The image window: keep a request to Subconscious at the newest screenshots.
+//
+// Every coding agent resends its whole history, every screenshot included, on
+// every turn, so a long screenshot session's upload grows without end. The
+// Subconscious gateway keeps only the newest images before it forwards a
+// request, but that does not stop the agent uploading all of them. subc's Pi
+// extension (index.ts) and OpenCode plugin apply this rule before the request
+// leaves the machine:
+//
+//   keep the newest screenshots, up to MAX_IMAGES and about SOFT_IMAGE_BYTES
+//   in total; replace every older one with the text IMAGE_LABEL.
+//
+// The label is what keeps Subconscious Cache working. The gateway puts the
+// same label before every image, so replacing an image with it removes only
+// the image's own tokens and nothing around it moves; the cache then reuses
+// the rest of the conversation and each turn only reads the new screenshot.
+//
+// The cache reuses across one removed image per turn, not several, so the
+// window never removes more than one screenshot per turn. A big screenshot can
+// take the total over SOFT_IMAGE_BYTES for a few turns while the window
+// catches up one screenshot at a time. Only if a request would pass
+// HARD_IMAGE_BYTES does it drop
+// straight back to the soft limit, which costs that turn's cache hit instead
+// of failing the request.
+
+export const MAX_IMAGES = 30;
+export const IMAGE_LABEL = 'image';
+const MIB = 1024 * 1024;
+/** Where trimming starts; room below the hard limit to catch up. */
+export const DEFAULT_SOFT_IMAGE_MIB = 25;
+/** Never forwarded above this. */
+export const DEFAULT_HARD_IMAGE_MIB = 30;
+export const SOFT_IMAGE_BYTES =
+  positiveNumber(
+    process.env.SUBCONSCIOUS_IMAGE_WINDOW_SOFT_MIB,
+    DEFAULT_SOFT_IMAGE_MIB,
+  ) * MIB;
+export const HARD_IMAGE_BYTES =
+  positiveNumber(
+    process.env.SUBCONSCIOUS_IMAGE_WINDOW_HARD_MIB,
+    DEFAULT_HARD_IMAGE_MIB,
+  ) * MIB;
+const SUBCONSCIOUS_MODEL = /^subconscious\//;
+const LABEL_PART = Object.freeze({ type: 'text', text: IMAGE_LABEL });
+
+function positiveNumber(raw, fallback) {
+  const value = Number(raw);
+  return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+
+/**
+ * How many of the oldest images to drop, given each image's size in order
+ * (oldest first). The answer for a request is worked out turn by turn over
+ * its history, as if each earlier screenshot had just arrived, so it depends
+ * only on the request and consecutive turns differ by at most one removal
+ * (except at the hard limit). The newest image is always kept.
+ */
+export function imagesToDrop(
+  sizes,
+  maxImages = MAX_IMAGES,
+  softBytes = SOFT_IMAGE_BYTES,
+  hardBytes = HARD_IMAGE_BYTES,
+) {
+  const total = [0];
+  for (const size of sizes) total.push(total.at(-1) + size);
+  const kept = (from, to) => total[to] - total[from];
+  let dropped = 0;
+  // Smallest drop count that meets both soft limits for the first k images.
+  let needed = 0;
+  for (let k = 1; k <= sizes.length; k++) {
+    needed = Math.max(needed, k - maxImages);
+    while (needed < k - 1 && kept(needed, k) > softBytes) needed += 1;
+    dropped = Math.max(dropped, Math.min(dropped + 1, needed));
+    if (kept(dropped, k) > hardBytes) dropped = needed;
+  }
+  return dropped;
+}
+
+function contentParts(message) {
+  return Array.isArray(message.content) ? message.content : [];
+}
+
+function isChatImage(part) {
+  return part?.type === 'image_url';
+}
+
+function chatImageSize(part) {
+  const url =
+    typeof part.image_url === 'string' ? part.image_url : part.image_url?.url;
+  return typeof url === 'string' ? url.length : 0;
+}
+
+/**
+ * Returns a new OpenAI chat payload with the oldest images replaced by the
+ * label, or undefined when there is nothing to change.
+ */
+export function windowImages(
+  payload,
+  maxImages = MAX_IMAGES,
+  softBytes = SOFT_IMAGE_BYTES,
+  hardBytes = HARD_IMAGE_BYTES,
+) {
+  if (!SUBCONSCIOUS_MODEL.test(payload?.model ?? '')) return undefined;
+  if (!Array.isArray(payload.messages)) return undefined;
+  const sizes = payload.messages
+    .flatMap(contentParts)
+    .filter(isChatImage)
+    .map(chatImageSize);
+  let drop = imagesToDrop(sizes, maxImages, softBytes, hardBytes);
+  if (drop === 0) return undefined;
+  const messages = payload.messages.map((message) => {
+    if (drop === 0 || !Array.isArray(message.content)) return message;
+    const content = message.content.map((part) => {
+      if (drop === 0 || !isChatImage(part)) return part;
+      drop -= 1;
+      return LABEL_PART;
+    });
+    return { ...message, content };
+  });
+  return { ...payload, messages };
+}
+
+/**
+ * Wraps a fetch so every JSON request body goes through windowImages first.
+ * Anything else, or a body that is not JSON, is sent unchanged: a problem here
+ * must never break a coding session.
+ */
+export function windowFetch(fetchFn) {
+  return async (input, init) => {
+    if (typeof init?.body !== 'string') return fetchFn(input, init);
+    let windowed;
+    try {
+      windowed = windowImages(JSON.parse(init.body));
+    } catch {
+      return fetchFn(input, init);
+    }
+    if (!windowed) return fetchFn(input, init);
+    return fetchFn(input, { ...init, body: JSON.stringify(windowed) });
+  };
+}