@hraness/kb 0.17.1

package/src/workflows/decision-context.ts

@@ -0,0 +1,81 @@
+import type { GitHistoryForNotesResult } from "../git.js";
+import type { MetadataFilter } from "../query.js";
+import {
+  packUntrustedSearchContext,
+  type KnowledgeBaseSearchResult,
+  type KnowledgeBaseSession,
+} from "../sdk.js";
+import { defineWorkflow } from "../workflow.js";
+
+export type DecisionContextInput = {
+  readonly query: string;
+  readonly filters?: readonly MetadataFilter[];
+  readonly tags?: readonly string[];
+  readonly related?: readonly string[];
+  readonly resultLimit?: number;
+  readonly maxBytes?: number;
+};
+
+export type DecisionContextOutput = {
+  /** Execution-safe envelope; retrieved note and Git fields remain inert JSON data inside. */
+  readonly context: string;
+  readonly truncated: boolean;
+};
+
+type DecisionContextResults = {
+  readonly search: KnowledgeBaseSearchResult;
+  readonly history: GitHistoryForNotesResult;
+  readonly pack: DecisionContextOutput;
+};
+
+/** Retrieve current rationale, explicit neighbors, and note history as one bounded handoff. */
+export const decisionContextWorkflow = defineWorkflow<
+  DecisionContextInput,
+  KnowledgeBaseSession,
+  DecisionContextResults,
+  "pack"
+>({
+  id: "decision-context",
+  nodes: [
+    {
+      id: "search",
+      resource: "qmd",
+      run: ({ input, kb }) => kb.search({
+        query: input.query,
+        filters: input.filters ?? [],
+        tags: input.tags ?? [],
+        graph: { related: input.related ?? [] },
+        history: false,
+        ...(input.resultLimit === undefined ? {} : { limit: input.resultLimit }),
+      }),
+    },
+    {
+      id: "history",
+      resource: "git",
+      needs: ["search"],
+      run: async ({ kb, result }) => {
+        const search = result("search");
+        return await kb.history(search.results.slice(0, 5).map(({ id }) => id), {
+          commitsPerNote: 3,
+          cochangedPathsPerCommit: 8,
+        });
+      },
+    },
+    {
+      id: "pack",
+      needs: ["search", "history"],
+      run: ({ input, result }): DecisionContextOutput => {
+        const search = result("search");
+        const enriched: KnowledgeBaseSearchResult = {
+          ...search,
+          history: result("history"),
+        };
+        const packed = packUntrustedSearchContext(enriched, {
+          ...(input.maxBytes === undefined ? {} : { maxBytes: input.maxBytes }),
+        });
+        return { context: packed.content, truncated: packed.truncated };
+      },
+    },
+  ],
+  output: "pack",
+});

package/src/workflows/explain-change.ts

@@ -0,0 +1,73 @@
+import type { GitHistorySearchResult } from "../git.js";
+import type { LinkNeighborhood } from "../navigation.js";
+import {
+  type KnowledgeBaseSearchResult,
+  type KnowledgeBaseSession,
+} from "../sdk.js";
+import { defineWorkflow } from "../workflow.js";
+
+export type ExplainChangeInput = {
+  readonly query: string;
+  readonly historyQuery?: string;
+  readonly note?: string;
+  readonly resultLimit?: number;
+  readonly historyLimit?: number;
+};
+
+export type ExplainChangeOutput = {
+  readonly rationale: KnowledgeBaseSearchResult;
+  readonly evolution: GitHistorySearchResult;
+  readonly neighborhood: LinkNeighborhood | null;
+};
+
+type ExplainChangeResults = {
+  readonly rationale: KnowledgeBaseSearchResult;
+  readonly evolution: GitHistorySearchResult;
+  readonly neighborhood: LinkNeighborhood | null;
+  readonly assemble: ExplainChangeOutput;
+};
+
+/** Search authored rationale and repository evolution concurrently. */
+export const explainChangeWorkflow = defineWorkflow<
+  ExplainChangeInput,
+  KnowledgeBaseSession,
+  ExplainChangeResults,
+  "assemble"
+>({
+  id: "explain-change",
+  nodes: [
+    {
+      id: "rationale",
+      resource: "qmd",
+      run: ({ input, kb }) => kb.search({
+        query: input.query,
+        history: false,
+        ...(input.resultLimit === undefined ? {} : { limit: input.resultLimit }),
+      }),
+    },
+    {
+      id: "evolution",
+      resource: "git",
+      run: ({ input, kb }) => kb.searchHistory({
+        query: input.historyQuery ?? input.query,
+        ...(input.historyLimit === undefined ? {} : { limit: input.historyLimit }),
+      }),
+    },
+    {
+      id: "neighborhood",
+      run: ({ input, kb }) => input.note === undefined
+        ? null
+        : kb.links(input.note, { direction: "both", depth: 1, limit: 20 }),
+    },
+    {
+      id: "assemble",
+      needs: ["rationale", "evolution", "neighborhood"],
+      run: ({ result }): ExplainChangeOutput => ({
+        rationale: result("rationale"),
+        evolution: result("evolution"),
+        neighborhood: result("neighborhood"),
+      }),
+    },
+  ],
+  output: "assemble",
+});

