@pellux/goodvibes-agent 1.5.5 → 1.5.6

package/src/tools/agent-harness-prompt-context.ts

@@ -1,7 +1,7 @@
 import type { MemoryApi } from '@pellux/goodvibes-sdk/platform/knowledge';
 import { getTierForContextWindow, getTierPromptSupplement } from '@pellux/goodvibes-sdk/platform/providers';
 import type { MemoryRecord } from '@pellux/goodvibes-sdk/platform/state';
-import { isPromptActiveMemory, MIN_PROMPT_MEMORY_CONFIDENCE } from '../agent/memory-prompt.ts';
+import { describeMemoryPromptEligibility, isPromptActiveMemory, MIN_PROMPT_MEMORY_CONFIDENCE } from '../agent/memory-prompt.ts';
 import { AgentPersonaRegistry, buildActivePersonaPrompt } from '../agent/persona-registry.ts';
 import { buildProjectContextPrompt, discoverProjectContextFiles } from '../agent/project-context-files.ts';
 import { AgentRoutineRegistry, buildEnabledRoutinesPrompt, evaluateAgentRoutineReadiness } from '../agent/routine-registry.ts';
@@ -229,6 +229,14 @@ function memorySegment(memory: PromptMemoryApi | undefined, includeParameters: b
     suppressedCount: suppressed.length,
     promptChars: promptText.length,
     promptText,
+    // F7c: this segment orders the eligible set by stored confidence/recency
+    // (memorySort), NOT by relevance to the current turn. The `context
+    // action:"receipt"` surface (prompt-context-receipts.ts) additionally
+    // ranks the same eligible set by per-turn semantic relevance when that
+    // scoring succeeds. Stating the ordering basis here up front keeps the
+    // two memory surfaces from reading as contradictory when their orders
+    // differ for the same eligible records.
+    note: 'Ordered by stored confidence/recency, not by relevance to the current turn — see context action:"receipt" for per-turn relevance scoring.',
     route: 'memory action:"status"',
     selected: active.map((record) => ({
       id: record.id,
@@ -237,17 +245,23 @@ function memorySegment(memory: PromptMemoryApi | undefined, includeParameters: b
       confidence: record.confidence,
       inspectRoute: `agent_local_registry domain:"memory" action:"get" recordId:"${record.id}"`,
     })),
-    suppressed: suppressed.slice(0, 12).map((record) => ({
-      id: record.id,
-      reviewState: record.reviewState,
-      confidence: record.confidence,
-      reason: record.reviewState !== 'reviewed'
-        ? 'not reviewed'
-        : record.confidence < MIN_PROMPT_MEMORY_CONFIDENCE
-          ? `confidence below ${MIN_PROMPT_MEMORY_CONFIDENCE}`
-          : 'outside prompt limit',
-      inspectRoute: `agent_local_registry domain:"memory" action:"get" recordId:"${record.id}"`,
-    })),
+    suppressed: suppressed.slice(0, 12).map((record) => {
+      // Honest, per-record reason straight from describeMemoryPromptEligibility (Wave-4
+      // W4-A1B) — the same wording source prompt-context-receipts.ts uses, never a
+      // locally invented "not reviewed"/"outside prompt limit" guess. A record here
+      // either genuinely failed eligibility, or passed it but was cut by the top-10
+      // prompt slice — those read differently.
+      const eligibility = describeMemoryPromptEligibility(record);
+      return {
+        id: record.id,
+        reviewState: record.reviewState,
+        confidence: record.confidence,
+        reason: eligibility.eligible
+          ? `eligible (${eligibility.reason}) but outside the top-10 prompt slice — budget-limited, not a trust problem`
+          : eligibility.reason,
+        inspectRoute: `agent_local_registry domain:"memory" action:"get" recordId:"${record.id}"`,
+      };
+    }),
   }, includeParameters);
 }
 

package/src/tools/agent-harness-workspace-actions.ts

