@prmichaelsen/remember-mcp 3.19.3 → 3.20.1

package/agent/tasks/milestone-22-admin-debugging-tools/task-523-user-inspection-tools.md

@@ -0,0 +1,126 @@
+# Task 523: User Inspection Tools
+
+**Milestone**: [M22 — Admin Debugging Tools](../../milestones/milestone-22-admin-debugging-tools.md)
+**Design Reference**: [local.admin-debugging-tools.md](../../design/local.admin-debugging-tools.md)
+**Status**: Not Started
+**Estimated Time**: 2-3 hours
+**Dependencies**: [Task 520](task-520-admin-gate-infrastructure.md)
+
+---
+
+## Objective
+
+Implement four granular admin tools for inspecting Firestore user data: `remember_admin_inspect_user_preferences`, `remember_admin_inspect_user_ghost_configs`, `remember_admin_inspect_user_escalation_records`, and `remember_admin_inspect_user_api_tokens`.
+
+## Context
+
+User data is spread across multiple Firestore collections. Rather than a single monolithic inspect tool, these are split into granular tools per data type — allowing precise queries and avoiding returning unnecessary data. Note: `space_configs` is excluded because it is not user-scoped.
+
+## Steps
+
+### 1. Implement `remember_admin_inspect_user_preferences`
+
+Create `src/tools/admin-inspect-user-preferences.ts`:
+
+**Input**:
+```typescript
+{ user_id: string }
+```
+
+**Output**: Full user preferences document from Firestore, including all categories (templates, search, location, privacy, notifications, display).
+
+**Implementation**:
+- Use remember-core preference service to fetch user preferences
+- Guard with `isAdmin(userId)` check
+- Return default preferences if none set (same as `remember_get_preferences` behavior, but for any user)
+
+### 2. Implement `remember_admin_inspect_user_ghost_configs`
+
+Create `src/tools/admin-inspect-user-ghost-configs.ts`:
+
+**Input**:
+```typescript
+{ user_id: string }
+```
+
+**Output**: All ghost configurations for the user — trust mode, content type filters, blocked users, etc.
+
+**Implementation**:
+- Use remember-core ghost config service to fetch all configs for user
+- Guard with `isAdmin(userId)` check
+- Return empty array if no ghost configs exist
+
+### 3. Implement `remember_admin_inspect_user_escalation_records`
+
+Create `src/tools/admin-inspect-user-escalation-records.ts`:
+
+**Input**:
+```typescript
+{ user_id: string }
+```
+
+**Output**: All escalation records for the user — trust escalation attempts, blocked interactions, timestamps.
+
+**Implementation**:
+- Use remember-core escalation service to fetch records for user
+- Guard with `isAdmin(userId)` check
+- Return empty array if no records exist
+
+### 4. Implement `remember_admin_inspect_user_api_tokens`
+
+Create `src/tools/admin-inspect-user-api-tokens.ts`:
+
+**Input**:
+```typescript
+{ user_id: string }
+```
+
+**Output**: API token metadata (no hashes, no raw tokens):
+- Token name/label
+- Created date
+- Last used date
+- Scopes
+- Disabled status
+
+**Implementation**:
+- Query Firestore `api_tokens` collection where `user_id` matches
+- Exclude `token_hash` field from response — only return metadata
+- Guard with `isAdmin(userId)` check
+- Return empty array if no tokens exist
+
+### 5. Add Unit Tests
+
+Create spec files for each tool:
+- `src/tools/admin-inspect-user-preferences.spec.ts`
+- `src/tools/admin-inspect-user-ghost-configs.spec.ts`
+- `src/tools/admin-inspect-user-escalation-records.spec.ts`
+- `src/tools/admin-inspect-user-api-tokens.spec.ts`
+
+Test cases per tool:
+- Admin fetches data for existing user → returns data
+- Admin fetches data for user with no data → returns defaults/empty
+- Non-admin → permission error
+- Invalid user_id → appropriate error
+
+Additional for api_tokens:
+- Token hash is never included in response
+
+---
+
+## Verification
+
+- [ ] Each tool returns correct Firestore data for the specified user
+- [ ] Each tool returns defaults/empty for users with no data
+- [ ] `inspect_user_api_tokens` never returns token hashes
+- [ ] All four tools reject non-admin users
+- [ ] All four tools registered conditionally (hidden from non-admins)
+- [ ] Unit tests pass for all four tools
+- [ ] Uses remember-core services (not direct Firestore calls from tool handlers)
+
+## Key Design Decisions
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| inspect_user granularity | Separate tools per data type | Allows precise queries; avoids returning unnecessary data |
+| space_configs | Excluded | Not user-scoped data |
+| api_tokens | Metadata only, no hashes | Security — token hashes must never be exposed |

