subconscious-cli 0.2.1 → 0.3.1

package/bin/runbook/opencode/subconscious-compaction.ts

@@ -0,0 +1,100 @@
+/**
+ * Report OpenCode compactions to the Subconscious API Gateway.
+ *
+ * Why this exists: OpenCode summarizes by issuing an ordinary completion through the
+ * configured provider, which is the gateway, carrying the same session headers as every
+ * other turn. Without a signal the gateway would count that summarization as the largest
+ * main-thread turn of the conversation, inflating peak context and the traditional
+ * comparison at exactly the turn where accuracy matters most.
+ *
+ * Two callbacks bracket it:
+ *   experimental.session.compacting -> phase "start" (awaited, so it is ordered before
+ *                                     the summarization request reaches the gateway)
+ *   session.compacted event         -> phase "end"
+ *
+ * Requests between them are the compaction. `sessionID` is the same value OpenCode sends
+ * as x-session-affinity / x-session-id, which is already the gateway's grouping key, so
+ * no fingerprinting is involved.
+ *
+ * Fail open: a gateway that is down or slow must never disturb a coding session.
+ *
+ * Install: copy to ~/.config/opencode/plugins/ (global) or .opencode/plugins/ (project).
+ * `opencode/install.sh` does this for you.
+ */
+
+import type { Plugin } from "@opencode-ai/plugin"
+
+const TIMEOUT_MS = 2000
+
+function gatewayUrl(): string | undefined {
+  const raw = process.env.SUBCONSCIOUS_GATEWAY_URL ?? process.env.GATEWAY_URL
+  return raw ? raw.replace(/\/+$/, "") : undefined
+}
+
+function apiKey(): string | undefined {
+  return process.env.SUBCONSCIOUS_API_KEY ?? process.env.API_KEY
+}
+
+async function report(
+  sessionID: string,
+  phase: "start" | "end",
+  hookEventName: string,
+): Promise<void> {
+  const url = gatewayUrl()
+  const key = apiKey()
+  if (!url || !key || !sessionID) return
+
+  // Idempotency key for this one event. It must be unique per compaction but stable for
+  // a redelivery of this same POST, so it is derived from the wall clock rather than any
+  // in-process counter: a counter resets when OpenCode restarts, and a resumed session
+  // compacting again would then reuse a key the gateway has already seen and silently
+  // drop the signal. Computed once here, before the request, so a transport-level retry
+  // carries the identical body.
+  const dedupeKey = `${sessionID}:${phase}:${Date.now()}`
+
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS)
+  try {
+    await fetch(`${url}/v1/agent-hooks`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${key}`,
+        "x-subconscious-client": "opencode",
+      },
+      body: JSON.stringify({
+        event: "conversation_compaction",
+        conversation_id: sessionID,
+        phase,
+        hook_event_name: hookEventName,
+        dedupe_key: dedupeKey,
+      }),
+      signal: controller.signal,
+    })
+  } catch {
+    // Fail open on timeout, offline gateway, or auth failure.
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+export const SubconsciousCompaction: Plugin = async () => {
+  return {
+    "experimental.session.compacting": async (input) => {
+      // Deliberately does not touch `output`: mutating `context` would change the
+      // customer's compaction prompt, and setting `prompt` would replace it entirely.
+      await report(input.sessionID, "start", "session.compacting")
+    },
+    event: async ({ event }) => {
+      if (event.type === "session.compacted") {
+        const sessionID = (event as { properties?: { sessionID?: string } }).properties
+          ?.sessionID
+        if (sessionID) {
+          // No shared id with the matching `start` is needed: the gateway pairs a start
+          // with the next end by server-stamped time, not by key.
+          await report(sessionID, "end", "session.compacted")
+        }
+      }
+    },
+  }
+}

package/bin/runbook/pi/install.sh

@@ -0,0 +1,278 @@
+#!/usr/bin/env bash
+# ── Subconscious API Gateway — Pi setup ───────────────────────────────────────
+# Point the Pi CLI at your gateway. Writes a model config with session headers
+# so the gateway can correlate Pi requests into Conversations.
+#
+# Quick start:
+#   ./install.sh --gateway-url https://your-gateway.example --api-key sk-gw-...
+#   ./install.sh status                 # show current config
+#   ./install.sh uninstall              # revert to default model config
+#
+# Writes ~/.pi/agent/models.json (user config). Restart Pi after install.
+#
+# ── What this does under the hood ────────────────────────────────────────────
+# Equivalent manual setup (writes ~/.pi/agent/models.json):
+#
+#   {
+#     "providers": {
+#       "subconscious": {
+#         "baseUrl": "https://your-gateway.example/v1",
+#         "api": "openai-completions",
+#         "apiKey": "sk-gw-...",
+#         "headers": { "x-subconscious-client": "pi" },
+#         "models": [{
+#           "id": "subconscious/glm-5.2",
+#           "contextWindow": 5000000,
+#           "maxTokens": 65536,
+#           "compat": {
+#             "sendSessionAffinityHeaders": true,
+#             "sessionAffinityFormat": "openai-nosession"
+#           }
+#         }]
+#       }
+#     }
+#   }
+#
+# The compat flags make Pi send x-session-affinity headers (openai-nosession)
+# so the gateway groups requests into Conversations.
+#
+# Also installs ~/.pi/agent/extensions/subconscious-compaction.ts so Pi reports
+# session_before_compact / session_compact to /v1/agent-hooks. Pi summarizes
+# through the configured provider; without the extension that turn looks like
+# a normal main-thread peak.
+# Docs: https://pi.dev/docs/latest/compaction
+#       https://pi.dev/docs/latest/extensions
+# ─────────────────────────────────────────────────────────────────────────────
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+EXTENSION_SRC="${SCRIPT_DIR}/subconscious-compaction.ts"
+
+# 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
+
+COMMAND="install"
+GATEWAY_URL="${GATEWAY_URL:-}"
+API_KEY="${PI_API_KEY:-${API_KEY:-}}"
+MODEL="${MODEL:-subconscious/glm-5.2}"
+CONTEXT_WINDOW="${PI_CONTEXT_WINDOW:-5000000}"
+MAX_TOKENS="${PI_MAX_TOKENS:-65536}"
+
+usage() {
+  cat <<'EOF'
+Usage:
+  subc pi install [--gateway-url URL] [--api-key KEY] [--model MODEL]
+             [--context-window N] [--max-tokens N]
+  subc pi uninstall
+  subc pi status
+
+Merges a Subconscious provider into ~/.pi/agent/models.json without replacing
+other providers. Launch Pi with subc pi after install.
+
+Requires: jq. Restart Pi after install (or /reload for the extension).
+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
+      ;;
+    --model)
+      MODEL="${2:-}"
+      shift 2
+      ;;
+    --context-window)
+      CONTEXT_WINDOW="${2:-}"
+      shift 2
+      ;;
+    --max-tokens)
+      MAX_TOKENS="${2:-}"
+      shift 2
+      ;;
+    -h|--help|help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "unknown argument: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+DEFAULT_SUBCONSCIOUS_MODELS="subconscious/glm-5.2
+subconscious/tim-qwen3.6-27b
+subconscious/deepseek-v4-flash-marathon"
+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}"
+
+MODEL_ENTRIES_JSON=""
+for model_id in "${SUPPORTED_MODELS[@]}"; do
+  model_json="{\"id\":\"${model_id}\",\"contextWindow\":${CONTEXT_WINDOW},\"maxTokens\":${MAX_TOKENS},\"compat\":{\"sendSessionAffinityHeaders\":true,\"sessionAffinityFormat\":\"openai-nosession\"}}"
+  if [[ -n "$MODEL_ENTRIES_JSON" ]]; then
+    MODEL_ENTRIES_JSON="${MODEL_ENTRIES_JSON},${model_json}"
+  else
+    MODEL_ENTRIES_JSON="$model_json"
+  fi
+done
+
+PI_DIR="${HOME}/.pi/agent"
+MODELS_JSON="${PI_DIR}/models.json"
+EXTENSIONS_DIR="${PI_DIR}/extensions"
+EXTENSION_DST="${EXTENSIONS_DIR}/subconscious-compaction.ts"
+ENV_FILE="${PI_DIR}/subconscious.env"
+MARKER='x-subconscious-client'
+
+require_cmds() {
+  local missing=0
+  for c in jq; 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_config() {
+  mkdir -p "$PI_DIR"
+  local base_url="${GATEWAY_URL%/}/v1"
+  local provider
+  provider=$(cat <<EOF
+{
+  "baseUrl": "${base_url}",
+  "api": "openai-completions",
+  "apiKey": "${API_KEY}",
+  "headers": {
+    "x-subconscious-client": "pi"
+  },
+  "models": [${MODEL_ENTRIES_JSON}]
+}
+EOF
+)
+  if [[ -f "$MODELS_JSON" ]]; then
+    local tmp
+    tmp="$(mktemp)"
+    jq --argjson provider "$provider" '
+      .providers = (.providers // {})
+      | .providers.subconscious = $provider
+    ' "$MODELS_JSON" >"$tmp"
+    mv "$tmp" "$MODELS_JSON"
+  else
+    jq -n --argjson provider "$provider" '{providers: {subconscious: $provider}}' >"$MODELS_JSON"
+  fi
+  chmod 600 "$MODELS_JSON"
+
+  umask 077
+  cat >"$ENV_FILE" <<EOF
+# Generated by subc — do not commit secrets.
+# Loaded by subconscious-compaction.ts if process env is unset.
+export SUBCONSCIOUS_GATEWAY_URL='${GATEWAY_URL%/}'
+export SUBCONSCIOUS_API_KEY='${API_KEY}'
+EOF
+  chmod 600 "$ENV_FILE"
+}
+
+write_extension() {
+  if [[ ! -f "$EXTENSION_SRC" ]]; then
+    echo "warning: ${EXTENSION_SRC} missing; skipping compaction extension" >&2
+    return
+  fi
+  mkdir -p "$EXTENSIONS_DIR"
+  cp "$EXTENSION_SRC" "$EXTENSION_DST"
+}
+
+uninstall_config() {
+  if [[ -f "$MODELS_JSON" ]]; then
+    local tmp
+    tmp="$(mktemp)"
+    jq 'del(.providers.subconscious)' "$MODELS_JSON" >"$tmp"
+    mv "$tmp" "$MODELS_JSON"
+    echo "Removed Subconscious provider from $MODELS_JSON"
+  else
+    echo "No Pi models.json at $MODELS_JSON"
+  fi
+  rm -f "$EXTENSION_DST" "$ENV_FILE"
+}
+
+status() {
+  echo "scope: user"
+  echo "pi dir: $PI_DIR"
+  echo "config: $MODELS_JSON"
+  if [[ -f "$MODELS_JSON" ]] && grep -q "$MARKER" "$MODELS_JSON" 2>/dev/null; then
+    echo "status: installed"
+    echo "models: $(jq -r '[.providers.subconscious.models[].id] | join(", ")' "$MODELS_JSON" 2>/dev/null || echo 'unknown')"
+    echo "contextWindow: $(jq -r '.providers.subconscious.models[0].contextWindow // "unset"' "$MODELS_JSON" 2>/dev/null || echo 'unknown')"
+  else
+    echo "status: not installed"
+  fi
+  if [[ -f "$EXTENSION_DST" ]]; then
+    echo "compaction extension: $EXTENSION_DST (installed)"
+  else
+    echo "compaction extension: not installed"
+  fi
+  if [[ -f "$ENV_FILE" ]]; then
+    echo "env: $ENV_FILE (present)"
+  else
+    echo "env: 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
+    write_config
+    write_extension
+    echo "Merged Subconscious Pi provider into $MODELS_JSON"
+    if [[ -f "$EXTENSION_DST" ]]; then
+      echo "Installed compaction reporting extension at $EXTENSION_DST"
+    fi
+    echo "Compaction extension reads ${ENV_FILE} automatically (sourcing optional)."
+    echo "Restart any running Pi sessions (or /reload for the extension)."
+    ;;
+  uninstall)
+    uninstall_config
+    ;;
+  status)
+    status
+    ;;
+esac

package/bin/runbook/pi/run.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Launch Pi with the Subconscious provider configured by `subc pi install`.
+# This script is deliberately read-only: it never installs Pi, writes config,
+# or updates the persistent integration.
+
+set -euo pipefail
+
+MODEL="${MODEL:-subconscious/glm-5.2}"
+PI_DIR="${PI_CODING_AGENT_DIR:-${HOME}/.pi/agent}"
+MODELS_JSON="${PI_DIR}/models.json"
+
+if [[ ! -f "$MODELS_JSON" ]] || ! grep -q 'x-subconscious-client' "$MODELS_JSON" 2>/dev/null; then
+  echo "Pi is not configured for Subconscious. Run 'subc pi install' first." >&2
+  exit 1
+fi
+
+if command -v jq >/dev/null 2>&1 && ! jq -e \
+  --arg model "$MODEL" \
+  '.providers.subconscious.models[]? | select(.id == $model)' \
+  "$MODELS_JSON" >/dev/null 2>&1; then
+  echo "Model '$MODEL' is not present in the Pi catalog. Run 'subc pi install' to refresh it." >&2
+  exit 1
+fi
+
+exec pi --provider subconscious --model "$MODEL" "$@"

package/bin/runbook/pi/subconscious-compaction.ts

@@ -0,0 +1,151 @@
+/**
+ * Report Pi compactions to the Subconscious API Gateway.
+ *
+ * Why this exists: Pi summarizes by calling the configured provider (the
+ * gateway) with a structured compaction prompt. Without a signal the gateway
+ * counts that summarization as the largest main-thread turn, inflating peak
+ * context and the traditional comparison at the boundary.
+ *
+ * Two extension events bracket it:
+ *   session_before_compact -> phase "start"
+ *   session_compact        -> phase "end"
+ *
+ * Observational only: never return { cancel } or a custom compaction summary.
+ * conversation_id is ctx.sessionManager.getSessionId(), which should match the
+ * x-session-affinity value used for conversation grouping when
+ * sendSessionAffinityHeaders is enabled (openai-nosession).
+ *
+ * Capture note (2026-08): Pi compaction/branch-summary requests use a *fresh*
+ * routing session id on the wire, so the summarization HTTP call lands in a
+ * separate Conversations row. start/end still open the epoch on the parent
+ * session via getSessionId(); the boundary charge on the parent may be empty.
+ * Split-turn /compact (huge mid-turn) may only drop a few k tokens because
+ * keepRecentTokens still retains most of the active turn.
+ *
+ * Fail open: a gateway that is down or slow must never disturb a coding session.
+ *
+ * Install: copy to ~/.pi/agent/extensions/ (global). `pi/install.sh` does this.
+ * Credentials: process env, or ~/.pi/agent/subconscious.env (loaded here so
+ * launching Pi without `source` still works).
+ * Docs: https://pi.dev/docs/latest/compaction
+ *       https://pi.dev/docs/latest/extensions
+ */
+
+import { readFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+const TIMEOUT_MS = 2000
+
+type CompactPhase = "start" | "end"
+
+let envFileLoaded = false
+
+function loadSubconsciousEnvFile(): void {
+  if (envFileLoaded) return
+  envFileLoaded = true
+  if (process.env.SUBCONSCIOUS_GATEWAY_URL && process.env.SUBCONSCIOUS_API_KEY) {
+    return
+  }
+  try {
+    const path = join(homedir(), ".pi", "agent", "subconscious.env")
+    const text = readFileSync(path, "utf8")
+    for (const line of text.split("\n")) {
+      const trimmed = line.trim()
+      if (!trimmed || trimmed.startsWith("#")) continue
+      const m = trimmed.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/)
+      if (!m) continue
+      const key = m[1]
+      let val = m[2]
+      if (
+        (val.startsWith('"') && val.endsWith('"')) ||
+        (val.startsWith("'") && val.endsWith("'"))
+      ) {
+        val = val.slice(1, -1)
+      }
+      if (process.env[key] === undefined) {
+        process.env[key] = val
+      }
+    }
+  } catch {
+    // Missing file or unreadable: fall through to process env / no-op report.
+  }
+}
+
+function gatewayUrl(): string | undefined {
+  loadSubconsciousEnvFile()
+  const raw = process.env.SUBCONSCIOUS_GATEWAY_URL ?? process.env.GATEWAY_URL
+  return raw ? raw.replace(/\/+$/, "") : undefined
+}
+
+function apiKey(): string | undefined {
+  loadSubconsciousEnvFile()
+  return process.env.SUBCONSCIOUS_API_KEY ?? process.env.API_KEY ?? process.env.PI_API_KEY
+}
+
+async function report(
+  sessionID: string,
+  phase: CompactPhase,
+  hookEventName: string,
+  metadata?: Record<string, unknown>,
+): Promise<void> {
+  const url = gatewayUrl()
+  const key = apiKey()
+  if (!url || !key || !sessionID) return
+
+  // Unique per event, stable for a transport-level retry of this same POST.
+  const dedupeKey = `${sessionID}:${phase}:${Date.now()}`
+
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS)
+  try {
+    await fetch(`${url}/v1/agent-hooks`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${key}`,
+        "x-subconscious-client": "pi",
+      },
+      body: JSON.stringify({
+        event: "conversation_compaction",
+        conversation_id: sessionID,
+        phase,
+        hook_event_name: hookEventName,
+        dedupe_key: dedupeKey,
+        metadata: metadata ?? undefined,
+      }),
+      signal: controller.signal,
+    })
+  } catch {
+    // Fail open on timeout, offline gateway, or auth failure.
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+// Pi auto-discovers default-exported extension factories from
+// ~/.pi/agent/extensions/*.ts. See https://pi.dev/docs/latest/extensions
+export default function (pi: {
+  on: (event: string, handler: (...args: any[]) => any) => void
+}) {
+  pi.on("session_before_compact", async (event: any, ctx: any) => {
+    const sessionID = ctx?.sessionManager?.getSessionId?.()
+    if (sessionID) {
+      await report(sessionID, "start", "session_before_compact", {
+        reason: event?.reason ?? null,
+        tokens_before: event?.preparation?.tokensBefore ?? null,
+      })
+    }
+    // Deliberately return nothing: do not cancel or replace summarization.
+  })
+
+  pi.on("session_compact", async (event: any, ctx: any) => {
+    const sessionID = ctx?.sessionManager?.getSessionId?.()
+    if (sessionID) {
+      await report(sessionID, "end", "session_compact", {
+        reason: event?.reason ?? null,
+        from_extension: event?.fromExtension ?? null,
+      })
+    }
+  })
+}

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "subconscious-cli",
-  "version": "0.2.1",
-  "description": "CLI for Subconscious — log in and launch coding agents (Claude Code, OpenCode, Aider, Codex) on your hosted models",
+  "version": "0.3.1",
+  "description": "CLI for Subconscious — run Claude Code, Codex, OpenCode, Cursor, Copilot, and Pi",
   "bin": {
-    "subconscious": "./bin/cli.js",
-    "subconscious-cli": "./bin/cli.js"
+    "subc": "./bin/cli.js"
+  },
+  "scripts": {
+    "test": "node --test"
   },
   "files": [
     "bin"
@@ -24,11 +26,14 @@
     "cli",
     "api-key",
     "authentication",
+    "profiles",
     "coding-agent",
     "claude-code",
     "opencode",
-    "aider",
     "codex",
+    "cursor",
+    "copilot",
+    "pi",
     "launcher"
   ],
   "author": "Subconscious Systems",