@pellux/goodvibes-agent 0.1.107 → 0.1.108

package/src/cli/agent-knowledge-command.ts

@@ -1,13 +1,22 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { createBrowserAgentSdk } from '@pellux/goodvibes-sdk/browser/agent';
-import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
-import { SDK_VERSION, VERSION } from '../version.ts';
 import type { CliCommandOutput } from './types.ts';
 import type { CliCommandRuntime } from './management.ts';
+import {
+  commandValues,
+  delegationTaskValues,
+  hasFlag,
+  parseConnectorInput,
+  readFirstStringList,
+  readOptionValue,
+  readPositiveInt,
+  readSinceMs,
+  readStringList,
+  stripCommandFlag,
+} from './agent-knowledge-args.ts';
 import {
   formatAsk,
   formatBatchIngest,
+  formatConnector,
+  formatConnectorDoctor,
   formatConnectors,
   formatEntityList,
   formatFailure,
@@ -18,100 +27,22 @@ import {
   formatSearch,
   formatStatus,
 } from './agent-knowledge-format.ts';
+import { AGENT_KNOWLEDGE_METHODS, DELEGATION_METHOD } from './agent-knowledge-methods.ts';
+import {
+  createAgentSdk,
+  fetchDaemonStatus,
+  findDisallowedKnowledgeScopeFlag,
+  formatScopeFlagRejection,
+  getAgentKnowledgeJson,
+  isRecord,
+  postAgentKnowledgeJson,
+  readPackageMetadata,
+  readString,
+  resolveDaemonConnection,
+  runKnowledgeCall,
+} from './agent-knowledge-runtime.ts';
 import { formatJsonOrText, yesNo } from './management.ts';
 
-type JsonRecord = Record<string, unknown>;
-
-interface AgentDaemonConnection {
-  readonly baseUrl: string;
-  readonly token: string | null;
-  readonly tokenPath: string;
-}
-
-interface AgentKnowledgeFailure {
-  readonly ok: false;
-  readonly kind: 'daemon_unavailable' | 'auth_required' | 'version_mismatch' | 'daemon_route_unavailable' | 'daemon_error';
-  readonly error: string;
-  readonly baseUrl: string;
-  readonly route: string;
-  readonly daemonVersion?: string;
-  readonly expectedSdkVersion?: string;
-}
-
-interface AgentKnowledgeSuccess<TData> {
-  readonly ok: true;
-  readonly kind: string;
-  readonly route: string;
-  readonly data: TData;
-}
-
-type AgentKnowledgeResult<TData> = AgentKnowledgeSuccess<TData> | AgentKnowledgeFailure;
-
-interface DaemonCallMethod {
-  readonly kind: string;
-  readonly route: string;
-}
-
-const AGENT_KNOWLEDGE_METHODS = {
-  status: {
-    kind: 'agentKnowledge.status',
-    route: '/api/goodvibes-agent/knowledge/status',
-  },
-  ask: {
-    kind: 'agentKnowledge.ask',
-    route: '/api/goodvibes-agent/knowledge/ask',
-  },
-  search: {
-    kind: 'agentKnowledge.search',
-    route: '/api/goodvibes-agent/knowledge/search',
-  },
-  sourcesList: {
-    kind: 'agentKnowledge.sources.list',
-    route: '/api/goodvibes-agent/knowledge/sources',
-  },
-  nodesList: {
-    kind: 'agentKnowledge.nodes.list',
-    route: '/api/goodvibes-agent/knowledge/nodes',
-  },
-  issuesList: {
-    kind: 'agentKnowledge.issues.list',
-    route: '/api/goodvibes-agent/knowledge/issues',
-  },
-  itemGet: {
-    kind: 'agentKnowledge.item.get',
-    route: '/api/goodvibes-agent/knowledge/items/{id}',
-  },
-  map: {
-    kind: 'agentKnowledge.map',
-    route: '/api/goodvibes-agent/knowledge/map',
-  },
-  connectorsList: {
-    kind: 'agentKnowledge.connectors.list',
-    route: '/api/goodvibes-agent/knowledge/connectors',
-  },
-  ingestUrl: {
-    kind: 'agentKnowledge.ingest.url',
-    route: '/api/goodvibes-agent/knowledge/ingest/url',
-  },
-  ingestUrls: {
-    kind: 'agentKnowledge.ingest.urls',
-    route: '/api/goodvibes-agent/knowledge/ingest/urls',
-  },
-  ingestBookmarks: {
-    kind: 'agentKnowledge.ingest.bookmarks',
-    route: '/api/goodvibes-agent/knowledge/ingest/bookmarks',
-  },
-  reindex: {
-    kind: 'agentKnowledge.reindex',
-    route: '/api/goodvibes-agent/knowledge/reindex',
-  },
-} as const;
-
-const DELEGATION_METHOD = {
-  kind: 'sessions.messages.create',
-  route: 'sessions.messages.create',
-} as const;
-
 interface DelegationResult {
   readonly sessionId: string;
   readonly message: unknown;
@@ -119,253 +50,6 @@ interface DelegationResult {
   readonly wrfcRequested: boolean;
 }
 
-function isRecord(value: unknown): value is JsonRecord {
-  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
-}
-
-function readString(record: JsonRecord | null, key: string): string | null {
-  const value = record?.[key];
-  return typeof value === 'string' ? value : null;
-}
-
-function commandValues(args: readonly string[]): string[] {
-  const values: string[] = [];
-  for (let index = 0; index < args.length; index += 1) {
-    const token = args[index]!;
-    if (!token.startsWith('--')) {
-      values.push(token);
-      continue;
-    }
-    if (!token.includes('=') && args[index + 1] && !args[index + 1]!.startsWith('--')) index += 1;
-  }
-  return values;
-}
-
-function delegationTaskValues(args: readonly string[]): string[] {
-  const values: string[] = [];
-  for (const token of args) {
-    if (token === '--wrfc') continue;
-    if (!token.startsWith('--')) values.push(token);
-  }
-  return values;
-}
-
-function readOptionValue(args: readonly string[], name: string): string | undefined {
-  for (let index = 0; index < args.length; index += 1) {
-    const token = args[index]!;
-    if (token === name) {
-      const next = args[index + 1];
-      return next && !next.startsWith('--') ? next : undefined;
-    }
-    if (token.startsWith(`${name}=`)) return token.slice(name.length + 1);
-  }
-  return undefined;
-}
-
-function readPositiveInt(args: readonly string[], name: string, fallback: number): number {
-  const raw = readOptionValue(args, name);
-  if (!raw) return fallback;
-  const parsed = Number.parseInt(raw, 10);
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
-}
-
-function readStringList(args: readonly string[], name: string): readonly string[] {
-  const raw = readOptionValue(args, name);
-  if (!raw) return [];
-  return raw.split(',').map((entry) => entry.trim()).filter(Boolean);
-}
-
-function hasFlag(args: readonly string[], flag: string): boolean {
-  return args.includes(flag);
-}
-
-function stripCommandFlag(args: readonly string[], flag: string): { readonly rest: readonly string[]; readonly present: boolean } {
-  const rest: string[] = [];
-  let present = false;
-  for (const arg of args) {
-    if (arg === flag) {
-      present = true;
-      continue;
-    }
-    rest.push(arg);
-  }
-  return { rest, present };
-}
-
-function readPackageMetadata(): { readonly version: string; readonly sdkVersion: string } {
-  return { version: VERSION, sdkVersion: SDK_VERSION };
-}
-
-function resolveDaemonConnection(runtime: CliCommandRuntime): AgentDaemonConnection {
-  const host = String(runtime.configManager.get('controlPlane.host') ?? '127.0.0.1');
-  const port = Number(runtime.configManager.get('controlPlane.port') ?? 3421);
-  const baseUrl = `http://${host}:${Number.isFinite(port) ? port : 3421}`;
-  const tokenPath = join(runtime.homeDirectory, '.goodvibes', 'daemon', 'operator-tokens.json');
-  if (!existsSync(tokenPath)) return { baseUrl, token: null, tokenPath };
-  try {
-    const parsed = JSON.parse(readFileSync(tokenPath, 'utf-8')) as unknown;
-    const token = isRecord(parsed) && typeof parsed.token === 'string' ? parsed.token : null;
-    return { baseUrl, token, tokenPath };
-  } catch {
-    return { baseUrl, token: null, tokenPath };
-  }
-}
-
-async function fetchDaemonStatus(connection: AgentDaemonConnection): Promise<{ readonly ok: boolean; readonly status: number; readonly body: unknown }> {
-  try {
-    const response = await fetch(`${connection.baseUrl}/status`, {
-      headers: connection.token ? { authorization: `Bearer ${connection.token}` } : undefined,
-    });
-    const text = await response.text();
-    let body: unknown = text;
-    try {
-      body = JSON.parse(text) as unknown;
-    } catch {
-      body = text;
-    }
-    return { ok: response.ok, status: response.status, body };
-  } catch (error) {
-    return { ok: false, status: 0, body: summarizeError(error) };
-  }
-}
-
-async function classifyKnowledgeError(error: unknown, connection: AgentDaemonConnection, route: string): Promise<AgentKnowledgeFailure> {
-  const message = summarizeError(error);
-  const lower = message.toLowerCase();
-  if (lower.includes('401') || lower.includes('unauthorized') || lower.includes('auth')) {
-    return { ok: false, kind: 'auth_required', error: message, baseUrl: connection.baseUrl, route };
-  }
-  if (lower.includes('404') || lower.includes('not found')) {
-    const metadata = readPackageMetadata();
-    const daemon = await fetchDaemonStatus(connection);
-    const daemonRecord = isRecord(daemon.body) ? daemon.body : {};
-    const daemonVersion = readString(daemonRecord, 'version') ?? 'unknown';
-    if (daemon.ok && daemonVersion !== metadata.sdkVersion) {
-      return {
-        ok: false,
-        kind: 'version_mismatch',
-        error: `External runtime SDK version ${daemonVersion} does not match Agent SDK pin ${metadata.sdkVersion}; Agent Knowledge route is unavailable.`,
-        baseUrl: connection.baseUrl,
-        route,
-        daemonVersion,
-        expectedSdkVersion: metadata.sdkVersion,
-      };
-    }
-    return { ok: false, kind: 'daemon_route_unavailable', error: message, baseUrl: connection.baseUrl, route };
-  }
-  if (lower.includes('fetch') || lower.includes('connect') || lower.includes('econnrefused')) {
-    return { ok: false, kind: 'daemon_unavailable', error: message, baseUrl: connection.baseUrl, route };
-  }
-  return { ok: false, kind: 'daemon_error', error: message, baseUrl: connection.baseUrl, route };
-}
-
-function createAgentSdk(connection: AgentDaemonConnection) {
-  return createBrowserAgentSdk({
-    baseUrl: connection.baseUrl,
-    authToken: connection.token,
-  });
-}
-
-async function postAgentKnowledgeJson<TData>(
-  connection: AgentDaemonConnection,
-  route: string,
-  body: JsonRecord,
-): Promise<TData> {
-  const response = await fetch(`${connection.baseUrl}${route}`, {
-    method: 'POST',
-    headers: {
-      authorization: `Bearer ${connection.token ?? ''}`,
-      'content-type': 'application/json',
-    },
-    body: JSON.stringify(body),
-  });
-  const text = await response.text();
-  let parsed: unknown = text;
-  if (text.trim()) {
-    try {
-      parsed = JSON.parse(text) as unknown;
-    } catch {
-      parsed = text;
-    }
-  }
-  if (!response.ok) {
-    const detail = isRecord(parsed) && typeof parsed.error === 'string' ? parsed.error : text;
-    throw new Error(`HTTP ${response.status} ${response.statusText}${detail ? `: ${detail}` : ''}`);
-  }
-  return parsed as TData;
-}
-
-function queryRoute(route: string, query: JsonRecord): string {
-  const params = new URLSearchParams();
-  for (const [key, value] of Object.entries(query)) {
-    if (value === undefined || value === null || value === '') continue;
-    if (Array.isArray(value)) {
-      for (const item of value) {
-        if (typeof item === 'string' && item.trim().length > 0) params.append(key, item);
-      }
-      continue;
-    }
-    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
-      params.set(key, String(value));
-    }
-  }
-  const suffix = params.toString();
-  return suffix ? `${route}?${suffix}` : route;
-}
-
-async function getAgentKnowledgeJson<TData>(
-  connection: AgentDaemonConnection,
-  route: string,
-  query: JsonRecord = {},
-): Promise<TData> {
-  const response = await fetch(`${connection.baseUrl}${queryRoute(route, query)}`, {
-    headers: {
-      authorization: `Bearer ${connection.token ?? ''}`,
-    },
-  });
-  const text = await response.text();
-  let parsed: unknown = text;
-  if (text.trim()) {
-    try {
-      parsed = JSON.parse(text) as unknown;
-    } catch {
-      parsed = text;
-    }
-  }
-  if (!response.ok) {
-    const detail = isRecord(parsed) && typeof parsed.error === 'string' ? parsed.error : text;
-    throw new Error(`HTTP ${response.status} ${response.statusText}${detail ? `: ${detail}` : ''}`);
-  }
-  return parsed as TData;
-}
-
-function findDisallowedKnowledgeScopeFlag(args: readonly string[]): string | null {
-  const disallowed = [
-    '--space',
-    '--knowledge-space',
-    '--knowledge-space-id',
-    ['--knowledge', 'SpaceId'].join(''),
-    '--include-all-spaces',
-    ['--include', 'AllSpaces'].join(''),
-    ['--home', 'graph'].join(''),
-    ['--home', '-graph'].join(''),
-  ];
-  for (const token of args) {
-    for (const flag of disallowed) {
-      if (token === flag || token.startsWith(`${flag}=`)) return flag;
-    }
-  }
-  return null;
-}
-
-function formatScopeFlagRejection(flag: string): string {
-  return [
-    `Agent Knowledge is isolated; ${flag} is not accepted.`,
-    'GoodVibes Agent must not use default Knowledge/Wiki or non-Agent product spaces.',
-    'Use only /api/goodvibes-agent/knowledge/* Agent-owned routes.',
-  ].join('\n');
-}
-
 function buildDelegationBody(task: string, wrfcRequested: boolean): string {
   return [
     'GoodVibes Agent explicit build delegation.',
@@ -383,29 +67,6 @@ function buildDelegationBody(task: string, wrfcRequested: boolean): string {
   ].join('\n');
 }
 
-async function runKnowledgeCall<TData>(
-  runtime: CliCommandRuntime,
-  method: DaemonCallMethod,
-  call: (connection: AgentDaemonConnection) => Promise<TData>,
-): Promise<AgentKnowledgeResult<TData>> {
-  const connection = resolveDaemonConnection(runtime);
-  if (!connection.token) {
-    return {
-      ok: false,
-      kind: 'auth_required',
-      error: `No runtime operator token found at ${connection.tokenPath}`,
-      baseUrl: connection.baseUrl,
-      route: method.route,
-    };
-  }
-  try {
-    const data = await call(connection);
-    return { ok: true, kind: method.kind, route: method.route, data };
-  } catch (error) {
-    return classifyKnowledgeError(error, connection, method.route);
-  }
-}
-
 export async function handleAgentKnowledgeCommand(runtime: CliCommandRuntime): Promise<CliCommandOutput> {
   const [sub = 'status', ...rawRest] = runtime.cli.commandArgs;
   const confirmation = stripCommandFlag(rawRest, '--yes');
@@ -521,6 +182,32 @@ export async function handleAgentKnowledgeCommand(runtime: CliCommandRuntime): P
   }
 
   if (normalized === 'connectors') {
+    const values = commandValues(rest);
+    if (values[0] === 'doctor') {
+      const id = values[1];
+      if (!id) return { output: 'Usage: goodvibes-agent knowledge connectors doctor <connectorId>', exitCode: 2 };
+      const route = `/api/goodvibes-agent/knowledge/connectors/${encodeURIComponent(id)}/doctor`;
+      const result = await runKnowledgeCall(runtime, AGENT_KNOWLEDGE_METHODS.connectorDoctor, async (connection) => (
+        await getAgentKnowledgeJson(connection, route)
+      ));
+      if (!result.ok) return { output: formatFailure(result, json), exitCode: 1 };
+      return {
+        output: formatJsonOrText(runtime.cli)(result, formatConnectorDoctor(result.data, id)),
+        exitCode: 0,
+      };
+    }
+    const id = values[0];
+    if (id) {
+      const route = `/api/goodvibes-agent/knowledge/connectors/${encodeURIComponent(id)}`;
+      const result = await runKnowledgeCall(runtime, AGENT_KNOWLEDGE_METHODS.connectorGet, async (connection) => (
+        await getAgentKnowledgeJson(connection, route)
+      ));
+      if (!result.ok) return { output: formatFailure(result, json), exitCode: 1 };
+      return {
+        output: formatJsonOrText(runtime.cli)(result, formatConnector(result.data, id)),
+        exitCode: 0,
+      };
+    }
     const result = await runKnowledgeCall(runtime, AGENT_KNOWLEDGE_METHODS.connectorsList, async (connection) => (
       await getAgentKnowledgeJson(connection, AGENT_KNOWLEDGE_METHODS.connectorsList.route)
     ));
@@ -531,6 +218,34 @@ export async function handleAgentKnowledgeCommand(runtime: CliCommandRuntime): P
     };
   }
 
+  if (normalized === 'connector' || normalized === 'connector-get') {
+    const [id] = commandValues(rest);
+    if (!id) return { output: 'Usage: goodvibes-agent knowledge connector <connectorId>', exitCode: 2 };
+    const route = `/api/goodvibes-agent/knowledge/connectors/${encodeURIComponent(id)}`;
+    const result = await runKnowledgeCall(runtime, AGENT_KNOWLEDGE_METHODS.connectorGet, async (connection) => (
+      await getAgentKnowledgeJson(connection, route)
+    ));
+    if (!result.ok) return { output: formatFailure(result, json), exitCode: 1 };
+    return {
+      output: formatJsonOrText(runtime.cli)(result, formatConnector(result.data, id)),
+      exitCode: 0,
+    };
+  }
+
+  if (normalized === 'connector-doctor' || normalized === 'doctor-connector') {
+    const [id] = commandValues(rest);
+    if (!id) return { output: 'Usage: goodvibes-agent knowledge connector-doctor <connectorId>', exitCode: 2 };
+    const route = `/api/goodvibes-agent/knowledge/connectors/${encodeURIComponent(id)}/doctor`;
+    const result = await runKnowledgeCall(runtime, AGENT_KNOWLEDGE_METHODS.connectorDoctor, async (connection) => (
+      await getAgentKnowledgeJson(connection, route)
+    ));
+    if (!result.ok) return { output: formatFailure(result, json), exitCode: 1 };
+    return {
+      output: formatJsonOrText(runtime.cli)(result, formatConnectorDoctor(result.data, id)),
+      exitCode: 0,
+    };
+  }
+
   if (normalized === 'ingest-url') {
     const values = commandValues(rest);
     const url = values[0];
@@ -565,6 +280,50 @@ export async function handleAgentKnowledgeCommand(runtime: CliCommandRuntime): P
     };
   }
 