package/src/workflows/index.ts

@@ -0,0 +1,3 @@
+export * from "./decision-context.js";
+export * from "./explain-change.js";
+export * from "./plan-radar.js";

package/src/workflows/plan-radar.ts

@@ -0,0 +1,101 @@
+import type { GitHistoryForNotesResult } from "../git.js";
+import type { MetadataFilter, QueryRow } from "../query.js";
+import {
+  activePlanStatuses,
+  type PlanStatus,
+} from "../repository-memory";
+import {
+  type KnowledgeBaseSearchResult,
+  type KnowledgeBaseSession,
+} from "../sdk.js";
+import { defineWorkflow } from "../workflow.js";
+
+export type PlanRadarInput = {
+  readonly query: string;
+  /** Omit for all active statuses; terminal statuses request an explicit historical view. */
+  readonly status?: PlanStatus;
+  readonly repositoryScopes?: readonly string[];
+  readonly resultLimit?: number;
+};
+
+export type PlanRadarOutput = {
+  readonly plans: readonly QueryRow[];
+  readonly matches: KnowledgeBaseSearchResult;
+  readonly history: GitHistoryForNotesResult;
+};
+
+type PlanRadarResults = {
+  readonly plans: readonly QueryRow[];
+  readonly matches: KnowledgeBaseSearchResult;
+  readonly history: GitHistoryForNotesResult;
+  readonly assemble: PlanRadarOutput;
+};
+
+function planFilters(status: PlanStatus | undefined): readonly MetadataFilter[] {
+  return [
+    { kind: "equals", path: "type", value: "plan" },
+    status === undefined
+      ? { kind: "one-of", path: "status", values: activePlanStatuses }
+      : { kind: "equals", path: "status", value: status },
+  ];
+}
+
+/** Combine exact plan state with semantic matches, backlinks, and recent provenance. */
+export const planRadarWorkflow = defineWorkflow<
+  PlanRadarInput,
+  KnowledgeBaseSession,
+  PlanRadarResults,
+  "assemble"
+>({
+  id: "plan-radar",
+  nodes: [
+    {
+      id: "plans",
+      run: ({ input, kb }) => kb.list({
+        filters: planFilters(input.status),
+        repositoryScopes: input.repositoryScopes ?? [],
+        sort: { kind: "builtin", field: "inbound" },
+        direction: "desc",
+        limit: 100,
+      }),
+    },
+    {
+      id: "matches",
+      resource: "qmd",
+      run: ({ input, kb }) => kb.search({
+        query: input.query,
+        filters: planFilters(input.status),
+        repositoryScopes: input.repositoryScopes ?? [],
+        history: false,
+        ...(input.resultLimit === undefined ? {} : { limit: input.resultLimit }),
+      }),
+    },
+    {
+      id: "history",
+      resource: "git",
+      needs: ["plans", "matches"],
+      run: async ({ kb, result }) => {
+        const plans = result("plans");
+        const matches = result("matches");
+        const noteIds = [...new Set([
+          ...matches.results.map(({ id }) => id),
+          ...plans.slice(0, 10).map(({ id }) => id),
+        ])].slice(0, 15);
+        return await kb.history(noteIds, {
+          commitsPerNote: 2,
+          cochangedPathsPerCommit: 5,
+        });
+      },
+    },
+    {
+      id: "assemble",
+      needs: ["plans", "matches", "history"],
+      run: ({ result }): PlanRadarOutput => ({
+        plans: result("plans"),
+        matches: result("matches"),
+        history: result("history"),
+      }),
+    },
+  ],
+  output: "assemble",
+});