@vellumai/assistant 0.8.7 → 0.8.8-dev.202606052332.17fc8ea

package/src/memory/llm-usage-store.ts

@@ -9,6 +9,13 @@ import type {
 import { APP_VERSION } from "../version.js";
 import { getDb } from "./db-connection.js";
 import { rawAll } from "./raw-query.js";
+import {
+  buildScheduleAttributionSubquery,
+  buildScheduleRunWindowExists,
+  normalizeScheduleAttributionFilter,
+  type ScheduleAttributionFilter,
+  type ScheduleAttributionSqlParam,
+} from "./schedule-attribution-sql.js";
 import { conversations, llmUsageEvents } from "./schema.js";
 import {
   bucketEventsByDay,
@@ -282,6 +289,8 @@ export interface UsageTimeRange {
   to: number;
 }
 
+export type UsageAggregationFilter = ScheduleAttributionFilter;
+
 /** Aggregate totals across a time range. */
 export interface UsageTotals {
   /** Direct input tokens only; cache traffic is reported separately below. */
@@ -332,14 +341,15 @@ export interface UsageGroupBreakdown {
   /**
    * Stable identifier for the group. Populated with the conversation id when
    * `groupBy === "conversation"` (and `null` for that mode's "Other" bucket,
-   * which aggregates events with no conversation id). For all other group-bys
-   * this is always `null`.
+   * which aggregates events with no conversation id) or with the schedule id
+   * when `groupBy === "schedule"` (and `null` for "Other"). For all other
+   * group-bys this is always `null`.
    */
   groupId: string | null;
   /**
    * Raw stored grouping value for dimensions whose display label may differ
-   * from storage (`call_site`, `inference_profile`). Omitted for legacy
-   * dimensions where `group` is already the raw value.
+   * from storage (`call_site`, `inference_profile`, `schedule`). Omitted for
+   * legacy dimensions where `group` is already the raw value.
    */
   groupKey?: string | null;
   /** Direct input tokens only; cache traffic is reported separately below. */
@@ -367,6 +377,7 @@ interface TotalsRow {
 interface GroupRow {
   group_key: string | null;
   group_id: string | null;
+  group_label: string | null;
   total_input_tokens: number;
   total_output_tokens: number;
   total_cache_creation_tokens: number;
@@ -375,6 +386,39 @@ interface GroupRow {
   event_count: number;
 }
 
+type UsageQueryParam = ScheduleAttributionSqlParam;
+
+function normalizeUsageAggregationFilter(
+  filter?: UsageAggregationFilter,
+): UsageAggregationFilter {
+  return normalizeScheduleAttributionFilter(filter);
+}
+
+function buildUsageAggregationWhere(
+  range: UsageTimeRange,
+  filter?: UsageAggregationFilter,
+  eventAlias?: string,
+  now: number = Date.now(),
+): { sql: string; params: UsageQueryParam[] } {
+  const normalized = normalizeUsageAggregationFilter(filter);
+  const eventTable = eventAlias ?? "llm_usage_events";
+  const createdAt = `${eventTable}.created_at`;
+  const clauses = [`${createdAt} >= ? AND ${createdAt} <= ?`];
+  const params: UsageQueryParam[] = [range.from, range.to];
+
+  if (normalized.scheduleId) {
+    const exists = buildScheduleRunWindowExists({
+      eventAlias: eventTable,
+      filter: normalized,
+      now,
+    });
+    clauses.push(exists.sql);
+    params.push(...exists.params);
+  }
+
+  return { sql: clauses.join(" AND "), params };
+}
+
 /**
  * Return aggregate usage for a single conversation (e.g. a subagent).
  */
@@ -406,10 +450,38 @@ export function getConversationUsageTotals(conversationId: string): {
   };
 }
 
+export function getUsageCostForConversationWindow({
+  conversationId,
+  from,
+  to,
+}: {
+  conversationId: string;
+  from: number;
+  to: number;
+}): number {
+  const rows = rawAll<{ total_cost: number | null }>(
+    /*sql*/ `
+    SELECT COALESCE(SUM(estimated_cost_usd), 0) AS total_cost
+    FROM llm_usage_events
+    WHERE conversation_id = ?1
+      AND created_at >= ?2
+      AND created_at <= ?3
+    `,
+    conversationId,
+    from,
+    to,
+  );
+  return rows[0]?.total_cost ?? 0;
+}
+
 /**
  * Return aggregate totals for all usage events within the given time range.
  */
-export function getUsageTotals(range: UsageTimeRange): UsageTotals {
+export function getUsageTotals(
+  range: UsageTimeRange,
+  filter?: UsageAggregationFilter,
+): UsageTotals {
+  const where = buildUsageAggregationWhere(range, filter);
   const rows = rawAll<TotalsRow>(
     /*sql*/ `
     SELECT
@@ -422,10 +494,9 @@ export function getUsageTotals(range: UsageTimeRange): UsageTotals {
       COUNT(CASE WHEN pricing_status = 'priced' THEN 1 END)       AS priced_event_count,
       COUNT(CASE WHEN pricing_status = 'unpriced' THEN 1 END)     AS unpriced_event_count
     FROM llm_usage_events
-    WHERE created_at >= ?1 AND created_at <= ?2
+    WHERE ${where.sql}
     `,
-    range.from,
-    range.to,
+    ...where.params,
   );
   const row = rows[0];
   return {
@@ -441,7 +512,11 @@ export function getUsageTotals(range: UsageTimeRange): UsageTotals {
 }
 
 /** Fetch raw events in a time range for in-memory bucketing. */
-function fetchRawBucketRows(range: UsageTimeRange): UsageEventBucketRow[] {
+function fetchRawBucketRows(
+  range: UsageTimeRange,
+  filter?: UsageAggregationFilter,
+): UsageEventBucketRow[] {
+  const where = buildUsageAggregationWhere(range, filter);
   return rawAll<UsageEventBucketRow>(
     /*sql*/ `
     SELECT
@@ -451,11 +526,10 @@ function fetchRawBucketRows(range: UsageTimeRange): UsageEventBucketRow[] {
       estimated_cost_usd,
       llm_call_count
     FROM llm_usage_events
-    WHERE created_at >= ?1 AND created_at <= ?2
+    WHERE ${where.sql}
     ORDER BY created_at ASC
     `,
-    range.from,
-    range.to,
+    ...where.params,
   );
 }
 
@@ -482,8 +556,9 @@ export function getUsageDayBuckets(
   range: UsageTimeRange,
   tz: string = "UTC",
   options: UsageBucketOptions = {},
+  filter?: UsageAggregationFilter,
 ): UsageDayBucket[] {
-  const rows = fetchRawBucketRows(range);
+  const rows = fetchRawBucketRows(range, filter);
   return bucketEventsByDay(rows, range, tz, options);
 }
 
@@ -500,8 +575,9 @@ export function getUsageHourBuckets(
   range: UsageTimeRange,
   tz: string = "UTC",
   options: UsageBucketOptions = {},
+  filter?: UsageAggregationFilter,
 ): UsageDayBucket[] {
-  const rows = fetchRawBucketRows(range);
+  const rows = fetchRawBucketRows(range, filter);
   return bucketEventsByHour(rows, range, tz, options);
 }
 
@@ -512,6 +588,7 @@ export const USAGE_GROUP_BY_DIMENSIONS = [
   "conversation",
   "call_site",
   "inference_profile",
+  "schedule",
 ] as const;
 
 export type GroupByDimension = (typeof USAGE_GROUP_BY_DIMENSIONS)[number];
@@ -522,10 +599,11 @@ export const USAGE_SERIES_GROUP_BY_DIMENSIONS = [
   "model",
   "call_site",
   "inference_profile",
+  "schedule",
 ] as const satisfies readonly GroupByDimension[];
 
 const GROUP_BY_COLUMNS: Record<
-  Exclude<GroupByDimension, "conversation">,
+  Exclude<GroupByDimension, "conversation" | "schedule">,
   string
 > = {
   actor: "actor",
@@ -550,9 +628,11 @@ function mapGroupRow(
   groupBy: GroupByDimension,
 ): UsageGroupBreakdown {
   const includeGroupKey =
-    groupBy === "call_site" || groupBy === "inference_profile";
+    groupBy === "call_site" ||
+    groupBy === "inference_profile" ||
+    groupBy === "schedule";
   return {
-    group: displayUsageGroup(groupBy, row.group_key),
+    group: row.group_label ?? displayUsageGroup(groupBy, row.group_key),
     groupId: row.group_id,
     ...(includeGroupKey ? { groupKey: row.group_key } : {}),
     totalInputTokens: row.total_input_tokens,
@@ -571,12 +651,16 @@ function mapGroupRow(
 export function getUsageGroupBreakdown(
   range: UsageTimeRange,
   groupBy: GroupByDimension,
+  filter?: UsageAggregationFilter,
 ): UsageGroupBreakdown[] {
   // Runtime allowlist — defense-in-depth against SQL injection via type assertions.
   assertGroupByDimension(groupBy);
 
+  const normalizedFilter = normalizeUsageAggregationFilter(filter);
+
   // Conversation grouping requires a JOIN with conversations to resolve titles.
   if (groupBy === "conversation") {
+    const where = buildUsageAggregationWhere(range, normalizedFilter, "e");
     const rows = rawAll<GroupRow>(
       /*sql*/ `
       SELECT
@@ -584,6 +668,7 @@ export function getUsageGroupBreakdown(
              ELSE COALESCE(c.title, 'Untitled')
         END AS group_key,
         e.conversation_id                                AS group_id,
+        NULL                                             AS group_label,
         COALESCE(SUM(e.input_tokens), 0)                 AS total_input_tokens,
         COALESCE(SUM(e.output_tokens), 0)                AS total_output_tokens,
         COALESCE(SUM(e.cache_creation_input_tokens), 0)  AS total_cache_creation_tokens,
@@ -592,36 +677,81 @@ export function getUsageGroupBreakdown(
         COALESCE(SUM(COALESCE(e.llm_call_count, 1)), 0)  AS event_count
       FROM llm_usage_events e
       LEFT JOIN conversations c ON e.conversation_id = c.id
-      WHERE e.created_at >= ?1 AND e.created_at <= ?2
+      WHERE ${where.sql}
       GROUP BY e.conversation_id
       ORDER BY total_estimated_cost_usd DESC
       LIMIT 50
       `,
-      range.from,
-      range.to,
+      ...where.params,
+    );
+    return rows.map((row) => mapGroupRow(row, groupBy));
+  }
+
+  if (groupBy === "schedule") {
+    const now = Date.now();
+    const where = buildUsageAggregationWhere(range, normalizedFilter, "e", now);
+    const groupKeySubquery = buildScheduleAttributionSubquery({
+      eventAlias: "e",
+      filter: normalizedFilter,
+      now,
+      selectExpression: "schedule_attr_runs.job_id",
+    });
+    const rows = rawAll<GroupRow>(
+      /*sql*/ `
+      WITH schedule_usage AS (
+        SELECT
+          e.input_tokens,
+          e.output_tokens,
+          e.cache_creation_input_tokens,
+          e.cache_read_input_tokens,
+          e.estimated_cost_usd,
+          e.llm_call_count,
+          ${groupKeySubquery.sql} AS group_key
+        FROM llm_usage_events e
+        WHERE ${where.sql}
+      )
+      SELECT
+        schedule_usage.group_key                                      AS group_key,
+        schedule_usage.group_key                                      AS group_id,
+        MAX(schedule_group_jobs.name)                                 AS group_label,
+        COALESCE(SUM(schedule_usage.input_tokens), 0)                 AS total_input_tokens,
+        COALESCE(SUM(schedule_usage.output_tokens), 0)                AS total_output_tokens,
+        COALESCE(SUM(schedule_usage.cache_creation_input_tokens), 0)  AS total_cache_creation_tokens,
+        COALESCE(SUM(schedule_usage.cache_read_input_tokens), 0)      AS total_cache_read_tokens,
+        COALESCE(SUM(schedule_usage.estimated_cost_usd), 0)           AS total_estimated_cost_usd,
+        COALESCE(SUM(COALESCE(schedule_usage.llm_call_count, 1)), 0)  AS event_count
+      FROM schedule_usage
+      LEFT JOIN cron_jobs schedule_group_jobs
+        ON schedule_group_jobs.id = schedule_usage.group_key
+      GROUP BY schedule_usage.group_key
+      ORDER BY total_estimated_cost_usd DESC
+      `,
+      ...groupKeySubquery.params,
+      ...where.params,
     );
     return rows.map((row) => mapGroupRow(row, groupBy));
   }
 
   const column = GROUP_BY_COLUMNS[groupBy];
+  const where = buildUsageAggregationWhere(range, normalizedFilter, "e");
   const rows = rawAll<GroupRow>(
     /*sql*/ `
     SELECT
-      ${column}                                      AS group_key,
-      NULL                                           AS group_id,
-      COALESCE(SUM(input_tokens), 0)                 AS total_input_tokens,
-      COALESCE(SUM(output_tokens), 0)                AS total_output_tokens,
-      COALESCE(SUM(cache_creation_input_tokens), 0)  AS total_cache_creation_tokens,
-      COALESCE(SUM(cache_read_input_tokens), 0)      AS total_cache_read_tokens,
-      COALESCE(SUM(estimated_cost_usd), 0)           AS total_estimated_cost_usd,
-      COALESCE(SUM(COALESCE(llm_call_count, 1)), 0)  AS event_count
-    FROM llm_usage_events
-    WHERE created_at >= ?1 AND created_at <= ?2
-    GROUP BY ${column}
+      e.${column}                                      AS group_key,
+      NULL                                             AS group_id,
+      NULL                                             AS group_label,
+      COALESCE(SUM(e.input_tokens), 0)                 AS total_input_tokens,
+      COALESCE(SUM(e.output_tokens), 0)                AS total_output_tokens,
+      COALESCE(SUM(e.cache_creation_input_tokens), 0)  AS total_cache_creation_tokens,
+      COALESCE(SUM(e.cache_read_input_tokens), 0)      AS total_cache_read_tokens,
+      COALESCE(SUM(e.estimated_cost_usd), 0)           AS total_estimated_cost_usd,
+      COALESCE(SUM(COALESCE(e.llm_call_count, 1)), 0)  AS event_count
+    FROM llm_usage_events e
+    WHERE ${where.sql}
+    GROUP BY e.${column}
     ORDER BY total_estimated_cost_usd DESC
     `,
-    range.from,
-    range.to,
+    ...where.params,
   );
   return rows.map((row) => mapGroupRow(row, groupBy));
 }
@@ -632,29 +762,73 @@ export function getUsageGroupedSeries(
   granularity: UsageGranularity,
   tz: string = "UTC",
   options: UsageBucketOptions = {},
+  filter?: UsageAggregationFilter,
 ): UsageGroupedSeriesBucket[] {
   assertGroupByDimension(groupBy);
   if (groupBy === "conversation") {
     throw new Error("Grouped usage series does not support conversation");
   }
 
-  const column = GROUP_BY_COLUMNS[groupBy];
-  const rows = rawAll<UsageGroupedBucketRow>(
-    /*sql*/ `
-    SELECT
-      created_at,
-      input_tokens,
-      output_tokens,
-      estimated_cost_usd,
-      llm_call_count,
-      ${column} AS group_key
-    FROM llm_usage_events
-    WHERE created_at >= ?1 AND created_at <= ?2
-    ORDER BY created_at ASC
-    `,
-    range.from,
-    range.to,
-  );
+  const normalizedFilter = normalizeUsageAggregationFilter(filter);
+  let rows: UsageGroupedBucketRow[];
+
+  if (groupBy === "schedule") {
+    const now = Date.now();
+    const where = buildUsageAggregationWhere(range, normalizedFilter, "e", now);
+    const groupKeySubquery = buildScheduleAttributionSubquery({
+      eventAlias: "e",
+      filter: normalizedFilter,
+      now,
+      selectExpression: "schedule_attr_runs.job_id",
+    });
+    rows = rawAll<UsageGroupedBucketRow>(
+      /*sql*/ `
+      WITH schedule_usage AS (
+        SELECT
+          e.created_at,
+          e.input_tokens,
+          e.output_tokens,
+          e.estimated_cost_usd,
+          e.llm_call_count,
+          ${groupKeySubquery.sql} AS group_key
+        FROM llm_usage_events e
+        WHERE ${where.sql}
+      )
+      SELECT
+        schedule_usage.created_at,
+        schedule_usage.input_tokens,
+        schedule_usage.output_tokens,
+        schedule_usage.estimated_cost_usd,
+        schedule_usage.llm_call_count,
+        schedule_usage.group_key,
+        schedule_group_jobs.name AS group_label
+      FROM schedule_usage
+      LEFT JOIN cron_jobs schedule_group_jobs
+        ON schedule_group_jobs.id = schedule_usage.group_key
+      ORDER BY schedule_usage.created_at ASC
+      `,
+      ...groupKeySubquery.params,
+      ...where.params,
+    );
+  } else {
+    const column = GROUP_BY_COLUMNS[groupBy];
+    const where = buildUsageAggregationWhere(range, normalizedFilter, "e");
+    rows = rawAll<UsageGroupedBucketRow>(
+      /*sql*/ `
+      SELECT
+        e.created_at,
+        e.input_tokens,
+        e.output_tokens,
+        e.estimated_cost_usd,
+        e.llm_call_count,
+        e.${column} AS group_key
+      FROM llm_usage_events e
+      WHERE ${where.sql}
+      ORDER BY e.created_at ASC
+      `,
+      ...where.params,
+    );
+  }
 
   return bucketGroupedUsageEvents(rows, range, tz, {
     ...options,

package/src/memory/migrations/222-strip-placeholder-sentinels-from-messages.ts

@@ -1,15 +1,16 @@
-import { isPlaceholderSentinelText } from "../../providers/anthropic/client.js";
+import { isPlaceholderSentinelText } from "../../providers/placeholder-sentinels.js";
 import type { DrizzleDb } from "../db-connection.js";
 import { getSqliteFrom } from "../db-connection.js";
 import { withCrashRecovery } from "./validate-migration-state.js";
 
 /**
- * Strip Anthropic provider placeholder sentinel text blocks from persisted
- * assistant messages.
+ * Strip provider placeholder sentinel text blocks from persisted assistant
+ * messages.
  *
  * PLACEHOLDER_EMPTY_TURN and PLACEHOLDER_BLOCKS_OMITTED are injected into
- * outbound Anthropic request bodies to preserve role alternation when an
- * assistant turn would otherwise be empty. They are never supposed to be
+ * outbound provider request bodies (Anthropic role alternation, OpenAI-
+ * compatible "content or tool_calls" constraint) when an assistant turn would
+ * otherwise be empty. They are never supposed to be
  * persisted, but a leak path caused them to be stored in the messages table
  * where they render in chat bubbles as bold "PLACEHOLDER[...]" (markdown
  * interprets the double-underscore surround as bold).

package/src/memory/migrations/270-schedule-source-conversation.ts

@@ -0,0 +1,13 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
+
+export function migrateScheduleSourceConversation(database: DrizzleDb): void {
+  const raw = getSqliteFrom(database);
+  try {
+    raw.exec(
+      `ALTER TABLE cron_jobs ADD COLUMN created_from_conversation_id TEXT`,
+    );
+  } catch {
+    // Column already exists — nothing to do.
+  }
+}

package/src/memory/migrations/271-create-auth-fallback-events.ts

@@ -0,0 +1,21 @@
+import type { DrizzleDb } from "../db-connection.js";
+
+/**
+ * Create the auth_fallback_events table for tracking legacy-loopback
+ * auth-fallback counts forwarded by the gateway. One row per
+ * (guard, path, failure_kind) per flush window.
+ */
+export function createAuthFallbackEventsTable(database: DrizzleDb): void {
+  database.run(/*sql*/ `
+    CREATE TABLE IF NOT EXISTS auth_fallback_events (
+      id TEXT PRIMARY KEY,
+      created_at INTEGER NOT NULL,
+      guard TEXT NOT NULL,
+      path TEXT NOT NULL,
+      failure_kind TEXT NOT NULL,
+      count INTEGER NOT NULL,
+      window_start INTEGER NOT NULL,
+      window_end INTEGER NOT NULL
+    )
+  `);
+}

package/src/memory/migrations/272-acp-session-history-cwd.ts

@@ -0,0 +1,36 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
+import { withCrashRecovery } from "./validate-migration-state.js";
+
+const CHECKPOINT_KEY = "migration_acp_session_history_cwd_v1";
+
+const TABLE = "acp_session_history";
+const COLUMN = "cwd";
+
+/**
+ * Add a nullable `cwd TEXT` column to `acp_session_history`.
+ *
+ * Records the working directory the ACP agent process was spawned with so
+ * that a persisted session can later be resumed (`session/load` /
+ * `session/resume` both require the original cwd to reconstruct params).
+ *
+ * `NULL` for rows persisted before this migration ran — legacy sessions
+ * simply are not resumable.
+ *
+ * Idempotent — the PRAGMA guard makes re-running a no-op once the column
+ * exists.
+ */
+export function migrateAcpSessionHistoryCwd(database: DrizzleDb): void {
+  withCrashRecovery(database, CHECKPOINT_KEY, () => {
+    const raw = getSqliteFrom(database);
+
+    const columns = raw.query(`PRAGMA table_info(${TABLE})`).all() as Array<{
+      name: string;
+    }>;
+    const columnNames = new Set(columns.map((c) => c.name));
+
+    if (!columnNames.has(COLUMN)) {
+      raw.exec(`ALTER TABLE ${TABLE} ADD COLUMN ${COLUMN} TEXT`);
+    }
+  });
+}

package/src/memory/migrations/index.ts

@@ -257,6 +257,9 @@ export { migrateLlmUsageEventsAddAssistantVersion } from "./267-llm-usage-events
 export { migrateAddMemoryV3Selections } from "./268-add-memory-v3-selections.js";
 export { migrateScheduleScriptTimeout } from "./269-schedule-script-timeout.js";
 export { migrateMessagesRoleCreatedAtIndex } from "./270-messages-role-created-at-index.js";
+export { migrateScheduleSourceConversation } from "./270-schedule-source-conversation.js";
+export { createAuthFallbackEventsTable } from "./271-create-auth-fallback-events.js";
+export { migrateAcpSessionHistoryCwd } from "./272-acp-session-history-cwd.js";
 export {
   MIGRATION_REGISTRY,
   type MigrationRegistryEntry,

package/src/memory/pkb/autoinject.ts

@@ -0,0 +1,61 @@
+/**
+ * Resolution of the PKB auto-inject file list (`pkb/_autoinject.md`).
+ *
+ * Which PKB files are always loaded into context is a PKB-domain concern
+ * owned here next to {@link getPkbRoot}, so both the runtime injector and the
+ * reminder-hint tracker resolve the list from a single canonical source
+ * rather than threading it through the orchestrator.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { stripCommentLines } from "../../util/strip-comment-lines.js";
+
+const PKB_DEFAULT_FILES = [
+  "INDEX.md",
+  "essentials.md",
+  "threads.md",
+  "buffer.md",
+];
+
+const AUTOINJECT_FILENAME = "_autoinject.md";
+
+/**
+ * Read `_autoinject.md` from the PKB directory and return the list of
+ * filenames to inject.
+ *
+ * - Returns `null` when the file is missing or unreadable — callers
+ *   should fall back to the hardcoded defaults.
+ * - Returns `[]` when the file exists but has no entries (empty or
+ *   comments only) — an explicit opt-out meaning "inject nothing."
+ */
+export function readAutoinjectList(pkbDir: string): string[] | null {
+  const filePath = join(pkbDir, AUTOINJECT_FILENAME);
+  if (!existsSync(filePath)) return null;
+  try {
+    const raw = stripCommentLines(readFileSync(filePath, "utf-8"));
+    const files = raw
+      .split("\n")
+      .map((l) => l.trim())
+      .filter((l) => l.length > 0);
+    return files.length > 0 ? files : [];
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the effective list of auto-inject filenames for a PKB directory.
+ *
+ * This is the single source of truth used both by `readPkbContext` (which
+ * actually injects the files) and by the PKB reminder-hint injector (which
+ * needs to know what's already in context so it doesn't redundantly
+ * recommend those files).
+ *
+ * Returns `PKB_DEFAULT_FILES` when `_autoinject.md` is missing/unreadable,
+ * or the parsed list (possibly empty) when it is present.
+ */
+export function getPkbAutoInjectList(pkbRoot: string): string[] {
+  return readAutoinjectList(pkbRoot) ?? PKB_DEFAULT_FILES;
+}

package/src/memory/pkb/context.ts

@@ -0,0 +1,50 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import { getWorkspaceDir } from "../../util/platform.js";
+import { stripCommentLines } from "../../util/strip-comment-lines.js";
+import { getPkbAutoInjectList } from "./autoinject.js";
+
+/** Max buffer.md lines injected into prompts — keeps context bounded even when filing is off. */
+const MAX_BUFFER_LINES = 50;
+
+/**
+ * Read the always-loaded PKB files and append a nudge encouraging the
+ * assistant to proactively read topic files and use `remember` aggressively.
+ *
+ * Which files are loaded is determined by `pkb/_autoinject.md` (one filename
+ * per line). Falls back to the built-in defaults when that file is absent.
+ *
+ * Returns the concatenated content ready for injection, or `null` if all
+ * files are missing or empty.
+ */
+export function readPkbContext(): string | null {
+  const pkbDir = join(getWorkspaceDir(), "pkb");
+  if (!existsSync(pkbDir)) return null;
+
+  const filesToInject = getPkbAutoInjectList(pkbDir);
+
+  const parts: string[] = [];
+  for (const file of filesToInject) {
+    // Path traversal guard: reject entries that escape the pkb directory
+    const filePath = resolve(pkbDir, file);
+    if (!filePath.startsWith(pkbDir + "/")) continue;
+
+    if (!existsSync(filePath)) continue;
+    try {
+      let content = stripCommentLines(readFileSync(filePath, "utf-8")).trim();
+      if (file === "buffer.md" && content.length > 0) {
+        // Cap buffer entries to prevent unbounded growth when filing is disabled
+        const lines = content.split("\n");
+        if (lines.length > MAX_BUFFER_LINES) {
+          content = lines.slice(-MAX_BUFFER_LINES).join("\n");
+        }
+      }
+      if (content.length > 0) parts.push(content);
+    } catch {
+      // Skip unreadable files
+    }
+  }
+
+  return parts.length > 0 ? parts.join("\n\n") : null;
+}

package/src/memory/pkb/types.ts

@@ -5,8 +5,22 @@
  * index writer) land in later PRs.
  */
 
+import { join } from "node:path";
+
+import { getWorkspaceDir } from "../../util/platform.js";
+
 export const PKB_TARGET_TYPE = "pkb_file" as const;
 
+/**
+ * Absolute path to the workspace's PKB directory (`<workspace>/pkb`). PKB is
+ * a workspace-shared resource with a single on-disk location, so this is the
+ * canonical way to resolve its root rather than re-joining the workspace dir
+ * at each call site.
+ */
+export function getPkbRoot(): string {
+  return join(getWorkspaceDir(), "pkb");
+}
+
 /**
  * Sentinel `memory_scope_id` under which ALL PKB points are indexed and
  * searched. PKB files are a workspace-shared resource: one copy on disk is