feat: add project learning recommendations

Author: igorcosta

src/__tests__/extension-features-e2e.test.ts

@@ -419,4 +419,48 @@ describe('extension RPC features', () => {
       sdk.respondToMcpInvocation(fixture.params)
     )).rejects.toThrow(/Invalid RPC result for autohand\.mcp\.invokeResponse/);
   });
+
+  it('gets project learning recommendations through the spawned CLI', async () => {
+    const fixture = {
+      method: 'autohand.learn.recommend',
+      params: { deep: true },
+      result: {
+        success: true,
+        projectSummary: 'TypeScript SDK',
+        audit: [{
+          skill: 'old-testing',
+          status: 'outdated' as const,
+          reason: 'Uses a retired command',
+        }],
+        recommendations: [{
+          slug: 'typescript-best-practices',
+          score: 0.97,
+          reason: 'Matches this repository',
+        }],
+        gapAnalysis: null,
+      },
+    };
+
+    await expect(withSDK(fixture, (sdk) =>
+      sdk.getLearningRecommendations(fixture.params)
+    )).resolves.toEqual(fixture.result);
+  });
+
+  it('rejects malformed project learning recommendation scores', async () => {
+    const fixture = {
+      method: 'autohand.learn.recommend',
+      params: {},
+      result: {
+        success: true,
+        projectSummary: 'SDK',
+        audit: [],
+        recommendations: [{ slug: 'testing', score: 'high', reason: 'Useful' }],
+        gapAnalysis: 'Needs integration testing',
+      },
+    };
+
+    await expect(withSDK(fixture, (sdk) =>
+      sdk.getLearningRecommendations(fixture.params)
+    )).rejects.toThrow(/Invalid RPC result for autohand\.learn\.recommend/);
+  });
 });

src/rpc/client.ts

