@geraldmaron/construct 1.0.6 → 1.0.8

package/lib/cache-strategy-google.js

@@ -1,17 +1,34 @@
 /**
- * lib/cache-strategy-google.js — Google Gemini cache strategy.
+ * lib/cache-strategy-google.js — Google Gemini cache strategy (agnostic skeleton).
  *
- * Google uses cachedContent API (resource-based caching, not annotations).
- * Cache TTL: 1h via cachedContent resource.
- * Requires separate API call to create/update cached content.
+ * Gemini uses a resource-based cachedContent API rather than per-message
+ * annotations. Construct does not own that integration: this module exposes
+ * the same surface as the other cache-strategy adapters and resolves cached
+ * resources via a pluggable resolver. The default resolver returns null
+ * (no cached resource), which is the safe agnostic default — callers will
+ * fall through to a fresh request. Provider plugins or operators can register
+ * a resolver via `setCachedContentResolver` to enable resource caching.
  */
 import { estimateTokens } from './token-engine.js';
 
 const GEMINI_CACHE_ENDPOINT = 'https://generativelanguage.googleapis.com/v1';
 
+let cachedContentResolver = null;
+
+/**
+ * Register a resolver responsible for producing a cachedContent resource name
+ * for a given system prompt. Contract:
+ *   resolver({ systemText, caps, apiKey, modelId }) -> Promise<string|null>
+ * Returning null means no cached resource is available; the annotation is
+ * omitted and the request proceeds without a cached prefix.
+ */
+export function setCachedContentResolver(resolver) {
+  cachedContentResolver = typeof resolver === 'function' ? resolver : null;
+}
+
 /**
- * Annotate prompt structure for Google Gemini models.
- * Note: Gemini uses cachedContent API, not message annotations.
+ * Annotate prompt structure for Google Gemini models. Returns the shared
+ * annotation shape that every cache-strategy adapter emits.
  *
  * @param {object} promptStructure - { system, messages }
  * @param {object} caps - Provider capabilities
@@ -22,12 +39,10 @@ export async function annotate(promptStructure, caps, { apiKey, modelId } = {})
   const { system, messages } = promptStructure || {};
 
   let cachedContentName = null;
-
-  if (apiKey && system) {
+  if (cachedContentResolver && apiKey && system) {
     try {
-      cachedContentName = await createCachedContent(system, caps, apiKey, modelId);
-    } catch (err) {
-    }
+      cachedContentName = await cachedContentResolver({ systemText: system, caps, apiKey, modelId });
+    } catch { /* resolver failure is non-fatal — fall through with no annotation */ }
   }
 
   return {
@@ -49,26 +64,6 @@ export async function annotate(promptStructure, caps, { apiKey, modelId } = {})
   };
 }
 
