gsd-pi 2.75.0-dev.b6ad8c5f7 → 2.75.0-dev.e41b70b10

package/src/resources/extensions/gsd/tools/memory-tools.ts

@@ -0,0 +1,380 @@
+// GSD Memory Tools — Phase 1 executors for capture_thought, memory_query, gsd_graph
+//
+// These executors back the three memory-layer tools the LLM can call at any
+// point in a session. They build on the existing `memory-store.ts` layer
+// (SQLite memories table) and degrade gracefully when the DB is unavailable.
+//
+// Phase 1 scope:
+//   - capture_thought → create a memory with the caller-supplied category/content
+//   - memory_query    → keyword-filtered, score-ranked listing of active memories
+//   - gsd_graph       → returns a memory and its supersedes edges only (Phase 4 adds memory_relations)
+
+import { _getAdapter, isDbAvailable } from "../gsd-db.js";
+import {
+  createMemory,
+  getActiveMemoriesRanked,
+  queryMemoriesRanked,
+  reinforceMemory,
+} from "../memory-store.js";
+import type { Memory, RankedMemory } from "../memory-store.js";
+import { traverseGraph } from "../memory-relations.js";
+
+// ─── Shared result shape (matches tools/workflow-tool-executors.ts) ─────────
+
+export interface ToolExecutionResult {
+  content: Array<{ type: "text"; text: string }>;
+  details: Record<string, unknown>;
+  isError?: boolean;
+}
+
+function dbUnavailable(operation: string): ToolExecutionResult {
+  return {
+    content: [
+      {
+        type: "text",
+        text: "Error: GSD database is not available. Memory tools require an initialized .gsd/ project.",
+      },
+    ],
+    details: { operation, error: "db_unavailable" },
+    isError: true,
+  };
+}
+
+// ─── capture_thought ────────────────────────────────────────────────────────
+
+export interface MemoryCaptureParams {
+  category: string;
+  content: string;
+  confidence?: number;
+  tags?: string[];
+  scope?: string;
+}
+
+const VALID_CATEGORIES = new Set([
+  "architecture",
+  "convention",
+  "gotcha",
+  "preference",
+  "environment",
+  "pattern",
+]);
+
+export function executeMemoryCapture(params: MemoryCaptureParams): ToolExecutionResult {
+  if (!isDbAvailable()) return dbUnavailable("memory_capture");
+
+  const category = (params.category ?? "").trim().toLowerCase();
+  const content = (params.content ?? "").trim();
+  if (!category || !content) {
+    return {
+      content: [{ type: "text", text: "Error: category and content are required." }],
+      details: { operation: "memory_capture", error: "missing_fields" },
+      isError: true,
+    };
+  }
+  if (!VALID_CATEGORIES.has(category)) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error: invalid category "${category}". Must be one of: ${[...VALID_CATEGORIES].join(", ")}.`,
+        },
+      ],
+      details: { operation: "memory_capture", error: "invalid_category" },
+      isError: true,
+    };
+  }
+  const confidence = clampConfidence(params.confidence);
+  const scope = normalizeScope(params.scope);
+  const tags = normalizeTags(params.tags);
+
+  const id = createMemory({ category, content, confidence, scope, tags });
+  if (!id) {
+    return {
+      content: [{ type: "text", text: "Error: failed to create memory." }],
+      details: { operation: "memory_capture", error: "create_failed" },
+      isError: true,
+    };
+  }
+
+  return {
+    content: [{ type: "text", text: `Captured ${id} (${category}): ${content}` }],
+    details: { operation: "memory_capture", id, category, confidence, scope, tags },
+  };
+}
+
+function normalizeScope(value: unknown): string {
+  if (typeof value !== "string") return "project";
+  const trimmed = value.trim();
+  return trimmed.length === 0 ? "project" : trimmed;
+}
+
+function normalizeTags(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((t): t is string => typeof t === "string" && t.trim().length > 0).slice(0, 10);
+}
+
+function clampConfidence(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return 0.8;
+  if (value < 0.1) return 0.1;
+  if (value > 0.99) return 0.99;
+  return value;
+}
+
+// ─── memory_query ───────────────────────────────────────────────────────────
+
+export interface MemoryQueryParams {
+  query: string;
+  k?: number;
+  category?: string;
+  scope?: string;
+  tag?: string;
+  include_superseded?: boolean;
+  reinforce_hits?: boolean;
+}
+
+export interface MemoryQueryHit {
+  id: string;
+  category: string;
+  content: string;
+  confidence: number;
+  hit_count: number;
+  score: number;
+  reason: "keyword" | "semantic" | "both" | "ranked";
+  keyword_rank: number | null;
+  semantic_rank: number | null;
+}
+
+export function executeMemoryQuery(params: MemoryQueryParams): ToolExecutionResult {
+  if (!isDbAvailable()) return dbUnavailable("memory_query");
+
+  const query = (params.query ?? "").trim();
+  const k = clampTopK(params.k, 10);
+  const includeSuperseded = params.include_superseded === true;
+  const category = params.category?.trim().toLowerCase() || undefined;
+  const scopeFilter = params.scope?.trim() || undefined;
+  const tagFilter = params.tag?.trim().toLowerCase() || undefined;
+
+  try {
+    let ranked: RankedMemory[] = [];
+    if (query) {
+      ranked = queryMemoriesRanked({
+        query,
+        k,
+        category,
+        scope: scopeFilter,
+        tag: tagFilter,
+        include_superseded: includeSuperseded,
+      });
+    } else {
+      const candidates: Memory[] = includeSuperseded
+        ? includeSupersededMemories(getActiveMemoriesRanked(200))
+        : getActiveMemoriesRanked(200);
+      ranked = candidates
+        .filter((m) => {
+          if (category && m.category.toLowerCase() !== category) return false;
+          if (scopeFilter && m.scope !== scopeFilter) return false;
+          if (tagFilter && !m.tags.map((t) => t.toLowerCase()).includes(tagFilter)) return false;
+          return true;
+        })
+        .slice(0, k)
+        .map((memory) => ({
+          memory,
+          score: memory.confidence * (1 + memory.hit_count * 0.1),
+          keywordRank: null,
+          semanticRank: null,
+          confidenceBoost: memory.confidence * (1 + memory.hit_count * 0.1),
+          reason: "ranked" as const,
+        }));
+    }
+
+    const hits: MemoryQueryHit[] = ranked.map((r) => ({
+      id: r.memory.id,
+      category: r.memory.category,
+      content: r.memory.content,
+      confidence: r.memory.confidence,
+      hit_count: r.memory.hit_count,
+      score: r.score,
+      reason: r.reason,
+      keyword_rank: r.keywordRank,
+      semantic_rank: r.semanticRank,
+    }));
+
+    if (params.reinforce_hits) {
+      for (const h of hits) reinforceMemory(h.id);
+    }
+
+    const summary = hits.length === 0
+      ? "No matching memories."
+      : hits.map((h) => `- [${h.id}] (${h.category}) ${h.content}`).join("\n");
+
+    return {
+      content: [{ type: "text", text: summary }],
+      details: {
+        operation: "memory_query",
+        query,
+        k,
+        returned: hits.length,
+        hits,
+      },
+    };
+  } catch (err) {
+    return {
+      content: [{ type: "text", text: `Error: memory query failed: ${(err as Error).message}` }],
+      details: { operation: "memory_query", error: (err as Error).message },
+      isError: true,
+    };
+  }
+}
+
+function clampTopK(value: unknown, fallback: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  if (value < 1) return 1;
+  if (value > 50) return 50;
+  return Math.floor(value);
+}
+
+function includeSupersededMemories(rankedActive: Memory[]): Memory[] {
+  const adapter = _getAdapter();
+  if (!adapter) return rankedActive;
+  try {
+    const rows = adapter.prepare("SELECT * FROM memories").all();
+    return rows.map((row) => {
+      let tags: string[] = [];
+      if (typeof row["tags"] === "string") {
+        try {
+          const parsed = JSON.parse(row["tags"] as string);
+          if (Array.isArray(parsed)) tags = parsed.filter((t): t is string => typeof t === "string");
+        } catch {
+          /* leave empty */
+        }
+      }
+      return {
+        seq: row["seq"] as number,
+        id: row["id"] as string,
+        category: row["category"] as string,
+        content: row["content"] as string,
+        confidence: row["confidence"] as number,
+        source_unit_type: (row["source_unit_type"] as string) ?? null,
+        source_unit_id: (row["source_unit_id"] as string) ?? null,
+        created_at: row["created_at"] as string,
+        updated_at: row["updated_at"] as string,
+        superseded_by: (row["superseded_by"] as string) ?? null,
+        hit_count: row["hit_count"] as number,
+        scope: (row["scope"] as string) ?? "project",
+        tags,
+      };
+    });
+  } catch {
+    return rankedActive;
+  }
+}
+
+// ─── gsd_graph ──────────────────────────────────────────────────────────────
+
+export interface GsdGraphParams {
+  mode: "build" | "query";
+  memoryId?: string;
+  depth?: number;
+  rel?: string;
+}
+
+export interface GraphNode {
+  id: string;
+  category: string;
+  content: string;
+  confidence: number;
+}
+
+export interface GraphEdge {
+  from: string;
+  to: string;
+  rel: string;
+  confidence: number;
+}
+
+export function executeGsdGraph(params: GsdGraphParams): ToolExecutionResult {
+  if (!isDbAvailable()) return dbUnavailable("gsd_graph");
+
+  if (params.mode === "build") {
+    // The extractor emits LINK actions incrementally (Phase 4). There is no
+    // batch rebuild step to run today — ingest artifacts via `/gsd memory
+    // extract <SRC-...>` and the next extraction turn will add edges.
+    return {
+      content: [
+        {
+          type: "text",
+          text:
+            "gsd_graph build acknowledged. Graph edges are populated incrementally by memory " +
+            "extraction (including LINK actions). Use `/gsd memory extract <SRC-...>` to trigger " +
+            "extraction against a specific ingested source.",
+        },
+      ],
+      details: { operation: "gsd_graph", mode: "build", built: 0 },
+    };
+  }
+
+  if (params.mode !== "query") {
+    return {
+      content: [{ type: "text", text: `Error: unknown mode "${params.mode}". Must be "build" or "query".` }],
+      details: { operation: "gsd_graph", error: "invalid_mode" },
+      isError: true,
+    };
+  }
+
+  const memoryId = params.memoryId?.trim();
+  if (!memoryId) {
+    return {
+      content: [{ type: "text", text: "Error: memoryId is required for mode=query." }],
+      details: { operation: "gsd_graph", error: "missing_memory_id" },
+      isError: true,
+    };
+  }
+
+  try {
+    const graph = traverseGraph(memoryId, clampDepth(params.depth));
+    const rel = params.rel?.trim().toLowerCase() || null;
+    const edges = rel ? graph.edges.filter((e) => e.rel === rel) : graph.edges;
+    const relevantIds = new Set<string>([memoryId]);
+    for (const e of edges) {
+      relevantIds.add(e.from);
+      relevantIds.add(e.to);
+    }
+    const nodes = graph.nodes.filter((n) => relevantIds.has(n.id));
+
+    if (nodes.length === 0) {
+      return {
+        content: [{ type: "text", text: `No memory found with id ${memoryId}.` }],
+        details: { operation: "gsd_graph", mode: "query", memoryId, nodes: [], edges: [] },
+      };
+    }
+
+    const summary = [
+      `Memory ${memoryId} — ${nodes.length} node(s), ${edges.length} edge(s).`,
+      ...nodes.map((n) => `  [${n.id}] (${n.category}) ${n.content}`),
+      ...edges.map((e) => `  ${e.from} --${e.rel}-> ${e.to}`),
+    ].join("\n");
+    return {
+      content: [{ type: "text", text: summary }],
+      details: {
+        operation: "gsd_graph",
+        mode: "query",
+        memoryId,
+        nodes: nodes.map((n) => ({ id: n.id, category: n.category, content: n.content })),
+        edges: edges.map((e) => ({ from: e.from, to: e.to, rel: e.rel })),
+      },
+    };
+  } catch (err) {
+    return {
+      content: [{ type: "text", text: `Error: graph query failed: ${(err as Error).message}` }],
+      details: { operation: "gsd_graph", error: (err as Error).message },
+      isError: true,
+    };
+  }
+}
+
+function clampDepth(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return 1;
+  if (value < 0) return 0;
+  if (value > 5) return 5;
+  return Math.floor(value);
+}