@@ -66,6 +66,8 @@ import type {
   McpSetVscodeToolsResult,
   McpInvokeResponseParams,
   McpInvokeResponseResult,
+  LearnRecommendParams,
+  LearnRecommendResult,
   PermissionResponseParams,
   SDKEvent,
   JsonRpcParams,
@@ -580,6 +582,14 @@ export class RPCClient {
     return validateExtensionRpcResult('autohand.mcp.invokeResponse', result);
   }
 
+  /** Audit installed skills and recommend project-relevant additions. */
+  async getLearningRecommendations(
+    params: LearnRecommendParams = {}
+  ): Promise<LearnRecommendResult> {
+    const result = await this.transport.request('autohand.learn.recommend', params);
+    return validateExtensionRpcResult('autohand.learn.recommend', result);
+  }
+
   /**
    * Set permission mode
    * 

src/sdk/agent.ts

@@ -25,6 +25,8 @@ import type {
   McpSetVscodeToolsResult,
   McpInvokeResponseParams,
   McpInvokeResponseResult,
+  LearnRecommendParams,
+  LearnRecommendResult,
   PermissionResponseParams,
   PromptParams,
   QueueGoalParams,
@@ -767,4 +769,10 @@ export class Agent {
   ): Promise<McpInvokeResponseResult> {
     return this.sdk.respondToMcpInvocation(params);
   }
+
+  async getLearningRecommendations(
+    params: LearnRecommendParams = {}
+  ): Promise<LearnRecommendResult> {
+    return this.sdk.getLearningRecommendations(params);
+  }
 }

src/sdk/index.ts

@@ -67,6 +67,8 @@ import type {
   McpSetVscodeToolsResult,
   McpInvokeResponseParams,
   McpInvokeResponseResult,
+  LearnRecommendParams,
+  LearnRecommendResult,
   PermissionResponseParams,
   SDKEvent,
   ModelInfo,
@@ -1627,6 +1629,14 @@ export class AutohandSDK {
     return this.client.respondToMcpInvocation(params);
   }
 
+  /** Audit installed skills and recommend project-relevant additions. */
+  async getLearningRecommendations(
+    params: LearnRecommendParams = {}
+  ): Promise<LearnRecommendResult> {
+    await this.ensureStarted();
+    return this.client.getLearningRecommendations(params);
+  }
+
   /**
    * Allow a pending permission request.
    *

src/types/index.ts

@@ -2012,6 +2012,31 @@ export interface McpInvokeResponseResult {
   success: boolean;
 }
 
+export interface LearnRecommendParams {
+  deep?: boolean;
+}
+
+export interface LearnAuditEntry {
+  skill: string;
+  status: 'redundant' | 'outdated' | 'conflicting';
+  reason: string;
+}
+
+export interface LearnRecommendation {
+  slug: string;
+  score: number;
+  reason: string;
+}
+
+export interface LearnRecommendResult {
+  success: boolean;
+  projectSummary: string;
+  audit: LearnAuditEntry[];
+  recommendations: LearnRecommendation[];
+  gapAnalysis: string | null;
+  error?: string;
+}
+
 // ============================================================================
 // RPC Response Results
 // ============================================================================

src/validation/extension-rpc-results.ts

@@ -9,6 +9,9 @@ import type {
   YoloSetResult,
   McpSetVscodeToolsResult,
   McpInvokeResponseResult,
+  LearnAuditEntry,
+  LearnRecommendation,
+  LearnRecommendResult,
   RpcHistoryEntry,
   DirectoryAccessResponseResult,
   DirectoryAccessAcknowledgedResult,
@@ -256,6 +259,63 @@ function mcpInvokeResponseResult(
   return { success: boolean(record.success, method, `${path}.success`) };
 }
 
+function learnAuditStatus(
+  value: unknown,
+  method: string,
+  path: string
+): LearnAuditEntry['status'] {
+  if (value === 'redundant' || value === 'outdated' || value === 'conflicting') return value;
+  return invalid(method, path, 'redundant | outdated | conflicting', value);
+}
+
+function learnAuditEntry(value: unknown, method: string, path: string): LearnAuditEntry {
+  const record = object(value, method, path);
+  return {
+    skill: string(record.skill, method, `${path}.skill`),
+    status: learnAuditStatus(record.status, method, `${path}.status`),
+    reason: string(record.reason, method, `${path}.reason`),
+  };
+}
+
+function learnRecommendation(
+  value: unknown,
+  method: string,
+  path: string
+): LearnRecommendation {
+  const record = object(value, method, path);
+  return {
+    slug: string(record.slug, method, `${path}.slug`),
+    score: number(record.score, method, `${path}.score`),
+    reason: string(record.reason, method, `${path}.reason`),
+  };
+}
+
+function learnRecommendResult(
+  value: unknown,
+  method: string,
+  path: string
+): LearnRecommendResult {
+  const record = object(value, method, path);
+  const result: LearnRecommendResult = {
+    success: boolean(record.success, method, `${path}.success`),
+    projectSummary: string(record.projectSummary, method, `${path}.projectSummary`),
+    audit: array(record.audit, method, `${path}.audit`, learnAuditEntry),
+    recommendations: array(
+      record.recommendations,
+      method,
+      `${path}.recommendations`,
+      learnRecommendation
+    ),
+    gapAnalysis: record.gapAnalysis === null
+      ? null
+      : string(record.gapAnalysis, method, `${path}.gapAnalysis`),
+  };
+  if (record.error !== undefined) {
+    result.error = string(record.error, method, `${path}.error`);
+  }
+  return result;
+}
+
 interface ExtensionRpcResultMap {
   'autohand.permissionAcknowledged': PermissionAcknowledgedResult;
   'autohand.directoryAccessResponse': DirectoryAccessResponseResult;
@@ -268,6 +328,7 @@ interface ExtensionRpcResultMap {
   'autohand.yolo.set': YoloSetResult;
   'autohand.mcp.setVscodeTools': McpSetVscodeToolsResult;
   'autohand.mcp.invokeResponse': McpInvokeResponseResult;
+  'autohand.learn.recommend': LearnRecommendResult;
 }
 
 export type ExtensionRpcMethod = keyof ExtensionRpcResultMap;
@@ -297,6 +358,8 @@ const validators: {
     mcpSetVscodeToolsResult(value, 'autohand.mcp.setVscodeTools', path),
   'autohand.mcp.invokeResponse': (value, path) =>
     mcpInvokeResponseResult(value, 'autohand.mcp.invokeResponse', path),
+  'autohand.learn.recommend': (value, path) =>
+    learnRecommendResult(value, 'autohand.learn.recommend', path),
 };
 
 export function validateExtensionRpcResult<Method extends ExtensionRpcMethod>(