package/agent/tasks/milestone-22-admin-debugging-tools/task-524-health-and-drift-tools.md

@@ -0,0 +1,120 @@
+# Task 524: Health and Drift Tools
+
+**Milestone**: [M22 — Admin Debugging Tools](../../milestones/milestone-22-admin-debugging-tools.md)
+**Design Reference**: [local.admin-debugging-tools.md](../../design/local.admin-debugging-tools.md)
+**Status**: Not Started
+**Estimated Time**: 2-3 hours
+**Dependencies**: [Task 520](task-520-admin-gate-infrastructure.md)
+
+---
+
+## Objective
+
+Implement two admin tools: `remember_admin_health` (deep connectivity check) and `remember_admin_detect_weaviate_drift` (expected vs actual schema comparison).
+
+## Context
+
+`health` is a simple connectivity check — can we reach Weaviate and Firestore? `detect_weaviate_drift` is a more detailed diagnostic that compares the expected schema (as defined in code) against the actual schema in Weaviate, identifying missing properties, type mismatches, and unexpected fields.
+
+## Steps
+
+### 1. Implement `remember_admin_health`
+
+Create `src/tools/admin-health.ts`:
+
+**Input**:
+```typescript
+{} // No parameters — checks all services
+```
+
+**Output**:
+```typescript
+{
+  weaviate: { status: 'ok' | 'error', message?: string, latency_ms?: number },
+  firestore: { status: 'ok' | 'error', message?: string, latency_ms?: number },
+  overall: 'healthy' | 'degraded' | 'unhealthy'
+}
+```
+
+**Implementation**:
+- Weaviate: attempt a simple meta query (e.g., `client.getMeta()`) and measure latency
+- Firestore: attempt a simple read (e.g., read a known document or list collection) and measure latency
+- Overall: `healthy` if both ok, `degraded` if one fails, `unhealthy` if both fail
+- Guard with `isAdmin(userId)` check
+- No schema drift detection (that's the separate tool)
+- No per-user memory counts
+
+### 2. Implement `remember_admin_detect_weaviate_drift`
+
+Create `src/tools/admin-detect-weaviate-drift.ts`:
+
+**Input**:
+```typescript
+{
+  collection_ids?: string[]; // Optional — check specific collections, or sample if omitted
+}
+```
+
+**Output**: Per-collection comparison:
+```typescript
+{
+  collection: string;
+  status: 'match' | 'drift' | 'error';
+  expected_properties: string[];   // Properties defined in code
+  actual_properties: string[];     // Properties in Weaviate
+  missing_properties: string[];    // In code but not in Weaviate
+  extra_properties: string[];      // In Weaviate but not in code
+  type_mismatches: Array<{ property: string, expected: string, actual: string }>;
+}
+```
+
+**Implementation**:
+- Get expected schema from remember-core schema definitions (the property lists defined in code)
+- Get actual schema from Weaviate collection inspection
+- Compare property names, types, and index settings
+- Report differences per collection
+- If no `collection_ids` provided, check a sample of collections (e.g., first user collection, spaces_public)
+- Guard with `isAdmin(userId)` check
+
+### 3. Add Unit Tests
+
+Create spec files:
+- `src/tools/admin-health.spec.ts`
+- `src/tools/admin-detect-weaviate-drift.spec.ts`
+
+Test cases for `health`:
+- Both services reachable → overall: healthy
+- Weaviate down, Firestore up → overall: degraded
+- Both down → overall: unhealthy
+- Non-admin → permission error
+- Latency included in response
+
+Test cases for `detect_weaviate_drift`:
+- Schema matches expected → status: match, empty diff arrays
+- Missing property → reported in missing_properties
+- Extra property → reported in extra_properties
+- Type mismatch → reported in type_mismatches
+- Specific collection_ids → only checks those
+- No collection_ids → checks sample
+- Non-admin → permission error
+
+### 4. Update CHANGELOG and README
+
+- Add M22 admin tools to CHANGELOG.md
+- Update README.md tool count and add admin tools section
+- Version bump (patch or minor as appropriate)
+
+---
+
+## Verification
+
+- [ ] `health` checks Weaviate and Firestore connectivity with latency
+- [ ] `health` returns correct overall status (healthy/degraded/unhealthy)
+- [ ] `detect_weaviate_drift` compares expected vs actual schema properties
+- [ ] `detect_weaviate_drift` reports missing, extra, and type-mismatched properties
+- [ ] `detect_weaviate_drift` accepts optional collection_ids filter
+- [ ] Both tools reject non-admin users
+- [ ] Both tools registered conditionally (hidden from non-admins)
+- [ ] Unit tests pass for both tools
+- [ ] CHANGELOG updated with M22 admin tools
+- [ ] README updated with new tool count and admin section

package/agent/tasks/task-1-{title}.template.md

@@ -1,10 +1,10 @@
 # Task {N}: {Descriptive Task Name}
 
-**Milestone**: [M{N} - Milestone Name](../milestones/milestone-{N}-{name}.md)
-**Design Reference**: [{Design Name}](../design/{namespace}.{design-name}.md) | None
-**Estimated Time**: [e.g., "2 hours", "4 hours", "1 day"]
-**Dependencies**: [List prerequisite tasks, or "None"]
-**Status**: Not Started | In Progress | Completed
+**Milestone**: [M{N} - Milestone Name](../milestones/milestone-{N}-{name}.md)  
+**Design Reference**: [{Design Name}](../design/{namespace}.{design-name}.md) | None  
+**Estimated Time**: [e.g., "2 hours", "4 hours", "1 day"]  
+**Dependencies**: [List prerequisite tasks, or "None"]  
+**Status**: Not Started | In Progress | Completed  
 
 ---
 
@@ -12,7 +12,7 @@
 
 [Clearly state what this task accomplishes. Be specific and focused on a single, achievable goal.]
 
-**Example**: "Create the basic project structure with all necessary configuration files and directory organization for a TypeScript-based MCP server."
+**Example**: "Create the basic project structure with all necessary configuration files and directory organization for a TypeScript-based MCP server."  
 
 ---
 
@@ -20,7 +20,7 @@
 
 [Provide background information that helps understand why this task is necessary and how it fits into the larger milestone.]
 
-**Example**: "This task establishes the foundation for the project. Without proper structure and configuration, subsequent development tasks cannot proceed. The structure follows industry best practices for TypeScript projects and MCP server organization."
+**Example**: "This task establishes the foundation for the project. Without proper structure and configuration, subsequent development tasks cannot proceed. The structure follows industry best practices for TypeScript projects and MCP server organization."  
 
 ---
 
@@ -190,22 +190,22 @@ project-root/
 [Document potential problems and how to resolve them:]
 
 ### Issue 1: [Problem description]
-**Symptom**: [What the user will see]
-**Solution**: [How to fix it]
+**Symptom**: [What the user will see]  
+**Solution**: [How to fix it]  
 
 ### Issue 2: [Problem description]
-**Symptom**: [What the user will see]
-**Solution**: [How to fix it]
+**Symptom**: [What the user will see]  
+**Solution**: [How to fix it]  
 
 **Example**:
 
 ### Issue 1: npm init fails
-**Symptom**: Error message about permissions or missing npm
-**Solution**: Ensure Node.js and npm are installed correctly. Run `node --version` and `npm --version` to verify.
+**Symptom**: Error message about permissions or missing npm  
+**Solution**: Ensure Node.js and npm are installed correctly. Run `node --version` and `npm --version` to verify.  
 
 ### Issue 2: TypeScript configuration errors
-**Symptom**: tsc complains about invalid configuration
-**Solution**: Validate JSON syntax in tsconfig.json. Ensure all required fields are present.
+**Symptom**: tsc complains about invalid configuration  
+**Solution**: Validate JSON syntax in tsconfig.json. Ensure all required fields are present.  
 
 ---
 
@@ -239,6 +239,6 @@ project-root/
 
 ---
 
-**Next Task**: [Link to next task: task-{N+1}-{name}.md]
-**Related Design Docs**: [Links to relevant design documents]
-**Estimated Completion Date**: [YYYY-MM-DD or "TBD"]
+**Next Task**: [Link to next task: task-{N+1}-{name}.md]  
+**Related Design Docs**: [Links to relevant design documents]  
+**Estimated Completion Date**: [YYYY-MM-DD or "TBD"]