package/src/resources/extensions/gsd/tools/workflow-tool-executors.ts

@@ -10,6 +10,8 @@ import {
 } from "../gsd-db.js";
 import { GATE_REGISTRY } from "../gate-registry.js";
 import { saveArtifactToDb } from "../db-writer.js";
+import { resolveMilestoneFile, resolveSliceFile } from "../paths.js";
+import { unlinkSync } from "node:fs";
 import type { CompleteMilestoneParams } from "./complete-milestone.js";
 import { handleCompleteMilestone } from "./complete-milestone.js";
 import { handleCompleteTask } from "./complete-task.js";
@@ -103,6 +105,18 @@ export async function executeSummarySave(
       },
       basePath,
     );
+
+    if (params.artifact_type === "CONTEXT" && !params.task_id) {
+      try {
+        const draftFile = params.slice_id
+          ? resolveSliceFile(basePath, params.milestone_id, params.slice_id, "CONTEXT-DRAFT")
+          : resolveMilestoneFile(basePath, params.milestone_id, "CONTEXT-DRAFT");
+        if (draftFile) unlinkSync(draftFile);
+      } catch (e) {
+        logWarning("tool", `CONTEXT-DRAFT.md unlink failed: ${(e as Error).message}`);
+      }
+    }
+
     return {
       content: [{ type: "text", text: `Saved ${params.artifact_type} artifact to ${relativePath}` }],
       details: { operation: "save_summary", path: relativePath, artifact_type: params.artifact_type },

package/src/resources/extensions/gsd/workflow-logger.ts

@@ -54,7 +54,9 @@ export type LogComponent =
   | "registry"      // Rule registry hook state
   | "renderer"      // Markdown renderer and projections
   | "safety"        // LLM safety harness
-  | "ecosystem";    // GSD ecosystem extension loader and dispatch
+  | "ecosystem"     // GSD ecosystem extension loader and dispatch
+  | "memory-embeddings" // Memory layer embedding generation
+  | "memory-ingest";    // Memory layer ingestion pipeline
 
 export interface LogEntry {
   ts: string;

package/src/resources/extensions/search-the-web/command-search-provider.ts

@@ -8,6 +8,7 @@
  * All provider logic lives in provider.ts (S01) — this is pure UI wiring.
  */
 
+import { isAnthropicApi } from '@gsd/pi-ai'
 import type { ExtensionAPI } from '@gsd/pi-coding-agent'
 import type { AutocompleteItem } from '@gsd/pi-tui'
 import {
@@ -90,7 +91,9 @@ export function registerSearchProviderCommand(pi: ExtensionAPI): void {
 
       setSearchProviderPreference(chosen)
       const effective = resolveSearchProvider()
-      const isAnthropic = ctx.model?.provider === 'anthropic'
+      // Gate on api (#4478 / ADR-012): covers claude-code, anthropic-vertex, and
+      // other Anthropic-fronting transports — not just the plain `anthropic` provider.
+      const isAnthropic = isAnthropicApi(ctx.model)
       const nativeNote = isAnthropic ? '\nNote: Native Anthropic web search is also active (automatic, no API key needed).' : ''
       ctx.ui.notify(
         `Search provider set to ${chosen}. Effective provider: ${effective ?? 'none (no API keys)'}${nativeNote}`,

package/src/resources/extensions/search-the-web/native-search.ts

@@ -5,6 +5,7 @@
  * the heavy tool-registration modules.
  */
 
+import { isAnthropicApi } from "@gsd/pi-ai";
 import { resolveSearchProviderFromPreferences } from "../gsd/preferences.js";
 
 /** Tool names for the Brave-backed custom search tools */
@@ -94,7 +95,10 @@ export function registerNativeSearchHooks(pi: NativeSearchPI): { getIsAnthropic:
   pi.on("model_select", async (event: any, ctx: any) => {
     modelSelectFired = true;
     const wasAnthropic = isAnthropicProvider;
-    isAnthropicProvider = event.model.provider === "anthropic";
+    // Gate on `api` not `provider` (#4478 / ADR-012): covers claude-code OAuth,
+    // anthropic-vertex, and Vercel-gateway-hosted Anthropic — all serve the
+    // Messages API and accept the native web_search tool.
+    isAnthropicProvider = isAnthropicApi(event.model);
 
     const hasBrave = !!process.env.BRAVE_API_KEY;
 
@@ -139,9 +143,15 @@ export function registerNativeSearchHooks(pi: NativeSearchPI): { getIsAnthropic:
     // the model_select flag, then to the model name heuristic (last resort).
     // The model name heuristic is needed for session restores where
     // modelsAreEqual suppresses model_select AND the SDK doesn't pass model.
-    const eventModel = event.model as { provider: string } | undefined;
+    const eventModel = event.model as { provider?: string; api?: string } | undefined;
     let isAnthropic: boolean;
-    if (eventModel?.provider) {
+    if (eventModel?.api) {
+      // Preferred path: gate on wire protocol (#4478 / ADR-012).
+      isAnthropic = isAnthropicApi(eventModel);
+    } else if (eventModel?.provider) {
+      // Fallback for event shapes that carry provider but not api — only plain
+      // `anthropic` maps unambiguously without the api field. Other Anthropic
+      // transports will arrive via the modelSelectFired or model-name branch.
       isAnthropic = eventModel.provider === "anthropic";
     } else if (modelSelectFired) {
       isAnthropic = isAnthropicProvider;

package/src/resources/extensions/gsd/tests/onboarding-handler-loader.test.ts

@@ -1,41 +0,0 @@
-import test from "node:test"
-import assert from "node:assert/strict"
-import { readFileSync } from "node:fs"
-import { join } from "node:path"
-
-test("onboarding handler resolves wizard module from deployed runtime paths", () => {
-  const source = readFileSync(
-    join(import.meta.dirname, "..", "commands", "handlers", "onboarding.ts"),
-    "utf-8",
-  )
-
-  assert.match(
-    source,
-    /process\.env\.GSD_PKG_ROOT/,
-    "handler should probe GSD_PKG_ROOT for deployed dist\/onboarding.js",
-  )
-
-  assert.match(
-    source,
-    /process\.argv\[1\]/,
-    "handler should fall back to argv-derived package root when env is missing",
-  )
-
-  assert.match(
-    source,
-    /candidates\.push\("\.\.\/\.\.\/\.\.\/\.\.\/\.\.\/onboarding\.js"\)/,
-    "handler must keep the relative source\/dist fallback",
-  )
-
-  assert.match(
-    source,
-    /for \(const specifier of candidates\)/,
-    "handler should try candidates in order",
-  )
-
-  assert.match(
-    source,
-    /Failed to load onboarding wizard module/,
-    "handler should throw a diagnostic error when no candidate resolves",
-  )
-})