-async function createCachedContent(systemText, caps, apiKey, modelId) {
-  // POST to https://generativelanguage.googleapis.com/v1/cachedContents
-  // Body: { model: 'gemini-1.5-pro', contents: [{ parts: [{ text: systemText }] }] }
-  // Returns: { name: 'cachedContents/abc123' }
-
-  const model = extractModelName(modelId);
-  const url = `${GEMINI_CACHE_ENDPOINT}/cachedContents?key=${apiKey}`;
-
-  // This is async but we don't want to block dispatch
-  // In production, this should be pre-cached
-  // For now, return null (defer to Phase C follow-up with live probing)
-  return null;
-}
-
-function extractModelName(modelId) {
-  const id = String(modelId || '').toLowerCase();
-  const match = id.match(/google\/(gemini-[^\/]+)/);
-  return match ? match[1] : 'gemini-1.5-pro';
-}
-
 export async function capabilities() {
   return {
     supportsAnnotations: false,

package/lib/cli-commands.mjs

@@ -199,14 +199,6 @@ export const CLI_COMMANDS = [
       { name: 'update', desc: 'Regenerate AUTO-managed regions' },
     ],
   },
-  {
-    name: 'models',
-    emoji: '🧠',
-    category: 'Core',
-    core: true,
-    description: 'Manage AI model assignments',
-    usage: 'construct models [--apply|--poll]',
-  },
   {
     name: 'doctor',
     emoji: '🩺',
@@ -273,145 +265,251 @@ export const CLI_COMMANDS = [
     description: 'Task graph management',
     usage: 'construct graph list|show|from-intake',
   },
+
+  // ── Models & Integrations ─────────────────────────────────────────────
   {
-    name: 'memory',
-    emoji: '💡',
-    category: 'Work',
-    core: false,
-    description: 'Inspect memory layer',
-    usage: 'construct memory stats|consolidate',
-  },
-  {
-    name: 'reflect',
-    emoji: '🪞',
-    category: 'Work',
-    core: false,
-    description: 'Capture improvement feedback',
-    usage: 'construct reflect [--summary=<text>]',
-  },
-  {
-    name: 'drop',
-    emoji: '📥',
-    category: 'Work',
-    core: false,
-    description: 'Ingest file from Downloads/Desktop',
-    usage: 'construct drop [--list]',
-  },
-  {
-    name: 'wireframe',
-    emoji: '✏️',
-    category: 'Work',
-    core: false,
-    description: 'Generate wireframes from description',
-    usage: 'construct wireframe "<description>"',
-  },
-  {
-    name: 'bootstrap',
-    emoji: '🌱',
-    category: 'Work',
-    core: false,
-    description: 'Import seed observations',
-    usage: 'construct bootstrap',
-  },
-  {
-    name: 'team',
-    emoji: '👥',
-    category: 'Work',
-    core: false,
-    description: 'Team review and templates',
-    usage: 'construct team review|templates',
+    name: 'models',
+    emoji: '🧠',
+    category: 'Models & Integrations',
+    description: 'Show or update model tier assignments',
+    usage: 'construct models [--poll|--apply|--reset|--tier=TIER|--set=MODEL|--prefer-free|--prefer-free-same-family]',
+    options: [
+      { flag: '--poll',        desc: 'Query OpenRouter for currently free models' },
+      { flag: '--apply',       desc: 'Auto-apply best free models and sync' },
+      { flag: '--reset',       desc: 'Remove model overrides, restore defaults' },
+      { flag: '--tier=TIER',   desc: 'Target tier: reasoning | standard | fast' },
+      { flag: '--set=MODEL_ID',desc: 'Set specific model for the tier' },
+      { flag: '--prefer-free', desc: 'When inferring sibling tiers, prefer free models where possible' },
+      { flag: '--prefer-free-same-family', desc: 'Prefer free siblings only when they stay in the same provider family' },
+    ],
   },
-  
-  // ── Integrations ──────────────────────────────────────────────────────
   {
     name: 'mcp',
     emoji: '🔌',
-    category: 'Integrations',
-    core: false,
+    category: 'Models & Integrations',
     description: 'Manage MCP integrations',
-    usage: 'construct mcp list|add|remove',
-  },
-  {
-    name: 'ollama',
-    emoji: '🦙',
-    category: 'Integrations',
-    core: false,
-    description: 'Manage local Ollama models',
-    usage: 'construct ollama status|pull|test',
+    usage: 'construct mcp <list|add|remove|info> [name]',
+    subcommands: [
+      { name: 'list',   desc: 'Show all MCP integrations and status' },
+      { name: 'add',    desc: 'Add an MCP integration interactively' },
+      { name: 'remove', desc: 'Remove an MCP integration' },
+      { name: 'info',   desc: 'Show setup details for an integration' },
+    ],
   },
   {
     name: 'plugin',
     emoji: '🧩',
-    category: 'Integrations',
-    core: false,
-    description: 'Manage plugin manifests',
-    usage: 'construct plugin list|validate',
+    category: 'Models & Integrations',
+    description: 'Manage external Construct plugin manifests',
+    usage: 'construct plugin <list|info|validate|init> [name]',
+    subcommands: [
+      { name: 'list', desc: 'Show loaded plugins and manifest sources' },
+      { name: 'info', desc: 'Show details for a plugin' },
+      { name: 'validate', desc: 'Validate all discovered plugin manifests' },
+      { name: 'init', desc: 'Create a starter plugin manifest in .cx/plugins/' },
+    ],
   },
   {
     name: 'hosts',
     emoji: '🖥️',
-    category: 'Integrations',
-    core: false,
-    description: 'Check host capabilities',
+    category: 'Models & Integrations',
+    description: 'Show host support for Construct orchestration',
     usage: 'construct hosts',
   },
   {
     name: 'claude:allow',
     emoji: '🔓',
-    category: 'Integrations',
-    core: false,
-    description: 'Manage Claude Code permissions',
-    usage: 'construct claude:allow list|add|check',
+    category: 'Models & Integrations',
+    description: 'Manage Claude Code `permissions.allow` from the outside (auto-classifier blocks the agent from editing it)',
+    usage: 'construct claude:allow <list|add|remove|check> [pattern...] [--apply]',
+    subcommands: [
+      { name: 'list',   desc: 'Print every allowlist entry' },
+      { name: 'add',    desc: 'Add one or more patterns (idempotent)' },
+      { name: 'remove', desc: 'Remove patterns' },
+      { name: 'check',  desc: 'Detect branch-prefix gaps; `--apply` writes the suggestions' },
+    ],
   },
-  
+
   // ── Observability ─────────────────────────────────────────────────────
   {
-    name: 'cost',
-    emoji: '💰',
+    name: 'review',
+    emoji: '📈',
     category: 'Observability',
-    core: false,
-    description: 'Token usage and cost breakdown',
-    usage: 'construct cost [--days=N]',
+    description: 'Generate agent performance review from Langfuse trace backend',
+    usage: 'construct review [--days=N] [--agent=NAME] [--schedule]',
+    options: [
+      { flag: '--days=N',      desc: 'Review window in days (default: 30)' },
+      { flag: '--agent=NAME',  desc: 'Filter to a specific agent' },
+      { flag: '--out=PATH',    desc: 'Output directory' },
+      { flag: '--json-only',   desc: 'Write raw JSON only, skip markdown report' },
+      { flag: '--schedule',    desc: 'Schedule automatic weekly reviews' },
+      { flag: '--cadence=CRON',desc: 'Cron expression for --schedule (default: Monday 9am)' },
+    ],
   },
   {
-    name: 'efficiency',
-    emoji: '🧮',
+    name: 'optimize',
+    emoji: '⚙️',
     category: 'Observability',
-    core: false,
-    description: 'Read efficiency metrics',
-    usage: 'construct efficiency',
+    description: 'Prompt optimization using Langfuse trace quality scores',
+    usage: 'construct optimize <agent> [--dry-run] [--list]',
+    options: [
+      { flag: '--dry-run',       desc: 'Preview changes without applying' },
+      { flag: '--list',          desc: 'Show all agents with quality scores' },
+      { flag: '--threshold=N',   desc: 'Quality threshold to trigger optimization (default: 0.7)' },
+      { flag: '--days=N',        desc: 'Trace window in days (default: 7)' },
+      { flag: '--min-traces=N',  desc: 'Minimum traces required (default: 20)' },
+    ],
   },
   {
-    name: 'review',
-    emoji: '📈',
+    name: 'telemetry-backfill',
+    emoji: '🩹',
     category: 'Observability',
-    core: false,
-    description: 'Agent performance review',
-    usage: 'construct review [--days=N]',
+    description: 'Backfill sparse traces with observations (trace backend)',
+    usage: 'construct telemetry-backfill [--limit=N]',
+    options: [
+      { flag: '--limit=N', desc: 'Maximum sparse traces to backfill (default: 10)' },
+      { flag: '--best-effort', desc: 'Skip failures instead of exiting non-zero' },
+    ],
   },
   {
-    name: 'optimize',
-    emoji: '⚙️',
+    name: 'eval-datasets',
+    emoji: '📊',
     category: 'Observability',
-    core: false,
-    description: 'Prompt optimization',
-    usage: 'construct optimize <agent>',
+    description: 'Sync scored Langfuse traces into eval datasets for prompt regression testing',
+    usage: 'construct eval-datasets [--limit=N]',
+    options: [
+      { flag: '--limit=N', desc: 'Maximum scored traces to sync (default: 100)' },
+    ],
+  },
+  {
+    name: 'llm-judge',
+    emoji: '⚖️',
+    category: 'Observability',
+    description: 'Run LLM-as-a-judge evaluations on unscored traces for continuous quality feedback',
+    usage: 'construct llm-judge [--limit=N] [--model=NAME]',
+    options: [
+      { flag: '--limit=N', desc: 'Maximum traces to evaluate (default: 10)' },
+      { flag: '--model=NAME', desc: 'LLM model to use for evaluation (default: claude-3-5-sonnet-20241022)' },
+    ],
+  },
+  {
+    name: 'efficiency',
+    emoji: '🧮',
+    category: 'Observability',
+    description: 'Show read efficiency, repeated files, and context-budget guidance',
+    usage: 'construct efficiency [--json]',
+    options: [
+      { flag: '--json', desc: 'Output raw JSON' },
+    ],
   },
   {
     name: 'evals',
     emoji: '🧪',
     category: 'Observability',
+    description: 'Show evaluator catalog for prompt and agent experiments',
+    usage: 'construct evals [--json]',
+    options: [
+      { flag: '--json', desc: 'Output raw JSON' },
+    ],
+  },
+  {
+    name: 'cleanup',
+    emoji: '🧹',
+    category: 'Diagnostics',
+    description: 'Release dev-agent memory pressure by cleaning stale helper and bridge processes',
+    usage: 'construct cleanup [--pressure-release] [--quiet]',
+    options: [
+      { flag: '--pressure-release', desc: 'Also terminate stale cass index processes when swap is above threshold' },
+      { flag: '--quiet', desc: 'Suppress per-process output and only act on the current policy' },
+    ],
+  },
+
+  // ── Teams & Audit ────────────────────────────────────────────────────
+  {
+    name: 'team',
+    emoji: '👥',
+    category: 'Work',
+    description: 'Team review and template listing',
+    usage: 'construct team <review|templates>',
+    subcommands: [
+      { name: 'review',    desc: 'Run telemetry-backed team performance review' },
+      { name: 'templates', desc: 'List available team templates from specialists/teams.json' },
+    ],
+  },
+  {
+    name: 'audit',
+    emoji: '🔍',
+    category: 'Diagnostics',
+    description: 'Audit Construct internals and review the mutation trail',
+    usage: 'construct audit <skills|trail>',
+    subcommands: [
+      { name: 'skills', desc: 'Audit skill files for stub headers, broken references, and missing content' },
+      { name: 'trail',  desc: 'Show the append-only audit trail of every mutation (agent, task, file, hash). Supports --verify, --agent, --tool, --since, --json.' },
+    ],
+  },
+  {
+    name: 'doc',
+    emoji: '🔏',
+    category: 'Diagnostics',
+    description: 'Verify or inspect auditability stamps on Construct-generated markdown files',
+    usage: 'construct doc <verify|install-hooks> [path] [--json]',
+    subcommands: [
+      { name: 'verify',       desc: 'Check body_hash stamps on one file or all .md files under a path. Exits non-zero if any fail.' },
+      { name: 'install-hooks', desc: 'Install the prepare-commit-msg git hook into .git/hooks/ for AI provenance trailers.' },
+    ],
+  },
+   {
+     name: 'bootstrap',
+     emoji: '🌱',
+     category: 'Work',
+     description: 'Import seed observation corpus into local memory store for cold-start acceleration',
+     usage: 'construct bootstrap [--verbose]',
+     options: [
+       { flag: '--verbose', desc: 'Print each observation imported or skipped' },
+     ],
+   },
+   {
+     name: 'reflect',
+     emoji: '🪞',
+     category: 'Work',
+     description: 'Capture improvement feedback from chat session and update Construct core',
+     usage: 'construct reflect [--target=<internal|how-tos|decisions>] [--summary=<text>]',
+     options: [
+       { flag: '--target=<internal|how-tos|decisions>', desc: 'Knowledge subdir to store feedback (default: internal)' },
+       { flag: '--summary=<text>', desc: 'Brief summary of the improvement feedback' },
+     ],
+   },
+  {
+    name: 'memory',
+    emoji: '💡',
+    category: 'Work',
     core: false,
-    description: 'Evaluator catalog',
-    usage: 'construct evals',
+    description: 'Inspect memory layer',
+    usage: 'construct memory stats|consolidate',
   },
   {
-    name: 'llm-judge',
-    emoji: '⚖️',
-    category: 'Observability',
+    name: 'drop',
+    emoji: '📥',
+    category: 'Work',
+    core: false,
+    description: 'Ingest file from Downloads/Desktop',
+    usage: 'construct drop [--list]',
+  },
+  {
+    name: 'wireframe',
+    emoji: '✏️',
+    category: 'Work',
+    core: false,
+    description: 'Generate wireframes from description',
+    usage: 'construct wireframe "<description>"',
+  },
+  {
+    name: 'ollama',
+    emoji: '🦙',
+    category: 'Integrations',
     core: false,
-    description: 'LLM-as-judge evaluations',
-    usage: 'construct llm-judge',
+    description: 'Manage local Ollama models',
+    usage: 'construct ollama status|pull|test',
   },
   
   // ── Advanced (hidden by default) ──────────────────────────────────────
@@ -487,14 +585,6 @@ export const CLI_COMMANDS = [
     description: 'Embed mode management',
     usage: 'construct embed start|stop|status',
   },
-  {
-    name: 'audit',
-    emoji: '🔍',
-    category: 'Advanced',
-    core: false,
-    description: 'Audit Construct internals',
-    usage: 'construct audit skills|trail',
-  },
   {
     name: 'backup',
     emoji: '💾',
@@ -527,14 +617,6 @@ export const CLI_COMMANDS = [
     description: 'Show version',
     usage: 'construct version | construct --version',
   },
-  {
-    name: 'cleanup',
-    emoji: '🧹',
-    category: 'Advanced',
-    core: false,
-    description: 'Clean stale processes',
-    usage: 'construct cleanup',
-  },
   {
     name: 'skills',
     emoji: '🎯',
@@ -559,6 +641,30 @@ export const CLI_COMMANDS = [
     description: 'Audit policy gates',
     usage: 'construct gates:audit',
   },
+  {
+    name: 'policy',
+    emoji: '🔒',
+    category: 'Advanced',
+    core: false,
+    description: 'Show active policy gates with enforcement details',
+    usage: 'construct policy show',
+    options: [
+      { flag: '--json', desc: 'Output as JSON' },
+    ],
+  },
+  {
+    name: 'ci',
+    emoji: '⚙️',
+    category: 'Advanced',
+    core: false,
+    description: 'Local CI mirror: run CI jobs locally or view recent run status',
+    usage: 'construct ci <preview|status|list>',
+    options: [
+      { flag: '--job=<name>', desc: 'Run a single CI job by id or name fragment' },
+      { flag: '--list',       desc: 'List all jobs without running them' },
+      { flag: '--full',       desc: 'Include Docker/Trivy steps (requires Docker daemon)' },
+    ],
+  },
   {
     name: 'provider',
     emoji: '🔌',
@@ -575,6 +681,54 @@ export const CLI_COMMANDS = [
     description: 'Check auth status',
     usage: 'construct auth:status',
   },
+  {
+    name: 'tags',
+    emoji: '🏷',
+    category: 'Work',
+    core: false,
+    description: 'Manage the controlled tag vocabulary (propose, add, deprecate, audit)',
+    usage: 'construct tags <audit|propose|add|deprecate|archive|list|proposed>',
+  },
+  {
+    name: 'scheduler',
+    emoji: '⏰',
+    category: 'Advanced',
+    core: false,
+    description: 'Manage scheduled background jobs (tag-mining, doc-hygiene, skill-rollup)',
+    usage: 'construct scheduler <list|run|runner>',
+  },
+  {
+    name: 'creds',
+    emoji: '🔑',
+    category: 'Integrations',
+    core: false,
+    description: 'Manage provider credentials (set, rotate, revoke, list)',
+    usage: 'construct creds <list|set|rotate|revoke|test>',
+  },
+  {
+    name: 'providers',
+    emoji: '🔌',
+    category: 'Integrations',
+    core: false,
+    description: 'Provider status, circuit-breaker reset, and resource discovery',
+    usage: 'construct providers <status|discover>',
+  },
+  {
+    name: 'workflow',
+    emoji: '🔄',
+    category: 'Work',
+    core: false,
+    description: 'Instantiate workflow templates (PRD-to-review chains, onboarding, handoffs)',
+    usage: 'construct workflow <list|show|new>',
+  },
+  {
+    name: 'telemetry',
+    emoji: '📊',
+    category: 'Observability',
+    core: false,
+    description: 'Query telemetry traces and latency data',
+    usage: 'construct telemetry query <latency|top-slow|errors|trace>',
+  },
 ];
 
 /** Flat list of all top-level command names (for completions). */