@llmindset/hf-mcp 0.2.33 → 0.2.35

package/src/jobs/types.ts

@@ -0,0 +1,237 @@
+import { z } from 'zod';
+
+/**
+ * Hardware flavors available for jobs
+ */
+export const CPU_FLAVORS = ['cpu-basic', 'cpu-upgrade', 'cpu-performance', 'cpu-xl'] as const;
+
+export const GPU_FLAVORS = [
+	'sprx8',
+	'zero-a10g',
+	't4-small',
+	't4-medium',
+	'l4x1',
+	'l4x4',
+	'l40sx1',
+	'l40sx4',
+	'l40sx8',
+	'a10g-small',
+	'a10g-large',
+	'a10g-largex2',
+	'a10g-largex4',
+	'a100-large',
+	'h100',
+	'h100x8',
+] as const;
+
+export const SPECIALIZED_FLAVORS = ['inf2x6'] as const;
+
+export const ALL_FLAVORS = [...CPU_FLAVORS, ...GPU_FLAVORS, ...SPECIALIZED_FLAVORS] as const;
+
+export type JobFlavor = (typeof ALL_FLAVORS)[number];
+
+/**
+ * Job status stages (from OpenAPI spec)
+ */
+export type JobStage = 'RUNNING' | 'COMPLETED' | 'CANCELED' | 'ERROR' | 'DELETED';
+
+/**
+ * Job status object from API
+ */
+export interface JobStatus {
+	stage: JobStage;
+	message?: string | null;
+}
+
+/**
+ * Job owner information
+ */
+export interface JobOwner {
+	id: string;
+	name: string;
+	type: 'user' | 'org';
+}
+
+/**
+ * Job information from API
+ * Based on OpenAPI schema
+ */
+export interface JobInfo {
+	id: string;
+	createdAt: string;
+	dockerImage?: string;
+	spaceId?: string;
+	command?: string[];
+	arguments?: string[];
+	environment: Record<string, string>;
+	secrets?: Record<string, string | null>;
+	flavor: string;
+	status: JobStatus;
+	owner: JobOwner;
+	createdBy?: JobOwner;
+	tags?: string[];
+	timeout?: number;
+	// Additional fields not in OpenAPI but present in responses
+	url?: string;
+	endpoint?: string;
+	finishedAt?: string;
+}
+
+/**
+ * Job specification for creating jobs
+ */
+export interface JobSpec {
+	dockerImage?: string;
+	spaceId?: string;
+	command: string[];
+	arguments?: string[];
+	environment?: Record<string, string>;
+	secrets?: Record<string, string>;
+	flavor: string;
+	timeoutSeconds?: number;
+}
+
+/**
+ * Scheduled job specification
+ */
+export interface ScheduledJobSpec {
+	schedule: string;
+	suspend?: boolean;
+	jobSpec: JobSpec;
+}
+
+/**
+ * Scheduled job information from API
+ */
+export interface ScheduledJobInfo {
+	id: string;
+	schedule: string;
+	suspend: boolean;
+	jobSpec: JobSpec;
+	lastRun?: string;
+	nextRun?: string;
+	owner: JobOwner;
+	createdAt: string;
+}
+
+/**
+ * Log event from SSE stream
+ */
+export interface LogEvent {
+	timestamp: string;
+	data: string;
+}
+
+/**
+ * Zod schemas for command arguments
+ */
+
+// Common args shared across commands
+const commonArgsSchema = z.object({
+	namespace: z.string().optional().describe('Target namespace (username or organization). Defaults to current user.'),
+});
+
+// Run command args
+export const runArgsSchema = commonArgsSchema.extend({
+	image: z.string().describe('Docker image or HF Space URL (e.g., "python:3.12" or "hf.co/spaces/user/space")'),
+	command: z
+		.union([z.string(), z.array(z.string())])
+		.describe(
+			'Command to execute. Array format recommended (e.g., ["python", "script.py"]). ' +
+				'String format is parsed with POSIX shell semantics (quotes, escaping). ' +
+				'For multiline scripts, use array with newlines in arguments.'
+		),
+	flavor: z
+		.enum(ALL_FLAVORS)
+		.optional()
+		.default('cpu-basic')
+		.describe(`Hardware flavor. Options: ${ALL_FLAVORS.join(', ')}`),
+	env: z.record(z.string()).optional().describe('Environment variables as key-value pairs'),
+	secrets: z.record(z.string()).optional().describe('Secret environment variables (encrypted server-side)'),
+	timeout: z
+		.string()
+		.optional()
+		.describe('Max duration (e.g., "5m", "2h", "30s"). Default: 30m')
+		.default('30m'),
+	detach: z
+		.boolean()
+		.optional()
+		.default(true)
+		.describe('Run in background and return immediately (default: true)'),
+});
+
+// UV command args
+export const uvArgsSchema = commonArgsSchema.extend({
+	script: z
+		.string()
+		.describe('Python script: local file path, URL, or inline code. UV will handle dependencies automatically.'),
+	repo: z.string().optional().describe('Persistent repository name for script storage'),
+	with_deps: z.array(z.string()).optional().describe('Additional package dependencies'),
+	script_args: z.array(z.string()).optional().describe('Arguments to pass to the script'),
+	python: z.string().optional().describe('Python interpreter version (e.g., "3.12")'),
+	flavor: z.enum(ALL_FLAVORS).optional().default('cpu-basic').describe('Hardware flavor'),
+	env: z.record(z.string()).optional().describe('Environment variables'),
+	secrets: z.record(z.string()).optional().describe('Secret environment variables'),
+	timeout: z.string().optional().default('30m').describe('Max duration'),
+	detach: z.boolean().optional().default(true).describe('Run in background'),
+});
+
+// PS command args
+export const psArgsSchema = commonArgsSchema.extend({
+	all: z.boolean().optional().default(false).describe('Show all jobs (default: only running)'),
+	status: z.string().optional().describe('Filter by status (e.g., "RUNNING", "COMPLETED")'),
+});
+
+// Logs command args
+export const logsArgsSchema = commonArgsSchema.extend({
+	job_id: z.string().describe('Job ID to fetch logs from'),
+	tail: z.number().optional().default(20).describe('Number of lines to return (default: 20)'),
+});
+
+// Inspect command args
+export const inspectArgsSchema = commonArgsSchema.extend({
+	job_id: z.union([z.string(), z.array(z.string())]).describe('Job ID(s) to inspect'),
+});
+
+// Cancel command args
+export const cancelArgsSchema = commonArgsSchema.extend({
+	job_id: z.string().describe('Job ID to cancel'),
+});
+
+// Scheduled run args
+export const scheduledRunArgsSchema = runArgsSchema.extend({
+	schedule: z
+		.string()
+		.describe('Schedule: cron expression or shorthand (@hourly, @daily, @weekly, @monthly, @yearly)'),
+	suspend: z.boolean().optional().default(false).describe('Create in suspended state'),
+});
+
+// Scheduled UV args
+export const scheduledUvArgsSchema = uvArgsSchema.extend({
+	schedule: z.string().describe('Schedule: cron expression or shorthand'),
+	suspend: z.boolean().optional().default(false).describe('Create in suspended state'),
+});
+
+// Scheduled PS args
+export const scheduledPsArgsSchema = commonArgsSchema.extend({
+	all: z.boolean().optional().default(false).describe('Show all scheduled jobs (default: hide suspended)'),
+});
+
+// Scheduled inspect/delete/suspend/resume args
+export const scheduledJobArgsSchema = commonArgsSchema.extend({
+	scheduled_job_id: z.string().describe('Scheduled job ID'),
+});
+
+/**
+ * Export type aliases for use in commands
+ */
+export type RunArgs = z.infer<typeof runArgsSchema>;
+export type UvArgs = z.infer<typeof uvArgsSchema>;
+export type PsArgs = z.infer<typeof psArgsSchema>;
+export type LogsArgs = z.infer<typeof logsArgsSchema>;
+export type InspectArgs = z.infer<typeof inspectArgsSchema>;
+export type CancelArgs = z.infer<typeof cancelArgsSchema>;
+export type ScheduledRunArgs = z.infer<typeof scheduledRunArgsSchema>;
+export type ScheduledUvArgs = z.infer<typeof scheduledUvArgsSchema>;
+export type ScheduledPsArgs = z.infer<typeof scheduledPsArgsSchema>;
+export type ScheduledJobArgs = z.infer<typeof scheduledJobArgsSchema>;