@@ -29,6 +29,7 @@ export interface WorkspaceEditorContext {
   readonly selectedRoutine: AgentWorkspaceLocalLibraryItem | null;
   readonly recentReviewerHandoffArtifacts: AgentWorkspaceRuntimeSnapshot['recentReviewerHandoffArtifacts'];
   readonly reviewPacketDefaults: AgentWorkspaceRuntimeSnapshot['reviewPacketDefaults'] | null;
+  readonly calendarOAuthConfigStatus: AgentWorkspaceRuntimeSnapshot['calendarOAuthConfigStatus'] | null;
 }
 
 export interface WorkspaceActionLookup {
@@ -247,6 +248,7 @@ export function buildWorkspaceEditorContext(context: CommandContext, args: Agent
       selectedRoutine: selectedRoutineFromArgs(snapshot, args),
       recentReviewerHandoffArtifacts: snapshot.recentReviewerHandoffArtifacts,
       reviewPacketDefaults: snapshot.reviewPacketDefaults,
+      calendarOAuthConfigStatus: snapshot.calendarOAuthConfigStatus,
     };
   } catch {
     return {
@@ -254,6 +256,7 @@ export function buildWorkspaceEditorContext(context: CommandContext, args: Agent
       selectedRoutine: null,
       recentReviewerHandoffArtifacts: [],
       reviewPacketDefaults: null,
+      calendarOAuthConfigStatus: null,
     };
   }
 }
@@ -267,6 +270,7 @@ export function createWorkspaceEditor(
     selectedRoutine: editorKind === 'routine-schedule' ? editorContext?.selectedRoutine ?? null : null,
     recentReviewerHandoffArtifacts: editorContext?.recentReviewerHandoffArtifacts ?? [],
     reviewPacketDefaults: editorContext?.reviewPacketDefaults ?? null,
+    calendarOAuthConfigStatus: editorContext?.calendarOAuthConfigStatus ?? null,
   });
 }
 

package/src/tools/agent-local-registry-args.ts

@@ -0,0 +1,117 @@
+/**
+ * Shared arg-reading/validation helpers for the agent_local_registry tool.
+ *
+ * Split out of agent-local-registry-tool.ts to stay under the 800-line
+ * architecture cap. These are generic across every domain (memory, note,
+ * persona, skill, skill_bundle, routine) — no domain-specific logic lives
+ * here.
+ */
+
+export interface AgentLocalRegistryToolArgs {
+  readonly domain?: unknown;
+  readonly action?: unknown;
+  readonly id?: unknown;
+  readonly query?: unknown;
+  readonly semantic?: unknown;
+  readonly cls?: unknown;
+  readonly scope?: unknown;
+  readonly summary?: unknown;
+  readonly detail?: unknown;
+  readonly confidence?: unknown;
+  readonly title?: unknown;
+  readonly name?: unknown;
+  readonly description?: unknown;
+  readonly body?: unknown;
+  readonly sourceUrl?: unknown;
+  readonly procedure?: unknown;
+  readonly steps?: unknown;
+  readonly skills?: unknown;
+  readonly skillIds?: unknown;
+  readonly requiresEnv?: unknown;
+  readonly requiresCommands?: unknown;
+  readonly triggers?: unknown;
+  readonly tags?: unknown;
+  readonly reason?: unknown;
+  readonly enabled?: unknown;
+  readonly activate?: unknown;
+  readonly provenance?: unknown;
+  readonly confirm?: unknown;
+  readonly explicitUserRequest?: unknown;
+}
+
+export const AGENT_TOOL_PROVENANCE = 'agent-local-registry-tool';
+
+export function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+export function readAffirmative(value: unknown): boolean {
+  const normalized = readString(value).toLowerCase();
+  return value === true || (typeof value === 'string' && (normalized === '' || normalized === 'yes' || normalized === 'y' || normalized === 'true' || normalized === 'on'));
+}
+
+export function readStringList(value: unknown): readonly string[] {
+  if (typeof value === 'string') {
+    return value.split(',').map((entry) => entry.trim()).filter(Boolean);
+  }
+  if (!Array.isArray(value)) return [];
+  return value.filter((entry): entry is string => typeof entry === 'string').map((entry) => entry.trim()).filter(Boolean);
+}
+
+export function readOptionalNumber(value: unknown): number | undefined {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value !== 'string' || !value.trim()) return undefined;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+export function readOptionalConfidence(value: unknown): number | undefined {
+  const confidence = readOptionalNumber(value);
+  if (confidence === undefined) return undefined;
+  if (confidence < 0 || confidence > 100) throw new Error('confidence must be between 0 and 100.');
+  return confidence;
+}
+
+export function registryError(message: string): { readonly success: false; readonly error: string } {
+  return { success: false, error: message };
+}
+
+export function registryOutput(output: string): { readonly success: true; readonly output: string } {
+  return { success: true, output };
+}
+
+export function requireId(args: AgentLocalRegistryToolArgs): string {
+  const id = readString(args.id);
+  if (!id) throw new Error('id is required.');
+  return id;
+}
+
+export function requireConfirmedDelete(args: AgentLocalRegistryToolArgs, label: string): void {
+  const explicitUserRequest = readString(args.explicitUserRequest);
+  if (!explicitUserRequest) throw new Error(`${label} deletion requires explicitUserRequest with the user's exact request or a short faithful summary.`);
+  if (args.confirm !== true) throw new Error(`${label} deletion requires confirm:true after an explicit user request.`);
+}
+
+export function requireName(args: AgentLocalRegistryToolArgs): string {
+  const name = readString(args.name);
+  if (!name) throw new Error('name is required.');
+  return name;
+}
+
+export function requireDescription(args: AgentLocalRegistryToolArgs): string {
+  const description = readString(args.description);
+  if (!description) throw new Error('description is required.');
+  return description;
+}
+
+export function requireTextField(value: unknown, fieldName: string): string {
+  const text = readString(value);
+  if (!text) throw new Error(`${fieldName} is required.`);
+  return text;
+}
+
+export function requireSummary(args: AgentLocalRegistryToolArgs): string {
+  const summary = readString(args.summary || args.description);
+  if (!summary) throw new Error('summary is required.');
+  return summary;
+}