+  if (normalized === 'ingest-file' || normalized === 'ingest-artifact') {
+    const values = commandValues(rest);
+    const path = values[0];
+    if (!path) return { output: 'Usage: goodvibes-agent knowledge ingest-file <path> [--title <title>] [--tags a,b] [--folder <path>] --yes', exitCode: 2 };
+    if (!confirmation.present) {
+      const failure = {
+        ok: false,
+        kind: 'confirmation_required',
+        error: `Refusing to ingest file into Agent Knowledge ${path} without --yes.`,
+        route: AGENT_KNOWLEDGE_METHODS.ingestArtifact.route,
+      };
+      return {
+        output: json ? JSON.stringify(failure, null, 2) : `${failure.error}\nUsage: goodvibes-agent knowledge ingest-file <path> [--title <title>] [--tags a,b] [--folder <path>] --yes`,
+        exitCode: 2,
+      };
+    }
+    const title = readOptionValue(rest, '--title');
+    const tags = readStringList(rest, '--tags');
+    const folderPath = readOptionValue(rest, '--folder');
+    const connectorId = readOptionValue(rest, '--connector') ?? 'goodvibes-agent-file';
+    const result = await runKnowledgeCall(runtime, AGENT_KNOWLEDGE_METHODS.ingestArtifact, async (connection) => (
+      await postAgentKnowledgeJson(connection, AGENT_KNOWLEDGE_METHODS.ingestArtifact.route, {
+        path,
+        title,
+        tags,
+        folderPath,
+        connectorId,
+        allowPrivateHosts: hasFlag(rest, '--allow-private-hosts'),
+        metadata: { originSurface: 'goodvibes-agent-cli' },
+      })
+    ));
+    if (!result.ok) return { output: formatFailure(result, json), exitCode: 1 };
+    return {
+      output: formatJsonOrText(runtime.cli)(result, formatIngest(
+        result.data,
+        path,
+        'ingest-file',
+        '/api/goodvibes-agent/knowledge/ingest/artifact',
+        'file',
+      )),
+      exitCode: 0,
+    };
+  }
+
   if (normalized === 'import-urls' || normalized === 'import-bookmarks') {
     const values = commandValues(rest);
     const path = values[0];
@@ -603,6 +362,78 @@ export async function handleAgentKnowledgeCommand(runtime: CliCommandRuntime): P
     };
   }
 
