subconscious-cli 6.2.0 → 6.3.0

package/bin/runbook/cursor/agent.json

@@ -1,138 +0,0 @@
-{
-  "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/hook.sh

@@ -1,145 +0,0 @@
-#!/usr/bin/env bash
-# Fail-open Cursor hook: announce prompts and compactions to the gateway. Never
-# blocks the agent.
-# Stdin: Cursor hook JSON. Stdout: permissive JSON for Cursor.
-#
-# Docs: https://cursor.com/docs/hooks
-#
-# Two events, one call each:
-#   beforeSubmitPrompt -> conversation_ensure     { conversation_id, prompt }
-#   preCompact         -> conversation_compaction { conversation_id, phase: point }
-#
-# The gateway fingerprints the raw prompt itself and chains every later turn of
-# the conversation onto the first one, so this hook needs no hashing and no local
-# state. Cursor cannot inject headers into model HTTP, which is why this
-# announcement exists at all.
-#
-# preCompact is observational and Cursor has no postCompact, so compaction is
-# reported as a zero-width "point": the gateway places the context boundary on the
-# first following turn whose retained context actually shrinks. Cursor compacts
-# mid-turn and keeps working without a new prompt, so a window closed at the next
-# beforeSubmitPrompt would wrongly swallow real turns.
-#
-# Deliberately NOT registered: afterAgentThought / afterAgentResponse /
-# preToolUse / stop / subagentStart / subagentStop. Subagents are correlated
-# gateway-side from the parent's tool-call prompt. Tool-execution hooks are also
-# the ones Cursor is known to emit with an empty conversation_id after a mid-turn
-# compaction; conversation-lifecycle hooks like the two above are unaffected.
-
-set -u
-
-CONFIG="${SUBCONSCIOUS_HOOKS_ENV:-${HOME}/.cursor/subconscious-hooks.env}"
-if [[ -f "$CONFIG" ]]; then
-  # shellcheck disable=SC1090
-  source "$CONFIG"
-fi
-
-GATEWAY_URL="${SUBCONSCIOUS_GATEWAY_URL:-}"
-API_KEY="${SUBCONSCIOUS_API_KEY:-}"
-
-# Cursor reads `user_message` on preCompact and a permission object on
-# beforeSubmitPrompt, so the reply shape depends on the event.
-HOOK_EVENT=""
-
-fail_open() {
-  if [[ "$HOOK_EVENT" == "preCompact" ]]; then
-    printf '%s\n' '{}'
-  else
-    printf '%s\n' '{"continue":true,"permission":"allow"}'
-  fi
-  exit 0
-}
-
-if [[ -z "$GATEWAY_URL" || -z "$API_KEY" ]]; then
-  echo "subconscious hook: missing SUBCONSCIOUS_GATEWAY_URL or SUBCONSCIOUS_API_KEY" >&2
-  fail_open
-fi
-
-for tool in jq curl; do
-  if ! command -v "$tool" >/dev/null 2>&1; then
-    echo "subconscious hook: ${tool} is required" >&2
-    fail_open
-  fi
-done
-
-INPUT="$(cat || true)"
-if [[ -z "$INPUT" ]]; then
-  fail_open
-fi
-
-HOOK_EVENT="$(printf '%s' "$INPUT" | jq -r '.hook_event_name // empty' 2>/dev/null || true)"
-case "$HOOK_EVENT" in
-  beforeSubmitPrompt | preCompact) ;;
-  *) fail_open ;;
-esac
-
-CONVERSATION_ID="$(printf '%s' "$INPUT" | jq -r '.conversation_id // .session_id // empty' 2>/dev/null || true)"
-if [[ -z "$CONVERSATION_ID" ]]; then
-  fail_open
-fi
-
-if [[ "$HOOK_EVENT" == "preCompact" ]]; then
-  # generation_id plus is_first_compaction keeps successive compactions distinct
-  # while making a redelivery of the same one idempotent server-side.
-  PAYLOAD="$(printf '%s' "$INPUT" | jq -c \
-    --arg conversation_id "$CONVERSATION_ID" \
-    --arg hook_event_name "$HOOK_EVENT" \
-    '{
-      event: "conversation_compaction",
-      conversation_id: $conversation_id,
-      phase: "point",
-      hook_event_name: $hook_event_name,
-      dedupe_key: ($conversation_id + ":" + ((.generation_id // "gen") | tostring)
-                   + ":" + ((.is_first_compaction // false) | tostring)),
-      metadata: {
-        trigger: .trigger,
-        context_tokens: .context_tokens,
-        context_window_size: .context_window_size,
-        context_usage_percent: .context_usage_percent,
-        message_count: .message_count,
-        messages_to_compact: .messages_to_compact,
-        is_first_compaction: .is_first_compaction
-      } | with_entries(select(.value != null))
-    }' 2>/dev/null || true)"
-else
-  PROMPT="$(printf '%s' "$INPUT" | jq -r '.prompt // empty' 2>/dev/null || true)"
-  WORKSPACE="$(printf '%s' "$INPUT" | jq -r '(.workspace_roots // [])[0] // empty' 2>/dev/null || true)"
-  if [[ -n "$WORKSPACE" ]]; then
-    WORKSPACE="$(basename "$WORKSPACE")"
-  fi
-
-  # Nothing to anchor on without a prompt.
-  if [[ -z "$PROMPT" ]]; then
-    fail_open
-  fi
-
-  PAYLOAD="$(jq -n \
-    --arg event "conversation_ensure" \
-    --arg conversation_id "$CONVERSATION_ID" \
-    --arg prompt "$PROMPT" \
-    --arg workspace "$WORKSPACE" \
-    --arg hook_event_name "$HOOK_EVENT" \
-    '{
-      event: $event,
-      conversation_id: $conversation_id,
-      prompt: $prompt,
-      workspace: (if $workspace == "" then null else $workspace end),
-      hook_event_name: $hook_event_name
-    } | with_entries(select(.value != null))'
-  )"
-fi
-
-if [[ -z "$PAYLOAD" ]]; then
-  fail_open
-fi
-
-# Response body is intentionally ignored: the gateway resolves the Cursor
-# conversation id to its own UUID on every call, so there is no mapping to cache.
-curl -sS -m 2 \
-  -H "Authorization: Bearer ${API_KEY}" \
-  -H "Content-Type: application/json" \
-  -H "x-subconscious-client: cursor" \
-  -d "$PAYLOAD" \
-  "${GATEWAY_URL%/}/v1/agent-hooks" >/dev/null 2>&1 || true
-
-fail_open

package/bin/runbook/cursor/hooks.json

@@ -1,17 +0,0 @@
-{
-  "version": 1,
-  "hooks": {
-    "beforeSubmitPrompt": [
-      {
-        "command": "HOOK_SH_PATH",
-        "timeout": 2
-      }
-    ],
-    "preCompact": [
-      {
-        "command": "HOOK_SH_PATH",
-        "timeout": 2
-      }
-    ]
-  }
-}

package/bin/runbook/cursor/install.sh

@@ -1,259 +0,0 @@
-#!/usr/bin/env bash
-# ── Subconscious API Gateway — Cursor hooks setup ─────────────────────────────
-# Install Cursor hooks that announce each agent handoff to your gateway so
-# /v1/chat/completions requests are grouped into Conversations.
-#
-# Quick start:
-#   ./install.sh --gateway-url https://your-gateway.example --api-key sk-gw-...
-#   ./install.sh status                 # show current hook config
-#   ./install.sh uninstall              # remove hooks
-#
-# Cursor model/URL are set in Cursor settings (OpenAI API Key Override), not
-# here. This script installs the conversation-correlation hooks (user-wide
-# under ~/.cursor). Restart Cursor after install so it reloads hooks.json.
-#
-# ── What this does under the hood ────────────────────────────────────────────
-# Equivalent manual setup (three pieces):
-#
-#   1. Cursor settings → enable "OpenAI API Key Override":
-#        Base URL: https://your-gateway.example/v1
-#        API Key:  sk-gw-...
-#
-#   2. Write ~/.cursor/hooks.json pointing at the hook script:
-#        {
-#          "version": 1,
-#          "hooks": {
-#            "beforeSubmitPrompt": [{ "command": "~/.cursor/hooks/subconscious-hook.sh", "timeout": 2 }],
-#            "preCompact": [{ "command": "~/.cursor/hooks/subconscious-hook.sh", "timeout": 2 }]
-#          }
-#        }
-#
-#   3. Write ~/.cursor/subconscious-hooks.env (mode 600):
-#        export SUBCONSCIOUS_GATEWAY_URL=https://your-gateway.example
-#        export SUBCONSCIOUS_API_KEY=sk-gw-...
-#
-# The hook script (hook.sh) POSTs conversation_ensure to /v1/agent-hooks with the raw
-# prompt text once per submission. The gateway fingerprints the prompt itself,
-# binds the first LLM request of that prompt, then chains every later turn of the
-# conversation onto it -- including subagents. Unlike Claude Code / Pi /
-# OpenCode, Cursor has no native session headers and hooks cannot inject headers
-# into model HTTP, so this announcement is required for correlation.
-# ─────────────────────────────────────────────────────────────────────────────
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-HOOK_SRC="${SCRIPT_DIR}/hook.sh"
-
-GATEWAY_URL="${GATEWAY_URL:-}"
-API_KEY="${CURSOR_API_KEY:-${API_KEY:-}}"
-MODEL="${MODEL:-}"
-COMMAND="install"
-
-usage() {
-  cat <<'EOF'
-Usage:
-  subc cursor install [--gateway-url URL] [--api-key KEY]
-  subc cursor uninstall
-  subc cursor status
-
-Installs Cursor hooks (user-wide under ~/.cursor) that POST to /v1/agent-hooks:
-conversation_ensure on each prompt submission so the gateway can group
-Conversations for Cursor traffic, and conversation_compaction on preCompact so
-context accounting restarts at the right turn. Existing hook entries are kept.
-
-Requires: jq, curl. Restart Cursor after install.
-EOF
-}
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    install|uninstall|status)
-      COMMAND="$1"
-      shift
-      ;;
-    --gateway-url)
-      GATEWAY_URL="${2:-}"
-      shift 2
-      ;;
-    --api-key)
-      API_KEY="${2:-}"
-      shift 2
-      ;;
-    -h|--help)
-      usage
-      exit 0
-      ;;
-    *)
-      echo "unknown argument: $1" >&2
-      usage >&2
-      exit 1
-      ;;
-  esac
-done
-
-CURSOR_DIR="${HOME}/.cursor"
-HOOKS_JSON="${CURSOR_DIR}/hooks.json"
-HOOK_DST="${CURSOR_DIR}/hooks/subconscious-hook.sh"
-ENV_FILE="${CURSOR_DIR}/subconscious-hooks.env"
-MARKER="subconscious-hook.sh"
-
-require_cmds() {
-  local missing=0
-  for c in jq curl; do
-    if ! command -v "$c" >/dev/null 2>&1; then
-      echo "missing required command: $c" >&2
-      missing=1
-    fi
-  done
-  if [[ "$missing" -ne 0 ]]; then
-    exit 1
-  fi
-}
-
-write_env() {
-  umask 077
-  cat >"$ENV_FILE" <<EOF
-# Generated by subc — do not commit secrets.
-export SUBCONSCIOUS_GATEWAY_URL='${GATEWAY_URL}'
-export SUBCONSCIOUS_API_KEY='${API_KEY}'
-EOF
-  chmod 600 "$ENV_FILE"
-}
-
-install_hook_script() {
-  mkdir -p "$(dirname "$HOOK_DST")"
-  cp "$HOOK_SRC" "$HOOK_DST"
-  chmod +x "$HOOK_DST"
-}
-
-# merge_hook_entries <hooks_json> <marker> <command> <event> [<event>...]
-#
-# Additive, idempotent merge of a single hook command into one or more events
-# of a hooks.json file. Preserves ALL other entries verbatim, including
-# third-party hooks, prompt hooks (no `command` field), and unknown events.
-#
-# Invariants:
-#  - Only entries whose `command` contains <marker> are replaced; others untouched.
-#  - Running twice yields the same result as once (idempotent, order-stable).
-#  - Entries without a `command` field are never matched/removed.
-#  - Missing/empty file is initialized to {"version":1,"hooks":{}}.
-merge_hook_entries() {
-  local hooks_json="$1" marker="$2" command="$3"
-  shift 3
-  local events
-  events="$(printf '%s\n' "$@" | jq -R . | jq -s .)"
-
-  if [[ ! -f "$hooks_json" ]]; then
-    printf '%s\n' '{"version":1,"hooks":{}}' >"$hooks_json"
-  fi
-
-  local tmp
-  tmp="$(mktemp)"
-  jq --arg marker "$marker" --arg cmd "$command" --argjson events "$events" '
-    .version = (.version // 1) |
-    .hooks = (.hooks // {}) |
-    # Strip prior entries with our marker from every event, keep everything else.
-    .hooks |= with_entries(
-      .value = ((.value // []) | map(select((.command // "") | tostring | contains($marker) | not)))
-    ) |
-    # Append our entry to each requested event (preserving any other entries).
-    .hooks = (.hooks | reduce ($events[]) as $e (.;
-      .[$e] = ((.[$e] // []) + [{"command": $cmd, "timeout": 2}])
-    ))
-  ' "$hooks_json" >"$tmp"
-  mv "$tmp" "$hooks_json"
-}
-
-# remove_hook_entries <hooks_json> <marker>
-#
-# Remove every entry whose `command` contains <marker> from all events.
-# Preserves all other entries (third-party, prompt hooks, unknown events).
-remove_hook_entries() {
-  local hooks_json="$1" marker="$2"
-  [[ -f "$hooks_json" ]] || return 0
-  local tmp
-  tmp="$(mktemp)"
-  jq --arg marker "$marker" '
-    .hooks //= {} |
-    .hooks |= with_entries(
-      .value = ((.value // []) | map(select((.command // "") | tostring | contains($marker) | not)))
-    )
-  ' "$hooks_json" >"$tmp"
-  mv "$tmp" "$hooks_json"
-}
-
-merge_hooks_json() {
-  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() {
-  remove_hook_entries "$HOOKS_JSON" "$MARKER"
-  rm -f "$HOOK_DST" "$ENV_FILE"
-}
-
-status() {
-  echo "cursor dir: $CURSOR_DIR"
-  echo "hooks.json: $HOOKS_JSON"
-  if [[ -f "$HOOKS_JSON" ]] && jq -e --arg m "$MARKER" '
-      [.hooks[]?[]? | select((.command // "") | tostring | contains($m))] | length > 0
-    ' "$HOOKS_JSON" >/dev/null 2>&1; then
-    echo "hooks: installed"
-  else
-    echo "hooks: not installed"
-  fi
-  if [[ -f "$ENV_FILE" ]]; then
-    echo "env: $ENV_FILE (present)"
-    # shellcheck disable=SC1090
-    source "$ENV_FILE"
-    echo "gateway: ${SUBCONSCIOUS_GATEWAY_URL:-unset}"
-    if [[ -n "${SUBCONSCIOUS_API_KEY:-}" ]]; then
-      echo "api key: set (${#SUBCONSCIOUS_API_KEY} chars)"
-    else
-      echo "api key: unset"
-    fi
-  else
-    echo "env: missing"
-  fi
-  if [[ -x "$HOOK_DST" ]]; then
-    echo "hook script: $HOOK_DST (executable)"
-  else
-    echo "hook script: missing"
-  fi
-}
-
-case "$COMMAND" in
-  install)
-    require_cmds
-    if [[ -z "$GATEWAY_URL" || -z "$API_KEY" ]]; then
-      echo "--gateway-url and --api-key are required for install" >&2
-      exit 1
-    fi
-    mkdir -p "$CURSOR_DIR"
-    install_hook_script
-    write_env
-    merge_hooks_json
-    echo "Installed Subconscious Cursor hooks into $CURSOR_DIR"
-    echo ""
-    echo "Finish in Cursor Settings"
-    echo "  Enable OpenAI API Key Override, then use:"
-    echo "    Base URL: ${GATEWAY_URL%/}/v1"
-    echo "  Add the available custom models:"
-    while IFS= read -r model_id; do
-      echo "    ${model_id}"
-    done <<< "$SUBC_MODEL_IDS"
-    echo "  Select ${MODEL} for this profile."
-    echo "  Paste your Subconscious API key there, then fully restart Cursor."
-    ;;
-  uninstall)
-    uninstall_hooks
-    echo "Removed Subconscious Cursor hooks from $CURSOR_DIR"
-    ;;
-  status)
-    status
-    ;;
-esac