package/src/tools/agent-local-registry-memory.ts

@@ -0,0 +1,227 @@
+/**
+ * Agent-local memory domain handler (W4-A1: memory honesty).
+ *
+ * Split out of agent-local-registry-tool.ts to stay under the 800-line
+ * architecture cap. Owns the `memory` domain of the agent_local_registry
+ * tool: list/search/get/create/update/review/stale/delete.
+ *
+ * The `search` action defaults to semantic recall (registry.searchSemantic)
+ * instead of the old literal LIKE-scan default — natural-language recall must
+ * not depend on the query text appearing as a literal substring in the
+ * stored summary/detail. Index health is checked before every semantic
+ * search so an unavailable index degrades honestly (stated reason, literal
+ * fallback) instead of silently returning zero matches that read as "nothing
+ * was ever stored."
+ */
+import {
+  HASHED_MEMORY_EMBEDDING_PROVIDER,
+  MemoryRegistry,
+  type MemoryClass,
+  type MemoryRecord,
+  type MemoryScope,
+  type MemorySemanticSearchResult,
+  type MemoryVectorStats,
+} from '@pellux/goodvibes-sdk/platform/state';
+import { assertNoSecretLikeMemoryText } from '../agent/memory-safety.ts';
+import { formatAgentRecordReference, formatAgentRecordReviewState } from '../agent/record-labels.ts';
+import {
+  AGENT_TOOL_PROVENANCE,
+  type AgentLocalRegistryToolArgs,
+  readOptionalConfidence,
+  readString,
+  readStringList,
+  requireConfirmedDelete,
+  requireId,
+  requireSummary,
+} from './agent-local-registry-args.ts';
+// `import type` is erased at compile time, so this does not create a runtime
+// circular dependency even though agent-local-registry-tool.ts imports
+// handleMemory (below) from this module.
+import type { AgentLocalRegistryAction } from './agent-local-registry-tool.ts';
+
+export const MEMORY_CLASSES: readonly MemoryClass[] = ['decision', 'constraint', 'incident', 'pattern', 'fact', 'risk', 'runbook', 'architecture', 'ownership'];
+export const MEMORY_SCOPES: readonly MemoryScope[] = ['session', 'project', 'team'];
+
+function isMemoryClass(value: unknown): value is MemoryClass {
+  return typeof value === 'string' && MEMORY_CLASSES.includes(value as MemoryClass);
+}
+
+function isMemoryScope(value: unknown): value is MemoryScope {
+  return typeof value === 'string' && MEMORY_SCOPES.includes(value as MemoryScope);
+}
+
+function requireMemoryClass(args: AgentLocalRegistryToolArgs): MemoryClass {
+  const cls = args.cls || 'fact';
+  if (!isMemoryClass(cls)) throw new Error(`Invalid memory class. Valid values ${MEMORY_CLASSES.join(', ')}.`);
+  return cls;
+}
+
+function readMemoryScope(args: AgentLocalRegistryToolArgs): MemoryScope {
+  const scope = args.scope || 'project';
+  if (!isMemoryScope(scope)) throw new Error(`Invalid memory scope. Valid values ${MEMORY_SCOPES.join(', ')}.`);
+  return scope;
+}
+
+export function formatMemory(record: MemoryRecord): string {
+  const tags = record.tags.length > 0 ? ` tags ${record.tags.join(', ')}` : '';
+  return `${record.id}  ${record.scope}/${record.cls}  ${formatAgentRecordReviewState(record.reviewState)}  ${record.confidence}%${tags}  ${record.summary}`;
+}
+
+function formatMemoryMatch(entry: MemorySemanticSearchResult): string {
+  const matchLabel = entry.similarity > 0 ? `  match ${Math.round(entry.similarity * 100)}% (score ${Math.round(entry.score)})` : '';
+  return `${formatMemory(entry.record)}${matchLabel}`;
+}
+
+/**
+ * A HARD unavailable reason: the semantic index cannot be consulted at all, so the
+ * search action must fall back to a literal LIKE-scan and say so — never a silent
+ * empty result that reads as "no memory matches" when the index was never asked.
+ */
+function describeMemoryIndexUnavailable(stats: MemoryVectorStats): string | null {
+  if (!stats.enabled) return 'the semantic memory index is disabled for this store';
+  if (!stats.available) return `the semantic memory index is unavailable${stats.error ? `: ${stats.error}` : ''}`;
+  if (stats.indexedRecords === 0) return 'the semantic memory index has no indexed records yet';
+  return null;
+}
+
+/**
+ * A SOFT caveat: the index is up and consulted, but it is running on the built-in
+ * hashed-only fallback embedding provider (bag-of-words/token hashing) rather than a
+ * real embedding model. That still ranks real matches meaningfully better than a
+ * literal substring scan, but it is not a modeled semantic understanding — say so
+ * rather than presenting it as equivalent to a configured semantic provider.
+ */
+function describeMemoryIndexCaveat(stats: MemoryVectorStats): string | null {
+  if (stats.embeddingProviderId === HASHED_MEMORY_EMBEDDING_PROVIDER.id) {
+    return 'running on the hashed-only fallback embedding provider (no dedicated semantic model configured) — ranking is approximate, not modeled semantic understanding';
+  }
+  return null;
+}
+
+function renderMemorySearch(mode: string, query: string, lines: readonly string[]): string {
+  if (lines.length === 0) {
+    return `Agent-local memory search (${mode})\nNo Agent-local memory records matched "${query}".`;
+  }
+  return [`Agent-local memory search (${mode})`, `query ${query || '(all)'}`, ...lines].join('\n');
+}
+
+export async function handleMemory(registry: MemoryRegistry, action: AgentLocalRegistryAction, args: AgentLocalRegistryToolArgs): Promise<string> {
+  if (action === 'list') {
+    const records = registry.getAll();
+    return records.length === 0
+      ? 'Agent-local memory\nNo Agent-local memory records.'
+      : ['Agent-local memory', ...records.map(formatMemory)].join('\n');
+  }
+  if (action === 'search') {
+    const query = readString(args.query);
+    const wantsLiteral = args.semantic === false;
+    if (wantsLiteral) {
+      const records = registry.search({ query, limit: 10 });
+      return renderMemorySearch('literal — explicitly requested', query, records.map(formatMemory));
+    }
+    // SEMANTIC BY DEFAULT: natural-language recall must not depend on the query text
+    // appearing as a literal substring in the stored summary/detail. Check index
+    // health FIRST so an unavailable index degrades honestly instead of silently
+    // returning zero matches that read as "nothing was ever stored."
+    const stats = registry.vectorStats();
+    const unavailable = describeMemoryIndexUnavailable(stats);
+    if (unavailable) {
+      const records = registry.search({ query, limit: 10 });
+      return renderMemorySearch(`literal fallback — ${unavailable}`, query, records.map(formatMemory));
+    }
+    const results = registry.searchSemantic({ query, limit: 10 });
+    const consultedSemanticIndex = query.length > 0 && results.some((entry) => entry.similarity > 0);
+    const caveat = describeMemoryIndexCaveat(stats);
+    const mode = !consultedSemanticIndex && query.length > 0
+      ? 'semantic — no vector match for this query, ranked by stored confidence instead'
+      : caveat
+        ? `semantic — ${caveat}`
+        : 'semantic';
+    return renderMemorySearch(mode, query, results.map(formatMemoryMatch));
+  }
+  if (action === 'get') {
+    const record = registry.get(requireId(args));
+    if (!record) return `Unknown Agent-local memory ${readString(args.id)}`;
+    return [
+      formatMemory(record),
+      `created ${new Date(record.createdAt).toISOString()}`,
+      `updated ${new Date(record.updatedAt).toISOString()}`,
+      `origin ${record.provenance.map((entry) => formatAgentRecordReference({ kind: String(entry.kind), ref: String(entry.ref) })).join(', ') || '(none)'}`,
+      `provenance: ${record.provenance.map((entry) => `${String(entry.kind)}:${String(entry.ref)}`).join(',') || '(none)'}`,
+      '',
+      record.detail || '(no detail)',
+    ].join('\n');
+  }
+  if (action === 'create') {
+    const summary = requireSummary(args);
+    const detail = readString(args.detail || args.body);
+    const tags = readStringList(args.tags);
+    const confidence = readOptionalConfidence(args.confidence);
+    assertNoSecretLikeMemoryText([summary, detail, ...tags]);
+    const record = await registry.add({
+      scope: readMemoryScope(args),
+      cls: requireMemoryClass(args),
+      summary,
+      detail,
+      tags: [...tags],
+      ...(confidence === undefined ? {} : { review: { state: 'fresh' as const, confidence } }),
+      provenance: [{ kind: 'event', ref: readString(args.provenance) || AGENT_TOOL_PROVENANCE }],
+    });
+    return [
+      'Created Agent-local memory',
+      `  id ${record.id}`,
+      `  summary ${record.summary}`,
+    ].join('\n');
+  }
+  if (action === 'update') {
+    const summary = readString(args.summary || args.description);
+    const detail = readString(args.detail || args.body);
+    const tags = args.tags === undefined ? undefined : [...readStringList(args.tags)];
+    assertNoSecretLikeMemoryText([summary, detail, ...(tags ?? [])]);
+    const record = registry.update(requireId(args), {
+      summary: summary || undefined,
+      detail: detail || undefined,
+      tags,
+      scope: args.scope === undefined ? undefined : readMemoryScope(args),
+    });
+    if (!record) return `Unknown Agent-local memory ${readString(args.id)}`;
+    return [
+      'Updated Agent-local memory',
+      `  id ${record.id}`,
+      `  summary ${record.summary}`,
+    ].join('\n');
+  }
+  if (action === 'review') {
+    const record = registry.review(requireId(args), {
+      state: 'reviewed',
+      confidence: readOptionalConfidence(args.confidence),
+      reviewedBy: 'agent',
+    });
+    if (!record) return `Unknown Agent-local memory ${readString(args.id)}`;
+    return [
+      'Reviewed Agent-local memory',
+      `  id ${record.id}`,
+    ].join('\n');
+  }
+  if (action === 'stale') {
+    const record = registry.review(requireId(args), {
+      state: 'stale',
+      staleReason: readString(args.reason) || 'Marked stale by Agent.',
+    });
+    if (!record) return `Unknown Agent-local memory ${readString(args.id)}`;
+    return [
+      'Marked Agent-local memory stale',
+      `  id ${record.id}`,
+    ].join('\n');
+  }
+  if (action === 'delete') {
+    const id = requireId(args);
+    requireConfirmedDelete(args, 'Agent-local memory');
+    if (!registry.delete(id)) return `Unknown Agent-local memory ${id}`;
+    return [
+      'Deleted Agent-local memory',
+      `  id ${id}`,
+    ].join('\n');
+  }
+  throw new Error(`Action ${action} is not valid for memory.`);
+}