package/src/tool-ids.ts

@@ -21,6 +21,7 @@ import {
 	DOCS_SEMANTIC_SEARCH_CONFIG,
 	DOC_FETCH_CONFIG,
 	USE_SPACE_TOOL_CONFIG,
+	HF_JOBS_TOOL_CONFIG,
 } from './index.js';
 
 // Extract tool IDs from their configs (single source of truth)
@@ -41,6 +42,7 @@ export const USER_SUMMARY_PROMPT_ID = USER_SUMMARY_PROMPT_CONFIG.name;
 export const PAPER_SUMMARY_PROMPT_ID = PAPER_SUMMARY_PROMPT_CONFIG.name;
 export const MODEL_DETAIL_PROMPT_ID = MODEL_DETAIL_PROMPT_CONFIG.name;
 export const DATASET_DETAIL_PROMPT_ID = DATASET_DETAIL_PROMPT_CONFIG.name;
+export const HF_JOBS_TOOL_ID = HF_JOBS_TOOL_CONFIG.name;
 
 // Complete list of all built-in tool IDs
 export const ALL_BUILTIN_TOOL_IDS = [
@@ -57,6 +59,7 @@ export const ALL_BUILTIN_TOOL_IDS = [
 	DOCS_SEMANTIC_SEARCH_TOOL_ID,
 	DOC_FETCH_TOOL_ID,
 	USE_SPACE_TOOL_ID,
+	HF_JOBS_TOOL_ID,
 ] as const;
 // Grouped tool IDs for bouquet configurations
 export const TOOL_ID_GROUPS = {
@@ -67,7 +70,13 @@ export const TOOL_ID_GROUPS = {
 		PAPER_SEARCH_TOOL_ID,
 		DOCS_SEMANTIC_SEARCH_TOOL_ID,
 	] as const,
-	spaces: [SPACE_SEARCH_TOOL_ID, DUPLICATE_SPACE_TOOL_ID, SPACE_INFO_TOOL_ID, SPACE_FILES_TOOL_ID, USE_SPACE_TOOL_ID] as const,
+	spaces: [
+		SPACE_SEARCH_TOOL_ID,
+		DUPLICATE_SPACE_TOOL_ID,
+		SPACE_INFO_TOOL_ID,
+		SPACE_FILES_TOOL_ID,
+		USE_SPACE_TOOL_ID,
+	] as const,
 	detail: [MODEL_DETAIL_TOOL_ID, DATASET_DETAIL_TOOL_ID, HUB_INSPECT_TOOL_ID] as const,
 	docs: [DOCS_SEMANTIC_SEARCH_TOOL_ID, DOC_FETCH_TOOL_ID] as const,
 	hf_api: [
@@ -77,6 +86,7 @@ export const TOOL_ID_GROUPS = {
 		PAPER_SEARCH_TOOL_ID,
 		HUB_INSPECT_TOOL_ID,
 		DOCS_SEMANTIC_SEARCH_TOOL_ID,
+		//		HF_JOBS_TOOL_ID,
 	] as const,
 	all: [...ALL_BUILTIN_TOOL_IDS] as const,
 } as const;

package/src/types/tool-result.ts

@@ -21,4 +21,10 @@ export interface ToolResult {
 	 * For prompts: 1 if generated successfully
 	 */
 	resultsShared: number;
+
+	/**
+	 * Indicates whether this result represents an error condition
+	 * When true, formatted contains an error message
+	 */
+	isError?: boolean;
 }

package/test/jobs/command-translation.spec.ts

@@ -0,0 +1,331 @@
+import { describe, it, expect } from 'vitest';
+import { parseTimeout, parseImageSource, parseCommand, createJobSpec } from '../../src/jobs/commands/utils.js';
+
+describe('Jobs Command Translation', () => {
+	describe('parseTimeout', () => {
+		it('should parse timeout with seconds', () => {
+			expect(parseTimeout('30s')).toBe(30);
+			expect(parseTimeout('45s')).toBe(45);
+		});
+
+		it('should parse timeout with minutes', () => {
+			expect(parseTimeout('5m')).toBe(300);
+			expect(parseTimeout('10m')).toBe(600);
+		});
+
+		it('should parse timeout with hours', () => {
+			expect(parseTimeout('2h')).toBe(7200);
+			expect(parseTimeout('1h')).toBe(3600);
+		});
+
+		it('should parse timeout with days', () => {
+			expect(parseTimeout('1d')).toBe(86400);
+		});
+
+		it('should parse plain number as seconds', () => {
+			expect(parseTimeout('300')).toBe(300);
+			expect(parseTimeout('60')).toBe(60);
+		});
+
+		it('should handle decimal values', () => {
+			expect(parseTimeout('1.5h')).toBe(5400);
+			expect(parseTimeout('2.5m')).toBe(150);
+		});
+
+		it('should throw error for invalid format', () => {
+			expect(() => parseTimeout('invalid')).toThrow(/Invalid timeout format/);
+			expect(() => parseTimeout('xyz')).toThrow(/Invalid timeout format/);
+		});
+
+		it('should parse partial numbers (parseInt behavior)', () => {
+			// parseInt stops at first non-numeric, so '5x' becomes 5
+			expect(parseTimeout('5x')).toBe(5);
+			expect(parseTimeout('10abc')).toBe(10);
+		});
+	});
+
+	describe('parseImageSource', () => {
+		it('should detect Docker Hub images', () => {
+			const result = parseImageSource('python:3.12');
+			expect(result.dockerImage).toBe('python:3.12');
+			expect(result.spaceId).toBeUndefined();
+		});
+
+		it('should detect HuggingFace Space URLs with https://huggingface.co/', () => {
+			const result = parseImageSource('https://huggingface.co/spaces/user/app');
+			expect(result.spaceId).toBe('user/app');
+			expect(result.dockerImage).toBeUndefined();
+		});
+
+		it('should detect HuggingFace Space URLs with https://hf.co/', () => {
+			const result = parseImageSource('https://hf.co/spaces/user/app');
+			expect(result.spaceId).toBe('user/app');
+			expect(result.dockerImage).toBeUndefined();
+		});
+
+		it('should detect HuggingFace Space URLs without https prefix', () => {
+			const result = parseImageSource('huggingface.co/spaces/user/app');
+			expect(result.spaceId).toBe('user/app');
+			expect(result.dockerImage).toBeUndefined();
+		});
+
+		it('should detect HuggingFace Space URLs with hf.co shorthand', () => {
+			const result = parseImageSource('hf.co/spaces/user/app');
+			expect(result.spaceId).toBe('user/app');
+			expect(result.dockerImage).toBeUndefined();
+		});
+
+		it('should treat complex docker images as docker images', () => {
+			const result = parseImageSource('ghcr.io/owner/repo:tag');
+			expect(result.dockerImage).toBe('ghcr.io/owner/repo:tag');
+			expect(result.spaceId).toBeUndefined();
+		});
+	});
+
+	describe('parseCommand', () => {
+		it('should return array commands as-is', () => {
+			const result = parseCommand(['python', '-c', 'print("hello")']);
+			expect(result.command).toEqual(['python', '-c', 'print("hello")']);
+		});
+
+		it('should split simple string commands', () => {
+			const result = parseCommand('python script.py');
+			expect(result.command).toEqual(['python', 'script.py']);
+		});
+
+		it('should handle single word commands', () => {
+			const result = parseCommand('ls');
+			expect(result.command).toEqual(['ls']);
+		});
+
+		it('should handle double-quoted strings', () => {
+			const result = parseCommand('python -c "print(\'Hello world!\')"');
+			expect(result.command).toEqual(['python', '-c', "print('Hello world!')"]);
+		});
+
+		it('should handle single-quoted strings', () => {
+			const result = parseCommand("python -c 'print(\"Hello world!\")'");
+			expect(result.command).toEqual(['python', '-c', 'print("Hello world!")']);
+		});
+
+		it('should handle escaped quotes', () => {
+			const result = parseCommand('echo "He said \\"hello\\""');
+			expect(result.command).toEqual(['echo', 'He said "hello"']);
+		});
+
+		it('should handle mixed quotes and spaces', () => {
+			const result = parseCommand('python -c "print(\'hello world\')"');
+			expect(result.command).toEqual(['python', '-c', "print('hello world')"]);
+		});
+
+		it('should handle multiple quoted arguments', () => {
+			const result = parseCommand('cmd "arg one" "arg two" "arg three"');
+			expect(result.command).toEqual(['cmd', 'arg one', 'arg two', 'arg three']);
+		});
+
+		it('should handle quoted strings with no spaces', () => {
+			const result = parseCommand('echo "hello"');
+			expect(result.command).toEqual(['echo', 'hello']);
+		});
+
+		it('should handle empty quotes', () => {
+			const result = parseCommand('echo "" test');
+			expect(result.command).toEqual(['echo', '', 'test']);
+		});
+
+		it('should handle real-world example from docs', () => {
+			const result = parseCommand('python -c "print(\'Hello world!\')"');
+			expect(result.command).toEqual(['python', '-c', "print('Hello world!')"]);
+		});
+
+		it('should handle commands with multiple spaces', () => {
+			const result = parseCommand('python    script.py    --arg');
+			expect(result.command).toEqual(['python', 'script.py', '--arg']);
+		});
+
+		it('should handle commands with tabs', () => {
+			const result = parseCommand('python\tscript.py\t--arg');
+			expect(result.command).toEqual(['python', 'script.py', '--arg']);
+		});
+
+		it('should handle mixed whitespace', () => {
+			const result = parseCommand('cmd  \t arg1\t\t  arg2');
+			expect(result.command).toEqual(['cmd', 'arg1', 'arg2']);
+		});
+
+		it('should handle backslash escaping (POSIX shell semantics)', () => {
+			// In POSIX shells, \n in double quotes is literal, not a newline
+			const result = parseCommand('echo "hello\\nworld"');
+			expect(result.command).toEqual(['echo', 'hello\\nworld']);
+		});
+
+		it('should handle backslash literally in single quotes', () => {
+			const result = parseCommand("echo 'hello\\nworld'");
+			expect(result.command).toEqual(['echo', 'hello\\nworld']);
+		});
+
+		it('should throw error for shell operators', () => {
+			expect(() => parseCommand('echo hello | grep world')).toThrow(/Unsupported shell syntax/);
+			expect(() => parseCommand('ls && pwd')).toThrow(/Unsupported shell syntax/);
+			expect(() => parseCommand('cat file > output.txt')).toThrow(/Unsupported shell syntax/);
+		});
+
+		it('should throw error for empty command', () => {
+			expect(() => parseCommand('')).toThrow(/Command cannot be empty/);
+			expect(() => parseCommand('   ')).toThrow(/Command cannot be empty/);
+		});
+
+		it('should handle environment variables as literal references', () => {
+			// shell-quote parses $HOME as an env token, which we format as literal string
+			// This preserves the variable reference for the job runtime to handle
+			const result = parseCommand('echo $HOME');
+			expect(result.command).toEqual(['echo', '$HOME']);
+		});
+
+		it('should preserve complex environment variable syntax', () => {
+			const result = parseCommand('echo ${FOO:-bar} ${BAR?missing}');
+			expect(result.command).toEqual(['echo', '${FOO:-bar}', '${BAR?missing}']);
+		});
+
+		it('should retain special parameter references', () => {
+			const result = parseCommand('echo $$ $1 $@ $* $- $! $_');
+			expect(result.command).toEqual(['echo', '$$', '$1', '$@', '$*', '$-', '$!', '$_']);
+		});
+
+		it('should treat escaped dollars as literal variables', () => {
+			const result = parseCommand('echo \\$FOO "$BAR"');
+			expect(result.command).toEqual(['echo', '$FOO', '$BAR']);
+		});
+
+		it('should handle multiline Python in array format', () => {
+			const result = parseCommand(['python', '-c', 'import sys\nprint("hello")\nprint("world")']);
+			expect(result.command).toEqual(['python', '-c', 'import sys\nprint("hello")\nprint("world")']);
+		});
+	});
+
+	describe('createJobSpec', () => {
+		it('should create a basic job spec', () => {
+			const spec = createJobSpec({
+				image: 'python:3.12',
+				command: 'python -c "print(123)"',
+			});
+
+			expect(spec.dockerImage).toBe('python:3.12');
+			expect(spec.command).toEqual(['python', '-c', 'print(123)']);
+			expect(spec.flavor).toBe('cpu-basic');
+		});
+
+		it('should handle Space URLs', () => {
+			const spec = createJobSpec({
+				image: 'hf.co/spaces/user/app',
+				command: 'python run.py',
+			});
+
+			expect(spec.spaceId).toBe('user/app');
+			expect(spec.dockerImage).toBeUndefined();
+		});
+
+		it('should include environment variables', () => {
+			const spec = createJobSpec({
+				image: 'python:3.12',
+				command: 'python script.py',
+				env: { FOO: 'bar', BAZ: 'qux' },
+			});
+
+			expect(spec.environment).toEqual({ FOO: 'bar', BAZ: 'qux' });
+		});
+
+		it('should include secrets', () => {
+			const spec = createJobSpec({
+				image: 'python:3.12',
+				command: 'python script.py',
+				secrets: { API_KEY: 'secret123' },
+			});
+
+			expect(spec.secrets).toEqual({ API_KEY: 'secret123' });
+		});
+
+		it('should keep HF_TOKEN literal when no expansion token provided', () => {
+			const spec = createJobSpec({
+				image: 'python:3.12',
+				command: 'echo $HF_TOKEN',
+			});
+
+			expect(spec.command).toEqual(['echo', '$HF_TOKEN']);
+		});
+
+		it('should keep command literal even when hfToken provided', () => {
+			const spec = createJobSpec({
+				image: 'python:3.12',
+				command: 'echo $HF_TOKEN',
+				hfToken: 'hf_secret_999',
+			});
+
+			expect(spec.command).toEqual(['echo', '$HF_TOKEN']);
+		});
+
+		it('should inject HF_TOKEN into secrets when placeholder provided', () => {
+			const spec = createJobSpec({
+				image: 'python:3.12',
+				command: 'python script.py',
+				secrets: { HF_TOKEN: '$HF_TOKEN', OTHER: 'keep' },
+				hfToken: 'hf_secret_123',
+			});
+
+			expect(spec.secrets).toEqual({ HF_TOKEN: 'hf_secret_123', OTHER: 'keep' });
+		});
+
+		it('should inject HF_TOKEN into env when placeholder provided', () => {
+			const spec = createJobSpec({
+				image: 'python:3.12',
+				command: 'python script.py',
+				env: { HF_TOKEN: '${HF_TOKEN}', NAME: 'demo' },
+				hfToken: 'hf_env_456',
+			});
+
+			expect(spec.environment).toEqual({ HF_TOKEN: 'hf_env_456', NAME: 'demo' });
+		});
+
+		it('should leave other env values unchanged', () => {
+			const spec = createJobSpec({
+				image: 'python:3.12',
+				command: 'python script.py',
+				env: { NAME: 'demo' },
+				secrets: { API_KEY: 'secret123' },
+				hfToken: 'hf_env_456',
+			});
+
+			expect(spec.environment).toEqual({ NAME: 'demo' });
+			expect(spec.secrets).toEqual({ API_KEY: 'secret123' });
+		});
+
+		it('should parse and include timeout', () => {
+			const spec = createJobSpec({
+				image: 'python:3.12',
+				command: 'python script.py',
+				timeout: '5m',
+			});
+
+			expect(spec.timeoutSeconds).toBe(300);
+		});
+
+		it('should use specified flavor', () => {
+			const spec = createJobSpec({
+				image: 'python:3.12',
+				command: 'python script.py',
+				flavor: 'a10g-small',
+			});
+
+			expect(spec.flavor).toBe('a10g-small');
+		});
+
+		it('should handle array commands', () => {
+			const spec = createJobSpec({
+				image: 'ubuntu',
+				command: ['bash', '-c', 'echo hello'],
+			});
+
+			expect(spec.command).toEqual(['bash', '-c', 'echo hello']);
+		});
+	});
+});