+  if (normalized === 'import-browser-history' || normalized === 'sync-browser-history') {
+    if (!confirmation.present) {
+      const failure = {
+        ok: false,
+        kind: 'confirmation_required',
+        error: 'Refusing to import browser history into Agent Knowledge without --yes.',
+        route: AGENT_KNOWLEDGE_METHODS.ingestBrowserHistory.route,
+      };
+      return {
+        output: json ? JSON.stringify(failure, null, 2) : `${failure.error}\nUsage: goodvibes-agent knowledge import-browser-history [--browsers chrome,firefox] [--sources history,bookmark] [--limit <n>] [--since-days <n>] --yes`,
+        exitCode: 2,
+      };
+    }
+    const browsers = readFirstStringList(rest, ['--browsers', '--browser']);
+    const sourceKinds = readFirstStringList(rest, ['--sources', '--source-kinds', '--source-kind']);
+    const homeOverride = readOptionValue(rest, '--home');
+    const result = await runKnowledgeCall(runtime, AGENT_KNOWLEDGE_METHODS.ingestBrowserHistory, async (connection) => (
+      await postAgentKnowledgeJson(connection, AGENT_KNOWLEDGE_METHODS.ingestBrowserHistory.route, {
+        browsers,
+        sourceKinds,
+        homeOverride,
+        limit: readPositiveInt(rest, '--limit', 250),
+        sinceMs: readSinceMs(rest),
+        connectorId: 'goodvibes-agent-browser-history',
+      })
+    ));
+    if (!result.ok) return { output: formatFailure(result, json), exitCode: 1 };
+    return {
+      output: formatJsonOrText(runtime.cli)(result, formatBatchIngest(result.data, 'browser-history')),
+      exitCode: 0,
+    };
+  }
+
+  if (normalized === 'ingest-connector') {
+    const values = commandValues(rest);
+    const connectorId = values[0];
+    if (!connectorId) return { output: 'Usage: goodvibes-agent knowledge ingest-connector <connectorId> [--input <json-or-text>|--path <path>|--content <text>] --yes', exitCode: 2 };
+    const input = parseConnectorInput(readOptionValue(rest, '--input'));
+    const path = readOptionValue(rest, '--path');
+    const content = readOptionValue(rest, '--content');
+    if (input === undefined && !path && !content) {
+      return { output: 'Usage: goodvibes-agent knowledge ingest-connector <connectorId> [--input <json-or-text>|--path <path>|--content <text>] --yes', exitCode: 2 };
+    }
+    if (!confirmation.present) {
+      const failure = {
+        ok: false,
+        kind: 'confirmation_required',
+        error: `Refusing to ingest connector input into Agent Knowledge for ${connectorId} without --yes.`,
+        route: AGENT_KNOWLEDGE_METHODS.ingestConnector.route,
+      };
+      return {
+        output: json ? JSON.stringify(failure, null, 2) : `${failure.error}\nUsage: goodvibes-agent knowledge ingest-connector <connectorId> [--input <json-or-text>|--path <path>|--content <text>] --yes`,
+        exitCode: 2,
+      };
+    }
+    const result = await runKnowledgeCall(runtime, AGENT_KNOWLEDGE_METHODS.ingestConnector, async (connection) => (
+      await postAgentKnowledgeJson(connection, AGENT_KNOWLEDGE_METHODS.ingestConnector.route, {
+        connectorId,
+        input,
+        path,
+        content,
+        allowPrivateHosts: hasFlag(rest, '--allow-private-hosts'),
+        sessionId: 'goodvibes-agent-cli',
+      })
+    ));
+    if (!result.ok) return { output: formatFailure(result, json), exitCode: 1 };
+    return {
+      output: formatJsonOrText(runtime.cli)(result, formatBatchIngest(result.data, `connector ${connectorId}`)),
+      exitCode: 0,
+    };
+  }
+
   if (normalized === 'reindex') {
     if (!confirmation.present) {
       const failure = {
@@ -627,7 +458,7 @@ export async function handleAgentKnowledgeCommand(runtime: CliCommandRuntime): P
   }
 
   return {
-    output: 'Usage: goodvibes-agent knowledge [status|ask <question>|search <query>|list|sources|nodes|issues|get <id>|map|connectors|ingest-url <url> --yes|import-urls <path> --yes|import-bookmarks <path> --yes|reindex --yes]',
+    output: 'Usage: goodvibes-agent knowledge [status|ask <question>|search <query>|list|sources|nodes|issues|get <id>|map|connectors|ingest-url <url> --yes|ingest-file <path> --yes|ingest-connector <id> --yes|import-urls <path> --yes|import-bookmarks <path> --yes|import-browser-history --yes|reindex --yes]',
     exitCode: 2,
   };
 }
@@ -687,7 +518,7 @@ export async function handleCompatCommand(runtime: CliCommandRuntime): Promise<C
     `  version compatible: ${yesNo(versionCompatible)}`,
     `  operator token: ${connection.token ? 'present' : 'missing'} (${connection.tokenPath})`,
     `  Agent knowledge route: ${knowledgeRouteReady ? 'ready' : `not ready (${knowledgeRoute.ok ? 'unknown' : knowledgeRoute.kind})`}`,
-    ...(versionCompatible ? [] : ['  next: update/restart the external GoodVibes runtime so /status matches the Agent SDK pin.']),
+    ...(versionCompatible ? [] : ['  next: update connected GoodVibes services so /status matches the Agent SDK pin.']),
   ].join('\n');
   return {
     output: runtime.cli.flags.outputFormat === 'json' ? JSON.stringify(value, null, 2) : text,